# 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

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

## Types

```ts
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

```ts
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`).

```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.