@spacemolt/lib 14.0.1 → 14.2.0

package/AGENTS.md

@@ -84,6 +84,30 @@ account.credits, account.ship, account.location, account.cargo, account.skills;
 account.on('mining_yield', (y) => console.log(y.quantity, y.resource_id));
 ```
 
+Push payloads are typed. Most come from the server's published schema; the `ok`
+and `fleet` families are hand-written unions, because the server publishes no
+schema for those two. `ok` splits its discriminator: most variants key on
+`action`, seven key on `type`. A bare `p.action` therefore does not compile on
+`OkPush` — guard with `'action' in p`, or narrow to the exported `OkActionPush`
+/ `OkTypePush` halves. `FleetPush` has one key and needs no guard:
+
+```ts
+account.on('ok', (p) => {
+  if ('action' in p && p.action === 'fleet_dock') p.base_id; // canonical base id
+  if ('type' in p && p.type === 'emergency_warp_stabilizer_activated') p.hull;
+});
+account.on('fleet', (p) => {
+  if (p.action === 'fleet_invite') p.fleet_id;
+});
+```
+
+Both unions are closed and were derived from a specific server build. A frame
+the server added since still arrives at your `on('ok')` handler — nothing
+validates the payload against these types — as a value matching no member, so
+give your `switch` a real default rather than a `never` assertion.
+`OK_PUSH_ACTIONS`, `OK_PUSH_TYPES` and `FLEET_PUSH_ACTIONS` are exported with
+their derived literal types if you want to enumerate.
+
 ## Gotchas worth knowing up front
 
 - **Preconditions are real.** A new account starts docked; `mine` needs an

package/README.md

@@ -138,7 +138,7 @@ for await (const hit of account.events('battle_damage')) { /* ... */ }
 
 ### Subscriptions
 
-Subscribe to a station's order book or to player presence at your location; the
+Subscribe to a station's order book or to presence at your location; the
 baseline snapshot seeds a local cache that the push stream keeps current:
 
 ```ts
@@ -146,9 +146,19 @@ await account.subscribeMarket();                 // current docked station
 account.market(baseId);                          // cached order book, kept live by `market_update`
 
 await account.subscribeObservation();
