@tesana/sdk 1.0.0 → 1.0.2

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.0";
+const VERSION = "1.0.2";
 
 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 };
@@ -444,7 +452,28 @@ export async function init(config = {}) {
   startListening();
   const boot = await waitBootstrap();
   const client = new TesanaClient(buildConfig(mergedConfig()));
-  await client.ensureSession();
+  // An unreachable play service must cost a *feature*, never the game.
+  //
+  // This is the client half of a contract the server already keeps: Django's
+  // mint returns None rather than failing a request, precisely so that "the
+  // play service being slow, down, or unconfigured means the SDK keeps saves in
+  // the browser — worse, but the game still runs". Without this catch the
+  // client contradicted that. `ensureSession()` mints an identity over HTTP, so
+  // a failure here rejected `__TESANA_READY__`, and a game doing the documented
+  // `await window.__TESANA_READY__` threw on its first line — turning a service
+  // outage into a broken game for everyone using it.
+  //
+  // Falling back to offline is the correct degradation, not a swallow: every
+  // read already has a local or empty answer (`balance()` reports zero,
+  // `shop.read()` reports a shut shutter, saves read as missing), and a later
+  // bootstrap upgrade still re-runs the identity step through
+  // `onBootstrapUpgrade` below. The player loses cloud features for that
+  // session and keeps their game.
+  try {
+    await client.ensureSession();
+  } catch (err) {
+    client.goOffline(err);
+  }
   window.__TESANA_PLAYER__ = client.player.me();
   // A provisional "offline" answer can upgrade later. Re-point this client in
   // place — the game holds a reference to it — and re-run the identity step,
@@ -497,6 +526,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
@@ -521,7 +555,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;
@@ -556,6 +590,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 = {
@@ -683,9 +719,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)}${
@@ -778,21 +814,29 @@ class TesanaClient {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
       enabled: this._mpEnabled,
+      // `_mpEnabled` alone is not enough. A game with no host has multiplayer
+      // "allowed" and no service to ask, so `list()` used to reject with a
+      // transport error — and a game that draws a lobby on load (which the
+      // skill tells games to do) got an unhandled rejection on its title
+      // 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.request("GET", "/v1/mp/rooms").then((r) => r.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),
@@ -1087,7 +1131,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 };
       }
@@ -1101,14 +1145,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),
@@ -1152,6 +1210,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;
@@ -1168,6 +1228,46 @@ class TesanaClient {
     return this;
   }
 
+  /**
+   * Carry on without the play service.
+   *
+   * The boot path calls this when the identity step fails — an unreachable
+   * endpoint, a 500, a bad secret, a cert the browser will not accept. A game
+   * must not die of it: the server side of this contract already returns no
+   * token and lets the game run, so the client falls back to exactly the state
+   * a game with no endpoint is in.
+   *
+   * Marking the client offline is the honest outcome rather than a silent
+   * swallow. Every read already has an offline answer — `balance()` reports
+   * zero coins and `canSpend: false`, the shop reports a shut shutter, saves
+   * read as absent and write to the local cache — so the game draws its
+   * title screen instead of throwing. A later bootstrap upgrade re-runs the
+   * identity step and flips this back off.
+   *
+   * The token is cleared rather than kept: it is the thing that failed to
+   * authenticate, and half an identity is worse than none — every call would
+   * retry a credential the service just refused.
+   *
+   * @param {unknown} [reason] the failure, kept for diagnostics
+   */
+  goOffline(reason) {
+    this.offline = true;
+    this.token = "";
+    this.saveToken = "";
+    this.canSaveToCloud = false;
+    this._mpEnabled = false;
+    this.multiplayer.enabled = false;
+    // One deduped line rather than a wall: a page whose endpoint is
+    // misconfigured would otherwise log this on every call.
+    warnOnce(
+      "play-session",
+      `[tesana] play service unavailable; running without cloud saves or the shop${
+        reason ? ` (${(reason && reason.message) || reason})` : ""
+      }`,
+    );
+    return this;
+  }
+
   /**
    * Which origin and which credential a path uses.
    *
@@ -1367,6 +1467,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 });
@@ -1399,7 +1506,8 @@ 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 });
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1414,7 +1522,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);
       };
@@ -1427,10 +1535,15 @@ 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() {
+    return Boolean(this._player && this._player.isGuest);
+  }
+
 }
 
 function enc(value) {

package/dist/tesana.iife.js

@@ -1,4 +1,4 @@
-/* Tesana play-time SDK v1.0.0 */
+/* Tesana play-time SDK v1.0.2 */
 (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.0";
+const VERSION = "1.0.2";
 
 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 };
