@spacemolt/lib 18.0.2 → 18.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -69,8 +69,11 @@ const status = await account.commands.spacemolt.get_status(); // query
69
69
  - **Mutations** queue for the next game tick; `await` resolves when the action
70
70
  actually executes (which may be several ticks later for `travel`/`jump`), with
71
71
  the local state cache already updated. Mutations are serialized one-in-flight
72
- per account and `rate_limited` retries are handled for you — expect a pause
73
- between mutations, not an error.
72
+ per account by default and `rate_limited` retries are handled for you — expect
73
+ a pause between mutations, not an error. Applications that coordinate
74
+ concurrency themselves can pass `serializeMutations: false` to `Account` or
75
+ `SpacemoltClient`; each promise still waits for its own final outcome, and
76
+ server action limits still apply.
74
77
 
75
78
  `COMMANDS.md` marks which kind each command is.
76
79
 
package/COMMANDS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- AUTO-GENERATED by scripts/generate.ts from openapi.json. DO NOT EDIT. -->
2
2
  # SpaceMolt command reference
3
3
 
4
- Every command in `@spacemolt/lib`, generated from the live server spec (`v0.715.2`). **312 commands across 19 tools.**
4
+ Every command in `@spacemolt/lib`, generated from the live server spec (`v0.717.0`). **312 commands across 19 tools.**
5
5
 
6
6
  ## How to call a command
7
7
 
package/README.md CHANGED
@@ -84,7 +84,7 @@ Every game command is one of two kinds, classified straight from the spec
84
84
  The library hides the two-phase protocol: `await account.commands.spacemolt.mine()`
85
85
  resolves when the action actually executes (which may be many ticks later for
86
86
  `travel`/`jump`), and the local state cache is already updated by the time it
87
- returns. Mutations are serialized per account, matching the server's
87
+ returns. Mutations are serialized per account by default, matching the server's
88
88
  one-action-per-tick rule, and `rate_limited` responses are retried for you.
89
89
 
90
90
  Call commands three ways — all equivalent, all paced and cached:
@@ -95,6 +95,22 @@ await account.mutate('spacemolt', 'jump', { id: 'sol' });
95
95
  await account.send('spacemolt', 'jump', { id: 'sol' }); // auto-routes query/mutation