-account.observation();                           // cached presence, kept live by `observation_update`
+const view = account.observation();              // kept live by `observation_update`
+view?.nearby;                                    // players at your POI, keyed by player_id
+view?.system;                                    // players system-wide
+view?.pirates;                                   // pirate NPCs, keyed by pirate_id
+view?.empireNpcs;                                // empire NPCs, keyed by npc_id
+view?.creatures;                                 // wildlife, keyed by creature_id
+view?.prizes;                                    // intact captured ships, keyed by prize_id
 ```
 
+The watch is not players only. It covers five of `get_nearby`'s six classes —
+arena NPCs are the one it does not carry — and every class except wildlife is
+also mirrored into `account.state.location`.
+
 ## Multi-account
 
 `SpacemoltClient` manages many accounts, staggers connects to respect login

package/dist/account.d.ts

@@ -14,6 +14,7 @@ import { type Commands } from './generated/commands.gen.js';
 import type { AuthCredentials } from './auth/credentials.js';
 import type { LoggedInPayload as LoggedInPayloadSchema, SubscribeMarketResponse, SubscribeObservationResponse } from './generated/openapi/types.gen.js';
 import type { NotificationPayloads, TypedNotificationType } from './generated/notifications.gen.js';
+import type { FleetPush, OkPush } from './push-frames.js';
 import { type ConnectionClosedError } from './errors.js';
 import { type MarketBook } from './state/market.js';
 import { type ObservationView } from './state/observation.js';
@@ -300,10 +301,14 @@ export declare class Account {
     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
-     * for not-yet-typed pushes. Returns an unsubscribe function.
+     * typed payload for published notification types, and for the `ok` and
+     * `fleet` families from the hand-written unions in `push-frames.ts` (the
+     * server publishes no schema for those two). Anything else is a
+     * loosely-typed object. Returns an unsubscribe function.
      */
     on<K extends TypedNotificationType>(type: K, handler: (payload: NotificationPayloads[K]) => void): () => void;
+    on(type: 'ok', handler: (payload: OkPush) => void): () => void;
+    on(type: 'fleet', handler: (payload: FleetPush) => void): () => void;
     on(type: string, handler: (payload: Record<string, unknown>) => void): () => void;
     /** Listen for every server push frame. Returns an unsubscribe function. */
     onAny(handler: (frame: RawFrame) => void): () => void;
@@ -313,6 +318,8 @@ export declare class Account {
      * Buffered, so a slow consumer won't drop frames; `break` unsubscribes.
      */
     events<K extends TypedNotificationType>(type: K): AsyncIterableIterator<NotificationPayloads[K]>;
+    events(type: 'ok'): AsyncIterableIterator<OkPush>;
+    events(type: 'fleet'): AsyncIterableIterator<FleetPush>;
     events(type: string): AsyncIterableIterator<Record<string, unknown>>;
     /** Async-iterate every push frame. */
     anyEvents(): AsyncIterableIterator<RawFrame>;
@@ -336,14 +343,17 @@ export declare class Account {
     /** The cached order book for a base, if subscribed. */
     market(baseId: string): MarketBook | undefined;
     /**
-     * Subscribe to a change-feed of player presence at your current POI/system.
+     * Subscribe to a change-feed of presence at your current POI/system: players
+     * (POI and system-wide), plus the pirates, empire NPCs, wildlife and intact
+     * prizes at the POI — not players only. That is five of `get_nearby`'s six
+     * classes; arena NPCs are not in the feed, so an arena match still needs
+     * `get_nearby` to see its opponents.
      * Returns the baseline and seeds the observation cache; `observation_update`
      * pushes are merged automatically. Read with `account.observation()`. Also
-     * bridges POI-scoped presence into the base state cache's
-     * `location.nearby_players`/`nearby_player_count` (see
-     * `bridgeObservationToLocation`), so `account.state.location` reflects live
-     * data too once subscribed, instead of only refreshing on the next
-     * `get_status`/mutation delta.
+     * bridges the POI-scoped classes into their matching `location` fields in the
+     * base state cache (see `bridgeObservationToLocation`), so
+     * `account.state.location` reflects live data too once subscribed, instead of
+     * only refreshing on the next `get_status`/mutation delta.
      *
      * Scoped to your current POI the same way `subscribeMarket` is scoped to
      * your current dock — see the docked_at note there; the same silent
@@ -355,14 +365,30 @@ export declare class Account {
     /** Unsubscribe from the observation watch and clear its cache. */
     unsubscribeObservation(): Promise<void>;
     /**
-     * Mirrors the observation watch's POI-scoped player presence into
-     * `location.nearby_players`/`nearby_player_count` in the base state cache,
-     * so code reading `account.state.location` (rather than
-     * `account.observation()`) sees live presence data once subscribed. NPC and
-     * pirate presence (`nearby_empire_npcs`/`nearby_pirates`, their counts, and
-     * `offline_collapsed`) have no equivalent in the observation feed — it only
-     * ever carries player presence — so those fields are left untouched by this
-     * bridge and still only refresh on the next `get_status`/mutation delta.
+     * Mirrors the observation watch's POI-scoped presence into the matching
+     * `location` fields in the base state cache, so code reading
+     * `account.state.location` (rather than `account.observation()`) sees live
+     * data once subscribed: players, pirates, empire NPCs, intact prizes, their
+     * counts, and the cloaked-signature hint. Wildlife has no `location` field —
+     * read creatures from `account.observation()`.
+     *
+     * Three ways the bridged values differ from what `get_status` would return
+     * for the same POI, none of them fixable from here:
+     * - The arrays are uncapped. `get_status` truncates them (50 players, 20
+     *   each of the rest) while reporting the pre-cap total in the count, so a
+     *   bridged array can be longer than the server would ever send. The counts
+     *   mean the same thing either way.
+     * - `offline_collapsed` is a `get_status` response cap the feed does not
+     *   report, so it is left untouched at whatever the server last said. Above
+     *   the crowding threshold `get_status` drops offline players from
+     *   `nearby_players` and counts them there instead; the feed carries them in
+     *   full, so once bridged the two no longer sum — read the array, not the sum.
+     * - `ship_name` on players and empire NPCs is the ship's display name here
+     *   (its custom name, else the class name) where `get_status` sends the
+     *   custom name alone. Present does not imply custom-named while subscribed.
+     *
+     * `unknown_signature` is written even when false, where `get_status` omits
+     * the key; the bridge has to write it to clear a signature that has gone.
      * No-ops if `location` hasn't been seeded yet or nothing is subscribed.
      */
     private bridgeObservationToLocation;

package/dist/index.d.ts

@@ -30,3 +30,11 @@ export type { ToolName, ActionName, ActionDef, ActionParam } from './generated/a
 export type * from './generated/openapi/types.gen.js';
 export { TYPED_NOTIFICATION_TYPES } from './generated/notifications.gen.js';
 export type { NotificationPayloads, TypedNotificationType, } from './generated/notifications.gen.js';
+/**
+ * Payload types for the `ok` and `fleet` push families, plus the discriminator
+ * lists. Hand-written rather than generated: the server publishes no
+ * `Notification_ok` or `Notification_fleet` schema, so codegen has nothing to
+ * derive them from. Re-exported wholesale so a variant added to the unions does
+ * not also have to be remembered here.
+ */
+export * from './push-frames.js';

package/dist/index.js

@@ -3832,6 +3832,15 @@ function indexBy(items, key) {
   }
   return map;
 }
+function merge(map, changed, departed, key) {
+  for (const item of changed ?? []) {
+    const k = key(item);
+    if (k)
+      map.set(k, item);
+  }
+  for (const id of departed ?? [])
+    map.delete(id);
+}
 
 class ObservationCache {
   view = null;
@@ -3842,6 +3851,10 @@ class ObservationCache {
       tick: 0,
       nearby: indexBy(snapshot.nearby, (p) => p.player_id),
       system: indexBy(snapshot.system_agents, (p) => p.player_id),
+      pirates: indexBy(snapshot.pirates, (p) => p.pirate_id),
+      empireNpcs: indexBy(snapshot.empire_npcs, (n) => n.npc_id),
+      creatures: indexBy(snapshot.creatures, (c) => c.creature_id),
+      prizes: indexBy(snapshot.prizes, (p) => p.prize_id),
       cloaked: indexBy(snapshot.cloaked_contacts, (c) => c.target_id),
       unknownSignature: snapshot.unknown_signature ?? false,
       activeScan: snapshot.active_scan ?? false
@@ -3856,6 +3869,10 @@ class ObservationCache {
         tick: update.tick,
         nearby: new Map,
         system: new Map,
+        pirates: new Map,
+        empireNpcs: new Map,
+        creatures: new Map,
+        prizes: new Map,
         cloaked: new Map,
         unknownSignature: false,
         activeScan: false
@@ -3863,21 +3880,13 @@ class ObservationCache {
     }
     const v = this.view;
     v.tick = update.tick;
-    for (const p of update.nearby_changed ?? [])
-      if (p.player_id)
-        v.nearby.set(p.player_id, p);
-    for (const id of update.nearby_departed ?? [])
-      v.nearby.delete(id);
-    for (const p of update.system_changed ?? [])
-      if (p.player_id)
-        v.system.set(p.player_id, p);
-    for (const id of update.system_departed ?? [])
-      v.system.delete(id);
-    for (const c of update.cloaked_resolved ?? [])
-      if (c.target_id)
-        v.cloaked.set(c.target_id, c);
-    for (const id of update.cloaked_lost ?? [])
-      v.cloaked.delete(id);
+    merge(v.nearby, update.nearby_changed, update.nearby_departed, (p) => p.player_id);
+    merge(v.system, update.system_changed, update.system_departed, (p) => p.player_id);
+    merge(v.pirates, update.pirates_changed, update.pirates_departed, (p) => p.pirate_id);
+    merge(v.empireNpcs, update.empire_npcs_changed, update.empire_npcs_departed, (n) => n.npc_id);
+    merge(v.creatures, update.creatures_changed, update.creatures_departed, (c) => c.creature_id);
+    merge(v.prizes, update.prizes_changed, update.prizes_departed, (p) => p.prize_id);
+    merge(v.cloaked, update.cloaked_resolved, update.cloaked_lost, (c) => c.target_id);
     if (update.unknown_signature !== undefined)
       v.unknownSignature = update.unknown_signature;
     if (update.active_scan !== undefined)
@@ -4579,9 +4588,39 @@ class Account {
       ...p.ship_name !== undefined && { ship_name: p.ship_name },
       ...p.username !== undefined && { username: p.username }
     }));
+    const nearbyPirates = [...view.pirates.values()].map((p) => ({
+      pirate_id: p.pirate_id,
+      name: p.name,
+      tier: p.tier,
+      is_boss: p.is_boss,
+      status: p.status,
+      hull: p.hull ?? 0,
+      max_hull: p.max_hull ?? 0,
+      shield: p.shield ?? 0,
+      max_shield: p.max_shield ?? 0,
+      ...p.faction !== undefined && { faction: p.faction },
+      ...p.faction_name !== undefined && { faction_name: p.faction_name }
+    }));
+    const nearbyEmpireNpcs = [...view.empireNpcs.values()].map((n) => ({
+      npc_id: n.npc_id,
+      name: n.name,
+      role: n.role,
+      empire: n.empire,
+      in_combat: n.in_combat,
+      ...n.fleet_name !== undefined && { fleet_name: n.fleet_name },
+      ...n.ship_class !== undefined && { ship_class: n.ship_class },
+      ...n.ship_name !== undefined && { ship_name: n.ship_name }
+    }));
     const changed = this.cache.patchSection("location", {
       nearby_players: nearbyPlayers,
-      nearby_player_count: view.nearby.size
+      nearby_player_count: view.nearby.size,
+      nearby_pirates: nearbyPirates,
+      nearby_pirate_count: view.pirates.size,
+      nearby_empire_npcs: nearbyEmpireNpcs,
+      nearby_empire_npc_count: view.empireNpcs.size,
+      nearby_prizes: [...view.prizes.values()],
+      nearby_prize_count: view.prizes.size,
+      unknown_signature: view.unknownSignature
     });
     if (changed.length)
       this.stateRevision++;
@@ -5533,6 +5572,48 @@ var TYPED_NOTIFICATION_TYPES = [
   "trade_declined",
   "trade_offer_received"
 ];
+// src/push-frames.ts
+var OK_PUSH_ACTIONS = [
+  "travel",
+  "jump",
+  "fleet_travel",
+  "fleet_jump",
+  "fleet_dock",
+  "fleet_undock",
+  "passenger_stranded",
+  "mobile_capital_transit",
+  "espionage",
+  "arrived",
+  "jumped",
+  "pathfinder_arrival",
+  "dock",
+  "attack",
+  "pathfinder_jump",
+  "pathfinder_redirect"
+];
+var OK_PUSH_TYPES = [
+  "auto_dock",
+  "auto_undock",
+  "emergency_warp_stabilizer_activated",
+  "passenger_arrivals",
+  "passengers_transferred",
+  "ship_processing",
+  "transit_lounge_departures",
+  "shipment_overdue",
+  "new_forum_post"
+];
+var FLEET_PUSH_ACTIONS = [
+  "fleet_invite",
+  "fleet_member_joined",
+  "fleet_member_left",
+  "fleet_member_kicked",
+  "fleet_kicked",
+  "fleet_disbanded",
+  "fleet_leader_promoted",
+  "fleet_member_died",
+  "fleet_passenger_boarded",
+  "fleet_passenger_disembarked"
+];
 export {
   ACTIONS,
   Account,
@@ -5541,10 +5622,13 @@ export {
   ClerkSource,
   ConnectionClosedError,
   EventStream,
+  FLEET_PUSH_ACTIONS,
   GENERATED_SPEC_VERSION,
   MapCache,
   MarketCache,
   MemoryCredentialStore,
+  OK_PUSH_ACTIONS,
+  OK_PUSH_TYPES,
   ObservationCache,
   STATE_SECTIONS,
   Socket,

package/dist/push-frames.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Hand-written payload types for the `ok` and `fleet` push frames.
+ *
+ * Every other push frame is typed from the server's published
+ * `Notification_<msg_type>` schema, and the generated `NotificationPayloads`
+ * map carries it. These two families publish no schema at all — neither
+ * appears in the spec's notification union — so without this file they reach a
+ * consumer as `Record<string, unknown>`.
+ *
+ * They are hand-written rather than published because splitting them into
+ * distinct `msg_type`s is the fix, and that breaks any v1 client switching on
+ * `type === "ok"`. Until v1 is retired the shapes live here.
+ * `tests/push-frames.test.ts` fails the moment the server does publish either
+ * schema, which is the signal to delete this file and let codegen take over.
+ *
+ * **Two discriminators.** Most `ok` variants key on `action`; seven key on
+ * `type` instead. That split is the server's, not ours, so a bare `p.action`
+ * does not compile on `OkPush` — guard with `'action' in p` first, or narrow to
+ * `OkActionPush` / `OkTypePush`. `FleetPush` has a single key and needs no guard.
+ *
+ * **The unions are closed**, derived from gameserver v0.596.2. A member typed
+ * `{ action: string }` to absorb later frames would join every literal's
+ * narrowing and make all of them useless. The cost is that a variant the server
+ * adds after that build still arrives at your `on('ok')` handler — nothing
+ * validates the payload against these types — as a value matching no member. An
+ * exhaustive `switch` with a `never` default therefore compiles but is unsafe at
+ * runtime; give it a real default branch.
+ */
+import type { AttackNpcResponse, AttackPlayerResponse, DockResponse, EspionageResponse, JumpResponse, PathfinderJumpResponse, TravelResponse } from './generated/openapi/types.gen.js';
+/** Human-readable summary, carried by the hand-written variants below. */
+interface PushBase {
+    message?: string;
+}
+/** Your own transit started. `applyMovementPush` applies this to the cache. */
+export interface OkTravelStarted extends PushBase {
+    action: 'travel';
+    /** POI ID being travelled to. */
+    destination: string;
+    /** Engine tick the arrival lands on. */
+    arrival_tick: number;
+}
+/** Your own jump started. `applyMovementPush` applies this to the cache. */
+export interface OkJumpStarted extends PushBase {
+    action: 'jump';
+    /** System ID being jumped to. */
+    destination: string;
+    arrival_tick: number;
+    /** True when the jump routes through a wormhole rather than a lane. */
+    is_wormhole: boolean;
+}
+/** Your fleet leader started an in-system travel and pulled you along. */
+export interface OkFleetTravelStarted extends PushBase {
+    action: 'fleet_travel';
+    destination: string;
+    arrival_tick: number;
+}
+/** Your fleet leader started a jump and pulled you along. */
+export interface OkFleetJumpStarted extends PushBase {
+    action: 'fleet_jump';
+    destination: string;
+    arrival_tick: number;
+}
+/** Your fleet leader docked and took the fleet with them. */
+export interface OkFleetDocked extends PushBase {
+    action: 'fleet_dock';
+    /** Station display name. */
+    base: string;
+    /** Canonical base ID — this is what `location.docked_at` holds, not `base`. */
+    base_id: string;
+}
+/** Your fleet leader undocked and took the fleet with them. */
+export interface OkFleetUndocked extends PushBase {
+    action: 'fleet_undock';
+}
+/**
+ * The ship you were riding was destroyed or captured. You are at your home
+ * station with no ship. A state delta follows on a v2 socket; `riding` is not a
+ * state section, so clear any cached value yourself.
+ */
+export interface OkPassengerStranded extends PushBase {
+    action: 'passenger_stranded';
+}
+/** The Mobile Capital jumped while you were docked at it, taking you along. */
+export interface OkMobileCapitalTransit extends PushBase {
+    action: 'mobile_capital_transit';
+    /** System ID the station arrived in. */
+    system: string;
+}
+/**
+ * An espionage operation you launched is under way (start) or resolved
+ * (outcome). The two shapes differ: the start carries `arrival_tick`, the
+ * resolution carries `outcome` and `story`. Only the start reaches a v2 socket
+ * — the resolution ships as a delta-carrying `action_result` — but both are
+ * here because a v1 transport sees both.
+ */
+export type OkEspionage = (PushBase & {
+    action: 'espionage';
+    arrival_tick: number;
+}) | (EspionageResponse & {
+    action: 'espionage';
+});
+/**
+ * In-system travel completed.
+ *
+ * v1 transports only. Over `/ws/v2` an arrival is a delta-carrying
+ * `action_result`; this plain broadcast is the fallback taken when no delta
+ * sections are set. A v2 consumer's `arrived` handler never fires — read
+ * `account.location` instead.
+ */
+export type OkArrived = TravelResponse & {
+    action: 'arrived';
+};
+/**
+ * A jump or Pathfinder drift completed. `pathfinder_arrival` is the off-network
+ * variant. v1 transports only, for the same reason as `OkArrived`.
+ */
+export type OkJumped = JumpResponse;
+/** Docking completed. */
+export type OkDocked = DockResponse & {
+    action: 'dock';
+};
+/**
+ * An attack resolved. Two shapes share the action and are separated by `kind`:
+ * `npc` covers pirates, wildlife, stations and prize hulls; `player` is PvP.
+ */
+export type OkAttack = AttackNpcResponse | AttackPlayerResponse;
+/** A Pathfinder off-network jump was plotted, or an in-flight drift replotted. */
+export type OkPathfinderPlot = PathfinderJumpResponse;
+/** The server docked you so a dock-required command could run. */
+export interface OkAutoDock extends PushBase {
+    type: 'auto_dock';
+}
+/** The server undocked you so a command needing open space could run. */
+export interface OkAutoUndock extends PushBase {
+    type: 'auto_undock';
+}
+/** An Emergency Warp Stabilizer fired at critical hull and warped you home. */
+export interface OkEmergencyWarpStabilizer extends PushBase {
+    type: 'emergency_warp_stabilizer_activated';
+    /** Home station display name — not a base ID. */
+    home_base: string;
+    hull: number;
+    max_hull: number;
+}
+/** Passengers you were carrying reached their destination. */
+export interface OkPassengerArrivals extends PushBase {
+    type: 'passenger_arrivals';
+    station: string;
+    delivered: number;
+    stranded: number;
+    fare_collected: number;
+    /**
+     * Reputation change per counterparty, keyed by empire or stronghold ID. The
+     * key is always present, but the value is `null` when the delivery moved no
+     * reputation — the common case. Check before iterating.
+     */
+    reputation_changes: Record<string, number> | null;
+}
+/** Another player moved connecting passengers onto one of your ships. */
+export interface OkPassengersTransferred extends PushBase {
+    type: 'passengers_transferred';
+    /** ID of your ship the passengers were moved onto. */
+    ship_id: string;
+    count: number;
+    /** Station display name. */
+    station: string;
+}
+/** A ship-processing job at a station finished. */
+export interface OkShipProcessing extends PushBase {
+    type: 'ship_processing';
+}
+/** Passengers are waiting in a transit lounge you can pick up from. */
+export interface OkTransitLoungeDepartures extends PushBase {
+    type: 'transit_lounge_departures';
+    station: string;
+    base_id: string;
+    passengers: number;
+    /** Ticks until the soonest departure. */
+    soonest_ticks: number;
+}
+/** A shipment you contracted for is past its delivery window. */
+export interface OkShipmentOverdue extends PushBase {
+    type: 'shipment_overdue';
+    shipment_id: string;
+    package_id: string;
+    /** Base ID the shipment is bound for. */
+    destination: string;
+    /** Ticks left before the shipment is recovered. */
+    recovery_ticks: number;
+    late_fee: number;
+}
+/** A new forum thread was posted. Broadcast to every connected player. */
+export interface OkNewForumPost extends PushBase {
+    type: 'new_forum_post';
+    thread_id: string;
+    title: string;
+    author: string;
+    category: string;
+    /** RFC3339 timestamp. */
+    timestamp: string;
+    is_dev_team: boolean;
+}
+/**
+ * A wildlife kill notice, sent when a hunt lands. Carries neither `action` nor
+ * `type` — the optional-undefined keys are what let the other members stay
+ * narrowable alongside it.
+ */
+export interface OkMessageOnly {
+    action?: undefined;
+    type?: undefined;
+    message: string;
+}
+/** You were invited to a fleet. */
+export interface FleetInvite extends PushBase {
+    action: 'fleet_invite';
+    fleet_id: string;
+    leader_name: string;
+    leader_id: string;
+    /** True for a fleet auto-created to carry an arena challenge. */
+    arena_only: boolean;
+}
+/** Someone joined the fleet. Sent to every other member. */
+export interface FleetMemberJoined {
+    action: 'fleet_member_joined';
+    player_id: string;
+    player_name: string;
+}
+/** Someone left the fleet. Sent to every other member. */
+export interface FleetMemberLeft {
+    action: 'fleet_member_left';
+    player_id: string;
+    player_name: string;
+}
+/** The leader removed someone. Sent to the remaining members, not the target. */
+export interface FleetMemberKicked {
+    action: 'fleet_member_kicked';
+    player_id: string;
+    player_name: string;
+}
+/** The leader removed *you* from the fleet. */
+export interface FleetKicked extends PushBase {
+    action: 'fleet_kicked';
+}
+/** The fleet was disbanded. */
+export interface FleetDisbanded extends PushBase {
+    action: 'fleet_disbanded';
+}
+/** Fleet leadership passed to another member. */
+export interface FleetLeaderPromoted extends PushBase {
+    action: 'fleet_leader_promoted';
+    new_leader: string;
+}
+/** A fleet member died. */
+export interface FleetMemberDied extends PushBase {
+    action: 'fleet_member_died';
+    player_name: string;
+}
+/** A passenger boarded a fleet ship. */
+export interface FleetPassengerBoarded extends PushBase {
+    action: 'fleet_passenger_boarded';
+    player_id: string;
+    player_name: string;
+}
+/** A passenger stopped riding and left the fleet. */
+export interface FleetPassengerDisembarked extends PushBase {
+    action: 'fleet_passenger_disembarked';
+    player_id: string;
+    player_name: string;
+}
+/** Every `ok` push known as of gameserver v0.596.2. */
+export type OkPush = OkTravelStarted | OkJumpStarted | OkFleetTravelStarted | OkFleetJumpStarted | OkFleetDocked | OkFleetUndocked | OkPassengerStranded | OkMobileCapitalTransit | OkEspionage | OkArrived | OkJumped | OkDocked | OkAttack | OkPathfinderPlot | OkAutoDock | OkAutoUndock | OkEmergencyWarpStabilizer | OkPassengerArrivals | OkPassengersTransferred | OkShipProcessing | OkTransitLoungeDepartures | OkShipmentOverdue | OkNewForumPost | OkMessageOnly;
+/** The `ok` variants keyed on `action`. `Extract`ed for an exhaustive switch. */
+export type OkActionPush = Extract<OkPush, {
+    action: string;
+}>;
+/** The `ok` variants keyed on `type`. `Extract`ed for an exhaustive switch. */
+export type OkTypePush = Extract<OkPush, {
+    type: string;
+}>;
+/** Every `fleet` push known as of gameserver v0.596.2, all keyed on `action`. */
+export type FleetPush = FleetInvite | FleetMemberJoined | FleetMemberLeft | FleetMemberKicked | FleetKicked | FleetDisbanded | FleetLeaderPromoted | FleetMemberDied | FleetPassengerBoarded | FleetPassengerDisembarked;
+/** `action` values carried by an `ok` push. */
+export declare const OK_PUSH_ACTIONS: readonly ["travel", "jump", "fleet_travel", "fleet_jump", "fleet_dock", "fleet_undock", "passenger_stranded", "mobile_capital_transit", "espionage", "arrived", "jumped", "pathfinder_arrival", "dock", "attack", "pathfinder_jump", "pathfinder_redirect"];
+export type OkPushAction = (typeof OK_PUSH_ACTIONS)[number];
+/** `type` values carried by an `ok` push, for the frames that use that key. */
+export declare const OK_PUSH_TYPES: readonly ["auto_dock", "auto_undock", "emergency_warp_stabilizer_activated", "passenger_arrivals", "passengers_transferred", "ship_processing", "transit_lounge_departures", "shipment_overdue", "new_forum_post"];
+export type OkPushType = (typeof OK_PUSH_TYPES)[number];
+/** `action` values carried by a `fleet` push. */
+export declare const FLEET_PUSH_ACTIONS: readonly ["fleet_invite", "fleet_member_joined", "fleet_member_left", "fleet_member_kicked", "fleet_kicked", "fleet_disbanded", "fleet_leader_promoted", "fleet_member_died", "fleet_passenger_boarded", "fleet_passenger_disembarked"];
+export type FleetPushAction = (typeof FLEET_PUSH_ACTIONS)[number];
+export {};

package/dist/state/observation.d.ts

@@ -2,11 +2,18 @@
  * Local cache of the subscribed observation watch (current POI + system).
  *
  * Seeded from the `subscribe_observation` baseline and kept current by merging
- * `observation_update` pushes: `*_changed` arrays upsert players (keyed by
- * `player_id`), `*_departed` arrays (player_id strings) remove them, and the
+ * `observation_update` pushes: `*_changed` arrays upsert entities (keyed by
+ * their own id), `*_departed` arrays (id strings) remove them, and the
  * cloaked-contact / signature hints are tracked alongside.
+ *
+ * Not a players-only feed: the baseline and every update also carry the
+ * pirate, empire-NPC, wildlife and intact-prize presence at the watched POI,
+ * each with the same changed/departed delta shape as players. It covers five
+ * of `get_nearby`'s six classes — arena NPCs are the one it does not carry, so
+ * a player in an arena match still has to poll `get_nearby` for their
+ * opponents. `offline_collapsed` has no equivalent here either.
  */
-import type { NotificationObservationUpdate, SubscribeObservationResponse } from '../generated/openapi/types.gen.js';
+import type { CreatureInfo, EmpireNpcInfo, NotificationObservationUpdate, PirateInfo, PrizeInfo, SubscribeObservationResponse } from '../generated/openapi/types.gen.js';
 export type ObservedPlayer = NonNullable<NotificationObservationUpdate['nearby_changed']>[number];
 export type CloakedContact = NonNullable<NotificationObservationUpdate['cloaked_resolved']>[number];
 export interface ObservationView {
@@ -18,6 +25,14 @@ export interface ObservationView {
     nearby: Map<string, ObservedPlayer>;
     /** Uncloaked players system-wide, keyed by player_id. */
     system: Map<string, ObservedPlayer>;
+    /** Pirate NPCs at the watched POI, keyed by pirate_id. */
+    pirates: Map<string, PirateInfo>;
+    /** Empire NPCs at the watched POI, keyed by npc_id. */
+    empireNpcs: Map<string, EmpireNpcInfo>;
+    /** Wildlife at the watched POI, keyed by creature_id. */
+    creatures: Map<string, CreatureInfo>;
+    /** Intact captured ships at the watched POI, keyed by prize_id. */
+    prizes: Map<string, PrizeInfo>;
     /** Cloaked contacts resolved by an active sensor sweep, keyed by target_id. */
     cloaked: Map<string, CloakedContact>;
     /** A faint cloaked-ship signature is present at the watched POI. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacemolt/lib",
-  "version": "14.0.1",
+  "version": "14.2.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",