@my-swu/simulator-client 0.1.0

package/dist/client.js

@@ -0,0 +1,92 @@
+import { EngineHttpRequester } from './http/request.js';
+import { getDefaultFetch } from './internal/transport.js';
+import { createAdminResource } from './resources/admin.js';
+import { createCardsResource } from './resources/card-resource.js';
+import { createLimitedEventsResource } from './resources/limited-events.js';
+import { createLobbiesResource } from './resources/lobbies.js';
+import { createMatchHistoryResource } from './resources/match-history.js';
+import { createMatchesResource } from './resources/matches.js';
+import { createSessionResource } from './resources/session.js';
+import { createSystemResource } from './resources/system.js';
+import { createTournamentRoomsResource } from './resources/tournament-rooms.js';
+import { passthroughValidator } from './validators/validator.js';
+import { scheduleValidatorWarmUp } from './validators/warm-up.js';
+/**
+ * Creates one typed simulator client.
+ *
+ * Use one client per simulator server origin. Payloads are returned as typed
+ * values without being checked at runtime; pass `validate` to have request
+ * bodies, responses and socket frames verified against the generated schemas.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/http-client
+ */
+export function createSimulatorClient(options) {
+    const baseUrl = new URL(options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`);
+    // One validator for the whole client: HTTP bodies, HTTP responses and socket
+    // frames all resolve their validation policy from this single value, so a
+    // client built without `validate` holds no reference to the schema map.
+    const validate = options.validate ?? passthroughValidator;
+    // Schema compilation is lazy, so without this the first schema — and with it
+    // the whole shared definition pool, ~215 ms measured — is compiled by the
+    // first server frame, i.e. during connect on the browser's main thread. Move
+    // it to idle time. A no-op when validation is off, and it never blocks here.
+    scheduleValidatorWarmUp(validate);
+    const requester = new EngineHttpRequester({
+        baseUrl,
+        fetch: options.fetch ?? getDefaultFetch(),
+        validate,
+        ...(options.timeoutMs == null ? {} : { defaultTimeoutMs: options.timeoutMs }),
+    });
+    const cards = createCardsResource(requester);
+    const admin = createAdminResource(requester);
+    const limitedEvents = createLimitedEventsResource(requester);
+    const lobbies = createLobbiesResource({
+        requester,
+        validate,
+        wsUrl: webSocketBaseUrl(baseUrl),
+        ...(options.webSocketFactory == null ? {} : { webSocketFactory: options.webSocketFactory }),
+    });
+    const matchHistory = createMatchHistoryResource({ requester });
+    const matches = createMatchesResource({ requester });
+    const session = createSessionResource({
+        matches,
+        validate,
+        wsUrl: webSocketBaseUrl(baseUrl),
+        ...(options.webSocketFactory == null ? {} : { webSocketFactory: options.webSocketFactory }),
+    });
+    const system = createSystemResource(requester);
+    const tournamentRooms = createTournamentRoomsResource({
+        requester,
+        validate,
+        wsUrl: webSocketBaseUrl(baseUrl),
+        ...(options.webSocketFactory == null ? {} : { webSocketFactory: options.webSocketFactory }),
+    });
+    return {
+        admin,
+        cards,
+        limitedEvents,
+        lobbies,
+        matchHistory,
+        matches,
+        session,
+        system,
+        tournamentRooms,
+    };
+}
+/**
+ * Resolves the WebSocket base URL from the HTTP base URL.
+ */
+function webSocketBaseUrl(baseUrl) {
+    const protocol = baseUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${protocol}//${baseUrl.host}/ws`;
+}

package/dist/connection/handshake.d.ts

@@ -0,0 +1,30 @@
+import type { EngineWebSocket } from '../internal/transport.js';
+/**
+ * Inputs for waiting on the initial socket handshake.
+ */
+export interface SocketHandshakeOptions {
+    /**
+     * Registers one snapshot listener and returns its cleanup.
+     */
+    onSnapshot(listener: () => void): () => void;
+    /**
+     * Marks the connection open when the transport opens.
+     */
+    onTransportOpen(): void;
+    /**
+     * Registers one welcome listener and returns its cleanup.
+     */
+    onWelcome(listener: () => void): () => void;
+    /**
+     * Socket being opened.
+     */
+    socket: EngineWebSocket;
+    /**
+     * Handshake timeout in milliseconds.
+     */
+    timeoutMs: number;
+}
+/**
+ * Waits for socket open, welcome, and first snapshot.
+ */
+export declare function waitForSocketHandshake(options: SocketHandshakeOptions): Promise<void>;

package/dist/connection/handshake.js

@@ -0,0 +1,62 @@
+import { SimulatorSocketError, simulatorSocketErrorFromClose } from '../internal/errors.js';
+import { websocketCloseInfo } from '../internal/websocket-event.js';
+/**
+ * Waits for socket open, welcome, and first snapshot.
+ */
+export function waitForSocketHandshake(options) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let sawSnapshot = false;
+        let sawWelcome = false;
+        let sawErrorEvent = false;
+        let stopSnapshot = () => { };
+        let stopWelcome = () => { };
+        const onOpen = () => {
+            options.onTransportOpen();
+        };
+        // The browser `error` event is an opaque `Event` with no diagnostics —
+        // never stringify it. Per spec it is always followed by `close`, which
+        // carries the classifiable code/reason, so classification waits for it.
+        const onError = () => {
+            sawErrorEvent = true;
+        };
+        const onClose = (event) => {
+            finish(() => reject(simulatorSocketErrorFromClose(websocketCloseInfo(event), sawErrorEvent)));
+        };
+        const cleanup = () => {
+            clearTimeout(timer);
+            stopWelcome();
+            stopSnapshot();
+            options.socket.removeEventListener('open', onOpen);
+            options.socket.removeEventListener('error', onError);
+            options.socket.removeEventListener('close', onClose);
+        };
+        const finish = (done) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            done();
+        };
+        const maybeResolve = () => {
+            if (sawWelcome && sawSnapshot) {
+                finish(resolve);
+            }
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(new SimulatorSocketError('timeout', 'socket handshake timed out')));
+        }, options.timeoutMs);
+        stopWelcome = options.onWelcome(() => {
+            sawWelcome = true;
+            maybeResolve();
+        });
+        stopSnapshot = options.onSnapshot(() => {
+            sawSnapshot = true;
+            maybeResolve();
+        });
+        options.socket.addEventListener('open', onOpen);
+        options.socket.addEventListener('error', onError);
+        options.socket.addEventListener('close', onClose);
+    });
+}

