@usions/sdk 2.11.1 → 2.13.0

package/src/modules/game-proxy.js

@@ -3,6 +3,7 @@
  */
 
 import { isTrustedMessageSource } from './core.js';
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
 
 /**
  * Add proxy connection methods to game module
@@ -42,7 +43,7 @@ export function applyGameProxy(game, Usion) {
       setTimeout(function() {
         if (!self.connected) {
           self._connecting = false;
-          reject(new Error('Proxy connection timeout'));
+          reject(new UsionError(ERROR_CODES.CONNECT_TIMEOUT, 'Proxy connection timeout'));
         }
       }, 10000);
     });
@@ -83,69 +84,97 @@ export function applyGameProxy(game, Usion) {
           self._connecting = false;
           break;
 
+        case 'GAME_DISCONNECTED':
+          // The host app's socket dropped; it will rejoin and resync for us.
+          self.connected = false;
+          self._dispatch('disconnect', data.reason || 'transport');
+          break;
+
+        case 'GAME_RECONNECTED':
+          self.connected = true;
+          self._dispatch('reconnect', data.attempts || 1);
+          break;
+
+        case 'GAME_PLAYER_CONNECTION':
+          self._dispatch('playerConnection', data);
+          break;
+
         case 'GAME_JOINED':
           self._joined = true;
-          if (data.sequence !== undefined) self._lastSequence = data.sequence;
+          if (data.sequence !== undefined) {
+            self._lastSequence = data.sequence;
+            self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
+          }
           if (self._proxyJoinResolve) {
             self._proxyJoinResolve(data);
             self._proxyJoinResolve = null;
           }
-          if (self._eventHandlers.joined) self._eventHandlers.joined(data);
+          self._dispatch('joined', data);
           break;
 
         case 'GAME_JOIN_ERROR':
           self._joined = false;
           if (self._proxyJoinReject) {
-            self._proxyJoinReject(new Error(data.message || 'Join failed'));
+            self._proxyJoinReject(toUsionError(data.message || 'Join failed'));
             self._proxyJoinReject = null;
           }
           break;
 
         case 'GAME_PLAYER_JOINED':
-          if (self._eventHandlers.playerJoined) self._eventHandlers.playerJoined(data);
+          self._dispatch('playerJoined', data);
           break;
 
         case 'GAME_PLAYER_LEFT':
-          if (self._eventHandlers.playerLeft) self._eventHandlers.playerLeft(data);
+          self._dispatch('playerLeft', data);
           break;
 
         case 'GAME_STATE':
           if (data.sequence !== undefined) self._lastSequence = Math.max(self._lastSequence, data.sequence);
-          if (self._eventHandlers.stateUpdate) self._eventHandlers.stateUpdate(data);
+          self._dispatch('stateUpdate', data);
           break;
 
         case 'GAME_ACTION_DATA':
-          if (data.sequence !== undefined) self._lastSequence = Math.max(self._lastSequence, data.sequence);
-          if (self._eventHandlers.action) self._eventHandlers.action(data);
+          if (data.sequence !== undefined) {
+            // Drop duplicates: actions are delivered exactly once per
+            // sequence (live, sender echo, or replay after reconnect).
+            if (data.sequence <= self._lastActionApplied) break;
+            self._lastActionApplied = data.sequence;
+            self._lastSequence = Math.max(self._lastSequence, data.sequence);
+          }
+          self._dispatch('action', data);
           break;
 
         case 'GAME_REALTIME_DATA':
-          if (self._eventHandlers.realtime) self._eventHandlers.realtime(data);
+          self._dispatch('realtime', data);
           break;
 
         case 'GAME_FINISHED':
           if (data.sequence !== undefined) self._lastSequence = data.sequence;
-          if (self._eventHandlers.finished) self._eventHandlers.finished(data);
+          self._dispatch('finished', data);
           break;
 
         case 'GAME_ERROR':
           Usion.log('Game error via proxy: ' + (data.message || data.code));
-          if (self._eventHandlers.error) self._eventHandlers.error(data);
+          self._dispatch('error', data);
           break;
 
         case 'GAME_RESTARTED':
           self._lastSequence = 0;
-          if (self._eventHandlers.restarted) self._eventHandlers.restarted(data);
+          self._lastActionApplied = 0;
+          self._dispatch('restarted', data);
           break;
 
         case 'GAME_REMATCH_REQUEST':
-          if (self._eventHandlers.rematchRequest) self._eventHandlers.rematchRequest(data);
+          self._dispatch('rematchRequest', data);
           break;
 
         case 'GAME_SYNC':
-          if (data.sequence !== undefined) self._lastSequence = data.sequence;
-          if (self._eventHandlers.sync) self._eventHandlers.sync(data);
-          if (self._eventHandlers.stateUpdate) self._eventHandlers.stateUpdate(data);
+          if (data.sequence !== undefined) {
+            self._lastSequence = data.sequence;
+            self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
+          }
+          self._dispatch('sync', data);
+          self._dispatch('stateUpdate', data);
           break;
       }
     });

package/src/modules/game-socket.js

@@ -57,17 +57,27 @@ export function applyGameSocket(game, Usion) {
           }
         }, 25000);
 
-        // Re-join room after reconnect
+        // Re-join room after reconnect. The promise is kept on
+        // _rejoinPromise so action() can gate sends until the room
+        // membership and sync are restored — otherwise a stale move could
+        // go out before the client has caught up.
         if (self.roomId) {
           self._joined = false;
           self._joinPromise = null;
-          self.join(self.roomId)
+          self._rejoinPromise = self.join(self.roomId)
             .then(function() {
               Usion.log('Reconnected - joined room ' + self.roomId);
               self.requestSync(self._lastSequence || 0);
             })
             .catch(function(err) {
               Usion.log('Rejoin failed: ' + (err && err.message ? err.message : String(err)));
+            })
+            .then(function() {
+              self._rejoinPromise = null;
+              // Send any moves queued while offline, now that membership
+              // and sync are restored. (Socket.IO v4 emits 'reconnect' on
+              // the Manager, not the Socket, so this is the reliable hook.)
+              if (self._flushOfflineQueue) self._flushOfflineQueue();
             });
         }
 
@@ -77,9 +87,7 @@ export function applyGameSocket(game, Usion) {
       self.socket.on('connect_error', function(err) {
         self._connecting = false;
         Usion.log('Game socket error: ' + err.message);
-        if (self._eventHandlers.connectionError) {
-          self._eventHandlers.connectionError(err);
-        }
+        self._dispatch('connectionError', err);
         reject(err);
       });
 
@@ -92,104 +100,92 @@ export function applyGameSocket(game, Usion) {
           self._heartbeatInterval = null;
         }
         Usion.log('Game socket disconnected: ' + reason);
-        if (self._eventHandlers.disconnect) {
-          self._eventHandlers.disconnect(reason);
-        }
+        self._dispatch('disconnect', reason);
       });
 
       self.socket.on('reconnect', function(attemptNumber) {
         Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-        if (self._eventHandlers.reconnect) {
-          self._eventHandlers.reconnect(attemptNumber);
-        }
+        self._dispatch('reconnect', attemptNumber);
       });
 
       // Game event handlers
       self.socket.on('game:joined', function(data) {
         if (data.sequence !== undefined) {
           self._lastSequence = data.sequence;
+          // Everything up to this sequence is reflected in the joined
+          // state — actions at or below it must not be re-delivered.
+          self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
         }
-        if (self._eventHandlers.joined) {
-          self._eventHandlers.joined(data);
-        }
+        self._dispatch('joined', data);
       });
 
       self.socket.on('game:player_joined', function(data) {
-        if (self._eventHandlers.playerJoined) {
-          self._eventHandlers.playerJoined(data);
-        }
+        self._dispatch('playerJoined', data);
       });
 
       self.socket.on('game:player_left', function(data) {
-        if (self._eventHandlers.playerLeft) {
-          self._eventHandlers.playerLeft(data);
-        }
+        self._dispatch('playerLeft', data);
       });
 
       self.socket.on('game:state', function(data) {
         if (data.sequence !== undefined) {
           self._lastSequence = Math.max(self._lastSequence, data.sequence);
         }
-        if (self._eventHandlers.stateUpdate) {
-          self._eventHandlers.stateUpdate(data);
-        }
+        self._dispatch('stateUpdate', data);
       });
 
       self.socket.on('game:sync', function(data) {
         if (data.sequence !== undefined) {
           self._lastSequence = data.sequence;
+          // The sync payload carries all actions up to this sequence; a
+          // live echo of one of them must not be applied a second time.
+          self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
         }
-        if (self._eventHandlers.sync) {
-          self._eventHandlers.sync(data);
-        }
+        self._dispatch('sync', data);
         // Also trigger stateUpdate for backwards compat
-        if (self._eventHandlers.stateUpdate) {
-          self._eventHandlers.stateUpdate(data);
-        }
+        self._dispatch('stateUpdate', data);
       });
 
       self.socket.on('game:action', function(data) {
         if (data.sequence !== undefined) {
+          // Drop duplicates: actions are delivered exactly once per
+          // sequence, whether they arrive live, as the sender's own echo,
+          // or replayed after a reconnect.
+          if (data.sequence <= self._lastActionApplied) return;
+          self._lastActionApplied = data.sequence;
           self._lastSequence = Math.max(self._lastSequence, data.sequence);
         }
-        if (self._eventHandlers.action) {
-          self._eventHandlers.action(data);
-        }
+        self._dispatch('action', data);
+      });
+
+      self.socket.on('game:player_connection', function(data) {
+        self._dispatch('playerConnection', data);
       });
 
       self.socket.on('game:realtime', function(data) {
-        if (self._eventHandlers.realtime) {
-          self._eventHandlers.realtime(data);
-        }
+        self._dispatch('realtime', data);
       });
 
       self.socket.on('game:finished', function(data) {
         if (data.sequence !== undefined) {
           self._lastSequence = data.sequence;
         }
-        if (self._eventHandlers.finished) {
-          self._eventHandlers.finished(data);
-        }
+        self._dispatch('finished', data);
       });
 
       self.socket.on('game:error', function(data) {
         Usion.log('Game error: ' + (data.message || data.code));
-        if (self._eventHandlers.error) {
-          self._eventHandlers.error(data);
-        }
+        self._dispatch('error', data);
       });
 
       self.socket.on('game:rematch_request', function(data) {
-        if (self._eventHandlers.rematchRequest) {
-          self._eventHandlers.rematchRequest(data);
-        }
+        self._dispatch('rematchRequest', data);
       });
 
       self.socket.on('game:restarted', function(data) {
         self._lastSequence = 0; // Reset sequence on rematch
-        if (self._eventHandlers.restarted) {
-          self._eventHandlers.restarted(data);
-        }
+        self._lastActionApplied = 0;
+        self._dispatch('restarted', data);
       });
 
     } catch (err) {

package/src/modules/index.js

@@ -29,8 +29,10 @@ import { createLobbyModule } from './lobby.js';
 import { createLeaderboardModule } from './leaderboard.js';
 import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.js';
+import { createNotifyModule } from './notify.js';
 import { applyBackendChannel } from './backend-channel.js';
 import { netcode } from './netcode/index.js';
+import { UsionError, ERROR_CODES } from './errors.js';
 
 // Build the Usion object from core
 const Usion = Object.assign({}, core);
@@ -44,12 +46,16 @@ Usion.chat = createChatModule(Usion);
 Usion.bot = createBotModule(Usion);
 Usion.fileStorage = createFileStorageModule(Usion);
 Usion.game = createGameModule(Usion);
+// Stable error class + codes — developers branch on err.code, not message text.
+Usion.UsionError = UsionError;
+Usion.ERROR_CODES = ERROR_CODES;
 // Unified backend channel (used by lobby etc.; works standalone + embedded).
 applyBackendChannel(Usion);
 Usion.lobby = createLobbyModule(Usion);
 Usion.leaderboard = createLeaderboardModule(Usion);
 Usion.cloud = createCloudModule(Usion);
 Usion.matchmaking = createMatchmakingModule(Usion);
+Usion.notify = createNotifyModule(Usion);
 
 // Netcode toolkit (transport-agnostic, zero-dependency).
 Usion.netcode = netcode;

package/src/modules/misc.js

@@ -13,6 +13,26 @@ export const miscMethods = {
     return this.wallet.requestPayment(amount, reason, data);
   },
 
+  /**
+   * Live SDK diagnostics snapshot: version, transport, connection and
+   * sequence state. Surfaced automatically in the platform debug overlay
+   * (game.debug attaches it as _diag) and useful in bug reports.
+   */
+  diagnostics: function() {
+    const game = this.game || {};
+    return {
+      version: this.version,
+      transport: game.directMode ? 'direct' : (game._useProxy ? 'proxy' : (game.socket ? 'socket' : 'none')),
+      connected: !!game.connected,
+      joined: !!game._joined,
+      roomId: game.roomId || null,
+      playerId: game.playerId || null,
+      lastSequence: game._lastSequence || 0,
+      lastActionApplied: game._lastActionApplied || 0,
+      rejoining: !!game._rejoinPromise,
+    };
+  },
+
   /**
    * Submit result and signal completion
    * @param {object} data - Result data to send to parent

package/src/modules/notify.js

@@ -0,0 +1,70 @@
+/**
+ * Usion SDK Notify — let a mini-app notify its own user.
+ *
+ * A notification reaches the user even when they aren't looking at the app:
+ *   - online elsewhere in Usion  -> in-app banner
+ *   - offline / app backgrounded -> OS push notification
+ * Tapping it re-opens THIS mini-app, optionally at a specific internal screen
+ * via `path` (read back on launch with `Usion.getLaunchParams().path`).
+ *
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ * Scope & safety: a notification can only target the CURRENT user (you cannot
+ * notify other people from here), and the platform rate-limits per user per
+ * service. Users can silence a service with `setMuted(true)`.
+ *
+ *   await Usion.notify.send({
+ *     title: 'Render complete',
+ *     body: 'Your video is ready to view.',
+ *     path: '/render/abc123',     // optional — deep-links inside the app
+ *   });
+ *
+ *   await Usion.notify.setMuted(true);   // user opts out for this app
+ *   const muted = await Usion.notify.isMuted();
+ *
+ * For server-triggered notifications (e.g. a long-running job finishing while
+ * the app is closed), a mini-app's own backend calls the signed REST endpoint
+ * `POST /services/{id}/notify` instead — see the publishing reference.
+ */
+export function createNotifyModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  return {
+    /**
+     * Send a notification to the current user.
+     * @param {{title: string, body: string, path?: string, serviceId?: string}} opts
+     * @returns {Promise<{success: boolean, delivered?: string}>}
+     */
+    send: function (opts) {
+      opts = opts || {};
+      return Usion._backendEmit('notify:send', {
+        service_id: serviceId(opts),
+        title: opts.title,
+        body: opts.body,
+        path: opts.path,
+      });
+    },
+
+    /**
+     * Mute (or unmute) notifications from this app for the current user.
+     * @param {boolean} muted
+     * @returns {Promise<{success: boolean, muted: boolean}>}
+     */
+    setMuted: function (muted, opts) {
+      return Usion._backendEmit('notify:set_pref', {
+        service_id: serviceId(opts),
+        muted: !!muted,
+      });
+    },
+
+    /**
+     * Whether the current user has muted notifications from this app.
+     * @returns {Promise<boolean>}
+     */
+    isMuted: function (opts) {
+      return Usion._backendEmit('notify:get_pref', { service_id: serviceId(opts) })
+        .then(function (r) { return !!(r && r.muted); });
+    },
+  };
+}

package/src/modules/wallet.js

@@ -112,7 +112,13 @@ export function createWalletModule(Usion) {
      * @param {function} callback - Called with new balance
      */
     onBalanceChange: function(callback) {
-      this._balanceChangeHandler = callback;
+      const self = this;
+      self._balanceChangeHandler = callback;
+      return function() {
+        if (self._balanceChangeHandler === callback) {
+          self._balanceChangeHandler = null;
+        }
+      };
     }
   };
 }