fpv-laptimer-client 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# fpv-laptimer-client (JavaScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client für die API des [FPV-Laptimers](https://github.com/bli-blu-bla/fpv-laptimer) (`/api/v1`,
+ausführlich in der [Doku](https://bli-blu-bla.github.io/fpv-laptimer/api/)):
+jeder Befehl als Methode, Events live über den WebSocket, mit automatischem Neuverbinden.
+
+- läuft in **Node ≥ 22** und im **Browser** (nutzt das eingebaute `fetch` und `WebSocket`)
+- **keine Abhängigkeiten**, reines JavaScript mit JSDoc-Typen (`// @ts-check`), der Editor
+  ergänzt also Befehle, Argumente und Event-Felder
+
+## Einbinden
+
+```sh
+npm install fpv-laptimer-client
+# oder aus dem Repo: npm install github:bli-blu-bla/fpv-laptimer-client-js
+```
+
+```js
+import { Laptimer, LaptimerError } from 'fpv-laptimer-client'
+// oder ohne npm, mit dem Pfad zum Klon: import { Laptimer } from './fpv-laptimer-client-js/src/index.js'
+
+const lt = new Laptimer({ url: 'http://pi:5800', key: 'lt_…' })
+```
+
+Den Schlüssel legst du auf der Seite unter *API & Hooks → Schlüssel* an.
+
+Optionen: `url`, `key`, `transport` (`'auto'` oder `'http'`, siehe unten), `timeout_ms`
+(pro Befehl, Standard 15 000), `max_backoff_ms` (längste Pause beim Neuverbinden, Standard
+10 000).
+
+## Beispiele
+
+**Rennen über 3 Runden starten:**
+
+```js
+await lt.channels.assign(['NITRO', 'ACE', null, 'BOB'], { create: true })
+const session = await lt.session.start({ race: true, laps: 3, countdown_s: 5 })
+console.log('Rennen', session.id, session.phase) // "countdown"
+```
+
+**Jede Runde ansagen** (hier: ausgeben):
+
+```js
+lt.on('pilot_pass', (d) => {
+  if (d.kind === 'lap') console.log(`${d.pilot}: Runde ${d.lap} in ${d.lap_time_s?.toFixed(2)} s, Platz ${d.position}`)
+})
+lt.on('pilot_finished', (d) => console.log(`${d.pilot} im Ziel, Platz ${d.position}`))
+await lt.connect()
+```
+
+**Ergebnis bestätigen**, sobald das Rennen vorbei ist (alle im Ziel oder gestoppt):
+
+```js
+lt.on('session_stopped', async (d) => {
+  if (!d.needs_confirmation) return
+  console.log('Sieger:', d.winner)
+  await lt.session.confirm(d.session_id)
+})
+```
+
+Oder der Reihe nach mit `waitFor`:
+
+```js
+const stopped = await lt.waitFor('session_stopped', { filter: (d) => d.session_id === session.id, timeout_ms: 30 * 60_000 })
+await lt.session.confirm(stopped.session_id)
+```
+
+**Fehler** kommen als `LaptimerError` mit der Meldung des Servers (deutsch, zum direkten
+Anzeigen):
+
+```js
+try {
+  await lt.session.start()
+} catch (e) {
+  if (e instanceof LaptimerError) console.log(e.message, e.status) // "Es läuft schon eine Session – erst stoppen." 400
+  else throw e
+}
+```
+
+`status`: HTTP-Status (400 falsche Argumente oder nicht erlaubt, 401 Schlüssel fehlt oder ist
+falsch, 404 unbekannter Befehl; über den WebSocket dieselben Zahlen); `null`, wenn der Server
+nicht erreichbar ist. `command`: der Befehl.
+
+Zum Ausprobieren in [`examples/`](examples/):
+
+```sh
+LAPTIMER_URL=http://pi:5800 LAPTIMER_KEY=lt_… node examples/events.js        # alle Events anzeigen
+LAPTIMER_URL=http://pi:5800 LAPTIMER_KEY=lt_… node examples/race.js NITRO ACE  # Rennen, Runden, bestätigen
+```
+
+## Methoden
+
+Alle geben ein Promise zurück. Kanäle zählen ab 0 (Slot 1 auf der Seite = Kanal 0), Zeiten
+sind µs seit 1970.
+
+| Methode | Befehl | Ergebnis |
+|---|---|---|
+| `ping()` | `ping` | `{pong, now_us}` |
+| `state()` | `state` | Gesamtzustand: `session`, `unconfirmed`, `channels`, `pilots`, `boards` |
+| `stats()` | `stats` | Bestzeiten, Rennen, Siege pro Pilot (`all`, `today`) |
+| `channels.list()` | `channels.list` | Kanäle |
+| `channels.set(index, {pilot, pilot_id, create, label, enabled, frequency})` | `channels.set` | der Kanal; nur Angegebenes ändert sich |
+| `channels.assign(pilots, {create})` | `channels.assign` | alle Kanäle; `pilots` = Callsign, ID oder `null` pro Kanal |
+| `pilots.list()` | `pilots.list` | Piloten |
+| `pilots.get(id)` | `pilots.get` | Pilot |
+| `pilots.create(name, full_name?)` | `pilots.create` | Pilot |
+| `pilots.update(id, {name, full_name})` | `pilots.update` | Pilot |
+| `pilots.delete(id)` | `pilots.delete` | `{}` |
+| `session.start({race, laps, seconds, countdown_s, start_mode})` | `session.start` | die Session; ohne Argumente ein Training |
+| `session.stop()` | `session.stop` | `{session_id}` |
+| `session.cancel()` | `session.cancel` | stoppt und löscht die laufende Session |
+| `session.confirm(id?)` | `session.confirm` | `{session_id}`; ohne `id` das Rennen, das auf Bestätigung wartet |
+| `session.discard(id?)` | `session.discard` | löscht eine beendete Session |
+| `sessions.list({limit})` | `sessions.list` | die letzten Sessions (Standard 20) |
+| `sessions.get(id)` | `sessions.get` | Session mit allen Durchflügen (`passes`) |
+| `passes.add(channel, {time_us, session_id})` | `passes.add` | `{pass_id, session_id, time_us}`; Standard: jetzt, laufende Session |
+| `passes.delete(id)` | `passes.delete` | erkannte werden nur markiert, von Hand eingefügte entfernt |
+| `passes.restore(id)` | `passes.restore` | einen markierten wiederherstellen |
+| `command(name, args)` | jeder | für Befehle, die neuer sind als dieser Client |
+
+Was die Felder bedeuten, steht in der Doku unter [Events](https://bli-blu-bla.github.io/fpv-laptimer/api/events/) und [Datenformate](https://bli-blu-bla.github.io/fpv-laptimer/api/datenformate/); die Typen in
+[`src/types.js`](src/types.js).
+
+## Events
+
+```js
+const off = lt.on('pilot_pass', (data, msg) => { … })   // msg: {event, seq, time_us, data}
+lt.on('*', (data, msg) => console.log(msg.event, data))  // jedes Event
+off()                                                    // oder lt.off('pilot_pass', fn)
+await lt.connect()                                       // liefert das hello mit state
+lt.close()
+```
+
+Events des Servers: `session_started`, `countdown`, `start_signal`, `pilot_pass`,
+`pilot_finished`, `session_stopped`, `race_confirmed`, `session_deleted`, `sessions_reset`, `passes_changed`,
+`channels_changed`, `pilot_added`, `pilot_updated`, `pilot_deleted`.
+
+Dazu drei vom Client selbst:
+
+| Name | wann |
+|---|---|
+| `hello` | verbunden (auch nach jedem Neuverbinden), `data.state` ist der aktuelle Zustand |
+| `disconnected` | Verbindung weg; der Client verbindet sich wieder |
+| `lagged` | der Client war zu langsam, `data.missed` Events fehlen: `state()` neu holen |
+
+`waitFor(name, {filter, timeout_ms})` wartet auf das nächste passende Event und liefert seine
+Daten (Standard-Zeitlimit 30 s, dann ein Fehler).
+
+**Neuverbinden:** Bricht die Verbindung ab (Pi neu gestartet, WLAN weg), verbindet sich der
+Client von selbst wieder, mit wachsenden Pausen (0,5 s, 1 s, 2 s … bis `max_backoff_ms`), bis
+`close()`. Events, die in der Pause passiert sind, kommen nicht nach: nach `hello` den Zustand
+aus `data.state` nehmen. Klappt schon der **erste** `connect()` nicht (falsche Adresse,
+falscher Schlüssel), lehnt das Promise mit der Meldung des Servers ab, und es wird nichts
+wiederholt.
+
+## HTTP oder WebSocket
+
+Befehle gehen per HTTP (`POST /api/v1/cmd/<befehl>`, Schlüssel im Header
+`Authorization: Bearer`). Solange der WebSocket verbunden ist, gehen sie über ihn (kein neuer
+Verbindungsaufbau pro Befehl). Mit `transport: 'http'` bleiben sie immer bei HTTP. Bricht der
+WebSocket mitten in einem Befehl ab, schlägt dieser mit einem `LaptimerError` fehl; er wird
+nicht automatisch wiederholt (er könnte schon ausgeführt sein).
+
+Der WebSocket bekommt den Schlüssel als `?key=…`, weil Browser bei WebSockets keine Header
+setzen können. Im Browser gilt außerdem: eine Seite über `https://` darf keine Verbindung zu
+`http://pi:5800` aufbauen; der Laptimer selbst läuft ohne HTTPS.
+
+## Tests
+
+Gegen einen laufenden Server ohne Boards, am besten mit eigenem Datenordner (die Tests legen
+Piloten an, starten Trainings und Rennen und ändern das gespeicherte Rennformat):
+
+```sh
+# im Laptimer-Repo:
+cd server && ./target/debug/laptimer serve --port 5801 --data /tmp/lt-test --sounds /tmp/leer
+curl -s -H 'content-type: application/json' -d '{"name":"test"}' http://localhost:5801/api/keys   # {"key": "lt_…"}
+# hier:
+LAPTIMER_URL=http://localhost:5801 LAPTIMER_KEY=lt_… npm test
+```
+
+Ohne die beiden Variablen werden die Tests übersprungen. Typprüfung: `npm run check` (lädt
+TypeScript nur als Prüfer).
+
+## Veröffentlichen (npm)
+
+Die Version kommt aus dem Git-Tag und ist unabhängig von Server und Python-Client. Im Repo
+steht in `package.json` nur der Platzhalter `0.0.0-dev`; der Workflow schreibt vor dem Packen
+die echte Version hinein. Ablauf:
+
+1. Tag `v<version>` pushen, z. B. `git tag v0.2.0 && git push origin v0.2.0`
+   (SemVer, Vorabversionen wie `0.2.0-rc.1`).
+2. Der Workflow `.github/workflows/npm.yml` setzt die Version, prüft die Typen, packt das Paket
+   (`prepack` erzeugt dabei `types/*.d.ts` aus dem JSDoc, damit auch TypeScript-Projekte die
+   Typen bekommen), installiert es testweise und lädt es per Trusted Publishing (ohne Token,
+   mit Herkunftsnachweis) auf npm. Vorabversionen bekommen das Dist-Tag `next`, damit
+   `npm install` weiter die letzte richtige Version holt.
+
+Von Hand starten (*Actions → npm → Run workflow*) packt und prüft nur
+(`npm publish --dry-run`); npm hat kein Test-Register wie TestPyPI.
+
+Einmal einrichten: npm bietet Trusted Publishing nur für ein Paket an, das es schon gibt. Die
+erste Version deshalb von Hand:
+
+```sh
+npm login
+npm version 0.1.0 --no-git-tag-version
+npm publish --access public
+git checkout package.json        # zurück auf den Platzhalter
+```
+
+Diese erste Version bekommt keinen Tag (der Workflow würde sie noch einmal hochladen wollen und
+scheitern); die nächste kommt dann über `v0.2.0`.
+
+Danach auf npmjs.com unter *Package → Settings → Trusted Publisher* GitHub Actions wählen:
+Owner `bli-blu-bla`, Repo `fpv-laptimer-client-js`, Workflow `npm.yml`, Environment `npm`; im
+GitHub-Repo unter *Settings → Environments* das Environment `npm` anlegen (am besten mit
+Freigabe durch dich). Ab dann gehen alle Versionen über den Tag.
+
+Lokal packen und ansehen: `npm pack --dry-run` (bzw. `npm pack` für die Datei).

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "fpv-laptimer-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "JavaScript-Client für die API des FPV-Laptimers (/api/v1): Befehle per HTTP oder WebSocket, Events live",
+  "keywords": [
+    "fpv",
+    "drone",
+    "racing",
+    "laptimer",
+    "lap timer"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "npx -y -p typescript@5.9.3 tsc -p jsconfig.json",
+    "types": "npx -y -p typescript@5.9.3 tsc -p jsconfig.json --noEmit false --declaration --emitDeclarationOnly --outDir types",
+    "prepack": "npm run types"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bli-blu-bla/fpv-laptimer-client-js.git"
+  },
+  "homepage": "https://bli-blu-bla.github.io/fpv-laptimer/api/clients/",
+  "bugs": "https://github.com/bli-blu-bla/fpv-laptimer-client-js/issues",
+  "author": "bli-blu-bla",
+  "license": "GPL-3.0-or-later"
+}

package/src/index.js

@@ -0,0 +1,16 @@
+// @ts-check
+// fpv-laptimer-client: everything in one import.
+export { Laptimer, LaptimerError } from './laptimer.js'
+
+/** @typedef {import('./types.js').Channel} Channel */
+/** @typedef {import('./types.js').ChannelChange} ChannelChange */
+/** @typedef {import('./types.js').Pilot} Pilot */
+/** @typedef {import('./types.js').Session} Session */
+/** @typedef {import('./types.js').SeatResult} SeatResult */
+/** @typedef {import('./types.js').Pass} Pass */
+/** @typedef {import('./types.js').State} State */
+/** @typedef {import('./types.js').Stats} Stats */
+/** @typedef {import('./types.js').StartOptions} StartOptions */
+/** @typedef {import('./types.js').EventMap} EventMap */
+/** @typedef {import('./types.js').PilotPassData} PilotPassData */
+/** @typedef {import('./types.js').SessionStoppedData} SessionStoppedData */

package/src/laptimer.js

@@ -0,0 +1,395 @@
+// @ts-check
+// Client for the lap timer's public API (/api/v1, https://bli-blu-bla.github.io/fpv-laptimer/api/).
+// No dependencies: global fetch and WebSocket (Node >= 22, browsers).
+
+/** @import { Channel, ChannelChange, EventMap, EventMessage, Hello, Pilot, Session, StartOptions, State, Stats } from './types.js' */
+
+/**
+ * An error from the server (its message is German, meant to be shown as is)
+ * or from the connection.
+ */
+export class LaptimerError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [info]
+   * @param {number | null} [info.status]   HTTP status (400 bad arguments, 401 key, 404 unknown command), the same over the WebSocket; null without an answer
+   * @param {string} [info.command]
+   * @param {unknown} [info.cause]
+   */
+  constructor(message, { status = null, command, cause } = {}) {
+    super(message, { cause })
+    this.name = 'LaptimerError'
+    /** @type {number | null} */
+    this.status = status
+    /** @type {string | undefined} */
+    this.command = command
+  }
+}
+
+/**
+ * What `on` can listen to: the server's events, `'*'` (every event) and
+ * three of the client's own: `hello` (connected, with the state),
+ * `lagged` (events were lost: fetch the state again) and `disconnected`.
+ * @typedef {EventMap & {
+ *   '*': any,
+ *   hello: Hello,
+ *   lagged: {missed: number},
+ *   disconnected: {code: number, reason: string},
+ * }} ClientEvents
+ */
+
+/**
+ * @template {string} K
+ * @typedef {(data: K extends keyof ClientEvents ? ClientEvents[K] : any, msg: EventMessage<any> | any) => void} Listener
+ */
+
+/**
+ * @typedef {object} LaptimerOptions
+ * @property {string} url                 e.g. "http://pi:5800"
+ * @property {string} key                 API key "lt_…"
+ * @property {'auto' | 'http'} [transport]  auto (default): commands over the WebSocket while it is connected, else HTTP
+ * @property {number} [timeout_ms]        per command, default 15000
+ * @property {number} [max_backoff_ms]    longest wait between reconnects, default 10000
+ */
+
+export class Laptimer {
+  /** @type {WebSocket | null} */
+  #ws = null
+  /** true between connect() and close(): reconnect when the socket drops. */
+  #wanted = false
+  /** The socket got its `hello` (commands may go over it). */
+  #ready = false
+  #attempt = 0
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  #retryTimer = null
+  /** @type {Promise<Hello> | null} */
+  #connecting = null
+  #nextId = 1
+  /** Commands sent over the WebSocket, waiting for their reply (by id). @type {Map<number, {resolve: (v: any) => void, reject: (e: Error) => void, timer: ReturnType<typeof setTimeout>, cmd: string}>} */
+  #pending = new Map()
+  /** @type {Map<string, Set<Function>>} */
+  #listeners = new Map()
+
+  /** @param {LaptimerOptions} options */
+  constructor({ url, key, transport = 'auto', timeout_ms = 15000, max_backoff_ms = 10000 }) {
+    if (!url) throw new TypeError("Laptimer: 'url' fehlt, z. B. http://pi:5800")
+    if (!key) throw new TypeError("Laptimer: 'key' fehlt (API-Schlüssel lt_…)")
+    this.url = url.replace(/\/+$/, '')
+    this.key = key
+    this.transport = transport
+    this.timeout_ms = timeout_ms
+    this.max_backoff_ms = max_backoff_ms
+
+    // The commands by group, as in the API (channels.set → client.channels.set).
+    this.channels = {
+      /** @returns {Promise<Channel[]>} */
+      list: () => this.command('channels.list'),
+      /**
+       * One channel; only the given fields change. A pilot or frequency another
+       * channel has is swapped with it.
+       * @param {number} index  0 = first channel
+       * @param {ChannelChange} change
+       * @returns {Promise<Channel>}
+       */
+      set: (index, change) => this.command('channels.set', { ...change, index }),
+      /**
+       * All channels at once, in order: callsign, pilot id or null per channel.
+       * @param {(string | number | null)[]} pilots
+       * @param {{create?: boolean}} [options]  create: make unknown callsigns pilots
+       * @returns {Promise<Channel[]>}
+       */
+      assign: (pilots, { create } = {}) => this.command('channels.assign', { pilots, create }),
+    }
+
+    this.pilots = {
+      /** @returns {Promise<Pilot[]>} */
+      list: () => this.command('pilots.list'),
+      /** @param {number} id @returns {Promise<Pilot>} */
+      get: (id) => this.command('pilots.get', { id }),
+      /** @param {string} name callsign @param {string} [full_name] @returns {Promise<Pilot>} */
+      create: (name, full_name) => this.command('pilots.create', { name, full_name }),
+      /** @param {number} id @param {{name?: string, full_name?: string}} change @returns {Promise<Pilot>} */
+      update: (id, change) => this.command('pilots.update', { ...change, id }),
+      /** @param {number} id @returns {Promise<{}>} */
+      delete: (id) => this.command('pilots.delete', { id }),
+    }
+
+    this.session = {
+      /**
+       * Starts a training (default) or a race. Refused while a session runs or
+       * a race waits for confirmation.
+       * @param {StartOptions} [options]
+       * @returns {Promise<Session>}
+       */
+      start: (options = {}) => this.command('session.start', options),
+      /** @returns {Promise<{session_id: number}>} */
+      stop: () => this.command('session.stop'),
+      /** Stops and deletes the running session. @returns {Promise<{session_id: number}>} */
+      cancel: () => this.command('session.cancel'),
+      /** @param {number} [id] default: the race waiting for confirmation @returns {Promise<{session_id: number}>} */
+      confirm: (id) => this.command('session.confirm', { id }),
+      /** Deletes an ended session. @param {number} [id] default: the race waiting for confirmation @returns {Promise<{session_id: number}>} */
+      discard: (id) => this.command('session.discard', { id }),
+    }
+
+    this.sessions = {
+      /** @param {{limit?: number}} [options] default 20 @returns {Promise<Session[]>} */
+      list: ({ limit } = {}) => this.command('sessions.list', { limit }),
+      /** With every pass (`passes`). @param {number} id @returns {Promise<Session>} */
+      get: (id) => this.command('sessions.get', { id }),
+    }
+
+    this.passes = {
+      /**
+       * A pass by hand: counts like a detected one (announcement, `pilot_pass`).
+       * @param {number} channel  index
+       * @param {{time_us?: number, session_id?: number}} [options]  default: now, the running session
+       * @returns {Promise<{pass_id: number, session_id: number, time_us: number}>}
+       */
+      add: (channel, { time_us, session_id } = {}) => this.command('passes.add', { channel, time_us, session_id }),
+      /** Detected passes are only marked (restorable). @param {number} id @returns {Promise<{session_id: number}>} */
+      delete: (id) => this.command('passes.delete', { id }),
+      /** @param {number} id @returns {Promise<{session_id: number}>} */
+      restore: (id) => this.command('passes.restore', { id }),
+    }
+  }
+
+  /** @returns {Promise<{pong: true, now_us: number}>} */
+  ping() {
+    return this.command('ping')
+  }
+
+  /** @returns {Promise<State>} */
+  state() {
+    return this.command('state')
+  }
+
+  /** @returns {Promise<Stats>} */
+  stats() {
+    return this.command('stats')
+  }
+
+  /** True while the WebSocket is connected (and commands go over it with transport "auto"). */
+  get connected() {
+    return this.#ready
+  }
+
+  // --- commands ---
+
+  /**
+   * Any command by name, e.g. `command('session.start', {race: true})`.
+   * Arguments that are `undefined` are left out.
+   * @param {string} name
+   * @param {Record<string, unknown>} [args]
+   * @returns {Promise<any>}
+   */
+  command(name, args = {}) {
+    // JSON.stringify drops undefined fields; the server treats missing as default.
+    const clean = JSON.parse(JSON.stringify(args))
+    if (this.transport === 'auto' && this.#ready) return this.#wsCommand(name, clean)
+    return this.#httpCommand(name, clean)
+  }
+
+  /** `POST /api/v1/cmd/<name>`: one route for every command (same as the REST routes). @param {string} name @param {object} args */
+  async #httpCommand(name, args) {
+    let res
+    try {
+      res = await fetch(`${this.url}/api/v1/cmd/${encodeURIComponent(name)}`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${this.key}`, 'content-type': 'application/json' },
+        body: JSON.stringify(args),
+        signal: AbortSignal.timeout(this.timeout_ms),
+      })
+    } catch (e) {
+      throw new LaptimerError(`Laptimer nicht erreichbar (${this.url}): ${e instanceof Error ? e.message : e}`, { command: name, cause: e })
+    }
+    const text = await res.text()
+    /** @type {any} */
+    let body = null
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // not JSON (e.g. a proxy's error page): the text is the message
+    }
+    if (!res.ok) {
+      const message = body?.error ?? (text || `HTTP ${res.status}`)
+      throw new LaptimerError(message, { status: res.status, command: name })
+    }
+    return body
+  }
+
+  /** @param {string} name @param {object} args @returns {Promise<any>} */
+  #wsCommand(name, args) {
+    const id = this.#nextId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id)
+        reject(new LaptimerError(`Keine Antwort auf '${name}' nach ${this.timeout_ms} ms.`, { command: name }))
+      }, this.timeout_ms)
+      this.#pending.set(id, { resolve, reject, timer, cmd: name })
+      this.#ws?.send(JSON.stringify({ id, cmd: name, args }))
+    })
+  }
+
+  // --- events ---
+
+  /**
+   * Listens to an event (`pilot_pass`, …), to `'*'` (every server event) or
+   * to `hello`, `lagged`, `disconnected`. The listener gets `data` and the
+   * whole message. Returns a function that removes the listener.
+   * @template {string} K
+   * @param {K} name
+   * @param {Listener<K>} fn
+   * @returns {() => void}
+   */
+  on(name, fn) {
+    let set = this.#listeners.get(name)
+    if (!set) this.#listeners.set(name, (set = new Set()))
+    set.add(fn)
+    return () => this.off(name, fn)
+  }
+
+  /** @template {string} K @param {K} name @param {Listener<K>} fn */
+  off(name, fn) {
+    this.#listeners.get(name)?.delete(fn)
+  }
+
+  /**
+   * Waits for the next event `name` for which `filter` is true (or for any,
+   * without a filter); resolves with its data. Rejects after `timeout_ms`.
+   * Needs a connected WebSocket (`connect()`).
+   * @template {string} K
+   * @param {K} name
+   * @param {{filter?: (data: K extends keyof ClientEvents ? ClientEvents[K] : any) => boolean, timeout_ms?: number}} [options]
+   * @returns {Promise<K extends keyof ClientEvents ? ClientEvents[K] : any>}
+   */
+  waitFor(name, { filter, timeout_ms = 30000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off()
+        reject(new LaptimerError(`Event '${name}' kam nicht innerhalb von ${timeout_ms} ms.`))
+      }, timeout_ms)
+      const off = this.on(name, (data) => {
+        if (filter && !filter(data)) return
+        clearTimeout(timer)
+        off()
+        resolve(data)
+      })
+    })
+  }
+
+  /** @param {string} name @param {unknown} data @param {unknown} msg */
+  #emit(name, data, msg) {
+    for (const fn of [...(this.#listeners.get(name) ?? [])]) {
+      try {
+        fn(data, msg)
+      } catch (e) {
+        // One broken listener must not stop the others or the connection.
+        console.error(`laptimer: Fehler im Listener für '${name}':`, e)
+      }
+    }
+  }
+
+  // --- WebSocket ---
+
+  /**
+   * Opens the WebSocket; resolves with the `hello` (contains `state`).
+   * Once connected, a dropped connection is opened again by itself (waiting
+   * 0.5 s, 1 s, 2 s, … up to `max_backoff_ms`) until `close()`. If the very
+   * first attempt fails (wrong address or key), the promise rejects and
+   * nothing is retried.
+   * @returns {Promise<Hello>}
+   */
+  connect() {
+    if (this.#connecting) return this.#connecting
+    this.#wanted = true
+    this.#connecting = this.#open(true)
+    return this.#connecting
+  }
+
+  /** Closes the WebSocket for good (no reconnect). Commands go over HTTP again. */
+  close() {
+    this.#wanted = false
+    this.#connecting = null
+    if (this.#retryTimer) clearTimeout(this.#retryTimer)
+    this.#retryTimer = null
+    this.#ws?.close()
+  }
+
+  /** @param {boolean} first  the first attempt of connect() @returns {Promise<Hello>} */
+  #open(first) {
+    return new Promise((resolve, reject) => {
+      // Browsers can't set headers on a WebSocket: the key goes into the query.
+      const wsUrl = this.url.replace(/^http/, 'ws') + `/api/v1/ws?key=${encodeURIComponent(this.key)}`
+      const ws = new WebSocket(wsUrl)
+      this.#ws = ws
+      let gotHello = false
+
+      ws.addEventListener('message', (ev) => {
+        /** @type {any} */
+        let msg
+        try {
+          msg = JSON.parse(String(ev.data))
+        } catch {
+          return
+        }
+        if (msg.type === 'hello') {
+          gotHello = true
+          this.#ready = true
+          this.#attempt = 0
+          resolve(msg)
+          this.#emit('hello', msg, msg)
+        } else if (msg.type === 'event') {
+          this.#emit(msg.event, msg.data, msg)
+          this.#emit('*', msg.data, msg)
+        } else if (msg.type === 'reply') {
+          const p = this.#pending.get(msg.id)
+          if (!p) return
+          this.#pending.delete(msg.id)
+          clearTimeout(p.timer)
+          if (msg.ok) p.resolve(msg.data)
+          else p.reject(new LaptimerError(msg.error, { status: msg.status ?? null, command: p.cmd }))
+        } else if (msg.type === 'lagged') {
+          this.#emit('lagged', { missed: msg.missed }, msg)
+        }
+      })
+
+      ws.addEventListener('close', (ev) => {
+        if (this.#ws !== ws) return // an old socket
+        this.#ws = null
+        this.#ready = false
+        for (const [id, p] of this.#pending) {
+          clearTimeout(p.timer)
+          p.reject(new LaptimerError(`Verbindung getrennt, bevor '${p.cmd}' beantwortet wurde.`, { command: p.cmd }))
+          this.#pending.delete(id)
+        }
+        if (gotHello) this.#emit('disconnected', { code: ev.code, reason: ev.reason }, null)
+        if (!gotHello && first) {
+          // Never connected: no retry. Ask over HTTP why (401 says "key"), so
+          // the error is the server's own message.
+          this.#wanted = false
+          this.#connecting = null
+          this.ping().then(
+            () => reject(new LaptimerError(`WebSocket ${wsUrl.replace(/key=[^&]*/, 'key=…')} ließ sich nicht öffnen.`)),
+            (e) => reject(e),
+          )
+          return
+        }
+        if (this.#wanted) this.#scheduleReconnect()
+      })
+      // 'error' is always followed by 'close', which handles it.
+      ws.addEventListener('error', () => {})
+    })
+  }
+
+  #scheduleReconnect() {
+    const delay = Math.min(500 * 2 ** this.#attempt, this.max_backoff_ms)
+    this.#attempt++
+    this.#retryTimer = setTimeout(() => {
+      this.#retryTimer = null
+      if (!this.#wanted) return
+      // Failed attempts end in 'close' again and come back here.
+      this.#open(false).catch(() => {})
+    }, delay)
+  }
+}