@my-swu/simulator-client 0.1.0 → 0.1.2

package/dist/match-session/controller.js

@@ -1,7 +1,9 @@
 import { MatchConnection } from '../connection.js';
 import { TypedEmitter } from '../internal/emitter.js';
+import { formatErrorMessages } from '../internal/errors.js';
 import { DEFAULT_ERROR_HISTORY_LIMIT, DEFAULT_MATCH_HISTORY_LIMIT } from '../internal/limits.js';
 import { nonNegativeNumber, normalizeReconnectBackoff, reconnectDelayMs, } from '../internal/reconnect-backoff.js';
+import { createMatchSessionHeartbeat } from './heartbeat.js';
 import { hasAccessSnapshot, matchReferenceFrom } from './access.js';
 import { errorPayloadFromUnknown } from './errors.js';
 const DEFAULT_EVENT_HISTORY_LIMIT = 50;
@@ -9,6 +11,8 @@ const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
 const DEFAULT_RECONNECT_MAX_DELAY_MS = 5_000;
 const DEFAULT_RECONNECT_MAX_RETRIES = 5;
 const DEFAULT_RECONNECT_BACKOFF_FACTOR = 2;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000;
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 10_000;
 /** SDK-owned live match session implementation. */
 export class MatchSessionController {
     /**
@@ -25,6 +29,7 @@ export class MatchSessionController {
     #matches;
     #openConnection;
     #autoReconnect;
+    #heartbeat;
     #access;
     #connection;
     #connectionState = 'idle';
@@ -49,6 +54,13 @@ export class MatchSessionController {
             ...(options.options?.handshakeTimeoutMs == null ? {} : { handshakeTimeoutMs: options.options.handshakeTimeoutMs }),
         };
         this.#autoReconnect = normalizeAutoReconnect(options.options?.autoReconnect);
+        if (this.#autoReconnect.heartbeat != null) {
+            this.#heartbeat = createMatchSessionHeartbeat({
+                config: this.#autoReconnect.heartbeat,
+                sendPing: nonce => this.#heartbeatPing(nonce),
+                onTimeout: () => this.#heartbeatTimedOut(),
+            });
+        }
         this.#maxEventHistory = options.options?.maxEventHistory ?? DEFAULT_EVENT_HISTORY_LIMIT;
         this.#maxErrorHistory = options.options?.maxErrorHistory ?? DEFAULT_ERROR_HISTORY_LIMIT;
         if (options.access != null) {
@@ -71,7 +83,7 @@ export class MatchSessionController {
         return [...this.#history];
     }
     get errorMessages() {
-        return this.#errors.map(error => `${error.code} - ${error.message}`);
+        return formatErrorMessages(this.#errors);
     }
     get matchId() {
         return this.#matchId;
@@ -257,7 +269,10 @@ export class MatchSessionController {
             connection.on('aiStatus', status => this.#setAiStatus(status)),
             connection.on('error', error => this.#recordError(error)),
             connection.on('message', message => this.#emitter.emit('message', message)),
-            connection.on('pong', pong => this.#emitter.emit('pong', pong)),
+            connection.on('pong', pong => {
+                this.#heartbeat?.acknowledge(pong.nonce);
+                this.#emitter.emit('pong', pong);
+            }),
         ];
     }
     #detachActiveConnection() {
@@ -272,6 +287,21 @@ export class MatchSessionController {
         this.#connection = undefined;
         activeConnection?.close();
     }
+    /** Send one watchdog ping through the current live raw connection. */
+    #heartbeatPing(nonce) {
+        const connection = this.#connection;
+        if (connection == null || connection.connectionState !== 'open') {
+            throw new Error('match connection is not open');
+        }
+        connection.ping(nonce);
+    }
+    /** Close a silent socket so its existing abnormal-close recovery takes over. */
+    #heartbeatTimedOut() {
+        if (this.#connectionState !== 'open') {
+            return;
+        }
+        this.#connection?.close();
+    }
     #cancelAutoReconnect() {
         this.#reconnectGeneration += 1;
         if (this.#reconnectTimer != null) {
@@ -430,6 +460,12 @@ export class MatchSessionController {
             return;
         }
         this.#connectionState = state;
+        if (state === 'open') {
+            this.#heartbeat?.start();
+        }
+        else {
+            this.#heartbeat?.stop();
+        }
         this.#emitter.emit('connectionState', state);
         this.#emitChange();
     }
