@switchbot/openapi-cli 2.3.0 → 2.4.0

package/dist/commands/doctor.js

@@ -3,8 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { printJson, isJsonMode } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
-import { configFilePath, listProfiles } from '../config.js';
+import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
 import { describeCache } from '../devices/cache.js';
+export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
     if (envOk)
@@ -39,21 +40,97 @@ function checkProfiles() {
         return { name: 'profiles', status: 'ok', detail: 'no profile dir (default profile only)' };
     }
     const profiles = listProfiles();
+    if (profiles.length === 0) {
+        return { name: 'profiles', status: 'ok', detail: 'profile dir empty' };
+    }
+    const labelled = profiles.map((p) => {
+        const meta = readProfileMeta(p);
+        if (meta?.label)
+            return `${p} (${meta.label})`;
+        return p;
+    });
     return {
         name: 'profiles',
         status: 'ok',
-        detail: profiles.length ? `found ${profiles.length}: ${profiles.join(', ')}` : 'profile dir empty',
+        detail: `found ${profiles.length}: ${labelled.join(', ')}`,
     };
 }
-function checkClockSkew() {
-    const now = Date.now();
-    const drift = now - Math.floor(now / 1000) * 1000;
-    // HMAC signing uses ms timestamps — we can't detect remote skew without a
-    // round-trip, but we can flag if the local clock has NTP issues via the
-    // classic "jumps back" pattern. Best-effort: just report local time.
-    const iso = new Date().toISOString();
-    return { name: 'clock', status: 'ok', detail: `local time ${iso} (drift check needs API round-trip)` };
-    void drift;
+async function checkClockSkew() {
+    // Real probe: HEAD the SwitchBot API endpoint and compare the server's Date
+    // header against local time. No auth required for the Date header — the API
+    // returns 401 but still stamps the response. Gracefully degrades to
+    // probeSource:'none' if offline / no network reachable.
+    //
+    // Under vitest, only run the probe if fetch has been stubbed (detected via
+    // vi.fn marker) — otherwise skip network I/O to keep unrelated tests fast.
+    const underVitest = Boolean(process.env.VITEST);
+    const fetchFn = globalThis.fetch;
+    const fetchIsMocked = Boolean(fetchFn && typeof fetchFn === 'function' && 'mock' in fetchFn);
+    if (underVitest && !fetchIsMocked) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: { probeSource: 'none', skewMs: null, message: 'skipped: test environment' },
+        };
+    }
+    const localBefore = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const res = await fetch('https://api.switch-bot.com/v1.1/devices', {
+            method: 'HEAD',
+            signal: ctrl.signal,
+        });
+        const localAfter = Date.now();
+        const dateHeader = res.headers.get('date');
+        if (!dateHeader) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: 'server returned no Date header' },
+            };
+        }
+        const serverMs = Date.parse(dateHeader);
+        if (!Number.isFinite(serverMs)) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: `unparseable Date header: ${dateHeader}` },
+            };
+        }
+        // Split the round-trip in half to estimate the local instant that matches
+        // the server's Date header. HTTP Date resolution is 1s, so treat anything
+        // under 2000ms as ok, 2000–60000ms as warn, beyond that as fail (HMAC
+        // auth rejects requests with skew > 5 minutes anyway).
+        const midpoint = (localBefore + localAfter) / 2;
+        const skewMs = Math.round(midpoint - serverMs);
+        const absSkew = Math.abs(skewMs);
+        const status = absSkew < 2000 ? 'ok' : absSkew < 60_000 ? 'warn' : 'fail';
+        return {
+            name: 'clock',
+            status,
+            detail: {
+                probeSource: 'api',
+                skewMs,
+                localIso: new Date(midpoint).toISOString(),
+                serverIso: new Date(serverMs).toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: {
+                probeSource: 'none',
+                skewMs: null,
+                message: `probe failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 function checkCatalog() {
     const catalog = getEffectiveCatalog();
@@ -153,7 +230,7 @@ Examples:
             checkCatalog(),
             checkCache(),
             checkQuotaFile(),
-            checkClockSkew(),
+            await checkClockSkew(),
             checkMqtt(),
         ];
         const summary = {
@@ -162,13 +239,27 @@ Examples:
             fail: checks.filter((c) => c.status === 'fail').length,
         };
         const overallFail = summary.fail > 0;
+        const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
         if (isJsonMode()) {
-            printJson({ overall: overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok', summary, checks });
+            // Stable contract (locked as doctor.schemaVersion=1):
+            //   { ok: boolean, overall: 'ok'|'warn'|'fail', generatedAt, schemaVersion,
+            //     summary: { ok, warn, fail }, checks: [{ name, status, detail }] }
+            // `ok` is an alias of (overall === 'ok') — agents prefer the boolean,
+            // humans prefer the string; both are provided.
+            printJson({
+                ok: overall === 'ok',
+                overall,
+                generatedAt: new Date().toISOString(),
+                schemaVersion: DOCTOR_SCHEMA_VERSION,
+                summary,
+                checks,
+            });
         }
         else {
             for (const c of checks) {
                 const icon = c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗';
-                console.log(`${icon} ${c.name.padEnd(12)} ${c.detail}`);
+                const detailStr = typeof c.detail === 'string' ? c.detail : JSON.stringify(c.detail);
+                console.log(`${icon} ${c.name.padEnd(12)} ${detailStr}`);
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);

package/dist/commands/events.js

@@ -1,4 +1,5 @@
 import http from 'node:http';
+import crypto from 'node:crypto';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { SwitchBotMqttClient } from '../mqtt/client.js';
@@ -16,6 +17,17 @@ import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
+function extractEventId(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    if (typeof p.eventId === 'string' && p.eventId.length > 0)
+        return p.eventId;
+    const ctx = p.context;
+    if (ctx && typeof ctx.eventId === 'string' && ctx.eventId.length > 0)
+        return ctx.eventId;
+    return null;
+}
 function matchFilter(body, filter) {
     if (!filter)
         return true;
@@ -220,7 +232,19 @@ Connects to the SwitchBot MQTT service using your existing credentials
 No additional MQTT configuration required.
 
 Output (JSONL, one event per line):
-  { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+  { "t": "<ISO>", "eventId": "<uuid>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+
+Control records (interleaved, no "payload" field — use type-prefix to filter):
+  { "type": "__connect",     "at": "<ISO>", "eventId": "<uuid>" }   first successful connect
+  { "type": "__reconnect",   "at": "<ISO>", "eventId": "<uuid>" }   connect after a disconnect
+  { "type": "__disconnect",  "at": "<ISO>", "eventId": "<uuid>" }   reconnecting or failed
+
+Reconnect policy: the MQTT client retries with exponential backoff
+(1s → 30s capped, forever) while the credential is still valid; if the
+credential is rejected or 5 consecutive reconnects fail, state goes to
+'failed' and the command exits non-zero so supervisors can restart it.
+QoS is 0 (at-most-once); agents requiring at-least-once delivery should
+fan-out via --sink file and deduplicate by eventId on the consumer side.
 
 Sink types (--sink, repeatable):
   stdout             Print JSONL to stdout (default when no --sink given)
@@ -321,9 +345,14 @@ Examples:
                     parsed = payload.toString('utf-8');
                 }
                 const t = new Date().toISOString();
+                // Every event carries an eventId so downstream sinks / replay tools
+                // can dedupe. If the broker supplied one (some providers do via a
+                // header), prefer that; otherwise synth a UUID locally.
+                const existingId = extractEventId(parsed);
+                const eventId = existingId ?? crypto.randomUUID();
                 if (dispatcher) {
                     const { deviceId, deviceType, text } = parseSinkEvent(parsed);
-                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text };
+                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text, eventId };
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
                     dispatcher.dispatch(sinkEvent).catch(() => { });
                 }
@@ -331,7 +360,7 @@ Examples:
                     // Default behavior: record history + print to stdout
                     const { deviceId, deviceType } = parseSinkEvent(parsed);
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
-                    const record = { t, topic: msgTopic, payload: parsed };
+                    const record = { t, eventId, topic: msgTopic, payload: parsed };
                     if (isJsonMode()) {
                         printJson(record);
                     }
@@ -345,12 +374,32 @@ Examples:
                 }
             });
             let mqttFailed = false;
+            let hasConnectedBefore = false;
+            const emitControl = (kind) => {
+                const ctl = { type: kind, at: new Date().toISOString(), eventId: crypto.randomUUID() };
+                // Control events always go to stdout as JSONL so consumers that
+                // filter real events by presence of `payload` can skip them.
+                if (isJsonMode()) {
+                    printJson(ctl);
+                }
+                else {
+                    console.log(JSON.stringify(ctl));
+                }
+            };
             const unsubState = client.onStateChange((state) => {
                 if (!isJsonMode()) {
                     console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
                 }
-                if (state === 'failed') {
+                if (state === 'connected') {
+                    emitControl(hasConnectedBefore ? '__reconnect' : '__connect');
+                    hasConnectedBefore = true;
+                }
+                else if (state === 'reconnecting') {
+                    emitControl('__disconnect');
+                }
+                else if (state === 'failed') {
                     mqttFailed = true;
+                    emitControl('__disconnect');
                     if (!isJsonMode()) {
                         console.error('MQTT connection failed permanently (credential expired or reconnect exhausted) — exiting.');
                     }

package/dist/commands/history.js

@@ -1,9 +1,10 @@
 import path from 'node:path';
 import os from 'node:os';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
-import { readAudit } from '../utils/audit.js';
+import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { readAudit, verifyAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
+import { queryDeviceHistory, queryDeviceHistoryStats, } from '../devices/history-query.js';
 const DEFAULT_AUDIT = path.join(os.homedir(), '.switchbot', 'audit.log');
 export function registerHistoryCommand(program) {
     const history = program
@@ -101,4 +102,125 @@ Examples:
             handleError(err);
         }
     });
+    history
+        .command('range')
+        .description('Query time-ranged device history from JSONL storage (populated by events mqtt-tail / MCP)')
+        .argument('<deviceId>', 'Device ID to query')
+        .option('--since <duration>', 'Relative window ending now, e.g. "30s", "15m", "1h", "7d" (mutually exclusive with --from/--to)', stringArg('--since'))
+        .option('--from <iso>', 'Range start (ISO-8601)', stringArg('--from'))
+        .option('--to <iso>', 'Range end (ISO-8601)', stringArg('--to'))
+        .option('--field <name>', 'Project a payload field (repeat to keep multiple)', (v, acc = []) => acc.concat(v), [])
+        .option('--limit <n>', 'Maximum records to return (default 1000)', intArg('--limit', { min: 1 }))
+        .addHelpText('after', `
+History is the append-only JSONL mirror of the per-device ring buffer: every
+'events mqtt-tail' event and every MCP tool status-refresh is written to
+~/.switchbot/device-history/<deviceId>.jsonl (rotates at 50MB × 3 files).
+
+Examples:
+  $ switchbot history range <id> --since 7d --json
+  $ switchbot history range <id> --since 1h --field temperature --field humidity
+  $ switchbot history range <id> --from 2026-04-18T00:00:00Z --to 2026-04-19T00:00:00Z
+`)
+        .action(async (deviceId, options) => {
+        // Usage-level validation: keep synchronous and pre-query so handleError
+        // maps these to exit 2 (via UsageError) rather than runtime exit 1.
+        if (options.since && (options.from || options.to)) {
+            handleError(new UsageError('--since is mutually exclusive with --from/--to.'));
+        }
+        try {
+            const records = await queryDeviceHistory(deviceId, {
+                since: options.since,
+                from: options.from,
+                to: options.to,
+                fields: options.field ?? [],
+                limit: options.limit !== undefined ? Number(options.limit) : undefined,
+            });
+            if (isJsonMode()) {
+                printJson({ deviceId, count: records.length, records });
+                return;
+            }
+            if (records.length === 0) {
+                console.log(`(no history records for ${deviceId} in requested range)`);
+                return;
+            }
+            for (const r of records) {
+                const payloadStr = JSON.stringify(r.payload);
+                console.log(`${r.t}  ${r.topic}  ${payloadStr}`);
+            }
+        }
+        catch (err) {
+            // Convert history-query's plain Error range messages into UsageError so
+            // they exit 2 instead of 1.
+            if (err instanceof Error && /^(Invalid --|--from|--since)/i.test(err.message)) {
+                handleError(new UsageError(err.message));
+            }
+            handleError(err);
+        }
+    });
+    history
+        .command('stats')
+        .description('Show on-disk size + record counts for a device history')
+        .argument('<deviceId>', 'Device ID to inspect')
+        .action((deviceId) => {
+        try {
+            const stats = queryDeviceHistoryStats(deviceId);
+            if (isJsonMode()) {
+                printJson(stats);
+                return;
+            }
+            console.log(`Device:        ${stats.deviceId}`);
+            console.log(`History dir:   ${stats.historyDir}`);
+            console.log(`JSONL files:   ${stats.fileCount} (${stats.jsonlFiles.join(', ') || '—'})`);
+            console.log(`Total size:    ${stats.totalBytes.toLocaleString()} bytes`);
+            console.log(`Record count:  ${stats.recordCount}`);
+            console.log(`Oldest:        ${stats.oldest ?? '—'}`);
+            console.log(`Newest:        ${stats.newest ?? '—'}`);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    history
+        .command('verify')
+        .description('Check the audit log for malformed lines and schema-version drift')
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
+        .addHelpText('after', `
+See docs/audit-log.md for the audit log format. Exit code:
+  0  every line parses and carries the current auditVersion
+  1  one or more lines are malformed OR the file is missing
+  2  (usage) — not emitted by this subcommand
+
+Examples:
+  $ switchbot history verify
+  $ switchbot history verify --file ./custom.log --json
+`)
+        .action((options) => {
+        const file = options.file ?? DEFAULT_AUDIT;
+        const report = verifyAudit(file);
+        if (isJsonMode()) {
+            printJson(report);
+        }
+        else {
+            console.log(`Audit log:       ${report.file}`);
+            console.log(`Parsed lines:    ${report.parsedLines} / ${report.totalLines}`);
+            console.log(`Malformed:       ${report.malformedLines}`);
+            console.log(`Unversioned:     ${report.unversionedEntries}`);
+            const versions = Object.entries(report.versionCounts)
+                .map(([v, n]) => `${v}:${n}`)
+                .join(', ');
+            console.log(`Version counts:  ${versions || '—'}`);
+            if (report.earliest)
+                console.log(`Earliest:        ${report.earliest}`);
+            if (report.latest)
+                console.log(`Latest:          ${report.latest}`);
+            if (report.problems.length > 0) {
+                console.log('\nProblems:');
+                for (const p of report.problems) {
+                    console.log(`  line ${p.line}: ${p.reason}${p.preview ? ` — "${p.preview}"` : ''}`);
+                }
+            }
+        }
+        const ok = report.malformedLines === 0 && report.problems.length === 0;
+        process.exit(ok ? 0 : 1);
+    });
 }

package/dist/commands/mcp.js

@@ -10,6 +10,7 @@ import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { deviceHistoryStore } from '../mcp/device-history.js';
+import { queryDeviceHistory } from '../devices/history-query.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
@@ -146,6 +147,47 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             structuredContent: result,
         };
     });
+    // ---- query_device_history --------------------------------------------------
+    server.registerTool('query_device_history', {
+        title: 'Query time-ranged device history',
+        description: 'Return records from the append-only JSONL history (~/.switchbot/device-history/<deviceId>.jsonl) ' +
+            'filtered by a relative duration (since) or absolute ISO-8601 range (from/to). ' +
+            'No API call — zero quota cost. Use for trend questions like "how many times did this switch turn on last week".',
+        inputSchema: {
+            deviceId: z.string().describe('Device ID to query'),
+            since: z.string().optional().describe('Relative window ending now, e.g. "30s", "15m", "1h", "7d". Mutually exclusive with from/to.'),
+            from: z.string().optional().describe('Range start (ISO-8601).'),
+            to: z.string().optional().describe('Range end (ISO-8601).'),
+            fields: z.array(z.string()).optional().describe('Project these payload fields; omit for the full payload.'),
+            limit: z.number().int().min(1).max(10000).optional().describe('Max records to return (default 1000).'),
+        },
+        outputSchema: {
+            deviceId: z.string(),
+            count: z.number().int(),
+            records: z.array(z.object({
+                t: z.string(),
+                topic: z.string(),
+                deviceType: z.string().optional(),
+                payload: z.unknown(),
+            })),
+        },
+    }, async ({ deviceId, since, from, to, fields, limit }) => {
+        if (since && (from || to)) {
+            return mcpError('usage', 2, '--since is mutually exclusive with --from/--to.');
+        }
+        try {
+            const records = await queryDeviceHistory(deviceId, { since, from, to, fields, limit });
+            const result = { deviceId, count: records.length, records };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'history query failed';
+            return mcpError('usage', 2, msg);
+        }
+    });
     // ---- send_command ---------------------------------------------------------
     server.registerTool('send_command', {
         title: 'Send a control command to a device',
@@ -167,14 +209,26 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 .optional()
                 .default(false)
                 .describe('Required true for destructive commands (unlock, garage open, createKey, ...)'),
+            idempotencyKey: z
+                .string()
+                .optional()
+                .describe('Deduplication key — repeat calls with the same key within 60s replay the first result (adds replayed:true). Same key + different (command, parameter) within 60s returns an idempotency_conflict guard error.'),
         },
         outputSchema: {
             ok: z.literal(true),
             command: z.string(),
             deviceId: z.string(),
             result: z.unknown().describe('API response body from SwitchBot'),
+            verification: z
+                .object({
+                verifiable: z.boolean(),
+                reason: z.string(),
+                suggestedFollowup: z.string(),
+            })
+                .optional()
+                .describe('Present when the target is an IR device. IR is unidirectional — agents should treat the success as "signal sent" not "state changed".'),
         },
-    }, async ({ deviceId, command, parameter, commandType, confirm }) => {
+    }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey }) => {
         const effectiveType = commandType ?? 'command';
         // Resolve the device's catalog type via cache or a fresh lookup so we
         // can evaluate destructive/validation without an extra round-trip if
@@ -217,8 +271,33 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         if (!validation.ok) {
             return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
         }
-        const result = await executeCommand(deviceId, command, parameter, effectiveType);
+        let result;
+        try {
+            result = await executeCommand(deviceId, command, parameter, effectiveType, undefined, {
+                idempotencyKey,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'IdempotencyConflictError') {
+                return mcpError('guard', 2, err.message, {
+                    hint: 'Use a fresh idempotencyKey, or wait for the prior key to expire (60s TTL).',
+                    context: {
+                        existingShape: err.existingShape,
+                        newShape: err.newShape,
+                    },
+                });
+            }
+            throw err;
+        }
+        const isIr = getCachedDevice(deviceId)?.category === 'ir';
         const structured = { ok: true, command, deviceId, result };
+        if (isIr) {
+            structured.verification = {
+                verifiable: false,
+                reason: 'IR transmission is unidirectional; no receipt acknowledgment is possible.',
+                suggestedFollowup: 'Confirm visible change manually or via a paired state sensor.',
+            };
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
             structuredContent: structured,

package/dist/commands/quota.js

@@ -11,17 +11,19 @@ is a best-effort mirror of the SwitchBot 10,000/day limit — it does not
 include requests made outside this CLI (mobile app, other scripts).
 
 Subcommands:
-  status   Show today's usage and the last 7 days
+  status   Show today's usage and the last 7 days (alias: show)
   reset    Delete the local counter file
 
 Examples:
   $ switchbot quota status
+  $ switchbot quota show            # alias of 'status'
   $ switchbot quota status --json
   $ switchbot quota reset
 `);
     quota
         .command('status')
-        .description("Show today's usage and the last 7 days")
+        .alias('show')
+        .description("Show today's usage and the last 7 days (alias: show)")
         .action(() => {
         const usage = todayUsage();
         const history = loadQuota();