@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/api/client.js

@@ -4,7 +4,23 @@ import { buildAuthHeaders } from '../auth.js';
 import { loadConfig } from '../config.js';
 import { isVerbose, isDryRun, getTimeout, getRetryOn429, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
 import { nextRetryDelayMs, sleep } from '../utils/retry.js';
-import { recordRequest } from '../utils/quota.js';
+import { recordRequest, checkDailyCap } from '../utils/quota.js';
+import { readProfileMeta } from '../config.js';
+import { getActiveProfile } from '../lib/request-context.js';
+import { redactHeaders, warnOnceIfUnsafe } from '../utils/redact.js';
+class DailyCapExceededError extends Error {
+    cap;
+    total;
+    profile;
+    constructor(cap, total, profile) {
+        super(`Local daily cap reached: ${total}/${cap} SwitchBot API calls used today${profile ? ` for profile "${profile}"` : ''}. ` +
+            `Raise with: switchbot ${profile ? `--profile ${profile} ` : ''}config set-token --daily-cap <N>`);
+        this.cap = cap;
+        this.total = total;
+        this.profile = profile;
+        this.name = 'DailyCapExceededError';
+    }
+}
 const API_ERROR_MESSAGES = {
     151: 'Device type does not support this command',
     152: 'Device ID does not exist',
@@ -31,18 +47,34 @@ export function createClient() {
     const maxRetries = getRetryOn429();
     const backoff = getBackoffStrategy();
     const quotaEnabled = !isQuotaDisabled();
+    const profile = getActiveProfile();
+    const profileMeta = readProfileMeta(profile);
+    const dailyCap = profileMeta?.limits?.dailyCap;
     const client = axios.create({
         baseURL: 'https://api.switch-bot.com',
         timeout: getTimeout(),
     });
     // Inject auth headers; optionally log the request; short-circuit on --dry-run.
     client.interceptors.request.use((config) => {
+        // Pre-flight cap check: refuse the call before it touches the network.
+        if (dailyCap) {
+            const check = checkDailyCap(dailyCap);
+            if (check.over) {
+                throw new DailyCapExceededError(dailyCap, check.total, profile);
+            }
+        }
         const authHeaders = buildAuthHeaders(token, secret);
         Object.assign(config.headers, authHeaders);
         const method = (config.method ?? 'get').toUpperCase();
         const url = `${config.baseURL ?? ''}${config.url ?? ''}`;
         if (verbose) {
+            warnOnceIfUnsafe();
             process.stderr.write(chalk.grey(`[verbose] ${method} ${url}\n`));
+            const { safe, redactedCount } = redactHeaders(config.headers);
+            process.stderr.write(chalk.grey(`[verbose] headers: ${JSON.stringify(safe)}\n`));
+            if (redactedCount > 0) {
+                process.stderr.write(chalk.grey(`[verbose] 🔒 ${redactedCount} sensitive header(s) redacted.\n`));
+            }
             if (config.data !== undefined) {
                 process.stderr.write(chalk.grey(`[verbose] body: ${JSON.stringify(config.data)}\n`));
             }

package/dist/commands/agent-bootstrap.js

@@ -0,0 +1,128 @@
+import { printJson } from '../utils/output.js';
+import { loadCache } from '../devices/cache.js';
+import { getEffectiveCatalog } from '../devices/catalog.js';
+import { readProfileMeta } from '../config.js';
+import { todayUsage, DAILY_QUOTA } from '../utils/quota.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',
+};
+const SAFETY_TIERS = {
+    read: 'No state mutation; safe to call freely.',
+    action: 'Mutates device/cloud state but reversible (turnOn, setColor).',
+    destructive: 'Hard to reverse / physical-world side effects (unlock). Requires confirmation.',
+};
+const QUICK_REFERENCE = {
+    discovery: ['devices list', 'devices describe <id>', 'devices status <id>'],
+    action: ['devices command <id> <cmd>', 'devices command --name <q> <cmd>', 'scenes execute <id>'],
+    safety: ['--dry-run', '--idempotency-key <k>', '--audit-log', '--no-quota'],
+    observability: ['doctor --json', 'quota status', 'cache status', 'events mqtt-tail'],
+    history: ['history range <id> --since 7d', 'history stats <id>'],
+};
+export function registerAgentBootstrapCommand(program) {
+    program
+        .command('agent-bootstrap')
+        .description('Print a compact, aggregate JSON snapshot for agent onboarding — combines identity, cached devices, catalog summary, quota usage, and profile in a single call. Offline-safe; does not hit the API.')
+        .option('--compact', 'Emit an even smaller payload by dropping catalog descriptions and non-essential fields (target: <20 KB).')
+        .addHelpText('after', `
+Output is always JSON (this command ignores --format). It is a one-shot
+orientation document for an agent/LLM to understand what's available without
+spending quota. It reads from local cache (devices + quota + profile) and the
+bundled catalog — no network calls.
+
+For fresher device state, have the agent follow up with:
+  $ switchbot devices list --json               # refreshes cache
+  $ switchbot devices status <id> --json
+
+Examples:
+  $ switchbot agent-bootstrap --compact | wc -c   # fit in agent context window
+  $ switchbot agent-bootstrap | jq '.devices | length'
+  $ switchbot agent-bootstrap --compact | jq '.quickReference'
+`)
+        .action((opts) => {
+        const compact = Boolean(opts.compact);
+        const cache = loadCache();
+        const catalog = getEffectiveCatalog();
+        const usage = todayUsage();
+        const meta = readProfileMeta(undefined);
+        const cachedDevices = cache
+            ? Object.entries(cache.devices).map(([id, d]) => ({
+                deviceId: id,
+                type: d.type,
+                name: d.name,
+                category: d.category,
+                roomName: d.roomName ?? null,
+            }))
+            : [];
+        const usedTypes = new Set(cachedDevices.map((d) => d.type.toLowerCase()));
+        const relevantCatalog = cachedDevices.length > 0
+            ? catalog.filter((e) => usedTypes.has(e.type.toLowerCase()) ||
+                (e.aliases ?? []).some((a) => usedTypes.has(a.toLowerCase())))
+            : catalog;
+        const catalogTypes = relevantCatalog.map((e) => {
+            if (compact) {
+                return {
+                    type: e.type,
+                    category: e.category,
+                    role: e.role ?? null,
+                    readOnly: e.readOnly ?? false,
+                    commands: e.commands.map((c) => c.command),
+                    statusFields: e.statusFields ?? [],
+                };
+            }
+            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,
+                    destructive: Boolean(c.destructive),
+                    idempotent: Boolean(c.idempotent),
+                })),
+                statusFields: e.statusFields ?? [],
+            };
+        });
+        const payload = {
+            schemaVersion: '1.0',
+            generatedAt: new Date().toISOString(),
+            cliVersion: pkgVersion,
+            identity: IDENTITY,
+            quickReference: QUICK_REFERENCE,
+            safetyTiers: SAFETY_TIERS,
+            profile: meta
+                ? {
+                    label: meta.label ?? null,
+                    description: meta.description ?? null,
+                    dailyCap: meta.limits?.dailyCap ?? null,
+                    defaultFlags: meta.defaults?.flags ?? null,
+                }
+                : null,
+            quota: {
+                date: usage.date,
+                total: usage.total,
+                remaining: usage.remaining,
+                dailyLimit: DAILY_QUOTA,
+            },
+            devices: cachedDevices,
+            catalog: {
+                scope: cachedDevices.length > 0 ? 'used' : 'all',
+                types: catalogTypes,
+            },
+            // hints: empty array means no hints to report; always emitted, never null.
+            // An empty array signals "nothing to act on" — agents should not treat
+            // it as a disabled or missing field.
+            hints: cachedDevices.length === 0
+                ? ['Run `switchbot devices list` once to populate the device cache for richer bootstrap output.']
+                : [],
+        };
+        printJson(payload);
+    });
+}

package/dist/commands/batch.js

@@ -8,8 +8,12 @@ import { DryRunSignal } from '../api/client.js';
 import { getCachedTypeMap } from '../devices/cache.js';
 const DEFAULT_CONCURRENCY = 5;
 const COMMAND_TYPES = ['command', 'customize'];
-/** Run `task(x)` for every element with at most `concurrency` running at once. */
-async function runPool(items, concurrency, task) {
+/**
+ * Run `task(x)` for every element with at most `concurrency` running at once.
+ * `staggerMs`: when > 0, delay each task start by this fixed interval (replaces
+ * the default 20-60ms jitter). Useful for rate-limited endpoints.
+ */
+async function runPool(items, concurrency, staggerMs, task) {
     const results = new Array(items.length);
     let cursor = 0;
     const workers = [];
@@ -19,9 +23,10 @@ async function runPool(items, concurrency, task) {
             while (cursor < items.length) {
                 const idx = cursor++;
                 results[idx] = await task(items[idx]);
-                // Tiny jitter between starts so we don't hammer the endpoint in a
-                // perfectly aligned burst. Keeps the default concurrency=5 polite.
-                await new Promise((r) => setTimeout(r, 20 + Math.random() * 40));
+                // Fixed stagger wins over random jitter when set; else keep the
+                // default polite spacing so we don't hammer the endpoint.
+                const delay = staggerMs > 0 ? staggerMs : 20 + Math.random() * 40;
+                await new Promise((r) => setTimeout(r, delay));
             }
         })());
     }
