@my-swu/simulator-client 0.1.0

package/dist/resources/limited-event-types.d.ts

@@ -0,0 +1,252 @@
+import type { CreateLimitedEventRequest, JoinLimitedEventRequest, LimitedEventAccessResponse, LimitedEventPreflightResponse } from '../generated/index.js';
+import type { LimitedEventSnapshot as GeneratedLimitedEventSnapshot } from '../generated/types/limited-event-access-response.js';
+import type { LimitedEventCommand as GeneratedLimitedEventCommand } from '../generated/types/limited-event-command-request.js';
+import type { SimulatorRequestOptions } from '../http/options.js';
+/**
+ * Access token and private snapshot returned after creating or joining a Limited Event.
+ *
+ * Keep `seatToken` private. It authorizes one player seat inside the event pod.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, type LimitedEventAccess } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const draftEventAccess: LimitedEventAccess =
+ *   await simulatorClient.limitedEvents.create({
+ *     kind: 'draft',
+ *     draftRounds: [],
+ *     pickTimerEnabled: false,
+ *     setCode: 'SOR',
+ *     playerCount: 4,
+ *   })
+ * console.log(draftEventAccess.eventId)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export type LimitedEventAccess = LimitedEventAccessResponse;
+/**
+ * Player command accepted by one Limited Event seat.
+ *
+ * Commands drive hidden draft picks, leader choices, and ready gates.
+ *
+ * @example
+ * ```ts
+ * import type { LimitedEventCommand } from '@my-swu/simulator-client'
+ *
+ * const readyForNextDraft: LimitedEventCommand = {
+ *   type: 'readyForNextDraft',
+ * }
+ *
+ * console.log(readyForNextDraft.type)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export type LimitedEventCommand = GeneratedLimitedEventCommand;
+/** Read-only booster-pool validation result for a limited event request. */
+export type LimitedEventPreflight = LimitedEventPreflightResponse;
+/**
+ * Snapshot visible to the current Limited Event requester.
+ *
+ * Public event state is always present; viewer-private pack, pool, and pick
+ * data are included only when the request carries a valid seat token.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, type LimitedEventSnapshot } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const limitedEventSnapshot: LimitedEventSnapshot =
+ *   await simulatorClient.limitedEvents.get('event_123')
+ * console.log(limitedEventSnapshot.phase.kind)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export type LimitedEventSnapshot = GeneratedLimitedEventSnapshot;
+/**
+ * Public reference to one Limited Event.
+ *
+ * This reference is safe to share for join flows because it does not include a
+ * private seat token.
+ *
+ * @example
+ * ```ts
+ * import type { LimitedEventReference } from '@my-swu/simulator-client'
+ *
+ * const draftEventReference: LimitedEventReference = { eventId: 'event_123' }
+ * console.log(draftEventReference.eventId)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export interface LimitedEventReference {
+    /**
+     * Public Limited Event id.
+     */
+    eventId: string;
+}
+/**
+ * Minimal data needed to act as one Limited Event seat.
+ *
+ * Persist this shape when a browser needs to resume an event after a reload.
+ *
+ * @example
+ * ```ts
+ * import type { LimitedEventAccessInput } from '@my-swu/simulator-client'
+ *
+ * const draftSeatAccess: LimitedEventAccessInput = {
+ *   eventId: 'event_123',
+ *   seatToken: 'limited_token_123',
+ * }
+ *
+ * console.log(draftSeatAccess.eventId)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export interface LimitedEventAccessInput extends LimitedEventReference {
+    /**
+     * Private token authorizing one Limited Event seat.
+     */
+    seatToken: string;
+}
+/**
+ * Limited Event resource API methods.
+ *
+ * Use this resource for Draft and Sealed pods before creating a match from the
+ * completed pool.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const draftEventAccess = await simulatorClient.limitedEvents.create({
+ *   kind: 'draft',
+ *   draftRounds: [],
+ *   pickTimerEnabled: false,
+ *   setCode: 'SOR',
+ *   playerCount: 4,
+ * })
+ *
+ * console.log(draftEventAccess.snapshot.phase.kind)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/limited-events
+ */
+export interface LimitedEventsResource {
+    /**
+     * Checks whether every required booster can be generated without creating an
+     * event. Use the returned seed when creating the event after a clean check.
+     */
+    preflight(request: CreateLimitedEventRequest, options?: SimulatorRequestOptions): Promise<LimitedEventPreflight>;
+    /**
+     * Creates one generated Draft or Sealed event.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const draftEventAccess = await simulatorClient.limitedEvents.create({
+     *   kind: 'draft',
+     *   draftRounds: [],
+     *   pickTimerEnabled: false,
+     *   setCode: 'SOR',
+     *   playerCount: 4,
+     * })
+     *
+     * console.log(draftEventAccess.eventId)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/limited-events#create
+     */
+    create(request: CreateLimitedEventRequest, options?: SimulatorRequestOptions): Promise<LimitedEventAccess>;
+    /**
+     * Fetches one limited event, optionally with viewer-private state.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     * const draftSeatAccess = {
+     *   eventId: 'event_123',
+     *   seatToken: 'limited_token_123',
+     * }
+     *
+     * const limitedEventSnapshot =
+     *   await simulatorClient.limitedEvents.get(draftSeatAccess)
+     *
+     * console.log(limitedEventSnapshot.viewer?.activePack.length)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/limited-events#fetch-state
+     */
+    get(event: string | LimitedEventReference | LimitedEventAccessInput, options?: SimulatorRequestOptions): Promise<LimitedEventSnapshot>;
+    /**
+     * Applies one seat command to a limited event.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     * const draftSeatAccess = {
+     *   eventId: 'event_123',
+     *   seatToken: 'limited_token_123',
+     * }
+     *
+     * const limitedEventSnapshot =
+     *   await simulatorClient.limitedEvents.applyCommand(
+     *     draftSeatAccess,
+     *     { type: 'readyForNextDraft' },
+     *   )
+     *
+     * console.log(limitedEventSnapshot.phase.kind)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/limited-events#draft-commands
+     */
+    applyCommand(access: LimitedEventAccessInput, command: LimitedEventCommand, options?: SimulatorRequestOptions): Promise<LimitedEventSnapshot>;
+    /**
+     * Joins one limited event.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     * const draftEventReference = { eventId: 'event_123' }
+     *
+     * const draftSeatAccess =
+     *   await simulatorClient.limitedEvents.join(draftEventReference)
+     *
+     * console.log(draftSeatAccess.seatIndex)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/limited-events#join
+     */
+    join(event: LimitedEventReference, request?: JoinLimitedEventRequest, options?: SimulatorRequestOptions): Promise<LimitedEventAccess>;
+}

