@clocktone/game-sdk 1.0.0

package/docs/ui.md

@@ -0,0 +1,248 @@
+# UI Module
+
+Standalone-mode UI overlay: top bar, sponsored interstitials, bonus/booster offers, tier celebrations, and coin toasts.
+
+**Accessor**: `cashable.ui` (nullable — `null` in embedded mode or when the user is not authenticated)
+
+## Overview
+
+The UI module renders a DOM overlay on top of the game canvas in standalone mode. It provides:
+
+- **PlayLoopButton** — floating button that opens a panel with three content areas:
+  - **Rewards tab (main screen)** — coins pill, tier card with progress bar, "Convert coins to real money" CTA button, partners section
+  - **Cashout screen (sub-screen)** — countdown timer, earnings display, cashout button (with wait modal), partners. Accessed via the CTA button; back button returns to main screen
+  - **Games tab** — lists available games
+- **SponsoredModal** — animated countdown before interstitial ads
+- **BonusOfferModal** — periodic bonus coin offers (watch ad to claim)
+- **BoostOfferModal** — 2x coin multiplier activation (watch ad to activate)
+- **TierCelebrationModal** — tier-up celebrations with optional ad-doubled rewards
+- **CoinToast** — floating "+N coins" notifications
+
+The module is initialized automatically during `cashable.init()` when running in standalone mode with an authenticated user. The `showPlayLoopButton` config option (default: `false`) controls whether the floating button is rendered.
+
+### PlayLoopButton Config
+
+```typescript
+ui: {
+  showPlayLoopButton: true,
+  cashableButton: {
+    position: 'top-left',  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+    autoPeek: false,        // Auto-open panel briefly on first wallet data (default: true)
+  },
+  onClose: () => { /* handle close */ },
+  onMenuOpen: () => { /* handle menu */ },
+}
+```
+
+## Methods
+
+### `showSponsoredInterstitial(): Promise<boolean>`
+
+Shows a sponsored interstitial ad flow:
+
+1. Reserves a reward amount from the backend (`rewards.reserveSponsoredVideo`)
+2. Shows a 3-second animated countdown modal
+3. Plays the interstitial ad
+4. On success: claims the reward (`rewards.claimSponsoredVideo`), updates coin balance, shows toast
+5. On failure: shows "Video unavailable" state
+
+Returns `true` if the ad was shown and the reward was claimed. Returns `false` if the interstitial is on cooldown, the reservation fails, or the ad fails.
+
+```typescript
+const success = await cashable.ui?.showSponsoredInterstitial();
+if (success) {
+  console.log('User earned coins from sponsored video');
+}
+```
+
+### `showCoinAward(newTotalCoins): void`
+
+Calculates the delta from the current balance, updates the displayed coin count, and shows a coin toast for the difference.
+
+- `newTotalCoins: number` — the user's new total coin balance
+
+```typescript
+cashable.ui?.showCoinAward(1500); // If user had 1400, shows "+100 coins" toast
+```
+
+### `showCoinToast(amount, note?): void`
+
+Shows a floating coin toast notification. Automatically appends "Includes 2x boost" when a boost is active and no custom note is provided.
+
+- `amount: number` — coins earned
+- `note?: string` — optional note text
+
+```typescript
+cashable.ui?.showCoinToast(50, 'Bonus reward!');
+```
+
+### `updateCoins(coins): void`
+
+Updates the displayed coin count in the panel and triggers a tier advancement check.
+
+- `coins: number` — new total coin balance
+
+```typescript
+cashable.ui?.updateCoins(2000);
+```
+
+### `updateThemeColor(color): void`
+
+Changes the panel background color. The panel automatically adjusts text/icon colors for contrast.
+
+- `color: string` — CSS color value (e.g. `'#1a1a2e'`)
+
+```typescript
+cashable.ui?.updateThemeColor('#1a1a2e');
+```
+
+### `refreshWallet(): Promise<void>`
+
+Re-fetches wallet data from the backend (`session.getWallet`) and updates all UI elements (coins, tier progress).
+
+```typescript
+await cashable.ui?.refreshWallet();
+```
+
+### `getTopBarHeight(): number`
+
+Returns the current pixel height of the panel trigger row. Useful for positioning game content below the button.
+
+```typescript
+const offset = cashable.ui?.getTopBarHeight() ?? 0;
+gameCanvas.style.marginTop = `${offset}px`;
+```
+
+Also available as a top-level convenience method: `cashable.getTopBarHeight()`.
+
+### `setVisible(visible): void`
+
+Shows or hides the UI overlay. Called automatically on `lifecycle.freeze` (hide) and `lifecycle.resume` (show). Also pauses/resumes the offer scheduler.
+
+- `visible: boolean`
+
+```typescript
+cashable.ui?.setVisible(false); // Hide during cutscene
+cashable.ui?.setVisible(true);  // Show again
+```
+
+### `triggerBonusOffer(): Promise<void>`
+
+**Debug method.** Immediately triggers a bonus offer modal by fetching one from the backend, bypassing the normal offer scheduler cadence.
+
+```typescript
+await cashable.ui?.triggerBonusOffer();
+```
+
+### `triggerBoosterOffer(): Promise<void>`
+
+**Debug method.** Immediately triggers a booster offer modal, bypassing the normal offer scheduler cadence.
+
+```typescript
+await cashable.ui?.triggerBoosterOffer();
+```
+
+### `dispose(): void`
+
+Removes all DOM elements, clears timers, and disposes child components. Called automatically by `cashable.dispose()`.
+
+## Components
+
+### PlayLoopButton (Panel)
+
+Floating button that opens an expandable panel with tabbed navigation:
+
+- **Trigger row** — coin balance display with earn animation, inline countdown timer, offer countdown badge
+- **Rewards tab (main screen):**
+  - Coins pill with "Your Coins" header
+  - Tier card with progress bar, tier name, and "Fill the bar to maximize your earnings" hint
+  - "Convert coins to real money" CTA button (navigates to cashout screen)
+  - Partners section ("Get paid through" with payment logos)
+- **Cashout screen (sub-screen):**
+  - Back button to return to main screen
+  - Title: "Coins → Real Money" (no earnings) or "Money Ready!" (has earnings)
+  - Subtitle with context-sensitive messaging
+  - Countdown timer (hidden when earnings ready)
+  - Earnings display (shown when earnings ready)
+  - Cashout CTA button with wait modal logic
+  - Partners section
+- **Games tab** — lists available games with play buttons
+- **Close button** — calls `config.onClose` callback
+
+The panel auto-resets to the rewards main screen when closed.
+
+### SponsoredModal
+
+Fullscreen modal with phases:
+
+1. **Countdown** (3 seconds) — animated SVG ring, reward badge shows "+{amount} coins"
+2. **Playing** — "Loading video..." while the ad shows
+3. **Success** — green checkmark + "Coins Earned!" (auto-dismiss after 2s)
+4. **Failed** — "Video unavailable" (auto-dismiss after 2s)
+
+### BonusOfferModal
+
+Modal showing a periodic bonus coin offer. Displays the reward amount (doubled if boost is active). User taps "Claim" to watch a rewarded ad, then coins are awarded via `rewards.awardBonus`.
+
+### BoostOfferModal
+
+Modal offering a 2x coin multiplier for 3 minutes. User taps "Activate" to watch a rewarded ad, then the boost is activated.
+
+### TierCelebrationModal
+
+Shown when the user advances to a new tier. Offers two claim options:
+
+- **Claim** — claim the tier reward directly (`tier.claimCelebration` with `doubled: false`)
+- **Watch Ad & Double** — watch a rewarded ad, then claim doubled reward (`tier.claimCelebration` with `doubled: true`)
+
+### CoinToast
+
+Floating toast notification showing "+N coins" with an optional note line.
+
+## Types
+
+### `ActiveOffer`
+
+Represents a bonus or booster offer in progress:
+
+```typescript
+interface ActiveOffer {
+  offerId: string;
+  amount?: number;        // Coin reward amount (bonus offers only)
+  type: 'bonus' | 'booster';
+}
+```
+
+## Tier System
+
+Tier progress is tracked via `WalletData.tier`:
+
+- `currentTier` — current tier number (0-based)
+- `currentTierName` — display name (e.g. "Silver")
+- `nextTier` — next tier info with `name` and `target` (coins needed)
+
+When `updateCoins()` is called, the module fetches fresh wallet data and compares the new tier against the last known tier. If the tier increased, a `TierCelebrationModal` is shown.
+
+## Offer System
+
+The `OfferScheduler` alternates between bonus and booster offers on configurable cadences:
+
+- **Bonus offer cadence**: `adConfig.gamesBonusOfferCadenceMs` (default: 60s)
+- **Booster offer cadence**: `adConfig.gamesCoinBoosterCadenceMs` (default: 60s)
+
+When an offer triggers:
+1. The scheduler fetches a bonus offer from the backend (for bonus type)
+2. A countdown badge appears on the panel trigger (20 seconds)
+3. If the user taps within the countdown, the corresponding modal opens
+4. If the countdown expires, the offer is dismissed
+
+The scheduler pauses when the UI is hidden and resumes when visible.
+
+## Boost Mechanics
+
+- **Duration**: 3 minutes (180,000ms)
+- **Multiplier**: 2x on all coin awards
+- **Persistence**: `localStorage` key `cashable:boost:endsAt` stores the expiry timestamp
+- **Survival**: Boost survives page reloads within the 3-minute window
+- **Countdown**: Panel trigger shows remaining time (updates every second)
+- **Integration**: The `RewardsModule` reads boost state from localStorage to apply the multiplier