96
96
  ```
97
97
 
98
+ Applications that coordinate overlapping commands themselves can disable the
99
+ client-side mutation queue at construction:
100
+
101
+ ```ts
102
+ const account = new Account({ serializeMutations: false });
103
+ // Or apply the setting to every account managed by a client:
104
+ const client = new SpacemoltClient({ serializeMutations: false });
105
+ ```
106
+
107
+ With `serializeMutations: false`, a mutation does not wait for an earlier
108
+ mutation's response before sending. Each promise still waits for its own final
109
+ outcome, with independent response correlation and timeouts. Automatic
110
+ `rate_limited` retries remain enabled, and queries are unaffected. This option
111
+ does not change server action limits: conflicting commands can be rejected with
112
+ `action_pending`, and callers must await prerequisites when command order matters.
113
+
98
114
  Every one of those takes an optional trailing `requestId`. The server echoes it
99
115
  back on the response, so you can correlate your own in-flight requests:
100
116
 
@@ -209,15 +225,17 @@ const catalog = await client.catalog(); // shared reference data, fetched once o
209
225
  Token minting draws on a separate per-user rate budget from gameplay, token
210
226
  redemption is rate limited per player rather than per IP (so a fleet
211
227
  connecting once each doesn't compete for one shared budget), and `connectOwned`
212
- staggers the connects on top of that — a fleet up to 100 accounts (the
213
- server's per-IP WS-connection cap) connects in one pass, exactly as before.
214
- Past that, connects are batched — `connectBatchSize` (default 100) per batch,
215
- pausing `connectBatchWaitMs` (default 65s) between batches — so a fleet of any
216
- size never actually asks the server for more connections than it allows in a
217
- window; it just takes longer to fully connect, and never risks the IP-level
218
- timeout that repeat 429s escalate into. `connectRetry` (backoff on a failed
219
- handshake, on by default) is a fallback underneath the batching, in case
220
- something unexpected still trips the cap (e.g. other traffic sharing the IP).
228
+ staggers the connects on top of that. Starts are also capped at
229
+ `connectBatchSize` (default 100, the server's per-IP WS-connection cap) in any
230
+ sliding `connectBatchWaitMs` window (default 65s). Every socket open the client
231
+ paces counts against that one budget: bulk connects, their retries and
232
+ reconnects after a drop. So a fleet of any size never actually asks the server
233
+ for more connections than it allows in a window; it just takes longer to fully
234
+ connect, and never risks the IP-level timeout that repeat 429s escalate into.
235
+ `connectRetry` (backoff on a failed handshake, on by default) is a fallback
236
+ underneath the pacing, in case something unexpected still trips the cap (e.g.
237
+ other traffic sharing the IP). A `session_replaced` or `auth_timeout` close is
238
+ never retried.
221
239
  This is the path to reach for.
222
240
 
223
241
  Reconnect is close-code-aware: a `session_replaced` (the player opened one
@@ -306,6 +324,65 @@ of being treated as an empty store.
306
324
  In the browser, implement the small `CredentialStore` interface over
307
325
  `localStorage` (or anything else) and pass it as `store`.
308
326
 
327
+ ### Host-managed connection and command lifecycles
328
+
329
+ Long-running fleet hosts can coordinate SDK work without replacing its sockets,
330
+ response correlator or state cache. These hooks are optional; ordinary clients
331
+ keep SDK retries and mutation serialization.
332
+
333
+ | API | Use in a fleet host |
334
+ | --- | --- |
335
+ | `scheduleOpen(request, open)` | Coordinate an actual WebSocket open, including reconnects, and attach session/account identity to transport monitoring. |
336
+ | `scheduleSend(request, send)` | Apply shared admission to each actual frame, including authentication and automatic retries. Scheduling does not consume the server-response timeout. |
337
+ | `scheduleConnection(id, attempt, signal?)` | Schedule each connection attempt: initial connects, every connect retry, registrations and reconnects after a drop. When this hook is present, it replaces the SDK start pacing. |
338
+ | `onAccountCreated(account)` | Install lifetime state/push observers before authentication and the optional initial cache seed. Also sees failed connection candidates. |
339
+ | `onConnectionStage(account, stage, error?)` | Distinguish socket-open, authentication and authenticated progress/failure without parsing log messages. Observer errors do not affect connection work. |
340
+ | `connectAll({ onError })`, `connectOwned({ onError })` | Identify individual failed accounts for independent recovery while retaining successful bulk results. |
341
+ | `maxRateLimitRetries` | Forward the existing account setting to managed accounts; `0` lets the host coordinate retries using shared server feedback. The default remains `5`. |
342
+ | `cancelConnection(id)` | Cancel a pending connect or registration (queued, retrying or in flight), close its current candidate and keep credentials. A later `connect(id)` can start a replacement. |
343
+ | `releaseAccount(account)` | Dispose of an exact account object without forgetting credentials or deleting a newer connection for the same ID. |
344
+ | `serializeMutations: false` | Send a selected command without waiting for an earlier mutation's final outcome. Callers own dependency ordering and handle server rejection; the default remains `true`. |
345
+
346
+ Transport requests contain `accountId`, an opaque `sessionId`, and an
347
+ `AbortSignal`. Send requests also identify `tool`, `action` and `requestId`;
348
+ they never include the frame payload or credentials. Session IDs identify
349
+ socket lifetimes and are not authentication tokens. They change when a socket
350
+ is replaced. Closing/replacing a socket aborts its queued work. Scheduling
351
+ callbacks must honor cancellation, invoke their supplied operation once, and
352
+ resolve only after it has run. A send callback is synchronous; an open or
353
+ connection callback must be awaited. If an open or send scheduler resolves
354
+ without running its operation, or runs it twice, the request fails instead of
355
+ waiting. If the scheduler throws after the operation ran, the SDK logs the
356
+ error and keeps waiting for the server's response. A scheduler that
357
+ indefinitely defers work must provide its own admission deadline; response
358
+ deadlines start after admission.
359
+
360
+ For example, a host that already owns recovery can install early observers and
361
+ turn off duplicate SDK retry/mutation coordination:
362
+
363
+ ```ts
364
+ const client = new SpacemoltClient({
365
+ reconnect: false,
366
+ connectRetry: false,
367
+ maxRateLimitRetries: 0,
368
+ serializeMutations: false,
369
+ onAccountCreated: (account) => {
370
+ account.onStateChange((changed) => console.log(account.id, changed));
371
+ },
372
+ onConnectionStage: (account, stage, error) => {
373
+ console.log(account.id, stage, error);
374
+ },
375
+ });
376
+ ```
377
+
378
+ Concurrent `connect(id)` calls share one authenticated candidate. The default
379
+ pacing spaces starts without waiting for earlier authentication to complete.
380
+ `closeAll()` and `cancelConnection(id)` also cancel attempts that still wait
381
+ for a start slot. Clerk token minting uses the account's `connectTimeoutMs`
382
+ and is aborted on deliberate close.
383
+ The query/auth response clock starts after the scheduled send; mutation ACK
384
+ and final-outcome deadlines remain separate.
385
+
309
386
  ## Browser
310
387
 
311
388
  The main entry imports no Node built-ins — bundle it as-is. Provide a
package/dist/account.d.ts CHANGED
@@ -52,7 +52,29 @@ export interface RateLimitedInfo {
52
52
  /** How long this retry is waiting before resending, including jitter. */
53
53
  delayMs: number;
54
54
  }
55
+ /** Identity and cancellation for one socket lifetime; never contains credentials. */
56
+ export interface TransportAdmissionRequest {
57
+ accountId?: string;
58
+ sessionId: string;
59
+ signal: AbortSignal;
60
+ }
61
+ export interface SendAdmissionRequest extends TransportAdmissionRequest {
62
+ tool: string;
63
+ action: string;
64
+ requestId: string;
65
+ }
55
66
  export interface AccountOptions {
67
+ /** Optional host scheduling at the actual socket open. Await open() before resolving; honor signal. */
68
+ scheduleOpen?: (request: TransportAdmissionRequest, open: () => Promise<void>) => Promise<void>;
69
+ /** Optional host scheduling at each actual frame send, including auth and retries. Call send() once; honor signal. */
70
+ scheduleSend?: (request: SendAdmissionRequest, send: () => void) => Promise<void>;
71
+ /**
72
+ * Wait for each mutation to settle before sending the next one on this
73
+ * account. Default true. Set false when the caller coordinates overlapping
74
+ * commands; server action limits and rate-limit retries still apply, and
75
+ * each mutation still resolves or rejects with its own final outcome.
76
+ */
77
+ serializeMutations?: boolean;
56
78
  /** WebSocket URL of the v2 endpoint. Defaults to the production server. */
57
79
  url?: string;
58
80
  /** Inject a WebSocket implementation (tests, custom runtimes). */
@@ -122,8 +144,8 @@ export interface AccountOptions {
122
144
  * `fastMutationTimeoutMs`) and uses that much shorter bound instead.
123
145
  * Without this, a single silently-dropped outcome frame hangs forever AND
124
146
  * wedges every subsequent mutation on this account behind it (mutations
125
- * are serialized per account, see `enqueueMutation`). Default 600000 (10
126
- * minutes).
147
+ * are serialized per account by default, see `serializeMutations`). Default
148
+ * 600000 (10 minutes).
127
149
  */
128
150
  mutationTimeoutMs?: number;
129
151
  /**
@@ -153,6 +175,10 @@ export interface RegisterResult {
153
175
  }
154
176
  export declare class Account {
155
177
  private socket;
178
+ private readonly scheduleOpen?;
179
+ private readonly scheduleSend?;
180
+ private transportAbort;
181
+ private sessionId;
156
182
  private readonly correlator;
157
183
  private readonly cache;
158
184
  private readonly emitter;
@@ -188,6 +214,7 @@ export declare class Account {
188
214
  /** The close seen on the current reconnect attempt's socket, if any — the loop reads it to decide whether the attempt really succeeded. */
189
215
  private attemptClose;
190
216
  private mutationLane;
217
+ private readonly serializeMutations;
191
218
  private marketSubscribedState;
192
219
  private subscribedMarketBaseId;
193
220
  private observationSubscribedState;
@@ -303,8 +330,8 @@ export declare class Account {
303
330
  * Run a mutation; resolves when the action executes on a later tick (after
304
331
  * the immediate pending ack). `onAck` fires when the pending ack arrives.
305
332
  *
306
- * Mutations are serialized per account — the next is sent only after the
307
- * previous resolves — because the server queues one action per tick and
333
+ * Mutations are serialized per account by default — the next is sent only
334
+ * after the previous settles — because the server queues one action per tick and
308
335
  * rejects a concurrent mutation with `action_pending`. Also auto-retries on
309
336
  * `rate_limited`.
310
337
  *
@@ -498,12 +525,9 @@ export declare class Account {
498
525
  /** Returns whether the auth exchange was accepted — a caller must not send its frame when it wasn't. */
499
526
  private beginAuth;
500
527
  private sendFrame;
501
- /**
502
- * Calls an optional single-callback hook (`onSend`/`onReceive`), swallowing
503
- * a throw so a broken observer can't stop the frame being sent or routed —
504
- * same handling as `notifyListeners` for a `Set` of listeners.
505
- */
506
- private callHook;
528
+ /** Throws unless `socket` is still this account's live, wanted transport. */
529
+ private assertTransport;
530
+ private sendFrameNow;
507
531
  private nextRequestId;
508
532
  /**
509
533
  * Pick the `request_id` for one frame. A caller-supplied id is echoed by the
@@ -556,6 +580,6 @@ export declare class Account {
556
580
  * listener (`tool.action`, or `'authenticate'`).
557
581
  */
558
582
  private withRateLimitRetry;
559
- /** Serialize mutations: each runs only after the previous settles. */
583
+ /** Serialize mutations by default; caller-managed concurrency is opt-in. */
560
584
  private enqueueMutation;
561
585
  }
package/dist/client.d.ts CHANGED
@@ -11,14 +11,31 @@ import { Account } from './account.js';
11
11
  import { type AuthCredentials, type CredentialStore, type StoredAccount } from './auth/credentials.js';
12
12
  import type { WebSocketFactory } from './transport/socket.js';
13
13
  import type { InboundFrame, RawFrame } from './protocol.js';
14
- import type { ReconnectOptions, RegisterParams, RegisterResult } from './account.js';
14
+ import type { AccountOptions, ReconnectOptions, RegisterParams, RegisterResult } from './account.js';
15
15
  import { CatalogCache } from './data/catalog.js';
16
16
  import { MapCache } from './data/map.js';
17
17
  import { type MobileBaseLocation } from './data/mobile-base.js';
18
18
  import { type StationList } from './data/stations.js';
19
19
  import { type ClerkPlayer } from './auth/clerk.js';
20
- import { type ConnectionClosedError } from './errors.js';
21
- export interface SpacemoltClientOptions {
20
+ import { ConnectionClosedError } from './errors.js';
21
+ /** Progress of one connection candidate, reported to `onConnectionStage`. */
22
+ export type ConnectionStage = 'connection_open' | 'authentication' | 'authenticated';
23
+ /**
24
+ * `scheduleOpen`, `scheduleSend`, `serializeMutations` and `maxRateLimitRetries`
25
+ * are forwarded to every managed account; see `AccountOptions`.
26
+ */
27
+ export interface SpacemoltClientOptions extends Pick<AccountOptions, 'scheduleOpen' | 'scheduleSend' | 'serializeMutations' | 'maxRateLimitRetries'> {
28
+ /**
29
+ * Host scheduling around each connection attempt: initial connects, every
30
+ * connect retry, registrations and reconnects after a drop. When set, it
31
+ * replaces the SDK start pacing (`connectStaggerMs`/`connectBatchSize`/
32
+ * `connectBatchWaitMs`). Honor `signal` and await `attempt()`.
33
+ */
34
+ scheduleConnection?: <T>(id: string, attempt: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
35
+ /** Observe each account before any connect/auth/seed work, including failed candidates. */
36
+ onAccountCreated?: (account: Account) => void;
37
+ /** Observe connection progress; exceptions from this observer are isolated. */
38
+ onConnectionStage?: (account: Account, stage: ConnectionStage, error?: unknown) => void;
22
39
  /** WebSocket URL of the v2 endpoint. */
23
40
  url?: string;
24
41
  /** Where credentials live. Defaults to an in-memory store. */
@@ -42,20 +59,19 @@ export interface SpacemoltClientOptions {
42
59
  */
43
60
  connectStaggerMs?: number;
44
61
  /**
45
- * Max accounts to connect before pausing for `connectBatchWaitMs`, so a
46
- * fleet never actually trips the server's per-IP WS-connection rate limit
62
+ * Max connection starts in any `connectBatchWaitMs` window, so a fleet
63
+ * never actually trips the server's per-IP WS-connection rate limit
47
64
  * (hitting it risks an IP-level timeout/ban on repeat offense — better to
48
- * never ask). Matches the server's default connection cap (100/min), so a
49
- * fleet at or under this size behaves exactly like a single stagger pass,
50
- * same as before; a larger fleet connects in batches of this size instead.
51
- * Default 100.
65
+ * never ask). Matches the server's default connection cap (100/min). Every
66
+ * socket open the SDK paces counts: bulk connects, their retries and
67
+ * reconnects after a drop. Default 100. Set `0` to turn batching off.
52
68
  */
53
69
  connectBatchSize?: number;
54
70
  /**
55
- * Pause between batches once `connectBatchSize` is exceeded, letting the
56
- * server's per-IP rate-limit window (1 minute by default) fully roll over
57
- * before the next batch starts. Default 65000 (65s — a margin over the
58
- * server's 1-minute window).
71
+ * Length of the sliding window that `connectBatchSize` counts starts in.
72
+ * Default 65000 (65s — a margin over the server's 1-minute window). The
73
+ * count is shared by every bulk call, retry and reconnect on this client.
74
+ * A slow authentication does not hold a start slot.
59
75
  */
60
76
  connectBatchWaitMs?: number;
61
77
  /**
@@ -161,6 +177,15 @@ export declare class SpacemoltClient {
161
177
  private readonly opts;
162
178
  private readonly store;
163
179
  private readonly connected;
180
+ /** The pending connect or register for each id, and the controller that cancels it. */
181
+ private readonly pending;
182
+ /** Reconnect chains in flight, keyed by the exact `Account` they restore. */
183
+ private readonly reconnects;
184
+ /** Times of the starts inside the current `connectBatchWaitMs` window, oldest first. */
185
+ private readonly recentStarts;
186
+ private nextConnectStartAt;
187
+ /** The latest client-initiated credential write per id; see `persist`. */
188
+ private readonly storeWrites;
164
189
  private catalogCache?;
165
190
  private catalogFetchedAt;
166
191
  private mapCache?;
@@ -168,18 +193,9 @@ export declare class SpacemoltClient {
168
193
  private readonly accountConnectedListeners;
169
194
  private readonly accountReconnectedListeners;
170
195
  private readonly accountDisconnectedListeners;
171
- /** Paced by connectBatchSize/connectStaggerMs/connectBatchWaitMs — the same limiter drains both the initial fleet connect and later reconnects, see `enqueueRateLimited`. */
172
- private readonly rateLimitedQueue;
173
- private rateLimitedQueueDraining;
174
- /**
175
- * Ids currently mid-reconnect. Guards against a socket dropping again
176
- * *during* `reconnectAccountInPlace` (e.g. another rate-limit close before
177
- * auth completes) re-firing `handleAccountDisconnected` and enqueuing a
178
- * second, parallel reconnect chain for the same id — the drop instead
179
- * surfaces as a failure inside the one already-running `withConnectRetry`
180
- * loop, which retries it itself.
181
- */
182
- private readonly reconnectingIds;
196
+ /** Attempts waiting for a start slot; see `startSlot`. */
197
+ private readonly startQueue;
198
+ private startQueueDraining;
183
199
  constructor(opts?: SpacemoltClientOptions);
184
200
  /**
185
201
  * Fires the first time an id becomes a connected+authenticated `Account`
@@ -239,23 +255,28 @@ export declare class SpacemoltClient {
239
255
  /**
240
256
  * Register a brand-new account: connect, register, and persist the generated
241
257
  * password as login credentials (keyed by username) for future sessions.
258
+ * Rejects if the username already has a pending or live connection.
242
259
  */
243
260
  register(params: RegisterParams): Promise<{
244
261
  account: Account;
245
262
  result: RegisterResult;
246
263
  }>;
264
+ private registerAccount;
247
265
  /** Resolves `connectRetry` into a concrete backoff config. */
248
266
  private connectRetryConfig;
249
267
  /**
250
268
  * Retry `attempt` with the shared `connectRetry` backoff, honoring a 4003
251
269
  * `connection_rate_limited` close's `retry_after` hint over the
252
270
  * exponential fallback. Shared by the initial connect (`connect`) and an
253
- * in-place reconnect (`reconnectAccountInPlace`) so both back off
254
- * identically.
271
+ * in-place reconnect (`handleAccountDisconnected`) so both back off
272
+ * identically. With `paced`, every attempt — retries included — waits for
273
+ * its own start slot, so retries stay inside the per-IP budget. A
274
+ * session_replaced or auth_timeout close is terminal and not retried.
255
275
  */
256
276
  private withConnectRetry;
257
277
  /**
258
- * Connect and authenticate one stored account. Idempotent per id.
278
+ * Connect and authenticate one stored account. Idempotent per id:
279
+ * concurrent calls share one attempt.
259
280
  *
260
281
  * Retries the whole connect+authenticate sequence with backoff on failure
261
282
  * (see `connectRetry`) — a fleet large enough to exceed the per-IP
@@ -263,9 +284,25 @@ export declare class SpacemoltClient {
263
284
  * which self-heals once the server's rate-limit window rolls over.
264
285
  */
265
286
  connect(id: string): Promise<Account>;
287
+ private connectTracked;
288
+ /** Register one connect/register for `id` so `cancelConnection`/`closeAll` can stop it. */
289
+ private trackPending;
290
+ private connectAccount;
291
+ /** One connect+authenticate attempt with a fresh `Account`. */
292
+ private connectCandidate;
293
+ /** Throws unless `account` is still the live, wanted candidate for `id`. */
294
+ private assertCandidate;
295
+ private connectionStage;
296
+ /**
297
+ * Run `attempt` through the host scheduler, if any. Rejects as soon as
298
+ * `signal` aborts, so a cancelled caller never waits on the host queue;
299
+ * `attempt` itself refuses to start after that.
300
+ */
301
+ private scheduleConnection;
266
302
  /** Connect every stored account, staggered to respect rate limits. */
267
303
  connectAll(opts?: {
268
304
  onConnect?: (account: Account) => void;
305
+ onError?: (id: string, error: unknown) => void;
269
306
  }): Promise<Account[]>;
270
307
  /** List the player accounts the Clerk user owns. Requires `clerkApiKey`. */
271
308
  listOwnedPlayers(): Promise<ClerkPlayer[]>;
@@ -284,47 +321,54 @@ export declare class SpacemoltClient {
284
321
  connectOwned(opts?: {
285
322
  filter?: (player: ClerkPlayer) => boolean;
286
323
  onConnect?: (account: Account) => void;
324
+ onError?: (id: string, error: unknown) => void;
287
325
  }): Promise<Account[]>;
288
326
  private requireClerkAuth;
289
327
  /**
290
- * Connect the given stored ids, staggered to respect rate limits. At or
291
- * under `connectBatchSize` accounts this is a single stagger pass — the
292
- * same behavior as before batching existed. Past that, it pauses for
293
- * `connectBatchWaitMs` between batches so the fleet never actually asks
294
- * for more connections than the server's per-IP window allows. A single
295
- * account failing to connect must not abort the rest of the batch — it's
296
- * logged and skipped so the caller still gets every account that succeeded.
328
+ * Connect the given stored ids. Without `scheduleConnection`, every
329
+ * attempt (retries included) waits for a start slot under
330
+ * `connectStaggerMs`/`connectBatchSize`/`connectBatchWaitMs`; with it, the
331
+ * host schedules the attempts instead. A single account failing to
332
+ * connect must not abort the rest of the batch — it's logged, reported to
333
+ * `onError` and skipped, so the caller still gets every account that
334
+ * succeeded.
297
335
  *
298
336
  * `onConnect` fires synchronously as each id finishes (success only) so a
299
337
  * caller managing many accounts (e.g. indexing them for lookup) doesn't
300
338
  * have to wait for the entire — potentially minutes-long — batch before
301
339
  * any single account becomes usable.
302
- *
303
- * Pacing itself is `enqueueRateLimited` — the same queue a later
304
- * reconnect (see `handleAccountDisconnected`) competes for a slot in, so a
305
- * reconnect landing mid-batch is paced fairly alongside the rest of the
306
- * fleet instead of racing it on a separate timer.
307
340
  */
308
341
  private connectIds;
309
342
  /**
310
- * Enqueues `task`, paced by `connectBatchSize`/`connectStaggerMs`/
311
- * `connectBatchWaitMs` — the single rate limiter shared by the initial
312
- * fleet connect (`connectIds`) and every later reconnect
343
+ * Wait for one connection start slot. The single rate limiter shared by
344
+ * bulk connects (`connectIds`), their retries and every later reconnect
313
345
  * (`handleAccountDisconnected`), so the server's per-IP WS-connection cap
314
- * is respected by one mechanism, not a parallel one for each case. Returns
315
- * a promise settling with `task`'s own outcome once its turn comes up.
346
+ * is respected by one mechanism. Rejects with the signal's reason if it
347
+ * aborts first; an aborted waiter takes no slot.
316
348
  */
317
- private enqueueRateLimited;
318
- private drainRateLimitedQueue;
349
+ private startSlot;
350
+ private drainStartQueue;
351
+ /** Wait until the stagger has passed and the sliding window has room for one more start. */
352
+ private waitForStartBudget;
319
353
  /** The connected account for an id, if connected. */
320
354
  account(id: string): Account | undefined;
321
355
  /** All currently-connected accounts. */
322
356
  accounts(): Account[];
323
357
  /** Ids of all currently-connected accounts. */
324
358
  ids(): string[];
359
+ /**
360
+ * Cancel the pending connect/register for `id` (queued, retrying or in
361
+ * flight) and close its current account. Returns once the cancelled call
362
+ * has settled; an abandoned attempt can no longer publish an account, but
363
+ * a credential write it already started can still finish. Keeps
364
+ * credentials. A later `connect(id)` can start a replacement.
365
+ */
366
+ cancelConnection(id: string): Promise<void>;
367
+ /** Close this exact account without deleting a newer connection or its stored credentials. */
368
+ releaseAccount(account: Account): void;
325
369
  /** Close and forget an account, and remove its stored credentials. */
326
370
  remove(id: string): Promise<void>;
327
- /** Close every connection (credentials remain in the store). */
371
+ /** Close every connection and cancel every pending connect and reconnect (credentials remain in the store). */
328
372
  closeAll(): void;
329
373
  /**
330
374
  * Reconnection for a client-managed account is driven here, not by the
@@ -344,5 +388,7 @@ export declare class SpacemoltClient {
344
388
  private handleAccountDisconnected;
345
389
  private createAccount;
346
390
  private capturePlayerId;
391
+ /** `store.put`, tracked so `remove` can wait for a write still in flight. */
392
+ private persist;
347
393
  }
348
394
  export type { AuthCredentials, CredentialStore, StoredAccount };
package/dist/errors.d.ts CHANGED
@@ -62,6 +62,13 @@ export declare const CLOSE_CODE: {
62
62
  readonly AUTH_TIMEOUT: 4002;
63
63
  readonly CONNECTION_RATE_LIMITED: 4003;
64
64
  };
65
+ /**
66
+ * Closes no reconnect can recover from. session_replaced: another connection
67
+ * took our slot — reconnecting would just fight it. auth_timeout: we failed to
68
+ * auth in time. Unlike those two, connection_rate_limited (4003) IS worth
69
+ * reconnecting after — callers honor its retry_after hint.
70
+ */
71
+ export declare function isTerminalClose(err: unknown): boolean;
65
72
  /**
66
73
  * Parses the `retry_after=<seconds>` hint the server includes on a `4003`
67
74
  * (connection_rate_limited) close reason. Returns the wait time in
@@ -6,6 +6,8 @@
6
6
  * this (loosely-typed) core.
7
7
  */
8
8
  import type { RawFrame } from '../protocol.js';
9
+ /** Calls one optional hook, isolating a throw the same way as `notifyListeners`. */
10
+ export declare function callHook<A extends unknown[]>(hook: ((...args: A) => void) | undefined, label: string, ...args: A): void;
9
11
  /**
10
12
  * Fan an event out to every registered listener. A throwing listener is warned
11
13
  * and skipped — a listener is told what already happened, so it must never
@@ -1,5 +1,5 @@
1
1
  /** The gameserver spec version this command surface was generated from. */
2
- export declare const GENERATED_SPEC_VERSION = "v0.715.2";
2
+ export declare const GENERATED_SPEC_VERSION = "v0.717.0";
3
3
  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";
4
4
  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_mobile_base_jump" | "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" | "decommission_mobile_base" | "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" | "fit_preview" | "forum_create_thread" | "forum_delete_reply" | "forum_delete_thread" | "forum_edit_reply" | "forum_edit_thread" | "forum_get_thread" | "forum_list" | "forum_reply" | "forum_upvote" | "found_gate_site" | "found_station" | "garages" | "generator" | "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_mobile_base" | "get_nearby" | "get_notes" | "get_notification_settings" | "get_notifications" | "get_player" | "get_player_profile" | "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" | "interact_poi" | "invite" | "jettison" | "job_add" | "job_cancel" | "job_list" | "job_reorder" | "join" | "jump" | "jump_mobile_base" | "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" | "move_mobile_base" | "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" | "reset_contraband" | "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_contraband" | "set_description" | "set_enemy" | "set_gate_access" | "set_home" | "set_market_fee" | "set_name" | "set_output_price" | "set_public" | "set_refuel_price" | "set_repair_price" | "set_service_access" | "set_status" | "set_toll" | "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";
5
5
  export interface ActionParam {