@ecobridge.xyz/devicemanager 3.0.2

package/ts/features/feature.lock.ts

@@ -0,0 +1,223 @@
+/**
+ * Lock Feature
+ * Provides control for smart locks
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TLockProtocol,
+  TLockState,
+  ILockCapabilities,
+  ILockStateInfo,
+  ILockFeatureInfo,
+  ILockProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a LockFeature
+ */
+export interface ILockFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TLockProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for controlling the lock */
+  protocolClient: ILockProtocolClient;
+  /** Whether the lock supports physical open */
+  supportsOpen?: boolean;
+}
+
+/**
+ * Lock Feature - control for smart locks
+ *
+ * Protocol-agnostic: works with Home Assistant, MQTT, August, Yale, etc.
+ *
+ * @example
+ * ```typescript
+ * const lock = device.getFeature<LockFeature>('lock');
+ * if (lock) {
+ *   await lock.lock();
+ *   console.log(`Lock is ${lock.isLocked ? 'locked' : 'unlocked'}`);
+ * }
+ * ```
+ */
+export class LockFeature extends Feature {
+  public readonly type = 'lock' as const;
+  public readonly protocol: TLockProtocol;
+
+  /** Entity ID (e.g., "lock.front_door") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: ILockCapabilities;
+
+  /** Current state */
+  protected _lockState: TLockState = 'unknown';
+  protected _isLocked: boolean = false;
+
+  /** Protocol client for controlling the lock */
+  private protocolClient: ILockProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: ILockFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+
+    this.capabilities = {
+      supportsOpen: options.supportsOpen ?? false,
+    };
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Get current lock state (cached)
+   */
+  public get lockState(): TLockState {
+    return this._lockState;
+  }
+
+  /**
+   * Check if locked (cached)
+   */
+  public get isLocked(): boolean {
+    return this._isLocked;
+  }
+
+  /**
+   * Check if unlocked
+   */
+  public get isUnlocked(): boolean {
+    return this._lockState === 'unlocked';
+  }
+
+  /**
+   * Check if currently locking
+   */
+  public get isLocking(): boolean {
+    return this._lockState === 'locking';
+  }
+
+  /**
+   * Check if currently unlocking
+   */
+  public get isUnlocking(): boolean {
+    return this._lockState === 'unlocking';
+  }
+
+  /**
+   * Check if jammed
+   */
+  public get isJammed(): boolean {
+    return this._lockState === 'jammed';
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    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
+  }
+
+  // ============================================================================
+  // Lock Control
+  // ============================================================================
+
+  /**
+   * Lock the lock
+   */
+  public async lock(): Promise<void> {
+    await this.protocolClient.lock(this.entityId);
+    this._lockState = 'locking';
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Unlock the lock
+   */
+  public async unlock(): Promise<void> {
+    await this.protocolClient.unlock(this.entityId);
+    this._lockState = 'unlocking';
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Open the lock (physically open the door if supported)
+   */
+  public async open(): Promise<void> {
+    if (!this.capabilities.supportsOpen) {
+      throw new Error('Lock does not support physical open');
+    }
+    await this.protocolClient.open(this.entityId);
+    this._lockState = 'unlocked';
+    this._isLocked = false;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Get current state as object
+   */
+  public getState(): ILockStateInfo {
+    return {
+      state: this._lockState,
+      isLocked: this._isLocked,
+    };
+  }
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<ILockStateInfo> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this.updateStateInternal(state);
+    return state;
+  }
+
+  /**
+   * Update state from external source
+   */
+  public updateState(state: ILockStateInfo): void {
+    this.updateStateInternal(state);
+    this.emit('state:changed', state);
+  }
+
+  /**
+   * Internal state update
+   */
+  private updateStateInternal(state: ILockStateInfo): void {
+    this._lockState = state.state;
+    this._isLocked = state.isLocked;
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): ILockFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'lock',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: this.getState(),
+    };
+  }
+}

package/ts/features/feature.playback.ts

