ledgerdock/frontend/src/types.ts

/**
 * Shared TypeScript API contracts used by frontend components.
 */

/**
 * Enumerates backend document lifecycle states.
 */
export type DocumentStatus = 'queued' | 'processed' | 'unsupported' | 'error' | 'trashed';

/**
 * Represents one document row returned by backend APIs.
 */
export interface DmsDocument {
  id: string;
  original_filename: string;
  source_relative_path: string;
  mime_type: string;
  extension: string;
  size_bytes: number;
  sha256: string;
  logical_path: string;
  suggested_path: string | null;
  image_text_type: string | null;
  handwriting_style_id: string | null;
  tags: string[];
  suggested_tags: string[];
  status: DocumentStatus;
  preview_available: boolean;
  is_archive_member: boolean;
  archived_member_path: string | null;
  parent_document_id: string | null;
  replaces_document_id: string | null;
  created_at: string;
  processed_at: string | null;
}

/**
 * Represents full document detail payload including extracted text and metadata.
 */
export interface DmsDocumentDetail extends DmsDocument {
  extracted_text: string;
  metadata_json: Record<string, unknown>;
}

/**
 * Represents paginated document list payload.
 */
export interface DocumentListResponse {
  total: number;
  items: DmsDocument[];
}

/**
 * Represents search result payload.
 */
export interface SearchResponse {
  total: number;
  items: DmsDocument[];
}

/**
 * Represents one authenticated user identity returned by backend auth endpoints.
 */
export interface AuthUser {
  id: string;
  username: string;
  role: 'admin' | 'user';
}

/**
 * Represents active authentication session metadata.
 */
export interface AuthSessionInfo {
  user: AuthUser;
  expires_at: string;
}

/**
 * Represents login response payload with issued bearer token and session metadata.
 */
export interface AuthLoginResponse extends AuthSessionInfo {
  access_token: string;
  token_type: 'bearer';
}

/**
 * Represents distinct document type values available for filter controls.
 */
export interface TypeListResponse {
  types: string[];
}

/**
 * Represents one processing pipeline event entry returned by the backend.
 */
export interface ProcessingLogEntry {
  id: number;
  created_at: string;
  level: string;
  stage: string;
  event: string;
  document_id: string | null;
  document_filename: string | null;
  provider_id: string | null;
  model_name: string | null;
  prompt_text: string | null;
  response_text: string | null;
  payload_json: Record<string, unknown>;
}

/**
 * Represents paginated processing log response payload.
 */
export interface ProcessingLogListResponse {
  total: number;
  items: ProcessingLogEntry[];
}

/**
 * Represents upload conflict information.
 */
export interface UploadConflict {
  original_filename: string;
  sha256: string;
  existing_document_id: string;
}

/**
 * Represents upload response payload.
 */
export interface UploadResponse {
  uploaded: DmsDocument[];
  conflicts: UploadConflict[];
}

/**
 * Represents one model provider binding served by the backend.
 */
export interface ProviderSettings {
  id: string;
  label: string;
  provider_type: string;
  base_url: string;
  timeout_seconds: number;
  api_key_set: boolean;
  api_key_masked: string;
}

/**
 * Represents OCR task settings served by the backend.
 */
export interface OcrTaskSettings {
  enabled: boolean;
  provider_id: string;
  model: string;
  prompt: string;
}

/**
 * Represents summarization task settings served by the backend.
 */
export interface SummaryTaskSettings {
  enabled: boolean;
  provider_id: string;
  model: string;
  prompt: string;
  max_input_tokens: number;
}

/**
 * Represents routing task settings served by the backend.
 */
export interface RoutingTaskSettings {
  enabled: boolean;
  provider_id: string;
  model: string;
  prompt: string;
  neighbor_count: number;
  neighbor_min_similarity: number;
  auto_apply_confidence_threshold: number;
  auto_apply_neighbor_similarity_threshold: number;
  neighbor_path_override_enabled: boolean;
  neighbor_path_override_min_similarity: number;
  neighbor_path_override_min_gap: number;
  neighbor_path_override_max_confidence: number;
}

