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

Quests — client.quests

QuestsService (source: src/quests/QuestsService.ts). The player's global quests — list, claim, report metric progress. Plain call-and-response service, NOT observable (no sync revision key): re-list after a claim or report.

Distinct from scenario quest nodes, which advance through client.effects.onQuest (see reference/scenarios.md).

Methods

list(): Promise<Quest[]>
claim(questSlug: string): Promise<ClaimQuestResponse>
reportProgress(metric: string, amount: number): Promise<string[]>  // slugs of quests completed by this report

Types

interface Quest {
  slug?: string;   // stable across environments — what claim() takes
  name?: string;
  objectives?: QuestObjectiveProgress[];
  rewards?: Reward[];
  status?: 'active' | 'claimed' | 'completed';
}

interface QuestObjectiveProgress {
  completed?: boolean;
  current?: number;
  metric?: string;
  objectiveId?: string;
  target?: number;
}

interface ClaimQuestResponse {
  alreadyClaimed?: boolean;
  error?: string;
  granted?: Reward[];   // { amount?, currency?, itemId? }
  success?: boolean;
}

Usage notes

const quests = await client.quests.list();
for (const quest of quests) {
  if (quest.status === 'completed' && quest.slug) {
    const res = await client.quests.claim(quest.slug);
    // res.success / res.alreadyClaimed / res.granted
  }
}
const completedSlugs = await client.quests.reportProgress('kills', 1);

• claim is idempotent server-side; check success / alreadyClaimed / error in the response rather than relying on exceptions.
• Objective completion is judged server-side from metric reports.

QuestMetrics helpers

Exported as a namespace: import { QuestMetrics } from '@rudder/js-sdk' (source: src/quests/QuestMetrics.ts).

QuestMetrics.purchaseOffer('starter-pack');  // "purchase.offer:starter-pack"
QuestMetrics.purchaseItem('moonberry');      // "purchase.item:moonberry"

Purchase metrics are reported automatically server-side by the store purchase fan-out — these helpers exist so quest configs and client code name the format consistently. Catalog counter slugs are reported via reportProgress. Custom free-text metrics no longer progress quests — they no-op at runtime.