@switchbot/openapi-cli 2.2.1 → 2.4.0

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();

package/dist/commands/schema.js

@@ -1,6 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
+import { loadCache } from '../devices/cache.js';
 function toSchemaEntry(e) {
     return {
         type: e.type,
@@ -24,6 +25,30 @@ function toSchemaCommand(c) {
         ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
     };
 }
+function toCompactEntry(e) {
+    return {
+        type: e.type,
+        category: e.category,
+        role: e.role ?? null,
+        readOnly: e.readOnly ?? false,
+        commands: e.commands.map((c) => ({
+            command: c.command,
+            parameter: c.parameter,
+            commandType: (c.commandType ?? 'command'),
+            idempotent: Boolean(c.idempotent),
+            destructive: Boolean(c.destructive),
+        })),
+        statusFields: e.statusFields ?? [],
+    };
+}
+function projectFields(entry, fields) {
+    const out = {};
+    for (const f of fields) {
+        if (f in entry)
+            out[f] = entry[f];
+    }
+    return out;
+}
 export function registerSchemaCommand(program) {
     const ROLES = ['lighting', 'security', 'sensor', 'climate', 'media', 'cleaning', 'curtain', 'fan', 'power', 'hub', 'other'];
     const CATEGORIES = ['physical', 'ir'];
@@ -32,20 +57,41 @@ export function registerSchemaCommand(program) {
         .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
     schema
         .command('export')
-        .description('Print the full catalog as structured JSON (one object per type)')
+        .description('Print the catalog as structured JSON (one object per type)')
         .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")', stringArg('--type'))
+        .option('--types <csv>', 'Restrict to multiple device types (comma-separated)', stringArg('--types'))
         .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other', enumArg('--role', ROLES))
         .option('--category <cat>', 'Restrict to "physical" or "ir"', enumArg('--category', CATEGORIES))
+        .option('--compact', 'Drop descriptions/aliases/example params — emit ~60% smaller payload. Useful for agent prompts.')
+        .option('--used', 'Restrict to device types present in the local devices cache (run "devices list" first)')
+        .option('--project <csv>', 'Project per-type fields (e.g. --project type,commands,statusFields)', stringArg('--project'))
         .addHelpText('after', `
 Output is always JSON (this command ignores --format). The output is a
 catalog export — not a formal JSON Schema standard document — suitable for
 pre-baking LLM prompts or regenerating docs when the catalog changes.
 
+Size tips:
+  --compact --used          Smallest realistic payload for a given account
+                            (< 15 KB on most accounts).
+  --fields type,commands    Strip statusFields / role / etc. when only
+                            commands are needed.
+  --type + --compact        Inspect one type with minimum footprint.
+
+Common top-level fields:
+  schemaVersion             CLI schema version (stable for agent contracts)
+  data.version              Catalog schema version
+  data.types                Array of SchemaEntry (or CompactSchemaEntry with --compact)
+  data._fetchedAt           CLI-added; present on live-query responses ('devices status'),
+                            not on this offline export.
+
 Examples:
   $ switchbot schema export > catalog.json
-  $ switchbot schema export --type Bot | jq '.types[0].commands'
-  $ switchbot schema export --role lighting | jq '[.types[].type]'
+  $ switchbot schema export --compact --used | wc -c   # small prompt-ready payload
+  $ switchbot schema export --type Bot | jq '.data.types[0].commands'
+  $ switchbot schema export --types "Bot,Curtain,Color Bulb"
+  $ switchbot schema export --role lighting | jq '[.data.types[].type]'
   $ switchbot schema export --role security --category physical
+  $ switchbot schema export --project type,commands,statusFields
 `)
         .action((options) => {
         const catalog = getEffectiveCatalog();
@@ -55,6 +101,11 @@ Examples:
             filtered = filtered.filter((e) => e.type.toLowerCase() === q ||
                 (e.aliases ?? []).some((a) => a.toLowerCase() === q));
         }
+        if (options.types) {
+            const set = new Set(options.types.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean));
+            filtered = filtered.filter((e) => set.has(e.type.toLowerCase()) ||
+                (e.aliases ?? []).some((a) => set.has(a.toLowerCase())));
+        }
         if (options.role) {
             const q = options.role.toLowerCase();
             filtered = filtered.filter((e) => (e.role ?? 'other') === q);
@@ -63,11 +114,50 @@ Examples:
             const q = options.category.toLowerCase();
             filtered = filtered.filter((e) => e.category === q);
         }
+        if (options.used) {
+            const cache = loadCache();
+            if (cache) {
+                const usedTypes = new Set(Object.values(cache.devices).map((d) => d.type.toLowerCase()));
+                filtered = filtered.filter((e) => usedTypes.has(e.type.toLowerCase()) ||
+                    (e.aliases ?? []).some((a) => usedTypes.has(a.toLowerCase())));
+            }
+            else {
+                filtered = [];
+            }
+        }
+        const mapped = options.compact
+            ? filtered.map(toCompactEntry)
+            : filtered.map(toSchemaEntry);
+        const projected = options.project
+            ? mapped.map((e) => projectFields(e, options.project.split(',').map((s) => s.trim()).filter(Boolean)))
+            : mapped;
         const payload = {
             version: '1.0',
-            generatedAt: new Date().toISOString(),
-            types: filtered.map(toSchemaEntry),
+            types: projected,
         };
+        if (!options.compact) {
+            payload.generatedAt = new Date().toISOString();
+            payload.cliAddedFields = [
+                {
+                    field: '_fetchedAt',
+                    appliesTo: ['devices status', 'devices describe'],
+                    type: 'string (ISO-8601)',
+                    description: 'CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API.',
+                },
+                {
+                    field: 'replayed',
+                    appliesTo: ['devices command (with --idempotency-key)'],
+                    type: 'boolean',
+                    description: 'CLI-synthesized flag — true when the response was served from the idempotency cache instead of re-executing the command.',
+                },
+                {
+                    field: 'verification',
+                    appliesTo: ['devices command'],
+                    type: 'object',
+                    description: 'CLI-synthesized receipt-acknowledgment metadata. For IR devices, verifiable:false signals that no device-side confirmation is possible.',
+                },
+            ];
+        }
         printJson(payload);
     });
 }

