@switchbot/openapi-cli 2.6.4 → 2.7.2

package/README.md

@@ -6,8 +6,8 @@
 [![node](https://img.shields.io/node/v/@switchbot/openapi-cli.svg)](https://nodejs.org)
 [![CI](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml)
 
-Command-line interface for the [SwitchBot API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI).
-List devices, query live status, send control commands, run scenes, receive real-time events, and connect AI agents via the built-in MCP server — all from your terminal or shell scripts.
+**SwitchBot** smart home CLI — control lights, locks, curtains, sensors, plugs, and IR appliances (TV/AC/fan) via the [SwitchBot Cloud API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI).
+Run scenes, stream real-time events over MQTT, and plug AI agents into your home via the built-in MCP server — all from your terminal or shell scripts.
 
 - **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)

package/dist/api/client.js

@@ -87,6 +87,15 @@ export function createClient() {
             }
             throw new DryRunSignal(method, url);
         }
+        // P8: record the quota attempt BEFORE the request is dispatched so
+        // failures (timeouts / DNS errors / 5xx / aborted) also count. Only
+        // pre-flight refusals (daily-cap, --dry-run) above skip recording
+        // since they never touch the network. Retries re-enter this
+        // interceptor and record again, which matches the SwitchBot API
+        // billing model (every dispatched HTTP request consumes quota).
+        if (quotaEnabled) {
+            recordRequest(method, url);
+        }
         return config;
     });
     // Handle API-level errors (HTTP 200 but statusCode !== 100)
