@switchbot/openapi-cli 2.5.0 → 2.5.1

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.
@@ -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/package.json

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