@clocktone/game-sdk 1.0.0

package/docs/game-integration-guide.md

@@ -0,0 +1,449 @@
+# Game Integration Guide
+
+How to add the PlayLoop SDK to your game using the CDN loader — the only supported integration path.
+
+## Overview
+
+The `@clocktone/game-sdk` npm package provides:
+
+- **CDN loader** (`loadPlayLoopSDK`) — thin bootstrap that fetches the SDK from CDN at runtime
+- **TypeScript types** — `PlayLoopSDK`, `PlayLoopSDKConfig`, `UIConfig`, etc.
+- **Native Capacitor plugins** (Android) — `PlayLoopDeviceIdPlugin` (App Set ID) and `PlayLoopAppLovinMaxPlugin` (ads)
+
+The full SDK runtime (~2.8 MB, includes Statsig) is **not bundled** into your game. Instead, the loader injects it from CDN at startup. This allows SDK updates without game rebuilds and enables Statsig-gated version rollouts.
+
+## Install
+
+```bash
+npm install @clocktone/game-sdk
+```
+
+## Architecture: How SDK Loading Works
+
+```
+Game bundle                          CDN
+┌──────────────────┐    ┌─────────────────────────────┐
+│  loadPlayLoopSDK │───>│ GET /api/games/sdk-version  │
+│  (~2 KB loader)  │    │ → { version, url, enabled } │
+│                  │    └─────────────────────────────┘
+│                  │                 │
+│                  │    ┌────────────▼────────────────┐
+│                  │<───│ <script> playloop-sdk.js    │
+│                  │    │ (~2.8 MB IIFE from CDN)     │
+│                  │    └─────────────────────────────┘
+│                  │
+│  window.PlayLoopSDK.PlayLoopSDK  ← typed constructor
+└──────────────────┘
+```
+
+1. Game imports `loadPlayLoopSDK` from `@clocktone/game-sdk/loader`
+2. Loader calls `GET {apiBaseUrl}/api/games/sdk-version` — backend returns a CDN URL (version controlled via Statsig dynamic config)
+3. Loader injects a `<script>` tag for the IIFE bundle
+4. `window.PlayLoopSDK` becomes available — loader returns the typed constructor
+5. If the version fetch fails, the loader falls back to a hardcoded CDN URL
+
+The type re-exports (`PlayLoopSDK`, `PlayLoopSDKConfig`, `UIConfig`) are **type-only** — zero SDK runtime code ends up in your game bundle.
+
+See the [Loader API Reference](loader.md) for full details.
+
+## Creating an Integration Wrapper
+
+We recommend wrapping all SDK interactions in a game-specific class. This keeps SDK concerns out of core game logic and provides a single place to manage lifecycle, ads, and rewards.
+
+Block Blast's `PlayLoopIntegration.ts` is the canonical reference. The key pattern:
+
+```typescript
+import { loadPlayLoopSDK } from '@clocktone/game-sdk/loader';
+import type {
+  PlayLoopSDK as PlayLoopSDKInstance,
+  PlayLoopSDKConfig,
+} from '@clocktone/game-sdk/loader';
+
+type SDKConstructor = new (config: PlayLoopSDKConfig) => PlayLoopSDKInstance;
+
+export class PlayLoopIntegration {
+  private sdk: PlayLoopSDKInstance;
+  private disposeCallbacks: (() => void)[] = [];
+
+  /** Factory: load SDK from CDN, detect mode, construct instance */
+  static async create(): Promise<PlayLoopIntegration> {
+    const embeddedCfg = PlayLoopIntegration.getEmbeddedConfig();
+    const apiBaseUrl = embeddedCfg?.apiBaseUrl ?? 'https://api.vbackendapi.com';
+    const SDK = await loadPlayLoopSDK({ apiBaseUrl });
+    return new PlayLoopIntegration(SDK as unknown as SDKConstructor, embeddedCfg);
+  }
+
+  /** Read host-injected config (set by React Native's usePlayLoopGameBridge) */
+  static getEmbeddedConfig() {
+    const cfg = (window as any).__CASHABLE_CONFIG__;
+    return cfg?.clientId && cfg?.apiBaseUrl ? cfg : null;
+  }
+
+  private constructor(SDK: SDKConstructor, embeddedCfg: { clientId: string; apiBaseUrl: string } | null) {
+    const isEmbedded = !!embeddedCfg;
+    const config: PlayLoopSDKConfig = {
+      gameId: 'your-game-id',
+      apiBaseUrl: embeddedCfg?.apiBaseUrl ?? 'https://api.vbackendapi.com',
+      debug: true,
+      ...(embeddedCfg ? { clientId: embeddedCfg.clientId } : {}),
+      ...(!isEmbedded ? {
+        mode: 'standalone' as const,
+        appLovin: { /* your ad unit IDs */ },
+      } : {}),
+      ui: { /* see Dual-Mode Configuration below */ },
+    };
+    this.sdk = new SDK(config);
+  }
+
+  async initialize(): Promise<void> {
+    await this.sdk.init();
+  }
+
+  dispose(): void {
+    for (const unsub of this.disposeCallbacks) unsub();
+    this.disposeCallbacks = [];
+    this.sdk.dispose();
+  }
+}
+```
+
+Your game code only ever calls `PlayLoopIntegration.create()` and methods on the returned instance — never the SDK directly.
+
+## Loading the SDK
+
+```typescript
+import { loadPlayLoopSDK } from '@clocktone/game-sdk/loader';
+import type { PlayLoopSDK, PlayLoopSDKConfig } from '@clocktone/game-sdk/loader';
+
+const SDK = await loadPlayLoopSDK({ apiBaseUrl: 'https://api.vbackendapi.com' });
+```
+
+`loadPlayLoopSDK` returns the `PlayLoopSDK` constructor (not an instance). You then create an instance with your config and call `init()`.
+
+## Dual-Mode Configuration (Embedded + Standalone)
+
+Every PlayLoop game runs in two contexts:
+
+| | Embedded | Standalone |
+|---|---|---|
+| **Context** | WebView inside PlayLoop app | Capacitor-wrapped APK |
+| **How it starts** | PlayLoop app loads your game URL in a WebView | User opens your standalone APK |
+| **Auth** | Host injects `window.__CASHABLE_CONFIG__` with `clientId` | SDK uses App Set ID via Capacitor plugin |
+| **Ads** | Host app shows ads via native bridge | SDK uses AppLovin MAX via Capacitor plugin |
+
+### Detecting the Mode
+
+The host PlayLoop app injects `window.__CASHABLE_CONFIG__` before your game loads. Check for it:
+
+```typescript
+const hostCfg = (window as any).__CASHABLE_CONFIG__;
+const isEmbedded = !!hostCfg?.clientId;
+```
+
+`__CASHABLE_CONFIG__` shape: `{ gameId: string, clientId: string, apiBaseUrl: string, debug?: boolean }`
+
+### Embedded Mode Config
+
+When running inside the PlayLoop app, pass the host-provided `clientId`. Don't set `mode` (auto-detected via `window.ReactNativeWebView`). Don't configure `appLovin` (host handles ads via native bridge).
+
+```typescript
+const config: PlayLoopSDKConfig = {
+  gameId: 'your-game-id',
+  apiBaseUrl: hostCfg.apiBaseUrl,
+  clientId: hostCfg.clientId,
+  debug: hostCfg.debug ?? false,
+  ui: {
+    showPlayLoopButton: true,
+    showClose: true,
+    showMenu: true,
+    cashableButton: { position: 'top-left' },
+  },
+};
+```
+
+### Standalone Mode Config
+
+Set `mode: 'standalone'` explicitly, provide your AppLovin ad unit IDs, and wire up `onClose`:
+
+```typescript
+const config: PlayLoopSDKConfig = {
+  gameId: 'your-game-id',
+  mode: 'standalone',
+  apiBaseUrl: 'https://api.vbackendapi.com',
+  debug: true,
+  appLovin: {
+    sdkKey: 'YOUR_APPLOVIN_SDK_KEY',
+    rewardedAdUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
+    interstitialAdUnitId: 'YOUR_INTERSTITIAL_AD_UNIT_ID',
+    bannerAdUnitId: 'YOUR_BANNER_AD_UNIT_ID',
+  },
+  ui: {
+    showPlayLoopButton: true,
+    showClose: true,
+    showMenu: true,
+    cashableButton: { position: 'top-left' },
+    onClose: () => {
+      // Use dynamic import — @capacitor/core is not available in WebView
+      import('@capacitor/core').then(({ Capacitor }) => {
+        if (Capacitor.isNativePlatform()) {
+          import('@capacitor/app').then(({ App }) => App.exitApp());
+        }
+      }).catch(() => {});
+    },
+  },
+};
+```
+
+> **Important**: Always use dynamic `import('@capacitor/core')` — never a static import. Static imports fail in the WebView (embedded mode) where Capacitor is not available.
+
+### Putting It Together
+
+```typescript
+const hostCfg = (window as any).__CASHABLE_CONFIG__;
+const isEmbedded = !!hostCfg?.clientId;
+
+const config: PlayLoopSDKConfig = {
+  gameId: 'your-game-id',
+  apiBaseUrl: isEmbedded ? hostCfg.apiBaseUrl : 'https://api.vbackendapi.com',
+  debug: true,
+  // Embedded: pass clientId from host
+  ...(isEmbedded ? { clientId: hostCfg.clientId } : {}),
+  // Standalone: set mode + appLovin
+  ...(!isEmbedded ? {
+    mode: 'standalone' as const,
+    appLovin: {
+      sdkKey: 'YOUR_APPLOVIN_SDK_KEY',
+      rewardedAdUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
+      interstitialAdUnitId: 'YOUR_INTERSTITIAL_AD_UNIT_ID',
+      bannerAdUnitId: 'YOUR_BANNER_AD_UNIT_ID',
+    },
+  } : {}),
+  ui: {
+    showPlayLoopButton: true,
+    showClose: true,
+    showMenu: true,
+    cashableButton: { position: 'top-left' },
+    onClose: () => {
+      if (isEmbedded) return; // Host handles close via bridge
+      import('@capacitor/core').then(({ Capacitor }) => {
+        if (Capacitor.isNativePlatform()) {
+          import('@capacitor/app').then(({ App }) => App.exitApp());
+        }
+      }).catch(() => {});
+    },
+  },
+};
+```
+
+## Initialization
+
+```typescript
+const cashable = new SDK(config);
+await cashable.init();
+```
+
+`init()` is async — it sets up transports, authenticates, initializes feature flags and ads, and renders the UI. Wait for it to resolve before using any SDK module.
+
+After init, show a banner ad:
+
+```typescript
+cashable.ads.showBanner('bottom').catch(() => {});
+```
+
+## Wiring Lifecycle Events
+
+The PlayLoop app (and standalone ad overlays) freeze/resume your game. You **must** handle these:
+
+```typescript
+const unsubFreeze = cashable.onFreeze(() => {
+  // Pause game logic, audio, timers, animations
+  game.pause();
+});
+
+const unsubResume = cashable.onResume(() => {
+  // Resume game logic
+  game.resume();
+});
+```
+
+### Babylon.js
+
+If your game uses Babylon.js, bind the scene for automatic render loop freeze/resume:
+
+```typescript
+cashable.babylon.bindScene(scene, engine);
+```
+
+This handles `engine.stopRenderLoop()` / `engine.runRenderLoop()` for you. If your game uses a custom RAF loop instead of `engine.runRenderLoop`, you'll need to wire freeze/resume manually (as shown above).
+
+## Wiring Game Events
+
+### Awarding Coins
+
+Call `rewards.awardCoins()` whenever the player earns something (score, level clear, line clear, etc.):
+
+```typescript
+cashable.rewards.awardCoins().catch((e) => {
+  console.warn('awardCoins failed:', e);
+});
+```
+
+The SDK handles multipliers (2x boost), coin animations, and host notification automatically.
+
+### Sponsored Interstitials
+
+Trigger sponsored interstitials on gameplay milestones (e.g., piece placed, level completed). The SDK manages cooldowns — safe to call frequently:
+
+```typescript
+cashable.ui?.showSponsoredInterstitial().catch(() => {});
+```
+
+This shows a 3-second countdown modal, then the ad, then awards coins on success. `cashable.ui` is `null` when the user isn't authenticated, so always use optional chaining.
+
+### Banner Ads
+
+Show a banner after initialization:
+
+```typescript
+cashable.ads.showBanner('bottom').catch(() => {});
+```
+
+Hide or destroy it when needed:
+
+```typescript
+await cashable.ads.hideBanner();   // Hides (can show again)
+await cashable.ads.destroyBanner(); // Destroys (must call showBanner again)
+```
+
+## TopBar Offset
+
+The SDK renders a floating UI (PlayLoopButton panel) that overlaps your game canvas. You need to offset your HUD elements below it.
+
+### Before `init()` — computed estimate
+
+`getWidgetHeight()` computes the height from `window.innerWidth` with no DOM or `init()` required. Use it at script load time so your layout is correct from the first frame:
+
+```typescript
+// From loader (works before CDN script loads)
+import { getWidgetHeight } from '@clocktone/game-sdk/loader';
+const cssPx = getWidgetHeight();
+game.setTopOffset(cssPx);
+```
+
+Or from the SDK constructor (CDN users):
+
+```typescript
+const cssPx = PlayLoopSDK.getWidgetHeight();
+```
+
+### After `init()` — exact DOM value
+
+Register `onWidgetReady` before calling `init()` to receive the real DOM-measured height:
+
+```typescript
+const cashable = new SDK(config);
+cashable.onWidgetReady(({ height }) => {
+  game.setTopOffset(height); // refine with real value
+});
+await cashable.init();
+```
+
+You can also read it synchronously after init:
+
+```typescript
+const cssPx = cashable.getTopBarHeight();
+```
+
+### Converting to Babylon.js GUI Coordinates
+
+If your game uses Babylon.js GUI with an ideal height (e.g., 960):
+
+```typescript
+const idealHeight = 960;
+const idealPx = Math.round((cssPx / window.innerHeight) * idealHeight);
+// Use idealPx as the top offset for your HUD elements
+```
+
+## Build Configuration (Vite)
+
+### `base: './'` (Required)
+
+Games are served from a subpath on the CDN (`vbackendapi.com/games/<game-id>/`). Using the default `base: '/'` causes asset URLs to resolve to the CDN root instead of the game directory.
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: './',
+  // ...
+});
+```
+
+### Externalize `@capacitor/core`
+
+Capacitor is only available in standalone mode (native APK). In embedded mode (WebView), it doesn't exist. Always use dynamic `import()` in your code and externalize the package so Vite doesn't try to bundle it:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: './',
+  build: {
+    rollupOptions: {
+      external: ['@clocktone/game-sdk'],
+      output: {
+        inlineDynamicImports: true,
+      },
+    },
+  },
+});
+```
+
+> The SDK itself is loaded from CDN, so it should be external. Dynamic imports of `@capacitor/core` and `@capacitor/app` are resolved at runtime by Capacitor's native layer.
+
+### Relative Fetch URLs
+
+All `fetch()` calls for game assets must use **relative** paths:
+
+```typescript
+// Correct — resolves relative to game's index.html
+fetch('./config/data.json')
+
+// Wrong — resolves to CDN root, not game subpath
+fetch('/config/data.json')
+```
+
+## Cleanup
+
+Always dispose the SDK when your game shuts down:
+
+```typescript
+cashable.dispose();
+```
+
+This stops analytics tracking, removes event listeners, aborts pending requests, tears down the UI, and cleans up the Babylon.js plugin.
+
+## Testing
+
+### Standalone (Capacitor APK)
+
+```bash
+# 1. Build your game's web assets
+npm run build
+
+# 2. Sync to Capacitor
+npx cap sync android
+
+# 3. Build the APK
+cd android
+JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew assembleDebug
+cd ..
+
+# 4. Install on device
+adb install -r android/app/build/outputs/apk/debug/app-debug.apk
+```
+
+### Embedded (WebView in PlayLoop App)
+
+1. Build your game's web assets (`npm run build`)
+2. Upload the `dist/` directory (including `config/` and any other asset directories) to R2 CDN
+3. Bump the `?v=N` cache parameter on the game's play URL in the backend
+4. Open the game from within the PlayLoop app

