@coffeerunhobby/mcp-ha-connect 2.1.0 → 2.2.0

package/src/haClient/events.ts

@@ -39,13 +39,30 @@ export interface HaEvent {
   };
 }
 
+/** Home Assistant answered a command with `success: false` (a refusal, not a connection problem). */
+export class HaCommandError extends Error {
+  constructor(
+    readonly commandType: string,
+    readonly code: string
+  ) {
+    super(`Home Assistant rejected '${commandType}' (${code})`);
+    this.name = 'HaCommandError';
+  }
+}
+
 export interface EventSubscription {
   id: string;
   subscriptionId: number;
+  /** The socket this subscription was sent on (HA forgets it when that socket closes). */
+  connection?: WebSocket | null;
+  /** The subscribe_events command in flight on that socket. */
+  sending?: Promise<number>;
   eventType?: string;
   domain?: string;
   entityId?: string;
   callback: (event: HaEvent) => void;
+  /** Called if Home Assistant refuses the subscription (e.g. a non-admin token); it is then dropped. */
+  onRejected?: (error: HaCommandError) => void;
 }
 
 export interface EventSubscriberConfig {
@@ -53,6 +70,16 @@ export interface EventSubscriberConfig {
   token: string;
   reconnectInterval?: number;
   maxReconnectAttempts?: number;
+  /** Upper bound for the exponential reconnect delay (ms). Default 60 s. */
+  maxReconnectDelay?: number;
+  /** Deadline for connecting and authenticating (ms). Default 30 s. */
+  connectTimeout?: number;
+  /** Verify the TLS certificate of a wss:// Home Assistant (HA_STRICT_SSL). Default true. */
+  strictSsl?: boolean;
+  /** How long a command waits for its result (ms). Default 30 s. */
+  commandTimeout?: number;
+  /** Delay before re-sending subscriptions that failed for a transient reason (ms). Default 30 s. */
+  resubscribeRetryDelay?: number;
 }
 
 /**
@@ -64,21 +91,33 @@ export class EventSubscriber extends EventEmitter {
   private messageId = 1;
   private authenticated = false;
   private subscriptions = new Map<string, EventSubscription>();
-  private pendingSubscriptions: Array<{ resolve: (id: number) => void; reject: (error: Error) => void }> = [];
+  /** Commands awaiting their `result`, keyed by message id (HA answers by id). */
+  private pendingCommands = new Map<
+    number,
+    { type: string; resolve: (result: unknown) => void; reject: (error: Error) => void }
+  >();
   private reconnectAttempts = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Deadline of the connect attempt in progress (cleared on auth_ok or close). */
+  private connectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Pending retry of subscriptions that failed for a transient reason. */
+  private resubscribeTimer: ReturnType<typeof setTimeout> | null = null;
   private isConnecting = false;
   private shouldReconnect = true;
 
   private readonly config: EventSubscriberConfig;
   private readonly reconnectInterval: number;
   private readonly maxReconnectAttempts: number;
+  private readonly maxReconnectDelay: number;
 
   constructor(config: EventSubscriberConfig) {
     super();
     this.config = config;
     this.reconnectInterval = config.reconnectInterval ?? 5000;
-    this.maxReconnectAttempts = config.maxReconnectAttempts ?? 10;
+    // Keep retrying by default: a long Home Assistant outage must not leave the
+    // server permanently deaf to events (the delay is capped, see handleDisconnect).
+    this.maxReconnectAttempts = config.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+    this.maxReconnectDelay = config.maxReconnectDelay ?? 60000;
   }
 
   /**
@@ -107,7 +146,20 @@ export class EventSubscriber extends EventEmitter {
 
         logger.info('Connecting to Home Assistant WebSocket', { url: wsUrl });
 
-        this.ws = new WebSocket(wsUrl);
+        // Same TLS policy as the REST client: only HA_STRICT_SSL=false skips verification.
+        this.ws = new WebSocket(wsUrl, { rejectUnauthorized: this.config.strictSsl !== false });
+        const ws = this.ws;
+        // A connection that never authenticates must not hang its caller.
+        this.clearConnectTimer();
+    if (this.resubscribeTimer) {
+      clearTimeout(this.resubscribeTimer);
+      this.resubscribeTimer = null;
+    }
+        this.connectTimer = setTimeout(() => {
+          this.connectTimer = null;
+          reject(new Error('Timed out connecting to the Home Assistant WebSocket'));
+          ws.terminate();
+        }, this.config.connectTimeout ?? 30000);
 
         this.ws.on('open', () => {
           logger.info('WebSocket connection established');
@@ -125,15 +177,20 @@ export class EventSubscriber extends EventEmitter {
 
         this.ws.on('close', (code, reason) => {
           logger.info('WebSocket connection closed', { code, reason: reason.toString() });
+          this.clearConnectTimer();
           this.authenticated = false;
           this.isConnecting = false;
+          this.rejectPendingCommands(new Error('WebSocket connection closed'));
+          // Closed before authenticating: fail the connect attempt (no-op once resolved).
+          reject(new Error('Home Assistant closed the WebSocket before authentication'));
           this.handleDisconnect();
         });
 
         this.ws.on('error', (error) => {
+          // The detail (often the internal address) stays in the server log.
           logger.error('WebSocket error', { error: error.message });
           this.isConnecting = false;
-          reject(error);
+          reject(new Error('Could not connect to the Home Assistant WebSocket'));
         });
       } catch (error) {
         this.isConnecting = false;
@@ -161,13 +218,18 @@ export class EventSubscriber extends EventEmitter {
         });
         break;
 
-      case 'auth_ok':
+      case 'auth_ok': {
         logger.info('WebSocket authentication successful');
+        this.clearConnectTimer();
         this.authenticated = true;
         this.isConnecting = false;
         this.emit('connected');
         resolveConnect();
+        // HA forgets subscriptions with the connection: (re)send every registered
+        // one, including those queued while Home Assistant was unreachable.
+        void this.resubscribeAll();
         break;
+      }
 
       case 'auth_invalid':
         logger.error('WebSocket authentication failed', { message: message.message });
@@ -193,17 +255,159 @@ export class EventSubscriber extends EventEmitter {
    */
   private handleResult(message: Record<string, unknown>): void {
     const id = message.id as number;
-    const success = message.success as boolean;
-
-    if (this.pendingSubscriptions.length > 0) {
-      const pending = this.pendingSubscriptions.shift()!;
-      if (success) {
-        pending.resolve(id);
-      } else {
-        const error = message.error as { message?: string } | undefined;
-        pending.reject(new Error(error?.message ?? 'Subscription failed'));
+    const pending = this.pendingCommands.get(id);
+    if (!pending) {
+      return;
+    }
+    this.pendingCommands.delete(id);
+    if (message.success) {
+      pending.resolve(message.result);
+    } else {
+      // Callers and logs get only HA's error code (a fixed vocabulary such as
+      // "unauthorized" or "not_found"); HA's free-text message can carry URLs or
+      // other detail and is never passed on or logged.
+      const error = message.error as { code?: string; message?: string } | undefined;
+      const code = typeof error?.code === 'string' && /^[a-z_]{1,40}$/.test(error.code) ? error.code : 'unknown_error';
+      logger.warn('Home Assistant command failed', { type: pending.type, code });
+      pending.reject(new HaCommandError(pending.type, code));
+    }
+  }
+
+  private clearConnectTimer(): void {
+    if (this.connectTimer) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
+  }
+
+  private rejectPendingCommands(error: Error): void {
+    for (const pending of this.pendingCommands.values()) {
+      pending.reject(error);
+    }
+    this.pendingCommands.clear();
+  }
+
+  /**
+   * Send a WebSocket command and resolve with its `result` (rejects on
+   * `success: false`, on disconnect, or after `timeoutMs`).
+   */
+  async sendCommand<T = unknown>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): Promise<T> {
+    return (await this.dispatchCommand<T>(command, timeoutMs)).result;
+  }
+
+  /** Like sendCommand, but also reports the message id the command was sent with. */
+  private async dispatchCommand<T>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): Promise<{ id: number; result: T }> {
+    if (!this.authenticated) {
+      await this.connect();
+    }
+    const { id, result } = this.beginCommand<T>(command, timeoutMs);
+    return { id, result: await result };
+  }
+
+  /**
+   * Send a command now and return its message id synchronously, with a promise
+   * for its result. Callers that must act on the id before the result arrives
+   * (subscriptions) use this directly.
+   */
+  private beginCommand<T>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): { id: number; result: Promise<T> } {
+    const id = this.messageId++;
+    const result = new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingCommands.delete(id);
+        reject(new Error(`Home Assistant command '${command.type}' timed out`));
+      }, timeoutMs);
+      this.pendingCommands.set(id, {
+        type: command.type,
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value as T);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        this.sendMessage({ ...command, id });
+      } catch (error) {
+        clearTimeout(timer);
+        this.pendingCommands.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
       }
