@switchbot/openapi-cli 3.1.0 → 3.2.0

package/dist/rules/webhook-listener.js

@@ -1,223 +0,0 @@
-/**
- * Local HTTP listener that delivers webhook events to the rules engine.
- *
- * Scope (E2):
- *   - Binds to `127.0.0.1` only — the loopback interface keeps the
- *     listener off the network by default. The plan's integration story
- *     is that an agent or local script POSTs to this endpoint.
- *   - Default port is 18790 (phase-3 design doc choice); override with
- *     `--webhook-port <n>` in `switchbot rules run`. `--webhook-port 0`
- *     asks the OS for an ephemeral port — useful in tests.
- *   - Bearer-token auth on every request: `Authorization: Bearer <t>`.
- *     The expected token comes from `WebhookTokenStore`; unauthorized
- *     requests get a 401 with no body, no hint about which header
- *     failed, and an audit entry (`rule-webhook-rejected`).
- *   - Matches request path against registered webhook rules: only
- *     `POST /path/exactly/as/declared`. Unknown paths return 404.
- *
- * Non-goals:
- *   - No TLS; operators who expose this outside loopback are expected
- *     to sit behind a reverse proxy that terminates TLS.
- *   - No payload parsing beyond reading the body as a string — the
- *     engine passes the raw body through in the event payload.
- */
-import http from 'node:http';
-import { timingSafeEqual } from 'node:crypto';
-import { writeAudit } from '../utils/audit.js';
-import { isWebhookTrigger } from './types.js';
-export const DEFAULT_WEBHOOK_PORT = 18790;
-const MAX_BODY_BYTES = 16 * 1024; // guard against huge POSTs from misbehaving callers
-export class WebhookListener {
-    opts;
-    server = null;
-    pathIndex = new Map();
-    actualPort = null;
-    constructor(opts) {
-        this.opts = opts;
-        for (const rule of opts.rules) {
-            if (!isWebhookTrigger(rule.when))
-                continue;
-            const normalised = normalisePath(rule.when.path);
-            if (this.pathIndex.has(normalised)) {
-                throw new Error(`WebhookListener: duplicate webhook path "${normalised}" — every webhook rule needs a unique path`);
-            }
-            this.pathIndex.set(normalised, rule);
-        }
-    }
-    /** Start listening. Resolves once the server has bound a port. */
-    async start() {
-        if (this.server)
-            return;
-        const server = http.createServer((req, res) => {
-            this.handle(req, res).catch((err) => {
-                // The dispatch chain should never reject — but if it does,
-                // make sure we close the socket so the caller doesn't hang.
-                if (!res.headersSent) {
-                    res.writeHead(500);
-                    res.end();
-                }
-                // eslint-disable-next-line no-console
-                console.error(`webhook-listener: unhandled dispatch error: ${err instanceof Error ? err.message : String(err)}`);
-            });
-        });
-        const host = this.opts.host ?? '127.0.0.1';
-        const port = this.opts.port ?? DEFAULT_WEBHOOK_PORT;
-        await new Promise((resolve, reject) => {
-            const onError = (err) => {
-                server.off('listening', onListening);
-                reject(err);
-            };
-            const onListening = () => {
-                server.off('error', onError);
-                resolve();
-            };
-            server.once('error', onError);
-            server.once('listening', onListening);
-            server.listen(port, host);
-        });
-        const address = server.address();
-        this.actualPort = typeof address === 'object' && address ? address.port : port;
-        this.server = server;
-    }
-    async stop() {
-        if (!this.server)
-            return;
-        const server = this.server;
-        this.server = null;
-        this.actualPort = null;
-        await new Promise((resolve) => server.close(() => resolve()));
-    }
-    getPort() {
-        return this.actualPort;
-    }
-    listPaths() {
-        return [...this.pathIndex.keys()].sort();
-    }
-    /**
-     * Replace the current rule → path index. Used by `engine.reload`: the
-     * listener keeps its open port and accepted connections, but routes
-     * subsequent requests against the fresh policy.
-     */
-    updateRules(rules) {
-        const next = new Map();
-        for (const rule of rules) {
-            if (!isWebhookTrigger(rule.when))
-                continue;
-            const normalised = normalisePath(rule.when.path);
-            if (next.has(normalised)) {
-                throw new Error(`WebhookListener.updateRules: duplicate webhook path "${normalised}"`);
-            }
-            next.set(normalised, rule);
-        }
-        this.pathIndex.clear();
-        for (const [k, v] of next)
-            this.pathIndex.set(k, v);
-    }
-    async handle(req, res) {
-        // Auth gate first — reject everything else so a wrong token never
-        // reveals which paths exist.
-        if (!this.isAuthorized(req)) {
-            writeAudit({
-                t: this.now().toISOString(),
-                kind: 'rule-webhook-rejected',
-                deviceId: 'unknown',
-                command: req.url ?? '',
-                parameter: null,
-                commandType: 'command',
-                dryRun: true,
-                result: 'error',
-                error: 'unauthorized',
-            });
-            res.writeHead(401);
-            res.end();
-            return;
-        }
-        if (req.method !== 'POST') {
-            res.writeHead(405, { Allow: 'POST' });
-            res.end();
-            return;
-        }
-        const reqUrl = req.url ?? '/';
-        const questionMarkIdx = reqUrl.indexOf('?');
-        const rawPath = questionMarkIdx === -1 ? reqUrl : reqUrl.slice(0, questionMarkIdx);
-        const normalised = normalisePath(rawPath);
-        const rule = this.pathIndex.get(normalised);
-        if (!rule) {
-            writeAudit({
-                t: this.now().toISOString(),
-                kind: 'rule-webhook-rejected',
-                deviceId: 'unknown',
-                command: rawPath,
-                parameter: null,
-                commandType: 'command',
-                dryRun: true,
-                result: 'error',
-                error: 'unknown-path',
-            });
-            res.writeHead(404);
-            res.end();
-            return;
-        }
-        const body = await readLimitedBody(req, MAX_BODY_BYTES);
-        if (body === null) {
-            res.writeHead(413);
-            res.end();
-            return;
-        }
-        const event = {
-            source: 'webhook',
-            event: normalised,
-            t: this.now(),
-            payload: { path: normalised, body },
-        };
-        // Accept the request before dispatch so callers aren't held waiting
-        // on rule actions (which can include SwitchBot API calls).
-        res.writeHead(202, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ status: 'accepted', path: normalised }));
-        this.opts.dispatch(rule, event).catch(() => undefined);
-    }
-    isAuthorized(req) {
-        const h = req.headers['authorization'];
-        if (typeof h !== 'string')
-            return false;
-        const match = /^Bearer\s+(.+)$/i.exec(h.trim());
-        if (!match)
-            return false;
-        const provided = Buffer.from(match[1].trim(), 'utf-8');
-        const expected = Buffer.from(this.opts.bearerToken, 'utf-8');
-        if (provided.length !== expected.length)
-            return false;
-        return timingSafeEqual(provided, expected);
-    }
-    now() {
-        return this.opts.now ? this.opts.now() : new Date();
-    }
-}
-function normalisePath(p) {
-    if (!p)
-        return '/';
-    let out = p.trim();
-    if (!out.startsWith('/'))
-        out = `/${out}`;
-    // Collapse a trailing slash (but leave the root '/').
-    if (out.length > 1 && out.endsWith('/'))
-        out = out.slice(0, -1);
-    return out;
-}
-function readLimitedBody(req, max) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let total = 0;
-        req.on('data', (chunk) => {
-            total += chunk.length;
-            if (total > max) {
-                req.destroy();
-                resolve(null);
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
-        req.on('error', reject);
-    });
-}

