@switchbot/openapi-cli 1.0.1 → 1.2.0

package/dist/devices/cache.js

@@ -0,0 +1,225 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getConfigPath } from '../utils/flags.js';
+/** GC cutoff for status entries: evict anything older than this. */
+const DEFAULT_STATUS_GC_TTL_MS = 24 * 60 * 60 * 1000; // 24 h
+function cacheFilePath() {
+    const override = getConfigPath();
+    const dir = override
+        ? path.dirname(path.resolve(override))
+        : path.join(os.homedir(), '.switchbot');
+    return path.join(dir, 'devices.json');
+}
+// In-memory hot-cache: undefined = not yet loaded, null = loaded but empty.
+let _listCache = undefined;
+/** Force the next loadCache() call to re-read from disk. Used in tests. */
+export function resetListCache() {
+    _listCache = undefined;
+}
+export function loadCache() {
+    if (_listCache !== undefined)
+        return _listCache;
+    const file = cacheFilePath();
+    if (!fs.existsSync(file)) {
+        _listCache = null;
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const cache = JSON.parse(raw);
+        if (!cache || typeof cache.devices !== 'object' || cache.devices === null) {
+            _listCache = null;
+            return null;
+        }
+        _listCache = cache;
+        return cache;
+    }
+    catch {
+        _listCache = null;
+        return null;
+    }
+}
+export function getCachedDevice(deviceId) {
+    const cache = loadCache();
+    if (!cache)
+        return null;
+    return cache.devices[deviceId] ?? null;
+}
+export function updateCacheFromDeviceList(body) {
+    const devices = {};
+    for (const d of body.deviceList) {
+        if (!d.deviceId || !d.deviceType)
+            continue;
+        devices[d.deviceId] = {
+            type: d.deviceType,
+            name: d.deviceName,
+            category: 'physical',
+            hubDeviceId: d.hubDeviceId,
+            enableCloudService: d.enableCloudService,
+            roomID: d.roomID,
+            roomName: d.roomName,
+            familyName: d.familyName,
+            controlType: d.controlType,
+        };
+    }
+    for (const d of body.infraredRemoteList) {
+        if (!d.deviceId)
+            continue;
+        devices[d.deviceId] = {
+            type: d.remoteType,
+            name: d.deviceName,
+            category: 'ir',
+            hubDeviceId: d.hubDeviceId,
+            controlType: d.controlType,
+        };
+    }
+    const cache = {
+        lastUpdated: new Date().toISOString(),
+        devices,
+    };
+    try {
+        const file = cacheFilePath();
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(cache, null, 2), { mode: 0o600 });
+        _listCache = cache;
+    }
+    catch {
+        // Cache write failures must not break the command that triggered them.
+    }
+}
+export function clearCache() {
+    const file = cacheFilePath();
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+    _listCache = null;
+}
+// ---- Device list freshness -------------------------------------------------
+/** Age of the on-disk list cache in ms, or null if there is no cache. */
+export function listCacheAgeMs(now = Date.now()) {
+    const cache = loadCache();
+    if (!cache)
+        return null;
+    const ts = Date.parse(cache.lastUpdated);
+    if (!Number.isFinite(ts))
+        return null;
+    return Math.max(0, now - ts);
+}
+/** True when the on-disk list cache is present and younger than `ttlMs`. */
+export function isListCacheFresh(ttlMs, now = Date.now()) {
+    if (!ttlMs || ttlMs <= 0)
+        return false;
+    const age = listCacheAgeMs(now);
+    return age !== null && age < ttlMs;
+}
+function statusCacheFilePath() {
+    const override = getConfigPath();
+    const dir = override
+        ? path.dirname(path.resolve(override))
+        : path.join(os.homedir(), '.switchbot');
+    return path.join(dir, 'status.json');
+}
+export function loadStatusCache() {
+    const file = statusCacheFilePath();
+    if (!fs.existsSync(file))
+        return { entries: {} };
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.entries !== 'object' || parsed.entries === null) {
+            return { entries: {} };
+        }
+        return parsed;
+    }
+    catch {
+        return { entries: {} };
+    }
+}
+function saveStatusCache(cache) {
+    try {
+        const file = statusCacheFilePath();
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(cache, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Read a status entry; returns null when missing or older than `ttlMs`. */
+export function getCachedStatus(deviceId, ttlMs, now = Date.now()) {
+    if (!ttlMs || ttlMs <= 0)
+        return null;
+    const cache = loadStatusCache();
+    const entry = cache.entries[deviceId];
+    if (!entry)
+        return null;
+    const ts = Date.parse(entry.fetchedAt);
+    if (!Number.isFinite(ts))
+        return null;
+    if (now - ts >= ttlMs)
+        return null;
+    return entry.body;
+}
+/** Evict status entries older than max(ttlMs × 10, 24 h) to bound file growth. */
+function evictExpiredStatusEntries(cache, ttlMs, now = Date.now()) {
+    const cutoff = now - Math.max(ttlMs * 10, 24 * 60 * 60 * 1000);
+    for (const id of Object.keys(cache.entries)) {
+        const entry = cache.entries[id];
+        const ts = Date.parse(entry.fetchedAt);
+        if (!Number.isFinite(ts) || ts < cutoff)
+            delete cache.entries[id];
+    }
+}
+export function setCachedStatus(deviceId, body, now = new Date()) {
+    const cache = loadStatusCache();
+    cache.entries[deviceId] = {
+        fetchedAt: now.toISOString(),
+        body,
+    };
+    evictExpiredStatusEntries(cache, DEFAULT_STATUS_GC_TTL_MS, now.getTime());
+    saveStatusCache(cache);
+}
+export function clearStatusCache() {
+    const file = statusCacheFilePath();
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+}
+export function describeCache(now = Date.now()) {
+    const listFile = cacheFilePath();
+    const listCache = loadCache();
+    const listExists = fs.existsSync(listFile);
+    const list = {
+        path: listFile,
+        exists: listExists,
+    };
+    if (listCache) {
+        list.lastUpdated = listCache.lastUpdated;
+        const ts = Date.parse(listCache.lastUpdated);
+        if (Number.isFinite(ts))
+            list.ageMs = Math.max(0, now - ts);
+        list.deviceCount = Object.keys(listCache.devices).length;
+    }
+    const statusFile = statusCacheFilePath();
+    const statusExists = fs.existsSync(statusFile);
+    const statusCache = loadStatusCache();
+    const entries = Object.values(statusCache.entries);
+    const status = {
+        path: statusFile,
+        exists: statusExists,
+        entryCount: entries.length,
+    };
+    if (entries.length > 0) {
+        const sorted = entries
+            .map((e) => e.fetchedAt)
+            .filter((s) => typeof s === 'string')
+            .sort();
+        status.oldestFetchedAt = sorted[0];
+        status.newestFetchedAt = sorted[sorted.length - 1];
+    }
+    return { list, status };
+}
+//# sourceMappingURL=cache.js.map

package/dist/devices/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/devices/cache.ts"],"names":[],"mappings":"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"}

package/dist/devices/catalog.d.ts

@@ -2,20 +2,69 @@
  * Static catalog of SwitchBot device types, control commands and status fields.
  * Sourced from https://github.com/OpenWonderLabs/SwitchBotAPI — keep in sync
  * when the upstream API adds new device types.
+ *
+ * Field conventions:
+ *   - CommandSpec.idempotent: repeat-safe — calling it N times ends in the
+ *     same state as calling it once (turnOn, setBrightness 50). Agents can
+ *     retry these freely. Counter-examples: toggle, press, volumeAdd.
+ *   - CommandSpec.destructive: causes a real-world effect that is hard or
+ *     unsafe to reverse (unlock, garage open, deleteKey). UIs and agents
+ *     should require explicit confirmation before issuing these.
+ *   - DeviceCatalogEntry.role: functional grouping for filter/search
+ *     ("all lighting", "all security"). Does not affect API behavior.
+ *   - DeviceCatalogEntry.readOnly: the device has no control commands; it
+ *     can only be queried via 'devices status'.
  */
 export interface CommandSpec {
     command: string;
     parameter: string;
     description: string;
     commandType?: 'command' | 'customize';
+    idempotent?: boolean;
+    destructive?: boolean;
+    /** One sentence explaining *why* this command is destructive — used in guard errors so agents/users can decide whether to confirm. */
+    destructiveReason?: string;
+    exampleParams?: string[];
 }
+/** Coarse functional role — helpful for cross-type selection in agents. */
+export type DeviceRole = 'lighting' | 'climate' | 'security' | 'media' | 'sensor' | 'cleaning' | 'curtain' | 'fan' | 'power' | 'hub' | 'other';
 export interface DeviceCatalogEntry {
     type: string;
     category: 'physical' | 'ir';
+    description?: string;
     aliases?: string[];
     commands: CommandSpec[];
     statusFields?: string[];
+    role?: DeviceRole;
+    readOnly?: boolean;
 }
 export declare const DEVICE_CATALOG: DeviceCatalogEntry[];
 /** Find a catalog entry by exact name, alias, or case-insensitive substring. */
 export declare function findCatalogEntry(query: string): DeviceCatalogEntry | DeviceCatalogEntry[] | null;
+/**
+ * Pick up to 3 non-destructive, idempotent commands an agent can safely invoke
+ * to explore or exercise a device. Used by `devices describe --json` to hint
+ * at concrete next steps.
+ */
+export declare function suggestedActions(entry: DeviceCatalogEntry): Array<{
+    command: string;
+    parameter?: string;
+    description: string;
+}>;
+export interface CatalogOverlayEntry extends Partial<DeviceCatalogEntry> {
+    type: string;
+    remove?: boolean;
+}
+export interface OverlayLoadResult {
+    path: string;
+    exists: boolean;
+    entries: CatalogOverlayEntry[];
+    error?: string;
+}
+export declare function getCatalogOverlayPath(): string;
+/** Read the overlay file. Never throws — returns `error` on bad files. */
+export declare function loadCatalogOverlay(): OverlayLoadResult;
+/** Clear the overlay cache (test helper; also useful for `catalog refresh`). */
+export declare function resetCatalogOverlayCache(): void;
+/** Merge built-in catalog with the on-disk overlay. */
+export declare function getEffectiveCatalog(): DeviceCatalogEntry[];