@switchbot/openapi-cli 2.6.0 → 2.6.2

package/README.md

@@ -238,7 +238,7 @@ switchbot devices status <deviceId>
 switchbot devices status <deviceId> --json
 
 # Resolve device by fuzzy name instead of ID (status, command, describe, expand, watch)
-switchbot devices status --name "客厅空调"
+switchbot devices status --name "Living Room AC"
 switchbot devices command --name "Office Light" turnOn
 switchbot devices describe --name "Kitchen Bot"
 
@@ -276,6 +276,9 @@ but each exposes its own key set:
 Clauses are comma-separated and AND-ed. No OR across clauses — use regex
 alternation (`=/A|B/`) for that. `category` is the one key that stays exact
 under `=` / `!=` to preserve `category=physical` / `category!=ir` semantics.
+A clause with an empty value (e.g. `name~`, `type=`) is rejected with exit 2 —
+the parser refuses to guess whether an empty value means "no constraint" or
+"match empty string". Drop the clause outright to remove the constraint.
 
 #### Parameter formats
 
@@ -316,7 +319,7 @@ Some commands require a packed string like `"26,2,2,on"`. `devices expand` build
 # Air Conditioner — setAll
 switchbot devices expand <acId> setAll --temp 26 --mode cool --fan low --power on
 # Resolve by name
-switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
+switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 
 # Curtain / Roller Shade — setPosition
 switchbot devices expand <curtainId> setPosition --position 50 --mode silent

package/dist/commands/batch.js

@@ -137,7 +137,7 @@ Safety:
   hitting the API.
 
 Examples:
-  $ switchbot devices batch turnOff --filter 'type~=Light,family=家里'
+  $ switchbot devices batch turnOff --filter 'type~=Light,family=home'
   $ switchbot devices batch turnOn --ids ID1,ID2,ID3
   $ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
   $ switchbot devices batch unlock --filter 'type=Smart Lock' --yes

package/dist/commands/devices.js

@@ -70,7 +70,7 @@ Examples:
   $ switchbot devices list
   $ switchbot devices list --wide
   $ switchbot devices list --format tsv --fields deviceId,deviceName,type,category
-  $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "家里")'
+  $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "home")'
   $ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | group_by(.familyName)'
   $ switchbot devices list --filter type="Air Conditioner"
   $ switchbot devices list --filter category=ir
@@ -215,7 +215,7 @@ all field names returned by your specific device, then narrow with --fields.
 
 Examples:
   $ switchbot devices status ABC123DEF456
-  $ switchbot devices status --name "客厅空调"
+  $ switchbot devices status --name "Living Room AC"
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
   $ switchbot devices status ABC123DEF456 --format tsv --fields power,battery

package/dist/commands/expand.js

@@ -50,7 +50,7 @@ Examples:
   $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
   $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
   $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
