@bountyboard/arcade-sdk 1.0.1 → 1.1.0

package/AGENTS.md

@@ -72,7 +72,9 @@ the safe/default experience the alphabetically-first name. Don't re-randomize cl
   assert that `show()` is called directly by your UI handler and only final status `'viewed'`
   grants the reward.
 - Multiplayer: run the room server locally (`wrangler dev` with `DEV_ALLOW_UNSIGNED=1`) and pass
-  `{ roomUrl, ticket }` overrides to `joinRoom` for development.
+  `{ roomUrl, ticket }` overrides to `joinRoom` for development. Exercise a disconnect/reconnect,
+  assert `trySend()` returns false while offline, and verify the authoritative module validates the
+  optional `joinData` rather than treating avatar/loadout/mode selections as trusted state.
 
 ## Design intent (read docs/game-design-playbook.md before building a NEW game)
 

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# @bountyboard/arcade-sdk
+
+## 1.1.0
+
+### Minor Changes
+
+- 10a4997: Support production real-time game modules with bounded join data, observable reconnect state, and explicit `trySend` backpressure.
+
+### Patch Changes
+
+- f701c2c: Require Bounty Board-approved, host-session-bound tickets for multiplayer rooms and harden the authoritative room server's edge authorization.
+- 732b929: Keep the Bounty Board host fullscreen overlay from covering provider iframe ad
+  controls on touch devices.
+- 72daa42: Ship the package changelog and add reproducible release validation for npm,
+  browser-script, ESM, CommonJS, TypeScript, global, and multiplayer consumers.
+
+## 1.0.1
+
+### Patch Changes
+
+- Added a two-stage rewarded-ad preparation flow that preserves the browser's
+  direct user activation requirement, with expanded integration guidance and
+  regression coverage.
+
+## 1.0.0
+
+### Major Changes
+
+- Initial public release with leaderboard, cloud-save, rewarded-ad,
+  experimentation, player, sitelock, and multiplayer APIs.

package/README.md

@@ -95,21 +95,31 @@ not break, but new integrations should use the prepared flow because an asynchro
 ```ts
 import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
 
-const room = await joinRoom({ create: true }); // or { code: 'ABCD' }
+const room = await joinRoom({
+  create: true, // or code: 'ABCD'
+  joinData: { avatar: 'golem', mode: 'ffa' }, // untrusted, validated by your module
+});
 room.on('snapshot', ({ state }) => render(state)); // server-authoritative state
 room.on('end', ({ results }) => showResults(results));
-room.send({ move: dir }); // inputs only — the server simulates
+room.on('connection', status => showReconnecting(!status.connected));
+if (!room.trySend({ move: dir })) showReconnecting(true); // inputs only
 ```
 
 Rooms run on Bounty Board's authoritative room servers: clients send inputs, the server
 validates and simulates, and each player receives only the state they're allowed to see
 (your hiders stay hidden). Auth is a short-lived signed ticket the SDK obtains from the
 host automatically; off Bounty Board `joinRoom` rejects with `code: 'unsupported'`.
+`joinData` is limited to a 1 KiB JSON object, is never trusted or broadcast by the
+platform, and must not contain secrets. The room runtime supports separate simulation
+and snapshot rates (for example 60 Hz simulation / 30 Hz snapshots), a 15-second seat
+grace for automatic reconnects, and bounded server frames.
 
 Multiplayer is currently a curated integration: Bounty Board must add and deploy a
 server-side game module for your slug before `joinRoom()` can accept players. The
 initial reference module is `hide-and-seek`; arbitrary games do not become
-authoritative multiplayer games merely by importing the client SDK.
+authoritative multiplayer games merely by importing the client SDK. A production
+module must validate join data and every input, clear held controls on disconnect,
+serialize only per-viewer-safe state, and return final authoritative standings.
 
 ## Docs
 

package/dist/global-sdk.d.ts

