@ecobridge.xyz/devicemanager 3.0.2

package/ts/features/feature.sensor.ts

@@ -0,0 +1,202 @@
+/**
+ * Sensor Feature
+ * Provides read-only state for sensors (temperature, humidity, power, etc.)
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TSensorProtocol,
+  TSensorDeviceClass,
+  TSensorStateClass,
+  ISensorCapabilities,
+  ISensorState,
+  ISensorFeatureInfo,
+  ISensorProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a SensorFeature
+ */
+export interface ISensorFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TSensorProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for reading sensor state */
+  protocolClient: ISensorProtocolClient;
+  /** Device class (temperature, humidity, etc.) */
+  deviceClass?: TSensorDeviceClass;
+  /** State class (measurement, total, etc.) */
+  stateClass?: TSensorStateClass;
+  /** Unit of measurement */
+  unit?: string;
+  /** Precision (decimal places) */
+  precision?: number;
+}
+
+/**
+ * Sensor Feature - read-only state values
+ *
+ * Protocol-agnostic: works with Home Assistant, MQTT, SNMP, etc.
+ *
+ * @example
+ * ```typescript
+ * const sensor = device.getFeature<SensorFeature>('sensor');
+ * if (sensor) {
+ *   await sensor.refreshState();
+ *   console.log(`Temperature: ${sensor.value} ${sensor.unit}`);
+ * }
+ * ```
+ */
+export class SensorFeature extends Feature {
+  public readonly type = 'sensor' as const;
+  public readonly protocol: TSensorProtocol;
+
+  /** Entity ID (e.g., "sensor.living_room_temperature") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: ISensorCapabilities;
+
+  /** Current state */
+  protected _value: string | number | boolean = '';
+  protected _numericValue?: number;
+  protected _unit?: string;
+  protected _lastUpdated: Date = new Date();
+
+  /** Protocol client for reading sensor state */
+  private protocolClient: ISensorProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: ISensorFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+    this.capabilities = {
+      deviceClass: options.deviceClass,
+      stateClass: options.stateClass,
+      unit: options.unit,
+      precision: options.precision,
+    };
+    this._unit = options.unit;
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Get current value (cached)
+   */
+  public get value(): string | number | boolean {
+    return this._value;
+  }
+
+  /**
+   * Get numeric value if available (cached)
+   */
+  public get numericValue(): number | undefined {
+    return this._numericValue;
+  }
+
+  /**
+   * Get unit of measurement
+   */
+  public get unit(): string | undefined {
+    return this._unit;
+  }
+
+  /**
+   * Get device class
+   */
+  public get deviceClass(): TSensorDeviceClass | undefined {
+    return this.capabilities.deviceClass;
+  }
+
+  /**
+   * Get state class
+   */
+  public get stateClass(): TSensorStateClass | undefined {
+    return this.capabilities.stateClass;
+  }
+
+  /**
+   * Get last updated timestamp
+   */
+  public get lastUpdated(): Date {
+    return this._lastUpdated;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Fetch initial state
+    try {
+      const state = await this.protocolClient.getState(this.entityId);
+      this.updateStateInternal(state);
+    } catch {
+      // Ignore errors fetching initial state
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Nothing to disconnect
+  }
+
+  // ============================================================================
+  // Sensor Reading
+  // ============================================================================
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<ISensorState> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this.updateStateInternal(state);
+    return state;
+  }
+
+  /**
+   * Update state from external source (e.g., state change event)
+   */
+  public updateState(state: ISensorState): void {
+    this.updateStateInternal(state);
+    this.emit('state:changed', state);
+  }
+
+  /**
+   * Internal state update
+   */
+  private updateStateInternal(state: ISensorState): void {
+    this._value = state.value;
+    this._numericValue = state.numericValue;
+    this._unit = state.unit || this._unit;
+    this._lastUpdated = state.lastUpdated;
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): ISensorFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'sensor',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: {
+        value: this._value,
+        numericValue: this._numericValue,
+        unit: this._unit,
+        lastUpdated: this._lastUpdated,
+      },
+    };
+  }
+}

package/ts/features/feature.snmp.ts

