@spacemolt/lib 4.6.0

package/dist/client.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Multi-account client.
+ *
+ * Manages N authenticated `Account` connections, persisting their credentials
+ * through a pluggable `CredentialStore`. Connecting many accounts is staggered
+ * to stay under the server's per-IP login/connection rate limits — the server
+ * itself advises "reuse one session per bot for its lifetime", so the intended
+ * pattern is: add accounts once, `connectAll()` at startup, keep them open.
+ */
+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 { ReconnectOptions, RegisterParams, RegisterResult } from './account.js';
+import { CatalogCache } from './data/catalog.js';
+import { MapCache } from './data/map.js';
+import { type ClerkPlayer } from './auth/clerk.js';
+import { type ConnectionClosedError } from './errors.js';
+export interface SpacemoltClientOptions {
+    /** WebSocket URL of the v2 endpoint. */
+    url?: string;
+    /** Where credentials live. Defaults to an in-memory store. */
+    store?: CredentialStore;
+    /** Inject a WebSocket implementation (tests, custom runtimes). */
+    webSocketFactory?: WebSocketFactory;
+    /** Seed each account's state cache after auth (see Account). Default true. */
+    seedState?: boolean;
+    /**
+     * Delay between connecting accounts. Default is derived from
+     * `connectBatchSize` (`60_000 / connectBatchSize` — 600ms for the default
+     * batch size of 100), guaranteeing a batch can't finish in under a minute
+     * regardless of how fast each connect() actually completes — a flat
+     * 250ms doesn't guarantee that (see `connectIds`). Set explicitly to
+     * override that computed default with your own value (trusted as-is, not
+     * a floor) — e.g. for a smaller test fleet where finishing fast is fine.
+     */
+    connectStaggerMs?: number;
+    /**
+     * Max accounts to connect before pausing for `connectBatchWaitMs`, so a
+     * fleet never actually trips the server's per-IP WS-connection rate limit
+     * (hitting it risks an IP-level timeout/ban on repeat offense — better to
+     * never ask). Matches the server's default connection cap (100/min), so a
+     * fleet at or under this size behaves exactly like a single stagger pass,
+     * same as before; a larger fleet connects in batches of this size instead.
+     * Default 100.
+     */
+    connectBatchSize?: number;
+    /**
+     * Pause between batches once `connectBatchSize` is exceeded, letting the
+     * server's per-IP rate-limit window (1 minute by default) fully roll over
+     * before the next batch starts. Default 65000 (65s — a margin over the
+     * server's 1-minute window).
+     */
+    connectBatchWaitMs?: number;
+    /**
+     * Reconnect an account after an unexpected disconnect (a dropped
+     * WebSocket after it was already connected — see `connectRetry` for the
+     * initial connect instead). Default `true`. Driven by the client itself
+     * (not each `Account`'s own standalone reconnect logic), reconnecting the
+     * *same* `Account` instance in place (`Account.reconnectOnce` — fresh
+     * socket, re-authenticated, subscriptions restored) rather than replacing
+     * it, so anything holding a direct reference (e.g. a running loop) keeps
+     * working transparently. Paced through the same rate-limited queue used
+     * for the initial connect — see `handleAccountDisconnected` — so a mass
+     * disconnect (e.g. every account dropped at once by a game-server restart)
+     * reconnects the fleet through the same `connectBatchSize`/
+     * `connectStaggerMs`/`connectBatchWaitMs` pacing, instead of every account
+     * racing an independent timer. Pass `false` to leave a dropped account
+     * disconnected instead (see `onAccountDisconnected`). If you pass a
+     * `ReconnectOptions` object, only its truthiness matters — reconnect
+     * pacing comes from `connectRetry` (the same backoff config used for the
+     * initial connect), not this option's own `maxRetries`/`baseDelayMs`/
+     * `maxDelayMs`. Never reconnects after a deliberate `close()`/`remove()`,
+     * a `session_replaced`, or an `auth_timeout`. Token-only accounts can't
+     * reconnect (the token is single-use).
+     */
+    reconnect?: boolean | ReconnectOptions;
+    /** HTTP origin for bulk data fetches. Defaults to the origin of `url`. */
+    httpBaseUrl?: string;
+    /**
+     * Clerk API key for `connectOwned()` / `listOwnedPlayers()` — connect every
+     * game account the Clerk user owns without storing per-account passwords.
+     * Generate one from the website; keep it secret.
+     */
+    clerkApiKey?: string;
+    /** Inject a `fetch` implementation (tests, custom runtimes). */
+    fetchImpl?: typeof fetch;
+    /**
+     * 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.
+     * Without this, a connection the server silently never completes (accepts
+     * the WS upgrade but never responds) hangs forever with no error and no
+     * retry — this can't be told apart from "still connecting" from the
+     * outside. Default 15000 (15s — generous over the ~150-300ms a healthy
+     * connect actually takes, per live measurement).
+     */
+    connectTimeoutMs?: number;
+    /**
+     * How long to wait for a query's response before giving up. Unlike a
+     * mutation (which can legitimately take minutes, e.g. a travel/jump's
+     * transit time), a query has no legitimate reason to take long — bounding
+     * it turns a silently-dropped response into a clean error instead of a
+     * permanent hang. Default 15000 (15s).
+     */
+    queryTimeoutMs?: number;
+    /**
+     * How long to wait, after a mutation's pending ack arrives, for its final
+     * `action_result`/`action_error` outcome before giving up. Generous by
+     * design — some mutations legitimately take many ticks (a jump/travel's
+     * transit time is distance-based and can run minutes) — but not infinite:
+     * without this, a single silently-dropped outcome frame hangs forever AND
+     * wedges every subsequent mutation on that account behind it (mutations
+     * are serialized per account). Default 600000 (10 minutes).
+     */
+    mutationTimeoutMs?: number;
+    /**
+     * Fallback safety net: retry a failed `connect()` (the raw WebSocket
+     * handshake, before any auth frame) with backoff instead of dropping the
+     * account. `connectBatchSize`/`connectBatchWaitMs` above are the primary
+     * defense — they're sized to avoid ever tripping the server's per-IP
+     * WS-connection rate limit in the first place — but this covers the
+     * unexpected case anyway (e.g. other traffic sharing the IP eating into
+     * the budget), since a 429 on the handshake surfaces as a plain
+     * `ConnectionClosedError` — not a `SpacemoltError` with `code:
+     * 'rate_limited'` — so it can't be told apart from a genuine connection
+     * failure and isn't covered by `Account`'s targeted rate-limit retry.
+     * Default `true` (enabled). Pass `false` to disable and fail fast instead.
+     */
+    connectRetry?: boolean | ReconnectOptions;
+}
+export declare class SpacemoltClient {
+    private readonly opts;
+    private readonly store;
+    private readonly connected;
+    private catalogCache?;
+    private mapCache?;
+    private clerkSource?;
+    private readonly accountConnectedListeners;
+    private readonly accountReconnectedListeners;
+    private readonly accountDisconnectedListeners;
+    /** Paced by connectBatchSize/connectStaggerMs/connectBatchWaitMs — the same limiter drains both the initial fleet connect and later reconnects, see `enqueueRateLimited`. */
+    private readonly rateLimitedQueue;
+    private rateLimitedQueueDraining;
+    /**
+     * Ids currently mid-reconnect. Guards against a socket dropping again
+     * *during* `reconnectAccountInPlace` (e.g. another rate-limit close before
+     * auth completes) re-firing `handleAccountDisconnected` and enqueuing a
+     * second, parallel reconnect chain for the same id — the drop instead
+     * surfaces as a failure inside the one already-running `withConnectRetry`
+     * loop, which retries it itself.
+     */
+    private readonly reconnectingIds;
+    constructor(opts?: SpacemoltClientOptions);
+    /**
+     * Fires the first time an id becomes a connected+authenticated `Account`
+     * instance — the initial connect (`connect`/`connectAll`/`connectOwned`/
+     * `register`). Does NOT fire again for a later reconnect after an
+     * unexpected disconnect — that reuses the same instance in place (see
+     * `Account.reconnectOnce`) rather than creating a new one, so there's
+     * nothing new to index/re-wire; see `onAccountReconnected` for that event
+     * instead. Unlike `connectAll`'s/`connectOwned`'s per-call `onConnect`
+     * option (scoped to that one call), this is a persistent subscription.
+     * Returns an unsubscribe function.
+     */
+    onAccountConnected(listener: (account: Account) => void): () => void;
+    /**
+     * Fires after an already-connected account's connection is restored
+     * following an unexpected disconnect — the same `Account` instance
+     * throughout, reconnected in place. Purely informational (e.g. logging);
+     * nothing needs re-indexing since the instance never changed. Returns an
+     * unsubscribe function.
+     */
+    onAccountReconnected(listener: (account: Account) => void): () => void;
+    /**
+     * Fires when an account is dropped for good: a terminal close (session
+     * replaced by another connection, or an auth timeout) that this client
+     * deliberately does not reconnect after, or a reconnect attempt that
+     * exhausted its retries. Silent otherwise today — this is the only
+     * visibility a caller has into that. Returns an unsubscribe function.
+     */
+    onAccountDisconnected(listener: (id: string, err: ConnectionClosedError) => void): () => void;
+    private notifyAccountConnected;
+    private notifyAccountReconnected;
+    private notifyAccountDisconnected;
+    /** HTTP origin used for bulk data fetches (catalog, map). */
+    get httpBaseUrl(): string;
+    /** The bulk catalog, fetched once and cached. Pass `force` to refetch. */
+    catalog(force?: boolean): Promise<CatalogCache>;
+    /** The static galaxy map, fetched once and cached. Pass `force` to refetch. */
+    map(force?: boolean): Promise<MapCache>;
+    /** The credential store backing this client. */
+    get credentialStore(): CredentialStore;
+    /** Persist username/password credentials. Returns the account id (username). */
+    addLogin(username: string, password: string): Promise<string>;
+    /** Persist a login-token credential under an explicit id. */
+    addToken(id: string, token: string): Promise<string>;
+    /**
+     * Register a brand-new account: connect, register, and persist the generated
+     * password as login credentials (keyed by username) for future sessions.
+     */
+    register(params: RegisterParams): Promise<{
+        account: Account;
+        result: RegisterResult;
+    }>;
+    /** Resolves `connectRetry` into a concrete backoff config. */
+    private connectRetryConfig;
+    /**
+     * Retry `attempt` with the shared `connectRetry` backoff, honoring a 4003
+     * `connection_rate_limited` close's `retry_after` hint over the
+     * exponential fallback. Shared by the initial connect (`connect`) and an
+     * in-place reconnect (`reconnectAccountInPlace`) so both back off
+     * identically.
+     */
+    private withConnectRetry;
+    /**
+     * Connect and authenticate one stored account. Idempotent per id.
+     *
+     * Retries the whole connect+authenticate sequence with backoff on failure
+     * (see `connectRetry`) — a fleet large enough to exceed the per-IP
+     * WS-connection rate limit sees some accounts rejected at the handshake,
+     * which self-heals once the server's rate-limit window rolls over.
+     */
+    connect(id: string): Promise<Account>;
+    /** Connect every stored account, staggered to respect rate limits. */
+    connectAll(opts?: {
+        onConnect?: (account: Account) => void;
+    }): Promise<Account[]>;
+    /** List the player accounts the Clerk user owns. Requires `clerkApiKey`. */
+    listOwnedPlayers(): Promise<ClerkPlayer[]>;
+    /**
+     * Connect every account the Clerk user owns (optionally filtered), staggered
+     * to respect rate limits. Stores a `clerk` credential per player — each
+     * account mints a fresh single-use WS token on connect and reconnect, so no
+     * passwords are persisted. Requires `clerkApiKey`.
+     *
+     * A fleet-wide call can legitimately take minutes (see `connectIds`'s
+     * pacing) — `onConnect` fires as each account finishes, so a caller can
+     * index/use accounts incrementally instead of only after the whole batch
+     * settles (the returned promise still doesn't resolve until every account
+     * has been attempted).
+     */
+    connectOwned(opts?: {
+        filter?: (player: ClerkPlayer) => boolean;
+        onConnect?: (account: Account) => void;
+    }): Promise<Account[]>;
+    private requireClerkSource;
+    /**
+     * Connect the given stored ids, staggered to respect rate limits. At or
+     * under `connectBatchSize` accounts this is a single stagger pass — the
+     * same behavior as before batching existed. Past that, it pauses for
+     * `connectBatchWaitMs` between batches so the fleet never actually asks
+     * for more connections than the server's per-IP window allows. A single
+     * account failing to connect must not abort the rest of the batch — it's
+     * logged and skipped so the caller still gets every account that succeeded.
+     *
+     * `onConnect` fires synchronously as each id finishes (success only) so a
+     * caller managing many accounts (e.g. indexing them for lookup) doesn't
+     * have to wait for the entire — potentially minutes-long — batch before
+     * any single account becomes usable.
+     *
+     * Pacing itself is `enqueueRateLimited` — the same queue a later
+     * reconnect (see `handleAccountDisconnected`) competes for a slot in, so a
+     * reconnect landing mid-batch is paced fairly alongside the rest of the
+     * fleet instead of racing it on a separate timer.
+     */
+    private connectIds;
+    /**
+     * Enqueues `task`, paced by `connectBatchSize`/`connectStaggerMs`/
+     * `connectBatchWaitMs` — the single rate limiter shared by the initial
+     * fleet connect (`connectIds`) and every later reconnect
+     * (`handleAccountDisconnected`), so the server's per-IP WS-connection cap
+     * is respected by one mechanism, not a parallel one for each case. Returns
+     * a promise settling with `task`'s own outcome once its turn comes up.
+     */
+    private enqueueRateLimited;
+    private drainRateLimitedQueue;
+    /** The connected account for an id, if connected. */
+    account(id: string): Account | undefined;
+    /** All currently-connected accounts. */
+    accounts(): Account[];
+    /** Ids of all currently-connected accounts. */
+    ids(): string[];
+    /** Close and forget an account, and remove its stored credentials. */
+    remove(id: string): Promise<void>;
+    /** Close every connection (credentials remain in the store). */
+    closeAll(): void;
+    /**
+     * Reconnection for a client-managed account is driven here, not by the
+     * `Account`'s own (disabled — see `createAccount`) reconnect logic: an
+     * unexpected disconnect closes every affected account at once (e.g. a
+     * game-server restart), and reconnecting through the same rate-limited
+     * queue used for the initial connect — instead of each account racing its
+     * own independent timer — is what keeps a mass reconnect from re-tripping
+     * the server's per-IP WS-connection rate limit right as it recovers.
+     *
+     * Reconnects in place (`Account.reconnectOnce`, same instance) rather than
+     * replacing the account with a new one: anything holding a direct
+     * reference to this `Account` (e.g. a running loop, which captures it once
+     * at start) keeps working transparently once the connection is restored,
+     * instead of being welded to a now-dead instance nobody is driving.
+     */
+    private handleAccountDisconnected;
+    private createAccount;
+    private capturePlayerId;
+}
+export type { AuthCredentials, CredentialStore, StoredAccount };

