@ecobridge.xyz/devicemanager 3.0.2

package/ts/interfaces/index.ts

@@ -0,0 +1,421 @@
+/**
+ * Device Manager Type Definitions
+ */
+
+// ============================================================================
+// Device Types
+// ============================================================================
+
+export type TDeviceType = 'scanner' | 'printer' | 'snmp' | 'ups' | 'speaker' | 'dlna-renderer' | 'dlna-server';
+export type TDeviceStatus = 'online' | 'offline' | 'busy' | 'error' | 'unknown';
+export type TConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+// ============================================================================
+// Scanner Types
+// ============================================================================
+
+export type TScannerProtocol = 'sane' | 'escl';
+export type TScanFormat = 'png' | 'jpeg' | 'pdf' | 'tiff';
+export type TColorMode = 'color' | 'grayscale' | 'blackwhite';
+export type TScanSource = 'flatbed' | 'adf' | 'adf-duplex';
+
+// ============================================================================
+// Base Interfaces
+// ============================================================================
+
+export interface IDeviceInfo {
+  id: string;
+  name: string;
+  type: TDeviceType;
+  address: string;
+  port: number;
+  status: TDeviceStatus;
+  manufacturer?: string;
+  model?: string;
+  serialNumber?: string;
+  firmwareVersion?: string;
+}
+
+export interface IDeviceManagerOptions {
+  /** Enable auto-discovery on startup */
+  autoDiscovery?: boolean;
+  /** Discovery timeout in milliseconds */
+  discoveryTimeout?: number;
+  /** Enable retry with exponential backoff */
+  enableRetry?: boolean;
+  /** Maximum retry attempts */
+  maxRetries?: number;
+  /** Base delay for retry backoff in milliseconds */
+  retryBaseDelay?: number;
+}
+
+// ============================================================================
+// Scanner Interfaces
+// ============================================================================
+
+export interface IScannerInfo extends IDeviceInfo {
+  type: 'scanner';
+  protocol: TScannerProtocol;
+  supportedFormats: TScanFormat[];
+  supportedResolutions: number[];
+  supportedColorModes: TColorMode[];
+  supportedSources: TScanSource[];
+  hasAdf: boolean;
+  hasDuplex: boolean;
+  maxWidth?: number;  // in mm
+  maxHeight?: number; // in mm
+}
+
+export interface IScanArea {
+  x: number;      // X offset in mm
+  y: number;      // Y offset in mm
+  width: number;  // Width in mm
+  height: number; // Height in mm
+}
+
+export interface IScanOptions {
+  /** Resolution in DPI (default: 300) */
+  resolution?: number;
+  /** Output format (default: 'png') */
+  format?: TScanFormat;
+  /** Color mode (default: 'color') */
+  colorMode?: TColorMode;
+  /** Scan source (default: 'flatbed') */
+  source?: TScanSource;
+  /** Scan area (default: full page) */
+  area?: IScanArea;
+  /** Document intent for optimization */
+  intent?: 'document' | 'photo' | 'preview';
+  /** Compression quality for JPEG (1-100) */
+  quality?: number;
+}
+
+export interface IScanResult {
+  /** Scanned image data */
+  data: Buffer;
+  /** Output format */
+  format: TScanFormat;
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Scan resolution in DPI */
+  resolution: number;
+  /** Color mode used */
+  colorMode: TColorMode;
+  /** MIME type */
+  mimeType: string;
+}
+
+export interface IScannerCapabilities {
+  resolutions: number[];
+  formats: TScanFormat[];
+  colorModes: TColorMode[];
+  sources: TScanSource[];
+  maxWidth: number;
+  maxHeight: number;
+  minWidth: number;
+  minHeight: number;
+}
+
+// ============================================================================
+// Printer Interfaces
+// ============================================================================
+
+export interface IPrinterInfo extends IDeviceInfo {
+  type: 'printer';
+  uri: string;
+  supportsColor: boolean;
+  supportsDuplex: boolean;
+  supportedMediaTypes: string[];
+  supportedMediaSizes: string[];
+  maxCopies: number;
+}
+
+export interface IPrintOptions {
+  /** Number of copies (default: 1) */
+  copies?: number;
+  /** Media size (e.g., 'iso_a4_210x297mm') */
+  mediaSize?: string;
+  /** Media type (e.g., 'stationery') */
+  mediaType?: string;
+  /** Print sides: 'one-sided', 'two-sided-long-edge', 'two-sided-short-edge' */
+  sides?: 'one-sided' | 'two-sided-long-edge' | 'two-sided-short-edge';
+  /** Print quality */
+  quality?: 'draft' | 'normal' | 'high';
+  /** Color mode */
+  colorMode?: 'color' | 'monochrome';
+  /** Job name */
+  jobName?: string;
+}
+
+export interface IPrintJob {
+  id: number;
+  name: string;
+  state: 'pending' | 'processing' | 'completed' | 'canceled' | 'aborted';
+  stateReason?: string;
+  createdAt: Date;
+  completedAt?: Date;
+  pagesPrinted?: number;
+  pagesTotal?: number;
+}
+
+export interface IPrinterCapabilities {
+  colorSupported: boolean;
+  duplexSupported: boolean;
+  mediaSizes: string[];
+  mediaTypes: string[];
+  resolutions: number[];
+  maxCopies: number;
+  sidesSupported: string[];
+  qualitySupported: string[];
+}
+
+// ============================================================================
+// Discovery Interfaces
+// ============================================================================
+
+export interface IDiscoveredDevice {
+  id: string;
+  name: string;
+  type: TDeviceType;
+  protocol: string; // 'escl' | 'sane' | 'ipp' | 'airplay' | 'sonos' | 'chromecast' | etc.
+  address: string;
+  port: number;
+  txtRecords: Record<string, string>;
+  serviceType: string;
+}
+
+export interface IDiscoveryOptions {
+  /** Service types to discover */
+  serviceTypes?: string[];
+  /** Discovery timeout in ms */
+  timeout?: number;
+}
+
+// ============================================================================
+// Retry Configuration
+// ============================================================================
+
+export interface IRetryOptions {
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+  /** Base delay in milliseconds */
+  baseDelay?: number;
+  /** Maximum delay in milliseconds */
+  maxDelay?: number;
+  /** Delay multiplier for exponential backoff */
+  multiplier?: number;
+  /** Whether to add jitter to delays */
+  jitter?: boolean;
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export type TDeviceManagerEvents = {
+  'scanner:found': (scanner: IScannerInfo) => void;
+  'scanner:lost': (scannerId: string) => void;
+  'printer:found': (printer: IPrinterInfo) => void;
+  'printer:lost': (printerId: string) => void;
+  'device:updated': (device: IDeviceInfo) => void;
+  'discovery:started': () => void;
+  'discovery:stopped': () => void;
+  'error': (error: Error) => void;
+};
+
+// ============================================================================
+// eSCL Protocol Types
+// ============================================================================
+
+export interface IEsclCapabilities {
+  version: string;
+  makeAndModel: string;
+  serialNumber?: string;
+  uuid?: string;
+  adminUri?: string;
+  iconUri?: string;
+  platen?: IEsclInputSource;
+  adf?: IEsclInputSource;
+  adfDuplex?: IEsclInputSource;
+}
+
+export interface IEsclInputSource {
+  minWidth: number;
+  maxWidth: number;
+  minHeight: number;
+  maxHeight: number;
+  maxScanRegions: number;
+  supportedResolutions: number[];
+  colorModes: string[];
+  documentFormats: string[];
+}
+
+export interface IEsclScanStatus {
+  state: 'Idle' | 'Processing' | 'Stopped' | 'Testing';
+  adfState?: 'Empty' | 'Loaded' | 'Jammed' | 'Open' | 'Closed';
+  jobs?: IEsclJobInfo[];
+}
+
+export interface IEsclJobInfo {
+  jobUri: string;
+  jobUuid: string;
+  age: number;
+  imagesCompleted: number;
+  imagesToTransfer: number;
+  jobState: 'Pending' | 'Processing' | 'Completed' | 'Canceled' | 'Aborted';
+  jobStateReason?: string;
+}
+
+// ============================================================================
+// SANE Protocol Types
+// ============================================================================
+
+export interface ISaneDevice {
+  name: string;
+  vendor: string;
+  model: string;
+  type: string;
+}
+
+export interface ISaneOption {
+  name: string;
+  title: string;
+  description: string;
+  type: 'bool' | 'int' | 'fixed' | 'string' | 'button' | 'group';
+  unit: 'none' | 'pixel' | 'bit' | 'mm' | 'dpi' | 'percent' | 'microsecond';
+  size: number;
+  capabilities: number;
+  constraintType: 'none' | 'range' | 'word_list' | 'string_list';
+  constraint?: ISaneConstraint;
+}
+
+export interface ISaneConstraint {
+  range?: { min: number; max: number; quant: number };
+  wordList?: number[];
+  stringList?: string[];
+}
+
+export interface ISaneParameters {
+  format: 'gray' | 'rgb' | 'red' | 'green' | 'blue';
+  lastFrame: boolean;
+  bytesPerLine: number;
+  pixelsPerLine: number;
+  lines: number;
+  depth: number;
+}
+
+// ============================================================================
+// Network Scanner Interfaces (IP-based discovery)
+// ============================================================================
+
+export interface INetworkScanOptions {
+  /** CIDR notation (e.g., "192.168.1.0/24") */
+  ipRange?: string;
+  /** Start IP address for range scan */
+  startIp?: string;
+  /** End IP address for range scan */
+  endIp?: string;
+  /** Maximum concurrent probes (default: 50) */
+  concurrency?: number;
+  /** Timeout per probe in milliseconds (default: 2000) */
+  timeout?: number;
+  /** Ports to probe (default: [80, 443, 631, 6566, 9100, 7000, 1400, 8009]) */
+  ports?: number[];
+  /** Check for eSCL scanners (default: true) */
+  probeEscl?: boolean;
+  /** Check for IPP printers (default: true) */
+  probeIpp?: boolean;
+  /** Check for SANE scanners (default: true) */
+  probeSane?: boolean;
+  /** Check for AirPlay speakers (default: true) */
+  probeAirplay?: boolean;
+  /** Check for Sonos speakers (default: true) */
+  probeSonos?: boolean;
+  /** Check for Chromecast devices (default: true) */
+  probeChromecast?: boolean;
+}
+
+export interface INetworkScanDevice {
+  type: 'scanner' | 'printer' | 'speaker';
+  protocol: 'escl' | 'sane' | 'ipp' | 'jetdirect' | 'airplay' | 'sonos' | 'chromecast';
+  port: number;
+  name?: string;
+  model?: string;
+}
+
+export interface INetworkScanResult {
+  address: string;
+  devices: INetworkScanDevice[];
+}
+
+export interface INetworkScanProgress {
+  /** Total IPs to scan */
+  total: number;
+  /** IPs scanned so far */
+  scanned: number;
+  /** Percentage complete (0-100) */
+  percentage: number;
+  /** Current IP being scanned */
+  currentIp?: string;
+  /** Devices found so far */
+  devicesFound: number;
+}
+
+export type TNetworkScannerEvents = {
+  'progress': (progress: INetworkScanProgress) => void;
+  'device:found': (result: INetworkScanResult) => void;
+  'complete': (results: INetworkScanResult[]) => void;
+  'error': (error: Error) => void;
+  'cancelled': () => void;
+};
+
+// ============================================================================
+// Device Selector Interface
+// ============================================================================
+
+import type { TFeatureType } from './feature.interfaces.js';
+
+/**
+ * Criteria for selecting devices from the manager.
+ * Identity selectors (id, address) match exactly.
+ * Attribute selectors (name, model, manufacturer) match partially (case-insensitive).
+ * Capability selectors filter by feature availability.
+ */
+export interface IDeviceSelector {
+  /** Exact match on device ID */
+  id?: string;
+  /** Exact match on IP address */
+  address?: string;
+  /** Partial match on device name (case-insensitive) */
+  name?: string;
+  /** Partial match on device model (case-insensitive) */
+  model?: string;
+  /** Partial match on manufacturer name (case-insensitive) */
+  manufacturer?: string;
+  /** Device must have this feature */
+  hasFeature?: TFeatureType;
+  /** Device must have ALL of these features */
+  hasFeatures?: TFeatureType[];
+  /** Device must have ANY of these features */
+  hasAnyFeature?: TFeatureType[];
+}
+
+// ============================================================================
+// Feature Types (Universal Device Architecture)
+// ============================================================================
+
+export * from './feature.interfaces.js';
+
+// ============================================================================
+// Smart Home Types (Generic, Protocol-agnostic)
+// ============================================================================
+
+export * from './smarthome.interfaces.js';
+
+// ============================================================================
+// Home Assistant Specific Types
+// ============================================================================
+
+export * from './homeassistant.interfaces.js';