@@ -220,6 +220,13 @@ interface BBArcadeMpJoinOptions {
   code?: string;
   /** Create a new room (a share code is generated for you). */
   create?: boolean;
+  /**
+   * Game-defined, JSON-serializable data supplied to the authoritative module
+   * before it admits this player (avatar/loadout/mode selections, for example).
+   * The room server treats this as untrusted input and limits it to 1 KiB.
+   * Never put credentials or other secrets here.
+   */
+  joinData?: Readonly<Record<string, unknown>>;
   /**
    * 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
@@ -240,6 +247,8 @@ interface BBArcadeMpRoomEvents {
   /** The match finished; results were reported by the server, not by clients. */
   end: { results: BBArcadeMpResult[] };
   error: { code: string };
+  /** Connection state, including successful automatic reconnection. */
+  connection: { connected: boolean; reconnecting: boolean };
   /** Connection dropped. reconnecting: true means the SDK is retrying. */
   close: { reconnecting: boolean };
 }
@@ -254,8 +263,12 @@ interface BBArcadeMpRoom {
   players: BBArcadeMpPlayer[];
   /** Latest authoritative state snapshot (as filtered for you). */
   state: unknown;
+  /** Whether the room currently has an accepted WebSocket connection. */
+  connected: boolean;
   /** 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. */
+  trySend(input: unknown): boolean;
   /** Subscribe to a room event; returns an unsubscribe function. */
   on<K extends keyof BBArcadeMpRoomEvents>(
     event: K,

package/dist/global.js

@@ -884,6 +884,7 @@
   // src/multiplayer.ts
   var WELCOME_TIMEOUT_MS = 1e4;
   var MAX_RECONNECT_ATTEMPTS = 3;
+  var MAX_JOIN_DATA_BYTES = 1024;
   var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
   var CODE_LENGTH = 4;
   function sdkError3(code) {
@@ -905,15 +906,42 @@
   function generateCode() {
     return randomChars(CODE_LENGTH);
   }
-  var guestKey = null;
-  function getGuestKey() {
-    if (!guestKey) guestKey = randomChars(16);
-    return guestKey;
+  function utf8ByteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+      const code = value.charCodeAt(i);
+      if (code < 128) bytes += 1;
+      else if (code < 2048) bytes += 2;
+      else if (code >= 55296 && code <= 56319 && i + 1 < value.length) {
+        const next = value.charCodeAt(i + 1);
+        if (next >= 56320 && next <= 57343) {
+          bytes += 4;
+          i += 1;
+        } else {
+          bytes += 3;
+        }
+      } else bytes += 3;
+    }
+    return bytes;
+  }
+  function serializeJoinData(data) {
+    if (data === void 0) return null;
+    if (!data || typeof data !== "object" || Array.isArray(data)) throw sdkError3("rejected");
+    let serialized;
+    try {
+      serialized = JSON.stringify(data);
+    } catch (e) {
+      throw sdkError3("rejected");
+    }
+    if (!serialized || utf8ByteLength(serialized) > MAX_JOIN_DATA_BYTES) {
+      throw sdkError3("rejected");
+    }
+    return serialized;
   }
   function requestTicket(roomId) {
     const request = BBArcade._request;
     if (typeof request !== "function") return Promise.reject(sdkError3("unsupported"));
-    return request("mp_ticket", { roomId, guestKey: getGuestKey() }).then((grant) => {
+    return request("mp_ticket", { roomId }).then((grant) => {
       const g = grant;
       if (!g || typeof g.ticket !== "string" || typeof g.roomUrl !== "string") {
         throw sdkError3("error");
@@ -922,10 +950,11 @@
     });
   }
   var RoomConnection = class {
-    constructor(code, devGrant) {
+    constructor(code, devGrant, joinData) {
       this.playerId = "";
       this.players = [];
       this.state = null;
+      this.connected = false;
       this.ws = null;
       // Keyed by event name; values are erased to (unknown) => void internally and
       // retyped at the on()/emit() boundary, which keeps the public API strictly
@@ -940,12 +969,13 @@
       this.reconnectAttempts = 0;
       this.code = code;
       this.devGrant = devGrant;
+      this.joinData = joinData;
     }
     /** Connect and resolve on the server's welcome (post-ticket-verification). */
     connect(grant) {
       return new Promise((resolve, reject) => {
         let settled = false;
-        const url = grant.roomUrl + (grant.roomUrl.indexOf("?") === -1 ? "?" : "&") + "ticket=" + encodeURIComponent(grant.ticket);
+        const url = grant.roomUrl + (grant.roomUrl.indexOf("?") === -1 ? "?" : "&") + "ticket=" + encodeURIComponent(grant.ticket) + (this.joinData === null ? "" : "&join=" + encodeURIComponent(this.joinData));
         let ws;
         try {
           ws = new WebSocket(url);
@@ -973,15 +1003,18 @@
           }
           if (!msg || typeof msg.t !== "string") return;
           if (msg.t === "welcome") {
+            const reconnected = this.reconnectAttempts > 0;
             this.playerId = String((_a = msg.playerId) != null ? _a : "");
             this.players = Array.isArray(msg.players) ? msg.players : [];
             this.state = (_b = msg.state) != null ? _b : null;
+            this.connected = true;
             this.reconnectAttempts = 0;
             if (!settled) {
               settled = true;
               clearTimeout(welcomeTimer);
               resolve(this);
             }
+            if (reconnected) this.emit("connection", { connected: true, reconnecting: false });
             return;
           }
           if (msg.t === "snapshot") {
@@ -1031,6 +1064,7 @@
           }
         };
         ws.onclose = () => {
+          this.connected = false;
           if (!settled) {
             settled = true;
             clearTimeout(welcomeTimer);
@@ -1038,6 +1072,7 @@
             return;
           }
           if (this.intentionalClose || this.ended || this.terminal) {
+            this.emit("connection", { connected: false, reconnecting: false });
             this.emit("close", { reconnecting: false });
             return;
           }
@@ -1055,6 +1090,7 @@
         return;
       }
       this.reconnectAttempts += 1;
+      this.emit("connection", { connected: false, reconnecting: true });
       this.emit("close", { reconnecting: true });
       await new Promise((r) => setTimeout(r, 400 * this.reconnectAttempts));
       if (this.intentionalClose || this.ended || this.terminal) return;
@@ -1068,11 +1104,16 @@
       }
     }
     send(input) {
-      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+      this.trySend(input);
+    }
+    trySend(input) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false;
       this.seq += 1;
       try {
         this.ws.send(JSON.stringify({ t: "input", seq: this.seq, data: input }));
+        return true;
       } catch (err) {
+        return false;
       }
     }
     on(event, handler) {
@@ -1088,6 +1129,7 @@
     leave() {
       var _a;
       this.intentionalClose = true;
+      this.connected = false;
       try {
         (_a = this.ws) == null ? void 0 : _a.close(1e3);
       } catch (err) {
@@ -1113,11 +1155,17 @@
       return Promise.reject(sdkError3("unsupported"));
     }
     const code = opts.create || !opts.code ? generateCode() : opts.code.toUpperCase();
+    let joinData;
+    try {
+      joinData = serializeJoinData(opts.joinData);
+    } catch (err) {
+      return Promise.reject(err);
+    }
     if (opts.roomUrl && opts.ticket) {
       const devGrant = { ticket: opts.ticket, roomUrl: opts.roomUrl, expiresAt: 0 };
-      return new RoomConnection(code, devGrant).connect(devGrant);
+      return new RoomConnection(code, devGrant, joinData).connect(devGrant);
     }
-    return requestTicket(code).then((grant) => new RoomConnection(code, null).connect(grant));
+    return requestTicket(code).then((grant) => new RoomConnection(code, null, joinData).connect(grant));
   }
   var multiplayer = { joinRoom };
 

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BBArcadeSDK } from './types-BKChtV3H.cjs';
-export { a as BBArcadeConfig, b as BBArcadeError, c as BBArcadeErrorCode, d as BBArcadeLockToHostOptions, e as BBArcadePlayer, f as BBArcadePrepareRewardedAdOptions, g as BBArcadePreparedRewardedAd, h as BBArcadeRewardedAdOptions, i as BBArcadeRewardedAdPreparation, j as BBArcadeRewardedAdPrepareFailure, k as BBArcadeRewardedAdResult, l as BBArcadeRewardedAdStatus, m as BBArcadeRewardedAdsConfig, n as BBArcadeRewardedBreakOptions } from './types-BKChtV3H.cjs';
+import { B as BBArcadeSDK } from './types-Cq8p7ZkC.cjs';
+export { a as BBArcadeConfig, b as BBArcadeError, c as BBArcadeErrorCode, d as BBArcadeLockToHostOptions, e as BBArcadePlayer, f as BBArcadePrepareRewardedAdOptions, g as BBArcadePreparedRewardedAd, h as BBArcadeRewardedAdOptions, i as BBArcadeRewardedAdPreparation, j as BBArcadeRewardedAdPrepareFailure, k as BBArcadeRewardedAdResult, l as BBArcadeRewardedAdStatus, m as BBArcadeRewardedAdsConfig, n as BBArcadeRewardedBreakOptions } from './types-Cq8p7ZkC.cjs';
 
 /**
  * Wire-protocol constants for the bb-arcade postMessage protocol. The protocol

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BBArcadeSDK } from './types-BKChtV3H.js';
-export { a as BBArcadeConfig, b as BBArcadeError, c as BBArcadeErrorCode, d as BBArcadeLockToHostOptions, e as BBArcadePlayer, f as BBArcadePrepareRewardedAdOptions, g as BBArcadePreparedRewardedAd, h as BBArcadeRewardedAdOptions, i as BBArcadeRewardedAdPreparation, j as BBArcadeRewardedAdPrepareFailure, k as BBArcadeRewardedAdResult, l as BBArcadeRewardedAdStatus, m as BBArcadeRewardedAdsConfig, n as BBArcadeRewardedBreakOptions } from './types-BKChtV3H.js';
+import { B as BBArcadeSDK } from './types-Cq8p7ZkC.js';
+export { a as BBArcadeConfig, b as BBArcadeError, c as BBArcadeErrorCode, d as BBArcadeLockToHostOptions, e as BBArcadePlayer, f as BBArcadePrepareRewardedAdOptions, g as BBArcadePreparedRewardedAd, h as BBArcadeRewardedAdOptions, i as BBArcadeRewardedAdPreparation, j as BBArcadeRewardedAdPrepareFailure, k as BBArcadeRewardedAdResult, l as BBArcadeRewardedAdStatus, m as BBArcadeRewardedAdsConfig, n as BBArcadeRewardedBreakOptions } from './types-Cq8p7ZkC.js';
 
 /**
  * Wire-protocol constants for the bb-arcade postMessage protocol. The protocol

package/dist/multiplayer.cjs

@@ -909,6 +909,7 @@ var BBArcade = typeof window === "undefined" ? createInertBBArcade() : createBBA
 // src/multiplayer.ts
 var WELCOME_TIMEOUT_MS = 1e4;
 var MAX_RECONNECT_ATTEMPTS = 3;
+var MAX_JOIN_DATA_BYTES = 1024;
 var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 var CODE_LENGTH = 4;
 function sdkError3(code) {
@@ -930,15 +931,42 @@ function randomChars(length) {
 function generateCode() {
   return randomChars(CODE_LENGTH);
 }
-var guestKey = null;
-function getGuestKey() {
-  if (!guestKey) guestKey = randomChars(16);
-  return guestKey;
+function utf8ByteLength(value) {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319 && i + 1 < value.length) {
+      const next = value.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i += 1;
+      } else {
+        bytes += 3;
+      }
+    } else bytes += 3;
+  }
+  return bytes;
+}
+function serializeJoinData(data) {
+  if (data === void 0) return null;
+  if (!data || typeof data !== "object" || Array.isArray(data)) throw sdkError3("rejected");
+  let serialized;
+  try {
+    serialized = JSON.stringify(data);
+  } catch (e) {
+    throw sdkError3("rejected");
+  }
+  if (!serialized || utf8ByteLength(serialized) > MAX_JOIN_DATA_BYTES) {
+    throw sdkError3("rejected");
+  }
+  return serialized;
 }
 function requestTicket(roomId) {
   const request = BBArcade._request;
   if (typeof request !== "function") return Promise.reject(sdkError3("unsupported"));
-  return request("mp_ticket", { roomId, guestKey: getGuestKey() }).then((grant) => {
+  return request("mp_ticket", { roomId }).then((grant) => {
     const g = grant;
     if (!g || typeof g.ticket !== "string" || typeof g.roomUrl !== "string") {
       throw sdkError3("error");
@@ -947,10 +975,11 @@ function requestTicket(roomId) {
   });
 }
 var RoomConnection = class {
-  constructor(code, devGrant) {
+  constructor(code, devGrant, joinData) {
     this.playerId = "";
     this.players = [];
     this.state = null;
+    this.connected = false;
     this.ws = null;
     // Keyed by event name; values are erased to (unknown) => void internally and
     // retyped at the on()/emit() boundary, which keeps the public API strictly
@@ -965,12 +994,13 @@ var RoomConnection = class {
     this.reconnectAttempts = 0;
     this.code = code;
     this.devGrant = devGrant;
+    this.joinData = joinData;
   }
   /** Connect and resolve on the server's welcome (post-ticket-verification). */
   connect(grant) {
     return new Promise((resolve, reject) => {
       let settled = false;
-      const url = grant.roomUrl + (grant.roomUrl.indexOf("?") === -1 ? "?" : "&") + "ticket=" + encodeURIComponent(grant.ticket);
+      const url = grant.roomUrl + (grant.roomUrl.indexOf("?") === -1 ? "?" : "&") + "ticket=" + encodeURIComponent(grant.ticket) + (this.joinData === null ? "" : "&join=" + encodeURIComponent(this.joinData));
       let ws;
       try {
         ws = new WebSocket(url);
@@ -998,15 +1028,18 @@ var RoomConnection = class {
         }
         if (!msg || typeof msg.t !== "string") return;
         if (msg.t === "welcome") {
+          const reconnected = this.reconnectAttempts > 0;
           this.playerId = String((_a = msg.playerId) != null ? _a : "");
           this.players = Array.isArray(msg.players) ? msg.players : [];
           this.state = (_b = msg.state) != null ? _b : null;
+          this.connected = true;
           this.reconnectAttempts = 0;
           if (!settled) {
             settled = true;
             clearTimeout(welcomeTimer);
             resolve(this);
           }
+          if (reconnected) this.emit("connection", { connected: true, reconnecting: false });
           return;
         }
         if (msg.t === "snapshot") {
@@ -1056,6 +1089,7 @@ var RoomConnection = class {
         }
       };
       ws.onclose = () => {
+        this.connected = false;
         if (!settled) {
           settled = true;
           clearTimeout(welcomeTimer);
@@ -1063,6 +1097,7 @@ var RoomConnection = class {
           return;
         }
         if (this.intentionalClose || this.ended || this.terminal) {
+          this.emit("connection", { connected: false, reconnecting: false });
           this.emit("close", { reconnecting: false });
           return;
         }
@@ -1080,6 +1115,7 @@ var RoomConnection = class {
       return;
     }
     this.reconnectAttempts += 1;
+    this.emit("connection", { connected: false, reconnecting: true });
     this.emit("close", { reconnecting: true });
     await new Promise((r) => setTimeout(r, 400 * this.reconnectAttempts));
     if (this.intentionalClose || this.ended || this.terminal) return;
@@ -1093,11 +1129,16 @@ var RoomConnection = class {
     }
   }
   send(input) {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.trySend(input);
+  }
+  trySend(input) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false;
     this.seq += 1;
     try {
       this.ws.send(JSON.stringify({ t: "input", seq: this.seq, data: input }));
+      return true;
     } catch (err) {
+      return false;
     }
   }
   on(event, handler) {
@@ -1113,6 +1154,7 @@ var RoomConnection = class {
   leave() {
     var _a;
     this.intentionalClose = true;
+    this.connected = false;
     try {
       (_a = this.ws) == null ? void 0 : _a.close(1e3);
     } catch (err) {
@@ -1138,11 +1180,17 @@ function joinRoom(options) {
     return Promise.reject(sdkError3("unsupported"));
   }
   const code = opts.create || !opts.code ? generateCode() : opts.code.toUpperCase();
+  let joinData;
+  try {
+    joinData = serializeJoinData(opts.joinData);
+  } catch (err) {
+    return Promise.reject(err);
+  }
   if (opts.roomUrl && opts.ticket) {
     const devGrant = { ticket: opts.ticket, roomUrl: opts.roomUrl, expiresAt: 0 };
-    return new RoomConnection(code, devGrant).connect(devGrant);
+    return new RoomConnection(code, devGrant, joinData).connect(devGrant);
   }
-  return requestTicket(code).then((grant) => new RoomConnection(code, null).connect(grant));
+  return requestTicket(code).then((grant) => new RoomConnection(code, null, joinData).connect(grant));
 }
 var multiplayer = { joinRoom };
 // Annotate the CommonJS export names for ESM import in node: