@clocktone/game-sdk 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,481 @@
+interface PlayLoopRequest {
+    type: 'jp:request';
+    action: PlayLoopAction;
+    requestId: string;
+    payload?: Record<string, unknown>;
+}
+interface PlayLoopResponse {
+    type: 'jp:response';
+    requestId: string;
+    data?: unknown;
+    error?: {
+        code: PlayLoopErrorCode;
+        message: string;
+    };
+}
+interface PlayLoopEvent {
+    type: 'jp:event';
+    event: PlayLoopEventName;
+    data?: unknown;
+}
+interface PlayLoopReady {
+    type: 'jp:ready';
+    version: string;
+}
+type PlayLoopMessage = PlayLoopRequest | PlayLoopResponse | PlayLoopEvent | PlayLoopReady;
+type PlayLoopAction = 'ads.showRewarded' | 'ads.showInterstitial' | 'ads.isInterstitialAvailable' | 'ads.showBanner' | 'ads.hideBanner' | 'ads.destroyBanner' | 'rewards.awardCoins' | 'rewards.reserveSponsoredVideo' | 'rewards.claimSponsoredVideo' | 'rewards.bonusOffer' | 'rewards.awardBonus' | 'session.getBalance' | 'session.getWallet' | 'games.init' | 'analytics.playTick' | 'analytics.themeColor' | 'lifecycle.ready' | 'lifecycle.progress' | 'tier.claimCelebration' | 'games.list' | 'ui.closeGame' | 'ui.openMenu';
+type PlayLoopEventName = 'lifecycle.freeze' | 'lifecycle.resume' | 'rewards.coinsAwarded';
+type PlayLoopErrorCode = 'TIMEOUT' | 'TRANSPORT_ERROR' | 'AD_NOT_AVAILABLE' | 'NETWORK_ERROR' | 'USER_NOT_LINKED';
+interface PlayLoopSDKConfig {
+    gameId: string;
+    mode?: 'embedded' | 'standalone';
+    apiBaseUrl?: string;
+    requestTimeoutMs?: number;
+    debug?: boolean;
+    /** Client ID for embedded mode (host passes it for direct HTTP auth) */
+    clientId?: string;
+    /** AppLovin MAX config (required for standalone mode ads) */
+    appLovin?: {
+        /** SDK key from AppLovin dashboard (Account → General → Keys) */
+        sdkKey: string;
+        rewardedAdUnitId: string;
+        interstitialAdUnitId: string;
+        /** Ad unit ID for banner ads (optional - banners disabled if omitted) */
+        bannerAdUnitId?: string;
+    };
+    /** Auto-show a banner ad at this position after init completes. */
+    banner?: BannerPosition;
+    /** Called when SDK needs the game to pause (e.g. ad overlay). */
+    onPause?: () => void;
+    /** Called when SDK signals the game can resume. */
+    onResume?: () => void;
+    /** UI config (top bar, sponsored modal, close/menu buttons) */
+    ui?: UIConfig;
+}
+interface UIConfig {
+    /** Called when close button is tapped */
+    onClose?: () => void;
+    /** Called when menu button is tapped (optional) */
+    onMenuOpen?: () => void;
+    /** Show the floating PlayLoop button (default: false) */
+    showPlayLoopButton?: boolean;
+    /** Show close button on the PlayLoopButton trigger (default: true in embedded) */
+    showClose?: boolean;
+    /** Show menu button on the PlayLoopButton trigger (default: true in embedded) */
+    showMenu?: boolean;
+    /** Position and style config for the PlayLoop button */
+    PlayLoopButton?: {
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    };
+}
+interface TierInfo {
+    tier: number;
+    name: string;
+    target: number;
+}
+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 ActiveOffer {
+    offerId: string;
+    amount?: number;
+    type: 'bonus' | 'booster';
+}
+interface InitResponse {
+    userId: string;
+    featureFlags?: {
+        clientKey: string;
+        bootstrapValues?: string;
+    };
+}
+interface AdConfig {
+    fullScreenIntervalMs: number;
+    initialFullScreenMs: number;
+    optToFullGapMs: number;
+    fullToOptGapMs: number;
+    actionFullScreenMs: number;
+    rewardMediaDelayMs: number;
+    arcadeBonusIntervalMs: number;
+    arcadeBoostIntervalMs: number;
+}
+/** Default ad config values (matches PlayLoop app defaults). */
+declare const DEFAULT_AD_CONFIG: AdConfig;
+type EventHandler = (event: PlayLoopEventName, data?: unknown) => void;
+interface SendOptions {
+    timeoutMs?: number;
+}
+interface ITransport {
+    send<T = unknown>(action: PlayLoopAction, payload?: Record<string, unknown>, opts?: SendOptions): Promise<T>;
+    onEvent(handler: EventHandler): () => void;
+    dispose(): void;
+}
+type BannerPosition = 'top' | 'bottom';
+interface IAdsAdapter {
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    hideBanner(): Promise<void>;
+    destroyBanner(): Promise<void>;
+}
+interface IAds {
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    hideBanner(): Promise<void>;
+    destroyBanner(): Promise<void>;
+    onBeforeAd(handler: () => void): () => void;
+    onAfterAd(handler: (result: {
+        success: boolean;
+    }) => void): () => void;
+    dispose(): void;
+    /** Whether an interstitial can be shown (cooldown check). Always true without cooldowns. */
+    isInterstitialAvailable(): boolean;
+    /** Whether a rewarded ad can be shown (cooldown check). Always true without cooldowns. */
+    isRewardedAvailable(): boolean;
+    /** Update ad cooldown config at runtime (standalone mode only, no-op in embedded). */
+    updateAdConfig?(overrides: Partial<AdConfig>): void;
+    /** Reset all cooldown timers so ads can be shown immediately (standalone only, no-op in embedded). */
+    resetCooldowns?(): void;
+    /** Current ad config snapshot (standalone only). */
+    getAdConfig?(): Readonly<AdConfig>;
+}
+
+declare class UIModule {
+    private transport;
+    private nativeTransport;
+    private ads;
+    private config;
+    private adConfig;
+    private debug;
+    private mode;
+    private rootEl;
+    private playLoopButton;
+    private wallet;
+    private scheduler;
+    private modals;
+    constructor(transport: ITransport, ads: IAds, config: UIConfig, debug: boolean, adConfig: AdConfig, mode?: 'embedded' | 'standalone', nativeTransport?: ITransport);
+    /**
+     * Mount the UI shell (styles + root + PlayLoopButton in loading state).
+     * Called early before auth completes so the pill is visible immediately.
+     */
+    mountShell(): void;
+    updateAds(ads: IAds, adConfig?: AdConfig): void;
+    initialize(): Promise<void>;
+    getTopBarHeight(): number;
+    showSponsoredInterstitial(): Promise<boolean>;
+    showCoinAward(newTotalCoins: number): void;
+    showCoinToast(amount: number, note?: string): void;
+    updateCoins(coins: number): void;
+    refreshWallet(): Promise<void>;
+    triggerBonusOffer(): Promise<void>;
+    triggerBoosterOffer(): Promise<void>;
+    setVisible(visible: boolean): void;
+    dispose(): void;
+    private initPlayLoopButton;
+    private handleCloseGame;
+    private handleOpenMenu;
+    private log;
+}
+
+declare class SessionModule {
+    private transport;
+    private mode;
+    private appSetId;
+    private clientId;
+    constructor(transport: ITransport | null, mode: 'embedded' | 'standalone', clientId?: string);
+    setTransport(transport: ITransport): void;
+    initialize(): Promise<void>;
+    getAuthHeaders(): Record<string, string>;
+    getBalance(): Promise<{
+        coins: number;
+    }>;
+}
+
+declare class RewardsModule {
+    private transport;
+    private emitter;
+    private getMultiplier;
+    private lastAwardTime;
+    private static readonly AWARD_COOLDOWN_MS;
+    constructor(transport: ITransport, getMultiplier?: () => number);
+    awardCoins(opts?: {
+        multiplier?: number;
+    }): Promise<{
+        coins: number;
+    }>;
+    onCoinsAwarded(handler: (data: {
+        coins: number;
+    }) => void): () => void;
+    dispose(): void;
+}
+
+declare class AnalyticsModule {
+    private transport;
+    private gameId;
+    private tickTimer;
+    private secondsAccumulated;
+    constructor(transport: ITransport, gameId: string);
+    startAutoTracking(): void;
+    stopAutoTracking(): void;
+    reportThemeColor(hex: string): void;
+    dispose(): void;
+    private flush;
+}
+
+declare class FeatureFlagModule {
+    private client;
+    private _adConfig;
+    private initialized;
+    private debug;
+    constructor(debug: boolean);
+    /**
+     * Initialize Statsig with bootstrap values from the backend init endpoint.
+     * Mirrors the frontend StatsigAdapter.initialize() pattern.
+     * Returns the userId from the init response.
+     */
+    initialize(transport: ITransport, appSetId: string | null, gameId: string, mode: 'embedded' | 'standalone'): Promise<string | null>;
+    /** Get the current ad configuration (Statsig overrides merged with defaults). */
+    get adConfig(): Readonly<AdConfig>;
+    /** Check if the adapter is initialized. */
+    isInitialized(): boolean;
+    /**
+     * Read a dynamic config value by name.
+     * Mirrors frontend StatsigAdapter.getConfig().
+     */
+    getConfig(configName: string): {
+        get: <V>(key: string, defaultValue: V) => V;
+        value: Record<string, unknown>;
+    };
+    /** Check a feature gate. Returns false if Statsig is not initialized. */
+    checkGate(name: string): boolean;
+    /** Log an event to Statsig. */
+    logEvent(eventName: string, value?: number, metadata?: Record<string, string>): void;
+    dispose(): void;
+    /** Read `media_settings` dynamic config and merge with defaults. */
+    private readAdConfig;
+}
+
+type BabylonEngine = {
+    stopRenderLoop(renderFunction?: () => void): void;
+    runRenderLoop(renderFunction: () => void): void;
+};
+type BabylonScene = {
+    render(): void;
+};
+declare class BabylonPlugin {
+    private engine;
+    private scene;
+    bindScene(scene: BabylonScene, engine?: BabylonEngine): void;
+    freeze(): void;
+    resume(): void;
+    dispose(): void;
+}
+
+declare class PlayLoopSDK {
+    private config;
+    private transport;
+    private nativeTransport;
+    private emitter;
+    private unsubTransportEvents;
+    private unsubNativeEvents;
+    private unsubRewardsCoins;
+    private _session;
+    private _rewards;
+    private _ads;
+    private _analytics;
+    private _featureFlags;
+    private _babylon;
+    private _ui;
+    private _isAuthenticated;
+    readonly mode: 'embedded' | 'standalone';
+    static getHostConfig(): {
+        clientId?: string;
+        apiBaseUrl?: string;
+        debug?: boolean;
+    } | null;
+    static getWidgetHeight(): number;
+    constructor(config: PlayLoopSDKConfig);
+    init(): Promise<void>;
+    private initEmbeddedMode;
+    private initStandaloneMode;
+    private initRewards;
+    private finalizeUI;
+    private subscribeTransportEvents;
+    private autoDetectBabylon;
+    private handleTransportEvent;
+    get session(): SessionModule;
+    get rewards(): RewardsModule;
+    get ads(): IAds;
+    get analytics(): AnalyticsModule;
+    get isAuthenticated(): boolean;
+    get featureFlags(): FeatureFlagModule | null;
+    getTopBarHeight(): number;
+    getTopBarHeightAsync(): Promise<number>;
+    get adConfig(): Readonly<AdConfig>;
+    get ui(): UIModule | null;
+    get babylon(): BabylonPlugin;
+    onFreeze(handler: () => void): () => void;
+    onResume(handler: () => void): () => void;
+    onWidgetReady(handler: (data: {
+        height: number;
+    }) => void): () => void;
+    dispose(): void;
+    private detectMode;
+}
+
+/**
+ * Ads module for embedded mode (game hosted in PlayLoop WebView).
+ * Thin pass-through — the host app manages cooldowns.
+ */
+declare class EmbeddedAdsModule implements IAds {
+    private adapter;
+    private emitter;
+    constructor(adapter: IAdsAdapter);
+    /** Always available — host app manages cooldowns. */
+    isInterstitialAvailable(): boolean;
+    /** Always available — host app manages cooldowns. */
+    isRewardedAvailable(): boolean;
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    /** Show a banner ad at the given screen position (default: bottom). */
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    /** Hide the banner ad (keeps it loaded for fast re-show). */
+    hideBanner(): Promise<void>;
+    /** Destroy the banner ad and free resources. */
+    destroyBanner(): Promise<void>;
+    onBeforeAd(handler: () => void): () => void;
+    onAfterAd(handler: (result: {
+        success: boolean;
+    }) => void): () => void;
+    dispose(): void;
+}
+
+/**
+ * Ads module for standalone mode (Capacitor game running independently).
+ * Wraps EmbeddedAdsModule with cooldown enforcement since there is no host app
+ * to manage ad pacing.
+ *
+ * Cooldown rules (matching frontend/src/lib/ads.ts):
+ *   - First interstitial delayed by `initialFullScreenMs`
+ *   - After interstitial: next interstitial in `fullScreenIntervalMs`,
+ *     next rewarded in `fullToOptGapMs`
+ *   - After rewarded: next interstitial in `optToFullGapMs`
+ *   - Rewarded ads are never blocked (user-initiated), but record cross-cooldowns
+ */
+declare class StandaloneAdsModule implements IAds {
+    private inner;
+    private config;
+    private _nextInterstitialAt;
+    private _nextRewardedAt;
+    private _hasShownFullScreenAd;
+    constructor(inner: EmbeddedAdsModule, config: AdConfig);
+    /** Whether an interstitial can be shown right now (cooldown elapsed). */
+    isInterstitialAvailable(): boolean;
+    /** Whether a rewarded ad can be shown right now (cooldown elapsed). */
+    isRewardedAvailable(): boolean;
+    /** Whether any full-screen ad has been shown this session. */
+    get hasShownFullScreenAd(): boolean;
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    hideBanner(): Promise<void>;
+    destroyBanner(): Promise<void>;
+    onBeforeAd(handler: () => void): () => void;
+    onAfterAd(handler: (result: {
+        success: boolean;
+    }) => void): () => void;
+    /** Update ad cooldown config at runtime (partial merge). */
+    updateAdConfig(overrides: Partial<AdConfig>): void;
+    /** Reset all cooldown timers so ads can be shown immediately. */
+    resetCooldowns(): void;
+    /** Current ad config (read-only snapshot). */
+    getAdConfig(): Readonly<AdConfig>;
+    dispose(): void;
+    /** Lazy-init: first access starts the first-interstitial cooldown. */
+    private getNextInterstitialAt;
+    private recordInterstitialShown;
+    private recordRewardedShown;
+}
+
+declare class WebViewTransport implements ITransport {
+    private pending;
+    private eventHandlers;
+    private messageListener;
+    private defaultTimeoutMs;
+    constructor(opts?: {
+        defaultTimeoutMs?: number;
+    });
+    send<T = unknown>(action: PlayLoopAction, payload?: Record<string, unknown>, opts?: SendOptions): Promise<T>;
+    onEvent(handler: EventHandler): () => void;
+    dispose(): void;
+    private handleMessage;
+}
+
+interface HttpTransportConfig {
+    apiBaseUrl: string;
+    gameId: string;
+    getAuthHeaders: () => Record<string, string>;
+    defaultTimeoutMs?: number;
+    /** SDK version for X-Client-Build header */
+    sdkVersion?: string;
+}
+declare class HttpTransport implements ITransport {
+    private config;
+    private activeControllers;
+    private disposed;
+    constructor(config: HttpTransportConfig);
+    send<T = unknown>(action: PlayLoopAction, payload?: Record<string, unknown>, opts?: SendOptions): Promise<T>;
+    onEvent(_handler: EventHandler): () => void;
+    dispose(): void;
+}
+
+declare class WebViewAdsAdapter implements IAdsAdapter {
+    private transport;
+    constructor(transport: ITransport);
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    hideBanner(): Promise<void>;
+    destroyBanner(): Promise<void>;
+}
+
+interface AppLovinConfig {
+    sdkKey: string;
+    rewardedAdUnitId: string;
+    interstitialAdUnitId: string;
+    bannerAdUnitId?: string;
+    debug?: boolean;
+}
+declare class CapacitorAdsAdapter implements IAdsAdapter {
+    private plugin;
+    private config;
+    private initialized;
+    private initPromise;
+    private debug;
+    constructor(config: AppLovinConfig);
+    initialize(): Promise<void>;
+    showRewardedVideo(): Promise<boolean>;
+    showInterstitial(): Promise<boolean>;
+    showBanner(position?: BannerPosition): Promise<boolean>;
+    hideBanner(): Promise<void>;
+    destroyBanner(): Promise<void>;
+}
+
+/** Compute widget top-bar height from window.innerWidth — no init required. */
+declare function getWidgetHeight(): number;
+
+export { AnalyticsModule, BabylonPlugin, CapacitorAdsAdapter, DEFAULT_AD_CONFIG, EmbeddedAdsModule, FeatureFlagModule, HttpTransport, PlayLoopSDK, RewardsModule, SessionModule, StandaloneAdsModule, UIModule, WebViewAdsAdapter, WebViewTransport, getWidgetHeight };
+export type { ActiveOffer, AdConfig, BannerPosition, EventHandler, IAds, IAdsAdapter, ITransport, InitResponse, PlayLoopAction, PlayLoopErrorCode, PlayLoopEvent, PlayLoopEventName, PlayLoopMessage, PlayLoopReady, PlayLoopRequest, PlayLoopResponse, PlayLoopSDKConfig, SendOptions, TierInfo, UIConfig, WalletData };