@switchbot/openapi-cli 2.4.0 → 2.5.1

package/dist/utils/filter.js

@@ -4,42 +4,109 @@ 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       → substring (case-insensitive).
+ *   3. 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 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 (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.`);
+            }
+        }
+        else if (eqIdx !== -1) {
+            key = part.slice(0, eqIdx).trim();
+            op = 'eq';
+            raw = part.slice(eqIdx + 1).trim();
         }
-        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 {
+            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>", "<key>~<value>", or "<key>=/<regex>/"`);
         }
-        if (!value) {
+        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.
+ */
+export function matchClause(candidate, clause, options) {
+    if (candidate === undefined)
+        return false;
+    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'];
+    if (exactKeys.includes(clause.key)) {
+        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 +129,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 +154,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

@@ -92,7 +92,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 +104,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) {
@@ -12,10 +12,11 @@ export function parseFormat(flag) {
         case 'tsv': return 'tsv';
         case 'yaml': return 'yaml';
         case 'id': return 'id';
+        case 'markdown': return 'markdown';
         default: {
-            const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id.`;
+            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);
@@ -67,6 +68,13 @@ export function renderRows(headers, rows, format, fields, aliases) {
     const filtered = filterFields(headers, rows, fields, aliases);
     const h = filtered.headers;
     const r = filtered.rows;
+    // Markdown format is rendered as table with markdown style forced regardless
+    // of the user's --table-style, so `--format markdown` is a self-contained
+    // contract (bug #8).
+    if (format === 'markdown') {
+        printTable(h, r, 'markdown');
+        return;
+    }
     switch (format) {
         case 'table':
             printTable(h, r);

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) {
@@ -34,9 +34,17 @@ function resolveDeviceByName(query, opts = {}) {
         const alias = meta.devices[deviceId]?.alias;
         const rawName = normalizeDeviceName(device.name);
         const normAlias = alias ? normalizeDeviceName(alias) : null;
-        // exact alias/name wins regardless of strategy
+        // exact alias/name wins immediately for lenient strategies.
+        // Under require-unique we must NOT short-circuit: there may be other devices
+        // that also match (e.g. via substring), making the result ambiguous.  Collect
+        // the exact hit as a candidate and let the full ambiguity check decide below.
         if ((normAlias && normAlias === q) || rawName === q) {
-            return { ok: true, deviceId };
+            if (strategy !== 'require-unique') {
+                return { ok: true, deviceId };
+            }
+            // require-unique: treat exact match as a high-priority candidate (score 0)
+            candidates.push({ deviceId, name: device.name, score: 0 });
+            continue;
         }
         if (strategy === 'exact')
             continue;

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.
@@ -46,8 +65,8 @@ const ASCII_BORDER_CHARS = {
     left: '|', 'left-mid': '+', mid: '-', 'mid-mid': '+',
     right: '|', 'right-mid': '+', middle: '|',
 };
-export function printTable(headers, rows) {
-    const style = getTableStyle();
+export function printTable(headers, rows, styleOverride) {
+    const style = styleOverride ?? getTableStyle();
     if (style === 'markdown') {
         console.log(renderMarkdownTable(headers, rows));
         return;
@@ -119,11 +138,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,7 +232,16 @@ 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') {
@@ -247,11 +276,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/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+export { VERSION };

package/package.json

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