@ecobridge.xyz/devicemanager 3.0.2

package/ts/features/feature.print.ts

@@ -0,0 +1,297 @@
+/**
+ * Print Feature
+ * Provides document printing capability using IPP protocol
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import { IppProtocol } from '../protocols/index.js';
+import type {
+  TPrintProtocol,
+  TPrintSides,
+  TPrintQuality,
+  TPrintColorMode,
+  IPrintCapabilities,
+  IPrintOptions,
+  IPrintJob,
+  IPrintFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+import type { IPrinterCapabilities } from '../interfaces/index.js';
+
+/**
+ * Options for creating a PrintFeature
+ */
+export interface IPrintFeatureOptions extends IFeatureOptions {
+  protocol?: TPrintProtocol;
+  uri?: string;
+  supportsColor?: boolean;
+  supportsDuplex?: boolean;
+  supportedMediaSizes?: string[];
+  supportedMediaTypes?: string[];
+  maxCopies?: number;
+}
+
+/**
+ * Print Feature - provides document printing capability
+ *
+ * Wraps the IPP protocol to provide a unified printing interface.
+ *
+ * @example
+ * ```typescript
+ * const printFeature = device.getFeature<PrintFeature>('print');
+ * if (printFeature) {
+ *   await printFeature.connect();
+ *   const job = await printFeature.print(pdfBuffer, { copies: 2 });
+ *   console.log(`Print job ${job.id} created`);
+ * }
+ * ```
+ */
+export class PrintFeature extends Feature {
+  public readonly type = 'print' as const;
+  public readonly protocol: TPrintProtocol;
+
+  // Protocol client
+  private ippClient: IppProtocol | null = null;
+
+  // Configuration
+  public readonly uri: string;
+
+  // Capabilities
+  public supportsColor: boolean = true;
+  public supportsDuplex: boolean = false;
+  public supportedMediaSizes: string[] = ['iso_a4_210x297mm', 'na_letter_8.5x11in'];
+  public supportedMediaTypes: string[] = ['stationery'];
+  public maxCopies: number = 99;
+  public supportedSides: TPrintSides[] = ['one-sided'];
+  public supportedQualities: TPrintQuality[] = ['normal'];
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options?: IPrintFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options?.protocol ?? 'ipp';
+    this.uri = options?.uri ?? `ipp://${device.address}:${port}/ipp/print`;
+
+    // Set capabilities from options if provided
+    if (options?.supportsColor !== undefined) this.supportsColor = options.supportsColor;
+    if (options?.supportsDuplex !== undefined) {
+      this.supportsDuplex = options.supportsDuplex;
+      if (options.supportsDuplex) {
+        this.supportedSides = ['one-sided', 'two-sided-long-edge', 'two-sided-short-edge'];
+      }
+    }
+    if (options?.supportedMediaSizes) this.supportedMediaSizes = options.supportedMediaSizes;
+    if (options?.supportedMediaTypes) this.supportedMediaTypes = options.supportedMediaTypes;
+    if (options?.maxCopies) this.maxCopies = options.maxCopies;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    if (this.protocol === 'ipp') {
+      // Parse URI to get address, port, and path
+      const url = new URL(this.uri.replace('ipp://', 'http://').replace('ipps://', 'https://'));
+      const address = url.hostname;
+      const port = parseInt(url.port) || this._port;
+      const path = url.pathname || '/ipp/print';
+
+      this.ippClient = new IppProtocol(address, port, path);
+      // Verify connection by getting printer attributes
+      const attrs = await this.ippClient.getAttributes();
+      this.updateCapabilitiesFromIpp(attrs);
+    }
+    // JetDirect and LPD don't need connection verification
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    this.ippClient = null;
+  }
+
+  // ============================================================================
+  // Printing Operations
+  // ============================================================================
+
+  /**
+   * Get printer capabilities
+   */
+  public async getCapabilities(): Promise<IPrintCapabilities> {
+    return {
+      colorSupported: this.supportsColor,
+      duplexSupported: this.supportsDuplex,
+      mediaSizes: this.supportedMediaSizes,
+      mediaTypes: this.supportedMediaTypes,
+      resolutions: [300, 600],
+      maxCopies: this.maxCopies,
+      sidesSupported: this.supportedSides,
+      qualitySupported: this.supportedQualities,
+    };
+  }
+
+  /**
+   * Print a document
+   */
+  public async print(data: Buffer, options?: IPrintOptions): Promise<IPrintJob> {
+    if (!this.isConnected) {
+      throw new Error('Print feature not connected');
+    }
+
+    if (this.protocol === 'ipp' && this.ippClient) {
+      return this.printWithIpp(data, options);
+    }
+
+    throw new Error(`Protocol ${this.protocol} not supported yet`);
+  }
+
+  /**
+   * Get active print jobs
+   */
+  public async getJobs(): Promise<IPrintJob[]> {
+    if (!this.isConnected || !this.ippClient) {
+      throw new Error('Print feature not connected');
+    }
+
+    return this.ippClient.getJobs();
+  }
+
+  /**
+   * Get info about a specific job
+   */
+  public async getJobInfo(jobId: number): Promise<IPrintJob> {
+    if (!this.isConnected || !this.ippClient) {
+      throw new Error('Print feature not connected');
+    }
+
+    return this.ippClient.getJobInfo(jobId);
+  }
+
+  /**
+   * Cancel a print job
+   */
+  public async cancelJob(jobId: number): Promise<void> {
+    if (!this.isConnected || !this.ippClient) {
+      throw new Error('Print feature not connected');
+    }
+
+    await this.ippClient.cancelJob(jobId);
+    this.emit('job:cancelled', jobId);
+  }
+
+  // ============================================================================
+  // Protocol-Specific Printing
+  // ============================================================================
+
+  private async printWithIpp(data: Buffer, options?: IPrintOptions): Promise<IPrintJob> {
+    if (!this.ippClient) {
+      throw new Error('IPP client not initialized');
+    }
+
+    this.emit('print:started', options);
+
+    // IppProtocol.print() accepts IPrintOptions and returns IPrintJob
+    const job = await this.ippClient.print(data, options);
+
+    this.emit('print:submitted', job);
+    return job;
+  }
+
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+
+  private updateCapabilitiesFromIpp(caps: IPrinterCapabilities): void {
+    this.supportsColor = caps.colorSupported;
+    this.supportsDuplex = caps.duplexSupported;
+    this.maxCopies = caps.maxCopies;
+
+    if (caps.mediaSizes && caps.mediaSizes.length > 0) {
+      this.supportedMediaSizes = caps.mediaSizes;
+    }
+    if (caps.mediaTypes && caps.mediaTypes.length > 0) {
+      this.supportedMediaTypes = caps.mediaTypes;
+    }
+    if (caps.sidesSupported && caps.sidesSupported.length > 0) {
+      this.supportedSides = caps.sidesSupported.filter((s): s is TPrintSides =>
+        ['one-sided', 'two-sided-long-edge', 'two-sided-short-edge'].includes(s)
+      );
+    }
+    if (caps.qualitySupported && caps.qualitySupported.length > 0) {
+      this.supportedQualities = caps.qualitySupported.filter((q): q is TPrintQuality =>
+        ['draft', 'normal', 'high'].includes(q)
+      );
+    }
+  }
+
+  private qualityToIpp(quality: TPrintQuality): number {
+    switch (quality) {
+      case 'draft': return 3;
+      case 'normal': return 4;
+      case 'high': return 5;
+      default: return 4;
+    }
+  }
+
+  private mapIppJob(job: Record<string, unknown>): IPrintJob {
+    const stateMap: Record<number, IPrintJob['state']> = {
+      3: 'pending',
+      4: 'pending',
+      5: 'processing',
+      6: 'processing',
+      7: 'canceled',
+      8: 'aborted',
+      9: 'completed',
+    };
+
+    return {
+      id: job['job-id'] as number,
+      name: job['job-name'] as string ?? 'Unknown',
+      state: stateMap[(job['job-state'] as number) ?? 3] ?? 'pending',
+      stateReason: (job['job-state-reasons'] as string[])?.[0],
+      createdAt: new Date((job['time-at-creation'] as number) * 1000),
+      completedAt: job['time-at-completed']
+        ? new Date((job['time-at-completed'] as number) * 1000)
+        : undefined,
+    };
+  }
+
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
+  public getFeatureInfo(): IPrintFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'print',
+      protocol: this.protocol,
+      supportsColor: this.supportsColor,
+      supportsDuplex: this.supportsDuplex,
+      supportedMediaSizes: this.supportedMediaSizes,
+    };
+  }
+
+  // ============================================================================
+  // Static Factory
+  // ============================================================================
+
+  /**
+   * Create from discovery metadata
+   */
+  public static fromDiscovery(
+    device: TDeviceReference,
+    port: number,
+    protocol: TPrintProtocol,
+    metadata: Record<string, unknown>
+  ): PrintFeature {
+    const txtRecords = metadata.txtRecords as Record<string, string> ?? {};
+
+    return new PrintFeature(device, port, {
+      protocol,
+      uri: metadata.uri as string,
+      supportsColor: txtRecords['Color'] === 'T' || txtRecords['color'] === 'true',
+      supportsDuplex: txtRecords['Duplex'] === 'T' || txtRecords['duplex'] === 'true',
+    });
+  }
+}

