fireboard-api-client 0.1.0 → 0.2.0

package/README.md

@@ -22,25 +22,29 @@ const token = await login({
 
 const fireboard = new FireboardClient({ token });
 const devices = await fireboard.getDevices();
-const sessions = await fireboard.getSessions();
+
+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. The library supplies Fireboard's required User-Agent header and does not store login credentials.
+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 Cloud API](https://docs.fireboard.io/app/app-api/).
+API reference: [Fireboard API](https://docs.fireboard.io/app/app-api/).
 
 ## Methods
 
-All methods below are called on `FireboardClient`, except the standalone `login` function. Read methods return promises of the listed types.
+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 readings less than one minute old                                     | `RawDeviceTemperatures` |
-| `getDriveLog(deviceUuid)`                   | Retrieves a Drive log less than one minute old                                  | `RawDriveLog`           |
+| `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[]`     |
@@ -63,35 +67,35 @@ Options are `loginUrl`, `timeoutMs`, `fetch`, and `userAgent`. Store the returne
 
 ### `getDevices()`
 
-Returns an array of devices. Reuse their UUIDs in later method calls.
+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.
 
-```typescript
-const devices = await fireboard.getDevices();
-```
+### `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)`
 
-Pass the device’s UUID, not its numeric ID. Returns the device and its available channel metadata.
+Returns the device and its available channel metadata without using the device-list cache.
 
 ### `getDeviceTemperatures(deviceUuid)`
 
-Retrieves the latest channel temperatures for one device. Fireboard includes readings only when they are less than one minute old; older channels are omitted.
-
-```typescript
-const readings = await fireboard.getDeviceTemperatures("your-device-uuid");
-```
+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 containing the observed `driveper`, `setpoint`, `modetype`, `tiedchannel`, `degreetype`, and `created` fields. Pass the device’s UUID.
+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");
-```
 
-Fireboard only returns log data less than one minute old. The client expects a single object; other shapes raise `INVALID_RESPONSE`. Fireboard does not document the empty/stale-log response shape.
+if (Object.keys(drive).length === 0) {
+  console.log("No recent Drive data");
+}
+```
 
 ### `getSessions()`
 
@@ -105,15 +109,13 @@ Pass a non-negative integer session ID. Returns metadata, linked devices, and co
 
 ### `getSessionChart(sessionId, includeDrive = false)`
 
-Returns an array of channel series. Each includes `x` timestamps, `y` temperature values or Drive percentages, `device`, `label`, and `degreetype` (`1` for Celsius, `2` for Fahrenheit). Observed `channel_id` values are optional and numeric identifiers are normalized to strings.
+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);
 ```
 
-Passing `true` includes Drive data.
-
 ### `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.
@@ -136,7 +138,7 @@ Pass a finite percentage between `0` and `100`. This puts Drive in manual mode a
 await fireboard.setDriveSpeed("your-device-uuid", 50);
 ```
 
-A value of `0` stops the fan. Use `setDriveOff` when you want to explicitly clear the setpoint as well.
+A value of `0` stops the fan. Use `setDriveOff()` to clear the setpoint as well.
 
 ### `setDriveOff(deviceUuid)`
 
@@ -148,24 +150,31 @@ await fireboard.setDriveOff("your-device-uuid");
 
 ### Response validation
 
-Responses retain Fireboard’s field names and unknown fields, including nested fields. Zod validates known fields. Channel, alert, note, and Drive-log models include observed fields that Fireboard’s public reference does not fully specify.
+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?, timeoutMs?, fetch?, userAgent? })`
+`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.
 
-## Rate limits
+## 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.
 
-The client does not cache responses, schedule requests, or retry failures. Consuming applications are responsible for caching and rate-limit mitigation.
+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.
 
-Fireboard returns temperature and Drive-log readings only when they are less than one minute old.
+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.
 
@@ -209,11 +218,13 @@ All public exports are imported from `"fireboard-api-client"`; no internal file
 | `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                          |
@@ -221,11 +232,12 @@ All public exports are imported from `"fireboard-api-client"`; no internal file
 
 ### Default constants
 
-| Constant             | Value                                       |
-| -------------------- | ------------------------------------------- |
-| `DEFAULT_BASE_URL`   | `https://fireboard.io/api/v1`               |
-| `DEFAULT_LOGIN_URL`  | `https://fireboard.io/api/rest-auth/login/` |
-| `DEFAULT_TIMEOUT_MS` | `15_000`                                    |
+| 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
 
@@ -236,7 +248,7 @@ The client already validates responses. These exports are also available if you
 | `deviceSchema`                     | One device                                              |
 | `devicesResponseSchema`            | An array of devices                                     |
 | `deviceTemperaturesResponseSchema` | JSON temperature data without an assumed response shape |
-| `driveLogResponseSchema`           | The observed single-object Drive log                    |
+| `driveLogResponseSchema`           | A populated Drive log or an empty object                |
 | `sessionsResponseSchema`           | An array of session summaries                           |
 | `sessionDetailSchema`              | One detailed session                                    |
 | `chartChannelSchema`               | One chart channel                                       |

package/dist/client.d.ts

@@ -1,13 +1,14 @@
 import type { z } from "zod";
-import type { DriveSetpointOptions, FireboardClientOptions } from "./types.js";
+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; every call sends a separate request. */
+    /** Lists account devices using the per-client device cache. */
     getDevices(): Promise<{
         [x: string]: unknown;
         uuid: string;
@@ -57,14 +58,16 @@ export declare class FireboardClient {
             created: string;
         } | null | undefined;
         active?: boolean | undefined;
-        last_battery_reading?: number | 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> | undefined;
-        last_templog?: string | 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;
@@ -115,13 +118,13 @@ export declare class FireboardClient {
             created: string;
         } | null | undefined;
         active?: boolean | undefined;
-        last_battery_reading?: number | 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> | undefined;
-        last_templog?: string | 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>;
@@ -134,7 +137,7 @@ export declare class FireboardClient {
         tiedchannel: number;
         degreetype: number;
         created: string;
-    }>;
+    } | Record<string, never>>;
     /** Lists account sessions; the API does not document their ordering. */
     getSessions(): Promise<{
         [x: string]: unknown;

package/dist/client.js

@@ -1,3 +1,4 @@
+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";
@@ -7,11 +8,13 @@ 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);
@@ -20,9 +23,13 @@ export class FireboardClient {
         const response = await request(`${this.baseUrl}${path}`, { headers: headers(this.#options, this.#options.token) }, this.#options);
         return decode(response, schema);
     }
-    /** Lists account devices; every call sends a separate request. */
-    getDevices() {
-        return this.get("/devices.json", devicesResponseSchema);
+    /** 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) {

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/index.d.ts

@@ -1,7 +1,8 @@
 export { FireboardClient, DEFAULT_BASE_URL } from "./client.js";
+export { DEFAULT_DEVICE_CACHE_TTL_MS } from "./device-cache.js";
 export { login, DEFAULT_LOGIN_URL } from "./login.js";
 export { DEFAULT_TIMEOUT_MS } from "./request.js";
 export { FireboardError } from "./errors.js";
 export type { FireboardErrorCode } from "./errors.js";
-export type { FireboardClientOptions, RequestOptions, LoginOptions, DriveSetpointOptions, } from "./types.js";
+export type { FireboardClientOptions, RequestOptions, LoginOptions, DriveSetpointOptions, DeviceListResult, } from "./types.js";
 export * from "./schemas.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { FireboardClient, DEFAULT_BASE_URL } from "./client.js";
+export { DEFAULT_DEVICE_CACHE_TTL_MS } from "./device-cache.js";
 export { login, DEFAULT_LOGIN_URL } from "./login.js";
 export { DEFAULT_TIMEOUT_MS } from "./request.js";
 export { FireboardError } from "./errors.js";

package/dist/schemas.d.ts

@@ -68,13 +68,13 @@ export declare const deviceSchema: z.ZodObject<{
         created: z.ZodString;
     }, z.core.$loose>>>;
     active: z.ZodOptional<z.ZodBoolean>;
-    last_battery_reading: z.ZodOptional<z.ZodNumber>;
+    last_battery_reading: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     model_name: z.ZodOptional<z.ZodString>;
     created: z.ZodOptional<z.ZodString>;
     hardware_id: z.ZodOptional<z.ZodString>;
     latest_temps: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
-    device_log: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    last_templog: z.ZodOptional<z.ZodString>;
+    device_log: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    last_templog: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 export declare const devicesResponseSchema: z.ZodArray<z.ZodObject<{
     uuid: z.ZodString;
@@ -120,23 +120,23 @@ export declare const devicesResponseSchema: z.ZodArray<z.ZodObject<{
         created: z.ZodString;
     }, z.core.$loose>>>;
     active: z.ZodOptional<z.ZodBoolean>;
-    last_battery_reading: z.ZodOptional<z.ZodNumber>;
+    last_battery_reading: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     model_name: z.ZodOptional<z.ZodString>;
     created: z.ZodOptional<z.ZodString>;
     hardware_id: z.ZodOptional<z.ZodString>;
     latest_temps: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
-    device_log: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    last_templog: z.ZodOptional<z.ZodString>;
+    device_log: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    last_templog: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>>;
 export declare const deviceTemperaturesResponseSchema: z.ZodJSONSchema;
-export declare const driveLogResponseSchema: z.ZodObject<{
+export declare const driveLogResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
     driveper: z.ZodNumber;
     setpoint: z.ZodNumber;
     modetype: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
     tiedchannel: z.ZodNumber;
     degreetype: z.ZodNumber;
     created: z.ZodString;
-}, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{}, z.core.$strict>]>;
 declare const sessionSummarySchema: z.ZodObject<{
     id: z.ZodNumber;
     title: z.ZodString;
@@ -207,5 +207,6 @@ export type RawSessionSummary = z.infer<typeof sessionSummarySchema>;
 export type RawSessionDetail = z.infer<typeof sessionDetailSchema>;
 export type RawChartChannel = z.infer<typeof chartChannelSchema>;
 export type RawDriveLog = z.infer<typeof driveLogSchema>;
+export type RawDriveLogResponse = z.infer<typeof driveLogResponseSchema>;
 export type RawDeviceTemperatures = z.infer<typeof deviceTemperaturesResponseSchema>;
 export {};

package/dist/schemas.js

@@ -96,13 +96,13 @@ export const deviceSchema = z.looseObject({
     channels: z.array(deviceChannelSchema),
     last_drivelog: driveLogSchema.nullable().optional(),
     active: z.boolean().optional(),
-    last_battery_reading: z.number().optional(),
+    last_battery_reading: z.number().nullable().optional(),
     model_name: z.string().optional(),
     created: z.string().optional(),
     hardware_id: z.string().optional(),
     latest_temps: z.array(z.unknown()).optional(),
-    device_log: z.record(z.string(), z.unknown()).optional(),
-    last_templog: z.string().optional(),
+    device_log: z.record(z.string(), z.unknown()).nullable().optional(),
+    last_templog: z.string().nullable().optional(),
 });
 // GET /api/v1/devices.json
 // Returns all devices associated with the authenticated account.
@@ -132,8 +132,9 @@ export const deviceTemperaturesResponseSchema = z.json();
 // GET /api/v1/devices/{uuid}/drivelog.json
 // Official docs: returns the latest Drive log if it is less than one minute old.
 // A single-object response and the fields above are based on observed responses;
-// the official page does not define the body when no recent Drive log exists.
-export const driveLogResponseSchema = driveLogSchema;
+// Observed with Drive disconnected or the device offline: HTTP 200 with {}.
+// Keep an empty response unchanged, and reject incomplete non-empty logs.
+export const driveLogResponseSchema = z.union([driveLogSchema, z.strictObject({})]);
 // Represents a session summary as returned in the sessions list.
 // Used as an element in GET /api/v1/sessions.json.
 //

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { RawDevice } from "./schemas.js";
 export interface RequestOptions {
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
@@ -6,6 +7,7 @@ export interface RequestOptions {
 export interface FireboardClientOptions extends RequestOptions {
     token: string;
     baseUrl?: string;
+    deviceCacheTtlMs?: number;
 }
 export interface LoginOptions extends RequestOptions {
     loginUrl?: string;
@@ -17,3 +19,8 @@ export type DriveSetpointOptions = {
     setpoint?: number;
     channel: number;
 };
+export interface DeviceListResult {
+    data: RawDevice[];
+    fromCache: boolean;
+    cacheAgeSeconds: number;
+}

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
 export declare function validateEndpoint(value: string): string;
-export declare function validateTiming(value: number, name: string): number;
+export declare function validateTiming(value: number, name: string, allowZero?: boolean): number;
 export declare function encodeDeviceId(uuid: string): string;
 export declare function validateSessionId(id: number): number;

package/dist/validation.js

@@ -9,8 +9,8 @@ export function validateEndpoint(value) {
     }
     return url.href;
 }
-export function validateTiming(value, name) {
-    if (!Number.isFinite(value) || value < 1 || value > 2_147_483_647) {
+export function validateTiming(value, name, allowZero = false) {
+    if (!Number.isFinite(value) || value < (allowZero ? 0 : 1) || value > 2_147_483_647) {
         throw new TypeError(`Invalid ${name}`);
     }
     return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireboard-api-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Unofficial TypeScript client for the Fireboard temperature monitoring API",
   "keywords": [
     "api-client",