@switchbot/openapi-cli 2.6.3 → 2.7.2

package/dist/commands/watch.js

@@ -1,10 +1,11 @@
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitStreamHeader } from '../utils/output.js';
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
 import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
+import { resolveFieldList, listAllCanonical } from '../schema/field-aliases.js';
 const DEFAULT_INTERVAL_MS = 30_000;
 const MIN_INTERVAL_MS = 1_000;
 function diff(prev, next, fields) {
@@ -101,7 +102,15 @@ Examples:
                 maxTicks = Math.floor(n);
             }
             const forMs = options.for ? parseDurationToMs(options.for) : null;
-            const fields = getFields() ?? null;
+            const rawFields = getFields() ?? null;
+            // Resolve aliases upfront against the static canonical registry.
+            // Validating here lets UsageError exit the command before any
+            // polling starts, and keeps mid-loop error handling free of
+            // "misuse" concerns. Unknown fields that are not registered as
+            // aliases but happen to match an API key pass through unchanged.
+            const fields = rawFields
+                ? resolveFieldList(rawFields, listAllCanonical())
+                : null;
             const ac = new AbortController();
             const onSig = () => ac.abort();
             process.on('SIGINT', onSig);
@@ -109,6 +118,10 @@ Examples:
             const forTimer = forMs !== null && forMs > 0
                 ? setTimeout(() => ac.abort(), forMs)
                 : null;
