Add agent skill (SKILL.md + per-domain reference)
This commit is contained in:
edmand46
@@ -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.
|
||||
Reference in New Issue
Block a user