@ontos-ai/knowhere-sdk 2.0.0 → 2.1.1

package/dist/index.d.ts

@@ -118,176 +118,6 @@ interface JobResult {
     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;
-}
-/**
- * Client-provided display metadata copied onto the published document.
- */
-type DocumentMetadata = Record<string, unknown>;
-/**
- * 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;
-    /** Retrieval namespace for the canonical document */
-    namespace?: string;
-    /** Existing document identifier when updating a published document */
-    documentId?: string;
-    /** Display metadata to copy onto the published document */
-    documentMetadata?: DocumentMetadata;
-    /** 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 */
-    summaryTxt?: boolean;
-    /** Custom data identifier */
-    dataId?: string;
-    /** Retrieval namespace for the canonical document */
-    namespace?: string;
-    /** Existing document identifier when updating a published document */
-    documentId?: string;
-    /** Display metadata to copy onto the published document */
-    documentMetadata?: DocumentMetadata;
-    /** 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
  */
@@ -469,6 +299,8 @@ interface ImageChunk extends BaseChunk {
     type: 'image';
     /** Relative file path in ZIP */
     filePath: string;
+    /** Application-owned or server-provided display URL for the image asset. */
+    assetUrl?: string;
     /** Image data buffer */
     data: Buffer;
     /** Image format (derived from file extension) */
@@ -483,65 +315,575 @@ interface TableChunk extends BaseChunk {
     type: 'table';
     /** Relative file path in ZIP */
     filePath: string;
+    /** Application-owned or server-provided display URL for the table asset. */
+    assetUrl?: string;
     /** HTML representation */
     html: string;
     /** Save table HTML to disk */
     save(directory: string): Promise<string>;
 }
 /**
- * Page chunk
+ * Page chunk
+ */
+interface PageChunk extends BaseChunk {
+    type: 'page';
+}
+/**
+ * Union type of all chunk types
+ */
+type Chunk = TextChunk | ImageChunk | TableChunk | PageChunk;
+/**
+ * Complete parse result
+ */
+interface ParseResult {
+    /** Manifest metadata */
+    manifest: Manifest;
+    /** All chunks */
+    chunks: Chunk[];
+    /** Document navigation tree from doc_nav.json (current worker output) */
+    docNav?: DocNav;
+    /** Full document as Markdown (if available) */
+    fullMarkdown?: string;
+    /** Raw ZIP buffer */
+    rawZip: Buffer;
+    /** @deprecated Current worker no longer emits chunks_slim.json */
+    chunksSlim?: SlimChunk[];
+    /** @deprecated Current worker no longer emits hierarchy.json */
+    hierarchy?: unknown;
+    /** @deprecated Table-of-contents hierarchy hints (if available) */
+    tocHierarchies?: unknown;
+    /** @deprecated Knowledge-base CSV export (if available) */
+    kbCsv?: string;
+    /** @deprecated Pre-rendered hierarchy HTML view (if available) */
+    hierarchyViewHtml?: string;
+    /** Text chunks only */
+    readonly textChunks: TextChunk[];
+    /** Image chunks only */
+    readonly imageChunks: ImageChunk[];
+    /** Table chunks only */
+    readonly tableChunks: TableChunk[];
+    /** Page chunks only */
+    readonly pageChunks: PageChunk[];
+    /** Job ID */
+    readonly jobId: string;
+    /** Effective retrieval namespace when loaded from a job result */
+    namespace?: string;
+    /** Canonical document identifier when loaded from a job result */
+    documentId?: 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>;
+}
+
+/**
+ * Canonical document state returned by document lifecycle endpoints.
+ */
+interface Document {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current lifecycle status */
+    status: string;
+    /** Current published job result identifier */
+    currentJobResultId?: string;
+    /** Original source file name */
+    sourceFileName?: string;
+    /** Client-provided display metadata copied from the publishing job */
+    documentMetadata?: Record<string, unknown>;
+    /** Document creation timestamp */
+    createdAt?: Date;
+    /** Last update timestamp */
+    updatedAt?: Date;
+    /** Archive timestamp, when archived */
+    archivedAt?: Date;
+}
+/**
+ * Pagination metadata returned by document list endpoints.
+ */
+interface DocumentListPagination {
+    /** Current page number */
+    page: number;
+    /** Number of items requested per page */
+    pageSize: number;
+    /** Total matching documents */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Query parameters for GET /v2/documents.
+ */
+interface DocumentListParams {
+    /** Retrieval namespace */
+    namespace?: string;
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 50, maximum: 200) */
+    pageSize?: number;
+}
+/**
+ * Response from GET /v2/documents.
+ */
+interface DocumentListResponse {
+    /** Namespace listed by the API */
+    namespace: string;
+    /** Documents visible in the namespace */
+    documents: Document[];
+    /** Pagination metadata */
+    pagination: DocumentListPagination;
+}
+/**
+ * Document chunk types supported by document chunk endpoints.
+ */
+type DocumentChunkType = 'text' | 'image' | 'table' | 'page';
+/**
+ * Pagination metadata returned by chunk list endpoints.
+ */
+interface DocumentChunkPagination {
+    /** Current page number */
+    page: number;
+    /** Number of items requested per page */
+    pageSize: number;
+    /** Total matching chunks */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Query parameters for GET /v2/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListParams {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 50, maximum: 200) */
+    pageSize?: number;
+    /** Optional chunk type filter */
+    chunkType?: DocumentChunkType;
+    /** Set true to include 7-day asset URLs for media and page citation assets */
+    includeAssetUrls?: boolean;
+}
+/**
+ * Query parameters for GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkGetParams {
+    /** Set true to include 7-day asset URLs for media and page citation assets */
+    includeAssetUrls?: boolean;
+}
+/**
+ * One current-revision document chunk.
+ */
+interface DocumentChunk {
+    /** Stable document chunk row identifier */
+    id: string;
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Chunk content type */
+    chunkType: DocumentChunkType;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string | null;
+    /** Chunk text or generated summary content */
+    content?: string | null;
+    /** Parent section identifier */
+    sectionId?: string | null;
+    /** Parent section path */
+    sectionPath?: string | null;
+    /** Source path from the parser output */
+    sourceChunkPath?: string | null;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Sort order within the document revision */
+    sortOrder: number;
+    /** Chunk metadata returned by the API */
+    metadata: Record<string, unknown>;
+    /** 7-day asset URL for media or page citation assets when available */
+    assetUrl?: string | null;
+    /** Chunk creation timestamp */
+    createdAt?: Date;
+}
+/**
+ * Response from GET /v2/documents/{document_id}/files/page-citation-source.
+ */
+interface DocumentPageCitationSource {
+    documentId: string;
+    namespace?: string;
+    jobId?: string;
+    jobResultId?: string;
+    variant?: string;
+    fileName: string;
+    contentType: string;
+    url: string;
+    expiresAt?: Date;
+}
+/**
+ * Response from GET /v2/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Current-revision chunks */
+    chunks: DocumentChunk[];
+    /** Pagination metadata */
+    pagination: DocumentChunkPagination;
+}
+/**
+ * Response from GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Requested current-revision chunk */
+    chunk: DocumentChunk;
+}
+
+type KnowhereAssetStorageBody = Uint8Array;
+interface KnowhereAssetStorageObject {
+    readonly key: string;
+    readonly body: KnowhereAssetStorageBody;
+    readonly contentType: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+interface KnowhereAssetStorageHead {
+    readonly key: string;
+    readonly contentType?: string;
+    readonly contentLength?: number;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly url?: string;
+}
+interface KnowhereAssetStorageWriteResult {
+    readonly key: string;
+    readonly url?: string;
+}
+interface KnowhereAssetStorageAdapter {
+    writeObject(input: KnowhereAssetStorageObject): Promise<KnowhereAssetStorageWriteResult>;
+    headObject?(key: string): Promise<KnowhereAssetStorageHead | null>;
+    getObjectUrl?(key: string): Promise<string | null>;
+}
+interface KnowhereAssetStorageOptions {
+    readonly adapter: KnowhereAssetStorageAdapter;
+    readonly keyPrefix: string;
+    readonly skipExisting?: boolean;
+    readonly chunkPageSize?: number;
+    readonly revisionKey?: string;
+}
+interface KnowhereParsedSnapshotChunk {
+    readonly id: string;
+    readonly chunkId: string;
+    readonly chunkType: string;
+    readonly contentSource?: string;
+    readonly content: string;
+    readonly sectionPath?: string;
+    readonly sourceChunkPath: string;
+    readonly filePath?: string;
+    readonly sortOrder: number;
+    readonly metadata: Record<string, unknown>;
+    readonly assetUrl?: string;
+}
+interface KnowhereParsedSnapshotChunkPage {
+    readonly version: 1;
+    readonly jobId: string;
+    readonly revisionKey?: string;
+    readonly documentId?: string;
+    readonly namespace?: string;
+    readonly sourceFileName: string;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total: number;
+    readonly totalPages: number;
+    readonly chunks: readonly KnowhereParsedSnapshotChunk[];
+}
+interface KnowhereParsedSnapshotChunkPageReference {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly chunkCount: number;
+    readonly key: string;
+    readonly url?: string;
+}
+interface KnowhereParsedSnapshotManifest {
+    readonly version: 1;
+    readonly kind: 'knowhere-parsed-result-snapshot';
+    readonly jobId: string;
+    readonly revisionKey?: string;
+    readonly documentId?: string;
+    readonly namespace?: string;
+    readonly sourceFileName: string;
+    readonly totalChunks: number;
+    readonly typeCounts?: Readonly<Partial<Record<DocumentChunkType, number>>>;
+    readonly chunkPageSize: number;
+    readonly chunkPages: readonly KnowhereParsedSnapshotChunkPageReference[];
+    readonly assetUrlsByFilePath: Readonly<Record<string, string>>;
+    readonly createdAt: string;
+}
+interface KnowhereParsedSnapshot {
+    readonly manifest: KnowhereParsedSnapshotManifest;
+    readonly manifestKey: string;
+    readonly manifestUrl?: string;
+    readonly indexKey: string;
+    readonly indexUrl?: string;
+    readonly chunkPageUrlsByPage: Readonly<Record<number, string>>;
+}
+interface KnowhereAssetStorageResult {
+    readonly result: ParseResult;
+    readonly assetUrlsByFilePath: Readonly<Record<string, string>>;
+    readonly snapshot?: KnowhereParsedSnapshot;
+}
+type ParsedDocumentAssetUrlPolicy = 'none' | 'durable';
+interface ParsedDocumentStorageDocument {
+    readonly documentId: string;
+    readonly revisionKey: string;
+}
+type ParsedDocumentStorageManifestParams = ParsedDocumentStorageDocument;
+interface ParsedDocumentStorageChunkPageParams extends ParsedDocumentStorageDocument {
+    readonly page: number;
+    readonly chunkType?: DocumentChunkType;
+}
+interface ParsedDocumentStorageAsset {
+    readonly sourcePath: string;
+    readonly body: KnowhereAssetStorageBody;
+    readonly contentType: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+interface ParsedDocumentStorageAssetParams extends ParsedDocumentStorageDocument {
+    readonly sourcePath: string;
+}
+interface ParsedDocumentSyncProgress {
+    readonly documentId: string;
+    readonly revisionKey: string;
+    readonly nextChunkPage: number;
+    readonly nextAssetIndex: number;
+    readonly status: 'running' | 'completed' | 'failed';
+    readonly updatedAt: string;
+    readonly error?: string;
+}
+interface ParsedDocumentStorage {
+    readManifest(params: ParsedDocumentStorageManifestParams): Promise<KnowhereParsedSnapshotManifest | null>;
+    writeManifest(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly manifest: KnowhereParsedSnapshotManifest;
+    }): Promise<void>;
+    readChunkPage(params: ParsedDocumentStorageChunkPageParams): Promise<KnowhereParsedSnapshotChunkPage | null>;
+    writeChunkPage(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly page: KnowhereParsedSnapshotChunkPage;
+    }): Promise<void>;
+    writeAsset(params: ParsedDocumentStorageDocument & ParsedDocumentStorageAsset): Promise<{
+        readonly sourcePath: string;
+        readonly url?: string;
+    }>;
+    getAssetUrl(params: ParsedDocumentStorageAssetParams): Promise<string | null>;
+    readSyncProgress(params: ParsedDocumentStorageDocument): Promise<ParsedDocumentSyncProgress | null>;
+    writeSyncProgress(params: ParsedDocumentSyncProgress): Promise<void>;
+}
+interface ParsedDocumentSyncScheduler {
+    schedule(task: () => Promise<void>): void | Promise<void>;
+}
+interface ParsedDocumentStorageLimits {
+    readonly chunkPageSize?: number;
+    readonly remotePageSize?: number;
+    readonly maxPagesPerSync?: number;
+    readonly maxAssetsPerSync?: number;
+    readonly syncDeadlineMs?: number;
+    readonly grepMaxPages?: number;
+    readonly grepDeadlineMs?: number;
+    readonly outlineMaxPages?: number;
+    readonly outlineDeadlineMs?: number;
+}
+interface ParsedDocumentStorageConfig {
+    readonly storage: ParsedDocumentStorage;
+    readonly scheduler?: ParsedDocumentSyncScheduler;
+    readonly limits?: ParsedDocumentStorageLimits;
+}
+
+/**
+ * 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;
+}
+/**
+ * Client-provided display metadata copied onto the published document.
+ */
+type DocumentMetadata = Record<string, unknown>;
+/**
+ * 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;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
+    /** Existing document identifier when updating a published document */
+    documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
+    /** 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 */
+    summaryTxt?: boolean;
+    /** Custom data identifier */
+    dataId?: string;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
+    /** Existing document identifier when updating a published document */
+    documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
+    /** 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;
+    /**
+     * Optional asset storage adapter used to copy parsed media and page citation
+     * assets into application-owned storage before the result is returned.
+     */
+    storageAdapter?: KnowhereAssetStorageOptions;
+    /** 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 PageChunk extends BaseChunk {
-    type: 'page';
+interface UploadProgress {
+    /** Bytes uploaded */
+    loaded: number;
+    /** Total bytes (may be undefined for streams) */
+    total?: number;
+    /** Upload percentage (0-100) */
+    percent: number;
 }
 /**
- * Union type of all chunk types
- */
-type Chunk = TextChunk | ImageChunk | TableChunk | PageChunk;
-/**
- * Complete parse result
+ * Polling progress information
  */
