@my-swu/simulator-client 0.1.0

package/dist/http/request.js

@@ -0,0 +1,182 @@
+import { EngineRequestAbortedError } from '../internal/abort-error.js';
+import { EngineHttpError } from '../internal/errors.js';
+import { passthroughValidator } from '../validators/validator.js';
+import { createRequestAbortPlan, resolveRequestTimeoutMs } from './abort.js';
+import { parseJsonForSchema } from './json.js';
+/**
+ * Minimal HTTP helper shared by all SDK resources.
+ *
+ * Whether request bodies and responses are checked against the generated
+ * schemas is decided once, here, by the injected validator.
+ */
+export class EngineHttpRequester {
+    #baseUrl;
+    #defaultTimeoutMs;
+    #fetch;
+    #validator;
+    /**
+     * Creates one requester.
+     */
+    constructor(options) {
+        this.#baseUrl = options.baseUrl;
+        this.#defaultTimeoutMs = options.defaultTimeoutMs;
+        this.#fetch = options.fetch;
+        this.#validator = options.validate ?? passthroughValidator;
+    }
+    /**
+     * Validates one outbound payload built by a resource method.
+     *
+     * Resources call this instead of `parseSchema` so a client without a
+     * validator neither pays for the check nor pulls the schema map into the
+     * bundle. With validation off it is the identity.
+     *
+     * @param schemaName Generated schema name the payload must match.
+     * @param value Payload about to be serialized into a request.
+     */
+    validate(schemaName, value) {
+        return this.#validator.parse(schemaName, value);
+    }
+    /**
+     * Sends one request and validates the JSON response against one schema.
+     *
+     * `init` carries the transport shape owned by the calling resource method;
+     * `options` carries the caller's cancellation controls. Both the network call
+     * and the body read run under the composed signal, so a timeout also cancels
+     * a response that streams forever.
+     */
+    async request(schemaName, pathname, init = {}, options = {}) {
+        const url = this.resolveUrl(pathname);
+        const method = init.method ?? 'GET';
+        const context = { method, url: url.toString() };
+        // An already-aborted caller signal never reaches the network.
+        if (options.signal?.aborted === true) {
+            throw new EngineRequestAbortedError('aborted', context);
+        }
+        const plan = createRequestAbortPlan(options.signal, resolveRequestTimeoutMs(options.timeoutMs, this.#defaultTimeoutMs));
+        let response;
+        let responseText;
+        try {
+            response = await this.#fetch(url, plan.signal == null ? init : { ...init, signal: plan.signal });
+            responseText = await response.text();
+        }
+        catch (error) {
+            throw plan.abortErrorFor(context) ?? error;
+        }
+        finally {
+            plan.dispose();
+        }
+        // A fetch adapter that ignores `signal` still resolves after the deadline
+        // passed. Honour the cancellation the caller asked for either way.
+        const abortError = plan.abortErrorFor(context);
+        if (abortError != null) {
+            throw abortError;
+        }
+        if (!response.ok) {
+            throw this.#buildHttpError(response, responseText, method, url);
+        }
+        return this.#validator.parse(schemaName, parseJsonForSchema(schemaName, responseText));
+    }
+    /**
+     * Resolves one API pathname against the configured base URL.
+     */
+    resolveUrl(pathname) {
+        return new URL(pathname.replace(/^\//, ''), this.#baseUrl);
+    }
+    #buildHttpError(response, responseText, method, url) {
+        const parsed = parseOptionalJson(responseText);
+        const rawText = responseText === '' ? undefined : responseText;
+        if (parsed.ok) {
+            const apiError = this.#parseApiError(parsed.value);
+            if (apiError != null) {
+                return new EngineHttpError(apiError.error.message, {
+                    code: apiError.error.code,
+                    method,
+                    payload: parsed.value,
+                    responseText: rawText,
+                    status: response.status,
+                    url: url.toString(),
+                });
+            }
+        }
+        return new EngineHttpError(`HTTP ${response.status} ${responseStatusText(response)}`, {
+            method,
+            payload: parsed.ok ? parsed.value : undefined,
+            responseText: rawText,
+            status: response.status,
+            url: url.toString(),
+        });
+    }
+    /**
+     * Returns one API error payload, or `undefined` when the body's shape differs.
+     *
+     * The structural check runs in both modes on purpose. An error body is the
+     * one payload the SDK must never trust blindly: with validation off `parse`
+     * is the identity, and reading `error.message` off an arbitrary gateway error
+     * page would turn a server failure into a `TypeError`.
+     */
+    #parseApiError(value) {
+        try {
+            return asApiErrorResponse(this.#validator.parse('api-error-response', value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Returns browser status text or a concise fallback for test/runtime parity.
+ */
+function responseStatusText(response) {
+    if (response.statusText !== '') {
+        return response.statusText;
+    }
+    return statusTextByCode(response.status);
+}
+/**
+ * Maps common HTTP status codes when runtime Response omits `statusText`.
+ */
+function statusTextByCode(status) {
+    switch (status) {
+        case 400:
+            return 'Bad Request';
+        case 401:
+            return 'Unauthorized';
+        case 403:
+            return 'Forbidden';
+        case 404:
+            return 'Not Found';
+        case 500:
+            return 'Internal Server Error';
+        case 503:
+            return 'Service Unavailable';
+        default:
+            return 'Error';
+    }
+}
+/**
+ * Parses one optional JSON error body without throwing.
+ */
+function parseOptionalJson(responseText) {
+    if (responseText === '') {
+        return { ok: false };
+    }
+    try {
+        return { ok: true, value: JSON.parse(responseText) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Narrows one parsed body to an API error payload by shape alone.
+ *
+ * `api-error-response` is one required `error` object of two required strings,
+ * so this check is the schema for every field the SDK reads off it.
+ */
+function asApiErrorResponse(value) {
+    const error = value?.error;
+    if (typeof error?.code !== 'string' || typeof error.message !== 'string') {
+        return undefined;
+    }
+    return value;
+}

package/dist/http/validated-json.d.ts

@@ -0,0 +1,9 @@
+import type { EngineHttpRequester } from './request.js';
+import type { SchemaTypeMap } from '../validators.js';
+/**
+ * Creates validated JSON POST request initializers bound to one SDK requester.
+ *
+ * Resource modules retain their public methods while sharing their request
+ * validation and JSON serialization boundary.
+ */
+export declare function createValidatedJsonPost(requester: EngineHttpRequester): <TName extends keyof SchemaTypeMap>(schemaName: TName, body: unknown) => RequestInit;

package/dist/http/validated-json.js

@@ -0,0 +1,14 @@
+import { jsonBody, jsonHeaders } from './json.js';
+/**
+ * Creates validated JSON POST request initializers bound to one SDK requester.
+ *
+ * Resource modules retain their public methods while sharing their request
+ * validation and JSON serialization boundary.
+ */
+export function createValidatedJsonPost(requester) {
+    return (schemaName, body) => ({
+        body: jsonBody(requester.validate(schemaName, body)),
+        headers: jsonHeaders(),
+        method: 'POST',
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export { createSimulatorClient } from './client.js';
+export type * from './generated/public-types.js';
+export type { AdminResource, RankedLeaderboardOptions, SimulatorAdminAuth, } from './resources/admin.js';
+export type { AddLobbyAiPlayerRequest, CreateLobbyRequest, JoinLobbyRequest, KickLobbyPlayerRequest, KickLobbySpectatorRequest, LeaveLobbyRequest, LobbiesResource, LobbyAccessInput, LobbyAccessResponse, LobbyChatMessage, LobbyChatRequest, LobbyChatResponse, LobbyConfig, LobbyDeckPreview, LobbyDeckSetPreview, LobbyKickedPayload, LobbyListAutoReconnect, LobbyListResponse, LobbyListServerMessage, LobbyListSession, LobbyListSessionEvents, LobbyListSessionOptions, LobbyListSessionState, LobbyMatchmakingDecisionRequest, LobbyMatchmakingKind, LobbyMatchmakingView, LobbyParticipantRole, LobbyPlayerController, PlayerPresenceStatus, RoomPlayerPresenceEvent, LobbyPlayerView, LobbyPrivateAiPlayerView, LobbyPrivateView, LobbyRemovalReason, LobbyResponse, LobbyServerMessage, LobbySession, LobbySessionEvents, LobbySnapshot, LobbySpectatorView, LobbyStartedAccess, LobbyStatus, LobbySyncRequest, LobbyVisibility, PrepareLobbyLimitedAiDecksRequest, PublicLobbySummary, LobbyMatchmakingConfig, LobbyMatchmakingRequest, ReturnLobbyMatchRequest, StartLobbyLimitedMatchRequest, StartLobbyRequest, SpectateLobbyRequest, SubmitLobbyLimitedDeckRequest, UpdateLobbyAiPlayerRequest, UpdateLobbyPlayerRequest, UpdateLobbySettingsRequest, } from './resources/lobbies.js';
+export type { CloseTournamentRoomRequest, CreateTournamentRoomRequest, CreateTournamentTableRequest, JoinTournamentRoomRequest, JoinTournamentTableRequest, LeaveTournamentRoomRequest, PublicTournamentRoomSummary, ReturnTournamentMatchRequest, StartTournamentEventRequest, SubmitTournamentDeckRequest, TournamentEventCommandRequest, TournamentRoomsResource, TournamentRoomAccessInput, TournamentRoomAccessResponse, TournamentRoomChatRequest, TournamentRoomChatResponse, TournamentRoomListResponse, TournamentRoomResponse, TournamentRoomServerMessage, TournamentRoomSession, TournamentRoomSessionEvents, TournamentRoomSnapshot, TournamentRoomSyncRequest, UpdateTournamentRoomPlayerRequest, UpdateTournamentRoomSettingsRequest, } from './resources/tournament-rooms.js';
+export { canDeployAnyLeader, flattenTargetGroups, getDeployableLeaderIndices, getLeaderDeployCommands, isSingleTargetPlan, leaderDeployCommand, targetGroupsOf, } from './actionable.js';
+export type { TargetingActionView } from './actionable.js';
+export type { SimulatorClient, SimulatorClientOptions } from './client.js';
+export type { AbandonMatchRequest, AbandonMatchResponse, ApiErrorResponse, AiStatusPayload, CardsResponse, CardCatalogRefreshResponse, ClientMessage, CreateLimitedEventRequest, CreateMetaWindowRequest, CreateMatchRequest, ErrorPayload, FormatEventResponse, FormatEventRequest, GameCommand, GameEvent, GameState, GetMatchResponse, HealthResponse, JoinLimitedEventRequest, JoinMatchRequest, LeaveMatchRequest, LeaveMatchResponse, LimitedEventAccessResponse, LimitedEventCommandRequest, LimitedEventPreflightResponse, LimitedEventResponse, ListActiveAiMatchesRequest, ListActiveAiMatchesResponse, MatchAccessResponse, MatchChatLookupResponse, MatchConnectionRole, MatchHistoryDeckStatsRequest, MatchHistoryDeckStatsResponse, MatchHistoryListRequest, MatchHistoryListResponse, MatchHistoryReplayRequest, MatchHistoryReplayResponse, MatchHistoryRestoreRequest, RestoreHistoryResponse, MatchSavePayload, MatchSpectatorAccessResponse, MetaWindow, MetaWindowsResponse, ResolveCardIdsRequest, ResolveCardIdsResponse, RankedAdminStatus, RankedLeaderboardEntry, RankedLeaderboardQuery, RankedLeaderboardResponse, RankedMatchmakingView, RankedProfileRequest, RankedProfileResponse, RankedQueue, RematchMatchRequest, RematchMatchResponse, RestoreMatchSaveRequest, RestoreMatchSaveResponse, SaveMatchRequest, ServerMessage, SetAiPausedRequest, SetRankedAdmissionRequest, SetSimulatorMaintenanceRequest, SimulatorAdminStatusResponse, SimulatorAvailabilityResponse, SpectateMatchRequest, SubmitMatchDeckRequest, SubmitMatchDeckResponse, UndoMatchRequest, UndoMatchResponse, UndoRespondMatchRequest, WelcomePayload, } from './generated/index.js';
+export type { UndoCancelReason } from './generated/types/game-event.js';
+export type { LimitedSideboardPoolView } from './generated/types/game-state.js';
+export type { HistoryIdentityInput, HistorySection, HistoryStatus, } from './generated/types/match-history-list-request.js';
+export type { MatchHistoryEntry, MatchHistoryPlayerSummary, } from './generated/types/match-history-entry.js';
+export type { MatchHistoryReplayArchive } from './generated/types/match-history-replay-response.js';
+export type { DeckArchetype, DeckArchetypeMatchup, DeckEndReasonCount, DeckFormatStats, DeckOpponentStats, DeckStats, DeckStatsArchetype, DeckStatsOpponentKind, WinLossDrawRecord, } from './generated/types/match-history-deck-stats-response.js';
+export { schemaVersion } from './generated/version.js';
+export type { FormatEventCommand } from './generated/types/format-event-request.js';
+export { EngineHttpError, SdkValidationError, SimulatorSocketError, SIMULATOR_REJECTION_CLOSE_CODE, } from './internal/errors.js';
+export type { EngineHttpErrorOptions, SimulatorSocketErrorKind, WebSocketCloseInfo, } from './internal/errors.js';
+export { EngineRequestAbortedError } from './internal/abort-error.js';
+export type { EngineRequestAbortKind, EngineRequestAbortedErrorOptions, } from './internal/abort-error.js';
+export type { SimulatorRequestOptions } from './http/options.js';
+export type { EngineWebSocket, FetchLike, WebSocketFactory } from './internal/transport.js';
+export { aiFormatEventMessage, commandMessage, formatEventMessage, interactionCueMessage, pingMessage, readyMessage, setAiPausedMessage, syncRequestMessage, undoMessage, undoResponseMessage, chatMessage, } from './messages.js';
+export type { CardInteractionCueRequest, } from './generated/types/client-message.js';
+export type { CardInteractionCue, CardInteractionCueKind, CardInteractionCueState, CardInteractionDragOffset, MatchChatMessage, MatchHistoryFeedEntry, MatchHistorySnapshot, MatchQuickPhrase, } from './generated/types/server-message.js';
+export type { CardIdResolution, CardMetadata, CardReferenceInput, CardReferenceType, DeckInput, DeckJson, DeckJsonCard, } from './resources/card-types.js';
+export type { CardsResource } from './resources/card-resource.js';
+export type { LimitedEventAccess, LimitedEventAccessInput, LimitedEventCommand, LimitedEventPreflight, LimitedEventReference, LimitedEventSnapshot, LimitedEventsResource, } from './resources/limited-events.js';
+export type { MatchHistoryResource, MatchHistoryReplayInput, MatchHistoryRestoreInput, } from './resources/match-history.js';
+export type { MatchAccess, MatchAccessInput, MatchConnectionAccessInput, MatchReference, MatchSpectatorAccess, MatchSpectatorAccessInput, MatchesResource, } from './resources/matches.js';
+export type { SessionResource } from './resources/session.js';
+export type { SystemResource } from './resources/system.js';
+export type { MatchSeat, MatchSession, MatchSessionAccess, MatchSessionAutoReconnectOptions, MatchSessionAutoReconnectPolicy, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionOptions, MatchSessionReconnectState, MatchSessionSnapshotPredicate, MatchSessionState, MatchSessionWaitOptions, } from './match-session.js';
+export type { ConnectionState, PongPayload } from './session.js';
+export { createSchemaValidator, parseSchema } from './validators.js';
+export type { SchemaTypeMap } from './validators.js';
+export type { SchemaValidator } from './validators/validator.js';
+export type { AbilityTarget, AbilityWindow, ActionAbilitySource, ActionAbilityView, ActiveAiMatchLimitScope, ActiveAiMatchRecoveryEntry, ActiveEffectDescriptionView, ActiveEffectView, AiDifficulty, AiOpponentConfig, AiSeatStatusPayload, AiTrilogyFormatMode, AspectCount, AttachmentMode, AttackChoiceView, AttackTarget, AvailableAttackView, CapturedUnitView, CaptureOptionsView, CaptureSelection, CardArena, CardChoiceResourcePaymentOptionView, CardDrawSource, CardInstanceView, CardReferenceMatchView, CloseTournamentRoomActiveMatches, ConstructedFormat, CurrentAttackStateView, CurrentAttackView, DeckRegistrationView, DelayedEffectDescriptionView, DelayedEffectTimingView, DelayedEffectView, DistributionAssignment, DistributionDamageKindView, DistributionItemView, DistributionTargetView, DistributionTokenKindView, DraftRoundConfig, DynamicPowerLimit, EffectCardScopeView, EffectDurationView, EffectRestrictionView, EffectSourceView, EffectTargetView, ExploitOptionsView, FormatSeatView, FormatSetupInput, GameTimerActiveClockView, GameTimerReserveView, GameTimerStateView, HiddenCardChoiceMode, HiddenZoneKind, InitiativeChoiceReason, InitiativeState, InstructedAttackView, LeaderActionView, LeaderDeployActionView, LeaderDeployCostView, LeaderDeployMode, LeaderDeployThresholdBonus, LeaderStateView, LimitedCardSlot, LimitedCardTreatment, LimitedDeckSourceView, LimitedEventKind, LimitedEventPhaseView, LimitedEventPreflightIssue, LimitedEventSeatView, LimitedEventView, LimitedEventViewerView, LimitedPackCardView, LobbyWelcomePayload, MaintenanceStatus, MatchEndReason, MatchFormat, MatchHistoryDeckSummary, MatchPhase, MatchResult, MatchSaveSeat, MatchScenarioInput, MatchSeriesView, MatchStatus, MctsConfigOverride, ModeChoiceView, NamedCardEffectDescriptionView, PendingAbilityAspectChoiceView, PendingAbilityAttackChoiceView, PendingAbilityCardChoiceView, PendingAbilityFamily, PendingAbilityModeChoiceView, PendingAbilityNameChoiceView, PendingAbilityOrderAbilityView, PendingAbilityOrderChoiceView, PendingAbilityOrderGroupView, PendingAbilityView, PendingChoiceView, PendingDistributionView, PendingUndoRequest, PlayActionView, PlayCardSourceView, PlayCardZone, PlayerTargetPattern, PresenceFilter, PromptShape, PromptState, RejectedPlayView, RelationFilter, ResourceCardView, ResourcePaymentOptionView, Seat, SeatDirection, SeatOfferIntent, SeatState, SelectionScope, SeriesEndReason, SeriesGameRecord, SeriesResultView, SharedCounterState, SimulatorRuntimeStats, SmuggleActionView, SmuggleKind, TargetGroupPurpose, TargetSelectionGroup, TargetSelectionPlanView, TournamentRoomMatchReadyPayload, TournamentRoomPlayerView, TournamentRoomPrivateView, TournamentRoomStatus, TournamentRoomWelcomePayload, TournamentTableStatus, TournamentTableView, TriggerWindowView, TurnPassSource, TwinSunsCounter, TwinSunsCountersView, UndoRequestReason, UniquenessFilter, UnitAbilitySuppressionView, UnitCopiedCardEntry, UnitDefeatCause, UnitExtremum, UnitFilter, UnitStateView, UpgradeStateView, } from './types.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createSimulatorClient } from './client.js';
+export { canDeployAnyLeader, flattenTargetGroups, getDeployableLeaderIndices, getLeaderDeployCommands, isSingleTargetPlan, leaderDeployCommand, targetGroupsOf, } from './actionable.js';
+// Routed through the standalone version module on purpose: re-exporting it
+// from `./generated/schemas.js` would drag the multi-MB schema map into every
+// consumer that only needs the wire marker.
+export { schemaVersion } from './generated/version.js';
+export { EngineHttpError, SdkValidationError, SimulatorSocketError, SIMULATOR_REJECTION_CLOSE_CODE, } from './internal/errors.js';
+export { EngineRequestAbortedError } from './internal/abort-error.js';
+export { aiFormatEventMessage, commandMessage, formatEventMessage, interactionCueMessage, pingMessage, readyMessage, setAiPausedMessage, syncRequestMessage, undoMessage, undoResponseMessage, chatMessage, } from './messages.js';
+export { createSchemaValidator, parseSchema } from './validators.js';

package/dist/internal/abort-error.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Why one simulator HTTP request stopped before the server answered.
+ *
+ * - `aborted`: the caller's own `AbortSignal` fired.
+ * - `timeout`: the per-call or client-level timeout elapsed first.
+ *
+ * When a caller passes both a signal and a timeout, whichever fired first
+ * names the kind.
+ */
+export type EngineRequestAbortKind = 'aborted' | 'timeout';
+/**
+ * Context captured for one cancelled HTTP request.
+ *
+ * These fields mirror {@link EngineHttpErrorOptions} so a UI can log both
+ * failure channels the same way.
+ *
+ * @example
+ * ```ts
+ * import type { EngineRequestAbortedErrorOptions } from '@my-swu/simulator-client'
+ *
+ * const timedOutOptions: EngineRequestAbortedErrorOptions = {
+ *   method: 'GET',
+ *   timeoutMs: 5_000,
+ *   url: 'http://127.0.0.1:4000/api/matches/match_123',
+ * }
+ *
+ * console.log(timedOutOptions.timeoutMs)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export interface EngineRequestAbortedErrorOptions {
+    /**
+     * HTTP method used for the cancelled request.
+     */
+    method?: string | undefined;
+    /**
+     * Timeout that applied to the request, when one did.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Fully resolved request URL.
+     */
+    url?: string | undefined;
+}
+/**
+ * Error thrown when a simulator HTTP request is cancelled before it answers.
+ *
+ * This is the fourth SDK failure channel next to `EngineHttpError` (the server
+ * answered with a non-2xx status), `SdkValidationError` (a payload did not
+ * match the schema), and `SimulatorSocketError` (a socket failed). Read
+ * [`kind`](#) to tell a caller-initiated abort from a timeout.
+ *
+ * @example
+ * ```ts
+ * import { EngineRequestAbortedError, createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({ baseUrl: 'http://127.0.0.1:4000' })
+ *
+ * try {
+ *   await simulatorClient.system.health({ timeoutMs: 2_000 })
+ * }
+ * catch (error) {
+ *   if (error instanceof EngineRequestAbortedError && error.kind === 'timeout') {
+ *     console.warn('health check timed out after', error.timeoutMs)
+ *   }
+ * }
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export declare class EngineRequestAbortedError extends Error {
+    /**
+     * Stable classification of the cancellation.
+     */
+    readonly kind: EngineRequestAbortKind;
+    /**
+     * HTTP method used for the cancelled request.
+     */
+    readonly method: string | undefined;
+    /**
+     * Timeout that applied to the request, when one did.
+     */
+    readonly timeoutMs: number | undefined;
+    /**
+     * Fully resolved request URL.
+     */
+    readonly url: string | undefined;
+    /** Creates one classified cancellation error with its request context. */
+    constructor(kind: EngineRequestAbortKind, options?: EngineRequestAbortedErrorOptions);
+}

package/dist/internal/abort-error.js

@@ -0,0 +1,62 @@
+/**
+ * Error thrown when a simulator HTTP request is cancelled before it answers.
+ *
+ * This is the fourth SDK failure channel next to `EngineHttpError` (the server
+ * answered with a non-2xx status), `SdkValidationError` (a payload did not
+ * match the schema), and `SimulatorSocketError` (a socket failed). Read
+ * [`kind`](#) to tell a caller-initiated abort from a timeout.
+ *
+ * @example
+ * ```ts
+ * import { EngineRequestAbortedError, createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({ baseUrl: 'http://127.0.0.1:4000' })
+ *
+ * try {
+ *   await simulatorClient.system.health({ timeoutMs: 2_000 })
+ * }
+ * catch (error) {
+ *   if (error instanceof EngineRequestAbortedError && error.kind === 'timeout') {
+ *     console.warn('health check timed out after', error.timeoutMs)
+ *   }
+ * }
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ */
+export class EngineRequestAbortedError extends Error {
+    /**
+     * Stable classification of the cancellation.
+     */
+    kind;
+    /**
+     * HTTP method used for the cancelled request.
+     */
+    method;
+    /**
+     * Timeout that applied to the request, when one did.
+     */
+    timeoutMs;
+    /**
+     * Fully resolved request URL.
+     */
+    url;
+    /** Creates one classified cancellation error with its request context. */
+    constructor(kind, options = {}) {
+        super(engineRequestAbortMessage(kind, options.timeoutMs));
+        this.name = 'EngineRequestAbortedError';
+        this.kind = kind;
+        this.method = options.method;
+        this.timeoutMs = options.timeoutMs;
+        this.url = options.url;
+    }
+}
+/** Human-readable developer message for one cancellation kind. */
+function engineRequestAbortMessage(kind, timeoutMs) {
+    if (kind === 'aborted') {
+        return 'request aborted by the caller';
+    }
+    return timeoutMs == null
+        ? 'request timed out'
+        : `request timed out after ${timeoutMs}ms`;
+}

package/dist/internal/authenticated-socket-session.d.ts

@@ -0,0 +1,63 @@
+import type { WebSocketFactory } from './transport.js';
+import { type WebSocketCloseInfo } from './errors.js';
+import type { SocketFrameSchemaName } from './socket-frame.js';
+import type { ConnectionState } from '../session.js';
+import type { SchemaValidator } from '../validators/validator.js';
+/** Events every authenticated room socket session emits. */
+export interface AuthenticatedSocketSessionEvents<TMessage, TSnapshot, TError> {
+    change: AuthenticatedSocketSessionState<TSnapshot, TError>;
+    connectionState: ConnectionState;
+    error: TError;
+    message: TMessage;
+    snapshot: TSnapshot;
+}
+/** Shared observable state for authenticated room socket sessions. */
+export interface AuthenticatedSocketSessionState<TSnapshot, TError> {
+    connectionState: ConnectionState;
+    errors: readonly TError[];
+    snapshot: TSnapshot | undefined;
+}
+/**
+ * Lifecycle shared by authenticated lobby-like sockets.
+ *
+ * Subclasses only route their protocol-specific server messages, naming the
+ * generated schema those messages must match; decoding and validating the
+ * frame is done here, once, so every room socket answers a malformed known
+ * frame the same way the match socket does. Tokens always travel through the
+ * WebSocket subprotocol list instead of the connection URL.
+ */
+export declare abstract class AuthenticatedSocketSessionController<TMessage, TSnapshot, TError extends {
+    code: string;
+    message: string;
+}, TEvents extends AuthenticatedSocketSessionEvents<TMessage, TSnapshot, TError>> {
+    #private;
+    readonly __v_skip = true;
+    protected constructor(options: {
+        /** Generated schema every inbound frame of this protocol must match. */
+        messageSchema: SocketFrameSchemaName;
+        playerToken: string;
+        socketError: (info: WebSocketCloseInfo) => TError;
+        socketUrl: string;
+        /** Boundary validator; defaults to the pass-through, which checks nothing. */
+        validate?: SchemaValidator | undefined;
+        webSocketFactory: WebSocketFactory;
+    });
+    get connectionState(): ConnectionState;
+    get errorMessages(): readonly string[];
+    get errors(): readonly TError[];
+    get snapshot(): TSnapshot | undefined;
+    connect(): Promise<this>;
+    close(): void;
+    on<TKey extends keyof TEvents>(event: TKey, listener: (value: TEvents[TKey]) => void): () => void;
+    ping(nonce?: string): void;
+    /** Emits one protocol-specific event from a subclass message router. */
+    protected emit<TKey extends keyof TEvents>(event: TKey, value: TEvents[TKey]): void;
+    /** Stores and emits a protocol snapshot from a subclass message router. */
+    protected setSnapshot(snapshot: TSnapshot): void;
+    /** Stores and emits a protocol error from a subclass message router. */
+    protected pushError(error: TError): void;
+    /** Routes one parsed server message into protocol-specific events. */
+    protected abstract handleServerMessage(message: TMessage): void;
+}
+/** Builds a token-free authenticated room socket URL. */
+export declare function authenticatedSocketUrl(base: string, path: string): string;

package/dist/internal/authenticated-socket-session.js

@@ -0,0 +1,170 @@
+import { TypedEmitter } from './emitter.js';
+import { websocketCloseInfo } from './websocket-event.js';
+import { SIMULATOR_REJECTION_CLOSE_CODE } from './errors.js';
+import { DEFAULT_ERROR_HISTORY_LIMIT } from './limits.js';
+import { decodeSocketFrame } from './socket-frame.js';
+import { playerTokenProtocols } from '../connection/url.js';
+import { passthroughValidator } from '../validators/validator.js';
+/**
+ * Lifecycle shared by authenticated lobby-like sockets.
+ *
+ * Subclasses only route their protocol-specific server messages, naming the
+ * generated schema those messages must match; decoding and validating the
+ * frame is done here, once, so every room socket answers a malformed known
+ * frame the same way the match socket does. Tokens always travel through the
+ * WebSocket subprotocol list instead of the connection URL.
+ */
+export class AuthenticatedSocketSessionController {
+    __v_skip = true;
+    #emitter = new TypedEmitter();
+    #messageSchema;
+    #socketError;
+    #socketUrl;
+    #validator;
+    #webSocketFactory;
+    #connectionState = 'idle';
+    #errors = [];
+    /** Previous live socket held until its replacement has opened. */
+    #replacedSocket;
+    #socket;
+    #snapshot;
+    constructor(options) {
+        this.#messageSchema = options.messageSchema;
+        this.#socketError = options.socketError;
+        this.#socketUrl = options.socketUrl;
+        this.#validator = options.validate ?? passthroughValidator;
+        this.#webSocketFactory = options.webSocketFactory;
+        this.#playerToken = options.playerToken;
+    }
+    #playerToken;
+    get connectionState() {
+        return this.#connectionState;
+    }
+    get errorMessages() {
+        return this.#errors.map(error => `${error.code} - ${error.message}`);
+    }
+    get errors() {
+        return [...this.#errors];
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    async connect() {
+        // Keep current room socket open until replacement reaches `open`. This
+        // makes a recovery handoff one logical presence on server, rather than a
+        // final disconnect followed by reconnect.
+        this.#replacedSocket?.close();
+        const previousSocket = this.#socket;
+        this.#replacedSocket = previousSocket;
+        this.#setConnectionState('connecting');
+        const socket = this.#webSocketFactory(this.#socketUrl, playerTokenProtocols(this.#playerToken));
+        this.#socket = socket;
+        let opened = false;
+        socket.addEventListener('open', () => {
+            if (this.#socket !== socket)
+                return;
+            opened = true;
+            this.#setConnectionState('open');
+            const replaced = this.#replacedSocket;
+            this.#replacedSocket = undefined;
+            replaced?.close();
+        });
+        socket.addEventListener('close', (event) => {
+            if (this.#socket !== socket)
+                return;
+            // The replacement never opened, so old socket cannot be retained.
+            // Closing it makes the following disconnect truthful rather than leaked.
+            if (!opened) {
+                const replaced = this.#replacedSocket;
+                this.#replacedSocket = undefined;
+                replaced?.close();
+            }
+            this.#setConnectionState('closed');
+            // The server refuses user-relevant connections by completing the
+            // upgrade and closing with the rejection code — surface that refusal
+            // (with the engine error code in the reason) instead of losing it.
+            const info = websocketCloseInfo(event);
+            if (info.closeCode === SIMULATOR_REJECTION_CLOSE_CODE) {
+                this.pushError(this.#socketError(info));
+            }
+        });
+        // Transport `error` events are opaque; they carry no code or message.
+        socket.addEventListener('error', () => {
+            if (this.#socket === socket)
+                this.pushError(this.#socketError({}));
+        });
+        socket.addEventListener('message', (event) => {
+            if (this.#socket === socket)
+                this.#handleMessage(event);
+        });
+        return this;
+    }
+    close() {
+        const socket = this.#socket;
+        const replaced = this.#replacedSocket;
+        this.#socket = undefined;
+        this.#replacedSocket = undefined;
+        socket?.close();
+        replaced?.close();
+        this.#setConnectionState('closed');
+    }
+    on(event, listener) {
+        return this.#emitter.on(event, listener);
+    }
+    ping(nonce) {
+        this.#socket?.send(JSON.stringify({ type: 'ping', payload: { nonce } }));
+    }
+    /** Emits one protocol-specific event from a subclass message router. */
+    emit(event, value) {
+        this.#emitter.emit(event, value);
+    }
+    /** Stores and emits a protocol snapshot from a subclass message router. */
+    setSnapshot(snapshot) {
+        this.#snapshot = snapshot;
+        this.emit('snapshot', snapshot);
+        this.#emitChange();
+    }
+    /** Stores and emits a protocol error from a subclass message router. */
+    pushError(error) {
+        // Bounded: a flapping room socket pushes one error per failed attempt.
+        this.#errors = [...this.#errors, error].slice(-DEFAULT_ERROR_HISTORY_LIMIT);
+        this.emit('error', error);
+        this.#emitChange();
+    }
+    #handleMessage(event) {
+        // The schema name is protocol-specific, so the decoded shapes are erased to
+        // this session's `TMessage` / `TError` — the subclass pairing them is what
+        // ties `messageSchema` to the message and error types it routes.
+        const decoded = decodeSocketFrame(event, this.#validator, this.#messageSchema);
+        if (decoded.type === 'ignored')
+            return;
+        // A malformed known frame is a contract violation, but a socket `message`
+        // listener is the wrong place to throw from: it escapes into the transport
+        // instead of reaching the consumer. Report it on the session's own error
+        // channel, exactly as the match socket does.
+        if (decoded.type === 'error') {
+            this.pushError(decoded.error);
+            return;
+        }
+        const message = decoded.message;
+        this.emit('message', message);
+        this.handleServerMessage(message);
+    }
+    #setConnectionState(state) {
+        this.#connectionState = state;
+        this.emit('connectionState', state);
+        this.#emitChange();
+    }
+    #emitChange() {
+        this.emit('change', {
+            connectionState: this.#connectionState,
+            errors: this.errors,
+            snapshot: this.#snapshot,
+        });
+    }
+}
+/** Builds a token-free authenticated room socket URL. */
+export function authenticatedSocketUrl(base, path) {
+    const root = base.endsWith('/') ? base : `${base}/`;
+    return new URL(path, root).toString();
+}