@@ -0,0 +1,246 @@
+/**
+ * Playback Feature
+ * Provides media playback control capability
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type {
+  TPlaybackProtocol,
+  TPlaybackState,
+  ITrackInfo,
+  IPlaybackStatus,
+  IPlaybackFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+
+/**
+ * Options for creating a PlaybackFeature
+ */
+export interface IPlaybackFeatureOptions extends IFeatureOptions {
+  protocol: TPlaybackProtocol;
+  supportsQueue?: boolean;
+  supportsSeek?: boolean;
+  /** Protocol-specific client instance (Sonos, AirPlay, etc.) */
+  protocolClient?: unknown;
+}
+
+/**
+ * Playback Feature - provides media playback control
+ *
+ * Abstract feature that can be backed by different protocols (Sonos, AirPlay, Chromecast, DLNA).
+ * Concrete implementations should extend this class for protocol-specific behavior.
+ *
+ * @example
+ * ```typescript
+ * const playback = device.getFeature<PlaybackFeature>('playback');
+ * if (playback) {
+ *   await playback.play('spotify:track:123');
+ *   const status = await playback.getPlaybackStatus();
+ *   console.log(`Playing: ${status.track?.title}`);
+ * }
+ * ```
+ */
+export class PlaybackFeature extends Feature {
+  public readonly type = 'playback' as const;
+  public readonly protocol: TPlaybackProtocol;
+
+  // Capabilities
+  public supportsQueue: boolean = true;
+  public supportsSeek: boolean = true;
+
+  // Current state
+  protected _playbackState: TPlaybackState = 'stopped';
+  protected _currentTrack: ITrackInfo | null = null;
+  protected _position: number = 0;
+  protected _duration: number = 0;
+
+  // Protocol client (set by subclass or passed in options)
+  protected protocolClient: unknown = null;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: IPlaybackFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    if (options.supportsQueue !== undefined) this.supportsQueue = options.supportsQueue;
+    if (options.supportsSeek !== undefined) this.supportsSeek = options.supportsSeek;
+    if (options.protocolClient) this.protocolClient = options.protocolClient;
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  public get playbackState(): TPlaybackState {
+    return this._playbackState;
+  }
+
+  public get currentTrack(): ITrackInfo | null {
+    return this._currentTrack;
+  }
+
+  public get position(): number {
+    return this._position;
+  }
+
+  public get duration(): number {
+    return this._duration;
+  }
+
+  public get isPlaying(): boolean {
+    return this._playbackState === 'playing';
+  }
+
+  // ============================================================================
+  // Connection (to be overridden by protocol-specific subclasses)
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Base implementation - protocol-specific subclasses should override
+    // and establish their protocol connection
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Base implementation - protocol-specific subclasses should override
+    this.protocolClient = null;
+  }
+
+  // ============================================================================
+  // Playback Control
+  // ============================================================================
+
+  /**
+   * Start playback
+   * @param uri Optional URI to play. If not provided, resumes current playback.
+   */
+  public async play(uri?: string): Promise<void> {
+    this.emit('playback:play', { uri });
+    // Protocol-specific implementation should be provided by subclass
+    this._playbackState = 'playing';
+    this.emit('playback:state:changed', this._playbackState);
+  }
+
+  /**
+   * Pause playback
+   */
+  public async pause(): Promise<void> {
+    this.emit('playback:pause');
+    this._playbackState = 'paused';
+    this.emit('playback:state:changed', this._playbackState);
+  }
+
+  /**
+   * Stop playback
+   */
+  public async stop(): Promise<void> {
+    this.emit('playback:stop');
+    this._playbackState = 'stopped';
+    this._position = 0;
+    this.emit('playback:state:changed', this._playbackState);
+  }
+
+  /**
+   * Skip to next track
+   */
+  public async next(): Promise<void> {
+    this.emit('playback:next');
+  }
+
+  /**
+   * Go to previous track
+   */
+  public async previous(): Promise<void> {
+    this.emit('playback:previous');
+  }
+
+  /**
+   * Seek to position
+   * @param seconds Position in seconds
+   */
+  public async seek(seconds: number): Promise<void> {
+    if (!this.supportsSeek) {
+      throw new Error('Seek not supported');
+    }
+    this._position = seconds;
+    this.emit('playback:seek', seconds);
+  }
+
+  // ============================================================================
+  // Status
+  // ============================================================================
+
+  /**
+   * Get current track info
+   */
+  public async getCurrentTrack(): Promise<ITrackInfo | null> {
+    return this._currentTrack;
+  }
+
+  /**
+   * Get playback status
+   */
+  public async getPlaybackStatus(): Promise<IPlaybackStatus> {
+    return {
+      state: this._playbackState,
+      position: this._position,
+      duration: this._duration,
+      track: this._currentTrack ?? undefined,
+    };
+  }
+
+  /**
+   * Update track info (called by protocol-specific implementations)
+   */
+  protected updateTrack(track: ITrackInfo | null): void {
+    const oldTrack = this._currentTrack;
+    this._currentTrack = track;
+    if (track?.title !== oldTrack?.title || track?.uri !== oldTrack?.uri) {
+      this.emit('playback:track:changed', track);
+    }
+  }
+
+  /**
+   * Update position (called by protocol-specific implementations)
+   */
+  protected updatePosition(position: number, duration: number): void {
+    this._position = position;
+    this._duration = duration;
+    this.emit('playback:position:changed', { position, duration });
+  }
+
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
+  public getFeatureInfo(): IPlaybackFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'playback',
+      protocol: this.protocol,
+      supportsQueue: this.supportsQueue,
+      supportsSeek: this.supportsSeek,
+    };
+  }
+
+  // ============================================================================
+  // Static Factory
+  // ============================================================================
+
+  /**
+   * Create from discovery metadata
+   */
+  public static fromDiscovery(
+    device: TDeviceReference,
+    port: number,
+    protocol: TPlaybackProtocol,
+    metadata: Record<string, unknown>
+  ): PlaybackFeature {
+    return new PlaybackFeature(device, port, {
+      protocol,
+      supportsQueue: metadata.supportsQueue as boolean ?? true,
+      supportsSeek: metadata.supportsSeek as boolean ?? true,
+    });
+  }
+}