package/dist/config.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import os from 'node:os';
 import { getConfigPath } from './utils/flags.js';
 import { getActiveProfile } from './lib/request-context.js';
+function sanitizeOptionalString(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed ? trimmed : undefined;
+}
 /**
  * Credential file resolution priority:
  *   1. --config <path> (absolute override — wins over everything)
@@ -85,15 +91,70 @@ export function tryLoadConfig() {
         return null;
     }
 }
-export function saveConfig(token, secret) {
+export function saveConfig(token, secret, extras) {
     const file = configFilePath();
     const dir = path.dirname(file);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const cfg = { token, secret };
+    // Merge with existing file so label/limits/defaults aren't dropped when the
+    // user just rotates the token.
+    let existing = {};
+    if (fs.existsSync(file)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const cfg = {
+        token,
+        secret,
+        ...(existing.label ? { label: existing.label } : {}),
+        ...(existing.description ? { description: existing.description } : {}),
+        ...(existing.limits ? { limits: existing.limits } : {}),
+        ...(existing.defaults ? { defaults: existing.defaults } : {}),
+    };
+    if (extras) {
+        const label = sanitizeOptionalString(extras.label);
+        const description = sanitizeOptionalString(extras.description);
+        if (label !== undefined)
+            cfg.label = label;
+        if (description !== undefined)
+            cfg.description = description;
+        if (extras.limits)
+            cfg.limits = { ...(cfg.limits ?? {}), ...extras.limits };
+        if (extras.defaults)
+            cfg.defaults = { ...(cfg.defaults ?? {}), ...extras.defaults };
+    }
     fs.writeFileSync(file, JSON.stringify(cfg, null, 2), { mode: 0o600 });
 }
+/**
+ * Read a profile's metadata (label / description / limits / defaults) without
+ * exposing the token/secret. Returns null when the file is missing or invalid.
+ */
+export function readProfileMeta(profile) {
+    const file = profile
+        ? profileFilePath(profile)
+        : path.join(os.homedir(), '.switchbot', 'config.json');
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const cfg = JSON.parse(raw);
+        return {
+            label: cfg.label,
+            description: cfg.description,
+            limits: cfg.limits,
+            defaults: cfg.defaults,
+            path: file,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 export function showConfig() {
     const envToken = process.env.SWITCHBOT_TOKEN;
     const envSecret = process.env.SWITCHBOT_SECRET;
@@ -112,8 +173,16 @@ export function showConfig() {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         console.log(`Credential source: ${file}`);
+        if (cfg.label)
+            console.log(`label : ${cfg.label}`);
+        if (cfg.description)
+            console.log(`desc  : ${cfg.description}`);
         console.log(`token : ${maskCredential(cfg.token)}`);
         console.log(`secret: ${maskSecret(cfg.secret)}`);
+        if (cfg.limits?.dailyCap)
+            console.log(`limits: dailyCap=${cfg.limits.dailyCap}`);
+        if (cfg.defaults?.flags?.length)
+            console.log(`defaults: ${cfg.defaults.flags.join(' ')}`);
     }
     catch {
         console.error('Failed to read config file');