@usions/sdk 2.17.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.17.0",
+  "version": "2.19.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.17.0', // injected from package.json at build
+    version: '2.19.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,
       };
     },
 
@@ -2346,6 +2357,72 @@ var Usion = (function () {
       });
     };
 
+    /**
+     * Invite friends to play in your room — like asking for money, but for players.
+     *
+     * Opens the host's friend/group picker (recent chats + search any user by
+     * username + your groups, multi-select). Everyone you pick gets a game-invite
+     * card in their chat; anyone who taps it joins THIS room and your game
+     * receives `onPlayerJoined`.
+     *
+     * Works for any multiplayer-capable game. If the game was opened solo (from
+     * Explore / the Game hub) with no room yet, the host creates one with you as
+     * host and this method joins you to it — so register `onPlayerJoined` before
+     * or right after calling invite(). Capacity is bounded by the game's
+     * `max_players`; the picker caps selection at the remaining seats.
+     *
+     * Embedded feature (the host renders the picker). Standalone resolves
+     * `{ success: false }`. Never rejects.
+     *
+     * @param {{ maxPlayers?: number, timeout?: number }} [opts]
+     * @returns {Promise<{ success: boolean, roomId: string|null, invited: string[] }>}
+     */
+    game.invite = function(opts) {
+      const self = this;
+      opts = opts || {};
+
+      const embedded = typeof window !== 'undefined' &&
+        (!!window.ReactNativeWebView ||
+         (!!window.parent && window.parent !== window));
+
+      const currentRoom = self.roomId || (Usion.config && Usion.config.roomId) || null;
+
+      if (!embedded) {
+        try { console.warn('[Usion] game.invite needs the Usion app; resolving as not sent.'); } catch (e) { /* noop */ }
+        return Promise.resolve({ success: false, roomId: currentRoom, invited: [] });
+      }
+
+      const reqData = { roomId: currentRoom };
+      if (typeof opts.maxPlayers === 'number' && opts.maxPlayers > 0) {
+        reqData.maxPlayers = opts.maxPlayers;
+      }
+
+      // Long timeout — the user may sit in the picker. Never reject: a dropped
+      // result must not throw inside the game (mirrors permissions.request).
+      return Usion._request('GAME_INVITE_REQUEST', reqData, opts.timeout || 120000)
+        .then(function(res) {
+          res = res || {};
+          const roomId = res.roomId || currentRoom || null;
+          const result = {
+            success: !!res.success,
+            roomId: roomId,
+            invited: Array.isArray(res.invited) ? res.invited : [],
+          };
+          if (!result.success || !roomId) return result;
+          // Ensure the inviter is connected + joined to the room (as host) so
+          // they get onPlayerJoined as invitees arrive. Idempotent when the game
+          // is already in this room; invites were sent by the host regardless.
+          return Promise.resolve()
+            .then(function() { return self.connect(); })
+            .then(function() { return self.join(roomId); })
+            .then(function() { return result; })
+            .catch(function() { return result; });
+        })
+        .catch(function() {
+          return { success: false, roomId: currentRoom, invited: [] };
+        });
+    };
+
     /**
      * Disconnect from the game socket
      */
@@ -2507,6 +2584,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}

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

@@ -406,6 +406,72 @@ export function applyGameMethods(game, Usion) {
     });
   };
 