package/ts/features/feature.power.ts

@@ -0,0 +1,231 @@
+/**
+ * Power Feature
+ * Provides UPS/power monitoring and control capability
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type {
+  TPowerProtocol,
+  TPowerStatus,
+  IBatteryInfo,
+  IPowerInfo,
+  IPowerFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+
+/**
+ * Options for creating a PowerFeature
+ */
+export interface IPowerFeatureOptions extends IFeatureOptions {
+  protocol: TPowerProtocol;
+  hasBattery?: boolean;
+  supportsShutdown?: boolean;
+  supportsTest?: boolean;
+  /** For NUT protocol: UPS name */
+  upsName?: string;
+  /** For SNMP: community string */
+  community?: string;
+}
+
+/**
+ * Power Feature - provides UPS/power monitoring and control
+ *
+ * Supports NUT (Network UPS Tools) and SNMP protocols for monitoring
+ * UPS devices and smart power equipment.
+ *
+ * @example
+ * ```typescript
+ * const power = device.getFeature<PowerFeature>('power');
+ * if (power) {
+ *   const status = await power.getStatus();
+ *   const battery = await power.getBatteryInfo();
+ *   console.log(`Status: ${status}, Battery: ${battery.charge}%`);
+ * }
+ * ```
+ */
+export class PowerFeature extends Feature {
+  public readonly type = 'power' as const;
+  public readonly protocol: TPowerProtocol;
+
+  // Configuration
+  public readonly upsName: string;
+  public readonly community: string;
+
+  // Capabilities
+  public readonly hasBattery: boolean;
+  public readonly supportsShutdown: boolean;
+  public readonly supportsTest: boolean;
+
+  // Current state
+  protected _status: TPowerStatus = 'unknown';
+  protected _batteryCharge: number = 0;
+  protected _batteryRuntime: number = 0;
+  protected _load: number = 0;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: IPowerFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.upsName = options.upsName ?? 'ups';
+    this.community = options.community ?? 'public';
+    this.hasBattery = options.hasBattery ?? true;
+    this.supportsShutdown = options.supportsShutdown ?? false;
+    this.supportsTest = options.supportsTest ?? false;
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  public get powerStatus(): TPowerStatus {
+    return this._status;
+  }
+
+  public get batteryCharge(): number {
+    return this._batteryCharge;
+  }
+
+  public get batteryRuntime(): number {
+    return this._batteryRuntime;
+  }
+
+  public get load(): number {
+    return this._load;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Protocol-specific connection would be implemented here
+    // For now, just verify the port is reachable
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Protocol-specific disconnection
+  }
+
+  // ============================================================================
+  // Status Monitoring
+  // ============================================================================
+
+  /**
+   * Get current power status
+   */
+  public async getStatus(): Promise<TPowerStatus> {
+    // Protocol-specific implementation would fetch status
+    return this._status;
+  }
+
+  /**
+   * Get battery information
+   */
+  public async getBatteryInfo(): Promise<IBatteryInfo> {
+    return {
+      charge: this._batteryCharge,
+      runtime: this._batteryRuntime,
+    };
+  }
+
+  /**
+   * Get power information
+   */
+  public async getPowerInfo(): Promise<IPowerInfo> {
+    return {
+      load: this._load,
+    };
+  }
+
+  // ============================================================================
+  // Control Commands
+  // ============================================================================
+
+  /**
+   * Initiate shutdown
+   */
+  public async shutdown(delay?: number): Promise<void> {
+    if (!this.supportsShutdown) {
+      throw new Error('Shutdown not supported');
+    }
+    this.emit('power:shutdown', { delay });
+  }
+
+  /**
+   * Start battery test
+   */
+  public async testBattery(): Promise<void> {
+    if (!this.supportsTest) {
+      throw new Error('Battery test not supported');
+    }
+    this.emit('power:test:started');
+  }
+
+  // ============================================================================
+  // State Updates
+  // ============================================================================
+
+  protected updateStatus(status: TPowerStatus): void {
+    const oldStatus = this._status;
+    this._status = status;
+    if (oldStatus !== status) {
+      this.emit('power:status:changed', { oldStatus, newStatus: status });
+
+      // Emit specific events
+      if (status === 'onbattery') {
+        this.emit('power:onbattery');
+      } else if (status === 'online' && oldStatus === 'onbattery') {
+        this.emit('power:restored');
+      } else if (status === 'lowbattery') {
+        this.emit('power:lowbattery');
+      }
+    }
+  }
+
+  protected updateBattery(charge: number, runtime: number): void {
+    const oldCharge = this._batteryCharge;
+    this._batteryCharge = charge;
+    this._batteryRuntime = runtime;
+
+    if (oldCharge !== charge) {
+      this.emit('battery:changed', { charge, runtime });
+    }
+  }
+
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
+  public getFeatureInfo(): IPowerFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'power',
+      protocol: this.protocol,
+      hasBattery: this.hasBattery,
+      supportsShutdown: this.supportsShutdown,
+      supportsTest: this.supportsTest,
+    };
+  }
+
+  // ============================================================================
+  // Static Factory
+  // ============================================================================
+
+  public static fromDiscovery(
+    device: TDeviceReference,
+    port: number,
+    protocol: TPowerProtocol,
+    metadata: Record<string, unknown>
+  ): PowerFeature {
+    return new PowerFeature(device, port, {
+      protocol,
+      upsName: metadata.upsName as string,
+      hasBattery: metadata.hasBattery as boolean ?? true,
+      supportsShutdown: metadata.supportsShutdown as boolean ?? false,
+      supportsTest: metadata.supportsTest as boolean ?? false,
+    });
+  }
+}