@my-swu/simulator-client 0.1.0

package/dist/internal/emitter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Function called when one typed event fires.
+ */
+export type EventListener<TValue> = (value: TValue) => void;
+/**
+ * Small typed event emitter used by the SDK session layer.
+ */
+export declare class TypedEmitter<TEvents extends object> {
+    #private;
+    /**
+     * Registers one listener and returns its unsubscribe function.
+     */
+    on<TKey extends keyof TEvents>(event: TKey, listener: EventListener<TEvents[TKey]>): () => void;
+    /**
+     * Emits one event to all current listeners.
+     */
+    emit<TKey extends keyof TEvents>(event: TKey, value: TEvents[TKey]): void;
+}

package/dist/internal/emitter.js

@@ -0,0 +1,34 @@
+/**
+ * Small typed event emitter used by the SDK session layer.
+ */
+export class TypedEmitter {
+    #listeners = new Map();
+    /**
+     * Registers one listener and returns its unsubscribe function.
+     */
+    on(event, listener) {
+        const eventName = event;
+        const listeners = this.#listeners.get(eventName) ?? new Set();
+        listeners.add(listener);
+        this.#listeners.set(eventName, listeners);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                this.#listeners.delete(eventName);
+            }
+        };
+    }
+    /**
+     * Emits one event to all current listeners.
+     */
+    emit(event, value) {
+        const listeners = this.#listeners.get(event);
+        if (listeners == null) {
+            return;
+        }
+        for (const listener of listeners) {
+            ;
+            listener(value);
+        }
+    }
+}

