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

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

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

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.