@ecobridge.xyz/devicemanager 3.0.2

package/ts/discovery/discovery.classes.homeassistant.ts

@@ -0,0 +1,376 @@
+import * as plugins from '../plugins.js';
+import type {
+  IHomeAssistantInstanceConfig,
+  IHomeAssistantEntity,
+  IHomeAssistantDiscoveredInstance,
+  THomeAssistantDomain,
+  THomeAssistantDiscoveryEvents,
+} from '../interfaces/homeassistant.interfaces.js';
+import { HomeAssistantProtocol } from '../protocols/protocol.homeassistant.js';
+
+/**
+ * mDNS service type for Home Assistant discovery
+ */
+const HA_SERVICE_TYPE = '_home-assistant._tcp';
+
+/**
+ * Default domains to discover
+ */
+const DEFAULT_DOMAINS: THomeAssistantDomain[] = [
+  'light',
+  'switch',
+  'sensor',
+  'binary_sensor',
+  'climate',
+  'fan',
+  'cover',
+  'lock',
+  'camera',
+  'media_player',
+];
+
+/**
+ * Home Assistant Discovery
+ * Discovers HA instances via mDNS and/or manual configuration,
+ * connects to them, and enumerates all entities
+ */
+export class HomeAssistantDiscovery extends plugins.events.EventEmitter {
+  private bonjour: plugins.bonjourService.Bonjour | null = null;
+  private browser: plugins.bonjourService.Browser | null = null;
+  private discoveredInstances: Map<string, IHomeAssistantDiscoveredInstance> = new Map();
+  private connectedProtocols: Map<string, HomeAssistantProtocol> = new Map();
+  private entityCache: Map<string, IHomeAssistantEntity> = new Map();
+  private enabledDomains: THomeAssistantDomain[];
+  private isRunning: boolean = false;
+
+  constructor(options?: { enabledDomains?: THomeAssistantDomain[] }) {
+    super();
+    this.enabledDomains = options?.enabledDomains || DEFAULT_DOMAINS;
+  }
+
+  /**
+   * Check if discovery is running
+   */
+  public get running(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get all discovered HA instances
+   */
+  public getInstances(): IHomeAssistantDiscoveredInstance[] {
+    return Array.from(this.discoveredInstances.values());
+  }
+
+  /**
+   * Get connected protocol for an instance
+   */
+  public getProtocol(instanceId: string): HomeAssistantProtocol | undefined {
+    return this.connectedProtocols.get(instanceId);
+  }
+
+  /**
+   * Get all connected protocols
+   */
+  public getProtocols(): Map<string, HomeAssistantProtocol> {
+    return this.connectedProtocols;
+  }
+
+  /**
+   * Get all cached entities
+   */
+  public getEntities(): IHomeAssistantEntity[] {
+    return Array.from(this.entityCache.values());
+  }
+
+  /**
+   * Get entities by domain
+   */
+  public getEntitiesByDomain(domain: THomeAssistantDomain): IHomeAssistantEntity[] {
+    return this.getEntities().filter((e) => e.entity_id.startsWith(`${domain}.`));
+  }
+
+  /**
+   * Get entities for a specific instance
+   */
+  public getEntitiesForInstance(instanceId: string): IHomeAssistantEntity[] {
+    const protocol = this.connectedProtocols.get(instanceId);
+    if (!protocol) return [];
+    return Array.from(protocol.entities.values());
+  }
+
+  /**
+   * Start mDNS discovery for Home Assistant instances
+   */
+  public async startMdnsDiscovery(): Promise<void> {
+    if (this.isRunning) {
+      return;
+    }
+
+    this.bonjour = new plugins.bonjourService.Bonjour();
+    this.isRunning = true;
+
+    this.browser = this.bonjour.find({ type: HA_SERVICE_TYPE }, (service) => {
+      this.handleInstanceFound(service);
+    });
+
+    this.browser.on('down', (service) => {
+      this.handleInstanceLost(service);
+    });
+  }
+
+  /**
+   * Stop mDNS discovery
+   */
+  public async stopMdnsDiscovery(): Promise<void> {
+    if (!this.isRunning) {
+      return;
+    }
+
+    if (this.browser) {
+      this.browser.stop();
+      this.browser = null;
+    }
+
+    if (this.bonjour) {
+      this.bonjour.destroy();
+      this.bonjour = null;
+    }
+
+    this.isRunning = false;
+  }
+
+  /**
+   * Add a manually configured HA instance
+   */
+  public async addInstance(config: IHomeAssistantInstanceConfig): Promise<HomeAssistantProtocol> {
+    const instanceId = this.generateInstanceId(config.host, config.port || 8123);
+
+    // Check if already connected
+    if (this.connectedProtocols.has(instanceId)) {
+      return this.connectedProtocols.get(instanceId)!;
+    }
+
+    // Create protocol and connect
+    const protocol = new HomeAssistantProtocol(config);
+
+    // Set up event handlers
+    this.setupProtocolHandlers(protocol, instanceId);
+
+    // Connect
+    await protocol.connect();
+
+    // Subscribe to state changes
+    await protocol.subscribeToStateChanges();
+
+    // Cache entities
+    const entities = await protocol.getStates();
+    for (const entity of entities) {
+      if (this.isEnabledDomain(entity.entity_id)) {
+        const cacheKey = `${instanceId}:${entity.entity_id}`;
+        this.entityCache.set(cacheKey, entity);
+        this.emit('entity:found', entity);
+      }
+    }
+
+    // Store protocol
+    this.connectedProtocols.set(instanceId, protocol);
+
+    // Also store as discovered instance
+    this.discoveredInstances.set(instanceId, {
+      id: instanceId,
+      host: config.host,
+      port: config.port || 8123,
+      base_url: `http://${config.host}:${config.port || 8123}`,
+      txtRecords: {},
+      requires_api_password: true,
+      friendlyName: config.friendlyName,
+    });
+
+    return protocol;
+  }
+
+  /**
+   * Remove an HA instance
+   */
+  public async removeInstance(instanceId: string): Promise<void> {
+    const protocol = this.connectedProtocols.get(instanceId);
+    if (protocol) {
+      await protocol.disconnect();
+      this.connectedProtocols.delete(instanceId);
+    }
+
+    this.discoveredInstances.delete(instanceId);
+
+    // Remove cached entities for this instance
+    for (const key of this.entityCache.keys()) {
+      if (key.startsWith(`${instanceId}:`)) {
+        this.entityCache.delete(key);
+      }
+    }
+
+    this.emit('instance:lost', instanceId);
+  }
+
+  /**
+   * Stop all and cleanup
+   */
+  public async stop(): Promise<void> {
+    await this.stopMdnsDiscovery();
+
+    // Disconnect all protocols
+    for (const [instanceId, protocol] of this.connectedProtocols) {
+      await protocol.disconnect();
+    }
+    this.connectedProtocols.clear();
+    this.discoveredInstances.clear();
+    this.entityCache.clear();
+  }
+
+  /**
+   * Handle mDNS service found
+   */
+  private handleInstanceFound(service: plugins.bonjourService.Service): void {
+    const addresses = service.addresses ?? [];
+    const address = addresses.find((a) => !a.includes(':')) ?? addresses[0] ?? service.host;
+
+    if (!address) {
+      return;
+    }
+
+    const instanceId = this.generateInstanceId(address, service.port);
+    const txtRecords = this.parseTxtRecords(service.txt);
+
+    const instance: IHomeAssistantDiscoveredInstance = {
+      id: instanceId,
+      host: address,
+      port: service.port,
+      base_url: txtRecords['base_url'] || `http://${address}:${service.port}`,
+      txtRecords,
+      requires_api_password: txtRecords['requires_api_password'] === 'true',
+      friendlyName: service.name,
+    };
+
+    // Check if this is a new instance
+    const existing = this.discoveredInstances.get(instanceId);
+    if (!existing) {
+      this.discoveredInstances.set(instanceId, instance);
+      this.emit('instance:found', instance);
+    }
+  }
+
+  /**
+   * Handle mDNS service lost
+   */
+  private handleInstanceLost(service: plugins.bonjourService.Service): void {
+    const addresses = service.addresses ?? [];
+    const address = addresses.find((a) => !a.includes(':')) ?? addresses[0] ?? service.host;
+
+    if (!address) {
+      return;
+    }
+
+    const instanceId = this.generateInstanceId(address, service.port);
+
+    if (this.discoveredInstances.has(instanceId)) {
+      // Don't remove if we have an active connection (manually added)
+      if (!this.connectedProtocols.has(instanceId)) {
+        this.discoveredInstances.delete(instanceId);
+      }
+      this.emit('instance:lost', instanceId);
+    }
+  }
+
+  /**
+   * Set up event handlers for a protocol
+   */
+  private setupProtocolHandlers(protocol: HomeAssistantProtocol, instanceId: string): void {
+    protocol.on('state:changed', (event) => {
+      const cacheKey = `${instanceId}:${event.entity_id}`;
+
+      if (event.new_state) {
+        if (this.isEnabledDomain(event.entity_id)) {
+          const existing = this.entityCache.has(cacheKey);
+          this.entityCache.set(cacheKey, event.new_state);
+
+          if (existing) {
+            this.emit('entity:updated', event.new_state);
+          } else {
+            this.emit('entity:found', event.new_state);
+          }
+        }
+      } else {
+        // Entity removed
+        if (this.entityCache.has(cacheKey)) {
+          this.entityCache.delete(cacheKey);
+          this.emit('entity:removed', event.entity_id);
+        }
+      }
+    });
+
+    protocol.on('disconnected', () => {
+      // Clear cached entities for this instance on disconnect
+      for (const key of this.entityCache.keys()) {
+        if (key.startsWith(`${instanceId}:`)) {
+          this.entityCache.delete(key);
+        }
+      }
+    });
+
+    protocol.on('error', (error) => {
+      this.emit('error', error);
+    });
+  }
+
+  /**
+   * Check if entity domain is enabled
+   */
+  private isEnabledDomain(entityId: string): boolean {
+    const domain = entityId.split('.')[0] as THomeAssistantDomain;
+    return this.enabledDomains.includes(domain);
+  }
+
+  /**
+   * Generate unique instance ID
+   */
+  private generateInstanceId(host: string, port: number): string {
+    return `ha:${host}:${port}`;
+  }
+
+  /**
+   * Parse TXT records from mDNS service
+   */
+  private parseTxtRecords(txt: Record<string, unknown> | undefined): Record<string, string> {
+    const records: Record<string, string> = {};
+
+    if (!txt) {
+      return records;
+    }
+
+    for (const [key, value] of Object.entries(txt)) {
+      if (typeof value === 'string') {
+        records[key] = value;
+      } else if (Buffer.isBuffer(value)) {
+        records[key] = value.toString('utf-8');
+      } else if (value !== undefined && value !== null) {
+        records[key] = String(value);
+      }
+    }
+
+    return records;
+  }
+
+  /**
+   * Probe if a host has Home Assistant running
+   */
+  public static async probe(
+    host: string,
+    port: number = 8123,
+    secure: boolean = false,
+    timeout: number = 5000
+  ): Promise<boolean> {
+    return HomeAssistantProtocol.probe(host, port, secure, timeout);
+  }
+}
+
+export { HA_SERVICE_TYPE };

package/ts/discovery/discovery.classes.mdns.ts

@@ -0,0 +1,347 @@
+import * as plugins from '../plugins.js';
+import type {
+  IDiscoveredDevice,
+  IDiscoveryOptions,
+  TDeviceType,
+  TScannerProtocol,
+} from '../interfaces/index.js';
+
+/**
+ * Service type definitions for mDNS discovery
+ */
+const SERVICE_TYPES = {
+  // Scanners
+  ESCL: '_uscan._tcp',           // eSCL/AirScan scanners
+  ESCL_SECURE: '_uscans._tcp',   // eSCL over TLS
+  SANE: '_scanner._tcp',         // SANE network scanners
+
+  // Printers
+  IPP: '_ipp._tcp',              // IPP printers
+  IPPS: '_ipps._tcp',            // IPP over TLS
+  PDL: '_pdl-datastream._tcp',   // Raw/JetDirect printers
+
+  // Speakers / Audio
+  AIRPLAY: '_airplay._tcp',      // AirPlay devices (Apple TV, HomePod, etc.)
+  RAOP: '_raop._tcp',            // Remote Audio Output Protocol (AirPlay audio)
+  SONOS: '_sonos._tcp',          // Sonos speakers
+  GOOGLECAST: '_googlecast._tcp', // Chromecast / Google Cast devices
+  SPOTIFY: '_spotify-connect._tcp', // Spotify Connect devices
+} as const;
+
+/**
+ * Default discovery options
+ */
+const DEFAULT_OPTIONS: Required<IDiscoveryOptions> = {
+  serviceTypes: [
+    // Scanners
+    SERVICE_TYPES.ESCL,
+    SERVICE_TYPES.ESCL_SECURE,
+    SERVICE_TYPES.SANE,
+    // Printers
+    SERVICE_TYPES.IPP,
+    SERVICE_TYPES.IPPS,
+    // Speakers
+    SERVICE_TYPES.AIRPLAY,
+    SERVICE_TYPES.RAOP,
+    SERVICE_TYPES.SONOS,
+    SERVICE_TYPES.GOOGLECAST,
+  ],
+  timeout: 10000,
+};
+
+/**
+ * mDNS/Bonjour discovery service for network devices
+ */
+export class MdnsDiscovery extends plugins.events.EventEmitter {
+  private bonjour: plugins.bonjourService.Bonjour | null = null;
+  private browsers: plugins.bonjourService.Browser[] = [];
+  private discoveredDevices: Map<string, IDiscoveredDevice> = new Map();
+  private options: Required<IDiscoveryOptions>;
+  private isRunning: boolean = false;
+
+  constructor(options?: IDiscoveryOptions) {
+    super();
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Check if discovery is currently running
+   */
+  public get running(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get all discovered devices
+   */
+  public getDevices(): IDiscoveredDevice[] {
+    return Array.from(this.discoveredDevices.values());
+  }
+
+  /**
+   * Get discovered scanners only
+   */
+  public getScanners(): IDiscoveredDevice[] {
+    return this.getDevices().filter((d) => d.type === 'scanner');
+  }
+
+  /**
+   * Get discovered printers only
+   */
+  public getPrinters(): IDiscoveredDevice[] {
+    return this.getDevices().filter((d) => d.type === 'printer');
+  }
+
+  /**
+   * Start mDNS discovery
+   */
+  public async start(): Promise<void> {
+    if (this.isRunning) {
+      return;
+    }
+
+    this.bonjour = new plugins.bonjourService.Bonjour();
+    this.isRunning = true;
+    this.emit('started');
+
+    for (const serviceType of this.options.serviceTypes) {
+      this.browseService(serviceType);
+    }
+  }
+
+  /**
+   * Stop mDNS discovery
+   */
+  public async stop(): Promise<void> {
+    if (!this.isRunning) {
+      return;
+    }
+
+    // Stop all browsers
+    for (const browser of this.browsers) {
+      browser.stop();
+    }
+    this.browsers = [];
+
+    // Destroy bonjour instance
+    if (this.bonjour) {
+      this.bonjour.destroy();
+      this.bonjour = null;
+    }
+
+    this.isRunning = false;
+    this.emit('stopped');
+  }
+
+  /**
+   * Clear discovered devices
+   */
+  public clear(): void {
+    this.discoveredDevices.clear();
+  }
+
+  /**
+   * Browse for a specific service type
+   */
+  private browseService(serviceType: string): void {
+    if (!this.bonjour) {
+      return;
+    }
+
+    const browser = this.bonjour.find({ type: serviceType }, (service) => {
+      this.handleServiceFound(service, serviceType);
+    });
+
+    browser.on('down', (service) => {
+      this.handleServiceLost(service, serviceType);
+    });
+
+    this.browsers.push(browser);
+  }
+
+  /**
+   * Handle discovered service
+   */
+  private handleServiceFound(
+    service: plugins.bonjourService.Service,
+    serviceType: string
+  ): void {
+    const device = this.parseService(service, serviceType);
+    if (!device) {
+      return;
+    }
+
+    const existingDevice = this.discoveredDevices.get(device.id);
+    if (existingDevice) {
+      // Update existing device
+      this.discoveredDevices.set(device.id, device);
+      this.emit('device:updated', device);
+    } else {
+      // New device found
+      this.discoveredDevices.set(device.id, device);
+      this.emit('device:found', device);
+
+      if (device.type === 'scanner') {
+        this.emit('scanner:found', device);
+      } else if (device.type === 'printer') {
+        this.emit('printer:found', device);
+      }
+    }
+  }
+
+  /**
+   * Handle lost service
+   */
+  private handleServiceLost(
+    service: plugins.bonjourService.Service,
+    serviceType: string
+  ): void {
+    const deviceId = this.generateDeviceId(service, serviceType);
+    const device = this.discoveredDevices.get(deviceId);
+
+    if (device) {
+      this.discoveredDevices.delete(deviceId);
+      this.emit('device:lost', device);
+
+      if (device.type === 'scanner') {
+        this.emit('scanner:lost', deviceId);
+      } else if (device.type === 'printer') {
+        this.emit('printer:lost', deviceId);
+      }
+    }
+  }
+
+  /**
+   * Parse Bonjour service into device info
+   */
+  private parseService(
+    service: plugins.bonjourService.Service,
+    serviceType: string
+  ): IDiscoveredDevice | null {
+    const addresses = service.addresses ?? [];
+    // Prefer IPv4 address
+    const address =
+      addresses.find((a) => !a.includes(':')) ?? addresses[0] ?? service.host;
+
+    if (!address) {
+      return null;
+    }
+
+    const txtRecords = this.parseTxtRecords(service.txt);
+    const deviceType = this.getDeviceType(serviceType);
+    const protocol = this.getProtocol(serviceType);
+
+    const deviceId = this.generateDeviceId(service, serviceType);
+
+    return {
+      id: deviceId,
+      name: service.name || txtRecords['ty'] || txtRecords['product'] || 'Unknown Device',
+      type: deviceType,
+      protocol: protocol,
+      address: address,
+      port: service.port,
+      txtRecords: txtRecords,
+      serviceType: serviceType,
+    };
+  }
+
+  /**
+   * Generate unique device ID
+   */
+  private generateDeviceId(
+    service: plugins.bonjourService.Service,
+    serviceType: string
+  ): string {
+    const addresses = service.addresses ?? [];
+    const address = addresses.find((a) => !a.includes(':')) ?? addresses[0] ?? service.host;
+    return `${serviceType}:${address}:${service.port}`;
+  }
+
+  /**
+   * Parse TXT records from service
+   */
+  private parseTxtRecords(
+    txt: Record<string, unknown> | undefined
+  ): Record<string, string> {
+    const records: Record<string, string> = {};
+
+    if (!txt) {
+      return records;
+    }
+
+    for (const [key, value] of Object.entries(txt)) {
+      if (typeof value === 'string') {
+        records[key] = value;
+      } else if (Buffer.isBuffer(value)) {
+        records[key] = value.toString('utf-8');
+      } else if (value !== undefined && value !== null) {
+        records[key] = String(value);
+      }
+    }
+
+    return records;
+  }
+
+  /**
+   * Determine device type from service type
+   */
+  private getDeviceType(serviceType: string): TDeviceType {
+    switch (serviceType) {
+      case SERVICE_TYPES.ESCL:
+      case SERVICE_TYPES.ESCL_SECURE:
+      case SERVICE_TYPES.SANE:
+        return 'scanner';
+      case SERVICE_TYPES.IPP:
+      case SERVICE_TYPES.IPPS:
+      case SERVICE_TYPES.PDL:
+        return 'printer';
+      case SERVICE_TYPES.AIRPLAY:
+      case SERVICE_TYPES.RAOP:
+      case SERVICE_TYPES.SONOS:
+      case SERVICE_TYPES.GOOGLECAST:
+      case SERVICE_TYPES.SPOTIFY:
+        return 'speaker';
+      default:
+        // Check if it's a scanner or printer based on service type pattern
+        if (serviceType.includes('scan') || serviceType.includes('scanner')) {
+          return 'scanner';
+        }
+        if (serviceType.includes('airplay') || serviceType.includes('raop') ||
+            serviceType.includes('sonos') || serviceType.includes('cast') ||
+            serviceType.includes('spotify')) {
+          return 'speaker';
+        }
+        return 'printer';
+    }
+  }
+
+  /**
+   * Determine protocol from service type
+   */
+  private getProtocol(serviceType: string): string {
+    switch (serviceType) {
+      case SERVICE_TYPES.ESCL:
+      case SERVICE_TYPES.ESCL_SECURE:
+        return 'escl';
+      case SERVICE_TYPES.SANE:
+        return 'sane';
+      case SERVICE_TYPES.IPP:
+      case SERVICE_TYPES.IPPS:
+      case SERVICE_TYPES.PDL:
+        return 'ipp';
+      case SERVICE_TYPES.AIRPLAY:
+      case SERVICE_TYPES.RAOP:
+        return 'airplay';
+      case SERVICE_TYPES.SONOS:
+        return 'sonos';
+      case SERVICE_TYPES.GOOGLECAST:
+        return 'chromecast';
+      case SERVICE_TYPES.SPOTIFY:
+        return 'spotify';
+      default:
+        return 'unknown';
+    }
+  }
+}
+
+export { SERVICE_TYPES };