@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/utils/health.js

@@ -0,0 +1,101 @@
+/**
+ * Health report utilities — collects process, quota, audit, and circuit
+ * breaker state into a single snapshot suitable for /health-style checks
+ * and Prometheus-compatible metrics export.
+ *
+ * No side effects: reading is safe to call from any context.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { todayUsage, DAILY_QUOTA } from './quota.js';
+import { readAudit } from './audit.js';
+import { apiCircuitBreaker } from '../api/client.js';
+const DEFAULT_AUDIT_PATH = path.join(os.homedir(), '.switchbot', 'audit.log');
+const AUDIT_ERROR_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
+export function getHealthReport(auditPath = DEFAULT_AUDIT_PATH) {
+    const now = new Date();
+    // Process info
+    const procHealth = {
+        pid: process.pid,
+        uptimeSeconds: Math.floor(process.uptime()),
+        platform: process.platform,
+        nodeVersion: process.version,
+        memoryMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
+    };
+    // Quota
+    const { total: used } = todayUsage(now);
+    const pct = Math.round((used / DAILY_QUOTA) * 100);
+    const quotaHealth = {
+        used,
+        limit: DAILY_QUOTA,
+        percentUsed: pct,
+        remaining: Math.max(0, DAILY_QUOTA - used),
+        status: pct >= 90 ? 'critical' : pct >= 70 ? 'warn' : 'ok',
+    };
+    // Audit error rate (last 24h)
+    let auditHealth;
+    if (!fs.existsSync(auditPath)) {
+        auditHealth = { present: false, recentErrors: 0, recentTotal: 0, errorRatePercent: 0, status: 'ok' };
+    }
+    else {
+        const entries = readAudit(auditPath);
+        const windowStart = now.getTime() - AUDIT_ERROR_WINDOW_MS;
+        const recent = entries.filter((e) => new Date(e.t).getTime() >= windowStart);
+        const errors = recent.filter((e) => e.result === 'error').length;
+        const total = recent.length;
+        const errorRate = total > 0 ? Math.round((errors / total) * 100) : 0;
+        auditHealth = {
+            present: true,
+            recentErrors: errors,
+            recentTotal: total,
+            errorRatePercent: errorRate,
+            status: errorRate >= 30 ? 'warn' : 'ok',
+        };
+    }
+    // Circuit breaker
+    const cbStats = apiCircuitBreaker.getStats();
+    const circuitHealth = {
+        name: apiCircuitBreaker.name,
+        state: cbStats.state,
+        failures: cbStats.failures,
+        status: cbStats.state === 'open' ? 'open' : 'ok',
+    };
+    // Overall
+    const degraded = quotaHealth.status !== 'ok' ||
+        auditHealth.status !== 'ok' ||
+        circuitHealth.status !== 'ok';
+    const down = circuitHealth.status === 'open';
+    const overall = down ? 'down' : degraded ? 'degraded' : 'ok';
+    return {
+        generatedAt: now.toISOString(),
+        overall,
+        process: procHealth,
+        quota: quotaHealth,
+        audit: auditHealth,
+        circuit: circuitHealth,
+    };
+}
+/**
+ * Render a minimal Prometheus-compatible text metrics export.
+ * Only includes the most actionable gauges.
+ */
+export function toPrometheusText(report) {
+    const lines = [];
+    const push = (name, value, help) => {
+        if (help)
+            lines.push(`# HELP ${name} ${help}`);
+        lines.push(`# TYPE ${name} gauge`);
+        lines.push(`${name} ${value}`);
+    };
+    push('switchbot_quota_used_total', report.quota.used, 'SwitchBot API requests used today');
+    push('switchbot_quota_remaining', report.quota.remaining, 'SwitchBot API quota remaining today');
+    push('switchbot_quota_percent_used', report.quota.percentUsed, 'SwitchBot API quota percent used today');
+    push('switchbot_audit_recent_errors', report.audit.recentErrors, 'Audit log errors in the last 24h');
+    push('switchbot_audit_error_rate_percent', report.audit.errorRatePercent, 'Audit error rate percent (last 24h)');
+    push('switchbot_circuit_open', report.circuit.state === 'open' ? 1 : 0, 'API circuit breaker open (1=open, 0=closed/half-open)');
+    push('switchbot_circuit_failures', report.circuit.failures, 'Consecutive API failures recorded by circuit breaker');
+    push('switchbot_process_uptime_seconds', report.process.uptimeSeconds, 'Process uptime in seconds');
+    push('switchbot_process_memory_mb', report.process.memoryMb, 'Process RSS memory usage in MB');
+    return lines.join('\n') + '\n';
+}

