@bountyboard/arcade-sdk 1.1.0 → 1.3.0

package/dist/{types-Cq8p7ZkC.d.ts → types-B5bqWnHH.d.ts}

@@ -22,6 +22,8 @@ type BBArcadeErrorCode =
 /** Rejection reason for save()/load(): a real Error that also carries `code`. */
 interface BBArcadeError extends Error {
     code: BBArcadeErrorCode;
+    /** Optional server detail for 'rejected' errors (e.g. 'room_full'). */
+    detail?: string;
 }
 /** Rewarded-ads settings accepted by init()/configure(). */
 interface BBArcadeRewardedAdsConfig {
@@ -40,6 +42,46 @@ interface BBArcadeRewardedAdsConfig {
 interface BBArcadeConfig {
     rewardedAds?: BBArcadeRewardedAdsConfig;
 }
+/**
+ * What is backing `window.localStorage` right now.
+ * - `native` — a real Storage works here; the SDK changed nothing.
+ * - `cloud` — the shim is installed and syncs to the player's Bounty Board save.
+ * - `memory` — the shim is installed but nothing can persist (guest, standalone,
+ *   off-host); reads and writes work for the session and are then discarded.
+ */
+type BBArcadeStorageMode = 'native' | 'cloud' | 'memory';
+/**
+ * localStorage compatibility for hosted builds. Bounty-Board-hosted uploads run
+ * in an opaque-origin sandbox where `localStorage` THROWS rather than returning
+ * empty, which breaks engine exports (GameMaker `ini_*`, Godot, Unity) that
+ * assume synchronous storage. The shim replaces it with a Storage-shaped object
+ * backed by the SDK's own cloud save, so those builds persist per player and
+ * across devices with no engine changes.
+ *
+ * The script-tag build installs it automatically at load. Module consumers keep
+ * a side-effect-free import and call `install()` themselves before boot.
+ */
+interface BBArcadeStorage {
+    /**
+     * Install the shim if this origin has no working localStorage, and return the
+     * resulting mode. Idempotent, and a no-op when native storage works. Call it
+     * BEFORE the engine/game script runs.
+     */
+    install(): BBArcadeStorageMode;
+    /**
+     * Resolves once the cloud read has landed (or settled as unpersistable).
+     * `getItem` is synchronous but the cloud read is not, so a game that reads
+     * saved progress during boot should await this first.
+     */
+    ready(): Promise<BBArcadeStorageMode>;
+    /**
+     * Force pending writes out now instead of waiting for the debounce. Rejects
+     * with the same BBArcadeError codes as save().
+     */
+    flush(): Promise<void>;
+    /** The current backing mode. */
+    readonly mode: BBArcadeStorageMode;
+}
 /**
  * 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,
@@ -73,7 +115,17 @@ interface BBArcadeLockToHostOptions {
     redirect?: string;
 }
 /** Outcome of a rewarded placement. */
-type BBArcadeRewardedAdStatus = 'viewed' | 'dismissed' | 'ready' | 'unavailable' | 'error';
+type BBArcadeRewardedAdStatus = 
+/** The player watched the ad to completion — the only status that grants. */
+'viewed'
+/** The player closed the ad early, or a prepared ad ended before it was ever shown. */
+ | 'dismissed'
+/** An ad is ready to show (preparation result; terminal only in the legacy shown-but-unreported edge). */
+ | 'ready'
+/** No ad could be offered. */
+ | 'unavailable'
+/** The placement failed. */
+ | 'error';
 /** Resolution value of rewardedAd()/showRewardedAd(). */
 interface BBArcadeRewardedAdResult {
     /** 'viewed' is the only status that should grant the reward. */
@@ -196,6 +248,15 @@ interface BBArcadeMpJoinOptions {
     code?: string;
     /** Create a new room (a share code is generated for you). */
     create?: boolean;
+    /**
+     * Public quick match: join your game's open public room, or start a fresh
+     * one when no seat is free. Mutually exclusive with code/create. Rooms fill
+     * to the game's player cap (at most 64), and a matched room still exposes
+     * room.code so the player can invite friends into the same room. If the
+     * last free seat is lost to a race, the SDK re-matchmakes automatically a
+     * couple of times before rejecting.
+     */
+    match?: boolean;
     /**
      * Game-defined, JSON-serializable data supplied to the authoritative module
      * before it admits this player (avatar/loadout/mode selections, for example).
@@ -210,6 +271,12 @@ interface BBArcadeMpJoinOptions {
      */
     roomUrl?: string;
     ticket?: string;
+    /**
+     * How long to wait for the room server's welcome before the join rejects
+     * with code 'error', in ms (default 10000, clamped to 1000–60000). Applies
+     * to the initial join and to every automatic reconnect attempt.
+     */
+    timeoutMs?: number;
 }
 /** Events a multiplayer room emits. */
 interface BBArcadeMpRoomEvents {
@@ -255,6 +322,13 @@ interface BBArcadeMpRoom {
     state: unknown;
     /** Whether the room currently has an accepted WebSocket connection. */
     connected: boolean;
+    /**
+     * Join-handshake latency in ms (socket open → server welcome, so ticket
+     * verification plus one round trip), refreshed on every successful
+     * (re)connect; null until the first welcome arrives. A tuning estimate for
+     * render-side smoothing, not a measured RTT.
+     */
+    latencyMs: number | null;
     /** Send an INPUT to the server (never authoritative state — the server simulates). */
     send(input: unknown): void;
     /** Like send(), but reports false when disconnected or the socket raced closed. */
@@ -286,6 +360,9 @@ interface BBArcadeSDK {
     /**
      * Refuse to run unless embedded on a Bounty Board host (anti
      * scrape-and-reupload deterrent — not DRM). Call once, early, before boot.
+     * When the embedder can't be determined from browser signals (opaque-origin
+     * sandboxed builds), the SDK asks the embedding page and blocks if nothing
+     * answers within ~5 seconds.
      */
     lockToHost(options?: BBArcadeLockToHostOptions): void;
     /**
@@ -353,14 +430,23 @@ interface BBArcadeSDK {
      * 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').
+     * 'unauthenticated' / 'too_large' / 'rejected' / 'error'). Oversized blobs
+     * reject 'too_large' immediately (client-side precheck against the same 1
+     * MiB cap the server enforces); a host that never answers rejects 'error'
+     * after a 15s request timeout.
      */
     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).
+     * is no save yet. Rejects like save() ('unauthenticated' when logged out,
+     * 'error' after the same 15s request timeout when no host answers).
      */
     load(): Promise<string | null>;
+    /**
+     * localStorage compatibility for hosted builds — the escape hatch for engine
+     * exports that can't be rewired to call save()/load(). See BBArcadeStorage.
+     */
+    storage: BBArcadeStorage;
     /**
      * The logged-in player's display identity for in-game UI. Resolves
      * { name, avatarUrl } once the host's config handshake completes (or after
@@ -369,6 +455,15 @@ interface BBArcadeSDK {
      * display name + avatar only, never ids, emails, or roles.
      */
     getPlayer(): Promise<BBArcadePlayer | null>;
+    /**
+     * Subscribe to CHANGES in the player's display identity (e.g. the player
+     * logs in or out mid-session and the host pushes a fresh config). The
+     * handler runs only when the identity actually changes — subscribing does
+     * not replay the current value; call getPlayer() for that. Receives the
+     * same { name, avatarUrl } | null shape as getPlayer(). Returns an
+     * unsubscribe function.
+     */
+    onPlayerChange(handler: (player: BBArcadePlayer | null) => void): () => void;
     /**
      * Deterministic A/B variant for this player (even split; stable per
      * player+game+key). Resolves the alphabetically-first variant as the
@@ -386,4 +481,4 @@ interface BBArcadeSDK {
     version: number;
 }
 
-export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeMpJoinOptions as o, BBArcadeMpRoom as p, BBArcadeMultiplayer as q, BBArcadeMpPlayer as r, BBArcadeMpResult as s, BBArcadeMpRoomEvents as t };
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeStorage as o, BBArcadeStorageMode as p, BBArcadeMpJoinOptions as q, BBArcadeMpRoom as r, BBArcadeMultiplayer as s, BBArcadeMpPlayer as t, BBArcadeMpResult as u, BBArcadeMpRoomEvents as v };

package/docs/external-authoritative-servers.md

@@ -0,0 +1,265 @@
+# External authoritative multiplayer servers
+
+Use this integration when your game already has a mature authoritative server
+that must remain responsible for admission, inputs, simulation, state, and
+results. Bounty Board connects the Arcade SDK to that server through a small
+adapter contract; it does not relay traffic or run a second simulation.
+
+External authorities are reviewed and enabled per game. Registration is not
+self-service. Contact Bounty Board before implementing the adapter so the game
+slug, endpoints, room-code rules, ticket keys, and result model can be agreed
+for staging and production.
+
+## What stays authoritative
+
+Your server remains the only source of truth. It must:
+
+- admit a socket only after verifying its Bounty Board ticket;
+- treat `joinData` and every client input as untrusted;
+- run the only game simulation;
+- clear held controls and other transient input on disconnect;
+- send each player only the state that player may see;
+- decide when a finite match is over and author the final standings; and
+- keep endless rooms endless instead of inventing a terminal result.
+
+The SDK handles ticket acquisition, WebSocket connection, reconnection, and a
+small room-message envelope. It never grants a client authority over identity,
+state, roles, or results.
+
+## Registration information
+
+Provide Bounty Board with the following for each environment:
+
+- the exact Arcade game slug;
+- one fixed `wss:` endpoint dedicated to authenticated SDK rooms;
+- the room-code format and maximum length your server accepts;
+- whether missing room codes may create rooms;
+- any validated, game-defined `joinData` fields;
+- whether the game has finite matches or endless sessions; and
+- an operational contact for key rotation or incident response.
+
+The registered endpoint must not contain userinfo, query parameters, or a
+fragment. Use `ws:` only for loopback development. Staging and production need
+different endpoints and different secrets.
+
+Bounty Board provisions a dedicated ticket-verification secret for the game
+and environment. Store it only on servers. Do not put it in the game bundle,
+browser storage, logs, analytics, crash reports, or client-visible environment
+variables. Do not reuse credentials from another game or room service.
+
+## Connection flow
+
+1. The game calls `joinRoom()` from the Arcade SDK.
+2. The SDK asks the trusted Bounty Board host for a room ticket.
+3. Bounty Board verifies the game approval, multiplayer approval, active play
+   session, player or guest identity, game slug, and requested room code.
+4. Bounty Board returns a 60-second ticket and the registered WebSocket URL.
+5. The SDK appends the encoded ticket and optional encoded `joinData`, then
+   opens the socket.
+6. Your server verifies the ticket before admitting the socket and sends a
+   `welcome` frame within 10 seconds.
+
+The sandboxed game never receives a Bounty Board session cookie and never calls
+the ticket HTTP endpoint itself.
+
+## Ticket format
+
+Tickets are compact HMAC envelopes, not JWTs:
+
+```text
+payloadB64 = base64url(UTF8(JSON(payload)))
+signatureB64 = base64url(HMAC-SHA256(payloadB64, ticketSecret))
+ticket = payloadB64 + "." + signatureB64
+```
+
+The HMAC input is the UTF-8 byte sequence of the base64url payload string.
+`iat` and `exp` are Unix milliseconds. The current lifetime is 60 seconds.
+
+```json
+{
+  "v": 1,
+  "sub": "player:<opaque-game-scoped-value>",
+  "name": "Display Name",
+  "avatarUrl": null,
+  "slug": "your-game-slug",
+  "roomId": "ROOM-CODE",
+  "guest": false,
+  "iat": 1700000000000,
+  "exp": 1700000060000
+}
+```
+
+Before accepting a connection, verify all of the following:
+
+- the ticket contains exactly one separator and both parts decode;
+- the HMAC matches using a constant-time comparison;
+- `v` is the supported ticket version;
+- `exp` is still in the future and `iat` is reasonable;
+- `slug` exactly matches the registered game;
+- `roomId` exactly matches the requested room and your registered rules;
+- `sub` is non-empty; and
+- required claim types and lengths are valid.
+
+Treat `sub` as an opaque game-scoped identity. Never attempt to map it to a
+Bounty Board account or correlate it with another game. `name` and `avatarUrl`
+are display data, not authorization data. `avatarUrl` may be `null` for any
+player.
+
+## SDK call
+
+Module builds import multiplayer from its dedicated entry point:
+
+```ts
+import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
+
+const room = await joinRoom({
+  code: 'ROOM-CODE', // or create: true to ask the SDK for a new code
+  joinData: {
+    schemaVersion: 1,
+    loadout: 'starter',
+    mode: 'friends',
+  },
+});
+
+room.on('snapshot', ({ state }) => renderAuthoritativeState(state));
+room.on('connection', ({ connected }) => setReconnecting(!connected));
+
+if (!room.trySend({ type: 'move', x: 1, y: 0 })) {
+  setReconnecting(true);
+}
+```
+
+Script-tag builds use `BBArcade.multiplayer.joinRoom(...)`.
+
+`joinData` is an optional JSON object capped at 1 KiB. Validate every field,
+reject unknown or oversized values, and never accept credentials or identity
+claims from it. If your server distinguishes create from join, use a documented
+game-defined intent field and rate-limit room creation. That field is still
+untrusted and grants no role or permission by itself.
+
+## WebSocket URL
+
+The SDK opens the registered endpoint with URL-encoded query parameters:
+
+```text
+wss://multiplayer.example.com/bountyboard?ticket=<encoded>&join=<encoded-json>
+```
+
+The `join` parameter is omitted when no `joinData` was supplied. Keep this path
+separate from any anonymous or legacy socket endpoint so a guessed room code
+cannot cross the authentication boundary. Redact or disable request-URI logging
+on this route because the short-lived ticket is in the query string.
+
+## SDK room envelope
+
+All frames are JSON text. After successful verification and admission, send a
+`welcome` frame within 10 seconds:
+
+```json
+{
+  "t": "welcome",
+  "playerId": "room-scoped-player-id",
+  "players": [{ "id": "room-scoped-player-id", "name": "Display Name", "avatarUrl": null }],
+  "state": { "phase": "lobby" }
+}
+```
+
+Send authoritative state snapshots as:
+
+```json
+{
+  "t": "snapshot",
+  "tick": 42,
+  "state": { "phase": "playing", "players": [] }
+}
+```
+
+Send game-defined transient events without changing their payload:
+
+```json
+{ "t": "event", "data": { "type": "round_started", "round": 2 } }
+```
+
+The SDK also recognizes player roster events:
+
+```json
+{ "t": "player_join", "player": { "id": "p2", "name": "Guest", "avatarUrl": null } }
+{ "t": "player_leave", "playerId": "p2" }
+```
+
+Clients send inputs, never state:
+
+```json
+{ "t": "input", "seq": 7, "data": { "type": "move", "x": 1, "y": 0 } }
+```
+
+Validate the envelope, sequence, payload shape, value ranges, rate, current
+player state, and game rules before applying an input. Bound both inbound and
+outbound frame sizes.
+
+Reject an invalid ticket before `welcome` with an error and close the socket:
+
+```json
+{ "t": "error", "code": "unauthenticated" }
+```
+
+Use `rejected` for invalid admission or `joinData`. After admission, error codes
+remain game-defined strings and are surfaced through `room.on('error', ...)`.
+
+## Reconnection
+
+The SDK automatically makes a small number of reconnect attempts. It requests
+a fresh ticket for the same room and reuses the original `joinData`. Rebind the
+seat using the verified `(ticket.sub, ticket.roomId)` pair. Never trust a
+client-supplied player id or reconnect token as the proof of identity.
+
+Send the latest complete viewer-safe state in the new `welcome` frame. If your
+client uses prediction, include the last processed input sequence in that state
+so it can discard acknowledged inputs. Clear held controls while the socket is
+absent.
+
+## Finite matches and endless rooms
+
+Only a server-authoritative finite game may emit `match_end`:
+
+```json
+{
+  "t": "match_end",
+  "results": [
+    {
+      "playerId": "p1",
+      "name": "Display Name",
+      "placement": 1,
+      "score": 1200,
+      "outcome": "win"
+    }
+  ]
+}
+```
+
+The client receives this as `room.on('end', ({ results }) => ...)`. Persistent
+Bounty Board results, when enabled, use a separately provisioned
+server-to-server reporting credential. Never accept a client-originated result
+or reporting credential.
+
+Endless rooms must not emit `match_end`. Death, respawn, a round transition, or
+a player leaving is not automatically a terminal match result.
+
+## Production checklist
+
+- Use an isolated staging endpoint and secrets before production.
+- Confirm tampered, expired, wrong-slug, and wrong-room tickets fail closed.
+- Test both guest and logged-in opaque subjects.
+- Reject malformed, unknown, or oversized `joinData`.
+- Send `welcome` only after ticket and admission validation succeeds.
+- Verify every snapshot is safe for its specific viewer.
+- Test disconnect, held-input cleanup, fresh-ticket reconnect, and `leave()`.
+- Rate-limit upgrades, room creation, joins, and inputs.
+- Redact tickets and join payloads from access logs and error telemetry.
+- Rotate the dedicated ticket secret without reusing another environment's key.
+- Emit final results only from a real authoritative terminal condition.
+- Keep the game playable when multiplayer is unsupported or temporarily down.
+
+For SDK integration basics, see https://www.bountyboard.gg/arcade/sdk. For the
+agent-readable API contract, see
+https://www.bountyboard.gg/arcade/sdk/llms.txt.