package/dist/internal/errors.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Context captured for one non-2xx HTTP response.
+ *
+ * These fields make HTTP failures safe to render or log without parsing the
+ * original `Response` object again.
+ *
+ * @example
+ * ```ts
+ * import type { EngineHttpErrorOptions } from '@my-swu/simulator-client'
+ *
+ * const notFoundOptions: EngineHttpErrorOptions = {
+ *   status: 404,
+ *   code: 'match_not_found',
+ *   method: 'GET',
+ *   url: 'http://127.0.0.1:4000/api/matches/missing',
+ * }
+ *
+ * console.log(notFoundOptions.status)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export interface EngineHttpErrorOptions {
+    /**
+     * Engine error code when the response body matched `api-error-response`.
+     */
+    code?: string | undefined;
+    /**
+     * HTTP method used for the failed request.
+     */
+    method?: string | undefined;
+    /**
+     * Parsed JSON payload when an error body was JSON but not a valid engine error.
+     */
+    payload?: unknown;
+    /**
+     * Raw response text when the server returned an error body.
+     */
+    responseText?: string | undefined;
+    /**
+     * HTTP response status.
+     */
+    status: number;
+    /**
+     * Fully resolved request URL.
+     */
+    url?: string | undefined;
+}
+/**
+ * Close code the simulator server uses to refuse a socket after completing
+ * the WebSocket upgrade.
+ *
+ * Browsers cannot read the HTTP status or body of a failed upgrade, so the
+ * server accepts user-relevant refusals (unknown match, dead token, full,
+ * maintenance, …) and closes immediately with this code; the close reason
+ * carries the engine error code (e.g. `match_not_found`) for classification.
+ */
+export declare const SIMULATOR_REJECTION_CLOSE_CODE = 4000;
+/**
+ * Why a simulator socket connection failed.
+ *
+ * - `unreachable`: transport-level failure (offline, refused, DNS, reset).
+ * - `timeout`: the handshake never completed within its deadline.
+ * - `closed-before-welcome`: the server closed cleanly mid-handshake.
+ * - `rejected`: the server refused the connection with a machine-readable
+ *   close frame; see [`SimulatorSocketError.serverCode`](#).
+ */
+export type SimulatorSocketErrorKind = 'unreachable' | 'timeout' | 'closed-before-welcome' | 'rejected';
+/** Close-frame facts extracted from a browser-style close event. */
+export interface WebSocketCloseInfo {
+    /** Close status code when the transport exposed one. */
+    closeCode?: number | undefined;
+    /** UTF-8 close reason when the transport exposed one. */
+    reason?: string | undefined;
+}
+/**
+ * Error thrown when a simulator socket connection fails.
+ *
+ * The browser WebSocket `error` event is an opaque `Event` (historically
+ * stringified as `"[object Event]"`), so the SDK classifies failures from
+ * what the transport CAN expose: the close code and reason. A close with
+ * [`SIMULATOR_REJECTION_CLOSE_CODE`](#) means the server deliberately refused
+ * the socket and named the engine error in the reason.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, SimulatorSocketError } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({ baseUrl: 'http://127.0.0.1:4000' })
+ * const matchSession = simulatorClient.session.create({
+ *   matchId: 'match_123',
+ *   seatToken: 'seat_token_123',
+ * })
+ *
+ * try {
+ *   await matchSession.connect()
+ * } catch (error) {
+ *   if (error instanceof SimulatorSocketError && error.serverCode) {
+ *     console.log('refused with', error.serverCode)
+ *   }
+ * }
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export declare class SimulatorSocketError extends Error {
+    /**
+     * Stable classification of the connection failure.
+     */
+    readonly kind: SimulatorSocketErrorKind;
+    /**
+     * WebSocket close status code when the transport exposed one.
+     */
+    readonly closeCode: number | undefined;
+    /**
+     * WebSocket close reason when the transport exposed one.
+     */
+    readonly reason: string | undefined;
+    /** Creates one classified socket error with its close-frame context. */
+    constructor(kind: SimulatorSocketErrorKind, message: string, options?: WebSocketCloseInfo);
+    /**
+     * Engine error code carried by a rejection close frame, when any.
+     *
+     * Only close frames using [`SIMULATOR_REJECTION_CLOSE_CODE`](#) carry a
+     * server-authored code; every other failure yields `undefined`.
+     */
+    get serverCode(): string | undefined;
+}
+/**
+ * Classify one failed connection from its close frame.
+ *
+ * Transport `error` events carry no diagnostics, so classification leans on
+ * the close frame that always follows: code 4000 is a deliberate server
+ * refusal, 1006 (or a seen error event) is an unreachable transport, and
+ * anything else closed before the handshake finished.
+ */
+export declare function simulatorSocketErrorFromClose(info: WebSocketCloseInfo, sawErrorEvent: boolean): SimulatorSocketError;
+/** Stable payload code pushed for each classified socket failure kind. */
+export declare function socketPayloadCodeForKind(kind: SimulatorSocketErrorKind): string;
+/**
+ * Default `{ code, message }` payload for authenticated room sockets.
+ *
+ * Lobby-like sessions push these when their transport fails. Classification
+ * runs through `simulatorSocketErrorFromClose` so every close shape maps to
+ * the same kind — and payload code — a thrown socket error would carry; a
+ * rejection close frame keeps the engine error code so clients can map it
+ * exactly like the equivalent HTTP error.
+ */
+export declare function simulatorSocketErrorPayload(info: WebSocketCloseInfo): {
+    code: string;
+    message: string;
+};
+/**
+ * Error thrown when a simulator payload does not match the generated schema.
+ *
+ * A client built with `validate` throws this when response, request-body or
+ * socket payload validation fails; the default client never validates those.
+ * It is also thrown by direct `parseSchema()` calls, whatever the client does.
+ *
+ * @example
+ * ```ts
+ * import { SdkValidationError } from '@my-swu/simulator-client'
+ *
+ * const validationError = new SdkValidationError(
+ *   'payload does not match schema health-response',
+ *   'health-response',
+ *   ['/status must be equal to constant'],
+ * )
+ *
+ * console.log(validationError.schemaName)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export declare class SdkValidationError extends Error {
+    readonly schemaName: string;
+    readonly details: readonly string[];
+    /**
+     * Creates one validation error with schema name and readable detail strings.
+     */
+    constructor(message: string, schemaName: string, details: readonly string[]);
+}
+/**
+ * Error thrown for non-2xx HTTP responses from the simulator server.
+ *
+ * When the response body matches the API error schema, `code` contains the
+ * server error code. Malformed JSON or non-schema error bodies are preserved in
+ * `payload` or `responseText`.
+ *
+ * @example
+ * ```ts
+ * import { EngineHttpError } from '@my-swu/simulator-client'
+ *
+ * const httpError = new EngineHttpError('match not found', {
+ *   status: 404,
+ *   code: 'match_not_found',
+ *   method: 'GET',
+ *   url: 'http://127.0.0.1:4000/api/matches/missing',
+ * })
+ *
+ * console.log(httpError.status, httpError.code)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export declare class EngineHttpError extends Error {
+    /**
+     * Engine error code when available.
+     */
+    readonly code: string | undefined;
+    /**
+     * HTTP method used for the failed request.
+     */
+    readonly method: string | undefined;
+    /**
+     * Parsed malformed JSON payload when available.
+     */
+    readonly payload: unknown;
+    /**
+     * Raw response text when available.
+     */
+    readonly responseText: string | undefined;
+    /**
+     * HTTP response status.
+     */
+    readonly status: number;
+    /**
+     * Fully resolved request URL.
+     */
+    readonly url: string | undefined;
+    /** Creates one HTTP error with normalized response context. */
+    constructor(message: string, options: EngineHttpErrorOptions);
+}

