gameglue 3.0.2 → 4.0.0

package/examples/server.js

@@ -27,8 +27,8 @@ function handleRequest(req, res) {
   // Remove query string
   filePath = filePath.split('?')[0];
 
-  // Security: prevent directory traversal
-  filePath = path.normalize(filePath).replace(/^(\.\.[\/\\])+/, '');
+  // Security: prevent directory traversal (normalize but keep forward slashes for URL matching)
+  filePath = path.normalize(filePath).replace(/^(\.\.[\/\\])+/, '').split(path.sep).join('/');
 
   // Check if requesting SDK from parent dist folder
   if (filePath.startsWith('/dist/')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gameglue",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "description": "Javascript SDK for the GameGlue developer platform.",
   "type": "module",
   "main": "dist/gg.cjs.js",

package/src/auth.js

@@ -180,7 +180,7 @@ export class GameGlueAuth {
     if (token) {
       this._setTokenRefreshTimeout(token);
     }
-    return token;
+    return token || undefined;
   }
 
   _setAccessToken(token) {

package/src/index.js

@@ -1,6 +1,7 @@
 import { GameGlueAuth } from './auth';
 import { io } from "socket.io-client";
 import { Listener } from "./listener";
+import { PresenceListener } from "./presence_listener";
 import { isCorsError, logCorsHelp } from './utils';
 import { getGameSchema, getCategorySchema, normalizeTelemetry } from '@gameglue/schemas';
 
@@ -52,6 +53,48 @@ class GameGlue extends GameGlueAuth {
     return listener.setupEventListener();
   }
 
+  /**
+   * Create a presence listener for public broadcaster updates.
+   * This does not require authentication.
+   * @param {Object} config - { clientId, gameId }
+   * @returns {Promise<PresenceListener>}
+   */
+  async createPresenceListener(config) {
+    if (!config) throw new Error('Not a valid presence listener config');
+    if (!config.gameId || !GAME_IDS[config.gameId]) throw new Error('Not a valid Game ID');
+    if (!config.clientId) throw new Error('Client ID not supplied');
+
+    const socket = io(this._socketUrl, {
+      transports: ['websocket'],
+    });
+
+    await new Promise((resolve, reject) => {
+      socket.on('connect', resolve);
+      socket.on('connect_error', (err) => {
+        if (isCorsError(err)) {
+          logCorsHelp('WebSocket Connection', this._socketUrl);
+        }
+        reject(new Error(`Socket connection failed: ${err.message}`));
+      });
+    });
+
+    const listener = new PresenceListener(socket, config);
+    const establishConnectionResponse = await listener.establishConnection();
+
+    // Handle reconnection
+    socket.io.on('reconnect', () => {
+      listener.establishConnection();
+    });
+
+    if (establishConnectionResponse.status !== 'success') {
+      throw new Error(
+        `There was a problem setting up the presence listener. Reason: ${establishConnectionResponse.reason}`
+      );
+    }
+
+    return listener.setupEventListener();
+  }
+
   // ============ Internal Methods ============
 
   async _ensureConnected() {

package/src/listener.js

@@ -1,5 +1,5 @@
 import EventEmitter from 'event-emitter';
-import { getGameSchema, normalizeTelemetry, denormalizeCommand } from '@gameglue/schemas';
+import { getGameSchema, normalizeTelemetry } from '@gameglue/schemas';
 
 export class Listener  {
   constructor(socket, config) {
@@ -150,26 +150,13 @@ export class Listener  {
       throw new Error('command must be a non-empty string');
     }
 
-    // Denormalize canonical command to game-specific command
-    let gameCommand = command;
-    let gameValue = value;
-
-    if (this._gameSchema) {
-      const denormalized = denormalizeCommand(command, this._gameSchema, value);
-      if (denormalized) {
-        gameCommand = denormalized.command;
-        gameValue = denormalized.value;
-      }
-      // If not found, pass through as-is (allows game-specific commands)
-    }
-
     return new Promise((resolve) => {
       const payload = {
         userId: this._config.userId,
         gameId: this._config.gameId,
         data: {
-          fieldName: gameCommand,
-          value: gameValue
+          fieldName: command,
+          value
         }
       };
 
@@ -203,4 +190,4 @@ export class Listener  {
   }
 }
 
-EventEmitter(Listener.prototype);
+EventEmitter(Listener.prototype);

package/src/listener.spec.js

@@ -6,11 +6,12 @@ jest.mock('@gameglue/schemas', () => ({
   getGameSchema: jest.fn(() => ({
     gameId: 'msfs',
     fieldMappings: {},  // Empty means no transformation, fields pass through
-    commandMappings: {},
+    commandMappings: {
+      gear_up: { gameCommand: 'GEAR_UP', type: 'command' }
+    },
     extraFields: {}
   })),
-  normalizeTelemetry: jest.fn((raw) => raw),  // Identity function - return raw data as-is
-  denormalizeCommand: jest.fn((cmd, schema, value) => ({ command: cmd, value }))
+  normalizeTelemetry: jest.fn((raw) => raw)  // Identity function - return raw data as-is
 }));
 
 describe('Listener', () => {
@@ -420,6 +421,21 @@ describe('Listener', () => {
       expect(result).toEqual({ status: 'success' });
     });
 
+    it('should send canonical command without denormalizing', async () => {
+      await listener.sendCommand('gear_up', true);
+
+      expect(mockSocket.emit).toHaveBeenCalledWith(
+        'set',
+        expect.objectContaining({
+          data: {
+            fieldName: 'gear_up',
+            value: true
+          }
+        }),
+        expect.any(Function)
+      );
+    });
+
     it('should handle various value types', async () => {
       await listener.sendCommand('altitude', 35000);
       await listener.sendCommand('flaps', 0.5);

package/src/presence_listener.js

@@ -0,0 +1,112 @@
+import EventEmitter from 'event-emitter';
+import { getGameSchema, normalizeTelemetry } from '@gameglue/schemas';
+
+export class PresenceListener {
+  constructor(socket, config) {
+    this._config = config;
+    this._socket = socket;
+    this._gameSchema = getGameSchema(config.gameId);
+    this._broadcasters = [];
+  }
+
+  async establishConnection() {
+    if (!this._socket || !this._config.clientId || !this._config.gameId) {
+      throw new Error('Missing arguments in establishConnection');
+    }
+
+    return new Promise((resolve) => {
+      const payload = {
+        clientId: this._config.clientId,
+        gameId: this._config.gameId
+      };
+
+      this._socket.timeout(5000).emit('presenceSubscribe', payload, (error, response) => {
+        if (error) {
+          return resolve({ status: 'failed', reason: 'Presence request timed out.' });
+        }
+
+        if (response?.status === 'success') {
+          const broadcasters = Array.isArray(response.broadcasters)
+            ? response.broadcasters.map((snapshot) => this._normalizeSnapshot(snapshot))
+            : [];
+          this._broadcasters = broadcasters;
+          return resolve({ status: 'success', broadcasters });
+        }
+
+        return resolve({
+          status: 'failed',
+          reason: response?.reason || 'Presence subscription failed.'
+        });
+      });
+    });
+  }
+
+  setupEventListener() {
+    this._socket.on('presence-update', (snapshot) => {
+      const normalized = this._normalizeSnapshot(snapshot);
+      this._upsertBroadcaster(normalized);
+      this.emit('update', normalized);
+    });
+
+    this._socket.on('presence-remove', ({ userId }) => {
+      if (!userId) return;
+      this._broadcasters = this._broadcasters.filter((b) => b.userId !== userId);
+      this.emit('remove', { userId });
+    });
+
+    this._socket.on('connect', () => {
+      this.emit('connect');
+    });
+
+    this._socket.on('disconnect', (reason) => {
+      this.emit('disconnect', reason);
+    });
+
+    return this;
+  }
+
+  getBroadcasters() {
+    return [...this._broadcasters];
+  }
+
+  disconnect() {
+    if (this._socket) {
+      this._socket.disconnect();
+    }
+  }
+
+  _normalizeSnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object') {
+      return snapshot;
+    }
+
+    const rawData = snapshot.data;
+    const normalizedData = rawData && this._gameSchema
+      ? normalizeTelemetry(rawData, this._gameSchema)
+      : rawData;
+
+    return {
+      ...snapshot,
+      data: normalizedData,
+      raw: rawData
+    };
+  }
+
+  _upsertBroadcaster(snapshot) {
+    if (!snapshot || !snapshot.userId) {
+      return;
+    }
+
+    const idx = this._broadcasters.findIndex((b) => b.userId === snapshot.userId);
+    if (idx >= 0) {
+      const next = [...this._broadcasters];
+      next[idx] = snapshot;
+      this._broadcasters = next;
+      return;
+    }
+
+    this._broadcasters = [...this._broadcasters, snapshot];
+  }
+}
+
+EventEmitter(PresenceListener.prototype);

package/types/index.d.ts

@@ -21,6 +21,23 @@ declare module 'gameglue' {
     fields?: string[];
   }
 
+  export interface PresenceListenerConfig {
+    /** Client ID of the app (e.g., 'remote-pilot') */
+    clientId: string;
+    /** Game ID (e.g., 'msfs', 'xplane') */
+    gameId: string;
+  }
+
+  export interface PresenceSnapshot<T = Record<string, unknown>, R = Record<string, unknown>> {
+    userId: string;
+    username: string;
+    displayName: string;
+    gameId: string;
+    data: T;
+    raw?: R;
+    updatedAt: number;
+  }
+
   export interface CommandResult {
     status: 'success' | 'failed';
     reason?: string;
@@ -158,9 +175,32 @@ declare module 'gameglue' {
      */
     on(event: 'flight_phase', callback: (evt: FlightPhaseEvent) => void): void;
 
+    /**
+     * Unsubscribe a callback from telemetry update events
+     */
+    off<T = Record<string, unknown>, R = Record<string, unknown>>(
+      event: 'update',
+      callback: (evt: UpdateEvent<T, R>) => void
+    ): void;
+
+    /**
+     * Unsubscribe a callback from landing events
+     */
+    off(event: 'landing', callback: (evt: LandingEvent) => void): void;
+
+    /**
+     * Unsubscribe a callback from takeoff events
+     */
+    off(event: 'takeoff', callback: (evt: TakeoffEvent) => void): void;
+
+    /**
+     * Unsubscribe a callback from flight phase change events
+     */
+    off(event: 'flight_phase', callback: (evt: FlightPhaseEvent) => void): void;
+
     /**
      * Send a command to the broadcaster (game client)
-     * Commands are automatically denormalized from canonical names to game-specific commands.
+     * Commands are sent as canonical names; the game client handles game-specific translation.
      * @param command The canonical command name (e.g., 'gear_up', 'set_autopilot_heading')
      * @param value The value to set (optional for toggle commands)
      */
@@ -185,6 +225,60 @@ declare module 'gameglue' {
     getFields(): string[] | null;
   }
 
+  export interface PresenceListener {
+    /**
+     * Subscribe to presence update events
+     * @param event Event name ('update')
+     * @param callback Callback function receiving presence snapshot
+     */
+    on<T = Record<string, unknown>, R = Record<string, unknown>>(
+      event: 'update',
+      callback: (snapshot: PresenceSnapshot<T, R>) => void
+    ): void;
+
+    /**
+     * Subscribe to presence removal events
+     * @param event Event name ('remove')
+     * @param callback Callback function receiving removed userId
+     */
+    on(event: 'remove', callback: (evt: { userId: string }) => void): void;
+
+    /**
+     * Subscribe to connection events
+     */
+    on(event: 'connect', callback: () => void): void;
+    on(event: 'disconnect', callback: (reason?: string) => void): void;
+
+    /**
+     * Unsubscribe a callback from presence update events
+     */
+    off<T = Record<string, unknown>, R = Record<string, unknown>>(
+      event: 'update',
+      callback: (snapshot: PresenceSnapshot<T, R>) => void
+    ): void;
+
+    /**
+     * Unsubscribe a callback from presence removal events
+     */
+    off(event: 'remove', callback: (evt: { userId: string }) => void): void;
+
+    /**
+     * Unsubscribe from connection events
+     */
+    off(event: 'connect', callback: () => void): void;
+    off(event: 'disconnect', callback: (reason?: string) => void): void;
+
+    /**
+     * Get current list of broadcasters
+     */
+    getBroadcasters<T = Record<string, unknown>, R = Record<string, unknown>>(): PresenceSnapshot<T, R>[];
+
+    /**
+     * Disconnect the presence socket
+     */
+    disconnect(): void;
+  }
+
   export interface LogoutOptions {
     /** If false, only clears local tokens without redirecting to Keycloak logout */
     redirect?: boolean;
@@ -220,7 +314,7 @@ declare module 'gameglue' {
     /**
      * Get the access token for API calls.
      */
-    getAccessToken(): string | null;
+    getAccessToken(): string | undefined;
 
     /**
      * Create a listener for game telemetry.
@@ -228,6 +322,12 @@ declare module 'gameglue' {
      */
     createListener(config: ListenerConfig): Promise<Listener>;
 
+    /**
+     * Create a presence listener for public broadcaster updates.
+     * Does not require authentication.
+     */
+    createPresenceListener(config: PresenceListenerConfig): Promise<PresenceListener>;
+
     /**
      * Register callback for token refresh events.
      */