@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/src/haClient/history.ts

@@ -1,73 +0,0 @@
-/**
- * History Operations for Home Assistant API
- * Handles historical data and system logs
- */
-
-import type { Entity, LogbookEntry } from '../types/index.js';
-import { logger } from '../utils/logger.js';
-import type { RequestHandler } from './request.js';
-
-/**
- * History-related operations for the Home Assistant API.
- */
-export class HistoryOperations {
-  constructor(private readonly request: RequestHandler) {}
-
-  /**
-   * Get historical data for an entity
-   */
-  async getHistory(entityId: string, hours: number = 24): Promise<Entity[][]> {
-    logger.debug('Fetching history', { entityId, hours });
-
-    const endTime = new Date();
-    const startTime = new Date(endTime.getTime() - hours * 60 * 60 * 1000);
-
-    const path = `/history/period/${startTime.toISOString()}`;
-    const history = await this.request.get<Entity[][]>(path, {
-      filter_entity_id: entityId,
-      end_time: endTime.toISOString(),
-    });
-
-    logger.info('Fetched history', {
-      entityId,
-      hours,
-      records: history[0]?.length ?? 0
-    });
-
-    return history;
-  }
-
-  /**
-   * Get system log entries from the logbook
-   * Returns recent events/state changes, optionally filtered by entity
-   */
-  async getSystemLog(options: {
-    hours?: number;
-    entity_id?: string;
-    limit?: number;
-  } = {}): Promise<LogbookEntry[]> {
-    const hours = Math.min(options.hours || 24, 168); // Cap at 1 week
-    const limit = options.limit || 100;
-    logger.debug('Fetching system log', { hours, entity_id: options.entity_id, limit });
-
-    const endTime = new Date();
-    const startTime = new Date(endTime.getTime() - hours * 60 * 60 * 1000);
-
-    const path = `/logbook/${startTime.toISOString()}`;
-    const params: Record<string, string> = {
-      end_time: endTime.toISOString(),
-    };
-
-    if (options.entity_id) {
-      params.entity = options.entity_id;
-    }
-
-    const entries = await this.request.get<LogbookEntry[]>(path, params);
-
-    // Apply limit - return most recent entries first
-    const limited = entries.slice(-limit);
-
-    logger.info('Fetched system log', { count: entries.length, returned: limited.length, hours, limit });
-    return limited;
-  }
-}

package/src/haClient/index.ts

