@switchbot/openapi-cli 2.5.0 → 2.6.0

package/dist/devices/param-validator.js

@@ -100,8 +100,178 @@ export function validateParameter(deviceType, command, raw) {
     if (deviceType.startsWith('Relay Switch') && command === 'setMode') {
         return validateRelaySetMode(raw);
     }
+    if (command === 'setBrightness' && isBrightnessDevice(deviceType)) {
+        return validateSetBrightness(raw);
+    }
+    if (command === 'setColor' && isColorDevice(deviceType)) {
+        return validateSetColor(raw);
+    }
+    if (command === 'setColorTemperature' && isColorDevice(deviceType)) {
+        return validateSetColorTemperature(raw);
+    }
     return { ok: true };
 }
+function isBrightnessDevice(deviceType) {
+    return (deviceType === 'Color Bulb' ||
+        deviceType === 'Strip Light' ||
+        deviceType === 'Strip Light 3' ||
+        deviceType === 'Ceiling Light' ||
+        deviceType === 'Ceiling Light Pro' ||
+        deviceType === 'Floor Lamp' ||
+        deviceType === 'Light Strip' ||
+        deviceType === 'Dimmer' ||
+        deviceType === 'Fill Light');
+}
+function isColorDevice(deviceType) {
+    return (deviceType === 'Color Bulb' ||
+        deviceType === 'Strip Light' ||
+        deviceType === 'Strip Light 3' ||
+        deviceType === 'Ceiling Light' ||
+        deviceType === 'Ceiling Light Pro' ||
+        deviceType === 'Floor Lamp' ||
+        deviceType === 'Light Strip' ||
+        deviceType === 'Fill Light');
+}
+function validateSetBrightness(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setBrightness requires an integer 1-100 (percent). Example: "50".`,
+        };
+    }
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed)) {
+        return {
+            ok: false,
+            error: `setBrightness must be an integer 1-100, got ${JSON.stringify(raw)}. ${hintBrightnessRetry()}`,
+        };
+    }
+    const n = Number(trimmed);
+    if (!Number.isInteger(n) || n < 1 || n > 100) {
+        return {
+            ok: false,
+            error: `setBrightness must be an integer 1-100, got "${raw}". ${hintBrightnessRetry()}`,
+        };
+    }
+    return { ok: true, normalized: String(n) };
+}
+function hintBrightnessRetry() {
+    return `Ask the user whether they meant a percentage (1-100). Example: "50".`;
+}
+// B-12: setColor accepts R:G:B, R,G,B, #RRGGBB, #RGB, or a small CSS named color
+// palette. All forms are normalized to `R:G:B` (the only wire shape SwitchBot
+// accepts) so the caller can POST the result unchanged.
+const 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],
+    warm: [255, 180, 100],
+};
+function validateSetColor(raw) {
+    if (raw === undefined || 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(', ')}, ...).`,
+        };
+    }
+    const trimmed = raw.trim();
+    // Named color.
+    const named = NAMED_COLORS[trimmed.toLowerCase()];
+    if (named) {
+        return { ok: true, normalized: `${named[0]}:${named[1]}:${named[2]}` };
+    }
+    // Hex #RRGGBB or #RGB.
+    if (trimmed.startsWith('#')) {
+        const hex = trimmed.slice(1);
+        if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+            const r = parseInt(hex.slice(0, 2), 16);
+            const g = parseInt(hex.slice(2, 4), 16);
+            const b = parseInt(hex.slice(4, 6), 16);
+            return { ok: true, normalized: `${r}:${g}:${b}` };
+        }
+        if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+            const r = parseInt(hex[0] + hex[0], 16);
+            const g = parseInt(hex[1] + hex[1], 16);
+            const b = parseInt(hex[2] + hex[2], 16);
+            return { ok: true, normalized: `${r}:${g}:${b}` };
+        }
+        return {
+            ok: false,
+            error: `setColor "${raw}" is not valid hex. ${hintColorRetry()}`,
+        };
+    }
+    // R:G:B or R,G,B — pick whichever separator appears.
+    const sep = trimmed.includes(':') ? ':' : trimmed.includes(',') ? ',' : null;
+    if (!sep) {
+        return {
+            ok: false,
+            error: `setColor "${raw}" is not a recognized format. ${hintColorRetry()}`,
+        };
+    }
+    const parts = trimmed.split(sep).map((s) => s.trim());
+    if (parts.length !== 3) {
+        return {
+            ok: false,
+            error: `setColor expects 3 components (R${sep}G${sep}B), got ${parts.length} (${JSON.stringify(raw)}). ${hintColorRetry()}`,
+        };
+    }
+    const nums = [];
+    for (const p of parts) {
+        if (!/^-?\d+$/.test(p)) {
+            return {
+                ok: false,
+                error: `setColor component "${p}" is not an integer. ${hintColorRetry()}`,
+            };
+        }
+        const n = Number(p);
+        if (!Number.isInteger(n) || n < 0 || n > 255) {
+            return {
+                ok: false,
+                error: `setColor components must be integers 0-255, got "${p}". ${hintColorRetry()}`,
+            };
+        }
+        nums.push(n);
+    }
+    return { ok: true, normalized: `${nums[0]}:${nums[1]}:${nums[2]}` };
+}
+function hintColorRetry() {
+    return `Expected "R:G:B" (e.g. "255:0:0"), "#RRGGBB", "#RGB", "R,G,B", or a named color.`;
+}
+function validateSetColorTemperature(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setColorTemperature requires an integer Kelvin value 2700-6500. Example: "4000".`,
+        };
+    }
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed)) {
+        return {
+            ok: false,
+            error: `setColorTemperature must be an integer 2700-6500, got ${JSON.stringify(raw)}.`,
+        };
+    }
+    const n = Number(trimmed);
+    if (!Number.isInteger(n) || n < 2700 || n > 6500) {
+        return {
+            ok: false,
+            error: `setColorTemperature must be an integer 2700-6500, got "${raw}".`,
+        };
+    }
+    return { ok: true, normalized: String(n) };
+}
 function validateAcSetAll(raw) {
     if (raw === undefined || raw === '' || raw === 'default') {
         return {

package/dist/utils/arg-parsers.js

@@ -37,7 +37,8 @@ export function durationArg(flagName) {
         }
         const ms = parseDurationToMs(value);
         if (ms === null) {
-            throw new InvalidArgumentError(`${flagName} must look like "30s", "1m", "500ms", "1h" (got "${value}")`);
+            throw new InvalidArgumentError(`${flagName} must look like "30s", "1m", "500ms", "1h", "7d", "2w" ` +
+                `(supported units: ms, s, m, h, d, w — got "${value}")`);
         }
         return value;
     };

package/dist/utils/filter.js

@@ -4,42 +4,127 @@ export class FilterSyntaxError extends Error {
         this.name = 'FilterSyntaxError';
     }
 }
-const VALID_KEYS = ['type', 'family', 'room', 'category'];
 /**
- * Parse a filter expression like "type=Bot,family=Home" into discrete clauses.
+ * Parse a comma-separated filter expression into discrete clauses.
  *
- * Grammar:
- *   expr    := clause ("," clause)*
- *   clause  := KEY OP VALUE
- *   KEY     := type | family | room | category
- *   OP      := "=" | "~="
- *   VALUE   := any non-empty string (no comma — split at the clause boundary)
+ * Grammar (per clause, recognition order):
+ *   1. key=/pattern/   → regex (case-insensitive); invalid regex throws.
+ *   2. key!=value      → 'neq' op (negated substring; exact-negated for keys
+ *                        listed in matchClause's `exactKeys` option).
+ *   3. key~value       → substring (case-insensitive).
+ *   4. key=value       → 'eq' op (substring; caller decides whether to treat
+ *                        as exact for specific keys via matchClause's
+ *                        `exactKeys` option).
  *
- * Whitespace around keys / values is trimmed. Empty expressions return [].
+ * `allowedKeys` is command-specific: `devices list` uses
+ * {type,name,category,room}; `devices batch` uses {type,family,room,category};
+ * `events tail` uses {deviceId,type}.
  */
-export function parseFilter(expr) {
+export function parseFilterExpr(expr, allowedKeys) {
     if (!expr)
         return [];
     const parts = expr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
     const clauses = [];
     for (const part of parts) {
-        const m = /^([a-zA-Z_]+)\s*(~=|=)\s*(.+)$/.exec(part);
-        if (!m) {
-            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>" or "<key>~=<pattern>"`);
+        const regexMatch = /^([^=~!]+)=\/(.*)\/$/.exec(part);
+        const neqIdx = part.indexOf('!=');
+        const tildeIdx = part.indexOf('~');
+        const eqIdx = part.indexOf('=');
+        let key;
+        let op;
+        let raw;
+        let regex;
+        if (regexMatch) {
+            key = regexMatch[1].trim();
+            op = 'regex';
+            raw = regexMatch[2];
+            try {
+                regex = new RegExp(raw, 'i');
+            }
+            catch (err) {
+                throw new FilterSyntaxError(`Invalid regex in --filter "${part}": ${err.message}`);
+            }
+        }
+        else if (neqIdx !== -1 && (tildeIdx === -1 || neqIdx < tildeIdx)) {
+            key = part.slice(0, neqIdx).trim();
+            op = 'neq';
+            raw = part.slice(neqIdx + 2).trim();
+        }
+        else if (tildeIdx !== -1 && (eqIdx === -1 || tildeIdx < eqIdx)) {
+            key = part.slice(0, tildeIdx).trim();
+            op = 'sub';
+            raw = part.slice(tildeIdx + 1).trim();
+            if (raw.startsWith('=')) {
+                throw new FilterSyntaxError(`Invalid filter clause "${part}" — "~=" is no longer supported. Use "${key}~${raw.slice(1)}" instead.`);
+            }
         }