package/dist/rules/webhook-token.js

@@ -1,90 +0,0 @@
-/**
- * Webhook bearer-token management for the rules engine.
- *
- * Responsibilities:
- *   - Resolve the bearer token the listener will accept. The order is
- *     env var (SWITCHBOT_WEBHOOK_TOKEN) → on-disk cache
- *     (~/.switchbot/webhook-token, chmod 0600) → generate a fresh
- *     32-byte hex token and persist it.
- *   - Rotate the token on demand (`rules webhook-rotate-token` cli).
- *
- * Why not the OS keychain (F1 abstraction)? The webhook bearer is a
- * single opaque string, whereas `CredentialStore` is shaped around the
- * SwitchBot {token,secret} bundle. Fitting a one-field artifact into
- * that contract bloats every profile; keeping it in a 0600 file gives
- * the same protection the CLI has used for `~/.switchbot/config.json`.
- * Promotion into the keychain is a future follow-up once the
- * abstraction grows a generic single-value slot.
- */
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { randomBytes } from 'node:crypto';
-const ENV_TOKEN = 'SWITCHBOT_WEBHOOK_TOKEN';
-const DEFAULT_FILE = '.switchbot/webhook-token';
-export class WebhookTokenStore {
-    filePath;
-    envLookup;
-    constructor(opts = {}) {
-        this.filePath = opts.filePath ?? path.join(os.homedir(), DEFAULT_FILE);
-        this.envLookup = opts.envLookup ?? (() => process.env[ENV_TOKEN]);
-    }
-    /**
-     * Return a bearer token, creating + persisting one if none exists yet.
-     * Env var wins when set; otherwise the on-disk token is read (and
-     * generated on first call).
-     */
-    getOrCreate() {
-        const fromEnv = this.envLookup();
-        if (fromEnv && fromEnv.trim().length > 0)
-            return fromEnv.trim();
-        const existing = this.readFromDisk();
-        if (existing)
-            return existing;
-        const fresh = generateToken();
-        this.writeToDisk(fresh);
-        return fresh;
-    }
-    /**
-     * Read the persisted token, returning null when the file is absent
-     * or empty. Does NOT consult the env var — callers that want the
-     * env-aware path should use `getOrCreate()`.
-     */
-    readFromDisk() {
-        try {
-            const raw = fs.readFileSync(this.filePath, 'utf-8').trim();
-            return raw.length > 0 ? raw : null;
-        }
-        catch (err) {
-            if (err.code === 'ENOENT')
-                return null;
-            throw err;
-        }
-    }
-    /** Write a new token, persisting with 0600 perms. */
-    rotate() {
-        const fresh = generateToken();
-        this.writeToDisk(fresh);
-        return fresh;
-    }
-    getFilePath() {
-        return this.filePath;
-    }
-    writeToDisk(token) {
-        const dir = path.dirname(this.filePath);
-        fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(this.filePath, `${token}\n`, { mode: 0o600 });
-        // mkdirSync + writeFileSync race can leave broader perms on Windows
-        // (perm bits are mostly advisory there anyway), but on POSIX we
-        // re-chmod to be explicit about intent.
-        try {
-            fs.chmodSync(this.filePath, 0o600);
-        }
-        catch {
-            // non-POSIX filesystems may reject chmod — intentional best effort.
-        }
-    }
-}
-export function generateToken() {
-    return randomBytes(32).toString('hex');
-}

