@spacemolt/lib 15.1.0 → 15.2.1

package/COMMANDS.md

@@ -1,7 +1,7 @@
 <!-- AUTO-GENERATED by scripts/generate.ts from openapi.json. DO NOT EDIT. -->
 # SpaceMolt command reference
 
-Every command in `@spacemolt/lib`, generated from the live server spec (`v0.612.0`). **296 commands across 19 tools.**
+Every command in `@spacemolt/lib`, generated from the live server spec (`v0.613.4`). **296 commands across 19 tools.**
 
 ## How to call a command
 

package/README.md

@@ -136,6 +136,23 @@ account.onAny((frame) => console.log('push:', frame.type));
 for await (const hit of account.events('battle_damage')) { /* ... */ }
 ```
 
+`onAny` sees only unsolicited pushes. To log every frame on the wire, including
+your own query/mutation replies, pass `onSend`/`onReceive` (the client variants
+also receive the account id). Credentials are redacted in both directions:
+`onSend` sees a `spacemolt_auth` frame with its `password`, `token`,
+`registration_code`, or `device_code` (from `login_link_poll`) replaced by
+`'[redacted]'`, and `onReceive` sees a `registered` push (which carries the
+account's generated password) with that password redacted, and a `result`
+frame carrying a `device_code` (`login_link`'s response) with that code
+redacted too — the frame actually sent/routed is unaffected either way:
+
+```ts
+new SpacemoltClient({
+  onSend: (id, frame) => console.log(id, '→', frame.tool, frame.action, frame.request_id),
+  onReceive: (id, frame) => console.log(id, '←', frame.type, frame.request_id),
+});
+```
+
 ### Subscriptions
 
 Subscribe to a station's order book or to presence at your location; the
@@ -303,6 +320,40 @@ const { stations } = await fetchStations('https://game.spacemolt.com');
 const { system } = await fetchMobileBase('https://game.spacemolt.com'); // the moving capital
 ```
 
+Every one of these fetches is bounded by a timeout (30s by default, covering the
+response body, not just the headers; pass `{ timeoutMs }`, or `httpTimeoutMs` on
+the client, to change it — the catalog is several MB), retries a transient `429`/`503` a few times
+(honoring `Retry-After`, jittered), and throws a typed `HttpError`
+(`status`/`url`/`attempts`/`retryAfterMs`) on a retry-exhausted or otherwise
+non-ok response. A timeout or network error throws the native error
+(`DOMException`/`TypeError`) instead — it's not an `HttpError`. The 60s
+retry-wait cap is on the *total* base wait summed across every attempt, not
+each attempt checked in isolation — so three retries of a near-the-cap
+`Retry-After` can't add up to several times the cap.
+
+With a client, the same data is `client.catalog()`, `client.map()`,
+`client.stations()` and `client.mobileBase()`. To observe HTTP traffic
+(status/bytes/timing/retries), set `fetchImpl` once on the client — every
+HTTP call it makes, including Clerk, goes through it:
+
+```ts
+const client = new SpacemoltClient({
+  fetchImpl: async (input, init) => {
+    const started = Date.now();
+    const res = await fetch(input, init);
+    console.log(res.status, String(input), `${Date.now() - started}ms`);
+    return res;
+  },
+});
+```
+
+The per-call timeout is delivered through `init.signal` (an `AbortSignal`), not
+a separate argument — a wrapper must pass `init` through to the real `fetch`
+unchanged, as above, or it silently loses the timeout.
+
+The standalone functions above take the same option as a trailing
+`{ fetchImpl }` for use without a client.
+
 ## Examples
 
 Runnable scripts in [`examples/`](./examples), run with `bun run examples/<name>.ts`:

package/dist/account.d.ts

@@ -18,7 +18,7 @@ import type { FleetPush, OkPush } from './push-frames.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 { GameState, MutationAck, MutationResult, QueryResult, InboundFrame, RawFrame, StateSection, WelcomeFrame } from './protocol.js';
 import { type WebSocketFactory } from './transport/socket.js';
 /**
  * The `logged_in` frame payload, typed from the server's published
@@ -43,11 +43,36 @@ export interface ReconnectOptions {
     /** Backoff ceiling in ms. Default 30000. */
     maxDelayMs?: number;
 }
