fireboard-api-client 0.0.0-stage → 0.2.0

package/dist/drive.js

@@ -0,0 +1,53 @@
+import { headers, request } from "./request.js";
+import { encodeDeviceId } from "./validation.js";
+export class DriveControls {
+    baseUrl;
+    #options;
+    constructor(baseUrl, options) {
+        this.baseUrl = baseUrl;
+        this.#options = options;
+    }
+    async send(uuid, payload) {
+        await request(`${this.baseUrl}/devices/${encodeDeviceId(uuid)}/mq.json`, {
+            method: "POST",
+            headers: {
+                ...headers(this.#options, this.#options.token),
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                topic: "device",
+                payload: { ...payload, request_type: "control" },
+            }),
+        }, this.#options);
+    }
+    async setSetpoint(uuid, options) {
+        encodeDeviceId(uuid);
+        if (!options || (options.setpoint === undefined && options.channel === undefined)) {
+            throw new TypeError("At least one of setpoint or channel is required");
+        }
+        if (options.setpoint !== undefined && !Number.isFinite(options.setpoint)) {
+            throw new TypeError("Setpoint must be a finite number");
+        }
+        if (options.channel !== undefined &&
+            (!Number.isSafeInteger(options.channel) || options.channel < 1)) {
+            throw new TypeError("Channel must be a positive integer");
+        }
+        const writes = [];
+        if (options.channel !== undefined) {
+            writes.push(this.send(uuid, { cc: String(options.channel) }));
+        }
+        if (options.setpoint !== undefined) {
+            writes.push(this.send(uuid, { t: "fan", setpoint: String(options.setpoint) }));
+        }
+        await Promise.all(writes);
+    }
+    async setSpeed(uuid, percent) {
+        if (!Number.isFinite(percent) || percent < 0 || percent > 100) {
+            throw new TypeError("Fan speed must be a number between 0 and 100");
+        }
+        await this.send(uuid, { t: "fan", p: String(percent / 100) });
+    }
+    async off(uuid) {
+        await this.send(uuid, { t: "fan", setpoint: "0" });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type FireboardErrorCode = "AUTHENTICATION" | "RATE_LIMIT" | "API_UNAVAILABLE" | "INVALID_RESPONSE" | "TIMEOUT" | "NETWORK";
+export declare class FireboardError extends Error {
+    readonly code: FireboardErrorCode;
+    readonly status?: number | undefined;
+    constructor(message: string, code: FireboardErrorCode, status?: number | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class FireboardError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "FireboardError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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, DeviceListResult, } from "./types.js";
+export * from "./schemas.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+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 * from "./schemas.js";

package/dist/login.d.ts

@@ -0,0 +1,6 @@
+import type { LoginOptions } from "./types.js";
+export declare const DEFAULT_LOGIN_URL = "https://fireboard.io/api/rest-auth/login/";
+export declare function login(credentials: {
+    username: string;
+    password: string;
+}, options?: LoginOptions): Promise<string>;

package/dist/login.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { decode, headers, request } from "./request.js";
+import { validateEndpoint } from "./validation.js";
+export const DEFAULT_LOGIN_URL = "https://fireboard.io/api/rest-auth/login/";
+export async function login(credentials, options = {}) {
+    if (typeof credentials?.username !== "string" ||
+        !credentials.username.trim() ||
+        typeof credentials.password !== "string" ||
+        !credentials.password) {
+        throw new TypeError("Username and password are required");
+    }
+    const loginUrl = validateEndpoint(options.loginUrl ?? DEFAULT_LOGIN_URL);
+    const response = await request(loginUrl, {
+        method: "POST",
+        headers: { ...headers(options), "Content-Type": "application/json" },
+        body: JSON.stringify(credentials),
+    }, options, true);
+    return (await decode(response, z.object({ key: z.string().min(1) }))).key;
+}

package/dist/request.d.ts

@@ -0,0 +1,6 @@
+import type { z } from "zod";
+import type { RequestOptions } from "./types.js";
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare function request(url: string, init: RequestInit, options: RequestOptions, isLogin?: boolean): Promise<Response>;
+export declare function decode<S extends z.ZodType>(response: Response, schema: S): Promise<z.output<S>>;
+export declare function headers(options: RequestOptions, token?: string): Record<string, string>;

package/dist/request.js

@@ -0,0 +1,56 @@
+import { createRequire } from "node:module";
+import { FireboardError } from "./errors.js";
+import { validateTiming } from "./validation.js";
+export const DEFAULT_TIMEOUT_MS = 15_000;
+const { version } = createRequire(import.meta.url)("../package.json");
+const defaultUserAgent = `fireboard-api-client/${version}`;
+export async function request(url, init, options, isLogin = false) {
+    const timeoutMs = validateTiming(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, "timeoutMs");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await (options.fetch ?? globalThis.fetch)(url, {
+            ...init,
+            signal: controller.signal,
+            redirect: "error",
+        });
+        if (response.status === 401 || (isLogin && response.status === 400)) {
+            throw new FireboardError("Invalid Fireboard token. Check your API key.", "AUTHENTICATION", response.status);
+        }
+        if (response.status === 429) {
+            throw new FireboardError("Fireboard REST API rate limit reached (17 calls / 5 min). Further requests are blocked for ~5 minutes. See: https://docs.fireboard.io/app/app-api/#rate-limits", "RATE_LIMIT", 429);
+        }
+        if (!response.ok) {
+            throw new FireboardError("Fireboard API unavailable. Try again shortly.", "API_UNAVAILABLE", response.status);
+        }
+        // Read the body under the timeout; method callers validate the decoded JSON.
+        const body = await response.text();
+        return new Response(body || null, { status: response.status, headers: response.headers });
+    }
+    catch (error) {
+        if (error instanceof FireboardError) {
+            throw error;
+        }
+        if (controller.signal.aborted) {
+            throw new FireboardError("Fireboard API request timed out.", "TIMEOUT");
+        }
+        throw new FireboardError("Could not connect to the Fireboard API.", "NETWORK");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function decode(response, schema) {
+    try {
+        return schema.parse(await response.json());
+    }
+    catch {
+        throw new FireboardError("Unexpected Fireboard API response.", "INVALID_RESPONSE", response.status);
+    }
+}
+export function headers(options, token) {
+    return {
+        ...(token ? { Authorization: `Token ${token}` } : {}),
+        "User-Agent": options.userAgent ?? defaultUserAgent,
+    };
+}

package/dist/schemas.d.ts

@@ -0,0 +1,212 @@
+import { z } from "zod";
+declare const driveLogSchema: 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>;
+declare const alertSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    temp_min: z.ZodNumber;
+    temp_max: z.ZodNumber;
+    notify_app: z.ZodBoolean;
+    notify_email: z.ZodBoolean;
+    notify_sms: z.ZodBoolean;
+    time_start: z.ZodString;
+    time_stop: z.ZodString;
+    minutes_buffer: z.ZodNumber;
+    minutes_repeat: z.ZodNumber;
+    enabled: z.ZodBoolean;
+    created: z.ZodString;
+    channel: z.ZodNumber;
+    device_id: z.ZodNumber;
+    session_id: z.ZodNumber;
+}, z.core.$loose>;
+export declare const deviceSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    id: z.ZodNumber;
+    title: z.ZodString;
+    channel_count: z.ZodOptional<z.ZodNumber>;
+    channels: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        channel: z.ZodNumber;
+        channel_label: z.ZodString;
+        current_temp: z.ZodOptional<z.ZodNumber>;
+        degreetype: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        enabled: z.ZodBoolean;
+        alerts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            temp_min: z.ZodNumber;
+            temp_max: z.ZodNumber;
+            notify_app: z.ZodBoolean;
+            notify_email: z.ZodBoolean;
+            notify_sms: z.ZodBoolean;
+            time_start: z.ZodString;
+            time_stop: z.ZodString;
+            minutes_buffer: z.ZodNumber;
+            minutes_repeat: z.ZodNumber;
+            enabled: z.ZodBoolean;
+            created: z.ZodString;
+            channel: z.ZodNumber;
+            device_id: z.ZodNumber;
+            session_id: z.ZodNumber;
+        }, z.core.$loose>>>;
+        last_templog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            temp: z.ZodNumber;
+            created: z.ZodString;
+            degreetype: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    last_drivelog: z.ZodOptional<z.ZodNullable<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>>>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    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.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;
+    id: z.ZodNumber;
+    title: z.ZodString;
+    channel_count: z.ZodOptional<z.ZodNumber>;
+    channels: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        channel: z.ZodNumber;
+        channel_label: z.ZodString;
+        current_temp: z.ZodOptional<z.ZodNumber>;
+        degreetype: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        enabled: z.ZodBoolean;
+        alerts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            temp_min: z.ZodNumber;
+            temp_max: z.ZodNumber;
+            notify_app: z.ZodBoolean;
+            notify_email: z.ZodBoolean;
+            notify_sms: z.ZodBoolean;
+            time_start: z.ZodString;
+            time_stop: z.ZodString;
+            minutes_buffer: z.ZodNumber;
+            minutes_repeat: z.ZodNumber;
+            enabled: z.ZodBoolean;
+            created: z.ZodString;
+            channel: z.ZodNumber;
+            device_id: z.ZodNumber;
+            session_id: z.ZodNumber;
+        }, z.core.$loose>>>;
+        last_templog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            temp: z.ZodNumber;
+            created: z.ZodString;
+            degreetype: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    last_drivelog: z.ZodOptional<z.ZodNullable<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>>>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    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.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.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.ZodObject<{}, z.core.$strict>]>;
+declare const sessionSummarySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    description: z.ZodString;
+    start_time: z.ZodString;
+    end_time: z.ZodNullable<z.ZodString>;
+    device_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    devices: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    duration: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodString>;
+    owner: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export declare const sessionsResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    description: z.ZodString;
+    start_time: z.ZodString;
+    end_time: z.ZodNullable<z.ZodString>;
+    device_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    devices: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    duration: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodString>;
+    owner: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>>;
+export declare const sessionDetailSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    description: z.ZodString;
+    start_time: z.ZodString;
+    end_time: z.ZodNullable<z.ZodString>;
+    devices: z.ZodArray<z.ZodObject<{
+        uuid: z.ZodString;
+        title: z.ZodString;
+        channels: z.ZodArray<z.ZodObject<{
+            channel_label: z.ZodString;
+            channel: z.ZodNumber;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    notes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        note_time: z.ZodString;
+        note_text: z.ZodString;
+        channel: z.ZodNullable<z.ZodNumber>;
+        device: z.ZodString;
+    }, z.core.$loose>>>;
+    duration: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodString>;
+    owner: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export declare const chartChannelSchema: z.ZodObject<{
+    device: z.ZodString;
+    label: z.ZodString;
+    degreetype: z.ZodNumber;
+    channel_id: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>;
+    x: z.ZodArray<z.ZodNumber>;
+    y: z.ZodArray<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const chartResponseSchema: z.ZodArray<z.ZodObject<{
+    device: z.ZodString;
+    label: z.ZodString;
+    degreetype: z.ZodNumber;
+    channel_id: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>;
+    x: z.ZodArray<z.ZodNumber>;
+    y: z.ZodArray<z.ZodNumber>;
+}, z.core.$loose>>;
+export type RawDevice = z.infer<typeof deviceSchema>;
+export type RawAlert = z.infer<typeof alertSchema>;
+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

@@ -0,0 +1,276 @@
+import { z } from "zod";
+// Unused channel slots on a device may omit degreetype or send null.
+// Nested field shapes are based on responses observed while building fireboard-mcp.
+// The official API page does not specify their complete structure.
+const nullableDegreeTypeSchema = z.number().nullable().optional();
+// Represents a single drive controller log entry.
+// Used both as a top-level response from GET /api/v1/devices/{uuid}/drivelog.json
+// and nested inside device objects from GET /api/v1/devices.json.
+//
+// Illustrative excerpt (GET /api/v1/devices/{uuid}/drivelog.json):
+// {
+//   "tiedchannel": 1,
+//   "setpoint": 107.0,
+//   "driveper": 0.0,
+//   "modetype": "Off",      // can also be a number, e.g. 2
+//   "degreetype": 1,
+//   "created": "2024-01-01T12:00:00+00:00"
+// }
+const driveLogSchema = z.looseObject({
+    driveper: z.number(),
+    setpoint: z.number(),
+    modetype: z.union([z.string(), z.number()]), // string from /drivelog.json ("Off"), integer from /devices.json last_drivelog (2) — API inconsistency
+    tiedchannel: z.number(),
+    degreetype: z.number(),
+    created: z.string(),
+});
+// Represents a temperature alert configured on a channel.
+// Nested inside channel objects from GET /api/v1/devices.json.
+const alertSchema = z.looseObject({
+    id: z.number(),
+    temp_min: z.number(),
+    temp_max: z.number(),
+    notify_app: z.boolean(),
+    notify_email: z.boolean(),
+    notify_sms: z.boolean(),
+    time_start: z.string(),
+    time_stop: z.string(),
+    minutes_buffer: z.number(),
+    minutes_repeat: z.number(),
+    enabled: z.boolean(),
+    created: z.string(),
+    channel: z.number(),
+    device_id: z.number(),
+    session_id: z.number(),
+});
+// Represents a single temperature probe channel on a device.
+// Nested inside device objects from GET /api/v1/devices.json.
+//
+// Illustrative channel excerpt (not a complete schema fixture):
+// {
+//   "channel": 1,
+//   "channel_label": "Grill Temp",
+//   "current_temp": 107.6,
+//   "degreetype": 1,
+//   "enabled": true,
+//   "last_templog": {
+//     "temp": 107.6,
+//     "created": "2024-01-01T12:00:00Z",
+//     "degreetype": 1
+//   }
+// }
+const deviceChannelSchema = z.looseObject({
+    id: z.number(),
+    channel: z.number(),
+    channel_label: z.string(),
+    current_temp: z.number().optional(),
+    degreetype: nullableDegreeTypeSchema,
+    enabled: z.boolean(),
+    alerts: z.array(alertSchema).default([]),
+    last_templog: z
+        .looseObject({
+        temp: z.number(),
+        created: z.string(),
+        degreetype: nullableDegreeTypeSchema,
+    })
+        .nullable()
+        .optional(),
+});
+// Represents a single Fireboard device.
+// Used as an element in GET /api/v1/devices.json.
+//
+// Illustrative excerpt (GET /api/v1/devices.json, first element):
+// {
+//   "uuid": "abc12345-0000-0000-0000-000000000000",
+//   "title": "Big Green Egg",
+//   "channel_count": 3,
+//   "active": true,
+//   "channels": [ ... ],          // see deviceChannelSchema
+//   "last_drivelog": { ... }       // see driveLogSchema, null if no drive session
+// }
+export const deviceSchema = z.looseObject({
+    uuid: z.string(),
+    id: z.number(),
+    title: z.string(),
+    channel_count: z.number().optional(),
+    channels: z.array(deviceChannelSchema),
+    last_drivelog: driveLogSchema.nullable().optional(),
+    active: z.boolean().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()).nullable().optional(),
+    last_templog: z.string().nullable().optional(),
+});
+// GET /api/v1/devices.json
+// Returns all devices associated with the authenticated account.
+//
+// Illustrative response excerpt (truncated):
+// [
+//   {
+//     "uuid": "abc12345-0000-0000-0000-000000000000",
+//     "title": "Big Green Egg",
+//     "channel_count": 3,
+//     "active": true,
+//     "channels": [
+//       { "channel": 1, "channel_label": "Grill Temp", "current_temp": 225.0, "degreetype": 1, "enabled": true,
+//         "last_templog": { "temp": 225.0, "created": "2024-01-01T12:00:00Z", "degreetype": 1 } },
+//       { "channel": 2, "channel_label": "Meat Temp", "current_temp": 145.0, "degreetype": 1, "enabled": true,
+//         "last_templog": { "temp": 145.0, "created": "2024-01-01T12:00:00Z", "degreetype": 1 } }
+//     ],
+//     "last_drivelog": { "driveper": 0.0, "setpoint": 225.0, "modetype": 2, "tiedchannel": 1,
+//                        "degreetype": 1, "created": "2024-01-01T12:00:02Z" }
+//   }
+// ]
+export const devicesResponseSchema = z.array(deviceSchema);
+// GET /api/v1/devices/{uuid}/temps.json
+// Official docs specify the one-minute freshness cutoff, but not the response structure.
+// Preserve JSON without inventing required field names or a top-level container shape.
+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;
+// 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.
+//
+// Illustrative session summary excerpt:
+// {
+//   "id": 12345678,
+//   "title": "Sat Jan 1 Session",
+//   "description": "Auto-created session",
+//   "start_time": "2024-01-01T10:00:00Z",
+//   "end_time": null,
+//   "device_ids": ["abc12345-0000-0000-0000-000000000000"]
+// }
+const sessionSummarySchema = z.looseObject({
+    id: z.number(),
+    title: z.string(),
+    description: z.string(),
+    start_time: z.string(),
+    end_time: z.string().nullable(),
+    // Observed list-response field; not listed in the official session properties.
+    device_ids: z.array(z.string()).optional(),
+    devices: z.array(z.unknown()).optional(),
+    duration: z.string().optional(),
+    created: z.string().optional(),
+    owner: z.record(z.string(), z.unknown()).optional(),
+});
+// GET /api/v1/sessions.json
+// Returns sessions for the authenticated account. The official docs do not specify ordering.
+//
+// Illustrative response excerpt (two entries shown):
+// [
+//   { "id": 12345678, "title": "Sat Jan 1 Session", "description": "Auto-created session",
+//     "start_time": "2024-01-01T10:00:00Z", "end_time": null,
+//     "device_ids": ["abc12345-0000-0000-0000-000000000000"] },
+//   { "id": 12345677, "title": "Mon May 25: Pulled Pork",
+//     "description": "User-initiated session",
+//     "start_time": "2024-01-01T08:00:00Z", "end_time": "2024-01-01T20:00:00Z",
+//     "device_ids": ["abc12345-0000-0000-0000-000000000000"] }
+// ]
+export const sessionsResponseSchema = z.array(sessionSummarySchema);
+// Represents a single cook note attached to a session.
+// Nested inside the notes array of a session detail response.
+//
+// Illustrative note excerpt:
+// {
+//   "note_time": "2024-01-01T12:00:00Z",
+//   "note_text": "Added more fuel",
+//   "channel": 2,       // null if not tied to a specific channel
+//   "device": "abc12345-0000-0000-0000-000000000000"
+// }
+const noteSchema = z.looseObject({
+    note_time: z.string(),
+    note_text: z.string(),
+    channel: z.number().nullable(),
+    device: z.string(),
+});
+// Represents a device summary nested inside a session detail response.
+// Contains only the fields needed to identify the device and its channels.
+const sessionDeviceSchema = z.looseObject({
+    uuid: z.string(),
+    title: z.string(),
+    channels: z.array(z.looseObject({
+        channel_label: z.string(),
+        channel: z.number(),
+    })),
+});
+// GET /api/v1/sessions/{id}.json
+// Returns full detail for a single cooking session including devices and notes.
+//
+// Illustrative excerpt (GET /api/v1/sessions/12345678.json):
+// {
+//   "id": 12345678,
+//   "title": "Sat Jan 1 Session",
+//   "description": "Auto-created session",
+//   "start_time": "2024-01-01T10:00:00Z",
+//   "end_time": null,
+//   "devices": [
+//     {
+//       "uuid": "abc12345-0000-0000-0000-000000000000",
+//       "title": "Big Green Egg",
+//       "channels": [
+//         { "channel": 1, "channel_label": "Grill Temp" },
+//         { "channel": 2, "channel_label": "Meat Temp" },
+//         { "channel": 3, "channel_label": "Channel 3" }
+//       ]
+//     }
+//   ],
+//   "notes": [
+//     { "note_time": "2024-01-01T12:00:00Z", "note_text": "Added more fuel",
+//       "channel": 2, "device": "abc12345-0000-0000-0000-000000000000" }
+//   ]
+// }
+export const sessionDetailSchema = z.looseObject({
+    id: z.number(),
+    title: z.string(),
+    description: z.string(),
+    start_time: z.string(),
+    end_time: z.string().nullable(),
+    devices: z.array(sessionDeviceSchema),
+    notes: z.array(noteSchema).default([]),
+    duration: z.string().optional(),
+    created: z.string().optional(),
+    owner: z.record(z.string(), z.unknown()).optional(),
+});
+// Represents a single channel's time-series temperature data within a session.
+// Used as an element in GET /api/v1/sessions/{id}/chart.json.
+//
+// x: array of Unix timestamps (seconds since epoch)
+// y: array of temperature readings corresponding to each timestamp
+//
+// Illustrative channel excerpt:
+// {
+//   "device": "abc12345-0000-0000-0000-000000000000",
+//   "label": "Grill Temp",
+//   "degreetype": 1,
+//   "channel_id": "1",
+//   "x": [1704110400, 1704110460, ...],
+//   "y": [225.0, 226.1, ...]
+// }
+export const chartChannelSchema = z.looseObject({
+    device: z.string(),
+    label: z.string(),
+    degreetype: z.number(),
+    channel_id: z.union([z.string(), z.number()]).transform(String).optional(),
+    x: z.array(z.number()),
+    y: z.array(z.number()),
+});
+// GET /api/v1/sessions/{id}/chart.json
+// Returns time-series temperature data for all channels in a session.
+// Each entry represents a channel on a device. The docs describe x as Unix timestamps
+// and y as temperature values or Drive %. They do not specify channel_id.
+//
+// Illustrative response excerpt (two channels, values truncated):
+// [
+//   { "device": "abc12345-0000-0000-0000-000000000000", "label": "Grill Temp",
+//     "degreetype": 1, "channel_id": "1", "x": [1704110400, 1704110460], "y": [225.0, 226.1] },
+//   { "device": "abc12345-0000-0000-0000-000000000000", "label": "Meat Temp",
+//     "degreetype": 1, "channel_id": "2", "x": [1704110400, 1704110460], "y": [145.0, 145.3] }
+// ]
+export const chartResponseSchema = z.array(chartChannelSchema);