@@ -446,7 +454,28 @@ async function init(config = {}) {
   startListening();
   const boot = await waitBootstrap();
   const client = new TesanaClient(buildConfig(mergedConfig()));
-  await client.ensureSession();
+  // An unreachable play service must cost a *feature*, never the game.
+  //
+  // This is the client half of a contract the server already keeps: Django's
+  // mint returns None rather than failing a request, precisely so that "the
+  // play service being slow, down, or unconfigured means the SDK keeps saves in
+  // the browser — worse, but the game still runs". Without this catch the
+  // client contradicted that. `ensureSession()` mints an identity over HTTP, so
+  // a failure here rejected `__TESANA_READY__`, and a game doing the documented
+  // `await window.__TESANA_READY__` threw on its first line — turning a service
+  // outage into a broken game for everyone using it.
+  //
+  // Falling back to offline is the correct degradation, not a swallow: every
+  // read already has a local or empty answer (`balance()` reports zero,
+  // `shop.read()` reports a shut shutter, saves read as missing), and a later
+  // bootstrap upgrade still re-runs the identity step through
+  // `onBootstrapUpgrade` below. The player loses cloud features for that
+  // session and keeps their game.
+  try {
+    await client.ensureSession();
+  } catch (err) {
+    client.goOffline(err);
+  }
   window.__TESANA_PLAYER__ = client.player.me();
   // A provisional "offline" answer can upgrade later. Re-point this client in
   // place — the game holds a reference to it — and re-run the identity step,
@@ -499,6 +528,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
@@ -523,7 +557,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;
@@ -558,6 +592,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 = {
@@ -685,9 +721,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)}${
@@ -780,21 +816,29 @@ class TesanaClient {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
       enabled: this._mpEnabled,
+      // `_mpEnabled` alone is not enough. A game with no host has multiplayer
+      // "allowed" and no service to ask, so `list()` used to reject with a
+      // transport error — and a game that draws a lobby on load (which the
+      // skill tells games to do) got an unhandled rejection on its title
+      // 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.request("GET", "/v1/mp/rooms").then((r) => r.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),
@@ -1089,7 +1133,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 };
       }
@@ -1103,14 +1147,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),
@@ -1154,6 +1212,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;
@@ -1170,6 +1230,46 @@ class TesanaClient {
     return this;
   }
 
