@spacemolt/lib 12.2.1 → 13.0.0

package/dist/protocol.d.ts

@@ -7,7 +7,7 @@
  * spec instead (see src/generated/). Endpoint: `/ws/v2`.
  */
 import type { NotificationPayloads, TypedNotificationType } from './generated/notifications.gen.js';
-import type { V2GameState } from './generated/openapi/types.gen.js';
+import type { LoggedInPayload, RegisteredPayload, V2GameState, WelcomePayload } from './generated/openapi/types.gen.js';
 /** Inbound frame: client -> server. `payload` is omitted when an action takes none. */
 export interface InboundFrame {
     tool: string;
@@ -70,38 +70,31 @@ export interface ErrorFrame {
         pending_command?: string;
     };
 }
-/** Unsolicited frame sent immediately after the socket upgrade. No request_id. */
+/**
+ * Unsolicited frame sent immediately after the socket upgrade. No request_id.
+ *
+ * The three auth/handshake payloads below are the server's published schemas
+ * rather than hand-written mirrors, so a server-side field change breaks
+ * `typecheck` here instead of silently rotting a copy (gameserver-todo #2/#5).
+ */
 export interface WelcomeFrame {
     type: 'welcome';
-    payload: {
-        version: string;
-        release_date: string;
-        release_notes: string[];
-        tick_rate: number;
-        current_tick: number;
-        server_time: number;
-        motd?: string;
-        game_info: string;
-        website: string;
-        help_text: string;
-        terms: string;
-    };
+    payload: WelcomePayload;
 }
 /** Auth success frame carrying the full initial session state. */
 export interface LoggedInFrame {
     type: 'logged_in';
     request_id?: string;
-    payload: Record<string, unknown>;
+    payload: LoggedInPayload;
 }
-/** Auth success frame after `register`, carrying generated credentials. */
+/**
+ * Auth success frame after `register`, carrying generated credentials.
+ * `password` is a 256-bit hex credential — this is the only chance to capture it.
+ */
 export interface RegisteredFrame {
     type: 'registered';
     request_id?: string;
-    payload: {
-        /** 256-bit hex credential — only chance to capture it. */
-        password: string;
-        player_id: string;
-    };
+    payload: RegisteredPayload;
 }
 /**
  * A server-initiated push frame whose msg_type has a published payload schema.
@@ -133,15 +126,29 @@ export declare function isWelcomeFrame(frame: RawFrame): frame is WelcomeFrame;
 export declare function isLoggedInFrame(frame: RawFrame): frame is LoggedInFrame;
 export declare function isRegisteredFrame(frame: RawFrame): frame is RegisteredFrame;
 /**
- * The cacheable game-state sections — the eight independently-tracked sections
+ * The cacheable game-state sections — the nine independently-tracked sections
  * the server emits deltas for. Section shapes are derived from the spec's
  * `V2GameState`, so they stay correct as the spec evolves.
+ *
+ * The list itself is not spec-derived, so it has to be kept in step by hand:
+ * the authority is the `x-state-sections` a mutation operation declares (from
+ * the server's `StateSections` bitmask in `internal/handlers/delta_wrapper.go`).
+ * A section missing here is silently dropped from every delta, so
+ * `tests/generated.test.ts` cross-checks this list against the spec.
+ *
+ * `V2GameState` carries further keys that are *not* delta sections and so are
+ * deliberately absent from the cache — read them off the query response that
+ * returns them: `riding` (`get_status`, when riding as a passenger with no ship
+ * of your own), `drone_bay` (`get_ship`), `carried_ships`/`bay_used`/
+ * `bay_capacity` (`get_cargo`, carriers only), and `version` (`get_status`).
+ * Note `fleet/board` and `fleet/disembark` declare no state sections at all, so
+ * boarding emits no delta: call `refresh()` after one.
  */
-export type GameState = Pick<V2GameState, 'player' | 'ship' | 'modules' | 'cargo' | 'location' | 'missions' | 'queue' | 'skills'>;
+export type GameState = Pick<V2GameState, 'player' | 'ship' | 'modules' | 'cargo' | 'location' | 'missions' | 'queue' | 'skills' | 'prize_recoveries'>;
 /**
  * A `V2GameState` delta carried on `action_result`. Only changed sections are
  * present; an absent section means unchanged (keep prior local state). Carries
- * the same eight sections as `GameState` plus the per-action convenience fields.
+ * the same nine sections as `GameState` plus the per-action convenience fields.
  */
 export type StateDelta = GameState & Pick<V2GameState, 'message' | 'details' | 'credits'>;
 /**
@@ -181,5 +188,5 @@ export interface MutationResult<TDetails = Record<string, unknown>> {
     autoDocked?: boolean;
     autoUndocked?: boolean;
 }
-export declare const STATE_SECTIONS: readonly ["player", "ship", "modules", "cargo", "location", "missions", "queue", "skills"];
+export declare const STATE_SECTIONS: readonly ["player", "ship", "modules", "cargo", "location", "missions", "queue", "skills", "prize_recoveries"];
 export type StateSection = (typeof STATE_SECTIONS)[number];

package/dist/state/cache.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-account local cache of the eight game-state sections.
+ * Per-account local cache of the nine game-state sections.
  *
  * Seeded canonically from a full `V2GameState` snapshot (the `get_status`
  * query returns exactly this shape) and kept current by applying the section
@@ -37,6 +37,14 @@ export declare class StateCache {
     get modules(): GameState['modules'];
     get missions(): GameState['missions'];
     get skills(): GameState['skills'];
+    /**
+     * Active intact-ship recovery operations assigned to this player, including
+     * prizes in transit or stalled outside the current POI. Refreshed by the
+     * deltas of the player's own prize commands (`claim_prize`, `service_prize`)
+     * and by `refresh()` — the `prize_update`/`ship_captured` pushes do not carry
+     * a delta, so this is not a live feed.
+     */
+    get prizeRecoveries(): GameState['prize_recoveries'];
     /** True when a tick-deferred action is queued for this account. */
     get hasPendingAction(): boolean;
     get credits(): number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacemolt/lib",
-  "version": "12.2.1",
+  "version": "13.0.0",
   "description": "The definitive TypeScript library for SpaceMolt. WebSocket-v2-first, multi-account, with local state caches. Internals are regenerated from the server's OpenAPI spec.",
   "type": "module",
   "module": "./dist/index.js",