@tesana/sdk 1.0.1 → 1.0.3

package/dist/tesana.esm.js

@@ -37,7 +37,7 @@
 // 1.0.0 ships six services together: saves, shop, leaderboards, achievements,
 // a vanity address (`tesana.vanity`) and in-game ads (`tesana.ads`). These are
 // the first release, so there is no earlier number to stay compatible with.
-const VERSION = "1.0.1";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -145,12 +145,20 @@ function warnOnce(key, message) {
   }
 }
 
+function isGuestBootstrap(data) {
+  return Boolean(data && data.player && data.player.isGuest);
+}
+
 /** Fold a host's answer into the live config, upgrading a provisional one. */
 function applyBootstrap(data) {
   const next = data && typeof data === "object" ? data : {};
   if (bootstrap) {
-    if (!bootstrap.offline) return; // a real host has already answered
-    if (next.offline) return; // still nobody; nothing has changed
+    // A real host has already answered — unless that answer was a guest and
+    // this one is the account they just signed in to.
+    if (!bootstrap.offline && !(isGuestBootstrap(bootstrap) && !next.offline && !isGuestBootstrap(next))) return;
+    // Still offline, unless it now carries a room token: a signed-out
+    // visitor's multiplayer arrives after the site has already said "offline".
+    if (next.offline && !(next.roomToken && !bootstrap.roomToken)) return;
   }
   bootstrap = next;
   window.__TESANA__ = { ...(window.__TESANA__ || {}), ...next };
@@ -407,6 +415,21 @@ function deviceId() {
   return id;
 }
 
+/**
+ * The store-native purchase surface a desktop prelude publishes, or null.
+ *
+ * A desktop, Steam or App Store build has no page above it and no Stripe — the
+ * store's own purchase must run instead, and only the native side can open it.
+ * `tesana-desktop.js` publishes `TesanaDesktop.storePurchase` on exactly those
+ * builds and nothing else, so its presence is the whole signal. Reaching for it
+ * on a plain web page finds `undefined` and changes nothing.
+ */
+function storeBilling() {
+  const desktop = typeof window !== "undefined" ? window.TesanaDesktop : null;
+  if (!desktop || typeof desktop.storePurchase !== "function") return null;
+  return desktop;
+}
+
 /** How long the host has to answer a sign-in before we give up. */
 const SIGN_IN_TIMEOUT_MS = 120000;
 
@@ -518,6 +541,11 @@ function buildConfig(merged) {
     // it still has to play — the shop stays dark and saves stay local, which
     // is the same shape as `offline`, only without a host to have said so.
     offline: Boolean(merged.offline) || !endpoint || !gameId,
+    // A signed-out visitor stays offline for saves and the shop, but the host
+    // may still hand them a token that only opens rooms, so they can play
+    // together on the game's own address. Used by `multiplayer.*` alone.
+    roomEndpoint: merged.roomEndpoint || "",
+    roomToken: merged.roomToken || "",
     player: merged.player || null,
     // The host tells the frame which public address this game answers on, so
     // a game can show and copy its own link without asking the player to
@@ -542,7 +570,7 @@ function defaultEndpoint() {
 
 class TesanaClient {
   /**
-   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
+   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, roomEndpoint?: string, roomToken?: string, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
    */
   constructor(opts) {
     this.endpoint = opts.endpoint;
@@ -577,6 +605,8 @@ class TesanaClient {
     // doomed request on every save is noise, not a save.
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(opts.offline);
+    this.roomEndpoint = String(opts.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = opts.roomToken || "";
     this._player = opts.player || null;
     const reconnect = opts.multiplayerReconnect || {};
     this._mp = {
@@ -704,9 +734,9 @@ class TesanaClient {
       submit: (board, score) =>
         this.request("POST", "/v1/scores", { board: String(board || ""), score: Number(score) }),
       // One board's standings, best first. `{ board, order, entries }`, where
-      // an entry is `{ rank, score, displayName, isGuest, you? }`. Guest runs
-      // are never listed — a ranking of identities that vanish with a tab is
-      // not a ranking.
+      // an entry is `{ rank, score, displayName, isGuest, you? }`. A guest the
+      // site vouches for is listed under its placeholder name; one the game
+      // minted for itself is not.
       top: (board, opts) =>
         read(
           `/v1/scores/${enc(board)}?gameId=${enc(this.gameId)}${
@@ -806,22 +836,22 @@ class TesanaClient {
       // screen. An empty lobby is the honest answer for a game that cannot
       // reach the room service, and it is what the game can render.
       list: () =>
-        this._mpEnabled && !this.offline
-          ? this.request("GET", "/v1/mp/rooms")
+        this._mpEnabled && (!this.offline || this._roomsOnly())
+          ? this._mpRequest("GET", "/v1/mp/rooms")
               .then((r) => r.rooms)
               .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/rooms", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/rooms", opts || {}))
           : this._mpRefuse(),
       join: (roomId) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
+          ? this._mpEnter(this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
           : this._mpRefuse(),
       quickJoin: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/quick-join", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/quick-join", opts || {}))
           : this._mpRefuse(),
       send: (data) => this._mpSend(data),
       on: (fn) => this._mpOn(fn),
@@ -886,6 +916,12 @@ class TesanaClient {
    * @param {{ clientRequestId?: string }} [opts]
    */
   async _topUp(packId, opts = {}) {
+    // A desktop/Steam build buys through its store, not through a Tesana page.
+    // `hasHost()` is false there (no parent frame) and Stripe is the wrong rail,
+    // so store billing is checked first — its presence is what distinguishes a
+    // storefront build from a page opened straight from the play CDN.
+    const desktop = storeBilling();
+    if (desktop) return this._topUpViaStore(desktop, packId);
     if (hasHost()) {
       // The host owns checkout: it opens Stripe in a window of its own and
       // tells us how it went. We only ask. The message names are the host's,
@@ -918,6 +954,67 @@ class TesanaClient {
     return result;
   }
 
+  /**
+   * Buy a coin pack through the store this build ships on.
+   *
+   * Two halves, in this order for a reason: the store takes the money, and only
+   * then does the play service turn the store's own transaction id into coins.
+   * The id is the store's, not ours — it is the one thing a client cannot
+   * invent twice, so it is what makes the credit idempotent when the purchase
+   * is replayed after a crash. Reporting before a successful purchase would
+   * credit coins for a purchase that never happened.
+   *
+   * The result is shaped like the web top-up: a purchase returns the new
+   * balance, and a decline is `{ ok: false, code: "cancelled" }` rather than an
+   * exception, because a player closing the store sheet is a normal answer.
+   *
+   * @param {any} desktop  `window.TesanaDesktop` with `storePurchase`
+   * @param {string} packId
+   */
+  async _topUpViaStore(desktop, packId) {
+    // Sign in *before* the store sheet, never after.
+    //
+    // Coins are account-scoped, so a player with no account has nothing to hold
+    // them: `redeem` refuses an unlinked player, and a guest is exactly that.
+    // On the web rail the refusal arrives harmlessly first, because the host
+    // runs checkout server-side and no money has moved yet. Here the store
+    // charges on this side of the wire, so a refusal discovered at redemption
+    // is a player who was billed and got nothing — the one outcome worth
+    // blocking a sale over. A launcher that cannot sign anyone in therefore
+    // refuses the sale rather than taking payment it cannot honour.
+    const canBuy = () => !this.offline && !this._isGuestSession();
+    if (!canBuy()) {
+      if (typeof desktop.signIn !== "function") {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+      const answer = await this._signInViaNative(canBuy);
+      if (!answer || answer.signedIn !== true) {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+    }
+    const purchase = await desktop.storePurchase({ packId });
+    if (!purchase || purchase.ok !== true) {
+      return {
+        ok: false,
+        purchased: false,
+        code: (purchase && purchase.code) || "cancelled",
+      };
+    }
+    // A store that charged but reported no id cannot be credited — there would
+    // be no way to tell a replay from a new purchase. Surface it as a failure
+    // rather than granting an untraceable lot.
+    if (!purchase.transactionId) {
+      const err = new Error("The store did not return a transaction id.");
+      err.code = "no_transaction_id";
+      throw err;
+    }
+    return this.request("POST", "/v1/economy/redeem", {
+      rail: this.rail,
+      packId,
+      transactionId: purchase.transactionId,
+    });
+  }
+
   _mpRefuse() {
     const err = new Error("Multiplayer is not available for this game yet");
     err.code = "multiplayer_disabled";
@@ -1116,7 +1213,7 @@ class TesanaClient {
     try {
       if (!roomId) return { ok: true, room: null };
       try {
-        return await this.request("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
+        return await this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
       } catch {
         return { ok: true, room: null };
       }
@@ -1130,14 +1227,28 @@ class TesanaClient {
    * @param {string} path
    * @param {object} [body]
    */
-  async request(method, path, body) {
+  request(method, path, body) {
+    return this._send(this._baseFor(), this._authFor(), method, path, body);
+  }
+
+  /** Whether multiplayer rides a rooms-only token while everything else is offline. */
+  _roomsOnly() {
+    return Boolean(this.offline && this.roomEndpoint && this.roomToken);
+  }
+
+  _mpRequest(method, path, body) {
+    return this._roomsOnly()
+      ? this._send(this.roomEndpoint, this.roomToken, method, path, body)
+      : this.request(method, path, body);
+  }
+
+  async _send(base, authToken, method, path, body) {
     const headers = { "content-type": "application/json" };
-    const authToken = this._authFor();
     if (authToken) headers.authorization = `Bearer ${authToken}`;
     if (this.deviceId) headers["x-tesana-device"] = this.deviceId;
     let res;
     try {
-      res = await fetch(`${this._baseFor()}${path}`, {
+      res = await fetch(`${base}${path}`, {
         method,
         headers,
         body: body == null || method === "GET" ? undefined : JSON.stringify(body),
@@ -1181,6 +1292,8 @@ class TesanaClient {
     }
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(config.offline) || !this.endpoint || !this.gameId;
+    this.roomEndpoint = String(config.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = config.roomToken || "";
     if (config.player) this._player = config.player;
     if (config.vanityAddress !== undefined) {
       this._vanityAddress = config.vanityAddress ? String(config.vanityAddress) : null;
@@ -1436,6 +1549,13 @@ class TesanaClient {
     if (!this.canSaveToCloud) return local === undefined ? null : local;
     try {
       const data = await this.request("GET", `/v1/db/${enc(key)}`);
+      if ((data.value === undefined || data.value === null) && local != null && this._isGuestSession()) {
+        // A guest's first cloud session, after playing with saves kept only in
+        // this browser: their progress is theirs, so it goes up rather than
+        // being overwritten by the empty cloud answer.
+        this.request("PUT", `/v1/db/${enc(key)}`, { value: local }).catch(() => {});
+        return local;
+      }
       const db = readCache().db || {};
       db[key] = data.value;
       writeCache({ db });
@@ -1468,7 +1588,15 @@ class TesanaClient {
    * inventory() and buy() start working without the game reloading.
    */
   _signIn() {
-    if (!this.offline) return Promise.resolve({ signedIn: true });
+    const signedIn = () => !this.offline && !this._isGuestSession();
+    if (signedIn()) return Promise.resolve({ signedIn: true });
+    // A desktop/Steam build has no host to draw an account UI. Its launcher is
+    // the sign-in surface, and only it can vouch for the player to the host
+    // with the internal secret that account linking requires — so this asks the
+    // native side to run sign-in and then waits for the bootstrap that carries
+    // the linked token, exactly as the web path waits for the host's answer.
+    const desktop = storeBilling();
+    if (desktop && typeof desktop.signIn === "function") return this._signInViaNative(signedIn);
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1483,7 +1611,7 @@ class TesanaClient {
       // second time for still being offline — the exact dead end this whole
       // exchange exists to remove.
       const waitForToken = (attempt) => {
-        if (!this.offline) return finish({ signedIn: true });
+        if (signedIn()) return finish({ signedIn: true });
         if ((attempt || 0) >= 60) return finish({ signedIn: true });
         setTimeout(() => waitForToken((attempt || 0) + 1), 50);
       };
@@ -1496,7 +1624,51 @@ class TesanaClient {
       window.addEventListener("message", onMessage);
       // Declining is an answer too. Report what is actually true rather than
       // leaving the game's promise pending forever.
-      expiry = setTimeout(() => finish({ signedIn: !this.offline }), SIGN_IN_TIMEOUT_MS);
+      expiry = setTimeout(() => finish({ signedIn: signedIn() }), SIGN_IN_TIMEOUT_MS);
+    });
+  }
+
+  /** A guest the site vouches for: saves in the cloud, but has no account to spend from. */
+  _isGuestSession() {
+    if (!this._player) return false;
+    // Two signals, because the answer arrives from two places. A host posts
+    // `isGuest: true` in its bootstrap — the web's word for it — while an
+    // identity this client resolves itself (`/v1/player/me`) reports `isLinked`
+    // and no `isGuest` at all. Reading only the first would let a native
+    // session, whose whole point is an account-free identity, pass as a
+    // signed-in player; the store path gates a sale on exactly this, so that
+    // mistake is a card charged for coins we then refuse to grant.
+    return this._player.isGuest === true || this._player.isLinked === false;
+  }
+
+  /**
+   * Ask the native launcher to sign the player in, then wait for the token.
+   *
+   * The launcher is the only party that can reach the host route with the
+   * internal secret that account linking needs, so this hands it the request
+   * and then watches `signedIn()` — which flips the moment the linked bootstrap
+   * replaces the guest one. Polling rather than listening is deliberate: the
+   * bootstrap arrives through the SDK's own upgrade path (`onBootstrapUpgrade`
+   * re-points the client and re-runs identity), and there is no second channel
+   * to subscribe to here.
+   */
+  _signInViaNative(signedIn) {
+    return window.TesanaDesktop.signIn({ gameId: this.gameId }).then((answer) => {
+      if (!answer || answer.ok !== true || answer.signedIn !== true) return { signedIn: false };
+      return new Promise((resolve) => {
+        const waitForToken = (attempt) => {
+          if (signedIn()) return resolve({ signedIn: true });
+          // Report what is actually true when the wait runs out. The web path
+          // predates this and answers optimistically; its launcher-started
+          // sign-in gets a fresh page instead, so it never observes the lie.
+          // Here the caller is a store purchase deciding whether money may
+          // move, and "probably signed in" is not a state a charge may proceed
+          // on — a token that never arrived means no account to hold the coins.
+          if ((attempt || 0) >= 60) return resolve({ signedIn: signedIn() });
+          setTimeout(() => waitForToken((attempt || 0) + 1), 50);
+        };
+        waitForToken(0);
+      });
     });
   }
 

package/dist/tesana.iife.js

@@ -1,4 +1,4 @@
-/* Tesana play-time SDK v1.0.1 */
+/* Tesana play-time SDK v1.0.3 */
 (function (root) {
 /**
  * Tesana play-time SDK. Vanilla JS, no npm in games.
@@ -39,7 +39,7 @@
 // 1.0.0 ships six services together: saves, shop, leaderboards, achievements,
 // a vanity address (`tesana.vanity`) and in-game ads (`tesana.ads`). These are
 // the first release, so there is no earlier number to stay compatible with.
-const VERSION = "1.0.1";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -147,12 +147,20 @@ function warnOnce(key, message) {
   }
 }
 
+function isGuestBootstrap(data) {
+  return Boolean(data && data.player && data.player.isGuest);
+}
+
 /** Fold a host's answer into the live config, upgrading a provisional one. */
 function applyBootstrap(data) {
   const next = data && typeof data === "object" ? data : {};
   if (bootstrap) {
-    if (!bootstrap.offline) return; // a real host has already answered
-    if (next.offline) return; // still nobody; nothing has changed
+    // A real host has already answered — unless that answer was a guest and
+    // this one is the account they just signed in to.
+    if (!bootstrap.offline && !(isGuestBootstrap(bootstrap) && !next.offline && !isGuestBootstrap(next))) return;
+    // Still offline, unless it now carries a room token: a signed-out
+    // visitor's multiplayer arrives after the site has already said "offline".
+    if (next.offline && !(next.roomToken && !bootstrap.roomToken)) return;
   }
   bootstrap = next;
   window.__TESANA__ = { ...(window.__TESANA__ || {}), ...next };
@@ -409,6 +417,21 @@ function deviceId() {
   return id;
 }
 
+/**
+ * The store-native purchase surface a desktop prelude publishes, or null.
+ *
+ * A desktop, Steam or App Store build has no page above it and no Stripe — the
+ * store's own purchase must run instead, and only the native side can open it.
+ * `tesana-desktop.js` publishes `TesanaDesktop.storePurchase` on exactly those
+ * builds and nothing else, so its presence is the whole signal. Reaching for it
+ * on a plain web page finds `undefined` and changes nothing.
+ */
+function storeBilling() {
+  const desktop = typeof window !== "undefined" ? window.TesanaDesktop : null;
+  if (!desktop || typeof desktop.storePurchase !== "function") return null;
+  return desktop;
+}
+
 /** How long the host has to answer a sign-in before we give up. */
 const SIGN_IN_TIMEOUT_MS = 120000;
 
@@ -520,6 +543,11 @@ function buildConfig(merged) {
     // it still has to play — the shop stays dark and saves stay local, which
     // is the same shape as `offline`, only without a host to have said so.
     offline: Boolean(merged.offline) || !endpoint || !gameId,
+    // A signed-out visitor stays offline for saves and the shop, but the host
+    // may still hand them a token that only opens rooms, so they can play
+    // together on the game's own address. Used by `multiplayer.*` alone.
+    roomEndpoint: merged.roomEndpoint || "",
+    roomToken: merged.roomToken || "",
     player: merged.player || null,
     // The host tells the frame which public address this game answers on, so
     // a game can show and copy its own link without asking the player to
@@ -544,7 +572,7 @@ function defaultEndpoint() {
 
 class TesanaClient {
   /**
-   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
+   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, roomEndpoint?: string, roomToken?: string, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
    */
   constructor(opts) {
     this.endpoint = opts.endpoint;
@@ -579,6 +607,8 @@ class TesanaClient {
     // doomed request on every save is noise, not a save.
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(opts.offline);
+    this.roomEndpoint = String(opts.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = opts.roomToken || "";
     this._player = opts.player || null;
     const reconnect = opts.multiplayerReconnect || {};
     this._mp = {
@@ -706,9 +736,9 @@ class TesanaClient {
       submit: (board, score) =>
         this.request("POST", "/v1/scores", { board: String(board || ""), score: Number(score) }),
       // One board's standings, best first. `{ board, order, entries }`, where
-      // an entry is `{ rank, score, displayName, isGuest, you? }`. Guest runs
-      // are never listed — a ranking of identities that vanish with a tab is
-      // not a ranking.
+      // an entry is `{ rank, score, displayName, isGuest, you? }`. A guest the
+      // site vouches for is listed under its placeholder name; one the game
+      // minted for itself is not.
       top: (board, opts) =>
         read(
           `/v1/scores/${enc(board)}?gameId=${enc(this.gameId)}${
@@ -808,22 +838,22 @@ class TesanaClient {
       // screen. An empty lobby is the honest answer for a game that cannot
       // reach the room service, and it is what the game can render.
       list: () =>
-        this._mpEnabled && !this.offline
-          ? this.request("GET", "/v1/mp/rooms")
+        this._mpEnabled && (!this.offline || this._roomsOnly())
+          ? this._mpRequest("GET", "/v1/mp/rooms")
               .then((r) => r.rooms)
               .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/rooms", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/rooms", opts || {}))
           : this._mpRefuse(),
       join: (roomId) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
+          ? this._mpEnter(this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
           : this._mpRefuse(),
       quickJoin: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/quick-join", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/quick-join", opts || {}))
           : this._mpRefuse(),
       send: (data) => this._mpSend(data),
       on: (fn) => this._mpOn(fn),
@@ -888,6 +918,12 @@ class TesanaClient {
    * @param {{ clientRequestId?: string }} [opts]
    */
   async _topUp(packId, opts = {}) {
+    // A desktop/Steam build buys through its store, not through a Tesana page.
+    // `hasHost()` is false there (no parent frame) and Stripe is the wrong rail,
+    // so store billing is checked first — its presence is what distinguishes a
+    // storefront build from a page opened straight from the play CDN.
+    const desktop = storeBilling();
+    if (desktop) return this._topUpViaStore(desktop, packId);
     if (hasHost()) {
       // The host owns checkout: it opens Stripe in a window of its own and
       // tells us how it went. We only ask. The message names are the host's,
@@ -920,6 +956,67 @@ class TesanaClient {
     return result;
   }
 
+  /**
+   * Buy a coin pack through the store this build ships on.
+   *
+   * Two halves, in this order for a reason: the store takes the money, and only
+   * then does the play service turn the store's own transaction id into coins.
+   * The id is the store's, not ours — it is the one thing a client cannot
+   * invent twice, so it is what makes the credit idempotent when the purchase
+   * is replayed after a crash. Reporting before a successful purchase would
+   * credit coins for a purchase that never happened.
+   *
+   * The result is shaped like the web top-up: a purchase returns the new
+   * balance, and a decline is `{ ok: false, code: "cancelled" }` rather than an
+   * exception, because a player closing the store sheet is a normal answer.
+   *
+   * @param {any} desktop  `window.TesanaDesktop` with `storePurchase`
+   * @param {string} packId
+   */
+  async _topUpViaStore(desktop, packId) {
+    // Sign in *before* the store sheet, never after.
+    //
+    // Coins are account-scoped, so a player with no account has nothing to hold
+    // them: `redeem` refuses an unlinked player, and a guest is exactly that.
+    // On the web rail the refusal arrives harmlessly first, because the host
+    // runs checkout server-side and no money has moved yet. Here the store
+    // charges on this side of the wire, so a refusal discovered at redemption
+    // is a player who was billed and got nothing — the one outcome worth
+    // blocking a sale over. A launcher that cannot sign anyone in therefore
+    // refuses the sale rather than taking payment it cannot honour.
+    const canBuy = () => !this.offline && !this._isGuestSession();
+    if (!canBuy()) {
+      if (typeof desktop.signIn !== "function") {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+      const answer = await this._signInViaNative(canBuy);
+      if (!answer || answer.signedIn !== true) {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+    }
+    const purchase = await desktop.storePurchase({ packId });
+    if (!purchase || purchase.ok !== true) {
+      return {
+        ok: false,
+        purchased: false,
+        code: (purchase && purchase.code) || "cancelled",
+      };
+    }
+    // A store that charged but reported no id cannot be credited — there would
+    // be no way to tell a replay from a new purchase. Surface it as a failure
+    // rather than granting an untraceable lot.
+    if (!purchase.transactionId) {
+      const err = new Error("The store did not return a transaction id.");
+      err.code = "no_transaction_id";
+      throw err;
+    }
+    return this.request("POST", "/v1/economy/redeem", {
+      rail: this.rail,
+      packId,
+      transactionId: purchase.transactionId,
+    });
+  }
+
   _mpRefuse() {
     const err = new Error("Multiplayer is not available for this game yet");
     err.code = "multiplayer_disabled";
@@ -1118,7 +1215,7 @@ class TesanaClient {
     try {
       if (!roomId) return { ok: true, room: null };
       try {
-        return await this.request("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
+        return await this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
       } catch {
         return { ok: true, room: null };
       }
@@ -1132,14 +1229,28 @@ class TesanaClient {
    * @param {string} path
    * @param {object} [body]
    */
-  async request(method, path, body) {
+  request(method, path, body) {
+    return this._send(this._baseFor(), this._authFor(), method, path, body);
+  }
+
+  /** Whether multiplayer rides a rooms-only token while everything else is offline. */
+  _roomsOnly() {
+    return Boolean(this.offline && this.roomEndpoint && this.roomToken);
+  }
+
+  _mpRequest(method, path, body) {
+    return this._roomsOnly()
+      ? this._send(this.roomEndpoint, this.roomToken, method, path, body)
+      : this.request(method, path, body);
+  }
+
+  async _send(base, authToken, method, path, body) {
     const headers = { "content-type": "application/json" };
-    const authToken = this._authFor();
     if (authToken) headers.authorization = `Bearer ${authToken}`;
     if (this.deviceId) headers["x-tesana-device"] = this.deviceId;
     let res;
     try {
-      res = await fetch(`${this._baseFor()}${path}`, {
+      res = await fetch(`${base}${path}`, {
         method,
         headers,
         body: body == null || method === "GET" ? undefined : JSON.stringify(body),
@@ -1183,6 +1294,8 @@ class TesanaClient {
     }
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(config.offline) || !this.endpoint || !this.gameId;
+    this.roomEndpoint = String(config.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = config.roomToken || "";
     if (config.player) this._player = config.player;
     if (config.vanityAddress !== undefined) {
       this._vanityAddress = config.vanityAddress ? String(config.vanityAddress) : null;
@@ -1438,6 +1551,13 @@ class TesanaClient {
     if (!this.canSaveToCloud) return local === undefined ? null : local;
     try {
       const data = await this.request("GET", `/v1/db/${enc(key)}`);
+      if ((data.value === undefined || data.value === null) && local != null && this._isGuestSession()) {
+        // A guest's first cloud session, after playing with saves kept only in
+        // this browser: their progress is theirs, so it goes up rather than
+        // being overwritten by the empty cloud answer.
+        this.request("PUT", `/v1/db/${enc(key)}`, { value: local }).catch(() => {});
+        return local;
+      }
       const db = readCache().db || {};
       db[key] = data.value;
       writeCache({ db });
@@ -1470,7 +1590,15 @@ class TesanaClient {
    * inventory() and buy() start working without the game reloading.
    */
   _signIn() {
-    if (!this.offline) return Promise.resolve({ signedIn: true });
+    const signedIn = () => !this.offline && !this._isGuestSession();
+    if (signedIn()) return Promise.resolve({ signedIn: true });
+    // A desktop/Steam build has no host to draw an account UI. Its launcher is
+    // the sign-in surface, and only it can vouch for the player to the host
+    // with the internal secret that account linking requires — so this asks the
+    // native side to run sign-in and then waits for the bootstrap that carries
+    // the linked token, exactly as the web path waits for the host's answer.
+    const desktop = storeBilling();
+    if (desktop && typeof desktop.signIn === "function") return this._signInViaNative(signedIn);
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1485,7 +1613,7 @@ class TesanaClient {
       // second time for still being offline — the exact dead end this whole
       // exchange exists to remove.
       const waitForToken = (attempt) => {
-        if (!this.offline) return finish({ signedIn: true });
+        if (signedIn()) return finish({ signedIn: true });
         if ((attempt || 0) >= 60) return finish({ signedIn: true });
         setTimeout(() => waitForToken((attempt || 0) + 1), 50);
       };
@@ -1498,7 +1626,51 @@ class TesanaClient {
       window.addEventListener("message", onMessage);
       // Declining is an answer too. Report what is actually true rather than
       // leaving the game's promise pending forever.
-      expiry = setTimeout(() => finish({ signedIn: !this.offline }), SIGN_IN_TIMEOUT_MS);
+      expiry = setTimeout(() => finish({ signedIn: signedIn() }), SIGN_IN_TIMEOUT_MS);
+    });
+  }
+
+  /** A guest the site vouches for: saves in the cloud, but has no account to spend from. */
+  _isGuestSession() {
+    if (!this._player) return false;
+    // Two signals, because the answer arrives from two places. A host posts
+    // `isGuest: true` in its bootstrap — the web's word for it — while an
+    // identity this client resolves itself (`/v1/player/me`) reports `isLinked`
+    // and no `isGuest` at all. Reading only the first would let a native
+    // session, whose whole point is an account-free identity, pass as a
+    // signed-in player; the store path gates a sale on exactly this, so that
+    // mistake is a card charged for coins we then refuse to grant.
+    return this._player.isGuest === true || this._player.isLinked === false;
+  }
+
+  /**
+   * Ask the native launcher to sign the player in, then wait for the token.
+   *
+   * The launcher is the only party that can reach the host route with the
+   * internal secret that account linking needs, so this hands it the request
+   * and then watches `signedIn()` — which flips the moment the linked bootstrap
+   * replaces the guest one. Polling rather than listening is deliberate: the
+   * bootstrap arrives through the SDK's own upgrade path (`onBootstrapUpgrade`
+   * re-points the client and re-runs identity), and there is no second channel
+   * to subscribe to here.
+   */
+  _signInViaNative(signedIn) {
+    return window.TesanaDesktop.signIn({ gameId: this.gameId }).then((answer) => {
+      if (!answer || answer.ok !== true || answer.signedIn !== true) return { signedIn: false };
+      return new Promise((resolve) => {
+        const waitForToken = (attempt) => {
+          if (signedIn()) return resolve({ signedIn: true });
+          // Report what is actually true when the wait runs out. The web path
+          // predates this and answers optimistically; its launcher-started
+          // sign-in gets a fresh page instead, so it never observes the lie.
+          // Here the caller is a store purchase deciding whether money may
+          // move, and "probably signed in" is not a state a charge may proceed
+          // on — a token that never arrived means no account to hold the coins.
+          if ((attempt || 0) >= 60) return resolve({ signedIn: signedIn() });
+          setTimeout(() => waitForToken((attempt || 0) + 1), 50);
+        };
+        waitForToken(0);
+      });
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tesana/sdk",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Tesana play-time SDK — players, cloud saves, leaderboards, achievements and the in-game coin shop for a web game.",
   "type": "module",
   "license": "UNLICENSED",

package/src/tesana.js

@@ -37,7 +37,7 @@
 // 1.0.0 ships six services together: saves, shop, leaderboards, achievements,
 // a vanity address (`tesana.vanity`) and in-game ads (`tesana.ads`). These are
 // the first release, so there is no earlier number to stay compatible with.
-const VERSION = "1.0.1";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -145,12 +145,20 @@ function warnOnce(key, message) {
   }
 }
 
+function isGuestBootstrap(data) {
+  return Boolean(data && data.player && data.player.isGuest);
+}
+
 /** Fold a host's answer into the live config, upgrading a provisional one. */
 function applyBootstrap(data) {
   const next = data && typeof data === "object" ? data : {};
   if (bootstrap) {
-    if (!bootstrap.offline) return; // a real host has already answered
-    if (next.offline) return; // still nobody; nothing has changed
+    // A real host has already answered — unless that answer was a guest and
+    // this one is the account they just signed in to.
+    if (!bootstrap.offline && !(isGuestBootstrap(bootstrap) && !next.offline && !isGuestBootstrap(next))) return;
+    // Still offline, unless it now carries a room token: a signed-out
+    // visitor's multiplayer arrives after the site has already said "offline".
+    if (next.offline && !(next.roomToken && !bootstrap.roomToken)) return;
   }
   bootstrap = next;
   window.__TESANA__ = { ...(window.__TESANA__ || {}), ...next };
@@ -407,6 +415,21 @@ function deviceId() {
   return id;
 }
 
+/**
+ * The store-native purchase surface a desktop prelude publishes, or null.
+ *
+ * A desktop, Steam or App Store build has no page above it and no Stripe — the
+ * store's own purchase must run instead, and only the native side can open it.
+ * `tesana-desktop.js` publishes `TesanaDesktop.storePurchase` on exactly those
+ * builds and nothing else, so its presence is the whole signal. Reaching for it
+ * on a plain web page finds `undefined` and changes nothing.
+ */
+function storeBilling() {
+  const desktop = typeof window !== "undefined" ? window.TesanaDesktop : null;
+  if (!desktop || typeof desktop.storePurchase !== "function") return null;
+  return desktop;
+}
+
 /** How long the host has to answer a sign-in before we give up. */
 const SIGN_IN_TIMEOUT_MS = 120000;
 
@@ -518,6 +541,11 @@ function buildConfig(merged) {
     // it still has to play — the shop stays dark and saves stay local, which
     // is the same shape as `offline`, only without a host to have said so.
     offline: Boolean(merged.offline) || !endpoint || !gameId,
+    // A signed-out visitor stays offline for saves and the shop, but the host
+    // may still hand them a token that only opens rooms, so they can play
+    // together on the game's own address. Used by `multiplayer.*` alone.
+    roomEndpoint: merged.roomEndpoint || "",
+    roomToken: merged.roomToken || "",
     player: merged.player || null,
     // The host tells the frame which public address this game answers on, so
     // a game can show and copy its own link without asking the player to
@@ -542,7 +570,7 @@ function defaultEndpoint() {
 
 class TesanaClient {
   /**
-   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
+   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, roomEndpoint?: string, roomToken?: string, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
    */
   constructor(opts) {
     this.endpoint = opts.endpoint;
@@ -577,6 +605,8 @@ class TesanaClient {
     // doomed request on every save is noise, not a save.
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(opts.offline);
+    this.roomEndpoint = String(opts.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = opts.roomToken || "";
     this._player = opts.player || null;
     const reconnect = opts.multiplayerReconnect || {};
     this._mp = {
@@ -704,9 +734,9 @@ class TesanaClient {
       submit: (board, score) =>
         this.request("POST", "/v1/scores", { board: String(board || ""), score: Number(score) }),
       // One board's standings, best first. `{ board, order, entries }`, where
-      // an entry is `{ rank, score, displayName, isGuest, you? }`. Guest runs
-      // are never listed — a ranking of identities that vanish with a tab is
-      // not a ranking.
+      // an entry is `{ rank, score, displayName, isGuest, you? }`. A guest the
+      // site vouches for is listed under its placeholder name; one the game
+      // minted for itself is not.
       top: (board, opts) =>
         read(
           `/v1/scores/${enc(board)}?gameId=${enc(this.gameId)}${
@@ -806,22 +836,22 @@ class TesanaClient {
       // screen. An empty lobby is the honest answer for a game that cannot
       // reach the room service, and it is what the game can render.
       list: () =>
-        this._mpEnabled && !this.offline
-          ? this.request("GET", "/v1/mp/rooms")
+        this._mpEnabled && (!this.offline || this._roomsOnly())
+          ? this._mpRequest("GET", "/v1/mp/rooms")
               .then((r) => r.rooms)
               .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/rooms", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/rooms", opts || {}))
           : this._mpRefuse(),
       join: (roomId) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
+          ? this._mpEnter(this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
           : this._mpRefuse(),
       quickJoin: (opts) =>
         this._mpEnabled
-          ? this._mpEnter(this.request("POST", "/v1/mp/quick-join", opts || {}))
+          ? this._mpEnter(this._mpRequest("POST", "/v1/mp/quick-join", opts || {}))
           : this._mpRefuse(),
       send: (data) => this._mpSend(data),
       on: (fn) => this._mpOn(fn),
@@ -886,6 +916,12 @@ class TesanaClient {
    * @param {{ clientRequestId?: string }} [opts]
    */
   async _topUp(packId, opts = {}) {
+    // A desktop/Steam build buys through its store, not through a Tesana page.
+    // `hasHost()` is false there (no parent frame) and Stripe is the wrong rail,
+    // so store billing is checked first — its presence is what distinguishes a
+    // storefront build from a page opened straight from the play CDN.
+    const desktop = storeBilling();
+    if (desktop) return this._topUpViaStore(desktop, packId);
     if (hasHost()) {
       // The host owns checkout: it opens Stripe in a window of its own and
       // tells us how it went. We only ask. The message names are the host's,
@@ -918,6 +954,67 @@ class TesanaClient {
     return result;
   }
 
+  /**
+   * Buy a coin pack through the store this build ships on.
+   *
+   * Two halves, in this order for a reason: the store takes the money, and only
+   * then does the play service turn the store's own transaction id into coins.
+   * The id is the store's, not ours — it is the one thing a client cannot
+   * invent twice, so it is what makes the credit idempotent when the purchase
+   * is replayed after a crash. Reporting before a successful purchase would
+   * credit coins for a purchase that never happened.
+   *
+   * The result is shaped like the web top-up: a purchase returns the new
+   * balance, and a decline is `{ ok: false, code: "cancelled" }` rather than an
+   * exception, because a player closing the store sheet is a normal answer.
+   *
+   * @param {any} desktop  `window.TesanaDesktop` with `storePurchase`
+   * @param {string} packId
+   */
+  async _topUpViaStore(desktop, packId) {
+    // Sign in *before* the store sheet, never after.
+    //
+    // Coins are account-scoped, so a player with no account has nothing to hold
+    // them: `redeem` refuses an unlinked player, and a guest is exactly that.
+    // On the web rail the refusal arrives harmlessly first, because the host
+    // runs checkout server-side and no money has moved yet. Here the store
+    // charges on this side of the wire, so a refusal discovered at redemption
+    // is a player who was billed and got nothing — the one outcome worth
+    // blocking a sale over. A launcher that cannot sign anyone in therefore
+    // refuses the sale rather than taking payment it cannot honour.
+    const canBuy = () => !this.offline && !this._isGuestSession();
+    if (!canBuy()) {
+      if (typeof desktop.signIn !== "function") {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+      const answer = await this._signInViaNative(canBuy);
+      if (!answer || answer.signedIn !== true) {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+    }
+    const purchase = await desktop.storePurchase({ packId });
+    if (!purchase || purchase.ok !== true) {
+      return {
+        ok: false,
+        purchased: false,
+        code: (purchase && purchase.code) || "cancelled",
+      };
+    }
+    // A store that charged but reported no id cannot be credited — there would
+    // be no way to tell a replay from a new purchase. Surface it as a failure
+    // rather than granting an untraceable lot.
+    if (!purchase.transactionId) {
+      const err = new Error("The store did not return a transaction id.");
+      err.code = "no_transaction_id";
+      throw err;
+    }
+    return this.request("POST", "/v1/economy/redeem", {
+      rail: this.rail,
+      packId,
+      transactionId: purchase.transactionId,
+    });
+  }
+
   _mpRefuse() {
     const err = new Error("Multiplayer is not available for this game yet");
     err.code = "multiplayer_disabled";
@@ -1116,7 +1213,7 @@ class TesanaClient {
     try {
       if (!roomId) return { ok: true, room: null };
       try {
-        return await this.request("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
+        return await this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/leave`);
       } catch {
         return { ok: true, room: null };
       }
@@ -1130,14 +1227,28 @@ class TesanaClient {
    * @param {string} path
    * @param {object} [body]
    */
-  async request(method, path, body) {
+  request(method, path, body) {
+    return this._send(this._baseFor(), this._authFor(), method, path, body);
+  }
+
+  /** Whether multiplayer rides a rooms-only token while everything else is offline. */
+  _roomsOnly() {
+    return Boolean(this.offline && this.roomEndpoint && this.roomToken);
+  }
+
+  _mpRequest(method, path, body) {
+    return this._roomsOnly()
+      ? this._send(this.roomEndpoint, this.roomToken, method, path, body)
+      : this.request(method, path, body);
+  }
+
+  async _send(base, authToken, method, path, body) {
     const headers = { "content-type": "application/json" };
-    const authToken = this._authFor();
     if (authToken) headers.authorization = `Bearer ${authToken}`;
     if (this.deviceId) headers["x-tesana-device"] = this.deviceId;
     let res;
     try {
-      res = await fetch(`${this._baseFor()}${path}`, {
+      res = await fetch(`${base}${path}`, {
         method,
         headers,
         body: body == null || method === "GET" ? undefined : JSON.stringify(body),
@@ -1181,6 +1292,8 @@ class TesanaClient {
     }
     this.canSaveToCloud = Boolean(this.saveEndpoint && this.saveToken);
     this.offline = Boolean(config.offline) || !this.endpoint || !this.gameId;
+    this.roomEndpoint = String(config.roomEndpoint || "").replace(/\/$/, "");
+    this.roomToken = config.roomToken || "";
     if (config.player) this._player = config.player;
     if (config.vanityAddress !== undefined) {
       this._vanityAddress = config.vanityAddress ? String(config.vanityAddress) : null;
@@ -1436,6 +1549,13 @@ class TesanaClient {
     if (!this.canSaveToCloud) return local === undefined ? null : local;
     try {
       const data = await this.request("GET", `/v1/db/${enc(key)}`);
+      if ((data.value === undefined || data.value === null) && local != null && this._isGuestSession()) {
+        // A guest's first cloud session, after playing with saves kept only in
+        // this browser: their progress is theirs, so it goes up rather than
+        // being overwritten by the empty cloud answer.
+        this.request("PUT", `/v1/db/${enc(key)}`, { value: local }).catch(() => {});
+        return local;
+      }
       const db = readCache().db || {};
       db[key] = data.value;
       writeCache({ db });
@@ -1468,7 +1588,15 @@ class TesanaClient {
    * inventory() and buy() start working without the game reloading.
    */
   _signIn() {
-    if (!this.offline) return Promise.resolve({ signedIn: true });
+    const signedIn = () => !this.offline && !this._isGuestSession();
+    if (signedIn()) return Promise.resolve({ signedIn: true });
+    // A desktop/Steam build has no host to draw an account UI. Its launcher is
+    // the sign-in surface, and only it can vouch for the player to the host
+    // with the internal secret that account linking requires — so this asks the
+    // native side to run sign-in and then waits for the bootstrap that carries
+    // the linked token, exactly as the web path waits for the host's answer.
+    const desktop = storeBilling();
+    if (desktop && typeof desktop.signIn === "function") return this._signInViaNative(signedIn);
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1483,7 +1611,7 @@ class TesanaClient {
       // second time for still being offline — the exact dead end this whole
       // exchange exists to remove.
       const waitForToken = (attempt) => {
-        if (!this.offline) return finish({ signedIn: true });
+        if (signedIn()) return finish({ signedIn: true });
         if ((attempt || 0) >= 60) return finish({ signedIn: true });
         setTimeout(() => waitForToken((attempt || 0) + 1), 50);
       };
@@ -1496,7 +1624,51 @@ class TesanaClient {
       window.addEventListener("message", onMessage);
       // Declining is an answer too. Report what is actually true rather than
       // leaving the game's promise pending forever.
-      expiry = setTimeout(() => finish({ signedIn: !this.offline }), SIGN_IN_TIMEOUT_MS);
+      expiry = setTimeout(() => finish({ signedIn: signedIn() }), SIGN_IN_TIMEOUT_MS);
+    });
+  }
+
+  /** A guest the site vouches for: saves in the cloud, but has no account to spend from. */
+  _isGuestSession() {
+    if (!this._player) return false;
+    // Two signals, because the answer arrives from two places. A host posts
+    // `isGuest: true` in its bootstrap — the web's word for it — while an
+    // identity this client resolves itself (`/v1/player/me`) reports `isLinked`
+    // and no `isGuest` at all. Reading only the first would let a native
+    // session, whose whole point is an account-free identity, pass as a
+    // signed-in player; the store path gates a sale on exactly this, so that
+    // mistake is a card charged for coins we then refuse to grant.
+    return this._player.isGuest === true || this._player.isLinked === false;
+  }
+
+  /**
+   * Ask the native launcher to sign the player in, then wait for the token.
+   *
+   * The launcher is the only party that can reach the host route with the
+   * internal secret that account linking needs, so this hands it the request
+   * and then watches `signedIn()` — which flips the moment the linked bootstrap
+   * replaces the guest one. Polling rather than listening is deliberate: the
+   * bootstrap arrives through the SDK's own upgrade path (`onBootstrapUpgrade`
+   * re-points the client and re-runs identity), and there is no second channel
+   * to subscribe to here.
+   */
+  _signInViaNative(signedIn) {
+    return window.TesanaDesktop.signIn({ gameId: this.gameId }).then((answer) => {
+      if (!answer || answer.ok !== true || answer.signedIn !== true) return { signedIn: false };
+      return new Promise((resolve) => {
+        const waitForToken = (attempt) => {
+          if (signedIn()) return resolve({ signedIn: true });
+          // Report what is actually true when the wait runs out. The web path
+          // predates this and answers optimistically; its launcher-started
+          // sign-in gets a fresh page instead, so it never observes the lie.
+          // Here the caller is a store purchase deciding whether money may
+          // move, and "probably signed in" is not a state a charge may proceed
+          // on — a token that never arrived means no account to hold the coins.
+          if ((attempt || 0) >= 60) return resolve({ signedIn: signedIn() });
+          setTimeout(() => waitForToken((attempt || 0) + 1), 50);
+        };
+        waitForToken(0);
+      });
     });
   }