@tesana/sdk 1.0.3 → 1.0.4

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.3";
+const VERSION = "1.0.4";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -197,6 +197,60 @@ function onBootstrapUpgrade(fn) {
  */
 let adClient = null;
 
+/**
+ * The live localization capability, kept module-scoped for the same reason as
+ * the ad client: the host can change the language at any moment, and the game
+ * holds a reference to `tesana.l10n` that must not be replaced underneath it.
+ * The listener calls `applyLocale`, which re-points this object in place.
+ */
+let l10nClient = null;
+
+/**
+ * The languages the platform can translate into, in display order.
+ *
+ * Mirrors the service's own list, which is the authority; this copy exists so a
+ * language picker can be drawn before the service has answered — and so a page
+ * with no host at all, where nothing will ever answer, still has an honest
+ * list rather than an empty one.
+ */
+const L10N_TARGETS = ["en", "es", "fr", "de", "it", "pt-BR", "ru", "zh", "ja", "ko"];
+
+/**
+ * Fold whatever a host calls a language onto one of ours.
+ *
+ * `navigator.language` reports `en-US` and `pt-PT`; a site may store `pt` or
+ * `zh`; a player may be handed `de-AT`. None of those are in the list above and
+ * all of them mean a language we do translate into, so the base tag is what
+ * gets matched and the region is dropped — a game in `pt-BR` is more useful to
+ * a `pt-PT` player than one left in English. An unknown tag stays as it is and
+ * simply falls back to the source language at the call site.
+ */
+function normalizeLocale(tag) {
+  const value = String(tag || "").trim().replace(/_/g, "-");
+  if (!value) return "";
+  const exact = L10N_TARGETS.find((t) => t.toLowerCase() === value.toLowerCase());
+  if (exact) return exact;
+  const base = value.split("-")[0].toLowerCase();
+  return L10N_TARGETS.find((t) => t.split("-")[0].toLowerCase() === base) || value;
+}
+
+/** `{name}` in `text`, filled from `values`. The one interpolation rule the SDK and the service share. */
+function fillPlaceholders(text, values) {
+  const source = String(text == null ? "" : text);
+  if (!values || typeof values !== "object") return source;
+  return source.replace(/\{(\w+)\}/g, (whole, key) =>
+    Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : whole,
+  );
+}
+
+/** Fold a locale message from the host into the live client, if it is listening. */
+function resyncLocale(data) {
+  if (!l10nClient) return;
+  const payload = data && typeof data.payload === "object" ? data.payload : data;
+  const next = payload && (payload.locale || payload.lang || payload.language);
+  if (next) l10nClient.applyLocale(next);
+}
+
 /** A policy message from the host, or `null` when none is in force. */
 function adPolicyFrom(data) {
   if (!data || typeof data !== "object") return null;
@@ -366,6 +420,19 @@ function startListening() {
       }
       return;
     }
+    // The player changed the site's language. The host is the authority — it
+    // resolved which language the player wants, and it owns the setting — so
+    // this only carries it down. The game's own text re-renders when it draws
+    // again, which is why the skill tells games to redraw from `t()` rather
+    // than cache translated strings at startup.
+    if (data.type === "tesana-locale") {
+      try {
+        resyncLocale(data);
+      } catch {
+        /* a bad locale must never break the listener */
+      }
+      return;
+    }
     if (data.type === "tesana-ad-show") {
       try {
         const requestId = data.requestId || data.request_id;
@@ -489,6 +556,16 @@ export async function init(config = {}) {
   } catch (err) {
     client.goOffline(err);
   }
+  // Localization comes after identity, not before: the bundle is fetched with
+  // the player's token, so a game that just minted one would otherwise load it
+  // unauthenticated and stay in its source language all session. Awaited here
+  // so `await __TESANA_READY__` is genuinely enough — the first frame a game
+  // draws can already be translated.
+  try {
+    await client.l10n.reload();
+  } catch {
+    /* localization must never block the game's start */
+  }
   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,
@@ -496,7 +573,7 @@ export async function init(config = {}) {
   // player with a balance frozen at zero.
   const finishUpgrade = () => {
     client.configure(buildConfig(mergedConfig()));
-    client.ensureSession();
+    client.ensureSession().then(() => client.l10n.reload());
     window.__TESANA_PLAYER__ = client.player.me();
   };
   onBootstrapUpgrade(finishUpgrade);
@@ -559,6 +636,15 @@ function buildConfig(merged) {
     adsEnabled: merged.adsEnabled,
     adFormats: merged.adFormats || merged.ad_formats || [],
     adMinIntervalMs: merged.adMinIntervalMs ?? merged.ad_min_interval_ms,
+    // The player's language, as the host resolved it. The host owns the
+    // setting (the site has a language picker and the game does not), so this
+    // is read from the bootstrap rather than sniffed here — a game that
+    // guessed from `navigator.language` would disagree with the site the
+    // player is reading. Absent means an older host: localization then falls
+    // back to the source language and the game renders exactly as it did.
+    locale: normalizeLocale(
+      merged.locale || merged.language || merged.lang || (typeof navigator !== "undefined" && navigator.language) || "",
+    ),
   };
 }
 
@@ -570,7 +656,7 @@ function defaultEndpoint() {
 
 class TesanaClient {
   /**
-   * @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
+   * @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, locale?: string }} opts
    */
   constructor(opts) {
     this.endpoint = opts.endpoint;
@@ -613,6 +699,8 @@ class TesanaClient {
       ws: null,
       handlers: [],
       roomId: null,
+      // The current room's share code, or null for a public room.
+      code: null,
       // Reconnect state. `wsUrl` is kept so a dropped socket can re-enter the
       // same room; `leaving` stops a deliberate leave from being retried.
       wsUrl: null,
@@ -825,6 +913,16 @@ class TesanaClient {
     // same object in place, rather than the game holding a stale policy.
     adClient = this.ads;
 
+    // Localization. A generated game draws its text onto a canvas, so the
+    // platform cannot translate the running game the way it translates the
+    // site's own pages — the game has to ask, and this is the surface it asks
+    // through. The same one rule as the shop: an unreachable service costs a
+    // translation and never the game. Every method here has a source-language
+    // answer, and `t()` is synchronous, so a menu never waits on a network to
+    // draw itself in the player's language.
+    this.l10n = this._makeL10n(opts);
+    l10nClient = this.l10n;
+
     this.multiplayer = {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
@@ -841,14 +939,42 @@ class TesanaClient {
               .then((r) => r.rooms)
               .catch(() => [])
           : Promise.resolve([]),
+      // Open a room. It is public and always joinable unless you pass a `code`,
+      // which is the only way entry is restricted: the room is then unlisted and
+      // only someone with the code can reach it. The resolved code is on
+      // `room.code` in the result (the service generates one if you pass
+      // `code: true`), so show it to the room.
       create: (opts) =>
         this._mpEnabled
           ? this._mpEnter(this._mpRequest("POST", "/v1/mp/rooms", opts || {}))
           : this._mpRefuse(),
-      join: (roomId) =>
-        this._mpEnabled
-          ? this._mpEnter(this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
-          : this._mpRefuse(),
+      // Accept the room a game got from list() as well as from a session. Both
+      // read as "the room to join": `list()` rows are keyed `id`, a
+      // create/quickJoin/join result carries `roomId`. Taking an object here is
+      // what stops a lobby that calls `join(room)` from having to know which.
+      join: (room) => {
+        if (!this._mpEnabled) return this._mpRefuse();
+        const roomId =
+          room && typeof room === "object" ? room.id || room.roomId : room;
+        // The bug this guards: a game read `room.roomId` off a list() row,
+        // where it is undefined, and we asked the service for the room named
+        // "undefined" — a 404 indistinguishable from a deleted room. Fail
+        // here, by name, so the mistake is legible.
+        if (roomId == null || roomId === "") {
+          const err = new Error(
+            "join() needs a room id — pass a room from list() (its `id`) or a create/join result",
+          );
+          err.code = "mp_room_id_required";
+          return Promise.reject(err);
+        }
+        return this._mpEnter(
+          this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`),
+        );
+      },
+      // Join the fullest public room with a free seat, creating one if there is
+      // none. Pass `code` to enter a private room instead: the first player to
+      // use a code opens that room and the rest join it, and a full one refuses
+      // rather than opening a second room under the same code.
       quickJoin: (opts) =>
         this._mpEnabled
           ? this._mpEnter(this._mpRequest("POST", "/v1/mp/quick-join", opts || {}))
@@ -1026,11 +1152,27 @@ class TesanaClient {
    */
   async _mpEnter(session) {
     const joined = await session;
-    await this._mpOpen(joined.wsUrl);
+    // A room that was opened and then could not be entered is reported as what
+    // it is: the room exists. The SDK cannot seat the player — that is the
+    // host's job — but it can name the room so a game retries `join(roomId)`
+    // instead of opening a second one and stranding the first.
+    try {
+      await this._mpOpen(joined.wsUrl);
+    } catch (err) {
+      const roomId = joined.roomId || joined.room?.id || null;
+      const wrapped = new Error(
+        roomId ? `${err?.message || "multiplayer unavailable"} (room ${roomId})` : err?.message || "multiplayer unavailable",
+      );
+      wrapped.code = err?.code || "mp_enter_failed";
+      wrapped.roomId = roomId;
+      throw wrapped;
+    }
     this._mp.roomId = joined.roomId || joined.room?.id || null;
+    this._mp.code = joined.room?.code || null;
     return {
       wsUrl: joined.wsUrl,
       roomId: this._mp.roomId,
+      code: this._mp.code,
       playerId: joined.playerId || this._player?.id,
       room: joined.room,
     };
@@ -1207,6 +1349,7 @@ class TesanaClient {
     this._mp.leaving = true;
     this._mpClose();
     this._mp.roomId = null;
+    this._mp.code = null;
     this._mp.wsUrl = null;
     this._mp.reconnectAttempts = 0;
     this._mp.reconnectExhausted = false;
@@ -1305,6 +1448,13 @@ class TesanaClient {
         minIntervalMs: config.adMinIntervalMs,
       });
     }
+    // A later bootstrap may carry the player's language — a provisionally
+    // "offline" answer has none, and the real one arrives a moment later. The
+    // capability is re-pointed in place, exactly as the ad policy is.
+    if (config.locale && this.l10n) {
+      const next = normalizeLocale(config.locale);
+      if (next && next !== this.l10n.locale()) this.l10n.applyLocale(next);
+    }
     this._mpEnabled = config.multiplayer !== false;
     this.multiplayer.enabled = this._mpEnabled;
     return this;
@@ -1538,6 +1688,300 @@ class TesanaClient {
     };
   }
 
+  // -------------------------------------------------------------------- l10n
+  //
+  // Localization, from the game's side. The service owns the dictionary and the
+  // translation; this owns one promise: a game that asks for its text in the
+  // player's language gets something renderable, always.
+  //
+  // Deliberately synchronous where the game needs it to be. `t()` reads a map
+  // that was filled before the first frame, so drawing a localized menu costs no
+  // await and no round trip; only text the game discovers at runtime — a
+  // procedurally generated item name, something the player typed — goes through
+  // the async path. A game that never awaits anything still localizes.
+  _makeL10n(opts) {
+    const state = {
+      locale: normalizeLocale(opts.locale || ""),
+      // The language the game's own strings are written in. Declared by the
+      // build; the service is told the same value, so the two agree rather
+      // than one guessing what the other meant.
+      source: "en",
+      // The platform's list, refined by the service's answer when it arrives.
+      languages: L10N_TARGETS.slice(),
+      // Source text -> translated text, filled before `ready` resolves.
+      bundle: {},
+      // The game's own key -> source text, for `t("ui.play")`.
+      index: {},
+      handlers: [],
+      // `requested`: what the game's source language resolved to (en, de, …)
+      // vs `target`: what is actually being served — the difference is a
+      // language the game did not declare, where the source is the answer.
+      target: "",
+      loaded: false,
+      // The bundle is asked for from three places on a normal boot — `ready`,
+      // `init`'s await, and the post-session reload — and all three want the
+      // same one. `inflight` is the shared request; `loadedFor` is the target
+      // that has already been answered, so a repeat is a no-op rather than a
+      // second round trip for an object we already hold.
+      inflight: null,
+      inflightTarget: "",
+      loadedFor: null,
+    };
+
+    const self = this;
+
+    /** Emit a locale change to every listener, without letting one break the rest. */
+    function emit() {
+      const event = { locale: state.locale, target: state.target, languages: state.languages.slice() };
+      for (const fn of [...state.handlers]) {
+        try {
+          fn(event);
+        } catch {
+          /* a game handler */
+        }
+      }
+    }
+
+    /**
+     * Resolve `key` against the bundle.
+     *
+     * Three shapes, because a game reaches for all three: a key it declared
+     * (`"ui.play"`), the source sentence itself (`"Play"`), and a key with a
+     * fallback for the source text that was never declared. Whatever is not
+     * found comes back as the fallback or the key, which is what makes an
+     * unreachable service a non-event.
+     */
+    function lookup(key, fallback) {
+      const name = String(key == null ? "" : key);
+      const source = state.index[name] || name;
+      const hit = state.bundle[source];
+      if (typeof hit === "string" && hit) return hit;
+      if (typeof fallback === "string" && fallback) return fallback;
+      return source;
+    }
+
+    /**
+     * Load the bundle, at most once per (language, reachability) combination.
+     *
+     * A boot calls this from several independent places — the `ready` promise,
+     * `init`'s await, and the post-session `reload` — and they all want the
+     * same bundle. Coalescing them is not an optimization for its own sake:
+     * every extra request is the player's bundle fetched twice, and a game
+     * that redraws on `onChange` should not be able to multiply it.
+     */
+    function load() {
+      const target = self._canReach() && state.locale && state.locale !== state.source ? state.locale : "";
+      if (state.inflight && state.inflightTarget === target) return state.inflight;
+      if (state.loadedFor === target && state.loaded) return Promise.resolve(state);
+      state.inflightTarget = target;
+      state.inflight = fetchBundle(target).finally(() => {
+        state.inflight = null;
+      });
+      return state.inflight;
+    }
+
+    async function fetchBundle(target) {
+      if (!self._canReach()) {
+        // No address, or no game id: nothing will ever answer, and asking
+        // anyway would throw a relative-URL fetch. The source language is the
+        // honest answer and the game renders exactly as it always did.
+        state.loaded = true;
+        state.loadedFor = target;
+        return state;
+      }
+      try {
+        if (!target) {
+          // Nothing to fetch — and no request at all, either. A source-language
+          // boot needs no bundle (nothing is translated) and no language list
+          // (the platform's known set is already in memory), so a game with no
+          // localization in force makes zero localization requests. That
+          // matters beyond tidiness: it is the same rule as the rest of the
+          // SDK, that a capability nobody asked for must not put bytes on the
+          // wire, and it is what a game running entirely offline relies on.
+          state.target = "";
+          state.loaded = true;
+          state.loadedFor = target;
+          return state;
+        }
+        const data = await self.request(
+          "GET",
+          `/v1/l10n/bundle?target=${enc(target)}`,
+        );
+        if (data && typeof data.translations === "object" && data.translations) {
+          state.bundle = data.translations;
+        }
+        if (data && typeof data.index === "object" && data.index) {
+          state.index = data.index;
+        }
+        if (typeof data?.source === "string" && data.source) state.source = data.source;
+        // `target` is the service's answer about what it actually served.
+        // It is `""` for a language this game has not declared, which is the
+        // signal that the source text IS the answer.
+        state.target = typeof data?.target === "string" && data.target ? data.target : "";
+        // The declared language set arrives with the bundle's own response
+        // rather than a second route. It is one fact about one game, and two
+        // requests to learn it is one more chance for a boot to be slower than
+        // the first frame.
+        if (Array.isArray(data?.languages) && data.languages.length) {
+          // The game's own declared set, in the order it chose — which is how
+          // a game that lists French first gets French first in its picker.
+          state.languages = data.languages.slice();
+        }
+      } catch (err) {
+        // An outage costs the translation, not the game. One deduped line is
+        // enough to make it findable without spamming the console on retry.
+        warnOnce(
+          "l10n-unreachable",
+          `Tesana localization: could not reach the translation service (${(err && err.message) || "request failed"}).`
+            + " The game keeps playing in its source language.",
+        );
+      }
+      state.loaded = true;
+      state.loadedFor = target;
+      return state;
+    }
+
+    return {
+      /**
+       * The player's language, synchronously, as the host resolved it.
+       *
+       * Follows the same tag vocabulary the site uses (`pt-BR`, `zh`), not
+       * AWS's, so a game can pass it straight to `Intl`/`toLocaleString`.
+       */
+      locale: () => state.locale,
+      /** The languages this game offers, the host's order preserved. */
+      languages: () => state.languages.slice(),
+      /** The language text is actually being served in, or `""` when it is the source. */
+      target: () => state.target,
+      /** The language the game's own strings are written in. */
+      source: () => state.source,
+      /** Whether the initial bundle has landed. `t()` works before it does. */
+      get loaded() {
+        return state.loaded;
+      },
+
+      /**
+       * The translated text for `key`, synchronously.
+       *
+       * Prefer this. It is filled before the first frame, so a game never has
+       * to await anything to draw a localized menu — and when the bundle is
+       * empty (a service outage, a language the game never declared) it returns
+       * the source text, which is a rendered game rather than a blank one.
+       *
+       * @param {string} key  a declared key, or the source sentence itself
+       * @param {object|string} [vars]  `{name}` values, or a fallback string
+       */
+      t: (key, vars) => {
+        // The second argument is both of the things a caller wants to pass:
+        // placeholder values, and a fallback for an undeclared key. A string is
+        // unambiguously a fallback; an object is unambiguously values.
+        const values = vars && typeof vars === "object" ? vars : null;
+        const fallback = typeof vars === "string" ? vars : "";
+        return fillPlaceholders(lookup(key, fallback), values);
+      },
+
+      /**
+       * Translate text the game discovered while running.
+       *
+       * The one path that costs a round trip, so it is the one to keep off the
+       * hot path: ask once, at the moment the text is created (a generated
+       * name, a line of dialogue just chosen), never per frame. Resolves the
+       * source text on any failure, so a `.then` never sees a rejection.
+       *
+       * @param {string} text
+       * @param {{ id?: string, values?: Record<string, unknown>, target?: string }} [opts]
+       */
+      translate: async (text, opts = {}) => {
+        const values = opts.values && typeof opts.values === "object" ? opts.values : null;
+        const target = opts.target || state.target || (state.locale !== state.source ? state.locale : "");
+        // A named string is routed through the id-keyed path, which is what
+        // lets the service remember it under the game's own name and serve it
+        // from cache next time without even a hash lookup.
+        if (opts.id && self._canReach() && target) {
+          try {
+            const data = await self.request("POST", "/v1/l10n/string", {
+              id: String(opts.id),
+              text: String(text == null ? "" : text),
+              values: values || undefined,
+              target,
+              source: state.source,
+            });
+            if (data && typeof data.value === "string" && data.value) return data.value;
+          } catch {
+            /* falls through to the source text below */
+          }
+        }
+        // The anonymous path requires a target to be worth a call. With no
+        // target this *is* the source language, and asking the server to hand
+        // back what it was given is the most expensive no-op available.
+        if (self._canReach() && target) {
+          try {
+            const data = await self.request("POST", "/v1/l10n/translate", {
+              strings: [String(text == null ? "" : text)],
+              target,
+              source: state.source,
+            });
+            const hit = data?.translations?.[String(text)];
+            if (typeof hit === "string" && hit) return fillPlaceholders(hit, values);
+          } catch {
+            /* ditto */
+          }
+        }
+        return fillPlaceholders(String(text == null ? "" : text), values);
+      },
+
+      /**
+       * Subscribe to a language change. Returns an unsubscribe function.
+       *
+       * A game should redraw its text (or call `t()` again) on this rather than
+       * caching translated strings at startup, because the player can change
+       * the site's language without reloading the frame.
+       *
+       * @param {(event: { locale: string, target: string, languages: string[] }) => void} fn
+       */
+      onChange: (fn) => {
+        if (typeof fn !== "function") return () => {};
+        state.handlers.push(fn);
+        return () => {
+          state.handlers = state.handlers.filter((handler) => handler !== fn);
+        };
+      },
+
+      /** Resolves after the initial bundle. A game may await it with `__TESANA_READY__`. */
+      ready: load(),
+
+      /**
+       * Reload the bundle, after an identity or language change.
+       *
+       * The constructor loads immediately from whatever the page already
+       * carries. A game that minted its own token — or a host whose real
+       * bootstrap replaced a provisional "offline" one — has no credential that
+       * first time, so the bundle would be empty and the game would stay in its
+       * source language for the whole session. `init` awaits this after the
+       * identity step, which is what makes the documented
+       * `await window.__TESANA_READY__` sufficient for a localized first frame.
+       */
+      reload: () => load(),
+
+      // ---- internal wiring (used by the bootstrap listener) ----
+      /** A new language from the host. Resolves the same promise the game already holds. */
+      applyLocale(next) {
+        const locale = normalizeLocale(next);
+        if (!locale || locale === state.locale) return state;
+        state.locale = locale;
+        // The old bundle is the *previous* language's, so it is cleared rather
+        // than left to serve: showing a menu in a language the player just
+        // switched away from is worse than showing the source text for the
+        // moment the refill takes. `t()` falls back to source in between.
+        state.bundle = {};
+        state.target = "";
+        emit();
+        load().catch(() => {});
+        return state;
+      },
+    };
+  }
+
   // ------------------------------------------------------------------ saves
   //
   // Writes go to the local cache first, always, so a failed upload is a save