@usions/sdk 2.14.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.14.0",
+  "version": "2.17.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.14.0', // injected from package.json at build
+    version: '2.17.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}
@@ -5044,6 +5090,163 @@ var Usion = (function () {
     };
   }
 
+  /**
+   * Usion SDK Permissions — a mini-app asks the user to allow capabilities.
+   *
+   * Works exactly like asking for money: the app requests, the HOST shows a modal,
+   * the user **allows or cancels**, and the result flows back. The user can later
+   * change any grant in the Usion app's settings for this app.
+   *
+   *   const res = await Usion.permissions.request(['notifications']);
+   *   if (res.permissions.notifications) { ... }     // granted
+   *
+   *   const state = await Usion.permissions.query(['notifications']);
+   *   const ok    = await Usion.permissions.has('notifications');
+   *
+   * Permissions are enforced by the PLATFORM, not by this return value — e.g.
+   * `Usion.notify.send` is dropped (`delivered: 'blocked'`) until the user grants
+   * `notifications`. So the pattern is: request first, then notify.
+   *
+   * This is an EMBEDDED feature. Running standalone (outside the Usion host) there
+   * is no modal — request()/query() resolve to a benign "not granted" default and
+   * the user manages the grant inside the Usion app.
+   */
+
+  function createPermissionsModule(Usion) {
+    function normalizeList(perms) {
+      if (typeof perms === 'string') return perms ? [perms] : [];
+      if (Array.isArray(perms)) {
+        return perms.filter(function (p) { return typeof p === 'string' && p; });
+      }
+      return [];
+    }
+
+    function isEmbedded() {
+      return typeof window !== 'undefined' &&
+        (!!window.ReactNativeWebView || (!!window.parent && window.parent !== window));
+    }
+
+    function denyAll(list) {
+      const out = {};
+      list.forEach(function (p) { out[p] = false; });
+      return out;
+    }
+
+    function summarize(list, map) {
+      const perms = map || {};
+      const granted = list.length > 0 && list.every(function (p) { return !!perms[p]; });
+      return { granted: granted, permissions: perms };
+    }
+
+    const api = {
+      // How long to wait for the host's PERMISSION_RESULT before falling back to a
+      // state query — the user may sit on the modal. We NEVER reject: a dropped
+      // result must not strand the caller (mirrors wallet.requestPayment recovery).
+      // Overridable, mainly for tests.
+      _requestTimeoutMs: 120000,
+
+      /**
+       * Ask the user to allow one or more permissions. Shows the host modal
+       * (unless every requested permission is already granted, in which case the
+       * host resolves immediately).
+       *
+       * @param {string|string[]} permissions e.g. 'notifications' or ['notifications']
+       * @param {{reason?: string}} [opts] optional one-line context shown in the modal
+       * @returns {Promise<{granted: boolean, permissions: Object}>}
+       *   `granted` is true only if EVERY requested permission ended granted;
+       *   `permissions` maps each requested key to its resulting boolean state.
+       */
+      request: function (permissions, opts) {
+        const list = normalizeList(permissions);
+        const reason = (opts && typeof opts.reason === 'string') ? opts.reason : undefined;
+
+        if (!isEmbedded()) {
+          try { console.warn('[Usion] permissions.request needs the Usion app; resolving as not granted.'); } catch (e) { /* noop */ }
+          return Promise.resolve(summarize(list, denyAll(list)));
+        }
+
+        return new Promise(function (resolve) {
+          const requestId = getNextRequestId();
+          let settled = false;
+          let timer = null;
+
+          function cleanup() {
+            if (timer) clearTimeout(timer);
+            window.removeEventListener('message', handler);
+          }
+
+          function finish(result) {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            resolve(result);
+          }
+
+          function handler(event) {
+            // Only honor results from the trusted host shell. (A forged result can
+            // only mislead this app's UI — the backend gate is the real guard.)
+            if (!isTrustedMessageSource(event)) return;
+            let response;
+            try {
+              response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+            } catch (e) { return; }
+            if (!response || response._requestId !== requestId) return;
+            if (response.type === 'PERMISSION_RESULT') {
+              finish(summarize(list, response.permissions));
+            }
+          }
+
+          window.addEventListener('message', handler);
+
+          // Host never answered (lost message / older host shell): fall back to the
+          // current persisted state so we still resolve with the truth.
+          timer = setTimeout(function () {
+            if (settled) return;
+            api.query(list).then(function (map) {
+              finish(summarize(list, map));
+            }).catch(function () {
+              finish(summarize(list, denyAll(list)));
+            });
+          }, api._requestTimeoutMs || 120000);
+
+          Usion._post({
+            type: 'PERMISSION_REQUEST',
+            _requestId: requestId,
+            permissions: list,
+            reason: reason,
+          });
+        });
+      },
+
+      /**
+       * Read current permission state WITHOUT prompting the user.
+       * @param {string|string[]} [permissions]
+       * @returns {Promise<Object>} map of permission key -> boolean (granted)
+       */
+      query: function (permissions) {
+        const list = normalizeList(permissions);
+        if (!isEmbedded()) {
+          return Promise.resolve(denyAll(list));
+        }
+        return Usion._request('PERMISSION_QUERY', { permissions: list }, 8000)
+          .then(function (res) { return (res && res.permissions) || {}; });
+      },
+
+      /**
+       * Convenience: is a single permission currently granted?
+       * @param {string} permission
+       * @returns {Promise<boolean>}
+       */
+      has: function (permission) {
+        return api.query([permission]).then(function (map) {
+          return !!(map && map[permission]);
+        });
+      },
+    };
+
+    return api;
+  }
+
   /**
    * Usion SDK — unified backend channel.
    *
@@ -5182,6 +5385,8 @@ var Usion = (function () {
   Usion.cloud = createCloudModule(Usion);
   Usion.matchmaking = createMatchmakingModule(Usion);
   Usion.notify = createNotifyModule(Usion);
+  // Permission requests (host-mediated modal; embedded feature).
+  Usion.permissions = createPermissionsModule(Usion);
 
   // Netcode toolkit (transport-agnostic, zero-dependency).
   Usion.netcode = netcode;

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/index.js

@@ -30,6 +30,7 @@ import { createLeaderboardModule } from './leaderboard.js';
 import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.js';
 import { createNotifyModule } from './notify.js';
+import { createPermissionsModule } from './permissions.js';
 import { applyBackendChannel } from './backend-channel.js';
 import { netcode } from './netcode/index.js';
 import { UsionError, ERROR_CODES } from './errors.js';
@@ -56,6 +57,8 @@ Usion.leaderboard = createLeaderboardModule(Usion);
 Usion.cloud = createCloudModule(Usion);
 Usion.matchmaking = createMatchmakingModule(Usion);
 Usion.notify = createNotifyModule(Usion);
+// Permission requests (host-mediated modal; embedded feature).
+Usion.permissions = createPermissionsModule(Usion);
 
 // Netcode toolkit (transport-agnostic, zero-dependency).
 Usion.netcode = netcode;

package/src/modules/permissions.js

@@ -0,0 +1,157 @@
+/**
+ * Usion SDK Permissions — a mini-app asks the user to allow capabilities.
+ *
+ * Works exactly like asking for money: the app requests, the HOST shows a modal,
+ * the user **allows or cancels**, and the result flows back. The user can later
+ * change any grant in the Usion app's settings for this app.
+ *
+ *   const res = await Usion.permissions.request(['notifications']);
+ *   if (res.permissions.notifications) { ... }     // granted
+ *
+ *   const state = await Usion.permissions.query(['notifications']);
+ *   const ok    = await Usion.permissions.has('notifications');
+ *
+ * Permissions are enforced by the PLATFORM, not by this return value — e.g.
+ * `Usion.notify.send` is dropped (`delivered: 'blocked'`) until the user grants
+ * `notifications`. So the pattern is: request first, then notify.
+ *
+ * This is an EMBEDDED feature. Running standalone (outside the Usion host) there
+ * is no modal — request()/query() resolve to a benign "not granted" default and
+ * the user manages the grant inside the Usion app.
+ */
+import { getNextRequestId, isTrustedMessageSource } from './core.js';
+
+export function createPermissionsModule(Usion) {
+  function normalizeList(perms) {
+    if (typeof perms === 'string') return perms ? [perms] : [];
+    if (Array.isArray(perms)) {
+      return perms.filter(function (p) { return typeof p === 'string' && p; });
+    }
+    return [];
+  }
+
+  function isEmbedded() {
+    return typeof window !== 'undefined' &&
+      (!!window.ReactNativeWebView || (!!window.parent && window.parent !== window));
+  }
+
+  function denyAll(list) {
+    const out = {};
+    list.forEach(function (p) { out[p] = false; });
+    return out;
+  }
+
+  function summarize(list, map) {
+    const perms = map || {};
+    const granted = list.length > 0 && list.every(function (p) { return !!perms[p]; });
+    return { granted: granted, permissions: perms };
+  }
+
+  const api = {
+    // How long to wait for the host's PERMISSION_RESULT before falling back to a
+    // state query — the user may sit on the modal. We NEVER reject: a dropped
+    // result must not strand the caller (mirrors wallet.requestPayment recovery).
+    // Overridable, mainly for tests.
+    _requestTimeoutMs: 120000,
+
+    /**
+     * Ask the user to allow one or more permissions. Shows the host modal
+     * (unless every requested permission is already granted, in which case the
+     * host resolves immediately).
+     *
+     * @param {string|string[]} permissions e.g. 'notifications' or ['notifications']
+     * @param {{reason?: string}} [opts] optional one-line context shown in the modal
+     * @returns {Promise<{granted: boolean, permissions: Object}>}
+     *   `granted` is true only if EVERY requested permission ended granted;
+     *   `permissions` maps each requested key to its resulting boolean state.
+     */
+    request: function (permissions, opts) {
+      const list = normalizeList(permissions);
+      const reason = (opts && typeof opts.reason === 'string') ? opts.reason : undefined;
+
+      if (!isEmbedded()) {
+        try { console.warn('[Usion] permissions.request needs the Usion app; resolving as not granted.'); } catch (e) { /* noop */ }
+        return Promise.resolve(summarize(list, denyAll(list)));
+      }
+
+      return new Promise(function (resolve) {
+        const requestId = getNextRequestId();
+        let settled = false;
+        let timer = null;
+
+        function cleanup() {
+          if (timer) clearTimeout(timer);
+          window.removeEventListener('message', handler);
+        }
+
+        function finish(result) {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve(result);
+        }
+
+        function handler(event) {
+          // Only honor results from the trusted host shell. (A forged result can
+          // only mislead this app's UI — the backend gate is the real guard.)
+          if (!isTrustedMessageSource(event)) return;
+          let response;
+          try {
+            response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+          } catch (e) { return; }
+          if (!response || response._requestId !== requestId) return;
+          if (response.type === 'PERMISSION_RESULT') {
+            finish(summarize(list, response.permissions));
+          }
+        }
+
+        window.addEventListener('message', handler);
+
+        // Host never answered (lost message / older host shell): fall back to the
+        // current persisted state so we still resolve with the truth.
+        timer = setTimeout(function () {
+          if (settled) return;
+          api.query(list).then(function (map) {
+            finish(summarize(list, map));
+          }).catch(function () {
+            finish(summarize(list, denyAll(list)));
+          });
+        }, api._requestTimeoutMs || 120000);
+
+        Usion._post({
+          type: 'PERMISSION_REQUEST',
+          _requestId: requestId,
+          permissions: list,
+          reason: reason,
+        });
+      });
+    },
+
+    /**
+     * Read current permission state WITHOUT prompting the user.
+     * @param {string|string[]} [permissions]
+     * @returns {Promise<Object>} map of permission key -> boolean (granted)
+     */
+    query: function (permissions) {
+      const list = normalizeList(permissions);
+      if (!isEmbedded()) {
+        return Promise.resolve(denyAll(list));
+      }
+      return Usion._request('PERMISSION_QUERY', { permissions: list }, 8000)
+        .then(function (res) { return (res && res.permissions) || {}; });
+    },
+
+    /**
+     * Convenience: is a single permission currently granted?
+     * @param {string} permission
+     * @returns {Promise<boolean>}
+     */
+    has: function (permission) {
+      return api.query([permission]).then(function (map) {
+        return !!(map && map[permission]);
+      });
+    },
+  };
+
+  return api;
+}