package/dist/internal/errors.js

@@ -0,0 +1,238 @@
+/**
+ * Close code the simulator server uses to refuse a socket after completing
+ * the WebSocket upgrade.
+ *
+ * Browsers cannot read the HTTP status or body of a failed upgrade, so the
+ * server accepts user-relevant refusals (unknown match, dead token, full,
+ * maintenance, …) and closes immediately with this code; the close reason
+ * carries the engine error code (e.g. `match_not_found`) for classification.
+ */
+export const SIMULATOR_REJECTION_CLOSE_CODE = 4000;
+/**
+ * Error thrown when a simulator socket connection fails.
+ *
+ * The browser WebSocket `error` event is an opaque `Event` (historically
+ * stringified as `"[object Event]"`), so the SDK classifies failures from
+ * what the transport CAN expose: the close code and reason. A close with
+ * [`SIMULATOR_REJECTION_CLOSE_CODE`](#) means the server deliberately refused
+ * the socket and named the engine error in the reason.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, SimulatorSocketError } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({ baseUrl: 'http://127.0.0.1:4000' })
+ * const matchSession = simulatorClient.session.create({
+ *   matchId: 'match_123',
+ *   seatToken: 'seat_token_123',
+ * })
+ *
+ * try {
+ *   await matchSession.connect()
+ * } catch (error) {
+ *   if (error instanceof SimulatorSocketError && error.serverCode) {
+ *     console.log('refused with', error.serverCode)
+ *   }
+ * }
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export class SimulatorSocketError extends Error {
+    /**
+     * Stable classification of the connection failure.
+     */
+    kind;
+    /**
+     * WebSocket close status code when the transport exposed one.
+     */
+    closeCode;
+    /**
+     * WebSocket close reason when the transport exposed one.
+     */
+    reason;
+    /** Creates one classified socket error with its close-frame context. */
+    constructor(kind, message, options = {}) {
+        super(message);
+        this.name = 'SimulatorSocketError';
+        this.kind = kind;
+        this.closeCode = options.closeCode;
+        this.reason = options.reason;
+    }
+    /**
+     * Engine error code carried by a rejection close frame, when any.
+     *
+     * Only close frames using [`SIMULATOR_REJECTION_CLOSE_CODE`](#) carry a
+     * server-authored code; every other failure yields `undefined`.
+     */
+    get serverCode() {
+        if (this.closeCode !== SIMULATOR_REJECTION_CLOSE_CODE) {
+            return undefined;
+        }
+        const reason = this.reason?.trim();
+        return reason ? reason : undefined;
+    }
+}
+/** Human-readable developer message for one socket failure kind. */
+function simulatorSocketErrorMessage(kind, info) {
+    switch (kind) {
+        case 'unreachable':
+            return 'socket error: could not reach the simulator server';
+        case 'timeout':
+            return 'socket handshake timed out';
+        case 'closed-before-welcome':
+            return 'socket closed before initial handshake completed';
+        case 'rejected':
+            return info.reason
+                ? `socket rejected by the simulator server: ${info.reason}`
+                : 'socket rejected by the simulator server';
+    }
+}
+/**
+ * Classify one failed connection from its close frame.
+ *
+ * Transport `error` events carry no diagnostics, so classification leans on
+ * the close frame that always follows: code 4000 is a deliberate server
+ * refusal, 1006 (or a seen error event) is an unreachable transport, and
+ * anything else closed before the handshake finished.
+ */
+export function simulatorSocketErrorFromClose(info, sawErrorEvent) {
+    let kind;
+    if (info.closeCode === SIMULATOR_REJECTION_CLOSE_CODE) {
+        kind = 'rejected';
+    }
+    else if (sawErrorEvent || info.closeCode === 1006) {
+        kind = 'unreachable';
+    }
+    else {
+        kind = 'closed-before-welcome';
+    }
+    return new SimulatorSocketError(kind, simulatorSocketErrorMessage(kind, info), info);
+}
+/** Stable payload code pushed for each classified socket failure kind. */
+export function socketPayloadCodeForKind(kind) {
+    switch (kind) {
+        case 'closed-before-welcome':
+            return 'sdk_socket_closed';
+        case 'rejected':
+            return 'sdk_socket_rejected';
+        case 'timeout':
+            return 'sdk_socket_timeout';
+        case 'unreachable':
+            return 'sdk_socket_unreachable';
+    }
+}
+/**
+ * Default `{ code, message }` payload for authenticated room sockets.
+ *
+ * Lobby-like sessions push these when their transport fails. Classification
+ * runs through `simulatorSocketErrorFromClose` so every close shape maps to
+ * the same kind — and payload code — a thrown socket error would carry; a
+ * rejection close frame keeps the engine error code so clients can map it
+ * exactly like the equivalent HTTP error.
+ */
+export function simulatorSocketErrorPayload(info) {
+    // A missing close code means the payload comes from a transport `error`
+    // event, which never carries close facts.
+    const sawErrorEvent = info.closeCode === undefined;
+    const error = simulatorSocketErrorFromClose(info, sawErrorEvent);
+    return {
+        code: error.serverCode ?? socketPayloadCodeForKind(error.kind),
+        message: error.message,
+    };
+}
+/**
+ * Error thrown when a simulator payload does not match the generated schema.
+ *
+ * A client built with `validate` throws this when response, request-body or
+ * socket payload validation fails; the default client never validates those.
+ * It is also thrown by direct `parseSchema()` calls, whatever the client does.
+ *
+ * @example
+ * ```ts
+ * import { SdkValidationError } from '@my-swu/simulator-client'
+ *
+ * const validationError = new SdkValidationError(
+ *   'payload does not match schema health-response',
+ *   'health-response',
+ *   ['/status must be equal to constant'],
+ * )
+ *
+ * console.log(validationError.schemaName)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export class SdkValidationError extends Error {
+    schemaName;
+    details;
+    /**
+     * Creates one validation error with schema name and readable detail strings.
+     */
+    constructor(message, schemaName, details) {
+        super(message);
+        this.schemaName = schemaName;
+        this.details = details;
+        this.name = 'SdkValidationError';
+    }
+}
+/**
+ * Error thrown for non-2xx HTTP responses from the simulator server.
+ *
+ * When the response body matches the API error schema, `code` contains the
+ * server error code. Malformed JSON or non-schema error bodies are preserved in
+ * `payload` or `responseText`.
+ *
+ * @example
+ * ```ts
+ * import { EngineHttpError } from '@my-swu/simulator-client'
+ *
+ * const httpError = new EngineHttpError('match not found', {
+ *   status: 404,
+ *   code: 'match_not_found',
+ *   method: 'GET',
+ *   url: 'http://127.0.0.1:4000/api/matches/missing',
+ * })
+ *
+ * console.log(httpError.status, httpError.code)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export class EngineHttpError extends Error {
+    /**
+     * Engine error code when available.
+     */
+    code;
+    /**
+     * HTTP method used for the failed request.
+     */
+    method;
+    /**
+     * Parsed malformed JSON payload when available.
+     */
+    payload;
+    /**
+     * Raw response text when available.
+     */
+    responseText;
+    /**
+     * HTTP response status.
+     */
+    status;
+    /**
+     * Fully resolved request URL.
+     */
+    url;
+    /** Creates one HTTP error with normalized response context. */
+    constructor(message, options) {
+        super(message);
+        this.name = 'EngineHttpError';
+        this.status = options.status;
+        this.code = options.code;
+        this.method = options.method;
+        this.payload = options.payload;
+        this.responseText = options.responseText;
+        this.url = options.url;
+    }
+}