@@ -89,10 +94,13 @@ export function registerBatchCommand(devices) {
         .option('--filter <expr>', 'Target devices matching a filter, e.g. type=Bot,family=Home', stringArg('--filter'))
         .option('--ids <csv>', 'Explicit comma-separated list of deviceIds', stringArg('--ids'))
         .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('--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 "-")')
-        .option('--idempotency-key-prefix <prefix>', 'Prefix for idempotency keys (key per device: <prefix>-<deviceId>)', stringArg('--idempotency-key-prefix'))
+        .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key-prefix'))
         .addHelpText('after', `
 Targets are resolved in this priority order:
   1. --ids when present       (explicit deviceIds)
@@ -109,7 +117,16 @@ Supported keys:  type, family, room, category  (category: physical | ir)
 
 Output:
   Human mode:  one status line per device, summary at the end.
-  --json:      {succeeded[], failed[{deviceId,error}], summary:{total,ok,failed,skipped,durationMs}}
+  --json:      {succeeded[], failed[{deviceId,error}], summary:{total,ok,failed,skipped,durationMs,maxConcurrent,staggerMs}}
+  Each step includes startedAt / finishedAt / durationMs / replayed (when cached).
+
+Concurrency & pacing:
+  --max-concurrent <n>   Upper bound on in-flight requests (alias for --concurrency).
+  --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
+                         for agents that want to show the user what will run.
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
@@ -212,10 +229,48 @@ Examples:
                 // keep as string
             }
         }
-        const concurrency = Math.max(1, Number.parseInt(options.concurrency, 10) || DEFAULT_CONCURRENCY);
+        const maxConcurrentRaw = options.maxConcurrent ?? options.concurrency;
+        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) {
+            const steps = resolved.ids.map((id) => ({
+                deviceId: id,
+                command: cmd,
+                parameter: parsedParam,
+                type: effectiveType,
+                idempotencyKey: options.idempotencyKeyPrefix
+                    ? `${options.idempotencyKeyPrefix}-${id}`
+                    : undefined,
+            }));
+            const planDoc = {
+                schemaVersion: '1.1',
+                dryRun: true,
+                plan: {
+                    command: cmd,
+                    parameter: parsedParam,
+                    type: effectiveType,
+                    maxConcurrent: concurrency,
+                    staggerMs,
+                    stepCount: steps.length,
+                    steps,
+                },
+            };
+            if (isJsonMode()) {
+                printJson(planDoc);
+            }
+            else {
+                console.log(`Plan: ${steps.length} step(s), command=${cmd}, maxConcurrent=${concurrency}, staggerMs=${staggerMs}`);
+                for (const s of steps)
+                    console.log(`  → ${s.deviceId} ${s.type} ${s.command}`);
+            }
+            return;
+        }
         const startedAt = Date.now();
-        const outcomes = await runPool(resolved.ids, concurrency, async (id) => {
+        const outcomes = await runPool(resolved.ids, concurrency, staggerMs, async (id) => {
+            const stepStart = Date.now();
+            const startedIso = new Date(stepStart).toISOString();
             try {
                 const idempotencyKey = options.idempotencyKeyPrefix
                     ? `${options.idempotencyKeyPrefix}-${id}`
@@ -223,30 +278,67 @@ Examples:
                 const result = await executeCommand(id, cmd, parsedParam, effectiveType, getClient(), {
                     idempotencyKey,
                 });
+                const finishedIso = new Date().toISOString();
+                const durationMs = Date.now() - stepStart;
+                const replayed = typeof result === 'object' && result !== null && result.replayed === true;
                 if (!isJsonMode()) {
-                    console.log(`✓ ${id}: ${cmd}`);
+                    console.log(`✓ ${id}: ${cmd}${replayed ? ' (replayed)' : ''}`);
                 }
-                return { ok: true, deviceId: id, result };
+                return {
+                    ok: true,
+                    deviceId: id,
+                    result,
+                    startedAt: startedIso,
+                    finishedAt: finishedIso,
+                    durationMs,
+                    replayed,
+                };
             }
             catch (err) {
                 // --dry-run uses DryRunSignal to short-circuit; surface that as a
                 // "skipped" outcome, not a failure.
                 if (err instanceof DryRunSignal) {
-                    return { ok: 'dry-run', deviceId: id };
+                    return {
+                        ok: 'dry-run',
+                        deviceId: id,
+                        startedAt: startedIso,
+                        finishedAt: new Date().toISOString(),
+                        durationMs: Date.now() - stepStart,
+                    };
                 }
                 const errorPayload = buildErrorPayload(err);
                 if (!isJsonMode()) {
                     console.error(`✗ ${id}: ${errorPayload.message}`);
                 }
-                return { ok: false, deviceId: id, error: errorPayload };
+                return {
+                    ok: false,
+                    deviceId: id,
+                    error: errorPayload,
+                    startedAt: startedIso,
+                    finishedAt: new Date().toISOString(),
+                    durationMs: Date.now() - stepStart,
+                };
             }
         });
         const succeeded = outcomes.filter((o) => o.ok === true);
         const failed = outcomes.filter((o) => o.ok === false);
         const dryRunned = outcomes.filter((o) => o.ok === 'dry-run');
         const result = {
-            succeeded: succeeded.map((s) => ({ deviceId: s.deviceId, result: s.result })),
-            failed: failed.map((f) => ({ deviceId: f.deviceId, error: f.error })),
+            succeeded: succeeded.map((s) => ({
+                deviceId: s.deviceId,
+                result: s.result,
+                startedAt: s.startedAt,
+                finishedAt: s.finishedAt,
+                durationMs: s.durationMs,
+                replayed: s.replayed,
+            })),
+            failed: failed.map((f) => ({
+                deviceId: f.deviceId,
+                error: f.error,
+                startedAt: f.startedAt,
+                finishedAt: f.finishedAt,
+                durationMs: f.durationMs,
+            })),
             summary: {
                 total: resolved.ids.length,
                 ok: succeeded.length,
@@ -254,6 +346,8 @@ Examples:
                 skipped: dryRunned.length,
                 durationMs: Date.now() - startedAt,
                 schemaVersion: '1.1',
+                maxConcurrent: concurrency,
+                staggerMs,
                 ...(dryRun ? { dryRun: true } : {}),
             },
         };

package/dist/commands/cache.js

@@ -46,6 +46,7 @@ Examples:
 `);
     cache
         .command('show')
+        .alias('status')
         .description('Summarize the cache files (paths, ages, entry counts)')
         .action(() => {
         const summary = describeCache();