package/dist/resources/limited-event-types.js

@@ -0,0 +1 @@
+export {};

package/dist/resources/limited-events.d.ts

@@ -0,0 +1,7 @@
+import type { EngineHttpRequester } from '../http/request.js';
+import type { LimitedEventsResource } from './limited-event-types.js';
+export type * from './limited-event-types.js';
+/**
+ * Creates the Limited Event resource client.
+ */
+export declare function createLimitedEventsResource(requester: EngineHttpRequester): LimitedEventsResource;

package/dist/resources/limited-events.js

@@ -0,0 +1,49 @@
+import { jsonBody, jsonHeaders } from '../http/json.js';
+/**
+ * Creates the Limited Event resource client.
+ */
+export function createLimitedEventsResource(requester) {
+    return {
+        applyCommand: (access, command, options) => requester.request('limited-event-response', `/api/limited-events/${eventIdFrom(access)}/commands`, {
+            body: jsonBody(requester.validate('limited-event-command-request', {
+                command,
+                seatToken: access.seatToken,
+            })),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options).then(response => response.snapshot),
+        create: (request, options) => requester.request('limited-event-access-response', '/api/limited-events', {
+            body: jsonBody(requester.validate('create-limited-event-request', request)),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+        preflight: (request, options) => requester.request('limited-event-preflight-response', '/api/limited-events/preflight', {
+            body: jsonBody(requester.validate('create-limited-event-request', request)),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+        get: (event, options) => {
+            const seatToken = seatTokenFrom(event);
+            const query = seatToken == null ? '' : `?${new URLSearchParams({ seatToken }).toString()}`;
+            return requester.request('limited-event-response', `/api/limited-events/${eventIdFrom(event)}${query}`, {}, options)
+                .then(response => response.snapshot);
+        },
+        join: (event, request = {}, options) => requester.request('limited-event-access-response', `/api/limited-events/${eventIdFrom(event)}/join`, {
+            body: jsonBody(requester.validate('join-limited-event-request', request)),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+    };
+}
+/**
+ * Reads a Limited Event id from either a public id string or event reference object.
+ */
+function eventIdFrom(event) {
+    return typeof event === 'string' ? event : event.eventId;
+}
+/**
+ * Reads a Limited Event seat token when the input carries private seat access.
+ */
+function seatTokenFrom(event) {
+    return typeof event === 'string' || !('seatToken' in event) ? undefined : event.seatToken;
+}

package/dist/resources/lobbies.d.ts

@@ -0,0 +1,53 @@
+import type { SimulatorRequestOptions } from '../http/options.js';
+import type { EngineHttpRequester } from '../http/request.js';
+import type { WebSocketFactory } from '../internal/transport.js';
+import type { SchemaValidator } from '../validators/validator.js';
+import type { AddLobbyAiPlayerRequest, CreateLobbyRequest, JoinLobbyRequest, KickLobbyPlayerRequest, KickLobbySpectatorRequest, LeaveLobbyRequest, LobbyAccessInput, LobbyAccessResponse, LobbyChatRequest, LobbyChatResponse, LobbyListResponse, LobbyListSession, LobbyListSessionOptions, LobbyMatchmakingDecisionRequest, LobbyMatchmakingRequest, PrepareLobbyLimitedAiDecksRequest, LobbySession, LobbySnapshot, LobbySyncRequest, ReturnLobbyMatchRequest, StartLobbyLimitedMatchRequest, StartLobbyRequest, SpectateLobbyRequest, SubmitLobbyLimitedDeckRequest, UpdateLobbyAiPlayerRequest, UpdateLobbyPlayerRequest, UpdateLobbySettingsRequest } from './lobby-types.js';
+export type * from './lobby-types.js';
+export interface LobbiesResource {
+    create(request: CreateLobbyRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    /**
+     * Queues the player through the unified matchmaking entry point. The
+     * server chooses the pairing pool; the response never reveals more than
+     * the shared lobby matchmaking handshake.
+     */
+    matchmake(request: LobbyMatchmakingRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    acceptMatchmaking(lobbyId: string, request: LobbyMatchmakingDecisionRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    declineMatchmaking(lobbyId: string, request: LobbyMatchmakingDecisionRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    list(options?: SimulatorRequestOptions): Promise<LobbyListResponse>;
+    /**
+     * Subscribes to live public lobby-list updates over `GET /ws/lobbies`.
+     *
+     * Returns a session controller that opens an unauthenticated WebSocket, emits
+     * the current list on connect and a fresh full snapshot on every change, and
+     * auto-reconnects on abnormal close. Prefer this over polling {@link list};
+     * keep {@link list} as a one-shot fallback when the socket cannot open.
+     */
+    subscribeList(options?: LobbyListSessionOptions): LobbyListSession;
+    get(lobbyId: string, options?: SimulatorRequestOptions): Promise<LobbySnapshot>;
+    join(lobbyId: string, request: JoinLobbyRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    spectate(lobbyId: string, request: SpectateLobbyRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    sync(lobbyId: string, request: LobbySyncRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    updatePlayer(lobbyId: string, request: UpdateLobbyPlayerRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    addAiPlayer(lobbyId: string, request: AddLobbyAiPlayerRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    updateAiPlayer(lobbyId: string, playerId: string, request: UpdateLobbyAiPlayerRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    updateSettings(lobbyId: string, request: UpdateLobbySettingsRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    kickPlayer(lobbyId: string, playerId: string, request: KickLobbyPlayerRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    kickSpectator(lobbyId: string, spectatorId: string, request: KickLobbySpectatorRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    sendChat(lobbyId: string, request: LobbyChatRequest, options?: SimulatorRequestOptions): Promise<LobbyChatResponse>;
+    start(lobbyId: string, request: StartLobbyRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    returnMatch(lobbyId: string, request: ReturnLobbyMatchRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    submitLimitedDeck(lobbyId: string, request: SubmitLobbyLimitedDeckRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    prepareLimitedAiDecks(lobbyId: string, request: PrepareLobbyLimitedAiDecksRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    startLimitedMatch(lobbyId: string, request: StartLobbyLimitedMatchRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    leave(lobbyId: string, request: LeaveLobbyRequest, options?: SimulatorRequestOptions): Promise<LobbyAccessResponse>;
+    createSession(access: LobbyAccessInput | LobbyAccessResponse): LobbySession;
+}
+export interface LobbiesResourceOptions {
+    requester: EngineHttpRequester;
+    /** Boundary validator applied to the lobby and public lobby-list sockets. */
+    validate?: SchemaValidator | undefined;
+    webSocketFactory?: WebSocketFactory | undefined;
+    wsUrl: string;
+}
+export declare function createLobbiesResource(options: LobbiesResourceOptions): LobbiesResource;

package/dist/resources/lobbies.js

@@ -0,0 +1,50 @@
+import { createValidatedJsonPost } from '../http/validated-json.js';
+import { getDefaultWebSocketFactory } from '../internal/transport.js';
+import { createLobbyListSession } from './lobby-list-session.js';
+import { createLobbySession } from './lobby-session.js';
+export function createLobbiesResource(options) {
+    const { requester } = options;
+    const webSocketFactory = options.webSocketFactory ?? getDefaultWebSocketFactory();
+    const jsonPost = createValidatedJsonPost(requester);
+    return {
+        create: (request, options) => requestResource(requester, 'lobby-access-response', '/api/lobbies', jsonPost('create-lobby-request', request), options),
+        matchmake: (request, options) => requestResource(requester, 'lobby-access-response', '/api/lobbies/matchmaking', jsonPost('lobby-matchmaking-request', request), options),
+        acceptMatchmaking: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/matchmaking/accept`, jsonPost('lobby-matchmaking-decision-request', request), options),
+        declineMatchmaking: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/matchmaking/decline`, jsonPost('lobby-matchmaking-decision-request', request), options),
+        list: options => requestResource(requester, 'lobby-list-response', '/api/lobbies', undefined, options),
+        get: (lobbyId, options) => requestResource(requester, 'lobby-response', `/api/lobbies/${lobbyId}`, undefined, options)
+            .then(response => response.snapshot),
+        join: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/join`, jsonPost('join-lobby-request', request), options),
+        spectate: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/spectate`, jsonPost('spectate-lobby-request', request), options),
+        sync: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/sync`, jsonPost('lobby-sync-request', request), options),
+        updatePlayer: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/players/me`, jsonPost('update-lobby-player-request', request), options),
+        addAiPlayer: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/players/ai`, jsonPost('add-lobby-ai-player-request', request), options),
+        updateAiPlayer: (lobbyId, playerId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/players/${playerId}/ai`, jsonPost('update-lobby-ai-player-request', request), options),
+        updateSettings: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/settings`, jsonPost('update-lobby-settings-request', request), options),
+        kickPlayer: (lobbyId, playerId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/players/${playerId}/kick`, jsonPost('kick-lobby-player-request', request), options),
+        kickSpectator: (lobbyId, spectatorId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/spectators/${spectatorId}/kick`, jsonPost('kick-lobby-spectator-request', request), options),
+        sendChat: (lobbyId, request, options) => requestResource(requester, 'lobby-chat-response', `/api/lobbies/${lobbyId}/chat`, jsonPost('lobby-chat-request', request), options),
+        start: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/start`, jsonPost('start-lobby-request', request), options),
+        returnMatch: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/return-match`, jsonPost('return-lobby-match-request', request), options),
+        submitLimitedDeck: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/limited-deck`, jsonPost('submit-lobby-limited-deck-request', request), options),
+        prepareLimitedAiDecks: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/prepare-limited-ai-decks`, jsonPost('prepare-lobby-limited-ai-decks-request', request), options),
+        startLimitedMatch: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/start-limited-match`, jsonPost('start-lobby-limited-match-request', request), options),
+        leave: (lobbyId, request, options) => requestResource(requester, 'lobby-access-response', `/api/lobbies/${lobbyId}/leave`, jsonPost('leave-lobby-request', request), options),
+        createSession: access => createLobbySession({
+            access,
+            webSocketFactory,
+            wsUrl: options.wsUrl,
+            ...(options.validate == null ? {} : { validate: options.validate }),
+        }),
+        subscribeList: sessionOptions => createLobbyListSession({
+            webSocketFactory,
+            wsUrl: options.wsUrl,
+            sessionOptions,
+            ...(options.validate == null ? {} : { validate: options.validate }),
+        }),
+    };
+}
+/** Validates one response with a generated schema and returns the curated lobby DTO type. */
+function requestResource(requester, schemaName, pathname, init, options) {
+    return requester.request(schemaName, pathname, init, options);
+}

package/dist/resources/lobby-list-session.d.ts

@@ -0,0 +1,13 @@
+import type { WebSocketFactory } from '../internal/transport.js';
+import type { SchemaValidator } from '../validators/validator.js';
+import type { LobbyListSession, LobbyListSessionOptions } from './lobby-types.js';
+/**
+ * Creates a controller for the public, unauthenticated lobby-list socket
+ * (`GET /ws/lobbies`).
+ */
+export declare function createLobbyListSession(options: {
+    validate?: SchemaValidator | undefined;
+    webSocketFactory: WebSocketFactory;
+    wsUrl: string;
+    sessionOptions?: LobbyListSessionOptions | undefined;
+}): LobbyListSession;

package/dist/resources/lobby-list-session.js

@@ -0,0 +1,198 @@
+import { TypedEmitter } from '../internal/emitter.js';
+import { SIMULATOR_REJECTION_CLOSE_CODE, simulatorSocketErrorPayload } from '../internal/errors.js';
+import { websocketCloseInfo } from '../internal/websocket-event.js';
+import { decodeSocketFrame } from '../internal/socket-frame.js';
+import { passthroughValidator } from '../validators/validator.js';
+import { DEFAULT_ERROR_HISTORY_LIMIT } from '../internal/limits.js';
+import { normalizeReconnectBackoff, reconnectDelayMs, } from '../internal/reconnect-backoff.js';
+/** Default initial reconnect backoff delay (ms). */
+const DEFAULT_INITIAL_DELAY_MS = 500;
+/** Default reconnect backoff ceiling (ms). */
+const DEFAULT_MAX_DELAY_MS = 5_000;
+/** Default exponential backoff multiplier between reconnect attempts. */
+const DEFAULT_BACKOFF_FACTOR = 2;
+/**
+ * Creates a controller for the public, unauthenticated lobby-list socket
+ * (`GET /ws/lobbies`).
+ */
+export function createLobbyListSession(options) {
+    return new LobbyListSessionController({
+        validate: options.validate ?? passthroughValidator,
+        webSocketFactory: options.webSocketFactory,
+        wsUrl: options.wsUrl,
+        autoReconnect: normalizeAutoReconnect(options.sessionOptions?.autoReconnect),
+    });
+}
+/**
+ * Public, viewer-agnostic lobby-list subscription.
+ *
+ * Mirrors the per-lobby `LobbySessionController` but: opens a token-free URL
+ * (no `Sec-WebSocket-Protocol`), tracks a `PublicLobbySummary[]` instead of a
+ * single snapshot, and auto-reconnects on abnormal close with capped backoff.
+ */
+class LobbyListSessionController {
+    __v_skip = true;
+    #emitter = new TypedEmitter();
+    #validator;
+    #webSocketFactory;
+    #wsUrl;
+    #autoReconnect;
+    #connectionState = 'idle';
+    #errors = [];
+    #socket;
+    #lobbies;
+    // Set when the consumer calls `close()`; suppresses auto-reconnect.
+    #manualClose = false;
+    // Monotonic generation guards stale reconnect timers across reconnects/closes.
+    #reconnectGeneration = 0;
+    #reconnectTimer;
+    constructor(options) {
+        this.#validator = options.validate;
+        this.#webSocketFactory = options.webSocketFactory;
+        this.#wsUrl = options.wsUrl;
+        this.#autoReconnect = options.autoReconnect;
+    }
+    get connectionState() {
+        return this.#connectionState;
+    }
+    get errorMessages() {
+        return this.#errors.map(error => `${error.code} - ${error.message}`);
+    }
+    get errors() {
+        return [...this.#errors];
+    }
+    get lobbies() {
+        return this.#lobbies;
+    }
+    async connect() {
+        this.#manualClose = false;
+        this.#openSocket();
+        return this;
+    }
+    close() {
+        this.#manualClose = true;
+        this.#clearReconnectTimer();
+        // Bump the generation so any in-flight reconnect timer becomes a no-op.
+        this.#reconnectGeneration += 1;
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.#setConnectionState('closed');
+    }
+    on(event, listener) {
+        return this.#emitter.on(event, listener);
+    }
+    onSnapshot(listener) {
+        return this.#emitter.on('snapshot', listener);
+    }
+    ping(nonce) {
+        this.#socket?.send(JSON.stringify({ type: 'ping', payload: { nonce } }));
+    }
+    /** Opens a fresh socket, replacing any existing one. */
+    #openSocket() {
+        if (this.#socket) {
+            this.#socket.close();
+            this.#socket = undefined;
+        }
+        this.#setConnectionState('connecting');
+        // No token, no subprotocols: the list is public and unauthenticated.
+        const socket = this.#webSocketFactory(lobbyListSocketUrl(this.#wsUrl));
+        this.#socket = socket;
+        socket.addEventListener('open', () => this.#setConnectionState('open'));
+        socket.addEventListener('close', (event) => {
+            const info = websocketCloseInfo(event);
+            // Surface an explicit server refusal (code 4000 + engine error in the
+            // reason) instead of losing it in the reconnect loop.
+            if (info.closeCode === SIMULATOR_REJECTION_CLOSE_CODE) {
+                this.#pushError(simulatorSocketErrorPayload(info));
+            }
+            this.#handleClose();
+        });
+        socket.addEventListener('error', () => {
+            this.#pushError(simulatorSocketErrorPayload({}));
+        });
+        socket.addEventListener('message', event => this.#handleMessage(event));
+    }
+    #handleMessage(event) {
+        // Shared with every other SDK socket, so a malformed known frame is
+        // reported the same way here as on the match and lobby sockets: as an
+        // error payload, never as a throw. This listener runs inside the
+        // transport, so a throw would escape past the consumer entirely.
+        const decoded = decodeSocketFrame(event, this.#validator, 'lobby-list-server-message');
+        if (decoded.type === 'ignored')
+            return;
+        if (decoded.type === 'error') {
+            this.#pushError(decoded.error);
+            return;
+        }
+        const message = decoded.message;
+        this.#emitter.emit('message', message);
+        switch (message.type) {
+            case 'snapshot':
+                this.#lobbies = message.payload.lobbies;
+                this.#emitter.emit('snapshot', message.payload);
+                this.#emitChange();
+                break;
+            case 'pong':
+                this.#emitter.emit('pong', message.payload);
+                break;
+        }
+    }
+    #handleClose() {
+        this.#socket = undefined;
+        this.#setConnectionState('closed');
+        if (this.#manualClose || !this.#autoReconnect.enabled)
+            return;
+        this.#scheduleReconnect(1);
+    }
+    #scheduleReconnect(attempt) {
+        const generation = this.#reconnectGeneration;
+        const delayMs = reconnectDelayMs(this.#autoReconnect, attempt);
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            // A close() (or another reconnect) bumped the generation: this is stale.
+            if (generation !== this.#reconnectGeneration || this.#manualClose)
+                return;
+            this.#openSocket();
+        }, delayMs);
+    }
+    #clearReconnectTimer() {
+        if (this.#reconnectTimer != null) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+    }
+    #pushError(error) {
+        // Bounded: a flapping list socket pushes one error per failed attempt.
+        this.#errors = [...this.#errors, error].slice(-DEFAULT_ERROR_HISTORY_LIMIT);
+        this.#emitter.emit('error', error);
+        this.#emitChange();
+    }
+    #setConnectionState(state) {
+        this.#connectionState = state;
+        this.#emitter.emit('connectionState', state);
+        this.#emitChange();
+    }
+    #emitChange() {
+        this.#emitter.emit('change', {
+            connectionState: this.#connectionState,
+            errors: this.errors,
+            lobbies: this.#lobbies,
+        });
+    }
+}
+/** Resolves the auto-reconnect option into concrete bounds. */
+function normalizeAutoReconnect(option) {
+    return normalizeReconnectBackoff(option, {
+        enabled: true,
+        initialDelayMs: DEFAULT_INITIAL_DELAY_MS,
+        maxDelayMs: DEFAULT_MAX_DELAY_MS,
+        backoffFactor: DEFAULT_BACKOFF_FACTOR,
+    });
+}
+/** Builds the token-free list socket URL `${base}/lobbies`. */
+function lobbyListSocketUrl(base) {
+    const root = base.endsWith('/') ? base : `${base}/`;
+    // No id segment and no token: the public list socket is unauthenticated.
+    const url = new URL('lobbies', root);
+    return url.toString();
+}

package/dist/resources/lobby-session.d.ts

@@ -0,0 +1,9 @@
+import type { WebSocketFactory } from '../internal/transport.js';
+import type { SchemaValidator } from '../validators/validator.js';
+import type { LobbyAccessInput, LobbyAccessResponse, LobbySession } from './lobby-types.js';
+export declare function createLobbySession(options: {
+    access: LobbyAccessInput | LobbyAccessResponse;
+    validate?: SchemaValidator | undefined;
+    webSocketFactory: WebSocketFactory;
+    wsUrl: string;
+}): LobbySession;