Add agent skill (SKILL.md + per-domain reference)

skills/rudder-web-sdk/reference/battlepass.md

@@ -0,0 +1,87 @@
+# Battle pass — `client.battlePass`
+
+`BattlePassService` (source: `src/battlepass/BattlePassService.ts`).
+Call-and-response access to battle pass endpoints. Battle pass state is tied to
+a **scenario battle pass node**, so calls carry `scenarioId` + `nodeId` (plus
+`runId` for mutating calls). NOT observable — re-fetch progress explicitly
+after a mutation.
+
+In most games you do not call this service directly: a scenario battle pass
+node surfaces through `client.effects.onBattlePass` with a session object that
+wraps these calls (see `reference/scenarios.md`). Use the service directly when
+you already know the scenario/node/run identifiers.
+
+## Methods
+
+```ts
+getProgress(scenarioId: string, nodeId: string): Promise<GetBattlePassProgressResponse>
+addXp(request: AddBattlePassXpRequest): Promise<AddBattlePassXpResponse>
+claimReward(request: ClaimBattlePassRewardRequest): Promise<ClaimBattlePassRewardResponse>
+purchasePremium(request: PurchaseBattlePassPremiumRequest): Promise<PurchaseBattlePassPremiumResponse>
+```
+
+## Request / response types
+
+```ts
+interface AddBattlePassXpRequest {
+  amount?: number;
+  nodeId?: string;
+  runId?: string;
+  scenarioId?: string;
+  source?: string;   // configured XP source
+}
+interface AddBattlePassXpResponse {
+  level?: number;
+  leveledUp?: boolean;
+  maxLevel?: boolean;
+  plan?: ExecutionPlan;  // scenario plan continuation, handled by the runtime
+  xp?: number;
+}
+
+interface ClaimBattlePassRewardRequest {
+  level?: number;
+  nodeId?: string;
+  runId?: string;
+  scenarioId?: string;
+  track?: 'free' | 'premium';
+}
+interface ClaimBattlePassRewardResponse {
+  alreadyClaimed?: boolean;
+  error?: string;
+  granted?: Reward[];   // { amount?, currency?, itemId? }
+  success?: boolean;
+}
+
+interface GetBattlePassProgressResponse {
+  claimedTiers?: ClaimedTier[];  // { level?, track? }
+  level?: number;
+  premiumOwned?: boolean;
+  xp?: number;
+}
+
+interface PurchaseBattlePassPremiumRequest {
+  idempotencyKey?: string;
+  nodeId?: string;
+  runId?: string;
+  scenarioId?: string;
+}
+interface PurchaseBattlePassPremiumResponse {
+  error?: string;
+  plan?: ExecutionPlan;
+  success?: boolean;
+}
+```
+
+## Semantics
+
+- `addXp` credits XP from a configured source; returns the new `xp`/`level`
+  plus `leveledUp` / `maxLevel` flags.
+- `claimReward` claims a tier reward at a reached level; idempotent
+  server-side (`alreadyClaimed`). Claiming a tier above the current level (or
+  a premium tier without premium) fails server-side — check `success`/`error`
+  in the response and the typed error `code` (`RudderErrorCodes`).
+- `purchasePremium` charges the player's wallet; idempotent; pass your own
+  `idempotencyKey` for safe retries.
+- Mutations return `ExecutionPlan` continuations — when driving battle pass
+  manually you are responsible for the scenario run state; prefer the
+  `onBattlePass` effect session which handles this.