@spacemolt/lib 15.1.0 → 15.2.0

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/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/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';

package/dist/index.js

@@ -3641,6 +3641,21 @@ function errorFromActionFrame(frame) {
   });
 }
 
+class HttpError extends Error {
+  status;
+  url;
+  attempts;
+  retryAfterMs;
+  constructor(message, opts) {
+    super(message);
+    this.name = "HttpError";
+    this.status = opts.status;
+    this.url = opts.url;
+    this.attempts = opts.attempts;
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
 class ConnectionClosedError extends Error {
   code;
   reason;
@@ -3902,6 +3917,11 @@ class ObservationCache {
   }
 }
 
+// src/jitter.ts
+function jitteredDelayMs(baseMs) {
+  return baseMs + Math.random() * Math.max(baseMs * 0.25, 250);
+}
+
 // src/state/cache.ts
 function copySection(target, source, section) {
   const value = source[section];
@@ -4239,6 +4259,36 @@ function retryAfterMs(err) {
   const seconds = fromDetails ?? (match ? Number(match[1]) : undefined);
   return Math.max(250, (seconds ?? 1) * 1000);
 }
+var AUTH_SECRET_PAYLOAD_FIELDS = new Set(["password", "token", "registration_code", "device_code"]);
+function redactForOnSend(frame) {
+  if (frame.tool !== "spacemolt_auth" || !isRecord(frame.payload))
+    return frame;
+  let redacted;
+  for (const field of AUTH_SECRET_PAYLOAD_FIELDS) {
+    if (field in frame.payload) {
+      redacted ??= { ...frame.payload };
+      redacted[field] = "[redacted]";
+    }
+  }
+  return redacted ? { ...frame, payload: redacted } : frame;
+}
+function redactForOnReceive(frame) {
+  if (frame.type === "registered" && isRecord(frame.payload) && "password" in frame.payload) {
+    return { ...frame, payload: { ...frame.payload, password: "[redacted]" } };
+  }
+  if (frame.type === "result" && isRecord(frame.payload)) {
+    const { structuredContent } = frame.payload;
+    if (isRecord(structuredContent) && typeof structuredContent.device_code === "string" && structuredContent.device_code) {
+      const code = structuredContent.device_code;
+      const result = typeof frame.payload.result === "string" && frame.payload.result.includes(code) ? frame.payload.result.split(code).join("[redacted]") : frame.payload.result;
+      return {
+        ...frame,
+        payload: { ...frame.payload, result, structuredContent: { ...structuredContent, device_code: "[redacted]" } }
+      };
+    }
+  }
+  return frame;
+}
 function requireStructuredContent(result, command) {
   if (result.structuredContent === undefined) {
     throw new SpacemoltError("invalid_response", `${command} returned no structured content`);
@@ -4256,6 +4306,8 @@ class Account {
   seedState;
   url;
   webSocketFactory;
+  onSend;
+  onReceive;
   reconnectConfig;
   credentialsProvider;
   fetchImpl;
@@ -4268,6 +4320,7 @@ class Account {
   requestSeq = 0;
   _welcome = null;
   _authenticated = false;
+  reconnectsPending = 0;
   _loginPayload = null;
   _currentTick = 0;
   _commands = null;
@@ -4287,10 +4340,13 @@ class Account {
   reconnectedListeners = new Set;
   reconnectingListeners = new Set;
   disconnectedListeners = new Set;
+  rateLimitedListeners = new Set;
   constructor(opts = {}) {
     this.seedState = opts.seedState ?? true;
     this.url = opts.url ?? DEFAULT_URL;
     this.webSocketFactory = opts.webSocketFactory;
+    this.onSend = opts.onSend;
+    this.onReceive = opts.onReceive;
     this.credentialsProvider = opts.credentials;
     this.fetchImpl = opts.fetchImpl;
     this.maxRateLimitRetries = opts.maxRateLimitRetries ?? 5;
@@ -4384,37 +4440,47 @@ class Account {
     return this.open();
   }
   async open() {
+    const socket = this.socket;
     this._welcome = null;
-    await this.socket.connect();
+    await socket.connect();
     if (this._welcome)
       return this._welcome;
+    let waiter;
     const waitForWelcome = new Promise((resolve, reject) => {
-      this.welcomeWaiter = { resolve, reject };
+      waiter = { resolve, reject };
+      this.welcomeWaiter = waiter;
     });
     try {
       return await withTimeout(waitForWelcome, this.connectTimeoutMs, `No welcome frame received within ${this.connectTimeoutMs}ms`);
     } catch (err) {
-      this.welcomeWaiter = null;
-      this.socket.close();
+      if (waiter && this.welcomeWaiter === waiter)
+        this.welcomeWaiter = null;
+      if (this.socket === socket)
+        socket.close();
       throw err;
     }
   }
   async register(params) {
+    let authEntry;
     const registerPromise = new Promise((resolve, reject) => {
-      this.beginAuth((state, registered) => {
+      const accepted = this.beginAuth((state, registered) => {
         if (!registered) {
           reject(new SpacemoltError("missing_credentials", "register succeeded but no credentials frame was received"));
           return;
         }
         resolve({ password: registered.password, player_id: registered.player_id, state });
       }, reject);
-      this.sendFrame("spacemolt_auth", "register", { ...params }, this.nextRequestId());
+      if (accepted)
+        authEntry = this.pendingAuth ?? undefined;
+      if (accepted)
+        this.sendFrame("spacemolt_auth", "register", { ...params }, this.nextRequestId());
     });
     let result;
     try {
       result = await withTimeout(registerPromise, this.connectTimeoutMs, `No register response received within ${this.connectTimeoutMs}ms`);
     } catch (err) {
-      this.pendingAuth = null;
+      if (authEntry && this.pendingAuth === authEntry)
+        this.pendingAuth = null;
       throw err;
     }
     this._loginPayload = result.state;
@@ -4428,7 +4494,7 @@ class Account {
     return this.authExchange("login_token", { token });
   }
   authenticate(creds) {
-    return this.withRateLimitRetry(() => this.authenticateOnce(creds));
+    return this.withRateLimitRetry("authenticate", () => this.authenticateOnce(creds));
   }
   async authenticateOnce(creds) {
     switch (creds.kind) {
@@ -4486,7 +4552,7 @@ class Account {
     this._authenticated = false;
   }
   query(tool, action, payload, requestId) {
-    return this.withRateLimitRetry(async () => {
+    return this.withRateLimitRetry(`${tool}.${action}`, async () => {
       const id = this.claimRequestId(requestId);
       const promise = this.correlator.awaitQuery(id);
       try {
@@ -4500,7 +4566,7 @@ class Account {
   }
   mutate(tool, action, payload, onAck, requestId) {
     const mutationTimeoutMs = TRANSIT_ACTIONS.has(`${tool}/${action}`) ? this.mutationTimeoutMs : this.fastMutationTimeoutMs;
-    return this.enqueueMutation(() => this.withRateLimitRetry(() => {
+    return this.enqueueMutation(() => this.withRateLimitRetry(`${tool}.${action}`, () => {
       const id = this.claimRequestId(requestId);
       return this.awaitMutationWithTimeout(id, mutationTimeoutMs, () => this.sendFrame(tool, action, payload, id), onAck);
     }));
@@ -4779,6 +4845,12 @@ class Account {
       this.reconnectingListeners.delete(listener);
     };
   }
+  onRateLimited(listener) {
+    this.rateLimitedListeners.add(listener);
+    return () => {
+      this.rateLimitedListeners.delete(listener);
+    };
+  }
   onDisconnected(listener) {
     this.disconnectedListeners.add(listener);
     return () => {
@@ -4786,15 +4858,20 @@ class Account {
     };
   }
   async authExchange(action, payload) {
+    let authEntry;
     const authPromise = new Promise((resolve, reject) => {
-      this.beginAuth(resolve, reject);
-      this.sendFrame("spacemolt_auth", action, payload, this.nextRequestId());
+      const accepted = this.beginAuth(resolve, reject);
+      if (accepted)
+        authEntry = this.pendingAuth ?? undefined;
+      if (accepted)
+        this.sendFrame("spacemolt_auth", action, payload, this.nextRequestId());
     });
     let state;
     try {
       state = await withTimeout(authPromise, this.connectTimeoutMs, `No auth response received within ${this.connectTimeoutMs}ms`);
     } catch (err) {
-      this.pendingAuth = null;
+      if (authEntry && this.pendingAuth === authEntry)
+        this.pendingAuth = null;
       throw err;
     }
     this._loginPayload = state;
@@ -4811,16 +4888,32 @@ class Account {
   beginAuth(onLoggedIn, onError) {
     if (this.pendingAuth) {
       onError(new SpacemoltError("auth_in_progress", "another auth exchange is already in flight"));
-      return;
+      return false;
     }
     if (this._authenticated) {
       onError(new SpacemoltError("already_authenticated", "this connection is already authenticated"));
-      return;
+      return false;
     }
     this.pendingAuth = { onLoggedIn, onError };
+    return true;
   }
   sendFrame(tool, action, payload, requestId) {
-    this.socket.send({ tool, action, ...payload ? { payload } : {}, request_id: requestId });
+    const isAuthHandshake = tool === "spacemolt_auth" && action !== "logout";
+    if (this.reconnectsPending > 0 && !this._authenticated && !isAuthHandshake) {
+      throw new ConnectionClosedError("cannot send: account is reconnecting");
+    }
+    const frame = { tool, action, ...payload ? { payload } : {}, request_id: requestId };
+    this.callHook(this.onSend, "onSend", redactForOnSend(frame));
+    this.socket.send(frame);
+  }
+  callHook(hook, label, ...args) {
+    if (!hook)
+      return;
+    try {
+      hook(...args);
+    } catch (err) {
+      console.warn(`[spacemolt] ${label} hook threw: ${err}`);
+    }
   }
   nextRequestId() {
     let id = `r${++this.requestSeq}`;
@@ -4837,6 +4930,7 @@ class Account {
     return requestId;
   }
   routeFrame(frame) {
+    this.callHook(this.onReceive, "onReceive", redactForOnReceive(frame));
     if (isRecord(frame.payload))
       this.observeTick(frame.payload.tick);
     switch (frame.type) {
@@ -4924,10 +5018,9 @@ class Account {
   warnMalformedFrame(frame) {
     console.warn(`[spacemolt] dropped malformed ${frame.type} frame`);
   }
-  handleClose(err) {
+  failPendingWork(err) {
     this._authenticated = false;
     this.correlator.rejectAll(err);
-    this.emitter.closeStreams();
     if (this.welcomeWaiter) {
       const waiter = this.welcomeWaiter;
       this.welcomeWaiter = null;
@@ -4938,6 +5031,10 @@ class Account {
       this.pendingAuth = null;
       auth.onError(err);
     }
+  }
+  handleClose(err) {
+    this.failPendingWork(err);
+    this.emitter.closeStreams();
     if (this.reconnecting) {
       this.attemptClose = err;
       return;
@@ -5001,11 +5098,17 @@ class Account {
     };
     stopIfClosed();
     this.socket.close();
-    this.makeSocket();
-    await this.open();
-    stopIfClosed();
-    await this.authenticate(await this.credentialsProvider());
-    stopIfClosed();
+    this.reconnectsPending++;
+    this.failPendingWork(new ConnectionClosedError("account is reconnecting"));
+    try {
+      this.makeSocket();
+      await this.open();
+      stopIfClosed();
+      await this.authenticate(await this.credentialsProvider());
+      stopIfClosed();
+    } finally {
+      this.reconnectsPending--;
+    }
     await this.resubscribe();
   }
   async resubscribe() {
@@ -5020,13 +5123,15 @@ class Account {
       } catch {}
     }
   }
-  async withRateLimitRetry(fn) {
+  async withRateLimitRetry(command, fn) {
     for (let attempt = 0;; attempt++) {
       try {
         return await fn();
       } catch (err) {
         if (err instanceof SpacemoltError && err.code === "rate_limited" && attempt < this.maxRateLimitRetries) {
-          await delay(retryAfterMs(err));
+          const delayMs = jitteredDelayMs(retryAfterMs(err));
+          notifyListeners(this.rateLimitedListeners, "onRateLimited", { command, attempt: attempt + 1, delayMs });
+          await delay(delayMs);
           continue;
         }
         throw err;
@@ -5062,6 +5167,46 @@ class MemoryCredentialStore {
   }
 }
 
+// src/data/http.ts
+var MAX_RETRIES = 3;
+var BASE_BACKOFF_MS = 500;
+var MAX_RETRY_WAIT_MS = 60000;
+var delay2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function parseRetryAfterMs(header) {
+  if (!header)
+    return;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds))
+    return Math.max(0, seconds * 1000);
+  const dateMs = Date.parse(header);
+  return Number.isNaN(dateMs) ? undefined : Math.max(0, dateMs - Date.now());
+}
+async function httpGet(url, opts = {}) {
+  const { headers, timeoutMs = 30000, fetchImpl = fetch, okStatuses = [], maxRetryWaitMs = MAX_RETRY_WAIT_MS } = opts;
+  let totalBaseWaitMs = 0;
+  for (let attempt = 1;; attempt++) {
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok || okStatuses.includes(res.status))
+      return res;
+    const retryAfterMs = parseRetryAfterMs(res.headers.get("retry-after"));
+    const baseWaitMs = retryAfterMs ?? BASE_BACKOFF_MS * 2 ** (attempt - 1);
+    const retryable = (res.status === 429 || res.status === 503) && totalBaseWaitMs + baseWaitMs <= maxRetryWaitMs;
+    if (retryable && attempt <= MAX_RETRIES) {
+      totalBaseWaitMs += baseWaitMs;
+      await res.body?.cancel().catch(() => {});
+      await delay2(jitteredDelayMs(baseWaitMs));
+      continue;
+    }
+    await res.body?.cancel().catch(() => {});
+    throw new HttpError(`GET ${url} -> ${res.status} ${res.statusText}`, {
+      status: res.status,
+      url,
+      attempts: attempt,
+      retryAfterMs
+    });
+  }
+}
+
 // src/data/catalog.ts
 function catalogEntries(value) {
   return Array.isArray(value) ? value.filter(isRecord) : [];
@@ -5082,16 +5227,14 @@ function normalizeCatalog(value) {
     hidden_faction_achievement_count: typeof data.hidden_faction_achievement_count === "number" ? data.hidden_faction_achievement_count : 0
   };
 }
-async function fetchCatalogConditional(httpBaseUrl, etag) {
+async function fetchCatalogConditional(httpBaseUrl, etag, opts = {}) {
   const url = `${httpBaseUrl.replace(/\/$/, "")}/api/catalog.json`;
   const headers = { accept: "application/json" };
   if (etag)
     headers["if-none-match"] = etag;
-  const res = await fetch(url, { headers });
+  const res = await httpGet(url, { headers, fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs, okStatuses: [304] });
   if (res.status === 304)
     return { notModified: true, etag };
-  if (!res.ok)
-    throw new Error(`GET ${url} -> ${res.status} ${res.statusText}`);
   const data = await res.json();
   return {
     notModified: false,
@@ -5099,8 +5242,8 @@ async function fetchCatalogConditional(httpBaseUrl, etag) {
     etag: res.headers?.get?.("etag") ?? undefined
   };
 }
-async function fetchCatalog(httpBaseUrl) {
-  const { catalog } = await fetchCatalogConditional(httpBaseUrl);
+async function fetchCatalog(httpBaseUrl, opts = {}) {
+  const { catalog } = await fetchCatalogConditional(httpBaseUrl, undefined, opts);
   if (!catalog)
     throw new Error("unconditional catalog fetch returned no catalog");
   return catalog;
@@ -5125,14 +5268,14 @@ class CatalogCache {
     this.facilitiesById = index(catalog.facilities);
     this.achievementsById = index([...catalog.achievements, ...catalog.faction_achievements]);
   }
-  static async load(httpBaseUrl) {
-    const { catalog, etag } = await fetchCatalogConditional(httpBaseUrl);
+  static async load(httpBaseUrl, opts = {}) {
+    const { catalog, etag } = await fetchCatalogConditional(httpBaseUrl, undefined, opts);
     if (!catalog)
       throw new Error("unconditional catalog fetch returned no catalog");
     return new CatalogCache(catalog, etag);
   }
-  async revalidate(httpBaseUrl) {
-    const result = await fetchCatalogConditional(httpBaseUrl, this.etag);
+  async revalidate(httpBaseUrl, opts = {}) {
+    const result = await fetchCatalogConditional(httpBaseUrl, this.etag, opts);
     if (result.notModified)
       return this;
     if (!result.catalog)
@@ -5199,11 +5342,13 @@ function index(entries) {
 }
 
 // src/data/map.ts
-async function fetchMap(httpBaseUrl) {
+async function fetchMap(httpBaseUrl, opts = {}) {
   const url = `${httpBaseUrl.replace(/\/$/, "")}/api/map`;
-  const res = await fetch(url, { headers: { accept: "application/json" } });
-  if (!res.ok)
-    throw new Error(`GET ${url} -> ${res.status} ${res.statusText}`);
+  const res = await httpGet(url, {
+    headers: { accept: "application/json" },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs
+  });
   const data = requireRecord(await res.json(), "map response");
   const systems = Array.isArray(data.systems) ? data.systems.filter((system) => isRecord(system)) : [];
   const empires = isRecord(data.empires) ? Object.fromEntries(Object.entries(data.empires).filter((entry) => typeof entry[1] === "string")) : {};
@@ -5222,8 +5367,8 @@ class MapCache {
         this.bySystemId.set(id, system);
     }
   }
-  static async load(httpBaseUrl) {
-    return new MapCache(await fetchMap(httpBaseUrl));
+  static async load(httpBaseUrl, opts = {}) {
+    return new MapCache(await fetchMap(httpBaseUrl, opts));
   }
   system(id) {
     return this.bySystemId.get(id);
@@ -5245,11 +5390,39 @@ function httpBaseFromWs(wsUrl) {
   }
 }
 
+// src/data/mobile-base.ts
+async function fetchMobileBase(httpBaseUrl, opts = {}) {
+  const url = `${httpBaseUrl.replace(/\/$/, "")}/wheres-mobile-base`;
+  const res = await httpGet(url, {
+    headers: { accept: "application/json" },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs
+  });
+  const data = requireRecord(await res.json(), "mobile base response");
+  if (typeof data.system !== "string")
+    throw new Error("mobile base response is missing a system id");
+  return { system: data.system };
+}
+
+// src/data/stations.ts
+async function fetchStations(httpBaseUrl, opts = {}) {
+  const url = `${httpBaseUrl.replace(/\/$/, "")}/api/stations`;
+  const res = await httpGet(url, {
+    headers: { accept: "application/json" },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs
+  });
+  const data = requireRecord(await res.json(), "stations response");
+  const stations = Array.isArray(data.stations) ? data.stations.filter(isRecord) : [];
+  const empires = Array.isArray(data.empires) ? data.empires.filter((empire) => isRecord(empire) && typeof empire.id === "string" && typeof empire.name === "string") : [];
+  return { stations, empires };
+}
+
 // src/client.ts
 var DEFAULT_HTTP_BASE = "https://game.spacemolt.com";
 var DEFAULT_CONNECT_RETRY = { maxRetries: 8, baseDelayMs: 2000, maxDelayMs: 60000 };
 var CONNECT_RATE_WINDOW_MS = 60000;
-var delay2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var delay3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 class SpacemoltClient {
   opts;
@@ -5293,21 +5466,30 @@ class SpacemoltClient {
   get httpBaseUrl() {
     return this.opts.httpBaseUrl ?? (this.opts.url ? httpBaseFromWs(this.opts.url) : DEFAULT_HTTP_BASE);
   }
+  get httpOptions() {
+    return { fetchImpl: this.opts.fetchImpl, timeoutMs: this.opts.httpTimeoutMs };
+  }
   async catalog(force = false) {
     const maxAgeMs = this.opts.catalogMaxAgeMs ?? 3600000;
     const cached = this.catalogCache;
     const fresh = cached && !force && Date.now() - this.catalogFetchedAt < maxAgeMs;
     if (fresh)
       return cached;
-    this.catalogCache = !this.catalogCache || force ? await CatalogCache.load(this.httpBaseUrl) : await this.catalogCache.revalidate(this.httpBaseUrl);
+    this.catalogCache = !this.catalogCache || force ? await CatalogCache.load(this.httpBaseUrl, this.httpOptions) : await this.catalogCache.revalidate(this.httpBaseUrl, this.httpOptions);
     this.catalogFetchedAt = Date.now();
     return this.catalogCache;
   }
   async map(force = false) {
     if (force || !this.mapCache)
-      this.mapCache = await MapCache.load(this.httpBaseUrl);
+      this.mapCache = await MapCache.load(this.httpBaseUrl, this.httpOptions);
     return this.mapCache;
   }
+  stations() {
+    return fetchStations(this.httpBaseUrl, this.httpOptions);
+  }
+  mobileBase() {
+    return fetchMobileBase(this.httpBaseUrl, this.httpOptions);
+  }
   get credentialStore() {
     return this.store;
   }
@@ -5355,7 +5537,7 @@ class SpacemoltClient {
         lastErr = err;
         if (i < retry.maxRetries) {
           const retryAfterMs = retryAfterMsFromClose(err);
-          await delay2(retryAfterMs ?? Math.min(retry.baseDelayMs * 2 ** i, retry.maxDelayMs));
+          await delay3(retryAfterMs ?? Math.min(retry.baseDelayMs * 2 ** i, retry.maxDelayMs));
         }
       }
     }
@@ -5458,10 +5640,10 @@ class SpacemoltClient {
     while (this.rateLimitedQueue.length > 0) {
       if (!isFirst) {
         if (batchSize > 0 && ranInCurrentBatch >= batchSize) {
-          await delay2(batchWaitMs);
+          await delay3(batchWaitMs);
           ranInCurrentBatch = 0;
         } else if (stagger > 0) {
-          await delay2(stagger);
+          await delay3(stagger);
         }
       }
       isFirst = false;
@@ -5520,6 +5702,8 @@ class SpacemoltClient {
       id,
       url: this.opts.url,
       webSocketFactory: this.opts.webSocketFactory,
+      onSend: this.opts.onSend && ((f) => this.opts.onSend?.(id, f)),
+      onReceive: this.opts.onReceive && ((f) => this.opts.onReceive?.(id, f)),
       seedState: this.opts.seedState,
       reconnect: false,
       fetchImpl: this.opts.fetchImpl,
@@ -5542,28 +5726,6 @@ class SpacemoltClient {
     }
   }
 }
-// src/data/stations.ts
-async function fetchStations(httpBaseUrl) {
-  const url = `${httpBaseUrl.replace(/\/$/, "")}/api/stations`;
-  const res = await fetch(url, { headers: { accept: "application/json" } });
-  if (!res.ok)
-    throw new Error(`GET ${url} -> ${res.status} ${res.statusText}`);
-  const data = requireRecord(await res.json(), "stations response");
-  const stations = Array.isArray(data.stations) ? data.stations.filter(isRecord) : [];
-  const empires = Array.isArray(data.empires) ? data.empires.filter((empire) => isRecord(empire) && typeof empire.id === "string" && typeof empire.name === "string") : [];
-  return { stations, empires };
-}
-// src/data/mobile-base.ts
-async function fetchMobileBase(httpBaseUrl) {
-  const url = `${httpBaseUrl.replace(/\/$/, "")}/wheres-mobile-base`;
-  const res = await fetch(url, { headers: { accept: "application/json" } });
-  if (!res.ok)
-    throw new Error(`GET ${url} -> ${res.status} ${res.statusText}`);
-  const data = requireRecord(await res.json(), "mobile base response");
-  if (typeof data.system !== "string")
-    throw new Error("mobile base response is missing a system id");
-  return { system: data.system };
-}
 // src/generated/notifications.gen.ts
 var TYPED_NOTIFICATION_TYPES = [
   "achievement_unlocked",
@@ -5678,6 +5840,7 @@ export {
   EventStream,
   FLEET_PUSH_ACTIONS,
   GENERATED_SPEC_VERSION,
+  HttpError,
   MapCache,
   MarketCache,
   MemoryCredentialStore,

package/dist/jitter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Adds random jitter to a retry delay, so multiple callers retrying together
+ * (e.g. a fleet of accounts sharing a per-IP rate limit) don't all wake up
+ * and retry in the same instant. Extra is uniform in `[0, max(25% of base,
+ * 250ms))`. Shared by the WebSocket rate-limit retry (`account.ts`) and the
+ * HTTP retry (`data/http.ts`).
+ */
+export declare function jitteredDelayMs(baseMs: number): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacemolt/lib",
-  "version": "15.1.0",
+  "version": "15.2.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",