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

2026-08-29 11:46:20 +03:00
parent 04e3565412
commit 8753239fbd
11 changed files with 936 additions and 0 deletions
@@ -0,0 +1,136 @@
+---
+name: rudder-web-sdk
+description: Use when working with the Rudder TypeScript/JavaScript SDK (@rudder/js-sdk) — the browser/player-facing SDK for the Rudder LiveOps platform. Covers client setup, device/custom auth, observable domains (player, inventory, catalog, stores, remote config, storage), leaderboards, quests, battle pass, scenario effects, and error handling. Load this whenever code imports from @rudder/js-sdk or RudderClient appears.
+---
+
+# Rudder Web SDK (@rudder/js-sdk)
+
+Browser-facing player SDK for the Rudder LiveOps platform. Source of truth:
+`liveops-web-sdk/src` (generated wire types in `src/generated` come from the
+gateway's apigen — never edit them by hand).
+
+## Install
+
+Published to a private registry, not npmjs. Point the `@rudder` scope at it in
+`.npmrc` (anonymous read, no token):
+
+```
+@rudder:registry=https://hub.rudder.build/api/packages/rudder/npm/
+```
+
+```bash
+npm install @rudder/js-sdk
+```
+
+ESM + CJS + `.d.ts`; `type: module`; zero runtime dependencies.
+
+## Init
+
+```ts
+import { RudderClient } from '@rudder/js-sdk';
+
+const client = new RudderClient({
+  baseUrl: 'https://api.rudder.build',   // required
+  projectKey: 'your-project-key',        // required
+  // tokenStore?: TokenStore              — default: localStorage, in-memory fallback
+  // requestTimeoutMs?: number            — default 10000
+  // syncIntervalMs?: number              — revision poll, default 30000 (±20% jitter)
+  // onEffectError?: (error) => void      — default console.error
+  // runtime?: { planStateStore?, loginEvent? }  — advanced, see reference/scenarios.md
+});
+```
+
+`client` is generic: `RudderClient<TConfig extends Record<string, unknown>>`
+types `client.remoteConfig.get()`. Missing `baseUrl`/`projectKey` throws
+`RudderError` with `code: 'sdk/invalid-options'` from the constructor.
+
+Call `client.dispose()` on unmount/HMR to stop the sync poll, wait timers, and
+drop cached state.
+
+## Auth essentials
+
+```ts
+await client.auth.loginWithDevice({ region, language, nickname }); // device id auto-generated/persisted
+await client.auth.loginWithCustom({ customData, region, language, nickname });
+client.auth.logout();
+client.auth.isAuthenticated;                       // boolean
+client.auth.onAuthStateChange(cb);                 // fires immediately, returns unsubscribe
+```
+
+Tokens are saved to the `TokenStore` automatically. The transport injects
+`Authorization: Bearer <token>`, retries GETs, and single-flight refreshes on
+401; a failed refresh clears tokens and emits `signed-out`. Details:
+[reference/auth.md](reference/auth.md).
+
+## Client surface (all domains that exist)
+
+Every member below is a property on `RudderClient`. There is no UGC, wallet
+service, or standalone economy service in this SDK — wallets live on
+`client.player.data.wallets`, and purchases go through `client.stores`.
+
+| Area | Access | Kind |
+|---|---|---|
+| Auth | `client.auth` | service |
+| Player profile + wallets | `client.player` | observable `SyncedState<PlayerProfile>` |
+| Inventory (catalog-merged) | `client.inventory` | observable `SyncedState<InventoryItem[]>` |
+| Catalog | `client.catalog` | observable `SyncedState<Map<string, CatalogItem>>` |
+| Stores / purchases | `client.stores` + `client.stores.purchase(slug, offerId, opts?)` | observable `SyncedState<ShopHandle[]>` |
+| Remote config | `client.remoteConfig` + `.get(key, default?)` | observable, typed |
+| Player storage | `client.storage` + `.save(items)` / `.delete(type)` | observable + mutations |
+| Project storage | `client.projectStorage` + `.save(items)` | observable + mutation |
+| Leaderboards | `client.leaderboards.findBySlug(slug)` | service → cached handle |
+| Battle pass | `client.battlePass` | plain service (no live sync) |
+| Quests | `client.quests` | plain service (no live sync) |
+| Scenario effects | `client.effects.on*` | event subscriptions |
+
+## Observable domains — the shared pattern
+
+`player`, `catalog`, `inventory`, `remoteConfig`, `storage`,
+`projectStorage`, and `stores` all extend `SyncedState<T>`:
+
+- `.data: T | undefined`, `.status: 'idle' | 'loading' | 'ready' | 'error'`,
+  `.error?: Error`
+- `onChange(cb: (snapshot: SyncedSnapshot<T>) => void): () => void` — fires
+  immediately with the current snapshot; maps onto React `useSyncExternalStore`
+- `load(): Promise<T>` — deduplicated, no-op when ready
+- `reload(): Promise<T>` — forced refetch
+
+`remoteConfig`, `player`, `stores`, and `catalog` are warmed once at login;
+`inventory`, `storage`, and `projectStorage` load on first use. All observable
+domains are then kept fresh by a revision poll every 30 s (±20% jitter);
+polling pauses while the tab is hidden. Mutations (purchases, storage writes,
+scenario callbacks) invalidate affected domains immediately. Call `reload()`
+when you need a freshness guarantee.
+
+`leaderboards`, `battlePass`, and `quests` are NOT observable — refetch
+explicitly after mutations.
+
+## Errors
+
+All SDK errors extend `RudderError` (optional machine-readable `code`):
+
+- `RudderNetworkError` — fetch failed / timeout (`error.cause` holds the original)
+- `RudderHttpError` — non-2xx, carries `status`, `statusText`, `body`, `code`
+- `RudderAuthError extends RudderHttpError` — 401 after failed refresh; tokens
+  already cleared, `signed-out` already emitted
+- `RudderError` with `code: 'sdk/invalid-options'` (`SDK_ERROR_INVALID_OPTIONS`)
+  — constructor validation
+
+Server error codes (`RudderErrorCodes`, from `src/generated/errors.ts`):
+`early_completion`, `forbidden`, `level_not_reached`, `node_not_active`,
+`objectives_incomplete`, `run_expired`, `run_not_active`,
+`scenario_not_active`, `unknown_run`. Compare with
+`error.code === RudderErrorCodes.runExpired`.
+
+## Reference files
+
+- [reference/auth.md](reference/auth.md) — login flows, options, token store, session lifecycle
+- [reference/player.md](reference/player.md) — profile + wallets (`PlayerProfile`, `Wallet`)
+- [reference/inventory.md](reference/inventory.md) — inventory domain, merged `InventoryItem`, catalog
+- [reference/stores.md](reference/stores.md) — `ShopHandle`/`OfferHandle`, purchases, idempotency
+- [reference/remote-config.md](reference/remote-config.md) — typed `get()`, value types, overrides
+- [reference/storage.md](reference/storage.md) — player + project storage, limits
+- [reference/leaderboards.md](reference/leaderboards.md) — handles, submit, list
+- [reference/quests.md](reference/quests.md) — list/claim/reportProgress, `QuestMetrics`
+- [reference/battlepass.md](reference/battlepass.md) — progress, XP, claims, premium
+- [reference/scenarios.md](reference/scenarios.md) — effects, scenario runtime, wait/quest/battlepass nodes
@@ -0,0 +1,106 @@
+# Auth — `client.auth`
+
+`AuthService` (source: `src/auth/AuthService.ts`). Player authentication:
+device ID login (primary for game clients), custom webhook login, logout, and
+auth state observation.
+
+## Methods
+
+```ts
+loginWithDevice(options?: LoginWithDeviceOptions): Promise<LoginViaDeviceResponse>
+loginWithCustom(options: LoginWithCustomOptions): Promise<LoginViaCustomResponse>
+logout(): void
+get isAuthenticated(): boolean
+onAuthStateChange(listener: AuthStateListener): () => void
+```
+
+### `LoginWithDeviceOptions`
+
+```ts
+{
+  region?: string;    // default 'global'
+  language?: string;  // default 'en'
+  nickname?: string;  // omitted from the request when not set
+}
+```
+
+The device ID is auto-generated on first call and persisted in localStorage
+(`src/device/DeviceId.ts`). The request also carries the client's
+`projectKey`.
+
+### `LoginWithCustomOptions`
+
+```ts
+{
+  customData: Record<string, unknown>;  // required — forwarded to the project's custom auth webhook
+  region?: string;                      // default 'global'
+  language?: string;                    // default 'en'
+  nickname?: string;
+}
+```
+
+### Login responses
+
+```ts
+interface LoginViaDeviceResponse { accessToken?: string; refreshToken?: string }
+interface LoginViaCustomResponse { accessToken?: string; refreshToken?: string }
+```
+
+On success both tokens are saved to the client's `TokenStore`, the runtime
+starts (domains warmed, scenario engine restored, `player_login` event fired),
+and the state flips to `'signed-in'`.
+
+## Auth state
+
+```ts
+type AuthState = 'signed-in' | 'signed-out';
+type AuthStateListener = (state: AuthState) => void;
+```
+
+- `isAuthenticated` is `true` while an access token is present in the token store.
+- `onAuthStateChange` fires the listener **immediately** with the current state
+  and returns an unsubscribe function.
+- `logout()` clears tokens, stops the runtime (sync poll, scenario runs,
+  cached domain data), and emits `'signed-out'`.
+
+## Token refresh (automatic, transport level)
+
+Source: `src/transport/request.ts`.
+
+- Every request injects `Authorization: Bearer <accessToken>` when a token exists.
+- On 401 the transport does a single-flight refresh against
+  `POST /sdk/v1/authorization/refresh` (concurrent 401s share one refresh) and
+  retries the original request once.
+- If refresh fails, tokens are cleared, `onAuthStateChange` listeners get
+  `'signed-out'`, and the request throws `RudderAuthError`.
+
+## TokenStore
+
+```ts
+interface TokenStore {
+  getAccessToken(): string | null;
+  getRefreshToken(): string | null;
+  saveTokens(accessToken: string, refreshToken: string): void;
+  clear(): void;
+}
+```
+
+Factories (exported from the package root):
+
+- `createDefaultTokenStore()` — localStorage, with a silent in-memory fallback
+  where localStorage is unavailable (SSR, private mode). This is the default
+  when `tokenStore` is omitted from `RudderClientOptions`.
+- `createLocalStorageTokenStore()` — keys `rudder_access_token` /
+  `rudder_refresh_token`.
+
+Provide a custom `TokenStore` via `RudderClientOptions.tokenStore` for other
+backends (sessionStorage, cookies).
+
+## Errors
+
+- Constructor: missing `baseUrl`/`projectKey` → `RudderError`,
+  `code: 'sdk/invalid-options'`.
+- Login failure → `RudderHttpError` (e.g. unknown project key) or
+  `RudderNetworkError`.
+- Any later request with an expired session → `RudderAuthError` (after the
+  refresh attempt above fails).
@@ -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.
@@ -0,0 +1,56 @@
+# Inventory + catalog — `client.inventory`, `client.catalog`
+
+## Inventory
+
+`InventoryDomain` (source: `src/domains/InventoryDomain.ts`) — owned items
+merged with their catalog entries. Synced under revision key `inventory`;
+also refreshed whenever the catalog changes.
+
+```ts
+client.inventory.data   // InventoryItem[] | undefined
+client.inventory.onChange(cb);
+await client.inventory.load() / .reload();
+```
+
+### `InventoryItem` (merged view, source: `src/state/inventory.ts`)
+
+```ts
+interface InventoryItem {
+  slug: string;                        // '' when the wire item has no slug
+  amount: number;                      // 0 when absent on the wire
+  name: string;                        // nameOverride || catalog name || slug
+  properties: Record<string, unknown>; // catalog properties + propertiesOverride (override wins)
+  tags: string[];                      // from the catalog entry
+}
+```
+
+The raw wire shape is `PlayerInventoryItem`
+(`slug?, amount?, nameOverride?, propertiesOverride?, updatedAt?`) — you rarely
+need it; the domain hands out the merged `InventoryItem`.
+
+## Catalog
+
+`CatalogDomain` (source: `src/domains/CatalogDomain.ts`) — the item catalog
+keyed by slug. Synced under revision key `catalog`.
+
+```ts
+client.catalog.data   // Map<string, CatalogItem> | undefined
+
+interface CatalogItem {
+  name?: string;
+  properties?: { [key: string]: unknown };
+  slug?: string;
+  tags?: string[];
+}
+```
+
+Items without a `slug` are skipped when the map is built.
+
+## Behavior notes
+
+- The catalog is warmed at login; inventory loads on first use, waits on the
+  catalog load, and merges, so `client.inventory.data` always has catalog
+  fields filled in.
+- Invalidated after store purchases and scenario callbacks.
+- Inventory has no client-side mutations — items change via purchases, quest /
+  battle pass rewards, and scenario nodes (all server-side).
@@ -0,0 +1,50 @@
+# Leaderboards — `client.leaderboards`
+
+`LeaderboardsService` (source: `src/leaderboards/LeaderboardsService.ts`).
+Plain call-and-response service, NOT observable — refetch explicitly.
+
+## Surface
+
+```ts
+const board = client.leaderboards.findBySlug('weekly-kills'); // cached handle
+await board.submit(score);
+const entries = await board.list(limit?);
+board.getEntries();
+```
+
+## `LeaderboardHandle`
+
+```ts
+class LeaderboardHandle {
+  readonly slug: string;
+
+  getEntries(): readonly RankEntry[];             // last fetched list, [] initially
+  submit(score: number): Promise<void>;
+  list(limit = 100): Promise<readonly RankEntry[]>; // fetches and caches
+}
+```
+
+- `findBySlug(slug)` caches handles per slug — repeated calls return the same
+  instance (and its cached entries).
+- `list(limit)`: `limit <= 0` sends no limit to the server; default is 100.
+- `submit` does not update the cached entries; call `list()` afterwards to see
+  the effect.
+
+## Types
+
+```ts
+interface RankEntry {
+  playerId?: string;
+  playerName?: string;
+  rank?: number;
+  score?: number;
+}
+```
+
+## Notes
+
+- No player-around-me or metadata endpoints are exposed by this SDK — submit
+  and top-N list only.
+- Scenario `leaderboard` nodes surface through
+  `client.effects.onLeaderboard` (`end()`, `rewardClaimed()`) — see
+  `reference/scenarios.md`.
@@ -0,0 +1,53 @@
+# Player profile + wallets — `client.player`
+
+`PlayerDomain` (source: `src/domains/PlayerDomain.ts`) — the observable player
+profile: identity plus currency wallets. Synced under revision key `profile`.
+
+There is no separate wallet service in this SDK. Wallet balances are read from
+the profile and are credited/debited server-side (purchases, quest/battle pass
+rewards, scenario nodes).
+
+## Surface
+
+`client.player` is a `SyncedState<PlayerProfile>`:
+
+```ts
+client.player.data       // PlayerProfile | undefined
+client.player.status     // 'idle' | 'loading' | 'ready' | 'error'
+client.player.onChange((snapshot) => { /* fires immediately */ });
+await client.player.load();
+await client.player.reload();  // force refetch
+```
+
+## Types
+
+```ts
+interface PlayerProfile {
+  player?: Player;
+  wallets?: Wallet[];
+}
+
+interface Player {
+  createdAt?: string;
+  id?: string;
+  language?: string;
+  nickname?: string;
+  projectId?: string;
+  region?: string;
+}
+
+interface Wallet {
+  balance?: number;
+  currency?: string;  // currency code configured in the dashboard
+}
+```
+
+## Behavior notes
+
+- Warmed automatically at login (one of the four parallel warm loads).
+- Invalidated (refetched) after every successful store purchase and after
+  scenario server callbacks — subscribers see fresh balances without waiting
+  for the revision poll.
+- All fields are optional on the wire (`?`); code defensively.
+- React: `useSyncExternalStore` maps directly onto `onChange` (see the SDK
+  README "React recipe").
@@ -0,0 +1,75 @@
+# 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(questId: string): Promise<ClaimQuestResponse>
+reportProgress(metric: string, amount: number): Promise<string[]>  // ids of quests completed by this report
+```
+
+## Types
+
+```ts
+interface Quest {
+  id?: string;
+  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.id) {
+    const res = await client.quests.claim(quest.id);
+    // res.success / res.alreadyClaimed / res.granted
+  }
+}
+const completedIds = 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.
@@ -0,0 +1,63 @@
+# Remote config — `client.remoteConfig`
+
+`ConfigDomain<TConfig>` (source: `src/domains/ConfigDomain.ts`, base class
+`src/state/RemoteConfigState.ts`) — typed remote configuration as an
+observable entity. Synced under revision key `config`.
+
+## Typed access
+
+```ts
+interface GameConfig extends Record<string, unknown> {
+  player_speed: number;
+  feature_x: boolean;
+}
+
+const client = new RudderClient<GameConfig>({ baseUrl, projectKey });
+
+client.remoteConfig.get('player_speed', 200);  // number
+client.remoteConfig.get('feature_x');          // boolean | undefined
+```
+
+`get()` overloads:
+
+```ts
+get(key): TConfig[key] | undefined;
+get(key, defaultValue: TConfig[key]): TConfig[key];
+```
+
+- Values are parsed synchronously from the loaded snapshot according to the
+  config's server-declared `valueType`.
+- Returns the default value (or `undefined`) while not loaded, for unknown
+  keys, and when parsing fails.
+- Parsing rules: `int`/`integer` → `parseInt`; `float`/`double`/`number` →
+  `parseFloat`; `bool`/`boolean` → `value === 'true'`; `json`/`object` →
+  `JSON.parse`; anything else → raw string.
+
+## Observable
+
+```ts
+client.remoteConfig.data      // Map<string, RemoteConfig> | undefined
+client.remoteConfig.onChange(cb);   // fires immediately
+await client.remoteConfig.reload();
+```
+
+```ts
+interface RemoteConfig {
+  active?: boolean; createdAt?: string; description?: string;
+  environment?: string; id?: string; key?: string; projectId?: string;
+  updatedAt?: string; value?: string;
+  valueType?: 'bool' | 'float' | 'int' | 'json' | 'string';
+}
+```
+
+Only configs that are not explicitly `active: false` enter the map (the server
+already filters inactive configs out and may omit the flag).
+
+## Behavior notes
+
+- Warmed at login.
+- Scenario `remote_config_override` nodes patch the local snapshot and fire
+  `client.effects.onConfigChanged({ key })` — the patched value is what
+  `get()` returns afterwards.
+- Without a `TConfig` type argument, `RemoteConfigShape` defaults to
+  `Record<string, unknown>` and `get()` returns `unknown`.
@@ -0,0 +1,161 @@
+# Scenarios + effects — `client.effects`
+
+Scenarios are server-authored node graphs (configured in the dashboard) that
+run per player. The SDK's scenario runtime is deliberately **not** part of the
+public client surface: scenario nodes surface as typed effects through
+`client.effects` (source: `src/effects/EffectsCenter.ts`), and the engine
+itself loads lazily on first login.
+
+## Lifecycle
+
+- The runtime starts after login: scenario state is restored from persistence,
+  then the login event (`'player_login'` by default) is fired to trigger
+  event-driven scenarios.
+- Runs persist to IndexedDB by default, so waits and pending nodes survive
+  page reloads. On restore, each run is reconciled with the server
+  (`unknown_run` / `expired` runs are dropped).
+- `logout()` / `dispose()` clear all runs and persisted state.
+
+### Runtime options (`RudderClientOptions.runtime`)
+
+```ts
+runtime?: {
+  // Scenario plan persistence. undefined = default IndexedDB store (created
+  // lazily); null = disable persistence entirely; or pass a PlanStateStore.
+  planStateStore?: PlanStateStore | null;
+
+  // Scenario event fired automatically after login.
+  // undefined = 'player_login'; null = fire nothing.
+  loginEvent?: string | null;
+}
+```
+
+## Subscribing
+
+Every `on*` method takes a handler `(effect) => void | Promise<void>` and
+returns an unsubscribe function. Errors thrown inside handlers go to the
+`onEffectError` client option (default `console.error`).
+
+```ts
+const off = client.effects.onNotification(async (n) => {
+  showToast(n.title, n.message);
+  await n.done();   // always resolve the session or the run stalls
+});
+```
+
+## Effect types
+
+```ts
+interface Effects {
+  onNotification(handler): EffectUnsubscribe;
+  onStoreOffer(handler): EffectUnsubscribe;
+  onLeaderboard(handler): EffectUnsubscribe;
+  onConfigChanged(handler): EffectUnsubscribe;
+  onWait(handler): EffectUnsubscribe;
+  onScenarioCompleted(handler): EffectUnsubscribe;
+  onScenarioFailed(handler): EffectUnsubscribe;
+  onQuest(handler): EffectUnsubscribe;
+  onBattlePass(handler): EffectUnsubscribe;
+  onBattlePassLevel(handler): EffectUnsubscribe;
+}
+```
+
+### `NotificationEffect` — a notification node became active
+
+```ts
+{ readonly title: string; readonly message: string; done(): Promise<void> }
+```
+
+### `StoreOfferEffect` — a store node became active
+
+```ts
+{
+  readonly store: ShopHandle;
+  readonly offers: readonly OfferHandle[];
+  readonly message?: string;
+  buy(offer: OfferHandle, options?: BuyOptions): Promise<PurchaseOfferResponse>;
+  dismiss(): Promise<void>;   // declines the offer and advances the run
+}
+```
+
+### `LeaderboardEffect` — a leaderboard node became active
+
+```ts
+{ end(): Promise<void>; rewardClaimed(): Promise<void> }
+```
+
+### `ConfigChangedEffect` — a `remote_config_override` node patched config
+
+```ts
+{ readonly key: string }   // client.remoteConfig.get(key) already returns the override
+```
+
+### `WaitEffect` — a wait node became active
+
+```ts
+{ readonly deadlineUtc: Date }   // run resumes automatically at the deadline
+```
+
+### `QuestEffect` — a scenario quest node became active
+
+```ts
+{
+  readonly name: string;
+  readonly objectives: ReadonlyArray<Record<string, unknown>>;
+  reportProgress(objectiveId: string, amount?: number): Promise<void>;
+}
+```
+
+The node auto-completes server-side once every objective is satisfied; the SDK
+crosses the `onComplete` boundary itself when the server reports completion.
+
+### `BattlePassEffect` — a battle pass node became active
+
+```ts
+{
+  getProgress(): Promise<GetBattlePassProgressResponse>;
+  addXp(source: string, amount: number): Promise<AddBattlePassXpResponse>;
+  claimReward(level: number, track?: 'free' | 'premium'): Promise<ClaimBattlePassRewardResponse>;
+  purchasePremium(): Promise<PurchaseBattlePassPremiumResponse>;
+  levelUp(): Promise<void>;
+  end(): Promise<void>;
+}
+```
+
+These wrap `client.battlePass` with the run's `scenarioId`/`nodeId`/`runId`
+already bound — prefer them over calling the service manually.
+
+### `BattlePassLevelEffect` — a `battlepass_level` node (single claimable tier)
+
+```ts
+{ readonly level: number; claim(): Promise<void> }
+```
+
+### Run lifecycle effects
+
+```ts
+interface ScenarioCompletedEffect { readonly runId: string; readonly scenarioId: string }
+interface ScenarioFailedEffect {
+  readonly runId: string; readonly scenarioId: string; readonly nodeId: string;
+  readonly error: Error;   // transport gave up, or unsupported node type
+}
+```
+
+Always subscribe to `onScenarioFailed` — otherwise run failures surface only
+as console warnings.
+
+## Supported node types
+
+`wait`, `remote_config_override`, `notification`, `store`, `leaderboard`,
+`quest`, `battlepass`, `battlepass_level`. Any other node type fails the run
+(surfaced via `onScenarioFailed`).
+
+## Reliability notes
+
+- Node completion is idempotent client-side (completed handles are tracked).
+- Transient boundary failures (network error, 5xx) leave the node active for
+  retry on reconnect; terminal server errors fail the run.
+- Server scenario errors use the typed codes `run_expired`, `run_not_active`,
+  `node_not_active`, `scenario_not_active`, `unknown_run`,
+  `early_completion`, `objectives_incomplete`, `level_not_reached`,
+  `forbidden` (`RudderErrorCodes`).
@@ -0,0 +1,69 @@
+# Storage — `client.storage` + `client.projectStorage`
+
+Two key/value stores: per-player (`StorageDomain`, revision key `storage`) and
+project-wide shared (`ProjectStorageDomain`, revision key `projectStorage`).
+Sources: `src/domains/StorageDomain.ts`, `src/domains/ProjectStorageDomain.ts`.
+
+## Player storage
+
+```ts
+client.storage.data    // GetStorageResponse | undefined
+await client.storage.save(items);
+await client.storage.delete(type);
+```
+
+```ts
+interface GetStorageResponse {
+  items?: StorageItem[];
+  nextCursor?: string;
+}
+interface StorageItem {
+  data?: string;   // opaque payload, JSON-stringify yourself if needed
+  id?: string;
+  type?: string;   // the storage "collection" key
+}
+```
+
+- `save(items: StorageItem[]): Promise<void>` — upserts items, then
+  invalidates the domain so subscribers refetch.
+- `delete(type: string): Promise<void>` — deletes **all** player storage items
+  of that type, then invalidates.
+
+## Project storage
+
+```ts
+client.projectStorage.data   // GetProjectStorageResponse | undefined
+await client.projectStorage.save(items);
+```
+
+```ts
+interface GetProjectStorageResponse {
+  items?: ProjectStorageItem[];
+  nextCursor?: string;
+}
+interface ProjectStorageItem {
+  data?: string;
+  expiresAt?: string;
+  id?: string;
+  readPermission?: 'public' | 'serverOnly';
+  size?: number;
+  type?: string;
+  updatedAt?: string;
+  version?: number;
+  writePermission?: 'public' | 'serverOnly';
+}
+interface ProjectStorageUpdateItem { data?: string; type?: string }
+```
+
+- `save(items: ProjectStorageUpdateItem[]): Promise<void>` — upserts, then
+  invalidates. Writing is only possible for items whose `writePermission` is
+  `public`; `serverOnly` items are read-only for clients.
+- The SDK exposes no client-side project-storage delete.
+
+## Limits and notes
+
+- Both domains load with `{ limit: 100 }` — the observable snapshot holds at
+  most 100 items and `nextCursor` pagination is not surfaced by the domain.
+- `data` is a raw string on the wire; serialize/deserialize JSON yourself.
+- Both are observable (`SyncedState`) and warmed by the revision poll only when
+  in use; mutations self-invalidate.
@@ -0,0 +1,80 @@
+# Stores / purchases — `client.stores`
+
+`StoresDomain` (source: `src/domains/StoresDomain.ts`, handles in
+`src/state/shops.ts`). The observable store list plus the purchase executor.
+Synced under revision key `stores`. This is the SDK's economy surface — there
+is no separate economy service.
+
+## Surface
+
+```ts
+client.stores.data       // ShopHandle[] | undefined
+client.stores.onChange(cb);
+await client.stores.load() / .reload();
+
+// Direct purchase (bypassing handles):
+await client.stores.purchase(storeSlug, offerId, options?);
+```
+
+## Handles
+
+```ts
+class ShopHandle {
+  readonly slug: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly data?: { [key: string]: unknown };
+  readonly offers: OfferHandle[];
+}
+
+class OfferHandle {
+  readonly id: string;
+  readonly name?: string;
+  readonly price?: OfferPrice;        // { amount?: number; currency?: string }
+  readonly contents: OfferContent[];  // { amount?: number; itemId?: string }[]
+  readonly maxPurchases?: number;
+
+  buy(options?: BuyOptions): Promise<PurchaseOfferResponse>;
+}
+
+interface BuyOptions { idempotencyKey?: string }
+
+interface PurchaseOfferResponse {
+  error?: string;
+  purchaseId?: string;
+  success?: boolean;
+}
+```
+
+## Purchase semantics
+
+- `stores.purchase(storeSlug, offerId, options?)` and `offer.buy(options?)` are
+  the same executor; handles just bind the slug/id.
+- When `options.idempotencyKey` is omitted the SDK generates
+  `crypto.randomUUID()` per call — safe retries require passing your own key.
+- On success the executor invalidates `player`, `inventory`, and `stores`, so
+  subscribers observe fresh wallet/inventory/store data immediately.
+- Check `response.success` / `response.error` — a failed purchase is a resolved
+  response, not necessarily a thrown error.
+- Purchase metrics (`purchase.offer:<offerId>`, `purchase.item:<itemId>`) are
+  reported to quests automatically server-side — do not report them manually
+  (see `reference/quests.md`).
+
+## Wire types
+
+```ts
+interface Store {
+  createdAt?: string; data?: { [key: string]: unknown }; description?: string;
+  environment?: string; id?: string; name?: string; offers?: Offer[];
+  projectId?: string; scenarioId?: string; slug?: string; status?: string;
+  updatedAt?: string;
+}
+interface Offer {
+  contents?: OfferContent[]; createdAt?: string; id?: string;
+  maxPurchases?: number; name?: string; price?: OfferPrice; updatedAt?: string;
+}
+```
+
+`ShopHandle`/`OfferHandle` throw a plain `Error` if constructed from a store
+without `slug` / an offer without `id` — in practice the domain only builds
+handles from server data that has both.