package/docs/loader.md

@@ -0,0 +1,113 @@
+# CDN Loader
+
+Thin bootstrap that loads the full PlayLoop SDK from CDN at runtime. Games bundle only the loader (~2 KB) — the SDK itself is fetched dynamically.
+
+**Import path**: `@clocktone/game-sdk/loader`
+
+## `loadPlayLoopSDK(options): Promise<typeof PlayLoopSDK>`
+
+Loads the SDK from CDN and returns the constructor.
+
+```typescript
+import { loadPlayLoopSDK } from '@clocktone/game-sdk/loader';
+import type { PlayLoopSDK, PlayLoopSDKConfig } from '@clocktone/game-sdk/loader';
+
+const SDK = await loadPlayLoopSDK({ apiBaseUrl: 'https://api.vbackendapi.com' });
+const cashable = new SDK({ gameId: 'my-game' });
+await cashable.init();
+```
+
+### Steps
+
+1. **Shims `window.CapacitorCore`** — the IIFE's UMD globals wrapper expects `CapacitorCore` to exist. In standalone mode (Capacitor available), the shim maps to the real `Capacitor` object. In embedded mode (WebView), it's an empty stub so the IIFE doesn't crash.
+
+2. **Fetches SDK version** — `GET {apiBaseUrl}/s/arcade/sdk-ver` returns `{ version, url, enabled }`. The backend uses Statsig dynamic config (`sdk_version_config`) for targeted version rollouts and a kill switch gate (`sdk_cdn_disabled`) to disable CDN delivery entirely.
+
+3. **Injects `<script>` tag** — appends the IIFE bundle URL to `document.head`.
+
+4. **Returns typed constructor** — reads `window.PlayLoopSDK.PlayLoopSDK` and returns it with full TypeScript types.
+
+## `LoaderOptions`
+
+```typescript
+interface LoaderOptions {
+  /** Backend base URL (e.g. "https://api.vbackendapi.com") */
+  apiBaseUrl: string;
+  /** Hardcoded fallback CDN URL if version fetch fails */
+  fallbackUrl?: string;
+  /** Timeout for the version-fetch request (default: 5000ms) */
+  timeoutMs?: number;
+}
+```
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `apiBaseUrl` | `string` | Yes | — | Backend base URL used to fetch the SDK version |
+| `fallbackUrl` | `string` | No | `https://getplayloop.com/sdk/v0.7.0/playloop-sdk.js` | CDN URL used when the version fetch fails |
+| `timeoutMs` | `number` | No | `5000` | Timeout in milliseconds for the version-fetch request |
+
+## Version Resolution
+
+The loader calls `GET {apiBaseUrl}/s/arcade/sdk-ver`. The backend:
+
+1. Identifies the user via `X-Device-Token` or `X-Install-Token` headers
+2. Checks the `sdk_cdn_disabled` Statsig gate — if true, returns `enabled: false`
+3. Reads the `sdk_version_config` Statsig dynamic config for the `version` field
+4. Returns `{ version, url, enabled }` where `url` is `{SDK_CDN_BASE_URL}/v{version}/playloop-sdk.js`
+
+If the version fetch fails (network error, timeout, non-JSON response), the loader silently falls back to the hardcoded `fallbackUrl`.
+
+## CapacitorCore Shim
+
+The SDK's IIFE bundle uses a UMD/globals wrapper that expects `window.CapacitorCore` for `@capacitor/core` imports. The loader creates this shim before loading the script:
+
+- **Standalone mode** (`window.Capacitor` exists): shim maps `CapacitorCore.Capacitor` and `CapacitorCore.registerPlugin` to the real Capacitor runtime
+- **Embedded mode** (WebView, no Capacitor): shim is an empty object `{}` — SDK code that checks for Capacitor gracefully handles its absence
+
+This happens automatically — game code doesn't need to do anything.
+
+## `getWidgetHeight(): number`
+
+Computes the widget top-bar height from `window.innerWidth` alone — no SDK load or `init()` required. The formula mirrors the CSS layout of the PlayLoopButton trigger row. Use it at script load time to offset your game canvas before the CDN script even loads:
+
+```typescript
+import { getWidgetHeight } from '@clocktone/game-sdk/loader';
+
+const cssPx = getWidgetHeight();
+game.setTopOffset(cssPx);
+```
+
+## Type Re-exports
+
+The loader re-exports types from the parent package for convenience. These are **type-only** — zero runtime cost, nothing added to your bundle:
+
+| Export | Description |
+|--------|-------------|
+| `PlayLoopSDK` | SDK instance type (constructor signature, all module accessors) |
+| `PlayLoopSDKConfig` | Configuration object passed to `new PlayLoopSDK(config)` |
+| `UIConfig` | UI configuration subset (`onClose`, `showPlayLoopButton`, etc.) |
+
+```typescript
+import type { PlayLoopSDK, PlayLoopSDKConfig, UIConfig } from '@clocktone/game-sdk/loader';
+```
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Version fetch fails (network error, timeout) | Silently falls back to `fallbackUrl`. Warning logged to console. |
+| Version fetch returns `enabled: false` | Uses `fallbackUrl` (CDN URL from response is ignored). |
+| Script tag fails to load (`onerror`) | **Throws** `Error: Failed to load SDK from {url}` |
+| Script loads but `window.PlayLoopSDK.PlayLoopSDK` is missing | **Throws** `Error: window.PlayLoopSDK.PlayLoopSDK not found after script load` |
+
+Wrap `loadPlayLoopSDK` in a try-catch if you want to handle load failures gracefully:
+
+```typescript
+try {
+  const SDK = await loadPlayLoopSDK({ apiBaseUrl: 'https://api.vbackendapi.com' });
+  // SDK loaded successfully
+} catch (err) {
+  console.error('Failed to load PlayLoop SDK:', err);
+  // Start game without SDK integration
+}
+```

