divoom-timesgate-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,921 @@
+import { F as FetchLike, D as DivoomBaseResponse, P as PanelIndex, a as DivoomCommandRequest, L as LcdArray } from './common-D8oHDNi6.cjs';
+
+/**
+ * The HTTP transport that every command flows through. It builds the request
+ * URL, injects the `LocalToken`, enforces timeouts, retries transient failures
+ * with exponential backoff, and maps failures onto the SDK's typed
+ * {@link DivoomError | error hierarchy}.
+ *
+ * @packageDocumentation
+ */
+
+/** Configuration for the {@link HttpTransport}. */
+interface TransportOptions {
+    /** The device's IP address or hostname, e.g. `"192.168.1.50"`. */
+    host: string;
+    /** TCP port. Defaults to `80` (hardware version 400). */
+    port?: number;
+    /** Request path. Defaults to `"/post"` (hardware version 400). */
+    path?: string;
+    /** URL scheme. Defaults to `"http"`. */
+    protocol?: 'http' | 'https';
+    /**
+     * The device's local authentication token, read from the Divoom app
+     * (device → Settings). Injected into every request body. Defaults to `0`,
+     * which is accepted by read-only commands but rejected by commands that
+     * require authentication (e.g. `Channel/SetBrightness`).
+     */
+    localToken?: number;
+    /** Per-request timeout in milliseconds. Defaults to `8000`. */
+    timeoutMs?: number;
+    /** Number of automatic retries for transient failures. Defaults to `2`. */
+    retries?: number;
+    /** Base backoff delay in milliseconds (doubled each retry). Defaults to `300`. */
+    retryDelayMs?: number;
+    /** A custom `fetch` implementation. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Extra HTTP headers to send with every request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Low-level HTTP transport. Most users interact with the high-level
+ * {@link TimesGateClient} instead, but the transport is exported for advanced
+ * scenarios and testing.
+ */
+declare class HttpTransport {
+    /** The fully-resolved endpoint URL every request is POSTed to. */
+    readonly endpoint: string;
+    private readonly localToken;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly retryDelayMs;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(options: TransportOptions);
+    /**
+     * Sends a command payload to the device and returns the parsed response.
+     *
+     * The configured `LocalToken` is merged in automatically (an explicit
+     * `LocalToken` on the payload wins). Transient network errors, timeouts, and
+     * 5xx responses are retried with exponential backoff; device-level errors and
+     * 4xx responses are thrown immediately.
+     *
+     * @typeParam TResponse - The expected response shape.
+     * @throws {@link DivoomTimeoutError} when the request exceeds the timeout.
+     * @throws {@link DivoomHttpError} on a non-2xx HTTP status.
+     * @throws {@link DivoomDeviceError} when the device reports a non-zero `error_code`.
+     * @throws {@link DivoomConnectionError} when the device cannot be reached.
+     */
+    send<TResponse extends DivoomBaseResponse = DivoomBaseResponse>(payload: {
+        Command: string;
+    } & Record<string, unknown>): Promise<TResponse>;
+    private attempt;
+}
+
+/**
+ * Animation & on-device text commands: play stored Divoom GIFs, stream GIF URLs
+ * (uniformly or per-panel), overlay scrolling text, and compose data-rich item
+ * lists.
+ *
+ * @packageDocumentation
+ */
+
+/** Text scroll direction. */
+type TextDirection = 'left' | 'right';
+/** Horizontal text alignment. */
+type TextAlign = 'left' | 'center' | 'right';
+/** Options for {@link AnimationCommands.sendText} (`Draw/SendHttpText`). */
+interface SendTextOptions {
+    /** Unique text id (reused id replaces the text). Must be < 20. Defaults to `1`. */
+    textId?: number;
+    /** X start position. Defaults to `0`. */
+    x?: number;
+    /** Y start position. Defaults to `40`. */
+    y?: number;
+    /** Scroll direction. Defaults to `"left"`. */
+    direction?: TextDirection;
+    /** App animation font, 0–7. Defaults to `4`. */
+    font?: number;
+    /** Text area width in points (16–64). Defaults to `56`. */
+    width?: number;
+    /** Scroll speed: ms per step. Defaults to `100`. */
+    speed?: number;
+    /** Hex color, e.g. `"#FFFF00"`. Defaults to `"#FFFFFF"`. */
+    color?: string;
+    /** Horizontal alignment. Defaults to `"left"`. */
+    align?: TextAlign;
+}
+/**
+ * A single element in a {@link AnimationCommands.sendItemList} composition.
+ * Field names/casing match the device protocol verbatim (including the
+ * misspelled `Textheight`).
+ */
+interface DisplayItem {
+    /** Unique id for in-place replacement (max 40). */
+    TextId: number;
+    /** Display type: 1–21 = data fields, 22 = static text, 23 = URL text. */
+    type: number;
+    /** Horizontal start position. */
+    x: number;
+    /** Vertical start position. */
+    y: number;
+    /** Scroll direction: `0` = left, `1` = right. */
+    dir?: number;
+    /** Font id from {@link DivoomCloudClient.getFontList}. */
+    font?: number;
+    /** Text area width in pixels. */
+    TextWidth?: number;
+    /** Text area height in pixels (protocol spelling). */
+    Textheight?: number;
+    /** Text (type 22) or URL (type 23); UTF-8, max 512 chars. */
+    TextString?: string;
+    /** Scroll speed in ms per step. */
+    speed?: number;
+    /** Hex color, e.g. `"#FFFF00"`. */
+    color?: string;
+    /** Refresh interval in seconds (type 23). */
+    update_time?: number;
+    /** Alignment: `1` = left, `2` = center, `3` = right (firmware ≥ 90102). */
+    align?: number;
+}
+/** Options for {@link AnimationCommands.sendItemList}. */
+interface SendItemListOptions {
+    /** `true` (default) replaces all items; `false` appends. */
+    replace?: boolean;
+    /** Optional background GIF URL for the panel. */
+    backgroundGif?: string;
+}
+/** Animation & on-device text commands. Access via {@link TimesGateClient.animation}. */
+declare class AnimationCommands {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Plays a stored Divoom GIF (by `FileId`) on the given panels
+     * (`Draw/SendRemote`). Obtain `fileId` from
+     * {@link DivoomCloudClient.getLikedImages} or
+     * {@link DivoomCloudClient.getUploadedImages}.
+     */
+    playStoredGif(panels: PanelIndex[], fileId: string): Promise<DivoomBaseResponse>;
+    /**
+     * Plays one or more GIF URLs on the given panels (`Device/PlayGif`).
+     *
+     * @param urls - Up to 10 GIF URLs (dimensions 16/32/64/128).
+     */
+    playGifUrls(panels: PanelIndex[], urls: string[]): Promise<DivoomBaseResponse>;
+    /**
+     * Plays a distinct list of GIF URLs on each panel (`Device/PlayGifLCDs`).
+     *
+     * @param perPanel - GIF URL lists keyed by panel index (0–4).
+     *
+     * @example
+     * ```ts
+     * await client.animation.playGifPerPanel({
+     *   0: ['http://f.divoom-gz.com/Kirby.gif'],
+     *   1: ['http://f.divoom-gz.com/loz.gif'],
+     * });
+     * ```
+     */
+    playGifPerPanel(perPanel: Partial<Record<PanelIndex, string[]>>): Promise<DivoomBaseResponse>;
+    /**
+     * Overlays a single scrolling/aligned text string on a panel
+     * (`Draw/SendHttpText`).
+     *
+     * @param panel - Panel index 0–4.
+     * @param text - UTF-8 string (< 512 chars).
+     */
+    sendText(panel: PanelIndex, text: string, options?: SendTextOptions): Promise<DivoomBaseResponse>;
+    /**
+     * Composes a panel from a list of display items — static text, live data
+     * fields, and URL-backed text — over an optional background GIF
+     * (`Draw/SendHttpItemList`).
+     *
+     * @param panel - Panel index 0–4.
+     * @param items - The display elements to render.
+     */
+    sendItemList(panel: PanelIndex, items: DisplayItem[], options?: SendItemListOptions): Promise<DivoomBaseResponse>;
+}
+
+/**
+ * Batch-execution commands: run several commands in one request, or have the
+ * device fetch a command list from a URL. Requires firmware ≥ 90102.
+ *
+ * @packageDocumentation
+ */
+
+/** Batch-execution commands. Access via {@link TimesGateClient.batch}. */
+declare class BatchCommands {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Runs multiple commands in sequence in a single request (`Draw/CommandList`).
+     *
+     * @example
+     * ```ts
+     * await client.batch.run([
+     *   { Command: 'Channel/SetBrightness', Brightness: 100 },
+     *   { Command: 'Channel/OnOffScreen', OnOff: 1 },
+     * ]);
+     * ```
+     */
+    run(commands: DivoomCommandRequest[]): Promise<DivoomBaseResponse>;
+    /**
+     * Tells the device to fetch and execute a command-array file from a URL
+     * (`Draw/UseHTTPCommandSource`).
+     */
+    useCommandSource(commandUrl: string): Promise<DivoomBaseResponse>;
+}
+
+/**
+ * Dial / channel-control commands (device-side). These switch what each panel
+ * displays — a single "whole" dial spanning all five panels, or independent
+ * per-panel sub-dials and visualizers.
+ *
+ * Discovering the `ClockId` / `LcdIndependence` values these methods need is a
+ * cloud operation — see {@link DivoomCloudClient}.
+ *
+ * @packageDocumentation
+ */
+
+/** Channel/dial display mode. `whole` spans all panels; `independent` is per-panel. */
+type ChannelMode = 'whole' | 'independent';
+/** Response from {@link DialCommands.getIndex} (`Channel/GetIndex`). */
+interface GetIndexResponse extends DivoomBaseResponse {
+    /**
+     * The currently-selected channel index. On Pixoo-class devices:
+     * `0` = Faces/Clock, `1` = Cloud, `2` = Visualizer/EQ, `3` = Custom.
+     */
+    SelectIndex: number;
+}
+/** Dial-control commands. Access via {@link TimesGateClient.dial}. */
+declare class DialCommands {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Selects a "whole" dial that spans all five panels
+     * (`Channel/Set5LcdWholeClockId`).
+     *
+     * @param clockId - A whole-dial id from
+     *   {@link DivoomCloudClient.getWholeDialList}.
+     */
+    selectWholeDial(clockId: number): Promise<DivoomBaseResponse>;
+    /**
+     * Switches between whole and independent dial modes
+     * (`Channel/Set5LcdChannelType`).
+     *
+     * @param mode - `"whole"` (one dial across all panels) or `"independent"`.
+     * @param lcdIndependence - Required for `"independent"` mode; the group id from
+     *   {@link DivoomCloudClient.getChannelInfo}.
+     */
+    setChannelMode(mode: ChannelMode, lcdIndependence?: number): Promise<DivoomBaseResponse>;
+    /**
+     * Selects a sub-dial for a single panel (`Channel/SetClockSelectId`).
+     *
+     * @param panel - Panel index 0–4.
+     * @param clockId - A sub-dial id from {@link DivoomCloudClient.getDialList}.
+     * @param lcdIndependence - The group id from {@link DivoomCloudClient.getChannelInfo}.
+     */
+    selectSubDial(panel: PanelIndex, clockId: number, lcdIndependence: number): Promise<DivoomBaseResponse>;
+    /**
+     * Selects a sub-visualizer (EQ) component for a panel
+     * (`Channel/SetEqPosition`).
+     *
+     * @param panel - Panel index 0–4.
+     * @param eqPosition - Visualizer index, starting at 0.
+     * @param lcdIndependence - The group id from {@link DivoomCloudClient.getChannelInfo}.
+     */
+    selectVisualizer(panel: PanelIndex, eqPosition: number, lcdIndependence: number): Promise<DivoomBaseResponse>;
+    /** Reads the currently-selected channel index (`Channel/GetIndex`). */
+    getIndex(): Promise<GetIndexResponse>;
+}
+
+/**
+ * The image pipeline: push base64-encoded frames to panels (`Draw/SendHttpGif`),
+ * manage the device's frame cache (`Draw/ResetHttpGifId`), and query the current
+ * PicID (`Draw/GetHttpGifId`).
+ *
+ * PicIDs must strictly increase or the device caches a stale frame; this class
+ * manages them automatically while still letting you override when needed.
+ *
+ * @packageDocumentation
+ */
+
+/** The raw `Draw/SendHttpGif` payload (minus `Command`), for full manual control. */
+interface SendHttpGifRequest {
+    /** 5-element panel mask (`1` = draw, `0` = skip). */
+    LcdArray: LcdArray;
+    /** Total frame count in the animation (must be < 60). */
+    PicNum: number;
+    /** Frame pixel dimension. The Times Gate accepts `128`. */
+    PicWidth: number;
+    /** Zero-based frame index (`0`…`PicNum-1`). */
+    PicOffset: number;
+    /** Unique, strictly-increasing animation id. */
+    PicID: number;
+    /** Per-frame playback duration, in milliseconds. */
+    PicSpeed: number;
+    /** Base64-encoded JPEG/PNG frame data. */
+    PicData: string;
+}
+/** Options for {@link DrawCommands.sendImage} / {@link DrawCommands.sendImageToPanels}. */
+interface SendImageOptions {
+    /** Frame pixel dimension. Defaults to `128`. */
+    picWidth?: number;
+    /** Playback duration in ms (irrelevant for a single still). Defaults to `1000`. */
+    picSpeed?: number;
+    /** Override the auto-generated PicID. */
+    picId?: number;
+}
+/** Options for {@link DrawCommands.sendAnimation}. */
+interface SendAnimationOptions {
+    /** Frame pixel dimension. Defaults to `128`. */
+    picWidth?: number;
+    /** Per-frame duration in ms. Defaults to `100`. */
+    picSpeed?: number;
+    /** Override the auto-generated PicID (shared by every frame). */
+    picId?: number;
+}
+/** Response from {@link DrawCommands.getPicId} (`Draw/GetHttpGifId`). */
+interface GetPicIdResponse extends DivoomBaseResponse {
+    /** The device's current picture/animation id. */
+    PicId: number;
+}
+/** Image-pipeline commands. Access via {@link TimesGateClient.draw}. */
+declare class DrawCommands {
+    private readonly transport;
+    private readonly picIds;
+    constructor(transport: HttpTransport, picIdSeed?: number);
+    /**
+     * Pushes a single still image to one panel.
+     *
+     * @param panel - Panel index 0–4.
+     * @param picData - Base64-encoded JPEG/PNG (e.g. {@link EncodedFrame.data}).
+     *
+     * @example
+     * ```ts
+     * import { encodePanel } from 'divoom-timesgate-sdk/image';
+     * const frame = await encodePanel('./cover.jpg');
+     * await client.draw.sendImage(0, frame.data);
+     * ```
+     */
+    sendImage(panel: PanelIndex, picData: string, options?: SendImageOptions): Promise<DivoomBaseResponse>;
+    /**
+     * Pushes the same still image to several panels at once.
+     *
+     * @param panels - Panel indices to target.
+     * @param picData - Base64-encoded JPEG/PNG.
+     */
+    sendImageToPanels(panels: PanelIndex[], picData: string, options?: SendImageOptions): Promise<DivoomBaseResponse>;
+    /**
+     * Pushes a multi-frame animation to one or more panels. Each frame is sent as
+     * a separate `Draw/SendHttpGif` request sharing one PicID, per the protocol.
+     *
+     * @param panels - Panel indices to target.
+     * @param frames - Base64-encoded frames, in order (1–59 frames).
+     * @returns One response per frame.
+     */
+    sendAnimation(panels: PanelIndex[], frames: string[], options?: SendAnimationOptions): Promise<DivoomBaseResponse[]>;
+    /** Sends a fully-specified `Draw/SendHttpGif` frame — maximum control. */
+    sendFrame(request: SendHttpGifRequest): Promise<DivoomBaseResponse>;
+    /** Clears the device's image cache and resets the PicID counter (`Draw/ResetHttpGifId`). */
+    resetCache(): Promise<DivoomBaseResponse>;
+    /** Reads the device's current PicID (`Draw/GetHttpGifId`). */
+    getPicId(): Promise<number>;
+    /** Returns the next locally-generated, strictly-increasing PicID. */
+    nextPicId(panel?: PanelIndex): number;
+    private pushStill;
+}
+
+/**
+ * System-setting commands: brightness, screen power, time, time zone, weather
+ * location, display modes, and the device's current configuration/weather.
+ *
+ * @packageDocumentation
+ */
+
+/** Temperature unit for {@link SystemCommands.setTemperatureMode}. */
+type TemperatureUnit = 'celsius' | 'fahrenheit';
+/** Response from {@link SystemCommands.getAllConfig} (`Channel/GetAllConf`). */
+interface GetAllConfigResponse extends DivoomBaseResponse {
+    /** System brightness, 0–100. */
+    Brightness: number;
+    /** `1` if the device rotates between faces and GIFs. */
+    RotationFlag: number;
+    /** The configured date format, e.g. `"YYYY-MM-DD"`. */
+    DateFormat: string;
+    /** `1` for 24-hour clock, `0` for 12-hour. */
+    Time24Flag: number;
+    /** `0` for Celsius, `1` for Fahrenheit. */
+    TemperatureMode: number;
+    /** `1` if mirror mode is enabled. */
+    MirrorFlag: number;
+    /** `1` if the screen is on. */
+    LightSwitch: number;
+}
+/** Response from {@link SystemCommands.getDeviceTime} (`Device/GetDeviceTime`). */
+interface GetDeviceTimeResponse extends DivoomBaseResponse {
+    /** Device time as a UTC epoch (seconds). */
+    UTCTime: number;
+    /** Device local time, e.g. `"2022-03-14 03:40:28"`. */
+    LocalTime: string;
+}
+/** Response from {@link SystemCommands.getWeather} (`Device/GetWeatherInfo`). */
+interface GetWeatherResponse extends DivoomBaseResponse {
+    /** Condition text, e.g. `"Sunny"`, `"Cloudy"`. */
+    Weather: string;
+    /** Current temperature, in the device's configured unit. */
+    CurTemp: number;
+    /** Minimum temperature. */
+    MinTemp: number;
+    /** Maximum temperature. */
+    MaxTemp: number;
+    /** Atmospheric pressure (hPa). */
+    Pressure: number;
+    /** Relative humidity (%). */
+    Humidity: number;
+    /** Visibility (metres). */
+    Visibility: number;
+    /** Wind speed (m/s). */
+    WindSpeed: number;
+}
+/**
+ * System-setting commands. Access via {@link TimesGateClient.system}.
+ *
+ * @remarks Several of these settings (temperature mode, mirror mode, hour mode)
+ * are not persisted by the device and reset on power-off.
+ */
+declare class SystemCommands {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /** Sets the LCD brightness (`Channel/SetBrightness`). @param brightness 0–100. */
+    setBrightness(brightness: number): Promise<DivoomBaseResponse>;
+    /** Reads every device setting (`Channel/GetAllConf`). */
+    getAllConfig(): Promise<GetAllConfigResponse>;
+    /** Turns the screen on or off (`Channel/OnOffScreen`). */
+    setScreen(on: boolean): Promise<DivoomBaseResponse>;
+    /**
+     * Sets the weather location (`Sys/LogAndLat`). Coordinates drive the on-device
+     * weather readout.
+     */
+    setWeatherLocation(longitude: number | string, latitude: number | string): Promise<DivoomBaseResponse>;
+    /** Sets the time zone (`Sys/TimeZone`). @param timeZone e.g. `"GMT-5"`. */
+    setTimeZone(timeZone: string): Promise<DivoomBaseResponse>;
+    /**
+     * Sets the system clock (`Device/SetUTC`).
+     *
+     * @param time - A `Date` or a UTC epoch in **seconds**.
+     */
+    setSystemTime(time: Date | number): Promise<DivoomBaseResponse>;
+    /** Reads the device's UTC and local time (`Device/GetDeviceTime`). */
+    getDeviceTime(): Promise<GetDeviceTimeResponse>;
+    /** Sets the temperature unit (`Device/SetDisTempMode`). */
+    setTemperatureMode(unit: TemperatureUnit): Promise<DivoomBaseResponse>;
+    /** Enables or disables mirror mode (`Device/SetMirrorMode`). */
+    setMirrorMode(enabled: boolean): Promise<DivoomBaseResponse>;
+    /** Selects 24-hour (`true`) or 12-hour (`false`) clock (`Device/SetTime24Flag`). */
+    setHourMode(use24Hour: boolean): Promise<DivoomBaseResponse>;
+    /** Reads the current on-device weather (`Device/GetWeatherInfo`). */
+    getWeather(): Promise<GetWeatherResponse>;
+}
+
+/**
+ * Built-in tool commands: countdown timer, stopwatch, scoreboard, noise meter,
+ * and the buzzer.
+ *
+ * @packageDocumentation
+ */
+
+/** Stopwatch action for {@link ToolCommands.setStopwatch}. */
+type StopwatchAction = 'start' | 'stop' | 'reset';
+/** Options for {@link ToolCommands.playBuzzer}. */
+interface BuzzerOptions {
+    /** On-time per cycle, in milliseconds. Defaults to `500`. */
+    activeMs?: number;
+    /** Off-time per cycle, in milliseconds. Defaults to `500`. */
+    offMs?: number;
+    /** Total duration to buzz, in milliseconds. Defaults to `1000`. */
+    totalMs?: number;
+}
+/** Built-in tool commands. Access via {@link TimesGateClient.tool}. */
+declare class ToolCommands {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Starts or stops a countdown timer (`Tools/SetTimer`).
+     *
+     * @param minutes - Countdown minutes (0–99).
+     * @param seconds - Countdown seconds (0–59).
+     * @param start - `true` to start, `false` to stop. Defaults to `true`.
+     */
+    setCountdown(minutes: number, seconds: number, start?: boolean): Promise<DivoomBaseResponse>;
+    /** Controls the stopwatch (`Tools/SetStopWatch`). */
+    setStopwatch(action: StopwatchAction): Promise<DivoomBaseResponse>;
+    /**
+     * Sets the scoreboard (`Tools/SetScoreBoard`).
+     *
+     * @param redScore - Red team score (0–999).
+     * @param blueScore - Blue team score (0–999).
+     */
+    setScoreboard(redScore: number, blueScore: number): Promise<DivoomBaseResponse>;
+    /** Starts or stops the noise meter (`Tools/SetNoiseStatus`). */
+    setNoiseMeter(start: boolean): Promise<DivoomBaseResponse>;
+    /**
+     * Plays the buzzer (`Device/PlayBuzzer`). Requires firmware ≥ 90109.
+     *
+     * @example
+     * ```ts
+     * await client.tool.playBuzzer({ activeMs: 200, offMs: 100, totalMs: 900 });
+     * ```
+     */
+    playBuzzer(options?: BuzzerOptions): Promise<DivoomBaseResponse>;
+}
+
+/**
+ * The high-level {@link TimesGateClient} — one object that exposes every
+ * device-side command, grouped by area, over a single configured transport.
+ *
+ * @packageDocumentation
+ */
+
+/** Options for constructing a {@link TimesGateClient}. */
+interface TimesGateClientOptions extends TransportOptions {
+    /**
+     * Optional seed for the PicID generator used by {@link TimesGateClient.draw}.
+     * Mostly useful for deterministic tests.
+     */
+    picIdSeed?: number;
+}
+/**
+ * The main entry point for controlling a Times Gate on your local network.
+ *
+ * @example
+ * ```ts
+ * import { TimesGateClient } from 'divoom-timesgate-sdk';
+ *
+ * const client = new TimesGateClient({
+ *   host: '192.168.1.50',
+ *   localToken: 229930, // from the Divoom app → device → Settings
+ * });
+ *
+ * if (await client.ping()) {
+ *   await client.system.setBrightness(80);
+ * }
+ * ```
+ */
+declare class TimesGateClient {
+    /** The underlying HTTP transport. */
+    readonly transport: HttpTransport;
+    /** System settings: brightness, screen, time, weather, display modes. */
+    readonly system: SystemCommands;
+    /** Dial/channel control: whole vs independent dials, sub-dials, visualizers. */
+    readonly dial: DialCommands;
+    /** Built-in tools: countdown, stopwatch, scoreboard, noise meter, buzzer. */
+    readonly tool: ToolCommands;
+    /** The image pipeline: push frames/animations, manage the device cache. */
+    readonly draw: DrawCommands;
+    /** Animations & text: stored GIFs, GIF URLs, text overlays, item lists. */
+    readonly animation: AnimationCommands;
+    /** Batch execution: run multiple commands or a remote command list. */
+    readonly batch: BatchCommands;
+    constructor(options: TimesGateClientOptions);
+    /** The resolved endpoint URL this client talks to. */
+    get endpoint(): string;
+    /**
+     * Sends a raw command payload — an escape hatch for commands the typed API
+     * doesn't cover yet. The configured `LocalToken` is still injected.
+     */
+    send<TResponse extends DivoomBaseResponse = DivoomBaseResponse>(payload: {
+        Command: string;
+    } & Record<string, unknown>): Promise<TResponse>;
+    /**
+     * Checks whether the device is reachable by issuing `Channel/GetIndex`.
+     * Returns `false` instead of throwing on failure.
+     */
+    ping(): Promise<boolean>;
+}
+
+/**
+ * The Divoom **cloud** API client (`app.divoom-gz.com`). These endpoints don't
+ * touch your device directly — they discover the `ClockId`, `FileId`, and font
+ * ids you then feed to on-device {@link DialCommands} / {@link AnimationCommands}.
+ *
+ * Cloud responses use `ReturnCode` (0 = success) rather than `error_code`.
+ *
+ * @packageDocumentation
+ */
+
+/** Default Divoom cloud base URL. */
+declare const DEFAULT_CLOUD_BASE_URL = "https://app.divoom-gz.com";
+/** Base shape of every Divoom cloud response. */
+interface CloudResponse {
+    /** `0` indicates success. */
+    ReturnCode: number;
+    /** Human-readable status message. */
+    ReturnMessage?: string;
+    [key: string]: unknown;
+}
+/** Configuration for {@link DivoomCloudClient} and {@link cloudPost}. */
+interface CloudClientOptions {
+    /** Cloud base URL. Defaults to {@link DEFAULT_CLOUD_BASE_URL}. */
+    baseUrl?: string;
+    /** Custom `fetch`. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms. Defaults to `10000`. */
+    timeoutMs?: number;
+    /** Retry count for transient failures. Defaults to `2`. */
+    retries?: number;
+    /** Base backoff in ms (doubled per retry). Defaults to `300`. */
+    retryDelayMs?: number;
+    /** Extra HTTP headers. */
+    headers?: Record<string, string>;
+}
+/** A liked/uploaded image entry. */
+interface CloudImage {
+    /** Display name. */
+    FileName: string;
+    /** File identifier — pass to {@link AnimationCommands.playStoredGif}. */
+    FileId: string;
+}
+/** A sub-dial entry from {@link DivoomCloudClient.getDialList}. */
+interface SubDial {
+    /** Dial identifier. */
+    ClockId: number;
+    /** Display name. */
+    Name: string;
+}
+/** A whole-dial entry from {@link DivoomCloudClient.getWholeDialList}. */
+interface WholeDial {
+    /** Dial identifier. */
+    ClockId: number;
+    /** Display name. */
+    ClockName: string;
+    /** Description. */
+    ClockExPlain: string;
+}
+/** A font entry from {@link DivoomCloudClient.getFontList}. */
+interface CloudFont {
+    /** Font id — use as `font` in {@link DisplayItem}. */
+    id: number;
+    /** Font name. */
+    name: string;
+    /** Glyph width. */
+    width: string;
+    /** Glyph height. */
+    high: string;
+    /** Included character set. */
+    charset: string;
+    /** `0` = scrolls when too wide, `1` = no scroll. */
+    type: number;
+}
+/** An independent dial group from {@link DivoomCloudClient.getChannelInfo}. */
+interface IndependentDialGroup {
+    /** Group display name. */
+    IndependenceName: string;
+    /** Group id — used as `lcdIndependence` in {@link DialCommands}. */
+    LcdIndependence: number;
+    /** Per-panel clock ids. */
+    LcdList: Array<{
+        LcdClockId: number;
+    }>;
+}
+/** Response from {@link DivoomCloudClient.getDialTypes}. */
+interface DialTypesResponse extends CloudResponse {
+    /** Available sub-dial category names. */
+    DialTypeList: string[];
+}
+/** Response from {@link DivoomCloudClient.getDialList}. */
+interface DialListResponse extends CloudResponse {
+    /** Total available dials in this category. */
+    TotalNum: number;
+    /** This page of sub-dials (30 per page). */
+    DialList: SubDial[];
+}
+/** Response from {@link DivoomCloudClient.getWholeDialList}. */
+interface WholeDialListResponse extends CloudResponse {
+    /** Total available whole dials. */
+    TotalNum: number;
+    /** This page of whole dials (30 per page). */
+    ClockList: WholeDial[];
+}
+/** Response from {@link DivoomCloudClient.getChannelInfo}. */
+interface ChannelInfoResponse extends CloudResponse {
+    /** Current mode: `0` = whole, `1` = independent. */
+    ChannelType: number;
+    /** Selected independent group id. */
+    LcdIndependence: number;
+    /** Selected whole-dial id. */
+    ClockId: number;
+    /** All independent dial groups. */
+    LcdIndependenceList: IndependentDialGroup[];
+    /** The device id. */
+    DeviceId: number;
+}
+/** Response from {@link DivoomCloudClient.getLikedImages} / {@link DivoomCloudClient.getUploadedImages}. */
+interface ImageListResponse extends CloudResponse {
+    /** The returned images. */
+    ImgList: CloudImage[];
+}
+/** Response from {@link DivoomCloudClient.getFontList}. */
+interface FontListResponse extends CloudResponse {
+    /** Available fonts. */
+    FontList: CloudFont[];
+}
+/**
+ * POSTs JSON to a Divoom cloud URL with timeout, retry, and `ReturnCode`
+ * checking. Exported for advanced use (e.g. {@link discoverDevices}).
+ */
+declare function cloudPost<T extends CloudResponse>(url: string, body: Record<string, unknown>, options?: CloudClientOptions): Promise<T>;
+/** Client for the Divoom cloud discovery APIs. */
+declare class DivoomCloudClient {
+    private readonly baseUrl;
+    private readonly options;
+    constructor(options?: CloudClientOptions);
+    private post;
+    /** Lists sub-dial category names (`Channel/GetDialType`). */
+    getDialTypes(): Promise<DialTypesResponse>;
+    /** Lists sub-dials in a category, paged 30 at a time (`Channel/GetDialList`). */
+    getDialList(dialType: string, page?: number, deviceType?: string): Promise<DialListResponse>;
+    /** Lists whole (5-panel) dials, paged (`Channel/Get5LcdClockListForCommon`). */
+    getWholeDialList(page?: number): Promise<WholeDialListResponse>;
+    /** Gets channel info incl. independent dial groups (`Channel/Get5LcdInfoV2`). */
+    getChannelInfo(deviceId: number, deviceType?: string): Promise<ChannelInfoResponse>;
+    /** Lists the account's liked images (`Device/GetImgLikeList`). */
+    getLikedImages(deviceId: number, deviceMac: string, page?: number): Promise<ImageListResponse>;
+    /** Lists the account's uploaded images (`Device/GetImgUploadList`). */
+    getUploadedImages(deviceId: number, deviceMac: string, page?: number): Promise<ImageListResponse>;
+    /** Lists fonts usable in {@link AnimationCommands.sendItemList} (`Device/GetTimeDialFontList`). */
+    getFontList(): Promise<FontListResponse>;
+}
+
+/**
+ * LAN device discovery. Divoom's cloud reports every device bound to the
+ * caller's public IP, which is how you find a Times Gate's local IP address
+ * without scanning the network yourself.
+ *
+ * @packageDocumentation
+ */
+
+/** A device returned by {@link discoverDevices}. */
+interface DiscoveredDevice {
+    /** Friendly device name, e.g. `"Times Gate"`. */
+    name: string;
+    /** Divoom device id. */
+    id: number;
+    /** The device's private (LAN) IP — use this as the client `host`. */
+    ip: string;
+    /** The device's MAC address. */
+    mac: string;
+}
+/**
+ * Discovers Divoom devices on the same network as this machine.
+ *
+ * @example
+ * ```ts
+ * const devices = await discoverDevices();
+ * const gate = devices.find((d) => d.name.includes('Times Gate'));
+ * const client = new TimesGateClient({ host: gate!.ip, localToken: 229930 });
+ * ```
+ *
+ * @remarks Requires outbound internet access (the lookup goes through Divoom's
+ * cloud). It returns devices seen from your public IP, so it won't work across
+ * different networks or some VPNs.
+ */
+declare function discoverDevices(options?: CloudClientOptions): Promise<DiscoveredDevice[]>;
+
+/**
+ * Error hierarchy for the Divoom Times Gate SDK.
+ *
+ * Every error thrown by the SDK extends {@link DivoomError}, so you can catch
+ * the whole family with a single `instanceof DivoomError` check, or narrow to a
+ * specific subclass when you need to react differently (e.g. retry on a
+ * timeout, but surface a validation mistake to the user).
+ *
+ * @packageDocumentation
+ */
+/** Base class for every error thrown by the SDK. */
+declare class DivoomError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when arguments fail validation before a request is ever sent. */
+declare class DivoomValidationError extends DivoomError {
+    constructor(message: string);
+}
+/** Thrown when the device cannot be reached (DNS, connection refused, etc.). */
+declare class DivoomConnectionError extends DivoomError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a request does not complete within the configured timeout. */
+declare class DivoomTimeoutError extends DivoomError {
+    /** The command that timed out. */
+    readonly command: string;
+    /** The timeout budget, in milliseconds, that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(command: string, timeoutMs: number);
+}
+/** Thrown when the device responds with a non-2xx HTTP status. */
+declare class DivoomHttpError extends DivoomError {
+    /** The HTTP status code returned by the device. */
+    readonly status: number;
+    /** The command that produced the error. */
+    readonly command: string;
+    /** The full request URL. */
+    readonly url: string;
+    constructor(status: number, command: string, url: string);
+}
+/**
+ * Thrown when a Divoom **cloud** API (`app.divoom-gz.com`) reports a non-zero
+ * `ReturnCode`.
+ */
+declare class DivoomCloudError extends DivoomError {
+    /** The non-zero `ReturnCode` reported by the cloud API. */
+    readonly returnCode: number;
+    /** The cloud endpoint path that failed. */
+    readonly endpoint: string;
+    /** The `ReturnMessage`, when provided. */
+    readonly returnMessage?: string;
+    constructor(returnCode: number, endpoint: string, returnMessage?: string);
+}
+/**
+ * Thrown when the device accepts the request but reports a non-zero
+ * `error_code` in the response body.
+ */
+declare class DivoomDeviceError extends DivoomError {
+    /** The non-zero `error_code` reported by the device. */
+    readonly errorCode: number;
+    /** The command that was rejected. */
+    readonly command: string;
+    /** The raw response body returned by the device. */
+    readonly response: unknown;
+    constructor(errorCode: number, command: string, response: unknown);
+}
+
+/**
+ * Device-level constants for the Divoom Times Gate.
+ *
+ * @packageDocumentation
+ */
+/** The Times Gate has five individually-addressable LCD panels. */
+declare const PANEL_COUNT = 5;
+/** Each panel renders a square {@link PANEL_SIZE}×{@link PANEL_SIZE} image. */
+declare const PANEL_SIZE = 128;
+/** Default HTTP port for hardware version 400 devices. */
+declare const DEFAULT_PORT = 80;
+/** Default request path for hardware version 400 devices (`http://IP:80/post`). */
+declare const DEFAULT_PATH = "/post";
+/** HTTP port for hardware version 402 devices. */
+declare const HARDWARE_402_PORT = 9000;
+/** Request path for hardware version 402 devices (`http://IP:9000/divoom_api`). */
+declare const HARDWARE_402_PATH = "/divoom_api";
+/**
+ * Divoom's cloud endpoint that returns every Divoom device currently visible
+ * on the same LAN as the caller. Used by {@link discoverDevices}.
+ */
+declare const LAN_DISCOVERY_URL = "https://app.divoom-gz.com/Device/ReturnSameLANDevice";
+
+/**
+ * Small, dependency-free helpers shared across the SDK: argument validation,
+ * panel-mask construction, and a monotonic PicID generator.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Builds a panel selection mask for a single panel.
+ *
+ * @example
+ * ```ts
+ * panelToLcdArray(2); // → [0, 0, 1, 0, 0]
+ * ```
+ */
+declare function panelToLcdArray(panel: PanelIndex): LcdArray;
+/**
+ * Builds a panel selection mask from a set of panels.
+ *
+ * @example
+ * ```ts
+ * panelsToLcdArray([0, 4]); // → [1, 0, 0, 0, 1]
+ * ```
+ */
+declare function panelsToLcdArray(panels: Iterable<PanelIndex>): LcdArray;
+/**
+ * Generates strictly-increasing PicIDs for image uploads. The Times Gate caches
+ * frames by ID, so every pushed frame needs a fresh, monotonically growing ID.
+ *
+ * Uniqueness within a single generator comes from the `+10` step taken on every
+ * `next()` call; the per-panel offset only spaces consecutive IDs apart and is
+ * not what prevents collisions. The generator is seeded from the current time in
+ * seconds, so two *separate* generators created within the same second can
+ * produce overlapping IDs — share one generator if you need cross-instance
+ * uniqueness (or seed from the device via `Draw/GetHttpGifId`).
+ */
+declare class PicIdGenerator {
+    private base;
+    constructor(seed?: number);
+    /** Returns the next unique PicID for the given panel. */
+    next(panel?: number): number;
+}
+
+export { AnimationCommands, BatchCommands, type BuzzerOptions, type ChannelInfoResponse, type ChannelMode, type CloudClientOptions, type CloudFont, type CloudImage, type CloudResponse, DEFAULT_CLOUD_BASE_URL, DEFAULT_PATH, DEFAULT_PORT, DialCommands, type DialListResponse, type DialTypesResponse, type DiscoveredDevice, type DisplayItem, DivoomBaseResponse, DivoomCloudClient, DivoomCloudError, DivoomCommandRequest, DivoomConnectionError, DivoomDeviceError, DivoomError, DivoomHttpError, DivoomTimeoutError, DivoomValidationError, DrawCommands, FetchLike, type FontListResponse, type GetAllConfigResponse, type GetDeviceTimeResponse, type GetIndexResponse, type GetPicIdResponse, type GetWeatherResponse, HARDWARE_402_PATH, HARDWARE_402_PORT, HttpTransport, type ImageListResponse, type IndependentDialGroup, LAN_DISCOVERY_URL, LcdArray, PANEL_COUNT, PANEL_SIZE, PanelIndex, PicIdGenerator, type SendAnimationOptions, type SendHttpGifRequest, type SendImageOptions, type SendItemListOptions, type SendTextOptions, type StopwatchAction, type SubDial, SystemCommands, type TemperatureUnit, type TextAlign, type TextDirection, TimesGateClient, type TimesGateClientOptions, ToolCommands, type TransportOptions, type WholeDial, type WholeDialListResponse, cloudPost, discoverDevices, panelToLcdArray, panelsToLcdArray };