Air France (AFKL Open Data) flight tracker

Quick start (one-off status)

1) Create an API key (and optional secret) - Register on: https://developer.airfranceklm.com - Subscribe to the Open Data product(s) you need (at least Flight Status API) - Generate credentials (API key; some accounts also provide an API secret)

2) Provide API credentials (do not print them): - Preferred: env vars AFKL_API_KEY (and optional AFKL_API_SECRET) - Or files in your state dir (CLAWDBOT_STATE_DIR or ./state): - afkl_api_key.txt (chmod 600) - afkl_api_secret.txt (chmod 600, optional)

2) Query flight status: - Run: node skills/airfrance-afkl/scripts/afkl_flightstatus_query.mjs --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29

Notes: - Send Accept: */* (API returns application/hal+json). - Keep within limits: <= 1 request/sec. When making multiple calls, sleep ~1100ms between them.

Start monitoring (watcher)

Use when the user wants proactive updates.

• Run: node skills/airfrance-afkl/scripts/afkl_watch_flight.mjs --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29

What it does: - Fetches the operational flight(s) for the date window. - Emits a single message only when something meaningful changes. - Also follows the previous-flight chain (flightRelations.previousFlightData.id) up to a configurable depth and alerts if a previous segment is delayed/cancelled.

Polling strategy (default): - >36h before departure: at most every 60 min - 36h→12h: every 30 min - 12h→3h: every 15 min - 3h→departure: every 5–10 min (stay under daily quota) - After departure: every 30 min until arrival

Implementation detail: run cron every 5–15 min, but the script self-throttles using a state file so it won’t hit the API when it’s not time. The watcher prints no output when nothing changed (so cron jobs can send only when stdout is non-empty).

Input shorthand

Preferred user-facing format: - AF7 demain / AF7 jeudi

Interpretation rule: - The day always refers to the departure date (not arrival).

Implementation notes: - Convert relative day words to a departure date in the user’s timezone unless the origin timezone is explicitly known. - When ambiguous (long-haul crossing midnight), prefer the departure local date at the origin if origin is known.

(For scripts, still pass --origin + --dep-date YYYY-MM-DD.)

Interpret “interesting” fields

See references/fields.md for: - flightRelations (prev/next) - places.* (terminal/gate/check-in zone) - times.* (scheduled/estimated/latest/actual) - aircraft (type, registration) - “parking position” / stand-type hints (when present) - Wi‑Fi hints and how to reason about cabin recency

Cabin recency / upgrade heuristics

When aircraft registration is available: - Use tail number to infer sub-fleet and likely cabin generation. - If data suggests older config (or no Wi‑Fi), upgrading can be more/less worth it.

Be conservative: - Open Data often doesn’t expose exact seat model; treat this as best-effort.