@@ -1,336 +0,0 @@
-/**
- * Home Assistant API Client
- * Main client class that composes all operation modules
- */
-
-import type {
-  Entity,
-  ServiceCallData,
-  ServiceCallResponse,
-  Automation,
-  AutomationConfig,
-  DomainSummary,
-  HaVersion,
-  LogbookEntry,
-  UpdateInfo,
-  Calendar,
-  CalendarEvent,
-} from '../types/index.js';
-import { logger } from '../utils/logger.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';
-import { HistoryOperations } from './history.js';
-import { RequestHandler } from './request.js';
-import { ServiceOperations } from './services.js';
-import { StateOperations } from './states.js';
-import { UpdateOperations } from './updates.js';
-import { CalendarOperations } from './calendars.js';
-
-export interface HaClientOptions {
-  baseUrl: string;
-  token: string;
-  timeout: number;
-  strictSsl: boolean;
-}
-
-/**
- * Main client for interacting with the Home Assistant API.
- * Organized with dedicated operation classes for each domain.
- */
-export class HaClient {
-  private readonly request: RequestHandler;
-  private readonly stateOps: StateOperations;
-  private readonly serviceOps: ServiceOperations;
-  private readonly entityOps: EntityOperations;
-  private readonly automationOps: AutomationOperations;
-  private readonly historyOps: HistoryOperations;
-  private readonly updateOps: UpdateOperations;
-  private readonly configOps: ConfigOperations;
-  private readonly calendarOps: CalendarOperations;
-  public readonly devices: DeviceOperations;
-
-  constructor(config: HaClientOptions) {
-    logger.debug('Initializing HaClient');
-
-    // Initialize request handler
-    this.request = new RequestHandler({
-      baseUrl: config.baseUrl,
-      token: config.token,
-      timeout: config.timeout,
-      strictSsl: config.strictSsl,
-    });
-
-    // Initialize operation modules with dependencies
-    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,
-      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);
-    this.calendarOps = new CalendarOperations(this.request);
-    this.devices = new DeviceOperations(this.serviceOps, this.stateOps);
-
-    logger.info('HaClient initialized');
-  }
-
-  // ===== State Operations =====
-
-  /**
-   * Get all states (entities)
-   */
-  async getStates(): Promise<Entity[]> {
-    return this.stateOps.getStates();
-  }
-
-  /**
-   * Get state of a specific entity
-   */
-  async getState(entityId: string): Promise<Entity | null> {
-    return this.stateOps.getState(entityId);
-  }
-
-  /**
-   * Get all sensors (sensor.* and binary_sensor.* entities)
-   */
-  async getAllSensors(): Promise<Entity[]> {
-    return this.stateOps.getAllSensors();
-  }
-
-  // ===== Service Operations =====
-
-  /**
-   * Call a service
-   */
-  async callService(data: ServiceCallData): Promise<ServiceCallResponse> {
-    return this.serviceOps.callService(data);
-  }
-
-  /**
-   * Restart Home Assistant
-   */
-  async restartServer(): Promise<void> {
-    return this.serviceOps.restartServer();
-  }
-
-  // ===== Entity Operations =====
-
-  /**
-   * Get entities filtered by domain
-   */
-  async getEntitiesByDomain(domain: string): Promise<Entity[]> {
-    return this.entityOps.getEntitiesByDomain(domain);
-  }
-
-  /**
-   * Search entities by name or entity_id
-   */
-  async searchEntities(query: string): Promise<Entity[]> {
-    return this.entityOps.searchEntities(query);
-  }
-
-  /**
-   * Get domain summary with entity counts and state breakdown
-   */
-  async getDomainSummary(domain: string): Promise<DomainSummary> {
-    return this.entityOps.getDomainSummary(domain);
-  }
-
-  /**
-   * List entities with optional filtering
-   */
-  async listEntities(options: {
-    domain?: string;
-    search?: string;
-    limit?: number;
-    state?: string;
-  } = {}): Promise<Entity[]> {
-    return this.entityOps.listEntities(options);
-  }
-
-  // ===== Automation Operations =====
-
-  /**
-   * Get all automations
-   */
-  async getAutomations(): Promise<Automation[]> {
-    return this.automationOps.getAutomations();
-  }
-
-  /**
-   * Get a single automation by entity_id
-   */
-  async getAutomation(entityId: string): Promise<Automation | null> {
-    return this.automationOps.getAutomation(entityId);
-  }
-
-  /**
-   * Trigger an automation manually
-   */
-  async triggerAutomation(entityId: string, variables?: Record<string, unknown>): Promise<ServiceCallResponse> {
-    return this.automationOps.triggerAutomation(entityId, variables);
-  }
-
-  /**
-   * Enable an automation
-   */
-  async enableAutomation(entityId: string): Promise<ServiceCallResponse> {
-    return this.automationOps.enableAutomation(entityId);
-  }
-
-  /**
-   * Disable an automation
-   */
-  async disableAutomation(entityId: string): Promise<ServiceCallResponse> {
-    return this.automationOps.disableAutomation(entityId);
-  }
-
-  /**
-   * Toggle an automation
-   */
-  async toggleAutomation(entityId: string): Promise<ServiceCallResponse> {
-    return this.automationOps.toggleAutomation(entityId);
-  }
-
-  /**
-   * Reload all automations from configuration
-   */
-  async reloadAutomations(): Promise<void> {
-    return this.automationOps.reloadAutomations();
-  }
-
-  /**
-   * Create a new automation
-   */
-  async createAutomation(config: AutomationConfig): Promise<{ id: string }> {
-    return this.automationOps.createAutomation(config);
-  }
-
-  /**
-   * Update an existing automation
-   */
-  async updateAutomation(automationId: string, config: Partial<AutomationConfig>): Promise<void> {
-    return this.automationOps.updateAutomation(automationId, config);
-  }
-
-  /**
-   * Delete an automation
-   */
-  async deleteAutomation(automationId: string): Promise<void> {
-    return this.automationOps.deleteAutomation(automationId);
-  }
-
-  /**
-   * Get automation execution trace
-   */
-  async getAutomationTrace(entityId: string, limit?: number): Promise<AutomationTraceSummary[]> {
-    return this.automationOps.getAutomationTrace(entityId, limit);
-  }
-
-  // ===== History Operations =====
-
-  /**
-   * Get historical data for an entity
-   */
-  async getHistory(entityId: string, hours: number = 24): Promise<Entity[][]> {
-    return this.historyOps.getHistory(entityId, hours);
-  }
-
-  /**
-   * Get system log entries from the logbook
-   */
-  async getSystemLog(options: {
-    hours?: number;
-    entity_id?: string;
-    limit?: number;
-  } = {}): Promise<LogbookEntry[]> {
-    return this.historyOps.getSystemLog(options);
-  }
-
-  // ===== Update Operations =====
-
-  /**
-   * Get available updates by checking update.* entities
-   */
-  async getAvailableUpdates(): Promise<{
-    updates: UpdateInfo[];
-    entities: Entity[];
-  }> {
-    return this.updateOps.getAvailableUpdates();
-  }
-
-  // ===== Config Operations =====
-
-  /**
-   * Get config
-   */
-  async getConfig(): Promise<Record<string, unknown>> {
-    return this.configOps.getConfig();
-  }
-
-  /**
-   * Check API (health check)
-   */
-  async checkApi(): Promise<{ message: string }> {
-    return this.configOps.checkApi();
-  }
-
-  /**
-   * Get Home Assistant version and configuration info
-   */
-  async getVersion(): Promise<HaVersion> {
-    return this.configOps.getVersion();
-  }
-
-  // ===== Calendar Operations =====
-
-  /**
-   * Get all calendar entities
-   */
-  async getCalendars(): Promise<Calendar[]> {
-    return this.calendarOps.getCalendars();
-  }
-
-  /**
-   * Get events from a calendar
-   */
-  async getCalendarEvents(
-    entityId: string,
-    startDate?: Date,
-    endDate?: Date
-  ): Promise<CalendarEvent[]> {
-    return this.calendarOps.getCalendarEvents(entityId, startDate, endDate);
-  }
-
-  /**
-   * Get events from all calendars
-   */
-  async getAllCalendarEvents(
-    startDate?: Date,
-    endDate?: Date
-  ): Promise<Array<{ calendar: string; events: CalendarEvent[] }>> {
-    return this.calendarOps.getAllCalendarEvents(startDate, endDate);
-  }
-}
-
-// Re-export operation classes for testing
-export { RequestHandler } from './request.js';
-export { StateOperations } from './states.js';
-export { ServiceOperations } from './services.js';
-export { EntityOperations } from './entities.js';
-export { AutomationOperations } from './automations.js';
-export { HistoryOperations } from './history.js';
-export { UpdateOperations } from './updates.js';
-export { ConfigOperations } from './config.js';
-export { DeviceOperations } from './devices.js';
-export { CalendarOperations } from './calendars.js';
-export type { LightControlOptions, ClimateControlOptions, MediaPlayerControlOptions, CoverControlOptions, FanControlOptions } from './devices.js';

