@usions/sdk 2.18.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.18.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.18.0', // injected from package.json at build
+    version: '2.19.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -2357,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
      */

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
    */

package/types/index.d.ts

@@ -256,6 +256,24 @@ 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>;
@@ -292,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