# PvPScout (WoW Retail)

PvPScout adds PvP ratings from the official leaderboards directly to unit tooltips. It also provides a simple chat print via `/pvpscout`.

Key features:

- Tooltip ratings for 2v2, 3v3, Solo Shuffle, Rated Battlegrounds (10v10), and Blitz RBG
- Options panel: enable/disable, show rank, per‑bracket visibility and ordering, minimap icon
- Minimap button with quick toggle menu
- Optional “Updated X ago” header, stale‑data notice, and color‑by‑rating

## Installation

Install via CurseForge or extract the ZIP so the folder structure is:

```text
Interface/AddOns/PvPScout/
  PvPScout.toc
  PvPScout.lua
  Data.lua
  ...
```

Data is generated outside the game and stored in `Data.lua`.
Releases ship with a prebuilt `Data.lua`; it is generated automatically in CI both on schedule and when you create a tag.

## Usage

- Hover a player to see ratings for the enabled brackets.
- Commands:
  - `/pvpscout` prints the current target’s ratings in chat.
  - `/pvpscout enable` and `/pvpscout disable` toggle tooltip lines.

## Options

Open Settings → AddOns → PvPScout. Available toggles include:

- Show rank, show header, show “Updated X ago”, color by rating
- Per‑bracket visibility and ordering
- Minimap icon visibility and position reset

## Compatibility

If you use tooltip addons (e.g., ElvUI/TipTac), enable “Compatible tooltip hook (ElvUI/TipTac)” in Settings. This uses a safer hook path. Reload UI after toggling.

## Data updates

The addon relies on a prebuilt `Data.lua` snapshot. A scheduled GitHub Actions workflow updates this data periodically and builds a ZIP for release. End users don’t need any setup.

Release tagging also generates a fresh `Data.lua` during packaging, so proper releases always include current data even if your local environment can’t fetch it.

The scraper now always writes Data.lua so the `updatedAt` timestamp is refreshed each run.
The workflow commits Data.lua back to the repository when it changes, so the in-game Setup page and tooltip show the latest update time.

How data is sourced

- Brackets covered: 2v2, 3v3, Solo Shuffle, Rated Battlegrounds (10v10), and Battleground Blitz.
- Source pages: the general bracket leaderboards (e.g., `/game/pvp/leaderboards/3v3?region=EU`). The class/spec pages are UI filters of the same base leaderboard; we collect the full bracket lists, not the per‑class slices.
- Schedule: every 3 hours by default (GitHub Actions CRON). You can adjust via repository variables.
- Region & locale: the generator filters rows to the intended region. When EU is among regions and no locale is set, it defaults to `en_GB` for consistent parsing.

Temporary fallback scraper

If Blizzard’s official API credentials are not configured, the workflow uses a polite HTML scraper to collect the public leaderboard top lists and generate `Data.lua`. This scraper is a stopgap only; as soon as API credentials are available again, the workflow automatically switches back to the official API path. The scraper identifies itself with a clear User‑Agent, rate limits (~1 request/second), and backs off on errors.

Maintainers: Inputs and override

- Variables (Repository → Settings → Variables → Actions):
  - `REGIONS` (default: `eu`) like `eu,us`
  - `BRACKETS` (default: `2v2,3v3,shuffle,rbg,blitz`)
  - `LOCALE` (default: `en_US`)
  - Optional `DATA_MODE`: set to `fetch` to force API mode or `scrape` to force scraper; otherwise it auto‑selects based on API credentials presence.
- Secrets (Repository → Settings → Secrets and variables → Actions):
  - `BLIZZARD_CLIENT_ID`, `BLIZZARD_CLIENT_SECRET` for API mode
  - `CF_API_KEY` for CurseForge upload on tag/scheduled builds

Pagination and size controls (scraper)

- `MAX_PAGES_PER_BRACKET` (default: `0` → auto/all pages discovered). Limits how many leaderboard pages to scrape per bracket.
- `MAX_ENTRIES_PER_BRACKET` (default: `0` → no cap). Truncates entries written per bracket to keep `Data.lua` compact if desired.

Local testing behind TLS-inspecting proxies

If local scraping fails with an error like “unable to get local issuer certificate”, your environment likely intercepts TLS. You have these options when running `npm run scrape` locally:

- Provide the corporate root/intermediate certificates (recommended):
  - Set `CA_CERT_PATH` or `NODE_EXTRA_CA_CERTS` to a PEM file path.
- As a last resort for local testing only (not in CI):
  - Set `INSECURE_TLS=1` to disable certificate verification.

Example (PowerShell):

```powershell
# Trust corporate CA
$env:CA_CERT_PATH = 'C:\path\to\corp-root.pem'
cd tools; npm run scrape

# OR (testing only) disable verification
$env:INSECURE_TLS = '1'
cd tools; npm run scrape
```

## Troubleshooting

- Only characters present on the official leaderboards will show ratings.
- If a known character is missing, the ladder may not include them yet; try again later.

### Addon size impact

`Data.lua` is plain text with a compact Lua table. You can cap entries per bracket via `MAX_ENTRIES_PER_BRACKET` (default: no cap). Even with multiple pages per bracket, sizes remain practical for distribution; adjust caps if needed.

## License

MIT
