divoom-timesgate-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,991 @@
+// src/errors.ts
+var DivoomError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "DivoomError";
+  }
+};
+var DivoomValidationError = class extends DivoomError {
+  constructor(message) {
+    super(message);
+    this.name = "DivoomValidationError";
+  }
+};
+var DivoomConnectionError = class extends DivoomError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "DivoomConnectionError";
+  }
+};
+var DivoomTimeoutError = class extends DivoomError {
+  /** The command that timed out. */
+  command;
+  /** The timeout budget, in milliseconds, that was exceeded. */
+  timeoutMs;
+  constructor(command, timeoutMs) {
+    super(`Command "${command}" timed out after ${timeoutMs}ms.`);
+    this.name = "DivoomTimeoutError";
+    this.command = command;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var DivoomHttpError = class extends DivoomError {
+  /** The HTTP status code returned by the device. */
+  status;
+  /** The command that produced the error. */
+  command;
+  /** The full request URL. */
+  url;
+  constructor(status, command, url) {
+    super(`Times Gate returned HTTP ${status} for command "${command}" (${url}).`);
+    this.name = "DivoomHttpError";
+    this.status = status;
+    this.command = command;
+    this.url = url;
+  }
+};
+var DivoomCloudError = class extends DivoomError {
+  /** The non-zero `ReturnCode` reported by the cloud API. */
+  returnCode;
+  /** The cloud endpoint path that failed. */
+  endpoint;
+  /** The `ReturnMessage`, when provided. */
+  returnMessage;
+  constructor(returnCode, endpoint, returnMessage) {
+    super(
+      `Divoom cloud endpoint "${endpoint}" failed with ReturnCode ${returnCode}` + (returnMessage ? `: ${returnMessage}` : ".")
+    );
+    this.name = "DivoomCloudError";
+    this.returnCode = returnCode;
+    this.endpoint = endpoint;
+    this.returnMessage = returnMessage;
+  }
+};
+var DivoomDeviceError = class extends DivoomError {
+  /** The non-zero `error_code` reported by the device. */
+  errorCode;
+  /** The command that was rejected. */
+  command;
+  /** The raw response body returned by the device. */
+  response;
+  constructor(errorCode, command, response) {
+    super(
+      `Times Gate rejected command "${command}" with error_code ${errorCode}. This often means the LocalToken is missing or incorrect for a command that requires it.`
+    );
+    this.name = "DivoomDeviceError";
+    this.errorCode = errorCode;
+    this.command = command;
+    this.response = response;
+  }
+};
+
+// src/constants.ts
+var PANEL_COUNT = 5;
+var PANEL_SIZE = 128;
+var DEFAULT_PORT = 80;
+var DEFAULT_PATH = "/post";
+var HARDWARE_402_PORT = 9e3;
+var HARDWARE_402_PATH = "/divoom_api";
+var LAN_DISCOVERY_URL = "https://app.divoom-gz.com/Device/ReturnSameLANDevice";
+
+// src/utils.ts
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function drainBody(response) {
+  try {
+    await response.body?.cancel?.();
+  } catch {
+  }
+}
+function assertIntInRange(value, min, max, label) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new DivoomValidationError(
+      `${label} must be an integer between ${min} and ${max} (received ${String(value)}).`
+    );
+  }
+}
+function assertPanelIndex(value) {
+  if (!Number.isInteger(value) || value < 0 || value >= PANEL_COUNT) {
+    throw new DivoomValidationError(
+      `panel must be an integer between 0 and ${PANEL_COUNT - 1} (received ${String(value)}).`
+    );
+  }
+}
+function assertNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new DivoomValidationError(`${label} must be a non-empty string.`);
+  }
+}
+function panelToLcdArray(panel) {
+  assertPanelIndex(panel);
+  const arr = [0, 0, 0, 0, 0];
+  arr[panel] = 1;
+  return arr;
+}
+function panelsToLcdArray(panels) {
+  const arr = [0, 0, 0, 0, 0];
+  for (const panel of panels) {
+    assertPanelIndex(panel);
+    arr[panel] = 1;
+  }
+  return arr;
+}
+var PicIdGenerator = class {
+  base;
+  constructor(seed = Math.floor(Date.now() / 1e3)) {
+    this.base = seed;
+  }
+  /** Returns the next unique PicID for the given panel. */
+  next(panel = 0) {
+    this.base += 10;
+    return this.base + panel;
+  }
+};
+
+// src/commands/animation.ts
+var DIRECTION = { left: 0, right: 1 };
+var ALIGN = { left: 1, center: 2, right: 3 };
+var AnimationCommands = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Plays a stored Divoom GIF (by `FileId`) on the given panels
+   * (`Draw/SendRemote`). Obtain `fileId` from
+   * {@link DivoomCloudClient.getLikedImages} or
+   * {@link DivoomCloudClient.getUploadedImages}.
+   */
+  async playStoredGif(panels, fileId) {
+    assertNonEmptyString(fileId, "fileId");
+    if (panels.length === 0) {
+      throw new DivoomValidationError("playStoredGif requires at least one panel.");
+    }
+    panels.forEach(assertPanelIndex);
+    return this.transport.send({
+      Command: "Draw/SendRemote",
+      FileId: fileId,
+      LcdArray: panelsToLcdArray(panels)
+    });
+  }
+  /**
+   * Plays one or more GIF URLs on the given panels (`Device/PlayGif`).
+   *
+   * @param urls - Up to 10 GIF URLs (dimensions 16/32/64/128).
+   */
+  async playGifUrls(panels, urls) {
+    if (panels.length === 0) {
+      throw new DivoomValidationError("playGifUrls requires at least one panel.");
+    }
+    panels.forEach(assertPanelIndex);
+    if (urls.length === 0 || urls.length > 10) {
+      throw new DivoomValidationError(`playGifUrls accepts 1\u201310 URLs (received ${urls.length}).`);
+    }
+    return this.transport.send({
+      Command: "Device/PlayGif",
+      LcdArray: panelsToLcdArray(panels),
+      FileName: urls
+    });
+  }
+  /**
+   * 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'],
+   * });
+   * ```
+   */
+  async playGifPerPanel(perPanel) {
+    const payload = { Command: "Device/PlayGifLCDs" };
+    let any = false;
+    for (let panel = 0; panel < 5; panel += 1) {
+      const urls = perPanel[panel];
+      if (urls && urls.length > 0) {
+        payload[`LCD${panel}GifFile`] = urls;
+        any = true;
+      }
+    }
+    if (!any) {
+      throw new DivoomValidationError("playGifPerPanel requires URLs for at least one panel.");
+    }
+    return this.transport.send(payload);
+  }
+  /**
+   * 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).
+   */
+  async sendText(panel, text, options = {}) {
+    assertPanelIndex(panel);
+    assertNonEmptyString(text, "text");
+    if (options.textId !== void 0) assertIntInRange(options.textId, 0, 19, "textId");
+    if (options.font !== void 0) assertIntInRange(options.font, 0, 7, "font");
+    if (options.width !== void 0) assertIntInRange(options.width, 16, 64, "width");
+    return this.transport.send({
+      Command: "Draw/SendHttpText",
+      LcdIndex: panel,
+      TextId: options.textId ?? 1,
+      x: options.x ?? 0,
+      y: options.y ?? 40,
+      dir: DIRECTION[options.direction ?? "left"],
+      font: options.font ?? 4,
+      TextWidth: options.width ?? 56,
+      speed: options.speed ?? 100,
+      TextString: text,
+      color: options.color ?? "#FFFFFF",
+      align: ALIGN[options.align ?? "left"]
+    });
+  }
+  /**
+   * 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.
+   */
+  async sendItemList(panel, items, options = {}) {
+    assertPanelIndex(panel);
+    if (items.length === 0) {
+      throw new DivoomValidationError("sendItemList requires at least one item.");
+    }
+    const payload = {
+      Command: "Draw/SendHttpItemList",
+      LcdIndex: panel,
+      NewFlag: options.replace === false ? 0 : 1,
+      ItemList: items
+    };
+    if (options.backgroundGif !== void 0) {
+      payload.BackgroudGif = options.backgroundGif;
+    }
+    return this.transport.send(payload);
+  }
+};
+
+// src/commands/batch.ts
+var BatchCommands = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * 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) {
+    return this.transport.send({ Command: "Draw/CommandList", CommandList: commands });
+  }
+  /**
+   * Tells the device to fetch and execute a command-array file from a URL
+   * (`Draw/UseHTTPCommandSource`).
+   */
+  async useCommandSource(commandUrl) {
+    assertNonEmptyString(commandUrl, "commandUrl");
+    return this.transport.send({ Command: "Draw/UseHTTPCommandSource", CommandUrl: commandUrl });
+  }
+};
+
+// src/commands/dial.ts
+var DialCommands = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Selects a "whole" dial that spans all five panels
+   * (`Channel/Set5LcdWholeClockId`).
+   *
+   * @param clockId - A whole-dial id from
+   *   {@link DivoomCloudClient.getWholeDialList}.
+   */
+  selectWholeDial(clockId) {
+    return this.transport.send({ Command: "Channel/Set5LcdWholeClockId", ClockId: clockId });
+  }
+  /**
+   * 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}.
+   */
+  async setChannelMode(mode, lcdIndependence) {
+    if (mode === "independent" && lcdIndependence === void 0) {
+      throw new DivoomValidationError(
+        "setChannelMode('independent') requires an lcdIndependence id (from DivoomCloudClient.getChannelInfo)."
+      );
+    }
+    const payload = {
+      Command: "Channel/Set5LcdChannelType",
+      ChannelType: mode === "independent" ? 1 : 0
+    };
+    if (lcdIndependence !== void 0) {
+      payload.LcdIndependence = lcdIndependence;
+    }
+    return this.transport.send(payload);
+  }
+  /**
+   * 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}.
+   */
+  async selectSubDial(panel, clockId, lcdIndependence) {
+    assertPanelIndex(panel);
+    return this.transport.send({
+      Command: "Channel/SetClockSelectId",
+      ClockId: clockId,
+      LcdIndex: panel,
+      LcdIndependence: lcdIndependence
+    });
+  }
+  /**
+   * 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}.
+   */
+  async selectVisualizer(panel, eqPosition, lcdIndependence) {
+    assertPanelIndex(panel);
+    return this.transport.send({
+      Command: "Channel/SetEqPosition",
+      EqPosition: eqPosition,
+      LcdIndex: panel,
+      LcdIndependence: lcdIndependence
+    });
+  }
+  /** Reads the currently-selected channel index (`Channel/GetIndex`). */
+  getIndex() {
+    return this.transport.send({ Command: "Channel/GetIndex" });
+  }
+};
+
+// src/commands/draw.ts
+var MAX_FRAMES = 59;
+var DrawCommands = class {
+  constructor(transport, picIdSeed) {
+    this.transport = transport;
+    this.picIds = new PicIdGenerator(picIdSeed);
+  }
+  transport;
+  picIds;
+  /**
+   * 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);
+   * ```
+   */
+  async sendImage(panel, picData, options = {}) {
+    assertPanelIndex(panel);
+    return this.pushStill(panelToLcdArray(panel), picData, panel, options);
+  }
+  /**
+   * Pushes the same still image to several panels at once.
+   *
+   * @param panels - Panel indices to target.
+   * @param picData - Base64-encoded JPEG/PNG.
+   */
+  async sendImageToPanels(panels, picData, options = {}) {
+    if (panels.length === 0) {
+      throw new DivoomValidationError("sendImageToPanels requires at least one panel.");
+    }
+    panels.forEach(assertPanelIndex);
+    return this.pushStill(panelsToLcdArray(panels), picData, panels[0] ?? 0, options);
+  }
+  /**
+   * 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.
+   */
+  async sendAnimation(panels, frames, options = {}) {
+    if (panels.length === 0) {
+      throw new DivoomValidationError("sendAnimation requires at least one panel.");
+    }
+    panels.forEach(assertPanelIndex);
+    if (frames.length === 0) {
+      throw new DivoomValidationError("sendAnimation requires at least one frame.");
+    }
+    if (frames.length > MAX_FRAMES) {
+      throw new DivoomValidationError(
+        `An animation may contain at most ${MAX_FRAMES} frames (received ${frames.length}).`
+      );
+    }
+    const lcdArray = panelsToLcdArray(panels);
+    const picId = options.picId ?? this.picIds.next(panels[0] ?? 0);
+    const picWidth = options.picWidth ?? PANEL_SIZE;
+    const picSpeed = options.picSpeed ?? 100;
+    const responses = [];
+    for (let offset = 0; offset < frames.length; offset += 1) {
+      responses.push(
+        await this.sendFrame({
+          LcdArray: lcdArray,
+          PicNum: frames.length,
+          PicWidth: picWidth,
+          PicOffset: offset,
+          PicID: picId,
+          PicSpeed: picSpeed,
+          PicData: frames[offset] ?? ""
+        })
+      );
+    }
+    return responses;
+  }
+  /** Sends a fully-specified `Draw/SendHttpGif` frame — maximum control. */
+  sendFrame(request) {
+    return this.transport.send({ Command: "Draw/SendHttpGif", ...request });
+  }
+  /** Clears the device's image cache and resets the PicID counter (`Draw/ResetHttpGifId`). */
+  resetCache() {
+    return this.transport.send({ Command: "Draw/ResetHttpGifId" });
+  }
+  /** Reads the device's current PicID (`Draw/GetHttpGifId`). */
+  async getPicId() {
+    const response = await this.transport.send({ Command: "Draw/GetHttpGifId" });
+    if (typeof response.PicId !== "number") {
+      throw new DivoomError("Draw/GetHttpGifId did not return a numeric PicId.");
+    }
+    return response.PicId;
+  }
+  /** Returns the next locally-generated, strictly-increasing PicID. */
+  nextPicId(panel = 0) {
+    return this.picIds.next(panel);
+  }
+  pushStill(lcdArray, picData, offsetPanel, options) {
+    return this.sendFrame({
+      LcdArray: lcdArray,
+      PicNum: 1,
+      PicWidth: options.picWidth ?? PANEL_SIZE,
+      PicOffset: 0,
+      PicID: options.picId ?? this.picIds.next(offsetPanel),
+      PicSpeed: options.picSpeed ?? 1e3,
+      PicData: picData
+    });
+  }
+};
+
+// src/commands/system.ts
+var SystemCommands = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Sets the LCD brightness (`Channel/SetBrightness`). @param brightness 0–100. */
+  async setBrightness(brightness) {
+    assertIntInRange(brightness, 0, 100, "brightness");
+    return this.transport.send({ Command: "Channel/SetBrightness", Brightness: brightness });
+  }
+  /** Reads every device setting (`Channel/GetAllConf`). */
+  getAllConfig() {
+    return this.transport.send({ Command: "Channel/GetAllConf" });
+  }
+  /** Turns the screen on or off (`Channel/OnOffScreen`). */
+  setScreen(on) {
+    return this.transport.send({ Command: "Channel/OnOffScreen", OnOff: on ? 1 : 0 });
+  }
+  /**
+   * Sets the weather location (`Sys/LogAndLat`). Coordinates drive the on-device
+   * weather readout.
+   */
+  setWeatherLocation(longitude, latitude) {
+    return this.transport.send({
+      Command: "Sys/LogAndLat",
+      Longitude: String(longitude),
+      Latitude: String(latitude)
+    });
+  }
+  /** Sets the time zone (`Sys/TimeZone`). @param timeZone e.g. `"GMT-5"`. */
+  async setTimeZone(timeZone) {
+    assertNonEmptyString(timeZone, "timeZone");
+    return this.transport.send({ Command: "Sys/TimeZone", TimeZoneValue: timeZone });
+  }
+  /**
+   * Sets the system clock (`Device/SetUTC`).
+   *
+   * @param time - A `Date` or a UTC epoch in **seconds**.
+   */
+  async setSystemTime(time) {
+    const utc = time instanceof Date ? Math.floor(time.getTime() / 1e3) : Math.floor(time);
+    if (!Number.isFinite(utc)) {
+      throw new DivoomValidationError(
+        "setSystemTime requires a valid Date or a finite epoch-seconds number."
+      );
+    }
+    return this.transport.send({ Command: "Device/SetUTC", Utc: utc });
+  }
+  /** Reads the device's UTC and local time (`Device/GetDeviceTime`). */
+  getDeviceTime() {
+    return this.transport.send({ Command: "Device/GetDeviceTime" });
+  }
+  /** Sets the temperature unit (`Device/SetDisTempMode`). */
+  setTemperatureMode(unit) {
+    return this.transport.send({
+      Command: "Device/SetDisTempMode",
+      Mode: unit === "fahrenheit" ? 1 : 0
+    });
+  }
+  /** Enables or disables mirror mode (`Device/SetMirrorMode`). */
+  setMirrorMode(enabled) {
+    return this.transport.send({ Command: "Device/SetMirrorMode", Mode: enabled ? 1 : 0 });
+  }
+  /** Selects 24-hour (`true`) or 12-hour (`false`) clock (`Device/SetTime24Flag`). */
+  setHourMode(use24Hour) {
+    return this.transport.send({ Command: "Device/SetTime24Flag", Mode: use24Hour ? 1 : 0 });
+  }
+  /** Reads the current on-device weather (`Device/GetWeatherInfo`). */
+  getWeather() {
+    return this.transport.send({ Command: "Device/GetWeatherInfo" });
+  }
+};
+
+// src/commands/tool.ts
+var STOPWATCH_STATUS = { stop: 0, start: 1, reset: 2 };
+var ToolCommands = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * 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`.
+   */
+  async setCountdown(minutes, seconds, start = true) {
+    assertIntInRange(minutes, 0, 99, "minutes");
+    assertIntInRange(seconds, 0, 59, "seconds");
+    return this.transport.send({
+      Command: "Tools/SetTimer",
+      Minute: minutes,
+      Second: seconds,
+      Status: start ? 1 : 0
+    });
+  }
+  /** Controls the stopwatch (`Tools/SetStopWatch`). */
+  setStopwatch(action) {
+    return this.transport.send({ Command: "Tools/SetStopWatch", Status: STOPWATCH_STATUS[action] });
+  }
+  /**
+   * Sets the scoreboard (`Tools/SetScoreBoard`).
+   *
+   * @param redScore - Red team score (0–999).
+   * @param blueScore - Blue team score (0–999).
+   */
+  async setScoreboard(redScore, blueScore) {
+    assertIntInRange(redScore, 0, 999, "redScore");
+    assertIntInRange(blueScore, 0, 999, "blueScore");
+    return this.transport.send({
+      Command: "Tools/SetScoreBoard",
+      RedScore: redScore,
+      BlueScore: blueScore
+    });
+  }
+  /** Starts or stops the noise meter (`Tools/SetNoiseStatus`). */
+  setNoiseMeter(start) {
+    return this.transport.send({ Command: "Tools/SetNoiseStatus", NoiseStatus: start ? 1 : 0 });
+  }
+  /**
+   * Plays the buzzer (`Device/PlayBuzzer`). Requires firmware ≥ 90109.
+   *
+   * @example
+   * ```ts
+   * await client.tool.playBuzzer({ activeMs: 200, offMs: 100, totalMs: 900 });
+   * ```
+   */
+  async playBuzzer(options = {}) {
+    const activeMs = options.activeMs ?? 500;
+    const offMs = options.offMs ?? 500;
+    const totalMs = options.totalMs ?? 1e3;
+    assertIntInRange(activeMs, 0, 36e5, "activeMs");
+    assertIntInRange(offMs, 0, 36e5, "offMs");
+    assertIntInRange(totalMs, 0, 36e5, "totalMs");
+    return this.transport.send({
+      Command: "Device/PlayBuzzer",
+      ActiveTimeInCycle: activeMs,
+      OffTimeInCycle: offMs,
+      PlayTotalTime: totalMs
+    });
+  }
+};
+
+// src/transport.ts
+var DEFAULTS = {
+  port: DEFAULT_PORT,
+  path: DEFAULT_PATH,
+  protocol: "http",
+  localToken: 0,
+  timeoutMs: 8e3,
+  retries: 2,
+  retryDelayMs: 300
+};
+var HttpTransport = class {
+  /** The fully-resolved endpoint URL every request is POSTed to. */
+  endpoint;
+  localToken;
+  timeoutMs;
+  retries;
+  retryDelayMs;
+  fetchImpl;
+  headers;
+  constructor(options) {
+    const host = options.host?.trim();
+    if (!host) {
+      throw new DivoomValidationError("A device `host` (IP address or hostname) is required.");
+    }
+    if (/[\s/\\?#@]/.test(host)) {
+      throw new DivoomValidationError(
+        `Invalid device host "${host}": expected a bare IP address or hostname.`
+      );
+    }
+    const port = options.port ?? DEFAULTS.port;
+    const rawPath = options.path ?? DEFAULTS.path;
+    const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+    const protocol = options.protocol ?? DEFAULTS.protocol;
+    this.endpoint = `${protocol}://${host}:${port}${path}`;
+    this.localToken = options.localToken ?? DEFAULTS.localToken;
+    this.timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
+    this.retries = Math.max(0, options.retries ?? DEFAULTS.retries);
+    this.retryDelayMs = options.retryDelayMs ?? DEFAULTS.retryDelayMs;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.headers = { "Content-Type": "application/json", ...options.headers };
+    if (typeof this.fetchImpl !== "function") {
+      throw new DivoomValidationError(
+        "No `fetch` implementation is available. Use Node 18+ or pass a custom `fetch`."
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async send(payload) {
+    const body = JSON.stringify({ LocalToken: this.localToken, ...payload });
+    let lastError;
+    for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+      if (attempt > 0) {
+        await delay(this.retryDelayMs * 2 ** (attempt - 1));
+      }
+      try {
+        return await this.attempt(body, payload.Command);
+      } catch (error) {
+        lastError = error;
+        if (!isRetryable(error)) {
+          throw error;
+        }
+      }
+    }
+    throw lastError;
+  }
+  async attempt(body, command) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      let response;
+      try {
+        response = await this.fetchImpl(this.endpoint, {
+          method: "POST",
+          headers: this.headers,
+          body,
+          signal: controller.signal
+        });
+      } catch (error) {
+        if (controller.signal.aborted) {
+          throw new DivoomTimeoutError(command, this.timeoutMs);
+        }
+        throw new DivoomConnectionError(`Failed to reach Times Gate at ${this.endpoint}.`, {
+          cause: error
+        });
+      }
+      if (!response.ok) {
+        await drainBody(response);
+        throw new DivoomHttpError(response.status, command, this.endpoint);
+      }
+      let text;
+      try {
+        text = await response.text();
+      } catch (error) {
+        if (controller.signal.aborted) {
+          throw new DivoomTimeoutError(command, this.timeoutMs);
+        }
+        throw new DivoomConnectionError(
+          `Failed to read the response body from Times Gate for command "${command}".`,
+          { cause: error }
+        );
+      }
+      const data = parseDeviceBody(text, command);
+      if (typeof data.error_code === "number" && data.error_code !== 0) {
+        throw new DivoomDeviceError(data.error_code, command, data);
+      }
+      return data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function parseDeviceBody(text, command) {
+  if (text.trim() === "") {
+    return { error_code: 0 };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new DivoomConnectionError(
+      `Times Gate returned a malformed (non-JSON) response for command "${command}".`,
+      { cause: error }
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new DivoomConnectionError(
+      `Times Gate returned an unexpected (non-object) response for command "${command}".`
+    );
+  }
+  return parsed;
+}
+function isRetryable(error) {
+  if (error instanceof DivoomTimeoutError || error instanceof DivoomConnectionError) {
+    return true;
+  }
+  if (error instanceof DivoomHttpError) {
+    return error.status >= 500;
+  }
+  return false;
+}
+
+// src/client.ts
+var TimesGateClient = class {
+  /** The underlying HTTP transport. */
+  transport;
+  /** System settings: brightness, screen, time, weather, display modes. */
+  system;
+  /** Dial/channel control: whole vs independent dials, sub-dials, visualizers. */
+  dial;
+  /** Built-in tools: countdown, stopwatch, scoreboard, noise meter, buzzer. */
+  tool;
+  /** The image pipeline: push frames/animations, manage the device cache. */
+  draw;
+  /** Animations & text: stored GIFs, GIF URLs, text overlays, item lists. */
+  animation;
+  /** Batch execution: run multiple commands or a remote command list. */
+  batch;
+  constructor(options) {
+    this.transport = new HttpTransport(options);
+    this.system = new SystemCommands(this.transport);
+    this.dial = new DialCommands(this.transport);
+    this.tool = new ToolCommands(this.transport);
+    this.draw = new DrawCommands(this.transport, options.picIdSeed);
+    this.animation = new AnimationCommands(this.transport);
+    this.batch = new BatchCommands(this.transport);
+  }
+  /** The resolved endpoint URL this client talks to. */
+  get endpoint() {
+    return this.transport.endpoint;
+  }
+  /**
+   * Sends a raw command payload — an escape hatch for commands the typed API
+   * doesn't cover yet. The configured `LocalToken` is still injected.
+   */
+  send(payload) {
+    return this.transport.send(payload);
+  }
+  /**
+   * Checks whether the device is reachable by issuing `Channel/GetIndex`.
+   * Returns `false` instead of throwing on failure.
+   */
+  async ping() {
+    try {
+      await this.dial.getIndex();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/cloud.ts
+var DEFAULT_CLOUD_BASE_URL = "https://app.divoom-gz.com";
+function parseCloudBody(text, url) {
+  if (text.trim() === "") {
+    return { ReturnCode: 0 };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new DivoomConnectionError(
+      `Cloud endpoint ${url} returned a malformed (non-JSON) response.`,
+      {
+        cause: error
+      }
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new DivoomConnectionError(
+      `Cloud endpoint ${url} returned an unexpected (non-object) response.`
+    );
+  }
+  return parsed;
+}
+async function cloudPost(url, body, options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const retries = Math.max(0, options.retries ?? 2);
+  const retryDelayMs = options.retryDelayMs ?? 300;
+  const headers = { "Content-Type": "application/json", ...options.headers };
+  const payload = JSON.stringify(body);
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    if (attempt > 0) await delay(retryDelayMs * 2 ** (attempt - 1));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: payload,
+        signal: controller.signal
+      });
+    } catch (error) {
+      lastError = controller.signal.aborted ? new DivoomTimeoutError(url, timeoutMs) : new DivoomConnectionError(`Failed to reach cloud endpoint ${url}.`, { cause: error });
+      continue;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      await drainBody(response);
+      const httpError = new DivoomConnectionError(
+        `Cloud request to ${url} failed: HTTP ${response.status}.`
+      );
+      if (response.status < 500) throw httpError;
+      lastError = httpError;
+      continue;
+    }
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      lastError = new DivoomConnectionError(`Failed to read cloud response body from ${url}.`, {
+        cause: error
+      });
+      continue;
+    }
+    let data;
+    try {
+      data = parseCloudBody(text, url);
+    } catch (error) {
+      lastError = error;
+      continue;
+    }
+    if (typeof data.ReturnCode === "number" && data.ReturnCode !== 0) {
+      throw new DivoomCloudError(data.ReturnCode, url, data.ReturnMessage);
+    }
+    return data;
+  }
+  throw lastError instanceof Error ? lastError : new DivoomConnectionError(`Cloud request to ${url} failed.`);
+}
+var DivoomCloudClient = class {
+  baseUrl;
+  options;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_CLOUD_BASE_URL).replace(/\/$/, "");
+    this.options = options;
+  }
+  post(path, body = {}) {
+    return cloudPost(`${this.baseUrl}${path}`, body, this.options);
+  }
+  /** Lists sub-dial category names (`Channel/GetDialType`). */
+  getDialTypes() {
+    return this.post("/Channel/GetDialType");
+  }
+  /** Lists sub-dials in a category, paged 30 at a time (`Channel/GetDialList`). */
+  getDialList(dialType, page = 1, deviceType = "LCD") {
+    return this.post("/Channel/GetDialList", {
+      DialType: dialType,
+      DeviceType: deviceType,
+      Page: page
+    });
+  }
+  /** Lists whole (5-panel) dials, paged (`Channel/Get5LcdClockListForCommon`). */
+  getWholeDialList(page = 1) {
+    return this.post("/Channel/Get5LcdClockListForCommon", { Page: page });
+  }
+  /** Gets channel info incl. independent dial groups (`Channel/Get5LcdInfoV2`). */
+  getChannelInfo(deviceId, deviceType = "LCD") {
+    return this.post("/Channel/Get5LcdInfoV2", {
+      DeviceId: deviceId,
+      DeviceType: deviceType
+    });
+  }
+  /** Lists the account's liked images (`Device/GetImgLikeList`). */
+  getLikedImages(deviceId, deviceMac, page = 1) {
+    return this.post("/Device/GetImgLikeList", {
+      DeviceId: deviceId,
+      DeviceMac: deviceMac,
+      Page: page
+    });
+  }
+  /** Lists the account's uploaded images (`Device/GetImgUploadList`). */
+  getUploadedImages(deviceId, deviceMac, page = 1) {
+    return this.post("/Device/GetImgUploadList", {
+      DeviceId: deviceId,
+      DeviceMac: deviceMac,
+      Page: page
+    });
+  }
+  /** Lists fonts usable in {@link AnimationCommands.sendItemList} (`Device/GetTimeDialFontList`). */
+  getFontList() {
+    return this.post("/Device/GetTimeDialFontList");
+  }
+};
+
+// src/discovery.ts
+async function discoverDevices(options = {}) {
+  const response = await cloudPost(LAN_DISCOVERY_URL, {}, options);
+  return (response.DeviceList ?? []).map((device) => ({
+    name: device.DeviceName ?? "",
+    id: device.DeviceId ?? 0,
+    ip: device.DevicePrivateIP ?? "",
+    mac: device.DeviceMac ?? ""
+  }));
+}
+
+export { AnimationCommands, BatchCommands, DEFAULT_CLOUD_BASE_URL, DEFAULT_PATH, DEFAULT_PORT, DialCommands, DivoomCloudClient, DivoomCloudError, DivoomConnectionError, DivoomDeviceError, DivoomError, DivoomHttpError, DivoomTimeoutError, DivoomValidationError, DrawCommands, HARDWARE_402_PATH, HARDWARE_402_PORT, HttpTransport, LAN_DISCOVERY_URL, PANEL_COUNT, PANEL_SIZE, PicIdGenerator, SystemCommands, TimesGateClient, ToolCommands, cloudPost, discoverDevices, panelToLcdArray, panelsToLcdArray };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map