@usions/sdk 2.11.0 → 2.12.0

package/src/modules/core.js

@@ -66,7 +66,7 @@ export function isTrustedMessageSource(event) {
  * Core Usion object with init, _post, _request
  */
 export const core = {
-  version: '2.1.0',
+  version: '__USION_SDK_VERSION__', // injected from package.json at build
   config: {},
   _initialized: false,
   _initCallback: null,

package/src/modules/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Usion SDK Errors — stable, machine-readable error codes.
+ *
+ * Developers should branch on `err.code`, never on message text. Messages
+ * are human-readable and may change; codes are part of the public API and
+ * follow the deprecation policy (never removed within a major version).
+ */
+
+/** @type {Record<string, string>} */
+export const ERROR_CODES = {
+  NOT_CONNECTED: 'NOT_CONNECTED',           // No live connection for this call
+  NO_ROOM: 'NO_ROOM',                       // No room id provided/known
+  ROOM_NOT_FOUND: 'ROOM_NOT_FOUND',         // Room does not exist server-side
+  NOT_PARTICIPANT: 'NOT_PARTICIPANT',       // Caller is not a player in the room
+  NOT_AUTHORITY: 'NOT_AUTHORITY',           // Authority-only call (e.g. setState)
+  NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',   // Missing/invalid auth server-side
+  JOIN_TIMEOUT: 'JOIN_TIMEOUT',             // Join did not complete in time
+  CONNECT_TIMEOUT: 'CONNECT_TIMEOUT',       // Connect did not complete in time
+  STATE_TOO_LARGE: 'STATE_TOO_LARGE',       // setState payload over the quota
+  INVALID_STATE: 'INVALID_STATE',           // setState payload not a JSON object
+  INVALID_NEXT_TURN: 'INVALID_NEXT_TURN',   // nextTurn is not a player in the room
+  RATE_LIMITED: 'RATE_LIMITED',             // Too many calls; back off
+  REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',       // Host/parent did not reply in time
+  QUEUE_FULL: 'QUEUE_FULL',                 // Offline action queue at capacity
+  UNSUPPORTED: 'UNSUPPORTED',               // Not available in this transport
+  UNKNOWN: 'UNKNOWN',                       // Unmapped error (see message)
+};
+
+export class UsionError extends Error {
+  /**
+   * @param {string} code - One of ERROR_CODES
+   * @param {string} [message] - Human-readable detail (may change between versions)
+   */
+  constructor(code, message) {
+    super(message || code);
+    this.name = 'UsionError';
+    this.code = ERROR_CODES[code] ? code : ERROR_CODES.UNKNOWN;
+  }
+}
+
+// Backend error strings → stable codes. Order matters: first match wins.
+/** @type {Array<[RegExp, string]>} */
+const BACKEND_PATTERNS = [
+  [/not authenticated/i, ERROR_CODES.NOT_AUTHENTICATED],
+  [/room_id required|no room id/i, ERROR_CODES.NO_ROOM],
+  [/room not found/i, ERROR_CODES.ROOM_NOT_FOUND],
+  [/not a participant/i, ERROR_CODES.NOT_PARTICIPANT],
+  [/room authority/i, ERROR_CODES.NOT_AUTHORITY],
+  [/exceeds .*limit/i, ERROR_CODES.STATE_TOO_LARGE],
+  [/state must be/i, ERROR_CODES.INVALID_STATE],
+  [/next_turn must be/i, ERROR_CODES.INVALID_NEXT_TURN],
+  [/rate limit|too many/i, ERROR_CODES.RATE_LIMITED],
+  [/join timeout/i, ERROR_CODES.JOIN_TIMEOUT],
+  [/connection timeout|connect timeout/i, ERROR_CODES.CONNECT_TIMEOUT],
+  [/request timeout/i, ERROR_CODES.REQUEST_TIMEOUT],
+  [/not connected/i, ERROR_CODES.NOT_CONNECTED],
+];
+
+/**
+ * Normalize anything (backend `{error}` string, Error, raw string) into a
+ * UsionError with the best-matching stable code.
+ * @param {*} err
+ * @param {string} [fallbackCode] - Code to use when nothing matches
+ * @returns {UsionError}
+ */
+export function toUsionError(err, fallbackCode) {
+  if (err instanceof UsionError) return err;
+  const message = err && err.message ? err.message : String(err || 'Unknown error');
+  for (let i = 0; i < BACKEND_PATTERNS.length; i++) {
+    if (BACKEND_PATTERNS[i][0].test(message)) {
+      return new UsionError(BACKEND_PATTERNS[i][1], message);
+    }
+  }
+  return new UsionError(fallbackCode || ERROR_CODES.UNKNOWN, message);
+}

package/src/modules/game-core.js

@@ -8,6 +8,36 @@ import { applyGameProxy } from './game-proxy.js';
 import { applyGameMethods } from './game-methods.js';
 import { applyGameNetcode } from './game-netcode.js';
 
+// Map any reasonable spelling of a game event onto the internal handler
+// name: 'game:player_joined' / 'player_joined' / 'playerJoined' → 'playerJoined'.
+const _EVENT_ALIASES = {
+  joined: 'joined',
+  player_joined: 'playerJoined',
+  player_left: 'playerLeft',
+  player_connection: 'playerConnection',
+  state: 'stateUpdate',
+  state_update: 'stateUpdate',
+  sync: 'sync',
+  action: 'action',
+  realtime: 'realtime',
+  finished: 'finished',
+  restarted: 'restarted',
+  error: 'error',
+  rematch_request: 'rematchRequest',
+  disconnect: 'disconnect',
+  reconnect: 'reconnect',
+  connection_error: 'connectionError',
+};
+
+function _normalizeEventName(event) {
+  let name = String(event || '');
+  if (name.indexOf('game:') === 0) name = name.slice(5);
+  if (_EVENT_ALIASES[name]) return _EVENT_ALIASES[name];
+  // camelCase passthrough ('playerJoined', 'stateUpdate', …)
+  const snake = name.replace(/([A-Z])/g, function(m) { return '_' + m.toLowerCase(); });
+  return _EVENT_ALIASES[snake] || name;
+}
+
 /**
  * Create the game module with all sub-modules applied
  * @param {object} Usion - Reference to the main Usion object
@@ -33,6 +63,11 @@ export function createGameModule(Usion) {
     _heartbeatInterval: null,
     _pingMeter: null,
     _pongWaiters: [],
+    // Reliability state: highest action sequence already delivered to the
+    // game (duplicate echoes/replays are dropped), and the in-flight rejoin
+    // promise that gates action() sends right after a reconnect.
+    _lastActionApplied: 0,
+    _rejoinPromise: null,
 
     /**
      * Connect to the game socket server
@@ -115,34 +150,85 @@ export function createGameModule(Usion) {
       return self._connectPromise;
     },
 
-    // Event handler registrations
-    onJoined: function(callback) { this._eventHandlers.joined = callback; },
-    onPlayerJoined: function(callback) { this._eventHandlers.playerJoined = callback; },
-    onPlayerLeft: function(callback) { this._eventHandlers.playerLeft = callback; },
-    onStateUpdate: function(callback) { this._eventHandlers.stateUpdate = callback; },
-    onSync: function(callback) { this._eventHandlers.sync = callback; },
-    onAction: function(callback) { this._eventHandlers.action = callback; },
-    onRealtime: function(callback) { this._eventHandlers.realtime = callback; },
-    onGameFinished: function(callback) { this._eventHandlers.finished = callback; },
-    onGameRestarted: function(callback) { this._eventHandlers.restarted = callback; },
-    onError: function(callback) { this._eventHandlers.error = callback; },
-    onRematchRequest: function(callback) { this._eventHandlers.rematchRequest = callback; },
-    onDisconnect: function(callback) { this._eventHandlers.disconnect = callback; },
-    onReconnect: function(callback) { this._eventHandlers.reconnect = callback; },
-    onConnectionError: function(callback) { this._eventHandlers.connectionError = callback; },
+    // Event handler registrations.
+    //
+    // Each onX(cb) keeps the long-standing "single handler, last one wins"
+    // behavior for back-compat, but now ALSO returns an unsubscribe
+    // function. For multiple listeners use game.on(event, cb), which
+    // supports any number of listeners, works before connect() in every
+    // transport, and returns an unsubscribe function.
+    onJoined: function(callback) { return this._setHandler('joined', callback); },
+    onPlayerJoined: function(callback) { return this._setHandler('playerJoined', callback); },
+    onPlayerLeft: function(callback) { return this._setHandler('playerLeft', callback); },
+    onStateUpdate: function(callback) { return this._setHandler('stateUpdate', callback); },
+    onSync: function(callback) { return this._setHandler('sync', callback); },
+    onAction: function(callback) { return this._setHandler('action', callback); },
+    onRealtime: function(callback) { return this._setHandler('realtime', callback); },
+    onGameFinished: function(callback) { return this._setHandler('finished', callback); },
+    onGameRestarted: function(callback) { return this._setHandler('restarted', callback); },
+    onError: function(callback) { return this._setHandler('error', callback); },
+    onRematchRequest: function(callback) { return this._setHandler('rematchRequest', callback); },
+    onDisconnect: function(callback) { return this._setHandler('disconnect', callback); },
+    onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
+    onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
+    onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+
+    /** @private Set the single legacy handler; returns an unsubscribe fn. */
+    _setHandler: function(name, callback) {
+      const self = this;
+      self._eventHandlers[name] = callback;
+      return function() {
+        if (self._eventHandlers[name] === callback) {
+          self._eventHandlers[name] = null;
+        }
+      };
+    },
 
     /**
-     * Register a generic event handler
+     * @private Deliver an event to the legacy single handler and every
+     * game.on() listener. All game event delivery flows through here.
+     */
+    _dispatch: function(name) {
+      const args = Array.prototype.slice.call(arguments, 1);
+      const single = this._eventHandlers[name];
+      if (single) {
+        try { single.apply(null, args); } catch (e) { Usion.log('game handler error (' + name + '): ' + e.message); }
+      }
+      const list = this._listeners[name];
+      if (list && list.length) {
+        const copy = list.slice();
+        for (let i = 0; i < copy.length; i++) {
+          try { copy[i].apply(null, args); } catch (e) { Usion.log('game listener error (' + name + '): ' + e.message); }
+        }
+      }
+    },
+
+    /**
+     * 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 (standalone, embedded
+     * proxy, direct). Accepts internal names ('action'), wire names
+     * ('game:action'), or snake_case ('player_joined').
      * @param {string} event - Event name
      * @param {function} callback - Handler function
+     * @returns {function} Unsubscribe function
      */
     on: function(event, callback) {
-      if (this.socket) {
-        this.socket.on(event, callback);
-      }
+      const self = this;
+      const name = _normalizeEventName(event);
+      if (!self._listeners[name]) self._listeners[name] = [];
+      self._listeners[name].push(callback);
+      return function() {
+        const list = self._listeners[name];
+        if (!list) return;
+        const i = list.indexOf(callback);
+        if (i >= 0) list.splice(i, 1);
+      };
     }
   };
 
+  game._listeners = {};
+
   // Apply sub-modules
   applyGameDirect(game, Usion);
   applyGameSocket(game, Usion);

package/src/modules/game-direct.js

@@ -43,9 +43,7 @@ export function applyGameDirect(game, Usion) {
         self._connecting = false;
         self.connected = false;
         self.directMode = false;
-        if (self._eventHandlers.connectionError) {
-          self._eventHandlers.connectionError(err);
-        }
+        self._dispatch('connectionError', err);
         throw err;
       });
     return self._connectPromise;
