@my-swu/simulator-client 0.1.0

package/dist/resources/lobby-session.js

@@ -0,0 +1,59 @@
+import { AuthenticatedSocketSessionController, authenticatedSocketUrl, } from '../internal/authenticated-socket-session.js';
+import { simulatorSocketErrorPayload } from '../internal/errors.js';
+export function createLobbySession(options) {
+    return new LobbySessionController({
+        access: normalizeLobbyAccess(options.access),
+        webSocketFactory: options.webSocketFactory,
+        wsUrl: options.wsUrl,
+        ...(options.validate == null ? {} : { validate: options.validate }),
+    });
+}
+function normalizeLobbyAccess(access) {
+    return {
+        lobbyId: access.lobbyId,
+        playerToken: access.playerToken,
+    };
+}
+class LobbySessionController extends AuthenticatedSocketSessionController {
+    constructor(options) {
+        super({
+            messageSchema: 'lobby-server-message',
+            playerToken: options.access.playerToken,
+            socketError: info => simulatorSocketErrorPayload(info),
+            socketUrl: authenticatedSocketUrl(options.wsUrl, `lobbies/${encodeURIComponent(options.access.lobbyId)}`),
+            webSocketFactory: options.webSocketFactory,
+            ...(options.validate == null ? {} : { validate: options.validate }),
+        });
+    }
+    handleServerMessage(message) {
+        switch (message.type) {
+            case 'welcome':
+                this.emit('welcome', message.payload);
+                break;
+            case 'snapshot':
+                this.setSnapshot(message.payload);
+                break;
+            case 'matchmakingRelocated':
+                this.emit('matchmakingRelocated', message.payload);
+                break;
+            case 'chatMessage':
+                this.emit('chatMessage', message.payload);
+                break;
+            case 'playerPresence':
+                this.emit('playerPresence', message.payload);
+                break;
+            case 'started':
+                this.emit('started', undefined);
+                break;
+            case 'kicked':
+                this.emit('kicked', message.payload);
+                break;
+            case 'error':
+                this.pushError(message.payload);
+                break;
+            case 'pong':
+                this.emit('pong', message.payload);
+                break;
+        }
+    }
+}

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

