@spacemolt/lib 4.6.0

package/dist/account.d.ts

@@ -0,0 +1,389 @@
+/**
+ * A single authenticated SpaceMolt connection.
+ *
+ * Owns one WebSocket, performs raw-credential auth, and exposes the
+ * query/mutation command API, the local state cache (M2), and the typed push
+ * event system + market/observation subscriptions (M3).
+ *
+ * Auth frames (`registered`, `logged_in`) are handled out-of-band from the
+ * `request_id` correlator: after `register` the `logged_in` frame is an
+ * unsolicited push with no `request_id`, so auth is sequenced by frame type
+ * instead (only one auth exchange is ever in flight on a connection).
+ */
+import { type Commands } from './generated/commands.gen.js';
+import type { AuthCredentials } from './auth/credentials.js';
+import type { SubscribeMarketResponse, SubscribeObservationResponse } from './generated/openapi/types.gen.js';
+import type { NotificationPayloads, TypedNotificationType } from './generated/notifications.gen.js';
+import { ConnectionClosedError } from './errors.js';
+import { type MarketBook } from './state/market.js';
+import { type ObservationView } from './state/observation.js';
+import type { GameState, MutationAck, MutationResult, QueryResult, RawFrame, StateSection, WelcomeFrame } from './protocol.js';
+import { type WebSocketFactory } from './transport/socket.js';
+export type LoggedInPayload = Record<string, unknown>;
+export interface ReconnectOptions {
+    /**
+     * Max reconnect attempts before giving up and emitting `disconnected`.
+     * Default `Infinity` — a real game-server restart is a routine, recurring
+     * event (not an edge case) and can legitimately take several minutes; a
+     * finite default tuned for a brief network blip (the old default was 10,
+     * exhausted in ~3.5 minutes at the default backoff) would abandon the
+     * account mid-restart and require manual intervention to reconnect it.
+     * Backoff still caps at `maxDelayMs` per attempt, so this never busy-loops.
+     * Pass a finite value to restore the old give-up behavior.
+     */
+    maxRetries?: number;
+    /** Base backoff in ms (doubles per attempt). Default 1000. */
+    baseDelayMs?: number;
+    /** Backoff ceiling in ms. Default 30000. */
+    maxDelayMs?: number;
+}
+export interface AccountOptions {
+    /** WebSocket URL of the v2 endpoint. Defaults to the production server. */
+    url?: string;
+    /** Inject a WebSocket implementation (tests, custom runtimes). */
+    webSocketFactory?: WebSocketFactory;
+    /**
+     * After authenticating, issue a `get_status` query to seed the local state
+     * cache with the canonical full state. Default `true`. Disable to avoid the
+     * extra round-trip; the cache then fills from the first mutation delta.
+     */
+    seedState?: boolean;
+    /**
+     * Auto-reconnect + re-auth on an unexpected disconnect. Requires
+     * `credentials`. Off unless enabled. Never reconnects after a deliberate
+     * `close()`, a `session_replaced` (4001), or an `auth_timeout` (4002).
+     */
+    reconnect?: boolean | ReconnectOptions;
+    /**
+     * Supplies credentials for re-auth on reconnect. `login_token` credentials
+     * are single-use and can't reconnect; `clerk` credentials re-mint a fresh
+     * token each time, so they reconnect cleanly.
+     */
+    credentials?: () => AuthCredentials | Promise<AuthCredentials>;
+    /** Inject a `fetch` implementation, used by `clerk` auth (tests, runtimes). */
+    fetchImpl?: typeof fetch;
+    /** Max automatic retries when a command is `rate_limited`. Default 5. */
+    maxRateLimitRetries?: number;
+    /** Stable id this account is managed under (e.g. the credential-store key / username). Exposed as `account.id`. */
+    id?: string;
+    /**
+     * How long to wait for the server's `welcome` frame and for a
+     * `logged_in`/error response to an auth attempt, before giving up. Default
+     * 15000 (15s — see `SpacemoltClientOptions.connectTimeoutMs` for why this
+     * exists).
+     */
+    connectTimeoutMs?: number;
+    /**
+     * How long to wait for a query's response before giving up. Queries
+     * resolve synchronously server-side (no game-tick delay, unlike
+     * mutations) — per the game's own design there's no legitimate reason for
+     * one to take long, so unlike mutations (which can legitimately take
+     * minutes, e.g. a travel/jump's transit time) it's safe to bound these.
+     * Default 15000 (15s).
+     */
+    queryTimeoutMs?: number;
+    /**
+     * How long to wait, after a mutation's pending ack arrives, for its final
+     * `action_result`/`action_error` outcome before giving up, for the two
+     * commands whose transit time is distance-based and can legitimately span
+     * many ticks: `jump` and `travel`. Every other mutation settles on the same
+     * tick it was queued on (per the game's own design — see
+     * `fastMutationTimeoutMs`) and uses that much shorter bound instead.
+     * Without this, a single silently-dropped outcome frame hangs forever AND
+     * wedges every subsequent mutation on this account behind it (mutations
+     * are serialized per account, see `enqueueMutation`). Default 600000 (10
+     * minutes).
+     */
+    mutationTimeoutMs?: number;
+    /**
+     * How long to wait, after a mutation's pending ack arrives, for its final
+     * outcome — for every mutation except `jump`/`travel` (see
+     * `mutationTimeoutMs`). These settle within the same tick they were queued
+     * on, so there's no legitimate reason for one to take anywhere near as long
+     * as a transit; bounding them tightly turns a dropped outcome frame into a
+     * fast, visible failure instead of a many-minute stall each retry cycle.
+     * Kept well above one tick (default 180000 — 3 minutes, ~18 ticks at the
+     * game's 10s tick rate) so a merely-slow tick or a `rate_limited` resend
+     * can't trip it. Default 180000 (3 minutes).
+     */
+    fastMutationTimeoutMs?: number;
+}
+export interface RegisterParams {
+    username: string;
+    empire: string;
+    registration_code?: string;
+}
+export interface RegisterResult {
+    /** 256-bit hex credential — store it; it cannot be recovered. */
+    password: string;
+    player_id: string;
+    /** Full initial game state from the following `logged_in` frame. */
+    state: LoggedInPayload;
+}
+export declare class Account {
+    private socket;
+    private readonly correlator;
+    private readonly cache;
+    private readonly emitter;
+    private readonly marketCache;
+    private readonly observationCache;
+    private readonly seedState;
+    private readonly url;
+    private readonly webSocketFactory?;
+    private readonly reconnectConfig;
+    private readonly credentialsProvider?;
+    private readonly fetchImpl?;
+    private readonly maxRateLimitRetries;
+    private readonly connectTimeoutMs;
+    private readonly queryTimeoutMs;
+    private readonly mutationTimeoutMs;
+    private readonly fastMutationTimeoutMs;
+    private readonly _id;
+    private requestSeq;
+    private _welcome;
+    private _authenticated;
+    private _loginPayload;
+    private _commands;
+    private welcomeWaiter;
+    private pendingAuth;
+    private stateListener;
+    private userClosing;
+    private reconnecting;
+    private mutationLane;
+    private marketSubscribedState;
+    private subscribedMarketBaseId;
+    private observationSubscribedState;
+    private observationActiveScanState;
+    private subscribedObservationPoiId;
+    private reconnectedListener;
+    private reconnectingListener;
+    private disconnectedListener;
+    constructor(opts?: AccountOptions);
+    private makeSocket;
+    /** Live view of the cached game state. Treat as read-only. */
+    get state(): Readonly<GameState>;
+    /** The id this account is managed under (store key / username), if any. */
+    get id(): string | undefined;
+    get player(): GameState['player'];
+    get ship(): GameState['ship'];
+    get location(): GameState['location'];
+    get cargo(): GameState['cargo'];
+    get skills(): GameState['skills'];
+    get credits(): number | undefined;
+    /** True when a tick-deferred action is queued for this account. */
+    get hasPendingAction(): boolean;
+    /** The raw `logged_in` payload from the last successful auth (login extras). */
+    get loginPayload(): LoggedInPayload | null;
+    /**
+     * Typed, generated command facade grouped by tool:
+     * `account.commands.spacemolt.jump({ id: 'sol' })`,
+     * `account.commands.spacemolt_market.view_market({ item_id: 'iron_ore' })`.
+     * Each method dispatches through `send`, so pacing and the state cache apply.
+     */
+    get commands(): Commands;
+    /** The server's `welcome` payload, available after `connect()` resolves. */
+    get welcome(): WelcomeFrame['payload'] | null;
+    get authenticated(): boolean;
+    /**
+     * Whether `subscribeMarket()` is currently active on this instance —
+     * `resubscribe()` reads this directly to restore the subscription across a
+     * reconnect (this account's own `reconnectLoop`, or `reconnectOnce()`
+     * called by `SpacemoltClient` for a client-managed account).
+     */
+    get marketSubscribed(): boolean;
+    /** Whether `subscribeObservation()` is currently active — see `marketSubscribed`. */
+    get observationSubscribed(): boolean;
+    /** The `activeScan` flag passed to the active `subscribeObservation()` call, if any — see `marketSubscribed`. */
+    get observationActiveScan(): boolean;
+    /** Open the connection and resolve once the `welcome` frame arrives. */
+    connect(): Promise<WelcomeFrame['payload']>;
+    private open;
+    /** Register a new account; resolves with the generated credentials + state. */
+    register(params: RegisterParams): Promise<RegisterResult>;
+    /** Authenticate an existing account with username + password. */
+    login(params: {
+        username: string;
+        password: string;
+    }): Promise<LoggedInPayload>;
+    /** Authenticate with a short-lived single-use token (web/Clerk path). */
+    loginToken(token: string): Promise<LoggedInPayload>;
+    /**
+     * Authenticate from a stored `AuthCredentials` (dispatches by kind).
+     * Auto-retries on `rate_limited` (waiting the server's interval) — for
+     * `clerk` credentials each retry mints a fresh ws-token, so a transient
+     * rejection doesn't waste a single-use token.
+     */
+    authenticate(creds: AuthCredentials): Promise<void>;
+    private authenticateOnce;
+    /**
+     * Re-seed the cache from the canonical full state (`get_status`). Returns the
+     * cached state. Called automatically after auth unless `seedState` is false.
+     */
+    refresh(): Promise<Readonly<GameState>>;
+    /** Register a listener fired with the sections that changed on each update. */
+    onStateChange(listener: (changed: StateSection[]) => void): void;
+    /** Log out, releasing the connection's authenticated session. */
+    logout(): Promise<void>;
+    /**
+     * Run a read-only command; resolves synchronously with the result.
+     * Auto-retries on `rate_limited` (waiting the server's interval). Bounded
+     * by `queryTimeoutMs` — unlike a mutation, a query has no legitimate reason
+     * to take long, so a response that never arrives (the server silently
+     * drops it rather than erroring) fails cleanly instead of hanging forever.
+     */
+    query(tool: string, action: string, payload?: Record<string, unknown>): Promise<QueryResult>;
+    /**
+     * Run a mutation; resolves when the action executes on a later tick (after
+     * the immediate pending ack). `onAck` fires when the pending ack arrives.
+     *
+     * Mutations are serialized per account — the next is sent only after the
+     * previous resolves — because the server queues one action per tick and
+     * rejects a concurrent mutation with `action_pending`. Also auto-retries on
+     * `rate_limited`.
+     *
+     * Bounded in two phases (see `awaitMutationWithTimeout`) rather than left
+     * unbounded: a dropped outcome frame should fail cleanly, not hang this
+     * call (and every mutation queued behind it on this account) forever. Only
+     * `jump`/`travel` (`TRANSIT_ACTIONS`) get the generous `mutationTimeoutMs`;
+     * every other mutation — `mine`, `craft`, etc. — settles within the tick it
+     * was queued on and gets the much shorter `fastMutationTimeoutMs`.
+     */
+    mutate(tool: string, action: string, payload?: Record<string, unknown>, onAck?: (ack: MutationAck) => void): Promise<MutationResult>;
+    /**
+     * Waits for a mutation's outcome with two-phase timeout protection. The
+     * pending ack (`result` frame) is a synchronous validation step with no
+     * game-tick delay — like a query, there's no legitimate reason for it to be
+     * missing, so it's bounded by `queryTimeoutMs`. Once the ack arrives, the
+     * final `action_result`/`action_error` can legitimately take many ticks for
+     * a transit mutation, so that phase gets the caller-supplied
+     * `mutationTimeoutMs` (either the long transit bound or the short
+     * same-tick bound — see `mutate`) instead. Either phase timing out cancels
+     * the correlator entry — otherwise a truly-dropped response would wedge
+     * every later mutation on this account behind it forever (see
+     * `enqueueMutation`).
+     */
+    private awaitMutationWithTimeout;
+    /**
+     * Run a command, dispatching to `query`/`mutate` based on the spec's
+     * `x-is-mutation` classification. Unknown commands are treated as queries.
+     */
+    send(tool: string, action: string, payload?: Record<string, unknown>): Promise<QueryResult | MutationResult>;
+    /**
+     * Listen for a specific server push by msg_type. The handler receives the
+     * typed payload for published notification types, or a loosely-typed object
+     * for not-yet-typed pushes. Returns an unsubscribe function.
+     */
+    on<K extends TypedNotificationType>(type: K, handler: (payload: NotificationPayloads[K]) => void): () => void;
+    on(type: string, handler: (payload: Record<string, unknown>) => void): () => void;
+    /** Listen for every server push frame. Returns an unsubscribe function. */
+    onAny(handler: (frame: RawFrame) => void): () => void;
+    /**
+     * Async-iterate one push msg_type's payloads:
+     * `for await (const msg of account.events('chat_message')) { ... }`.
+     * Buffered, so a slow consumer won't drop frames; `break` unsubscribes.
+     */
+    events<K extends TypedNotificationType>(type: K): AsyncIterableIterator<NotificationPayloads[K]>;
+    events(type: string): AsyncIterableIterator<Record<string, unknown>>;
+    /** Async-iterate every push frame. */
+    anyEvents(): AsyncIterableIterator<RawFrame>;
+    /**
+     * Subscribe to the order book of the station you're docked at. Returns the
+     * baseline snapshot and seeds the market cache; `market_update` pushes are
+     * merged automatically. Read with `account.market(baseId)`.
+     *
+     * The server subscription is scoped to "wherever you're currently docked"
+     * and has no explicit unsubscribe signal when it lapses: it's silently
+     * dropped server-side the instant you undock (`flushMarketSubscriptions`,
+     * `internal/game/market_subscriptions.go`), with no notification telling
+     * the client this happened. `checkSubscriptionsAgainstLocation` below is
+     * the client-side half of that — it watches for the same docked_at change
+     * and drops the stale book proactively, so `market()` can't keep serving a
+     * book the server has already stopped updating.
+     */
+    subscribeMarket(): Promise<SubscribeMarketResponse>;
+    /** Unsubscribe from the current station's market and drop its cached book. */
+    unsubscribeMarket(): Promise<void>;
+    /** The cached order book for a base, if subscribed. */
+    market(baseId: string): MarketBook | undefined;
+    /**
+     * Subscribe to a change-feed of player presence at your current POI/system.
+     * Returns the baseline and seeds the observation cache; `observation_update`
+     * pushes are merged automatically. Read with `account.observation()`. Also
+     * bridges POI-scoped presence into the base state cache's
+     * `location.nearby_players`/`nearby_player_count` (see
+     * `bridgeObservationToLocation`), so `account.state.location` reflects live
+     * data too once subscribed, instead of only refreshing on the next
+     * `get_status`/mutation delta.
+     *
+     * Scoped to your current POI the same way `subscribeMarket` is scoped to
+     * your current dock — see the docked_at note there; the same silent
+     * server-side drop on leaving the POI applies here
+     * (`internal/game/observation_subscriptions.go`), and
+     * `checkSubscriptionsAgainstLocation` guards against it the same way.
+     */
+    subscribeObservation(activeScan?: boolean): Promise<SubscribeObservationResponse>;
+    /** Unsubscribe from the observation watch and clear its cache. */
+    unsubscribeObservation(): Promise<void>;
+    /**
+     * Mirrors the observation watch's POI-scoped player presence into
+     * `location.nearby_players`/`nearby_player_count` in the base state cache,
+     * so code reading `account.state.location` (rather than
+     * `account.observation()`) sees live presence data once subscribed. NPC and
+     * pirate presence (`nearby_empire_npcs`/`nearby_pirates`, their counts, and
+     * `offline_collapsed`) have no equivalent in the observation feed — it only
+     * ever carries player presence — so those fields are left untouched by this
+     * bridge and still only refresh on the next `get_status`/mutation delta.
+     * No-ops if `location` hasn't been seeded yet or nothing is subscribed.
+     */
+    private bridgeObservationToLocation;
+    /** The current observation watch view, if subscribed. */
+    observation(): ObservationView | null;
+    /**
+     * Detects a docked/POI change away from an active market or observation
+     * subscription and proactively drops the now-dead cache entry, mirroring
+     * the server's own silent unsubscribe-on-move (see the notes on
+     * `subscribeMarket`/`subscribeObservation`). Without this, `market()`/
+     * `observation()` would keep serving whatever was last cached — frozen,
+     * with nothing distinguishing it from a genuinely live book — for as long
+     * as nothing else happens to touch that specific base/POI again. Called
+     * after every state update that could carry a `location` change.
+     */
+    private checkSubscriptionsAgainstLocation;
+    /** Close the connection deliberately. Suppresses auto-reconnect. */
+    close(): void;
+    /** Fired after a successful reconnect + re-auth. */
+    onReconnected(listener: () => void): void;
+    /** Fired at the start of each reconnect attempt (1-based). */
+    onReconnecting(listener: (attempt: number) => void): void;
+    /** Fired when the connection is gone for good (non-reconnectable or retries exhausted). */
+    onDisconnected(listener: (err: ConnectionClosedError) => void): void;
+    private authExchange;
+    /** Best-effort seed of the state cache after auth; failures are non-fatal. */
+    private maybeSeedState;
+    private beginAuth;
+    private sendFrame;
+    private nextRequestId;
+    private routeFrame;
+    private handleClose;
+    private shouldReconnect;
+    private reconnectLoop;
+    /**
+     * Reconnect this account's underlying connection in place: a fresh socket,
+     * re-authenticated, subscriptions restored — while preserving this
+     * instance's identity (cache, correlator, every wired listener). A single
+     * attempt with no internal retry/backoff; the caller owns retry pacing
+     * (this account's own `reconnectLoop`, or `SpacemoltClient`'s rate-limited
+     * queue for a client-managed account — see `handleAccountDisconnected`).
+     * Requires `credentials` (constructor option).
+     *
+     * Closes the current socket first — a no-op on the normal disconnect path
+     * (already closed), but avoids orphaning a still-open one if this is ever
+     * called outside that path (e.g. a future forced reconnect while a socket
+     * is technically still alive but not receiving pushes).
+     */
+    reconnectOnce(): Promise<void>;
+    private resubscribe;
+    private withRateLimitRetry;
+    /** Serialize mutations: each runs only after the previous settles. */
+    private enqueueMutation;
+}

