@aeroswarm/client 0.1.14 → 0.1.15

package/README.md

@@ -470,6 +470,31 @@ catch (e) {
 ```
 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.
 
+### `tracks.trail` / `createTrailPoller` / `useTrackTrail` — the path an aircraft has flown
+
+The airport's backend builds the trail (memory first, stored history as a fallback), so the client computes nothing: it gets a GeoJSON `FeatureCollection` with one `LineString` (`[lon, lat, altitude m]`) and a `Point` per time mark, each with `properties.label` already written in the time zone you ask for.
+
+```ts
+const { trail } = await client.tracks.trail({
+  trackId,
+  endpoint: "https://asmgcs.example/aero",   // the airport backend (or an airportId with a historyEndpoint)
+  tz: "Asia/Jakarta",                        // labels such as "01-11-26 11:16"; default UTC
+});
+// whole flight by default. fromMs/toMs: a period. stepM: coarser line. limit: at most n points. labelEveryMs: marks (default 2 min)
+```
+
+Keep it current while an aircraft is selected: the first request is the whole trail, after that only what is new is fetched (`sinceMs`), so polling every few seconds costs a few hundred bytes.
+
+```ts
+const poller = createTrailPoller(
+  (sinceMs) => client.tracks.trail({ trackId, endpoint, tz: "Asia/Jakarta", sinceMs }),
+  { pollMs: 5000, onUpdate: (trail) => draw(trail) },   // draw the line, and each mark's properties.label
+);
+poller.stop();                                          // when it is deselected
+```
+
+React: `const { trail, loading, error } = useTrackTrail(selectedTrackId, { endpoint, tz: "Asia/Jakarta" })` (pass `null` while nothing is selected). A fixed period (`toMs`) is fetched once. A trail already shown stays when a request fails; polling stops for good when the server says the track is unknown (`NOT_FOUND`). `mergeTrail(prev, delta)` and `trailEnd(trail)` are exported if you manage the polling yourself. To end the line at the icon, draw one more segment from the trail's last point to `createTrackMotion().sample(trackId)`.
+
 ### `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-CyxVoJXL.d.ts → index-CeayQnTp.d.ts}