-        const key = m[1];
-        const op = m[2];
-        const value = m[3].trim();
-        if (!VALID_KEYS.includes(key)) {
-            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${VALID_KEYS.join(', ')}`);
+        else if (eqIdx !== -1) {
+            key = part.slice(0, eqIdx).trim();
+            op = 'eq';
+            raw = part.slice(eqIdx + 1).trim();
         }
-        if (!value) {
+        else {
+            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>", "<key>!=<value>", "<key>~<value>", or "<key>=/<regex>/"`);
+        }
+        if (!key) {
+            throw new FilterSyntaxError(`Empty key in filter clause "${part}"`);
+        }
+        if (!raw) {
             throw new FilterSyntaxError(`Empty value for filter clause "${part}"`);
         }
-        clauses.push({ key, op, value });
+        if (!allowedKeys.includes(key)) {
+            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${allowedKeys.join(', ')}`);
+        }
+        clauses.push({ key, op, raw, regex });
     }
     return clauses;
 }
+/**
+ * Match a single candidate string against a clause.
+ *
+ * - `regex` → RegExp.test against the candidate (case-insensitive by construction).
+ * - `sub`   → case-insensitive substring.
+ * - `eq`    → case-insensitive substring, except for keys listed in
+ *             `exactKeys`, which get case-insensitive exact comparison.
+ *             Default `exactKeys` is `['category']` to preserve the existing
+ *             list/batch behavior for that key.
+ * - `neq`   → logical inverse of `eq` (negated substring; exact-negated for
+ *             `exactKeys`). `undefined` candidates remain non-matching so a
+ *             `neq` clause does NOT accidentally match missing data.
+ */
+export function matchClause(candidate, clause, options) {
+    if (candidate === undefined) {
+        // Missing field: `neq` treats absence as "definitely not X"; everything
+        // else treats it as "no evidence — don't match".
+        return clause.op === 'neq';
+    }
+    if (clause.op === 'regex') {
+        return clause.regex.test(candidate);
+    }
+    const cLower = candidate.toLowerCase();
+    const vLower = clause.raw.toLowerCase();
+    if (clause.op === 'sub') {
+        return cLower.includes(vLower);
+    }
+    const exactKeys = options?.exactKeys ?? ['category'];
+    const exact = exactKeys.includes(clause.key);
+    if (clause.op === 'neq') {
+        return exact ? cLower !== vLower : !cLower.includes(vLower);
+    }
+    if (exact) {
+        return cLower === vLower;
+    }
+    return cLower.includes(vLower);
+}
+const BATCH_KEYS = ['type', 'family', 'room', 'category'];
+/**
+ * Back-compat narrow signature: parses with the batch key set. Callers that
+ * need a different key set (list, events tail) should call parseFilterExpr
+ * directly.
+ */
+export function parseFilter(expr) {
+    return parseFilterExpr(expr, BATCH_KEYS);
+}
 /** Normalize a physical / IR device entry to the shape the filter matcher expects. */
 function toFilterable(d, isPhysical, hubLocation) {
     if (isPhysical) {
@@ -62,27 +147,23 @@ function toFilterable(d, isPhysical, hubLocation) {
         category: 'ir',
     };
 }
-function matches(d, clause) {
-    const candidate = clause.key === 'type'
-        ? d.type
-        : clause.key === 'family'
-            ? d.family
-            : clause.key === 'room'
-                ? d.room
-                : d.category;
-    if (candidate === undefined)
-        return false;
-    if (clause.op === '=')
-        return candidate.toLowerCase() === clause.value.toLowerCase();
-    // '~=' — case-insensitive substring match on the candidate.
-    return candidate.toLowerCase().includes(clause.value.toLowerCase());
+function candidateFor(d, key) {
+    switch (key) {
+        case 'type':
+            return d.type;
+        case 'family':
+            return d.family;
+        case 'room':
+            return d.room;
+        case 'category':
+            return d.category;
+        default:
+            return undefined;
+    }
 }
 /**
  * Apply the parsed clauses to a mixed list of physical devices + IR remotes.
- * Returns the deviceIds of the entries that satisfy every clause.
- *
- * `hubLocation` (optional) allows family/room filters to match IR remotes by
- * the Hub-inherited location.
+ * Returns the filterable entries that satisfy every clause.
  */
 export function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation) {
     const candidates = [
@@ -91,5 +172,5 @@ export function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation
     ];
     if (clauses.length === 0)
         return candidates;
-    return candidates.filter((c) => clauses.every((clause) => matches(c, clause)));
+    return candidates.filter((c) => clauses.every((clause) => matchClause(candidateFor(c, clause.key), clause)));
 }

package/dist/utils/flags.js

@@ -8,6 +8,14 @@ function getFlagValue(...flagNames) {
         if (idx !== -1 && idx + 1 < process.argv.length) {
             return process.argv[idx + 1];
         }
+        // Also accept the `--flag=value` token form. Commander.js recognizes it at
+        // the option layer but global-flag scans like this one used to miss it,
+        // so `--format=json` silently fell back to the default (table).
+        const prefix = `${flag}=`;
+        const combined = process.argv.find((arg) => arg.startsWith(prefix));
+        if (combined !== undefined) {
+            return combined.slice(prefix.length);
+        }
     }
     return undefined;
 }
@@ -82,6 +90,22 @@ export function getBackoffStrategy() {
         return 'linear';
     return 'exponential';
 }
+/**
+ * Max retries on 5xx / gateway-timeout responses for idempotent (GET) reads.
+ * Default 2. `--no-retry` disables retries entirely. POSTs are not retried
+ * automatically — use --idempotency-key and let the server dedupe.
+ */
+export function getRetryOn5xx() {
+    if (process.argv.includes('--no-retry'))
+        return 0;
+    const v = getFlagValue('--retry-on-5xx');
+    if (v === undefined)
+        return 2;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0)
+        return 2;
+    return Math.floor(n);
+}
 /**
  * Whether local quota counting is disabled. Quota counting is best-effort
  * (see src/utils/quota.ts) — this lets scripts opt out entirely when even
@@ -92,7 +116,7 @@ export function isQuotaDisabled() {
 }
 const DEFAULT_LIST_TTL_MS = 60 * 60 * 1000;
 function parseDurationToMs(v) {
-    const m = /^(\d+)(ms|s|m|h)?$/.exec(v.trim().toLowerCase());
+    const m = /^(\d+)(ms|s|m|h|d|w)?$/.exec(v.trim().toLowerCase());
     if (!m)
         return null;
     const n = Number(m[1]);
@@ -104,6 +128,8 @@ function parseDurationToMs(v) {
         case 's': return n * 1000;
         case 'm': return n * 60 * 1000;
         case 'h': return n * 60 * 60 * 1000;
+        case 'd': return n * 24 * 60 * 60 * 1000;
+        case 'w': return n * 7 * 24 * 60 * 60 * 1000;
         default: return null;
     }
 }

package/dist/utils/format.js

@@ -1,4 +1,4 @@
-import { printTable, printJson, isJsonMode, UsageError } from './output.js';
+import { printTable, printJson, isJsonMode, UsageError, emitJsonError } from './output.js';
 import { getFormat, getFields } from './flags.js';
 import { dump as yamlDump } from 'js-yaml';
 export function parseFormat(flag) {
@@ -16,7 +16,7 @@ export function parseFormat(flag) {
         default: {
             const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id, markdown.`;
             if (isJsonMode()) {
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
             }
             else {
                 console.error(msg);

package/dist/utils/name-resolver.js

@@ -2,7 +2,7 @@ import { loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { levenshtein, normalizeDeviceName } from './string.js';
 import { UsageError, StructuredUsageError } from './output.js';
-const ALL_STRATEGIES = [
+export const ALL_STRATEGIES = [
     'exact', 'prefix', 'substring', 'fuzzy', 'first', 'require-unique',
 ];
 export function isValidStrategy(s) {
@@ -117,9 +117,12 @@ export function resolveDeviceId(deviceId, nameQuery, opts = {}) {
             narrow.push('--category');
         if (!opts.room)
             narrow.push('--room');
+        const strategyHint = opts.strategy === 'fuzzy'
+            ? `pass --name-strategy=first to pick the best match`
+            : `pass --name-strategy=fuzzy or --name-strategy=first to pick the best match`;
         const hint = narrow.length > 0
-            ? `Narrow with ${narrow.join(' / ')} or use the deviceId directly, or pass --name-strategy first to pick the best match.`
-            : `Use the deviceId directly, or pass --name-strategy first to pick the best match.`;
+            ? `Narrow with ${narrow.join(' / ')}, refine the name, use the deviceId directly, or ${strategyHint}.`
+            : `Refine the name, use the deviceId directly, or ${strategyHint}.`;
         throw new StructuredUsageError(`"${nameQuery}" is ambiguous — ${candidates.length} devices match.`, {
             error: 'ambiguous_name_match',
             query: nameQuery,

package/dist/utils/output.js

@@ -9,6 +9,25 @@ export function isJsonMode() {
 export function printJson(data) {
     console.log(JSON.stringify({ schemaVersion: SCHEMA_VERSION, data }, null, 2));
 }
+/**
+ * Emit a structured JSON error envelope on stdout.
+ *
+ * Bug #SYS-1: Under `--json`, both success and error payloads must share
+ * the same output channel (stdout) so a single `cli --json ... | jq` pipe
+ * can decode either shape. Use this helper everywhere that previously
+ * called `console.error(JSON.stringify({ error: ... }))` in --json mode.
+ *
+ * The envelope is always `{ schemaVersion, error }` — callers pass only the
+ * error payload. Also emits a brief human-readable line on stderr when a
+ * TTY is attached, so interactive runs still see the failure.
+ */
+export function emitJsonError(errorPayload) {
+    console.log(JSON.stringify({ schemaVersion: SCHEMA_VERSION, error: errorPayload }));
+    if (process.stderr.isTTY) {
+        const msg = typeof errorPayload.message === 'string' ? errorPayload.message : 'Error';
+        console.error(chalk.red(msg));
+    }
+}
 function escapeMarkdownCell(s) {
     // Pipes break markdown table layout; backslash-escape them. Collapse
     // newlines into <br> so each row stays on one line.
@@ -25,6 +44,9 @@ function formatCell(cell, style) {
     return String(cell);
 }
 function renderMarkdownTable(headers, rows) {
+    if (rows.length === 0) {
+        return '_(empty)_';
+    }
     const head = `| ${headers.map(escapeMarkdownCell).join(' | ')} |`;
     const sep = `| ${headers.map(() => '---').join(' | ')} |`;
     const body = rows.map((r) => `| ${r
@@ -119,11 +141,12 @@ export class StructuredUsageError extends Error {
 function classifyApiError(code) {
     switch (code) {
         case 151:
-        case 160: return 'command-not-supported';
+        case 160:
+        case 3005: return 'command-not-supported';
         case 152: return 'device-not-found';
         case 161:
         case 171: return 'device-offline';
-        case 190: return 'device-busy';
+        case 190: return 'device-internal-error';
         case 401: return 'auth-failed';
         case 429: return 'quota-exceeded';
         default: return 'unknown-api-error';
@@ -212,11 +235,46 @@ export function handleError(error) {
     }
     const payload = buildErrorPayload(error);
     if (isJsonMode()) {
-        console.error(JSON.stringify({ schemaVersion: SCHEMA_VERSION, error: payload }));
+        // Bug #SYS-1: Under --json, route the structured envelope to stdout so
+        // `cli --json ... | jq` pipelines can decode the error shape exactly
+        // the same way they decode success. Previously it went to stderr, which
+        // silently broke every error-path pipeline. TTY users still get a
+        // terse human-readable line on stderr so interactive runs don't look
+        // like the process simply exited.
+        console.log(JSON.stringify({ schemaVersion: SCHEMA_VERSION, error: payload }));
+        if (process.stderr.isTTY) {
+            console.error(chalk.red(payload.message));
+        }
         process.exit(payload.code === 2 ? 2 : 1);
     }
     if (payload.kind === 'usage') {
         console.error(payload.message);
+        const ctx = payload.context;
+        if (ctx && Array.isArray(ctx.candidates) && ctx.candidates.length > 0) {
+            const names = ctx.candidates
+                .map((c) => {
+                if (typeof c === 'string')
+                    return c;
+                if (c && typeof c === 'object') {
+                    const o = c;
+                    const name = typeof o.name === 'string'
+                        ? o.name
+                        : typeof o.sceneName === 'string' ? o.sceneName : undefined;
+                    const id = typeof o.deviceId === 'string'
+                        ? o.deviceId
+                        : typeof o.sceneId === 'string' ? o.sceneId : typeof o.id === 'string' ? o.id : undefined;
+                    if (name && id)
+                        return `${name} (${id})`;
+                    return name ?? id ?? JSON.stringify(c);
+                }
+                return String(c);
+            })
+                .slice(0, 6);
+            console.error(`Did you mean: ${names.join(', ')}?`);
+        }
+        if (ctx && typeof ctx.hint === 'string') {
+            console.error(ctx.hint);
+        }
         process.exit(2);
     }
     if (payload.kind === 'guard') {
@@ -247,11 +305,13 @@ function errorHint(code) {
         case 171:
             return 'The Hub itself is offline — check its power and Wi-Fi.';
         case 190:
-            return "Often means the deviceId is wrong or the command/parameter is invalid for this device. Double-check with 'switchbot devices list' and 'switchbot devices describe <deviceId>'. Use --verbose to see the raw API response.";
+            return 'SwitchBot API code 190 is a generic internal error. Common causes: invalid deviceId, unsupported command/parameter, or the endpoint does not apply (e.g., "webhook query" with no webhook configured). Verify with --verbose.';
         case 401:
             return "Re-run 'switchbot config set-token <token> <secret>', or verify SWITCHBOT_TOKEN / SWITCHBOT_SECRET.";
         case 429:
             return 'Daily quota is 10,000 requests/account — retry after midnight UTC.';
+        case 3005:
+            return "SwitchBot rejected the command as invalid for this specific device model. For IR remotes, this often means the command works only on --type customize (user-learned buttons). Try 'switchbot devices commands <type>' or check the device's capabilities.";
         default:
             return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.5.0",
+  "version": "2.6.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",