@aeroswarm/client 0.1.12 → 0.1.14

package/README.md

@@ -65,6 +65,23 @@ client.disconnect();
 | `tracks.stream(opts)` | Same live stream as an `AsyncIterable<LabeledTrack>` (`for await`) |
 | `tracks.updateFilter(opts)` | Change bbox / minConfidence / maxUpdateHz / maxTracks without reconnecting |
 | `tracks.reconnect()` | Force an immediate reconnect (skips backoff, re-subscribes with the last options, resumes after `disconnect()`); `false` if never subscribed. Also `AeroSwarm.reconnect()` and `useAeroTracks().reconnect` |
+| `tracks.snapshot(input?)` | One-shot current state via tRPC (`airportId`, `bbox`, `source`, `minConfidence`, `limit`, `offset`) |
+| `tracks.history(input)` | Persisted position history for one track (`trackId`, `airportId?`, `limit?`) — federated airports are served by their own backend |
+| `airports.*` | Airport registry: `list/create/update/delete` + `surface`/`setSurface` (runway/taxiway/apron GeoJSON for the map) |
+| `sources.*` | Register/list (optionally by `airportId`)/delete data sources (returns per-source auth tokens) |
+| `alerts.*` | Alert history + live alert subscription |
+| `rules.*` | Detection-rule CRUD — **global or per-airport** (see example below) |
+| `routes.*` | Route conformance: pre-defined ground routes + live track clearances (deviation alerts) |
+| `analytics.movements()` | Takeoffs/landings per hour + peak hour, per airport |
+| `webhooks.*` | Webhook CRUD |
+| `replay.days(input?)` | Data-availability calendar — which days have recorded tracks (see example below) |
+| `replay.range/seek/window` | Historical replay metadata: range summary, point-in-time seek, time-bucketed window for scrubbing |
+| `replay.stream(opts, cb)` | **Server-paced WS playback** — historical tracks streamed like live (see example below) |
+| `system.*` | `stats`, `infraHealth`, `getConfig`/`setConfig`, `clearTable`, `ingestHistory` |
+| `trpc` / `rest` / `graphql` | Direct typed API clients for anything not wrapped above — **untyped** (`createTRPCProxyClient<any>`), so prefer the wrappers above; fall back to `client.trpc.<router>.<procedure>.query/mutate(...)` only for endpoints not yet wrapped |
+| `cache` | A `TrackCache` instance (see below) |
+| `getStatus()` / `getLastUpdateAt()` / `getError()` / `getSourceStatus()` | Connection introspection |
+| `disconnect()` | Tear down the WS connection |
 
 ### Label category / color
 
@@ -106,6 +123,7 @@ The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client
   "targetType": "aircraft",       // optional: aircraft | vehicle | unknown
   "vehicleFleet": 3,              // optional, only for vehicles
   "airportId": "WARR",            // optional ICAO scope
+  "dataSource": { "sac": 32, "sic": 136 },  // optional: the sensor behind the position shown (ASTERIX feeds)
   "lat": -7.3797, "lon": 112.7868,// number | null
   "altitudeFt": 0,
   "groundSpeedKt": 12,