@@ -0,0 +1,357 @@
+import type { AddLobbyAiPlayerRequest, ErrorPayload, JoinLobbyRequest, KickLobbyPlayerRequest, KickLobbySpectatorRequest, LeaveLobbyRequest, LobbyChatRequest, LobbyMatchmakingDecisionRequest, LobbySyncRequest, PrepareLobbyLimitedAiDecksRequest, ReturnLobbyMatchRequest, SpectateLobbyRequest, StartLobbyLimitedMatchRequest, StartLobbyRequest, SubmitLobbyLimitedDeckRequest, UpdateLobbyAiPlayerRequest, UpdateLobbyPlayerRequest } from '../generated/index.js';
+import type { LobbyChatMessage, LobbyDeckPreview, LobbyDeckSetPreview, LobbyMatchmakingKind as GeneratedLobbyMatchmakingKind, LobbyParticipantRole, LobbyPlayerController, LobbyPlayerView, LobbyPrivateAiPlayerView, LobbyPrivateView, LobbySpectatorView, LobbyStartedAccess, LobbyStatus, LobbyVisibility, PlayerPresenceStatus, RoomPlayerPresenceEvent } from '../generated/types/lobby-access-response.js';
+import type { LobbyKickedPayload, LobbyRemovalReason } from '../generated/types/lobby-server-message.js';
+import type { HistoryIdentityInput } from '../generated/types/match-history-list-request.js';
+import type { ConnectionState, PongPayload } from '../session.js';
+import type { ConstructedFormat, FormatSetupInput, LimitedEventKind, MatchFormat } from '../types.js';
+import type { DeckInput } from './card-types.js';
+/**
+ * Wire shapes the generator owns, re-exported under their public SDK names.
+ *
+ * Each name below used to be declared here by hand *next to* the generated
+ * declaration of the same shape — two sources of truth for one contract, which
+ * stays invisible for exactly as long as the two copies happen to agree, and
+ * silently diverges the first time a field is added on one side only. The
+ * lobby lifecycle enums (`LobbyStatus`, `LobbyVisibility`, `LobbyRemovalReason`,
+ * …) were additionally recovered through indexed access on a response type
+ * (`LobbyListResponse['lobbies'][number]['status']`), which is the
+ * reconstruction the generated contract now makes unnecessary: every one of
+ * them is a declaration in `generated/types/common.ts`.
+ *
+ * A re-export is not a second declaration, so this block is the healthy form;
+ * `test/handwritten-wire-shapes.test.ts` fails if a hand-written *declaration*
+ * shadows a generated one again.
+ *
+ * `AddLobbyAiPlayerRequest`, `SubmitLobbyLimitedDeckRequest`,
+ * `UpdateLobbyPlayerRequest`, `LobbyPrivateView` and
+ * `LobbyPrivateAiPlayerView` joined this block after their hand-written copies
+ * were found *looser* than the schema the server validates against: three of
+ * them borrowed `JoinMatchRequest['deck']`, which is optional-nullable because
+ * a match seat may join deckless and submit later, on endpoints whose Rust
+ * request struct takes a plain `DeckInput`; two dropped wire fields the server
+ * reads (`authenticated`, `deckId`); and the AI view made
+ * `trilogyFormatMode` optional where the server always sends it.
+ * `test/lobby-wire-parity.test.ts` now pins each of them against its schema.
+ */
+export type { AddLobbyAiPlayerRequest, JoinLobbyRequest, KickLobbyPlayerRequest, KickLobbySpectatorRequest, LeaveLobbyRequest, LobbyChatMessage, LobbyChatRequest, LobbyDeckPreview, LobbyDeckSetPreview, LobbyKickedPayload, LobbyMatchmakingDecisionRequest, LobbyParticipantRole, LobbyPlayerController, LobbyPlayerView, LobbyPrivateAiPlayerView, LobbyPrivateView, LobbyRemovalReason, LobbySpectatorView, LobbyStartedAccess, LobbyStatus, LobbySyncRequest, LobbyVisibility, PlayerPresenceStatus, PrepareLobbyLimitedAiDecksRequest, RoomPlayerPresenceEvent, SpectateLobbyRequest, StartLobbyLimitedMatchRequest, StartLobbyRequest, SubmitLobbyLimitedDeckRequest, UpdateLobbyAiPlayerRequest, UpdateLobbyPlayerRequest, };
+export type LobbyConfig = {
+    type: 'match';
+    format: MatchFormat;
+    playerCount: number;
+    bestOfMatches: 1 | 3;
+    /** Enables the AFK game timer for started lobby matches. */
+    gameTimerEnabled: boolean;
+    /** Constructed legality profile used when `format` is `trilogy`. */
+    trilogyFormat?: ConstructedFormat | null;
+} | {
+    type: 'limitedEvent';
+    eventKind: LimitedEventKind;
+    setCode: string;
+    playerCount: number;
+    bestOfMatches: 1 | 3;
+    /** Enables the AFK game timer for started lobby matches. */
+    gameTimerEnabled: boolean;
+    /** Per-round booster set configuration. Empty outside chaos draft. */
+    draftRounds: Array<{
+        setCode: string;
+    }>;
+    /** Enables the per-pick countdown for chaos draft. */
+    pickTimerEnabled: boolean;
+    sealedPackCount?: number | null | undefined;
+};
+export interface CreateLobbyRequest {
+    config: LobbyConfig;
+    /** Fixed limited pack/leader seed. */
+    packSeed?: number | null;
+    /** Fixed match seed reused for limited duel matches. */
+    matchSeed?: number | null;
+    /** Whether the lobby should appear in public browsing surfaces. */
+    visibility: LobbyVisibility;
+    hostName: string;
+    /** Whether the host joined from an authenticated app session. */
+    hostAuthenticated: boolean;
+    /** Public avatar image URL for the lobby host. */
+    hostAvatarUrl?: string | null;
+    /** Public profile URL for the lobby host. */
+    hostProfileUrl?: string | null;
+    /** Personal identities that should own the host player's history. */
+    historyIdentities: HistoryIdentityInput[];
+}
+export type LobbyMatchmakingConfig = {
+    mode: 'duel';
+    format: ConstructedFormat;
+    bestOfMatches: 1 | 3;
+} | {
+    mode: 'trilogy';
+    format: ConstructedFormat;
+} | {
+    mode: 'twinSuns';
+};
+export interface LobbyMatchmakingRequest {
+    config: LobbyMatchmakingConfig;
+    name: string;
+    /** Public avatar image URL for the queued player. */
+    avatarUrl?: string | null;
+    /** Public profile URL for the queued player. */
+    profileUrl?: string | null;
+    /** Whether the player queued from an authenticated app session. */
+    authenticated: boolean;
+    /** Personal identities that should own this queued player's history. */
+    historyIdentities: HistoryIdentityInput[];
+    /**
+     * Deck the queued player brings to the pairing. Required: matchmaking has
+     * no later deck-submission step, so the server rejects a request without
+     * one.
+     */
+    deck: DeckInput;
+    /** Format-specific setup submitted with the matchmaking deck. */
+    formatSetup?: FormatSetupInput | null;
+    /** Display title for the submitted matchmaking deck. */
+    deckTitle?: string | null;
+    /** Freeform client deck id for the submitted deck. */
+    deckId?: string | null;
+    /**
+     * Optional verified account proof. When present and the selection is
+     * eligible, the server may silently place the player in a skill-based
+     * queue; a missing or invalid token always degrades to random pairing
+     * instead of failing.
+     */
+    accountToken?: string | null;
+}
+export type { ReturnLobbyMatchRequest };
+export interface UpdateLobbySettingsRequest {
+    playerToken: string;
+    visibility?: LobbyVisibility | null;
+    playerCount?: number | null;
+    gameTimerEnabled?: boolean | null;
+    matchFormat?: ConstructedFormat | null;
+    bestOfMatches?: 1 | 3 | null;
+    trilogyFormat?: ConstructedFormat | null;
+}
+export interface LobbyAccessResponse {
+    lobbyId: string;
+    playerId: string;
+    playerToken: string;
+    snapshot: LobbySnapshot;
+    private: LobbyPrivateView;
+}
+export interface LobbyResponse {
+    snapshot: LobbySnapshot;
+}
+export interface LobbyListResponse {
+    lobbies: PublicLobbySummary[];
+}
+export interface PublicLobbySummary {
+    lobbyId: string;
+    status: LobbyStatus;
+    visibility: LobbyVisibility;
+    config: LobbyConfig;
+    requiredPlayerCount: number;
+    playerCount: number;
+    spectatorCount: number;
+    canJoinAsPlayer: boolean;
+    canSpectate: boolean;
+    deckPreviews: LobbyDeckPreview[];
+    createdAtMs: number;
+}
+/**
+ * Queue kinds that can use the shared lobby matchmaking handshake.
+ *
+ * Wire-level only: the server picks the queue and clients must not surface
+ * the distinction to players.
+ *
+ * Aliased rather than re-exported so this warning stays attached to the name;
+ * the type is the generated declaration, unchanged.
+ */
+export type LobbyMatchmakingKind = GeneratedLobbyMatchmakingKind;
+export type LobbyMatchmakingView = {
+    kind: LobbyMatchmakingKind;
+    phase: 'searching';
+} | {
+    kind: LobbyMatchmakingKind;
+    phase: 'matchFound';
+    acceptDeadlineAtMs: number;
+    acceptedPlayerIds: string[];
+};
+export interface LobbyChatResponse {
+    message: LobbyChatMessage;
+    snapshot: LobbySnapshot;
+}
+export interface LobbySnapshot {
+    lobbyId: string;
+    status: LobbyStatus;
+    visibility: LobbyVisibility;
+    config: LobbyConfig;
+    /** Fixed limited pack/leader seed when configured. */
+    packSeed?: number | null;
+    /** Fixed match seed when configured. */
+    matchSeed?: number | null;
+    hostPlayerId: string;
+    requiredPlayerCount: number;
+    /** Absolute server deadline for the ready-lobby auto-start countdown. */
+    autoStartDeadlineAtMs?: number | null;
+    matchmaking?: LobbyMatchmakingView | null;
+    players: LobbyPlayerView[];
+    spectators: LobbySpectatorView[];
+    chat: LobbyChatMessage[];
+    /** Server-owned room activity. Empty when no player transition occurred. */
+    activity: RoomPlayerPresenceEvent[];
+}
+export interface LobbyAccessInput {
+    lobbyId: string;
+    playerToken: string;
+}
+export type LobbyServerMessage = {
+    type: 'welcome';
+    payload: {
+        lobbyId: string;
+        playerId: string;
+    };
+} | {
+    type: 'snapshot';
+    payload: LobbySnapshot;
+}
+/** A ranked sweep moved this player into a paired lobby; reconnect with the supplied access. */
+ | {
+    type: 'matchmakingRelocated';
+    payload: LobbyAccessResponse;
+} | {
+    type: 'chatMessage';
+    payload: LobbyChatMessage;
+} | {
+    type: 'playerPresence';
+    payload: RoomPlayerPresenceEvent;
+} | {
+    type: 'started';
+} | {
+    type: 'kicked';
+    payload: LobbyKickedPayload;
+} | {
+    type: 'error';
+    payload: ErrorPayload;
+} | {
+    type: 'pong';
+    payload: {
+        nonce?: string | null;
+    };
+};
+export interface LobbySessionEvents {
+    change: LobbySessionState;
+    chatMessage: LobbyChatMessage;
+    connectionState: ConnectionState;
+    error: ErrorPayload;
+    kicked: LobbyKickedPayload;
+    matchmakingRelocated: LobbyAccessResponse;
+    playerPresence: RoomPlayerPresenceEvent;
+    message: LobbyServerMessage;
+    pong: PongPayload;
+    snapshot: LobbySnapshot;
+    started: undefined;
+    welcome: {
+        lobbyId: string;
+        playerId: string;
+    };
+}
+export interface LobbySessionState {
+    connectionState: ConnectionState;
+    errors: readonly ErrorPayload[];
+    snapshot: LobbySnapshot | undefined;
+}
+export interface LobbySession {
+    readonly __v_skip: true;
+    readonly connectionState: ConnectionState;
+    readonly errorMessages: readonly string[];
+    readonly errors: readonly ErrorPayload[];
+    readonly snapshot: LobbySnapshot | undefined;
+    close: () => void;
+    connect: () => Promise<LobbySession>;
+    on: <TKey extends keyof LobbySessionEvents>(event: TKey, listener: (value: LobbySessionEvents[TKey]) => void) => () => void;
+    ping: (nonce?: string) => void;
+}
+/**
+ * Wire messages pushed over the list-level lobby socket (`GET /ws/lobbies`).
+ *
+ * Unlike {@link LobbyServerMessage} (the per-lobby socket), this carries the
+ * public, viewer-agnostic lobby list. The server sends a `snapshot` immediately
+ * on connect and a fresh `snapshot` on every list-affecting change; `pong`
+ * replies to a client `ping` keepalive. Each `snapshot` is the complete,
+ * authoritative list — replace, never merge.
+ */
+export type LobbyListServerMessage = {
+    type: 'snapshot';
+    payload: LobbyListResponse;
+} | {
+    type: 'pong';
+    payload: {
+        nonce?: string | null;
+    };
+};
+/**
+ * Auto-reconnect policy for the public lobby-list socket.
+ *
+ * The list socket reconnects on abnormal close/error with capped exponential
+ * backoff. Pass `false` to disable reconnect entirely, `true` for the defaults,
+ * or an object to tune the bounds. This is the one behavioral addition over the
+ * per-lobby {@link LobbySession}, which does not reconnect.
+ */
+export type LobbyListAutoReconnect = boolean | {
+    /** Initial backoff delay before the first reconnect attempt (ms). Default 500. */
+    initialDelayMs?: number;
+    /** Maximum backoff delay between reconnect attempts (ms). Default 5000. */
+    maxDelayMs?: number;
+    /** Exponential backoff multiplier applied each attempt. Default 2. */
+    backoffFactor?: number;
+};
+/** Options accepted by {@link LobbiesResource.subscribeList}. */
+export interface LobbyListSessionOptions {
+    /**
+     * Auto-reconnect policy for abnormal socket closes. Defaults to enabled with
+     * 500ms → 5s capped exponential backoff.
+     */
+    autoReconnect?: LobbyListAutoReconnect;
+}
+/** Events emitted by a {@link LobbyListSession}. */
+export interface LobbyListSessionEvents {
+    /** Aggregated state snapshot emitted on every change. */
+    change: LobbyListSessionState;
+    /** Underlying socket connection state transitions. */
+    connectionState: ConnectionState;
+    /** SDK or server error payloads. */
+    error: ErrorPayload;
+    /** Every decoded server message, before per-type dispatch. */
+    message: LobbyListServerMessage;
+    /** Keepalive replies to {@link LobbyListSession.ping}. */
+    pong: PongPayload;
+    /** The latest complete, authoritative public lobby list. */
+    snapshot: LobbyListResponse;
+}
+/** Aggregated state of a {@link LobbyListSession}. */
+export interface LobbyListSessionState {
+    connectionState: ConnectionState;
+    errors: readonly ErrorPayload[];
+    /** Latest public lobby list, or `undefined` before the first snapshot. */
+    lobbies: PublicLobbySummary[] | undefined;
+}
+/**
+ * Public, unauthenticated subscription to the live lobby list.
+ *
+ * Returned by {@link LobbiesResource.subscribeList}. Opens `${wsUrl}/lobbies`
+ * with no token and no `Sec-WebSocket-Protocol`, replaces its state from each
+ * pushed `snapshot`, and auto-reconnects on abnormal close (the one behavior
+ * added over the per-lobby {@link LobbySession}). On reconnect the server sends
+ * a fresh full snapshot, so no replay or cursor is needed.
+ */
+export interface LobbyListSession {
+    readonly __v_skip: true;
+    readonly connectionState: ConnectionState;
+    readonly errorMessages: readonly string[];
+    readonly errors: readonly ErrorPayload[];
+    /** Latest public lobby list, or `undefined` before the first snapshot. */
+    readonly lobbies: PublicLobbySummary[] | undefined;
+    close: () => void;
+    connect: () => Promise<LobbyListSession>;
+    on: <TKey extends keyof LobbyListSessionEvents>(event: TKey, listener: (value: LobbyListSessionEvents[TKey]) => void) => () => void;
+    /** Alias for `on('snapshot', listener)`, returning an unsubscribe function. */
+    onSnapshot: (listener: (lobbies: LobbyListResponse) => void) => () => void;
+    ping: (nonce?: string) => void;
+}

