@usions/sdk 2.13.0 → 2.14.0

package/package.json

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

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.14.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -426,6 +426,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 +463,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);
+          }
 
-          // Listen for response
+          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);
+          }
+
+          // 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 +539,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 +637,8 @@ var Usion = (function () {
             _requestId: requestId,
             amount: amount,
             reason: reason,
-            data: data
+            data: data,
+            idempotencyKey: idempotencyKey || undefined,
           });
         });
       },

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;