@aeroswarm/client 0.1.13 → 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,6 +452,24 @@ 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` |
 
+### 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:

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 };

package/dist/{index-BXiTmKdS.d.ts → index-CyxVoJXL.d.ts}

@@ -332,6 +332,38 @@ declare class TrackCache extends TypedEmitter<{
     })[];
 }
 
+/** Mirrors `API_ERROR_CODES` in @aeroswarm/core/api. A server may send codes this client does not know. */
+type ApiErrorCode = "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "BAD_REQUEST" | "CONFLICT" | "RATE_LIMITED" | "UNAVAILABLE" | "INTERNAL";
+/** The code for an HTTP status when the server sent none. */
+declare function codeForStatus(status: number): ApiErrorCode;
+interface ApiErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    recoverable: boolean;
+    details?: unknown;
+}
+/** A REST call failed. `code` is stable and meant for `switch`; `message` is for people. */
+declare class AeroApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Retrying later may succeed (rate limit, server busy or failing). */
+    readonly recoverable: boolean;
+    readonly details?: unknown;
+    constructor(init: ApiErrorInit);
+}
+/**
+ * The parsed JSON of a response, untouched. Throws `AeroApiError` for a non-2xx status
+ * and for a 2xx that carries `{ ok: false }`. For endpoints whose callers read the
+ * envelope themselves (`r.data.x`).
+ */
+declare function readApiBody(res: Response, label?: string): Promise<unknown>;
+/**
+ * The data of a response: unwrapped from `{ ok, data }`, or the body as it is for servers
+ * that answer with bare data. Throws `AeroApiError` on failure.
+ */
+declare function parseApiResponse<T>(res: Response, label?: string): Promise<T>;
+
 interface AeroSwarmOptions {
     endpoint: string;
     token: string;
@@ -698,4 +730,4 @@ declare class AeroSwarm {
     reconnect(): boolean;
 }
 
-export { AeroReplayClient as A, type DayAvailability as D, type FlightPlanRow as F, LABEL_COLORS as L, type ReplayCallbacks as R, type SourceRow as S, TrackCache as T, type UseAeroTracksResult as U, AeroSwarm as a, type AeroSwarmOptions as b, AeroWsClient as c, type AftnMessageRow as d, type LabelCategory as e, type LabeledTrack as f, type LiveTrackCallbacks as g, type ReplayHandle as h, type ReplayProgress as i, type ReplayStreamOptions as j, type StreamMeta as k, type SubscribeOptions as l, type TrackCallbacks as m, type TrackHistoryPoint as n, getLabelCategory as o, withLabel as w };
+export { AeroApiError as A, type DayAvailability as D, type FlightPlanRow as F, LABEL_COLORS as L, type ReplayCallbacks as R, type SourceRow as S, TrackCache as T, type UseAeroTracksResult as U, AeroReplayClient as a, AeroSwarm as b, type AeroSwarmOptions as c, AeroWsClient as d, type AftnMessageRow as e, type ApiErrorCode as f, type ApiErrorInit as g, type LabelCategory as h, type LabeledTrack as i, type LiveTrackCallbacks as j, type ReplayHandle as k, type ReplayProgress as l, type ReplayStreamOptions as m, type StreamMeta as n, type SubscribeOptions as o, type TrackCallbacks as p, type TrackHistoryPoint as q, codeForStatus as r, getLabelCategory as s, parseApiResponse as t, readApiBody as u, withLabel as w };

package/dist/index.d.ts

@@ -1,79 +1,26 @@
-export { A as AeroReplayClient, a as AeroSwarm, b as AeroSwarmOptions, c as AeroWsClient, d as AftnMessageRow, D as DayAvailability, F as FlightPlanRow, L as LABEL_COLORS, e as LabelCategory, f as LabeledTrack, g as LiveTrackCallbacks, R as ReplayCallbacks, h as ReplayHandle, i as ReplayProgress, j as ReplayStreamOptions, S as SourceRow, k as StreamMeta, l as SubscribeOptions, T as TrackCache, m as TrackCallbacks, n as TrackHistoryPoint, U as UseAeroTracksResult, o as getLabelCategory, w as withLabel } from './index-BXiTmKdS.js';
+export { A as AeroApiError, a as AeroReplayClient, b as AeroSwarm, c as AeroSwarmOptions, d as AeroWsClient, e as AftnMessageRow, f as ApiErrorCode, g as ApiErrorInit, D as DayAvailability, F as FlightPlanRow, L as LABEL_COLORS, h as LabelCategory, i as LabeledTrack, j as LiveTrackCallbacks, R as ReplayCallbacks, k as ReplayHandle, l as ReplayProgress, m as ReplayStreamOptions, S as SourceRow, n as StreamMeta, o as SubscribeOptions, T as TrackCache, p as TrackCallbacks, q as TrackHistoryPoint, U as UseAeroTracksResult, r as codeForStatus, s as getLabelCategory, t as parseApiResponse, u as readApiBody, w as withLabel } from './index-CyxVoJXL.js';
 import { CurrentTrack } from '@aeroswarm/core/types';
-export { AeroConnectionStatus, AeroRecoverableError, Bbox, ConfidenceBudget, CurrentTrack, FlightPhase, FlightPlan, FlightPlanStatus, FlightPlanSummary, FusedTrackEvent, Position, Protocol, SourceHealthEvent, SourceStatus, StreamEnvelope, TrackSource, TrackStatus, Velocity } from '@aeroswarm/core/types';
+export { AeroConnectionStatus, AeroRecoverableError, Bbox, ConfidenceBudget, CurrentTrack, DataSource, FlightPhase, FlightPlan, FlightPlanStatus, FlightPlanSummary, FusedTrackEvent, Position, Protocol, SourceHealthEvent, SourceStatus, StreamEnvelope, TrackSource, TrackStatus, Velocity } from '@aeroswarm/core/types';
 export { clamp, haversineKm, isInsideBbox, isRenderableTrack, toCurrentTrack } from '@aeroswarm/core/utils';
+export { M as MotionFrame, a as MotionInput, b as MotionOptions, c as MotionSample, d as MotionScheduler, T as TrackMotion, e as createTrackMotion } from './index-ByNBpjNk.js';
 import '@trpc/client';
 
-/** 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;
+/**
+ * Short label for the kind of sensor behind a track.
+ *
+ *   ADSB     ADS-B (CAT021, or raw ADS-B)
+ *   SURFACE  surface movement data (CAT010 / CAT011): SMR, MLAT or an ADS-B station on the ground
+ *   MLAT     multilateration (CAT020)
+ *   RADAR    radar plots and tracks (CAT048)
+ *   SYSTEM   system track (CAT062)
+ *   FUSED    several sensors merged
+ */
+type SourceLabel = "ADSB" | "SURFACE" | "MLAT" | "RADAR" | "SYSTEM" | "FUSED";
+declare function sourceLabel(source: CurrentTrack["source"]): SourceLabel;
+/**
+ * The sensor behind a track as a display string: `"ADSB 32/136"` (kind, then SAC/SIC),
+ * or just `"ADSB"` when the feed gave no SAC/SIC.
+ */
+declare function formatDataSource(track: Pick<CurrentTrack, "source" | "dataSource">): string;
 
-export { type MotionFrame, type MotionInput, type MotionOptions, type MotionSample, type MotionScheduler, type TrackMotion, createTrackMotion };
+export { type SourceLabel, formatDataSource, sourceLabel };

package/dist/index.js

@@ -314,6 +314,85 @@ function createAeroTrpcClient(endpoint, token) {
   });
 }
 
+// src/sdk/api/response.ts
+var ENVELOPE_HEADER = "x-aero-envelope";
+var STATUS_CODES = [
+  [401, "UNAUTHORIZED"],
+  [403, "FORBIDDEN"],
+  [404, "NOT_FOUND"],
+  [400, "BAD_REQUEST"],
+  [409, "CONFLICT"],
+  [429, "RATE_LIMITED"],
+  [503, "UNAVAILABLE"],
+  [500, "INTERNAL"]
+];
+function codeForStatus(status) {
+  const hit = STATUS_CODES.find(([s]) => s === status);
+  if (hit) return hit[1];
+  return status >= 500 ? "INTERNAL" : "BAD_REQUEST";
+}
+var AeroApiError = class extends Error {
+  status;
+  code;
+  /** Retrying later may succeed (rate limit, server busy or failing). */
+  recoverable;
+  details;
+  constructor(init) {
+    super(init.message);
+    this.name = "AeroApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.recoverable = init.recoverable;
+    this.details = init.details;
+  }
+};
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function isEnvelope(body) {
+  return isObject(body) && body.ok === true && "data" in body;
+}
+function isFailure(body) {
+  return isObject(body) && body.ok === false;
+}
+function errorFrom(res, body, text, label) {
+  const prefix = label ? `${label} \u2192 ${res.status}` : `HTTP ${res.status}`;
+  const failure = isFailure(body) ? body : void 0;
+  const e = failure?.error;
+  if (isObject(e)) {
+    const code = typeof e.code === "string" ? e.code : codeForStatus(res.status);
+    const message2 = typeof e.message === "string" ? e.message : res.statusText || prefix;
+    return new AeroApiError({
+      status: res.status,
+      code,
+      message: `${prefix}: ${message2}`,
+      recoverable: typeof e.recoverable === "boolean" ? e.recoverable : res.status >= 500,
+      details: e.details
+    });
+  }
+  const message = typeof e === "string" ? e : text.slice(0, 200) || res.statusText;
+  return new AeroApiError({
+    status: res.status,
+    code: codeForStatus(res.status),
+    message: message ? `${prefix}: ${message}` : prefix,
+    recoverable: res.status >= 500 || res.status === 429,
+    details: failure?.detail
+  });
+}
+async function readApiBody(res, label) {
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : void 0;
+  } catch {
+    body = void 0;
+  }
+  if (!res.ok || isFailure(body)) throw errorFrom(res, body, text, label);
+  return body;
+}
+async function parseApiResponse(res, label) {
+  const body = await readApiBody(res, label);
+  return isEnvelope(body) ? body.data : body;
+}
+
 // src/sdk/api/rest.ts
 var AeroRestClient = class {
   constructor(endpoint, token) {
@@ -331,8 +410,7 @@ var AeroRestClient = class {
       },
       body: body ? JSON.stringify(body) : void 0
     });
-    if (!res.ok) throw new Error(`${method} ${path} \u2192 ${res.status}`);
-    return res.json();
+    return await readApiBody(res, `${method} ${path}`);
   }
   createSource(body) {
     return this.req("POST", "/v1/sources", body);
@@ -554,9 +632,10 @@ var AeroSwarm = class _AeroSwarm {
   async federatedFetch(base, path, query) {
     const url = new URL(`${base}${path}`);
     for (const [k, v] of Object.entries(query ?? {})) if (v !== void 0) url.searchParams.set(k, v);
-    const res = await fetch(url, { headers: { Authorization: `Bearer ${this.opts.token}` } });
-    if (!res.ok) throw new Error(`Federated request failed: ${res.status} ${res.statusText} (${url.pathname})`);
-    return res.json();
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.opts.token}`, [ENVELOPE_HEADER]: "1" }
+    });
+    return parseApiResponse(res, `Federated request ${url.pathname}`);
   }
   tracks = {
     subscribe: (opts, callbacks) => {
@@ -1091,18 +1170,53 @@ var Motion = class {
 function createTrackMotion(options = {}) {
   return new Motion(options);
 }
+
+// src/shared/source/index.ts
+function sourceLabel(source) {
+  switch (source) {
+    case "ADSB":
+    case "ASTERIX_CAT021":
+      return "ADSB";
+    case "ASTERIX_CAT010":
+    case "ASTERIX_CAT011":
+      return "SURFACE";
+    case "ASTERIX_CAT020":
+      return "MLAT";
+    case "ASTERIX_CAT048":
+      return "RADAR";
+    case "ASTERIX_CAT062":
+      return "SYSTEM";
+    case "FUSED":
+      return "FUSED";
+    default: {
+      const unreachable = source;
+      return unreachable;
+    }
+  }
+}
+function formatDataSource(track) {
+  const kind = sourceLabel(track.source);
+  const ds = track.dataSource;
+  return ds ? `${kind} ${ds.sac}/${ds.sic}` : kind;
+}
 export {
+  AeroApiError,
   AeroReplayClient,
   AeroSwarm,
   AeroWsClient,
   LABEL_COLORS,
   TrackCache,
   clamp,
+  codeForStatus,
   createTrackMotion,
+  formatDataSource,
   getLabelCategory,
   haversineKm,
   isInsideBbox,
   isRenderableTrack2 as isRenderableTrack,
+  parseApiResponse,
+  readApiBody,
+  sourceLabel,
   toCurrentTrack,
   withLabel
 };