@usions/sdk 2.11.1 → 2.12.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

@@ -31,6 +31,7 @@ import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.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,6 +45,9 @@ 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);

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/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;
+        }
+      };
     }
   };
 }

package/types/index.d.ts

@@ -76,7 +76,7 @@ export interface WalletModule {
   getBalance(): Promise<number>;
   hasCredits(amount: number): Promise<boolean>;
   requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
-  onBalanceChange(callback: (balance: number) => void): void;
+  onBalanceChange(callback: (balance: number) => void): UnsubscribeFn;
 }
 
 // ─── Session ─────────────────────────────────────────────────────
@@ -178,6 +178,38 @@ export interface GameActionData {
   action_type: string;
   action_data: Record<string, any>;
   sequence?: number;
+  /** Present when the sender passed { nextTurn } — the server-remembered turn. */
+  current_turn?: string;
+}
+
+/** Returned by event registrations; call to remove the handler. */
+export type UnsubscribeFn = () => void;
+
+export interface GameActionOptions {
+  /**
+   * Player ID whose turn comes after this action. The server stores it (no
+   * game logic — a relay that remembers) and returns it as current_turn in
+   * join acks and game:sync, so turn state survives reconnects.
+   */
+  nextTurn?: string;
+  /**
+   * Hold this action while disconnected and send it (in order) once the
+   * connection recovers, instead of rejecting with NOT_CONNECTED — "your
+   * move is saved and sends when you're back". For turn-based games only;
+   * never queue realtime-style inputs. Queue cap 20 (then QUEUE_FULL).
+   */
+  queueOffline?: boolean;
+}
+
+export interface PlayerConnectionData {
+  room_id: string;
+  player_id: string;
+  /**
+   * connected     — player (re)joined the room.
+   * reconnecting  — player's connection dropped; grace window running (~15s).
+   * gone          — player did not return before the grace/heartbeat expiry.
+   */
+  state: 'connected' | 'reconnecting' | 'gone';
 }
 
 export interface GameFinishedData {
@@ -191,6 +223,7 @@ export interface SyncData {
   room_id: string;
   actions: GameActionData[];
   game_state: Record<string, any>;
+  current_turn?: string | null;
   sequence: number;
 }
 
@@ -207,14 +240,35 @@ export interface GameModule {
   isConnected(): boolean;
 
   // Room & actions
+  //
+  // RELIABILITY CONTRACT (what the platform guarantees / what your game must do):
+  // - Every action is echoed back to the sender with the authoritative
+  //   sequence number. Apply game state ONLY in onAction — never
+  //   optimistically on send — so all clients apply identical actions in
+  //   identical order. The SDK deduplicates by sequence, so each action is
+  //   delivered exactly once even across reconnect replays.
+  // - On a connection blip the host/SDK rejoins the room and replays missed
+  //   actions via onSync automatically. Use onDisconnect/onReconnect to
+  //   pause input and show a "reconnecting" indicator.
+  // - For turn-based games, pass { nextTurn } on each move and trust
+  //   current_turn from join/sync instead of deriving the turn locally.
+  // - The room authority (player_ids[0]) should checkpoint via setState()
+  //   at meaningful transitions so rejoining clients can restore instantly.
   join(roomId?: string): Promise<GameJoinResult>;
   leave(): void;
-  action(actionType: string, actionData?: Record<string, any>): Promise<ActionResult>;
+  action(actionType: string, actionData?: Record<string, any>, opts?: GameActionOptions): Promise<ActionResult>;
   realtime(actionType: string, actionData?: Record<string, any>): void;
   requestSync(lastSequence?: number): void;
   requestRematch(): void;
   forfeit(): Promise<{ success: boolean; error?: string }>;
 
+  /**
+   * Checkpoint authoritative game state on the server (authority only —
+   * player_ids[0]/host). (Re)joining clients receive the latest checkpoint
+   * as game_state in the join ack and in game:sync. Max 64 KB serialized.
+   */
+  setState(state: Record<string, any>): Promise<{ success: boolean; error?: string; code?: UsionErrorCode }>;
+
   // Persisted state — survives iframe unmount/remount.
   // Keyed by (player_id, room_id) in localStorage. Schema is up to the game.
   saveState<T = any>(state: T): boolean;
@@ -226,23 +280,31 @@ export interface GameModule {
   debug(payload: Record<string, any>): void;
 
   // Event handlers
-  onJoined(callback: (data: GameJoinResult) => void): void;
-  onPlayerJoined(callback: (data: PlayerJoinedData) => void): void;
-  onPlayerLeft(callback: (data: PlayerLeftData) => void): void;
-  onStateUpdate(callback: (data: StateUpdateData) => void): void;
-  onSync(callback: (data: SyncData) => void): void;
-  onAction(callback: (data: GameActionData) => void): void;
-  onRealtime(callback: (data: Record<string, any>) => void): void;
-  onGameFinished(callback: (data: GameFinishedData) => void): void;
-  onGameRestarted(callback: (data: Record<string, any>) => void): void;
-  onError(callback: (data: { message: string; code?: string }) => void): void;
-  onRematchRequest(callback: (data: RematchData) => void): void;
-  onDisconnect(callback: (reason: string) => void): void;
-  onReconnect(callback: (attemptNumber: number) => void): void;
-  onConnectionError(callback: (error: Error) => void): void;
-
-  // Generic event listener
-  on(event: string, callback: (data: any) => void): void;
+  onJoined(callback: (data: GameJoinResult) => void): UnsubscribeFn;
+  onPlayerJoined(callback: (data: PlayerJoinedData) => void): UnsubscribeFn;
+  onPlayerLeft(callback: (data: PlayerLeftData) => void): UnsubscribeFn;
+  onStateUpdate(callback: (data: StateUpdateData) => void): UnsubscribeFn;
+  onSync(callback: (data: SyncData) => void): UnsubscribeFn;
+  onAction(callback: (data: GameActionData) => void): UnsubscribeFn;
+  onRealtime(callback: (data: Record<string, any>) => void): UnsubscribeFn;
+  onGameFinished(callback: (data: GameFinishedData) => void): UnsubscribeFn;
+  onGameRestarted(callback: (data: Record<string, any>) => void): UnsubscribeFn;
+  onError(callback: (data: { message: string; code?: string }) => void): UnsubscribeFn;
+  onRematchRequest(callback: (data: RematchData) => void): UnsubscribeFn;
+  onDisconnect(callback: (reason: string) => void): UnsubscribeFn;
+  onReconnect(callback: (attemptNumber: number) => void): UnsubscribeFn;
+  onConnectionError(callback: (error: Error) => void): UnsubscribeFn;
+  /** Peer connection lifecycle: connected / reconnecting (grace) / gone. */
+  onPlayerConnection(callback: (data: PlayerConnectionData) => void): UnsubscribeFn;
+
+  /**
+   * Register an ADDITIONAL event listener. Unlike the onX methods this
+   * supports multiple listeners per event, can be called before connect(),
+   * and works in every transport. Accepts internal names ('action'), wire
+   * names ('game:action'), or snake_case ('player_joined').
+   * @returns Unsubscribe function.
+   */
+  on(event: string, callback: (data: any) => void): UnsubscribeFn;
 
   // ─── Netcode helpers (low-latency realtime) ──────────────────
   // JSON state delta compression.
@@ -667,7 +729,7 @@ export interface BotModule {
   sendMessage(text: string): void;
   updateContext(ctx: Record<string, any>): void;
   close(result?: any): void;
-  onMessage(callback: (message: BotMessage) => void): void;
+  onMessage(callback: (message: BotMessage) => void): UnsubscribeFn;
 }
 
 // ─── Selection Grid ──────────────────────────────────────────────
@@ -733,6 +795,29 @@ export interface UsionSDK {
     onChange: (selected: string, item: HTMLElement) => void
   ): SelectionGrid;
 
+  /** SDK version (injected from package.json at build time). */
+  version: string;
+
+  /**
+   * Live diagnostics snapshot: version, transport, connection + sequence
+   * state. game.debug() attaches this automatically as payload._diag.
+   */
+  diagnostics(): {
+    version: string;
+    transport: 'socket' | 'proxy' | 'direct' | 'none';
+    connected: boolean;
+    joined: boolean;
+    roomId: string | null;
+    playerId: string | null;
+    lastSequence: number;
+    lastActionApplied: number;
+    rejoining: boolean;
+  };
+
+  // Errors — branch on err.code (stable), never on message text.
+  UsionError: typeof UsionError;
+  ERROR_CODES: typeof ERROR_CODES;
+
   // Modules
   user: UserModule;
   storage: StorageModule;
@@ -822,6 +907,38 @@ export interface LobbyModule {
   queue(serviceId: string, opts?: { conversationId?: string }): Promise<any>;
 }
 
+/**
+ * Stable machine-readable error codes. Part of the public API: codes are
+ * never removed within a major version. Messages may change — branch on
+ * `err.code`, never on message text.
+ */
+export declare const ERROR_CODES: {
+  readonly NOT_CONNECTED: 'NOT_CONNECTED';
+  readonly NO_ROOM: 'NO_ROOM';
+  readonly ROOM_NOT_FOUND: 'ROOM_NOT_FOUND';
+  readonly NOT_PARTICIPANT: 'NOT_PARTICIPANT';
+  readonly NOT_AUTHORITY: 'NOT_AUTHORITY';
+  readonly NOT_AUTHENTICATED: 'NOT_AUTHENTICATED';
+  readonly JOIN_TIMEOUT: 'JOIN_TIMEOUT';
+  readonly CONNECT_TIMEOUT: 'CONNECT_TIMEOUT';
+  readonly STATE_TOO_LARGE: 'STATE_TOO_LARGE';
+  readonly INVALID_STATE: 'INVALID_STATE';
+  readonly INVALID_NEXT_TURN: 'INVALID_NEXT_TURN';
+  readonly RATE_LIMITED: 'RATE_LIMITED';
+  readonly REQUEST_TIMEOUT: 'REQUEST_TIMEOUT';
+  readonly QUEUE_FULL: 'QUEUE_FULL';
+  readonly UNSUPPORTED: 'UNSUPPORTED';
+  readonly UNKNOWN: 'UNKNOWN';
+};
+
+export type UsionErrorCode = keyof typeof ERROR_CODES;
+
+export declare class UsionError extends Error {
+  readonly name: 'UsionError';
+  readonly code: UsionErrorCode;
+  constructor(code: UsionErrorCode | string, message?: string);
+}
+
 declare const Usion: UsionSDK;
 
 export { Usion };