@usions/sdk 2.13.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.13.0",
+  "version": "2.16.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",
@@ -60,4 +60,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/browser.js

@@ -69,7 +69,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.13.0', // injected from package.json at build
+    version: '2.16.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -192,10 +192,56 @@ var Usion = (function () {
         }
       });
 
+      // Report the user's first real interaction to the host (see below).
+      this._setupInteractionBeacon();
+
       // Signal ready to parent
       this._post({ type: 'READY' });
     },
 
+    /**
+     * Tell the host the moment the user FIRST genuinely interacts with the
+     * mini-app — a tap, click, key press, or touch — and only once.
+     *
+     * The host uses this as the SOLE signal to surface the mini-app in the user's
+     * chat list — only after real engagement (opening alone, and automatic
+     * load-time SDK calls, never count). It works for a fully self-contained
+     * app/game that never calls any other SDK method: no `Usion.*` call is
+     * required for the host to know the user is engaged.
+     *
+     * Standalone (non-embedded) apps are unaffected — `_post` no-ops when there
+     * is no host. Note: input that produces no DOM gesture (pure device-motion,
+     * gamepad) won't trigger this until the first tap/click/key.
+     * @private
+     */
+    _setupInteractionBeacon: function() {
+      const self = this;
+      if (self._interactionBeaconSetup) return;
+      self._interactionBeaconSetup = true;
+      if (typeof window === 'undefined' || !window.addEventListener) return;
+
+      const events = ['pointerdown', 'mousedown', 'touchstart', 'keydown'];
+      function fire(event) {
+        // Only count real user gestures, never programmatically dispatched ones.
+        if (event && event.isTrusted === false) return;
+        if (self._interactionReported) return;
+        self._interactionReported = true;
+        for (let i = 0; i < events.length; i++) {
+          try { window.removeEventListener(events[i], fire, true); } catch (e) { /* noop */ }
+        }
+        self._post({ type: 'USER_INTERACTION' });
+      }
+      for (let i = 0; i < events.length; i++) {
+        // Capture phase + passive so we observe the gesture without interfering
+        // with the app's own handlers or scroll performance.
+        try {
+          window.addEventListener(events[i], fire, { capture: true, passive: true });
+        } catch (e) {
+          try { window.addEventListener(events[i], fire, true); } catch (e2) { /* noop */ }
+        }
+      }
+    },
+
     /**
      * Get the current theme ('light' or 'dark')
      * @returns {string}
@@ -426,6 +472,13 @@ var Usion = (function () {
       _balance: null,
       _balanceChangeHandler: null,
 
+      // Payment timing knobs (overridable, mainly for tests). The defaults are
+      // the production values.
+      _paymentTimeoutMs: 60000,      // wait this long for the direct PAYMENT_SUCCESS
+      _recoveryPollMs: 2000,         // gap between result-recovery re-queries
+      _recoveryMaxPolls: 10,         // bounded recovery window after the timeout
+      _recoveryQueryTimeoutMs: 8000, // per re-query round-trip budget
+
       /**
        * Get current wallet balance
        * @returns {Promise<number>} Balance in credits
@@ -456,20 +509,69 @@ var Usion = (function () {
       },
 
       /**
-       * Request payment from user with balance check
+       * Request payment from user with balance check.
+       *
+       * The charge is debited immediately by the host (escrow); the resolved
+       * value carries a `receiptToken` the mini-app server later settles/refunds.
+       *
+       * Reliability: if the host's PAYMENT_SUCCESS message is lost (network blip,
+       * backgrounded tab, race) the user may ALREADY be charged. Instead of
+       * rejecting at the timeout, this re-queries the host for the result and
+       * recovers the receipt token — so a dropped message never strands a paid
+       * charge. Pass `idempotencyKey` to additionally guarantee that any retry of
+       * the SAME intent reuses the SAME charge (the host + backend dedupe on it),
+       * so the user can never be charged twice even across reloads.
+       *
        * @param {number} amount - Credit amount to charge
        * @param {string} reason - Description shown to user
-       * @param {object} data - Optional additional data
+       * @param {object} [data] - Optional options/payload. `data.idempotencyKey`
+       *   (string) makes the charge safely retryable. Any other fields are
+       *   forwarded to the host verbatim (backward compatible).
        * @returns {Promise} Resolves on payment success, rejects on failure
        */
       requestPayment: function(amount, reason, data) {
         const self = this;
 
+        const opts = (data && typeof data === 'object') ? data : null;
+        const idempotencyKey = (opts && typeof opts.idempotencyKey === 'string' && opts.idempotencyKey)
+          ? opts.idempotencyKey
+          : null;
+
         return new Promise(function(resolve, reject) {
           const requestId = getNextRequestId();
-          const timeoutMs = 60000;
+          const timeoutMs = self._paymentTimeoutMs || 60000;
+          let settled = false;
+          let recoverTimer = null;
+
+          function cleanup() {
+            clearTimeout(timer);
+            if (recoverTimer) clearTimeout(recoverTimer);
+            window.removeEventListener('message', handler);
+          }
+
+          function finishResolve(response) {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            // Update cached balance from the authoritative new balance, else
+            // best-effort subtract (no-op if balance is unknown).
+            if (response && response.newBalance !== undefined) {
+              self._balance = response.newBalance;
+            } else if (self._balance !== null) {
+              self._balance -= amount;
+            }
+            resolve(response);
+          }
+
+          function finishReject(error) {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            reject(error);
+          }
 
-          // Listen for response
+          // Direct response from the host. Kept registered through the recovery
+          // window so a late PAYMENT_SUCCESS still resolves.
           function handler(event) {
             // Only honor payment results from the trusted host shell — a forged
             // PAYMENT_SUCCESS must never resolve this promise.
@@ -483,32 +585,97 @@ var Usion = (function () {
             }
 
             // Only accept responses for this specific payment request.
-            if (response._requestId !== requestId) {
+            if (!response || response._requestId !== requestId) {
               return;
             }
 
             if (response.type === 'PAYMENT_SUCCESS') {
-              clearTimeout(timer);
-              window.removeEventListener('message', handler);
-              // Update cached balance
-              if (response.newBalance !== undefined) {
-                self._balance = response.newBalance;
-              } else if (self._balance !== null) {
-                self._balance -= amount;
-              }
-              resolve(response);
+              finishResolve(response);
             } else if (response.type === 'PAYMENT_FAILED') {
-              clearTimeout(timer);
-              window.removeEventListener('message', handler);
-              reject(new Error(response.reason || 'Payment failed'));
+              finishReject(new Error(response.reason || 'Payment failed'));
             }
           }
 
+          // After the direct deadline, re-query the host for this payment's
+          // result instead of rejecting.
+          //   succeeded -> resolve with the recovered token
+          //   failed    -> reject
+          //   pending   -> the modal is STILL OPEN / charge still in progress, so
+          //                the charge is fully recoverable: keep waiting (do NOT
+          //                count this toward the give-up cap). A slow user who
+          //                confirms minutes later still resolves — via the next
+          //                'succeeded' poll or the direct handler, which stays
+          //                registered. Without this, a charge made after we gave
+          //                up would be stranded (the original bug, shifted to the
+          //                slow-confirm case).
+          //   none/other -> likely no charge; confirm twice then reject cleanly so
+          //                a fresh requestPayment is safe.
+          // The bounded cap only governs the give-up paths (none-streak and a host
+          // that never answers the query at all, e.g. an older host shell).
+          function recoverPaymentResult() {
+            const pollMs = self._recoveryPollMs || 2000;
+            const maxPolls = self._recoveryMaxPolls || 10;
+            const queryTimeoutMs = self._recoveryQueryTimeoutMs || 8000;
+            let noneStreak = 0;
+            let errorStreak = 0;
+
+            function poll() {
+              if (settled) return;
+              Usion._request('PAYMENT_RESULT_QUERY', {
+                paymentRequestId: requestId,
+                idempotencyKey: idempotencyKey || undefined,
+              }, queryTimeoutMs).then(function(res) {
+                if (settled) return;
+                const status = res && res.status;
+                if (status === 'succeeded') {
+                  finishResolve({
+                    type: 'PAYMENT_SUCCESS',
+                    _requestId: requestId,
+                    newBalance: res.newBalance,
+                    transactionId: res.transactionId,
+                    receiptToken: res.receiptToken,
+                  });
+                  return;
+                }
+                if (status === 'failed') {
+                  finishReject(new Error(res.reason || 'Payment failed'));
+                  return;
+                }
+                if (status === 'pending') {
+                  // Charge still recoverable — keep waiting, no give-up budget.
+                  noneStreak = 0;
+                  errorStreak = 0;
+                  recoverTimer = setTimeout(poll, pollMs);
+                  return;
+                }
+                // 'none' or unknown — host is confident no charge exists. Confirm
+                // twice (guards a host that simply hasn't recorded yet) then reject.
+                errorStreak = 0;
+                noneStreak += 1;
+                if (noneStreak >= 2) {
+                  finishReject(new Error('Payment confirmation timeout'));
+                  return;
+                }
+                recoverTimer = setTimeout(poll, pollMs);
+              }).catch(function() {
+                // Host didn't answer the query (e.g. an older host shell without
+                // PAYMENT_RESULT_QUERY support). Retry a bounded number of times,
+                // then fall back to the original timeout rejection.
+                if (settled) return;
+                errorStreak += 1;
+                if (errorStreak >= maxPolls) {
+                  finishReject(new Error('Payment confirmation timeout'));
+                  return;
+                }
+                recoverTimer = setTimeout(poll, pollMs);
+              });
+            }
+
+            poll();
+          }
+
           window.addEventListener('message', handler);
-          const timer = setTimeout(function() {
-            window.removeEventListener('message', handler);
-            reject(new Error('Payment confirmation timeout'));
-          }, timeoutMs);
+          const timer = setTimeout(recoverPaymentResult, timeoutMs);
 
           // Send payment request
           Usion._post({
@@ -516,7 +683,8 @@ var Usion = (function () {
             _requestId: requestId,
             amount: amount,
             reason: reason,
-            data: data
+            data: data,
+            idempotencyKey: idempotencyKey || undefined,
           });
         });
       },

package/src/modules/core.js

@@ -189,10 +189,56 @@ export const core = {
       }
     });
 
+    // Report the user's first real interaction to the host (see below).
+    this._setupInteractionBeacon();
+
     // Signal ready to parent
     this._post({ type: 'READY' });
   },
 
+  /**
+   * Tell the host the moment the user FIRST genuinely interacts with the
+   * mini-app — a tap, click, key press, or touch — and only once.
+   *
+   * The host uses this as the SOLE signal to surface the mini-app in the user's
+   * chat list — only after real engagement (opening alone, and automatic
+   * load-time SDK calls, never count). It works for a fully self-contained
+   * app/game that never calls any other SDK method: no `Usion.*` call is
+   * required for the host to know the user is engaged.
+   *
+   * Standalone (non-embedded) apps are unaffected — `_post` no-ops when there
+   * is no host. Note: input that produces no DOM gesture (pure device-motion,
+   * gamepad) won't trigger this until the first tap/click/key.
+   * @private
+   */
+  _setupInteractionBeacon: function() {
+    const self = this;
+    if (self._interactionBeaconSetup) return;
+    self._interactionBeaconSetup = true;
+    if (typeof window === 'undefined' || !window.addEventListener) return;
+
+    const events = ['pointerdown', 'mousedown', 'touchstart', 'keydown'];
+    function fire(event) {
+      // Only count real user gestures, never programmatically dispatched ones.
+      if (event && event.isTrusted === false) return;
+      if (self._interactionReported) return;
+      self._interactionReported = true;
+      for (let i = 0; i < events.length; i++) {
+        try { window.removeEventListener(events[i], fire, true); } catch (e) { /* noop */ }
+      }
+      self._post({ type: 'USER_INTERACTION' });
+    }
+    for (let i = 0; i < events.length; i++) {
+      // Capture phase + passive so we observe the gesture without interfering
+      // with the app's own handlers or scroll performance.
+      try {
+        window.addEventListener(events[i], fire, { capture: true, passive: true });
+      } catch (e) {
+        try { window.addEventListener(events[i], fire, true); } catch (e2) { /* noop */ }
+      }
+    }
+  },
+
   /**
    * Get the current theme ('light' or 'dark')
    * @returns {string}

package/src/modules/wallet.js

@@ -12,6 +12,13 @@ export function createWalletModule(Usion) {
     _balance: null,
     _balanceChangeHandler: null,
 
+    // Payment timing knobs (overridable, mainly for tests). The defaults are
+    // the production values.
+    _paymentTimeoutMs: 60000,      // wait this long for the direct PAYMENT_SUCCESS
+    _recoveryPollMs: 2000,         // gap between result-recovery re-queries
+    _recoveryMaxPolls: 10,         // bounded recovery window after the timeout
+    _recoveryQueryTimeoutMs: 8000, // per re-query round-trip budget
+
     /**
      * Get current wallet balance
      * @returns {Promise<number>} Balance in credits
@@ -42,20 +49,69 @@ export function createWalletModule(Usion) {
     },
 
     /**
-     * Request payment from user with balance check
+     * Request payment from user with balance check.
+     *
+     * The charge is debited immediately by the host (escrow); the resolved
+     * value carries a `receiptToken` the mini-app server later settles/refunds.
+     *
+     * Reliability: if the host's PAYMENT_SUCCESS message is lost (network blip,
+     * backgrounded tab, race) the user may ALREADY be charged. Instead of
+     * rejecting at the timeout, this re-queries the host for the result and
+     * recovers the receipt token — so a dropped message never strands a paid
+     * charge. Pass `idempotencyKey` to additionally guarantee that any retry of
+     * the SAME intent reuses the SAME charge (the host + backend dedupe on it),
+     * so the user can never be charged twice even across reloads.
+     *
      * @param {number} amount - Credit amount to charge
      * @param {string} reason - Description shown to user
-     * @param {object} data - Optional additional data
+     * @param {object} [data] - Optional options/payload. `data.idempotencyKey`
+     *   (string) makes the charge safely retryable. Any other fields are
+     *   forwarded to the host verbatim (backward compatible).
      * @returns {Promise} Resolves on payment success, rejects on failure
      */
     requestPayment: function(amount, reason, data) {
       const self = this;
 
+      const opts = (data && typeof data === 'object') ? data : null;
+      const idempotencyKey = (opts && typeof opts.idempotencyKey === 'string' && opts.idempotencyKey)
+        ? opts.idempotencyKey
+        : null;
+
       return new Promise(function(resolve, reject) {
         const requestId = getNextRequestId();
-        const timeoutMs = 60000;
+        const timeoutMs = self._paymentTimeoutMs || 60000;
+        let settled = false;
+        let recoverTimer = null;
+
+        function cleanup() {
+          clearTimeout(timer);
+          if (recoverTimer) clearTimeout(recoverTimer);
+          window.removeEventListener('message', handler);
+        }
+
+        function finishResolve(response) {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          // Update cached balance from the authoritative new balance, else
+          // best-effort subtract (no-op if balance is unknown).
+          if (response && response.newBalance !== undefined) {
+            self._balance = response.newBalance;
+          } else if (self._balance !== null) {
+            self._balance -= amount;
+          }
+          resolve(response);
+        }
 
-        // Listen for response
+        function finishReject(error) {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(error);
+        }
+
+        // Direct response from the host. Kept registered through the recovery
+        // window so a late PAYMENT_SUCCESS still resolves.
         function handler(event) {
           // Only honor payment results from the trusted host shell — a forged
           // PAYMENT_SUCCESS must never resolve this promise.
@@ -69,32 +125,97 @@ export function createWalletModule(Usion) {
           }
 
           // Only accept responses for this specific payment request.
-          if (response._requestId !== requestId) {
+          if (!response || response._requestId !== requestId) {
             return;
           }
 
           if (response.type === 'PAYMENT_SUCCESS') {
-            clearTimeout(timer);
-            window.removeEventListener('message', handler);
-            // Update cached balance
-            if (response.newBalance !== undefined) {
-              self._balance = response.newBalance;
-            } else if (self._balance !== null) {
-              self._balance -= amount;
-            }
-            resolve(response);
+            finishResolve(response);
           } else if (response.type === 'PAYMENT_FAILED') {
-            clearTimeout(timer);
-            window.removeEventListener('message', handler);
-            reject(new Error(response.reason || 'Payment failed'));
+            finishReject(new Error(response.reason || 'Payment failed'));
+          }
+        }
+
+        // After the direct deadline, re-query the host for this payment's
+        // result instead of rejecting.
+        //   succeeded -> resolve with the recovered token
+        //   failed    -> reject
+        //   pending   -> the modal is STILL OPEN / charge still in progress, so
+        //                the charge is fully recoverable: keep waiting (do NOT
+        //                count this toward the give-up cap). A slow user who
+        //                confirms minutes later still resolves — via the next
+        //                'succeeded' poll or the direct handler, which stays
+        //                registered. Without this, a charge made after we gave
+        //                up would be stranded (the original bug, shifted to the
+        //                slow-confirm case).
+        //   none/other -> likely no charge; confirm twice then reject cleanly so
+        //                a fresh requestPayment is safe.
+        // The bounded cap only governs the give-up paths (none-streak and a host
+        // that never answers the query at all, e.g. an older host shell).
+        function recoverPaymentResult() {
+          const pollMs = self._recoveryPollMs || 2000;
+          const maxPolls = self._recoveryMaxPolls || 10;
+          const queryTimeoutMs = self._recoveryQueryTimeoutMs || 8000;
+          let noneStreak = 0;
+          let errorStreak = 0;
+
+          function poll() {
+            if (settled) return;
+            Usion._request('PAYMENT_RESULT_QUERY', {
+              paymentRequestId: requestId,
+              idempotencyKey: idempotencyKey || undefined,
+            }, queryTimeoutMs).then(function(res) {
+              if (settled) return;
+              const status = res && res.status;
+              if (status === 'succeeded') {
+                finishResolve({
+                  type: 'PAYMENT_SUCCESS',
+                  _requestId: requestId,
+                  newBalance: res.newBalance,
+                  transactionId: res.transactionId,
+                  receiptToken: res.receiptToken,
+                });
+                return;
+              }
+              if (status === 'failed') {
+                finishReject(new Error(res.reason || 'Payment failed'));
+                return;
+              }
+              if (status === 'pending') {
+                // Charge still recoverable — keep waiting, no give-up budget.
+                noneStreak = 0;
+                errorStreak = 0;
+                recoverTimer = setTimeout(poll, pollMs);
+                return;
+              }
+              // 'none' or unknown — host is confident no charge exists. Confirm
+              // twice (guards a host that simply hasn't recorded yet) then reject.
+              errorStreak = 0;
+              noneStreak += 1;
+              if (noneStreak >= 2) {
+                finishReject(new Error('Payment confirmation timeout'));
+                return;
+              }
+              recoverTimer = setTimeout(poll, pollMs);
+            }).catch(function() {
+              // Host didn't answer the query (e.g. an older host shell without
+              // PAYMENT_RESULT_QUERY support). Retry a bounded number of times,
+              // then fall back to the original timeout rejection.
+              if (settled) return;
+              errorStreak += 1;
+              if (errorStreak >= maxPolls) {
+                finishReject(new Error('Payment confirmation timeout'));
+                return;
+              }
+              recoverTimer = setTimeout(poll, pollMs);
+            });
           }
+
+          poll();
         }
 
         window.addEventListener('message', handler);
-        const timer = setTimeout(function() {
-          window.removeEventListener('message', handler);
-          reject(new Error('Payment confirmation timeout'));
-        }, timeoutMs);
+        const timer = setTimeout(recoverPaymentResult, timeoutMs);
 
         // Send payment request
         Usion._post({
@@ -102,7 +223,8 @@ export function createWalletModule(Usion) {
           _requestId: requestId,
           amount: amount,
           reason: reason,
-          data: data
+          data: data,
+          idempotencyKey: idempotencyKey || undefined,
         });
       });
     },

package/types/index.d.ts

@@ -43,6 +43,17 @@ export interface PaymentResponse {
   transactionId?: string;
 }
 
+export interface PaymentOptions {
+  /**
+   * Optional idempotency key. When set, the host + backend dedupe on it so any
+   * retry of the SAME intent (network error, reload, double-tap) reuses the
+   * SAME charge instead of debiting again, and returns the same receiptToken.
+   * Omit for the legacy one-shot behavior.
+   */
+  idempotencyKey?: string;
+  [key: string]: any;
+}
+
 // ─── User ────────────────────────────────────────────────────────
 
 export interface UserProfile {
@@ -82,7 +93,7 @@ export interface FileStorageModule {
 export interface WalletModule {
   getBalance(): Promise<number>;
   hasCredits(amount: number): Promise<boolean>;
-  requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
+  requestPayment(amount: number, reason: string, data?: PaymentOptions): Promise<PaymentResponse>;
   onBalanceChange(callback: (balance: number) => void): UnsubscribeFn;
 }
 
@@ -768,7 +779,7 @@ export interface UsionSDK {
   getLaunchParams(): { path: string | null; ref: string | null; roomId: string | null };
 
   // Payments
-  requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
+  requestPayment(amount: number, reason: string, data?: PaymentOptions): Promise<PaymentResponse>;
 
   // Service communication
   submit(data: Record<string, any>): void;