package/dist/connection/options.d.ts

@@ -0,0 +1,36 @@
+import type { WebSocketFactory } from '../internal/transport.js';
+import type { SchemaValidator } from '../validators/validator.js';
+/**
+ * Construction options for one match socket session.
+ */
+export type MatchConnectionOptions = MatchConnectionBaseOptions & ({
+    seatToken: string;
+    spectatorToken?: never;
+} | {
+    seatToken?: never;
+    spectatorToken: string;
+});
+export interface MatchConnectionBaseOptions {
+    /**
+     * Milliseconds to wait for welcome plus first snapshot.
+     */
+    handshakeTimeoutMs?: number | undefined;
+    /**
+     * Public match id.
+     */
+    matchId: string;
+    /**
+     * Optional boundary validator for inbound frames and outbound envelopes.
+     *
+     * Defaults to the typed pass-through, matching the client-level default.
+     */
+    validate?: SchemaValidator | undefined;
+    /**
+     * Optional socket factory for runtimes without global `WebSocket`.
+     */
+    webSocketFactory?: WebSocketFactory;
+    /**
+     * Base WebSocket URL ending at `/ws`.
+     */
+    wsUrl: string;
+}

package/dist/connection/options.js

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

package/dist/connection/url.d.ts

@@ -0,0 +1,55 @@
+export interface MatchSocketUrlBaseOptions {
+    /**
+     * Public match id segment.
+     */
+    matchId: string;
+    /**
+     * Base WebSocket URL ending at the match socket root.
+     */
+    wsUrl: string;
+}
+/**
+ * Auth token carried off-URL via the WebSocket subprotocol list.
+ */
+export type MatchSocketToken = {
+    seatToken: string;
+    spectatorToken?: never;
+} | {
+    seatToken?: never;
+    spectatorToken: string;
+};
+/**
+ * WebSocket subprotocol kind naming the seat (player) credential.
+ *
+ * The auth wire format is a two-element subprotocol list whose first element is
+ * the credential KIND and whose second is the token VALUE, so the token never
+ * appears in the URL. See `RULES.md` for the full contract.
+ */
+export declare const MATCH_SEAT_TOKEN_PROTOCOL = "swu.seat-token";
+/**
+ * WebSocket subprotocol kind naming the spectator credential.
+ */
+export declare const MATCH_SPECTATOR_TOKEN_PROTOCOL = "swu.spectator-token";
+/**
+ * WebSocket subprotocol kind naming the lobby / tournament-room player credential.
+ */
+export declare const PLAYER_TOKEN_PROTOCOL = "swu.player-token";
+/**
+ * Builds one encoded, token-FREE match WebSocket URL.
+ *
+ * The auth token is intentionally NOT placed in the URL; pass the result of
+ * {@link matchSocketProtocols} as the WebSocket constructor's `protocols`
+ * argument instead.
+ */
+export declare function buildMatchSocketUrl(options: MatchSocketUrlBaseOptions): string;
+/**
+ * Returns the WebSocket subprotocol list that carries the seat or spectator
+ * token off-URL: `['swu.seat-token', seatToken]` or
+ * `['swu.spectator-token', spectatorToken]`.
+ */
+export declare function matchSocketProtocols(token: MatchSocketToken): string[];
+/**
+ * Returns the WebSocket subprotocol list carrying a lobby / tournament-room
+ * player token off-URL: `['swu.player-token', playerToken]`.
+ */
+export declare function playerTokenProtocols(playerToken: string): string[];

