AirTrail 3.13 adds /api/v1 and marks the /api/flight/* routes as deprecated. TREK now asks the public discovery document GET /api/v1 and uses v1 when the instance has it. It uses the legacy routes for an older instance. The client methods keep their signatures, and the sync hash stays the same, so a linked flight does not sync again when an instance changes to v1. The probe cache holds only a clear answer: 200 with the discovery document gives v1, and 404 gives legacy. The cache is per AirTrail URL, for 10 minutes. A timeout, a 5xx or a network error fails that call only. A 401, a 403 or a page that is not the discovery document uses legacy for that call only. A 404 for one flight makes the client ask the probe again before it reports the flight as deleted. A missing scope gives AirtrailScopeError, which names the scope. It does not unlink a flight. The API key hint and the help step list the scopes for read and for write-back, in all languages. Each new request goes through safeFetch, with the SSRF guard, the timeout and the size cap. The flight list reads pages of 100 and fails above 50 pages. A failed list unlinks nothing. airtrail-v1.ts translates between the v1 shapes and the legacy shapes. A write-back looks up the airport, airline and aircraft ids, and changes each local time to a UTC instant in the zone of its own airport. It writes each instant in the +00:00 form of the legacy save, because AirTrail stores the string as it gets it and the sync hash reads that string. The tests cover both APIs over HTTP, the probe cache rules, the sync hash on a switch and on a save, the page limit, the scope error, and the UTC conversion across midnight, the date line and daylight-saving changes.
@trek/shared
Single source of truth for TREK's API contracts, expressed as Zod schemas and consumed by both the server (request validation + inferred DTO types) and the client (typed requests/responses).
This package is part of the incremental NestJS + React 19 migration (see the "Brownfield Rewrite" board). It is intentionally dormant until modules start importing it — adding it changes nothing for users.
Rules
- One folder per domain:
src/<domain>/<domain>.schema.ts(+.spec.ts). - Domain-agnostic building blocks live in
src/common/. - A route is only considered migrated once its contract lives here.
- Schemas are the source of truth; server DTOs and client types are inferred from them
(
z.infer<typeof schema>), never hand-duplicated.
Consumption (dev)
Both apps resolve @trek/shared to this package's TypeScript source:
- Server (
tsx): viapathsinserver/tsconfig.json. - Client (
vite): viaresolve.aliasinclient/vite.config.ts(+pathsfor the type-checker).
Production packaging (Docker / workspace wiring) is introduced in card F2, when the server first depends on this package at runtime. Until then prod builds are untouched.
Not yet here
The canonical error envelope is finalised in card F5 (it must match TREK's current Express error responses byte-for-byte), so it is deliberately not invented in F1.