@aeroswarm/client 0.1.14 → 0.1.16

package/dist/{index-CyxVoJXL.d.ts → index-DH3DH1Nj.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.
@@ -367,6 +477,13 @@ declare function parseApiResponse<T>(res: Response, label?: string): Promise<T>;
 interface AeroSwarmOptions {
     endpoint: string;
     token: string;
+    /**
+     * Credential for the airport's OWN backend (history, trail, replay days: whatever goes to a
+     * `historyEndpoint` or an explicit `endpoint`), when it differs from `token`. Pass a function to
+     * have it read on every request, e.g. `() => session.accessToken`, so a login that is refreshed
+     * is picked up without rebuilding the client. Defaults to `token`.
+     */
+    backendToken?: string | (() => string | undefined | Promise<string | undefined>);
     wsEndpoint?: string;
     reconnect?: boolean;
     maxReconnectDelay?: number;
@@ -423,6 +540,9 @@ declare class AeroSwarm {
      *  (a broken airports.list() call must never brick replay/history for
      *  everyone else). */
     private resolveHistoryEndpoint;
+    /** What to present to an airport's own backend: `backendToken` (read now if it is a function), else `token`. */
+    private backendCredential;
+    private federatedRequest;
     private federatedFetch;
     constructor(opts: AeroSwarmOptions);
     readonly tracks: {
@@ -451,6 +571,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 +859,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-DH3DH1Nj.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,22 @@ var AeroSwarm = class _AeroSwarm {
       return null;
     }
   }
-  async federatedFetch(base, path, query) {
+  /** What to present to an airport's own backend: `backendToken` (read now if it is a function), else `token`. */
+  async backendCredential() {
+    const given = this.opts.backendToken;
+    const value = typeof given === "function" ? await given() : given;
+    return value || this.opts.token;
+  }
+  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" }
+      headers: { Authorization: `Bearer ${await this.backendCredential()}`, [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 +740,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 +1249,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 +1331,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