@switchbot/openapi-cli 3.4.1 → 3.5.0

package/README.md

@@ -63,7 +63,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 2225 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 2263 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements

package/dist/index.js

@@ -8380,9 +8380,8 @@ function updateCacheFromDeviceList(body) {
   for (const d of body.deviceList) {
     if (!d.deviceId) continue;
     devices[d.deviceId] = {
-      // Some real devices omit deviceType entirely (for example AI accessories).
-      // Keep them in cache with an empty type string rather than dropping the row.
-      type: d.deviceType ?? "",
+      type: d.deviceType || d.controlType || "Unknown Device",
+      typeSource: d.deviceType ? "deviceType" : d.controlType ? "controlType" : "deviceType",
       name: d.deviceName,
       category: "physical",
       hubDeviceId: d.hubDeviceId,
@@ -8397,6 +8396,7 @@ function updateCacheFromDeviceList(body) {
     if (!d.deviceId) continue;
     devices[d.deviceId] = {
       type: d.remoteType,
+      typeSource: "remoteType",
       name: d.deviceName,
       category: "ir",
       hubDeviceId: d.hubDeviceId,
@@ -8793,10 +8793,11 @@ async function fetchDeviceList(client, options = {}) {
       const infraredRemoteList = [];
       for (const [deviceId, entry] of Object.entries(cached2.devices)) {
         if (entry.category === "physical") {
+          const cachedDeviceType = entry.typeSource === "deviceType" ? entry.type : entry.typeSource === void 0 && entry.type !== entry.controlType ? entry.type : void 0;
           deviceList.push({
             deviceId,
             deviceName: entry.name,
-            ...entry.type ? { deviceType: entry.type } : {},
+            ...cachedDeviceType && cachedDeviceType !== "Unknown Device" ? { deviceType: cachedDeviceType } : {},
             enableCloudService: entry.enableCloudService ?? true,
             hubDeviceId: entry.hubDeviceId ?? "",
             roomID: entry.roomID,
@@ -8867,10 +8868,12 @@ async function executeCommand(deviceId, cmd, parameter, commandType, client, opt
       if (err instanceof Error && err.name === "DryRunSignal") {
         writeAudit({ ...baseAudit, result: "dry-run" });
       } else {
+        const statusCode = err instanceof ApiError ? err.code : void 0;
         writeAudit({
           ...baseAudit,
           result: "error",
-          error: err instanceof Error ? err.message : String(err)
+          error: err instanceof Error ? err.message : String(err),
+          ...statusCode !== void 0 ? { statusCode } : {}
         });
       }
       throw err;
@@ -8991,7 +8994,23 @@ async function describeDevice(deviceId, options = {}, client) {
     ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
   }
   if (!physical && !ir) throw new DeviceNotFoundError(deviceId);
-  const typeName = physical ? physical.deviceType ?? "" : ir.remoteType;
+  let typeName;
+  let typeSource;
+  if (physical) {
+    if (physical.deviceType) {
+      typeName = physical.deviceType;
+      typeSource = "deviceType";
+    } else if (physical.controlType) {
+      typeName = physical.controlType;
+      typeSource = "controlType";
+    } else {
+      typeName = "Unknown Device";
+      typeSource = "deviceType";
+    }
+  } else {
+    typeName = ir.remoteType;
+    typeSource = "remoteType";
+  }
   const match = typeName ? findCatalogEntry(typeName) : null;
   const catalogEntry = !match || Array.isArray(match) ? null : match;
   let liveStatus;
@@ -9027,6 +9046,7 @@ async function describeDevice(deviceId, options = {}, client) {
     device: selectedDevice,
     isPhysical: Boolean(physical),
     typeName,
+    typeSource,
     controlType: physical?.controlType ?? ir?.controlType ?? null,
     catalog: catalogEntry,
     capabilities,
@@ -31710,6 +31730,161 @@ function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation) {
 // src/devices/param-validator.ts
 init_cjs_shim();
 init_output();
+
+// src/devices/css-colors.ts
+init_cjs_shim();
+var CSS_COLORS = {
+  aliceblue: [240, 248, 255],
+  antiquewhite: [250, 235, 215],
+  aqua: [0, 255, 255],
+  aquamarine: [127, 255, 212],
+  azure: [240, 255, 255],
+  beige: [245, 245, 220],
+  bisque: [255, 228, 196],
+  black: [0, 0, 0],
+  blanchedalmond: [255, 235, 205],
+  blue: [0, 0, 255],
+  blueviolet: [138, 43, 226],
+  brown: [165, 42, 42],
+  burlywood: [222, 184, 135],
+  cadetblue: [95, 158, 160],
+  chartreuse: [127, 255, 0],
+  chocolate: [210, 105, 30],
+  coral: [255, 127, 80],
+  cornflowerblue: [100, 149, 237],
+  cornsilk: [255, 248, 220],
+  crimson: [220, 20, 60],
+  cyan: [0, 255, 255],
+  darkblue: [0, 0, 139],
+  darkcyan: [0, 139, 139],
+  darkgoldenrod: [184, 134, 11],
+  darkgray: [169, 169, 169],
+  darkgreen: [0, 100, 0],
+  darkgrey: [169, 169, 169],
+  darkkhaki: [189, 183, 107],
+  darkmagenta: [139, 0, 139],
+  darkolivegreen: [85, 107, 47],
+  darkorange: [255, 140, 0],
+  darkorchid: [153, 50, 204],
+  darkred: [139, 0, 0],
+  darksalmon: [233, 150, 122],
+  darkseagreen: [143, 188, 143],
+  darkslateblue: [72, 61, 139],
+  darkslategray: [47, 79, 79],
+  darkslategrey: [47, 79, 79],
+  darkturquoise: [0, 206, 209],
+  darkviolet: [148, 0, 211],
+  deeppink: [255, 20, 147],
+  deepskyblue: [0, 191, 255],
+  dimgray: [105, 105, 105],
+  dimgrey: [105, 105, 105],
+  dodgerblue: [30, 144, 255],
+  firebrick: [178, 34, 34],
+  floralwhite: [255, 250, 240],
+  forestgreen: [34, 139, 34],
+  fuchsia: [255, 0, 255],
+  gainsboro: [220, 220, 220],
+  ghostwhite: [248, 248, 255],
+  gold: [255, 215, 0],
+  goldenrod: [218, 165, 32],
+  gray: [128, 128, 128],
+  green: [0, 128, 0],
+  greenyellow: [173, 255, 47],
+  grey: [128, 128, 128],
+  honeydew: [240, 255, 240],
+  hotpink: [255, 105, 180],
+  indianred: [205, 92, 92],
+  indigo: [75, 0, 130],
+  ivory: [255, 255, 240],
+  khaki: [240, 230, 140],
+  lavender: [230, 230, 250],
+  lavenderblush: [255, 240, 245],
+  lawngreen: [124, 252, 0],
+  lemonchiffon: [255, 250, 205],
+  lightblue: [173, 216, 230],
+  lightcoral: [240, 128, 128],
+  lightcyan: [224, 255, 255],
+  lightgoldenrodyellow: [250, 250, 210],
+  lightgray: [211, 211, 211],
+  lightgreen: [144, 238, 144],
+  lightgrey: [211, 211, 211],
+  lightpink: [255, 182, 193],
+  lightsalmon: [255, 160, 122],
+  lightseagreen: [32, 178, 170],
+  lightskyblue: [135, 206, 250],
+  lightslategray: [119, 136, 153],
+  lightslategrey: [119, 136, 153],
+  lightsteelblue: [176, 196, 222],
+  lightyellow: [255, 255, 224],
+  lime: [0, 255, 0],
+  limegreen: [50, 205, 50],
+  linen: [250, 240, 230],
+  magenta: [255, 0, 255],
+  maroon: [128, 0, 0],
+  mediumaquamarine: [102, 205, 170],
+  mediumblue: [0, 0, 205],
+  mediumorchid: [186, 85, 211],
+  mediumpurple: [147, 111, 219],
+  mediumseagreen: [60, 179, 113],
+  mediumslateblue: [123, 104, 238],
+  mediumspringgreen: [0, 250, 154],
+  mediumturquoise: [72, 209, 204],
+  mediumvioletred: [199, 21, 133],
+  midnightblue: [25, 25, 112],
+  mintcream: [245, 255, 250],
+  mistyrose: [255, 228, 225],
+  moccasin: [255, 228, 181],
+  navajowhite: [255, 222, 173],
+  navy: [0, 0, 128],
+  oldlace: [253, 245, 230],
+  olive: [128, 128, 0],
+  olivedrab: [107, 142, 35],
+  orange: [255, 165, 0],
+  orangered: [255, 69, 0],
+  orchid: [218, 112, 214],
+  palegoldenrod: [238, 232, 170],
+  palegreen: [152, 251, 152],
+  paleturquoise: [175, 238, 238],
+  palevioletred: [219, 112, 147],
+  papayawhip: [255, 239, 213],
+  peachpuff: [255, 218, 185],
+  peru: [205, 133, 63],
+  pink: [255, 192, 203],
+  plum: [221, 160, 221],
+  powderblue: [176, 224, 230],
+  purple: [128, 0, 128],
+  rebeccapurple: [102, 51, 153],
+  red: [255, 0, 0],
+  rosybrown: [188, 143, 143],
+  royalblue: [65, 105, 225],
+  saddlebrown: [139, 69, 19],
+  salmon: [250, 128, 114],
+  sandybrown: [244, 164, 96],
+  seagreen: [46, 139, 87],
+  seashell: [255, 245, 238],
+  sienna: [160, 82, 45],
+  silver: [192, 192, 192],
+  skyblue: [135, 206, 235],
+  slateblue: [106, 90, 205],
+  slategray: [112, 128, 144],
+  slategrey: [112, 128, 144],
+  snow: [255, 250, 250],
+  springgreen: [0, 255, 127],
+  steelblue: [70, 130, 180],
+  tan: [210, 180, 140],
+  teal: [0, 128, 128],
+  thistle: [216, 191, 216],
+  tomato: [255, 99, 71],
+  turquoise: [64, 224, 208],
+  violet: [238, 130, 238],
+  wheat: [245, 222, 179],
+  white: [255, 255, 255],
+  whitesmoke: [245, 245, 245],
+  yellow: [255, 255, 0],
+  yellowgreen: [154, 205, 50]
+};
+
+// src/devices/param-validator.ts
 var AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
 var AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
 var CURTAIN_MODE_MAP = { default: "ff", performance: "0", silent: "1" };
@@ -31858,29 +32033,18 @@ function validateSetBrightness(raw) {
 function hintBrightnessRetry() {
   return `Ask the user whether they meant a percentage (1-100). Example: "50".`;
 }
-var NAMED_COLORS = {
-  red: [255, 0, 0],
-  green: [0, 128, 0],
-  lime: [0, 255, 0],
-  blue: [0, 0, 255],
-  yellow: [255, 255, 0],
-  cyan: [0, 255, 255],
-  magenta: [255, 0, 255],
-  white: [255, 255, 255],
-  black: [0, 0, 0],
-  orange: [255, 165, 0],
-  purple: [128, 0, 128],
-  pink: [255, 192, 203],
-  brown: [165, 42, 42],
-  grey: [128, 128, 128],
-  gray: [128, 128, 128],
+var CUSTOM_COLORS = {
   warm: [255, 180, 100]
 };
+var NAMED_COLORS = {
+  ...CSS_COLORS,
+  ...CUSTOM_COLORS
+};
 function validateSetColor(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
     return {
       ok: false,
-      error: `setColor requires a color. Expected one of: "R:G:B" (e.g. "255:0:0"), "#RRGGBB" (e.g. "#FF0000"), "#RGB", "R,G,B", or a named color (${Object.keys(NAMED_COLORS).slice(0, 8).join(", ")}, ...).`
+      error: `setColor requires a color. Use a CSS color name (e.g. coral, teal, salmon), hex (#RRGGBB / #RGB), or R:G:B format.`
     };
   }
   const trimmed = raw.trim();
@@ -32395,8 +32559,11 @@ Examples:
         }
         return;
       }
+      const totalDevices = resolved.ids.length;
+      const deviceIndices = new Map(resolved.ids.map((id, i) => [id, i + 1]));
       const startedAt = Date.now();
       const outcomes = await runPool(resolved.ids, concurrency, staggerMs, async (id) => {
+        const stepIdx = deviceIndices.get(id);
         const stepStart = Date.now();
         const startedIso = new Date(stepStart).toISOString();
         try {
@@ -32408,7 +32575,7 @@ Examples:
           const durationMs = Date.now() - stepStart;
           const replayed = typeof result2 === "object" && result2 !== null && result2.replayed === true;
           if (!isJsonMode()) {
-            console.log(`\u2713 ${id}: ${cmd}${replayed ? " (replayed)" : ""}`);
+            console.log(`[${stepIdx}/${totalDevices}] \u2713 ${id}: ${cmd}${replayed ? " (replayed)" : ""}`);
           }
           return {
             ok: true,
@@ -32431,7 +32598,7 @@ Examples:
           }
           const errorPayload = buildErrorPayload(err);
           if (!isJsonMode()) {
-            console.error(`\u2717 ${id}: ${errorPayload.message}`);
+            console.error(`[${stepIdx}/${totalDevices}] \u2717 ${id}: ${errorPayload.message}`);
           }
           return {
             ok: false,
@@ -32681,7 +32848,7 @@ function registerWatchCommand(devices) {
     `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1e3}s)`,
     durationArg("--interval"),
     "30s"
-  ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--for <dur>", 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg("--for")).option("--include-unchanged", "Emit a tick even when no field changed").option("--initial <mode>", "How to handle the first poll: snapshot | emit | skip (default: snapshot)", enumArg("--initial", INITIAL_MODES), "snapshot").addHelpText(
+  ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--once", "Stop after one tick (shorthand for --max 1)").option("--for <dur>", 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg("--for")).option("--include-unchanged", "Emit a tick even when no field changed").option("--initial <mode>", "How to handle the first poll: snapshot | emit | skip (default: snapshot)", enumArg("--initial", INITIAL_MODES), "snapshot").addHelpText(
     "after",
     `
 Default output is a human-readable table of field changes per tick; add --json
@@ -32710,6 +32877,12 @@ Examples:
   ).action(
     async (deviceIds, options) => {
       try {
+        if (options.once && options.max !== void 0) {
+          throw new UsageError("--once and --max are mutually exclusive.");
+        }
+        if (options.once) {
+          options.max = "1";
+        }
         const allIds = [...deviceIds];
         if (options.name) {
           const resolved = resolveDeviceId(void 0, options.name);
@@ -33258,13 +33431,16 @@ var EXPAND_HINTS = {
   "Relay Switch 2PM": { command: "setMode", flags: "--channel 1 --mode edge" }
 };
 function annotateStatusPayload(deviceId, body) {
-  const annotated = { ...body };
+  const cached2 = getCachedDevice(deviceId);
+  const deviceType = cached2?.type ?? "";
+  const annotated = { deviceId, deviceType, ...body };
+  annotated.deviceId = deviceId;
+  annotated.deviceType = deviceType;
   if (Object.keys(body).length === 0) {
     annotated.supported = false;
     annotated.note = "this device does not expose cloud status";
     return annotated;
   }
-  const cached2 = getCachedDevice(deviceId);
   const looksLikeMeter = cached2?.type?.toLowerCase().includes("meter") ?? false;
   const staleZeroReading = looksLikeMeter && !Object.prototype.hasOwnProperty.call(body, "onlineStatus") && body.battery === 0 && body.temperature === 0 && body.humidity === 0;
   if (staleZeroReading) {
@@ -33421,7 +33597,7 @@ Examples:
         rows.push([
           d.deviceId,
           d.deviceName,
-          d.deviceType || "\u2014",
+          d.deviceType || d.controlType || "Unknown Device",
           "physical",
           d.controlType || "\u2014",
           d.familyName || "\u2014",
@@ -33970,12 +34146,19 @@ Examples:
         });
         return;
       }
+      if (result.typeSource === "controlType") {
+        const deviceName2 = device.deviceName ?? deviceId;
+        console.error(`warning: ${deviceName2} (${deviceId}): deviceType not reported by API, using controlType "${result.controlType}". Capabilities may be limited.`);
+      } else if (typeName === "Unknown Device") {
+        const deviceName2 = device.deviceName ?? deviceId;
+        console.error(`warning: ${deviceName2} (${deviceId}): neither deviceType nor controlType reported by API. Capabilities may be limited.`);
+      }
       if (isPhysical) {
         const physical = device;
         printKeyValue({
           deviceId: physical.deviceId,
           deviceName: physical.deviceName,
-          deviceType: physical.deviceType || "\u2014",
+          deviceType: physical.deviceType || physical.controlType || "Unknown Device",
           controlType: physical.controlType || "\u2014",
           family: physical.familyName || "\u2014",
           roomID: physical.roomID || "\u2014",
@@ -34154,7 +34337,7 @@ Examples:
       handleError(error48);
     }
   });
-  scenes.command("execute").description("Execute a manual scene by its ID").argument("<sceneId>", 'Scene ID from "scenes list"').addHelpText("after", `
+  scenes.command("execute").alias("run").description("Execute a manual scene by its ID").argument("<sceneId>", 'Scene ID from "scenes list"').addHelpText("after", `
 Example:
   $ switchbot scenes execute T12345678
 `).action(async (sceneId) => {
@@ -49887,15 +50070,27 @@ against the live API without executing any mutations.
       handleError(err);
     }
   });
-  plan.command("run").description("Validate + preview/execute a plan. Respects --dry-run; destructive steps require the reviewed plan flow by default").argument("[file]", 'Path to plan.json, or "-" / omit to read stdin').option("--yes", "Authorize destructive commands (e.g. Smart Lock unlock, Garage open)").option("--require-approval", "Prompt for confirmation before each destructive step (TTY only; mutually exclusive with --json)").option("--continue-on-error", "Keep running after a failed step (default: stop at first error)").action(
+  plan.command("run").description("Validate + preview/execute a plan. Respects --dry-run; destructive steps require the reviewed plan flow by default").argument("[file]", 'Path to plan.json, or "-" / omit to read stdin').option("--yes", "Authorize destructive commands (e.g. Smart Lock unlock, Garage open)").option("--require-approval", "Prompt for confirmation before each destructive step (TTY only; mutually exclusive with --json)").option("--continue-on-error", "Keep running after a failed step (default: stop at first error)").option("--plan <json>", "Inline plan JSON (alternative to file argument or stdin)").action(
     async (file2, options) => {
       if (options.requireApproval && isJsonMode()) {
         console.error("error: --require-approval cannot be used with --json (no TTY available for prompts)");
         process.exit(1);
       }
+      if (options.plan !== void 0 && file2 !== void 0) {
+        console.error("error: --plan and a file argument are mutually exclusive.");
+        process.exit(2);
+      }
       let raw;
       try {
-        raw = await readPlanSource(file2);
+        if (options.plan !== void 0) {
+          try {
+            raw = JSON.parse(options.plan);
+          } catch (err) {
+            throw new UsageError(`--plan is not valid JSON: ${err.message}`);
+          }
+        } else {
+          raw = await readPlanSource(file2);
+        }
       } catch (err) {
         handleError(err);
       }
@@ -55689,7 +55884,7 @@ Examples:
   $ switchbot history show --limit 10
   $ switchbot history replay 3
 `);
-  history.command("show").description("Print recent audit entries").option("--file <path>", `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg("--file")).option("--limit <n>", "Show only the last N entries", intArg("--limit", { min: 1 })).action((options) => {
+  history.command("show").alias("list").description("Print recent audit entries").option("--file <path>", `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg("--file")).option("--limit <n>", "Show only the last N entries", intArg("--limit", { min: 1 })).action((options) => {
     const file2 = options.file ?? DEFAULT_AUDIT;
     const entries = readAudit(file2);
     const limited = options.limit !== void 0 ? entries.slice(-Math.max(1, Number(options.limit) || 1)) : entries;
@@ -59338,6 +59533,7 @@ import os25 from "node:os";
 import path27 from "node:path";
 var DEFAULT_AUDIT_PATH3 = path27.join(os25.homedir(), ".switchbot", "audit.log");
 var AUDIT_ERROR_WINDOW_MS = 24 * 60 * 60 * 1e3;
+var EXPECTED_ERROR_CODES = /* @__PURE__ */ new Set([161, 171, 190]);
 function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
   const now = /* @__PURE__ */ new Date();
   const procHealth = {
@@ -59358,20 +59554,46 @@ function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
   };
   let auditHealth;
   if (!fs31.existsSync(auditPath)) {
-    auditHealth = { present: false, recentErrors: 0, recentTotal: 0, errorRatePercent: 0, status: "ok" };
+    auditHealth = {
+      present: false,
+      recentErrors: 0,
+      recentTotal: 0,
+      errorRatePercent: 0,
+      expectedErrors: 0,
+      unexpectedErrors: 0,
+      unexpectedRatePercent: 0,
+      breakdown: {},
+      status: "ok"
+    };
   } else {
     const entries = readAudit(auditPath);
     const windowStart = now.getTime() - AUDIT_ERROR_WINDOW_MS;
     const recent = entries.filter((e) => new Date(e.t).getTime() >= windowStart);
-    const errors = recent.filter((e) => e.result === "error").length;
+    const errorEntries = recent.filter((e) => e.result === "error");
     const total = recent.length;
+    const errors = errorEntries.length;
     const errorRate = total > 0 ? Math.round(errors / total * 100) : 0;
+    const breakdown = {};
+    let expectedErrors = 0;
+    for (const e of errorEntries) {
+      const code = e.statusCode !== void 0 ? String(e.statusCode) : "unknown";
+      breakdown[code] = (breakdown[code] ?? 0) + 1;
+      if (e.statusCode !== void 0 && EXPECTED_ERROR_CODES.has(e.statusCode)) {
+        expectedErrors++;
+      }
+    }
+    const unexpectedErrors = errors - expectedErrors;
+    const unexpectedRatePercent = total > 0 ? Math.round(unexpectedErrors / total * 100 * 10) / 10 : 0;
     auditHealth = {
       present: true,
       recentErrors: errors,
       recentTotal: total,
       errorRatePercent: errorRate,
-      status: errorRate >= 30 ? "warn" : "ok"
+      expectedErrors,
+      unexpectedErrors,
+      unexpectedRatePercent,
+      breakdown,
+      status: unexpectedRatePercent >= 30 ? "warn" : "ok"
     };
   }
   const cbStats = apiCircuitBreaker.getStats();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",