package/dist/connection/url.js

@@ -0,0 +1,46 @@
+/**
+ * WebSocket subprotocol kind naming the seat (player) credential.
+ *
+ * The auth wire format is a two-element subprotocol list whose first element is
+ * the credential KIND and whose second is the token VALUE, so the token never
+ * appears in the URL. See `RULES.md` for the full contract.
+ */
+export const MATCH_SEAT_TOKEN_PROTOCOL = 'swu.seat-token';
+/**
+ * WebSocket subprotocol kind naming the spectator credential.
+ */
+export const MATCH_SPECTATOR_TOKEN_PROTOCOL = 'swu.spectator-token';
+/**
+ * WebSocket subprotocol kind naming the lobby / tournament-room player credential.
+ */
+export const PLAYER_TOKEN_PROTOCOL = 'swu.player-token';
+/**
+ * Builds one encoded, token-FREE match WebSocket URL.
+ *
+ * The auth token is intentionally NOT placed in the URL; pass the result of
+ * {@link matchSocketProtocols} as the WebSocket constructor's `protocols`
+ * argument instead.
+ */
+export function buildMatchSocketUrl(options) {
+    const base = options.wsUrl.endsWith('/') ? options.wsUrl : `${options.wsUrl}/`;
+    const url = new URL(encodeURIComponent(options.matchId), base);
+    return url.toString();
+}
+/**
+ * Returns the WebSocket subprotocol list that carries the seat or spectator
+ * token off-URL: `['swu.seat-token', seatToken]` or
+ * `['swu.spectator-token', spectatorToken]`.
+ */
+export function matchSocketProtocols(token) {
+    if ('spectatorToken' in token && token.spectatorToken != null) {
+        return [MATCH_SPECTATOR_TOKEN_PROTOCOL, token.spectatorToken];
+    }
+    return [MATCH_SEAT_TOKEN_PROTOCOL, token.seatToken];
+}
+/**
+ * Returns the WebSocket subprotocol list carrying a lobby / tournament-room
+ * player token off-URL: `['swu.player-token', playerToken]`.
+ */
+export function playerTokenProtocols(playerToken) {
+    return [PLAYER_TOKEN_PROTOCOL, playerToken];
+}

package/dist/connection/wait.d.ts