@@ -127,23 +145,8 @@ The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client
 ```
 
 `status` and `labelColor` change only when the track's category or status actually changes — position-only deltas leave them untouched, so a label painted from `labelColor` does not flicker.
-| `tracks.snapshot(input?)` | One-shot current state via tRPC (`airportId`, `bbox`, `source`, `minConfidence`, `limit`, `offset`) |
-| `tracks.history(input)` | Persisted position history for one track (`trackId`, `airportId?`, `limit?`) — federated airports are served by their own backend |
-| `airports.*` | Airport registry: `list/create/update/delete` + `surface`/`setSurface` (runway/taxiway/apron GeoJSON for the map) |
-| `sources.*` | Register/list (optionally by `airportId`)/delete data sources (returns per-source auth tokens) |
-| `alerts.*` | Alert history + live alert subscription |
-| `rules.*` | Detection-rule CRUD — **global or per-airport** (see example below) |
-| `routes.*` | Route conformance: pre-defined ground routes + live track clearances (deviation alerts) |
-| `analytics.movements()` | Takeoffs/landings per hour + peak hour, per airport |
-| `webhooks.*` | Webhook CRUD |
-| `replay.days(input?)` | Data-availability calendar — which days have recorded tracks (see example below) |
-| `replay.range/seek/window` | Historical replay metadata: range summary, point-in-time seek, time-bucketed window for scrubbing |
-| `replay.stream(opts, cb)` | **Server-paced WS playback** — historical tracks streamed like live (see example below) |
-| `system.*` | `stats`, `infraHealth`, `getConfig`/`setConfig`, `clearTable`, `ingestHistory` |
-| `trpc` / `rest` / `graphql` | Direct typed API clients for anything not wrapped above — **untyped** (`createTRPCProxyClient<any>`), so prefer the wrappers above; fall back to `client.trpc.<router>.<procedure>.query/mutate(...)` only for endpoints not yet wrapped |
-| `cache` | A `TrackCache` instance (see below) |
-| `getStatus()` / `getLastUpdateAt()` / `getError()` / `getSourceStatus()` | Connection introspection |
-| `disconnect()` | Tear down the WS connection |
+
+`dataSource` is the ASTERIX System Area / System Identification Code (SAC/SIC) of the sensor that reported the position shown (for a merged track, the sensor that is currently preferred). `formatDataSource(track)` gives the display string `"ADSB 32/136"` (`sourceLabel(track.source)` gives just the kind: `ADSB`, `SURFACE` for CAT010/011, `MLAT`, `RADAR`, `SYSTEM`, `FUSED`); without a SAC/SIC it is the kind alone.
 
 ## Per-domain usage examples
 
@@ -449,7 +452,59 @@ Shared live-track state; feed it from your subscription callbacks and read it im
 | `setStatus` / `setSourceStatus` / `setError` / `setDegraded` / `clear` | Connection metadata |
 | Selectors | `selectAllTracks`, `selectRenderableTracks`, `selectTrack(id)`, `selectTrackCount`, `selectStatus`, `selectIsDegraded`, `selectLastUpdateAt`, `selectError` |
 
-### `useTrackHistory` — smooth map animation
+### REST errors: `AeroApiError`
+
+Every failed REST call (`client.rest.*`, federated `tracks.history` and the like) throws an `AeroApiError` that keeps what the server said, instead of just `GET /x → 500`:
+
+```ts
+try { await client.tracks.history({ trackId, airportId: "WARR" }); }
+catch (e) {
+  if (e instanceof AeroApiError) {
+    e.status;       // 403
+    e.code;         // "FORBIDDEN" — stable, for switch; a newer server may send a code you do not know
+    e.recoverable;  // retrying later may help (rate limit, server busy)
+    e.message;      // "Federated request /tracks/t1/history → 403: not your airport"
+    e.details;      // whatever the server attached
+  }
+}
+```
+Servers answer either in the standard format (`{ ok, data, meta }` / `{ ok: false, error: { code, message, recoverable } }`, see `@aeroswarm/core/api`) or in the older shape (bare data, `{ ok: false, error: "text" }`); both are read. Federated calls send `x-aero-envelope: 1` to get the standard format. `parseApiResponse(res)` and `readApiBody(res)` are exported for your own `fetch` calls.
+
+### `useTrackMotion` / `createTrackMotion` — smooth live tracks
+
+Feeds update a track once a second (MLAT, ADS-B) or once per antenna sweep (radar, ~7.5 s). Drawn as they arrive, icons jump. `createTrackMotion` (no React needed) shows where the aircraft *probably is right now* and eases corrections in, like a flight tracker:
+
+```ts
+import { createTrackMotion } from "@aeroswarm/client";
+
+const motion = createTrackMotion();                     // all options optional
+
+client.tracks.subscribe(opts, {
+  onSnapshot: (tracks, meta) => tracks.forEach((t) => motion.update(t, meta)),
+  onTrackUpdate: (t, meta) => motion.update(t, meta),   // meta.serverTime keeps the clocks aligned
+  onTrackRemoved: ({ trackId }) => motion.remove(trackId),
+});
+
+const stop = motion.start(({ changed }) => {            // ~30 frames/s, only tracks that moved
+  for (const [id, s] of changed) layer.put(id, s.lat, s.lon, s.headingDeg);
+});
+```
+
+React: `const motion = useTrackMotion({ onFrame })`, then call `motion.update(...)` from the subscription. Nothing here renders React.
+
+What it does:
+
+| | |
+|---|---|
+| **Dead reckoning** | From the last fix, speed and heading carry the position forward, up to `maxExtrapolateMs` (20 s in the air, 8 s on the surface). `lost` tracks freeze. |
+| **Eased corrections** | A new fix does not snap the icon. The gap between where it was shown and where the fix says it should be becomes an offset that fades out (smoothstep over `blendMs`, 1.5 s). The icon keeps moving at its own speed meanwhile, so there is no stop-and-go at every update. A correction larger than `snapDistanceM` (5 km) is a glitch and jumps. |
+| **Heading** | Eases along the shortest arc (`headingSmoothMs`, 0.8 s); keeps the last heading when the track stops. |
+| **Server clock** | `lastSeenAt` is the server's clock. `meta.serverTime` of each message lets the engine learn the offset to the browser clock (the estimate with the least network delay wins), so a wrong browser clock does not stretch or shrink the prediction. |
+| **Cheap frames** | Tracks that stand still, or whose picture changed by less than `epsilonM` (0.5 m) / 0.5°, are not reported; no timer runs while nothing moves; `frameHz` caps the rate (30). |
+
+Options (`MotionOptions`): `blendMs`, `headingSmoothMs`, `maxExtrapolateMs`, `minMovingKt` (5), `snapDistanceM`, `frameHz`, `epsilonM`, `extrapolate` (`false` shows raw positions, for comparing sources), `isSurface`, `clock` (inject the replay clock to play back at another speed), `scheduler` (tests). `motion.sample(id)` gives the shown position at any time without touching frame state, e.g. to attach a trail's head to the icon.
+
+### `useTrackHistory` — smooth map animation (deprecated: use `useTrackMotion`)
 
 Maintains per-track position interpolation (tweening), dead-reckoning between updates, and bounded trail history, emitting animation frames outside React render:
 

package/dist/index-ByNBpjNk.d.ts

@@ -0,0 +1,75 @@
+import { CurrentTrack } from '@aeroswarm/core/types';
+
+/** What the engine reads from a track. */
+type MotionInput = Pick<CurrentTrack, "trackId" | "lat" | "lon" | "groundSpeedKt" | "headingDeg" | "altitudeFt" | "status" | "lastSeenAt"> & {
+    targetType?: CurrentTrack["targetType"];
+};
+interface MotionSample {
+    lat: number;
+    lon: number;
+    /** Degrees 0..360, eased; null until a valid heading has been seen. */
+    headingDeg: number | null;
+    altitudeFt: number | null;
+    /** Speed is above `minMovingKt`. */
+    moving: boolean;
+    /** Position currently comes from dead reckoning (not frozen, limit not reached). */
+    extrapolating: boolean;
+}
+interface MotionFrame {
+    /** Server-aligned time of this frame (ms). */
+    at: number;
+    /** Only tracks whose picture changed since the previous frame. */
+    changed: ReadonlyMap<string, MotionSample>;
+}
+interface MotionScheduler {
+    request(callback: (timestamp: number) => void): unknown;
+    cancel(handle: unknown): void;
+}
+interface MotionOptions {
+    /** How long a correction takes to fade out. Default 1500 ms. */
+    blendMs?: number;
+    /** How long the icon takes to turn to a new heading. Default 800 ms. */
+    headingSmoothMs?: number;
+    /** Dead reckoning stops after this long without a new fix. Default 20 s in the air, 8 s on the surface. */
+    maxExtrapolateMs?: {
+        air: number;
+        surface: number;
+    };
+    /** Below this speed a track is treated as standing still. Default 5 kt. */
+    minMovingKt?: number;
+    /** A correction larger than this is a glitch or a sensor change far away: jump instead of easing. Default 5000 m. */
+    snapDistanceM?: number;
+    /** Frame rate limit for `start()`. Default 30. */
+    frameHz?: number;
+    /** Changes smaller than this are not reported. Default 0.5 m (and 0.5 degrees of heading). */
+    epsilonM?: number;
+    /** false = show raw positions (for comparing against another source). Default true. */
+    extrapolate?: boolean;
+    /** Decides what counts as "on the surface". Default: vehicles, or below 150 ft. */
+    isSurface?: (track: MotionInput) => boolean;
+    /** Browser clock. Default Date.now. Inject the replay clock to play back at another speed. */
+    clock?: () => number;
+    /** Frame timer. Default requestAnimationFrame, else setTimeout. Inject in tests. */
+    scheduler?: MotionScheduler;
+}
+interface TrackMotion {
+    /** `meta.serverTime` (from the WS envelope) keeps the server/browser clock offset current. */
+    update(track: MotionInput, meta?: {
+        serverTime?: number;
+    }): void;
+    remove(trackId: string): void;
+    clear(): void;
+    /** Where the track is shown at `at` (browser time; default now). Pure: does not touch frame state. */
+    sample(trackId: string, at?: number): MotionSample | undefined;
+    /** One frame: the tracks whose picture changed since the previous frame. `start()` calls this for you. */
+    tick(at?: number): ReadonlyMap<string, MotionSample>;
+    /** Runs frames until the returned function is called. Idles (no timer) while nothing moves. */
+    start(onFrame: (frame: MotionFrame) => void): () => void;
+    /** Tracks currently held. */
+    readonly size: number;
+    /** Current server minus browser clock, ms. */
+    offsetMs(): number;
+}
+declare function createTrackMotion(options?: MotionOptions): TrackMotion;
+
+export { type MotionFrame as M, type TrackMotion as T, type MotionInput as a, type MotionOptions as b, type MotionSample as c, type MotionScheduler as d, createTrackMotion as e };