@@ -0,0 +1,235 @@
+/**
+ * SNMP Feature
+ * Provides SNMP query capability for network management
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type {
+  TSnmpVersion,
+  ISnmpVarbind,
+  ISnmpFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+
+/**
+ * Options for creating an SnmpFeature
+ */
+export interface ISnmpFeatureOptions extends IFeatureOptions {
+  version?: TSnmpVersion;
+  community?: string;
+  // SNMPv3 options
+  username?: string;
+  authProtocol?: 'md5' | 'sha';
+  authKey?: string;
+  privProtocol?: 'des' | 'aes';
+  privKey?: string;
+}
+
+/**
+ * SNMP Feature - provides SNMP query capability
+ *
+ * Allows querying devices via SNMP for monitoring and management.
+ * Many network devices (printers, switches, UPS) support SNMP.
+ *
+ * @example
+ * ```typescript
+ * const snmp = device.getFeature<SnmpFeature>('snmp');
+ * if (snmp) {
+ *   const sysDescr = await snmp.get('1.3.6.1.2.1.1.1.0');
+ *   console.log(`System: ${sysDescr.value}`);
+ *
+ *   const interfaces = await snmp.walk('1.3.6.1.2.1.2.2.1');
+ *   console.log(`Found ${interfaces.length} interface entries`);
+ * }
+ * ```
+ */
+export class SnmpFeature extends Feature {
+  public readonly type = 'snmp' as const;
+  public readonly protocol = 'snmp';
+
+  // Configuration
+  public readonly version: TSnmpVersion;
+  public readonly community: string;
+
+  // System info (populated after connect)
+  public sysDescr?: string;
+  public sysObjectId?: string;
+  public sysName?: string;
+  public sysLocation?: string;
+  public sysContact?: string;
+  public sysUpTime?: number;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options?: ISnmpFeatureOptions
+  ) {
+    super(device, port ?? 161, options);
+    this.version = options?.version ?? 'v2c';
+    this.community = options?.community ?? 'public';
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Test connection by getting system description
+    try {
+      const result = await this.get('1.3.6.1.2.1.1.1.0'); // sysDescr
+      if (result) {
+        this.sysDescr = String(result.value);
+      }
+    } catch {
+      // Connection test failed
+      throw new Error('SNMP connection failed');
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // SNMP is connectionless, nothing to disconnect
+  }
+
+  // ============================================================================
+  // SNMP Operations
+  // ============================================================================
+
+  /**
+   * Get a single OID value
+   */
+  public async get(oid: string): Promise<ISnmpVarbind> {
+    // This would use the SNMP library to perform the query
+    // Placeholder implementation
+    return {
+      oid,
+      type: 0,
+      value: null,
+    };
+  }
+
+  /**
+   * Get multiple OID values
+   */
+  public async getMultiple(oids: string[]): Promise<ISnmpVarbind[]> {
+    const results: ISnmpVarbind[] = [];
+    for (const oid of oids) {
+      results.push(await this.get(oid));
+    }
+    return results;
+  }
+
+  /**
+   * Get next OID in MIB tree
+   */
+  public async getNext(oid: string): Promise<ISnmpVarbind> {
+    // Placeholder
+    return {
+      oid,
+      type: 0,
+      value: null,
+    };
+  }
+
+  /**
+   * Walk a subtree of the MIB
+   */
+  public async walk(baseOid: string): Promise<ISnmpVarbind[]> {
+    const results: ISnmpVarbind[] = [];
+    // This would iterate through the MIB tree using getNext
+    return results;
+  }
+
+  /**
+   * Bulk get (SNMPv2c/v3)
+   */
+  public async getBulk(
+    oids: string[],
+    nonRepeaters: number = 0,
+    maxRepetitions: number = 10
+  ): Promise<ISnmpVarbind[]> {
+    if (this.version === 'v1') {
+      throw new Error('getBulk not supported in SNMPv1');
+    }
+    // Placeholder
+    return [];
+  }
+
+  /**
+   * Set an OID value
+   */
+  public async set(oid: string, type: number, value: unknown): Promise<ISnmpVarbind> {
+    // Placeholder
+    return {
+      oid,
+      type,
+      value,
+    };
+  }
+
+  // ============================================================================
+  // System Info
+  // ============================================================================
+
+  /**
+   * Get all system info OIDs
+   */
+  public async getSystemInfo(): Promise<{
+    sysDescr?: string;
+    sysObjectId?: string;
+    sysName?: string;
+    sysLocation?: string;
+    sysContact?: string;
+    sysUpTime?: number;
+  }> {
+    const oids = [
+      '1.3.6.1.2.1.1.1.0',  // sysDescr
+      '1.3.6.1.2.1.1.2.0',  // sysObjectID
+      '1.3.6.1.2.1.1.3.0',  // sysUpTime
+      '1.3.6.1.2.1.1.4.0',  // sysContact
+      '1.3.6.1.2.1.1.5.0',  // sysName
+      '1.3.6.1.2.1.1.6.0',  // sysLocation
+    ];
+
+    const results = await this.getMultiple(oids);
+
+    return {
+      sysDescr: results[0]?.value as string,
+      sysObjectId: results[1]?.value as string,
+      sysUpTime: results[2]?.value as number,
+      sysContact: results[3]?.value as string,
+      sysName: results[4]?.value as string,
+      sysLocation: results[5]?.value as string,
+    };
+  }
+
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
+  public getFeatureInfo(): ISnmpFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'snmp',
+      version: this.version,
+      community: this.version !== 'v3' ? this.community : undefined,
+      sysDescr: this.sysDescr,
+      sysName: this.sysName,
+      sysLocation: this.sysLocation,
+    };
+  }
+
+  // ============================================================================
+  // Static Factory
+  // ============================================================================
+
+  public static fromDiscovery(
+    device: TDeviceReference,
+    port: number,
+    metadata: Record<string, unknown>
+  ): SnmpFeature {
+    return new SnmpFeature(device, port ?? 161, {
+      version: metadata.version as TSnmpVersion ?? 'v2c',
+      community: metadata.community as string ?? 'public',
+    });
+  }
+}

