@spacemolt/lib 12.1.0 → 12.2.1

package/README.md

@@ -95,6 +95,19 @@ await account.mutate('spacemolt', 'jump', { id: 'sol' });
 await account.send('spacemolt', 'jump', { id: 'sol' }); // auto-routes query/mutation
 ```
 
+Every one of those takes an optional trailing `requestId`. The server echoes it
+back on the response, so you can correlate your own in-flight requests:
+
+```ts
+await account.commands.spacemolt.jump({ id: 'sol' }, 'my-id-1');
+await account.query('spacemolt', 'get_status', undefined, 'my-id-2');
+await account.mutate('spacemolt', 'mine', undefined, undefined, 'my-id-3');
+```
+
+Omit it and the library picks one. Give each request a new id: an id that is
+already in flight is refused with a `duplicate_request_id` error, and an id you
+reuse after its request timed out can settle on the wrong response.
+
 ### Local state cache
 
 Seeded from `get_status` after auth and updated from the delta on every

package/dist/account.d.ts

@@ -160,6 +160,8 @@ export declare class Account {
     private subscribedMarketBaseId;
     private observationSubscribedState;
     private observationActiveScanState;
+    /** Invalidates an in-flight reconciliation whenever a newer cache update arrives. */
+    private stateRevision;
     private subscribedObservationPoiId;
     private readonly reconnectedListeners;
     private readonly reconnectingListeners;
@@ -256,7 +258,7 @@ export declare class Account {
      * to take long, so a response that never arrives (the server silently
      * drops it rather than erroring) fails cleanly instead of hanging forever.
      */
-    query(tool: string, action: string, payload?: Record<string, unknown>): Promise<QueryResult>;
+    query(tool: string, action: string, payload?: Record<string, unknown>, requestId?: string): Promise<QueryResult>;
     /**
      * Run a mutation; resolves when the action executes on a later tick (after
      * the immediate pending ack). `onAck` fires when the pending ack arrives.
@@ -273,7 +275,7 @@ export declare class Account {
      * every other mutation — `mine`, `craft`, etc. — settles within the tick it
      * was queued on and gets the much shorter `fastMutationTimeoutMs`.
      */
-    mutate(tool: string, action: string, payload?: Record<string, unknown>, onAck?: (ack: MutationAck) => void): Promise<MutationResult>;
+    mutate(tool: string, action: string, payload?: Record<string, unknown>, onAck?: (ack: MutationAck) => void, requestId?: string): Promise<MutationResult>;
     /**
      * Waits for a mutation's outcome with two-phase timeout protection. The
      * pending ack (`result` frame) is a synchronous validation step with no
@@ -292,7 +294,7 @@ export declare class Account {
      * Run a command, dispatching to `query`/`mutate` based on the spec's
      * `x-is-mutation` classification. Unknown commands are treated as queries.
      */
-    send(tool: string, action: string, payload?: Record<string, unknown>): Promise<QueryResult | MutationResult>;
+    send(tool: string, action: string, payload?: Record<string, unknown>, requestId?: string): Promise<QueryResult | MutationResult>;
     /**
      * Listen for a specific server push by msg_type. The handler receives the
      * typed payload for published notification types, or a loosely-typed object
@@ -374,6 +376,22 @@ export declare class Account {
      * after every state update that could carry a `location` change.
      */
     private checkSubscriptionsAgainstLocation;
+    /**
+     * Fleet followers do not submit the movement mutation themselves, so their
+     * arrival is delivered as a plain `ok` push rather than an `action_result`
+     * carrying a state delta. Bridge the location data present on those pushes
+     * into the cache. Fleet docking is the one exception: its push only contains
+     * the station's display name, not the canonical base ID used by `docked_at`,
+     * so refresh the canonical snapshot instead of caching the wrong identifier.
+     */
+    private applyFleetMovementPush;
+    /**
+     * Fleet movement pushes omit follower fuel and skill deltas, while docking
+     * omits the canonical base ID. Reconcile those fields from one authoritative
+     * snapshot. A newer movement push invalidates an older in-flight query so a
+     * delayed dock/arrival snapshot cannot move the cache backwards.
+     */
+    private reconcileFleetState;
     /** Close the connection deliberately. Suppresses auto-reconnect. */
     close(): void;
     /** Fired after a successful reconnect + re-auth. Returns an unsubscribe function. */
@@ -391,6 +409,18 @@ export declare class Account {
     private beginAuth;
     private sendFrame;
     private nextRequestId;
+    /**
+     * Pick the `request_id` for one frame. A caller-supplied id is echoed by the
+     * server unchanged, which is the point — it lets the caller correlate its own
+     * in-flight requests. An empty id is treated as no id, because the server
+     * drops falsy ids and the request would then hang until it timed out.
+     *
+     * A caller-supplied id must be unique for the life of the connection, not
+     * only while it is in flight. Reusing a live id is refused here. Reusing an
+     * id whose request timed out is not detected, and a late frame for the first
+     * request then settles the second one with the wrong outcome.
+     */
+    private claimRequestId;
     private routeFrame;
     private warnMalformedFrame;
     private handleClose;