@tesana/sdk 1.0.2 → 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.2";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -415,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;
 
@@ -901,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,
@@ -933,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";
@@ -1508,6 +1590,13 @@ class TesanaClient {
   _signIn() {
     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;
@@ -1541,7 +1630,46 @@ class TesanaClient {
 
   /** 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);
+    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.2 */
+/* 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.2";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -417,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;
 
@@ -903,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,
@@ -935,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";
@@ -1510,6 +1592,13 @@ class TesanaClient {
   _signIn() {
     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;
@@ -1543,7 +1632,46 @@ class TesanaClient {
 
   /** 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);
+    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.2",
+  "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.2";
+const VERSION = "1.0.3";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -415,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;
 
@@ -901,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,
@@ -933,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";
@@ -1508,6 +1590,13 @@ class TesanaClient {
   _signIn() {
     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;
@@ -1541,7 +1630,46 @@ class TesanaClient {
 
   /** 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);
+    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);
+      });
+    });
   }
 
 }