@usions/sdk 2.0.1 → 2.1.0

package/src/modules/game-direct.js

@@ -0,0 +1,219 @@
+/**
+ * Usion SDK Game Direct — WebSocket direct connection to game server
+ */
+
+/**
+ * Add direct WebSocket connection methods to game module
+ * @param {object} game - The game module object
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function applyGameDirect(game, Usion) {
+  /**
+   * Connect directly to creator-controlled WebSocket server.
+   * Uses backend-issued short-lived room token.
+   * @returns {Promise}
+   */
+  game.connectDirect = function(config) {
+    var self = this;
+    config = config || {};
+
+    if (self.directMode && self.directSocket && self.connected) {
+      return Promise.resolve();
+    }
+    if (self._connecting && self._connectPromise) {
+      return self._connectPromise;
+    }
+
+    self._connecting = true;
+    self.directMode = true;
+    self._connectPromise = self._fetchDirectAccess(config)
+      .then(function(access) {
+        self.directConfig = access;
+        return self._initDirectSocket(access);
+      })
+      .then(function() {
+        self.connected = true;
+        self._connecting = false;
+        Usion.log('Direct game socket connected');
+      })
+      .catch(function(err) {
+        self._connecting = false;
+        self.connected = false;
+        self.directMode = false;
+        if (self._eventHandlers.connectionError) {
+          self._eventHandlers.connectionError(err);
+        }
+        throw err;
+      });
+    return self._connectPromise;
+  };
+
+  game._fetchDirectAccess = function(config) {
+    var roomId = config.roomId || this.roomId || Usion.config.roomId;
+    var serviceId = config.serviceId || Usion.config.serviceId;
+    var apiUrl = config.apiUrl || Usion.config.apiUrl || '';
+    var token = config.token || Usion.user.getToken();
+
+    if (!roomId) return Promise.reject(new Error('No room ID provided'));
+    if (!serviceId) return Promise.reject(new Error('No service ID provided'));
+
+    this.roomId = roomId;
+    this.playerId = Usion.user.getId();
+
+    // When embedded (iframe/WebView), proxy through parent app to avoid
+    // CORS / Private Network Access issues
+    if (Usion._isEmbedded) {
+      return Usion._request('GAME_ACCESS_REQUEST', {
+        room_id: roomId,
+        service_id: serviceId,
+        protocol_version: (config.protocolVersion || Usion.config.protocolVersion || Usion.config.protocol_version || '2')
+      }, 10000);
+    }
+
+    if (!apiUrl) return Promise.reject(new Error('No API URL provided'));
+    if (!token) return Promise.reject(new Error('No auth token available'));
+
+    var cleanApiUrl = String(apiUrl).replace(/\/$/, '');
+    var endpoint = cleanApiUrl + '/games/rooms/' + encodeURIComponent(roomId) + '/access';
+    return fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': 'Bearer ' + token
+      },
+      body: JSON.stringify({
+        service_id: serviceId,
+        client_type: 'iframe',
+        protocol_version: (config.protocolVersion || Usion.config.protocolVersion || Usion.config.protocol_version || '2')
+      })
+    }).then(function(res) {
+      if (!res.ok) {
+        return res.text().then(function(text) {
+          throw new Error(text || ('Direct access failed: HTTP ' + res.status));
+        });
+      }
+      return res.json();
+    });
+  };
+
+  game._initDirectSocket = function(access) {
+    var self = this;
+    return new Promise(function(resolve, reject) {
+      if (!access || !access.ws_url || !access.access_token) {
+        reject(new Error('Invalid direct access payload'));
+        return;
+      }
+
+      var wsUrl = access.ws_url;
+      var separator = wsUrl.indexOf('?') === -1 ? '?' : '&';
+      var urlWithToken = wsUrl + separator + 'token=' + encodeURIComponent(access.access_token);
+      var ws = new WebSocket(urlWithToken);
+      self.directSocket = ws;
+
+      var opened = false;
+      var joinSent = false;
+      var timeout = setTimeout(function() {
+        if (!opened) {
+          try { ws.close(); } catch (e) {}
+          reject(new Error('Direct WebSocket connection timeout'));
+        }
+      }, 10000);
+
+      ws.onopen = function() {
+        opened = true;
+        clearTimeout(timeout);
+        if (!joinSent) {
+          joinSent = true;
+          self._sendDirect('join', {});
+        }
+        // Start heartbeat for direct mode
+        if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
+        self._heartbeatInterval = setInterval(function() {
+          if (self.directSocket && self.directSocket.readyState === WebSocket.OPEN) {
+            self._sendDirect('heartbeat', {});
+          }
+        }, 25000);
+        resolve();
+      };
+
+      ws.onerror = function() {
+        if (!opened) {
+          clearTimeout(timeout);
+          reject(new Error('Direct WebSocket connection error'));
+        }
+      };
+
+      ws.onclose = function(evt) {
+        self.connected = false;
+        self._joined = false;
+        self._joinPromise = null;
+        if (self._heartbeatInterval) {
+          clearInterval(self._heartbeatInterval);
+          self._heartbeatInterval = null;
+        }
+        if (self._eventHandlers.disconnect) {
+          self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
+        }
+      };
+
+      ws.onmessage = function(evt) {
+        self._handleDirectMessage(evt && evt.data);
+      };
+    });
+  };
+
+  game._sendDirect = function(type, payload) {
+    if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
+    this._directSeq = this._directSeq + 1;
+    this.directSocket.send(JSON.stringify({
+      type: type,
+      room_id: this.roomId,
+      ts: Date.now(),
+      seq: this._directSeq,
+      session_id: (this.directConfig && this.directConfig.session_id) ? this.directConfig.session_id : null,
+      protocol_version: (this.directConfig && this.directConfig.protocol_version) ? this.directConfig.protocol_version : '2',
+      payload: payload || {}
+    }));
+  };
+
+  game._handleDirectMessage = function(raw) {
+    var data;
+    try {
+      data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    } catch (e) {
+      return;
+    }
+    if (!data || !data.type) return;
+    var payload = data.payload || {};
+
+    if (data.type === 'joined') {
+      this._joined = true;
+      if (this._eventHandlers.joined) this._eventHandlers.joined(payload);
+      return;
+    }
+    if (data.type === 'player_joined') {
+      if (this._eventHandlers.playerJoined) this._eventHandlers.playerJoined(payload);
+      return;
+    }
+    if (data.type === 'player_left') {
+      if (this._eventHandlers.playerLeft) this._eventHandlers.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);
+      return;
+    }
+    if (data.type === 'pong') {
+      if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
+      return;
+    }
+    if (data.type === 'match_end') {
+      if (this._eventHandlers.finished) this._eventHandlers.finished(payload);
+      return;
+    }
+    if (data.type === 'error' && this._eventHandlers.error) {
+      this._eventHandlers.error(payload);
+    }
+  };
+}

