@switchbot/openapi-cli 2.6.4 → 2.7.2

package/dist/schema/field-aliases.js

@@ -1,5 +1,20 @@
 import { UsageError } from '../utils/output.js';
+/**
+ * User-facing aliases for canonical field names.
+ *
+ * Keys are canonical names (matching API response keys and CLI/schema output);
+ * values are lowercase alternatives a user may type for `--fields` or `--filter`.
+ *
+ * Conflict rules (do not add an alias that violates these — tests will fail):
+ * - `temp` is exclusive to `temperature` (NOT `colorTemperature`, `targetTemperature`).
+ * - `motion` is exclusive to `moveDetected`; `moving` uses `active` instead.
+ * - `mode` is exclusive to top-level `mode` (preset); device-specific modes go through `deviceMode`.
+ * - Reserved / too-generic words never appear as aliases: `auto`, `status`, `state`,
+ *   `switch`, `type`, `on`, `off`.
+ * - Device-type words are never aliases: `lock`, `fan`.
+ */
 export const FIELD_ALIASES = {
+    // Identification (shared with list/filter)
     deviceId: ['id'],
     deviceName: ['name'],
     deviceType: ['type'],
@@ -10,7 +25,71 @@ export const FIELD_ALIASES = {
     hubDeviceId: ['hub'],
     enableCloudService: ['cloud'],
     alias: ['alias'],
+    // Phase 1 — common status fields
+    battery: ['batt', 'bat'],
+    temperature: ['temp', 'ambient'],
+    colorTemperature: ['kelvin', 'colortemp'],
+    humidity: ['humid', 'rh'],
+    brightness: ['bright', 'bri'],
+    fanSpeed: ['speed'],
+    position: ['pos'],
+    moveDetected: ['motion'],
+    openState: ['open'],
+    doorState: ['door'],
+    CO2: ['co2'],
+    power: ['enabled'],
+    mode: ['preset'],
+    // Phase 2 — niche device fields
+    childLock: ['safe', 'childlock'],
+    targetTemperature: ['setpoint', 'target'],
+    electricCurrent: ['current', 'amps'],
+    voltage: ['volts'],
+    usedElectricity: ['energy', 'kwh'],
+    electricityOfDay: ['daily', 'today'],
+    weight: ['load'],
+    version: ['firmware', 'fw'],
+    lightLevel: ['light', 'lux'],
+    oscillation: ['swing', 'osc'],
+    verticalOscillation: ['vswing'],
+    nightStatus: ['night'],
+    chargingStatus: ['charging', 'charge'],
+    switch1Status: ['ch1', 'channel1'],
+    switch2Status: ['ch2', 'channel2'],
+    taskType: ['task'],
+    moving: ['active'],
+    onlineStatus: ['online_status'],
+    workingStatus: ['working'],
+    // Phase 3 — catalog statusFields coverage
+    group: ['cluster'],
+    calibrate: ['calibration', 'calib'],
+    direction: ['tilt'],
+    deviceMode: ['devmode'],
+    nebulizationEfficiency: ['mist', 'spray'],
+    sound: ['audio'],
+    lackWater: ['tank', 'water-low'],
+    filterElement: ['filter'],
+    color: ['rgb', 'hex'],
+    useTime: ['runtime', 'uptime'],
+    switchStatus: ['relay'],
+    lockState: ['locked'],
+    slidePosition: ['slide'],
+    // Phase 4 — ultra-niche sensor + webhook fields (~98% coverage target)
+    waterLeakDetect: ['leak', 'water'],
+    pressure: ['press', 'pa'],
+    moveCount: ['movecnt'],
+    errorCode: ['err'],
+    buttonName: ['btn', 'button'],
+    pressedAt: ['pressed'],
+    deviceMac: ['mac'],
+    detectionState: ['detected', 'detect'],
 };
+/**
+ * Resolve a user-typed field name to its canonical form against an allowed list.
+ *
+ * Matching is case-insensitive and trims surrounding whitespace. Direct matches
+ * win over alias matches. Throws UsageError if the input is empty or does not
+ * match any canonical / alias in the allowed list.
+ */
 export function resolveField(input, allowedCanonical) {
     const normalized = input.trim().toLowerCase();
     if (!normalized) {
@@ -19,12 +98,21 @@ export function resolveField(input, allowedCanonical) {
     for (const canonical of allowedCanonical) {
         if (canonical.toLowerCase() === normalized)
             return canonical;
+    }
+    for (const canonical of allowedCanonical) {
         const aliases = FIELD_ALIASES[canonical] ?? [];
         if (aliases.some((a) => a.toLowerCase() === normalized))
             return canonical;
     }
     throw new UsageError(`Unknown field "${input}". Supported: ${listSupportedFieldInputs(allowedCanonical).join(', ')}`);
 }
+/**
+ * Resolve every field in a list. Preserves order and the original UsageError
+ * from resolveField() on the first unknown input.
+ */
+export function resolveFieldList(inputs, allowedCanonical) {
+    return inputs.map((f) => resolveField(f, allowedCanonical));
+}
 export function listSupportedFieldInputs(allowedCanonical) {
     const out = new Set();
     for (const canonical of allowedCanonical) {
@@ -34,3 +122,10 @@ export function listSupportedFieldInputs(allowedCanonical) {
     }
     return [...out];
 }
+/**
+ * All canonical keys known to the alias registry. Use when no dynamic
+ * canonical list is available (e.g. `watch` before the first poll response).
+ */
+export function listAllCanonical() {
+    return Object.keys(FIELD_ALIASES);
+}

package/dist/utils/help-json.js

@@ -0,0 +1,54 @@
+import { IDENTITY } from '../commands/identity.js';
+export function commandToJson(cmd, opts = {}) {
+    const args = cmd.registeredArguments.map((a) => ({
+        name: a.name(),
+        required: a.required,
+        variadic: a.variadic,
+        description: a.description ?? '',
+    }));
+    const options = cmd.options
+        .filter((o) => o.long !== '--help' && o.long !== '--version')
+        .map((o) => {
+        const entry = { flags: o.flags, description: o.description ?? '' };
+        if (o.defaultValue !== undefined)
+            entry.defaultValue = o.defaultValue;
+        if (o.argChoices && o.argChoices.length > 0)
+            entry.choices = o.argChoices;
+        return entry;
+    });
+    const subcommands = cmd.commands
+        .filter((c) => !c.name().startsWith('_'))
+        .map((c) => ({ name: c.name(), description: c.description() }));
+    const out = {
+        name: cmd.name(),
+        description: cmd.description(),
+        arguments: args,
+        options,
+        subcommands,
+    };
+    if (opts.includeIdentity) {
+        out.product = IDENTITY.product;
+        out.domain = IDENTITY.domain;
+        out.vendor = IDENTITY.vendor;
+        out.apiVersion = IDENTITY.apiVersion;
+        out.apiDocs = IDENTITY.apiDocs;
+        out.productCategories = IDENTITY.productCategories;
+    }
+    return out;
+}
+/** Walk argv tokens (skipping flags) to find the deepest matching subcommand. */
+export function resolveTargetCommand(root, argv) {
+    let cmd = root;
+    for (const token of argv) {
+        if (token.startsWith('-'))
+            continue;
+        const sub = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
+        if (sub) {
+            cmd = sub;
+        }
+        else {
+            break;
+        }
+    }
+    return cmd;
+}

package/dist/utils/output.js

@@ -28,6 +28,23 @@ export function emitJsonError(errorPayload) {
         console.error(chalk.red(msg));
     }
 }
+/**
+ * P7: emit the stream-header first line for any NDJSON/streaming command
+ * running under `--json`. Downstream JSON consumers can key on
+ * `{ stream: true }` to distinguish the header from subsequent event
+ * lines, and on `eventKind` / `cadence` to pick a parser strategy.
+ *
+ * Non-streaming commands (single-object / array output) do NOT emit this
+ * header — only watch / events tail / events mqtt-tail.
+ */
+export function emitStreamHeader(opts) {
+    console.log(JSON.stringify({
+        schemaVersion: '1',
+        stream: true,
+        eventKind: opts.eventKind,
+        cadence: opts.cadence,
+    }));
+}
 export function exitWithError(messageOrOpts) {
     const opts = typeof messageOrOpts === 'string' ? { message: messageOrOpts } : messageOrOpts;
     const { message, kind = 'usage', code = 2, hint, context, extra } = opts;

package/package.json

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