package/docs/rewards.md

@@ -0,0 +1,57 @@
+# Rewards Module
+
+Handles coin awarding and reward notifications.
+
+**Accessor**: `cashable.rewards`
+
+## Methods
+
+### `awardCoins(opts?): Promise<{ coins: number }>`
+
+Awards coins to the current user. Typically called after a rewarded video ad completes.
+
+```typescript
+const { coins } = await cashable.rewards.awardCoins();
+console.log(`Awarded! New balance: ${coins}`);
+```
+
+**Parameters**:
+
+| Name | Type | Description |
+|---|---|---|
+| `opts.multiplier` | `number` (optional) | Coin multiplier (e.g. `2` for double coins) |
+
+```typescript
+// Award with multiplier
+const { coins } = await cashable.rewards.awardCoins({ multiplier: 2 });
+```
+
+**Returns**: `{ coins: number }` - the updated coin balance.
+
+**Throws**: Error with `code: 'USER_NOT_LINKED'` if the user isn't authenticated.
+
+### `onCoinsAwarded(handler): () => void`
+
+Subscribes to coin award notifications. Fired both when `awardCoins()` completes and when the host pushes a `rewards.coinsAwarded` event (e.g., bonus awards).
+
+```typescript
+const unsub = cashable.rewards.onCoinsAwarded(({ coins }) => {
+  updateUI(coins);
+});
+
+// Later: stop listening
+unsub();
+```
+
+## Typical Flow
+
+```typescript
+// 1. Show an ad
+const adSuccess = await cashable.ads.showRewardedVideo();
+
+// 2. If the user watched it, award coins
+if (adSuccess) {
+  const { coins } = await cashable.rewards.awardCoins();
+  showCoinAnimation(coins);
+}
+```