package/src/modules/game-methods.js

@@ -0,0 +1,334 @@
+/**
+ * Usion SDK Game Methods — join, leave, action, realtime, sync, etc.
+ */
+
+/**
+ * Add game action methods to game module
+ * @param {object} game - The game module object
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function applyGameMethods(game, Usion) {
+  /**
+   * Join a game room
+   * @param {string} roomId - Game room ID (optional, uses config)
+   * @returns {Promise} Resolves with join data
+   */
+  game.join = function(roomId) {
+    const self = this;
+    roomId = roomId || Usion.config.roomId;
+
+    // If already joined this room, return cached promise/data
+    if (self._joined && self.roomId === roomId && self._joinPromise) {
+      return self._joinPromise;
+    }
+
+    self.roomId = roomId;
+    self.playerId = Usion.user.getId();
+
+    if (self.directMode) {
+      self._joined = true;
+      self._joinPromise = Promise.resolve({
+        room_id: roomId,
+        player_id: self.playerId
+      });
+      return self._joinPromise;
+    }
+
+    // Proxy mode: send join request to parent
+    if (self._useProxy) {
+      self._joinPromise = new Promise(function(resolve, reject) {
+        self._proxyJoinResolve = resolve;
+        self._proxyJoinReject = reject;
+        Usion._post({ type: 'GAME_JOIN', room_id: roomId });
+        setTimeout(function() {
+          if (!self._joined && self._proxyJoinReject) {
+            self._proxyJoinReject = null;
+            reject(new Error('Join timeout'));
+          }
+        }, 15000);
+      });
+      return self._joinPromise;
+    }
+
+    self._joinPromise = new Promise(function(resolve, reject) {
+      if (!self.socket || !self.connected) {
+        reject(new Error('Not connected'));
+        return;
+      }
+
+      if (!roomId) {
+        reject(new Error('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));
+        } else {
+          self._joined = true;
+          if (response.sequence !== undefined) {
+            self._lastSequence = response.sequence;
+          }
+          resolve(response);
+        }
+      });
+    });
+
+    return self._joinPromise;
+  };
+
+  /**
+   * Leave the current game room
+   */
+  game.leave = function() {
+    const self = this;
+
+    if (self.directMode) {
+      if (self.roomId) self._sendDirect('leave', {});
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._joined = false;
+      self._joinPromise = null;
+      return;
+    }
+
+    if (self._useProxy) {
+      if (self.roomId) Usion._post({ type: 'GAME_LEAVE', room_id: self.roomId });
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._joined = false;
+      self._joinPromise = null;
+      return;
+    }
+
+    if (self.socket && self.connected && self.roomId) {
+      self.socket.emit('game:leave', { room_id: self.roomId });
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._joined = false;
+      self._joinPromise = null;
+    }
+  };
+
+  /**
+   * Send a game action
+   * @param {string} actionType - Type of action (e.g., 'move')
+   * @param {object} actionData - Action data
+   * @returns {Promise} Resolves when action is processed
+   */
+  game.action = function(actionType, actionData) {
+    const self = this;
+
+    if (self.directMode) {
+      self._sendDirect(actionType || 'action', actionData || {});
+      return Promise.resolve({ success: true });
+    }
+
+    if (self._useProxy) {
+      Usion._post({ type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData });
+      return Promise.resolve({ success: true });
+    }
+
+    return new Promise(function(resolve, reject) {
+      if (!self.socket || !self.connected) {
+        reject(new Error('Not connected'));
+        return;
+      }
+
+      self.socket.emit('game:action', {
+        room_id: self.roomId,
+        action_type: actionType,
+        action_data: actionData
+      }, function(response) {
+        if (response.error) {
+          reject(new Error(response.message || response.error));
+        } else {
+          if (response.sequence !== undefined) {
+            self._lastSequence = response.sequence;
+          }
+          resolve(response);
+        }
+      });
+    });
+  };
+
+  /**
+   * Send a real-time game update (fire-and-forget).
+   * @param {string} actionType - Type of action
+   * @param {object} actionData - Action data
+   */
+  game.realtime = function(actionType, actionData) {
+    const self = this;
+
+    if (self.directMode) {
+      self._sendDirect('input', {
+        action_type: actionType,
+        action_data: actionData || {}
+      });
+      return;
+    }
+
+    if (self._useProxy) {
+      Usion._post({ type: 'GAME_REALTIME', room_id: self.roomId, action_type: actionType, action_data: actionData });
+      return;
+    }
+
+    if (!self.socket || !self.connected) {
+      return;
+    }
+
+    self.socket.emit('game:realtime', {
+      room_id: self.roomId,
+      action_type: actionType,
+      action_data: actionData
+    });
+  };
+
+  /**
+   * Request game state sync (for reconnection)
+   * @param {number} lastSequence - Last known sequence number
+   */
+  game.requestSync = function(lastSequence) {
+    const self = this;
+    lastSequence = lastSequence !== undefined ? lastSequence : self._lastSequence;
+
+    if (self.directMode) {
+      self._sendDirect('ping', { last_sequence: lastSequence || 0 });
+      return;
+    }
+
+    if (self._useProxy && self.roomId) {
+      Usion._post({ type: 'GAME_SYNC_REQUEST', room_id: self.roomId, last_sequence: lastSequence || 0 });
+      return;
+    }
+
+    if (self.socket && self.connected && self.roomId) {
+      self.socket.emit('game:sync_request', {
+        room_id: self.roomId,
+        last_sequence: lastSequence || 0
+      });
+    }
+  };
+
+  /**
+   * Request a rematch
+   */
+  game.requestRematch = function() {
+    const self = this;
+
+    if (self.directMode) {
+      self._sendDirect('rematch', {});
+      return;
+    }
+
+    if (self._useProxy && self.roomId) {
+      Usion._post({ type: 'GAME_REMATCH', room_id: self.roomId });
+      return;
+    }
+
+    if (self.socket && self.connected && self.roomId) {
+      self.socket.emit('game:rematch', { room_id: self.roomId });
+    }
+  };
+
+  /**
+   * Forfeit the current game
+   * @returns {Promise}
+   */
+  game.forfeit = function() {
+    const self = this;
+
+    if (self.directMode) {
+      self._sendDirect('forfeit', {});
+      return Promise.resolve({ success: true });
+    }
+
+    if (self._useProxy) {
+      Usion._post({ type: 'GAME_FORFEIT', room_id: self.roomId });
+      return Promise.resolve({ success: true });
+    }
+
+    return new Promise(function(resolve, reject) {
+      if (!self.socket || !self.connected) {
+        reject(new Error('Not connected'));
+        return;
+      }
+
+      self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
+        if (response.error) {
+          reject(new Error(response.message || response.error));
+        } else {
+          resolve(response);
+        }
+      });
+    });
+  };
+
+  /**
+   * Disconnect from the game socket
+   */
+  game.disconnect = function() {
+    const self = this;
+
+    // Always clear heartbeat
+    if (self._heartbeatInterval) {
+      clearInterval(self._heartbeatInterval);
+      self._heartbeatInterval = null;
+    }
+
+    if (self.directMode) {
+      if (self.directSocket) {
+        try { self.directSocket.close(); } catch (e) {}
+      }
+      self.directSocket = null;
+      self.connected = false;
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._connecting = false;
+      self._connectPromise = null;
+      self._joined = false;
+      self._joinPromise = null;
+      self.directMode = false;
+      self.directConfig = null;
+      self._directSeq = 0;
+      return;
+    }
+
+    if (self._useProxy) {
+      Usion._post({ type: 'GAME_DISCONNECT' });
+      self.connected = false;
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._connecting = false;
+      self._connectPromise = null;
+      self._joined = false;
+      self._joinPromise = null;
+      self._useProxy = false;
+      return;
+    }
+
+    if (self.socket) {
+      self.socket.disconnect();
+      self.socket = null;
+      self.connected = false;
+      self.roomId = null;
+      self._lastSequence = 0;
+      self._connecting = false;
+      self._connectPromise = null;
+      self._joined = false;
+      self._joinPromise = null;
+    }
+  };
+
+  /**
+   * Get connection status
+   * @returns {boolean}
+   */
+  game.isConnected = function() {
+    if (this.directMode) {
+      return this.connected && this.directSocket && this.directSocket.readyState === WebSocket.OPEN;
+    }
+    return this.connected && this.socket && this.socket.connected;
+  };
+}

