@my-swu/simulator-client 0.1.0

package/dist/match-session/methods.d.ts

@@ -0,0 +1,433 @@
+import type { FormatEventCommand } from '../generated/types/format-event-request.js';
+import type { CardInteractionCueRequest } from '../generated/types/client-message.js';
+import type { CreateMatchRequest, GameCommand, GameState, JoinMatchRequest, SpectateMatchRequest } from '../generated/index.js';
+import type { MatchAccess, MatchReference, MatchSpectatorAccess } from '../resources/matches.js';
+import type { MatchSessionAccess, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionSnapshotPredicate, MatchSessionWaitOptions } from './session-state.js';
+import type { MatchSession } from './types.js';
+/** Stateful actions exposed by one SDK-owned match session. */
+export interface MatchSessionMethods {
+    /**
+     * Opens a socket using existing or supplied private access.
+     *
+     * Call this after seeding access from `matches.create()`, `matches.join()`,
+     * `matches.spectate()`, `createMatch()`, `joinMatch()`, or `spectateMatch()`.
+     * Resolves after welcome and snapshot.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * async function resumeMatch(matchSession: MatchSession) {
+     *   await matchSession.connect({
+     *     matchId: 'match_123',
+     *     seatToken: 'seat_token_123',
+     *   })
+     * }
+     *
+     * console.log(resumeMatch)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-session#lifecycle
+     */
+    connect(access?: MatchSessionAccess, options?: MatchSessionConnectOptions): Promise<MatchSession>;
+    /**
+     * Creates a host match, stores private access, and connects.
+     *
+     * Use this when one UI action should create a match and start live state.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * const premierHostDeck = {
+     *   leader: 46102,
+     *   leaders: [],
+     *   base: 308,
+     *   cards: Array.from({ length: 50 }, () => 45),
+     *   sideboard: [],
+     * }
+     *
+     * async function hostPremier(matchSession: MatchSession) {
+     *   return matchSession.createMatch({
+     *     format: 'premier',
+     *     playerCount: 2,
+     *     hostDeck: premierHostDeck,
+     *     hostName: 'Host',
+     *     hostAuthenticated: false,
+     *     historyIdentities: [],
+     *     aiOpponents: [],
+     *   })
+     * }
+     *
+     * console.log(hostPremier)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-lifecycle#create
+     */
+    createMatch(request: CreateMatchRequest, options?: MatchSessionConnectOptions): Promise<MatchAccess>;
+    /**
+     * Joins a match, stores private access, and connects.
+     *
+     * Use this for guest tabs or players entering through a shared match id.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * const premierGuestDeck = {
+     *   leader: 46107,
+     *   leaders: [],
+     *   base: 309,
+     *   cards: Array.from({ length: 50 }, () => 35),
+     *   sideboard: [],
+     * }
+     *
+     * async function joinPremier(matchSession: MatchSession) {
+     *   return matchSession.joinMatch('match_123', {
+     *     deck: premierGuestDeck,
+     *     name: 'Guest',
+     *     authenticated: false,
+     *     historyIdentities: [],
+     *   })
+     * }
+     *
+     * console.log(joinPremier)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-lifecycle#join
+     */
+    joinMatch(match: string | MatchReference, request: JoinMatchRequest, options?: MatchSessionConnectOptions): Promise<MatchAccess>;
+    /**
+     * Spectates a match, stores private read-only access, and connects.
+     *
+     * Use this for viewers entering through a shared match id without taking a
+     * player seat.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * async function spectatePremier(matchSession: MatchSession) {
+     *   return matchSession.spectateMatch('match_123', {
+     *     name: 'Spectator',
+     *     authenticated: false,
+     *   })
+     * }
+     *
+     * console.log(spectatePremier)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-lifecycle#spectate
+     */
+    spectateMatch(match: string | MatchReference, request: SpectateMatchRequest, options?: MatchSessionConnectOptions): Promise<MatchSpectatorAccess>;
+    /**
+     * Closes the active socket.
+     *
+     * Listeners stay registered, and stored access remains available for
+     * `reconnect()`.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function leaveView(matchSession: MatchSession) {
+     *   matchSession.close()
+     * }
+     *
+     * console.log(leaveView)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-session#close
+     */
+    close(): void;
+    /**
+     * Reopens the socket using the stored private access.
+     *
+     * Closes the old socket, opens a new one, waits for handshake, then syncs.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * async function restoreSocket(matchSession: MatchSession) {
+     *   await matchSession.reconnect({ handshakeTimeoutMs: 10_000 })
+     * }
+     *
+     * console.log(restoreSocket)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/reconnect
+     */
+    reconnect(options?: MatchSessionConnectOptions): Promise<MatchSession>;
+    /**
+     * Sends one ready message for the current seat.
+     *
+     * Use this in lobby and setup phases when a seat must acknowledge readiness.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function markSeatReady(matchSession: MatchSession) {
+     *   matchSession.ready()
+     * }
+     *
+     * console.log(markSeatReady)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay#ready-and-setup
+     */
+    ready(): void;
+    /**
+     * Requests rollback of the latest accepted player action.
+     *
+     * Any valid seat token may send undo. When the undo needs no approval, the
+     * server restores the previous snapshot and emits one or more `undoApplied`
+     * events. In matches with other human seats, a sensitive undo (hidden
+     * information was revealed, or another player acted since) is recorded on
+     * `GameState.pendingUndo` with an `undoRequested` event instead, and only
+     * applies once every other human seat approves via {@link respondUndo}. In
+     * AI matches, one human undo also consumes any AI responses that happened
+     * after that human action, pauses the AI, then automatically resumes it
+     * after the next successful human mutation.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function undoLastAction(matchSession: MatchSession) {
+     *   matchSession.undo()
+     * }
+     *
+     * console.log(undoLastAction)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay
+     */
+    undo(): void;
+    /**
+     * Answers the pending undo approval request.
+     *
+     * Approving as the last outstanding seat applies the undo; declining
+     * cancels it (`undoDeclined`). A response sent by the original requester
+     * withdraws the request regardless of `approve` (`undoCancelled`).
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function approvePendingUndo(matchSession: MatchSession) {
+     *   matchSession.respondUndo(true)
+     * }
+     *
+     * console.log(approvePendingUndo)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay
+     */
+    respondUndo(approve: boolean): void;
+    /**
+     * Pauses or resumes an attached AI opponent.
+     *
+     * This is session-level manual control only; it does not mutate gameplay
+     * state. Undo-created AI pauses resume automatically after the next
+     * successful human mutation.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function resumeAi(matchSession: MatchSession) {
+     *   matchSession.setAiPaused(false)
+     * }
+     *
+     * console.log(resumeAi)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay
+     */
+    setAiPaused(paused: boolean): void;
+    /**
+     * Sends one request for the latest server snapshot.
+     *
+     * Use after reconnects, tab restores, or missed UI updates.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function requestFreshState(matchSession: MatchSession) {
+     *   matchSession.sync()
+     * }
+     *
+     * console.log(requestFreshState)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/websocket#sync-request
+     */
+    sync(): void;
+    /**
+     * Sends one ping frame with an optional nonce echoed by `pong`.
+     *
+     * Use the nonce to match a pong to one latency measurement.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function measureLatency(matchSession: MatchSession) {
+     *   matchSession.ping('latency-check-1')
+     * }
+     *
+     * console.log(measureLatency)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/websocket#ping
+     */
+    ping(nonce?: string | null): void;
+    /**
+     * Sends one typed gameplay command for the current prompt.
+     *
+     * Invalid command shapes fail SDK validation before a socket frame is sent.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function passAction(matchSession: MatchSession) {
+     *   matchSession.sendCommand('pass')
+     * }
+     *
+     * console.log(passAction)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay
+     */
+    sendCommand(command: GameCommand): void;
+    /**
+     * Sends one typed out-of-game format command for series flows.
+     *
+     * Use for match-series actions such as readying for the next game.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function readyForSeriesGame(matchSession: MatchSession) {
+     *   matchSession.sendFormatEvent({ type: 'readyNextGame' })
+     * }
+     *
+     * console.log(readyForSeriesGame)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay#out-of-game-commands
+     */
+    sendFormatEvent(command: FormatEventCommand): void;
+    /**
+     * Sends one host-authorized AI Trilogy format command.
+     *
+     * Use this only for manual Player vs AI Trilogy ban/pick flows. The server
+     * applies accepted commands to the AI seat after validating the sender.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function chooseAiBan(matchSession: MatchSession) {
+     *   matchSession.sendAiFormatEvent({ type: 'banTrilogyDeck', deckIndex: 1 })
+     * }
+     *
+     * console.log(chooseAiBan)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/driving-gameplay#out-of-game-commands
+     */
+    sendAiFormatEvent(command: FormatEventCommand): void;
+    /**
+     * Sends one in-match chat message.
+     *
+     * The server trims and caps the message, then broadcasts it as a match
+     * history entry to connected seats.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function chat(matchSession: MatchSession) {
+     *   matchSession.sendChat('ready?')
+     * }
+     *
+     * console.log(chat)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/websocket
+     */
+    sendChat(message: string): void;
+    /**
+     * Sends one transient hand-card interaction cue.
+     *
+     * Use this for live hover/drag presentation. The server broadcasts it to
+     * connected viewers without changing authoritative gameplay state.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function showRemoteHover(matchSession: MatchSession) {
+     *   matchSession.sendInteractionCue({
+     *     kind: 'handCard',
+     *     index: 0,
+     *     state: 'hover',
+     *   })
+     * }
+     *
+     * console.log(showRemoteHover)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/websocket
+     */
+    sendInteractionCue(cue: CardInteractionCueRequest): void;
+    /**
+     * Registers one typed event listener and returns an unsubscribe function.
+     *
+     * Event listeners stay registered across reconnects. Unsubscribe on unmount.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * function watchState(matchSession: MatchSession) {
+     *   return matchSession.on('snapshot', actionSnapshot => {
+     *     console.log(actionSnapshot.phase)
+     *   })
+     * }
+     *
+     * console.log(watchState)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-session#events
+     */
+    on<TKey extends keyof MatchSessionEvents>(event: TKey, listener: (value: MatchSessionEvents[TKey]) => void): () => void;
+    /**
+     * Resolves with the current or next matching snapshot.
+     *
+     * Checks current state first, then waits for future snapshots until timeout.
+     *
+     * @example
+     * ```ts
+     * import type { MatchSession } from '@my-swu/simulator-client'
+     *
+     * async function waitForAction(matchSession: MatchSession) {
+     *   return matchSession.waitForSnapshot(
+     *     matchSnapshot => matchSnapshot.phase === 'action',
+     *     { timeoutMs: 5_000 },
+     *   )
+     * }
+     *
+     * console.log(waitForAction)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/match-session#waiting
+     */
+    waitForSnapshot(predicate?: MatchSessionSnapshotPredicate, options?: MatchSessionWaitOptions): Promise<GameState>;
+}

