@clocktone/game-sdk 1.0.0

package/dist/types/ui/UIModule.d.ts

@@ -0,0 +1,64 @@
+import { ITransport, IAds, UIConfig, AdConfig } from '../types.js';
+
+declare class UIModule {
+    private transport;
+    private ads;
+    private config;
+    private adConfig;
+    private debug;
+    private rootEl;
+    private cashableButton;
+    private sponsoredModal;
+    private bonusModal;
+    private boostOfferModal;
+    private coinToast;
+    private tierModal;
+    private offerScheduler;
+    private boostInterval;
+    private walletData;
+    private games;
+    private lastKnownTier;
+    private tierInitialized;
+    private lastWalletFetchAt;
+    constructor(transport: ITransport, ads: IAds, config: UIConfig, debug: boolean, adConfig: AdConfig);
+    initialize(): Promise<void>;
+    getTopBarHeight(): number;
+    /**
+     * Show the sponsored video countdown, then show an interstitial ad.
+     * Reserves the reward amount from the backend first, then claims after the ad.
+     * Returns true if the ad was shown and reward claimed successfully.
+     */
+    showSponsoredInterstitial(): Promise<boolean>;
+    /** Award coins: calculate delta from current balance, update display, show toast. */
+    showCoinAward(newTotalCoins: number): void;
+    /** Show a coin earned toast notification. Auto-appends boost note when active. */
+    showCoinToast(amount: number, note?: string): void;
+    /** Update displayed coin count and check for tier advancement. */
+    updateCoins(coins: number): void;
+    /** Re-fetch wallet data from backend and update UI. Debounced to 1s. */
+    refreshWallet(): Promise<void>;
+    /** Debug: trigger a bonus offer on the widget (fetches from backend). */
+    triggerBonusOffer(): Promise<void>;
+    /** Debug: trigger a booster offer on the widget. */
+    triggerBoosterOffer(): Promise<void>;
+    /** Hide/show the UI (for freeze/resume). */
+    setVisible(visible: boolean): void;
+    dispose(): void;
+    private initCashableButton;
+    private applyWalletData;
+    private handleBoostTap;
+    private startBoostCountdown;
+    private initOfferScheduler;
+    private handleOfferTap;
+    private handleBonusOffer;
+    private handleBoosterOffer;
+    private activateBoost;
+    private checkTierAdvancement;
+    private handleTierClaim;
+    private handleTierClaimWithAd;
+    /** Update coins display without triggering tier check (to avoid loops). */
+    private updateCoinsDisplay;
+    private log;
+}
+
+export { UIModule };

package/docs/ads.md

