@ontos-ai/knowhere-sdk 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,668 @@
+import { Agent } from 'http';
+import { Agent as Agent$1 } from 'https';
+import { ReadStream } from 'fs';
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+/**
+ * Configuration options for the Knowhere client
+ */
+interface KnowhereOptions {
+    /** API authentication key (defaults to KNOWHERE_API_KEY env var) */
+    apiKey?: string;
+    /** API base URL (defaults to https://api.knowhereto.ai) */
+    baseURL?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+    /** Upload timeout in milliseconds (default: 600000) */
+    uploadTimeout?: number;
+    /** Maximum number of retry attempts (default: 5) */
+    maxRetries?: number;
+    /** Additional headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+    /** Custom HTTP agent for HTTP requests */
+    httpAgent?: Agent;
+    /** Custom HTTPS agent for HTTPS requests */
+    httpsAgent?: Agent$1;
+}
+
+/**
+ * Job status
+ */
+type JobStatus = 'pending' | 'waiting-file' | 'running' | 'converting' | 'done' | 'failed';
+/**
+ * Job creation response
+ */
+interface Job {
+    /** Unique job identifier */
+    jobId: string;
+    /** Current job status */
+    status: JobStatus;
+    /** Source type (file or url) */
+    sourceType: string;
+    /** Optional custom data identifier */
+    dataId?: string;
+    /** Job creation timestamp */
+    createdAt: Date;
+    /** Presigned URL for file upload (if sourceType is 'file') */
+    uploadUrl?: string;
+    /** Headers to include in upload request */
+    uploadHeaders?: Record<string, string>;
+    /** Upload URL expiration time in seconds */
+    expiresIn?: number;
+}
+/**
+ * Job error details
+ */
+interface JobError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Request ID for debugging */
+    requestId: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Job status response with full details
+ */
+interface JobResult {
+    /** Unique job identifier */
+    jobId: string;
+    /** Current job status */
+    status: JobStatus;
+    /** Source type (file or url) */
+    sourceType: string;
+    /** Optional custom data identifier */
+    dataId?: string;
+    /** Job creation timestamp */
+    createdAt: Date;
+    /** Processing progress information */
+    progress?: Record<string, unknown>;
+    /** Error details (if job failed) */
+    error?: JobError;
+    /** Result metadata */
+    result?: Record<string, unknown>;
+    /** Presigned URL to download result ZIP */
+    resultUrl?: string;
+    /** Result URL expiration timestamp */
+    resultUrlExpiresAt?: Date;
+    /** Original file name */
+    fileName?: string;
+    /** File extension */
+    fileExtension?: string;
+    /** Model used for parsing */
+    model?: string;
+    /** Whether OCR was enabled */
+    ocrEnabled?: boolean;
+    /** Processing duration in seconds */
+    durationSeconds?: number;
+    /** Credits consumed */
+    creditsSpent?: number;
+    /** Whether the job is in a terminal state (done or failed) */
+    readonly isTerminal: boolean;
+    /** Whether the job completed successfully */
+    readonly isDone: boolean;
+    /** Whether the job failed */
+    readonly isFailed: boolean;
+}
+
+/**
+ * Parsing model options
+ */
+type ParsingModel = 'base' | 'advanced';
+/**
+ * Document type options
+ */
+type DocType = 'auto' | 'pdf' | 'docx' | 'txt' | 'md';
+/**
+ * Parsing configuration parameters
+ */
+interface ParsingParams {
+    /** Parsing model to use (default: 'base') */
+    model?: ParsingModel;
+    /** Enable OCR for scanned documents (default: false) */
+    ocrEnabled?: boolean;
+    /** Knowledge base directory */
+    kbDir?: string;
+    /** Document type hint (default: 'auto') */
+    docType?: DocType;
+    /** Enable smart title parsing (default: false) */
+    smartTitleParse?: boolean;
+    /** Generate image summaries (default: false) */
+    summaryImage?: boolean;
+    /** Generate table summaries (default: false) */
+    summaryTable?: boolean;
+    /** Generate text summaries (default: false) */
+    summaryTxt?: boolean;
+    /** Additional fragment description */
+    addFragDesc?: string;
+}
+/**
+ * Webhook configuration
+ */
+interface WebhookConfig {
+    /** Webhook URL to notify on job completion */
+    url: string;
+}
+/**
+ * Job creation parameters
+ */
+interface CreateJobParams {
+    /** Source type: 'file' for upload, 'url' for remote document */
+    sourceType: 'file' | 'url';
+    /** Source URL (required if sourceType is 'url') */
+    sourceUrl?: string;
+    /** File name (required if sourceType is 'file') */
+    fileName?: string;
+    /** Optional custom data identifier */
+    dataId?: string;
+    /** Parsing configuration */
+    parsingParams?: ParsingParams;
+    /** Webhook configuration */
+    webhook?: WebhookConfig;
+}
+/**
+ * File upload parameters
+ */
+interface UploadParams {
+    /** File to upload (path, Buffer, Stream, or Uint8Array) */
+    file: string | Buffer | ReadStream | Uint8Array;
+    /** Upload progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Wait options for polling
+ */
+interface WaitOptions {
+    /** Polling interval in milliseconds (default: 10000) */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds (default: 1800000 = 30 minutes) */
+    pollTimeout?: number;
+    /** Progress callback */
+    onProgress?: (status: PollProgress) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Load options for result parsing
+ */
+interface LoadOptions {
+    /** Whether to verify ZIP checksum (default: true) */
+    verifyChecksum?: boolean;
+}
+/**
+ * High-level parse parameters
+ */
+interface ParseParams {
+    /** Source URL (mutually exclusive with file) */
+    url?: string;
+    /** File to parse (path, Buffer, Stream, or Uint8Array) */
+    file?: string | Buffer | ReadStream | Uint8Array;
+    /** File name (auto-inferred for file paths and fs.ReadStream with a path) */
+    fileName?: string;
+    /** Parsing model (default: 'base') */
+    model?: ParsingModel;
+    /** Enable OCR (default: false) */
+    ocr?: boolean;
+    /** Document type hint */
+    docType?: DocType;
+    /** Enable smart title parsing */
+    smartTitleParse?: boolean;
+    /** Generate image summaries */
+    summaryImage?: boolean;
+    /** Generate table summaries */
+    summaryTable?: boolean;
+    /** Generate text summaries */
+    summaryText?: boolean;
+    /** Custom data identifier */
+    dataId?: string;
+    /** Additional fragment description */
+    addFragDesc?: string;
+    /** Knowledge base directory */
+    kbDir?: string;
+    /** Polling interval in milliseconds */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds */
+    pollTimeout?: number;
+    /** Whether to verify ZIP checksum (default: true) */
+    verifyChecksum?: boolean;
+    /** Webhook configuration */
+    webhook?: WebhookConfig;
+    /** Upload progress callback */
+    onUploadProgress?: (progress: UploadProgress) => void;
+    /** Poll progress callback */
+    onPollProgress?: (status: PollProgress) => void;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Upload progress information
+ */
+interface UploadProgress {
+    /** Bytes uploaded */
+    loaded: number;
+    /** Total bytes (may be undefined for streams) */
+    total?: number;
+    /** Upload percentage (0-100) */
+    percent: number;
+}
+/**
+ * Polling progress information
+ */
+interface PollProgress {
+    /** Current job status */
+    status: JobStatus;
+    /** Elapsed time in seconds */
+    elapsedSeconds: number;
+    /** Current job result */
+    jobResult: JobResult;
+}
+
+/**
+ * Statistics about the parsed document
+ */
+interface Statistics {
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Number of text chunks */
+    textChunks: number;
+    /** Number of image chunks */
+    imageChunks: number;
+    /** Number of table chunks */
+    tableChunks: number;
+    /** Total number of pages (if applicable) */
+    totalPages?: number;
+}
+/**
+ * File index mapping chunk IDs to file paths
+ */
+interface FileIndex {
+    [chunkId: string]: string;
+}
+/**
+ * Manifest containing metadata about the parse result
+ */
+interface Manifest {
+    /** Manifest version */
+    version: string;
+    /** Job ID */
+    jobId: string;
+    /** Custom data ID */
+    dataId?: string;
+    /** Original source file name */
+    sourceFileName: string;
+    /** Processing completion date */
+    processingDate: Date;
+    /** Statistics */
+    statistics: Statistics;
+    /** File index */
+    files: FileIndex;
+}
+/**
+ * Base chunk properties
+ */
+interface BaseChunk {
+    /** Unique chunk identifier */
+    chunkId: string;
+    /** Chunk type */
+    type: 'text' | 'image' | 'table';
+    /** Main content */
+    content: string;
+    /** Relative path in ZIP */
+    path: string;
+}
+/**
+ * Text chunk
+ */
+interface TextChunk extends BaseChunk {
+    type: 'text';
+    /** Content length */
+    length: number;
+    /** Tokens or token count, depending on backend payload */
+    tokens?: number | string[];
+    /** Extracted keywords */
+    keywords?: string[];
+    /** Generated summary */
+    summary?: string;
+    /** Related chunk IDs */
+    relationships?: string[];
+}
+/**
+ * Image chunk
+ */
+interface ImageChunk extends BaseChunk {
+    type: 'image';
+    /** Content length */
+    length: number;
+    /** Relative file path in ZIP */
+    filePath: string;
+    /** Generated summary */
+    summary?: string;
+    /** Image data buffer */
+    data: Buffer;
+    /** Image format (derived from file extension) */
+    readonly format: string;
+    /** Save image to disk */
+    save(directory: string): Promise<string>;
+}
+/**
+ * Table chunk
+ */
+interface TableChunk extends BaseChunk {
+    type: 'table';
+    /** Content length */
+    length: number;
+    /** Relative file path in ZIP */
+    filePath: string;
+    /** Table type */
+    tableType?: string;
+    /** Generated summary */
+    summary?: string;
+    /** HTML representation */
+    html: string;
+    /** Save table HTML to disk */
+    save(directory: string): Promise<string>;
+}
+/**
+ * Union type of all chunk types
+ */
+type Chunk = TextChunk | ImageChunk | TableChunk;
+/**
+ * Complete parse result
+ */
+interface ParseResult {
+    /** Manifest metadata */
+    manifest: Manifest;
+    /** All chunks */
+    chunks: Chunk[];
+    /** Full document as Markdown (if available) */
+    fullMarkdown?: string;
+    /** Document hierarchy (if available) */
+    hierarchy?: unknown;
+    /** Raw ZIP buffer */
+    rawZip: Buffer;
+    /** Text chunks only */
+    readonly textChunks: TextChunk[];
+    /** Image chunks only */
+    readonly imageChunks: ImageChunk[];
+    /** Table chunks only */
+    readonly tableChunks: TableChunk[];
+    /** Job ID */
+    readonly jobId: string;
+    /** Statistics */
+    readonly statistics: Statistics;
+    /** Find a specific chunk by ID */
+    getChunk(chunkId: string): Chunk | undefined;
+    /** Save all results to a directory */
+    save(directory: string): Promise<string>;
+}
+
+interface HttpClientOptions {
+    baseURL: string;
+    apiKey: string;
+    timeout?: number;
+    uploadTimeout?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+    httpAgent?: Agent;
+    httpsAgent?: Agent$1;
+}
+/**
+ * HTTP client wrapper around axios with retry logic and error handling
+ */
+declare class HttpClient {
+    private axios;
+    private maxRetries;
+    private uploadTimeout;
+    private httpAgent?;
+    private httpsAgent?;
+    constructor(options: HttpClientOptions);
+    private setupInterceptors;
+    private handleError;
+    private getErrorObject;
+    private normalizeErrorData;
+    private decodeErrorPayload;
+    private getErrorMessage;
+    private getErrorCode;
+    private requestExternal;
+    /**
+     * GET request
+     */
+    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * PUT request (typically for uploads, no retry)
+     */
+    put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Download file as buffer
+     */
+    download(url: string, config?: AxiosRequestConfig): Promise<Buffer>;
+    /**
+     * Upload file with progress tracking
+     */
+    upload(url: string, data: unknown, options?: {
+        headers?: Record<string, string>;
+        onProgress?: (progress: {
+            loaded: number;
+            total?: number;
+            percent: number;
+        }) => void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Get the underlying axios instance
+     */
+    getAxiosInstance(): AxiosInstance;
+}
+
+/**
+ * Base class for all API resources
+ */
+declare abstract class BaseResource {
+    protected httpClient: HttpClient;
+    constructor(httpClient: HttpClient);
+}
+
+/**
+ * Jobs resource for managing parsing jobs
+ */
+declare class Jobs extends BaseResource {
+    private pendingUploadJobs;
+    /**
+     * Create a new parsing job
+     */
+    create(params: CreateJobParams): Promise<Job>;
+    /**
+     * Get job status
+     */
+    get(jobId: string): Promise<JobResult>;
+    /**
+     * Upload file for a job
+     */
+    upload(jobOrId: string | Job, params: UploadParams): Promise<void>;
+    /**
+     * Wait for job completion
+     */
+    wait(jobId: string, options?: WaitOptions): Promise<JobResult>;
+    /**
+     * Load parse result from completed job
+     */
+    load(jobResultOrIdOrUrl: JobResult | string, options?: LoadOptions): Promise<ParseResult>;
+    private isHttpUrl;
+    private resolveUploadJob;
+    private resolveLoadJobResult;
+}
+
+/**
+ * Main Knowhere SDK client
+ */
+declare class Knowhere {
+    /** Jobs resource for low-level API */
+    readonly jobs: Jobs;
+    private httpClient;
+    /**
+     * Create a new Knowhere client
+     */
+    constructor(options?: KnowhereOptions);
+    /**
+     * High-level API: Parse a document and return structured results
+     *
+     * @example
+     * ```typescript
+     * // Parse from URL
+     * const result = await client.parse({ url: 'https://example.com/doc.pdf' });
+     *
+     * // Parse from file
+     * const result = await client.parse({ file: './document.pdf' });
+     *
+     * // Parse with options
+     * const result = await client.parse({
+     *   url: 'https://example.com/doc.pdf',
+     *   model: 'advanced',
+     *   ocr: true,
+     *   onUploadProgress: (p) => console.log(`${p.percent}%`),
+     * });
+     * ```
+     */
+    parse(params: ParseParams): Promise<ParseResult>;
+}
+
+declare const VERSION = "0.1.0";
+
+/**
+ * Base error class for all Knowhere SDK errors
+ */
+declare class KnowhereError extends Error {
+    constructor(message: string);
+}
+/**
+ * Network-related errors
+ */
+declare class NetworkError extends KnowhereError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Request timeout error
+ */
+declare class TimeoutError extends NetworkError {
+    constructor(message?: string);
+}
+/**
+ * Polling timeout error
+ */
+declare class PollingTimeoutError extends KnowhereError {
+    readonly elapsedMs: number;
+    constructor(message: string | undefined, elapsedMs: number);
+}
+/**
+ * ZIP checksum verification failed
+ */
+declare class ChecksumError extends KnowhereError {
+    readonly expected?: string | undefined;
+    readonly actual?: string | undefined;
+    constructor(message?: string, expected?: string | undefined, actual?: string | undefined);
+}
+/**
+ * Raised when the caller provides invalid arguments
+ */
+declare class ValidationError extends KnowhereError {
+    constructor(message: string);
+}
+/**
+ * Raised when an object is in an unexpected state for the operation
+ */
+declare class InvalidStateError extends KnowhereError {
+    constructor(message: string);
+}
+
+/**
+ * Base class for all API errors
+ */
+declare class APIError extends KnowhereError {
+    readonly statusCode: number;
+    readonly code?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, code?: string | undefined, requestId?: string | undefined, details?: Record<string, unknown> | undefined, body?: unknown | undefined);
+}
+/**
+ * 400 Bad Request
+ */
+declare class BadRequestError extends APIError {
+    constructor(message: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 401 Unauthorized
+ */
+declare class AuthenticationError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 402 Payment Required
+ */
+declare class PaymentRequiredError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 403 Forbidden
+ */
+declare class PermissionDeniedError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 404 Not Found
+ */
+declare class NotFoundError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 409 Conflict
+ */
+declare class ConflictError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 429 Rate Limit Exceeded
+ */
+declare class RateLimitError extends APIError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown, retryAfter?: number | undefined);
+}
+/**
+ * 500 Internal Server Error
+ */
+declare class InternalServerError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 502/503 Service Unavailable
+ */
+declare class ServiceUnavailableError extends APIError {
+    constructor(message?: string, statusCode?: number, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+/**
+ * 504 Gateway Timeout
+ */
+declare class GatewayTimeoutError extends APIError {
+    constructor(message?: string, code?: string, requestId?: string, details?: Record<string, unknown>, body?: unknown);
+}
+
+/**
+ * Job execution failed
+ */
+declare class JobFailedError extends KnowhereError {
+    readonly code: string;
+    readonly jobResult: JobResult;
+    constructor(message: string, code: string, jobResult: JobResult);
+}
+
+export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default };