@@ -486,9 +522,24 @@ function normalizeAutoReconnect(options) {
     const optionPolicy = options === true || options === false || options == null ? {} : options;
     return {
         ...policy,
+        heartbeat: policy.enabled ? normalizeHeartbeat(optionPolicy.heartbeat) : undefined,
         maxRetries: Math.max(0, Math.floor(nonNegativeNumber(optionPolicy.maxRetries, DEFAULT_RECONNECT_MAX_RETRIES))),
     };
 }
+/** Normalize an enabled heartbeat without allowing zero-delay timer loops. */
+function normalizeHeartbeat(options) {
+    if (options === false)
+        return undefined;
+    const policy = options === true || options == null ? {} : options;
+    return {
+        intervalMs: positiveInteger(policy.intervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS),
+        timeoutMs: positiveInteger(policy.timeoutMs, DEFAULT_HEARTBEAT_TIMEOUT_MS),
+    };
+}
+/** Keep timer settings finite and strictly positive after user configuration. */
+function positiveInteger(value, fallback) {
+    return Math.max(1, Math.floor(nonNegativeNumber(value, fallback)));
+}
 function sameReconnectState(left, right) {
     if (left.phase !== right.phase) {
         return false;

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

@@ -0,0 +1,33 @@
+/** Normalized timing configuration for one session heartbeat. */
+export interface MatchSessionHeartbeatConfig {
+    /** Delay between a valid pong and the next ping. */
+    intervalMs: number;
+    /** Maximum wait for a pong matching the outstanding ping. */
+    timeoutMs: number;
+}
+/** Dependencies owned by the match-session controller. */
+export interface MatchSessionHeartbeatOptions {
+    /** Normalized timing configuration. */
+    config: MatchSessionHeartbeatConfig;
+    /** Sends a transport ping carrying the supplied nonce. */
+    sendPing: (nonce: string) => void;
+    /** Replaces the active connection after a matching pong never arrives. */
+    onTimeout: () => void;
+}
+/** Small liveness timer for one already-open match socket. */
+export interface MatchSessionHeartbeat {
+    /** Starts a new heartbeat generation. */
+    start: () => void;
+    /** Cancels all timers and ignores late callbacks from this generation. */
+    stop: () => void;
+    /** Accepts the pong only when it acknowledges the active ping. */
+    acknowledge: (nonce: string | null | undefined) => void;
+}
+/**
+ * Create a ping/pong watchdog for a match session.
+ *
+ * One nonce is outstanding at most once. Every start and stop increments a
+ * generation, preventing a timer from a replaced socket from closing its
+ * successor.
+ */
+export declare function createMatchSessionHeartbeat(options: MatchSessionHeartbeatOptions): MatchSessionHeartbeat;

package/dist/match-session/heartbeat.js

@@ -0,0 +1,70 @@
+/**
+ * Create a ping/pong watchdog for a match session.
+ *
+ * One nonce is outstanding at most once. Every start and stop increments a
+ * generation, preventing a timer from a replaced socket from closing its
+ * successor.
+ */
+export function createMatchSessionHeartbeat(options) {
+    let generation = 0;
+    let nonceIndex = 0;
+    let pendingNonce;
+    let pingTimer;
+    let timeoutTimer;
+    function clearTimers() {
+        if (pingTimer !== undefined)
+            clearTimeout(pingTimer);
+        if (timeoutTimer !== undefined)
+            clearTimeout(timeoutTimer);
+        pingTimer = undefined;
+        timeoutTimer = undefined;
+    }
+    function schedulePing(expectedGeneration) {
+        pingTimer = setTimeout(() => {
+            pingTimer = undefined;
+            if (expectedGeneration !== generation)
+                return;
+            const nonce = `match-session-heartbeat:${++nonceIndex}`;
+            pendingNonce = nonce;
+            timeoutTimer = setTimeout(() => {
+                timeoutTimer = undefined;
+                if (expectedGeneration !== generation || pendingNonce !== nonce)
+                    return;
+                pendingNonce = undefined;
+                options.onTimeout();
+            }, options.config.timeoutMs);
+            try {
+                options.sendPing(nonce);
+            }
+            catch {
+                if (expectedGeneration !== generation || pendingNonce !== nonce)
+                    return;
+                clearTimeout(timeoutTimer);
+                timeoutTimer = undefined;
+                pendingNonce = undefined;
+                options.onTimeout();
+            }
+        }, options.config.intervalMs);
+    }
+    function stop() {
+        generation += 1;
+        pendingNonce = undefined;
+        clearTimers();
+    }
+    return {
+        start: () => {
+            stop();
+            schedulePing(generation);
+        },
+        stop,
+        acknowledge: (nonce) => {
+            if (nonce == null || nonce !== pendingNonce)
+                return;
+            pendingNonce = undefined;
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+            timeoutTimer = undefined;
+            schedulePing(generation);
+        },
+    };
+}

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

@@ -100,11 +100,25 @@ export interface MatchSessionAutoReconnectPolicy {
     maxDelayMs?: number | undefined;
     /** Multiplier applied to each subsequent delay. */
     backoffFactor?: number | undefined;
+    /**
+     * Detect sockets that remain reported as open after their transport path
+     * stops delivering server messages. Enabled by default with auto-reconnect.
+     */
+    heartbeat?: MatchSessionHeartbeatOptions | undefined;
 }
 /**
  * Automatic reconnect setting for one match session.
  */
 export type MatchSessionAutoReconnectOptions = boolean | MatchSessionAutoReconnectPolicy;
+/** Settings for the ping/pong liveness check owned by an auto-reconnecting session. */
+export interface MatchSessionHeartbeatPolicy {
+    /** Delay between a successful pong and the next liveness ping. */
+    intervalMs?: number | undefined;
+    /** Maximum time to wait for the matching pong before reconnecting. */
+    timeoutMs?: number | undefined;
+}
+/** Enable, disable, or configure session heartbeat detection. */
+export type MatchSessionHeartbeatOptions = boolean | MatchSessionHeartbeatPolicy;
 /** Progress of automatic recovery after an abnormal match socket close. */
 export type MatchSessionReconnectState = {
     phase: 'idle';

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

@@ -3,7 +3,7 @@ import type { MatchHistoryFeedEntry } from '../generated/types/server-message.js
 import type { ConnectionState } from '../session.js';
 import type { MatchSessionMethods } from './methods.js';
 import type { MatchSeat, MatchSessionReconnectState, MatchSessionState } from './session-state.js';
-export type { MatchSeat, MatchSessionAccess, MatchSessionAutoReconnectOptions, MatchSessionAutoReconnectPolicy, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionOptions, MatchSessionReconnectState, MatchSessionSnapshotPredicate, MatchSessionState, MatchSessionWaitOptions, } from './session-state.js';
+export type { MatchSeat, MatchSessionAccess, MatchSessionAutoReconnectOptions, MatchSessionAutoReconnectPolicy, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionHeartbeatOptions, MatchSessionHeartbeatPolicy, MatchSessionOptions, MatchSessionReconnectState, MatchSessionSnapshotPredicate, MatchSessionState, MatchSessionWaitOptions, } from './session-state.js';
 /**
  * Main ergonomic SDK API for interacting with one live match.
  *

package/dist/match-session.d.ts

@@ -1,3 +1,3 @@
 export { MatchSessionController } from './match-session/controller.js';
 export type { MatchSessionControllerOptions } from './match-session/controller.js';
-export type { MatchSeat, MatchSession, MatchSessionAccess, MatchSessionAutoReconnectOptions, MatchSessionAutoReconnectPolicy, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionOptions, MatchSessionReconnectState, MatchSessionSnapshotPredicate, MatchSessionState, MatchSessionWaitOptions, } from './match-session/types.js';
+export type { MatchSeat, MatchSession, MatchSessionAccess, MatchSessionAutoReconnectOptions, MatchSessionAutoReconnectPolicy, MatchSessionConnectOptions, MatchSessionEvents, MatchSessionHeartbeatOptions, MatchSessionHeartbeatPolicy, MatchSessionOptions, MatchSessionReconnectState, MatchSessionSnapshotPredicate, MatchSessionState, MatchSessionWaitOptions, } from './match-session/types.js';

package/dist/resources/lobby-list-session.js

@@ -1,5 +1,5 @@
 import { TypedEmitter } from '../internal/emitter.js';
-import { SIMULATOR_REJECTION_CLOSE_CODE, simulatorSocketErrorPayload } from '../internal/errors.js';
+import { formatErrorMessages, SIMULATOR_REJECTION_CLOSE_CODE, simulatorSocketErrorPayload, } from '../internal/errors.js';
 import { websocketCloseInfo } from '../internal/websocket-event.js';
 import { decodeSocketFrame } from '../internal/socket-frame.js';
 import { passthroughValidator } from '../validators/validator.js';
@@ -56,7 +56,7 @@ class LobbyListSessionController {
         return this.#connectionState;
     }
     get errorMessages() {
-        return this.#errors.map(error => `${error.code} - ${error.message}`);
+        return formatErrorMessages(this.#errors);
     }
     get errors() {
         return [...this.#errors];

package/dist/resources/tournament-room-types.d.ts

@@ -1,10 +1,10 @@
-import type { CloseTournamentRoomRequest, CreateTournamentRoomRequest, CreateTournamentTableRequest, JoinTournamentRoomRequest, JoinTournamentTableRequest, LeaveTournamentRoomRequest, ReturnTournamentMatchRequest, StartTournamentEventRequest, SubmitTournamentDeckRequest, TournamentEventCommandRequest, TournamentRoomAccessResponse, TournamentRoomChatRequest, TournamentRoomChatResponse, TournamentRoomListResponse, TournamentRoomResponse, TournamentRoomServerMessage, TournamentRoomSyncRequest, UpdateTournamentRoomPlayerRequest, UpdateTournamentRoomSettingsRequest } from '../generated/index.js';
+import type { TournamentRoomServerMessage } from '../generated/index.js';
 import type { PublicTournamentRoomSummary } from '../generated/types/tournament-room-list-response.js';
 import type { TournamentRoomSnapshot } from '../generated/types/tournament-room-response.js';
 import type { ErrorPayload, LobbyChatMessage, TournamentRoomMatchReadyPayload, TournamentRoomWelcomePayload } from '../generated/types/tournament-room-server-message.js';
 import type { ConnectionState } from '../session.js';
 import type { RoomPlayerPresenceEvent } from './lobby-types.js';
-export type { CloseTournamentRoomRequest, CreateTournamentRoomRequest, CreateTournamentTableRequest, JoinTournamentRoomRequest, JoinTournamentTableRequest, LeaveTournamentRoomRequest, ReturnTournamentMatchRequest, StartTournamentEventRequest, SubmitTournamentDeckRequest, TournamentEventCommandRequest, TournamentRoomAccessResponse, TournamentRoomChatRequest, TournamentRoomChatResponse, TournamentRoomListResponse, TournamentRoomResponse, TournamentRoomServerMessage, TournamentRoomSyncRequest, UpdateTournamentRoomPlayerRequest, UpdateTournamentRoomSettingsRequest, };
+export type { CloseTournamentRoomRequest, CreateTournamentRoomRequest, CreateTournamentTableRequest, JoinTournamentRoomRequest, JoinTournamentTableRequest, LeaveTournamentRoomRequest, ReturnTournamentMatchRequest, StartTournamentEventRequest, SubmitTournamentDeckRequest, TournamentEventCommandRequest, TournamentRoomAccessResponse, TournamentRoomChatRequest, TournamentRoomChatResponse, TournamentRoomListResponse, TournamentRoomResponse, TournamentRoomServerMessage, TournamentRoomSyncRequest, UpdateTournamentRoomPlayerRequest, UpdateTournamentRoomSettingsRequest, } from '../generated/index.js';
 export type { PublicTournamentRoomSummary, TournamentRoomSnapshot };
 export type { RoomPlayerPresenceEvent } from './lobby-types.js';
 /** Minimal private tournament room credentials. */

package/dist/types.d.ts

@@ -25,7 +25,7 @@
  * `test/type-smoke.test.ts` enforces.
  */
 export type { AiDifficulty, AiOpponentConfig, AiTrilogyFormatMode, FormatSetupInput, MatchScenarioInput, MctsConfigOverride, } from "./generated/types/create-match-request.js";
-export type { AbilityWindow, ActionAbilitySource, ActionAbilityView, ActiveEffectDescriptionView, ActiveEffectView, AbilityTarget, AttachmentMode, AttackChoiceView, AttackTarget, AvailableAttackView, CapturedUnitView, CaptureOptionsView, CaptureSelection, CardArena, CardChoiceResourcePaymentOptionView, CardInstanceView, ConstructedFormat, CurrentAttackStateView, CurrentAttackView, DeckRegistrationView, DelayedEffectDescriptionView, DelayedEffectTimingView, DelayedEffectView, DistributionAssignment, DistributionDamageKindView, DistributionItemView, DistributionTargetView, DistributionTokenKindView, DynamicPowerLimit, EffectCardScopeView, EffectDurationView, EffectRestrictionView, EffectSourceView, EffectTargetView, ExploitOptionsView, FormatSeatView, GameTimerActiveClockView, GameTimerReserveView, GameTimerStateView, HiddenCardChoiceMode, HiddenZoneKind, InitiativeChoiceReason, InitiativeState, InstructedAttackView, LeaderActionView, LeaderDeployActionView, LeaderDeployCostView, LeaderDeployMode, LeaderDeployThresholdBonus, LeaderStateView, LimitedEventView, MatchEndReason, MatchFormat, MatchPhase, MatchResult, MatchSeriesView, MatchStatus, ModeChoiceView, NamedCardEffectDescriptionView, PendingAbilityAspectChoiceView, PendingAbilityAttackChoiceView, PendingAbilityCardChoiceView, PendingAbilityFamily, PendingAbilityModeChoiceView, PendingAbilityNameChoiceView, PendingAbilityOrderAbilityView, PendingAbilityOrderChoiceView, PendingAbilityOrderGroupView, PendingAbilityView, PendingChoiceView, PendingDistributionView, PendingUndoRequest, PlayActionView, PlayCardSourceView, PlayCardZone, PlayerTargetPattern, PresenceFilter, PromptState, RejectedPlayView, RelationFilter, ResourceCardView, ResourcePaymentOptionView, Seat, SeatDirection, SeatOfferIntent, SeatState, SelectionScope, SeriesEndReason, SeriesGameRecord, SeriesResultView, SharedCounterState, SmuggleActionView, SmuggleKind, TargetGroupPurpose, TargetSelectionGroup, TargetSelectionPlanView, TriggerWindowView, TwinSunsCounter, TwinSunsCountersView, UndoRequestReason, UniquenessFilter, UnitAbilitySuppressionView, UnitExtremum, UnitFilter, UnitStateView, UpgradeStateView, } from "./generated/types/get-match-response.js";
+export type { AbilityWindow, ActionAbilitySource, ActionAbilityView, ActiveEffectDescriptionView, ActiveEffectView, AbilityTarget, AttachmentMode, AttackChoiceView, AttackTarget, AvailableAttackView, CapturedUnitView, CaptureOptionsView, CaptureSelection, CardArena, CardChoiceResourcePaymentOptionView, CardInstanceView, ConstructedFormat, CurrentAttackStateView, CurrentAttackView, DeckRegistrationView, DelayedEffectDescriptionView, DelayedEffectTimingView, DelayedEffectView, DistributionAssignment, DistributionDamageKindView, DistributionItemView, DistributionTargetView, DistributionTokenKindView, DynamicPowerLimit, EffectCardScopeView, EffectDurationView, EffectResolutionDraftStepView, EffectResolutionDraftView, EffectRestrictionView, EffectSourceView, EffectTargetView, ExploitOptionsView, FormatSeatView, GameTimerActiveClockView, GameTimerReserveView, GameTimerStateView, HiddenCardChoiceMode, HiddenZoneKind, InitiativeChoiceReason, InitiativeState, InstructedAttackView, LeaderActionView, LeaderDeployActionView, LeaderDeployCostView, LeaderDeployMode, LeaderDeployThresholdBonus, LeaderStateView, LimitedEventView, MatchEndReason, MatchFormat, MatchPhase, MatchResult, MatchSeriesView, MatchStatus, ModeChoiceView, NamedCardEffectDescriptionView, PendingAbilityAspectChoiceView, PendingAbilityAttackChoiceView, PendingAbilityCardChoiceView, PendingAbilityFamily, PendingAbilityModeChoiceView, PendingAbilityNameChoiceView, PendingAbilityOrderAbilityView, PendingAbilityOrderChoiceView, PendingAbilityOrderGroupView, PendingAbilityView, PendingChoiceView, PendingDistributionView, PendingUndoRequest, PlayActionView, PlayCardSourceView, PlayCardZone, PlayerTargetPattern, PresenceFilter, PromptState, RejectedPlayView, RelationFilter, ResourceCardView, ResourcePaymentOptionView, Seat, SeatDirection, SeatOfferIntent, SeatState, SelectionScope, SeriesEndReason, SeriesGameRecord, SeriesResultView, SharedCounterState, SmuggleActionView, SmuggleKind, TargetGroupPurpose, TargetSelectionGroup, TargetSelectionPlanView, TriggerWindowView, TwinSunsCounter, TwinSunsCountersView, UndoRequestReason, UniquenessFilter, UnitAbilitySuppressionView, UnitExtremum, UnitFilter, UnitStateView, UpgradeStateView, } from "./generated/types/get-match-response.js";
 export type { AspectCount } from "./generated/types/cards-response.js";
 export type { CloseTournamentRoomActiveMatches } from "./generated/types/close-tournament-room-request.js";
 export type { CardDrawSource, TurnPassSource, UnitDefeatCause, } from "./generated/types/game-event.js";

package/dist/validators.d.ts

@@ -138,7 +138,7 @@ export interface SchemaTypeMap {
  * ```ts
  * import { parseSchema } from '@my-swu/simulator-client'
  *
- * const health = parseSchema('health-response', { status: 'ok' })
+ * const health = parseSchema('health-response', { buildSha: 'development', status: 'ok' })
  * console.log(health.status)
  * ```
  *

package/dist/validators.js

@@ -11,7 +11,7 @@ import { hasUnknownDiscriminant, warmDiscriminants } from './validators/discrimi
  * ```ts
  * import { parseSchema } from '@my-swu/simulator-client'
  *
- * const health = parseSchema('health-response', { status: 'ok' })
+ * const health = parseSchema('health-response', { buildSha: 'development', status: 'ok' })
  * console.log(health.status)
  * ```
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@my-swu/simulator-client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Typed TypeScript client for the swu-simulator HTTP and WebSocket engine.",
   "keywords": [
     "swu",