@switchbot/openapi-cli 2.1.0 → 2.2.0

package/dist/commands/events.js

@@ -3,6 +3,15 @@ import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.
 import { SwitchBotMqttClient } from '../mqtt/client.js';
 import { fetchMqttCredential } from '../mqtt/credential.js';
 import { tryLoadConfig } from '../config.js';
+import { SinkDispatcher } from '../sinks/dispatcher.js';
+import { StdoutSink } from '../sinks/stdout.js';
+import { FileSink } from '../sinks/file.js';
+import { WebhookSink } from '../sinks/webhook.js';
+import { OpenClawSink } from '../sinks/openclaw.js';
+import { TelegramSink } from '../sinks/telegram.js';
+import { HomeAssistantSink } from '../sinks/homeassistant.js';
+import { parseSinkEvent } from '../sinks/format.js';
+import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
@@ -192,6 +201,18 @@ Examples:
         .description('Subscribe to SwitchBot MQTT shadow events and stream them as JSONL')
         .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)')
         .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)')
+        .option('--sink <type>', 'Output sink: stdout (default), file, webhook, openclaw, telegram, homeassistant (repeatable)', (val, prev) => [...prev, val], [])
+        .option('--sink-file <path>', 'File path for file sink')
+        .option('--webhook-url <url>', 'Webhook URL for webhook sink')
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)')
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)')
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to')
+        .option('--telegram-token <token>', 'Telegram bot token (or env TELEGRAM_TOKEN)')
+        .option('--telegram-chat <id>', 'Telegram chat/channel ID to send messages to')
+        .option('--ha-url <url>', 'Home Assistant base URL (e.g. http://homeassistant.local:8123)')
+        .option('--ha-token <token>', 'HA long-lived access token (for REST event API)')
+        .option('--ha-webhook-id <id>', 'HA webhook ID (no auth; takes priority over --ha-token)')
+        .option('--ha-event-type <type>', 'HA event type for REST API (default: switchbot_event)')
         .addHelpText('after', `
 Connects to the SwitchBot MQTT service using your existing credentials
 (SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
@@ -200,10 +221,25 @@ No additional MQTT configuration required.
 Output (JSONL, one event per line):
   { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
 
+Sink types (--sink, repeatable):
+  stdout             Print JSONL to stdout (default when no --sink given)
+  file               Append JSONL to --sink-file <path>
+  webhook            HTTP POST to --webhook-url <url>
+  openclaw           POST to OpenClaw via --openclaw-url / --openclaw-token / --openclaw-model
+  telegram           Send to Telegram via --telegram-token / --telegram-chat
+  homeassistant      POST to HA via --ha-url + --ha-webhook-id (or --ha-token)
+
+Device state is also persisted to ~/.switchbot/device-history/<deviceId>.json
+regardless of sink configuration.
+
 Examples:
   $ switchbot events mqtt-tail
-  $ switchbot events mqtt-tail --topic 'switchbot/#'
   $ switchbot events mqtt-tail --max 10 --json
+  $ switchbot events mqtt-tail --sink file --sink-file ~/.switchbot/events.jsonl
+  $ switchbot events mqtt-tail --sink openclaw --openclaw-token abc --openclaw-model home-agent
+  $ switchbot events mqtt-tail --sink telegram --telegram-token <token> --telegram-chat <chatId>
+  $ switchbot events mqtt-tail --sink homeassistant --ha-url http://ha.local:8123 --ha-webhook-id switchbot
+  $ switchbot events mqtt-tail --sink stdout --sink openclaw --openclaw-token abc --openclaw-model home
 `)
         .action(async (options) => {
         try {
@@ -211,20 +247,70 @@ Examples:
             if (maxEvents !== null && (!Number.isInteger(maxEvents) || maxEvents < 1)) {
                 throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
             }
-            let creds;
             const loaded = tryLoadConfig();
             if (!loaded) {
                 throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
             }
-            creds = loaded;
+            const sinkTypes = options.sink;
+            let dispatcher = null;
+            if (sinkTypes.length > 0) {
+                const sinks = sinkTypes.map((type) => {
+                    switch (type) {
+                        case 'stdout':
+                            return new StdoutSink();
+                        case 'file': {
+                            if (!options.sinkFile)
+                                throw new UsageError('--sink file requires --sink-file <path>');
+                            return new FileSink(options.sinkFile);
+                        }
+                        case 'webhook': {
+                            if (!options.webhookUrl)
+                                throw new UsageError('--sink webhook requires --webhook-url <url>');
+                            return new WebhookSink(options.webhookUrl);
+                        }
+                        case 'openclaw': {
+                            const token = options.openclawToken ?? process.env.OPENCLAW_TOKEN;
+                            if (!token)
+                                throw new UsageError('--sink openclaw requires --openclaw-token or env OPENCLAW_TOKEN');
+                            if (!options.openclawModel)
+                                throw new UsageError('--sink openclaw requires --openclaw-model <id>');
+                            return new OpenClawSink({ url: options.openclawUrl, token, model: options.openclawModel });
+                        }
+                        case 'telegram': {
+                            const token = options.telegramToken ?? process.env.TELEGRAM_TOKEN;
+                            if (!token)
+                                throw new UsageError('--sink telegram requires --telegram-token or env TELEGRAM_TOKEN');
+                            if (!options.telegramChat)
+                                throw new UsageError('--sink telegram requires --telegram-chat <id>');
+                            return new TelegramSink({ token, chatId: options.telegramChat });
+                        }
+                        case 'homeassistant': {
+                            if (!options.haUrl)
+                                throw new UsageError('--sink homeassistant requires --ha-url <url>');
+                            if (!options.haWebhookId && !options.haToken) {
+                                throw new UsageError('--sink homeassistant requires --ha-webhook-id or --ha-token');
+                            }
+                            return new HomeAssistantSink({
+                                url: options.haUrl,
+                                token: options.haToken,
+                                webhookId: options.haWebhookId,
+                                eventType: options.haEventType,
+                            });
+                        }
+                        default:
+                            throw new UsageError(`Unknown --sink type "${type}". Supported: stdout, file, webhook, openclaw, telegram, homeassistant`);
+                    }
+                });
+                dispatcher = new SinkDispatcher(sinks);
+            }
             if (!isJsonMode()) {
                 console.error('Fetching MQTT credentials from SwitchBot service…');
             }
-            const credential = await fetchMqttCredential(creds.token, creds.secret);
+            const credential = await fetchMqttCredential(loaded.token, loaded.secret);
             const topic = options.topic ?? credential.topics.status;
             let eventCount = 0;
             const ac = new AbortController();
-            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(creds.token, creds.secret));
+            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(loaded.token, loaded.secret));
             const unsub = client.onMessage((msgTopic, payload) => {
                 let parsed;
                 try {
@@ -233,18 +319,35 @@ Examples:
                 catch {
                     parsed = payload.toString('utf-8');
                 }
-                const record = { t: new Date().toISOString(), topic: msgTopic, payload: parsed };
-                if (isJsonMode()) {
-                    printJson(record);
+                const t = new Date().toISOString();
+                if (dispatcher) {
+                    const { deviceId, deviceType, text } = parseSinkEvent(parsed);
+                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text };
+                    deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
+                    dispatcher.dispatch(sinkEvent).catch(() => { });
                 }
                 else {
-                    console.log(JSON.stringify(record));
+                    // Default behavior: record history + print to stdout
+                    const { deviceId, deviceType } = parseSinkEvent(parsed);
+                    deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
+                    const record = { t, topic: msgTopic, payload: parsed };
+                    if (isJsonMode()) {
+                        printJson(record);
+                    }
+                    else {
+                        console.log(JSON.stringify(record));
+                    }
                 }
                 eventCount++;
                 if (maxEvents !== null && eventCount >= maxEvents) {
                     ac.abort();
                 }
             });
+            const unsubState = client.onStateChange((state) => {
+                if (!isJsonMode()) {
+                    console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
+                }
+            });
             await client.connect();
             client.subscribe(topic);
             if (!isJsonMode()) {
@@ -255,6 +358,8 @@ Examples:
                     process.removeListener('SIGINT', cleanup);
                     process.removeListener('SIGTERM', cleanup);
                     unsub();
+                    unsubState();
+                    dispatcher?.close().catch(() => { });
                     client.disconnect().then(resolve).catch(resolve);
                 };
                 process.once('SIGINT', cleanup);

package/dist/commands/expand.js

@@ -2,6 +2,7 @@ import { handleError, isJsonMode, printJson, UsageError } from '../utils/output.
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
+import { resolveDeviceId } from '../utils/name-resolver.js';
 import { DryRunSignal } from '../api/client.js';
 // ---- Mapping tables --------------------------------------------------------
 const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
@@ -85,8 +86,9 @@ export function registerExpandCommand(devices) {
     devices
         .command('expand')
         .description('Send a command with semantic flags instead of raw positional parameters')
-        .argument('<deviceId>', 'Target device ID from "devices list"')
-        .argument('<command>', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
+        .argument('[deviceId]', 'Target device ID from "devices list" (or use --name)')
+        .argument('[command]', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
         .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)')
         .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary')
         .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high')
@@ -123,9 +125,24 @@ Examples:
   $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
   $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
   $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
+  $ switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
 `)
-        .action(async (deviceId, command, options) => {
+        .action(async (deviceIdArg, commandArg, options) => {
+        let deviceId = '';
+        let command = '';
         try {
+            // When --name is provided, Commander assigns the first positional to deviceIdArg
+            // and leaves commandArg undefined. Detect and shift.
+            let effectiveDeviceIdArg = deviceIdArg;
+            let effectiveCommand = commandArg;
+            if (options.name && deviceIdArg && !commandArg) {
+                effectiveCommand = deviceIdArg;
+                effectiveDeviceIdArg = undefined;
+            }
+            deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            if (!effectiveCommand)
+                throw new UsageError('A command argument is required (setAll, setPosition, setMode).');
+            command = effectiveCommand;
             const cached = getCachedDevice(deviceId);
             const deviceType = cached?.type ?? '';
             let parameter;

package/dist/commands/mcp.js

@@ -8,6 +8,7 @@ import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
+import { deviceHistoryStore } from '../mcp/device-history.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
@@ -110,6 +111,40 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             structuredContent: { status: body },
         };
     });
+    // ---- get_device_history ----------------------------------------------------
+    server.registerTool('get_device_history', {
+        title: 'Get locally-persisted device state history',
+        description: 'Return device state history recorded from MQTT events (persisted to ~/.switchbot/device-history/). ' +
+            'No API call — zero quota cost. Use when you need recent historical readings or want to avoid a live API call. ' +
+            'Omit deviceId to list all devices with stored history.',
+        inputSchema: {
+            deviceId: z.string().optional().describe('Device MAC address (deviceId). Omit to list all devices with history.'),
+            limit: z.number().int().min(1).max(100).optional().describe('Max history entries to return (default 20, max 100)'),
+        },
+        outputSchema: {
+            deviceId: z.string().optional(),
+            latest: z.unknown().optional(),
+            history: z.array(z.unknown()).optional(),
+            devices: z.array(z.object({ deviceId: z.string(), latest: z.unknown() })).optional(),
+        },
+    }, async ({ deviceId, limit }) => {
+        if (deviceId) {
+            const latest = deviceHistoryStore.getLatest(deviceId);
+            const history = deviceHistoryStore.getHistory(deviceId, limit ?? 20);
+            const result = { deviceId, latest, history };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        const ids = deviceHistoryStore.listDevices();
+        const devices = ids.map((id) => ({ deviceId: id, latest: deviceHistoryStore.getLatest(id) }));
+        const result = { devices };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
     // ---- send_command ---------------------------------------------------------
     server.registerTool('send_command', {
         title: 'Send a control command to a device',

package/dist/commands/plan.js

@@ -210,10 +210,18 @@ Workflow:
             process.exit(2);
         }
         if (isJsonMode()) {
-            printJson({ valid: true, steps: result.plan.steps.length });
+            const out = { valid: true, steps: result.plan.steps.length };
+            if (result.plan.steps.length === 0)
+                out.warning = 'plan has no steps — nothing will execute';
+            printJson(out);
         }
         else {
-            console.log(`✓ plan valid (${result.plan.steps.length} step${result.plan.steps.length === 1 ? '' : 's'})`);
+            if (result.plan.steps.length === 0) {
+                console.log('✓ plan valid — but 0 steps: nothing will execute');
+            }
+            else {
+                console.log(`✓ plan valid (${result.plan.steps.length} step${result.plan.steps.length === 1 ? '' : 's'})`);
+            }
         }
     });
     plan

package/dist/commands/scenes.js

@@ -27,7 +27,7 @@ Examples:
                 printJson(scenes);
                 return;
             }
-            renderRows(['sceneId', 'sceneName'], scenes.map((s) => [s.sceneId, s.sceneName]), fmt, resolveFields());
+            renderRows(['sceneId', 'sceneName'], scenes.map((s) => [s.sceneId, s.sceneName]), fmt, resolveFields(), { id: 'sceneId', name: 'sceneName' });
             if (fmt === 'table' && scenes.length === 0) {
                 console.log('No scenes found');
             }

package/dist/commands/watch.js

@@ -3,6 +3,7 @@ import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
 import { createClient } from '../api/client.js';
+import { resolveDeviceId } from '../utils/name-resolver.js';
 const DEFAULT_INTERVAL_MS = 30_000;
 const MIN_INTERVAL_MS = 1_000;
 function diff(prev, next, fields) {
@@ -55,7 +56,8 @@ export function registerWatchCommand(devices) {
     devices
         .command('watch')
         .description('Poll device status on an interval and emit field-level changes (JSONL)')
-        .argument('<deviceId...>', 'One or more deviceIds to watch')
+        .argument('[deviceId...]', 'One or more deviceIds to watch (or use --name for one device)')
+        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)')
         .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, '30s')
         .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)')
         .option('--include-unchanged', 'Emit a tick even when no field changed')
@@ -71,9 +73,18 @@ Examples:
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
+  $ switchbot devices watch --name "客厅空调" --interval 10s
 `)
         .action(async (deviceIds, options) => {
         try {
+            const allIds = [...deviceIds];
+            if (options.name) {
+                const resolved = resolveDeviceId(undefined, options.name);
+                if (!allIds.includes(resolved))
+                    allIds.push(resolved);
+            }
+            if (allIds.length === 0)
+                throw new UsageError('Provide at least one deviceId argument or --name.');
             const parsed = parseDurationToMs(options.interval);
             if (parsed === null || parsed < MIN_INTERVAL_MS) {
                 throw new UsageError(`Invalid --interval "${options.interval}". Minimum is ${MIN_INTERVAL_MS / 1000}s.`);
@@ -101,7 +112,7 @@ Examples:
                     const t = new Date().toISOString();
                     // Poll all devices in parallel; one failure per device doesn't stop
                     // the others.
-                    await Promise.all(deviceIds.map(async (id) => {
+                    await Promise.all(allIds.map(async (id) => {
                         const cached = getCachedDevice(id);
                         try {
                             const body = await fetchDeviceStatus(id, client);

package/dist/index.js

@@ -37,7 +37,8 @@ program
     .option('--no-cache', 'Disable cache reads (equivalent to --cache off)')
     .option('--config <path>', 'Override credential file location (default: ~/.switchbot/config.json)')
     .option('--profile <name>', 'Use a named profile: ~/.switchbot/profiles/<name>.json')
-    .option('--audit-log [path]', 'Append every mutating command to JSONL audit log (default ~/.switchbot/audit.log)')
+    .option('--audit-log', 'Append every mutating command to JSONL audit log (default path: ~/.switchbot/audit.log)')
+    .option('--audit-log-path <path>', 'Custom audit log file path; use together with --audit-log')
     .showHelpAfterError('(run with --help to see usage)')
     .showSuggestionAfterError();
 registerConfigCommand(program);

package/dist/lib/devices.js

@@ -147,9 +147,13 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     const spec = builtinCommands.find((c) => c.command === cmd);
     if (!spec) {
         const unique = [...new Set(builtinCommands.map((c) => c.command))];
+        const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
+        const hint = caseMatch
+            ? `Did you mean "${caseMatch}"? Supported commands: ${unique.join(', ')}`
+            : `Supported commands: ${unique.join(', ')}`;
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', `Supported commands: ${unique.join(', ')}`),
+            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
         };
     }
     const noParamExpected = spec.parameter === '—';
@@ -160,6 +164,17 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
             error: new CommandValidationError(`"${cmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${cmd}`),
         };
     }
+    // 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(`"${cmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
+                ? `Example: switchbot devices command <deviceId> ${cmd} "${example}"`
+                : `See: switchbot devices commands ${cached.type}`),
+        };
+    }
     return { ok: true };
 }
 /**

package/dist/mcp/device-history.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const MAX_HISTORY = 100;
+function historyDir() {
+    return path.join(os.homedir(), '.switchbot', 'device-history');
+}
+export class DeviceHistoryStore {
+    dir;
+    constructor() {
+        this.dir = historyDir();
+    }
+    record(deviceId, topic, deviceType, payload, t) {
+        try {
+            if (!fs.existsSync(this.dir))
+                fs.mkdirSync(this.dir, { recursive: true });
+            const file = path.join(this.dir, `${deviceId}.json`);
+            const existing = fs.existsSync(file)
+                ? JSON.parse(fs.readFileSync(file, 'utf-8'))
+                : { latest: null, history: [] };
+            const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
+            existing.latest = entry;
+            existing.history = [entry, ...existing.history].slice(0, MAX_HISTORY);
+            fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // best-effort — history loss is non-fatal
+        }
+    }
+    getLatest(deviceId) {
+        try {
+            const file = path.join(this.dir, `${deviceId}.json`);
+            if (!fs.existsSync(file))
+                return null;
+            return JSON.parse(fs.readFileSync(file, 'utf-8')).latest;
+        }
+        catch {
+            return null;
+        }
+    }
+    getHistory(deviceId, limit = 20) {
+        try {
+            const file = path.join(this.dir, `${deviceId}.json`);
+            if (!fs.existsSync(file))
+                return [];
+            const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return data.history.slice(0, Math.min(limit, MAX_HISTORY));
+        }
+        catch {
+            return [];
+        }
+    }
+    listDevices() {
+        try {
+            if (!fs.existsSync(this.dir))
+                return [];
+            return fs.readdirSync(this.dir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => f.slice(0, -5));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+export const deviceHistoryStore = new DeviceHistoryStore();

package/dist/mcp/events-subscription.js

@@ -5,6 +5,7 @@ import { fetchDeviceList } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { createClient } from '../api/client.js';
 import { log } from '../logger.js';
+import { deviceHistoryStore } from './device-history.js';
 export class EventSubscriptionManager {
     mqttClient = null;
     subscribers = new Map();
@@ -35,12 +36,18 @@ export class EventSubscriptionManager {
             client.onMessage((topic, payload) => {
                 try {
                     const data = JSON.parse(payload.toString());
-                    const deviceId = this.extractDeviceId(topic);
-                    if (deviceId && data.state) {
+                    // Support SwitchBot direct format: { eventType, context: { deviceMac, deviceType, ... } }
+                    // and AWS IoT shadow format: $aws/things/<id>/shadow/... with data.state
+                    const context = data.context;
+                    const deviceId = context?.deviceMac ?? this.extractDeviceId(topic);
+                    const payloadData = context ?? data.state;
+                    const deviceType = String(context?.deviceType ?? 'Unknown');
+                    if (deviceId && payloadData) {
+                        deviceHistoryStore.record(deviceId, topic, deviceType, payloadData);
                         this.addEvent({
                             kind: 'shadow.updated',
                             deviceId,
-                            payload: data.state,
+                            payload: payloadData,
                             timestamp: Date.now(),
                         });
                     }

package/dist/mqtt/client.js

@@ -17,6 +17,14 @@ export class SwitchBotMqttClient {
     async connect() {
         if (this.client && this.state === 'connected')
             return;
+        // Remove stale listeners before replacing the client instance, otherwise
+        // the old client's close event fires after the new connection is established
+        // (AWS IoT drops the old session), triggering a spurious reconnect loop.
+        if (this.client) {
+            this.client.removeAllListeners();
+            this.client.end(true);
+            this.client = null;
+        }
         this.setState('connecting');
         this.credentialExpired = false;
         this.reconnectAttempts = 0;

package/dist/mqtt/credential.js

@@ -2,8 +2,9 @@ import crypto from 'node:crypto';
 import { buildAuthHeaders } from '../auth.js';
 const CREDENTIAL_ENDPOINT = 'https://api.switchbot.net/v1.1/iot/credential';
 export async function fetchMqttCredential(token, secret) {
-    // Derive a stable instance ID per token so the server can track this client.
-    const instanceId = crypto.createHash('sha256').update(token).digest('hex').slice(0, 16);
+    // Use a random instanceId so each CLI session gets its own clientId, avoiding
+    // conflicts with the SwitchBot cloud service that shares the same account credentials.
+    const instanceId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);
     const headers = buildAuthHeaders(token, secret);
     const res = await fetch(CREDENTIAL_ENDPOINT, {
         method: 'POST',

package/dist/sinks/dispatcher.js

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,56 @@
+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),
+    };
+}