@bountyboard/arcade-sdk 1.0.0

package/dist/types-B6xH-lDi.d.cts

@@ -0,0 +1,328 @@
+/**
+ * Public API types for the Bounty Board Arcade SDK.
+ *
+ * SINGLE SOURCE OF TRUTH for the SDK's public types. The npm module's .d.ts is
+ * bundled from here by tsup, and the self-contained global declaration file
+ * (served at /arcade-sdk/v1.d.ts for script-tag users) is generated from this
+ * file by scripts/build-global-dts.mjs — keep every declaration here
+ * self-contained (no imports) so that generation stays a plain text transform.
+ */
+/** Machine-readable failure code carried by every SDK rejection (`err.code`). */
+type BBArcadeErrorCode = 
+/** Nothing will answer: standalone play, or not a Bounty-Board-hosted build. */
+'unsupported'
+/** The player isn't logged in to Bounty Board. */
+ | 'unauthenticated'
+/** The save blob is over the per-save byte cap (~1MB). */
+ | 'too_large'
+/** The host refused the request (bad payload, unknown game, etc.). */
+ | 'rejected'
+/** Transport/server failure or timeout. */
+ | 'error';
+/** Rejection reason for save()/load(): a real Error that also carries `code`. */
+interface BBArcadeError extends Error {
+    code: BBArcadeErrorCode;
+}
+/** Rewarded-ads settings accepted by init()/configure(). */
+interface BBArcadeRewardedAdsConfig {
+    /** Master switch for the game's own rewarded-ad calls (default true). Ads still only run when the Bounty Board host enables them for your game. */
+    enabled?: boolean;
+    /** Legacy AdSense channel label. Ignored on Bounty Board (revenue is attributed by page URL). */
+    adChannel?: string;
+    /** Force Google's test-ads mode. Defaults to true on localhost/file:, and the Bounty Board host sets it per environment. */
+    testMode?: boolean;
+    /** Warm up the H5 ads library immediately so the first placement is less likely to be unavailable. */
+    preload?: boolean;
+    /** How long a rewarded placement waits for an ad before resolving 'unavailable', in ms (default 6000, max 15000). */
+    loadTimeoutMs?: number;
+}
+/** Options bag for init() and configure(). */
+interface BBArcadeConfig {
+    rewardedAds?: BBArcadeRewardedAdsConfig;
+}
+/**
+ * The logged-in player's public display identity, as delivered by the Bounty
+ * Board host. Display name + avatar ONLY — the host never sends ids, emails,
+ * or roles.
+ */
+interface BBArcadePlayer {
+    /** Display name for in-game UI (e.g. "Good luck, Grant!"). */
+    name: string;
+    /** Avatar image URL, or null when the player has no avatar. */
+    avatarUrl: string | null;
+}
+/** Options for lockToHost(). */
+interface BBArcadeLockToHostOptions {
+    /**
+     * Extra hostnames to permit (your own domain, a staging or preview host).
+     * Matches the host and its subdomains; added to the bountyboard.gg +
+     * localhost defaults. Plain hosts, host:port, or full URLs all work.
+     */
+    allow?: string[];
+    /**
+     * Demand a cryptographically signed origin attestation from the host and
+     * verify it with the SDK's embedded public key (hardens the check beyond
+     * the best-effort browser signals). Falls back to best-effort when the host
+     * reports no signing key or the browser lacks Web Crypto; a present-but-
+     * invalid attestation — or no host answering at all — blocks.
+     */
+    signed?: boolean;
+    /** Called instead of the default block screen so you can render your own. */
+    onBlocked?: () => void;
+    /** URL to send the player to when blocked (best effort; a sandboxed build may not be allowed to navigate). */
+    redirect?: string;
+}
+/** Outcome of a rewarded placement. */
+type BBArcadeRewardedAdStatus = 'viewed' | 'dismissed' | 'ready' | 'unavailable' | 'error';
+/** Resolution value of rewardedAd()/showRewardedAd(). */
+interface BBArcadeRewardedAdResult {
+    /** 'viewed' is the only status that should grant the reward. */
+    status: BBArcadeRewardedAdStatus;
+    /** Sanitized placement name the ad ran under. */
+    placement: string;
+    /** Sanitized reward label. */
+    reward: string;
+    /** Unique id for this ad break (for your own logging/dedup). */
+    adBreakId: string;
+    /** Present when a size was requested. */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Failure detail when status is 'unavailable' or 'error', e.g.
+     * 'host_disabled' | 'ad_break_unavailable' | 'ad_break_timeout' |
+     * 'no_rewarded_ad' | 'ad_in_progress' | 'show_ad_error' |
+     * 'before_reward_error' | 'ad_break_error'.
+     */
+    error?: string;
+    /** Google's H5 breakStatus string, when the placement reported one. */
+    breakStatus?: string;
+}
+/** Options for rewardedAd()/showRewardedAd() (all optional). */
+interface BBArcadeRewardedAdOptions {
+    /** Placement name for analytics, e.g. 'revive' (alias: name). */
+    placement?: string;
+    /** Alias for placement. */
+    name?: string;
+    /** Reward label for analytics, e.g. 'extra_life'. */
+    reward?: string;
+    /** Supply your own ad-break id instead of the generated one. */
+    adBreakId?: string;
+    /** Requested ad size. */
+    size?: 'small' | 'medium' | 'large';
+    /** Legacy AdSense channel label. Ignored on Bounty Board. */
+    adChannel?: string;
+    /** Force Google's test-ads mode (the Bounty Board host's setting wins when present). */
+    testMode?: boolean;
+    /** Per-call override of how long to wait for an ad, in ms (max 15000). */
+    loadTimeoutMs?: number;
+    /**
+     * Called when an ad is ready. Pause your game, then call showAd() to run it.
+     * When omitted, the ad shows immediately.
+     */
+    beforeReward?: (showAd: () => void) => void;
+    /** The player watched the ad to completion — grant the reward. */
+    adViewed?: (result: BBArcadeRewardedAdResult) => void;
+    /** The player closed the ad early (or after viewing; check status). */
+    adDismissed?: (result: BBArcadeRewardedAdResult) => void;
+    /** Google's raw adBreakDone callback, with its placementInfo. */
+    adBreakDone?: (placementInfo: unknown) => void;
+    /** Alias of adViewed. */
+    onReward?: (result: BBArcadeRewardedAdResult) => void;
+    /** Alias of adDismissed. */
+    onDismissed?: (result: BBArcadeRewardedAdResult) => void;
+    /** Always called once with the final result (any status). */
+    onDone?: (result: BBArcadeRewardedAdResult) => void;
+    /** Called when the placement fails with status 'error'. */
+    onError?: (result: BBArcadeRewardedAdResult) => void;
+    /** Called when no ad could be shown (status 'unavailable'). */
+    onUnavailable?: (result: BBArcadeRewardedAdResult) => void;
+}
+/** Options for rewardedBreak(): everything rewardedAd() takes, plus onStart. */
+interface BBArcadeRewardedBreakOptions extends BBArcadeRewardedAdOptions {
+    /** Called once right before the ad shows — pause gameplay/audio here. */
+    onStart?: () => void;
+}
+/** A player in a multiplayer room — display identity only, plus the room-scoped id. */
+interface BBArcadeMpPlayer {
+    /** Room-scoped player id (stable for the connection, never a Bounty Board account id). */
+    id: string;
+    name: string;
+    avatarUrl: string | null;
+}
+/** One player's final standing in a finished multiplayer match. */
+interface BBArcadeMpResult {
+    playerId: string;
+    name: string;
+    placement: number;
+    score: number;
+    outcome: 'win' | 'loss' | 'draw';
+}
+/** Options for multiplayer joinRoom(). */
+interface BBArcadeMpJoinOptions {
+    /** Join an existing room by its share code. */
+    code?: string;
+    /** Create a new room (a share code is generated for you). */
+    create?: boolean;
+    /**
+     * Local development only: connect straight to a room server (e.g. wrangler
+     * dev with DEV_ALLOW_UNSIGNED=1) instead of asking the Bounty Board host for
+     * a ticket. Both must be provided together.
+     */
+    roomUrl?: string;
+    ticket?: string;
+}
+/** Events a multiplayer room emits. */
+interface BBArcadeMpRoomEvents {
+    /** Authoritative state snapshot (already filtered to what YOU may see). */
+    snapshot: {
+        tick: number;
+        state: unknown;
+    };
+    playerJoin: {
+        player: BBArcadeMpPlayer;
+    };
+    playerLeave: {
+        playerId: string;
+    };
+    /** Game-defined server event (tag happened, round started, ...). */
+    event: unknown;
+    /** The match finished; results were reported by the server, not by clients. */
+    end: {
+        results: BBArcadeMpResult[];
+    };
+    error: {
+        code: string;
+    };
+    /** Connection dropped. reconnecting: true means the SDK is retrying. */
+    close: {
+        reconnecting: boolean;
+    };
+}
+/** A live connection to an authoritative multiplayer room. */
+interface BBArcadeMpRoom {
+    /** The share code friends use to join this room. */
+    code: string;
+    /** Your room-scoped player id. */
+    playerId: string;
+    /** Players currently in the room (kept up to date). */
+    players: BBArcadeMpPlayer[];
+    /** Latest authoritative state snapshot (as filtered for you). */
+    state: unknown;
+    /** Send an INPUT to the server (never authoritative state — the server simulates). */
+    send(input: unknown): void;
+    /** Subscribe to a room event; returns an unsubscribe function. */
+    on<K extends keyof BBArcadeMpRoomEvents>(event: K, handler: (data: BBArcadeMpRoomEvents[K]) => void): () => void;
+    /** Leave the room and close the connection (no reconnect). */
+    leave(): void;
+}
+/** The multiplayer module (BBArcade.multiplayer in script-tag builds). */
+interface BBArcadeMultiplayer {
+    /**
+     * Create or join an authoritative multiplayer room. Resolves once the room
+     * server accepted the signed ticket and sent the welcome state. Rejects with
+     * a BBArcadeError ('unsupported' off Bounty Board, 'unauthenticated' /
+     * 'rejected' / 'error' from the ticket handshake).
+     */
+    joinRoom(options?: BBArcadeMpJoinOptions): Promise<BBArcadeMpRoom>;
+}
+/**
+ * The Bounty Board Arcade SDK surface (window.BBArcade for script-tag builds,
+ * the `BBArcade` export of @bountyboard/arcade-sdk for module builds).
+ *
+ * Every method is optional to call and safe standalone: off Bounty Board the
+ * fire-and-forget signals no-op, and save()/load() reject fast with code
+ * 'unsupported' instead of hanging.
+ */
+interface BBArcadeSDK {
+    /**
+     * Refuse to run unless embedded on a Bounty Board host (anti
+     * scrape-and-reupload deterrent — not DRM). Call once, early, before boot.
+     */
+    lockToHost(options?: BBArcadeLockToHostOptions): void;
+    /**
+     * Configure optional SDK modules and announce the game to the host. Resolves
+     * once the host answers with its config, or after a short grace (~1.5s) when
+     * nothing answers — so it never blocks your boot and awaiting is optional.
+     */
+    init(options?: BBArcadeConfig): Promise<void>;
+    /** Apply the same options as init() without the host handshake. */
+    configure(options?: BBArcadeConfig): void;
+    /** Warm up Google's H5 ads library. Resolves true when the placement API is available. */
+    preloadRewardedAds(options?: BBArcadeRewardedAdOptions): Promise<boolean>;
+    /** Alias of preloadRewardedAds. */
+    preloadRewardedAd(options?: BBArcadeRewardedAdOptions): Promise<boolean>;
+    /** Signal that the game finished loading and the player can start. */
+    ready(): void;
+    /** Poki-style alias of ready(). */
+    gameLoadingFinished(): void;
+    /** Signal that active gameplay started (run begins or resumes). */
+    gameplayStart(): void;
+    /** Signal that active gameplay stopped (death, pause menu, ad break). */
+    gameplayStop(): void;
+    /**
+     * Report the player's current integer score. Call freely; the host throttles.
+     * Pass { mode: 'daily' } when the run is your shared-seed Daily so the Today
+     * board can mark it.
+     */
+    submitScore(score: number, opts?: {
+        mode?: 'daily';
+    }): void;
+    /** Report the final integer score on game over (feeds the leaderboards). */
+    gameOver(score: number, opts?: {
+        mode?: 'daily';
+    }): void;
+    /** Signal that an immersive WebXR session started (keeps playtime counting). */
+    xrSessionStart(): void;
+    /** Signal that the immersive WebXR session ended. */
+    xrSessionEnd(): void;
+    /**
+     * Show a rewarded ad via Google's H5 placement API. Resolves with the full
+     * result object; only status 'viewed' should grant the reward. Prefer
+     * rewardedBreak() unless you need the low-level callbacks.
+     */
+    rewardedAd(options?: BBArcadeRewardedAdOptions): Promise<BBArcadeRewardedAdResult>;
+    /** Alias of rewardedAd. */
+    showRewardedAd(options?: BBArcadeRewardedAdOptions): Promise<BBArcadeRewardedAdResult>;
+    /**
+     * Developer-standard rewarded break. Show your own "Watch ad for reward" UI
+     * first; resolves true only when the ad was actually viewed. Accepts an
+     * options bag or a bare onStart callback.
+     */
+    rewardedBreak(optionsOrOnStart?: BBArcadeRewardedBreakOptions | (() => void)): Promise<boolean>;
+    /**
+     * Save the player's progress (a string blob, ~1MB max) to their Bounty Board
+     * account. Requires a Bounty-Board-hosted build upload and a logged-in
+     * player; rejects with a BBArcadeError otherwise (code 'unsupported' /
+     * 'unauthenticated' / 'too_large' / 'rejected' / 'error').
+     */
+    save(blob: string): Promise<void>;
+    /**
+     * Load the player's saved blob. Resolves with the string, or null when there
+     * is no save yet. Rejects like save() ('unauthenticated' when logged out).
+     */
+    load(): Promise<string | null>;
+    /**
+     * The logged-in player's display identity for in-game UI. Resolves
+     * { name, avatarUrl } once the host's config handshake completes (or after
+     * a short grace when nothing answers), and null for guests, standalone
+     * play, or off Bounty Board — always handle the null case. Privacy:
+     * display name + avatar only, never ids, emails, or roles.
+     */
+    getPlayer(): Promise<BBArcadePlayer | null>;
+    /**
+     * Deterministic A/B variant for this player (even split; stable per
+     * player+game+key). Resolves the alphabetically-first variant as the
+     * fallback/control on standalone play or any host error. Assignments show
+     * up split-by-variant in studio analytics.
+     */
+    getVariant(key: string, variants: string[]): Promise<string | null>;
+    /**
+     * Multiplayer rooms. Present in the script-tag build; module consumers
+     * import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer' instead
+     * (keeps the core import lean).
+     */
+    multiplayer?: BBArcadeMultiplayer;
+    /** SDK protocol version (matches the `v` field on every message). */
+    version: number;
+}
+
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadeRewardedAdOptions as f, BBArcadeRewardedAdResult as g, BBArcadeRewardedAdStatus as h, BBArcadeRewardedAdsConfig as i, BBArcadeRewardedBreakOptions as j, BBArcadeMpJoinOptions as k, BBArcadeMpRoom as l, BBArcadeMultiplayer as m, BBArcadeMpPlayer as n, BBArcadeMpResult as o, BBArcadeMpRoomEvents as p };

