fpv-laptimer-client 0.0.0-stage → 0.0.2

package/src/types.js

@@ -0,0 +1,276 @@
+// @ts-check
+// The JSON the server sends (the laptimer's docs/api/datenformate.md and events.md).
+// Only typedefs: this file exports nothing at runtime.
+
+/**
+ * A channel (a seat on the page: slot 1 = index 0).
+ * @typedef {object} Channel
+ * @property {number} index         0, 1, …
+ * @property {string} name          "R1" … "R8" or the MHz as text
+ * @property {number} mhz
+ * @property {boolean} enabled      false: does not fly along
+ * @property {number | null} pilot_id
+ * @property {string | null} pilot  callsign of the assigned pilot
+ * @property {string} label         free text instead of a pilot (wins over `pilot`)
+ * @property {string} shown         what the page shows
+ */
+
+/**
+ * @typedef {object} Pilot
+ * @property {number} id
+ * @property {string} name        callsign (unique)
+ * @property {string} full_name   may be empty
+ */
+
+/**
+ * One seat's result in a session (`results`, in seat order).
+ * @typedef {object} SeatResult
+ * @property {number} channel
+ * @property {string} channel_name
+ * @property {number} mhz
+ * @property {number | null} pilot_id
+ * @property {string} pilot              shown name: callsign, free text or channel name
+ * @property {number | null} position    null without a lap
+ * @property {number} laps
+ * @property {number[]} lap_times_us
+ * @property {number | null} last_lap_us
+ * @property {number | null} best_lap_us
+ * @property {number | null} best_consecutive_us
+ * @property {number | null} total_us
+ * @property {number | null} holeshot_us
+ * @property {boolean} finished
+ */
+
+/**
+ * A pass through the gate (only in `sessions.get`).
+ * @typedef {object} Pass
+ * @property {number} id
+ * @property {number} channel
+ * @property {number} time_us
+ * @property {number} peak_db
+ * @property {boolean} manual    added by hand
+ * @property {boolean} deleted
+ * @property {number} gate        0 = finish, 1 = arming gate
+ * @property {'no_arming' | null} [rejected]   deleted by the server, and why
+ * @property {number | null} [detected_us]   where the detector put it (null: added by hand; differs from time_us: moved by hand)
+ */
+
+/**
+ * A correction of a pass (only in `sessions.get`, as `changes`).
+ * @typedef {object} PassChange
+ * @property {number | null} pass_id
+ * @property {number} channel
+ * @property {'add' | 'delete' | 'restore' | 'move' | 'reject'} action
+ * @property {number | null} from_us
+ * @property {number | null} to_us
+ * @property {string | null} rejected
+ * @property {boolean} live      while the session ran
+ * @property {'seite' | 'editor' | 'api' | 'server'} origin
+ * @property {number} at_us
+ */
+
+/** @typedef {'holeshot' | 'from_start' | 'flying'} StartMode */
+
+/**
+ * @typedef {object} Session
+ * @property {number} id
+ * @property {boolean} race                  false = training
+ * @property {'countdown' | 'running' | 'ended'} phase
+ * @property {StartMode} start_mode
+ * @property {'open' | 'laps' | 'seconds'} end
+ * @property {number | null} end_value
+ * @property {number} countdown_s
+ * @property {number} min_lap_s
+ * @property {number} created_us
+ * @property {number} start_us
+ * @property {number | null} ended_us
+ * @property {number | null} confirmed_us
+ * @property {boolean} needs_confirmation
+ * @property {SeatResult[]} results
+ * @property {Pass[]} [passes]               only from `sessions.get`
+ * @property {PassChange[]} [changes]        only from `sessions.get`: every correction of a pass
+ */
+
+/**
+ * @typedef {object} Board
+ * @property {string} id
+ * @property {string} port
+ * @property {string} role       finish, arming or off
+ * @property {boolean} ok
+ * @property {string | null} error
+ * @property {number} levels_per_s
+ */
+
+/**
+ * @typedef {object} State
+ * @property {number} now_us
+ * @property {Session | null} session        the running session
+ * @property {Session | null} unconfirmed    the ended race waiting for confirmation
+ * @property {Channel[]} channels
+ * @property {Pilot[]} pilots
+ * @property {Board[]} boards
+ */
+
+/**
+ * @typedef {object} PilotStats
+ * @property {number | null} pilot_id
+ * @property {string} label
+ * @property {number | null} best_lap_us
+ * @property {number | null} best_consecutive_us
+ * @property {number} sessions
+ * @property {number} races
+ * @property {number} wins
+ */
+
+/**
+ * @typedef {object} Stats
+ * @property {number} today_races
+ * @property {PilotStats[]} all     best lap first
+ * @property {PilotStats[]} today
+ */
+
+/**
+ * Arguments of `session.start`.
+ * @typedef {object} StartOptions
+ * @property {boolean} [race]          true: race, false: training (default)
+ * @property {number} [laps]           race: end after this many laps (1–100)
+ * @property {number} [seconds]        race: end after this many seconds (10–3600), instead of laps
+ * @property {number} [countdown_s]    race: 0–60
+ * @property {StartMode} [start_mode]  race
+ */
+
+/**
+ * Arguments of `channels.set` (only given fields change).
+ * @typedef {object} ChannelChange
+ * @property {string | null} [pilot]      callsign, null = nobody
+ * @property {number | null} [pilot_id]   instead of `pilot`
+ * @property {boolean} [create]           make an unknown callsign a pilot
+ * @property {string} [label]             free text instead of a pilot ("" = none)
+ * @property {boolean} [enabled]
+ * @property {string | number} [frequency]  "R1" … "R8" or MHz (5300–6000); not during a session
+ */
+
+// --- events ---
+
+/**
+ * Fields every event about a pilot has ("Sitz" in docs/api/events.md).
+ * @typedef {object} Seat
+ * @property {number} channel
+ * @property {string} channel_name
+ * @property {number} mhz
+ * @property {number | null} pilot_id
+ * @property {string} pilot
+ */
+
+/**
+ * @typedef {object} SessionStartedData
+ * @property {number} session_id
+ * @property {boolean} race
+ * @property {StartMode} start_mode
+ * @property {'open' | 'laps' | 'seconds'} end
+ * @property {number | null} end_value
+ * @property {number} countdown_s
+ * @property {number} created_us
+ * @property {number} start_us
+ * @property {number} pilot_count
+ * @property {Seat[]} seats
+ */
+
+/**
+ * @typedef {object} CountdownData
+ * @property {number} session_id
+ * @property {boolean} race
+ * @property {number} seconds_left
+ */
+
+/**
+ * @typedef {object} StartSignalData
+ * @property {number} session_id
+ * @property {boolean} race
+ * @property {number} start_us
+ */
+
+/**
+ * @typedef {Seat & {
+ *   session_id: number, race: boolean, pass_id: number, time_us: number, manual: boolean,
+ *   kind: 'lap' | 'holeshot' | 'start' | 'ignored',
+ *   lap: number | null, lap_time_us: number | null, lap_time_s: number | null, laps: number,
+ *   best_lap_us: number | null, best_lap_s: number | null, personal_best: boolean, session_best: boolean,
+ *   holeshot_us: number | null, finished: boolean, position: number | null
+ * }} PilotPassData
+ */
+
+/**
+ * @typedef {Seat & {
+ *   session_id: number, laps: number, total_us: number | null, total_s: number | null,
+ *   best_lap_us: number | null, best_lap_s: number | null, position: number | null
+ * }} PilotFinishedData
+ */
+
+/**
+ * @typedef {object} SessionStoppedData
+ * @property {number} session_id
+ * @property {boolean} race
+ * @property {'stopped' | 'finished' | 'cancelled'} reason
+ * @property {number} ended_us
+ * @property {boolean} needs_confirmation
+ * @property {string | null} winner      race only
+ * @property {SeatResult[]} results
+ */
+
+/**
+ * @typedef {object} RaceConfirmedData
+ * @property {number} session_id
+ * @property {boolean} race
+ * @property {number} confirmed_us
+ * @property {string | null} winner
+ * @property {SeatResult[]} results
+ */
+
+/**
+ * @typedef {object} PilotEventData
+ * @property {number} pilot_id
+ * @property {string} name
+ * @property {string} [full_name]   not in pilot_deleted
+ */
+
+/**
+ * Event name → its `data`.
+ * @typedef {object} EventMap
+ * @property {SessionStartedData} session_started
+ * @property {CountdownData} countdown
+ * @property {StartSignalData} start_signal
+ * @property {PilotPassData} pilot_pass
+ * @property {PilotFinishedData} pilot_finished
+ * @property {SessionStoppedData} session_stopped
+ * @property {RaceConfirmedData} race_confirmed
+ * @property {{session_id: number, race: boolean}} session_deleted
+ * @property {{deleted: number}} sessions_reset
+ * @property {{session_id: number}} passes_changed
+ * @property {{channels: Channel[]}} channels_changed
+ * @property {PilotEventData} pilot_added
+ * @property {PilotEventData} pilot_updated
+ * @property {PilotEventData} pilot_deleted
+ */
+
+/**
+ * An event as it comes over the WebSocket.
+ * @template [D=any]
+ * @typedef {object} EventMessage
+ * @property {'event'} type
+ * @property {string} event
+ * @property {number} seq        counts from 1 since the server started; a gap = missed events
+ * @property {number} time_us
+ * @property {D} data
+ */
+
+/**
+ * The first message after connecting.
+ * @typedef {object} Hello
+ * @property {'hello'} type
+ * @property {number} api
+ * @property {State | null} state
+ * @property {string[]} commands
+ */
+
+export {}

