@aeroswarm/client 0.1.12 → 0.1.14

package/dist/index.js

@@ -140,12 +140,13 @@ var AeroWsClient = class {
       this._requestSnapshot();
     }
     this.lastSeq = msg.seq;
+    const meta = { serverTime: msg.serverTime, seq: msg.seq };
     switch (msg.type) {
       case "snapshot":
-        this.callbacks.onSnapshot?.(msg.payload.tracks);
+        this.callbacks.onSnapshot?.(msg.payload.tracks, meta);
         break;
       case "track.updated":
-        this.callbacks.onTrackUpdate?.(msg.payload.track);
+        this.callbacks.onTrackUpdate?.(msg.payload.track, meta);
         break;
       case "track.removed":
         this.callbacks.onTrackRemoved?.(msg.payload);
@@ -313,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) {
@@ -330,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);
@@ -553,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) => {
@@ -567,15 +647,15 @@ var AeroSwarm = class _AeroSwarm {
             this._status = s;
             callbacks.onStatusChange?.(s);
           },
-          onSnapshot: (tracks) => {
+          onSnapshot: (tracks, meta) => {
             const labeled = this.cache.applySnapshot(tracks);
             this._lastUpdateAt = Date.now();
-            callbacks.onSnapshot?.(labeled);
+            callbacks.onSnapshot?.(labeled, meta);
           },
-          onTrackUpdate: (track) => {
+          onTrackUpdate: (track, meta) => {
             const labeled = this.cache.applyUpdate(track);
             this._lastUpdateAt = Date.now();
-            callbacks.onTrackUpdate?.(labeled);
+            callbacks.onTrackUpdate?.(labeled, meta);
           },
           onTrackRemoved: (ev) => {
             this.cache.applyRemoved(ev);
@@ -600,7 +680,7 @@ var AeroSwarm = class _AeroSwarm {
     reconnect: () => this.wsClient.reconnect(),
     stream: (opts) => {
       const queue = [];
-      let resolve = null;
+      let resolve2 = null;
       let done = false;
       this.wsClient.connect({ encoding: "json", ...opts }, {
         onSnapshot: (tracks) => {
@@ -608,9 +688,9 @@ var AeroSwarm = class _AeroSwarm {
         },
         onTrackUpdate: (raw) => {
           const t = this.cache.applyUpdate(raw);
-          if (resolve) {
-            resolve({ value: t, done: false });
-            resolve = null;
+          if (resolve2) {
+            resolve2({ value: t, done: false });
+            resolve2 = null;
           } else queue.push(t);
         },
         onStatusChange: (s) => {
@@ -623,7 +703,7 @@ var AeroSwarm = class _AeroSwarm {
             if (queue.length) return Promise.resolve({ value: queue.shift(), done: false });
             if (done) return Promise.resolve({ value: void 0, done: true });
             return new Promise((r) => {
-              resolve = r;
+              resolve2 = r;
             });
           },
           return: async () => {
@@ -786,17 +866,357 @@ var AeroSwarm = class _AeroSwarm {
 
 // src/shared/utils/index.ts
 import { isRenderableTrack as isRenderableTrack2, haversineKm, isInsideBbox, toCurrentTrack, clamp } from "@aeroswarm/core/utils";
+
+// src/shared/motion/index.ts
+var KT_TO_MS = 0.514444;
+var M_PER_DEG = 111320;
+var MAX_PLAUSIBLE_KT = 1500;
+var OFFSET_WINDOW = 20;
+var ALT_EPSILON_FT = 10;
+var HEADING_EPSILON_DEG = 0.5;
+var SURFACE_ALT_FT = 150;
+var clamp01 = (x) => x < 0 ? 0 : x > 1 ? 1 : x;
+var smoothstep = (x) => {
+  const c = clamp01(x);
+  return c * c * (3 - 2 * c);
+};
+var wrapDeg = (d) => ((d + 180) % 360 + 360) % 360 - 180;
+var norm360 = (d) => (d % 360 + 360) % 360;
+var cosLat = (lat) => Math.max(0.01, Math.cos(lat * Math.PI / 180));
+function validHeading(h) {
+  return h != null && Number.isFinite(h) && h >= 0 && h <= 360 ? h % 360 : null;
+}
+function move(lat, lon, bearingDeg, distM) {
+  const rad = bearingDeg * Math.PI / 180;
+  const dLat = distM * Math.cos(rad) / M_PER_DEG;
+  const dLon = distM * Math.sin(rad) / (M_PER_DEG * cosLat(lat + dLat / 2));
+  return { lat: lat + dLat, lon: lon + dLon };
+}
+function distanceM(aLat, aLon, bLat, bLon) {
+  const dy = (bLat - aLat) * M_PER_DEG;
+  const dx = (bLon - aLon) * M_PER_DEG * cosLat((aLat + bLat) / 2);
+  return Math.hypot(dx, dy);
+}
+var headingChanged = (a, b) => a === null || b === null ? a !== b : Math.abs(wrapDeg(a - b)) > HEADING_EPSILON_DEG;
+var altitudeChanged = (a, b) => a === null || b === null ? a !== b : Math.abs(a - b) >= ALT_EPSILON_FT;
+var defaultIsSurface = (t) => t.targetType === "vehicle" || t.altitudeFt != null && t.altitudeFt <= SURFACE_ALT_FT;
+function resolve(o) {
+  return {
+    blendMs: o.blendMs ?? 1500,
+    headingSmoothMs: o.headingSmoothMs ?? 800,
+    maxExtrapolateMs: o.maxExtrapolateMs ?? { air: 2e4, surface: 8e3 },
+    minMovingKt: o.minMovingKt ?? 5,
+    snapDistanceM: o.snapDistanceM ?? 5e3,
+    frameHz: o.frameHz ?? 30,
+    epsilonM: o.epsilonM ?? 0.5,
+    extrapolate: o.extrapolate ?? true,
+    isSurface: o.isSurface ?? defaultIsSurface,
+    clock: o.clock ?? Date.now,
+    scheduler: o.scheduler
+  };
+}
+function defaultScheduler() {
+  const g = globalThis;
+  if (typeof g.requestAnimationFrame === "function" && typeof g.cancelAnimationFrame === "function") {
+    return {
+      request: (cb) => g.requestAnimationFrame(cb),
+      cancel: (h) => g.cancelAnimationFrame(h)
+    };
+  }
+  return {
+    request: (cb) => setTimeout(() => cb(Date.now()), 16),
+    cancel: (h) => clearTimeout(h)
+  };
+}
+var Motion = class {
+  o;
+  entries = /* @__PURE__ */ new Map();
+  /** Tracks whose picture can still change. Everything else costs nothing per frame. */
+  active = /* @__PURE__ */ new Set();
+  listeners = /* @__PURE__ */ new Set();
+  offsets = [];
+  offset = 0;
+  handle = null;
+  lastFrameAt = Number.NEGATIVE_INFINITY;
+  constructor(options) {
+    this.o = resolve(options);
+  }
+  get size() {
+    return this.entries.size;
+  }
+  offsetMs() {
+    return this.offset;
+  }
+  // ── time ────────────────────────────────────────────────────────────────
+  /** Browser clock + learned offset = the server's clock. */
+  serverNow(at) {
+    return (at ?? this.o.clock()) + this.offset;
+  }
+  /**
+   * `serverTime - browserNow` is the true offset MINUS the network delay, so the
+   * largest recent value is the one with the least delay, i.e. the best estimate.
+   */
+  observe(serverTime) {
+    if (!Number.isFinite(serverTime)) return;
+    this.offsets.push(serverTime - this.o.clock());
+    if (this.offsets.length > OFFSET_WINDOW) this.offsets.shift();
+    this.offset = Math.max(...this.offsets);
+  }
+  cap(e) {
+    const m = this.o.maxExtrapolateMs;
+    return e.surface ? m.surface : m.air;
+  }
+  // ── model ───────────────────────────────────────────────────────────────
+  posAt(e, s) {
+    const cap = this.cap(e);
+    let elapsed = Math.min(Math.max(0, s - e.fixAt), cap);
+    if (e.frozen !== null) elapsed = Math.min(elapsed, e.frozen);
+    if (!this.o.extrapolate || e.course === null || e.speedMs <= 0) {
+      return { lat: e.fixLat, lon: e.fixLon, extrapolating: false };
+    }
+    const p = move(e.fixLat, e.fixLon, e.course, e.speedMs * elapsed / 1e3);
+    return { ...p, extrapolating: e.frozen === null && elapsed < cap };
+  }
+  sampleAt(e, s) {
+    const p = this.posAt(e, s);
+    const rest = 1 - smoothstep((s - e.blendStart) / this.o.blendMs);
+    let headingDeg = null;
+    if (e.hdgTo !== null) {
+      const from = e.hdgFrom ?? e.hdgTo;
+      const left = 1 - smoothstep((s - e.hdgStart) / this.o.headingSmoothMs);
+      headingDeg = norm360(e.hdgTo + wrapDeg(from - e.hdgTo) * left);
+    }
+    let altitudeFt = null;
+    if (e.altTo !== null) {
+      const k = smoothstep((s - e.altStart) / this.o.blendMs);
+      altitudeFt = e.altFrom === null ? e.altTo : e.altFrom + (e.altTo - e.altFrom) * k;
+    }
+    return {
+      lat: p.lat + e.errLat * rest,
+      lon: p.lon + e.errLon * rest,
+      headingDeg,
+      altitudeFt,
+      moving: e.speedMs > 0,
+      extrapolating: p.extrapolating
+    };
+  }
+  // ── input ───────────────────────────────────────────────────────────────
+  update(t, meta) {
+    if (meta?.serverTime !== void 0) this.observe(meta.serverTime);
+    if (t.lat == null || t.lon == null || !Number.isFinite(t.lat) || !Number.isFinite(t.lon)) {
+      this.remove(t.trackId);
+      return;
+    }
+    const s = this.serverNow();
+    const e = this.entries.get(t.trackId);
+    if (!e) {
+      this.create(t, s);
+      return;
+    }
+    this.refresh(e, t, s);
+  }
+  moving(t, course) {
+    const kt = t.groundSpeedKt;
+    return course !== null && kt != null && Number.isFinite(kt) && kt >= this.o.minMovingKt && kt <= MAX_PLAUSIBLE_KT;
+  }
+  create(t, s) {
+    const course = validHeading(t.headingDeg);
+    const moving = this.moving(t, course);
+    const e = {
+      id: t.trackId,
+      fixLat: t.lat,
+      fixLon: t.lon,
+      fixAt: t.lastSeenAt,
+      speedMs: moving ? t.groundSpeedKt * KT_TO_MS : 0,
+      course,
+      surface: this.o.isSurface(t),
+      frozen: null,
+      errLat: 0,
+      errLon: 0,
+      blendStart: s,
+      hdgFrom: course,
+      hdgTo: course,
+      hdgStart: s,
+      altFrom: null,
+      altTo: t.altitudeFt,
+      altStart: s,
+      settleAt: 0,
+      emitted: null
+    };
+    if (t.status === "lost") e.frozen = this.frozenAt(e, s);
+    this.entries.set(e.id, e);
+    this.settle(e);
+    this.active.add(e.id);
+    this.ensureLoop();
+  }
+  frozenAt(e, s) {
+    return Math.min(Math.max(0, s - e.fixAt), this.cap(e));
+  }
+  refresh(e, t, s) {
+    e.surface = this.o.isSurface(t);
+    if (t.status === "lost") e.frozen ??= this.frozenAt(e, s);
+    else e.frozen = null;
+    const lat = t.lat;
+    const lon = t.lon;
+    const older = t.lastSeenAt < e.fixAt;
+    const same = t.lastSeenAt === e.fixAt && lat === e.fixLat && lon === e.fixLon;
+    if (older || same) {
+      this.settle(e);
+      this.touch(e);
+      return;
+    }
+    const shown = this.sampleAt(e, s);
+    const course = validHeading(t.headingDeg) ?? e.course;
+    const moving = this.moving(t, course);
+    e.fixLat = lat;
+    e.fixLon = lon;
+    e.fixAt = t.lastSeenAt;
+    e.speedMs = moving ? t.groundSpeedKt * KT_TO_MS : 0;
+    e.course = course;
+    const predicted = this.posAt(e, s);
+    const jump = distanceM(shown.lat, shown.lon, predicted.lat, predicted.lon);
+    const snap = jump > this.o.snapDistanceM;
+    e.errLat = snap ? 0 : shown.lat - predicted.lat;
+    e.errLon = snap ? 0 : shown.lon - predicted.lon;
+    e.blendStart = s;
+    e.hdgFrom = snap ? course : shown.headingDeg ?? course;
+    e.hdgTo = course;
+    e.hdgStart = s;
+    e.altFrom = snap ? t.altitudeFt : shown.altitudeFt;
+    e.altTo = t.altitudeFt;
+    e.altStart = s;
+    this.settle(e);
+    this.touch(e);
+  }
+  /** The server time after which nothing about this track changes on its own. */
+  settle(e) {
+    const ends = [e.blendStart + this.o.blendMs, e.hdgStart + this.o.headingSmoothMs, e.altStart + this.o.blendMs];
+    if (this.o.extrapolate && e.speedMs > 0 && e.frozen === null) ends.push(e.fixAt + this.cap(e));
+    e.settleAt = Math.max(...ends);
+  }
+  touch(e) {
+    this.active.add(e.id);
+    this.ensureLoop();
+  }
+  remove(trackId) {
+    this.entries.delete(trackId);
+    this.active.delete(trackId);
+  }
+  clear() {
+    this.entries.clear();
+    this.active.clear();
+  }
+  // ── output ──────────────────────────────────────────────────────────────
+  sample(trackId, at) {
+    const e = this.entries.get(trackId);
+    return e ? this.sampleAt(e, this.serverNow(at)) : void 0;
+  }
+  differs(a, b) {
+    if (a === null || a.moving !== b.moving || a.extrapolating !== b.extrapolating) return true;
+    if (distanceM(a.lat, a.lon, b.lat, b.lon) > this.o.epsilonM) return true;
+    return headingChanged(a.headingDeg, b.headingDeg) || altitudeChanged(a.altitudeFt, b.altitudeFt);
+  }
+  tick(at) {
+    const s = this.serverNow(at);
+    const changed = /* @__PURE__ */ new Map();
+    for (const id of [...this.active]) {
+      const e = this.entries.get(id);
+      if (!e) {
+        this.active.delete(id);
+        continue;
+      }
+      const sample = this.sampleAt(e, s);
+      if (this.differs(e.emitted, sample)) {
+        e.emitted = sample;
+        changed.set(id, sample);
+      }
+      if (s >= e.settleAt) this.active.delete(id);
+    }
+    return changed;
+  }
+  // ── frame loop ──────────────────────────────────────────────────────────
+  start(onFrame) {
+    this.listeners.add(onFrame);
+    this.ensureLoop();
+    return () => {
+      this.listeners.delete(onFrame);
+      if (this.listeners.size === 0) this.cancelLoop();
+    };
+  }
+  ensureLoop() {
+    if (this.handle !== null || this.listeners.size === 0 || this.active.size === 0) return;
+    const scheduler = this.o.scheduler ?? (this.o.scheduler = defaultScheduler());
+    this.handle = scheduler.request((ts) => this.frame(ts));
+  }
+  cancelLoop() {
+    if (this.handle === null) return;
+    (this.o.scheduler ?? defaultScheduler()).cancel(this.handle);
+    this.handle = null;
+  }
+  frame(ts) {
+    this.handle = null;
+    if (this.listeners.size === 0) return;
+    if (ts - this.lastFrameAt >= 1e3 / this.o.frameHz - 1) {
+      this.lastFrameAt = ts;
+      const changed = this.tick();
+      if (changed.size > 0) {
+        const frame = { at: this.serverNow(), changed };
+        for (const fn of [...this.listeners]) fn(frame);
+      }
+    }
+    this.ensureLoop();
+  }
+};
+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
 };