package/dist/data/catalog.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Local copy of the bulk game catalog (`GET /api/catalog.json`).
+ *
+ * Reference data — ships, items, recipes, skills, facilities — that changes
+ * only on a server release. Fetched once over HTTP and cached; the entry
+ * shapes aren't in the v2 OpenAPI spec, so they're typed loosely with `id`-keyed
+ * lookups. Public, ETag-cached, ~1h max-age on the server.
+ */
+export interface CatalogEntry {
+    id?: string;
+    [key: string]: unknown;
+}
+export interface Catalog {
+    version?: string;
+    ships: CatalogEntry[];
+    items: CatalogEntry[];
+    recipes: CatalogEntry[];
+    skills: CatalogEntry[];
+    facilities: CatalogEntry[];
+}
+export declare function fetchCatalog(httpBaseUrl: string): Promise<Catalog>;
+export declare class CatalogCache {
+    readonly catalog: Catalog;
+    private readonly indexes;
+    constructor(catalog: Catalog);
+    /** Fetch the catalog and wrap it in a cache. */
+    static load(httpBaseUrl: string): Promise<CatalogCache>;
+    get version(): string | undefined;
+    ship(id: string): CatalogEntry | undefined;
+    item(id: string): CatalogEntry | undefined;
+    recipe(id: string): CatalogEntry | undefined;
+    skill(id: string): CatalogEntry | undefined;
+    facility(id: string): CatalogEntry | undefined;
+    get ships(): readonly CatalogEntry[];
+    get items(): readonly CatalogEntry[];
+    get recipes(): readonly CatalogEntry[];
+    get skills(): readonly CatalogEntry[];
+    get facilities(): readonly CatalogEntry[];
+}