+  /**
+   * Invite friends to play in your room — like asking for money, but for players.
+   *
+   * Opens the host's friend/group picker (recent chats + search any user by
+   * username + your groups, multi-select). Everyone you pick gets a game-invite
+   * card in their chat; anyone who taps it joins THIS room and your game
+   * receives `onPlayerJoined`.
+   *
+   * Works for any multiplayer-capable game. If the game was opened solo (from
+   * Explore / the Game hub) with no room yet, the host creates one with you as
+   * host and this method joins you to it — so register `onPlayerJoined` before
+   * or right after calling invite(). Capacity is bounded by the game's
+   * `max_players`; the picker caps selection at the remaining seats.
+   *
+   * Embedded feature (the host renders the picker). Standalone resolves
+   * `{ success: false }`. Never rejects.
+   *
+   * @param {{ maxPlayers?: number, timeout?: number }} [opts]
+   * @returns {Promise<{ success: boolean, roomId: string|null, invited: string[] }>}
+   */
+  game.invite = function(opts) {
+    const self = this;
+    opts = opts || {};
+
+    const embedded = typeof window !== 'undefined' &&
+      (!!window.ReactNativeWebView ||
+       (!!window.parent && window.parent !== window));
+
+    const currentRoom = self.roomId || (Usion.config && Usion.config.roomId) || null;
+
+    if (!embedded) {
+      try { console.warn('[Usion] game.invite needs the Usion app; resolving as not sent.'); } catch (e) { /* noop */ }
+      return Promise.resolve({ success: false, roomId: currentRoom, invited: [] });
+    }
+
+    const reqData = { roomId: currentRoom };
+    if (typeof opts.maxPlayers === 'number' && opts.maxPlayers > 0) {
+      reqData.maxPlayers = opts.maxPlayers;
+    }
+
+    // Long timeout — the user may sit in the picker. Never reject: a dropped
+    // result must not throw inside the game (mirrors permissions.request).
+    return Usion._request('GAME_INVITE_REQUEST', reqData, opts.timeout || 120000)
+      .then(function(res) {
+        res = res || {};
+        const roomId = res.roomId || currentRoom || null;
+        const result = {
+          success: !!res.success,
+          roomId: roomId,
+          invited: Array.isArray(res.invited) ? res.invited : [],
+        };
+        if (!result.success || !roomId) return result;
+        // Ensure the inviter is connected + joined to the room (as host) so
+        // they get onPlayerJoined as invitees arrive. Idempotent when the game
+        // is already in this room; invites were sent by the host regardless.
+        return Promise.resolve()
+          .then(function() { return self.connect(); })
+          .then(function() { return self.join(roomId); })
+          .then(function() { return result; })
+          .catch(function() { return result; });
+      })
+      .catch(function() {
+        return { success: false, roomId: currentRoom, invited: [] };
+      });
+  };
+
   /**
    * Disconnect from the game socket
    */
@@ -567,6 +633,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/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 ─────────────────────────────────────────────────────
@@ -250,12 +256,36 @@ export interface RematchData {
   player_id: string;
 }
 
+/** Options for game.invite(). */
+export interface GameInviteOptions {
+  /** Cap the room at this many players (otherwise the game's max_players). */
+  maxPlayers?: number;
+  /** Max ms to wait for the user to finish in the picker (default 120000). */
+  timeout?: number;
+}
+
+/** Result of game.invite(). */
+export interface GameInviteResult {
+  /** True if the user sent at least one invite. */
+  success: boolean;
+  /** The room invitees will join (you are host); null if nothing was sent. */
+  roomId: string | null;
+  /** User/group ids the invite was sent to. */
+  invited: string[];
+}
+
 export interface GameModule {
   // Connection
   connect(socketUrl?: string, token?: string): Promise<void>;
   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
   //
@@ -280,6 +310,17 @@ export interface GameModule {
   requestRematch(): void;
   forfeit(): Promise<{ success: boolean; error?: string }>;
 
+  /**
+   * Invite friends to play in your room. Opens the host's friend/group picker
+   * (recent chats + username search + your groups, multi-select); each pick gets
+   * a game-invite card in their chat, and anyone who taps it joins THIS room
+   * (your game gets `onPlayerJoined`). Works for any multiplayer-capable game —
+   * if launched solo with no room, the host creates one with you as host and
+   * this joins you to it. Embedded only; standalone resolves `{success:false}`.
+   * Never rejects. (SDK ≥ 2.19)
+   */
+  invite(opts?: GameInviteOptions): Promise<GameInviteResult>;
+
   /**
    * Checkpoint authoritative game state on the server (authority only —
    * player_ids[0]/host). (Re)joining clients receive the latest checkpoint
@@ -774,9 +815,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>;