@switchbot/openapi-cli 1.3.2 → 2.0.1

package/README.md

@@ -11,6 +11,7 @@ List devices, query live status, send control commands, run scenes, and manage w
 
 - **npm package:** [`@switchbot/openapi-cli`](https://www.npmjs.com/package/@switchbot/openapi-cli)
 - **Source code:** [github.com/OpenWonderLabs/switchbot-openapi-cli](https://github.com/OpenWonderLabs/switchbot-openapi-cli)
+- **Releases / changelog:** [GitHub Releases](https://github.com/OpenWonderLabs/switchbot-openapi-cli/releases)
 - **Issues / feature requests:** [GitHub Issues](https://github.com/OpenWonderLabs/switchbot-openapi-cli/issues)
 
 ---
@@ -251,6 +252,34 @@ Generic parameter shapes (which one applies is decided by the device — see the
 
 For the complete per-device command reference, see the [SwitchBot API docs](https://github.com/OpenWonderLabs/SwitchBotAPI#send-device-control-commands).
 
+#### `devices expand` — named flags for packed parameters
+
+Some commands require a packed string like `"26,2,2,on"`. `devices expand` builds it from readable flags:
+
+```bash
+# Air Conditioner — setAll
+switchbot devices expand <acId> setAll --temp 26 --mode cool --fan low --power on
+
+# Curtain / Roller Shade — setPosition
+switchbot devices expand <curtainId> setPosition --position 50 --mode silent
+
+# Blind Tilt — setPosition
+switchbot devices expand <blindId> setPosition --direction up --angle 50
+
+# Relay Switch — setMode
+switchbot devices expand <relayId> setMode --channel 1 --mode edge
+```
+
+Run `switchbot devices expand <id> <command> --help` to see the available flags for any device command.
+
+#### `devices explain` — plain-language command description
+
+```bash
+switchbot devices explain <deviceId> <command>   # e.g. "explain ABC123 setAll"
+```
+
+Returns a human-readable description of what the command does and what each parameter means.
+
 ### `scenes` — run manual scenes
 
 ```bash
@@ -326,7 +355,7 @@ Output is a stream of JSON status objects (with `--json`) or a refreshed table.
 switchbot mcp serve
 ```
 
-Exposes 7 MCP tools: `list_devices`, `describe_device`, `get_device_status`, `send_command`, `list_scenes`, `run_scene`, `search_catalog`.
+Exposes 8 MCP tools (`list_devices`, `describe_device`, `get_device_status`, `send_command`, `list_scenes`, `run_scene`, `search_catalog`, `account_overview`) plus a `switchbot://events` resource for real-time shadow updates.
 See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full tool reference and safety rules (destructive-command guard).
 
 ### `cache` — inspect and clear local cache

package/dist/api/client.js

@@ -79,7 +79,7 @@ export function createClient() {
             throw error;
         if (axios.isAxiosError(error)) {
             if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
-                throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { retryable: false });
+                throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: false });
             }
             const status = error.response?.status;
             const config = error.config;
@@ -105,12 +105,26 @@ export function createClient() {
                 recordRequest(method, url);
             }
             if (status === 401) {
-                throw new ApiError('Authentication failed: invalid token or daily 10,000-request quota exceeded', 401, { retryable: false, hint: 'Run `switchbot config set-token <token> <secret>` to re-enter credentials, or `switchbot quota status` to check today\'s local count.' });
+                throw new ApiError('Authentication failed: invalid token or daily 10,000-request quota exceeded', 401, {
+                    transient: false,
+                    retryable: false,
+                    hint: 'Run `switchbot config set-token <token> <secret>` to re-enter credentials, or `switchbot quota status` to check today\'s local count.'
+                });
             }
             if (status === 429) {
-                throw new ApiError('Request rate too high: daily 10,000-request quota exceeded (retries exhausted)', 429, { retryable: true, hint: 'Use `switchbot quota status` to see today\'s usage; raise `--retry-on-429 <n>` for more retries.' });
+                const retryAfter = error.response?.headers?.['retry-after'];
+                const retryAfterMs = nextRetryDelayMs(maxRetries - 1, backoff, retryAfter);
+                throw new ApiError('Request rate too high: daily 10,000-request quota exceeded (retries exhausted)', 429, {
+                    retryable: true,
+                    transient: true,
+                    retryAfterMs,
+                    hint: 'Use `switchbot quota status` to see today\'s usage; raise `--retry-on-429 <n>` for more retries.'
+                });
             }
-            throw new ApiError(`HTTP ${status ?? '?'}: ${error.message}`, status ?? 0, { retryable: status !== undefined && status >= 500 });
+            throw new ApiError(`HTTP ${status ?? '?'}: ${error.message}`, status ?? 0, {
+                retryable: status !== undefined && status >= 500,
+                transient: status !== undefined && (status >= 500 || status === 0) // 5xx, 0 = connection error
+            });
         }
         throw error;
     });
@@ -120,12 +134,15 @@ export class ApiError extends Error {
     code;
     retryable;
     hint;
+    retryAfterMs;
+    transient;
     constructor(message, code, meta = {}) {
         super(message);
         this.code = code;
         this.name = 'ApiError';
         this.retryable = meta.retryable ?? false;
         this.hint = meta.hint;
+        this.retryAfterMs = meta.retryAfterMs;
+        this.transient = meta.transient ?? false;
     }
 }
-//# sourceMappingURL=client.js.map

package/dist/auth.js

@@ -18,4 +18,3 @@ export function buildAuthHeaders(token, secret) {
         'Content-Type': 'application/json',
     };
 }
