# @v2/season-pass-service

Season pass progression service for `TODOS.phase-72.72.12.2.1`.

This season pass package builds an XP-based track with free and premium lanes,
rewards at every level, server-authoritative XP grants, duplicate grant
idempotency, and a client payload that requires no client patch.

Duplicate grant idempotency is required for XP grant retries; duplicate grant
idempotency is part of the service contract. duplicate grant idempotency.

Primary APIs:

- `buildV2SeasonPassProgressionSurface`
- `resolveV2SeasonPassTierProgress`
- `applyV2SeasonPassXpGrant`
- `buildV2SeasonPassRewardDefinitionSurface`
- `validateV2SeasonPassRewardDefinitionFormat`
- `buildV2SeasonPassXpSourceSurface`
- `calculateV2SeasonPassXpGrantFromSource`
- `buildV2SeasonPassChallengeSystemSurface`
- `completeV2SeasonPassChallenge`

The default season uses a 60-tier, 90-day track. Each tier includes at least one
free reward and one premium reward, and the client payload exposes claimable
free rewards plus premium rewards gated by entitlement.

The reward definition format covers cosmetics, currency, items, emotes, and
titles per tier. Each reward definition emits `catalogRef`, `entitlementRef`,
`localizedNameKey`, and `grantPayload` metadata for grant fulfillment.

The XP source surface covers match completion, daily challenges, weekly
challenges, and event bonuses. Each XP source is server-authoritative and emits
bounded grants through `calculateV2SeasonPassXpGrantFromSource`. XP source grant
calculation uses `baseXp`, `maxXpPerGrant`, `replayEvidenceRequired`, and
`antiCheatValidated` metadata for match completion, daily challenges, weekly
challenges, and event bonuses. weekly challenges. grant calculation.

The challenge system builds daily challenges and weekly challenges randomly
generated from a challenge pool, marks every active challenge as auto-rotate
content, and rewards XP and currency rewards through
`completeV2SeasonPassChallenge`. Challenge currency grants use `season-credits`,
and the challenge system requires no client patch for updated pool definitions
or rotations.

Endpoints:

- `GET /v2/live-ops/season-pass/{seasonId}/track`
- `GET /v2/live-ops/season-pass/{seasonId}/progression/{accountIdHash}`
- `POST /v2/live-ops/season-pass/{seasonId}/xp-grants`
- `GET /v2/live-ops/season-pass/{seasonId}/reward-definitions`
- `POST /v2/live-ops/season-pass/{seasonId}/reward-definitions/validate`
- `GET /v2/live-ops/season-pass/{seasonId}/xp-sources`
- `POST /v2/live-ops/season-pass/{seasonId}/xp-sources/preview-grant`
- `GET /v2/live-ops/season-pass/{seasonId}/challenges`
- `POST /v2/live-ops/season-pass/{seasonId}/challenges/rotate`
- `POST /v2/live-ops/season-pass/{seasonId}/challenges/{challengeId}/complete`

Verification:

```bash
pnpm --filter @v2/season-pass-service test
pnpm --filter @v2/season-pass-service typecheck
pnpm --filter @v2/season-pass-service lint
pnpm --filter @v2/season-pass-service build
python3 V2/ue/Tools/check-v2-season-pass-progression.py
python3 V2/ue/Tools/check-v2-season-pass-reward-definitions.py
python3 V2/ue/Tools/check-v2-season-pass-xp-sources.py
python3 V2/ue/Tools/check-v2-season-pass-challenge-system.py
```