@ecobridge.xyz/devicemanager 3.0.2

package/ts/features/feature.abstract.ts

@@ -0,0 +1,251 @@
+/**
+ * Abstract Feature base class
+ * Features are composable capabilities that can be attached to devices
+ */
+
+import * as plugins from '../plugins.js';
+import type {
+  TFeatureType,
+  TFeatureState,
+  IFeature,
+  IFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+import type { IRetryOptions } from '../interfaces/index.js';
+import { withRetry } from '../helpers/helpers.retry.js';
+
+/**
+ * Forward reference to Device to avoid circular dependency
+ * The actual Device class will set this reference
+ */
+export type TDeviceReference = {
+  id: string;
+  name: string;
+  address: string;
+  port: number;
+};
+
+/**
+ * Abstract base class for all features
+ * Provides common functionality for connection management, state tracking, and retry logic
+ */
+export abstract class Feature extends plugins.events.EventEmitter implements IFeature {
+  /**
+   * The feature type identifier
+   */
+  public abstract readonly type: TFeatureType;
+
+  /**
+   * The protocol used by this feature
+   */
+  public abstract readonly protocol: string;
+
+  /**
+   * The port used by this feature
+   */
+  protected _port: number;
+
+  /**
+   * Current feature state
+   */
+  protected _state: TFeatureState = 'disconnected';
+
+  /**
+   * Last error encountered
+   */
+  protected _lastError?: Error;
+
+  /**
+   * Reference to the parent device
+   */
+  protected _device: TDeviceReference;
+
+  /**
+   * Retry configuration
+   */
+  protected _retryConfig: Required<IRetryOptions>;
+
+  /**
+   * Additional metadata from discovery
+   */
+  protected _metadata: Record<string, unknown>;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options?: IFeatureOptions
+  ) {
+    super();
+    this._device = device;
+    this._port = port;
+    this._metadata = options?.metadata ?? {};
+
+    // Setup retry config
+    const retryOpts = options?.retryOptions ?? {};
+    this._retryConfig = {
+      maxRetries: retryOpts.maxRetries ?? 3,
+      baseDelay: retryOpts.baseDelay ?? 1000,
+      maxDelay: retryOpts.maxDelay ?? 30000,
+      multiplier: retryOpts.multiplier ?? 2,
+      jitter: retryOpts.jitter ?? true,
+    };
+  }
+
+  // ============================================================================
+  // Public Properties
+  // ============================================================================
+
+  /**
+   * Get the feature port
+   */
+  public get port(): number {
+    return this._port;
+  }
+
+  /**
+   * Get the current feature state
+   */
+  public get state(): TFeatureState {
+    return this._state;
+  }
+
+  /**
+   * Check if the feature is connected
+   */
+  public get isConnected(): boolean {
+    return this._state === 'connected';
+  }
+
+  /**
+   * Get the last error
+   */
+  public get lastError(): Error | undefined {
+    return this._lastError;
+  }
+
+  /**
+   * Get the device address
+   */
+  public get address(): string {
+    return this._device.address;
+  }
+
+  /**
+   * Get the device ID
+   */
+  public get deviceId(): string {
+    return this._device.id;
+  }
+
+  // ============================================================================
+  // Connection Management
+  // ============================================================================
+
+  /**
+   * Connect to the feature endpoint
+   */
+  public async connect(): Promise<void> {
+    if (this._state === 'connected') {
+      return;
+    }
+
+    if (this._state === 'connecting') {
+      throw new Error(`Feature ${this.type} is already connecting`);
+    }
+
+    this.setState('connecting');
+    this._lastError = undefined;
+
+    try {
+      await this.withRetry(() => this.doConnect());
+      this.setState('connected');
+      this.emit('connected');
+    } catch (error) {
+      this._lastError = error instanceof Error ? error : new Error(String(error));
+      this.setState('error');
+      this.emit('error', this._lastError);
+      throw this._lastError;
+    }
+  }
+
+  /**
+   * Disconnect from the feature endpoint
+   */
+  public async disconnect(): Promise<void> {
+    if (this._state === 'disconnected') {
+      return;
+    }
+
+    try {
+      await this.doDisconnect();
+    } finally {
+      this.setState('disconnected');
+      this.emit('disconnected');
+    }
+  }
+
+  // ============================================================================
+  // Abstract Methods (implemented by subclasses)
+  // ============================================================================
+
+  /**
+   * Perform the actual connection logic
+   * Implemented by each feature subclass
+   */
+  protected abstract doConnect(): Promise<void>;
+
+  /**
+   * Perform the actual disconnection logic
+   * Implemented by each feature subclass
+   */
+  protected abstract doDisconnect(): Promise<void>;
+
+  /**
+   * Get feature-specific info for serialization
+   */
+  public abstract getFeatureInfo(): IFeatureInfo;
+
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+
+  /**
+   * Set the feature state and emit change event
+   */
+  protected setState(state: TFeatureState): void {
+    if (this._state !== state) {
+      const oldState = this._state;
+      this._state = state;
+      this.emit('state:changed', { oldState, newState: state });
+    }
+  }
+
+  /**
+   * Execute an operation with retry logic
+   */
+  protected async withRetry<T>(operation: () => Promise<T>): Promise<T> {
+    return withRetry(operation, this._retryConfig);
+  }
+
+  /**
+   * Get base feature info
+   */
+  protected getBaseFeatureInfo(): IFeatureInfo {
+    return {
+      type: this.type,
+      protocol: this.protocol,
+      port: this._port,
+      state: this._state,
+    };
+  }
+
+  /**
+   * Clear error state
+   */
+  public clearError(): void {
+    this._lastError = undefined;
+    if (this._state === 'error') {
+      this.setState('disconnected');
+    }
+  }
+}