package/dist/schema/field-aliases.js

@@ -1,131 +0,0 @@
-import { UsageError } from '../utils/output.js';
-/**
- * User-facing aliases for canonical field names.
- *
- * Keys are canonical names (matching API response keys and CLI/schema output);
- * values are lowercase alternatives a user may type for `--fields` or `--filter`.
- *
- * Conflict rules (do not add an alias that violates these — tests will fail):
- * - `temp` is exclusive to `temperature` (NOT `colorTemperature`, `targetTemperature`).
- * - `motion` is exclusive to `moveDetected`; `moving` uses `active` instead.
- * - `mode` is exclusive to top-level `mode` (preset); device-specific modes go through `deviceMode`.
- * - Reserved / too-generic words never appear as aliases: `auto`, `status`, `state`,
- *   `switch`, `type`, `on`, `off`.
- * - Device-type words are never aliases: `lock`, `fan`.
- */
-export const FIELD_ALIASES = {
-    // Identification (shared with list/filter)
-    deviceId: ['id'],
-    deviceName: ['name'],
-    deviceType: ['type'],
-    controlType: ['control'],
-    roomName: ['room'],
-    roomID: ['roomid'],
-    familyName: ['family'],
-    hubDeviceId: ['hub'],
-    enableCloudService: ['cloud'],
-    alias: ['alias'],
-    // Phase 1 — common status fields
-    battery: ['batt', 'bat'],
-    temperature: ['temp', 'ambient'],
-    colorTemperature: ['kelvin', 'colortemp'],
-    humidity: ['humid', 'rh'],
-    brightness: ['bright', 'bri'],
-    fanSpeed: ['speed'],
-    position: ['pos'],
-    moveDetected: ['motion'],
-    openState: ['open'],
-    doorState: ['door'],
-    CO2: ['co2'],
-    power: ['enabled'],
-    mode: ['preset'],
-    // Phase 2 — niche device fields
-    childLock: ['safe', 'childlock'],
-    targetTemperature: ['setpoint', 'target'],
-    electricCurrent: ['current', 'amps'],
-    voltage: ['volts'],
-    usedElectricity: ['energy', 'kwh'],
-    electricityOfDay: ['daily', 'today'],
-    weight: ['load'],
-    version: ['firmware', 'fw'],
-    lightLevel: ['light', 'lux'],
-    oscillation: ['swing', 'osc'],
-    verticalOscillation: ['vswing'],
-    nightStatus: ['night'],
-    chargingStatus: ['charging', 'charge'],
-    switch1Status: ['ch1', 'channel1'],
-    switch2Status: ['ch2', 'channel2'],
-    taskType: ['task'],
-    moving: ['active'],
-    onlineStatus: ['online_status'],
-    workingStatus: ['working'],
-    // Phase 3 — catalog statusFields coverage
-    group: ['cluster'],
-    calibrate: ['calibration', 'calib'],
-    direction: ['tilt'],
-    deviceMode: ['devmode'],
-    nebulizationEfficiency: ['mist', 'spray'],
-    sound: ['audio'],
-    lackWater: ['tank', 'water-low'],
-    filterElement: ['filter'],
-    color: ['rgb', 'hex'],
-    useTime: ['runtime', 'uptime'],
-    switchStatus: ['relay'],
-    lockState: ['locked'],
-    slidePosition: ['slide'],
-    // Phase 4 — ultra-niche sensor + webhook fields (~98% coverage target)
-    waterLeakDetect: ['leak', 'water'],
-    pressure: ['press', 'pa'],
-    moveCount: ['movecnt'],
-    errorCode: ['err'],
-    buttonName: ['btn', 'button'],
-    pressedAt: ['pressed'],
-    deviceMac: ['mac'],
-    detectionState: ['detected', 'detect'],
-};
-/**
- * Resolve a user-typed field name to its canonical form against an allowed list.
- *
- * Matching is case-insensitive and trims surrounding whitespace. Direct matches
- * win over alias matches. Throws UsageError if the input is empty or does not
- * match any canonical / alias in the allowed list.
- */
-export function resolveField(input, allowedCanonical) {
-    const normalized = input.trim().toLowerCase();
-    if (!normalized) {
-        throw new UsageError('Field name cannot be empty.');
-    }
-    for (const canonical of allowedCanonical) {
-        if (canonical.toLowerCase() === normalized)
-            return canonical;
-    }
-    for (const canonical of allowedCanonical) {
-        const aliases = FIELD_ALIASES[canonical] ?? [];
-        if (aliases.some((a) => a.toLowerCase() === normalized))
-            return canonical;
-    }
-    throw new UsageError(`Unknown field "${input}". Supported: ${listSupportedFieldInputs(allowedCanonical).join(', ')}`);
-}
-/**
- * Resolve every field in a list. Preserves order and the original UsageError
- * from resolveField() on the first unknown input.
- */
-export function resolveFieldList(inputs, allowedCanonical) {
-    return inputs.map((f) => resolveField(f, allowedCanonical));
-}
-export function listSupportedFieldInputs(allowedCanonical) {
-    const out = new Set();
-    for (const canonical of allowedCanonical) {
-        out.add(canonical);
-        for (const alias of FIELD_ALIASES[canonical] ?? [])
-            out.add(alias);
-    }
-    return [...out];
-}
-/**
- * All canonical keys known to the alias registry. Use when no dynamic
- * canonical list is available (e.g. `watch` before the first poll response).
- */
-export function listAllCanonical() {
-    return Object.keys(FIELD_ALIASES);
-}