+    });
+    return { id, result };
+  }
+
+  /** Send subscribe_events for every registered subscription on a new connection. */
+  private async resubscribeAll(): Promise<void> {
+    for (const sub of this.subscriptions.values()) {
+      if (sub.connection === this.ws) {
+        continue; // already subscribed (or in flight) on this connection
+      }
+      const connection = this.ws;
+      sub.connection = connection;
+      // HA identifies the subscription by this message's id and may send events
+      // right after its confirmation (even in the same read): accept them from
+      // the moment the command is sent, not when the confirmation is processed.
+      const { id, result } = this.beginCommand(
+        sub.eventType ? { type: 'subscribe_events', event_type: sub.eventType } : { type: 'subscribe_events' }
+      );
+      sub.subscriptionId = id;
+      sub.sending = result.then(() => id);
+      try {
+        await sub.sending;
+        logger.info('Event subscription active on new connection', { id: sub.id, eventType: sub.eventType });
+      } catch (error) {
+        if (this.subscriptions.get(sub.id) !== sub) {
+          continue; // unsubscribed meanwhile; unsubscribe() already cancelled it on HA's side
+        }
+        sub.subscriptionId = -1;
+        sub.connection = null;
+        if (error instanceof HaCommandError) {
+          // A refusal (e.g. a non-admin token for a non-allowlisted event) is
+          // permanent: drop it and tell the owner of the subscription.
+          this.subscriptions.delete(sub.id);
+          logger.error('Home Assistant refused an event subscription', { id: sub.id, eventType: sub.eventType, code: error.code });
+          sub.onRejected?.(error);
+        } else {
+          // Unconfirmed (e.g. timed out): HA may still have registered it. HA
+          // handles a connection's messages in order, so cancelling now is safe
+          // either way and keeps a retry from adding a duplicate.
+          if (this.authenticated && this.ws === connection) {
+            this.sendUnsubscribe(id);
+          }
+          logger.warn('Event subscription not confirmed; will retry', {
+            id: sub.id,
+            eventType: sub.eventType,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          this.scheduleResubscribe();
+        }
+      }
+    }
+  }
+
+  /** Retry failed subscriptions later on the same connection (a reconnect also retries them). */
+  private scheduleResubscribe(): void {
+    if (this.resubscribeTimer) {
+      return;
     }
+    this.resubscribeTimer = setTimeout(() => {
+      this.resubscribeTimer = null;
+      if (this.authenticated) {
+        void this.resubscribeAll();
+      }
+    }, this.config.resubscribeRetryDelay ?? 30000);
+    this.resubscribeTimer.unref?.();
   }
 
   /**
@@ -213,9 +417,12 @@ export class EventSubscriber extends EventEmitter {
     const event = message.event as HaEvent;
     if (!event) return;
 
-    // Emit to all matching subscriptions
+    // HA sends one copy of the event per subscription, tagged with that
+    // subscription's id: deliver each copy only to its own subscription, or two
+    // subscriptions to the same event type would each get every event twice.
+    const subscriptionId = message.id as number;
     for (const sub of this.subscriptions.values()) {
-      if (this.eventMatchesSubscription(event, sub)) {
+      if (sub.subscriptionId === subscriptionId && this.eventMatchesSubscription(event, sub)) {
         try {
           sub.callback(event);
         } catch (error) {
@@ -277,7 +484,7 @@ export class EventSubscriber extends EventEmitter {
     }
 
     this.reconnectAttempts++;
-    const delay = this.reconnectInterval * Math.pow(2, this.reconnectAttempts - 1);
+    const delay = Math.min(this.reconnectInterval * Math.pow(2, this.reconnectAttempts - 1), this.maxReconnectDelay);
 
     logger.info('Scheduling reconnect', {
       attempt: this.reconnectAttempts,
@@ -286,6 +493,7 @@ export class EventSubscriber extends EventEmitter {
     });
 
     this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
       this.connect().catch((error) => {
         logger.error('Reconnect failed', { error: error.message });
       });
@@ -304,10 +512,15 @@ export class EventSubscriber extends EventEmitter {
   /**
    * Subscribe to specific event type
    */
-  async subscribeEventType(eventType: string, callback: (event: HaEvent) => void): Promise<string> {
+  async subscribeEventType(
+    eventType: string,
+    callback: (event: HaEvent) => void,
+    onRejected?: (error: HaCommandError) => void
+  ): Promise<string> {
     return this.subscribe({
       eventType,
       callback,
+      onRejected,
     });
   }
 
@@ -334,30 +547,34 @@ export class EventSubscriber extends EventEmitter {
   }
 
   /**
-   * Internal subscribe method
+   * Internal subscribe method.
+   *
+   * The subscription is registered first and then sent on every authenticated
+   * connection: right away when connected, otherwise as soon as Home Assistant
+   * is reachable, and again after any reconnect (HA forgets subscriptions with
+   * the connection). It never fails because Home Assistant is down.
    */
   private async subscribe(options: {
     eventType?: string;
     domain?: string;
     entityId?: string;
     callback: (event: HaEvent) => void;
+    onRejected?: (error: HaCommandError) => void;
   }): Promise<string> {
-    if (!this.authenticated) {
-      await this.connect();
-    }
-
-    const subscriptionId = await this.sendSubscribeEvents(options.eventType);
     const id = `sub_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-    this.subscriptions.set(id, {
+    const entry: EventSubscription = {
       id,
-      subscriptionId,
+      subscriptionId: -1,
+      connection: null,
       eventType: options.eventType,
       domain: options.domain,
       entityId: options.entityId,
       callback: options.callback,
-    });
-
+      // Refusals that arrive later (after HA becomes reachable, or after a
+      // reconnect) are reported here.
+      onRejected: options.onRejected,
+    };
+    this.subscriptions.set(id, entry);
     logger.info('Created event subscription', {
       id,
       eventType: options.eventType,
@@ -365,27 +582,33 @@ export class EventSubscriber extends EventEmitter {
       entityId: options.entityId,
     });
 
-    return id;
-  }
-
-  /**
-   * Send subscribe_events command
-   */
-  private sendSubscribeEvents(eventType?: string): Promise<number> {
-    return new Promise((resolve, reject) => {
-      this.pendingSubscriptions.push({ resolve, reject });
-
-      const message: Record<string, unknown> = {
-        id: this.messageId++,
-        type: 'subscribe_events',
-      };
-
-      if (eventType) {
-        message.event_type = eventType;
+    if (!this.authenticated && !this.reconnectTimer) {
+      try {
+        await this.connect();
+      } catch (error) {
+        logger.warn('Home Assistant WebSocket not reachable; the subscription will be sent once it is', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return id;
       }
-
-      this.sendMessage(message);
-    });
+    }
+    if (this.authenticated) {
+      // Return once Home Assistant has confirmed it. A refusal now is thrown to
+      // the caller (and the subscription dropped) rather than reported to
+      // onRejected; a transient failure leaves it queued.
+      entry.onRejected = undefined;
+      try {
+        await this.resubscribeAll();
+        await entry.sending;
+      } catch (error) {
+        if (error instanceof HaCommandError) {
+          throw error;
+        }
+      } finally {
+        entry.onRejected = options.onRejected;
+      }
+    }
+    return id;
   }
 
   /**
@@ -397,15 +620,24 @@ export class EventSubscriber extends EventEmitter {
       return;
     }
 
-    // Send unsubscribe command
-    this.sendMessage({
-      id: this.messageId++,
-      type: 'unsubscribe_events',
-      subscription: sub.subscriptionId,
-    });
-
+    // Forget it locally first, whatever the connection state, so it is never
+    // restored on a later reconnect.
     this.subscriptions.delete(subscriptionId);
     logger.info('Removed event subscription', { id: subscriptionId });
+
+    // Tell HA if it was sent on the current connection, confirmed or not: HA
+    // handles a connection's messages in order, so the cancel follows the subscribe.
+    if (this.authenticated && sub.connection === this.ws && sub.subscriptionId >= 0) {
+      this.sendUnsubscribe(sub.subscriptionId);
+    }
+  }
+
+  private sendUnsubscribe(haSubscriptionId: number): void {
+    try {
+      this.sendMessage({ id: this.messageId++, type: 'unsubscribe_events', subscription: haSubscriptionId });
+    } catch (error) {
+      logger.debug('Could not send unsubscribe_events', { error: error instanceof Error ? error.message : String(error) });
+    }
   }
 
   /**
@@ -429,6 +661,7 @@ export class EventSubscriber extends EventEmitter {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    this.clearConnectTimer();
 
     if (this.ws) {
       this.ws.close();

package/src/haClient/index.ts

@@ -18,7 +18,8 @@ import type {
 } from '../types/index.js';
 import { logger } from '../utils/logger.js';
 
-import { AutomationOperations } from './automations.js';
+import { AutomationOperations, type AutomationTraceSummary } from './automations.js';
+import { createHaWebSocketCommand } from './wsCommand.js';
 import { ConfigOperations } from './config.js';
 import { DeviceOperations } from './devices.js';
 import { EntityOperations } from './entities.js';
@@ -67,7 +68,12 @@ export class HaClient {
     this.stateOps = new StateOperations(this.request);
     this.serviceOps = new ServiceOperations(this.request);
     this.entityOps = new EntityOperations(this.stateOps);
-    this.automationOps = new AutomationOperations(this.stateOps, this.serviceOps, this.request);
+    this.automationOps = new AutomationOperations(
+      this.stateOps,
+      this.serviceOps,
+      this.request,
+      createHaWebSocketCommand({ baseUrl: config.baseUrl, token: config.token, strictSsl: config.strictSsl })
+    );
     this.historyOps = new HistoryOperations(this.request);
     this.updateOps = new UpdateOperations(this.entityOps);
     this.configOps = new ConfigOperations(this.request);
@@ -226,8 +232,8 @@ export class HaClient {
   /**
    * Get automation execution trace
    */
-  async getAutomationTrace(entityId: string): Promise<unknown[]> {
-    return this.automationOps.getAutomationTrace(entityId);
+  async getAutomationTrace(entityId: string, limit?: number): Promise<AutomationTraceSummary[]> {
+    return this.automationOps.getAutomationTrace(entityId, limit);
   }
 
   // ===== History Operations =====

package/src/haClient/wsCommand.ts

@@ -0,0 +1,44 @@
+/**
+ * One-shot Home Assistant WebSocket command: connect, authenticate, send one
+ * command, return its result, disconnect. For the few HA APIs that exist only
+ * over WebSocket (e.g. automation traces), usable in every transport mode.
+ */
+
+import { EventSubscriber } from './events.js';
+
+export type HaWebSocketCommand = <T = unknown>(command: { type: string; [key: string]: unknown }) => Promise<T>;
+
+export function createHaWebSocketCommand(config: {
+    baseUrl: string;
+    token: string;
+    strictSsl?: boolean;
+    /** One deadline for connecting, authenticating and the command (ms). Default 30 s. */
+    timeoutMs?: number;
+}): HaWebSocketCommand {
+    const timeoutMs = config.timeoutMs ?? 30000;
+    return async <T>(command: { type: string; [key: string]: unknown }): Promise<T> => {
+        const connection = new EventSubscriber({
+            baseUrl: config.baseUrl,
+            token: config.token,
+            strictSsl: config.strictSsl,
+            maxReconnectAttempts: 0,
+            connectTimeout: timeoutMs,
+        });
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const deadline = new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Home Assistant command '${command.type}' timed out`)), timeoutMs);
+        });
+        const work = (async () => {
+            await connection.connect();
+            return await connection.sendCommand<T>(command, timeoutMs);
+        })();
+        // If the deadline wins, the abandoned attempt still settles later: observe it.
+        work.catch(() => undefined);
+        try {
+            return await Promise.race([work, deadline]);
+        } finally {
+            clearTimeout(timer);
+            connection.disconnect();
+        }
+    };
+}