@@ -264,6 +264,101 @@ declare class AeroReplayClient {
 declare function createAeroTrpcClient(endpoint: string, token: string): _trpc_client.TRPCClient<any>;
 type AeroTrpcClient = ReturnType<typeof createAeroTrpcClient>;
 
+interface TrailLine {
+    type: "Feature";
+    properties: {
+        kind: "trail";
+        trackId: string;
+        /** epoch ms of the first and the last point */
+        from: number;
+        to: number;
+        /** spacing of the points, metres */
+        stepM: number;
+        /** the line starts at the beginning of the flight (nothing older exists) */
+        fromStart: boolean;
+    };
+    /** [lon, lat, altitude in metres] */
+    geometry: {
+        type: "LineString";
+        coordinates: Array<[number, number, number]>;
+    };
+}
+interface TrailMark {
+    type: "Feature";
+    /** `label` is ready to display, e.g. "01-11-26 11:16" */
+    properties: {
+        kind: "mark";
+        t: number;
+        label: string;
+    };
+    geometry: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+}
+interface TrailFeatureCollection {
+    type: "FeatureCollection";
+    features: Array<TrailLine | TrailMark>;
+}
+interface TrailMeta {
+    serverTime?: number;
+    count?: number;
+    /** the server dropped points to honour `limit` */
+    truncated?: boolean;
+}
+interface TrailResult {
+    trail: TrailFeatureCollection;
+    meta?: TrailMeta;
+}
+interface TrailRequest {
+    trackId: string;
+    /** The airport backend's base URL (its `/aero` mount). Without it `airportId` must have a registered historyEndpoint. */
+    endpoint?: string;
+    airportId?: string;
+    /** A period instead of the whole flight (epoch ms). */
+    fromMs?: number;
+    toMs?: number;
+    /** Only what is newer than this: for keeping a trail current. */
+    sinceMs?: number;
+    /** Coarser spacing than the server stores, metres. */
+    stepM?: number;
+    /** At most this many points. */
+    limit?: number;
+    /** A time mark every this many ms (default 120 000), aligned to the clock. 0 = none. */
+    labelEveryMs?: number;
+    /** Time zone of the labels, e.g. "Asia/Jakarta" (default UTC). */
+    tz?: string;
+    labelFormat?: "datetime" | "time";
+}
+/** Time of the last point of a trail; undefined when it has none. What to pass as `sinceMs`. */
+declare function trailEnd(trail: TrailFeatureCollection): number | undefined;
+/**
+ * Appends a delta (a request with `sinceMs`) to the trail you already have. Returns `prev`
+ * itself when the delta adds nothing, so a caller can tell nothing changed.
+ */
+declare function mergeTrail(prev: TrailFeatureCollection | undefined, delta: TrailFeatureCollection): TrailFeatureCollection;
+interface TrailPollerOptions {
+    /** How often to ask for what is new. Default 5000. 0 or less: fetch once and stop. */
+    pollMs?: number;
+    /** Called with the whole trail, first when it arrives, then each time it grows. */
+    onUpdate: (trail: TrailFeatureCollection) => void;
+    onError?: (err: unknown) => void;
+    /** Stop for good when the server says the track is unknown (it left and its retention ended). Default true. */
+    stopWhenGone?: boolean;
+}
+interface TrailPoller {
+    stop(): void;
+    /** Ask now instead of waiting for the next tick. */
+    refresh(): Promise<void>;
+    /** The trail as it stands. */
+    current(): TrailFeatureCollection | undefined;
+}
+/**
+ * Fetches a trail once and then keeps it current by asking only for what is new.
+ * Framework-free: `useTrackTrail` is a thin wrapper around it.
+ */
+declare function createTrailPoller(fetchTrail: (sinceMs?: number) => Promise<TrailResult>, options: TrailPollerOptions): TrailPoller;
+
 declare class AeroGraphQLClient {
     private readonly endpoint;
     private readonly token;
@@ -358,6 +453,21 @@ declare class AeroApiError extends Error {
  * envelope themselves (`r.data.x`).
  */
 declare function readApiBody(res: Response, label?: string): Promise<unknown>;
+/** What a standard response says about itself (see `meta` in @aeroswarm/core/api). Absent for servers that answer with bare data. */
+interface ApiMetaLike {
+    serverTime?: number;
+    count?: number;
+    nextCursor?: string;
+    truncated?: boolean;
+}
+/**
+ * The data of a response together with its `meta`: unwrapped from `{ ok, data, meta }`, or the body
+ * as it is (and no meta) for servers that answer with bare data. Throws `AeroApiError` on failure.
+ */
+declare function parseApiEnvelope<T>(res: Response, label?: string): Promise<{
+    data: T;
+    meta?: ApiMetaLike;
+}>;
 /**
  * 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.
@@ -423,6 +533,7 @@ declare class AeroSwarm {
      *  (a broken airports.list() call must never brick replay/history for
      *  everyone else). */
     private resolveHistoryEndpoint;
+    private federatedRequest;
     private federatedFetch;
     constructor(opts: AeroSwarmOptions);
     readonly tracks: {
@@ -451,6 +562,15 @@ declare class AeroSwarm {
             limit?: number;
             endpoint?: string;
         }) => Promise<TrackHistoryPoint[]>;
+        /**
+         * The path an aircraft has flown, ready to draw: a GeoJSON line plus a point for every time
+         * mark, with the label already written in `tz`. By default the whole flight so far; `fromMs`
+         * and `toMs` choose a period, `sinceMs` fetches only what is new (see `createTrailPoller`),
+         * `stepM` asks for a coarser line. The airport's backend builds it (memory first, history
+         * as a fallback), so nothing is computed here. There is no AeroSwarm-side equivalent:
+         * pass `endpoint` or an `airportId` with a registered `historyEndpoint`.
+         */
+        trail: (input: TrailRequest) => Promise<TrailResult>;
     };
     /** Flight plans received from AFTN feeds. Live tracks that correlate with a
      *  plan (Mode-S address, else callsign) also carry `track.flightPlan`. */
@@ -730,4 +850,4 @@ declare class AeroSwarm {
     reconnect(): boolean;
 }
 
-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 };
+export { AeroApiError as A, codeForStatus as B, createTrailPoller as C, type DayAvailability as D, getLabelCategory as E, type FlightPlanRow as F, mergeTrail as G, parseApiEnvelope as H, parseApiResponse as I, readApiBody as J, trailEnd as K, LABEL_COLORS as L, withLabel as M, 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 ApiMetaLike as h, type LabelCategory as i, type LabeledTrack as j, type LiveTrackCallbacks as k, type ReplayHandle as l, type ReplayProgress as m, type ReplayStreamOptions as n, type StreamMeta as o, type SubscribeOptions as p, type TrackCallbacks as q, type TrackHistoryPoint as r, type TrailFeatureCollection as s, type TrailLine as t, type TrailMark as u, type TrailMeta as v, type TrailPoller as w, type TrailPollerOptions as x, type TrailRequest as y, type TrailResult as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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';
+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, h as ApiMetaLike, D as DayAvailability, F as FlightPlanRow, L as LABEL_COLORS, i as LabelCategory, j as LabeledTrack, k as LiveTrackCallbacks, R as ReplayCallbacks, l as ReplayHandle, m as ReplayProgress, n as ReplayStreamOptions, S as SourceRow, o as StreamMeta, p as SubscribeOptions, T as TrackCache, q as TrackCallbacks, r as TrackHistoryPoint, s as TrailFeatureCollection, t as TrailLine, u as TrailMark, v as TrailMeta, w as TrailPoller, x as TrailPollerOptions, y as TrailRequest, z as TrailResult, U as UseAeroTracksResult, B as codeForStatus, C as createTrailPoller, E as getLabelCategory, G as mergeTrail, H as parseApiEnvelope, I as parseApiResponse, J as readApiBody, K as trailEnd, M as withLabel } from './index-CeayQnTp.js';
 import { CurrentTrack } 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';

package/dist/index.js

@@ -388,9 +388,14 @@ async function readApiBody(res, label) {
   if (!res.ok || isFailure(body)) throw errorFrom(res, body, text, label);
   return body;
 }
-async function parseApiResponse(res, label) {
+async function parseApiEnvelope(res, label) {
   const body = await readApiBody(res, label);
-  return isEnvelope(body) ? body.data : body;
+  if (!isEnvelope(body)) return { data: body };
+  const meta = body.meta;
+  return { data: body.data, ...isObject(meta) && { meta } };
+}
+async function parseApiResponse(res, label) {
+  return (await parseApiEnvelope(res, label)).data;
 }
 
 // src/sdk/api/rest.ts
@@ -629,13 +634,16 @@ var AeroSwarm = class _AeroSwarm {
       return null;
     }
   }
-  async federatedFetch(base, path, query) {
+  async federatedRequest(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}`, [ENVELOPE_HEADER]: "1" }
     });
-    return parseApiResponse(res, `Federated request ${url.pathname}`);
+    return parseApiEnvelope(res, `Federated request ${url.pathname}`);
+  }
+  async federatedFetch(base, path, query) {
+    return (await this.federatedRequest(base, path, query)).data;
   }
   tracks = {
     subscribe: (opts, callbacks) => {
@@ -726,6 +734,42 @@ var AeroSwarm = class _AeroSwarm {
         });
       }
       return this.trpc.tracks.history.query(input);
+    },
+    /**
+     * The path an aircraft has flown, ready to draw: a GeoJSON line plus a point for every time
+     * mark, with the label already written in `tz`. By default the whole flight so far; `fromMs`
+     * and `toMs` choose a period, `sinceMs` fetches only what is new (see `createTrailPoller`),
+     * `stepM` asks for a coarser line. The airport's backend builds it (memory first, history
+     * as a fallback), so nothing is computed here. There is no AeroSwarm-side equivalent:
+     * pass `endpoint` or an `airportId` with a registered `historyEndpoint`.
+     */
+    trail: async (input) => {
+      const base = await this.resolveHistoryEndpoint(input.airportId, input.endpoint);
+      if (!base) {
+        throw new AeroApiError({
+          status: 400,
+          code: "BAD_REQUEST",
+          recoverable: false,
+          message: "tracks.trail needs the airport's backend: pass `endpoint`, or an `airportId` that has a historyEndpoint"
+        });
+      }
+      const num = (v) => v === void 0 ? void 0 : String(v);
+      const { data, meta } = await this.federatedRequest(
+        base,
+        `/tracks/${encodeURIComponent(input.trackId)}/trail`,
+        {
+          fromMs: num(input.fromMs),
+          toMs: num(input.toMs),
+          sinceMs: num(input.sinceMs),
+          stepM: num(input.stepM),
+          limit: num(input.limit),
+          labelEveryMs: num(input.labelEveryMs),
+          tz: input.tz,
+          labelFormat: input.labelFormat,
+          format: "geojson"
+        }
+      );
+      return { trail: data, ...meta && { meta } };
     }
   };
   /** Flight plans received from AFTN feeds. Live tracks that correlate with a
@@ -1199,6 +1243,78 @@ function formatDataSource(track) {
   const ds = track.dataSource;
   return ds ? `${kind} ${ds.sac}/${ds.sic}` : kind;
 }
+
+// src/shared/trail/index.ts
+var lineOf = (fc) => fc.features.find((f) => f.properties.kind === "trail");
+var marksOf = (fc) => fc.features.filter((f) => f.properties.kind === "mark");
+function trailEnd(trail) {
+  const line = lineOf(trail);
+  return line && line.geometry.coordinates.length > 0 ? line.properties.to : void 0;
+}
+function mergeTrail(prev, delta) {
+  if (!prev) return delta;
+  const before = lineOf(prev);
+  const added = lineOf(delta);
+  if (!before || !added) return prev;
+  if (added.geometry.coordinates.length === 0) return prev;
+  const seen = new Set(marksOf(prev).map((m) => m.properties.t));
+  const newMarks = marksOf(delta).filter((m) => !seen.has(m.properties.t));
+  const line = {
+    ...before,
+    properties: { ...before.properties, to: added.properties.to, stepM: Math.max(before.properties.stepM, added.properties.stepM) },
+    geometry: { type: "LineString", coordinates: [...before.geometry.coordinates, ...added.geometry.coordinates] }
+  };
+  return { type: "FeatureCollection", features: [line, ...marksOf(prev), ...newMarks] };
+}
+var isGone = (err) => typeof err === "object" && err !== null && err.code === "NOT_FOUND";
+function createTrailPoller(fetchTrail, options) {
+  const pollMs = options.pollMs ?? 5e3;
+  const stopWhenGone = options.stopWhenGone ?? true;
+  let current;
+  let stopped = false;
+  let timer;
+  let running;
+  const schedule = () => {
+    if (stopped || pollMs <= 0) return;
+    timer = setTimeout(() => void tick(), pollMs);
+  };
+  async function once() {
+    try {
+      const since = current ? trailEnd(current) : void 0;
+      const { trail } = await fetchTrail(since);
+      if (stopped) return;
+      const next = mergeTrail(current, trail);
+      if (next !== current) {
+        current = next;
+        options.onUpdate(next);
+      }
+    } catch (err) {
+      if (stopped) return;
+      options.onError?.(err);
+      if (stopWhenGone && isGone(err)) stopped = true;
+    }
+  }
+  function tick() {
+    if (stopped) return Promise.resolve();
+    running ??= once().finally(() => {
+      running = void 0;
+      schedule();
+    });
+    return running;
+  }
+  void tick();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+    async refresh() {
+      if (timer) clearTimeout(timer);
+      await (running ?? tick());
+    },
+    current: () => current
+  };
+}
 export {
   AeroApiError,
   AeroReplayClient,
@@ -1209,15 +1325,19 @@ export {
   clamp,
   codeForStatus,
   createTrackMotion,
+  createTrailPoller,
   formatDataSource,
   getLabelCategory,
   haversineKm,
   isInsideBbox,
   isRenderableTrack2 as isRenderableTrack,
+  mergeTrail,
+  parseApiEnvelope,
   parseApiResponse,
   readApiBody,
   sourceLabel,
   toCurrentTrack,
+  trailEnd,
   withLabel
 };
 //# sourceMappingURL=index.js.map