package/dist/sinks/dispatcher.js

@@ -1,12 +0,0 @@
-export class SinkDispatcher {
-    sinks;
-    constructor(sinks) {
-        this.sinks = sinks;
-    }
-    async dispatch(event) {
-        await Promise.allSettled(this.sinks.map((s) => s.write(event)));
-    }
-    async close() {
-        await Promise.allSettled(this.sinks.map((s) => s.close?.()));
-    }
-}

package/dist/sinks/file.js

@@ -1,19 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-export class FileSink {
-    filePath;
-    constructor(filePath) {
-        this.filePath = path.resolve(filePath);
-        const dir = path.dirname(this.filePath);
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-    }
-    async write(event) {
-        try {
-            fs.appendFileSync(this.filePath, JSON.stringify(event) + '\n', { encoding: 'utf-8' });
-        }
-        catch {
-            // best-effort
-        }
-    }
-}

package/dist/sinks/format.js

@@ -1,56 +0,0 @@
-const ICONS = {
-    'Bot': '🤖',
-    'Curtain': '🪟',
-    'Hub': '📡',
-    'Hub 2': '📡',
-    'Hub 3': '📡',
-    'Hub Mini': '📡',
-    'Smart Lock': '🔒',
-    'Smart Lock Pro': '🔒',
-    'Plug': '🔌',
-    'Plug Mini (US)': '🔌',
-    'Plug Mini (JP)': '🔌',
-    'Color Bulb': '💡',
-    'Strip Light': '💡',
-    'Contact Sensor': '🚪',
-    'Motion Sensor': '👁',
-    'Meter': '🌡',
-    'MeterPro': '🌡',
-    'Climate Panel': '🌡',
-    'WoMeter': '🌡',
-    'WoIOSensor': '🌡',
-};
-function icon(deviceType) {
-    return ICONS[deviceType] ?? '📱';
-}
-export function formatEventText(context) {
-    const type = context.deviceType ?? 'Unknown';
-    const pfx = `${icon(type)} ${type}`;
-    const parts = [];
-    if (context.temperature !== undefined)
-        parts.push(`${context.temperature}°C`);
-    if (context.humidity !== undefined)
-        parts.push(`${context.humidity}%`);
-    if (parts.length)
-        return `${pfx}: ${parts.join(' / ')}`;
-    if (context.power !== undefined)
-        return `${pfx}: ${context.power}`;
-    if (context.lockState !== undefined)
-        return `${pfx}: ${context.lockState}`;
-    if (context.openState !== undefined)
-        return `${pfx}: ${context.openState}`;
-    if (context.detectionState !== undefined)
-        return `${pfx}: ${context.detectionState}`;
-    if (context.brightness !== undefined)
-        return `${pfx}: ${context.brightness}`;
-    return `${pfx}: state change`;
-}
-export function parseSinkEvent(payload) {
-    const p = payload;
-    const context = (p?.context ?? {});
-    return {
-        deviceId: String(context.deviceMac ?? 'unknown'),
-        deviceType: String(context.deviceType ?? 'Unknown'),
-        text: formatEventText(context),
-    };
-}