package/dist/types-B6xH-lDi.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Public API types for the Bounty Board Arcade SDK.
+ *
+ * SINGLE SOURCE OF TRUTH for the SDK's public types. The npm module's .d.ts is
+ * bundled from here by tsup, and the self-contained global declaration file
+ * (served at /arcade-sdk/v1.d.ts for script-tag users) is generated from this
+ * file by scripts/build-global-dts.mjs — keep every declaration here
+ * self-contained (no imports) so that generation stays a plain text transform.
+ */
+/** Machine-readable failure code carried by every SDK rejection (`err.code`). */
+type BBArcadeErrorCode = 
+/** Nothing will answer: standalone play, or not a Bounty-Board-hosted build. */
+'unsupported'
+/** The player isn't logged in to Bounty Board. */
+ | 'unauthenticated'
+/** The save blob is over the per-save byte cap (~1MB). */
+ | 'too_large'
+/** The host refused the request (bad payload, unknown game, etc.). */
+ | 'rejected'
+/** Transport/server failure or timeout. */
+ | 'error';
+/** Rejection reason for save()/load(): a real Error that also carries `code`. */
+interface BBArcadeError extends Error {
+    code: BBArcadeErrorCode;
+}
+/** Rewarded-ads settings accepted by init()/configure(). */
+interface BBArcadeRewardedAdsConfig {
+    /** Master switch for the game's own rewarded-ad calls (default true). Ads still only run when the Bounty Board host enables them for your game. */
+    enabled?: boolean;
+    /** Legacy AdSense channel label. Ignored on Bounty Board (revenue is attributed by page URL). */
+    adChannel?: string;
+    /** Force Google's test-ads mode. Defaults to true on localhost/file:, and the Bounty Board host sets it per environment. */
+    testMode?: boolean;
+    /** Warm up the H5 ads library immediately so the first placement is less likely to be unavailable. */
+    preload?: boolean;
+    /** How long a rewarded placement waits for an ad before resolving 'unavailable', in ms (default 6000, max 15000). */
+    loadTimeoutMs?: number;
+}
+/** Options bag for init() and configure(). */
+interface BBArcadeConfig {
+    rewardedAds?: BBArcadeRewardedAdsConfig;
+}
+/**
+ * The logged-in player's public display identity, as delivered by the Bounty
+ * Board host. Display name + avatar ONLY — the host never sends ids, emails,
+ * or roles.
+ */
+interface BBArcadePlayer {
+    /** Display name for in-game UI (e.g. "Good luck, Grant!"). */
+    name: string;
+    /** Avatar image URL, or null when the player has no avatar. */
+    avatarUrl: string | null;
+}
+/** Options for lockToHost(). */
+interface BBArcadeLockToHostOptions {
+    /**
+     * Extra hostnames to permit (your own domain, a staging or preview host).
+     * Matches the host and its subdomains; added to the bountyboard.gg +
+     * localhost defaults. Plain hosts, host:port, or full URLs all work.
+     */
+    allow?: string[];
+    /**
+     * Demand a cryptographically signed origin attestation from the host and
+     * verify it with the SDK's embedded public key (hardens the check beyond
+     * the best-effort browser signals). Falls back to best-effort when the host
+     * reports no signing key or the browser lacks Web Crypto; a present-but-
+     * invalid attestation — or no host answering at all — blocks.
+     */
+    signed?: boolean;
+    /** Called instead of the default block screen so you can render your own. */
+    onBlocked?: () => void;
+    /** URL to send the player to when blocked (best effort; a sandboxed build may not be allowed to navigate). */
+    redirect?: string;
+}
+/** Outcome of a rewarded placement. */
+type BBArcadeRewardedAdStatus = 'viewed' | 'dismissed' | 'ready' | 'unavailable' | 'error';
+/** Resolution value of rewardedAd()/showRewardedAd(). */
+interface BBArcadeRewardedAdResult {
+    /** 'viewed' is the only status that should grant the reward. */
+    status: BBArcadeRewardedAdStatus;
+    /** Sanitized placement name the ad ran under. */
+    placement: string;
+    /** Sanitized reward label. */
+    reward: string;
+    /** Unique id for this ad break (for your own logging/dedup). */
+    adBreakId: string;
+    /** Present when a size was requested. */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Failure detail when status is 'unavailable' or 'error', e.g.
+     * 'host_disabled' | 'ad_break_unavailable' | 'ad_break_timeout' |
+     * 'no_rewarded_ad' | 'ad_in_progress' | 'show_ad_error' |
+     * 'before_reward_error' | 'ad_break_error'.
+     */
+    error?: string;
+    /** Google's H5 breakStatus string, when the placement reported one. */
+    breakStatus?: string;
+}
+/** Options for rewardedAd()/showRewardedAd() (all optional). */
+interface BBArcadeRewardedAdOptions {
+    /** Placement name for analytics, e.g. 'revive' (alias: name). */
+    placement?: string;
+    /** Alias for placement. */
+    name?: string;
+    /** Reward label for analytics, e.g. 'extra_life'. */
+    reward?: string;
+    /** Supply your own ad-break id instead of the generated one. */
+    adBreakId?: string;
+    /** Requested ad size. */
+    size?: 'small' | 'medium' | 'large';
+    /** Legacy AdSense channel label. Ignored on Bounty Board. */
+    adChannel?: string;
+    /** Force Google's test-ads mode (the Bounty Board host's setting wins when present). */
+    testMode?: boolean;
+    /** Per-call override of how long to wait for an ad, in ms (max 15000). */
+    loadTimeoutMs?: number;
+    /**
+     * Called when an ad is ready. Pause your game, then call showAd() to run it.
+     * When omitted, the ad shows immediately.
+     */
+    beforeReward?: (showAd: () => void) => void;
+    /** The player watched the ad to completion — grant the reward. */
+    adViewed?: (result: BBArcadeRewardedAdResult) => void;
+    /** The player closed the ad early (or after viewing; check status). */
+    adDismissed?: (result: BBArcadeRewardedAdResult) => void;
+    /** Google's raw adBreakDone callback, with its placementInfo. */
+    adBreakDone?: (placementInfo: unknown) => void;
+    /** Alias of adViewed. */
+    onReward?: (result: BBArcadeRewardedAdResult) => void;
+    /** Alias of adDismissed. */
+    onDismissed?: (result: BBArcadeRewardedAdResult) => void;
+    /** Always called once with the final result (any status). */
+    onDone?: (result: BBArcadeRewardedAdResult) => void;
+    /** Called when the placement fails with status 'error'. */
+    onError?: (result: BBArcadeRewardedAdResult) => void;
+    /** Called when no ad could be shown (status 'unavailable'). */
+    onUnavailable?: (result: BBArcadeRewardedAdResult) => void;
+}
+/** Options for rewardedBreak(): everything rewardedAd() takes, plus onStart. */
+interface BBArcadeRewardedBreakOptions extends BBArcadeRewardedAdOptions {
+    /** Called once right before the ad shows — pause gameplay/audio here. */
+    onStart?: () => void;
+}
+/** A player in a multiplayer room — display identity only, plus the room-scoped id. */
+interface BBArcadeMpPlayer {
+    /** Room-scoped player id (stable for the connection, never a Bounty Board account id). */
+    id: string;
+    name: string;
+    avatarUrl: string | null;
+}
+/** One player's final standing in a finished multiplayer match. */
+interface BBArcadeMpResult {
+    playerId: string;
+    name: string;
+    placement: number;
+    score: number;
+    outcome: 'win' | 'loss' | 'draw';
+}
+/** Options for multiplayer joinRoom(). */
+interface BBArcadeMpJoinOptions {
+    /** Join an existing room by its share code. */
+    code?: string;
+    /** Create a new room (a share code is generated for you). */
+    create?: boolean;
+    /**
+     * Local development only: connect straight to a room server (e.g. wrangler
+     * dev with DEV_ALLOW_UNSIGNED=1) instead of asking the Bounty Board host for
+     * a ticket. Both must be provided together.
+     */
+    roomUrl?: string;
+    ticket?: string;
+}
+/** Events a multiplayer room emits. */
+interface BBArcadeMpRoomEvents {
+    /** Authoritative state snapshot (already filtered to what YOU may see). */
+    snapshot: {
+        tick: number;
+        state: unknown;
+    };
+    playerJoin: {
+        player: BBArcadeMpPlayer;
+    };
+    playerLeave: {
+        playerId: string;
+    };
+    /** Game-defined server event (tag happened, round started, ...). */
+    event: unknown;
+    /** The match finished; results were reported by the server, not by clients. */
+    end: {
+        results: BBArcadeMpResult[];
+    };
+    error: {
+        code: string;
+    };
+    /** Connection dropped. reconnecting: true means the SDK is retrying. */
+    close: {
+        reconnecting: boolean;
+    };
+}
+/** A live connection to an authoritative multiplayer room. */
+interface BBArcadeMpRoom {
+    /** The share code friends use to join this room. */
+    code: string;
+    /** Your room-scoped player id. */
+    playerId: string;
+    /** Players currently in the room (kept up to date). */
+    players: BBArcadeMpPlayer[];
+    /** Latest authoritative state snapshot (as filtered for you). */
+    state: unknown;
+    /** Send an INPUT to the server (never authoritative state — the server simulates). */
+    send(input: unknown): void;
+    /** Subscribe to a room event; returns an unsubscribe function. */
+    on<K extends keyof BBArcadeMpRoomEvents>(event: K, handler: (data: BBArcadeMpRoomEvents[K]) => void): () => void;
+    /** Leave the room and close the connection (no reconnect). */
+    leave(): void;
+}
+/** The multiplayer module (BBArcade.multiplayer in script-tag builds). */
+interface BBArcadeMultiplayer {
+    /**
+     * Create or join an authoritative multiplayer room. Resolves once the room
+     * server accepted the signed ticket and sent the welcome state. Rejects with
+     * a BBArcadeError ('unsupported' off Bounty Board, 'unauthenticated' /
+     * 'rejected' / 'error' from the ticket handshake).
+     */
+    joinRoom(options?: BBArcadeMpJoinOptions): Promise<BBArcadeMpRoom>;
+}
+/**
+ * The Bounty Board Arcade SDK surface (window.BBArcade for script-tag builds,
+ * the `BBArcade` export of @bountyboard/arcade-sdk for module builds).
+ *
+ * Every method is optional to call and safe standalone: off Bounty Board the
+ * fire-and-forget signals no-op, and save()/load() reject fast with code
+ * 'unsupported' instead of hanging.
+ */
+interface BBArcadeSDK {
+    /**
+     * Refuse to run unless embedded on a Bounty Board host (anti
+     * scrape-and-reupload deterrent — not DRM). Call once, early, before boot.
+     */
+    lockToHost(options?: BBArcadeLockToHostOptions): void;
+    /**
+     * Configure optional SDK modules and announce the game to the host. Resolves
+     * once the host answers with its config, or after a short grace (~1.5s) when
+     * nothing answers — so it never blocks your boot and awaiting is optional.
+     */
+    init(options?: BBArcadeConfig): Promise<void>;
+    /** Apply the same options as init() without the host handshake. */
+    configure(options?: BBArcadeConfig): void;
+    /** Warm up Google's H5 ads library. Resolves true when the placement API is available. */
+    preloadRewardedAds(options?: BBArcadeRewardedAdOptions): Promise<boolean>;
+    /** Alias of preloadRewardedAds. */
+    preloadRewardedAd(options?: BBArcadeRewardedAdOptions): Promise<boolean>;
+    /** Signal that the game finished loading and the player can start. */
+    ready(): void;
+    /** Poki-style alias of ready(). */
+    gameLoadingFinished(): void;
+    /** Signal that active gameplay started (run begins or resumes). */
+    gameplayStart(): void;
+    /** Signal that active gameplay stopped (death, pause menu, ad break). */
+    gameplayStop(): void;
+    /**
+     * Report the player's current integer score. Call freely; the host throttles.
+     * Pass { mode: 'daily' } when the run is your shared-seed Daily so the Today
+     * board can mark it.
+     */
+    submitScore(score: number, opts?: {
+        mode?: 'daily';
+    }): void;
+    /** Report the final integer score on game over (feeds the leaderboards). */
+    gameOver(score: number, opts?: {
+        mode?: 'daily';
+    }): void;
+    /** Signal that an immersive WebXR session started (keeps playtime counting). */
+    xrSessionStart(): void;
+    /** Signal that the immersive WebXR session ended. */
+    xrSessionEnd(): void;
+    /**
+     * Show a rewarded ad via Google's H5 placement API. Resolves with the full
+     * result object; only status 'viewed' should grant the reward. Prefer
+     * rewardedBreak() unless you need the low-level callbacks.
+     */
+    rewardedAd(options?: BBArcadeRewardedAdOptions): Promise<BBArcadeRewardedAdResult>;
+    /** Alias of rewardedAd. */
+    showRewardedAd(options?: BBArcadeRewardedAdOptions): Promise<BBArcadeRewardedAdResult>;
+    /**
+     * Developer-standard rewarded break. Show your own "Watch ad for reward" UI
+     * first; resolves true only when the ad was actually viewed. Accepts an
+     * options bag or a bare onStart callback.
+     */
+    rewardedBreak(optionsOrOnStart?: BBArcadeRewardedBreakOptions | (() => void)): Promise<boolean>;
+    /**
+     * Save the player's progress (a string blob, ~1MB max) to their Bounty Board
+     * account. Requires a Bounty-Board-hosted build upload and a logged-in
+     * player; rejects with a BBArcadeError otherwise (code 'unsupported' /
+     * 'unauthenticated' / 'too_large' / 'rejected' / 'error').
+     */
+    save(blob: string): Promise<void>;
+    /**
+     * Load the player's saved blob. Resolves with the string, or null when there
+     * is no save yet. Rejects like save() ('unauthenticated' when logged out).
+     */
+    load(): Promise<string | null>;
+    /**
+     * The logged-in player's display identity for in-game UI. Resolves
+     * { name, avatarUrl } once the host's config handshake completes (or after
+     * a short grace when nothing answers), and null for guests, standalone
+     * play, or off Bounty Board — always handle the null case. Privacy:
+     * display name + avatar only, never ids, emails, or roles.
+     */
+    getPlayer(): Promise<BBArcadePlayer | null>;
+    /**
+     * Deterministic A/B variant for this player (even split; stable per
+     * player+game+key). Resolves the alphabetically-first variant as the
+     * fallback/control on standalone play or any host error. Assignments show
+     * up split-by-variant in studio analytics.
+     */
+    getVariant(key: string, variants: string[]): Promise<string | null>;
+    /**
+     * Multiplayer rooms. Present in the script-tag build; module consumers
+     * import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer' instead
+     * (keeps the core import lean).
+     */
+    multiplayer?: BBArcadeMultiplayer;
+    /** SDK protocol version (matches the `v` field on every message). */
+    version: number;
+}
+
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadeRewardedAdOptions as f, BBArcadeRewardedAdResult as g, BBArcadeRewardedAdStatus as h, BBArcadeRewardedAdsConfig as i, BBArcadeRewardedBreakOptions as j, BBArcadeMpJoinOptions as k, BBArcadeMpRoom as l, BBArcadeMultiplayer as m, BBArcadeMpPlayer as n, BBArcadeMpResult as o, BBArcadeMpRoomEvents as p };