import { finite, httpError, LiveSourceError, readResponse, } from './contract.js'; import { normalizeAircraftTrack, openSkySnapshot, readsbSnapshot, readsbIdentities, } from './aircraft.js'; import { normalizeVesselTrack, vesselSnapshot } from './vessels.js'; import { parsePlanespottersPhoto } from '../../data/planespottersPhoto.js'; import { MMSI, openVesselPhotosUrl, parseOpenVesselPhoto, } from '../../data/openVesselPhoto.js'; const defaultFetch = (...args) => globalThis.fetch(...args); const header = (response, name) => response.headers?.get?.(name); /** Planespotters' public photo lookup, called straight from the browser (it * answers with `access-control-allow-origin: *`). */ const PLANESPOTTERS_PHOTOS = 'https://api.planespotters.net/pub/photos/hex/'; /** A photo is decoration: a slow answer gives up rather than hold an * enrichment slot. */ const PHOTO_TIMEOUT_MS = 8000; /** The tracked plane's Planespotters photo, read and host-checked. */ async function planespottersPhoto(fetchImpl, hex, signal) { const id = String(hex || '').toLowerCase(); if (!/^[0-9a-f]{6}$/.test(id)) throw new LiveSourceError('unsupported', 'Enrichment unavailable'); const timeout = AbortSignal.timeout(PHOTO_TIMEOUT_MS); const { response, payload } = await readResponse( fetchImpl, PLANESPOTTERS_PHOTOS + id, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, credentials: 'omit', }, 'Planespotters', ); if (!response.ok) throw httpError(response, 'Planespotters'); return parsePlanespottersPhoto(payload); } /** * A vessel's Open Vessel Photos photo, read and host-checked. The API is * keyless and answers with `access-control-allow-origin: *`, so the browser * asks it straight. An MMSI it does not know answers 404: no photo. * @param {Function} fetchImpl fetch. * @param {string} mmsi The vessel's nine-digit MMSI. * @param {AbortSignal} [signal] Abort signal. * @returns {Promise} A `parseOpenVesselPhoto` result. */ export async function fetchOpenVesselPhoto(fetchImpl, mmsi, signal) { const id = String(mmsi || ''); if (!MMSI.test(id)) throw new LiveSourceError('unsupported', 'Enrichment unavailable'); const timeout = AbortSignal.timeout(PHOTO_TIMEOUT_MS); const { response, payload } = await readResponse( fetchImpl, openVesselPhotosUrl(id), { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, credentials: 'omit', }, 'Open Vessel Photos', ); if (response.status === 404) return parseOpenVesselPhoto(null); if (!response.ok) throw httpError(response, 'Open Vessel Photos'); return parseOpenVesselPhoto(payload, id); } function openSkyError(response) { const error = httpError(response, 'Flights'); const mode = String( header(response, 'x-opensky-auth-mode-used') || header(response, 'x-opensky-auth') || '', ).toLowerCase(); const reason = String( header(response, 'x-opensky-auth-reason') || '', ).toLowerCase(); if (response.status === 429 && (!mode || mode === 'anon')) error.message = 'OpenSky rate limited (anonymous)'; if (response.status === 401 || response.status === 403) { const reasons = { oauth_invalid_or_missing: 'OpenSky OAuth client missing/invalid', oauth_invalid_credentials: 'OpenSky OAuth rejected credentials', missing_oauth_creds: 'OpenSky auth missing', auth_required: 'OpenSky auth required', forced_anonymous: 'OpenSky auth required', }; error.message = reasons[reason] || (/^(oauth_|basic_)/.test(reason) ? 'OpenSky auth invalid' : mode === 'anon' ? 'OpenSky auth required' : 'OpenSky auth failed'); } return error; } /** * The provider a feed response names in `X-Feed-Source`, so a server that * answers a feed route from another provider is reported as that provider. */ function feedSource(response, fallback) { const named = header(response, 'x-feed-source'); return typeof named === 'string' && named.trim() ? named.trim().slice(0, 80) : fallback; } /** The flights feed (/api/flights); no request starts during construction. */ export function createFlightSource({ fetchImpl = defaultFetch, now = () => Date.now(), } = {}) { return { // i18n-ignore: feed source name, replaced by the provider from each snapshot and reported to AI tools label: 'Flights', async getSnapshot(query = {}, { signal } = {}) { const params = new URLSearchParams(); if (Number.isFinite(query.latitude) && Number.isFinite(query.longitude)) { params.set('lat', query.latitude.toFixed(4)); params.set('lon', query.longitude.toFixed(4)); } const { response, payload } = await readResponse( fetchImpl, `/api/flights${params.size ? '?' + params : ''}`, { signal }, 'Flights', ); if (!response.ok) throw openSkyError(response); return { ...openSkySnapshot(payload, { // A fallback provider names itself in X-Flight-Source. source: header(response, 'x-flight-source') || feedSource(response, 'Flights'), coverage: header(response, 'x-flight-coverage') || 'worldwide upstream snapshot', now: now(), }), status: response.status, }; }, async getTrack(reference, { signal } = {}) { const { response, payload } = await readResponse( fetchImpl, '/api/flights/track?icao24=' + encodeURIComponent(reference), { signal }, 'Flights', ); if (!response.ok) throw httpError(response, 'Flights'); return { records: normalizeAircraftTrack(payload?.path), complete: false, }; }, async getEnrichment(query, { signal } = {}) { if (query.kind === 'photo') return planespottersPhoto(fetchImpl, query.id, signal); if (!['type', 'route'].includes(query.kind)) throw new LiveSourceError('unsupported', 'Enrichment unavailable'); const { response, payload } = await readResponse( fetchImpl, `/api/adsbdb/${query.kind}/${encodeURIComponent(query.id)}`, { signal }, 'adsbdb', ); if (!response.ok) throw httpError(response, 'adsbdb'); return payload; }, }; } export function createMilitarySource({ fetchImpl = defaultFetch, now = () => Date.now(), } = {}) { return { // i18n-ignore: feed source name, replaced by the provider from each snapshot and reported to AI tools label: 'Military aircraft', async getIdentities(_query = {}, { signal } = {}) { const { response, payload } = await readResponse( fetchImpl, '/api/military', { signal }, 'Military aircraft', ); if (!response.ok) throw httpError(response, 'Military aircraft'); return readsbIdentities(payload); }, async getSnapshot(_query = {}, { signal } = {}) { const { response, payload } = await readResponse( fetchImpl, '/api/military', { signal }, 'Military aircraft', ); if (!response.ok) throw httpError(response, 'Military aircraft'); const age = finite(header(response, 'x-feed-age-ms')); return { ...readsbSnapshot(payload, { source: feedSource(response, 'Military aircraft'), observedAtMs: now() - (age != null && age > 0 ? age : 0), now: now(), stale: header(response, 'x-feed-cache') === 'STALE', }), status: response.status, }; }, // ADSB.lol does not expose a supported live-history endpoint. Omitting // optional getTrack keeps the tracking layer on its accumulated trail. }; } export function createVesselSource({ fetchImpl = defaultFetch, apiUrl = '/api/vessels', origin = () => globalThis.location?.origin || 'http://localhost', } = {}) { return { // i18n-ignore: feed source name, replaced by the provider from each snapshot and reported to AI tools label: 'Vessels', async getSnapshot({ maxRows = 12000, area } = {}, { signal } = {}) { const url = new URL(apiUrl, origin()); url.searchParams.set('maxRows', String(maxRows)); // An area asks for the vessels around a point; servers that hold every // vessel may ignore it, since callers still keep only what they need. if ( Number.isFinite(area?.lat) && Number.isFinite(area?.lon) && Number.isFinite(area?.radiusKm) ) { url.searchParams.set('lat', area.lat.toFixed(5)); url.searchParams.set('lon', area.lon.toFixed(5)); url.searchParams.set('radius_km', area.radiusKm.toFixed(1)); } const { response, payload } = await readResponse( fetchImpl, url.toString(), { signal, cache: 'no-store' }, 'Vessels', ); if (!response.ok) { const error = httpError(response, 'Vessels'); const reasons = { 'missing-key': 'AISSTREAM_API_KEY not set', 'auth-failed': 'API key rejected — check AISSTREAM_API_KEY', unsupported: 'live feed unsupported', error: 'feed down', closed: 'feed disconnected', }; error.message = reasons[payload?.status] || error.message; throw error; } return { ...vesselSnapshot(payload, { source: feedSource(response, 'Vessels') }), status: response.status, }; }, async getEnrichment(query, { signal } = {}) { if (query.kind !== 'photo') throw new LiveSourceError('unsupported', 'Enrichment unavailable'); return fetchOpenVesselPhoto(fetchImpl, query.id, signal); }, async getTrack(reference, { signal } = {}) { const { response, payload } = await readResponse( fetchImpl, '/api/vessels/track?mmsi=' + encodeURIComponent(reference), { signal }, 'Vessels', ); if (!response.ok) throw httpError(response, 'Vessels'); return { records: normalizeVesselTrack(payload?.samples), complete: false, }; }, }; }