@switchbot/openapi-cli 3.0.0 → 3.1.1

package/dist/rules/throttle.js

@@ -4,6 +4,8 @@
  * Semantics:
  *   - `max_per: "10m"` → a rule may fire at most once every 10 minutes
  *     per (rule, deviceId) pair.
+ *   - `dedupe_window: "5s"` → suppress fires whose key already fired
+ *     within the window (collapses rapid sensor bursts into one action).
  *   - Fires that would violate the window are **suppressed** (not
  *     queued) and surface as `{ allowed: false, reason: 'throttled' }`.
  *   - When a rule has no `throttle` block, `ThrottleGate.check` returns
@@ -26,6 +28,8 @@ export function parseMaxPerMs(expr) {
 }
 export class ThrottleGate {
     lastFireAt = new Map();
+    /** Sliding-window fire-time log for count-based maxFiringsPerHour. */
+    fireTimes = new Map();
     keyOf(ruleName, deviceId) {
         return deviceId ? `${ruleName}::${deviceId}` : ruleName;
     }
@@ -34,21 +38,45 @@ export class ThrottleGate {
      * actually runs so that dry-run / throttled paths don't bump the
      * window.
      */
-    check(ruleName, windowMs, now, deviceId) {
-        if (windowMs === null || windowMs <= 0)
-            return { allowed: true };
+    check(ruleName, windowMs, now, deviceId, dedupeWindowMs) {
         const key = this.keyOf(ruleName, deviceId);
         const last = this.lastFireAt.get(key);
+        // dedupe_window check: suppress if last fire was within this (typically smaller) window
+        if (dedupeWindowMs !== null && dedupeWindowMs !== undefined && dedupeWindowMs > 0) {
+            if (last !== undefined) {
+                const dedupeEnd = last + dedupeWindowMs;
+                if (now < dedupeEnd) {
+                    return { allowed: false, lastFiredAt: last, nextAllowedAt: dedupeEnd, dedupedBy: 'dedupe_window' };
+                }
+            }
+        }
+        // max_per / cooldown check
+        if (windowMs === null || windowMs <= 0)
+            return { allowed: true, lastFiredAt: last };
         if (last === undefined)
             return { allowed: true };
         const earliest = last + windowMs;
         if (now >= earliest)
             return { allowed: true, lastFiredAt: last };
-        return { allowed: false, lastFiredAt: last, nextAllowedAt: earliest };
+        return { allowed: false, lastFiredAt: last, nextAllowedAt: earliest, dedupedBy: windowMs > 0 ? 'max_per' : undefined };
     }
     record(ruleName, now, deviceId) {
         this.lastFireAt.set(this.keyOf(ruleName, deviceId), now);
     }
+    /** Count-based check: has the rule fired >= maxCount times in the last windowMs? */
+    checkMaxFirings(ruleName, maxCount, windowMs, now, deviceId) {
+        const key = this.keyOf(ruleName, deviceId);
+        const times = (this.fireTimes.get(key) ?? []).filter((t) => now - t < windowMs);
+        this.fireTimes.set(key, times);
+        return { allowed: times.length < maxCount, count: times.length, max: maxCount };
+    }
+    /** Record a count-based fire (call alongside record()). */
+    recordFire(ruleName, now, deviceId) {
+        const key = this.keyOf(ruleName, deviceId);
+        const times = this.fireTimes.get(key) ?? [];
+        times.push(now);
+        this.fireTimes.set(key, times);
+    }
     /** Drop everything — used by engine.reload when a rule is removed. */
     forget(ruleName) {
         const prefix = `${ruleName}::`;
@@ -56,6 +84,10 @@ export class ThrottleGate {
             if (k === ruleName || k.startsWith(prefix))
                 this.lastFireAt.delete(k);
         }
+        for (const k of this.fireTimes.keys()) {
+            if (k === ruleName || k.startsWith(prefix))
+                this.fireTimes.delete(k);
+        }
     }
     /**
      * Drop every window whose rule name isn't in the given set — used by
@@ -70,6 +102,12 @@ export class ThrottleGate {
             if (!ruleNames.has(ruleName))
                 this.lastFireAt.delete(k);
         }
+        for (const k of this.fireTimes.keys()) {
+            const sep = k.indexOf('::');
+            const ruleName = sep === -1 ? k : k.slice(0, sep);
+            if (!ruleNames.has(ruleName))
+                this.fireTimes.delete(k);
+        }
     }
     /** Test helper — exposes the underlying size. */
     size() {

package/dist/utils/audit.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { getAuditLog } from './flags.js';
+export const DEFAULT_AUDIT_PATH = path.join(os.homedir(), '.switchbot', 'audit.log');
 /**
  * Bump when breaking changes to the audit line shape land.
  *
@@ -20,7 +22,9 @@ function resolveAuditPath() {
     return path.resolve(flag);
 }
 export function writeAudit(entry) {
-    const file = resolveAuditPath();
+    let file = resolveAuditPath();
+    if (!file && entry.planId)
+        file = DEFAULT_AUDIT_PATH;
     if (!file)
         return;
     const dir = path.dirname(file);

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": "3.0.0",
+  "version": "3.1.1",
   "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",