package/src/omadaClient/site.ts

@@ -132,14 +132,29 @@ export function buildSiteUpdateBody(site: OmadaSiteInfo, ntpServers: string[], n
         const dst: NonNullable<SiteUpdateBody['dst']> = {};
         if (enable !== undefined) dst.enable = enable;
         if (mode !== undefined) dst.mode = mode;
-        if (start !== undefined) dst.start = start;
-        if (end !== undefined) dst.end = end;
+        // With DST off the controller returns start/end as `{}` but rejects them on
+        // write ("should not be null"), so only complete points are sent back.
+        if (isCompleteDstTime(start)) dst.start = start;
+        if (isCompleteDstTime(end)) dst.end = end;
         if (offset !== undefined) dst.offset = offset;
+        if (enable === true && (dst.start === undefined || dst.end === undefined)) {
+            throw new Error('Site has daylight saving enabled but an incomplete start/end; refusing to write');
+        }
         body.dst = dst;
     }
     return body;
 }
 
+const DST_TIME_FIELDS = ['month', 'serial', 'day', 'hour', 'minute'] as const;
+
+function isCompleteDstTime(value: unknown): value is DstTime {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const point = value as Record<string, unknown>;
+    return DST_TIME_FIELDS.every((field) => typeof point[field] === 'number');
+}
+
 /**
  * Validate a configured default site (`OMADA_SITE_ID`) against the controller's
  * live site list.