+            // P7: streaming JSON contract — first line under --json is the
+            // stream header so consumers can route by eventKind/cadence.
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'tick', cadence: 'poll' });
             try {
                 const prev = new Map();
                 const client = createClient();

package/dist/config.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { getConfigPath } from './utils/flags.js';
 import { getActiveProfile } from './lib/request-context.js';
+import { emitJsonError, isJsonMode } from './utils/output.js';
 function sanitizeOptionalString(v) {
     if (typeof v !== 'string')
         return undefined;
@@ -51,20 +52,36 @@ export function loadConfig() {
         const hint = profile
             ? `No credentials configured for profile "${profile}". Run: switchbot --profile ${profile} config set-token <token> <secret>`
             : 'No credentials configured. Run: switchbot config set-token <token> <secret>';
-        console.error(`${hint}\nOr set SWITCHBOT_TOKEN and SWITCHBOT_SECRET environment variables.`);
+        const msg = `${hint}\nOr set SWITCHBOT_TOKEN and SWITCHBOT_SECRET environment variables.`;
+        if (isJsonMode()) {
+            emitJsonError({ code: 1, kind: 'runtime', message: hint });
+        }
+        else {
+            console.error(msg);
+        }
         process.exit(1);
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         if (!cfg.token || !cfg.secret) {
-            console.error('Invalid config format. Please re-run: switchbot config set-token');
+            if (isJsonMode()) {
+                emitJsonError({ code: 1, kind: 'runtime', message: 'Invalid config format. Please re-run: switchbot config set-token' });
+            }
+            else {
+                console.error('Invalid config format. Please re-run: switchbot config set-token');
+            }
             process.exit(1);
         }
         return cfg;
     }
     catch {
-        console.error('Failed to read config file. Please re-run: switchbot config set-token');
+        if (isJsonMode()) {
+            emitJsonError({ code: 1, kind: 'runtime', message: 'Failed to read config file. Please re-run: switchbot config set-token' });
+        }
+        else {
+            console.error('Failed to read config file. Please re-run: switchbot config set-token');
+        }
         process.exit(1);
     }
 }
@@ -156,36 +173,63 @@ export function readProfileMeta(profile) {
     }
 }
 export function showConfig() {
+    const summary = getConfigSummary();
+    if (summary.source === 'env') {
+        console.log('Credential source: environment variables');
+        console.log(`token : ${summary.token ?? ''}`);
+        console.log(`secret: ${summary.secret ?? ''}`);
+        return;
+    }
+    if (summary.source === 'none') {
+        console.log('No credentials configured');
+        return;
+    }
+    if (summary.source === 'invalid') {
+        console.error('Failed to read config file');
+        return;
+    }
+    console.log(`Credential source: ${summary.path}`);
+    if (summary.label)
+        console.log(`label : ${summary.label}`);
+    if (summary.description)
+        console.log(`desc  : ${summary.description}`);
+    console.log(`token : ${summary.token ?? ''}`);
+    console.log(`secret: ${summary.secret ?? ''}`);
+    if (summary.dailyCap)
+        console.log(`limits: dailyCap=${summary.dailyCap}`);
+    if (summary.defaultFlags?.length)
+        console.log(`defaults: ${summary.defaultFlags.join(' ')}`);
+}
+export function getConfigSummary() {
     const envToken = process.env.SWITCHBOT_TOKEN;
     const envSecret = process.env.SWITCHBOT_SECRET;
     if (envToken && envSecret) {
-        console.log('Credential source: environment variables');
-        console.log(`token : ${maskCredential(envToken)}`);
-        console.log(`secret: ${maskSecret(envSecret)}`);
-        return;
+        return {
+            source: 'env',
+            token: maskCredential(envToken),
+            secret: maskSecret(envSecret),
+        };
     }
     const file = configFilePath();
     if (!fs.existsSync(file)) {
-        console.log('No credentials configured');
-        return;
+        return { source: 'none' };
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
-        console.log(`Credential source: ${file}`);
-        if (cfg.label)
-            console.log(`label : ${cfg.label}`);
-        if (cfg.description)
-            console.log(`desc  : ${cfg.description}`);
-        console.log(`token : ${maskCredential(cfg.token)}`);
-        console.log(`secret: ${maskSecret(cfg.secret)}`);
-        if (cfg.limits?.dailyCap)
-            console.log(`limits: dailyCap=${cfg.limits.dailyCap}`);
-        if (cfg.defaults?.flags?.length)
-            console.log(`defaults: ${cfg.defaults.flags.join(' ')}`);
+        return {
+            source: 'file',
+            path: file,
+            label: cfg.label,
+            description: cfg.description,
+            token: maskCredential(cfg.token),
+            secret: maskSecret(cfg.secret),
+            dailyCap: cfg.limits?.dailyCap,
+            defaultFlags: cfg.defaults?.flags,
+        };
     }
     catch {
-        console.error('Failed to read config file');
+        return { source: 'invalid', path: file };
     }
 }
 function maskCredential(token) {

package/dist/devices/catalog.js

@@ -7,14 +7,99 @@
  *   - 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.
+ *   - CommandSpec.safetyTier: explicit action safety classification. See
+ *     SafetyTier for the 5-tier enum. Built-in entries set this on the
+ *     destructive tier; other tiers are derived (see deriveSafetyTier).
+ *   - CommandSpec.destructive (deprecated, v3.0 removal): legacy boolean
+ *     that maps to safetyTier === 'destructive'. Still accepted in
+ *     ~/.switchbot/catalog.json overlays and derived into safetyTier.
  *   - 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'.
  */
+/**
+ * Catalog shape version. Bump when any of the exported interfaces
+ * (CommandSpec / DeviceCatalogEntry / SafetyTier) gain/lose/rename a
+ * load-bearing field. The agent-bootstrap payload's schemaVersion must
+ * stay pinned to this value; `doctor` fails the `catalog-schema` check
+ * when they drift.
+ */
+export const CATALOG_SCHEMA_VERSION = '1.0';
+/**
+ * Human-readable descriptions for common status fields. Populated from
+ * the SwitchBot API v1.1 docs. Used by deriveStatusQueries() so every
+ * query has a meaningful description even when the entry itself only
+ * declares the field name.
+ */
+const STATUS_FIELD_DESCRIPTIONS = {
+    power: 'Power state (on/off)',
+    battery: 'Battery percentage (0-100)',
+    version: 'Firmware version string',
+    temperature: 'Ambient temperature (°C)',
+    humidity: 'Ambient humidity (% RH)',
+    CO2: 'CO2 concentration (ppm)',
+    brightness: 'Current brightness (0-100)',
+    color: 'Current RGB color (r:g:b)',
+    colorTemperature: 'Color temperature in Kelvin',
+    mode: 'Operating mode',
+    deviceMode: 'Hardware mode (Bot-specific)',
+    lockState: 'Lock state (locked/unlocked)',
+    doorState: 'Door contact state (open/closed)',
+    calibrate: 'Calibration status',
+    moving: 'Motion in progress (boolean)',
+    slidePosition: 'Slide position (0-100)',
+    group: 'Multi-device group membership',
+    direction: 'Tilt direction',
+    voltage: 'Line voltage',
+    electricCurrent: 'Instantaneous current draw',
+    electricityOfDay: 'kWh consumed today',
+    usedElectricity: 'Cumulative kWh',
+    useTime: 'Total runtime (seconds)',
+    weight: 'Load / weight reading',
+    switchStatus: 'Relay state (integer encoded)',
+    switch1Status: 'Channel 1 relay state',
+    switch2Status: 'Channel 2 relay state',
+    workingStatus: 'Device working status (vacuum/purifier)',
+    onlineStatus: 'Online / offline (string)',
+    online: 'Online / offline (boolean or int)',
+    taskType: 'Current task identifier',
+    nightStatus: 'Night-mode status',
+    oscillation: 'Horizontal oscillation on/off',
+    verticalOscillation: 'Vertical oscillation on/off',
+    chargingStatus: 'Charging (boolean)',
+    fanSpeed: 'Current fan speed level',
+    nebulizationEfficiency: 'Humidifier mist level',
+    childLock: 'Child-lock engaged',
+    sound: 'Beep / audio feedback enabled',
+    lackWater: 'Water tank low (boolean)',
+    filterElement: 'Filter life remaining',
+    auto: 'Auto mode enabled',
+    targetTemperature: 'Thermostat target temperature',
+    moveDetected: 'Motion detected (boolean)',
+    openState: 'Contact sensor open/closed',
+    status: 'Device-specific status word',
+    lightLevel: 'Ambient light level',
+};
+/**
+ * P11: derive the read-only query list for an entry. If the entry has
+ * explicit `statusQueries`, return them as-is; otherwise synthesize one
+ * ReadOnlyQuerySpec per `statusFields` entry, all keyed to the `status`
+ * endpoint. IR-category entries have no status channel so return [].
+ */
+export function deriveStatusQueries(entry) {
+    if (entry.statusQueries && entry.statusQueries.length > 0)
+        return entry.statusQueries;
+    if (entry.category === 'ir')
+        return [];
+    const fields = entry.statusFields ?? [];
+    return fields.map((f) => ({
+        field: f,
+        description: STATUS_FIELD_DESCRIPTIONS[f] ?? `${f} (see API docs)`,
+        endpoint: 'status',
+        safetyTier: 'read',
+    }));
+}
 // ---- Command fragments (reused across entries) -------------------------
 const onOff = [
     { command: 'turnOn', parameter: '—', description: 'Power on', idempotent: true },
@@ -64,7 +149,7 @@ export const DEVICE_CATALOG = [
         aliases: ['Smart Lock Pro'],
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
             { command: 'deadbolt', parameter: '—', description: 'Pro only: engage deadbolt', idempotent: true },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
@@ -76,7 +161,7 @@ export const DEVICE_CATALOG = [
         role: 'security',
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
     },
@@ -87,7 +172,7 @@ export const DEVICE_CATALOG = [
         role: 'security',
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
             { command: 'deadbolt', parameter: '—', description: 'Engage deadbolt', idempotent: true },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
@@ -219,7 +304,7 @@ export const DEVICE_CATALOG = [
         category: 'physical',
         description: 'Entry-level robot vacuum with start/stop/dock and four suction power levels.',
         role: 'cleaning',
-        aliases: ['Robot Vacuum Cleaner S1 Plus', 'K10+'],
+        aliases: ['Robot Vacuum', 'Robot Vacuum Cleaner S1 Plus', 'K10+'],
         commands: [
             { command: 'start', parameter: '—', description: 'Start cleaning', idempotent: true },
             { command: 'stop', parameter: '—', description: 'Stop cleaning', idempotent: true },
@@ -306,8 +391,8 @@ export const DEVICE_CATALOG = [
         description: 'Cloud-connected garage door controller; turnOn opens and turnOff closes the door.',
         role: 'security',
         commands: [
-            { command: 'turnOn', parameter: '—', description: 'Open the garage door', idempotent: true, destructive: true, destructiveReason: 'Opens the garage door — anyone nearby can enter the space.' },
-            { command: 'turnOff', parameter: '—', description: 'Close the garage door', idempotent: true, destructive: true, destructiveReason: 'Closes the garage door — verify no person or obstacle is in the way.' },
+            { command: 'turnOn', parameter: '—', description: 'Open the garage door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Opens the garage door — anyone nearby can enter the space.' },
+            { command: 'turnOff', parameter: '—', description: 'Close the garage door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Closes the garage door — verify no person or obstacle is in the way.' },
         ],
         statusFields: ['switchStatus', 'version', 'online'],
     },
@@ -329,8 +414,8 @@ export const DEVICE_CATALOG = [
         role: 'security',
         aliases: ['Keypad Touch'],
         commands: [
-            { command: 'createKey', parameter: '\'{"name":"...","type":"permanent|timeLimit|disposable|urgent","password":"6-12 digits","startTime":<s>,"endTime":<s>}\'', description: 'Create a passcode (async; result via webhook)', idempotent: false, destructive: true, destructiveReason: 'Provisions a new access credential — anyone with this passcode can unlock the door.' },
-            { command: 'deleteKey', parameter: '\'{"id":<passcode_id>}\'', description: 'Delete a passcode (async; result via webhook)', idempotent: true, destructive: true, destructiveReason: 'Permanently removes a passcode — the holder immediately loses door access.' },
+            { command: 'createKey', parameter: '\'{"name":"...","type":"permanent|timeLimit|disposable|urgent","password":"6-12 digits","startTime":<s>,"endTime":<s>}\'', description: 'Create a passcode (async; result via webhook)', idempotent: false, safetyTier: 'destructive', safetyReason: 'Provisions a new access credential — anyone with this passcode can unlock the door.' },
+            { command: 'deleteKey', parameter: '\'{"id":<passcode_id>}\'', description: 'Delete a passcode (async; result via webhook)', idempotent: true, safetyTier: 'destructive', safetyReason: 'Permanently removes a passcode — the holder immediately loses door access.' },
         ],
         statusFields: ['version'],
     },
@@ -538,13 +623,41 @@ export function findCatalogEntry(query) {
         return matches[0];
     return matches;
 }
+/**
+ * Derive the safety tier for a catalog command, honouring an explicit
+ * `safetyTier` when present and falling back to heuristic inference.
+ *
+ * The inference order is:
+ *   1. Explicit `spec.safetyTier`.
+ *   2. Legacy `spec.destructive: true` → `'destructive'` (overlay compat).
+ *   3. IR context (customize command OR entry.category === 'ir')
+ *      → `'ir-fire-forget'`.
+ *   4. Default → `'mutation'`.
+ */
+export function deriveSafetyTier(spec, entry) {
+    if (spec.safetyTier)
+        return spec.safetyTier;
+    if (spec.destructive)
+        return 'destructive';
+    if (spec.commandType === 'customize')
+        return 'ir-fire-forget';
+    if (entry?.category === 'ir')
+        return 'ir-fire-forget';
+    return 'mutation';
+}
+/** Read the safety reason for a command, with fallback to the legacy field. */
+export function getCommandSafetyReason(spec) {
+    return spec.safetyReason ?? spec.destructiveReason ?? 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 function suggestedActions(entry) {
-    const safe = entry.commands.filter((c) => c.idempotent === true && !c.destructive && c.commandType !== 'customize');
+    const safe = entry.commands.filter((c) => c.idempotent === true &&
+        deriveSafetyTier(c, entry) !== 'destructive' &&
+        c.commandType !== 'customize');
     const picks = [];
     const seen = new Set();
     for (const c of safe) {

package/dist/devices/resources.js

@@ -0,0 +1,270 @@
+/**
+ * Declarative metadata for non-device resources exposed by the SwitchBot API:
+ * scenes, webhooks, and keypad credentials ("keys").
+ *
+ * Consumed by `capabilities --json` and `schema export` so AI agents can
+ * discover these surfaces the same way they discover device commands.
+ *
+ * Scope:
+ * - Descriptive metadata only (no runtime execution — CLI/MCP handlers stay
+ *   source-of-truth for behavior).
+ * - Webhook event list is derived from the device catalog and is advisory —
+ *   not every SwitchBot device actually pushes every listed event; refer to
+ *   the SwitchBot webhook docs for authoritative shapes.
+ */
+const COMMON_WEBHOOK_FIELDS = [
+    { name: 'deviceType', type: 'string', description: 'SwitchBot device type string', example: 'WoMeter' },
+    { name: 'deviceMac', type: 'string', description: 'Bluetooth MAC address (uppercase, colon-separated)', example: 'AA:BB:CC:11:22:33' },
+    { name: 'timeOfSample', type: 'timestamp', description: 'Millisecond Unix timestamp when the sample was taken', example: 1700000000000 },
+];
+export const RESOURCE_CATALOG = {
+    scenes: {
+        description: 'Manual scenes (IFTTT-style rules) authored in the SwitchBot app. Execution is fire-and-forget from the cloud — side-effects happen on the user\'s devices.',
+        operations: [
+            {
+                verb: 'list',
+                method: 'GET',
+                endpoint: '/v1.1/scenes',
+                params: [],
+                safetyTier: 'read',
+            },
+            {
+                verb: 'execute',
+                method: 'POST',
+                endpoint: '/v1.1/scenes/{sceneId}/execute',
+                params: [{ name: 'sceneId', required: true, type: 'string' }],
+                safetyTier: 'mutation',
+            },
+            {
+                verb: 'describe',
+                method: 'GET',
+                endpoint: '/v1.1/scenes/{sceneId}',
+                params: [{ name: 'sceneId', required: true, type: 'string' }],
+                safetyTier: 'read',
+            },
+        ],
+    },
+    webhooks: {
+        endpoints: [
+            {
+                verb: 'setup',
+                method: 'POST',
+                path: '/v1.1/webhook/setupWebhook',
+                safetyTier: 'mutation',
+                requiredParams: ['url'],
+            },
+            {
+                verb: 'query',
+                method: 'POST',
+                path: '/v1.1/webhook/queryWebhook',
+                safetyTier: 'read',
+                requiredParams: ['action'],
+            },
+            {
+                verb: 'update',
+                method: 'POST',
+                path: '/v1.1/webhook/updateWebhook',
+                safetyTier: 'mutation',
+                requiredParams: ['url', 'enable'],
+            },
+            {
+                verb: 'delete',
+                method: 'POST',
+                path: '/v1.1/webhook/deleteWebhook',
+                safetyTier: 'destructive',
+                requiredParams: ['url'],
+            },
+        ],
+        events: [
+            {
+                eventType: 'WoMeter',
+                devicePattern: 'Meter / Meter Plus / Indoor-Outdoor Meter',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius', example: 22.5 },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)', example: 45 },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)', example: 88 },
+                ],
+            },
+            {
+                eventType: 'WoCO2Sensor',
+                devicePattern: 'CO2 Monitor',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'CO2', type: 'number', description: 'CO2 concentration in ppm', example: 520 },
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
+                ],
+            },
+            {
+                eventType: 'WoPresence',
+                devicePattern: 'Motion Sensor / Video Doorbell motion',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'detectionState', type: 'string', description: 'Detection result word', example: 'DETECTED' },
+                ],
+            },
+            {
+                eventType: 'WoContact',
+                devicePattern: 'Contact Sensor',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'openState', type: 'string', description: 'Door/window state', example: 'open' },
+                    { name: 'moveDetected', type: 'boolean', description: 'Motion detected during this sample' },
+                ],
+            },
+            {
+                eventType: 'WoLock',
+                devicePattern: 'Smart Lock / Smart Lock Lite / Smart Lock Pro',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'lockState', type: 'string', description: 'Lock state: locked, unlocked, jammed', example: 'locked' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoPlug',
+                devicePattern: 'Plug Mini / Plug / Relay Switch',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)', example: 'on' },
+                    { name: 'voltage', type: 'number', description: 'Instantaneous voltage (V)' },
+                    { name: 'electricCurrent', type: 'number', description: 'Instantaneous current (A)' },
+                ],
+            },
+            {
+                eventType: 'WoBot',
+                devicePattern: 'Bot',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoCurtain',
+                devicePattern: 'Curtain / Blind Tilt / Roller Shade',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'slidePosition', type: 'number', description: 'Current slide position (0–100)' },
+                    { name: 'calibrate', type: 'boolean', description: 'True if device is calibrated' },
+                ],
+            },
+            {
+                eventType: 'WoDoorbell',
+                devicePattern: 'Video Doorbell button press',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'buttonName', type: 'string', description: 'Identifier of the pressed button' },
+                    { name: 'pressedAt', type: 'timestamp', description: 'Press timestamp in milliseconds' },
+                ],
+            },
+            {
+                eventType: 'WoKeypad',
+                devicePattern: 'Keypad scan / createKey result / deleteKey result',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'eventType', type: 'string', description: 'Sub-event (createKey / deleteKey / invalidCode)' },
+                    { name: 'commandId', type: 'string', description: 'Correlation id returned by the original command' },
+                    { name: 'result', type: 'string', description: 'Outcome (success / failed / timeout)' },
+                ],
+            },
+            {
+                eventType: 'WoColorBulb',
+                devicePattern: 'Color Bulb',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
+                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
+                    { name: 'colorTemperature', type: 'number', description: 'Color temperature in Kelvin' },
+                ],
+            },
+            {
+                eventType: 'WoStrip',
+                devicePattern: 'Strip Light',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
+                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
+                ],
+            },
+            {
+                eventType: 'WoSweeper',
+                devicePattern: 'Robot Vacuum',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'workingStatus', type: 'string', description: 'Cleaning state' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                    { name: 'taskType', type: 'string', description: 'Current task (standby / clean / charge)' },
+                ],
+            },
+            {
+                eventType: 'WoWaterLeakDetect',
+                devicePattern: 'Water Leak Detector',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'waterLeakDetect', type: 'number', description: 'Leak flag (0 = dry, 1 = leak detected)' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoHub',
+                devicePattern: 'Hub 2 / Hub 3 (ambient sensors)',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
+                    { name: 'lightLevel', type: 'number', description: 'Illuminance level' },
+                ],
+            },
+        ],
+        constraints: {
+            maxUrlLength: 2048,
+            maxWebhooksPerAccount: 1,
+        },
+    },
+    keys: [
+        {
+            keyType: 'permanent',
+            description: 'Passcode that never expires — valid until manually deleted.',
+            requiredParams: ['name', 'password'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'timeLimit',
+            description: 'Passcode valid only between startTime and endTime (Unix seconds).',
+            requiredParams: ['name', 'password', 'startTime', 'endTime'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'disposable',
+            description: 'Passcode that can be used once and then auto-expires.',
+            requiredParams: ['name', 'password'],
+            optionalParams: ['startTime', 'endTime'],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'urgent',
+            description: 'Emergency passcode (typically tied to panic / audit workflow).',
+            requiredParams: ['name', 'password'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+    ],
+};
+/** Convenience: return the list of known webhook event types. */
+export function listWebhookEventTypes() {
+    return RESOURCE_CATALOG.webhooks.events.map((e) => e.eventType);
+}
+/** Convenience: return the list of supported keypad key types. */
+export function listKeyTypes() {
+    return RESOURCE_CATALOG.keys.map((k) => k.keyType);
+}