package/src/haClient/request.ts

@@ -1,142 +0,0 @@
-/**
- * HTTP Request Handler for Home Assistant API
- * Handles authentication and HTTP requests
- */
-
-import type { Dispatcher } from 'undici';
-import type { RequestOptions } from '../types/index.js';
-import { AuthenticationError, ApiError } from '../types/index.js';
-import { logger } from '../utils/logger.js';
-import { createTlsDispatcher, tlsAwareFetch, type FetchInitWithDispatcher } from '../utils/tlsDispatcher.js';
-
-export interface RequestHandlerConfig {
-  baseUrl: string;
-  token: string;
-  timeout: number;
-  strictSsl: boolean;
-}
-
-/**
- * HTTP request handler for Home Assistant API calls.
- */
-export class RequestHandler {
-  /** Per-client undici dispatcher; set only when strictSsl is disabled (H2). */
-  private dispatcher?: Dispatcher;
-  private baseUrl: string;
-  private token: string;
-  private timeout: number;
-
-  constructor(config: RequestHandlerConfig) {
-    this.baseUrl = config.baseUrl;
-    this.token = config.token;
-    this.timeout = config.timeout;
-
-    // Relax TLS validation for THIS client only, via a per-instance undici
-    // dispatcher. Node's global fetch ignores the legacy `agent` option, so the
-    // previous https.Agent was silently a no-op for self-signed HA instances.
-    // baseUrl is passed so plain-http targets never carry a dispatcher (the
-    // v1.5.5-incident config: http HA + HA_STRICT_SSL=false on a node:26 base).
-    this.dispatcher = createTlsDispatcher(config.strictSsl, config.baseUrl);
-    if (this.dispatcher) {
-      logger.warn('SSL certificate validation is disabled');
-    }
-  }
-
-  /**
-   * Make authenticated request to Home Assistant API
-   */
-  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
-    const url = new URL(`${this.baseUrl}/api${path}`);
-
-    // H4 defense-in-depth: refuse any path that resolves outside /api/.
-    // Call sites encode user-controlled segments, but this guard catches any
-    // raw "../" traversal that would otherwise escape the API namespace.
-    if (url.pathname !== '/api' && !url.pathname.startsWith('/api/')) {
-      throw new ApiError('Invalid API path', 400, { path });
-    }
-
-    // Add query parameters
-    if (options.params) {
-      Object.entries(options.params).forEach(([key, value]) => {
-        url.searchParams.append(key, String(value));
-      });
-    }
-
-    const headers: Record<string, string> = {
-      'Authorization': `Bearer ${this.token}`,
-      'Content-Type': 'application/json',
-      ...options.headers,
-    };
-
-    logger.debug('Making API request', {
-      method: options.method ?? 'GET',
-      path,
-      params: options.params,
-    });
-
-    try {
-      const init: FetchInitWithDispatcher = {
-        method: options.method ?? 'GET',
-        headers,
-        body: options.body ? JSON.stringify(options.body) : undefined,
-        signal: AbortSignal.timeout(this.timeout),
-      };
-      if (this.dispatcher) {
-        init.dispatcher = this.dispatcher;
-      }
-
-      // tlsAwareFetch: dispatcher requests use undici's own fetch (pairing rule).
-      const response = await tlsAwareFetch(url.toString(), init);
-
-      if (!response.ok) {
-        const errorText = await response.text();
-
-        if (response.status === 401) {
-          throw new AuthenticationError(
-            'Invalid Home Assistant token',
-            { status: response.status, body: errorText }
-          );
-        }
-
-        throw new ApiError(
-          `API request failed: ${response.statusText}`,
-          response.status,
-          { path, body: errorText }
-        );
-      }
-
-      // Handle empty responses
-      const contentType = response.headers.get('content-type');
-      if (!contentType?.includes('application/json')) {
-        return {} as T;
-      }
-
-      const data = await response.json();
-      return data as T;
-    } catch (error) {
-      if (error instanceof AuthenticationError || error instanceof ApiError) {
-        throw error;
-      }
-
-      throw new ApiError(
-        `Request failed: ${error instanceof Error ? error.message : String(error)}`,
-        500,
-        { path }
-      );
-    }
-  }
-
-  /**
-   * Make a GET request
-   */
-  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
-    return this.request<T>(path, { params });
-  }
-
-  /**
-   * Make a POST request
-   */
-  async post<T>(path: string, body?: unknown): Promise<T> {
-    return this.request<T>(path, { method: 'POST', body });
-  }
-}

