@usions/sdk 2.18.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.18.0",
+  "version": "2.20.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.20.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -190,6 +190,27 @@ var Usion = (function () {
           const h = self._backendHandlers[data.event];
           if (h) h(data.data);
         }
+
+        // Handle a room assigned by the host AFTER launch — the solo→host
+        // promotion path. The user opened the game solo from Explore (launch
+        // mode 'single'), then shared it; the host created a room and tells us
+        // to adopt it so invitees connect to the SAME room and the host starts
+        // receiving onPlayerJoined. No-op when there is no game module.
+        if (data.type === 'GAME_ROOM_ASSIGNED' && data.roomId && self.game) {
+          var _assignedRoom = data.roomId;
+          // Reflect the new room in launch config so getLaunchParams().roomId,
+          // .mode and game.isMultiplayer() all report multiplayer from here on.
+          self.config.roomId = _assignedRoom;
+          self.config.mode = 'multiplayer';
+          // Let a solo game flip to its multiplayer UI before peers arrive.
+          self.game._dispatch('roomAssigned', { roomId: _assignedRoom });
+          // Connect + join so the host is actually in the room. Idempotent when
+          // already connected/joined; non-fatal on failure (the game can retry).
+          Promise.resolve()
+            .then(function() { return self.game.connect(); })
+            .then(function() { return self.game.join(_assignedRoom); })
+            .catch(function() { /* non-fatal */ });
+        }
       });
 
       // Report the user's first real interaction to the host (see below).
@@ -2357,6 +2378,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
      */
@@ -4549,6 +4636,7 @@ var Usion = (function () {
     disconnect: 'disconnect',
     reconnect: 'reconnect',
     connection_error: 'connectionError',
+    room_assigned: 'roomAssigned',
   };
 
   function _normalizeEventName(event) {
@@ -4694,6 +4782,11 @@ var Usion = (function () {
       onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
       onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
       onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+      // Fired when the host assigns this app a room AFTER launch (the user opened
+      // the game solo, then shared it — see GAME_ROOM_ASSIGNED). The SDK has
+      // already updated config.roomId and is connecting+joining; use this to flip
+      // a solo game into its multiplayer/hosting UI. onJoined fires right after.
+      onRoomAssigned: function(callback) { return this._setHandler('roomAssigned', callback); },
 
       /** @private Set the single legacy handler; returns an unsubscribe fn. */
       _setHandler: function(name, callback) {

package/src/modules/core.js

@@ -187,6 +187,27 @@ export const core = {
         const h = self._backendHandlers[data.event];
         if (h) h(data.data);
       }
+
+      // Handle a room assigned by the host AFTER launch — the solo→host
+      // promotion path. The user opened the game solo from Explore (launch
+      // mode 'single'), then shared it; the host created a room and tells us
+      // to adopt it so invitees connect to the SAME room and the host starts
+      // receiving onPlayerJoined. No-op when there is no game module.
+      if (data.type === 'GAME_ROOM_ASSIGNED' && data.roomId && self.game) {
+        var _assignedRoom = data.roomId;
+        // Reflect the new room in launch config so getLaunchParams().roomId,
+        // .mode and game.isMultiplayer() all report multiplayer from here on.
+        self.config.roomId = _assignedRoom;
+        self.config.mode = 'multiplayer';
+        // Let a solo game flip to its multiplayer UI before peers arrive.
+        self.game._dispatch('roomAssigned', { roomId: _assignedRoom });
+        // Connect + join so the host is actually in the room. Idempotent when
+        // already connected/joined; non-fatal on failure (the game can retry).
+        Promise.resolve()
+          .then(function() { return self.game.connect(); })
+          .then(function() { return self.game.join(_assignedRoom); })
+          .catch(function() { /* non-fatal */ });
+      }
     });
 
     // Report the user's first real interaction to the host (see below).

package/src/modules/game-core.js

@@ -27,6 +27,7 @@ const _EVENT_ALIASES = {
   disconnect: 'disconnect',
   reconnect: 'reconnect',
   connection_error: 'connectionError',
+  room_assigned: 'roomAssigned',
 };
 
 function _normalizeEventName(event) {
@@ -172,6 +173,11 @@ export function createGameModule(Usion) {
     onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
     onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
     onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+    // Fired when the host assigns this app a room AFTER launch (the user opened
+    // the game solo, then shared it — see GAME_ROOM_ASSIGNED). The SDK has
+    // already updated config.roomId and is connecting+joining; use this to flip
+    // a solo game into its multiplayer/hosting UI. onJoined fires right after.
+    onRoomAssigned: function(callback) { return this._setHandler('roomAssigned', callback); },
 
     /** @private Set the single legacy handler; returns an unsubscribe fn. */
     _setHandler: function(name, callback) {

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
@@ -326,6 +355,15 @@ export interface GameModule {
   onConnectionError(callback: (error: Error) => void): UnsubscribeFn;
   /** Peer connection lifecycle: connected / reconnecting (grace) / gone. */
   onPlayerConnection(callback: (data: PlayerConnectionData) => void): UnsubscribeFn;
+  /**
+   * Fired when the host assigns this app a room AFTER launch — the solo→host
+   * promotion path. The user opened the game solo (launch mode 'single'), then
+   * shared it from the host's top-bar Share button; the host created a room and
+   * the SDK has already updated `getLaunchParams().roomId`/`.mode` and is
+   * connecting+joining. Use this to flip a solo game into its multiplayer /
+   * hosting UI; `onJoined` fires right after the join completes.
+   */
+  onRoomAssigned(callback: (data: { roomId: string }) => void): UnsubscribeFn;
 
   /**
    * Register an ADDITIONAL event listener. Unlike the onX methods this