import type { RagMetadataFilters } from '../../../../lib/helpers/rag_metadata_filters';

/**
 * RAG Action Parameters
 */
export type RagActionParams =
  | {
      operation: 'upload_document';
      fileId: string;
      fileName?: string;
      contentType?: string;
      sync?: boolean;
      /**
       * Document Hub folder path (`parent/child`, no leading slash).
       * Stored on the RAG side for folder-scoped search. When omitted,
       * `uploadDocument` resolves it from the linked Hub document.
       */
      folderPath?: string;
    }
  | {
      operation: 'delete_document';
      fileId: string;
    }
  | {
      operation: 'search';
      query: string;
      fileIds: string[];
      topK?: number;
      similarityThreshold?: number;
      /**
       * Hierarchical Document Hub folder prefix filter
       * (`parent/child`, no leading slash). Narrowing-only — `fileIds`
       * stays the authorization boundary.
       */
      folderPath?: string;
      /**
       * Flat metadata pre-filters (scalar = equality, list = IN), e.g.
       * `{ department: 'legal', year: [2023, 2024] }`. Applied before
       * ranking on the RAG side.
       */
      metadataFilters?: RagMetadataFilters;
    }
  | {
      operation: 'get_chunks';
      fileId: string;
    };

/**
 * RAG Upload Result
 */
export interface RagUploadResult {
  /** Whether the request to RAG succeeded (enqueue + basic validation). */
  success: boolean;
  /** File storage ID that was uploaded to RAG. */
  fileId: string;
  /** Identifier returned by the RAG service for the ingested/queued document. */
  ragDocumentId?: string;
  /** Number of chunks created. For async ingestion this will typically be 0. */
  chunksCreated?: number;
  /** Time spent in the local HTTP call to the RAG service. */
  processingTimeMs?: number;
  /** Optional error message when the request fails before enqueue. */
  error?: string;
  /** Client-side timestamp when the upload finished (request-level). */
  timestamp: number;
  /** Total execution time of the Convex action step wrapping the upload. */
  executionTimeMs?: number;
}

/**
 * RAG Chunk Result
 */
export interface RagChunkResult {
  documentId: string;
  title: string | null;
  chunks: Array<{ index: number; content: string }>;
  totalChunks: number;
  executionTimeMs?: number;
}

/**
 * RAG Delete Result
 */
export interface RagDeleteResult {
  /** Whether the deletion was successful. */
  success: boolean;
  /** Number of documents deleted. */
  deletedCount: number;
  /** List of data IDs that were deleted from the RAG knowledge base. */
  deletedDataIds: Array<string>;
  /** Status message from the RAG service. */
  message: string;
  /** Time spent in the local HTTP call to the RAG service. */
  processingTimeMs?: number;
  /** Optional error message when the request fails. */
  error?: string;
  /** Client-side timestamp when the deletion finished. */
  timestamp: number;
  /** Total execution time of the Convex action step. */
  executionTimeMs?: number;
}