package/dist/data/map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Local copy of the static galaxy map (`GET /api/map`).
+ *
+ * Returns `{ systems, empires }` where `empires` maps an empire id to a display
+ * colour. System shapes aren't in the v2 spec, so they're typed loosely with
+ * `id`-keyed lookups. Static per release; the separate `/api/map/activity`
+ * overlay (online counts, battles) changes frequently and is not cached here.
+ */
+export interface MapSystem {
+    id?: string;
+    [key: string]: unknown;
+}
+export interface GalaxyMap {
+    systems: MapSystem[];
+    empires: Record<string, string>;
+}
+export declare function fetchMap(httpBaseUrl: string): 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>;
+    system(id: string): MapSystem | undefined;
+    get systems(): readonly MapSystem[];
+    /** Empire id -> display colour. */
+    get empires(): Record<string, string>;
+}
+/** Derive the HTTP origin from a WebSocket URL (wss://host/ws/v2 -> https://host). */
+export declare function httpBaseFromWs(wsUrl: string): string;

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/** Error types surfaced by the library. */
+import type { ActionErrorFrame, ErrorFrame } from './protocol.js';
+/**
+ * A server-reported error. Carries the machine-readable `code` from the
+ * server's error/action_error frame plus any structured details.
+ */
+export declare class SpacemoltError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    readonly requestId?: string;
+    /** Set when the failure came from a two-phase mutation outcome. */
+    readonly command?: string;
+    /** Game tick of the failure, for action_error outcomes. */
+    readonly tick?: number;
+    /** On `action_pending` errors: the mutation already queued. */
+    readonly pendingCommand?: string;
+    constructor(code: string, message: string, opts?: {
+        details?: Record<string, unknown>;
+        requestId?: string;
+        command?: string;
+        tick?: number;
+        pendingCommand?: string;
+    });
+}
+export declare function errorFromFrame(frame: ErrorFrame): SpacemoltError;
+export declare function errorFromActionFrame(frame: ActionErrorFrame): SpacemoltError;
+/** Raised against every in-flight request when the socket closes. */
+export declare class ConnectionClosedError extends Error {
+    readonly code?: number;
+    readonly reason?: string;
+    constructor(message?: string, code?: number, reason?: string);
+}
+/**
+ * Custom WS close codes the server documents (as of gameserver v0.471.4):
+ * `4001` session_replaced (another connection took your slot — don't
+ * reconnect, you'd just fight it), `4002` auth_timeout (connected but didn't
+ * authenticate in time), `4003` connection_rate_limited (exceeded the
+ * 100/min-per-IP WS-connection cap — the close reason carries a
+ * `retry_after=<seconds>` hint; honor it before reconnecting).
+ */
+export declare const CLOSE_CODE: {
+    readonly SESSION_REPLACED: 4001;
+    readonly AUTH_TIMEOUT: 4002;
+    readonly CONNECTION_RATE_LIMITED: 4003;
+};
+/**
+ * Parses the `retry_after=<seconds>` hint the server includes on a `4003`
+ * (connection_rate_limited) close reason. Returns the wait time in
+ * milliseconds, or `undefined` if `err` isn't a rate-limited close or carries
+ * no parseable hint.
+ */
+export declare function retryAfterMsFromClose(err: unknown): number | undefined;

