/**
 * @file companionTool.ts - Type definitions for integration with the RWP Companion desktop application.
 * The companion tool connects to the Rapid Workplace web application over a local WebSocker and provides hardware-dependent features such as document scanning (scan insert) and image cleanup operations.
 * Communication follows a request/response pattern:
 * - The web client sends a {@link CompanionRequest} containing a base64-encoded PDF page and the desired operation
 * - The companion tool returns a {@link CompanionResponse} with the processed PDF data and a status message
 */

/** High-level mode the Companion should operate in. */
export type OperationMode = 'scan' | 'cleanup';

/**
 * Specific automatic image processing operations the Companion can
 * perform. Used when {@link OperationMode} is `'cleanup'`, or `'scan'`
 * for the initial scan acquisition.
 */
export type AutomaticOperation =
  | 'scan'
  | 'border_crop'
  | 'line_removal'
  | 'deskew'
  | 'shear'
  | 'erode'
  | 'dilate'
  | 'blob_removal'
  | 'zoom_smooth';

// Scan mode
/** Status string returned by the Companion after a successful scan insert */
export type ScanInsertStatus = 'Scans inserted';
/** Where scanned pages should be inserted relative to the current page */
export type ScanInsertMode = 'before' | 'after' | 'end';

// Image cleanup mode
/** Status string returned by the Companion after a successful image cleanup */
export type ImageCleanupStatus = 'Page updated';

/**
 * Payload sent to the RWP Companion over the WebSocket connection.
 * Contains the PDF page data and the requested operation.
 */
export type CompanionRequest = {
  /** Base64-encoded PDF data for the page to be processed */
  pdfBase64: string;

  /** Zero-based index of the page within the document */
  pageIndex: number;

  /** Whether this is a scan or cleanup operation */
  operationMode: OperationMode;

  /** Optional specific cleanup operation; omitted for a plain scan */
  automaticOperation?: AutomaticOperation;
};

/**
 * Payload received from the RWP Companion after processing completes.
 */
export type CompanionResponse = {
  /** Indicates the outcome of the operation */
  status: ScanInsertStatus | ImageCleanupStatus;

  /** Base64-encoded PDF data with the processed result */
  pdfBase64: string;
};