@@ -94,11 +103,6 @@ export function createClient() {
         if (verbose) {
             process.stderr.write(chalk.grey(`[verbose] ${response.status} ${response.statusText}\n`));
         }
-        if (quotaEnabled && response.config) {
-            const method = (response.config.method ?? 'get').toUpperCase();
-            const url = `${response.config.baseURL ?? ''}${response.config.url ?? ''}`;
-            recordRequest(method, url);
-        }
         const data = response.data;
         if (data.statusCode !== undefined && data.statusCode !== 100) {
             const msg = API_ERROR_MESSAGES[data.statusCode] ??
@@ -161,13 +165,10 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
-            // Record exhausted/non-retryable HTTP responses too — they count
-            // against the daily quota.
-            if (quotaEnabled && error.response && config) {
-                const method = (config.method ?? 'get').toUpperCase();
-                const url = `${config.baseURL ?? ''}${config.url ?? ''}`;
-                recordRequest(method, url);
-            }
+            // P8: quota already recorded in the request interceptor before
+            // dispatch — no extra bookkeeping needed here on the error path.
+            // Timeouts, DNS failures, 5xx, and exhausted retries all counted
+            // when the attempt was first made.
             if (status === 401) {
                 throw new ApiError('Authentication failed: invalid token or daily 10,000-request quota exceeded', 401, {
                     transient: false,

package/dist/commands/agent-bootstrap.js

@@ -1,19 +1,21 @@
 import { printJson } from '../utils/output.js';
 import { loadCache } from '../devices/cache.js';
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, CATALOG_SCHEMA_VERSION, } from '../devices/catalog.js';
 import { readProfileMeta } from '../config.js';
 import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
 import { ALL_STRATEGIES } from '../utils/name-resolver.js';
+import { IDENTITY } from './identity.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../../package.json');
-const IDENTITY = {
-    product: 'SwitchBot',
-    domain: 'IoT smart home device control',
-    vendor: 'Wonderlabs, Inc.',
-    apiVersion: 'v1.1',
-    authMethod: 'HMAC-SHA256 token+secret',
-};
+/**
+ * Schema version of the agent-bootstrap payload. Must stay in lockstep
+ * with the catalog schema — bootstrap consumers (AI agents) reason about
+ * catalog-derived fields (safetyTier, destructive flag), so a drift
+ * between the two would silently break their assumptions. `doctor`
+ * fails the `catalog-schema` check when these differ.
+ */
+export const AGENT_BOOTSTRAP_SCHEMA_VERSION = CATALOG_SCHEMA_VERSION;
 const SAFETY_TIERS = {
     read: 'No state mutation; safe to call freely.',
     action: 'Mutates device/cloud state but reversible (turnOn, setColor).',
@@ -83,17 +85,21 @@ Examples:
                 category: e.category,
                 role: e.role ?? null,
                 readOnly: e.readOnly ?? false,
-                commands: e.commands.map((c) => ({
-                    command: c.command,
-                    parameter: c.parameter,
-                    destructive: Boolean(c.destructive),
-                    idempotent: Boolean(c.idempotent),
-                })),
+                commands: e.commands.map((c) => {
+                    const tier = deriveSafetyTier(c, e);
+                    return {
+                        command: c.command,
+                        parameter: c.parameter,
+                        safetyTier: tier,
+                        destructive: tier === 'destructive',
+                        idempotent: Boolean(c.idempotent),
+                    };
+                }),
                 statusFields: e.statusFields ?? [],
             };
         });
         const payload = {
-            schemaVersion: '1.0',
+            schemaVersion: AGENT_BOOTSTRAP_SCHEMA_VERSION,
             generatedAt: new Date().toISOString(),
             cliVersion: pkgVersion,
             identity: IDENTITY,

package/dist/commands/batch.js

@@ -1,5 +1,5 @@
 import { intArg, enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, emitJsonError, exitWithError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, exitWithError } 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';
@@ -96,7 +96,8 @@ export function registerBatchCommand(devices) {
         .option('--concurrency <n>', 'Max parallel in-flight requests (default 5)', intArg('--concurrency', { min: 1 }), '5')
         .option('--max-concurrent <n>', 'Alias for --concurrency; takes priority when set', intArg('--max-concurrent', { min: 1 }))
         .option('--stagger <ms>', 'Fixed delay between task starts in ms (default 0 = random 20-60ms jitter)', intArg('--stagger', { min: 0 }), '0')
-        .option('--plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
+        .option('--plan', '[DEPRECATED, use --emit-plan] With --dry-run: emit a plan JSON document instead of executing anything')
+        .option('--emit-plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
         .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
@@ -127,8 +128,9 @@ Concurrency & pacing:
   --stagger <ms>         Fixed delay between task starts; default 0 uses random 20-60ms jitter.
 
 Planning:
-  --dry-run --plan       Print the plan JSON without executing anything. Useful
+  --dry-run --emit-plan  Print the plan JSON without executing anything. Useful
                          for agents that want to show the user what will run.
+                         (--plan is the deprecated alias, removed in v3.0.)
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
@@ -146,6 +148,17 @@ Examples:
         // Trailing "-" sentinel selects stdin mode.
         const extra = commandObj.args ?? [];
         const readStdin = Boolean(options.stdin) || extra.includes('-');
+        // P12: --plan is deprecated in favor of --emit-plan. Reject both
+        // together (conflicting) and warn when only the old flag is used.
+        if (options.plan && options.emitPlan) {
+            handleError(new UsageError('Use --emit-plan; --plan is deprecated and cannot be combined with --emit-plan.'));
+            return;
+        }
+        if (options.plan && !options.emitPlan) {
+            // Warning goes to stderr so it cannot corrupt --json output on stdout.
+            console.error('[WARN] --plan is deprecated; use --emit-plan. Will be removed in v3.0.');
+        }
+        const emitPlan = Boolean(options.emitPlan || options.plan);
         // Accept --idempotency-key as alias; reject when both forms are supplied.
         if (options.idempotencyKey !== undefined && options.idempotencyKeyPrefix !== undefined) {
             handleError(new UsageError('Use either --idempotency-key or --idempotency-key-prefix, not both.'));
@@ -216,22 +229,14 @@ Examples:
             }
         }
         if (blockedForDestructive.length > 0 && !options.yes) {
-            if (isJsonMode()) {
-                const deviceIds = blockedForDestructive.map((b) => b.deviceId);
-                emitJsonError({
-                    code: 2,
-                    kind: 'guard',
-                    message: `Destructive command "${cmd}" requires --yes to run on ${blockedForDestructive.length} device(s).`,
-                    hint: 'Re-issue the call with --yes to proceed.',
-                    context: { command: cmd, deviceIds },
-                });
-            }
-            else {
-                console.error(`Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes:`);
-                for (const b of blockedForDestructive)
-                    console.error(`  ${b.deviceId}`);
-            }
-            process.exit(2);
+            const deviceIds = blockedForDestructive.map((b) => b.deviceId);
+            exitWithError({
+                code: 2,
+                kind: 'guard',
+                message: `Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes: ${deviceIds.join(', ')}`,
+                hint: 'Re-issue the call with --yes to proceed.',
+                context: { command: cmd, deviceIds },
+            });
         }
         // parameter may be a JSON object string; mirror the single-command action.
         let parsedParam = parameter ?? 'default';
@@ -247,8 +252,8 @@ Examples:
         const concurrency = Math.max(1, Number.parseInt(maxConcurrentRaw, 10) || DEFAULT_CONCURRENCY);
         const staggerMs = Math.max(0, Number.parseInt(options.stagger, 10) || 0);
         const dryRun = isDryRun();
-        // --dry-run --plan: emit a plan document and return without executing.
-        if (dryRun && options.plan) {
+        // --dry-run --emit-plan (or legacy --plan): emit a plan document and return without executing.
+        if (dryRun && emitPlan) {
             const steps = resolved.ids.map((id) => ({
                 deviceId: id,
                 command: cmd,

package/dist/commands/capabilities.js

@@ -1,7 +1,27 @@
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, deriveStatusQueries, } from '../devices/catalog.js';
+import { RESOURCE_CATALOG } from '../devices/resources.js';
 import { loadCache } from '../devices/cache.js';
 import { printJson } from '../utils/output.js';
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
+import { IDENTITY } from './identity.js';
+/** Collect the distinct catalog safety tiers actually used across the given entries. Sorted. */
+function collectSafetyTiersInUse(entries) {
+    const seen = new Set();
+    for (const e of entries) {
+        for (const c of e.commands) {
+            seen.add(deriveSafetyTier(c, e));
+        }
+        // P11: statusQueries contribute the 'read' tier.
+        if (deriveStatusQueries(e).length > 0) {
+            seen.add('read');
+        }
+    }
+    return [...seen].sort();
+}
+/** P11: total number of read-only queries exposed across the catalog. */
+function countStatusQueries(entries) {
+    return entries.reduce((n, e) => n + deriveStatusQueries(e).length, 0);
+}
 const AGENT_GUIDE = {
     safetyTiers: {
         read: 'No state mutation; safe to call freely — does not consume quota unless noted.',
@@ -68,23 +88,6 @@ const COMMAND_META = {
 function metaFor(command) {
     return COMMAND_META[command] ?? null;
 }
-const IDENTITY = {
-    product: 'SwitchBot',
-    domain: 'IoT smart home device control',
-    vendor: 'Wonderlabs, Inc.',
-    apiVersion: 'v1.1',
-    apiDocs: 'https://github.com/OpenWonderLabs/SwitchBotAPI',
-    deviceCategories: {
-        physical: 'Wi-Fi/BLE devices controllable via Cloud API (Hub required for BLE-only)',
-        ir: 'IR remote devices learned by a SwitchBot Hub (TV, AC, etc.)',
-    },
-    constraints: {
-        quotaPerDay: 10000,
-        bleRequiresHub: true,
-        authMethod: 'HMAC-SHA256 token+secret',
-    },
-    agentGuide: 'docs/agent-guide.md',
-};
 const MCP_TOOLS = [
     'list_devices',
     'get_device_status',
@@ -147,7 +150,7 @@ export function registerCapabilitiesCommand(program) {
     const SURFACES = ['cli', 'mcp', 'plan', 'mqtt', 'all'];
     program
         .command('capabilities')
-        .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
+        .description('Print a machine-readable manifest of SwitchBot CLI capabilities (for AI agent bootstrap)')
         .option('--minimal', 'Omit per-subcommand flag details to reduce output size (alias of --compact)')
         .option('--compact', 'Emit a compact summary: identity + leaf command list with safety metadata only')
         .option('--used', 'Restrict the catalog summary to device types present in the local cache. Mirrors `schema export --used`.')
@@ -249,9 +252,12 @@ export function registerCapabilitiesCommand(program) {
             catalog: {
                 typeCount: catalog.length,
                 roles,
-                destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
+                destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => deriveSafetyTier(c, e) === 'destructive').length, 0),
+                safetyTiersInUse: collectSafetyTiersInUse(catalog),
                 readOnlyTypeCount: catalog.filter((e) => e.readOnly).length,
+                readOnlyQueryCount: countStatusQueries(catalog),
             },
+            resources: RESOURCE_CATALOG,
         };
         if (!compact)
             payload.generatedAt = new Date().toISOString();
@@ -273,8 +279,10 @@ export function registerCapabilitiesCommand(program) {
                 payload.catalog = {
                     typeCount: filteredCatalog.length,
                     roles: [...new Set(filteredCatalog.map((e) => e.role ?? 'other'))].sort(),
-                    destructiveCommandCount: filteredCatalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
+                    destructiveCommandCount: filteredCatalog.reduce((n, e) => n + e.commands.filter((c) => deriveSafetyTier(c, e) === 'destructive').length, 0),
+                    safetyTiersInUse: collectSafetyTiersInUse(filteredCatalog),
                     readOnlyTypeCount: filteredCatalog.filter((e) => e.readOnly).length,
+                    readOnlyQueryCount: countStatusQueries(filteredCatalog),
                 };
                 payload.usedFilter = { applied: true, typesInCache: [...seen].sort() };
             }

package/dist/commands/catalog.js

@@ -1,12 +1,12 @@
 import { enumArg } from '../utils/arg-parsers.js';
 import { printTable, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { DEVICE_CATALOG, findCatalogEntry, getCatalogOverlayPath, getEffectiveCatalog, loadCatalogOverlay, resetCatalogOverlayCache, } from '../devices/catalog.js';
+import { DEVICE_CATALOG, findCatalogEntry, getCatalogOverlayPath, getEffectiveCatalog, loadCatalogOverlay, resetCatalogOverlayCache, deriveSafetyTier, } from '../devices/catalog.js';
 export function registerCatalogCommand(program) {
     const SOURCES = ['built-in', 'overlay', 'effective'];
     const catalog = program
         .command('catalog')
-        .description('Inspect the built-in device catalog and any local overlay')
+        .description('Inspect the SwitchBot device catalog (supported device types + any local overlay)')
         .addHelpText('after', `
 This CLI ships with a static catalog of known SwitchBot device types and
 their commands (see 'switchbot devices types'). You can extend or override
@@ -341,10 +341,11 @@ function renderEntry(entry) {
     else {
         console.log('\nCommands:');
         const rows = entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
             const flags = [];
             if (c.commandType === 'customize')
                 flags.push('customize');
-            if (c.destructive)
+            if (tier === 'destructive')
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
             return [label, c.parameter, c.description];

package/dist/commands/config.js

@@ -4,7 +4,7 @@ import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
 import { intArg } from '../utils/arg-parsers.js';
 import { saveConfig, showConfig, getConfigSummary, listProfiles, readProfileMeta } from '../config.js';
-import { isJsonMode, printJson, emitJsonError } from '../utils/output.js';
+import { isJsonMode, printJson, exitWithError } from '../utils/output.js';
 import chalk from 'chalk';
 function parseEnvFile(file) {
     const out = {};
@@ -145,14 +145,11 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         if (options.fromEnvFile) {
             if (!fs.existsSync(options.fromEnvFile)) {
-                const msg = `--from-env-file: file not found: ${options.fromEnvFile}`;
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: msg });
-                }
-                else {
-                    console.error(msg);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: `--from-env-file: file not found: ${options.fromEnvFile}`,
+                });
             }
             const parsed = parseEnvFile(options.fromEnvFile);
             token = token ?? parsed.token;
@@ -160,37 +157,33 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         if (options.fromOp) {
             if (!options.opSecret) {
-                const msg = '--from-op requires --op-secret <ref> for the secret reference.';
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: msg });
-                }
-                else {
-                    console.error(msg);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: '--from-op requires --op-secret <ref> for the secret reference.',
+                });
             }
             try {
                 token = readFromOp(options.fromOp);
                 secret = readFromOp(options.opSecret);
             }
             catch (err) {
-                const msg = `1Password CLI read failed: ${err instanceof Error ? err.message : String(err)}`;
-                if (isJsonMode()) {
-                    emitJsonError({ code: 1, kind: 'runtime', message: msg, hint: 'Ensure the "op" CLI is installed and authenticated (op signin).' });
-                }
-                else {
-                    console.error(msg);
-                    console.error('Ensure the "op" CLI is installed and authenticated (op signin).');
-                }
-                process.exit(1);
+                exitWithError({
+                    code: 1,
+                    kind: 'runtime',
+                    message: `1Password CLI read failed: ${err instanceof Error ? err.message : String(err)}`,
+                    hint: 'Ensure the "op" CLI is installed and authenticated (op signin).',
+                });
             }
         }
         // No credentials yet and stdin is a TTY → interactive prompt (safest path).
         if ((!token || !secret) && !options.fromEnvFile && !options.fromOp && process.stdin.isTTY) {
             if (isJsonMode()) {
-                const msg = 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.';
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.',
+                });
             }
             try {
                 if (!token)
@@ -204,14 +197,11 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             }
         }
         if (!token || !secret) {
-            const msg = 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).';
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).',
+            });
         }
         saveConfig(token, secret, {
             label: options.label,