@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 +5 -2
- package/COMMANDS.md +1 -1
- package/README.md +87 -10
- package/dist/account.d.ts +35 -11
- package/dist/client.d.ts +94 -48
- package/dist/errors.d.ts +7 -0
- package/dist/events/emitter.d.ts +2 -0
- package/dist/generated/actions.gen.d.ts +1 -1
- package/dist/generated/commands.gen.d.ts +17 -17
- package/dist/generated/openapi/types.gen.d.ts +21 -17
- package/dist/index.d.ts +2 -2
- package/dist/index.js +365 -119
- package/dist/index.js.map +9 -9
- package/dist/push-frames.d.ts +21 -6
- package/package.json +1 -1
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
|
|
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.
|
|
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
|
|
213
|
-
server's per-IP WS-connection cap)
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
window; it just takes longer to fully
|
|
218
|
-
timeout that repeat 429s escalate into.
|
|
219
|
-
handshake, on by default) is a fallback
|
|
220
|
-
something unexpected still trips the cap (e.g.
|
|
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 `
|
|
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
|
|
307
|
-
* previous
|
|
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
|
-
|
|
503
|
-
|
|
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
|
|
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 {
|
|
21
|
-
|
|
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
|
|
46
|
-
*
|
|
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)
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
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
|
-
/**
|
|
172
|
-
private readonly
|
|
173
|
-
private
|
|
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 (`
|
|
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
|
|
291
|
-
*
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
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
|
-
*
|
|
311
|
-
* `
|
|
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
|
|
315
|
-
*
|
|
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
|
|
318
|
-
private
|
|
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
|
package/dist/events/emitter.d.ts
CHANGED
|
@@ -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.
|
|
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 {
|