fireboard-api-client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 premium-bonds-client contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# Fireboard API Client
 
-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.
+An unofficial TypeScript client for the [Fireboard](https://fireboard.io) temperature monitoring API. Read devices, temperatures, and cook sessions, or control a Drive fan with typed methods.
+
+Requires Node.js 22 or newer. ESM only.
+
+## Quick start
+
+```sh
+npm install fireboard-api-client
+```
+
+Obtain an API token with `login`:
+
+```typescript
+import { FireboardClient, login } from "fireboard-api-client";
+
+const token = await login({
+  username: process.env.FIREBOARD_USERNAME!,
+  password: process.env.FIREBOARD_PASSWORD!,
+});
+
+const fireboard = new FireboardClient({ token });
+const devices = await fireboard.getDevices();
+
+for (const device of devices) {
+  console.log(device.uuid, device.title, device.channels);
+}
+```
+
+If you already have a token, pass it directly to `new FireboardClient({ token })`. Reuse one client per account: device lists are cached for two minutes by default. The client supplies Fireboard’s required User-Agent header and does not store login credentials.
+
+API reference: [Fireboard API](https://docs.fireboard.io/app/app-api/).
+
+## Methods
+
+Read and write methods are called on `FireboardClient`. `login` is a standalone function. Read methods return promises of the listed types.
+
+### Read methods
+
+| Method                                      | What it does                                                                    | Returns                 |
+| ------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------- |
+| `getDevices()`                              | Lists the account’s devices with channels, temperatures, and available metadata | `RawDevice[]`           |
+| `getDevicesWithCache()`                     | Lists devices with cache freshness metadata                                     | `DeviceListResult`      |
+| `getDevice(deviceUuid)`                     | Retrieves detailed information for one device                                   | `RawDevice`             |
+| `getDeviceTemperatures(deviceUuid)`         | Retrieves the latest available readings                                         | `RawDeviceTemperatures` |
+| `getDriveLog(deviceUuid)`                   | Retrieves a recent Drive log or an empty object                                 | `RawDriveLogResponse`   |
+| `getSessions()`                             | Lists current and historical account sessions                                   | `RawSessionSummary[]`   |
+| `getSessionDetail(sessionId)`               | Retrieves a session’s metadata, devices, and available notes                    | `RawSessionDetail`      |
+| `getSessionChart(sessionId, includeDrive?)` | Retrieves temperature time-series, optionally including Drive data              | `RawChartChannel[]`     |
+
+### Write methods
+
+| Method                                  | What it changes                                         |
+| --------------------------------------- | ------------------------------------------------------- |
+| `setDriveSetpoint(deviceUuid, options)` | Auto-mode temperature target and/or PID control channel |
+| `setDriveSpeed(deviceUuid, percent)`    | Manual fan speed, from 0 to 100 percent                 |
+| `setDriveOff(deviceUuid)`               | Clears the target and stops the fan                     |
+
+Writes return `Promise<void>` and are never automatically retried. Drive control uses a write API absent from Fireboard’s public reference.
+
+### `login(credentials, options?)`
+
+Pass `{ username, password }`; `username` can be a Fireboard username or email address. Returns the API token.
+
+Options are `loginUrl`, `timeoutMs`, `fetch`, and `userAgent`. Store the returned token in your application if needed.
+
+### `getDevices()`
+
+Returns an array of devices, cached for two minutes by default. Pass a device’s `uuid`, not its numeric `id`, to device reads and Drive controls.
+
+### `getDevicesWithCache()`
+
+Returns `{ data, fromCache, cacheAgeSeconds }`, where `data` is `RawDevice[]`. Shares the cache with `getDevices()`. Newly fetched responses have `fromCache: false` and age `0`; cached responses report their rounded age in seconds. This age describes the cached response, not the readings within it.
+
+### `getDevice(deviceUuid)`
+
+Returns the device and its available channel metadata without using the device-list cache.
+
+### `getDeviceTemperatures(deviceUuid)`
+
+Retrieves the latest available channel temperatures. Fireboard documents a one-minute freshness cutoff, but live checks returned older data after power-off. Check reading timestamps before treating values as current.
+
+Fireboard does not document this response’s JSON shape. `RawDeviceTemperatures` preserves the returned JSON; narrow the result before accessing its fields.
+
+### `getDriveLog(deviceUuid)`
+
+Returns a recent Drive log with `driveper`, `setpoint`, `modetype`, `tiedchannel`, `degreetype`, and `created` fields, or `{}` when no recent log is available.
+
+Check for an empty object before accessing log fields. Incomplete non-empty logs and other response shapes raise `INVALID_RESPONSE`.
+
+```typescript
+const drive = await fireboard.getDriveLog("your-device-uuid");
+
+if (Object.keys(drive).length === 0) {
+  console.log("No recent Drive data");
+}
+```
+
+### `getSessions()`
+
+Returns account session summaries. Ordering is not guaranteed; sort or filter results as needed.
+
+Use each summary’s numeric `id` for session-detail and chart requests. `device_ids` is optional.
+
+### `getSessionDetail(sessionId)`
+
+Pass a non-negative integer session ID. Returns metadata, linked devices, and cook notes; omitted notes become `[]`.
+
+### `getSessionChart(sessionId, includeDrive = false)`
+
+Returns an array of channel series. Each includes `x` Unix timestamps in seconds, `y` temperature values or Drive percentages, `device`, `label`, and `degreetype`. `channel_id` is optional; numeric identifiers become strings.
+
+```typescript
+const temperatures = await fireboard.getSessionChart(42);
+const temperaturesAndDrive = await fireboard.getSessionChart(42, true);
+```
+
+### `setDriveSetpoint(deviceUuid, options)`
+
+Pass a finite numeric `setpoint`, a positive integer `channel`, or both. At least one is required, and all arguments are validated before any write is sent.
+
+```typescript
+await fireboard.setDriveSetpoint("your-device-uuid", { setpoint: 110 });
+await fireboard.setDriveSetpoint("your-device-uuid", { channel: 2 });
+await fireboard.setDriveSetpoint("your-device-uuid", { setpoint: 110, channel: 2 });
+```
+
+A setpoint switches Drive to automatic control. Its temperature must use the device’s configured unit; the client does not convert Celsius/Fahrenheit. A channel-only call changes the PID control probe without setting a new target.
+
+Changes to the target and control channel are not atomic. If the method fails, one change may already have been applied.
+
+### `setDriveSpeed(deviceUuid, percent)`
+
+Pass a finite percentage between `0` and `100`. This puts Drive in manual mode and overrides the active automatic target.
+
+```typescript
+await fireboard.setDriveSpeed("your-device-uuid", 50);
+```
+
+A value of `0` stops the fan. Use `setDriveOff()` to clear the setpoint as well.
+
+### `setDriveOff(deviceUuid)`
+
+Clears the setpoint by setting it to zero and stops the Drive fan.
+
+```typescript
+await fireboard.setDriveOff("your-device-uuid");
+```
+
+### Response validation
+
+Responses retain Fireboard’s field names and extra fields, including nested fields. Zod validates known fields; extra fields are preserved without individual validation or specific TypeScript types. Missing alerts and notes become empty arrays, and numeric chart `channel_id` values become strings.
+
+Use each reading or chart series’ `degreetype` to interpret temperatures: `1` is Celsius and `2` is Fahrenheit. Device-level unit metadata may differ from the reading’s unit. Channels remain listed when probes are unplugged, but reading fields may be omitted.
+
+The exported TypeScript types describe the client’s validated fields, including observed fields not covered by Fireboard’s public reference.
+
+## Options
+
+`new FireboardClient({ token, baseUrl?, deviceCacheTtlMs?, timeoutMs?, fetch?, userAgent? })`
+
+- `baseUrl`: defaults to `https://fireboard.io/api/v1`.
+- `deviceCacheTtlMs`: device-list cache TTL; defaults to 120,000 ms. Set `0` to disable caching and shared in-flight reads.
+- `timeoutMs`: defaults to 15,000 ms and covers fetching the response body.
+- `fetch`: injectable for testing or custom transports.
+- `userAgent`: optional application identification; defaults to `fireboard-api-client/<version>`.
+
+`login` accepts `loginUrl`, `timeoutMs`, `fetch`, and `userAgent` separately. URL overrides must use HTTP(S), without credentials, query strings, or fragments. Redirects are rejected to avoid forwarding credentials.
+
+## Caching and rate limits
+
+Only `getDevices()` and `getDevicesWithCache()` are cached. Each client has its own cache, and concurrent cache misses share a request. The TTL starts when a valid response arrives; failures are never cached. Returned data is copied so caller mutations do not affect the cache.
+
+Other reads and all writes are uncached. Writes do not invalidate cached device data. Nested temperature and Drive readings can remain stale until expiry; use `deviceCacheTtlMs: 0` for fresh device-list reads.
+
+The client does not schedule requests or retry failures. Consuming applications remain responsible for rate-limit mitigation.
+
+Fireboard limits each user to **17 API calls within any five-minute period**. After a rate-limit error, pause requests: continued calls can extend the block. Access generally resumes after approximately five minutes, once the request rate falls below the threshold.
+
+## Errors
+
+API and transport failures throw `FireboardError`, with a `code` and an optional HTTP `status`. Invalid arguments throw `TypeError`.
+
+| Code               | Meaning                                                                 |
+| ------------------ | ----------------------------------------------------------------------- |
+| `AUTHENTICATION`   | Fireboard rejected the token or login credentials                       |
+| `RATE_LIMIT`       | Fireboard returned HTTP 429; stop making requests until access recovers |
+| `API_UNAVAILABLE`  | Fireboard returned another unsuccessful HTTP response                   |
+| `INVALID_RESPONSE` | Response JSON could not be parsed or did not match the expected model   |
+| `TIMEOUT`          | The request or response-body read exceeded `timeoutMs`                  |
+| `NETWORK`          | The transport failed, including rejected redirects                      |
+
+```typescript
+import { FireboardError } from "fireboard-api-client";
+
+try {
+  await fireboard.getSessions();
+} catch (error) {
+  if (error instanceof FireboardError) {
+    console.error(error.code, error.status, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+Errors omit response bodies and credentials.
+
+## Other public exports
+
+All public exports are imported from `"fireboard-api-client"`; no internal file paths are needed.
+
+### TypeScript types
+
+| Type                     | Describes                                                              |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `FireboardClientOptions` | Constructor options, including the required token                      |
+| `RequestOptions`         | Shared transport options: `fetch`, `timeoutMs`, and `userAgent`        |
+| `LoginOptions`           | Login transport options and optional `loginUrl`                        |
+| `DeviceListResult`       | Device-list data and cache freshness metadata                          |
+| `DriveSetpointOptions`   | A setpoint, a control channel, or both for `setDriveSetpoint`          |
+| `FireboardErrorCode`     | The union of error codes listed above                                  |
+| `RawDevice`              | One parsed device and its available metadata/channels                  |
+| `RawDeviceTemperatures`  | JSON returned by the temperature read, without an assumed field schema |
+| `RawAlert`               | An observed channel-alert model                                        |
+| `RawDriveLogResponse`    | A populated `RawDriveLog` or an empty object                           |
+| `RawDriveLog`            | An observed Drive-log model                                            |
+| `RawSessionSummary`      | A session-list entry                                                   |
+| `RawSessionDetail`       | Detailed session metadata, devices, and notes                          |
+| `RawChartChannel`        | One channel’s chart series                                             |
+
+### Default constants
+
+| Constant                      | Value                                       |
+| ----------------------------- | ------------------------------------------- |
+| `DEFAULT_BASE_URL`            | `https://fireboard.io/api/v1`               |
+| `DEFAULT_LOGIN_URL`           | `https://fireboard.io/api/rest-auth/login/` |
+| `DEFAULT_DEVICE_CACHE_TTL_MS` | `120_000`                                   |
+| `DEFAULT_TIMEOUT_MS`          | `15_000`                                    |
+
+### Zod validators
+
+The client already validates responses. These exports are also available if you need to validate saved or externally fetched data:
+
+| Validator                          | Accepts                                                 |
+| ---------------------------------- | ------------------------------------------------------- |
+| `deviceSchema`                     | One device                                              |
+| `devicesResponseSchema`            | An array of devices                                     |
+| `deviceTemperaturesResponseSchema` | JSON temperature data without an assumed response shape |
+| `driveLogResponseSchema`           | A populated Drive log or an empty object                |
+| `sessionsResponseSchema`           | An array of session summaries                           |
+| `sessionDetailSchema`              | One detailed session                                    |
+| `chartChannelSchema`               | One chart channel                                       |
+| `chartResponseSchema`              | An array of chart channels                              |
+
+```typescript
+import { devicesResponseSchema } from "fireboard-api-client";
+
+const devices = devicesResponseSchema.parse(savedDeviceData);
+```
+
+## Development and releases
+
+```sh
+npm ci
+npm run typecheck
+npm run lint
+npm run format:check
+npm test
+npm run smoke
+npm pack
+```
+
+The package contains compiled JavaScript and declaration files under `dist/`. `prepack` builds these automatically. Tests and smoke checks use synthetic responses and make no Fireboard account calls.
+
+No Fireboard credentials are needed for local tests or CI. Release configuration is maintained in `.github/workflows/`.

package/dist/client.d.ts

@@ -0,0 +1,198 @@
+import type { z } from "zod";
+import type { DeviceListResult, DriveSetpointOptions, FireboardClientOptions } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://fireboard.io/api/v1";
+export declare class FireboardClient {
+    #private;
+    private readonly baseUrl;
+    private readonly drive;
+    private readonly deviceCache;
+    constructor(options: FireboardClientOptions);
+    private get;
+    /** Lists account devices using the per-client device cache. */
+    getDevices(): Promise<{
+        [x: string]: unknown;
+        uuid: string;
+        id: number;
+        title: string;
+        channels: {
+            [x: string]: unknown;
+            id: number;
+            channel: number;
+            channel_label: string;
+            enabled: boolean;
+            alerts: {
+                [x: string]: unknown;
+                id: number;
+                temp_min: number;
+                temp_max: number;
+                notify_app: boolean;
+                notify_email: boolean;
+                notify_sms: boolean;
+                time_start: string;
+                time_stop: string;
+                minutes_buffer: number;
+                minutes_repeat: number;
+                enabled: boolean;
+                created: string;
+                channel: number;
+                device_id: number;
+                session_id: number;
+            }[];
+            current_temp?: number | undefined;
+            degreetype?: number | null | undefined;
+            last_templog?: {
+                [x: string]: unknown;
+                temp: number;
+                created: string;
+                degreetype?: number | null | undefined;
+            } | null | undefined;
+        }[];
+        channel_count?: number | undefined;
+        last_drivelog?: {
+            [x: string]: unknown;
+            driveper: number;
+            setpoint: number;
+            modetype: string | number;
+            tiedchannel: number;
+            degreetype: number;
+            created: string;
+        } | null | undefined;
+        active?: boolean | undefined;
+        last_battery_reading?: number | null | undefined;
+        model_name?: string | undefined;
+        created?: string | undefined;
+        hardware_id?: string | undefined;
+        latest_temps?: unknown[] | undefined;
+        device_log?: Record<string, unknown> | null | undefined;
+        last_templog?: string | null | undefined;
+    }[]>;
+    /** Lists devices with cache freshness metadata. */
+    getDevicesWithCache(): Promise<DeviceListResult>;
+    /** Retrieves one device and its available metadata. */
+    getDevice(uuid: string): Promise<{
+        [x: string]: unknown;
+        uuid: string;
+        id: number;
+        title: string;
+        channels: {
+            [x: string]: unknown;
+            id: number;
+            channel: number;
+            channel_label: string;
+            enabled: boolean;
+            alerts: {
+                [x: string]: unknown;
+                id: number;
+                temp_min: number;
+                temp_max: number;
+                notify_app: boolean;
+                notify_email: boolean;
+                notify_sms: boolean;
+                time_start: string;
+                time_stop: string;
+                minutes_buffer: number;
+                minutes_repeat: number;
+                enabled: boolean;
+                created: string;
+                channel: number;
+                device_id: number;
+                session_id: number;
+            }[];
+            current_temp?: number | undefined;
+            degreetype?: number | null | undefined;
+            last_templog?: {
+                [x: string]: unknown;
+                temp: number;
+                created: string;
+                degreetype?: number | null | undefined;
+            } | null | undefined;
+        }[];
+        channel_count?: number | undefined;
+        last_drivelog?: {
+            [x: string]: unknown;
+            driveper: number;
+            setpoint: number;
+            modetype: string | number;
+            tiedchannel: number;
+            degreetype: number;
+            created: string;
+        } | null | undefined;
+        active?: boolean | undefined;
+        last_battery_reading?: number | null | undefined;
+        model_name?: string | undefined;
+        created?: string | undefined;
+        hardware_id?: string | undefined;
+        latest_temps?: unknown[] | undefined;
+        device_log?: Record<string, unknown> | null | undefined;
+        last_templog?: string | null | undefined;
+    }>;
+    /** Retrieves recent temperatures; the official reference does not define their JSON fields. */
+    getDeviceTemperatures(uuid: string): Promise<z.core.util.JSONType>;
+    /** Returns a recent Drive log; Fireboard only returns log data less than a minute old. */
+    getDriveLog(uuid: string): Promise<{
+        [x: string]: unknown;
+        driveper: number;
+        setpoint: number;
+        modetype: string | number;
+        tiedchannel: number;
+        degreetype: number;
+        created: string;
+    } | Record<string, never>>;
+    /** Lists account sessions; the API does not document their ordering. */
+    getSessions(): Promise<{
+        [x: string]: unknown;
+        id: number;
+        title: string;
+        description: string;
+        start_time: string;
+        end_time: string | null;
+        device_ids?: string[] | undefined;
+        devices?: unknown[] | undefined;
+        duration?: string | undefined;
+        created?: string | undefined;
+        owner?: Record<string, unknown> | undefined;
+    }[]>;
+    getSessionDetail(id: number): Promise<{
+        [x: string]: unknown;
+        id: number;
+        title: string;
+        description: string;
+        start_time: string;
+        end_time: string | null;
+        devices: {
+            [x: string]: unknown;
+            uuid: string;
+            title: string;
+            channels: {
+                [x: string]: unknown;
+                channel_label: string;
+                channel: number;
+            }[];
+        }[];
+        notes: {
+            [x: string]: unknown;
+            note_time: string;
+            note_text: string;
+            channel: number | null;
+            device: string;
+        }[];
+        duration?: string | undefined;
+        created?: string | undefined;
+        owner?: Record<string, unknown> | undefined;
+    }>;
+    getSessionChart(id: number, includeDrive?: boolean): Promise<{
+        [x: string]: unknown;
+        device: string;
+        label: string;
+        degreetype: number;
+        x: number[];
+        y: number[];
+        channel_id?: string | undefined;
+    }[]>;
+    /** Sets an auto-mode target in the device's temperature unit and/or its control channel. */
+    setDriveSetpoint(uuid: string, options: DriveSetpointOptions): Promise<void>;
+    /** Sets a manual fan speed from 0 to 100 percent. */
+    setDriveSpeed(uuid: string, percent: number): Promise<void>;
+    /** Clears the setpoint and turns the Drive fan off. */
+    setDriveOff(uuid: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,68 @@
+import { DeviceCache, DEFAULT_DEVICE_CACHE_TTL_MS } from "./device-cache.js";
+import { DriveControls } from "./drive.js";
+import { decode, headers, request, DEFAULT_TIMEOUT_MS } from "./request.js";
+import { chartResponseSchema, devicesResponseSchema, deviceSchema, deviceTemperaturesResponseSchema, driveLogResponseSchema, sessionDetailSchema, sessionsResponseSchema, } from "./schemas.js";
+import { encodeDeviceId, validateEndpoint, validateSessionId, validateTiming, } from "./validation.js";
+export const DEFAULT_BASE_URL = "https://fireboard.io/api/v1";
+export class FireboardClient {
+    #options;
+    baseUrl;
+    drive;
+    deviceCache;
+    constructor(options) {
+        if (typeof options?.token !== "string" || !options.token.trim()) {
+            throw new TypeError("Fireboard token is required");
+        }
+        validateTiming(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, "timeoutMs");
+        this.deviceCache = new DeviceCache(validateTiming(options.deviceCacheTtlMs ?? DEFAULT_DEVICE_CACHE_TTL_MS, "deviceCacheTtlMs", true));
+        this.baseUrl = validateEndpoint(options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.#options = { ...options };
+        this.drive = new DriveControls(this.baseUrl, this.#options);
+    }
+    async get(path, schema) {
+        const response = await request(`${this.baseUrl}${path}`, { headers: headers(this.#options, this.#options.token) }, this.#options);
+        return decode(response, schema);
+    }
+    /** Lists account devices using the per-client device cache. */
+    async getDevices() {
+        return (await this.getDevicesWithCache()).data;
+    }
+    /** Lists devices with cache freshness metadata. */
+    getDevicesWithCache() {
+        return this.deviceCache.get(() => this.get("/devices.json", devicesResponseSchema));
+    }
+    /** Retrieves one device and its available metadata. */
+    getDevice(uuid) {
+        return this.get(`/devices/${encodeDeviceId(uuid)}.json`, deviceSchema);
+    }
+    /** Retrieves recent temperatures; the official reference does not define their JSON fields. */
+    getDeviceTemperatures(uuid) {
+        return this.get(`/devices/${encodeDeviceId(uuid)}/temps.json`, deviceTemperaturesResponseSchema);
+    }
+    /** Returns a recent Drive log; Fireboard only returns log data less than a minute old. */
+    getDriveLog(uuid) {
+        return this.get(`/devices/${encodeDeviceId(uuid)}/drivelog.json`, driveLogResponseSchema);
+    }
+    /** Lists account sessions; the API does not document their ordering. */
+    getSessions() {
+        return this.get("/sessions.json", sessionsResponseSchema);
+    }
+    getSessionDetail(id) {
+        return this.get(`/sessions/${validateSessionId(id)}.json`, sessionDetailSchema);
+    }
+    getSessionChart(id, includeDrive = false) {
+        return this.get(`/sessions/${validateSessionId(id)}/chart.json${includeDrive ? "?drive=1" : ""}`, chartResponseSchema);
+    }
+    /** Sets an auto-mode target in the device's temperature unit and/or its control channel. */
+    setDriveSetpoint(uuid, options) {
+        return this.drive.setSetpoint(uuid, options);
+    }
+    /** Sets a manual fan speed from 0 to 100 percent. */
+    setDriveSpeed(uuid, percent) {
+        return this.drive.setSpeed(uuid, percent);
+    }
+    /** Clears the setpoint and turns the Drive fan off. */
+    setDriveOff(uuid) {
+        return this.drive.off(uuid);
+    }
+}

package/dist/device-cache.d.ts

@@ -0,0 +1,11 @@
+import type { RawDevice } from "./schemas.js";
+import type { DeviceListResult } from "./types.js";
+export declare const DEFAULT_DEVICE_CACHE_TTL_MS = 120000;
+export declare class DeviceCache {
+    private readonly ttlMs;
+    private cached;
+    private pending;
+    constructor(ttlMs: number);
+    get(load: () => Promise<RawDevice[]>): Promise<DeviceListResult>;
+    private fetch;
+}

package/dist/device-cache.js

@@ -0,0 +1,40 @@
+export const DEFAULT_DEVICE_CACHE_TTL_MS = 120_000;
+export class DeviceCache {
+    ttlMs;
+    cached;
+    pending;
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    async get(load) {
+        if (this.ttlMs === 0) {
+            return { data: await load(), fromCache: false, cacheAgeSeconds: 0 };
+        }
+        const now = Date.now();
+        if (this.cached && now - this.cached.fetchedAt < this.ttlMs) {
+            return {
+                data: structuredClone(this.cached.data),
+                fromCache: true,
+                cacheAgeSeconds: Math.round((now - this.cached.fetchedAt) / 1000),
+            };
+        }
+        if (!this.pending) {
+            this.pending = this.fetch(load);
+        }
+        const pending = this.pending;
+        try {
+            const result = await pending;
+            return { ...result, data: structuredClone(result.data) };
+        }
+        finally {
+            if (this.pending === pending) {
+                this.pending = undefined;
+            }
+        }
+    }
+    async fetch(load) {
+        const data = await load();
+        this.cached = { data, fetchedAt: Date.now() };
+        return { data, fromCache: false, cacheAgeSeconds: 0 };
+    }
+}

package/dist/drive.d.ts

@@ -0,0 +1,10 @@
+import type { DriveSetpointOptions, FireboardClientOptions } from "./types.js";
+export declare class DriveControls {
+    #private;
+    private readonly baseUrl;
+    constructor(baseUrl: string, options: FireboardClientOptions);
+    private send;
+    setSetpoint(uuid: string, options: DriveSetpointOptions): Promise<void>;
+    setSpeed(uuid: string, percent: number): Promise<void>;
+    off(uuid: string): Promise<void>;
+}