@squidcloud/client/dist/internal-common/src/public-types/extraction.public-types.d.ts

A typescript implementation of the Squid client

/**
 * The extraction method to use for processing documents.
 */
export type DocumentExtractionMethod = 'mistral_ocr' | 'legacy' | 'amazon_textract';
/**
 * Options for customizing how data is extracted from a document.
 */
export interface ExtractDataFromDocumentOptions {
    /**
     * Minimum width/height (in pixels) of images to extract. Smaller images will be ignored.
     */
    imageMinSizePixels?: number;
    /**
     * Whether to extract embedded images from the document.
     */
    extractImages?: boolean;
    /**
     * Specific page indexes to extract from the document (0-based). If omitted, all pages are extracted.
     */
    pageIndexes?: number[];
    /**
     * The preferred method for extracting data from the document.
     */
    preferredExtractionMethod?: DocumentExtractionMethod;
    /**
     * Whether Squid keeps or discards the original file.
     *
     * Keeping the original file allows reprocessing and the ability for the user to download it later.
     *
     * Defaults to false.
     */
    discardOriginalFile?: boolean;
    /**
     * Format hint for text-based extraction (markdown / HTML). When omitted, the format is detected from
     * the content. Only consulted by extractors that handle text input.
     */
    textFormat?: 'auto' | 'markdown' | 'html' | 'plain';
    /**
     * Whether to read document-level properties (title/author/dates) from the source container and
     * return them as `documentMetadata`. Off by default: container parsing has a real per-file cost
     * (zip/PDF re-parse), so callers opt in only when the owning knowledge base declares metadata fields.
     *
     * Honored only by file-based extraction (which owns the original buffer for every format);
     * URL-based extraction ignores it and never returns `documentMetadata`.
     */
    collectDocumentMetadata?: boolean;
}
/**
 * Request payload for extracting data from a document via URL.
 */
export interface ExtractDataFromDocumentUrlRequest {
    /**
     * The publicly accessible URL pointing to the document file.
     */
    url: string;
    /**
     * Optional parameters to control how the extraction is performed.
     */
    options?: ExtractDataFromDocumentOptions;
}
/**
 * Request payload for extracting data from a document file (uploaded directly).
 */
export interface ExtractDataFromDocumentFileRequest {
    /**
     * Optional parameters to control how the extraction is performed.
     */
    options?: ExtractDataFromDocumentOptions;
}
/**
 * Representation of an image extracted from a document, for use in generated content.
 */
export interface ExtractDataFromDocumentImage {
    /**
     * A unique identifier for the image.
     */
    id: string;
    /**
     * A placeholder or marker in the content where this image should be inserted.
     */
    textToReplaceInContent: string;
    /**
     * The base64-encoded image data, prefixed with its MIME type (e.g., data:image/png;base64,...).
     */
    imageBase64Url: string;
}
/**
 * A single extracted page from the document, including structured content and images.
 */
export interface ExtractDataFromDocumentPage {
    /**
     * Optional title for the page (e.g., sheet name or section heading).
     */
    title?: string;
    /**
     * Page index in the original document (0-based).
     */
    index: number;
    /**
     * Extracted textual content or CSV representation of the page.
     */
    content: string;
    /**
     * List of images extracted from this page.
     */
    images: Array<ExtractDataFromDocumentImage>;
}
/**
 * The full result of extracting data from a document, including all pages and any extracted images.
 */
export interface ExtractDataFromDocumentResponse {
    /**
     * Array of pages containing extracted data.
     */
    pages: Array<ExtractDataFromDocumentPage>;
    /**
     * Path to the original file in cloud storage, if applicable.
     */
    longTermStoragePath?: string;
    /**
     * Document-level metadata extracted from the source container (best-effort). Present only when the
     * extractor was able to read it.
     */
    documentMetadata?: DocumentMetadata;
}
/**
 * Create PDF request type.
 */
export type CreatePdfType = 'html' | 'url';
/** The type of output options to apply when creating a PDF document. */
export type CreatePdfOutputOptionsType = 'format' | 'dimensions';
/** Base interface for PDF output options. This is used to define the type of output options. */
export interface BaseCreatePdfOutputOptions {
    /** The type of output options, either 'format' or 'dimensions'. */
    type: CreatePdfOutputOptionsType;
}
/** Output options by format */
export interface CreatePdfOutputFormatOptions extends BaseCreatePdfOutputOptions {
    /** The type of output options, always 'format' for this interface. */
    type: 'format';
    /** The type of formatting, always 'format' for this interface. */
    format: 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6';
}
/** Output options by custom dimensions */
export interface CreatePdfOutputDimensionsOptions extends BaseCreatePdfOutputOptions {
    /** The type of formatting, always 'dimensions' for this interface. */
    type: 'dimensions';
    /** The width of the PDF document in pixels. */
    width: number;
    /** The height of the PDF document in pixels. */
    height: number;
}
/** Combined formatting options for creating a PDF document. */
export type CreatePdfOutputOptions = CreatePdfOutputFormatOptions | CreatePdfOutputDimensionsOptions;
/**
 * Base request for creating a PDF document.
 */
export interface BaseCreatePdfRequest {
    /**
     * The type of PDF creation to perform, either from HTML or a URL.
     */
    type: CreatePdfType;
    /** The formatting options for the PDF document. Can be either a predefined format (like 'letter') or custom dimensions. */
    outputOptions?: CreatePdfOutputOptions;
    /** Optional title for the PDF document. */
    title?: string;
}
/**
 * Request payload for creating a PDF from a URL.
 */
export interface CreatePdfFromUrlRequest extends BaseCreatePdfRequest {
    /** The type of PDF creation, always 'url' for this request. */
    type: 'url';
    /**
     * The URL of the webpage to convert into a PDF.
     */
    url: string;
}
/**
 * Request payload for creating a PDF from HTML content.
 */
export interface CreatePdfFromHtmlRequest extends BaseCreatePdfRequest {
    /** The type of PDF creation, always 'html' for this request. */
    type: 'html';
    /** The HTML content to convert into a PDF. Should not contain <html>, <body>, <head>, should just include the inner HTML */
    innerHtml: string;
    /** Optional URL for CSS styles to apply to the HTML content. */
    cssUrl?: string;
}
/**
 * Combined request type for creating a PDF, which can be either from a URL or HTML content.
 */
export type CreatePdfRequest = CreatePdfFromUrlRequest | CreatePdfFromHtmlRequest;
/**
 * Response type for the PDF creation operation, containing the URL of the generated PDF.
 */
export interface CreatePdfResponse {
    /** The publicly accessible URL where the generated PDF can be downloaded. */
    url: string;
    /** The generated filename. */
    fileName?: string;
}
/**
 * Document-level properties read from the source container during extraction. Every field is optional
 * and best-effort: when a container does not expose a property (or parsing fails) the field is simply
 * absent. Consumed by schema-driven metadata extraction as the deterministic source for matching
 * knowledge-base `metadataFields` before falling back to LLM extraction.
 * @category AI
 */
export interface DocumentMetadata {
    /** Document title (e.g. OOXML `dc:title`, PDF `/Title`, front-matter `title`, `<title>`). */
    docTitle?: string;
    /** Document author (e.g. OOXML `dc:creator`, PDF `/Author`, front-matter / `<meta author>`). */
    docAuthor?: string;
    /** Creation timestamp, ISO 8601. */
    docCreatedAt?: string;
    /** Last-modified timestamp, ISO 8601. */
    docModifiedAt?: string;
    /** Source document type: `pdf` | `docx` | `pptx` | `xlsx` | `md` | `html` | `txt`. */
    docType?: string;
}