/** * Dawarich API client: the wire shapes HealthLog reads and nothing more. * * Dawarich (https://dawarich.app) is a self-hosted location history. HealthLog * reads four endpoints, all with `Authorization: Bearer `: * * GET /api/v1/timeline?start_at&end_at&distance_unit=km * one entry per day in the Dawarich account's own zone (its timezone * setting, the instance's `TIME_ZONE` by default; the request cannot * name one), summing only what lies inside the window, with a `summary`: * `total_distance`, `places_visited`, `mode_distances.{driving,train}` * in km to one decimal. At most 31 days per request. * GET /api/v1/visits?start_at&end_at * visits that STARTED in the window: `started_at`, `ended_at`, * `status`, `place.id`. The coordinates and the name in the payload * are read past and dropped here; nothing but the place id survives. * GET /api/v1/residency?year=YYYY * `daily_countries` (UTC date to country name) and `countries[]` * (country name to ISO 3166-1 alpha-2). Answers 403 on a hosted plan * without API access; then there is no travel signal. * GET /api/v1/places, /api/v1/places/:id * to pick and check the home place; id and name only, never stored. * GET /api/v1/users/me * the cheapest authenticated call, used to check a key. * * Every call goes through `safeFetch`: `requirePublicHost` for a public * instance, the operator-approved pinned dispatcher for an origin listed in * `DAWARICH_PRIVATE_ORIGINS`. The policy is re-read on every call, so taking * an origin off the list stops the next request. */ import { readBodyCapped } from "@/lib/http/read-capped"; import { SafeFetchError, safeFetch } from "@/lib/safe-fetch"; import { configuredDawarichPrivateOrigins, evaluateDawarichUrl, } from "./origin"; const DEFAULT_TIMEOUT_MS = 20_000; /** * The most any one answer may hold. A month of timeline with its entries and * a year of residency stay far below it; the cap is what keeps an instance * that streams without end from holding the worker's memory until the * timeout. */ const MAX_BODY_BYTES = 16 * 1024 * 1024; /** Dawarich refuses a timeline window longer than 31 days. */ export const TIMELINE_MAX_DAYS = 31; /** The places list is read once per request and capped before filtering. */ const PLACES_PAGE_SIZE = 500; /** At most this many places go back to the picker. */ const PLACES_RESULT_LIMIT = 200; export interface DawarichConnection { baseUrl: string; apiKey: string; } /** The instance answered with a status outside 2xx, or not with JSON. */ export class DawarichApiError extends Error { readonly status: number | null; constructor(message: string, status: number | null) { super(message); this.name = "DawarichApiError"; this.status = status; } } /** The address is private and not on the operator's list, or not usable at all. */ export class DawarichPolicyError extends Error { readonly reasonCode: string; constructor(reasonCode: string) { super(reasonCode); this.name = "DawarichPolicyError"; this.reasonCode = reasonCode; } } async function dawarichGet( conn: DawarichConnection, path: string, query: Record = {}, timeoutMs: number = DEFAULT_TIMEOUT_MS, ): Promise { const target = evaluateDawarichUrl( conn.baseUrl, configuredDawarichPrivateOrigins(), ); if (!target.allowed || !target.baseUrl || !target.origin) { throw new DawarichPolicyError( target.reasonCode ?? "private_origin_not_approved", ); } const url = new URL(`${target.baseUrl}${path}`); for (const [key, value] of Object.entries(query)) { url.searchParams.set(key, value); } let res: Response; try { res = await safeFetch( url.toString(), { method: "GET", headers: { Accept: "application/json", Authorization: `Bearer ${conn.apiKey}`, }, }, { requirePublicHost: !target.privateOriginApproved, ...(target.privateOriginApproved ? { operatorApprovedPrivateOrigin: target.origin } : {}), timeoutMs, }, ); } catch (error) { if (error instanceof SafeFetchError && error.kind === "private_host") { throw new DawarichPolicyError("private_origin_not_approved"); } throw error; } if (res.status < 200 || res.status >= 300) { throw new DawarichApiError(`Dawarich responded ${res.status}`, res.status); } const read = await readBodyCapped(res, MAX_BODY_BYTES); if (!read.ok) { throw new DawarichApiError("Dawarich returned an oversized body", null); } try { return JSON.parse(read.text) as unknown; } catch { throw new DawarichApiError("Dawarich returned a non-JSON body", null); } } // ── Timeline ───────────────────────────────────────────────────────── /** One day's summary, distances in km as Dawarich reports them. */ export interface TimelineDaySummary { date: string; totalKm: number | null; drivingKm: number | null; trainKm: number | null; placesVisited: number | null; } function finiteOrNull(value: unknown): number | null { return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null; } /** * Read the day summaries out of a timeline answer. A mode absent from * `mode_distances` is zero for that day (Dawarich leaves out a mode that moved * less than half a kilometre), so it reads as 0 whenever the summary itself is * there. Everything else in the payload (entries, bounds, names) is dropped. */ export function parseTimelineDays(payload: unknown): TimelineDaySummary[] { const days = (payload as { days?: unknown } | null)?.days; if (!Array.isArray(days)) return []; const out: TimelineDaySummary[] = []; for (const raw of days) { if (!raw || typeof raw !== "object") continue; const day = raw as { date?: unknown; summary?: unknown }; if (typeof day.date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(day.date)) { continue; } const summary = day.summary && typeof day.summary === "object" ? (day.summary as Record) : null; if (!summary) continue; const modes = summary.mode_distances && typeof summary.mode_distances === "object" ? (summary.mode_distances as Record) : {}; out.push({ date: day.date, totalKm: finiteOrNull(summary.total_distance), drivingKm: finiteOrNull(modes.driving) ?? 0, trainKm: finiteOrNull(modes.train) ?? 0, placesVisited: typeof summary.places_visited === "number" && Number.isInteger(summary.places_visited) && summary.places_visited >= 0 ? summary.places_visited : null, }); } return out; } export async function fetchTimeline( conn: DawarichConnection, startAt: Date, endAt: Date, ): Promise { return parseTimelineDays( await dawarichGet(conn, "/api/v1/timeline", { start_at: startAt.toISOString(), end_at: endAt.toISOString(), distance_unit: "km", }), ); } // ── Visits ─────────────────────────────────────────────────────────── /** A visit reduced to what time away from home needs. */ export interface VisitSpan { placeId: number | null; startMs: number; endMs: number; } /** * Read the visits. A declined visit (the person said it did not happen) is * dropped; so is one without a usable time span. Coordinates and names in the * payload are never copied out. */ export function parseVisits(payload: unknown): VisitSpan[] { if (!Array.isArray(payload)) return []; const out: VisitSpan[] = []; for (const raw of payload) { if (!raw || typeof raw !== "object") continue; const visit = raw as Record; if (visit.status === "declined") continue; const startMs = typeof visit.started_at === "string" ? Date.parse(visit.started_at) : NaN; const endMs = typeof visit.ended_at === "string" ? Date.parse(visit.ended_at) : NaN; if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) continue; if (endMs <= startMs) continue; const place = visit.place && typeof visit.place === "object" ? (visit.place as Record) : null; const placeId = typeof place?.id === "number" && Number.isInteger(place.id) ? place.id : null; out.push({ placeId, startMs, endMs }); } return out; } export async function fetchVisits( conn: DawarichConnection, startAt: Date, endAt: Date, ): Promise { return parseVisits( await dawarichGet(conn, "/api/v1/visits", { start_at: startAt.toISOString(), end_at: endAt.toISOString(), }), ); } // ── Residency ──────────────────────────────────────────────────────── /** UTC date to ISO 3166-1 alpha-2, for the days the year holds a country. */ export type DailyCountries = Map; /** * Read `daily_countries` and translate each country name through the * `countries[]` table into its alpha-2 code. A name without a code is dropped: * a country HealthLog cannot name is no basis for a travel day. */ export function parseResidency(payload: unknown): DailyCountries { const out: DailyCountries = new Map(); if (!payload || typeof payload !== "object") return out; const body = payload as Record; const codeByName = new Map(); if (Array.isArray(body.countries)) { for (const raw of body.countries) { if (!raw || typeof raw !== "object") continue; const country = raw as Record; if ( typeof country.country_name === "string" && typeof country.iso_a2 === "string" && /^[A-Za-z]{2}$/.test(country.iso_a2) ) { codeByName.set(country.country_name, country.iso_a2.toUpperCase()); } } } const daily = body.daily_countries && typeof body.daily_countries === "object" ? (body.daily_countries as Record) : {}; for (const [date, name] of Object.entries(daily)) { if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || typeof name !== "string") continue; const code = codeByName.get(name); if (code) out.set(date, code); } return out; } /** * One year of residency, or null when the instance does not offer it (a * hosted plan without API access answers 403, an older instance 404). Any * other failure is thrown like every other call. */ export async function fetchResidency( conn: DawarichConnection, year: number, ): Promise { try { return parseResidency( await dawarichGet(conn, "/api/v1/residency", { year: String(year) }), ); } catch (error) { if ( error instanceof DawarichApiError && (error.status === 403 || error.status === 404) ) { return null; } throw error; } } // ── Places ─────────────────────────────────────────────────────────── export interface DawarichPlace { id: number; name: string; } /** Id and name of each place, filtered by `q`, sorted by name, capped. */ export function parsePlaces(payload: unknown, q?: string): DawarichPlace[] { if (!Array.isArray(payload)) return []; const needle = q?.trim().toLocaleLowerCase() ?? ""; const out: DawarichPlace[] = []; for (const raw of payload) { if (!raw || typeof raw !== "object") continue; const place = raw as Record; if (typeof place.id !== "number" || !Number.isInteger(place.id)) continue; const name = typeof place.name === "string" ? place.name.trim() : ""; if (!name) continue; if (needle && !name.toLocaleLowerCase().includes(needle)) continue; out.push({ id: place.id, name: name.slice(0, 200) }); } out.sort((a, b) => a.name.localeCompare(b.name) || a.id - b.id); return out.slice(0, PLACES_RESULT_LIMIT); } export async function fetchPlaces( conn: DawarichConnection, q?: string, ): Promise { return parsePlaces( await dawarichGet(conn, "/api/v1/places", { filter: "all", page: "1", per_page: String(PLACES_PAGE_SIZE), }), q, ); } /** Whether the instance knows a place with this id. */ export async function placeExists( conn: DawarichConnection, id: number, ): Promise { try { await dawarichGet(conn, `/api/v1/places/${id}`); return true; } catch (error) { if (error instanceof DawarichApiError && error.status === 404) { return false; } throw error; } } /** Check the key with the cheapest authenticated call. */ export async function probeDawarich( conn: DawarichConnection, timeoutMs?: number, ): Promise { await dawarichGet(conn, "/api/v1/users/me", {}, timeoutMs); }