-interface ParseResult {
-    /** Manifest metadata */
-    manifest: Manifest;
-    /** All chunks */
-    chunks: Chunk[];
-    /** Document navigation tree from doc_nav.json (current worker output) */
-    docNav?: DocNav;
-    /** Full document as Markdown (if available) */
-    fullMarkdown?: string;
-    /** Raw ZIP buffer */
-    rawZip: Buffer;
-    /** @deprecated Current worker no longer emits chunks_slim.json */
-    chunksSlim?: SlimChunk[];
-    /** @deprecated Current worker no longer emits hierarchy.json */
-    hierarchy?: unknown;
-    /** @deprecated Table-of-contents hierarchy hints (if available) */
-    tocHierarchies?: unknown;
-    /** @deprecated Knowledge-base CSV export (if available) */
-    kbCsv?: string;
-    /** @deprecated Pre-rendered hierarchy HTML view (if available) */
-    hierarchyViewHtml?: string;
-    /** Text chunks only */
-    readonly textChunks: TextChunk[];
-    /** Image chunks only */
-    readonly imageChunks: ImageChunk[];
-    /** Table chunks only */
-    readonly tableChunks: TableChunk[];
-    /** Page chunks only */
-    readonly pageChunks: PageChunk[];
-    /** Job ID */
-    readonly jobId: string;
-    /** Effective retrieval namespace when loaded from a job result */
-    namespace?: string;
-    /** Canonical document identifier when loaded from a job result */
-    documentId?: 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 PollProgress {
+    /** Current job status */
+    status: JobStatus;
+    /** Elapsed time in seconds */
+    elapsedSeconds: number;
+    /** Current job result */
+    jobResult: JobResult;
 }
 
 interface HttpClientOptions {
@@ -809,165 +1151,6 @@ declare class Retrieval extends BaseResource {
     query(params: RetrievalQueryParams): Promise<RetrievalQueryResponse>;
 }
 
-/**
- * Canonical document state returned by document lifecycle endpoints.
- */
-interface Document {
-    /** Stable document identifier */
-    documentId: string;
-    /** Retrieval namespace */
-    namespace: string;
-    /** Current lifecycle status */
-    status: string;
-    /** Current published job result identifier */
-    currentJobResultId?: string;
-    /** Original source file name */
-    sourceFileName?: string;
-    /** Client-provided display metadata copied from the publishing job */
-    documentMetadata?: Record<string, unknown>;
-    /** Document creation timestamp */
-    createdAt?: Date;
-    /** Last update timestamp */
-    updatedAt?: Date;
-    /** Archive timestamp, when archived */
-    archivedAt?: Date;
-}
-/**
- * Pagination metadata returned by document list endpoints.
- */
-interface DocumentListPagination {
-    /** Current page number */
-    page: number;
-    /** Number of items requested per page */
-    pageSize: number;
-    /** Total matching documents */
-    total: number;
-    /** Total number of pages */
-    totalPages: number;
-}
-/**
- * Query parameters for GET /v2/documents.
- */
-interface DocumentListParams {
-    /** Retrieval namespace */
-    namespace?: string;
-    /** Page number (default: 1) */
-    page?: number;
-    /** Items per page (default: 50, maximum: 200) */
-    pageSize?: number;
-}
-/**
- * Response from GET /v2/documents.
- */
-interface DocumentListResponse {
-    /** Namespace listed by the API */
-    namespace: string;
-    /** Documents visible in the namespace */
-    documents: Document[];
-    /** Pagination metadata */
-    pagination: DocumentListPagination;
-}
-/**
- * Document chunk types supported by document chunk endpoints.
- */
-type DocumentChunkType = 'text' | 'image' | 'table' | 'page';
-/**
- * Pagination metadata returned by chunk list endpoints.
- */
-interface DocumentChunkPagination {
-    /** Current page number */
-    page: number;
-    /** Number of items requested per page */
-    pageSize: number;
-    /** Total matching chunks */
-    total: number;
-    /** Total number of pages */
-    totalPages: number;
-}
-/**
- * Query parameters for GET /v2/documents/{document_id}/chunks.
- */
-interface DocumentChunkListParams {
-    /** Page number (default: 1) */
-    page?: number;
-    /** Items per page (default: 50, maximum: 200) */
-    pageSize?: number;
-    /** Optional chunk type filter */
-    chunkType?: DocumentChunkType;
-    /** Set true to include 7-day asset URLs for media chunks */
-    includeAssetUrls?: boolean;
-}
-/**
- * Query parameters for GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
- */
-interface DocumentChunkGetParams {
-    /** Set true to include 7-day asset URLs for media chunks */
-    includeAssetUrls?: boolean;
-}
-/**
- * One current-revision document chunk.
- */
-interface DocumentChunk {
-    /** Stable document chunk row identifier */
-    id: string;
-    /** Parser-provided chunk identifier */
-    chunkId: string;
-    /** Chunk content type */
-    chunkType: DocumentChunkType;
-    /** Content source marker. Page chunks normally expose summaries as content. */
-    contentSource?: string | null;
-    /** Chunk text or generated summary content */
-    content?: string | null;
-    /** Parent section identifier */
-    sectionId?: string | null;
-    /** Parent section path */
-    sectionPath?: string | null;
-    /** Source path from the parser output */
-    sourceChunkPath?: string | null;
-    /** Generated artifact file path for media chunks */
-    filePath?: string | null;
-    /** Sort order within the document revision */
-    sortOrder: number;
-    /** Chunk metadata returned by the API */
-    metadata: Record<string, unknown>;
-    /** 7-day asset URL for media chunks when available */
-    assetUrl?: string | null;
-    /** Chunk creation timestamp */
-    createdAt?: Date;
-}
-/**
- * Response from GET /v2/documents/{document_id}/chunks.
- */
-interface DocumentChunkListResponse {
-    /** Stable document identifier */
-    documentId: string;
-    /** Retrieval namespace */
-    namespace: string;
-    /** Current published job result identifier */
-    jobResultId?: string | null;
-    /** Current published job identifier */
-    jobId?: string | null;
-    /** Current-revision chunks */
-    chunks: DocumentChunk[];
-    /** Pagination metadata */
-    pagination: DocumentChunkPagination;
-}
-/**
- * Response from GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
- */
-interface DocumentChunkResponse {
-    /** Stable document identifier */
-    documentId: string;
-    /** Retrieval namespace */
-    namespace: string;
-    /** Current published job result identifier */
-    jobResultId?: string | null;
-    /** Current published job identifier */
-    jobId?: string | null;
-    /** Requested current-revision chunk */
-    chunk: DocumentChunk;
-}
-
 /**
  * Resource for canonical document lifecycle operations.
  */
@@ -988,6 +1171,10 @@ declare class Documents extends BaseResource {
      * Get one current-revision chunk for one canonical document.
      */
     getChunk(documentId: string, documentChunkId: string, params?: DocumentChunkGetParams): Promise<DocumentChunkResponse>;
+    /**
+     * Get a signed normalized source-file URL for compatibility and debugging.
+     */
+    getPageCitationSource(documentId: string): Promise<DocumentPageCitationSource>;
     /**
      * Archive one canonical document by ID.
      */
@@ -998,6 +1185,18 @@ declare class Documents extends BaseResource {
     private createChunkGetRequestConfig;
 }
 
+type PageCitationAssetContentType = 'image/png' | 'image/jpeg';
+type PageCitationAssetSource = 'knowhere-rendered-page-citation-source';
+interface PageCitationAsset {
+    pageNum: number;
+    artifactRef: string;
+    assetUrl?: string;
+    contentType: PageCitationAssetContentType;
+    width?: number;
+    height?: number;
+    source: PageCitationAssetSource;
+}
+
 type KnowledgeChunkType = DocumentChunkType;
 interface KnowledgeParseParams extends ParseParams {
     /** Optional stable local identifier for this parsed result copy. */
@@ -1028,6 +1227,8 @@ interface LocalKnowledgeDocument {
 interface LocalKnowledgeParseResponse {
     document: LocalKnowledgeDocument;
     result: ParseResult;
+    assetUrlsByFilePath?: Readonly<Record<string, string>>;
+    parsedSnapshot?: KnowhereParsedSnapshot;
 }
 interface KnowledgeAsyncParseParams extends ParseParams {
     /** Optional stable local identifier to use when this job result is cached later. */
@@ -1052,11 +1253,21 @@ interface KnowledgeStartupRecoveryResponse {
     checkedJobs: number;
     results: KnowledgeAsyncJobStatusResponse[];
 }
-interface KnowledgeCacheJobResultParams {
+interface KnowledgeLoadJobResultParams {
     jobId: string;
-    localDocumentId?: string;
     verifyChecksum?: boolean;
+    storageAdapter?: KnowhereAssetStorageOptions;
+}
+interface KnowledgeImportJobResultParams extends KnowledgeLoadJobResultParams {
+    localDocumentId?: string;
+}
+interface KnowledgeJobResultResponse {
+    result: ParseResult;
+    assetUrlsByFilePath?: Readonly<Record<string, string>>;
+    parsedSnapshot?: KnowhereParsedSnapshot;
 }
+/** @deprecated Use KnowledgeImportJobResultParams with importJobResult instead. */
+type KnowledgeCacheJobResultParams = KnowledgeImportJobResultParams;
 interface KnowledgeCacheDocumentParams {
     /** Canonical Knowhere document identifier from published retrieval results. */
     documentId: string;
@@ -1070,6 +1281,16 @@ interface KnowledgeDocumentReference {
     documentId?: string;
     /** Server parse job identifier whose completed result should be cached before reading. */
     jobId?: string;
+    /** Current parsed revision key when the caller already has it. */
+    revisionKey?: string;
+}
+type KnowledgeParsedStorageOptions = ParsedDocumentStorageConfig;
+type KnowledgeSyncParsedDocumentParams = KnowledgeDocumentReference;
+interface KnowledgeSyncParsedDocumentResponse {
+    documentId: string;
+    revisionKey: string;
+    completed: boolean;
+    manifest?: KnowhereParsedSnapshotManifest;
 }
 interface KnowledgeSection {
     sectionPath: string;
@@ -1088,14 +1309,19 @@ interface KnowledgeOutline {
     typeCounts: Record<KnowledgeChunkType, number>;
     sections: KnowledgeSection[];
     sectionTree: KnowledgeSection[];
+    truncated?: boolean;
+    continuationCursor?: string;
 }
 interface KnowledgeReadParams extends KnowledgeDocumentReference {
+    page?: number;
+    pageSize?: number;
     sectionPath?: string;
     startChunk?: number;
     endChunk?: number;
     chunkId?: string;
     chunkType?: KnowledgeChunkType;
     limit?: number;
+    assetUrlPolicy?: ParsedDocumentAssetUrlPolicy;
 }
 interface KnowledgeReadChunk {
     position: number;
@@ -1109,6 +1335,7 @@ interface KnowledgeReadChunk {
     sectionPath: string;
     sourceChunkPath: string;
     filePath?: string;
+    assetUrl?: string;
     pageNumbers?: number[];
     metadata: Record<string, unknown>;
 }
@@ -1116,9 +1343,14 @@ interface KnowledgeReadResponse {
     document: LocalKnowledgeDocument;
     chunks: KnowledgeReadChunk[];
     nextChunk?: number;
+    page?: number;
+    pageSize?: number;
+    totalChunks?: number;
+    totalPages?: number;
 }
 interface KnowledgeGrepParams extends KnowledgeDocumentReference {
     pattern: string;
+    continuationCursor?: string;
     isRegex?: boolean;
     isCaseSensitive?: boolean;
     maxResults?: number;
@@ -1142,6 +1374,7 @@ interface KnowledgeGrepResponse {
     matches: KnowledgeGrepMatch[];
     scannedChunks: number;
     truncated: boolean;
+    continuationCursor?: string;
 }
 interface KnowledgeSearchParams {
     query: string;
@@ -1180,15 +1413,27 @@ interface KnowledgeSearchResult {
 declare class Knowledge {
     private readonly client;
     private readonly store;
+    private readonly cacheDirectory;
+    private readonly parsedStorageConfig;
     constructor(client: Knowhere, options?: {
         cacheDirectory?: string;
+        parsedStorage?: ParsedDocumentStorageConfig;
     });
     withCacheDirectory(cacheDirectory: string): Knowledge;
+    withParsedStorage(parsedStorage: KnowledgeParsedStorageOptions): Knowledge;
+    parseToLocalCache(params: KnowledgeParseParams): Promise<LocalKnowledgeParseResponse>;
+    /** @deprecated Use parseToLocalCache for local cache imports or the top-level client.parse for server-safe parsing. */
     parse(params: KnowledgeParseParams): Promise<LocalKnowledgeParseResponse>;
     startParse(params: KnowledgeAsyncParseParams): Promise<KnowledgeAsyncParseResponse>;
     getJobStatus(jobId: string): Promise<KnowledgeAsyncJobStatusResponse>;
     recoverPendingAsyncParseJobs(): Promise<KnowledgeStartupRecoveryResponse>;
+    loadJobResult(params: KnowledgeLoadJobResultParams): Promise<KnowledgeJobResultResponse>;
+    importJobResult(params: KnowledgeImportJobResultParams): Promise<LocalKnowledgeParseResponse>;
+    /** @deprecated Use importJobResult for local cache imports or loadJobResult for server-safe loads. */
     cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
+    syncParsedDocument(params: KnowledgeSyncParsedDocumentParams): Promise<KnowledgeSyncParsedDocumentResponse>;
+    private syncParseResultToConfiguredStorage;
+    private parseWithoutClientStorageAdapter;
     cacheDocument(params: KnowledgeCacheDocumentParams): Promise<LocalKnowledgeParseResponse>;
     private resolveAsyncCache;
     listDocuments(): Promise<LocalKnowledgeDocument[]>;
@@ -1198,6 +1443,20 @@ declare class Knowledge {
     search(params: KnowledgeSearchParams): Promise<KnowledgeSearchResponse>;
     private resolveSearchDocuments;
     private loadReadableResult;
+    private readRemoteDocumentChunks;
+    private scanRemoteDocumentChunks;
+    private grepRemoteDocumentChunks;
+    private getRemoteDocumentOutline;
+    private tryReadChunksFromParsedStorage;
+    private tryGrepChunksFromParsedStorage;
+    private tryReadOutlineFromParsedStorage;
+    private readFreshParsedStorageManifest;
+    private readStoredSnapshotChunks;
+    private toRemoteReadChunks;
+    private hardenReadChunkAssetUrls;
+    private scheduleParsedStorageSync;
+    private syncRemoteDocumentToParsedStorage;
+    private requireParsedStorageConfig;
     private findLocalDocumentByRemoteId;
     private getPublishedDocumentJobId;
 }
@@ -1295,6 +1554,73 @@ declare class Knowhere {
 
 declare const VERSION = "0.1.0";
 
+declare function storeParseResultAssets(result: ParseResult, options?: KnowhereAssetStorageOptions): Promise<KnowhereAssetStorageResult>;
+
+declare class DiskParsedDocumentStorage implements ParsedDocumentStorage {
+    private readonly rootDirectory;
+    constructor(rootDirectory: string);
+    readManifest(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+    }): Promise<KnowhereParsedSnapshotManifest | null>;
+    writeManifest(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly manifest: KnowhereParsedSnapshotManifest;
+    }): Promise<void>;
+    readChunkPage(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly page: number;
+    }): Promise<KnowhereParsedSnapshotChunkPage | null>;
+    writeChunkPage(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly page: KnowhereParsedSnapshotChunkPage;
+    }): Promise<void>;
+    writeAsset(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly sourcePath: string;
+        readonly body: Uint8Array;
+        readonly contentType: string;
+        readonly metadata?: Readonly<Record<string, string>>;
+    }): Promise<{
+        readonly sourcePath: string;
+        readonly url?: string;
+    }>;
+    getAssetUrl(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+        readonly sourcePath: string;
+    }): Promise<string | null>;
+    readSyncProgress(params: {
+        readonly documentId: string;
+        readonly revisionKey: string;
+    }): Promise<ParsedDocumentSyncProgress | null>;
+    writeSyncProgress(params: ParsedDocumentSyncProgress): Promise<void>;
+    private getManifestPath;
+    private getChunkPagePath;
+    private getProgressPath;
+    private getAssetPath;
+    private getRevisionDirectory;
+    private readOptionalJson;
+    private writeJson;
+}
+
+declare function syncParseResultToParsedDocumentStorage(params: {
+    readonly result: ParseResult;
+    readonly storage: ParsedDocumentStorage;
+    readonly documentId?: string;
+    readonly revisionKey?: string;
+    readonly chunkPageSize?: number;
+}): Promise<{
+    readonly result: ParseResult;
+    readonly snapshot?: KnowhereParsedSnapshot;
+    readonly documentId: string;
+    readonly revisionKey: string;
+}>;
+
 /**
  * Base error class for all Knowhere SDK errors
  */
@@ -1424,4 +1750,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NetworkError, NotFoundError, type PageChunk, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, type KnowhereParsedSnapshot, type KnowhereParsedSnapshotChunk, type KnowhereParsedSnapshotChunkPage, type KnowhereParsedSnapshotChunkPageReference, type KnowhereParsedSnapshotManifest, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentAssetUrlPolicy, type ParsedDocumentStorage, type ParsedDocumentStorageAsset, type ParsedDocumentStorageAssetParams, type ParsedDocumentStorageChunkPageParams, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentStorageManifestParams, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default, storeParseResultAssets, syncParseResultToParsedDocumentStorage };