airfrance-afkl

# 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...

# airfrance-afkl-skill

Clawdbot skill to track **Air France flights** using the **Air France–KLM Open Data APIs** (Flight Status).

It’s designed for day-to-day travel monitoring:
- Flight status + schedule vs latest published times
- Terminal / gate (when published)
- Boarding close time (when available)
- Aircraft tail number + cabin configuration summary (best-effort)
- Previous-flight chain (useful to estimate delay risk)
- Compact alerts: you only get pinged when displayed fields change

## Prerequisites

1) Register and create an API key on the AFKL developer portal:
- https://developer.airfranceklm.com

2) Subscribe to Open Data products (at least **Flight Status API**).

## Configuration

Provide credentials **via environment variables** (recommended):

```bash
export AFKL_API_KEY="..."
# optional
export AFKL_API_SECRET="..."
```

Or via files in your state dir:

- Set `CLAWDBOT_STATE_DIR` to your state directory (or it falls back to `./state`)
- Create:
  - `afkl_api_key.txt`
  - `afkl_api_secret.txt` (optional)

## Usage

### One-off query

```bash
node skills/airfrance-afkl/scripts/afkl_flightstatus_query.mjs \
  --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29
```

### Watcher (poll + change-only output)

```bash
node skills/airfrance-afkl/scripts/afkl_watch_flight.mjs \
  --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29 --prev-depth 2
```

Output behavior:
- **Prints nothing** when nothing changed
- Prints a **ready-to-send multi-line message** when something changed

The message is designed to be compact and human-readable:
- Emojis for 🛫/🕤/🛬/✈️/📶
- Weekday + date + time (to avoid timezone ambiguity)
- Tail + aircraft type + cabin config summary
- Wi‑Fi line (fast/slow) when available
- Previous-flight chain summary (e.g. `↩️ Dubai → Paris → New York (on time)`)
- Optional headline line highlighting what changed (new time, inbound delay, new aircraft, boarding started)


## Rate limits

AFKL Open Data is rate-limited (commonly...