package/src/haClient/services.ts

@@ -1,45 +0,0 @@
-/**
- * Service Operations for Home Assistant API
- * Handles service calls and server management
- */
-
-import type { ServiceCallData, ServiceCallResponse } from '../types/index.js';
-import { logger } from '../utils/logger.js';
-import type { RequestHandler } from './request.js';
-
-/**
- * Service-related operations for the Home Assistant API.
- */
-export class ServiceOperations {
-  constructor(private readonly request: RequestHandler) {}
-
-  /**
-   * Call a service
-   */
-  async callService(data: ServiceCallData): Promise<ServiceCallResponse> {
-    logger.info('Calling service', {
-      domain: data.domain,
-      service: data.service,
-      hasTarget: !!data.target,
-    });
-
-    const path = `/services/${encodeURIComponent(data.domain)}/${encodeURIComponent(data.service)}`;
-    const body = {
-      ...data.service_data,
-      ...data.target,
-    };
-
-    return await this.request.post<ServiceCallResponse>(path, body);
-  }
-
-  /**
-   * Restart Home Assistant
-   */
-  async restartServer(): Promise<void> {
-    logger.warn('Restarting Home Assistant');
-
-    await this.request.post('/services/homeassistant/restart', {});
-
-    logger.info('Home Assistant restart initiated');
-  }
-}

package/src/haClient/states.ts

@@ -1,60 +0,0 @@
-/**
- * State Operations for Home Assistant API
- * Handles entity state retrieval
- */
-
-import type { Entity } from '../types/index.js';
-import { ApiError } from '../types/index.js';
-import { logger } from '../utils/logger.js';
-import type { RequestHandler } from './request.js';
-
-/**
- * State-related operations for the Home Assistant API.
- */
-export class StateOperations {
-  constructor(private readonly request: RequestHandler) {}
-
-  /**
-   * Get all states (entities)
-   */
-  async getStates(): Promise<Entity[]> {
-    logger.debug('Fetching all states');
-    const states = await this.request.get<Entity[]>('/states');
-    logger.info('Fetched states', { count: states.length });
-    return states;
-  }
-
-  /**
-   * Get state of a specific entity
-   */
-  async getState(entityId: string): Promise<Entity | null> {
-    logger.debug('Fetching state', { entityId });
-
-    try {
-      const state = await this.request.get<Entity>(`/states/${encodeURIComponent(entityId)}`);
-      return state;
-    } catch (error) {
-      if (error instanceof ApiError && error.statusCode === 404) {
-        logger.warn('Entity not found', { entityId });
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Get all sensors (sensor.* and binary_sensor.* entities)
-   */
-  async getAllSensors(): Promise<Entity[]> {
-    logger.debug('Fetching all sensors');
-
-    const allStates = await this.getStates();
-    const sensors = allStates.filter(entity =>
-      entity.entity_id.startsWith('sensor.') ||
-      entity.entity_id.startsWith('binary_sensor.')
-    );
-
-    logger.info('Fetched sensors', { count: sensors.length });
-    return sensors;
-  }
-}