-//# sourceMappingURL=auth.js.map

package/dist/commands/batch.js

@@ -1,4 +1,4 @@
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, buildErrorPayload } from '../utils/output.js';
 import { fetchDeviceList, executeCommand, isDestructiveCommand, buildHubLocationMap, } from '../lib/devices.js';
 import { createClient } from '../api/client.js';
 import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js';
@@ -90,6 +90,7 @@ export function registerBatchCommand(devices) {
         .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
+        .option('--idempotency-key-prefix <prefix>', 'Prefix for idempotency keys (key per device: <prefix>-<deviceId>)')
         .addHelpText('after', `
 Targets are resolved in this priority order:
   1. --ids when present       (explicit deviceIds)
@@ -214,7 +215,12 @@ Examples:
         const startedAt = Date.now();
         const outcomes = await runPool(resolved.ids, concurrency, async (id) => {
             try {
-                const result = await executeCommand(id, cmd, parsedParam, effectiveType, getClient());
+                const idempotencyKey = options.idempotencyKeyPrefix
+                    ? `${options.idempotencyKeyPrefix}-${id}`
+                    : undefined;
+                const result = await executeCommand(id, cmd, parsedParam, effectiveType, getClient(), {
+                    idempotencyKey,
+                });
                 if (!isJsonMode()) {
                     console.log(`✓ ${id}: ${cmd}`);
                 }
@@ -226,11 +232,11 @@ Examples:
                 if (err instanceof DryRunSignal) {
                     return { ok: 'dry-run', deviceId: id };
                 }
-                const message = err instanceof Error ? err.message : String(err);
+                const errorPayload = buildErrorPayload(err);
                 if (!isJsonMode()) {
-                    console.error(`✗ ${id}: ${message}`);
+                    console.error(`✗ ${id}: ${errorPayload.message}`);
                 }
-                return { ok: false, deviceId: id, error: message };
+                return { ok: false, deviceId: id, error: errorPayload };
             }
         });
         const succeeded = outcomes.filter((o) => o.ok === true);
@@ -245,6 +251,7 @@ Examples:
                 failed: failed.length,
                 skipped: dryRunned.length,
                 durationMs: Date.now() - startedAt,
+                schemaVersion: '1.1',
                 ...(dryRun ? { dryRun: true } : {}),
             },
         };
@@ -259,4 +266,3 @@ Examples:
             process.exit(1);
     });
 }
-//# sourceMappingURL=batch.js.map

package/dist/commands/cache.js

@@ -105,4 +105,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=cache.js.map

package/dist/commands/capabilities.js

@@ -1,4 +1,5 @@
 import { getEffectiveCatalog } from '../devices/catalog.js';
+import { printJson } from '../utils/output.js';
 const IDENTITY = {
     product: 'SwitchBot',
     domain: 'IoT smart home device control',
@@ -24,6 +25,7 @@ const MCP_TOOLS = [
     'list_scenes',
     'run_scene',
     'search_catalog',
+    'account_overview',
 ];
 export function registerCapabilitiesCommand(program) {
     program
@@ -55,7 +57,7 @@ export function registerCapabilitiesCommand(program) {
             description: opt.description,
         }));
         const roles = [...new Set(catalog.map((e) => e.role ?? 'other'))].sort();
-        console.log(JSON.stringify({
+        printJson({
             version: program.version(),
             generatedAt: new Date().toISOString(),
             identity: IDENTITY,
@@ -64,6 +66,7 @@ export function registerCapabilitiesCommand(program) {
                     entry: 'mcp serve',
                     protocol: 'stdio (default) or --port <n> for HTTP',
                     tools: MCP_TOOLS,
+                    resources: ['switchbot://events'],
                 },
                 plan: {
                     schemaCmd: 'plan schema',
@@ -85,7 +88,6 @@ export function registerCapabilitiesCommand(program) {
                 destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
                 readOnlyTypeCount: catalog.filter((e) => e.readOnly).length,
             },
-        }, null, 2));
+        });
     });
 }
-//# sourceMappingURL=capabilities.js.map

package/dist/commands/catalog.js

@@ -288,4 +288,3 @@ function renderEntry(entry) {
         console.log('  ' + entry.statusFields.join(', '));
     }
 }
-//# sourceMappingURL=catalog.js.map

package/dist/commands/completion.js

@@ -256,4 +256,3 @@ source it directly:
         }
     });
 }
-//# sourceMappingURL=completion.js.map

package/dist/commands/config.js

@@ -147,4 +147,3 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             console.log(p);
     });
 }
-//# sourceMappingURL=config.js.map

package/dist/commands/device-meta.js

@@ -139,4 +139,3 @@ export function registerDevicesMetaCommand(devices) {
         }
     });
 }
-//# sourceMappingURL=device-meta.js.map

package/dist/commands/devices.js

@@ -189,6 +189,7 @@ Examples:
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
+        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)')
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their
@@ -298,7 +299,7 @@ Examples:
                     // keep as string
                 }
             }
-            const body = await executeCommand(deviceId, cmd, parsedParam, options.type);
+            const body = await executeCommand(deviceId, cmd, parsedParam, options.type, undefined, { idempotencyKey: options.idempotencyKey });
             const isIr = getCachedDevice(deviceId)?.category === 'ir';
             if (isJsonMode()) {
                 const result = { ok: true, command: cmd, deviceId };
@@ -554,4 +555,3 @@ function renderCatalogEntry(entry) {
         console.log('  ' + entry.statusFields.join(', '));
     }
 }
-//# sourceMappingURL=devices.js.map

package/dist/commands/doctor.js

@@ -144,4 +144,3 @@ Examples:
             process.exit(1);
     });
 }
-//# sourceMappingURL=doctor.js.map

package/dist/commands/events.js

@@ -185,4 +185,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=events.js.map

package/dist/commands/expand.js

@@ -192,4 +192,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=expand.js.map

package/dist/commands/explain.js

@@ -134,4 +134,3 @@ function printHuman(r) {
         }
     }
 }
-//# sourceMappingURL=explain.js.map

package/dist/commands/history.js

@@ -101,4 +101,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=history.js.map