gameglue 4.0.0 → 4.0.2

package/types/index.d.ts

@@ -1,338 +1,338 @@
-declare module 'gameglue' {
-  export interface GameGlueConfig {
-    /** OAuth client ID registered with GameGlue */
-    clientId: string;
-    /** Scopes to request (e.g., ['msfs:read', 'msfs:write', 'xplane:read', 'xplane:write']) */
-    scopes?: string[];
-    /** OAuth redirect URI (defaults to window.location.href) */
-    redirect_uri?: string;
-    /** Custom socket server URL (defaults to https://socks.gameglue.gg) */
-    socketUrl?: string;
-    /** Custom auth server URL (defaults to https://auth.gameglue.gg/realms/GameGlue) */
-    authUrl?: string;
-  }
-
-  export interface ListenerConfig {
-    /** User ID to listen to (from getUser()) */
-    userId: string;
-    /** Game ID (e.g., 'msfs', 'xplane') */
-    gameId: string;
-    /** Optional list of fields to subscribe to */
-    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;
-  }
-
-  export interface UpdateEvent<T = Record<string, unknown>, R = Record<string, unknown>> {
-    /** Normalized telemetry data (canonical field names) */
-    data: T;
-    /** Raw telemetry data (game-specific field names) */
-    raw: R;
-  }
-
-  // ===========================================
-  // DERIVED EVENTS
-  // ===========================================
-
-  /** Position coordinates */
-  export interface Position {
-    lat: number;
-    lon: number;
-  }
-
-  /** Landing quality rating based on touchdown rate */
-  export type LandingQuality = 'butter' | 'smooth' | 'normal' | 'firm' | 'hard' | 'crash';
-
-  /** Bounce data for tracking bounces before final landing */
-  export interface BounceData {
-    /** Vertical speed at this bounce (feet per minute) */
-    landing_rate: number;
-    /** Landing quality of this bounce */
-    quality: LandingQuality;
-    /** How long the aircraft was airborne during this bounce (ms) */
-    airborne_duration_ms: number;
-  }
-
-  /** Landing event - fired when aircraft touches down and stabilizes */
-  export interface LandingEvent {
-    /** Vertical speed at first touchdown (feet per minute, negative = descending) */
-    landing_rate: number;
-    /** Landing quality rating (based on first touchdown) */
-    quality: LandingQuality;
-    /** Pitch angle at touchdown (degrees) */
-    pitch_at_touchdown: number;
-    /** Roll angle at touchdown (degrees) */
-    roll_at_touchdown: number;
-    /** Indicated airspeed at touchdown (knots) */
-    speed_at_touchdown: number;
-    /** Heading at touchdown (degrees) */
-    heading_at_touchdown: number;
-    /** Touchdown position */
-    position: Position;
-    /** Number of bounces before landing stabilized (0 = clean landing) */
-    bounce_count: number;
-    /** Details of each bounce (if any) */
-    bounces: BounceData[];
-    /** Event timestamp (ms since epoch) */
-    timestamp: number;
-  }
-
-  /** Takeoff event - fired when aircraft leaves the ground */
-  export interface TakeoffEvent {
-    /** Speed at rotation (knots) */
-    rotation_speed: number;
-    /** Pitch angle at liftoff (degrees) */
-    pitch_at_liftoff: number;
-    /** Heading at liftoff (degrees) */
-    heading_at_liftoff: number;
-    /** Liftoff position */
-    position: Position;
-    /** Flap setting at liftoff (0-1 ratio) */
-    flaps_setting: number;
-    /** Event timestamp (ms since epoch) */
-    timestamp: number;
-  }
-
-  /** Flight phases */
-  export type FlightPhase =
-    | 'parked'
-    | 'taxi_out'
-    | 'takeoff_roll'
-    | 'initial_climb'
-    | 'climb'
-    | 'cruise'
-    | 'descent'
-    | 'approach'
-    | 'final'
-    | 'landing_roll'
-    | 'taxi_in';
-
-  /** Flight phase change event */
-  export interface FlightPhaseEvent {
-    /** Current flight phase */
-    phase: FlightPhase;
-    /** Previous flight phase */
-    previous_phase: FlightPhase;
-    /** Current altitude above ground level (feet AGL) */
-    altitude_agl: number;
-    /** Current altitude mean sea level (feet MSL) */
-    altitude_msl: number;
-    /** Current indicated airspeed (knots) */
-    speed: number;
-    /** Event timestamp (ms since epoch) */
-    timestamp: number;
-  }
-
-  export interface Listener {
-    /**
-     * Subscribe to telemetry update events
-     * @param event Event name ('update')
-     * @param callback Callback function receiving update data
-     */
-    on<T = Record<string, unknown>, R = Record<string, unknown>>(
-      event: 'update',
-      callback: (evt: UpdateEvent<T, R>) => void
-    ): void;
-
-    /**
-     * Subscribe to landing events
-     * @param event Event name ('landing')
-     * @param callback Callback function receiving landing data
-     */
-    on(event: 'landing', callback: (evt: LandingEvent) => void): void;
-
-    /**
-     * Subscribe to takeoff events
-     * @param event Event name ('takeoff')
-     * @param callback Callback function receiving takeoff data
-     */
-    on(event: 'takeoff', callback: (evt: TakeoffEvent) => void): void;
-
-    /**
-     * Subscribe to flight phase change events
-     * @param event Event name ('flight_phase')
-     * @param callback Callback function receiving flight phase data
-     */
-    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 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)
-     */
-    sendCommand(command: string, value?: unknown): Promise<CommandResult>;
-
-    /**
-     * Subscribe to additional fields dynamically
-     * @param fields Array of field names to add
-     */
-    subscribe(fields: string[]): Promise<CommandResult>;
-
-    /**
-     * Unsubscribe from specific fields
-     * @param fields Array of field names to remove
-     */
-    unsubscribe(fields: string[]): Promise<CommandResult>;
-
-    /**
-     * Get the current list of subscribed fields
-     * @returns Array of field names, or null if receiving all fields
-     */
-    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;
-  }
-
-  export class GameGlue {
-    constructor(config: GameGlueConfig);
-
-    /**
-     * Check if user is authenticated.
-     * If OAuth callback params are in URL, processes them first.
-     */
-    isAuthenticated(): Promise<boolean>;
-
-    /**
-     * Redirect to OAuth login page.
-     * Does not return - navigates away.
-     */
-    login(): void;
-
-    /**
-     * Log out the user.
-     * Clears local tokens and optionally redirects to Keycloak logout.
-     */
-    logout(options?: LogoutOptions): void;
-
-    /**
-     * Get the current user's ID.
-     * @throws Error if not authenticated
-     */
-    getUser(): string;
-
-    /**
-     * Get the access token for API calls.
-     */
-    getAccessToken(): string | undefined;
-
-    /**
-     * Create a listener for game telemetry.
-     * Connects to socket server lazily on first call.
-     */
-    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.
-     */
-    onTokenRefreshed(callback: (token: string) => void): void;
-  }
-
-  export default GameGlue;
-}
+declare module 'gameglue' {
+  export interface GameGlueConfig {
+    /** OAuth client ID registered with GameGlue */
+    clientId: string;
+    /** Scopes to request (e.g., ['msfs:read', 'msfs:write', 'xplane:read', 'xplane:write']) */
+    scopes?: string[];
+    /** OAuth redirect URI (defaults to window.location.href) */
+    redirect_uri?: string;
+    /** Custom socket server URL (defaults to https://socks.gameglue.gg) */
+    socketUrl?: string;
+    /** Custom auth server URL (defaults to https://auth.gameglue.gg/realms/GameGlue) */
+    authUrl?: string;
+  }
+
+  export interface ListenerConfig {
+    /** User ID to listen to (from getUser()) */
+    userId: string;
+    /** Game ID (e.g., 'msfs', 'xplane') */
+    gameId: string;
+    /** Optional list of fields to subscribe to */
+    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;
+  }
+
+  export interface UpdateEvent<T = Record<string, unknown>, R = Record<string, unknown>> {
+    /** Normalized telemetry data (canonical field names) */
+    data: T;
+    /** Raw telemetry data (game-specific field names) */
+    raw: R;
+  }
+
+  // ===========================================
+  // DERIVED EVENTS
+  // ===========================================
+
+  /** Position coordinates */
+  export interface Position {
+    lat: number;
+    lon: number;
+  }
+
+  /** Landing quality rating based on touchdown rate */
+  export type LandingQuality = 'butter' | 'smooth' | 'normal' | 'firm' | 'hard' | 'crash';
+
+  /** Bounce data for tracking bounces before final landing */
+  export interface BounceData {
+    /** Vertical speed at this bounce (feet per minute) */
+    landing_rate: number;
+    /** Landing quality of this bounce */
+    quality: LandingQuality;
+    /** How long the aircraft was airborne during this bounce (ms) */
+    airborne_duration_ms: number;
+  }
+
+  /** Landing event - fired when aircraft touches down and stabilizes */
+  export interface LandingEvent {
+    /** Vertical speed at first touchdown (feet per minute, negative = descending) */
+    landing_rate: number;
+    /** Landing quality rating (based on first touchdown) */
+    quality: LandingQuality;
+    /** Pitch angle at touchdown (degrees) */
+    pitch_at_touchdown: number;
+    /** Roll angle at touchdown (degrees) */
+    roll_at_touchdown: number;
+    /** Indicated airspeed at touchdown (knots) */
+    speed_at_touchdown: number;
+    /** Heading at touchdown (degrees) */
+    heading_at_touchdown: number;
+    /** Touchdown position */
+    position: Position;
+    /** Number of bounces before landing stabilized (0 = clean landing) */
+    bounce_count: number;
+    /** Details of each bounce (if any) */
+    bounces: BounceData[];
+    /** Event timestamp (ms since epoch) */
+    timestamp: number;
+  }
+
+  /** Takeoff event - fired when aircraft leaves the ground */
+  export interface TakeoffEvent {
+    /** Speed at rotation (knots) */
+    rotation_speed: number;
+    /** Pitch angle at liftoff (degrees) */
+    pitch_at_liftoff: number;
+    /** Heading at liftoff (degrees) */
+    heading_at_liftoff: number;
+    /** Liftoff position */
+    position: Position;
+    /** Flap setting at liftoff (0-1 ratio) */
+    flaps_setting: number;
+    /** Event timestamp (ms since epoch) */
+    timestamp: number;
+  }
+
+  /** Flight phases */
+  export type FlightPhase =
+    | 'parked'
+    | 'taxi_out'
+    | 'takeoff_roll'
+    | 'initial_climb'
+    | 'climb'
+    | 'cruise'
+    | 'descent'
+    | 'approach'
+    | 'final'
+    | 'landing_roll'
+    | 'taxi_in';
+
+  /** Flight phase change event */
+  export interface FlightPhaseEvent {
+    /** Current flight phase */
+    phase: FlightPhase;
+    /** Previous flight phase */
+    previous_phase: FlightPhase;
+    /** Current altitude above ground level (feet AGL) */
+    altitude_agl: number;
+    /** Current altitude mean sea level (feet MSL) */
+    altitude_msl: number;
+    /** Current indicated airspeed (knots) */
+    speed: number;
+    /** Event timestamp (ms since epoch) */
+    timestamp: number;
+  }
+
+  export interface Listener {
+    /**
+     * Subscribe to telemetry update events
+     * @param event Event name ('update')
+     * @param callback Callback function receiving update data
+     */
+    on<T = Record<string, unknown>, R = Record<string, unknown>>(
+      event: 'update',
+      callback: (evt: UpdateEvent<T, R>) => void
+    ): void;
+
+    /**
+     * Subscribe to landing events
+     * @param event Event name ('landing')
+     * @param callback Callback function receiving landing data
+     */
+    on(event: 'landing', callback: (evt: LandingEvent) => void): void;
+
+    /**
+     * Subscribe to takeoff events
+     * @param event Event name ('takeoff')
+     * @param callback Callback function receiving takeoff data
+     */
+    on(event: 'takeoff', callback: (evt: TakeoffEvent) => void): void;
+
+    /**
+     * Subscribe to flight phase change events
+     * @param event Event name ('flight_phase')
+     * @param callback Callback function receiving flight phase data
+     */
+    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 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)
+     */
+    sendCommand(command: string, value?: unknown): Promise<CommandResult>;
+
+    /**
+     * Subscribe to additional fields dynamically
+     * @param fields Array of field names to add
+     */
+    subscribe(fields: string[]): Promise<CommandResult>;
+
+    /**
+     * Unsubscribe from specific fields
+     * @param fields Array of field names to remove
+     */
+    unsubscribe(fields: string[]): Promise<CommandResult>;
+
+    /**
+     * Get the current list of subscribed fields
+     * @returns Array of field names, or null if receiving all fields
+     */
+    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;
+  }
+
+  export class GameGlue {
+    constructor(config: GameGlueConfig);
+
+    /**
+     * Check if user is authenticated.
+     * If OAuth callback params are in URL, processes them first.
+     */
+    isAuthenticated(): Promise<boolean>;
+
+    /**
+     * Redirect to OAuth login page.
+     * Does not return - navigates away.
+     */
+    login(): void;
+
+    /**
+     * Log out the user.
+     * Clears local tokens and optionally redirects to Keycloak logout.
+     */
+    logout(options?: LogoutOptions): void;
+
+    /**
+     * Get the current user's ID.
+     * @throws Error if not authenticated
+     */
+    getUser(): string;
+
+    /**
+     * Get the access token for API calls.
+     */
+    getAccessToken(): string | undefined;
+
+    /**
+     * Create a listener for game telemetry.
+     * Connects to socket server lazily on first call.
+     */
+    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.
+     */
+    onTokenRefreshed(callback: (token: string) => void): void;
+  }
+
+  export default GameGlue;
+}