package/dist/match-session/methods.js

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

package/dist/match-session/session-state.d.ts

@@ -0,0 +1,235 @@
+import type { AiStatusPayload, ErrorPayload, GameEvent, GameState, ServerMessage, WelcomePayload } from '../generated/index.js';
+import type { Seat } from '../generated/types/create-match-request.js';
+import type { CardInteractionCue, MatchHistoryFeedEntry, MatchHistorySnapshot } from '../generated/types/server-message.js';
+import type { MatchAccess, MatchConnectionAccessInput, MatchSpectatorAccess } from '../resources/matches.js';
+import type { ConnectionState, PongPayload } from '../session.js';
+/**
+ * Seat identifier exposed by live match session state.
+ *
+ * Values identify the player seat controlled by this session, not an auth
+ * credential.
+ *
+ * @example
+ * ```ts
+ * import type { MatchSeat } from '@my-swu/simulator-client'
+ *
+ * const activeSeat: MatchSeat = 'one'
+ * console.log(activeSeat)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session
+ */
+export type MatchSeat = Seat;
+/**
+ * Access shape accepted by a match session.
+ *
+ * Full `MatchAccess` responses can seed snapshot and seat state immediately.
+ * Minimal `MatchAccessInput` values are enough to connect or reconnect.
+ *
+ * @example
+ * ```ts
+ * import type { MatchSessionAccess } from '@my-swu/simulator-client'
+ *
+ * const reconnectAccess: MatchSessionAccess = {
+ *   matchId: 'match_123',
+ *   seatToken: 'seat_token_123',
+ * }
+ *
+ * console.log(reconnectAccess.matchId)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/reconnect
+ */
+export type MatchSessionAccess = MatchAccess | MatchSpectatorAccess | MatchConnectionAccessInput;
+/**
+ * Predicate used by `waitForSnapshot`.
+ *
+ * Return `true` when the current or next snapshot is acceptable for the caller.
+ *
+ * @example
+ * ```ts
+ * import type { MatchSessionSnapshotPredicate } from '@my-swu/simulator-client'
+ *
+ * const waitsForAction: MatchSessionSnapshotPredicate =
+ *   matchSnapshot => matchSnapshot.phase === 'action'
+ *
+ * console.log(waitsForAction)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session#waiting
+ */
+export type MatchSessionSnapshotPredicate = (snapshot: GameState) => boolean;
+/**
+ * Options for waiting on session snapshots.
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session#waiting
+ */
+export interface MatchSessionWaitOptions {
+    /** Milliseconds to wait before rejecting. */
+    timeoutMs?: number | undefined;
+}
+/**
+ * Options for opening or reopening one match session socket.
+ *
+ * @example
+ * ```ts
+ * import type { MatchSessionConnectOptions } from '@my-swu/simulator-client'
+ *
+ * const connectOptions: MatchSessionConnectOptions = {
+ *   handshakeTimeoutMs: 10_000,
+ * }
+ *
+ * console.log(connectOptions.handshakeTimeoutMs)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/reconnect
+ */
+export interface MatchSessionConnectOptions {
+    /** Milliseconds to wait for welcome plus first snapshot. */
+    handshakeTimeoutMs?: number | undefined;
+}
+/**
+ * Automatic reconnect policy for abnormal match socket closes.
+ */
+export interface MatchSessionAutoReconnectPolicy {
+    /** Maximum reconnect attempts before emitting an SDK error. */
+    maxRetries?: number | undefined;
+    /** Delay before the first retry in milliseconds. */
+    initialDelayMs?: number | undefined;
+    /** Maximum backoff delay in milliseconds. */
+    maxDelayMs?: number | undefined;
+    /** Multiplier applied to each subsequent delay. */
+    backoffFactor?: number | undefined;
+}
+/**
+ * Automatic reconnect setting for one match session.
+ */
+export type MatchSessionAutoReconnectOptions = boolean | MatchSessionAutoReconnectPolicy;
+/** Progress of automatic recovery after an abnormal match socket close. */
+export type MatchSessionReconnectState = {
+    phase: 'idle';
+} | {
+    phase: 'waiting';
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+} | {
+    phase: 'connecting';
+    attempt: number;
+    maxAttempts: number;
+} | {
+    phase: 'exhausted';
+    attempts: number;
+    maxAttempts: number;
+};
+/**
+ * Options for creating one SDK-owned match session.
+ *
+ * These options configure session-owned state, event retention, and default
+ * socket handshake behavior.
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session
+ */
+export interface MatchSessionOptions extends MatchSessionConnectOptions {
+    /** Opt-in automatic reconnect policy for abnormal socket closes. */
+    autoReconnect?: MatchSessionAutoReconnectOptions | undefined;
+    /** Maximum number of recent game events retained by the session. */
+    maxEventHistory?: number | undefined;
+    /** Maximum number of recent errors retained by the session. */
+    maxErrorHistory?: number | undefined;
+}
+/**
+ * Public, token-free state snapshot for one match session.
+ *
+ * This state can be stored in UI state managers because it intentionally omits
+ * the private `seatToken`.
+ *
+ * @example
+ * ```ts
+ * import type { MatchSessionState } from '@my-swu/simulator-client'
+ *
+ * const idleState: MatchSessionState = {
+ *   connectionState: 'idle',
+ *   errors: [],
+ *   events: [],
+ *   history: [],
+ *   errorMessages: [],
+ * }
+ *
+ * console.log(idleState.connectionState)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session
+ */
+export interface MatchSessionState {
+    /** Latest AI attachment/pause status announced by the server. */
+    aiStatus?: AiStatusPayload | undefined;
+    /** Current transport state. */
+    connectionState: ConnectionState;
+    /** Recent engine or SDK errors. */
+    errors: readonly ErrorPayload[];
+    /** Recent game events, trimmed to the configured history limit. */
+    events: readonly GameEvent[];
+    /** Recent match history entries supplied by the server. */
+    history: readonly MatchHistoryFeedEntry[];
+    /** Human-readable error summaries. */
+    errorMessages: readonly string[];
+    /** Public match id when one is known. */
+    matchId?: string | undefined;
+    /** Automatic reconnect progress, when recovering from an abnormal close. */
+    reconnectState?: MatchSessionReconnectState | undefined;
+    /** Latest authoritative private snapshot for this seat. */
+    snapshot?: GameState | undefined;
+    /** Seat controlled by this session when known. */
+    seat?: MatchSeat | undefined;
+    /** Latest welcome payload when the socket handshake has completed. */
+    welcome?: WelcomePayload | undefined;
+}
+/**
+ * Typed event map emitted by `MatchSession`.
+ *
+ * Register listeners through `matchSession.on()`. Each listener returns an
+ * unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * import type { GameState, MatchSessionEvents } from '@my-swu/simulator-client'
+ *
+ * const renderSnapshot = (matchSnapshot: GameState) => {
+ *   console.log(matchSnapshot.phase)
+ * }
+ * const snapshotEventName: keyof MatchSessionEvents = 'snapshot'
+ *
+ * console.log(snapshotEventName, renderSnapshot)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/match-session#events
+ */
+export interface MatchSessionEvents {
+    /** Emitted when the server reports AI attachment or pause status. */
+    aiStatus: AiStatusPayload;
+    /** Emitted after any public session state changes. */
+    change: MatchSessionState;
+    /** Emitted when the transport state changes. */
+    connectionState: ConnectionState;
+    /** Emitted when an engine or SDK error is recorded. */
+    error: ErrorPayload;
+    /** Emitted for each live game event. */
+    event: GameEvent;
+    /** Emitted for each transient hand-card interaction cue. */
+    interactionCue: CardInteractionCue;
+    /** Emitted when the server sends a full recent match-history snapshot. */
+    historySnapshot: MatchHistorySnapshot;
+    /** Emitted when the server sends one new match-history entry. */
+    historyEntry: MatchHistoryFeedEntry;
+    /** Emitted for every decoded server message. */
+    message: ServerMessage;
+    /** Emitted for each socket pong. */
+    pong: PongPayload;
+    /** Emitted when automatic reconnect progress changes. */
+    reconnectState: MatchSessionReconnectState;
+    /** Emitted when a new authoritative snapshot arrives. */
+    snapshot: GameState;
+    /** Emitted when the socket welcome payload arrives. */
+    welcome: WelcomePayload;
+}

package/dist/match-session/session-state.js

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