package/dist/utils/output.js

@@ -196,10 +196,40 @@ export function buildErrorPayload(error) {
             kind: 'usage',
             message: error.message,
             errorClass: 'usage',
-            transient: false
+            transient: false,
         };
-        if (error.context)
-            payload.context = error.context;
+        if (error.context) {
+            const ctx = error.context;
+            const { error: errorType, candidates, hint } = ctx;
+            if (errorType === 'ambiguous_name_match') {
+                payload.subKind = 'ambiguous-name-match';
+            }
+            if (Array.isArray(candidates) && candidates.length > 0) {
+                const normalized = candidates
+                    .map((c) => {
+                    if (typeof c !== 'object' || c === null)
+                        return null;
+                    const o = c;
+                    const name = typeof o.name === 'string' ? o.name
+                        : typeof o.sceneName === 'string' ? o.sceneName
+                            : '';
+                    const match = { name };
+                    if (typeof o.deviceId === 'string')
+                        match.deviceId = o.deviceId;
+                    if (typeof o.sceneId === 'string')
+                        match.sceneId = o.sceneId;
+                    return match;
+                })
+                    .filter((c) => c !== null && c.name.length > 0);
+                if (normalized.length > 0)
+                    payload.candidateMatches = normalized;
+            }
+            if (typeof hint === 'string') {
+                payload.resolutionHint = hint;
+            }
+            // Preserve full context for backward compatibility (including candidates / hint).
+            payload.context = ctx;
+        }
         return payload;
     }
     if (error instanceof UsageError) {
@@ -286,31 +316,50 @@ export function handleError(error) {
     }
     if (payload.kind === 'usage') {
         console.error(payload.message);
-        const ctx = payload.context;
-        if (ctx && Array.isArray(ctx.candidates) && ctx.candidates.length > 0) {
-            const names = ctx.candidates
+        if (Array.isArray(payload.candidateMatches) && payload.candidateMatches.length > 0) {
+            const names = payload.candidateMatches
                 .map((c) => {
-                if (typeof c === 'string')
-                    return c;
-                if (c && typeof c === 'object') {
-                    const o = c;
-                    const name = typeof o.name === 'string'
-                        ? o.name
-                        : typeof o.sceneName === 'string' ? o.sceneName : undefined;
-                    const id = typeof o.deviceId === 'string'
-                        ? o.deviceId
-                        : typeof o.sceneId === 'string' ? o.sceneId : typeof o.id === 'string' ? o.id : undefined;
-                    if (name && id)
-                        return `${name} (${id})`;
-                    return name ?? id ?? JSON.stringify(c);
-                }
-                return String(c);
+                const id = c.deviceId ?? c.sceneId;
+                if (c.name && id)
+                    return `${c.name} (${id})`;
+                return c.name ?? id ?? JSON.stringify(c);
             })
                 .slice(0, 6);
             console.error(`Did you mean: ${names.join(', ')}?`);
         }
-        if (ctx && typeof ctx.hint === 'string') {
-            console.error(ctx.hint);
+        else {
+            const ctx = payload.context;
+            if (ctx && Array.isArray(ctx.candidates) && ctx.candidates.length > 0) {
+                const names = ctx.candidates
+                    .map((c) => {
+                    if (typeof c === 'string')
+                        return c;
+                    if (c && typeof c === 'object') {
+                        const o = c;
+                        const name = typeof o.name === 'string'
+                            ? o.name
+                            : typeof o.sceneName === 'string' ? o.sceneName : undefined;
+                        const id = typeof o.deviceId === 'string'
+                            ? o.deviceId
+                            : typeof o.sceneId === 'string' ? o.sceneId : typeof o.id === 'string' ? o.id : undefined;
+                        if (name && id)
+                            return `${name} (${id})`;
+                        return name ?? id ?? JSON.stringify(c);
+                    }
+                    return String(c);
+                })
+                    .slice(0, 6);
+                console.error(`Did you mean: ${names.join(', ')}?`);
+            }
+        }
+        if (payload.resolutionHint) {
+            console.error(payload.resolutionHint);
+        }
+        else {
+            const ctx = payload.context;
+            if (ctx && typeof ctx.hint === 'string') {
+                console.error(ctx.hint);
+            }
         }
         process.exit(2);
     }

package/dist/utils/retry.js

@@ -8,6 +8,13 @@
  *
  * If the server returns a `Retry-After` header we always prefer it over our
  * own backoff — the API explicitly told us when to come back.
+ *
+ * Circuit breaker:
+ *   Prevents hammering a consistently-failing endpoint. Tracks consecutive
+ *   failures; when `failureThreshold` is exceeded the circuit opens and
+ *   subsequent calls fail immediately (with CircuitOpenError). After
+ *   `resetTimeoutMs` the circuit enters half-open state: the next call is
+ *   allowed as a probe — success closes it, failure re-opens it.
  */
 const BASE_MS = 1_000;
 const MAX_MS = 30_000;
@@ -57,3 +64,77 @@ export function nextRetryDelayMs(attempt, strategy, retryAfterHeader, now = Date
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Thrown when a call is blocked because the circuit is open.
+ */
+export class CircuitOpenError extends Error {
+    circuitName;
+    nextAttemptMs;
+    constructor(circuitName, nextAttemptMs) {
+        super(`Circuit "${circuitName}" is open — too many recent failures. Next probe allowed in ${Math.ceil((nextAttemptMs - Date.now()) / 1000)}s.`);
+        this.circuitName = circuitName;
+        this.nextAttemptMs = nextAttemptMs;
+        this.name = 'CircuitOpenError';
+    }
+}
+export class CircuitBreaker {
+    name;
+    state = 'closed';
+    failures = 0;
+    lastOpenedAt = 0;
+    failureThreshold;
+    resetTimeoutMs;
+    constructor(name, opts = {}) {
+        this.name = name;
+        this.failureThreshold = opts.failureThreshold ?? 5;
+        this.resetTimeoutMs = opts.resetTimeoutMs ?? 60_000;
+    }
+    getState() {
+        this._maybeHalfOpen();
+        return this.state;
+    }
+    getStats() {
+        this._maybeHalfOpen();
+        return {
+            state: this.state,
+            failures: this.failures,
+            lastOpenedAt: this.lastOpenedAt,
+            nextProbeMs: this.state === 'open' ? this.lastOpenedAt + this.resetTimeoutMs : 0,
+        };
+    }
+    /**
+     * Check if a call is allowed. Throws `CircuitOpenError` when the circuit
+     * is open and the reset timeout hasn't elapsed. Call `recordSuccess()` or
+     * `recordFailure()` after the operation completes.
+     */
+    checkAndAllow() {
+        this._maybeHalfOpen();
+        if (this.state === 'open') {
+            throw new CircuitOpenError(this.name, this.lastOpenedAt + this.resetTimeoutMs);
+        }
+        // closed or half-open: allow the call
+    }
+    recordSuccess() {
+        this.failures = 0;
+        this.state = 'closed';
+    }
+    recordFailure() {
+        this.failures++;
+        if (this.state === 'half-open' || this.failures >= this.failureThreshold) {
+            this.state = 'open';
+            this.lastOpenedAt = Date.now();
+        }
+    }
+    /** Reset to closed — useful for testing or manual recovery. */
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        this.lastOpenedAt = 0;
+    }
+    _maybeHalfOpen() {
+        if (this.state === 'open' &&
+            Date.now() >= this.lastOpenedAt + this.resetTimeoutMs) {
+            this.state = 'half-open';
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.7.2",
+  "version": "3.1.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",
@@ -36,10 +36,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
-    "build:prod": "tsc -p tsconfig.build.json",
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "build:prod": "tsc -p tsconfig.build.json && 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\"",
+    "lint:md:changelog": "markdownlint CHANGELOG.md",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -48,20 +50,26 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
     "axios": "^1.7.9",
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
+    "croner": "^10.0.1",
     "js-yaml": "^4.1.1",
     "mqtt": "^5.3.0",
     "pino": "^9.0.0",
-    "uuid": "^11.0.5"
+    "uuid": "^11.0.5",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.7",
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^2.1.9",
+    "markdownlint-cli": "^0.48.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
     "vitest": "^2.1.9"