package/dist/auth/clerk.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Clerk-backed multi-account source.
+ *
+ * Authenticates with a Clerk **API key** (the headless-client credential —
+ * generate one from the website; see docs/live-testing.md) to enumerate the
+ * player accounts the Clerk user owns and to mint short-lived, single-use
+ * WebSocket login tokens for them. This lets one client manage every account you
+ * own without storing per-account game passwords.
+ *
+ * The API key is sent as `Authorization: Bearer <key>` to two gameserver
+ * endpoints:
+ *   - `GET  /api/registration-code`     → the owned players list.
+ *   - `POST /api/player/{id}/ws-token`  → a single-use WS login token.
+ *
+ * ws-tokens are valid ~5 minutes and consumed on connect, so mint one per
+ * (re)connect rather than caching — the durable credential is the Clerk key.
+ *
+ * Uses only web-standard `fetch`, so it stays browser-safe.
+ */
+/** A player account owned by the authenticated Clerk user. */
+export interface ClerkPlayer {
+    id: string;
+    username: string;
+    empire: string;
+    /** Hidden in the player's dashboard; still connectable. */
+    hidden: boolean;
+}
+export interface ClerkSourceOptions {
+    /** Clerk API key, sent as a Bearer token. Keep it secret. */
+    apiKey: string;
+    /** HTTP origin of the gameserver, e.g. `https://game.spacemolt.com`. */
+    httpBaseUrl: string;
+    /** Inject a `fetch` implementation (tests, custom runtimes). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Mint a single-use WebSocket login token for one owned player. The token is
+ * valid ~5 minutes and consumed on connect, so call this once per (re)connect.
+ */
+export declare function mintWsToken(opts: {
+    httpBaseUrl: string;
+    apiKey: string;
+    playerId: string;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+export declare class ClerkSource {
+    private readonly opts;
+    private readonly fetchImpl;
+    /** HTTP origin of the gameserver (trailing slash stripped). */
+    readonly httpBaseUrl: string;
+    constructor(opts: ClerkSourceOptions);
+    /** The Clerk API key this source authenticates with. */
+    get apiKey(): string;
+    /** List the player accounts the authenticated Clerk user owns. */
+    listPlayers(): Promise<ClerkPlayer[]>;
+    /** Mint a single-use WS login token for one owned player. */
+    mintWsToken(playerId: string): Promise<string>;
+}

package/dist/auth/credentials.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pluggable credential storage for multi-account use.
+ *
+ * The `CredentialStore` interface is the only persistence seam in the library;
+ * swap the implementation to control where credentials live (memory, a file,
+ * the browser, a secrets manager, …). The core never imports Node built-ins —
+ * the file-backed store does, and lives here in `src/auth/` for that reason.
+ */
+/**
+ * How an account authenticates. Raw credentials (login / login_token / register)
+ * plus `clerk`: a Clerk API key + the owned player's id, from which the account
+ * mints a fresh single-use WS token on each (re)connect (see `src/auth/clerk.ts`).
+ */
+export type AuthCredentials = {
+    kind: 'login';
+    username: string;
+    password: string;
+} | {
+    kind: 'login_token';
+    token: string;
+} | {
+    kind: 'clerk';
+    apiKey: string;
+    playerId: string;
+    httpBaseUrl: string;
+} | {
+    kind: 'register';
+    username: string;
+    empire: string;
+    registration_code?: string;
+};
+export interface StoredAccount {
+    /** Stable handle for this account within the client (e.g. the username). */
+    id: string;
+    credentials: AuthCredentials;
+    /** Filled in after a successful auth. */
+    playerId?: string;
+}
+export interface CredentialStore {
+    list(): Promise<StoredAccount[]>;
+    get(id: string): Promise<StoredAccount | undefined>;
+    put(account: StoredAccount): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+/** In-memory store. The default; nothing is persisted across process restarts. */
+export declare class MemoryCredentialStore implements CredentialStore {
+    private readonly accounts;
+    list(): Promise<StoredAccount[]>;
+    get(id: string): Promise<StoredAccount | undefined>;
+    put(account: StoredAccount): Promise<void>;
+    remove(id: string): Promise<void>;
+}

package/dist/auth/file-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * File-backed credential store (Node / Bun).
+ *
+ * Persists accounts as JSON. Credentials are stored in plaintext — the same
+ * tradeoff the CLI makes — so point it at a path your environment protects.
+ * Imports Node built-ins; do not import this from browser bundles (use a
+ * custom `CredentialStore` there instead).
+ */
+import type { CredentialStore, StoredAccount } from './credentials.js';
+export declare class FileCredentialStore implements CredentialStore {
+    private readonly path;
+    private cache;
+    constructor(path: string);
+    private load;
+    private save;
+    list(): Promise<StoredAccount[]>;
+    get(id: string): Promise<StoredAccount | undefined>;
+    put(account: StoredAccount): Promise<void>;
+    remove(id: string): Promise<void>;
+}