package/types/index.d.ts

@@ -0,0 +1,13 @@
+export type Channel = import("./types.js").Channel;
+export type ChannelChange = import("./types.js").ChannelChange;
+export type Pilot = import("./types.js").Pilot;
+export type Session = import("./types.js").Session;
+export type SeatResult = import("./types.js").SeatResult;
+export type Pass = import("./types.js").Pass;
+export type State = import("./types.js").State;
+export type Stats = import("./types.js").Stats;
+export type StartOptions = import("./types.js").StartOptions;
+export type EventMap = import("./types.js").EventMap;
+export type PilotPassData = import("./types.js").PilotPassData;
+export type SessionStoppedData = import("./types.js").SessionStoppedData;
+export { Laptimer, LaptimerError } from "./laptimer.js";

package/types/laptimer.d.ts

@@ -0,0 +1,253 @@
+/** @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: string, { status, command, cause }?: {
+        status?: number | null | undefined;
+        command?: string | undefined;
+        cause?: unknown;
+    });
+    /** @type {number | null} */
+    status: number | null;
+    /** @type {string | undefined} */
+    command: string | undefined;
+}
+/**
+ * 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 {
+    /** @param {LaptimerOptions} options */
+    constructor({ url, key, transport, timeout_ms, max_backoff_ms }: LaptimerOptions);
+    url: string;
+    key: string;
+    transport: "auto" | "http";
+    timeout_ms: number;
+    max_backoff_ms: number;
+    channels: {
+        /** @returns {Promise<Channel[]>} */
+        list: () => Promise<Channel[]>;
+        /**
+         * 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: number, change: ChannelChange) => Promise<Channel>;
+        /**
+         * 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: (string | number | null)[], { create }?: {
+            create?: boolean;
+        }) => Promise<Channel[]>;
+    };
+    pilots: {
+        /** @returns {Promise<Pilot[]>} */
+        list: () => Promise<Pilot[]>;
+        /** @param {number} id @returns {Promise<Pilot>} */
+        get: (id: number) => Promise<Pilot>;
+        /** @param {string} name callsign @param {string} [full_name] @returns {Promise<Pilot>} */
+        create: (name: string, full_name?: string) => Promise<Pilot>;
+        /** @param {number} id @param {{name?: string, full_name?: string}} change @returns {Promise<Pilot>} */
+        update: (id: number, change: {
+            name?: string;
+            full_name?: string;
+        }) => Promise<Pilot>;
+        /** @param {number} id @returns {Promise<{}>} */
+        delete: (id: number) => Promise<{}>;
+    };
+    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?: StartOptions) => Promise<Session>;
+        /** @returns {Promise<{session_id: number}>} */
+        stop: () => Promise<{
+            session_id: number;
+        }>;
+        /** Stops and deletes the running session. @returns {Promise<{session_id: number}>} */
+        cancel: () => Promise<{
+            session_id: number;
+        }>;
+        /** @param {number} [id] default: the race waiting for confirmation @returns {Promise<{session_id: number}>} */
+        confirm: (id?: number) => Promise<{
+            session_id: number;
+        }>;
+        /** Deletes an ended session. @param {number} [id] default: the race waiting for confirmation @returns {Promise<{session_id: number}>} */
+        discard: (id?: number) => Promise<{
+            session_id: number;
+        }>;
+    };
+    sessions: {
+        /** @param {{limit?: number}} [options] default 20 @returns {Promise<Session[]>} */
+        list: ({ limit }?: {
+            limit?: number;
+        }) => Promise<Session[]>;
+        /** With every pass (`passes`). @param {number} id @returns {Promise<Session>} */
+        get: (id: number) => Promise<Session>;
+    };
+    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: number, { time_us, session_id }?: {
+            time_us?: number;
+            session_id?: number;
+        }) => Promise<{
+            pass_id: number;
+            session_id: number;
+            time_us: number;
+        }>;
+        /** Detected passes are only marked (restorable). @param {number} id @returns {Promise<{session_id: number}>} */
+        delete: (id: number) => Promise<{
+            session_id: number;
+        }>;
+        /** @param {number} id @returns {Promise<{session_id: number}>} */
+        restore: (id: number) => Promise<{
+            session_id: number;
+        }>;
+    };
+    /** @returns {Promise<{pong: true, now_us: number}>} */
+    ping(): Promise<{
+        pong: true;
+        now_us: number;
+    }>;
+    /** @returns {Promise<State>} */
+    state(): Promise<State>;
+    /** @returns {Promise<Stats>} */
+    stats(): Promise<Stats>;
+    /** True while the WebSocket is connected (and commands go over it with transport "auto"). */
+    get connected(): boolean;
+    /**
+     * 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: string, args?: Record<string, unknown>): Promise<any>;
+    /**
+     * 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<K extends string>(name: K, fn: Listener<K>): () => void;
+    /** @template {string} K @param {K} name @param {Listener<K>} fn */
+    off<K extends string>(name: K, fn: Listener<K>): void;
+    /**
+     * 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<K extends string>(name: K, { filter, timeout_ms }?: {
+        filter?: (data: K extends keyof ClientEvents ? ClientEvents[K] : any) => boolean;
+        timeout_ms?: number;
+    }): Promise<K extends keyof ClientEvents ? ClientEvents[K] : any>;
+    /**
+     * 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(): Promise<Hello>;
+    /** Closes the WebSocket for good (no reconnect). Commands go over HTTP again. */
+    close(): void;
+    #private;
+}
+/**
+ * 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`.
+ */
+export type ClientEvents = EventMap & {
+    "*": any;
+    hello: Hello;
+    lagged: {
+        missed: number;
+    };
+    disconnected: {
+        code: number;
+        reason: string;
+    };
+};
+export type Listener<K extends string> = (data: K extends keyof ClientEvents ? ClientEvents[K] : any, msg: EventMessage<any> | any) => void;
+export type LaptimerOptions = {
+    /**
+     * e.g. "http://pi:5800"
+     */
+    url: string;
+    /**
+     * API key "lt_…"
+     */
+    key: string;
+    /**
+     * auto (default): commands over the WebSocket while it is connected, else HTTP
+     */
+    transport?: "auto" | "http" | undefined;
+    /**
+     * per command, default 15000
+     */
+    timeout_ms?: number | undefined;
+    /**
+     * longest wait between reconnects, default 10000
+     */
+    max_backoff_ms?: number | undefined;
+};
+import type { Channel } from './types.js';
+import type { ChannelChange } from './types.js';
+import type { Pilot } from './types.js';
+import type { StartOptions } from './types.js';
+import type { Session } from './types.js';
+import type { State } from './types.js';
+import type { Stats } from './types.js';
+import type { Hello } from './types.js';
+import type { EventMap } from './types.js';
+import type { EventMessage } from './types.js';