devicemanager/ts/interfaces/index.ts

/**
 * 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;
};

// ============================================================================
// Feature Types (Universal Device Architecture)
// ============================================================================

export * from './feature.interfaces.js';