@switchbot/openapi-cli 3.1.0 → 3.2.0

package/dist/policy/schema/v0.2.json

@@ -18,7 +18,7 @@
       "description": "Unchanged from v0.1.",
       "additionalProperties": {
         "type": "string",
-        "pattern": "^[A-Z0-9]{2,}-[A-Z0-9-]+$"
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$"
       }
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "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",
@@ -37,7 +37,7 @@
   },
   "scripts": {
     "build": "tsc && node scripts/copy-assets.mjs",
-    "build:prod": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "build:prod": "node scripts/bundle.mjs && node scripts/copy-assets.mjs",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "dev": "tsx src/index.ts",
     "lint:md": "markdownlint \"**/*.md\"",
@@ -69,6 +69,7 @@
     "@types/node": "^22.10.7",
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^2.1.9",
+    "esbuild": "^0.28.0",
     "markdownlint-cli": "^0.48.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",

package/dist/api/client.js

@@ -1,235 +0,0 @@
-import axios from 'axios';
-import chalk from 'chalk';
-import { buildAuthHeaders } from '../auth.js';
-import { loadConfig } from '../config.js';
-import { isVerbose, isDryRun, getTimeout, getRetryOn429, getRetryOn5xx, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
-import { nextRetryDelayMs, sleep, CircuitBreaker, CircuitOpenError } from '../utils/retry.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',
-    160: 'This device does not support this command',
-    161: 'Device offline (check Wi-Fi / Bluetooth connection)',
-    171: 'Hub device offline (BLE devices require a Hub to communicate)',
-    190: 'Device internal error — often an invalid deviceId, unsupported parameter, or device busy',
-};
-/** Thrown by the request interceptor when --dry-run intercepts a mutating call. */
-export class DryRunSignal extends Error {
-    method;
-    url;
-    constructor(method, url) {
-        super('dry-run');
-        this.method = method;
-        this.url = url;
-        this.name = 'DryRunSignal';
-    }
-}
-/**
- * Module-level circuit breaker for the SwitchBot API. Shared across all
- * client instances in the process. Opens after 5 consecutive 5xx / network
- * errors; resets to half-open after 60 s.
- * Exported for health-check inspection.
- */
-export const apiCircuitBreaker = new CircuitBreaker('switchbot-api', {
-    failureThreshold: 5,
-    resetTimeoutMs: 60_000,
-});
-export { CircuitOpenError };
-export function createClient() {
-    const { token, secret } = loadConfig();
-    const verbose = isVerbose();
-    const dryRun = isDryRun();
-    const maxRetries = getRetryOn429();
-    const max5xxRetries = getRetryOn5xx();
-    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) => {
-        // Circuit breaker check — fail fast when the API is consistently down.
-        apiCircuitBreaker.checkAndAllow();
-        // 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`));
-            }
-        }
-        if (dryRun && method !== 'GET') {
-            process.stderr.write(chalk.yellow(`[dry-run] Would ${method} ${url}\n`));
-            if (config.data !== undefined) {
-                process.stderr.write(chalk.yellow(`[dry-run] body: ${JSON.stringify(config.data)}\n`));
-            }
-            throw new DryRunSignal(method, url);
-        }
-        // P8: record the quota attempt BEFORE the request is dispatched so
-        // failures (timeouts / DNS errors / 5xx / aborted) also count. Only
-        // pre-flight refusals (daily-cap, --dry-run) above skip recording
-        // since they never touch the network. Retries re-enter this
-        // interceptor and record again, which matches the SwitchBot API
-        // billing model (every dispatched HTTP request consumes quota).
-        if (quotaEnabled) {
-            recordRequest(method, url);
-        }
-        return config;
-    });
-    // Handle API-level errors (HTTP 200 but statusCode !== 100)
-    client.interceptors.response.use((response) => {
-        if (verbose) {
-            process.stderr.write(chalk.grey(`[verbose] ${response.status} ${response.statusText}\n`));
-        }
-        const data = response.data;
-        if (data.statusCode !== undefined && data.statusCode !== 100) {
-            const msg = API_ERROR_MESSAGES[data.statusCode] ??
-                data.message ??
-                `API error code: ${data.statusCode}`;
-            throw new ApiError(msg, data.statusCode);
-        }
-        // Successful HTTP response — record for circuit breaker.
-        apiCircuitBreaker.recordSuccess();
-        return response;
-    }, (error) => {
-        if (error instanceof DryRunSignal)
-            throw error;
-        if (axios.isAxiosError(error)) {
-            const config = error.config;
-            const method = (config?.method ?? 'get').toUpperCase();
-            const isIdempotentRead = method === 'GET';
-            if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
-                // Retry idempotent GETs on timeout up to `max5xxRetries` times.
-                if (isIdempotentRead && config && max5xxRetries > 0) {
-                    const attempt = config.__retryCount ?? 0;
-                    if (attempt < max5xxRetries) {
-                        config.__retryCount = attempt + 1;
-                        const delay = nextRetryDelayMs(attempt, backoff, undefined);
-                        if (verbose) {
-                            process.stderr.write(chalk.grey(`[verbose] timeout — retry ${attempt + 1}/${max5xxRetries} in ${delay}ms\n`));
-                        }
-                        return sleep(delay).then(() => client.request(config));
-                    }
-                }
-                // Network-level failure — record for circuit breaker.
-                apiCircuitBreaker.recordFailure();
-                throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: isIdempotentRead });
-            }
-            const status = error.response?.status;
-            // 429 → transparent retry with Retry-After / exponential backoff.
-            // Skipped when: no config (shouldn't happen for real axios errors),
-            // retries disabled, or we've already used our budget.
-            if (status === 429 && config && maxRetries > 0) {
-                const attempt = config.__retryCount ?? 0;
-                if (attempt < maxRetries) {
-                    config.__retryCount = attempt + 1;
-                    const delay = nextRetryDelayMs(attempt, backoff, error.response?.headers?.['retry-after']);
-                    if (verbose) {
-                        process.stderr.write(chalk.grey(`[verbose] 429 received — retry ${attempt + 1}/${maxRetries} in ${delay}ms\n`));
-                    }
-                    return sleep(delay).then(() => client.request(config));
-                }
-            }
-            // 502/503/504 on idempotent GETs → transparent retry. Mutating calls
-            // never auto-retry; use --idempotency-key for safe POST retries.
-            if (isIdempotentRead &&
-                status !== undefined &&
-                (status === 502 || status === 503 || status === 504) &&
-                config &&
-                max5xxRetries > 0) {
-                const attempt = config.__retryCount ?? 0;
-                if (attempt < max5xxRetries) {
-                    config.__retryCount = attempt + 1;
-                    const delay = nextRetryDelayMs(attempt, backoff, error.response?.headers?.['retry-after']);
-                    if (verbose) {
-                        process.stderr.write(chalk.grey(`[verbose] ${status} received — retry ${attempt + 1}/${max5xxRetries} in ${delay}ms\n`));
-                    }
-                    return sleep(delay).then(() => client.request(config));
-                }
-            }
-            // Record 5xx and network errors for circuit breaker. 4xx errors are
-            // expected business responses — don't count toward circuit threshold.
-            if (status === undefined || status >= 500) {
-                apiCircuitBreaker.recordFailure();
-            }
-            // P8: quota already recorded in the request interceptor before
-            // dispatch — no extra bookkeeping needed here on the error path.
-            // Timeouts, DNS failures, 5xx, and exhausted retries all counted
-            // when the attempt was first made.
-            if (status === 401) {
-                throw new ApiError('Authentication failed: invalid token or daily 10,000-request quota exceeded', 401, {
-                    transient: false,
-                    retryable: false,
-                    hint: 'Run `switchbot config set-token <token> <secret>` to re-enter credentials, or `switchbot quota status` to check today\'s local count.'
-                });
-            }
-            if (status === 429) {
-                const retryAfter = error.response?.headers?.['retry-after'];
-                const retryAfterMs = nextRetryDelayMs(maxRetries - 1, backoff, retryAfter);
-                throw new ApiError('Request rate too high: daily 10,000-request quota exceeded (retries exhausted)', 429, {
-                    retryable: true,
-                    transient: true,
-                    retryAfterMs,
-                    hint: 'Use `switchbot quota status` to see today\'s usage; raise `--retry-on-429 <n>` for more retries.'
-                });
-            }
-            throw new ApiError(`HTTP ${status ?? '?'}: ${error.message}`, status ?? 0, {
-                retryable: status !== undefined && status >= 500,
-                transient: status !== undefined && (status >= 500 || status === 0) // 5xx, 0 = connection error
-            });
-        }
-        throw error;
-    });
-    return client;
-}
-export class ApiError extends Error {
-    code;
-    retryable;
-    hint;
-    retryAfterMs;
-    transient;
-    constructor(message, code, meta = {}) {
-        super(message);
-        this.code = code;
-        this.name = 'ApiError';
-        this.retryable = meta.retryable ?? false;
-        this.hint = meta.hint;
-        this.retryAfterMs = meta.retryAfterMs;
-        this.transient = meta.transient ?? false;
-    }
-}