package/src/modules/game-proxy.js

@@ -0,0 +1,149 @@
+/**
+ * Usion SDK Game Proxy — postMessage relay through parent app
+ */
+
+/**
+ * Add proxy connection methods to game module
+ * @param {object} game - The game module object
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function applyGameProxy(game, Usion) {
+  /**
+   * Connect via parent app proxy (postMessage relay).
+   * Used when mixed content prevents direct socket connection.
+   * @private
+   */
+  game._connectViaProxy = function() {
+    var self = this;
+
+    if (self._useProxy && self.connected) {
+      return Promise.resolve();
+    }
+
+    self._useProxy = true;
+    self._connecting = true;
+    self._setupProxyListener();
+
+    self._connectPromise = new Promise(function(resolve, reject) {
+      // Listen for GAME_CONNECTED from parent
+      self._proxyConnectResolve = function() {
+        self.connected = true;
+        self._connecting = false;
+        Usion.log('Game socket connected via parent proxy');
+        resolve();
+      };
+
+      // Send connect request to parent
+      Usion._post({ type: 'GAME_CONNECT' });
+
+      // Timeout after 10s
+      setTimeout(function() {
+        if (!self.connected) {
+          self._connecting = false;
+          reject(new Error('Proxy connection timeout'));
+        }
+      }, 10000);
+    });
+
+    return self._connectPromise;
+  };
+
+  /**
+   * Set up message listener for proxy game events from parent.
+   * @private
+   */
+  game._setupProxyListener = function() {
+    var self = this;
+    if (self._proxyListenerSetup) return;
+    self._proxyListenerSetup = true;
+
+    window.addEventListener('message', function(event) {
+      var data;
+      try {
+        data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+      } catch (e) {
+        return;
+      }
+      if (!data || typeof data !== 'object' || !self._useProxy) return;
+
+      switch (data.type) {
+        case 'GAME_CONNECTED':
+          if (self._proxyConnectResolve) {
+            self._proxyConnectResolve();
+            self._proxyConnectResolve = null;
+          }
+          break;
+
+        case 'GAME_CONNECT_ERROR':
+          self.connected = false;
+          self._connecting = false;
+          break;
+
+        case 'GAME_JOINED':
+          self._joined = true;
+          if (data.sequence !== undefined) self._lastSequence = data.sequence;
+          if (self._proxyJoinResolve) {
+            self._proxyJoinResolve(data);
+            self._proxyJoinResolve = null;
+          }
+          if (self._eventHandlers.joined) self._eventHandlers.joined(data);
+          break;
+
+        case 'GAME_JOIN_ERROR':
+          self._joined = false;
+          if (self._proxyJoinReject) {
+            self._proxyJoinReject(new Error(data.message || 'Join failed'));
+            self._proxyJoinReject = null;
+          }
+          break;
+
+        case 'GAME_PLAYER_JOINED':
+          if (self._eventHandlers.playerJoined) self._eventHandlers.playerJoined(data);
+          break;
+
+        case 'GAME_PLAYER_LEFT':
+          if (self._eventHandlers.playerLeft) self._eventHandlers.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);
+          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);
+          break;
+
+        case 'GAME_REALTIME_DATA':
+          if (self._eventHandlers.realtime) self._eventHandlers.realtime(data);
+          break;
+
+        case 'GAME_FINISHED':
+          if (data.sequence !== undefined) self._lastSequence = data.sequence;
+          if (self._eventHandlers.finished) self._eventHandlers.finished(data);
+          break;
+
+        case 'GAME_ERROR':
+          Usion.log('Game error via proxy: ' + (data.message || data.code));
+          if (self._eventHandlers.error) self._eventHandlers.error(data);
+          break;
+
+        case 'GAME_RESTARTED':
+          self._lastSequence = 0;
+          if (self._eventHandlers.restarted) self._eventHandlers.restarted(data);
+          break;
+
+        case 'GAME_REMATCH_REQUEST':
+          if (self._eventHandlers.rematchRequest) self._eventHandlers.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);
+          break;
+      }
+    });
+  };
+}