package/types/index.d.ts

@@ -857,6 +857,7 @@ export interface UsionSDK {
   matchmaking: MatchmakingModule;
   cloud: CloudModule;
   notify: NotifyModule;
+  permissions: PermissionsModule;
   netcode: NetcodeModule;
 }
 
@@ -874,6 +875,29 @@ export interface NotifyModule {
   isMuted(opts?: { serviceId?: string }): Promise<boolean>;
 }
 
+/** Result of a permission request: per-key state + whether ALL were granted. */
+export interface PermissionResult {
+  /** True only if every requested permission ended granted. */
+  granted: boolean;
+  /** Map of each requested permission key to its resulting state. */
+  permissions: Record<string, boolean>;
+}
+
+/**
+ * Ask the user to allow capabilities (the host shows a modal — like asking for
+ * money). The platform enforces grants: e.g. `notify.send` is dropped until
+ * `notifications` is granted. Embedded feature; standalone resolves "not
+ * granted". Permission keys today: `'notifications'`.
+ */
+export interface PermissionsModule {
+  /** Prompt the user to allow one or more permissions. */
+  request(permissions: string | string[], opts?: { reason?: string }): Promise<PermissionResult>;
+  /** Read current state without prompting; map of key -> granted. */
+  query(permissions?: string | string[]): Promise<Record<string, boolean>>;
+  /** Convenience: is a single permission currently granted? */
+  has(permission: 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. */