@@ -0,0 +1,22 @@
+import type { GameState } from '../generated/index.js';
+/**
+ * Predicate used by snapshot wait helpers.
+ */
+export type SnapshotPredicate = (snapshot: GameState) => boolean;
+/**
+ * Options for snapshot wait helpers.
+ */
+export interface SnapshotWaitOptions {
+    /**
+     * Milliseconds to wait before rejecting.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Default timeout for explicit SDK wait helpers.
+ */
+export declare const DEFAULT_WAIT_TIMEOUT_MS = 10000;
+/**
+ * Returns true for every snapshot.
+ */
+export declare function anySnapshot(): SnapshotPredicate;

package/dist/connection/wait.js

@@ -0,0 +1,10 @@
+/**
+ * Default timeout for explicit SDK wait helpers.
+ */
+export const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+/**
+ * Returns true for every snapshot.
+ */
+export function anySnapshot() {
+    return () => true;
+}

package/dist/connection.d.ts

@@ -0,0 +1,110 @@
+import type { AiStatusPayload, GameCommand, GameState, WelcomePayload } from './generated/index.js';
+import type { MatchHistoryFeedEntry } from './generated/types/server-message.js';
+import type { CardInteractionCueRequest } from './generated/types/client-message.js';
+import type { FormatEventCommand } from './generated/types/format-event-request.js';
+import type { ConnectionState, MatchConnectionEvents } from './session.js';
+import type { MatchConnectionOptions } from './connection/options.js';
+import type { SnapshotPredicate, SnapshotWaitOptions } from './connection/wait.js';
+export type { MatchConnectionOptions } from './connection/options.js';
+/**
+ * Stateful typed connection to one simulator match socket.
+ */
+export declare class MatchConnection {
+    #private;
+    private constructor();
+    /**
+     * Opens one socket and waits for initial welcome plus snapshot.
+     */
+    static connect(options: MatchConnectionOptions): Promise<MatchConnection>;
+    /**
+     * Latest connection state.
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Latest AI attachment/pause status announced by the server.
+     */
+    get aiStatus(): AiStatusPayload | undefined;
+    /**
+     * Revision of the latest authoritative snapshot accepted by this connection.
+     */
+    get snapshotRevision(): number;
+    /**
+     * Latest known match snapshot.
+     */
+    get snapshot(): GameState | undefined;
+    /**
+     * Latest match-history entries announced by the server.
+     */
+    get history(): readonly MatchHistoryFeedEntry[];
+    /** Whether this socket received its full recovery history, even if empty. */
+    get historySnapshotReceived(): boolean;
+    /**
+     * Latest welcome payload.
+     */
+    get welcome(): WelcomePayload | undefined;
+    /**
+     * Registers one typed event listener.
+     */
+    on<TKey extends keyof MatchConnectionEvents>(event: TKey, listener: (value: MatchConnectionEvents[TKey]) => void): () => void;
+    /**
+     * Sends one `ready` message.
+     */
+    ready(): void;
+    /**
+     * Requests a rollback of the latest accepted player action.
+     */
+    undo(): void;
+    /**
+     * Answers (or withdraws, when sent by the requester) the pending undo
+     * approval request carried by `GameState.pendingUndo`.
+     */
+    respondUndo(approve: boolean): void;
+    /**
+     * Pauses or resumes an attached AI opponent for this match.
+     */
+    setAiPaused(paused: boolean): void;
+    /**
+     * Sends one typed game command.
+     *
+     * When the client validates, the envelope is checked against
+     * `client-message`, which already references the `game-command` schema, so no
+     * extra validation is required.
+     */
+    sendCommand(command: GameCommand): void;
+    /**
+     * Sends one typed out-of-game format-event command.
+     */
+    sendFormatEvent(command: FormatEventCommand): void;
+    /**
+     * Sends one host-authorized AI format-event command.
+     */
+    sendAiFormatEvent(command: FormatEventCommand): void;
+    /**
+     * Sends one in-match chat message.
+     */
+    sendChat(message: string): void;
+    /**
+     * Sends one transient hand-card interaction cue.
+     */
+    sendInteractionCue(cue: CardInteractionCueRequest): void;
+    /**
+     * Requests one fresh snapshot.
+     */
+    sync(): void;
+    /**
+     * Sends one ping frame with optional nonce.
+     */
+    ping(nonce?: string | null): void;
+    /**
+     * Closes the current socket and detaches its listeners.
+     */
+    close(): void;
+    /**
+     * Reconnects and then requests one explicit sync snapshot.
+     */
+    reconnect(options?: Pick<MatchConnectionOptions, 'handshakeTimeoutMs'>): Promise<void>;
+    /**
+     * Resolves with the current or next snapshot that matches the predicate.
+     */
+    waitForSnapshot(predicate?: SnapshotPredicate, options?: SnapshotWaitOptions): Promise<GameState>;
+}