@bountyboard/arcade-sdk 1.0.0 → 1.1.0

package/dist/global-sdk.d.ts

@@ -103,13 +103,19 @@ interface BBArcadeRewardedAdResult {
    * 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'.
+   * 'direct_user_action_required' | 'before_reward_error' |
+   * 'ad_break_error'.
    */
   error?: string;
   /** Google's H5 breakStatus string, when the placement reported one. */
   breakStatus?: string;
 }
 
+/** A terminal failure returned while preparing a rewarded placement. */
+type BBArcadeRewardedAdPrepareFailure = BBArcadeRewardedAdResult & {
+  status: 'unavailable' | 'error';
+};
+
 /** Options for rewardedAd()/showRewardedAd() (all optional). */
 interface BBArcadeRewardedAdOptions {
   /** Placement name for analytics, e.g. 'revive' (alias: name). */
@@ -120,7 +126,7 @@ interface BBArcadeRewardedAdOptions {
   reward?: string;
   /** Supply your own ad-break id instead of the generated one. */
   adBreakId?: string;
-  /** Requested ad size. */
+  /** Legacy SDK analytics metadata; never forwarded as a Google adBreak field. */
   size?: 'small' | 'medium' | 'large';
   /** Legacy AdSense channel label. Ignored on Bounty Board. */
   adChannel?: string;
@@ -129,8 +135,10 @@ interface BBArcadeRewardedAdOptions {
   /** 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.
+   * Called when an ad is ready. Retain showAd and invoke it directly from the
+   * player's click/tap handler. An asynchronous call without active browser
+   * user activation fails with 'direct_user_action_required'. Prefer
+   * prepareRewardedAd() for the typed two-stage flow.
    */
   beforeReward?: (showAd: () => void) => void;
   /** The player watched the ad to completion — grant the reward. */
@@ -151,6 +159,38 @@ interface BBArcadeRewardedAdOptions {
   onUnavailable?: (result: BBArcadeRewardedAdResult) => void;
 }
 
+/**
+ * Options for prepareRewardedAd(). The preparation owns Google's beforeReward
+ * callback so it can retain showAdFn safely; onStart runs synchronously inside
+ * the returned handle's show() method.
+ */
+type BBArcadePrepareRewardedAdOptions = Omit<BBArcadeRewardedAdOptions, 'beforeReward'> & {
+  /** Called synchronously immediately before Google's retained showAdFn. */
+  onStart?: () => void;
+};
+
+/**
+ * A rewarded placement Google has made available. Call show() directly from
+ * the player's click/tap handler; do not await or schedule other work first.
+ */
+interface BBArcadePreparedRewardedAd {
+  status: 'ready';
+  placement: string;
+  reward: string;
+  adBreakId: string;
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * One-shot display call. Invokes Google's retained showAdFn synchronously,
+   * then resolves with the final structured outcome. Only 'viewed' grants.
+   */
+  show(): Promise<BBArcadeRewardedAdResult>;
+}
+
+/** Result of prepareRewardedAd(): a ready handle or a terminal failure. */
+type BBArcadeRewardedAdPreparation =
+  | BBArcadePreparedRewardedAd
+  | BBArcadeRewardedAdPrepareFailure;
+
 /** Options for rewardedBreak(): everything rewardedAd() takes, plus onStart. */
 interface BBArcadeRewardedBreakOptions extends BBArcadeRewardedAdOptions {
   /** Called once right before the ad shows — pause gameplay/audio here. */
@@ -180,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
@@ -200,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 };
 }
@@ -214,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,
@@ -283,17 +336,32 @@ interface BBArcadeSDK {
   /** 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.
+   * Low-level rewarded placement API. Resolves with the full result object;
+   * only status 'viewed' should grant. Prefer prepareRewardedAd() for new
+   * integrations so Google's show function stays in the player's click stack.
    */
   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.
+   * Safely prepare a rewarded placement without showing it. When status is
+   * 'ready', call result.show() directly from the player's click/tap handler;
+   * it resolves with the full final result and only 'viewed' should grant.
+   */
+  prepareRewardedAd(
+    options?: BBArcadePrepareRewardedAdOptions
+  ): Promise<BBArcadeRewardedAdPreparation>;
+  /** Alias of prepareRewardedAd. */
+  prepareRewardedBreak(
+    options?: BBArcadePrepareRewardedAdOptions
+  ): Promise<BBArcadeRewardedAdPreparation>;
+  /**
+   * Legacy one-call rewarded break. Resolves true only when the ad was viewed.
+   *
+   * @deprecated Use prepareRewardedAd(), then call the ready handle's show()
+   * directly from the player's click/tap handler. Google's beforeReward may be
+   * asynchronous, so this convenience call cannot preserve user activation in
+   * every browser.
    */
   rewardedBreak(optionsOrOnStart?: BBArcadeRewardedBreakOptions | (() => void)): Promise<boolean>;
   /**

package/dist/global.js

@@ -42,6 +42,11 @@
   function cleanRewardedSize(value) {
     return value === "small" || value === "medium" || value === "large" ? value : "";
   }
+  function hasTransientUserActivation() {
+    if (typeof navigator === "undefined") return false;
+    const activation = navigator.userActivation;
+    return (activation == null ? void 0 : activation.isActive) === true;
+  }
   function safeCall(fn, arg) {
     if (typeof fn !== "function") return;
     try {
@@ -118,7 +123,7 @@
   function createBBArcade() {
     let adPlacementLoad = null;
     let adPreloadConfigured = false;
-    let rewardedBreakActive = false;
+    let rewardedBreakActive = null;
     let rewardedBreakSequence = 0;
     function isLocalAdHost() {
       try {
@@ -529,6 +534,16 @@
             function show() {
               if (shown) return;
               shown = true;
+              if (!hasTransientUserActivation()) {
+                const activationError = Object.assign(
+                  { status: "error", error: "direct_user_action_required" },
+                  base
+                );
+                post("rewarded_ad", void 0, Object.assign({ event: "error" }, activationError));
+                safeCall(options.onError, activationError);
+                done(activationError);
+                return;
+              }
               post("rewarded_ad", void 0, Object.assign({ event: "started" }, base));
               try {
                 showAdFn();
@@ -552,6 +567,7 @@
                 base
               );
               post("rewarded_ad", void 0, Object.assign({ event: "error" }, beforeError));
+              if (shown) return;
               safeCall(options.onError, beforeError);
               done(beforeError);
             }
@@ -560,9 +576,9 @@
             adBreak({
               type: "reward",
               name: options.placement,
-              size: options.size || void 0,
               beforeReward: startAd,
               adViewed: function() {
+                if (resolved) return;
                 status = "viewed";
                 const viewed = Object.assign({ status }, base);
                 post("rewarded_ad", void 0, Object.assign({ event: "viewed" }, viewed));
@@ -570,6 +586,7 @@
                 safeCall(options.onReward, viewed);
               },
               adDismissed: function() {
+                if (resolved) return;
                 if (status !== "viewed") status = "dismissed";
                 const dismissed = Object.assign({ status }, base);
                 post("rewarded_ad", void 0, Object.assign({ event: "dismissed" }, dismissed));
@@ -577,6 +594,7 @@
                 safeCall(options.onDismissed, dismissed);
               },
               adBreakDone: function(placementInfo) {
+                if (resolved) return;
                 const result = rewardOffered || status !== "unavailable" ? { status } : { status: "unavailable", error: "no_rewarded_ad" };
                 if (placementInfo && typeof placementInfo === "object") {
                   result.breakStatus = cleanText(
@@ -610,6 +628,52 @@
         });
       });
     }
+    function prepareRewardedAd(rawOptions) {
+      const normalized = normalizeRewardedOptions(rawOptions);
+      const base = {
+        placement: normalized.placement,
+        reward: normalized.reward,
+        adBreakId: normalized.adBreakId
+      };
+      if (normalized.size) base.size = normalized.size;
+      let ready2 = false;
+      let finalPromise;
+      return new Promise(function(resolvePreparation) {
+        finalPromise = rewardedAd(
+          Object.assign({}, rawOptions, {
+            // Preserve the id used by the ready handle and every lifecycle event;
+            // rewardedAd normalizes again, but this explicit id keeps both stages
+            // tied to the same placement.
+            adBreakId: normalized.adBreakId,
+            beforeReward: function(showAd) {
+              if (ready2) return;
+              ready2 = true;
+              let shown = false;
+              const prepared = Object.assign(
+                { status: "ready" },
+                base,
+                {
+                  show: function() {
+                    if (!shown) {
+                      shown = true;
+                      if (hasTransientUserActivation()) {
+                        safeCall(rawOptions && rawOptions.onStart);
+                      }
+                      showAd();
+                    }
+                    return finalPromise;
+                  }
+                }
+              );
+              resolvePreparation(prepared);
+            }
+          })
+        );
+        finalPromise.then(function(result) {
+          if (!ready2) resolvePreparation(result);
+        });
+      });
+    }
     function preloadRewardedAds(rawOptions) {
       const options = normalizeRewardedOptions(rawOptions);
       if (!areRewardedAdsEnabled()) return Promise.resolve(false);
@@ -656,7 +720,7 @@
         reward: normalized.reward
       };
       if (normalized.size) base.size = normalized.size;
-      if (rewardedBreakActive) {
+      if (rewardedBreakActive && rewardedBreakActive.state !== "ready") {
         post(
           "rewarded_ad",
           void 0,
@@ -667,24 +731,32 @@
         );
         return Promise.resolve(false);
       }
-      rewardedBreakActive = true;
+      const activeBreak = { state: "loading" };
+      rewardedBreakActive = activeBreak;
       let startCalled = false;
+      const callerBeforeReward = rawOptions.beforeReward;
       return rewardedAd(
         Object.assign({}, rawOptions, {
           beforeReward: function(showAd) {
-            if (startCalled) return;
-            startCalled = true;
-            safeCall(rawOptions.onStart);
-            showAd();
+            if (rewardedBreakActive === activeBreak) activeBreak.state = "ready";
+            const showWithStart = function() {
+              if (startCalled || rewardedBreakActive !== activeBreak) return;
+              startCalled = true;
+              activeBreak.state = "showing";
+              if (hasTransientUserActivation()) safeCall(rawOptions.onStart);
+              showAd();
+            };
+            if (typeof callerBeforeReward === "function") callerBeforeReward(showWithStart);
+            else showWithStart();
           }
         })
       ).then(
         function(result) {
-          rewardedBreakActive = false;
+          if (rewardedBreakActive === activeBreak) rewardedBreakActive = null;
           return Boolean(result && result.status === "viewed");
         },
         function() {
-          rewardedBreakActive = false;
+          if (rewardedBreakActive === activeBreak) rewardedBreakActive = null;
           return false;
         }
       );
@@ -722,6 +794,8 @@
       },
       rewardedAd,
       showRewardedAd: rewardedAd,
+      prepareRewardedAd,
+      prepareRewardedBreak: prepareRewardedAd,
       rewardedBreak,
       save: function(blob) {
         return request("save", String(blob));
@@ -767,6 +841,13 @@
       reward: "reward",
       adBreakId: "bbad_inert"
     });
+    const prepareUnavailable = () => Promise.resolve({
+      status: "unavailable",
+      error: "ad_break_unavailable",
+      placement: "rewarded",
+      reward: "reward",
+      adBreakId: "bbad_inert"
+    });
     return {
       lockToHost: noop,
       init: () => Promise.resolve(),
@@ -783,6 +864,8 @@
       xrSessionEnd: noop,
       rewardedAd: unavailable,
       showRewardedAd: unavailable,
+      prepareRewardedAd: prepareUnavailable,
+      prepareRewardedBreak: prepareUnavailable,
       rewardedBreak: () => Promise.resolve(false),
       save: () => Promise.reject(sdkError2("unsupported")),
       load: () => Promise.reject(sdkError2("unsupported")),
@@ -801,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) {
@@ -822,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");
@@ -839,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
@@ -857,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);
@@ -890,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") {
@@ -948,6 +1064,7 @@
           }
         };
         ws.onclose = () => {
+          this.connected = false;
           if (!settled) {
             settled = true;
             clearTimeout(welcomeTimer);
@@ -955,6 +1072,7 @@
             return;
           }
           if (this.intentionalClose || this.ended || this.terminal) {
+            this.emit("connection", { connected: false, reconnecting: false });
             this.emit("close", { reconnecting: false });
             return;
           }
@@ -972,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;
@@ -985,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) {
@@ -1005,6 +1129,7 @@
     leave() {
       var _a;
       this.intentionalClose = true;
+      this.connected = false;
       try {
         (_a = this.ws) == null ? void 0 : _a.close(1e3);
       } catch (err) {
@@ -1030,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 };