@tesana/sdk 1.0.0 → 1.0.1

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.1";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -444,7 +444,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,
@@ -778,9 +799,17 @@ 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.request("GET", "/v1/mp/rooms")
+              .then((r) => r.rooms)
+              .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
@@ -1168,6 +1197,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.
    *

package/dist/tesana.iife.js

@@ -1,4 +1,4 @@
-/* Tesana play-time SDK v1.0.0 */
+/* Tesana play-time SDK v1.0.1 */
 (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.1";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -446,7 +446,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,
@@ -780,9 +801,17 @@ 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.request("GET", "/v1/mp/rooms")
+              .then((r) => r.rooms)
+              .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
@@ -1170,6 +1199,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.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tesana/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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.1";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -444,7 +444,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,
@@ -778,9 +799,17 @@ 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.request("GET", "/v1/mp/rooms")
+              .then((r) => r.rooms)
+              .catch(() => [])
           : Promise.resolve([]),
       create: (opts) =>
         this._mpEnabled
@@ -1168,6 +1197,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.
    *