From 68287d212eee48543b18050eef23caf6ae3c8f0f Mon Sep 17 00:00:00 2001
From: edmand46 <theedison4@gmail.com>
Date: Tue, 25 Aug 2026 16:25:32 +0300
Subject: [PATCH] quests: QuestMetrics helpers (purchaseOffer/purchaseItem),
 README quests section

---
 README.md                  | 33 ++++++++++++++++++++++++++++++++-
 src/index.ts               |  1 +
 src/quests/QuestMetrics.ts | 18 ++++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 src/quests/QuestMetrics.ts

diff --git a/README.md b/README.md
index f7c87da..e379aaf 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ client.dispose();
 | Storage | `client.storage` (observable) + `.save(items)` / `.delete(type)` |
 | Leaderboards | `client.leaderboards.findBySlug(slug)` → `handle.submit(score)` / `handle.list(limit?)` |
 | Battle pass | `client.battlePass` (getProgress / addXp / claimReward / purchasePremium) |
-| Quests | `client.quests.list()` / `client.quests.claim(id)` |
+| Quests | `client.quests.list()` / `client.quests.claim(id)` / `client.quests.reportProgress(metric, amount)` |
 | Scenario effects | `client.effects.on*` |
 
 Type the remote config for `client.remoteConfig`:
@@ -75,6 +75,37 @@ const client = new RudderClient<GameConfig>({ /* … */ });
 client.remoteConfig.get('player_speed', 200); // number
 ```
 
+## Quests
+
+`client.quests` covers the player's global quests — list with per-objective
+progress, claim, and metric reports. These are distinct from scenario quest
+nodes, which advance through the `onQuest` effect's `QuestSession`. Global
+quests have no live sync: re-list after a claim or report.
+
+```ts
+const quests = await client.quests.list();
+for (const quest of quests) {
+  if (quest.status === 'completed' && quest.id) {
+    await client.quests.claim(quest.id);
+  }
+}
+
+// Custom metrics advance matching objectives server-side; the call returns
+// the ids of quests completed by this report.
+const completedIds = await client.quests.reportProgress('kills', 1);
+```
+
+Purchase metrics are reported automatically when a purchase goes through
+`client.stores`; the `QuestMetrics` helpers name the format so quest configs
+and client code agree on it:
+
+```ts
+import { QuestMetrics } from '@rudder/js-sdk';
+
+QuestMetrics.purchaseOffer('starter-pack'); // "purchase.offer:starter-pack"
+QuestMetrics.purchaseItem('moonberry'); // "purchase.item:moonberry"
+```
+
 ## Scenario effects
 
 The scenario runtime is not exposed directly; scenario nodes surface through
diff --git a/src/index.ts b/src/index.ts
index f0683c0..fc791f4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -27,6 +27,7 @@ export type {
 export type { LeaderboardsService, LeaderboardHandle } from './leaderboards/LeaderboardsService.js';
 export type { BattlePassService } from './battlepass/BattlePassService.js';
 export type { QuestsService } from './quests/QuestsService.js';
+export * as QuestMetrics from './quests/QuestMetrics.js';
 
 // Observable state primitives
 export { SyncedState } from './state/SyncedState.js';
diff --git a/src/quests/QuestMetrics.ts b/src/quests/QuestMetrics.ts
new file mode 100644
index 0000000..7c1d5db
--- /dev/null
+++ b/src/quests/QuestMetrics.ts
@@ -0,0 +1,18 @@
+/**
+ * QuestMetrics — builders for the quest metric strings known to the platform.
+ *
+ * Purchase metrics are reported automatically by the shop purchase fan-out,
+ * so these helpers exist mainly to name the format instead of hardcoding it.
+ * Any other metric is a custom string reported via
+ * {@link QuestsService.reportProgress}.
+ */
+
+/** Metric for purchasing a store offer; auto-reported on purchase. */
+export function purchaseOffer(offerId: string): string {
+  return `purchase.offer:${offerId}`;
+}
+
+/** Metric for purchasing a catalog item; auto-reported on purchase. */
+export function purchaseItem(itemId: string): string {
+  return `purchase.item:${itemId}`;
+}