@usions/sdk 2.12.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.12.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.12.0', // injected from package.json at build
+    version: '2.14.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -212,6 +212,22 @@ var Usion = (function () {
       return this.config.language || 'en';
     },
 
+    /**
+     * Launch parameters the host opened this app with. Use `path` to deep-link
+     * to a specific screen — e.g. when the user taps a notification sent via
+     * `Usion.notify.send({ path })`, the app reopens and `getLaunchParams().path`
+     * returns that same path so the app can route to it.
+     * @returns {{ path: string|null, ref: string|null, roomId: string|null }}
+     */
+    getLaunchParams: function() {
+      var c = this.config || {};
+      return {
+        path: c.launchPath || null,
+        ref: c.ref || c.launchRef || null,
+        roomId: c.roomId || null,
+      };
+    },
+
     /**
      * Send message to parent app
      * @private
@@ -410,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
@@ -440,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;
 
-          // Listen for response
+          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);
+          }
+
+          // 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.
@@ -467,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({
@@ -500,7 +637,8 @@ var Usion = (function () {
             _requestId: requestId,
             amount: amount,
             reason: reason,
-            data: data
+            data: data,
+            idempotencyKey: idempotencyKey || undefined,
           });
         });
       },
@@ -4835,6 +4973,77 @@ var Usion = (function () {
     };
   }
 
+  /**
+   * Usion SDK Notify — let a mini-app notify its own user.
+   *
+   * A notification reaches the user even when they aren't looking at the app:
+   *   - online elsewhere in Usion  -> in-app banner
+   *   - offline / app backgrounded -> OS push notification
+   * Tapping it re-opens THIS mini-app, optionally at a specific internal screen
+   * via `path` (read back on launch with `Usion.getLaunchParams().path`).
+   *
+   * Rides the unified backend channel, so it works standalone AND embedded.
+   * Scope & safety: a notification can only target the CURRENT user (you cannot
+   * notify other people from here), and the platform rate-limits per user per
+   * service. Users can silence a service with `setMuted(true)`.
+   *
+   *   await Usion.notify.send({
+   *     title: 'Render complete',
+   *     body: 'Your video is ready to view.',
+   *     path: '/render/abc123',     // optional — deep-links inside the app
+   *   });
+   *
+   *   await Usion.notify.setMuted(true);   // user opts out for this app
+   *   const muted = await Usion.notify.isMuted();
+   *
+   * For server-triggered notifications (e.g. a long-running job finishing while
+   * the app is closed), a mini-app's own backend calls the signed REST endpoint
+   * `POST /services/{id}/notify` instead — see the publishing reference.
+   */
+  function createNotifyModule(Usion) {
+    function serviceId(opts) {
+      return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+    }
+
+    return {
+      /**
+       * Send a notification to the current user.
+       * @param {{title: string, body: string, path?: string, serviceId?: string}} opts
+       * @returns {Promise<{success: boolean, delivered?: string}>}
+       */
+      send: function (opts) {
+        opts = opts || {};
+        return Usion._backendEmit('notify:send', {
+          service_id: serviceId(opts),
+          title: opts.title,
+          body: opts.body,
+          path: opts.path,
+        });
+      },
+
+      /**
+       * Mute (or unmute) notifications from this app for the current user.
+       * @param {boolean} muted
+       * @returns {Promise<{success: boolean, muted: boolean}>}
+       */
+      setMuted: function (muted, opts) {
+        return Usion._backendEmit('notify:set_pref', {
+          service_id: serviceId(opts),
+          muted: !!muted,
+        });
+      },
+
+      /**
+       * Whether the current user has muted notifications from this app.
+       * @returns {Promise<boolean>}
+       */
+      isMuted: function (opts) {
+        return Usion._backendEmit('notify:get_pref', { service_id: serviceId(opts) })
+          .then(function (r) { return !!(r && r.muted); });
+      },
+    };
+  }
+
   /**
    * Usion SDK — unified backend channel.
    *
@@ -4972,6 +5181,7 @@ var Usion = (function () {
   Usion.leaderboard = createLeaderboardModule(Usion);
   Usion.cloud = createCloudModule(Usion);
   Usion.matchmaking = createMatchmakingModule(Usion);
+  Usion.notify = createNotifyModule(Usion);
 
   // Netcode toolkit (transport-agnostic, zero-dependency).
   Usion.netcode = netcode;

package/src/modules/core.js

@@ -209,6 +209,22 @@ export const core = {
     return this.config.language || 'en';
   },
 
+  /**
+   * Launch parameters the host opened this app with. Use `path` to deep-link
+   * to a specific screen — e.g. when the user taps a notification sent via
+   * `Usion.notify.send({ path })`, the app reopens and `getLaunchParams().path`
+   * returns that same path so the app can route to it.
+   * @returns {{ path: string|null, ref: string|null, roomId: string|null }}
+   */
+  getLaunchParams: function() {
+    var c = this.config || {};
+    return {
+      path: c.launchPath || null,
+      ref: c.ref || c.launchRef || null,
+      roomId: c.roomId || null,
+    };
+  },
+
   /**
    * Send message to parent app
    * @private

package/src/modules/index.js

@@ -29,6 +29,7 @@ import { createLobbyModule } from './lobby.js';
 import { createLeaderboardModule } from './leaderboard.js';
 import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.js';
+import { createNotifyModule } from './notify.js';
 import { applyBackendChannel } from './backend-channel.js';
 import { netcode } from './netcode/index.js';
 import { UsionError, ERROR_CODES } from './errors.js';
@@ -54,6 +55,7 @@ Usion.lobby = createLobbyModule(Usion);
 Usion.leaderboard = createLeaderboardModule(Usion);
 Usion.cloud = createCloudModule(Usion);
 Usion.matchmaking = createMatchmakingModule(Usion);
+Usion.notify = createNotifyModule(Usion);
 
 // Netcode toolkit (transport-agnostic, zero-dependency).
 Usion.netcode = netcode;

package/src/modules/notify.js

@@ -0,0 +1,70 @@
+/**
+ * Usion SDK Notify — let a mini-app notify its own user.
+ *
+ * A notification reaches the user even when they aren't looking at the app:
+ *   - online elsewhere in Usion  -> in-app banner
+ *   - offline / app backgrounded -> OS push notification
+ * Tapping it re-opens THIS mini-app, optionally at a specific internal screen
+ * via `path` (read back on launch with `Usion.getLaunchParams().path`).
+ *
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ * Scope & safety: a notification can only target the CURRENT user (you cannot
+ * notify other people from here), and the platform rate-limits per user per
+ * service. Users can silence a service with `setMuted(true)`.
+ *
+ *   await Usion.notify.send({
+ *     title: 'Render complete',
+ *     body: 'Your video is ready to view.',
+ *     path: '/render/abc123',     // optional — deep-links inside the app
+ *   });
+ *
+ *   await Usion.notify.setMuted(true);   // user opts out for this app
+ *   const muted = await Usion.notify.isMuted();
+ *
+ * For server-triggered notifications (e.g. a long-running job finishing while
+ * the app is closed), a mini-app's own backend calls the signed REST endpoint
+ * `POST /services/{id}/notify` instead — see the publishing reference.
+ */
+export function createNotifyModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  return {
+    /**
+     * Send a notification to the current user.
+     * @param {{title: string, body: string, path?: string, serviceId?: string}} opts
+     * @returns {Promise<{success: boolean, delivered?: string}>}
+     */
+    send: function (opts) {
+      opts = opts || {};
+      return Usion._backendEmit('notify:send', {
+        service_id: serviceId(opts),
+        title: opts.title,
+        body: opts.body,
+        path: opts.path,
+      });
+    },
+
+    /**
+     * Mute (or unmute) notifications from this app for the current user.
+     * @param {boolean} muted
+     * @returns {Promise<{success: boolean, muted: boolean}>}
+     */
+    setMuted: function (muted, opts) {
+      return Usion._backendEmit('notify:set_pref', {
+        service_id: serviceId(opts),
+        muted: !!muted,
+      });
+    },
+
+    /**
+     * Whether the current user has muted notifications from this app.
+     * @returns {Promise<boolean>}
+     */
+    isMuted: function (opts) {
+      return Usion._backendEmit('notify:get_pref', { service_id: serviceId(opts) })
+        .then(function (r) { return !!(r && r.muted); });
+    },
+  };
+}

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

