@spacemolt/lib 4.6.0

package/dist/node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Node/Bun-only entry point (`@spacemolt/lib/node`).
+ *
+ * Exports the parts of the library that depend on Node built-ins, kept out of
+ * the main entry so `@spacemolt/lib` stays browser-safe. Import from here in
+ * Node/Bun when you want filesystem-backed credential storage.
+ */
+export { FileCredentialStore } from './auth/file-store.js';

package/dist/node.js

@@ -0,0 +1,49 @@
+// src/auth/file-store.ts
+import { readFile, writeFile, rename, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+class FileCredentialStore {
+  path;
+  cache = null;
+  constructor(path) {
+    this.path = path;
+  }
+  async load() {
+    if (this.cache)
+      return this.cache;
+    try {
+      const raw = await readFile(this.path, "utf-8");
+      const parsed = JSON.parse(raw);
+      this.cache = parsed.accounts ?? {};
+    } catch {
+      this.cache = {};
+    }
+    return this.cache;
+  }
+  async save() {
+    const data = { version: 1, accounts: this.cache ?? {} };
+    await mkdir(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp-${process.pid}`;
+    await writeFile(tmp, JSON.stringify(data, null, 2));
+    await rename(tmp, this.path);
+  }
+  async list() {
+    return Object.values(await this.load());
+  }
+  async get(id) {
+    return (await this.load())[id];
+  }
+  async put(account) {
+    const accounts = await this.load();
+    accounts[account.id] = account;
+    await this.save();
+  }
+  async remove(id) {
+    const accounts = await this.load();
+    delete accounts[id];
+    await this.save();
+  }
+}
+export {
+  FileCredentialStore
+};

package/dist/protocol.d.ts

@@ -0,0 +1,178 @@
+/**
+ * WebSocket v2 frame envelopes.
+ *
+ * These are the protocol-level message shapes — the framing layer that is
+ * stable across spec versions (see gameserver docs/websocket-v2.md). The
+ * per-action payloads and per-notification payloads are generated from the
+ * spec instead (see src/generated/). Endpoint: `/ws/v2`.
+ */
+import type { NotificationPayloads, TypedNotificationType } from './generated/notifications.gen.js';
+import type { V2GameState } from './generated/openapi/types.gen.js';
+/** Inbound frame: client -> server. `payload` is omitted when an action takes none. */
+export interface InboundFrame {
+    tool: string;
+    action: string;
+    payload?: Record<string, unknown>;
+    /** Opaque correlation token, <= 128 bytes. Echoed back on result/outcome frames. */
+    request_id?: string;
+}
+/** The synchronous query / mutation-ack response. */
+export interface ResultFrame {
+    type: 'result';
+    request_id?: string;
+    payload: {
+        /** Human-readable rendered text (or raw object when no renderer applies). */
+        result: unknown;
+        /** Raw JSON for programmatic consumption. */
+        structuredContent?: Record<string, unknown>;
+    };
+}
+/** Mutation-ack: a `result` frame whose structuredContent flags `pending: true`. */
+export interface PendingAck {
+    pending: true;
+    command: string;
+    message: string;
+}
+/** Outcome push for a queued mutation; echoes the original request_id. */
+export interface ActionResultFrame {
+    type: 'action_result';
+    request_id?: string;
+    payload: {
+        command: string;
+        tick: number;
+        /** A V2GameState delta — only the sections that changed. See StateDelta. */
+        result: StateDelta;
+        auto_docked?: boolean;
+        auto_undocked?: boolean;
+    };
+}
+/** Failure outcome for a queued mutation. */
+export interface ActionErrorFrame {
+    type: 'action_error';
+    request_id?: string;
+    payload: {
+        command: string;
+        tick: number;
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/** Generic error frame emitted by the framing layer or a handler. */
+export interface ErrorFrame {
+    type: 'error';
+    request_id?: string;
+    payload: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        /** Only on `action_pending` errors: names the already-queued mutation. */
+        pending_command?: string;
+    };
+}
+/** Unsolicited frame sent immediately after the socket upgrade. No request_id. */
+export interface WelcomeFrame {
+    type: 'welcome';
+    payload: {
+        version: string;
+        release_date: string;
+        release_notes: string[];
+        tick_rate: number;
+        current_tick: number;
+        server_time: number;
+        motd?: string;
+        game_info: string;
+        website: string;
+        help_text: string;
+        terms: string;
+    };
+}
+/** Auth success frame carrying the full initial session state. */
+export interface LoggedInFrame {
+    type: 'logged_in';
+    request_id?: string;
+    payload: Record<string, unknown>;
+}
+/** Auth success frame after `register`, carrying generated credentials. */
+export interface RegisteredFrame {
+    type: 'registered';
+    request_id?: string;
+    payload: {
+        /** 256-bit hex credential — only chance to capture it. */
+        password: string;
+        player_id: string;
+    };
+}
+/**
+ * A server-initiated push frame whose msg_type has a published payload schema.
+ * Unknown/untyped pushes are delivered as `RawFrame` (see below) until the
+ * server types them.
+ */
+export type NotificationFrame = {
+    [K in TypedNotificationType]: {
+        type: K;
+        payload: NotificationPayloads[K];
+    };
+}[TypedNotificationType];
+/**
+ * Any inbound frame as parsed off the wire, before classification. The router
+ * narrows this to a specific frame type by `type`. A bare-`string` discriminant
+ * is kept out of the typed `OutboundFrame` union so its members narrow cleanly.
+ */
+export interface RawFrame {
+    type: string;
+    request_id?: string;
+    payload?: unknown;
+}
+export type OutboundFrame = ResultFrame | ActionResultFrame | ActionErrorFrame | ErrorFrame | WelcomeFrame | LoggedInFrame | RegisteredFrame | NotificationFrame;
+/**
+ * The cacheable game-state sections — the eight independently-tracked sections
+ * the server emits deltas for. Section shapes are derived from the spec's
+ * `V2GameState`, so they stay correct as the spec evolves.
+ */
+export type GameState = Pick<V2GameState, 'player' | 'ship' | 'modules' | 'cargo' | 'location' | 'missions' | 'queue' | 'skills'>;
+/**
+ * A `V2GameState` delta carried on `action_result`. Only changed sections are
+ * present; an absent section means unchanged (keep prior local state). Carries
+ * the same eight sections as `GameState` plus the per-action convenience fields.
+ */
+export type StateDelta = GameState & Pick<V2GameState, 'message' | 'details' | 'credits'>;
+/**
+ * Resolved value of a synchronous query command. `T` is the command's specific
+ * `structuredContent` shape; the generated command facade binds it per command
+ * (e.g. `find_route` → `QueryResult<FindRouteResponse>`), so reads are typed with
+ * no cast. Defaults to untyped JSON for the low-level `query`/`send` paths.
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+    /** Human-readable rendered text (or raw object when no renderer applies). */
+    result: unknown;
+    /** Raw JSON for programmatic consumption, typed to the command's response. */
+    structuredContent?: T;
+}
+/** The immediate `pending: true` acknowledgement for a queued mutation. */
+export interface MutationAck {
+    command: string;
+    message: string;
+}
+/**
+ * Resolved value of a two-phase mutation, delivered when the action executes.
+ * `TDetails` is the action-specific shape of `delta.details` (e.g. `jump` ->
+ * `MutationResult<JumpResponse>`); the generated command facade binds it per
+ * command, so reads are typed with no cast. The rest of `delta` (the state
+ * sections that changed) is the same generic shape for every mutation — only
+ * `details` is action-specific. Defaults to untyped JSON for the low-level
+ * `mutate`/`send` paths.
+ */
+export interface MutationResult<TDetails = Record<string, unknown>> {
+    command: string;
+    /** Game tick on which the action executed. */
+    tick: number;
+    /** The V2GameState delta — only the sections that changed. */
+    delta: Omit<StateDelta, 'details'> & {
+        details?: TDetails;
+    };
+    autoDocked?: boolean;
+    autoUndocked?: boolean;
+}
+export declare const STATE_SECTIONS: readonly ["player", "ship", "modules", "cargo", "location", "missions", "queue", "skills"];
+export type StateSection = (typeof STATE_SECTIONS)[number];

package/dist/state/cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-account local cache of the eight game-state sections.
+ *
+ * Seeded canonically from a full `V2GameState` snapshot (the `get_status`
+ * query returns exactly this shape) and kept current by applying the section
+ * deltas carried on every `action_result`. Each present delta section is a
+ * complete replacement for that section — absent sections are left untouched
+ * (the server's "absent means unchanged" contract).
+ */
+import type { GameState, StateDelta, StateSection } from '../protocol.js';
+import type { V2GameState } from '../generated/openapi/types.gen.js';
+export declare class StateCache {
+    private state;
+    /** Replace the cache from a canonical full snapshot (e.g. `get_status`). */
+    seed(snapshot: V2GameState): StateSection[];
+    /**
+     * Apply a delta, replacing each present section. Returns the sections that
+     * changed (in `STATE_SECTIONS` order).
+     */
+    applyDelta(delta: StateDelta): StateSection[];
+    /**
+     * Merge a partial patch into a single section in place, preserving that
+     * section's other fields — unlike `applyDelta`/`seed`, which always
+     * replace a section wholesale. For bridging data from outside the normal
+     * action_result delta flow (e.g. observation pushes patching
+     * `location`'s nearby-player fields) into the corresponding section.
+     * No-ops (returns `[]`) if the section hasn't been seeded yet, since a
+     * partial patch can't stand in for a section's required fields.
+     */
+    patchSection<S extends StateSection>(section: S, patch: Partial<GameState[S]>): StateSection[];
+    /** Live view of the cached state. Treat as read-only — do not mutate. */
+    snapshot(): Readonly<GameState>;
+    get player(): GameState['player'];
+    get ship(): GameState['ship'];
+    get location(): GameState['location'];
+    get cargo(): GameState['cargo'];
+    get modules(): GameState['modules'];
+    get missions(): GameState['missions'];
+    get skills(): GameState['skills'];
+    /** True when a tick-deferred action is queued for this account. */
+    get hasPendingAction(): boolean;
+    get credits(): number | undefined;
+}

package/dist/state/market.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Local cache of subscribed station order books.
+ *
+ * Seeded from the `subscribe_market` baseline snapshot and kept current by
+ * merging `market_update` pushes (which carry only the items that changed).
+ * Keyed by `base_id`; items keyed by `item_id`.
+ */
+import type { NotificationMarketUpdate, SubscribeMarketResponse } from '../generated/openapi/types.gen.js';
+export type MarketItem = NotificationMarketUpdate['items'][number];
+export interface MarketBook {
+    base_id: string;
+    base_name?: string;
+    /** Tick of the most recent update (0 from the initial baseline). */
+    tick: number;
+    /** Order book per item_id. */
+    items: Map<string, MarketItem>;
+}
+export declare class MarketCache {
+    private readonly books;
+    /** Seed (or replace) a base's book from a subscribe_market baseline. */
+    seed(snapshot: SubscribeMarketResponse): string | undefined;
+    /** Merge a market_update push (changed items only) into the book. */
+    applyUpdate(update: NotificationMarketUpdate): void;
+    /** The cached book for a base, if subscribed. */
+    book(baseId: string): MarketBook | undefined;
+    /** All base_ids with a cached book. */
+    bases(): string[];
+    /** Drop a base's cached book (e.g. on unsubscribe). */
+    drop(baseId: string): void;
+}

package/dist/state/observation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Local cache of the subscribed observation watch (current POI + system).
+ *
+ * Seeded from the `subscribe_observation` baseline and kept current by merging
+ * `observation_update` pushes: `*_changed` arrays upsert players (keyed by
+ * `player_id`), `*_departed` arrays (player_id strings) remove them, and the
+ * cloaked-contact / signature hints are tracked alongside.
+ */
+import type { NotificationObservationUpdate, SubscribeObservationResponse } from '../generated/openapi/types.gen.js';
+export type ObservedPlayer = NonNullable<NotificationObservationUpdate['nearby_changed']>[number];
+export type CloakedContact = NonNullable<NotificationObservationUpdate['cloaked_resolved']>[number];
+export interface ObservationView {
+    poi_id?: string;
+    system_id?: string;
+    /** Tick of the most recent update (0 from the initial baseline). */
+    tick: number;
+    /** Uncloaked players at the watched POI, keyed by player_id. */
+    nearby: Map<string, ObservedPlayer>;
+    /** Uncloaked players system-wide, keyed by player_id. */
+    system: Map<string, ObservedPlayer>;
+    /** Cloaked contacts resolved by an active sensor sweep, keyed by target_id. */
+    cloaked: Map<string, CloakedContact>;
+    /** A faint cloaked-ship signature is present at the watched POI. */
+    unknownSignature: boolean;
+    /** Whether an active sensor sweep is running. */
+    activeScan: boolean;
+}
+export declare class ObservationCache {
+    private view;
+    /** Seed (or replace) the watch from a subscribe_observation baseline. */
+    seed(snapshot: SubscribeObservationResponse): ObservationView;
+    /** Merge an observation_update push into the watch. */
+    applyUpdate(update: NotificationObservationUpdate): void;
+    /** The current watch view, if subscribed. */
+    current(): ObservationView | null;
+    /** Clear the watch (e.g. on unsubscribe). */
+    clear(): void;
+}

package/dist/transport/correlator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Correlates server response frames to in-flight requests by `request_id`.
+ *
+ * Two request shapes:
+ *   - query    resolves on the synchronous `result` frame.
+ *   - mutation is usually two-phase: a `result` ack (pending marker set)
+ *              arrives first, then — possibly many ticks later — an
+ *              `action_result` (resolve) or `action_error` (reject). A
+ *              synchronous validation failure short-circuits to an `error`
+ *              frame (reject).
+ *              But some mutation-classified actions resolve synchronously in
+ *              a single `result` frame with no pending marker anywhere —
+ *              nothing was queued, so no `action_result` is ever coming (e.g.
+ *              `craft`/`recycle` with `dry_run: true`, which explicitly
+ *              queues nothing). That `result` frame is treated as the final
+ *              outcome instead of an ack, or the request would wait forever
+ *              for an `action_result` the server was never going to send.
+ *
+ * The pending marker's location in structuredContent is NOT consistent
+ * across actions — verified live against the real server: `scan`/`undock`
+ * carry it at the top level (`{pending: true, command, message}`), while
+ * `jump` nests it under `details` (`{details: {pending: true, command,
+ * message}, location: {...}, queue: {...}}`). Checking only the top level
+ * (an earlier version of this file did) misreads a real jump ack as the
+ * "nothing queued" case, resolving it immediately instead of waiting for the
+ * real outcome — which released the next queued mutation before the
+ * previous one actually executed, and the server correctly rejected it with
+ * `action_pending`, collapsing a whole multi-hop route in milliseconds.
+ *
+ * Frames may interleave arbitrarily on the wire, so nothing here assumes
+ * ordering beyond per-request_id sequencing.
+ */
+import type { MutationAck, MutationResult, QueryResult, RawFrame } from '../protocol.js';
+import { ConnectionClosedError, SpacemoltError } from '../errors.js';
+export type RequestKind = 'query' | 'mutation';
+export declare class Correlator {
+    private readonly pending;
+    /** Register a query request; resolves on its `result` frame. */
+    awaitQuery(requestId: string): Promise<QueryResult>;
+    /** Register a mutation request; resolves on its `action_result` outcome. */
+    awaitMutation(requestId: string, onAck?: (ack: MutationAck) => void): Promise<MutationResult>;
+    has(requestId: string): boolean;
+    /** Drop a pending request without settling it (e.g. after the caller gave up on a timeout). */
+    cancel(requestId: string): void;
+    /**
+     * Feed a frame to the correlator. Returns true if the frame was consumed
+     * (matched an in-flight request), false otherwise (caller treats it as a
+     * push frame).
+     */
+    handle(frame: RawFrame): boolean;
+    /** Reject every in-flight request — used when the socket closes. */
+    rejectAll(err: ConnectionClosedError | SpacemoltError): void;
+    private settle;
+}

package/dist/transport/socket.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Thin lifecycle wrapper over a web-standard WebSocket.
+ *
+ * Parses inbound text frames to `OutboundFrame` and hands them to `onFrame`;
+ * serializes outbound `InboundFrame`s. Reconnection and re-auth are M4 — this
+ * layer just owns one connection. The WebSocket implementation is injectable
+ * (`webSocketFactory`) so the transport can be driven by a mock in tests and
+ * so the browser/Bun/Node global `WebSocket` is used by default.
+ */
+import type { InboundFrame, RawFrame } from '../protocol.js';
+import { ConnectionClosedError } from '../errors.js';
+/** The minimal web-standard WebSocket surface this library depends on. */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'message', listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: (ev: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: (ev: unknown) => void): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export interface SocketOptions {
+    url: string;
+    webSocketFactory?: WebSocketFactory;
+}
+export declare class Socket {
+    private readonly opts;
+    private ws;
+    private opened;
+    private closed;
+    /** Called for every parsed inbound frame. */
+    onFrame?: (frame: RawFrame) => void;
+    /** Called once when the connection closes (for any reason). */
+    onClose?: (err: ConnectionClosedError) => void;
+    constructor(opts: SocketOptions);
+    /** Open the socket; resolves when the connection is established. */
+    connect(): Promise<void>;
+    send(frame: InboundFrame): void;
+    close(): void;
+    /**
+     * The server batches multiple pushes into a single WebSocket message as
+     * newline-delimited JSON under load (confirmed live: a burst of
+     * reconnect-related frames arrived as one message,
+     * `{"type":"reconnected",...}\n{"type":"logged_in",...}`). A JSON string
+     * value's own newlines are always escaped (`\n`, two characters) by any
+     * conforming serializer, so a raw newline byte in the message text is only
+     * ever a frame separator, never content — splitting on it is safe. Each
+     * line is parsed and routed independently, so one malformed line in a
+     * batch no longer takes every other frame in that same message down with
+     * it (the previous behavior: parsing the whole batch as one JSON value,
+     * which always failed whenever more than one frame arrived together).
+     */
+    private handleMessage;
+    private markClosed;
+}

package/llms.txt

@@ -0,0 +1,23 @@
+# @spacemolt/lib
+
+> The definitive TypeScript library for the game [SpaceMolt](https://www.spacemolt.com). Speaks the WebSocket v2 protocol, keeps a live local cache of your state, is multi-account native, and regenerates its own typed command surface from the server's OpenAPI spec. Runs on Bun, Node 22+, and the browser.
+
+If you are an AI agent writing code against this library, start with AGENTS.md
+(orientation) and COMMANDS.md (the full command list). The whole API is typed —
+run `tsc --noEmit` before executing a script to catch a wrong command or
+parameter as a compile error rather than a runtime surprise.
+
+## Start here
+
+- [AGENTS.md](./AGENTS.md): How to write against this library — the calling pattern, how to discover commands, and the typecheck-first workflow.
+- [COMMANDS.md](./COMMANDS.md): Generated reference of every command (250+) with its full typed signature, query/mutation kind, and description. Greppable.
+
+## Docs
+
+- [README.md](./README.md): Full guide — quickstart, queries vs mutations, the local state cache, live events, subscriptions, multi-account (Clerk API key), and bulk reference data.
+- [docs/live-testing.md](./docs/live-testing.md): Running against the real server — registration, the smoke test, and gotchas.
+- [CLAUDE.md](./CLAUDE.md): Developer guide for working *on* the library itself (codegen, layout, milestones).
+
+## Optional
+
+- [docs/gameserver-todo.md](./docs/gameserver-todo.md): Server-side gaps that further improve type coverage as they land.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@spacemolt/lib",
+  "version": "4.6.0",
+  "description": "The definitive TypeScript library for SpaceMolt. WebSocket-v2-first, multi-account, with local state caches. Internals are regenerated from the server's OpenAPI spec.",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "COMMANDS.md",
+    "AGENTS.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "fetch-spec": "bun run scripts/fetch-spec.ts",
+    "generate": "bun run openapi-ts && bun run scripts/generate.ts",
+    "typecheck": "bun x tsc --noEmit",
+    "prepare": "bun run build",
+    "build": "rm -rf dist && bun build src/index.ts --outfile dist/index.js --target node --format esm && bun build src/node.ts --outfile dist/node.js --target node --format esm && bun x tsc -p tsconfig.build.json && bun run scripts/fix-dts-extensions.ts",
+    "build:browser-check": "bun build src/index.ts --target browser --outfile /dev/null",
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpaceMolt/spacemolt-lib.git"
+  },
+  "homepage": "https://www.spacemolt.com",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.73.0",
+    "@types/bun": "^1.3.9"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}