package/dist/internal/limits.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Retention caps shared by the SDK's in-memory feeds.
+ *
+ * Every buffer fed by the network is bounded: a flapping connection or a long
+ * match must not grow an array without limit, and the copy-on-append pattern
+ * these feeds use is O(n²) once the array is unbounded. The caps live here so
+ * the low-level connection and the higher-level session agree on one number
+ * instead of drifting apart.
+ */
+/** Maximum match-history entries retained by one connection or session feed. */
+export declare const DEFAULT_MATCH_HISTORY_LIMIT = 200;
+/** Maximum recent errors retained by one connection, session or room socket. */
+export declare const DEFAULT_ERROR_HISTORY_LIMIT = 50;

package/dist/internal/limits.js

@@ -0,0 +1,13 @@
+/**
+ * Retention caps shared by the SDK's in-memory feeds.
+ *
+ * Every buffer fed by the network is bounded: a flapping connection or a long
+ * match must not grow an array without limit, and the copy-on-append pattern
+ * these feeds use is O(n²) once the array is unbounded. The caps live here so
+ * the low-level connection and the higher-level session agree on one number
+ * instead of drifting apart.
+ */
+/** Maximum match-history entries retained by one connection or session feed. */
+export const DEFAULT_MATCH_HISTORY_LIMIT = 200;
+/** Maximum recent errors retained by one connection, session or room socket. */
+export const DEFAULT_ERROR_HISTORY_LIMIT = 50;