+  /**
+   * Carry on without the play service.
+   *
+   * The boot path calls this when the identity step fails — an unreachable
+   * endpoint, a 500, a bad secret, a cert the browser will not accept. A game
+   * must not die of it: the server side of this contract already returns no
+   * token and lets the game run, so the client falls back to exactly the state
+   * a game with no endpoint is in.
+   *
+   * Marking the client offline is the honest outcome rather than a silent
+   * swallow. Every read already has an offline answer — `balance()` reports
+   * zero coins and `canSpend: false`, the shop reports a shut shutter, saves
+   * read as absent and write to the local cache — so the game draws its
+   * title screen instead of throwing. A later bootstrap upgrade re-runs the
+   * identity step and flips this back off.
+   *
+   * The token is cleared rather than kept: it is the thing that failed to
+   * authenticate, and half an identity is worse than none — every call would
+   * retry a credential the service just refused.
+   *
+   * @param {unknown} [reason] the failure, kept for diagnostics
+   */
+  goOffline(reason) {
+    this.offline = true;
+    this.token = "";
+    this.saveToken = "";
+    this.canSaveToCloud = false;
+    this._mpEnabled = false;
+    this.multiplayer.enabled = false;
+    // One deduped line rather than a wall: a page whose endpoint is
+    // misconfigured would otherwise log this on every call.
+    warnOnce(
+      "play-session",
+      `[tesana] play service unavailable; running without cloud saves or the shop${
+        reason ? ` (${(reason && reason.message) || reason})` : ""
+      }`,
+    );
+    return this;
+  }
+
   /**
    * Which origin and which credential a path uses.
    *
@@ -1369,6 +1469,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 });
@@ -1401,7 +1508,8 @@ 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 });
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1416,7 +1524,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);
       };
@@ -1429,10 +1537,15 @@ 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() {
+    return Boolean(this._player && this._player.isGuest);
+  }
+
 }
 
 function enc(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tesana/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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.0";
+const VERSION = "1.0.2";
 
 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 };
@@ -444,7 +452,28 @@ export async function init(config = {}) {
   startListening();
   const boot = await waitBootstrap();
   const client = new TesanaClient(buildConfig(mergedConfig()));
-  await client.ensureSession();
+  // An unreachable play service must cost a *feature*, never the game.
+  //
+  // This is the client half of a contract the server already keeps: Django's
+  // mint returns None rather than failing a request, precisely so that "the
+  // play service being slow, down, or unconfigured means the SDK keeps saves in
+  // the browser — worse, but the game still runs". Without this catch the
+  // client contradicted that. `ensureSession()` mints an identity over HTTP, so
+  // a failure here rejected `__TESANA_READY__`, and a game doing the documented
+  // `await window.__TESANA_READY__` threw on its first line — turning a service
+  // outage into a broken game for everyone using it.
+  //
+  // Falling back to offline is the correct degradation, not a swallow: every
+  // read already has a local or empty answer (`balance()` reports zero,
+  // `shop.read()` reports a shut shutter, saves read as missing), and a later
+  // bootstrap upgrade still re-runs the identity step through
+  // `onBootstrapUpgrade` below. The player loses cloud features for that
+  // session and keeps their game.
+  try {
+    await client.ensureSession();
+  } catch (err) {
+    client.goOffline(err);
+  }
   window.__TESANA_PLAYER__ = client.player.me();
   // A provisional "offline" answer can upgrade later. Re-point this client in
   // place — the game holds a reference to it — and re-run the identity step,
@@ -497,6 +526,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
@@ -521,7 +555,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;
@@ -556,6 +590,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 = {
@@ -683,9 +719,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)}${
@@ -778,21 +814,29 @@ class TesanaClient {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
       enabled: this._mpEnabled,
+      // `_mpEnabled` alone is not enough. A game with no host has multiplayer
+      // "allowed" and no service to ask, so `list()` used to reject with a
+      // transport error — and a game that draws a lobby on load (which the
+      // skill tells games to do) got an unhandled rejection on its title
+      // 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.request("GET", "/v1/mp/rooms").then((r) => r.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),
@@ -1087,7 +1131,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 };
       }
@@ -1101,14 +1145,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),
@@ -1152,6 +1210,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;
@@ -1168,6 +1228,46 @@ class TesanaClient {
     return this;
   }
 
+  /**
+   * Carry on without the play service.
+   *
+   * The boot path calls this when the identity step fails — an unreachable
+   * endpoint, a 500, a bad secret, a cert the browser will not accept. A game
+   * must not die of it: the server side of this contract already returns no
+   * token and lets the game run, so the client falls back to exactly the state
+   * a game with no endpoint is in.
+   *
+   * Marking the client offline is the honest outcome rather than a silent
+   * swallow. Every read already has an offline answer — `balance()` reports
+   * zero coins and `canSpend: false`, the shop reports a shut shutter, saves
+   * read as absent and write to the local cache — so the game draws its
+   * title screen instead of throwing. A later bootstrap upgrade re-runs the
+   * identity step and flips this back off.
+   *
+   * The token is cleared rather than kept: it is the thing that failed to
+   * authenticate, and half an identity is worse than none — every call would
+   * retry a credential the service just refused.
+   *
+   * @param {unknown} [reason] the failure, kept for diagnostics
+   */
+  goOffline(reason) {
+    this.offline = true;
+    this.token = "";
+    this.saveToken = "";
+    this.canSaveToCloud = false;
+    this._mpEnabled = false;
+    this.multiplayer.enabled = false;
+    // One deduped line rather than a wall: a page whose endpoint is
+    // misconfigured would otherwise log this on every call.
+    warnOnce(
+      "play-session",
+      `[tesana] play service unavailable; running without cloud saves or the shop${
+        reason ? ` (${(reason && reason.message) || reason})` : ""
+      }`,
+    );
+    return this;
+  }
+
   /**
    * Which origin and which credential a path uses.
    *
@@ -1367,6 +1467,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 });
@@ -1399,7 +1506,8 @@ 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 });
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1414,7 +1522,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);
       };
@@ -1427,10 +1535,15 @@ 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() {
+    return Boolean(this._player && this._player.isGuest);
+  }
+
 }
 
 function enc(value) {