import type { Download } from "@intuned/browser";
import type { JsonSchema } from "@intuned/browser/ai";
import type { z } from "zod";

/**
 * A file source provided as a base64-encoded string.
 *
 * @interface
 * @property base64 - The base64-encoded string of the file data.
 */
export interface Base64Source {
  base64: string;
}

/**
 * A file source provided as a URL. The URL is forwarded to the backend, which
 * fetches the file.
 *
 * @interface
 * @property url - The URL of the file.
 */
export interface UrlSource {
  url: string;
}

/**
 * A file source provided as a Node.js Buffer.
 *
 * @interface
 * @property buffer - The buffer data of the file.
 */
export interface BufferSource {
  buffer: Buffer;
}

/**
 * A file source provided as a browser download. Accepts the return value of the
 * `downloadFile` helper from `@intuned/browser` (a Playwright `Download`),
 * either already awaited or as the still-pending promise. The download is read
 * into a buffer before the operation runs.
 *
 * @interface
 * @property download - A Playwright `Download`, or a promise resolving to one.
 */
export interface DownloadSource {
  download: Download | Promise<Download>;
}

/**
 * The source of a file's contents. Exactly one source key must be provided.
 *
 * @type
 */
export type FileSource =
  | Base64Source
  | UrlSource
  | BufferSource
  | DownloadSource;

type PdfMetadata = { type: "pdf"; pages?: number[] };
type ImageMetadata = { type: "image" };
type SpreadsheetMetadata = { type: "spreadsheet"; sheetName: string };
type DocumentMetadata = { type: "document"; pages?: number[] };

/**
 * The file metadata (type discriminator and type-specific extras), without a
 * source. Crossed with a single {@link FileSource} to form a complete file.
 *
 * @type
 */
export type FileMetadata =
  | PdfMetadata
  | ImageMetadata
  | SpreadsheetMetadata
  | DocumentMetadata;

/**
 * Represents a PDF file.
 *
 * @interface
 * @property type - The type of the file, which is always "pdf".
 * @property [pages] - Optional. The specific pages of the PDF to process. If not provided, all pages are included.
 */
export type PdfFile = PdfMetadata & FileSource;

/**
 * Represents an image file (for example a PNG or JPEG).
 *
 * @interface
 * @property type - The type of the file, which is always "image".
 */
export type ImageFile = ImageMetadata & FileSource;

/**
 * Represents a spreadsheet file. For now, only `.xlsx` Excel spreadsheets are supported.
 *
 * @interface
 * @property type - The type of the file, which is always "spreadsheet".
 * @property sheetName - The name of the sheet to process.
 */
export type SpreadsheetFile = SpreadsheetMetadata & FileSource;

/**
 * Represents a document file. For now, only `.docx` Word files are supported.
 *
 * @interface
 * @property type - The type of the file, which is always "document".
 * @property [pages] - Optional. The specific pages of the document to process. If not provided, all pages are included.
 */
export type DocumentFile = DocumentMetadata & FileSource;

/**
 * The canonical file object accepted by the file operations. It is a
 * discriminated union on the `type` property, and carries exactly one source
 * key (`base64`, `url`, `buffer`, or `download`).
 *
 * @type
 */
export type File = PdfFile | ImageFile | SpreadsheetFile | DocumentFile;

/**
 * Options accepted by the file operations.
 *
 * @interface
 * @property [label] - Optional. A label for this operation, used for billing and monitoring.
 */
export interface FileOperationOptions {
  label?: string;
}

/**
 * Represents a table extracted from a file.
 *
 * @interface
 * @property pageNumber - The page number the table was found on.
 * @property title - The title of the table, if one was found.
 * @property content - A two dimensional array containing the table cell values.
 */
export interface ExtractedTable {
  pageNumber: number;
  title: string | null;
  content: (string | null)[][];
}

/**
 * Options accepted by {@link extractStructuredDataFromFile}.
 *
 * @interface
 * @property dataSchema - The schema describing the data to extract. Accepts a JSON Schema object or a zod schema.
 * @property [label] - Optional. A label for this operation, used for billing and monitoring. Applied to the underlying file-to-markdown conversion.
 * @property [prompt] - Optional. An additional natural-language instruction to guide the extraction.
 * @property [model] - Optional. The model to use for extraction. Defaults to the browser SDK's default.
 * @property [maxRetries] - Optional. The maximum number of retries if extraction fails to produce valid data.
 * @property [enableCache] - Optional. Whether to reuse cached extraction results. Defaults to the browser SDK's default.
 * @property [apiKey] - Optional. An API key override for the extraction model provider.
 */
export interface ExtractStructuredDataOptions {
  dataSchema: JsonSchema | z.ZodSchema;
  label?: string;
  prompt?: string;
  model?: string;
  maxRetries?: number;
  enableCache?: boolean;
  apiKey?: string;
}

/**
 * Extracts markdown from a file.
 *
 * @param file - The file to process. Provide exactly one source: `base64`, `url`, `buffer`, or `download`.
 * @param [options] - Optional. Options for the operation.
 * @param [options.label] - Optional. A label for this operation, used for billing and monitoring.
 * @returns {Promise<string>} A promise that resolves to the markdown content as a string.
 *
 * @example
 * ```typescript URL source
 * import { extractMarkdownFromFile } from "@intuned/files";
 *
 * const markdown = await extractMarkdownFromFile({
 *   type: "pdf",
 *   url: "<file url>",
 *   // pages is optional; omit it to include all pages
 *   pages: [1, 2],
 * }, {
 *   label: "convert_invoice",
 * });
 *
 * console.log(markdown);
 * ```
 *
 * @example
 * ```typescript Download source
 * import { extractMarkdownFromFile } from "@intuned/files";
 * import { downloadFile } from "@intuned/browser";
 *
 * const markdown = await extractMarkdownFromFile({
 *   type: "pdf",
 *   download: downloadFile({ page, trigger }),
 * });
 *
 * console.log(markdown);
 * ```
 */