package/dist/resources/lobby-types.js

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

package/dist/resources/match-history.d.ts

@@ -0,0 +1,49 @@
+import type { MatchHistoryDeckStatsRequest, MatchHistoryDeckStatsResponse, MatchHistoryListRequest, MatchHistoryListResponse, MatchHistoryReplayRequest, MatchHistoryReplayResponse, MatchHistoryRestoreRequest, RestoreHistoryResponse } from '../generated/index.js';
+import type { SimulatorRequestOptions } from '../http/options.js';
+import type { EngineHttpRequester } from '../http/request.js';
+/**
+ * Request used to restore a server-side history entry into a fresh match.
+ */
+export interface MatchHistoryRestoreInput extends MatchHistoryRestoreRequest {
+    /**
+     * Durable history row id returned by {@link MatchHistoryResource.list}.
+     */
+    historyId: string;
+}
+/** Request used to load a completed server-side replay archive. */
+export interface MatchHistoryReplayInput extends MatchHistoryReplayRequest {
+    /** Durable history row id returned by {@link MatchHistoryResource.list}. */
+    historyId: string;
+}
+/**
+ * Server-owned simulator history APIs.
+ */
+export interface MatchHistoryResource {
+    /**
+     * Returns private lifetime simulator results for My SWU deck ids.
+     */
+    deckStats(request: MatchHistoryDeckStatsRequest, options?: SimulatorRequestOptions): Promise<MatchHistoryDeckStatsResponse>;
+    /**
+     * Lists saved and completed matches visible to the supplied identities.
+     */
+    list(request: MatchHistoryListRequest, options?: SimulatorRequestOptions): Promise<MatchHistoryListResponse>;
+    /** Loads public and post-game reveal-all frames for an authorized result. */
+    replay(request: MatchHistoryReplayInput, options?: SimulatorRequestOptions): Promise<MatchHistoryReplayResponse>;
+    /**
+     * Restores one authorized row whose eligibility is `available`.
+     */
+    restore(request: MatchHistoryRestoreInput, options?: SimulatorRequestOptions): Promise<RestoreHistoryResponse>;
+}
+/**
+ * Dependencies needed by the match-history resource.
+ */
+export interface MatchHistoryResourceOptions {
+    /**
+     * HTTP requester shared with other resources.
+     */
+    requester: EngineHttpRequester;
+}
+/**
+ * Creates the match-history resource client.
+ */
+export declare function createMatchHistoryResource(options: MatchHistoryResourceOptions): MatchHistoryResource;

package/dist/resources/match-history.js

@@ -0,0 +1,34 @@
+import { jsonBody, jsonHeaders } from '../http/json.js';
+/**
+ * Creates the match-history resource client.
+ */
+export function createMatchHistoryResource(options) {
+    const { requester } = options;
+    return {
+        deckStats: (request, options) => requester.request('match-history-deck-stats-response', '/api/match-history/deck-stats', {
+            body: jsonBody(requester.validate('match-history-deck-stats-request', request)),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+        list: (request, options) => requester.request('match-history-list-response', '/api/match-history', {
+            body: jsonBody(requester.validate('match-history-list-request', request)),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+        replay: (request, options) => requester.request('match-history-replay-response', `/api/match-history/${request.historyId}/replay`, {
+            body: jsonBody(requester.validate('match-history-replay-request', {
+                identities: request.identities,
+            })),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+        restore: (request, options) => requester.request('restore-history-response', `/api/match-history/${request.historyId}/restore`, {
+            body: jsonBody(requester.validate('match-history-restore-request', {
+                identities: request.identities,
+                restoreRequestId: request.restoreRequestId,
+            })),
+            headers: jsonHeaders(),
+            method: 'POST',
+        }, options),
+    };
+}