@@ -24,6 +24,13 @@ export interface UsionConfig {
   serviceName?: string;
   apiUrl?: string;
   connectionMode?: 'platform' | 'direct';
+  /**
+   * Internal path the host opened this app at — set when the user taps a
+   * notification carrying a `path`. Read via `Usion.getLaunchParams().path`.
+   */
+  launchPath?: string;
+  /** Referral code the app was opened with, if any. */
+  ref?: string;
 }
 
 // ─── Payment ─────────────────────────────────────────────────────
@@ -36,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 {
@@ -75,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;
 }
 
@@ -753,8 +771,15 @@ export interface UsionSDK {
   getTheme(): 'light' | 'dark';
   getLanguage(): string;
 
+  /**
+   * Launch parameters the host opened this app with. `path` is the deep-link
+   * target (e.g. from a tapped `Usion.notify` notification); route to it after
+   * init so the user lands on the right screen.
+   */
+  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;
@@ -831,9 +856,24 @@ export interface UsionSDK {
   leaderboard: LeaderboardModule;
   matchmaking: MatchmakingModule;
   cloud: CloudModule;
+  notify: NotifyModule;
   netcode: NetcodeModule;
 }
 
+/**
+ * Send notifications to the CURRENT user that reopen this app (in-app banner
+ * when online, OS push when offline). `path` deep-links to a screen, read back
+ * via `Usion.getLaunchParams().path`. Rate-limited per user per service.
+ */
+export interface NotifyModule {
+  /** Notify the current user. */
+  send(opts: { title: string; body: string; path?: string; serviceId?: string }): Promise<{ success: boolean; delivered?: string }>;
+  /** Mute/unmute notifications from this app for the current user. */
+  setMuted(muted: boolean, opts?: { serviceId?: string }): Promise<{ success: boolean; muted: boolean }>;
+  /** Whether the current user has muted this app's notifications. */
+  isMuted(opts?: { serviceId?: string }): Promise<boolean>;
+}
+
 /** Scoped server-persisted KV operations (per-user or shared). */
 export interface CloudScope {
   /** Get a value; resolves to null when the key doesn't exist. */