/**
 * Represents default upload destination and tags.
 */
export interface UploadDefaultsSettings {
  logical_path: string;
  tags: string[];
}

/**
 * Represents display preferences for document listings.
 */
export interface DisplaySettings {
  cards_per_page: number;
  log_typing_animation_enabled: boolean;
}

/**
 * Represents retention targets used when trimming persisted processing logs.
 */
export interface ProcessingLogRetentionSettings {
  keep_document_sessions: number;
  keep_unbound_entries: number;
}

/**
 * Represents one predefined logical path and discoverability scope.
 */
export interface PredefinedPathEntry {
  value: string;
  global_shared: boolean;
}

/**
 * Represents one predefined tag and discoverability scope.
 */
export interface PredefinedTagEntry {
  value: string;
  global_shared: boolean;
}

/**
 * Represents handwriting-style clustering settings for Typesense image embeddings.
 */
export interface HandwritingStyleClusteringSettings {
  enabled: boolean;
  embed_model: string;
  neighbor_limit: number;
  match_min_similarity: number;
  bootstrap_match_min_similarity: number;
  bootstrap_sample_size: number;
  image_max_side: number;
}

/**
 * Represents all task-level settings served by the backend.
 */
export interface TaskSettings {
  ocr_handwriting: OcrTaskSettings;
  summary_generation: SummaryTaskSettings;
  routing_classification: RoutingTaskSettings;
}

/**
 * Represents runtime settings served by the backend.
 */
export interface AppSettings {
  upload_defaults: UploadDefaultsSettings;
  display: DisplaySettings;
  processing_log_retention: ProcessingLogRetentionSettings;
  handwriting_style_clustering: HandwritingStyleClusteringSettings;
  predefined_paths: PredefinedPathEntry[];
  predefined_tags: PredefinedTagEntry[];
  providers: ProviderSettings[];
  tasks: TaskSettings;
}

/**
 * Represents provider settings update input payload.
 */
export interface ProviderSettingsUpdate {
  id: string;
  label: string;
  provider_type: string;
  base_url: string;
  timeout_seconds: number;
  api_key?: string;
  clear_api_key?: boolean;
}

/**
 * Represents task settings update input payload.
 */
export interface TaskSettingsUpdate {
  ocr_handwriting?: Partial<OcrTaskSettings>;
  summary_generation?: Partial<SummaryTaskSettings>;
  routing_classification?: Partial<RoutingTaskSettings>;
}

/**
 * Represents upload defaults update input payload.
 */
export interface UploadDefaultsSettingsUpdate {
  logical_path?: string;
  tags?: string[];
}

/**
 * Represents display settings update input payload.
 */
export interface DisplaySettingsUpdate {
  cards_per_page?: number;
  log_typing_animation_enabled?: boolean;
}

/**
 * Represents processing-log retention update payload.
 */
export interface ProcessingLogRetentionSettingsUpdate {
  keep_document_sessions?: number;
  keep_unbound_entries?: number;
}

/**
 * Represents handwriting-style clustering settings update payload.
 */
export interface HandwritingStyleClusteringSettingsUpdate {
  enabled?: boolean;
  embed_model?: string;
  neighbor_limit?: number;
  match_min_similarity?: number;
  bootstrap_match_min_similarity?: number;
  bootstrap_sample_size?: number;
  image_max_side?: number;
}

/**
 * Represents app settings update payload sent to backend.
 */
export interface AppSettingsUpdate {
  upload_defaults?: UploadDefaultsSettingsUpdate;
  display?: DisplaySettingsUpdate;
  processing_log_retention?: ProcessingLogRetentionSettingsUpdate;
  handwriting_style_clustering?: HandwritingStyleClusteringSettingsUpdate;
  predefined_paths?: PredefinedPathEntry[];
  predefined_tags?: PredefinedTagEntry[];
  providers?: ProviderSettingsUpdate[];
  tasks?: TaskSettingsUpdate;
}