package/dist/internal/reconnect-backoff.d.ts

@@ -0,0 +1,33 @@
+/** Return a finite non-negative number, or the supplied fallback. */
+export declare function nonNegativeNumber(value: number | undefined, fallback: number): number;
+/** Return a finite positive number, or the supplied fallback. */
+export declare function positiveNumber(value: number | undefined, fallback: number): number;
+/** Values needed to calculate capped exponential reconnect backoff. */
+export interface ReconnectBackoffPolicy {
+    /** Multiplier applied after each failed attempt. */
+    backoffFactor: number;
+    /** Delay before the first reconnect attempt, in milliseconds. */
+    initialDelayMs: number;
+    /** Maximum reconnect delay, in milliseconds. */
+    maxDelayMs: number;
+}
+/** Defaults supplied by each session surface for reconnect behavior. */
+export interface ReconnectBackoffDefaults extends ReconnectBackoffPolicy {
+    /** Whether reconnect is enabled when callers omit the option. */
+    enabled: boolean;
+}
+/** Caller-provided reconnect fields before defaults and validation apply. */
+export interface ReconnectBackoffOptions {
+    backoffFactor?: number | undefined;
+    initialDelayMs?: number | undefined;
+    maxDelayMs?: number | undefined;
+}
+/** Concrete reconnect policy after boolean and invalid-number normalization. */
+export interface NormalizedReconnectBackoffPolicy extends ReconnectBackoffPolicy {
+    /** Whether this session schedules reconnect attempts. */
+    enabled: boolean;
+}
+/** Normalizes shared reconnect options while retaining caller-specific defaults. */
+export declare function normalizeReconnectBackoff(option: boolean | ReconnectBackoffOptions | undefined, defaults: ReconnectBackoffDefaults): NormalizedReconnectBackoffPolicy;
+/** Compute the capped exponential delay for a one-based reconnect attempt. */
+export declare function reconnectDelayMs(policy: ReconnectBackoffPolicy, attempt: number): number;