export declare function extractMarkdownFromFile(
  file: FileMetadata & Base64Source,
  options?: FileOperationOptions
): Promise<string>;
export declare function extractMarkdownFromFile(
  file: FileMetadata & UrlSource,
  options?: FileOperationOptions
): Promise<string>;
export declare function extractMarkdownFromFile(
  file: FileMetadata & BufferSource,
  options?: FileOperationOptions
): Promise<string>;
export declare function extractMarkdownFromFile(
  file: FileMetadata & DownloadSource,
  options?: FileOperationOptions
): Promise<string>;

/**
 * Extracts tables from a file.
 *
 * @param file - The file to extract tables from. Provide exactly one source: `base64`, `url`, `buffer`, or `download`.
 * @param [options] - Optional. Options for the operation.
 * @param [options.label] - Optional. A label for this operation, used for billing and monitoring.
 * @returns {Promise<Array<ExtractedTable>>} A promise that resolves to an array of extracted tables.
 *
 * @example
 * ```typescript URL source
 * import { extractTablesFromFile } from "@intuned/files";
 *
 * const tables = await extractTablesFromFile({
 *   type: "pdf",
 *   url: "<file url>",
 *   // pages is optional; omit it to include all pages
 *   pages: [1, 2],
 * }, {
 *   label: "extract_tables",
 * });
 *
 * console.log(tables);
 * ```
 *
 * @example
 * ```typescript Download source
 * import { extractTablesFromFile } from "@intuned/files";
 * import { downloadFile } from "@intuned/browser";
 *
 * const tables = await extractTablesFromFile({
 *   type: "pdf",
 *   download: downloadFile({ page, trigger }),
 * });
 *
 * console.log(tables);
 * ```
 */
export declare function extractTablesFromFile(
  file: FileMetadata & Base64Source,
  options?: FileOperationOptions
): Promise<Array<ExtractedTable>>;
export declare function extractTablesFromFile(
  file: FileMetadata & UrlSource,
  options?: FileOperationOptions
): Promise<Array<ExtractedTable>>;
export declare function extractTablesFromFile(
  file: FileMetadata & BufferSource,
  options?: FileOperationOptions
): Promise<Array<ExtractedTable>>;
export declare function extractTablesFromFile(
  file: FileMetadata & DownloadSource,
  options?: FileOperationOptions
): Promise<Array<ExtractedTable>>;

/**
 * Extracts structured data from a file against a schema.
 *
 * The file is first converted to markdown, and then the markdown is passed to
 * the structured-data extractor from `@intuned/browser`. This method therefore
 * requires the optional peer dependency `@intuned/browser` to be installed; it
 * is loaded lazily and throws a clear error at call time if it is missing. The
 * other file operations do not depend on it.
 *
 * @param file - The file to extract data from. Provide exactly one source: `base64`, `url`, `buffer`, or `download`.
 * @param options - Options for the operation. `dataSchema` is required.
 * @param options.dataSchema - The schema describing the data to extract. Accepts a JSON Schema object or a zod schema.
 * @param [options.label] - Optional. A label for this operation, used for billing and monitoring.
 * @param [options.prompt] - Optional. An additional natural-language instruction to guide the extraction.
 * @param [options.model] - Optional. The model to use for extraction.
 * @param [options.maxRetries] - Optional. The maximum number of retries if extraction fails to produce valid data.
 * @param [options.enableCache] - Optional. Whether to reuse cached extraction results.
 * @param [options.apiKey] - Optional. An API key override for the extraction model provider.
 * @returns {Promise<any>} A promise that resolves to the extracted data, shaped by `dataSchema`.
 *
 * @example
 * ```typescript URL source
 * import { extractStructuredDataFromFile } from "@intuned/files";
 *
 * const data = await extractStructuredDataFromFile({
 *   type: "pdf",
 *   url: "<file url>",
 * }, {
 *   dataSchema: {
 *     type: "object",
 *     properties: {
 *       invoiceNumber: { type: "string" },
 *       total: { type: "number" },
 *     },
 *     required: ["invoiceNumber", "total"],
 *   },
 *   label: "extract_invoice",
 * });
 *
 * console.log(data);
 * ```
 *
 * @example
 * ```typescript zod schema
 * import { extractStructuredDataFromFile } from "@intuned/files";
 * import { z } from "zod";
 *
 * const data = await extractStructuredDataFromFile({
 *   type: "pdf",
 *   url: "<file url>",
 * }, {
 *   dataSchema: z.object({
 *     invoiceNumber: z.string(),
 *     total: z.number(),
 *   }),
 * });
 * ```
 */
export declare function extractStructuredDataFromFile(
  file: FileMetadata & Base64Source,
  options: ExtractStructuredDataOptions
): Promise<any>;
export declare function extractStructuredDataFromFile(
  file: FileMetadata & UrlSource,
  options: ExtractStructuredDataOptions
): Promise<any>;
export declare function extractStructuredDataFromFile(
  file: FileMetadata & BufferSource,
  options: ExtractStructuredDataOptions
): Promise<any>;
export declare function extractStructuredDataFromFile(
  file: FileMetadata & DownloadSource,
  options: ExtractStructuredDataOptions
): Promise<any>;