-  $ switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
+  $ switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 `)
         .action(async (deviceIdArg, commandArg, options) => {
         let deviceId = '';

package/dist/commands/mcp.js

@@ -9,6 +9,7 @@ import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, val
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
+import { validateParameter } from '../devices/param-validator.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { deviceHistoryStore } from '../mcp/device-history.js';
 import { queryDeviceHistory } from '../devices/history-query.js';
@@ -273,6 +274,10 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        let effectiveParameter = parameter;
+        // stringifiedParam mirrors the CLI form that validateCommand /
+        // validateParameter expect — B-1 runs on the string representation.
+        const stringifiedParam = parameter === undefined ? undefined : typeof parameter === 'string' ? parameter : JSON.stringify(parameter);
         // dryRun early-return — no API call. We still preflight the deviceId
         // against the local cache so fabricated IDs don't silently pass
         // validation (bug #SYS-3). Dry-run is meant to catch bad inputs; a
@@ -286,10 +291,31 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
+            // R-2: run B-1 param validation in dry-run too, so dry-run doesn't
+            // falsely accept inputs the live API would reject.
+            if (effectiveType !== 'customize') {
+                const pv = validateParameter(cached.type, command, stringifiedParam);
+                if (!pv.ok) {
+                    return mcpError('usage', 2, pv.error, {
+                        hint: 'Dry-run rejected the parameter client-side; the API would reject it too.',
+                        context: { deviceType: cached.type, command, parameter: stringifiedParam },
+                    });
+                }
+                if (pv.normalized !== undefined) {
+                    effectiveParameter = pv.normalized;
+                }
+            }
+            const cmdVal = validateCommand(deviceId, command, stringifiedParam, effectiveType);
+            if (!cmdVal.ok) {
+                return mcpError('usage', 2, cmdVal.error.message, {
+                    hint: cmdVal.error.hint,
+                    context: { validationKind: cmdVal.error.kind },
+                });
+            }
             const wouldSend = {
                 deviceId,
                 command,
-                parameter: parameter ?? 'default',
+                parameter: effectiveParameter ?? 'default',
                 commandType: effectiveType,
             };
             const structured = { ok: true, dryRun: true, wouldSend };
@@ -332,16 +358,30 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 },
             });
         }
-        // stringifiedParam is what validateCommand expects to decide
-        // "no-parameter" conflicts — mirror the CLI behavior.
-        const stringifiedParam = parameter === undefined ? undefined : typeof parameter === 'string' ? parameter : JSON.stringify(parameter);
+        // validateCommand covers command existence + required/unexpected-parameter.
+        // stringifiedParam was computed once at the top of the handler so dry-run
+        // and live paths share the same shape.
         const validation = validateCommand(deviceId, command, stringifiedParam, effectiveType);
         if (!validation.ok) {
             return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
         }
+        // R-2: run B-1 client-side parameter validator (range/format checks).
+        // Customize commands (user-defined IR buttons) opt out — the catalog
+        // cannot know their expected shape.
+        if (effectiveType !== 'customize') {
+            const pv = validateParameter(typeName, command, stringifiedParam);
+            if (!pv.ok) {
+                return mcpError('usage', 2, pv.error, {
+                    context: { deviceType: typeName, command, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
+                });
+            }
+            if (pv.normalized !== undefined) {
+                effectiveParameter = pv.normalized;
+            }
+        }
         let result;
         try {
-            result = await executeCommand(deviceId, command, parameter, effectiveType, undefined, {
+            result = await executeCommand(deviceId, command, effectiveParameter, effectiveType, undefined, {
                 idempotencyKey,
             });
         }
@@ -393,7 +433,22 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ sceneId, dryRun }) => {
         if (dryRun) {
-            const wouldSend = { sceneId };
+            let scenes = [];
+            try {
+                scenes = await fetchScenes();
+            }
+            catch {
+                // network failure — degrade gracefully, skip validation
+            }
+            const found = scenes.find((s) => s.sceneId === sceneId);
+            if (scenes.length > 0 && !found) {
+                return mcpError('usage', 2, `Scene not found: ${sceneId}`, {
+                    subKind: 'scene-not-found',
+                    hint: "Check the sceneId with 'list_scenes' (IDs are case-sensitive).",
+                    context: { sceneId, candidates: scenes.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })).slice(0, 5) },
+                });
+            }
+            const wouldSend = { sceneId, sceneName: found?.sceneName ?? null };
             const structured = { ok: true, dryRun: true, wouldSend };
             return {
                 content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],

package/dist/commands/scenes.js

@@ -1,6 +1,7 @@
 import { printJson, isJsonMode, handleError, StructuredUsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
+import { isDryRun } from '../utils/flags.js';
 export function registerScenesCommand(program) {
     const scenes = program
         .command('scenes')
@@ -56,6 +57,16 @@ Example:
                     candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
                 });
             }
+            if (isDryRun()) {
+                const wouldSend = { method: 'POST', url: `/v1.1/scenes/${sceneId}/execute`, sceneId, sceneName: found.sceneName };
+                if (isJsonMode()) {
+                    printJson({ dryRun: true, wouldSend });
+                }
+                else {
+                    console.log(`[dry-run] Would POST /v1.1/scenes/${sceneId}/execute (${found.sceneName})`);
+                }
+                return;
+            }
             await executeScene(sceneId);
             if (isJsonMode()) {
                 printJson({ ok: true, sceneId });

package/dist/commands/watch.js

@@ -75,7 +75,7 @@ Examples:
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
-  $ switchbot devices watch --name "客厅空调" --interval 10s
+  $ switchbot devices watch --name "Living Room AC" --interval 10s
 `)
         .action(async (deviceIds, options) => {
         try {

package/package.json

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