package/dist/internal/reconnect-backoff.js

@@ -0,0 +1,25 @@
+/** Return a finite non-negative number, or the supplied fallback. */
+export function nonNegativeNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+/** Return a finite positive number, or the supplied fallback. */
+export function positiveNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/** Normalizes shared reconnect options while retaining caller-specific defaults. */
+export function normalizeReconnectBackoff(option, defaults) {
+    const enabled = option == null ? defaults.enabled : option !== false;
+    const policy = option === true || option === false || option == null ? {} : option;
+    return {
+        enabled,
+        backoffFactor: positiveNumber(policy.backoffFactor, defaults.backoffFactor),
+        initialDelayMs: nonNegativeNumber(policy.initialDelayMs, defaults.initialDelayMs),
+        maxDelayMs: nonNegativeNumber(policy.maxDelayMs, defaults.maxDelayMs),
+    };
+}
+/** Compute the capped exponential delay for a one-based reconnect attempt. */
+export function reconnectDelayMs(policy, attempt) {
+    const exponent = Math.max(0, attempt - 1);
+    const uncapped = policy.initialDelayMs * policy.backoffFactor ** exponent;
+    return Math.min(policy.maxDelayMs, Math.max(0, Math.floor(uncapped)));
+}

package/dist/internal/socket-frame.d.ts

@@ -0,0 +1,43 @@
+import type { ErrorPayload } from '../generated/index.js';
+import type { SchemaName } from '../generated/schemas.js';
+import type { SchemaTypeMap } from '../validators.js';
+import type { SchemaValidator } from '../validators/validator.js';
+/**
+ * Generated schema names usable as a socket frame contract.
+ *
+ * Every socket protocol root is both a validated schema and a tagged union, so
+ * a frame schema has to satisfy `parse` and `hasUnknownDiscriminant` alike.
+ */
+export type SocketFrameSchemaName = keyof SchemaTypeMap & SchemaName;
+/**
+ * Outcome of decoding one raw socket frame.
+ *
+ * `ignored` covers a non-text event and a frame carrying a `type` this build
+ * does not know; `error` covers a frame that is malformed against its schema.
+ */
+export type SocketFrameDecodeResult<TMessage> = {
+    type: 'ignored';
+} | {
+    error: ErrorPayload;
+    type: 'error';
+} | {
+    message: TMessage;
+    type: 'message';
+};
+/**
+ * Parses one browser-style message event into a typed, validated socket frame.
+ *
+ * Shared by every socket in the SDK so all of them answer a malformed known
+ * frame the same way, whatever their protocol root. The validator decides
+ * whether anything is actually checked: with the pass-through the frame is
+ * trusted exactly as sent, which is the SDK's default.
+ *
+ * A JSON syntax error and a schema violation both surface as an `error`
+ * result rather than a throw, because the only caller is a socket `message`
+ * listener — throwing there escapes into the transport, not into the consumer.
+ *
+ * @param event Raw socket message event.
+ * @param validator Boundary validator; the pass-through trusts the frame.
+ * @param schemaName Generated schema name this socket's frames must match.
+ */
+export declare function decodeSocketFrame<TName extends SocketFrameSchemaName>(event: unknown, validator: SchemaValidator, schemaName: TName): SocketFrameDecodeResult<SchemaTypeMap[TName]>;