+/** Info reported to an `onRateLimited` listener — see `Account.onRateLimited`. */
+export interface RateLimitedInfo {
+    /** The call being retried: `tool.action` for `query`/`mutate`, `'authenticate'` for auth. */
+    command: string;
+    /** 1-based retry attempt number. */
+    attempt: number;
+    /** How long this retry is waiting before resending, including jitter. */
+    delayMs: 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;
+    /**
+     * Observe every outbound frame (logging/review). Fires before it is sent.
+     * A `spacemolt_auth` frame's `password`, `token`, `registration_code`, or
+     * `device_code` (from `login_link_poll`) is replaced with `'[redacted]'`
+     * before this fires — the frame actually sent to the server is unaffected.
+     */
+    onSend?: (frame: InboundFrame) => void;
+    /**
+     * Observe every parsed inbound frame (logging/review). Fires before
+     * routing. A `registered` push's `password` (the account's generated
+     * credential), and a `result` frame's `device_code` (`login_link`'s
+     * response), are replaced with `'[redacted]'` before this fires — the
+     * frame that reaches `register()`'s/the correlator's own resolution is
+     * unaffected.
+     */
+    onReceive?: (frame: RawFrame) => void;
     /**
      * After authenticating, issue a `get_status` query to seed the local state
      * cache with the canonical full state. Default `true`. Disable to avoid the
@@ -136,6 +161,8 @@ export declare class Account {
     private readonly seedState;
     private readonly url;
     private readonly webSocketFactory?;
+    private readonly onSend?;
+    private readonly onReceive?;
     private readonly reconnectConfig;
     private readonly credentialsProvider?;
     private readonly fetchImpl?;
@@ -148,6 +175,8 @@ export declare class Account {
     private requestSeq;
     private _welcome;
     private _authenticated;
+    /** How many `reconnectOnce` calls are mid-swap; a count, so overlapping calls can't lift each other's guard. */
+    private reconnectsPending;
     private _loginPayload;
     private _currentTick;
     private _commands;
@@ -169,6 +198,7 @@ export declare class Account {
     private readonly reconnectedListeners;
     private readonly reconnectingListeners;
     private readonly disconnectedListeners;
+    private readonly rateLimitedListeners;
     constructor(opts?: AccountOptions);
     private makeSocket;
     /** Live view of the cached game state. Treat as read-only. */
@@ -446,6 +476,13 @@ export declare class Account {
     onReconnected(listener: () => void): () => void;
     /** Fired at the start of each reconnect attempt (1-based). Returns an unsubscribe function. */
     onReconnecting(listener: (attempt: number) => void): () => void;
+    /**
+     * Fired before each rate-limit retry sleep (`query`/`mutate`/`authenticate`
+     * auto-retrying a `rate_limited` error) — the delay includes jitter, so
+     * accounts rate-limited together don't retry in lockstep; this is what a
+     * caller sees per attempt. Returns an unsubscribe function.
+     */
+    onRateLimited(listener: (info: RateLimitedInfo) => void): () => void;
     /**
      * Fired when the connection is gone for good (non-reconnectable or retries
      * exhausted). Returns an unsubscribe function.
@@ -454,8 +491,15 @@ export declare class Account {
     private authExchange;
     /** Best-effort seed of the state cache after auth; failures are non-fatal. */
     private maybeSeedState;
+    /** Returns whether the auth exchange was accepted — a caller must not send its frame when it wasn't. */
     private beginAuth;
     private sendFrame;
+    /**
+     * Calls an optional single-callback hook (`onSend`/`onReceive`), swallowing
+     * a throw so a broken observer can't stop the frame being sent or routed —
+     * same handling as `notifyListeners` for a `Set` of listeners.
+     */
+    private callHook;
     private nextRequestId;
     /**
      * Pick the `request_id` for one frame. A caller-supplied id is echoed by the
@@ -471,6 +515,16 @@ export declare class Account {
     private claimRequestId;
     private routeFrame;
     private warnMalformedFrame;
+    /**
+     * Fails everything waiting on the current socket: in-flight correlator
+     * entries (query/mutate), a pending `welcome` wait, and a pending auth
+     * exchange (`login`/`register`/`loginToken`). Deliberately excludes
+     * `emitter.closeStreams()`: `handleClose` (a real close) still ends the
+     * player's event async iterators itself, but a `reconnectOnce` forced on a
+     * live socket leaves them running. Shared by `handleClose` and
+     * `reconnectOnce`, which both strand work on a socket that's going away.
+     */
+    private failPendingWork;
     private handleClose;
     private shouldReconnect;
     private reconnectLoop;
@@ -490,6 +544,13 @@ export declare class Account {
      */
     reconnectOnce(): Promise<void>;
     private resubscribe;
+    /**
+     * Runs `fn`, retrying on a `rate_limited` `SpacemoltError` up to
+     * `maxRateLimitRetries` times. The wait is jittered (see `jitteredDelayMs`)
+     * so accounts rate-limited together don't all retry in lockstep, and fires
+     * `onRateLimited` before each sleep. `command` identifies the call for that
+     * listener (`tool.action`, or `'authenticate'`).
+     */
     private withRateLimitRetry;
     /** Serialize mutations: each runs only after the previous settles. */
     private enqueueMutation;

package/dist/auth/clerk.d.ts

@@ -39,13 +39,14 @@ export interface ClerkRegistration {
     registrationCode: string;
     players: ClerkPlayer[];
 }
+type HeadersCtorInit = NonNullable<ConstructorParameters<typeof Headers>[0]>;
 /**
  * Headers that authorize calls to the Clerk-gated gameserver endpoints — an
  * alternative to `apiKey` for callers whose credential isn't a static key.
  * A factory is resolved fresh on every request, so short-lived tokens (e.g. a
  * browser Clerk session's `getToken()` JWT) stay valid across reconnects.
  */
-export type ClerkAuthHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export type ClerkAuthHeaders = HeadersCtorInit | (() => HeadersCtorInit | Promise<HeadersCtorInit>);
 /** How Clerk-gated requests are authorized. Provide `apiKey`, `headers`, or both. */
 export interface ClerkAuth {
     /** Clerk API key, sent as `Authorization: Bearer`. Keep it secret. */
@@ -83,3 +84,4 @@ export declare class ClerkSource {
     /** Mint a single-use WS login token for one owned player. */
     mintWsToken(playerId: string): Promise<string>;
 }
+export {};

package/dist/client.d.ts

@@ -10,9 +10,12 @@
 import { Account } from './account.js';
 import { type AuthCredentials, type CredentialStore, type StoredAccount } from './auth/credentials.js';
 import type { WebSocketFactory } from './transport/socket.js';
+import type { InboundFrame, RawFrame } from './protocol.js';
 import type { ReconnectOptions, RegisterParams, RegisterResult } from './account.js';
 import { CatalogCache } from './data/catalog.js';
 import { MapCache } from './data/map.js';
+import { type MobileBaseLocation } from './data/mobile-base.js';
+import { type StationList } from './data/stations.js';
 import { type ClerkPlayer } from './auth/clerk.js';
 import { type ConnectionClosedError } from './errors.js';
 export interface SpacemoltClientOptions {
@@ -22,6 +25,10 @@ export interface SpacemoltClientOptions {
     store?: CredentialStore;
     /** Inject a WebSocket implementation (tests, custom runtimes). */
     webSocketFactory?: WebSocketFactory;
+    /** Observe every outbound frame on every managed account (see Account). */
+    onSend?: (accountId: string, frame: InboundFrame) => void;
+    /** Observe every inbound frame on every managed account (see Account). */
+    onReceive?: (accountId: string, frame: RawFrame) => void;
     /** Seed each account's state cache after auth (see Account). Default true. */
     seedState?: boolean;
     /**
@@ -94,8 +101,19 @@ export interface SpacemoltClientOptions {
      * Generate one from the website; keep it secret.
      */
     clerkApiKey?: string;
-    /** Inject a `fetch` implementation (tests, custom runtimes). */
+    /**
+     * Inject a `fetch` implementation (tests, custom runtimes). The per-call
+     * timeout is delivered via `init.signal` (an `AbortSignal`), not a
+     * separate argument — a wrapper must pass `init` through to the real
+     * `fetch` unchanged or it silently loses the timeout.
+     */
     fetchImpl?: typeof fetch;
+    /**
+     * Abort each HTTP data fetch (catalog, map, stations, mobile base) after this
+     * many ms, body included. Default 30000. Raise it on a slow link: the catalog
+     * is several MB.
+     */
+    httpTimeoutMs?: number;
     /**
      * How long to wait for the server's `welcome` frame (post-WS-upgrade) and
      * for a `logged_in`/error response to an auth attempt, before giving up.
@@ -196,6 +214,7 @@ export declare class SpacemoltClient {
     private notifyAccountDisconnected;
     /** HTTP origin used for bulk data fetches (catalog, map). */
     get httpBaseUrl(): string;
+    private get httpOptions();
     /**
      * The bulk catalog. Fetched on first use and cached, then revalidated against
      * the server once the cache is older than `catalogMaxAgeMs` (default 1h) so a
@@ -207,6 +226,10 @@ export declare class SpacemoltClient {
     catalog(force?: boolean): Promise<CatalogCache>;
     /** The static galaxy map, fetched once and cached. Pass `force` to refetch. */
     map(force?: boolean): Promise<MapCache>;
+    /** The live station directory. Not cached — it changes as the game runs. */
+    stations(): Promise<StationList>;
+    /** The mobile base's current system. Not cached — it moves. */
+    mobileBase(): Promise<MobileBaseLocation>;
     /** The credential store backing this client. */
     get credentialStore(): CredentialStore;
     /** Persist username/password credentials. Returns the account id (username). */

package/dist/data/catalog.d.ts

@@ -1,4 +1,5 @@
 import type { CatalogAchievement, CatalogDump, FacilityDefinition, Item, Module, Recipe, ShipClass, SkillDefinition } from '../generated/openapi/types.gen.js';
+import { type FetchOptions } from './http.js';
 /**
  * Local copy of the bulk game catalog (`GET /api/catalog.json`).
  *
@@ -52,10 +53,14 @@ export interface CatalogFetchResult {
  * `etag` is passed and the server confirms the catalog is unchanged, this
  * returns `{ notModified: true }` after a ~0-byte `304` — no multi-MB download
  * or re-parse. Otherwise it returns the fresh catalog and its new `ETag`.
+ *
+ * Bounded by a request timeout and retried on a transient `429`/`503`; a
+ * failure that isn't a 304 throws `HttpError`. Pass `fetchImpl` to inject a
+ * `fetch` (tests, or an observability wrapper — see `httpGet`).
  */
-export declare function fetchCatalogConditional(httpBaseUrl: string, etag?: string): Promise<CatalogFetchResult>;
-/** Unconditionally fetch and normalize the catalog. */
-export declare function fetchCatalog(httpBaseUrl: string): Promise<Catalog>;
+export declare function fetchCatalogConditional(httpBaseUrl: string, etag?: string, opts?: FetchOptions): Promise<CatalogFetchResult>;
+/** Unconditionally fetch and normalize the catalog. See `fetchCatalogConditional` for `fetchImpl`. */
+export declare function fetchCatalog(httpBaseUrl: string, opts?: FetchOptions): Promise<Catalog>;
 export declare class CatalogCache {
     readonly catalog: Catalog;
     /** The server `ETag` this catalog was fetched with, for conditional reloads. */
@@ -70,13 +75,13 @@ export declare class CatalogCache {
     /** The server `ETag` this catalog was fetched with, for conditional reloads. */
     etag?: string | undefined);
     /** Fetch the catalog and wrap it in a cache. */
-    static load(httpBaseUrl: string): Promise<CatalogCache>;
+    static load(httpBaseUrl: string, opts?: FetchOptions): Promise<CatalogCache>;
     /**
      * Conditionally refresh via `If-None-Match`. Returns `this` unchanged when the
      * server confirms the catalog is still current (a cheap `304`), or a new
      * `CatalogCache` when the catalog has changed.
      */
-    revalidate(httpBaseUrl: string): Promise<CatalogCache>;
+    revalidate(httpBaseUrl: string, opts?: FetchOptions): Promise<CatalogCache>;
     /** Server release this catalog was built for; `''` if the response omitted it. */
     get version(): string;
     ship(id: string): CatalogShip | undefined;

package/dist/data/http.d.ts

@@ -0,0 +1,36 @@
+/** Options every public data fetcher accepts. */
+export interface FetchOptions {
+    /** Inject a `fetch` implementation (tests, observability). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Abort each request after this many ms, body included. Default 30000. */
+    timeoutMs?: number;
+}
+export interface HttpGetOptions {
+    headers?: Record<string, string>;
+    /** Abort the request after this many ms (`AbortSignal.timeout`). Default 30000. */
+    timeoutMs?: number;
+    /**
+     * Inject a `fetch` implementation — tests, custom runtimes, or an
+     * observability wrapper (status/bytes/timing/retries) a consumer supplies
+     * via `SpacemoltClientOptions.fetchImpl` / the per-call `fetchImpl` option.
+     * Defaults to global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /** Response statuses besides 2xx to return rather than treat as a failure (e.g. 304). */
+    okStatuses?: readonly number[];
+    /**
+     * Total (un-jittered) base retry wait allowed across every attempt before
+     * giving up — not re-checked per attempt in isolation. Default
+     * `MAX_RETRY_WAIT_MS` (60000). Mainly for tests that need a small cap to
+     * exercise this without waiting real seconds.
+     */
+    maxRetryWaitMs?: number;
+}
+/**
+ * `GET url`, bounded by `timeoutMs` (headers and body both) and retried up to
+ * `MAX_RETRIES` times on `429`/`503` (waiting `Retry-After` when present,
+ * else a short backoff — either way, jittered). A timeout or network error is
+ * not retried — it throws the native error as-is, not an `HttpError`. Any
+ * other non-ok, non-`okStatuses` response throws an `HttpError`.
+ */
+export declare function httpGet(url: string, opts?: HttpGetOptions): Promise<Response>;

package/dist/data/map.d.ts

@@ -1,4 +1,5 @@
 import type { MapData, MapDataSystem } from '../generated/openapi/types.gen.js';
+import { type FetchOptions } from './http.js';
 /**
  * Local copy of the static galaxy map (`GET /api/map`).
  *
@@ -15,13 +16,13 @@ import type { MapData, MapDataSystem } from '../generated/openapi/types.gen.js';
 /** A system entry from `GET /api/map`. */
 export type MapSystem = MapDataSystem;
 export type GalaxyMap = MapData;
-export declare function fetchMap(httpBaseUrl: string): Promise<GalaxyMap>;
+export declare function fetchMap(httpBaseUrl: string, opts?: FetchOptions): Promise<GalaxyMap>;
 export declare class MapCache {
     readonly map: GalaxyMap;
     private readonly bySystemId;
     constructor(map: GalaxyMap);
     /** Fetch the galaxy map and wrap it in a cache. */
-    static load(httpBaseUrl: string): Promise<MapCache>;
+    static load(httpBaseUrl: string, opts?: FetchOptions): Promise<MapCache>;
     system(id: string): MapSystem | undefined;
     get systems(): readonly MapSystem[];
     /** Empire id -> display colour. */

package/dist/data/mobile-base.d.ts

@@ -1,4 +1,5 @@
 import type { MobileBaseLocation } from '../generated/openapi/types.gen.js';
+import { type FetchOptions } from './http.js';
 /**
  * Where the galaxy's single moving capital currently is
  * (`GET /wheres-mobile-base`).
@@ -8,6 +9,6 @@ import type { MobileBaseLocation } from '../generated/openapi/types.gen.js';
  * is the spec's published `MobileBaseLocation` (`{ system }`), a system id that
  * indexes into the galaxy map.
  */
-/** Fetch the mobile base's current system id. */
-export declare function fetchMobileBase(httpBaseUrl: string): Promise<MobileBaseLocation>;
+/** Fetch the mobile base's current system id. Pass `fetchImpl` to inject a `fetch` (tests, observability). */
+export declare function fetchMobileBase(httpBaseUrl: string, opts?: FetchOptions): Promise<MobileBaseLocation>;
 export type { MobileBaseLocation };

package/dist/data/stations.d.ts

@@ -1,3 +1,4 @@
+import { type FetchOptions } from './http.js';
 /**
  * Station directory (`GET /api/stations`).
  *
@@ -53,5 +54,5 @@ export interface StationList {
     stations: StationSummary[];
     empires: StationEmpire[];
 }
-/** Fetch the public station directory. */
-export declare function fetchStations(httpBaseUrl: string): Promise<StationList>;
+/** Fetch the public station directory. Pass `fetchImpl` to inject a `fetch` (tests, observability). */
+export declare function fetchStations(httpBaseUrl: string, opts?: FetchOptions): Promise<StationList>;

package/dist/errors.d.ts

@@ -24,6 +24,25 @@ export declare class SpacemoltError extends Error {
 }
 export declare function errorFromFrame(frame: ErrorFrame): SpacemoltError;
 export declare function errorFromActionFrame(frame: ActionErrorFrame): SpacemoltError;
+/**
+ * Raised by a bulk/live HTTP data fetch (catalog, map, stations, mobile-base)
+ * that didn't come back ok — after retries, for a retryable status. Message
+ * text matches the old bare-`Error` format (`GET <url> -> <status> <text>`).
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    /** How many requests were made in total, including the one that finally failed. */
+    readonly attempts: number;
+    /** The server's `Retry-After` on the failing response, parsed to ms, if any. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, opts: {
+        status: number;
+        url: string;
+        attempts: number;
+        retryAfterMs?: number;
+    });
+}
 /** Raised against every in-flight request when the socket closes. */
 export declare class ConnectionClosedError extends Error {
     readonly code?: number;

package/dist/generated/actions.gen.d.ts

@@ -1,5 +1,5 @@
 /** The gameserver spec version this command surface was generated from. */
-export declare const GENERATED_SPEC_VERSION = "v0.612.0";
+export declare const GENERATED_SPEC_VERSION = "v0.613.4";
 export type ToolName = "spacemolt" | "spacemolt_arena" | "spacemolt_auth" | "spacemolt_battle" | "spacemolt_citizenship" | "spacemolt_drone" | "spacemolt_facility" | "spacemolt_faction" | "spacemolt_faction_admin" | "spacemolt_faction_commerce" | "spacemolt_fleet" | "spacemolt_intel" | "spacemolt_market" | "spacemolt_salvage" | "spacemolt_ship" | "spacemolt_shipping" | "spacemolt_social" | "spacemolt_storage" | "spacemolt_transfer";
 export type ActionName = "abandon_mission" | "accept" | "accept_ally" | "accept_invite" | "accept_mission" | "accept_peace" | "active" | "advance" | "allow_faction" | "allow_player" | "analyze_market" | "apply" | "attack" | "ban" | "base_cost" | "board" | "browse_for_sale" | "browse_ships" | "build" | "buy" | "buy_listed_ship" | "buy_listing" | "buy_ship_license" | "cancel" | "cancel_commission" | "cancel_listing" | "cancel_mission" | "cancel_order" | "cancel_ship_buy_order" | "cancel_ship_listing" | "captains_log_add" | "captains_log_delete" | "captains_log_get" | "captains_log_list" | "challenge" | "challenges" | "chat" | "claim" | "claim_prize" | "cloak" | "commission_quote" | "commission_ship" | "commission_status" | "complete_mission" | "completed_missions" | "craft" | "create" | "create_buy_order" | "create_note" | "create_role" | "create_sell_order" | "declare_war" | "decline" | "decline_invite" | "decline_mission" | "delete_note" | "delete_role" | "delete_room" | "deliver" | "deploy" | "deploy_outpost" | "deposit" | "disband" | "disembark" | "dismantle" | "dismantle_outpost" | "distress_signal" | "dock" | "edit" | "edit_role" | "engage" | "espionage" | "estimate_purchase" | "facility_set_description" | "faction_build" | "faction_dismantle" | "faction_list" | "faction_owned" | "faction_personnel" | "faction_upgrade" | "fight" | "find_route" | "forum_create_thread" | "forum_delete_reply" | "forum_delete_thread" | "forum_get_thread" | "forum_list" | "forum_reply" | "forum_upvote" | "found_station" | "garages" | "get" | "get_achievements" | "get_action_log" | "get_active_missions" | "get_base" | "get_cargo" | "get_chat_history" | "get_commands" | "get_empire_info" | "get_faction_achievements" | "get_guide" | "get_invites" | "get_location" | "get_map" | "get_missions" | "get_nearby" | "get_notes" | "get_notification_settings" | "get_notifications" | "get_player" | "get_poi" | "get_queue" | "get_ship" | "get_skills" | "get_state" | "get_status" | "get_system" | "get_system_agents" | "get_tax_estimate" | "get_trades" | "get_version" | "hunt" | "info" | "inspect" | "install_mod" | "insure" | "intel_status" | "invite" | "jettison" | "job_add" | "job_cancel" | "job_list" | "job_reorder" | "join" | "jump" | "kick" | "leave" | "list" | "list_for_sale" | "list_missions" | "list_passengers" | "list_ship_for_sale" | "list_ships" | "list_station_passengers" | "load" | "load_passenger" | "log" | "login" | "login_link" | "login_link_poll" | "login_token" | "logout" | "loot" | "mine" | "modify_order" | "mute_notifications" | "name" | "owned" | "pay_bounty" | "pay_debt" | "personal_build" | "personal_decorate" | "personal_visit" | "petition" | "place_ship_buy_order" | "policies" | "post" | "post_mission" | "prepay_tax" | "profile" | "promote" | "propose_ally" | "propose_peace" | "query_intel" | "query_trade_intel" | "quote" | "ranch_set_cull" | "ranch_status" | "read_note" | "recall" | "recruit_personnel" | "recycle" | "refit_ship" | "refuel" | "register" | "release" | "reload" | "remove_ally" | "remove_enemy" | "remove_faction" | "remove_player" | "rename_ship" | "renounce" | "repair" | "retreat" | "return" | "rooms" | "scan" | "scan_poi" | "scrap" | "scrap_ship" | "search_systems" | "self_destruct" | "sell" | "sell_ship_to_order" | "service_prize" | "set_access" | "set_auto_buy_fuel" | "set_build_policy" | "set_colors" | "set_description" | "set_enemy" | "set_home" | "set_market_fee" | "set_name" | "set_output_price" | "set_public" | "set_refuel_price" | "set_repair_price" | "set_service_access" | "set_status" | "stance" | "station_info" | "station_set_name" | "status" | "submit_intel" | "submit_trade_intel" | "subscribe_market" | "subscribe_observation" | "summary" | "supply_commission" | "survey_system" | "switch_ship" | "target" | "tax_estimate" | "tow" | "track" | "trade_accept" | "trade_cancel" | "trade_decline" | "trade_intel_status" | "trade_offer" | "transfer" | "transfer_personnel" | "travel" | "treat_personnel" | "types" | "unban" | "undock" | "uninstall_mod" | "unload" | "unload_passenger" | "unmute_notifications" | "unsubscribe_market" | "unsubscribe_observation" | "upgrade" | "upgrades" | "upload" | "use_item" | "view" | "view_completed_mission" | "view_market" | "view_orders" | "view_ship_buy_orders" | "visit_room" | "withdraw" | "withdraw_invite" | "wrecks" | "write_note" | "write_room";
 export interface ActionParam {

package/dist/generated/openapi/types.gen.d.ts

@@ -2877,7 +2877,7 @@ export type DockResponse = {
     commissions_active?: Array<CommissionActive>;
     facility_note?: string;
     fuel_warning?: string;
-    gifts?: Array<GiftNotification>;
+    gifts?: Array<StorageGift>;
     gifts_count?: number;
     gifts_note?: string;
     gifts_truncated?: boolean;
@@ -5069,14 +5069,6 @@ export type GetWrecksResponse = {
     count: number;
     wrecks: Array<EnrichedWreck>;
 };
-export type GiftNotification = {
-    credits?: number;
-    items?: Array<ItemQuantity>;
-    message?: string;
-    sender: string;
-    sender_id: string;
-    timestamp: string;
-};
 export type GiftShipResponse = {
     action: 'gift_ship';
     /**
@@ -5166,6 +5158,9 @@ export type InspectPackageShipment = {
 };
 export type InspectResponse = {
     base?: GetBaseResponse;
+    /**
+     * Present only when source is catalog. kind item or module → type items, entries are Item or Module. kind ship_class → type ships, entries are ShipClass. Other catalog types are not returned here.
+     */
     catalog?: {
         analysis?: RecipeAnalysis;
         estimated_material_cost?: number;
@@ -5704,6 +5699,10 @@ export type MarketInsight = {
 };
 export type MarketItemBook = {
     buy_orders: Array<MarketLevel>;
+    /**
+     * Item category of this item_id such as ore; refined; component; or module for a ship module. It is the category view_market reports for the same item_id. Omitted when the definition is no longer known.
+     */
+    category?: string;
     item_id: string;
     item_name?: string;
     sell_orders: Array<MarketLevel>;
@@ -10908,7 +10907,7 @@ export type V2Response = {
      */
     error?: {
         /**
-         * Machine-readable error code. Session/auth codes: session_required (no X-Session-Id header), session_invalid (session not found or expired — create a new one with POST /api/v2/session then login), not_authenticated (session exists but not logged in). Other codes: rate_limited, command_error, invalid_params, invalid_json, payload_too_large, method_not_allowed, missing_action, unknown_command.
+         * Machine-readable error code. Session/auth codes: session_required (no X-Session-Id header), session_invalid (session not found or expired — create a new one with POST /api/v2/session then login), not_authenticated (session exists but not logged in). Other codes: rate_limited, command_error, invalid_params, invalid_json, payload_too_large, method_not_allowed, missing_action, unknown_command. ip_timed_out is WebSocket-only: over HTTP an IP block returns a flat 429 body without this envelope: {"error": "rate_limited", "message", "retry_after", "limit": "ip_timeout", "scope": "ip"} plus a Retry-After header.
          */
         code?: string;
         /**
@@ -10922,7 +10921,7 @@ export type V2Response = {
          */
         message?: string;
         /**
-         * Seconds to wait before retrying. Present on rate_limited errors.
+         * Seconds to wait before retrying. Present on rate_limited errors from a rate-limit bucket (failed-login and bug-report rate_limited errors omit it), with the same value in the Retry-After header. details then carries limit (the bucket), scope (what the bucket is keyed on) and, for capped buckets, limit_per_min and current.
          */
         retry_after?: number;
     };

package/dist/index.d.ts

@@ -10,17 +10,18 @@
  * subsequent milestones.
  */
 export * from './protocol.js';
-export { Account, type AccountOptions, type ReconnectOptions, type RegisterParams, type RegisterResult, type LoggedInPayload, } from './account.js';
+export { Account, type AccountOptions, type ReconnectOptions, type RegisterParams, type RegisterResult, type LoggedInPayload, type RateLimitedInfo, } from './account.js';
 export { SpacemoltClient, type SpacemoltClientOptions } from './client.js';
 export { ClerkSource, mintWsToken, type ClerkAuth, type ClerkAuthHeaders, type ClerkPlayer, type ClerkRegistration, type ClerkSourceOptions, } from './auth/clerk.js';
 export { type CredentialStore, type StoredAccount, type AuthCredentials, MemoryCredentialStore, } from './auth/credentials.js';
-export { SpacemoltError, ConnectionClosedError, CLOSE_CODE, retryAfterMsFromClose } from './errors.js';
+export { SpacemoltError, ConnectionClosedError, HttpError, CLOSE_CODE, retryAfterMsFromClose } from './errors.js';
 export { StateCache } from './state/cache.js';
 export { MarketCache, type MarketBook, type MarketItem } from './state/market.js';
 export { ObservationCache, type ObservationView, type ObservedPlayer, type CloakedContact, } from './state/observation.js';
 export { TypedEmitter, EventStream } from './events/emitter.js';
 export { type Commands, type CommandDispatch, buildCommands } from './generated/commands.gen.js';
 export { CatalogCache, fetchCatalog, fetchCatalogConditional, type Catalog, type CatalogAchievement, type CatalogFacility, type CatalogFetchResult, type CatalogItem, type CatalogRecipe, type CatalogShip, type CatalogSkill, } from './data/catalog.js';
+export type { FetchOptions } from './data/http.js';
 export { MapCache, fetchMap, httpBaseFromWs, type GalaxyMap, type MapSystem } from './data/map.js';
 export { fetchStations, type StationEmpire, type StationList, type StationSummary } from './data/stations.js';
 export { fetchMobileBase, type MobileBaseLocation } from './data/mobile-base.js';