package/dist/auth.js

@@ -1,20 +0,0 @@
-import crypto from 'node:crypto';
-import { v4 as uuidv4 } from 'uuid';
-export function buildAuthHeaders(token, secret) {
-    const t = String(Date.now()); // 13-digit millisecond timestamp
-    const nonce = uuidv4(); // unique per request
-    const data = token + t + nonce;
-    const sign = crypto
-        .createHmac('sha256', secret)
-        .update(data)
-        .digest('base64')
-        .toUpperCase(); // API requires uppercase
-    return {
-        Authorization: token,
-        t,
-        sign,
-        nonce,
-        src: 'OpenClaw',
-        'Content-Type': 'application/json',
-    };
-}

package/dist/commands/agent-bootstrap.js

@@ -1,182 +0,0 @@
-import { printJson } from '../utils/output.js';
-import { loadCache } from '../devices/cache.js';
-import { getEffectiveCatalog, deriveSafetyTier, CATALOG_SCHEMA_VERSION, } from '../devices/catalog.js';
-import { readProfileMeta } from '../config.js';
-import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
-import { ALL_STRATEGIES } from '../utils/name-resolver.js';
-import { IDENTITY } from './identity.js';
-import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError, PolicyYamlParseError, } from '../policy/load.js';
-import { validateLoadedPolicy } from '../policy/validate.js';
-import { selectCredentialStore } from '../credentials/keychain.js';
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const { version: pkgVersion } = require('../../package.json');
-/**
- * Schema version of the agent-bootstrap payload. Must stay in lockstep
- * with the catalog schema — bootstrap consumers (AI agents) reason about
- * catalog-derived fields (safetyTier, destructive flag), so a drift
- * between the two would silently break their assumptions. `doctor`
- * fails the `catalog-schema` check when these differ.
- */
-export const AGENT_BOOTSTRAP_SCHEMA_VERSION = CATALOG_SCHEMA_VERSION;
-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>'],
-    meta: ['devices meta set <id> --alias <name>', 'devices meta list', 'devices meta get <id>'],
-    policy: ['policy validate', 'policy new', 'policy migrate'],
-    auth: ['auth keychain describe', 'auth keychain migrate', 'auth keychain get'],
-};
-function readPolicyStatus() {
-    // Lightweight read — used by the bootstrap payload so agents know whether
-    // a policy file exists and is healthy without shelling out to
-    // `switchbot policy validate`. Parallel to `checkPolicy` in doctor but
-    // returns a more compact shape (no first-error drill-down; agents who
-    // want that run the dedicated command).
-    const policyPath = resolvePolicyPath();
-    try {
-        const loaded = loadPolicyFile(policyPath);
-        const result = validateLoadedPolicy(loaded);
-        return {
-            present: true,
-            valid: result.valid,
-            path: policyPath,
-            schemaVersion: result.schemaVersion,
-            errorCount: result.valid ? 0 : result.errors.length,
-        };
-    }
-    catch (err) {
-        if (err instanceof PolicyFileNotFoundError) {
-            return { present: false, valid: null, path: policyPath };
-        }
-        if (err instanceof PolicyYamlParseError) {
-            return { present: true, valid: false, path: policyPath, errorCount: 1 };
-        }
-        return { present: false, valid: null, path: policyPath };
-    }
-}
-async function readCredentialsBackend() {
-    try {
-        const store = await selectCredentialStore();
-        const desc = store.describe();
-        return { name: store.name, label: desc.backend, writable: desc.writable };
-    }
-    catch {
-        return { name: 'file', label: 'File (~/.switchbot/config.json)', writable: true };
-    }
-}
-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(async (opts) => {
-        const compact = Boolean(opts.compact);
-        const cache = loadCache();
-        const catalog = getEffectiveCatalog();
-        const usage = todayUsage();
-        const meta = readProfileMeta(undefined);
-        const credentialsBackend = await readCredentialsBackend();
-        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) => {
-                    const tier = deriveSafetyTier(c, e);
-                    return {
-                        command: c.command,
-                        parameter: c.parameter,
-                        safetyTier: tier,
-                        idempotent: Boolean(c.idempotent),
-                    };
-                }),
-                statusFields: e.statusFields ?? [],
-            };
-        });
-        const payload = {
-            schemaVersion: AGENT_BOOTSTRAP_SCHEMA_VERSION,
-            generatedAt: new Date().toISOString(),
-            cliVersion: pkgVersion,
-            identity: IDENTITY,
-            quickReference: QUICK_REFERENCE,
-            safetyTiers: SAFETY_TIERS,
-            nameStrategies: [...ALL_STRATEGIES],
-            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,
-            },
-            policyStatus: readPolicyStatus(),
-            credentialsBackend,
-            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);
-    });
-}