package/ts/features/feature.scan.ts

@@ -0,0 +1,370 @@
+/**
+ * Scan Feature
+ * Provides document scanning capability using eSCL or SANE protocols
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import { EsclProtocol, SaneProtocol } from '../protocols/index.js';
+import type {
+  TScanProtocol,
+  TScanFormat,
+  TColorMode,
+  TScanSource,
+  IScanCapabilities,
+  IScanOptions,
+  IScanResult,
+  IScanFeatureInfo,
+  IFeatureOptions,
+} from '../interfaces/feature.interfaces.js';
+
+/**
+ * Options for creating a ScanFeature
+ */
+export interface IScanFeatureOptions extends IFeatureOptions {
+  protocol: TScanProtocol;
+  secure?: boolean;
+  deviceName?: string; // For SANE
+  supportedFormats?: TScanFormat[];
+  supportedResolutions?: number[];
+  supportedColorModes?: TColorMode[];
+  supportedSources?: TScanSource[];
+  hasAdf?: boolean;
+  hasDuplex?: boolean;
+}
+
+/**
+ * Scan Feature - provides document scanning capability
+ *
+ * Wraps eSCL (AirScan) or SANE protocols to provide a unified scanning interface.
+ *
+ * @example
+ * ```typescript
+ * const scanFeature = device.getFeature<ScanFeature>('scan');
+ * if (scanFeature) {
+ *   await scanFeature.connect();
+ *   const result = await scanFeature.scan({ format: 'pdf', resolution: 300 });
+ *   console.log(`Scanned ${result.width}x${result.height} pixels`);
+ * }
+ * ```
+ */
+export class ScanFeature extends Feature {
+  public readonly type = 'scan' as const;
+  public readonly protocol: TScanProtocol;
+
+  // Protocol clients
+  private esclClient: EsclProtocol | null = null;
+  private saneClient: SaneProtocol | null = null;
+
+  // Configuration
+  private readonly isSecure: boolean;
+  private readonly deviceName: string;
+
+  // Capabilities
+  public supportedFormats: TScanFormat[] = ['jpeg', 'png', 'pdf'];
+  public supportedResolutions: number[] = [75, 150, 300, 600];
+  public supportedColorModes: TColorMode[] = ['color', 'grayscale', 'blackwhite'];
+  public supportedSources: TScanSource[] = ['flatbed'];
+  public hasAdf: boolean = false;
+  public hasDuplex: boolean = false;
+  public maxWidth: number = 215.9;  // A4 width in mm
+  public maxHeight: number = 297;   // A4 height in mm
+  public minWidth: number = 10;
+  public minHeight: number = 10;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: IScanFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.isSecure = options.secure ?? false;
+    this.deviceName = options.deviceName ?? '';
+
+    // Set capabilities from options if provided
+    if (options.supportedFormats) this.supportedFormats = options.supportedFormats;
+    if (options.supportedResolutions) this.supportedResolutions = options.supportedResolutions;
+    if (options.supportedColorModes) this.supportedColorModes = options.supportedColorModes;
+    if (options.supportedSources) this.supportedSources = options.supportedSources;
+    if (options.hasAdf !== undefined) this.hasAdf = options.hasAdf;
+    if (options.hasDuplex !== undefined) this.hasDuplex = options.hasDuplex;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    if (this.protocol === 'escl') {
+      this.esclClient = new EsclProtocol(this.address, this._port, this.isSecure);
+      // Fetch capabilities to verify connection
+      const caps = await this.esclClient.getCapabilities();
+      this.updateCapabilitiesFromEscl(caps);
+    } else if (this.protocol === 'sane') {
+      this.saneClient = new SaneProtocol(this.address, this._port);
+      await this.saneClient.connect();
+      // Open the device if we have a name
+      if (this.deviceName) {
+        await this.saneClient.open(this.deviceName);
+      }
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    if (this.saneClient) {
+      try {
+        await this.saneClient.close();
+        await this.saneClient.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+      this.saneClient = null;
+    }
+    this.esclClient = null;
+  }
+
+  // ============================================================================
+  // Scanning Operations
+  // ============================================================================
+
+  /**
+   * Get scanner capabilities
+   */
+  public async getCapabilities(): Promise<IScanCapabilities> {
+    return {
+      resolutions: this.supportedResolutions,
+      formats: this.supportedFormats,
+      colorModes: this.supportedColorModes,
+      sources: this.supportedSources,
+      maxWidth: this.maxWidth,
+      maxHeight: this.maxHeight,
+      minWidth: this.minWidth,
+      minHeight: this.minHeight,
+    };
+  }
+
+  /**
+   * Perform a scan
+   */
+  public async scan(options?: IScanOptions): Promise<IScanResult> {
+    if (!this.isConnected) {
+      throw new Error('Scan feature not connected');
+    }
+
+    const opts = this.resolveOptions(options);
+
+    if (this.protocol === 'escl' && this.esclClient) {
+      return this.scanWithEscl(opts);
+    } else if (this.protocol === 'sane' && this.saneClient) {
+      return this.scanWithSane(opts);
+    }
+
+    throw new Error('No scanner protocol available');
+  }
+
+  /**
+   * Cancel an ongoing scan
+   */
+  public async cancelScan(): Promise<void> {
+    if (this.protocol === 'sane' && this.saneClient) {
+      await this.saneClient.cancel();
+    }
+    // eSCL cancellation is handled by deleting the job
+    this.emit('scan:cancelled');
+  }
+
+  // ============================================================================
+  // Protocol-Specific Scanning
+  // ============================================================================
+
+  private async scanWithEscl(options: Required<IScanOptions>): Promise<IScanResult> {
+    if (!this.esclClient) {
+      throw new Error('eSCL client not initialized');
+    }
+
+    this.emit('scan:started', options);
+
+    // Use the protocol's scan method which handles job submission,
+    // waiting for completion, and downloading in one operation
+    const result = await this.esclClient.scan({
+      format: options.format,
+      resolution: options.resolution,
+      colorMode: options.colorMode,
+      source: options.source,
+      area: options.area,
+      intent: options.intent,
+    });
+
+    this.emit('scan:completed', result);
+    return result;
+  }
+
+  private async scanWithSane(options: Required<IScanOptions>): Promise<IScanResult> {
+    if (!this.saneClient) {
+      throw new Error('SANE client not initialized');
+    }
+
+    this.emit('scan:started', options);
+
+    // Use the protocol's scan method which handles option configuration,
+    // parameter retrieval, and image reading in one operation
+    const result = await this.saneClient.scan({
+      format: options.format,
+      resolution: options.resolution,
+      colorMode: options.colorMode,
+      source: options.source,
+      area: options.area,
+    });
+
+    this.emit('scan:completed', result);
+    return result;
+  }
+
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+
+  private resolveOptions(options?: IScanOptions): Required<IScanOptions> {
+    return {
+      resolution: options?.resolution ?? 300,
+      format: options?.format ?? 'jpeg',
+      colorMode: options?.colorMode ?? 'color',
+      source: options?.source ?? 'flatbed',
+      area: options?.area ?? {
+        x: 0,
+        y: 0,
+        width: this.maxWidth,
+        height: this.maxHeight,
+      },
+      intent: options?.intent ?? 'document',
+      quality: options?.quality ?? 85,
+    };
+  }
+
+  private updateCapabilitiesFromEscl(caps: any): void {
+    if (caps.platen) {
+      this.supportedResolutions = caps.platen.supportedResolutions || this.supportedResolutions;
+      this.maxWidth = caps.platen.maxWidth || this.maxWidth;
+      this.maxHeight = caps.platen.maxHeight || this.maxHeight;
+      this.minWidth = caps.platen.minWidth || this.minWidth;
+      this.minHeight = caps.platen.minHeight || this.minHeight;
+    }
+    if (caps.adf) {
+      this.hasAdf = true;
+      if (!this.supportedSources.includes('adf')) {
+        this.supportedSources.push('adf');
+      }
+    }
+    if (caps.adfDuplex) {
+      this.hasDuplex = true;
+      if (!this.supportedSources.includes('adf-duplex')) {
+        this.supportedSources.push('adf-duplex');
+      }
+    }
+  }
+
+  private colorModeToSane(mode: TColorMode): string {
+    switch (mode) {
+      case 'color': return 'Color';
+      case 'grayscale': return 'Gray';
+      case 'blackwhite': return 'Lineart';
+      default: return 'Color';
+    }
+  }
+
+  private getMimeType(format: TScanFormat): string {
+    switch (format) {
+      case 'jpeg': return 'image/jpeg';
+      case 'png': return 'image/png';
+      case 'pdf': return 'application/pdf';
+      case 'tiff': return 'image/tiff';
+      default: return 'application/octet-stream';
+    }
+  }
+
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
+  public getFeatureInfo(): IScanFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'scan',
+      protocol: this.protocol,
+      supportedFormats: this.supportedFormats,
+      supportedResolutions: this.supportedResolutions,
+      supportedColorModes: this.supportedColorModes,
+      supportedSources: this.supportedSources,
+      hasAdf: this.hasAdf,
+      hasDuplex: this.hasDuplex,
+    };
+  }
+
+  // ============================================================================
+  // Static Factory
+  // ============================================================================
+
+  /**
+   * Create from discovery metadata
+   */
+  public static fromDiscovery(
+    device: TDeviceReference,
+    port: number,
+    protocol: TScanProtocol,
+    metadata: Record<string, unknown>
+  ): ScanFeature {
+    const txtRecords = metadata.txtRecords as Record<string, string> ?? {};
+
+    return new ScanFeature(device, port, {
+      protocol,
+      secure: metadata.secure as boolean ?? port === 443,
+      deviceName: metadata.deviceName as string,
+      supportedFormats: parseFormats(txtRecords),
+      supportedResolutions: parseResolutions(txtRecords),
+      supportedColorModes: parseColorModes(txtRecords),
+      supportedSources: parseSources(txtRecords),
+      hasAdf: Boolean(metadata.hasAdf),
+      hasDuplex: Boolean(metadata.hasDuplex),
+    });
+  }
+}
+
+// ============================================================================
+// Parsing Helpers
+// ============================================================================
+
+function parseFormats(txt: Record<string, string>): TScanFormat[] {
+  const pdl = txt['pdl'] || '';
+  const formats: TScanFormat[] = [];
+  if (pdl.includes('image/jpeg')) formats.push('jpeg');
+  if (pdl.includes('image/png')) formats.push('png');
+  if (pdl.includes('application/pdf')) formats.push('pdf');
+  if (pdl.includes('image/tiff')) formats.push('tiff');
+  return formats.length > 0 ? formats : ['jpeg', 'png', 'pdf'];
+}
+
+function parseResolutions(txt: Record<string, string>): number[] {
+  const rs = txt['rs'] || '';
+  if (!rs) return [75, 150, 300, 600];
+  return rs.split(',')
+    .map((r) => parseInt(r.trim(), 10))
+    .filter((r) => !isNaN(r) && r > 0);
+}
+
+function parseColorModes(txt: Record<string, string>): TColorMode[] {
+  const cs = txt['cs'] || '';
+  const modes: TColorMode[] = [];
+  if (cs.includes('color') || cs.includes('RGB')) modes.push('color');
+  if (cs.includes('grayscale') || cs.includes('gray')) modes.push('grayscale');
+  if (cs.includes('binary') || cs.includes('lineart')) modes.push('blackwhite');
+  return modes.length > 0 ? modes : ['color', 'grayscale', 'blackwhite'];
+}
+
+function parseSources(txt: Record<string, string>): TScanSource[] {
+  const is = txt['is'] || '';
+  const sources: TScanSource[] = [];
+  if (is.includes('platen') || is.includes('flatbed') || !is) sources.push('flatbed');
+  if (is.includes('adf') && is.includes('duplex')) sources.push('adf-duplex');
+  else if (is.includes('adf')) sources.push('adf');
+  return sources.length > 0 ? sources : ['flatbed'];
+}