@@ -0,0 +1,210 @@
+# Ads Module
+
+Handles showing rewarded video, interstitial, and banner ads.
+
+**Accessor**: `cashable.ads`
+
+## Methods
+
+### `showRewardedVideo(): Promise<boolean>`
+
+Shows a rewarded video ad. Returns `true` if the user watched the full ad, `false` if they dismissed it or no ad was available.
+
+```typescript
+const success = await cashable.ads.showRewardedVideo();
+if (success) {
+  await cashable.rewards.awardCoins();
+}
+```
+
+### `showInterstitial(): Promise<boolean>`
+
+Shows an interstitial ad. Returns `true` if the ad was shown, `false` otherwise.
+
+```typescript
+await cashable.ads.showInterstitial();
+```
+
+### `showBanner(position?): Promise<boolean>`
+
+Shows a banner ad at the given screen position. Returns `true` if the banner was shown, `false` if no banner ad unit is configured or no fill is available.
+
+- `position` — `'top'` or `'bottom'` (default: `'bottom'`)
+
+Banner size is automatic: 320×50 on phones, 728×90 on tablets.
+
+```typescript
+// Show banner at the bottom of the screen
+const shown = await cashable.ads.showBanner();
+
+// Show banner at the top
+await cashable.ads.showBanner('top');
+```
+
+### `hideBanner(): Promise<void>`
+
+Hides the banner ad without destroying it. The banner stays loaded in memory for fast re-show. Auto-refresh is paused while hidden.
+
+```typescript
+await cashable.ads.hideBanner();
+```
+
+### `destroyBanner(): Promise<void>`
+
+Destroys the banner ad and frees all resources. After calling this, you cannot show the banner again until the SDK is re-initialized.
+
+```typescript
+await cashable.ads.destroyBanner();
+```
+
+### `onBeforeAd(handler): () => void`
+
+Fires immediately before a fullscreen ad (rewarded/interstitial) is shown. Use this to pause audio, animations, or game logic.
+
+```typescript
+const unsub = cashable.ads.onBeforeAd(() => {
+  pauseGameAudio();
+});
+```
+
+### `onAfterAd(handler): () => void`
+
+Fires after a fullscreen ad completes or is dismissed.
+
+```typescript
+const unsub = cashable.ads.onAfterAd(({ success }) => {
+  resumeGameAudio();
+  if (success) {
+    showRewardAnimation();
+  }
+});
+```
+
+## How Ads Work Per Mode
+
+### Embedded mode
+
+The SDK sends a request to the host PlayLoop app via the WebView bridge. The host displays the ad using its own ad infrastructure and responds with the result. No `appLovin` config is needed.
+
+### Standalone mode
+
+The SDK uses the bundled AppLovin MAX native plugin (Android Kotlin) to show ads directly. You must provide the `appLovin` config when initializing the SDK:
+
+```typescript
+const cashable = new PlayLoopSDK({
+  gameId: 'my-game',
+  mode: 'standalone',
+  apiBaseUrl: 'https://api.cashable.app',
+  appLovin: {
+    sdkKey: 'YOUR_SDK_KEY',
+    rewardedAdUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
+    interstitialAdUnitId: 'YOUR_INTERSTITIAL_AD_UNIT_ID',
+    bannerAdUnitId: 'YOUR_BANNER_AD_UNIT_ID', // optional
+  },
+});
+```
+
+**Where to find these values**:
+- **SDK Key**: AppLovin dashboard → Account → General → Keys
+- **Ad Unit IDs**: AppLovin dashboard → MAX → Ad Units → create or select units for your app
+
+The native plugin (AppLovin MAX SDK 13.5.1) is bundled in the npm package under `android/`. When you install the SDK in a Capacitor project, Capacitor auto-links the native code.
+
+If `appLovin` config is omitted in standalone mode, ads will silently return `false` (a debug warning is logged if `debug: true`).
+
+If `bannerAdUnitId` is omitted, banner methods (`showBanner`, `hideBanner`, `destroyBanner`) will silently no-op.
+
+This difference is transparent to the game developer - the API is identical in both modes.
+
+## Standalone-Only Methods
+
+In standalone mode, the ads module wraps the core ad methods with cooldown enforcement (via `StandaloneAdsModule`). These additional methods are available for querying and managing cooldown state.
+
+### `isInterstitialAvailable(): boolean`
+
+Returns `true` if the interstitial cooldown has elapsed and an interstitial can be shown. In embedded mode, always returns `true` (the host app manages pacing).
+
+```typescript
+if (cashable.ads.isInterstitialAvailable()) {
+  await cashable.ui?.showSponsoredInterstitial();
+}
+```
+
+### `isRewardedAvailable(): boolean`
+
+Returns `true` if the rewarded ad cooldown has elapsed. In embedded mode, always returns `true`.
+
+```typescript
+if (cashable.ads.isRewardedAvailable()) {
+  const success = await cashable.ads.showRewardedVideo();
+}
+```
+
+### `hasShownFullScreenAd: boolean`
+
+Read-only property. Returns `true` if any full-screen ad (rewarded or interstitial) has been shown during this session. Useful for tracking whether the user has engaged with ads.
+
+```typescript
+if (!cashable.ads.hasShownFullScreenAd) {
+  // User hasn't seen any ads yet this session
+}
+```
+
+### `updateAdConfig(overrides: Partial<AdConfig>): void`
+
+Updates ad cooldown configuration at runtime by merging partial overrides into the current config. Standalone mode only — no-op in embedded mode.
+
+```typescript
+cashable.ads.updateAdConfig?.({
+  interstitialCooldownMs: 120_000, // 2 minutes between interstitials
+});
+```
+
+### `resetCooldowns(): void`
+
+Resets all cooldown timers so ads can be shown immediately. Standalone mode only — no-op in embedded mode.
+
+```typescript
+cashable.ads.resetCooldowns?.();
+```
+
+### `getAdConfig(): Readonly<AdConfig>`
+
+Returns a read-only snapshot of the current ad configuration. Standalone mode only.
+
+```typescript
+const config = cashable.ads.getAdConfig?.();
+console.log(config?.interstitialCooldownMs);
+```
+
+### Cooldown Rules
+
+The standalone ads module enforces cooldowns that match the PlayLoop host app behavior:
+
+| Trigger | Next Interstitial Delay | Next Rewarded Delay |
+|---------|-------------------------|---------------------|
+| First interstitial access | `firstInterstitialCooldownMs` (default: 45s) | — |
+| After interstitial shown | `interstitialCooldownMs` (default: 75s) | `interstitialToRewardedCooldownMs` (default: 30s) |
+| After rewarded shown | `rewardedToInterstitialCooldownMs` (default: 90s) | — |
+
+Key behaviors:
+- **Rewarded ads are never blocked** — they are user-initiated, but showing one records cross-cooldowns for interstitials.
+- **First interstitial is lazy-initialized** — the cooldown timer starts on the first availability check, not on SDK init.
+- Cooldown values are read from the `ad_config` Statsig dynamic config (see [Feature Flags](feature-flags.md)) and fall back to `DEFAULT_AD_CONFIG`.
+
+## Sponsored Interstitial
+
+In standalone mode, the SDK provides a `showSponsoredInterstitial()` method on the UI module. This reserves a reward amount from the backend, shows a 3-second animated countdown modal ("Sponsored Video"), then automatically displays the interstitial ad and claims the reward on success.
+
+```typescript
+// Available via cashable.ui (standalone + authenticated only)
+const success = await cashable.ui?.showSponsoredInterstitial();
+```
+
+**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)
+
+See the [UI Module docs](ui.md#showsponsoredinterstitial-promiseboolean) for the full flow details.

package/docs/analytics.md

@@ -0,0 +1,45 @@
+# Analytics Module
+
+Tracks play time and reports game metadata.
+
+**Accessor**: `cashable.analytics`
+
+## Methods
+
+### `startAutoTracking(): void`
+
+Starts automatic play-time tracking. Accumulates seconds and syncs to the backend every 10 seconds.
+
+```typescript
+cashable.analytics.startAutoTracking();
+```
+
+Call this once when the game starts. If called multiple times, subsequent calls are no-ops.
+
+### `stopAutoTracking(): void`
+
+Stops play-time tracking and flushes any remaining accumulated seconds.
+
+```typescript
+cashable.analytics.stopAutoTracking();
+```
+
+### `reportThemeColor(hex: string): void`
+
+Reports the game's dominant theme color to the host. Used for UI customization in the PlayLoop app. Fire-and-forget - errors are silently ignored.
+
+```typescript
+cashable.analytics.reportThemeColor('#FF6B35');
+```
+
+## Automatic Cleanup
+
+When `cashable.dispose()` is called, analytics tracking is automatically stopped and flushed. You don't need to call `stopAutoTracking()` manually if you're disposing the entire SDK.
+
+## Sync Details
+
+- Ticks accumulate locally at 1-second intervals
+- Every 10 seconds, accumulated seconds are flushed to the backend via `analytics.playTick`
+- Syncs are fire-and-forget: network failures don't block the game
+- In embedded mode, the sync goes through the WebView bridge
+- In standalone mode, it's a `POST /api/games/daily/{gameId}/tick?seconds=N` HTTP call

package/docs/babylon.md

@@ -0,0 +1,88 @@
+# Babylon.js Plugin
+
+Integrates with Babylon.js for automatic render loop freeze/resume when the host app sends lifecycle events.
+
+**Accessor**: `cashable.babylon`
+
+## Methods
+
+### `bindScene(scene, engine?): void`
+
+Binds a Babylon.js scene (and optionally its engine) to the SDK. Once bound, the SDK automatically stops and restarts the render loop on freeze/resume events.
+
+```typescript
+import { Engine, Scene } from '@babylonjs/core';
+
+const engine = new Engine(canvas);
+const scene = new Scene(engine);
+
+// Option 1: Pass both scene and engine
+cashable.babylon.bindScene(scene, engine);
+
+// Option 2: Pass scene only (engine auto-detected via scene.getEngine())
+cashable.babylon.bindScene(scene);
+```
+
+**Parameters**:
+
+| Name | Type | Description |
+|---|---|---|
+| `scene` | `{ render(): void }` | Babylon.js Scene instance |
+| `engine` | `{ stopRenderLoop, runRenderLoop }` (optional) | Babylon.js Engine instance. If omitted, auto-detected via `scene.getEngine()` |
+
+### `freeze(): void`
+
+Manually stops the render loop. Called automatically on `lifecycle.freeze` events.
+
+```typescript
+cashable.babylon.freeze();
+```
+
+### `resume(): void`
+
+Manually restarts the render loop. Called automatically on `lifecycle.resume` events.
+
+```typescript
+cashable.babylon.resume();
+```
+
+### `dispose(): void`
+
+Clears scene and engine references. Called automatically by `cashable.dispose()`.
+
+## Fallback Behavior
+
+If no Babylon.js scene is bound, the plugin falls back to calling `window.__eaFreeze()` / `window.__eaResume()` if they exist. This provides backward compatibility with games that set up their own freeze/resume hooks.
+
+## Why This Exists
+
+Previously, the PlayLoop app used ~200 lines of injected JavaScript to monkey-patch `setTimeout`, `setInterval`, `requestAnimationFrame`, `Date.now`, and `performance.now` for freeze/resume. This was fragile and Unity-specific.
+
+The Babylon.js plugin replaces all of that with two clean API calls: `engine.stopRenderLoop()` and `engine.runRenderLoop(() => scene.render())`.
+
+## Full Example
+
+```typescript
+import { Engine, Scene, ArcRotateCamera, HemisphericLight, MeshBuilder, Vector3 } from '@babylonjs/core';
+import { PlayLoopSDK } from '@clocktone/game-sdk';
+
+// Set up Babylon.js
+const canvas = document.getElementById('renderCanvas') as HTMLCanvasElement;
+const engine = new Engine(canvas, true);
+const scene = new Scene(engine);
+
+new ArcRotateCamera('cam', 0, 1, 10, Vector3.Zero(), scene);
+new HemisphericLight('light', new Vector3(0, 1, 0), scene);
+MeshBuilder.CreateSphere('sphere', {}, scene);
+
+engine.runRenderLoop(() => scene.render());
+
+// Set up SDK
+const cashable = new PlayLoopSDK({ gameId: 'my-babylon-game' });
+await cashable.init();
+cashable.babylon.bindScene(scene, engine);
+cashable.analytics.startAutoTracking();
+
+// The render loop is now automatically managed by the SDK
+// on freeze/resume events from the host app
+```

package/docs/feature-flags.md

@@ -0,0 +1,109 @@
+# Feature Flags Module
+
+Remote configuration and feature gating powered by Statsig.
+
+**Accessor**: `cashable.featureFlags` (nullable — `null` if not initialized)
+
+## Overview
+
+The Feature Flags module provides access to Statsig dynamic configs, feature gates, and event logging. It is initialized automatically during `cashable.init()` using bootstrap values from the backend `/api/games/init` endpoint.
+
+Bootstrap values are provided server-side so the Statsig client initializes synchronously without a blocking network request. Updated values are fetched in the background automatically.
+
+## Methods
+
+### `isInitialized(): boolean`
+
+Returns `true` if the Statsig client was successfully bootstrapped.
+
+```typescript
+if (cashable.featureFlags?.isInitialized()) {
+  // Safe to read configs and gates
+}
+```
+
+### `getConfig(configName): { get, value }`
+
+Read a Statsig dynamic config by name. Returns an object with:
+
+- `get<V>(key: string, defaultValue: V): V` — type-safe value accessor
+- `value: Record<string, unknown>` — raw config object
+
+If Statsig is not initialized, `get()` always returns the `defaultValue` and `value` is `{}`.
+
+```typescript
+const config = cashable.featureFlags?.getConfig('game_settings');
+const maxLives = config?.get('max_lives', 3) ?? 3;
+const dailyLimit = config?.get('daily_coin_limit', 1000) ?? 1000;
+```
+
+### `checkGate(name): boolean`
+
+Check whether a feature gate is passing. Returns `false` if Statsig is not initialized.
+
+```typescript
+if (cashable.featureFlags?.checkGate('new_bonus_flow')) {
+  showNewBonusUI();
+} else {
+  showLegacyBonusUI();
+}
+```
+
+### `logEvent(eventName, value?, metadata?): void`
+
+Log a custom event to Statsig for analytics and experiment exposure tracking.
+
+- `eventName: string` — event name
+- `value?: number` — optional numeric value
+- `metadata?: Record<string, string>` — optional key-value metadata
+
+No-op if Statsig is not initialized.
+
+```typescript
+cashable.featureFlags?.logEvent('level_completed', 5, {
+  difficulty: 'hard',
+  timeMs: '12345',
+});
+```
+
+### `adConfig: Readonly<AdConfig>`
+
+Getter that returns the current ad configuration values, with Statsig overrides merged on top of defaults. Used internally by the SDK to configure ad cooldowns and offer cadences.
+
+```typescript
+const config = cashable.featureFlags?.adConfig;
+console.log(config?.interstitialCooldownMs); // e.g. 75000
+```
+
+The ad config is read from the `ad_config` Statsig dynamic config. The following keys are mapped:
+
+| SDK Key | Statsig Key |
+|---------|-------------|
+| `interstitialCooldownMs` | `interstitial_cooldown_ms` |
+| `firstInterstitialCooldownMs` | `first_interstitial_cooldown_ms` |
+| `rewardedToInterstitialCooldownMs` | `rewarded_to_interstitial_cooldown_ms` |
+| `interstitialToRewardedCooldownMs` | `interstitial_to_rewarded_cooldown_ms` |
+| `playClickInterstitialCooldownMs` | `play_click_interstitial_cooldown_ms` |
+| `earnBeforePlayingAdCooldownMs` | `earn_before_playing_ad_cooldown_ms` |
+| `gamesBonusOfferCadenceMs` | `games_bonus_offer_cadence_ms` |
+| `gamesCoinBoosterCadenceMs` | `games_coin_booster_cadence_ms` |
+
+### `dispose(): void`
+
+Shuts down the Statsig client and releases resources. Called automatically by `cashable.dispose()`.
+
+## How It Works
+
+1. During `cashable.init()`, the SDK calls `games.init` (via the transport layer) to fetch init data from the backend.
+2. The backend responds with a `userId` and optional `featureFlags` containing a Statsig `clientKey` and pre-serialized `bootstrapValues`.
+3. The module creates a `StatsigClient` with the bootstrap values and calls `initializeSync()` for instant, synchronous initialization.
+4. If no bootstrap values are provided, `initializeAsync()` is used instead (blocking network call to Statsig).
+5. After initialization, the `ad_config` dynamic config is read and merged with `DEFAULT_AD_CONFIG`.
+
+## Peer Dependency
+
+The `@statsig/js-client` package is a peer dependency (optional). If not installed, the module will fail to initialize and fall back to default values.
+
+```bash
+npm install @statsig/js-client
+```