package/dist/events/emitter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed event dispatch for server push frames.
+ *
+ * Callbacks (`on`/`onAny`) and async iterators (`stream`/`anyStream`) are both
+ * supported. The Account facade adds the per-msg_type payload typing on top of
+ * this (loosely-typed) core.
+ */
+import type { RawFrame } from '../protocol.js';
+type PayloadHandler = (payload: unknown) => void;
+type FrameHandler = (frame: RawFrame) => void;
+/**
+ * An async iterator over events of one kind, with internal buffering so a slow
+ * consumer doesn't drop frames. Breaking out of a `for await` calls `return()`,
+ * which unsubscribes via the `onClose` callback.
+ */
+export declare class EventStream<T> implements AsyncIterableIterator<T> {
+    private readonly onClose;
+    private readonly buffer;
+    private readonly waiting;
+    private ended;
+    constructor(onClose: () => void);
+    /** Internal: deliver a value to the consumer or buffer it. */
+    push(value: T): void;
+    /** Internal: end the stream (e.g. on disconnect). */
+    end(): void;
+    next(): Promise<IteratorResult<T>>;
+    return(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+export declare class TypedEmitter {
+    private readonly handlers;
+    private readonly anyHandlers;
+    private readonly streams;
+    private readonly anyStreams;
+    /** Listen for one msg_type. Returns an unsubscribe function. */
+    on(type: string, handler: PayloadHandler): () => void;
+    /** Listen for every push frame. Returns an unsubscribe function. */
+    onAny(handler: FrameHandler): () => void;
+    /** Async-iterate one msg_type's payloads. */
+    stream(type: string): EventStream<unknown>;
+    /** Async-iterate every push frame. */
+    anyStream(): EventStream<RawFrame>;
+    /**
+     * Dispatch a push frame to all matching listeners and streams. Each
+     * callback is isolated with try/catch — this is the single funnel every
+     * `account.on(type, ...)`/`onAny` consumer runs through, invoked directly
+     * from `routeFrame`'s `default:` case with nothing above it to contain a
+     * throw. Without isolation, one listener throwing would skip every other
+     * listener/stream for this frame and propagate out through `routeFrame`
+     * into the WebSocket's `message` event handler, which has no try/catch of
+     * its own either.
+     */
+    emit(frame: RawFrame): void;
+    private safeCall;
+    /** End every open stream (on disconnect). Callback listeners are kept. */
+    closeStreams(): void;
+}
+export {};

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

@@ -0,0 +1,25 @@
+/** The gameserver spec version this command surface was generated from. */
+export declare const GENERATED_SPEC_VERSION = "v0.485.0";
+export type ToolName = "spacemolt" | "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_social" | "spacemolt_storage" | "spacemolt_transfer";
+export type ActionName = "abandon_mission" | "accept" | "accept_ally" | "accept_invite" | "accept_mission" | "accept_peace" | "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_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" | "chat" | "claim" | "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" | "deploy" | "deploy_outpost" | "deposit" | "disband" | "disembark" | "dismantle" | "distress_signal" | "dock" | "edit" | "edit_role" | "engage" | "espionage" | "estimate_purchase" | "facility_set_description" | "faction_build" | "faction_dismantle" | "faction_list" | "faction_owned" | "faction_upgrade" | "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" | "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" | "login" | "login_token" | "logout" | "loot" | "mine" | "modify_order" | "mute_notifications" | "name" | "owned" | "personal_build" | "personal_decorate" | "personal_visit" | "petition" | "place_ship_buy_order" | "policies" | "post_mission" | "prepay_tax" | "promote" | "propose_ally" | "propose_peace" | "query_intel" | "query_trade_intel" | "quote" | "read_note" | "recall" | "recycle" | "refit_ship" | "refuel" | "register" | "release" | "reload" | "remove_ally" | "remove_enemy" | "remove_faction" | "remove_player" | "rename_ship" | "renounce" | "repair" | "repair_module" | "retreat" | "rooms" | "scan" | "scan_poi" | "scrap" | "scrap_ship" | "search_systems" | "self_destruct" | "sell" | "sell_ship" | "sell_ship_to_order" | "set_access" | "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" | "supply_commission" | "survey_system" | "switch_ship" | "target" | "tax_estimate" | "tow" | "trade_accept" | "trade_cancel" | "trade_decline" | "trade_intel_status" | "trade_offer" | "transfer" | "travel" | "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 {
+    readonly name: string;
+    readonly type: string;
+    readonly required: boolean;
+    readonly description?: string;
+    readonly enumValues?: readonly string[];
+    readonly positional?: number;
+}
+export interface ActionDef {
+    readonly tool: ToolName;
+    readonly action: ActionName;
+    readonly kind: 'query' | 'mutation';
+    readonly summary?: string;
+    readonly params: readonly ActionParam[];
+    /** TS type name of the query's structuredContent response (queries with a published response schema). */
+    readonly responseType?: string;
+    /** TS type name of the mutation's delta.details response (mutations with a published details schema). */
+    readonly detailsType?: string;
+}
+/** Every v2 command, keyed by "tool/action". */
+export declare const ACTIONS: Record<string, ActionDef>;