package/docs/session.md

@@ -0,0 +1,43 @@
+# Session Module
+
+Handles user identity and balance retrieval.
+
+**Accessor**: `cashable.session`
+
+## Methods
+
+### `getBalance(): Promise<{ coins: number }>`
+
+Retrieves the current coin balance for the authenticated user.
+
+```typescript
+const { coins } = await cashable.session.getBalance();
+console.log(`Balance: ${coins} coins`);
+```
+
+**Throws**: Error with `code: 'USER_NOT_LINKED'` in standalone mode if the user hasn't been linked yet.
+
+## Internal Behavior
+
+### Embedded mode
+
+The host app manages identity. The session module is a passthrough - `getBalance()` sends a `session.getBalance` request through the WebView bridge.
+
+### Standalone mode
+
+On `init()`, the session module:
+
+1. Dynamically imports `@clocktone/capacitor-device-id`
+2. Calls `getAppSetId()` to get the device's App Set ID
+3. Sets the `X-Install-Token` header on all outgoing HTTP requests
+
+The backend resolves this header to a known user via a Redis mapping. If no mapping exists, requests that require authentication will return 401.
+
+## Auth Headers
+
+For advanced use, you can access the auth headers that the session module generates:
+
+```typescript
+// Returns { 'X-Install-Token': '...' } in standalone, {} in embedded
+const headers = cashable.session.getAuthHeaders();
+```