Initial commit

frontend/src/types.ts

@@ -0,0 +1,292 @@
+/**
+ * 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 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 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;
+  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 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;
+  handwriting_style_clustering?: HandwritingStyleClusteringSettingsUpdate;
+  predefined_paths?: PredefinedPathEntry[];
+  predefined_tags?: PredefinedTagEntry[];
+  providers?: ProviderSettingsUpdate[];
+  tasks?: TaskSettingsUpdate;
+}