@switchbot/openapi-cli 3.1.0 → 3.2.0

package/dist/lib/devices.js

@@ -1,382 +0,0 @@
-import { createClient } from '../api/client.js';
-import { idempotencyCache } from './idempotency.js';
-import { findCatalogEntry, suggestedActions, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
-import { getCachedDevice, updateCacheFromDeviceList, loadCache, isListCacheFresh, getCachedStatus, setCachedStatus, } from '../devices/cache.js';
-import { getCacheMode } from '../utils/flags.js';
-import { writeAudit } from '../utils/audit.js';
-import { isDryRun } from '../utils/flags.js';
-export class DeviceNotFoundError extends Error {
-    deviceId;
-    constructor(deviceId) {
-        super(`No device with id "${deviceId}" found on this account.`);
-        this.deviceId = deviceId;
-        this.name = 'DeviceNotFoundError';
-    }
-}
-export class CommandValidationError extends Error {
-    kind;
-    hint;
-    constructor(message, kind, hint) {
-        super(message);
-        this.kind = kind;
-        this.hint = hint;
-        this.name = 'CommandValidationError';
-    }
-}
-/** Fetch the full device + IR remote inventory and refresh the local cache. */
-export async function fetchDeviceList(client) {
-    // TTL-gated read: when the on-disk cache is younger than the configured
-    // list TTL, skip the API call and synthesize a DeviceListBody from the
-    // metadata cache.
-    const mode = getCacheMode();
-    if (mode.listTtlMs > 0 && isListCacheFresh(mode.listTtlMs)) {
-        const cached = loadCache();
-        if (cached) {
-            const deviceList = [];
-            const infraredRemoteList = [];
-            for (const [deviceId, entry] of Object.entries(cached.devices)) {
-                if (entry.category === 'physical') {
-                    deviceList.push({
-                        deviceId,
-                        deviceName: entry.name,
-                        deviceType: entry.type,
-                        enableCloudService: entry.enableCloudService ?? true,
-                        hubDeviceId: entry.hubDeviceId ?? '',
-                        roomID: entry.roomID,
-                        roomName: entry.roomName,
-                        familyName: entry.familyName,
-                        controlType: entry.controlType,
-                    });
-                }
-                else {
-                    infraredRemoteList.push({
-                        deviceId,
-                        deviceName: entry.name,
-                        remoteType: entry.type,
-                        hubDeviceId: entry.hubDeviceId ?? '',
-                        controlType: entry.controlType,
-                    });
-                }
-            }
-            return { deviceList, infraredRemoteList };
-        }
-    }
-    const c = client ?? createClient();
-    const res = await c.get('/v1.1/devices');
-    updateCacheFromDeviceList(res.data.body);
-    return res.data.body;
-}
-/** Fetch live status for a single physical device. IR remotes have no status channel. */
-export async function fetchDeviceStatus(deviceId, client) {
-    const mode = getCacheMode();
-    if (mode.statusTtlMs > 0) {
-        const cached = getCachedStatus(deviceId, mode.statusTtlMs);
-        if (cached)
-            return cached;
-    }
-    const c = client ?? createClient();
-    const res = await c.get(`/v1.1/devices/${deviceId}/status`);
-    if (mode.statusTtlMs > 0) {
-        setCachedStatus(deviceId, res.data.body, new Date(), mode.statusTtlMs);
-    }
-    return res.data.body;
-}
-/**
- * Execute a command on a device. `parameter` is the fully-parsed value already
- * (JSON-object when applicable), not a raw CLI string — callers should parse
- * upstream if needed.
- */
-export async function executeCommand(deviceId, cmd, parameter, commandType, client, options) {
-    const c = client ?? createClient();
-    const body = {
-        command: cmd,
-        parameter: parameter ?? 'default',
-        commandType,
-    };
-    const baseAudit = {
-        t: new Date().toISOString(),
-        kind: 'command',
-        deviceId,
-        command: cmd,
-        parameter,
-        commandType,
-        dryRun: isDryRun(),
-        ...(options?.planId ? { planId: options.planId } : {}),
-    };
-    // Wrap in idempotency cache if key is provided
-    const execute = async () => {
-        try {
-            const res = await c.post(`/v1.1/devices/${deviceId}/commands`, body);
-            writeAudit({ ...baseAudit, result: 'ok' });
-            return res.data.body;
-        }
-        catch (err) {
-            // Dry-run intercepts throw DryRunSignal — still log the intent.
-            if (err instanceof Error && err.name === 'DryRunSignal') {
-                writeAudit({ ...baseAudit, result: 'ok' });
-            }
-            else {
-                writeAudit({
-                    ...baseAudit,
-                    result: 'error',
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-            throw err;
-        }
-    };
-    const { result, replayed } = await idempotencyCache.run(options?.idempotencyKey, execute, { command: cmd, parameter });
-    if (!replayed)
-        return result;
-    // Cached hit — attach replayed marker without mutating the original.
-    if (result && typeof result === 'object') {
-        return { ...result, replayed: true };
-    }
-    return { value: result, replayed: true };
-}
-/**
- * Validate a command against the locally-cached device → catalog mapping.
- * Returns `{ ok: true }` when validation passes or is skipped (unknown device,
- * custom IR button, etc.). On a case-only mismatch the canonical command name
- * is returned via `normalized` along with a `caseNormalizedFrom` field so the
- * caller can emit a warning and continue with the canonical name.
- * Returns `{ ok: false, error }` only when the caller should refuse the call.
- */
-export function validateCommand(deviceId, cmd, parameter, commandType) {
-    if (commandType === 'customize')
-        return { ok: true };
-    const cached = getCachedDevice(deviceId);
-    if (!cached)
-        return { ok: true };
-    const match = findCatalogEntry(cached.type);
-    if (!match || Array.isArray(match))
-        return { ok: true };
-    const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
-    if (match.readOnly || builtinCommands.length === 0) {
-        return {
-            ok: false,
-            error: new CommandValidationError(`${cached.name} (${cached.type}) is a read-only sensor — it has no control commands.`, 'read-only-device', `Use 'switchbot devices status ${deviceId}' to read this device instead.`),
-        };
-    }
-    let spec = builtinCommands.find((c) => c.command === cmd);
-    let caseNormalizedFrom;
-    let normalizedCmd = cmd;
-    if (!spec) {
-        const unique = [...new Set(builtinCommands.map((c) => c.command))];
-        const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
-        if (caseMatch) {
-            // Case-only mismatch: normalize and continue.
-            caseNormalizedFrom = cmd;
-            normalizedCmd = caseMatch;
-            spec = builtinCommands.find((c) => c.command === caseMatch);
-        }
-        else {
-            const hint = `Supported commands: ${unique.join(', ')}`;
-            return {
-                ok: false,
-                error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
-            };
-        }
-    }
-    if (!spec)
-        return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
-    const noParamExpected = spec.parameter === '—';
-    const userProvidedParam = parameter !== undefined && parameter !== 'default';
-    if (noParamExpected && userProvidedParam) {
-        return {
-            ok: false,
-            error: new CommandValidationError(`"${normalizedCmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${normalizedCmd}`),
-        };
-    }
-    // Warn when a parameter is required but the user omitted it
-    const paramRequired = !noParamExpected && spec.parameter !== 'default';
-    if (paramRequired && !userProvidedParam) {
-        const example = spec.exampleParams?.[0];
-        return {
-            ok: false,
-            error: new CommandValidationError(`"${normalizedCmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
-                ? `Example: switchbot devices command <deviceId> ${normalizedCmd} "${example}"`
-                : `See: switchbot devices commands ${cached.type}`),
-        };
-    }
-    return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
-}
-/**
- * Inspect catalog annotations to decide whether a command is destructive,
- * i.e. has hard-to-reverse real-world effects and should require an explicit
- * confirmation from an agent / operator before execution. Customize commands
- * are considered non-destructive here — they're user-defined IR buttons
- * whose behavior the catalog can't know about.
- */
-export function isDestructiveCommand(deviceType, cmd, commandType) {
-    if (commandType === 'customize')
-        return false;
-    if (!deviceType)
-        return false;
-    const match = findCatalogEntry(deviceType);
-    if (!match || Array.isArray(match))
-        return false;
-    const spec = match.commands.find((c) => c.command === cmd);
-    if (!spec)
-        return false;
-    return deriveSafetyTier(spec, match) === 'destructive';
-}
-/** Return the safetyReason for a command, or null if not destructive / not found. */
-export function getDestructiveReason(deviceType, cmd, commandType) {
-    if (commandType === 'customize')
-        return null;
-    if (!deviceType)
-        return null;
-    const match = findCatalogEntry(deviceType);
-    if (!match || Array.isArray(match))
-        return null;
-    const spec = match.commands.find((c) => c.command === cmd);
-    return spec ? getCommandSafetyReason(spec) : null;
-}
-/**
- * Describe a device by id: metadata + catalog entry (if known) +
- * optional live status. Throws `DeviceNotFoundError` when the id is unknown.
- */
-export async function describeDevice(deviceId, options = {}, client) {
-    const body = await fetchDeviceList(client);
-    const { deviceList, infraredRemoteList } = body;
-    const physical = deviceList.find((d) => d.deviceId === deviceId);
-    const ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
-    if (!physical && !ir)
-        throw new DeviceNotFoundError(deviceId);
-    const typeName = physical ? (physical.deviceType ?? '') : ir.remoteType;
-    const match = typeName ? findCatalogEntry(typeName) : null;
-    const catalogEntry = !match || Array.isArray(match) ? null : match;
-    let liveStatus;
-    if (options.live && physical) {
-        try {
-            liveStatus = await fetchDeviceStatus(deviceId, client);
-        }
-        catch (err) {
-            liveStatus = { error: err instanceof Error ? err.message : String(err) };
-        }
-    }
-    const source = catalogEntry
-        ? liveStatus
-            ? 'catalog+live'
-            : 'catalog'
-        : liveStatus
-            ? 'live'
-            : 'none';
-    const capabilities = catalogEntry
-        ? {
-            role: catalogEntry.role ?? null,
-            readOnly: catalogEntry.readOnly ?? false,
-            commands: catalogEntry.commands.map((c) => {
-                const tier = deriveSafetyTier(c, catalogEntry);
-                const reason = getCommandSafetyReason(c);
-                return {
-                    ...c,
-                    safetyTier: tier,
-                    ...(reason ? { safetyReason: reason } : {}),
-                };
-            }),
-            statusFields: catalogEntry.statusFields ?? [],
-            ...(liveStatus !== undefined ? { liveStatus } : {}),
-        }
-        : liveStatus !== undefined
-            ? { liveStatus }
-            : null;
-    return {
-        device: (physical ?? ir),
-        isPhysical: Boolean(physical),
-        typeName,
-        controlType: physical?.controlType ?? ir?.controlType ?? null,
-        catalog: catalogEntry,
-        capabilities,
-        source,
-        suggestedActions: catalogEntry ? suggestedActions(catalogEntry) : [],
-        inheritedLocation: ir ? buildHubLocationMap(deviceList).get(ir.hubDeviceId) : undefined,
-    };
-}
-/** Build a map from hubDeviceId → room/family/roomID for IR-remote inheritance. */
-export function buildHubLocationMap(deviceList) {
-    const map = new Map();
-    for (const d of deviceList) {
-        if (!d.deviceId)
-            continue;
-        map.set(d.deviceId, {
-            family: d.familyName ?? undefined,
-            room: d.roomName ?? undefined,
-            roomID: d.roomID ?? undefined,
-        });
-    }
-    return map;
-}
-/**
- * Search the local catalog by type name / alias. Returns up to `limit`
- * entries whose type or alias contains the query (case-insensitive).
- * Intended for MCP's `search_catalog` tool — not for dispatching commands.
- */
-export function searchCatalog(query, limit = 20) {
-    const catalog = getEffectiveCatalog();
-    const q = query.trim().toLowerCase();
-    if (!q)
-        return catalog.slice(0, limit);
-    const hits = [];
-    for (const entry of catalog) {
-        const haystack = [entry.type, ...(entry.aliases ?? [])].map((s) => s.toLowerCase());
-        if (haystack.some((h) => h.includes(q))) {
-            hits.push(entry);
-            if (hits.length >= limit)
-                break;
-        }
-    }
-    return hits;
-}
-/** Convert a DescribeResult to the shape validated by the MCP outputSchema. */
-export function toMcpDescribeShape(r) {
-    const d = r.device;
-    return {
-        device: {
-            deviceId: d.deviceId,
-            deviceName: d.deviceName,
-            ...(d.deviceType !== undefined ? { deviceType: d.deviceType } : {}),
-            ...('enableCloudService' in d ? { enableCloudService: d.enableCloudService } : {}),
-            ...(d.hubDeviceId !== undefined ? { hubDeviceId: d.hubDeviceId } : {}),
-            ...(d.roomID !== undefined ? { roomID: d.roomID } : {}),
-            ...(d.roomName !== undefined ? { roomName: d.roomName } : {}),
-            ...(d.familyName !== undefined ? { familyName: d.familyName } : {}),
-            ...(d.controlType !== undefined ? { controlType: d.controlType } : {}),
-            ...('remoteType' in d && d.remoteType !== undefined ? { remoteType: d.remoteType } : {}),
-        },
-        isPhysical: r.isPhysical,
-        typeName: r.typeName,
-        controlType: r.controlType,
-        source: r.source,
-        capabilities: r.capabilities,
-        suggestedActions: r.suggestedActions,
-        ...(r.inheritedLocation !== undefined
-            ? { inheritedLocation: { family: r.inheritedLocation.family, room: r.inheritedLocation.room } }
-            : {}),
-    };
-}
-/** Shapes the device list body for the MCP list_devices outputSchema. */
-export function toMcpDeviceListShape(d) {
-    return {
-        deviceId: d.deviceId,
-        deviceName: d.deviceName,
-        deviceType: d.deviceType,
-        enableCloudService: d.enableCloudService,
-        hubDeviceId: d.hubDeviceId,
-        roomID: d.roomID,
-        roomName: d.roomName,
-        familyName: d.familyName,
-        controlType: d.controlType,
-    };
-}
-/** Shapes an infrared remote for the MCP list_devices outputSchema. */
-export function toMcpIrDeviceShape(d) {
-    return {
-        deviceId: d.deviceId,
-        deviceName: d.deviceName,
-        remoteType: d.remoteType,
-        hubDeviceId: d.hubDeviceId,
-        controlType: d.controlType,
-    };
-}

package/dist/lib/idempotency.js

@@ -1,106 +0,0 @@
-/**
- * In-memory LRU cache for idempotent request deduplication.
- * Caches the outcome of a keyed operation for 60 seconds;
- * duplicate keys within the window return the cached result (with a
- * `replayed: true` marker). Duplicate keys within the window for a DIFFERENT
- * (command, parameter) shape raise {@link IdempotencyConflictError}.
- *
- * Keys are stored in-memory as a SHA-256 fingerprint of the user-provided
- * key — the original string never touches the Map keys, so a later heap dump
- * or inadvertent log capture does not leak the raw token.
- *
- * Process-local only — not shared across replicas.
- */
-import crypto from 'node:crypto';
-const DEFAULT_TTL_MS = 60000; // 60 seconds
-const DEFAULT_MAX_ENTRIES = 1024;
-export class IdempotencyConflictError extends Error {
-    key;
-    existingShape;
-    newShape;
-    constructor(message, key, existingShape, newShape) {
-        super(message);
-        this.key = key;
-        this.existingShape = existingShape;
-        this.newShape = newShape;
-        this.name = 'IdempotencyConflictError';
-    }
-}
-function hashKey(key) {
-    return crypto.createHash('sha256').update(key).digest('hex');
-}
-function shapeSignature(command, parameter) {
-    // Canonical-ish JSON — stable enough for object equality with no nested sort
-    // (callers can pass primitives or small objects).
-    let parm;
-    try {
-        parm = JSON.stringify(parameter ?? 'default');
-    }
-    catch {
-        parm = String(parameter);
-    }
-    return `${command}::${parm}`;
-}
-export class IdempotencyCache {
-    cache = new Map();
-    ttlMs;
-    maxEntries;
-    constructor(ttlMs, maxEntries) {
-        this.ttlMs = ttlMs ?? DEFAULT_TTL_MS;
-        this.maxEntries = maxEntries ?? DEFAULT_MAX_ENTRIES;
-    }
-    /**
-     * Execute fn if the key is not cached, or return the cached result if it is.
-     * On new execution, caches the result for ttlMs.
-     *
-     * When `shape` is provided, a cached hit is validated against the original
-     * (command, parameter) fingerprint; mismatched shape raises
-     * {@link IdempotencyConflictError}.
-     *
-     * Returns a tuple-esque object with `replayed: true` when the cached
-     * result is served. The `result` field is the original cached value.
-     */
-    async run(key, fn, shape) {
-        if (!key) {
-            const result = await fn();
-            return { result, replayed: false };
-        }
-        const hashed = hashKey(key);
-        const now = Date.now();
-        const cached = this.cache.get(hashed);
-        const currentShape = shape ? shapeSignature(shape.command, shape.parameter) : '*';
-        if (cached && cached.expiresAt > now) {
-            if (shape && cached.shape !== '*' && cached.shape !== currentShape) {
-                throw new IdempotencyConflictError(`idempotency_conflict: key was first used for ${cached.shape.replace('::', ' ')}; refusing new shape ${currentShape.replace('::', ' ')}`, '<redacted>', cached.shape, currentShape);
-            }
-            return { result: cached.result, replayed: true };
-        }
-        const result = await fn();
-        if (this.cache.size >= this.maxEntries) {
-            const toRemove = Math.ceil(this.maxEntries * 0.1);
-            let removed = 0;
-            for (const [k, v] of this.cache.entries()) {
-                if (removed >= toRemove)
-                    break;
-                if (v.expiresAt <= now) {
-                    this.cache.delete(k);
-                    removed++;
-                }
-            }
-            if (this.cache.size >= this.maxEntries) {
-                const firstKey = this.cache.keys().next().value;
-                if (firstKey)
-                    this.cache.delete(firstKey);
-            }
-        }
-        this.cache.set(hashed, { result, expiresAt: now + this.ttlMs, shape: currentShape });
-        return { result, replayed: false };
-    }
-    clear() {
-        this.cache.clear();
-    }
-    size() {
-        return this.cache.size;
-    }
-}
-export const idempotencyCache = new IdempotencyCache();

package/dist/lib/plan-store.js

@@ -1,68 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-export const PLANS_DIR = path.join(os.homedir(), '.switchbot', 'plans');
-function ensurePlansDir() {
-    fs.mkdirSync(PLANS_DIR, { recursive: true, mode: 0o700 });
-}
-function planPath(planId) {
-    return path.join(PLANS_DIR, `${planId}.json`);
-}
-const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-function assertValidPlanId(planId) {
-    if (!UUID_V4_RE.test(planId)) {
-        throw new Error(`invalid planId: ${planId}`);
-    }
-}
-export function savePlanRecord(plan) {
-    ensurePlansDir();
-    const record = {
-        planId: randomUUID(),
-        createdAt: new Date().toISOString(),
-        status: 'pending',
-        plan,
-    };
-    fs.writeFileSync(planPath(record.planId), JSON.stringify(record, null, 2), { mode: 0o600 });
-    return record;
-}
-export function loadPlanRecord(planId) {
-    assertValidPlanId(planId);
-    try {
-        const raw = fs.readFileSync(planPath(planId), 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export function updatePlanRecord(planId, updates) {
-    assertValidPlanId(planId);
-    const record = loadPlanRecord(planId);
-    if (!record)
-        throw new Error(`Plan ${planId} not found in ${PLANS_DIR}`);
-    const updated = { ...record, ...updates };
-    fs.writeFileSync(planPath(planId), JSON.stringify(updated, null, 2), { mode: 0o600 });
-    return updated;
-}
-export function listPlanRecords() {
-    try {
-        if (!fs.existsSync(PLANS_DIR))
-            return [];
-        return fs
-            .readdirSync(PLANS_DIR)
-            .filter((f) => f.endsWith('.json'))
-            .flatMap((f) => {
-            try {
-                return [JSON.parse(fs.readFileSync(path.join(PLANS_DIR, f), 'utf-8'))];
-            }
-            catch {
-                return [];
-            }
-        })
-            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    }
-    catch {
-        return [];
-    }
-}

package/dist/lib/request-context.js

@@ -1,12 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { getProfile } from '../utils/flags.js';
-export const requestContext = new AsyncLocalStorage();
-export function withRequestContext(ctx, fn) {
-    return requestContext.run(ctx, fn);
-}
-export function getActiveProfile() {
-    const ctx = requestContext.getStore();
-    if (ctx?.profile !== undefined)
-        return ctx.profile;
-    return getProfile();
-}

package/dist/lib/scenes.js

@@ -1,10 +0,0 @@
-import { createClient } from '../api/client.js';
-export async function fetchScenes(client) {
-    const c = client ?? createClient();
-    const res = await c.get('/v1.1/scenes');
-    return res.data.body;
-}
-export async function executeScene(sceneId, client) {
-    const c = client ?? createClient();
-    await c.post(`/v1.1/scenes/${sceneId}/execute`);
-}

package/dist/logger.js

@@ -1,16 +0,0 @@
-import pino from 'pino';
-const logLevel = process.env.LOG_LEVEL || 'warn';
-const logFormat = process.env.LOG_FORMAT || 'json';
-const pinoConfig = {
-    level: logLevel,
-    transport: logFormat === 'pretty'
-        ? { target: 'pino-pretty' }
-        : undefined,
-};
-export const log = pino(pinoConfig);
-export function setLogLevel(level) {
-    log.level = level;
-}
-export function getLogLevel() {
-    return log.level;
-}