package/ts/features/feature.camera.ts

@@ -0,0 +1,214 @@
+/**
+ * Camera Feature
+ * Provides control for smart cameras (snapshots, streams)
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TCameraProtocol,
+  ICameraCapabilities,
+  ICameraState,
+  ICameraFeatureInfo,
+  ICameraProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a CameraFeature
+ */
+export interface ICameraFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TCameraProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for the camera */
+  protocolClient: ICameraProtocolClient;
+  /** Camera capabilities */
+  capabilities?: Partial<ICameraCapabilities>;
+}
+
+/**
+ * Camera Feature - snapshot and stream access
+ *
+ * Protocol-agnostic: works with Home Assistant, ONVIF, RTSP, etc.
+ *
+ * @example
+ * ```typescript
+ * const camera = device.getFeature<CameraFeature>('camera');
+ * if (camera) {
+ *   const snapshot = await camera.getSnapshot();
+ *   const streamUrl = await camera.getStreamUrl();
+ * }
+ * ```
+ */
+export class CameraFeature extends Feature {
+  public readonly type = 'camera' as const;
+  public readonly protocol: TCameraProtocol;
+
+  /** Entity ID (e.g., "camera.front_door") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: ICameraCapabilities;
+
+  /** Current state */
+  protected _isRecording: boolean = false;
+  protected _isStreaming: boolean = false;
+  protected _motionDetected: boolean = false;
+
+  /** Protocol client for the camera */
+  private protocolClient: ICameraProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: ICameraFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+
+    this.capabilities = {
+      supportsStream: options.capabilities?.supportsStream ?? true,
+      supportsPtz: options.capabilities?.supportsPtz ?? false,
+      supportsSnapshot: options.capabilities?.supportsSnapshot ?? true,
+      supportsMotionDetection: options.capabilities?.supportsMotionDetection ?? false,
+      frontendStreamType: options.capabilities?.frontendStreamType,
+      streamUrl: options.capabilities?.streamUrl,
+    };
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Check if recording (cached)
+   */
+  public get isRecording(): boolean {
+    return this._isRecording;
+  }
+
+  /**
+   * Check if streaming (cached)
+   */
+  public get isStreaming(): boolean {
+    return this._isStreaming;
+  }
+
+  /**
+   * Check if motion detected (cached)
+   */
+  public get motionDetected(): boolean {
+    return this._motionDetected;
+  }
+
+  // ============================================================================
+  // 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
+  }
+
+  // ============================================================================
+  // Camera Access
+  // ============================================================================
+
+  /**
+   * Get a snapshot image from the camera
+   * @returns Buffer containing image data
+   */
+  public async getSnapshot(): Promise<Buffer> {
+    if (!this.capabilities.supportsSnapshot) {
+      throw new Error('Camera does not support snapshots');
+    }
+
+    return this.protocolClient.getSnapshot(this.entityId);
+  }
+
+  /**
+   * Get snapshot URL
+   * @returns URL for the snapshot image
+   */
+  public async getSnapshotUrl(): Promise<string> {
+    if (!this.capabilities.supportsSnapshot) {
+      throw new Error('Camera does not support snapshots');
+    }
+
+    return this.protocolClient.getSnapshotUrl(this.entityId);
+  }
+
+  /**
+   * Get stream URL
+   * @returns URL for the video stream
+   */
+  public async getStreamUrl(): Promise<string> {
+    if (!this.capabilities.supportsStream) {
+      throw new Error('Camera does not support streaming');
+    }
+
+    return this.protocolClient.getStreamUrl(this.entityId);
+  }
+
+  /**
+   * Get current state as object
+   */
+  public getState(): ICameraState {
+    return {
+      isRecording: this._isRecording,
+      isStreaming: this._isStreaming,
+      motionDetected: this._motionDetected,
+    };
+  }
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<ICameraState> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this.updateStateInternal(state);
+    return state;
+  }
+
+  /**
+   * Update state from external source
+   */
+  public updateState(state: ICameraState): void {
+    this.updateStateInternal(state);
+    this.emit('state:changed', state);
+  }
+
+  /**
+   * Internal state update
+   */
+  private updateStateInternal(state: ICameraState): void {
+    this._isRecording = state.isRecording;
+    this._isStreaming = state.isStreaming;
+    this._motionDetected = state.motionDetected;
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): ICameraFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'camera',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: this.getState(),
+    };
+  }
+}