package/dist/sinks/homeassistant.js

@@ -1,44 +0,0 @@
-export class HomeAssistantSink {
-    url;
-    token;
-    webhookId;
-    eventType;
-    constructor(opts) {
-        this.url = opts.url.replace(/\/$/, '');
-        this.token = opts.token;
-        this.webhookId = opts.webhookId;
-        this.eventType = opts.eventType ?? 'switchbot_event';
-    }
-    async write(event) {
-        try {
-            let endpoint;
-            const headers = { 'content-type': 'application/json' };
-            if (this.webhookId) {
-                // Webhook mode: no auth needed, HA triggers automations directly
-                endpoint = `${this.url}/api/webhook/${this.webhookId}`;
-            }
-            else if (this.token) {
-                // REST event API: fires a custom event on the HA event bus
-                endpoint = `${this.url}/api/events/${this.eventType}`;
-                headers['authorization'] = `Bearer ${this.token}`;
-            }
-            else {
-                console.error('[homeassistant] requires --ha-webhook-id or --ha-token');
-                return;
-            }
-            const res = await fetch(endpoint, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(event),
-                signal: AbortSignal.timeout(10000),
-            });
-            if (!res.ok) {
-                const body = await res.text().catch(() => '');
-                console.error(`[homeassistant] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
-            }
-        }
-        catch (err) {
-            console.error(`[homeassistant] error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}

package/dist/sinks/openclaw.js

@@ -1,33 +0,0 @@
-export class OpenClawSink {
-    url;
-    token;
-    model;
-    constructor(opts) {
-        this.url = (opts.url ?? 'http://localhost:18789').replace(/\/$/, '');
-        this.token = opts.token;
-        this.model = opts.model;
-    }
-    async write(event) {
-        try {
-            const res = await fetch(`${this.url}/v1/chat/completions`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    'authorization': `Bearer ${this.token}`,
-                },
-                body: JSON.stringify({
-                    model: this.model,
-                    messages: [{ role: 'user', content: event.text }],
-                }),
-                signal: AbortSignal.timeout(10000),
-            });
-            if (!res.ok) {
-                const body = await res.text().catch(() => '');
-                console.error(`[openclaw] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
-            }
-        }
-        catch (err) {
-            console.error(`[openclaw] error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}

package/dist/sinks/stdout.js

@@ -1,5 +0,0 @@
-export class StdoutSink {
-    async write(event) {
-        console.log(JSON.stringify(event));
-    }
-}

package/dist/sinks/telegram.js

@@ -1,28 +0,0 @@
-export class TelegramSink {
-    token;
-    chatId;
-    constructor(opts) {
-        this.token = opts.token;
-        this.chatId = opts.chatId;
-    }
-    async write(event) {
-        try {
-            const res = await fetch(`https://api.telegram.org/bot${this.token}/sendMessage`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: JSON.stringify({
-                    chat_id: this.chatId,
-                    text: event.text,
-                }),
-                signal: AbortSignal.timeout(10000),
-            });
-            if (!res.ok) {
-                const body = await res.text().catch(() => '');
-                console.error(`[telegram] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
-            }
-        }
-        catch (err) {
-            console.error(`[telegram] error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}

package/dist/sinks/types.js

@@ -1 +0,0 @@
-export {};

package/dist/sinks/webhook.js

@@ -1,22 +0,0 @@
-export class WebhookSink {
-    url;
-    constructor(url) {
-        this.url = url;
-    }
-    async write(event) {
-        try {
-            const res = await fetch(this.url, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: JSON.stringify(event),
-                signal: AbortSignal.timeout(10000),
-            });
-            if (!res.ok) {
-                console.error(`[webhook] POST failed: HTTP ${res.status}`);
-            }
-        }
-        catch (err) {
-            console.error(`[webhook] error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}