package/ts/features/feature.switch.ts

@@ -0,0 +1,170 @@
+/**
+ * Switch Feature
+ * Provides binary on/off control for smart switches, outlets, etc.
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TSwitchProtocol,
+  ISwitchCapabilities,
+  ISwitchState,
+  ISwitchFeatureInfo,
+  ISwitchProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a SwitchFeature
+ */
+export interface ISwitchFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TSwitchProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for controlling the switch */
+  protocolClient: ISwitchProtocolClient;
+  /** Device class */
+  deviceClass?: 'outlet' | 'switch';
+}
+
+/**
+ * Switch Feature - binary on/off control
+ *
+ * Protocol-agnostic: works with Home Assistant, MQTT, Tasmota, Tuya, etc.
+ *
+ * @example
+ * ```typescript
+ * const sw = device.getFeature<SwitchFeature>('switch');
+ * if (sw) {
+ *   await sw.turnOn();
+ *   await sw.toggle();
+ *   console.log(`Switch is ${sw.isOn ? 'on' : 'off'}`);
+ * }
+ * ```
+ */
+export class SwitchFeature extends Feature {
+  public readonly type = 'switch' as const;
+  public readonly protocol: TSwitchProtocol;
+
+  /** Entity ID (e.g., "switch.living_room") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: ISwitchCapabilities;
+
+  /** Current state */
+  protected _isOn: boolean = false;
+
+  /** Protocol client for controlling the switch */
+  private protocolClient: ISwitchProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: ISwitchFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+    this.capabilities = {
+      deviceClass: options.deviceClass,
+    };
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Get current on/off state (cached)
+   */
+  public get isOn(): boolean {
+    return this._isOn;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Fetch initial state
+    try {
+      const state = await this.protocolClient.getState(this.entityId);
+      this._isOn = state.isOn;
+    } catch {
+      // Ignore errors fetching initial state
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Nothing to disconnect
+  }
+
+  // ============================================================================
+  // Switch Control
+  // ============================================================================
+
+  /**
+   * Turn on the switch
+   */
+  public async turnOn(): Promise<void> {
+    await this.protocolClient.turnOn(this.entityId);
+    this._isOn = true;
+    this.emit('state:changed', { isOn: true });
+  }
+
+  /**
+   * Turn off the switch
+   */
+  public async turnOff(): Promise<void> {
+    await this.protocolClient.turnOff(this.entityId);
+    this._isOn = false;
+    this.emit('state:changed', { isOn: false });
+  }
+
+  /**
+   * Toggle the switch
+   */
+  public async toggle(): Promise<void> {
+    await this.protocolClient.toggle(this.entityId);
+    this._isOn = !this._isOn;
+    this.emit('state:changed', { isOn: this._isOn });
+  }
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<ISwitchState> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this._isOn = state.isOn;
+    return state;
+  }
+
+  /**
+   * Update state from external source (e.g., state change event)
+   */
+  public updateState(state: ISwitchState): void {
+    const changed = this._isOn !== state.isOn;
+    this._isOn = state.isOn;
+    if (changed) {
+      this.emit('state:changed', state);
+    }
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): ISwitchFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'switch',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: {
+        isOn: this._isOn,
+      },
+    };
+  }
+}