@usions/sdk 2.16.0 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.16.0",
+  "version": "2.18.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.16.0', // injected from package.json at build
+    version: '2.18.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -263,14 +263,25 @@ var Usion = (function () {
      * 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 }}
+     *
+     * `mode` is how the app was launched: `'single'` (opened from Explore / the
+     * Game hub, played solo) or `'multiplayer'` (opened from a game invite in a
+     * chat, played with another person). The host declares it authoritatively;
+     * branch on it to skip lobby/matchmaking UI in single-player or wire up
+     * netcode in multiplayer. When the host doesn't declare a mode (legacy hosts
+     * or a standalone URL), it falls back to "a room means multiplayer".
+     * @returns {{ path: string|null, ref: string|null, roomId: string|null, mode: 'single'|'multiplayer' }}
      */
     getLaunchParams: function() {
       var c = this.config || {};
+      var mode = (c.mode === 'single' || c.mode === 'multiplayer')
+        ? c.mode
+        : (c.roomId ? 'multiplayer' : 'single');
       return {
         path: c.launchPath || null,
         ref: c.ref || c.launchRef || null,
         roomId: c.roomId || null,
+        mode: mode,
       };
     },
 
@@ -2507,6 +2518,17 @@ var Usion = (function () {
       } catch (e) { /* non-fatal */ }
     };
 
+    /**
+     * Whether this app was launched in multiplayer mode (opened from a game
+     * invite in a chat) rather than single-player (opened from Explore / the
+     * Game hub). Convenience wrapper over Usion.getLaunchParams().mode — use it
+     * to branch setup, e.g. skip matchmaking and run solo when false.
+     * @returns {boolean}
+     */
+    game.isMultiplayer = function() {
+      return Usion.getLaunchParams().mode === 'multiplayer';
+    };
+
     /**
      * Get connection status
      * @returns {boolean}
@@ -5090,6 +5112,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.
    *
@@ -5228,6 +5407,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

@@ -260,14 +260,25 @@ export const core = {
    * 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 }}
+   *
+   * `mode` is how the app was launched: `'single'` (opened from Explore / the
+   * Game hub, played solo) or `'multiplayer'` (opened from a game invite in a
+   * chat, played with another person). The host declares it authoritatively;
+   * branch on it to skip lobby/matchmaking UI in single-player or wire up
+   * netcode in multiplayer. When the host doesn't declare a mode (legacy hosts
+   * or a standalone URL), it falls back to "a room means multiplayer".
+   * @returns {{ path: string|null, ref: string|null, roomId: string|null, mode: 'single'|'multiplayer' }}
    */
   getLaunchParams: function() {
     var c = this.config || {};
+    var mode = (c.mode === 'single' || c.mode === 'multiplayer')
+      ? c.mode
+      : (c.roomId ? 'multiplayer' : 'single');
     return {
       path: c.launchPath || null,
       ref: c.ref || c.launchRef || null,
       roomId: c.roomId || null,
+      mode: mode,
     };
   },
 

package/src/modules/game-methods.js

@@ -567,6 +567,17 @@ export function applyGameMethods(game, Usion) {
     } catch (e) { /* non-fatal */ }
   };
 
+  /**
+   * Whether this app was launched in multiplayer mode (opened from a game
+   * invite in a chat) rather than single-player (opened from Explore / the
+   * Game hub). Convenience wrapper over Usion.getLaunchParams().mode — use it
+   * to branch setup, e.g. skip matchmaking and run solo when false.
+   * @returns {boolean}
+   */
+  game.isMultiplayer = function() {
+    return Usion.getLaunchParams().mode === 'multiplayer';
+  };
+
   /**
    * Get connection status
    * @returns {boolean}

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

@@ -31,6 +31,12 @@ export interface UsionConfig {
   launchPath?: string;
   /** Referral code the app was opened with, if any. */
   ref?: string;
+  /**
+   * How the app was launched: `'single'` (from Explore / the Game hub, solo)
+   * or `'multiplayer'` (from a game invite in a chat). Read via
+   * `Usion.getLaunchParams().mode`. (SDK ≥ 2.18)
+   */
+  mode?: 'single' | 'multiplayer';
 }
 
 // ─── Payment ─────────────────────────────────────────────────────
@@ -256,6 +262,12 @@ export interface GameModule {
   connectDirect(config?: DirectConnectionConfig): Promise<void>;
   disconnect(): void;
   isConnected(): boolean;
+  /**
+   * Whether the app was launched multiplayer (from a chat game invite) vs
+   * single-player (from Explore / the Game hub). Wrapper over
+   * `Usion.getLaunchParams().mode === 'multiplayer'`. (SDK ≥ 2.18)
+   */
+  isMultiplayer(): boolean;
 
   // Room & actions
   //
@@ -774,9 +786,11 @@ export interface UsionSDK {
   /**
    * 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.
+   * init so the user lands on the right screen. `mode` is `'single'` (opened
+   * from Explore / the Game hub, solo) or `'multiplayer'` (opened from a game
+   * invite in a chat) — branch game setup on it. (mode: SDK ≥ 2.18)
    */
-  getLaunchParams(): { path: string | null; ref: string | null; roomId: string | null };
+  getLaunchParams(): { path: string | null; ref: string | null; roomId: string | null; mode: 'single' | 'multiplayer' };
 
   // Payments
   requestPayment(amount: number, reason: string, data?: PaymentOptions): Promise<PaymentResponse>;
@@ -857,6 +871,7 @@ export interface UsionSDK {
   matchmaking: MatchmakingModule;
   cloud: CloudModule;
   notify: NotifyModule;
+  permissions: PermissionsModule;
   netcode: NetcodeModule;
 }
 
@@ -874,6 +889,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. */