package/docs/wire-protocol.md

@@ -0,0 +1,194 @@
+# Wire Protocol
+
+Reference for host app implementors (React Native WebView bridge). Game developers using the SDK don't need to know about this.
+
+## Overview
+
+Communication between the SDK (running inside a WebView) and the host PlayLoop app uses `postMessage` with JSON payloads. There are four message types:
+
+| Type | Direction | Purpose |
+|---|---|---|
+| `cashable:request` | SDK -> Host | SDK requests an action |
+| `cashable:response` | Host -> SDK | Host responds to a request |
+| `cashable:event` | Host -> SDK | Host pushes an event |
+| `cashable:ready` | SDK -> Host | SDK signals initialization complete |
+
+## Message Formats
+
+### Request (SDK -> Host)
+
+```json
+{
+  "type": "cashable:request",
+  "action": "ads.showRewarded",
+  "requestId": "req_1707000000000_1",
+  "payload": {}
+}
+```
+
+### Response (Host -> SDK)
+
+```json
+{
+  "type": "cashable:response",
+  "requestId": "req_1707000000000_1",
+  "data": { "success": true }
+}
+```
+
+Error response:
+
+```json
+{
+  "type": "cashable:response",
+  "requestId": "req_1707000000000_1",
+  "error": {
+    "code": "AD_NOT_AVAILABLE",
+    "message": "No ad fill available"
+  }
+}
+```
+
+### Event (Host -> SDK)
+
+```json
+{
+  "type": "cashable:event",
+  "event": "lifecycle.freeze",
+  "data": null
+}
+```
+
+### Ready (SDK -> Host)
+
+```json
+{
+  "type": "cashable:ready",
+  "version": "0.6.0"
+}
+```
+
+## Actions
+
+Actions are sent from the SDK to the host via `cashable:request` messages.
+
+| Action | Payload | Expected Response |
+|---|---|---|
+| `ads.showRewarded` | `{}` | `{ success: boolean }` |
+| `ads.showInterstitial` | `{}` | `{ success: boolean }` |
+| `ads.showBanner` | `{ position?: 'top' \| 'bottom' }` | `{ success: boolean }` |
+| `ads.hideBanner` | `{}` | `{}` (ack) |
+| `ads.destroyBanner` | `{}` | `{}` (ack) |
+| `rewards.awardCoins` | `{ multiplier?: number }` | `{ coins: number }` |
+| `rewards.bonusOffer` | `{}` | `{ offered: boolean }` |
+| `rewards.awardBonus` | `{}` | `{ coins: number }` |
+| `rewards.reserveSponsoredVideo` | `{}` | `{ offerId: string, amount: number }` |
+| `rewards.claimSponsoredVideo` | `{ offerId: string, amount: number }` | `{ coinsAwarded: number, totalCoins: number }` |
+| `session.getBalance` | - | `{ coins: number }` |
+| `session.getWallet` | - | `WalletData` (see [Types](#types)) |
+| `games.init` | `{ gameId: string, mode: string }` | `InitResponse` (see [Types](#types)) |
+| `analytics.playTick` | `{ seconds: number }` | `{}` (ack) |
+| `analytics.themeColor` | `{ color: string }` | `{}` (ack) |
+| `lifecycle.ready` | `{ version: string }` | `{}` (ack) |
+| `lifecycle.progress` | `{ percent: number }` | `{}` (ack) |
+| `tier.claimCelebration` | `{ tierNumber: number, doubled: boolean }` | `{ success: boolean, coinsAwarded: number, totalCoins: number }` |
+
+## Events
+
+Events are pushed from the host to the SDK via `cashable:event` messages.
+
+| Event | Data | Description |
+|---|---|---|
+| `lifecycle.freeze` | - | Host is putting the game in the background |
+| `lifecycle.resume` | - | Host is bringing the game back to the foreground |
+| `rewards.coinsAwarded` | `{ coins: number }` | Host awarded coins (e.g., bonus) |
+| `ui.topBarHeight` | `{ height: number }` | Host reports top bar pixel height for game layout offset |
+
+## Error Codes
+
+| Code | Meaning |
+|---|---|
+| `TIMEOUT` | Request timed out (default: 10s) |
+| `TRANSPORT_ERROR` | Communication failure |
+| `AD_NOT_AVAILABLE` | No ad fill |
+| `NETWORK_ERROR` | HTTP request failed |
+| `USER_NOT_LINKED` | User not found in backend |
+
+## Host Implementation
+
+The host (React Native) should:
+
+1. Listen for `onMessage` events from the WebView
+2. Parse JSON, check for `type: 'cashable:request'`
+3. Dispatch by `action`
+4. Send responses back via `webViewRef.current.injectJavaScript()`:
+
+```javascript
+// In React Native
+const sendResponse = (requestId, data, error) => {
+  const message = JSON.stringify({
+    type: 'cashable:response',
+    requestId,
+    data: error ? undefined : data,
+    error: error ? { code: error.code, message: error.message } : undefined,
+  });
+  webViewRef.current?.injectJavaScript(
+    `window.dispatchEvent(new MessageEvent('message', { data: '${message}' }));true;`
+  );
+};
+
+const sendEvent = (event, data) => {
+  const message = JSON.stringify({
+    type: 'cashable:event',
+    event,
+    data,
+  });
+  webViewRef.current?.injectJavaScript(
+    `window.dispatchEvent(new MessageEvent('message', { data: '${message}' }));true;`
+  );
+};
+```
+
+See `frontend/src/screens/PlayGamesScreen/hooks/usePlayLoopGameBridge.ts` for the full reference implementation.
+
+## Types
+
+### `WalletData`
+
+Returned by `session.getWallet`:
+
+```typescript
+interface WalletData {
+  coins: number;
+  tier: {
+    currentTier: number;
+    currentTierName: string;
+    nextTier?: { name: string; target: number };
+  };
+  tierDefinitions: TierInfo[];
+  coinGoal: number;
+  coinsEarnedThisPeriod: number;
+  earnings: number;
+  cashoutPeriodEndsAt: number;
+}
+
+interface TierInfo {
+  tier: number;
+  name: string;
+  target: number;
+}
+```
+
+### `InitResponse`
+
+Returned by `games.init`:
+
+```typescript
+interface InitResponse {
+  userId: string;
+  featureFlags?: {
+    clientKey: string;
+    bootstrapValues?: string;  // JSON-serialized Statsig bootstrap
+  };
+}
+```

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@clocktone/game-sdk",
+  "version": "1.0.0",
+  "description": "Cashable Unified Game SDK for embedded (WebView) and standalone (Capacitor) games",
+  "main": "dist/loader/cjs/index.js",
+  "module": "dist/loader/esm/index.js",
+  "types": "dist/types/loader/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/loader/esm/index.js",
+      "require": "./dist/loader/cjs/index.js"
+    },
+    "./loader": {
+      "types": "./dist/types/loader/index.d.ts",
+      "import": "./dist/loader/esm/index.js",
+      "require": "./dist/loader/cjs/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/loader",
+    "dist/types",
+    "android/src",
+    "android/build.gradle",
+    "docs"
+  ],
+  "capacitor": {
+    "android": {
+      "src": "android"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:loader && npm run build:cdn",
+    "build:loader": "rollup -c rollup.loader.config.mjs",
+    "build:cdn": "rollup -c rollup.cdn.config.mjs",
+    "dev": "rollup -c rollup.cdn.config.mjs -w",
+    "preview": "vite --config preview/vite.config.ts",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": ">=6.0.0",
+    "@capacitor/core": ">=5.0.0",
+    "@statsig/js-client": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@babylonjs/core": {
+      "optional": true
+    },
+    "@capacitor/core": {
+      "optional": true
+    },
+    "@statsig/js-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-image": "^3.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-replace": "^6.0.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.0",
+    "@statsig/js-client": "^3.31.2",
+    "@vitest/runner": "^4.1.5",
+    "happy-dom": "^20.9.0",
+    "jsdom": "^27.0.1",
+    "rollup": "^4.9.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "tslib": "^2.8.0",
+    "typescript": "~5.8.0",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.0"
+  },
+  "license": "UNLICENSED"
+}