@@ -154,9 +152,7 @@ export function applyGameDirect(game, Usion) {
           clearInterval(self._heartbeatInterval);
           self._heartbeatInterval = null;
         }
-        if (self._eventHandlers.disconnect) {
-          self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
-        }
+        self._dispatch('disconnect', evt && evt.reason ? evt.reason : 'direct socket closed');
         // Seamless resume: if the drop wasn't an intentional disconnect()
         // (which clears directMode), transparently re-establish + re-join +
         // resync from the last sequence.
@@ -190,7 +186,7 @@ export function applyGameDirect(game, Usion) {
           self.connected = true;
           self._reconnecting = false;
           self._reconnectAttempt = 0;
-          if (self._eventHandlers.reconnect) self._eventHandlers.reconnect(attempt);
+          self._dispatch('reconnect', attempt);
           if (self.roomId) self.requestSync(self._lastSequence || 0); // resync / resume
         })
         .catch(function() {
@@ -228,20 +224,20 @@ export function applyGameDirect(game, Usion) {
 
     if (data.type === 'joined') {
       this._joined = true;
-      if (this._eventHandlers.joined) this._eventHandlers.joined(payload);
+      this._dispatch('joined', payload);
       return;
     }
     if (data.type === 'player_joined') {
-      if (this._eventHandlers.playerJoined) this._eventHandlers.playerJoined(payload);
+      this._dispatch('playerJoined', payload);
       return;
     }
     if (data.type === 'player_left') {
-      if (this._eventHandlers.playerLeft) this._eventHandlers.playerLeft(payload);
+      this._dispatch('playerLeft', payload);
       return;
     }
     if (data.type === 'state_snapshot' || data.type === 'state_delta') {
-      if (this._eventHandlers.realtime) this._eventHandlers.realtime(payload);
-      if (this._eventHandlers.stateUpdate) this._eventHandlers.stateUpdate(payload);
+      this._dispatch('realtime', payload);
+      this._dispatch('stateUpdate', payload);
       return;
     }
     if (data.type === 'pong') {
@@ -250,15 +246,15 @@ export function applyGameDirect(game, Usion) {
         const waiter = this._pongWaiters.shift();
         if (waiter) waiter();
       }
-      if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
+      this._dispatch('sync', payload);
       return;
     }
     if (data.type === 'match_end') {
-      if (this._eventHandlers.finished) this._eventHandlers.finished(payload);
+      this._dispatch('finished', payload);
       return;
     }
-    if (data.type === 'error' && this._eventHandlers.error) {
-      this._eventHandlers.error(payload);
+    if (data.type === 'error') {
+      this._dispatch('error', payload);
     }
   };
 }

package/src/modules/game-methods.js

@@ -2,6 +2,8 @@
  * Usion SDK Game Methods — join, leave, action, realtime, sync, etc.
  */
 
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
+
 /**
  * Add game action methods to game module
  * @param {object} game - The game module object
@@ -43,7 +45,7 @@ export function applyGameMethods(game, Usion) {
         setTimeout(function() {
           if (!self._joined && self._proxyJoinReject) {
             self._proxyJoinReject = null;
-            reject(new Error('Join timeout'));
+            reject(new UsionError(ERROR_CODES.JOIN_TIMEOUT, 'Join timeout'));
           }
         }, 15000);
       });
@@ -52,19 +54,19 @@ export function applyGameMethods(game, Usion) {
 
     self._joinPromise = new Promise(function(resolve, reject) {
       if (!self.socket || !self.connected) {
-        reject(new Error('Not connected'));
+        reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
         return;
       }
 
       if (!roomId) {
-        reject(new Error('No room ID provided'));
+        reject(new UsionError(ERROR_CODES.NO_ROOM, 'No room ID provided'));
         return;
       }
 
       self.socket.emit('game:join', { room_id: roomId }, function(response) {
         if (response.error) {
           self._joined = false;
-          reject(new Error(response.message || response.error));
+          reject(toUsionError(response.message || response.error));
         } else {
           self._joined = true;
           if (response.sequence !== undefined) {
@@ -112,13 +114,25 @@ export function applyGameMethods(game, Usion) {
   };
 
   /**
-   * Send a game action
+   * Send a game action.
+   *
+   * RELIABILITY CONTRACT: the platform echoes every action back to the
+   * sender (with the authoritative sequence number). Apply game state ONLY
+   * in onAction — never optimistically on send — so every client applies
+   * the same actions in the same order. The SDK deduplicates by sequence,
+   * so an action is delivered exactly once even across reconnect replays.
+   *
    * @param {string} actionType - Type of action (e.g., 'move')
    * @param {object} actionData - Action data
+   * @param {object} [opts] - Options. opts.nextTurn: player ID whose turn
+   *   is next — the server remembers it and hands it to any (re)joining
+   *   client as current_turn, so turn state survives reconnects.
    * @returns {Promise} Resolves when action is processed
    */
-  game.action = function(actionType, actionData) {
+  game.action = function(actionType, actionData, opts) {
     const self = this;
+    const nextTurn = opts && opts.nextTurn;
+    const queueOffline = !!(opts && opts.queueOffline);
 
     if (self.directMode) {
       self._sendDirect('action', {
@@ -128,29 +142,153 @@ export function applyGameMethods(game, Usion) {
       return Promise.resolve({ success: true });
     }
 
+    // Opt-in offline queue: instead of failing while disconnected, hold
+    // the move and send it (in order) once the connection recovers.
+    // Turn-based games get "your move is saved and sends when you're
+    // back" for free; realtime games should NOT use this (stale inputs).
+    if (queueOffline && !self.connected) {
+      return self._queueOfflineAction(actionType, actionData, opts);
+    }
+
     if (self._useProxy) {
-      Usion._post({ type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData });
+      const proxyMsg = { type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData };
+      if (nextTurn) proxyMsg.next_turn = nextTurn;
+      Usion._post(proxyMsg);
       return Promise.resolve({ success: true });
     }
 
+    // Gate sends while a post-reconnect rejoin is in flight, so a stale
+    // move can't go out before the client has resynced.
+    const gate = self._rejoinPromise || Promise.resolve();
+    return gate.then(function() {
+      return new Promise(function(resolve, reject) {
+        if (!self.socket || !self.connected) {
+          if (queueOffline) {
+            self._queueOfflineAction(actionType, actionData, opts).then(resolve, reject);
+            return;
+          }
+          reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
+          return;
+        }
+
+        const payload = {
+          room_id: self.roomId,
+          action_type: actionType,
+          action_data: actionData
+        };
+        if (nextTurn) payload.next_turn = nextTurn;
+        self.socket.emit('game:action', payload, function(response) {
+          if (response.error) {
+            reject(toUsionError(response.message || response.error));
+          } else {
+            if (response.sequence !== undefined) {
+              self._lastSequence = response.sequence;
+            }
+            resolve(response);
+          }
+        });
+      });
+    });
+  };
+
+  // ── Offline action queue (opt-in via action(..., { queueOffline: true })) ──
+
+  const OFFLINE_QUEUE_MAX = 20;
+
+  /** @private Hold an action until the connection recovers. */
+  game._queueOfflineAction = function(actionType, actionData, opts) {
+    const self = this;
+    if (!self._offlineQueue) self._offlineQueue = [];
+    if (self._offlineQueue.length >= OFFLINE_QUEUE_MAX) {
+      return Promise.reject(new UsionError(ERROR_CODES.QUEUE_FULL,
+        'Offline action queue is full (' + OFFLINE_QUEUE_MAX + ')'));
+    }
+    Usion.log('Queued action while offline: ' + actionType);
+    return new Promise(function(resolve, reject) {
+      self._offlineQueue.push({
+        actionType: actionType,
+        actionData: actionData,
+        opts: Object.assign({}, opts, { queueOffline: false }),
+        resolve: resolve,
+        reject: reject,
+      });
+      self._ensureOfflineFlushHook();
+    });
+  };
+
+  /** @private Flush queued actions, in order, once reconnected. */
+  game._ensureOfflineFlushHook = function() {
+    const self = this;
+    if (self._offlineFlushHooked) return;
+    self._offlineFlushHooked = true;
+    self.on('reconnect', function() { self._flushOfflineQueue(); });
+  };
+
+  /** @private */
+  game._flushOfflineQueue = function() {
+    const self = this;
+    const queue = self._offlineQueue;
+    if (!queue || !queue.length) return;
+    self._offlineQueue = [];
+    Usion.log('Flushing ' + queue.length + ' queued action(s) after reconnect');
+    // Send strictly in order: each action waits for the previous ack so
+    // the server assigns sequences in the order the player acted.
+    let chain = Promise.resolve();
+    queue.forEach(function(item) {
+      chain = chain.then(function() {
+        return self.action(item.actionType, item.actionData, item.opts)
+          .then(item.resolve, item.reject);
+      });
+    });
+  };
+
+  /**
+   * Checkpoint the authoritative game state on the server. Any client that
+   * joins or rejoins the room receives the latest checkpoint as game_state
+   * in the join ack and in game:sync — recovery becomes "load checkpoint,
+   * replay the tail" instead of replaying every action from zero.
+   *
+   * Only the room authority (player_ids[0] / host) may call this. The
+   * serialized state is capped at 64 KB.
+   *
+   * @param {*} state - JSON-serializable authoritative game state
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  game.setState = function(state) {
+    const self = this;
+
+    if (self.directMode) {
+      // Direct-mode game servers own their state; no platform checkpoint.
+      return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode', code: ERROR_CODES.UNSUPPORTED });
+    }
+
+    if (self._useProxy) {
+      return Usion._request('GAME_SET_STATE', { room_id: self.roomId, state: state || {} })
+        .then(function(res) {
+          if (res && res.error) {
+            return { success: false, error: res.error, code: toUsionError(res.error).code };
+          }
+          return res || { success: true };
+        })
+        .catch(function(err) {
+          const ue = toUsionError(err, ERROR_CODES.REQUEST_TIMEOUT);
+          return { success: false, error: ue.message, code: ue.code };
+        });
+    }
+
     return new Promise(function(resolve, reject) {
       if (!self.socket || !self.connected) {
-        reject(new Error('Not connected'));
+        reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
         return;
       }
-
-      self.socket.emit('game:action', {
+      self.socket.emit('game:set_state', {
         room_id: self.roomId,
-        action_type: actionType,
-        action_data: actionData
+        state: state || {}
       }, function(response) {
-        if (response.error) {
-          reject(new Error(response.message || response.error));
+        if (response && response.error) {
+          resolve({ success: false, error: response.error, code: toUsionError(response.error).code });
         } else {
-          if (response.sequence !== undefined) {
-            self._lastSequence = response.sequence;
-          }
-          resolve(response);
+          resolve(response || { success: true });
         }
       });
     });
@@ -254,13 +392,13 @@ export function applyGameMethods(game, Usion) {
 
     return new Promise(function(resolve, reject) {
       if (!self.socket || !self.connected) {
-        reject(new Error('Not connected'));
+        reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
         return;
       }
 
       self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
         if (response.error) {
-          reject(new Error(response.message || response.error));
+          reject(toUsionError(response.message || response.error));
         } else {
           resolve(response);
         }
@@ -422,7 +560,9 @@ export function applyGameMethods(game, Usion) {
       var inFrame = window.parent && window.parent !== window;
       var inRNWebView = !!window.ReactNativeWebView;
       if (inFrame || inRNWebView) {
-        Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+        var body = Object.assign({}, payload || {});
+        body._diag = Usion.diagnostics ? Usion.diagnostics() : undefined;
+        Usion._post({ type: 'GAME_DEBUG', payload: body });
       }
     } catch (e) { /* non-fatal */ }
   };