@ontos-ai/knowhere-sdk 0.9.0 → 2.0.0

package/README.md

@@ -46,6 +46,7 @@ const result = await client.parse({
 console.log(`Found ${result.textChunks.length} text chunks`);
 console.log(`Found ${result.imageChunks.length} images`);
 console.log(`Found ${result.tableChunks.length} tables`);
+console.log(`Found ${result.pageChunks.length} page chunks`);
 
 // Work with chunks — worker metadata is in chunk.metadata
 result.textChunks.forEach((chunk) => {
@@ -54,6 +55,12 @@ result.textChunks.forEach((chunk) => {
   console.log(chunk.metadata.summary);
 });
 
+result.pageChunks.forEach((chunk) => {
+  console.log(chunk.contentSource); // "summary"
+  console.log(chunk.content); // page-level summary
+  console.log(chunk.metadata.pageNums); // citation pages
+});
+
 // Save results to disk
 await result.save('./output/');
 ```
@@ -200,6 +207,7 @@ console.log(documentId);
 const response = await client.retrieval.query({
   namespace: 'support-center',
   query: 'How do I reset Bluetooth pairing?',
+  chunkTypes: ['page'],
   topK: 5,
   useAgentic: true,
 });
@@ -212,7 +220,9 @@ console.log(response.failureReason); // no-answer reason, when returned
 
 for (const result of response.results) {
   console.log(result.content);
+  console.log(result.contentSource);
   console.log(result.score);
+  console.log(result.metadata?.pageNums);
   console.log(result.source.sourceFileName, result.source.sectionPath);
 }
 ```
@@ -221,9 +231,12 @@ Retrieval results use one canonical source object:
 
 ```typescript
 result.content;
+result.chunkId;
 result.chunkType;
+result.contentSource;
 result.score;
 result.assetUrl;
+result.metadata;
 result.source.documentId;
 result.source.sourceFileName;
 result.source.sectionPath;
@@ -237,10 +250,12 @@ const reference = response.referencedChunks[0];
 reference.chunkId;
 reference.documentId;
 reference.chunkType;
+reference.contentSource;
 reference.sectionPath;
 reference.filePath;
 reference.jobId;
 reference.assetUrl;
+reference.metadata;
 ```
 
 Use `documentId` to update or archive a document:
@@ -252,16 +267,22 @@ const updateJob = await client.jobs.create({
   documentId,
 });
 
-const documents = await client.documents.list({ namespace: 'support-center' });
+const documents = await client.documents.list({
+  namespace: 'support-center',
+  page: 1,
+  pageSize: 50,
+});
 const document = await client.documents.get(documentId);
 const chunks = await client.documents.listChunks(documentId, {
   page: 1,
   pageSize: 50,
-  chunkType: 'text',
+  chunkType: 'page',
+  includeAssetUrls: true,
 });
 const archived = await client.documents.archive(documentId);
 
 console.log(documents.documents.length);
+console.log(documents.pagination.totalPages);
 console.log(document.status);
 console.log(chunks.pagination.total);
 if (chunks.chunks[0]) {
@@ -269,6 +290,9 @@ if (chunks.chunks[0]) {
     includeAssetUrls: true,
   });
   console.log(chunk.chunk.content);
+  console.log(chunk.chunk.contentSource);
+  console.log(chunk.chunk.metadata.pageNums);
+  console.log(chunk.chunk.assetUrl);
 }
 console.log(archived.status);
 ```
@@ -282,7 +306,7 @@ tools over that cached copy. This is the implementation used by the separate
 ```typescript
 const parsed = await client.knowledge.parse({
   file: './manual.pdf',
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
 });
 
 const outline = await client.knowledge.getDocumentOutline(parsed.document.localDocumentId);
@@ -332,7 +356,7 @@ const remoteOutline = await client.knowledge.getDocumentOutline({
 
 const jobRead = await client.knowledge.readChunks({
   jobId: jobResult.jobId,
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
   limit: 5,
 });
 ```
@@ -347,7 +371,7 @@ job completes:
 ```typescript
 const started = await client.knowledge.startParse({
   file: './manual.pdf',
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
 });
 
 const status = await client.knowledge.getJobStatus(started.job.jobId);

package/dist/index.d.mts

@@ -300,6 +300,8 @@ interface Statistics {
     imageChunks: number;
     /** Number of table chunks */
     tableChunks: number;
+    /** Number of page chunks */
+    pageChunks?: number;
     /** Total number of pages (if applicable) */
     totalPages?: number;
 }
@@ -417,6 +419,7 @@ interface DocNav {
 interface ChunkMetadata {
     length?: number;
     pageNums?: number[];
+    entities?: Record<string, unknown>[];
     tokens?: string[];
     keywords?: string[];
     summary?: string;
@@ -435,7 +438,9 @@ interface BaseChunk {
     /** Unique chunk identifier */
     chunkId: string;
     /** Chunk type */
-    type: 'text' | 'image' | 'table';
+    type: 'text' | 'image' | 'table' | 'page';
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     /** Main content */
     content: string;
     /** Relative path in ZIP */
@@ -447,7 +452,7 @@ interface BaseChunk {
  * Minimal chunk representation emitted in chunks_slim.json (legacy).
  */
 interface SlimChunk {
-    type: 'text' | 'image' | 'table';
+    type: 'text' | 'image' | 'table' | 'page';
     path: string;
     content: string;
 }
@@ -483,10 +488,16 @@ interface TableChunk extends BaseChunk {
     /** Save table HTML to disk */
     save(directory: string): Promise<string>;
 }
+/**
+ * Page chunk
+ */
+interface PageChunk extends BaseChunk {
+    type: 'page';
+}
 /**
  * Union type of all chunk types
  */
-type Chunk = TextChunk | ImageChunk | TableChunk;
+type Chunk = TextChunk | ImageChunk | TableChunk | PageChunk;
 /**
  * Complete parse result
  */
@@ -517,6 +528,8 @@ interface ParseResult {
     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 */
@@ -602,6 +615,7 @@ declare class HttpClient {
 declare abstract class BaseResource {
     protected httpClient: HttpClient;
     constructor(httpClient: HttpClient);
+    protected endpoint(path: string): string;
 }
 
 /**
@@ -651,6 +665,7 @@ type RetrievalChannel = 'path' | 'content' | 'term';
  * Path filtering mode for retrieval queries.
  */
 type RetrievalFilterMode = 'delete' | 'keep';
+type RetrievalChunkType = 'text' | 'image' | 'table' | 'page';
 /**
  * Retrieval query parameters.
  */
@@ -669,8 +684,10 @@ interface RetrievalQueryParams {
      * - ``undefined`` / omitted — server default
      */
     useAgentic?: boolean;
-    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
-    dataType?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table, 7=page, 8=text+image+table */
+    dataType?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    /** Allowed chunk types. Overrides dataType when provided. */
+    chunkTypes?: RetrievalChunkType[];
     /** Path keywords for include/exclude filtering */
     signalPaths?: string[];
     /** Signal path filter mode */
@@ -705,14 +722,24 @@ interface RetrievalSource {
  * Canonical chunk result returned by retrieval query.
  */
 interface RetrievalResult {
+    /** Parser-provided chunk identifier when included by the API */
+    chunkId?: string;
     /** Knowledge content to use directly in the caller's answer */
     content: string;
-    /** Chunk type, for example text, image, or table */
+    /** Chunk type, for example text, image, table, or page */
     chunkType: string;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     /** Retrieval score returned by the API. Null when no score is available (agentic navigation-only results). */
     score: number | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string;
+    /** Source chunk path when returned by the API */
+    sourceChunkPath?: string | null;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Chunk metadata returned by the API */
+    metadata?: Record<string, unknown>;
     /** Source reference for this result */
     source: RetrievalSource;
 }
@@ -724,19 +751,25 @@ interface RetrievalReferencedChunk {
     chunkId: string;
     /** Stable document identifier */
     documentId: string;
-    /** Chunk type, for example text, image, or table */
+    /** Chunk type, for example text, image, table, or page */
     chunkType: string;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string | null;
     /** Human-readable section path */
     sectionPath: string;
+    /** Source chunk path when returned by the API */
+    sourceChunkPath?: string | null;
     /** Generated artifact file path for media chunks */
     filePath?: string | null;
     /** Published job identifier for the referenced chunk */
     jobId?: string | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string | null;
+    /** Chunk metadata returned by the API */
+    metadata?: Record<string, unknown>;
 }
 /**
- * Response from POST /v1/retrieval/query.
+ * Response from POST /v2/retrieval/query.
  *
  * Three PRIMARY output fields for downstream agent consumption:
  * - `evidenceText`: hierarchical evidence tree for LLM context
@@ -800,18 +833,44 @@ interface Document {
     archivedAt?: Date;
 }
 /**
- * Response from GET /v1/documents.
+ * 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';
+type DocumentChunkType = 'text' | 'image' | 'table' | 'page';
 /**
  * Pagination metadata returned by chunk list endpoints.
  */
@@ -826,7 +885,7 @@ interface DocumentChunkPagination {
     totalPages: number;
 }
 /**
- * Query parameters for GET /v1/documents/{document_id}/chunks.
+ * Query parameters for GET /v2/documents/{document_id}/chunks.
  */
 interface DocumentChunkListParams {
     /** Page number (default: 1) */
@@ -835,14 +894,14 @@ interface DocumentChunkListParams {
     pageSize?: number;
     /** Optional chunk type filter */
     chunkType?: DocumentChunkType;
-    /** Generate asset URLs for media chunks (default: false) */
+    /** Set true to include 7-day asset URLs for media chunks */
     includeAssetUrls?: boolean;
 }
 /**
- * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ * Query parameters for GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
  */
 interface DocumentChunkGetParams {
-    /** Generate asset URLs for media chunks (default: false) */
+    /** Set true to include 7-day asset URLs for media chunks */
     includeAssetUrls?: boolean;
 }
 /**
@@ -855,6 +914,8 @@ interface DocumentChunk {
     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 */
@@ -869,13 +930,13 @@ interface DocumentChunk {
     sortOrder: number;
     /** Chunk metadata returned by the API */
     metadata: Record<string, unknown>;
-    /** Generated asset URL when requested and available */
+    /** 7-day asset URL for media chunks when available */
     assetUrl?: string | null;
     /** Chunk creation timestamp */
     createdAt?: Date;
 }
 /**
- * Response from GET /v1/documents/{document_id}/chunks.
+ * Response from GET /v2/documents/{document_id}/chunks.
  */
 interface DocumentChunkListResponse {
     /** Stable document identifier */
@@ -892,7 +953,7 @@ interface DocumentChunkListResponse {
     pagination: DocumentChunkPagination;
 }
 /**
- * Response from GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ * Response from GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
  */
 interface DocumentChunkResponse {
     /** Stable document identifier */
@@ -914,9 +975,7 @@ declare class Documents extends BaseResource {
     /**
      * List canonical documents in a namespace.
      */
-    list(params?: {
-        namespace?: string;
-    }): Promise<DocumentListResponse>;
+    list(params?: DocumentListParams): Promise<DocumentListResponse>;
     /**
      * Get one canonical document by ID.
      */
@@ -933,6 +992,8 @@ declare class Documents extends BaseResource {
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createDocumentListRequestConfig;
+    private normalizeDocumentListResponse;
     private createChunkListRequestConfig;
     private createChunkGetRequestConfig;
 }
@@ -1040,10 +1101,15 @@ interface KnowledgeReadChunk {
     position: number;
     chunkId: string;
     chunkType: KnowledgeChunkType;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     content: string;
+    /** Display-safe text. For page chunks this prefers metadata.summary. */
+    readableContent: string;
     sectionPath: string;
     sourceChunkPath: string;
     filePath?: string;
+    pageNumbers?: number[];
     metadata: Record<string, unknown>;
 }
 interface KnowledgeReadResponse {
@@ -1358,4 +1424,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 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 ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, 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, 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 };

package/dist/index.d.ts

@@ -300,6 +300,8 @@ interface Statistics {
     imageChunks: number;
     /** Number of table chunks */
     tableChunks: number;
+    /** Number of page chunks */
+    pageChunks?: number;
     /** Total number of pages (if applicable) */
     totalPages?: number;
 }
@@ -417,6 +419,7 @@ interface DocNav {
 interface ChunkMetadata {
     length?: number;
     pageNums?: number[];
+    entities?: Record<string, unknown>[];
     tokens?: string[];
     keywords?: string[];
     summary?: string;
@@ -435,7 +438,9 @@ interface BaseChunk {
     /** Unique chunk identifier */
     chunkId: string;
     /** Chunk type */
-    type: 'text' | 'image' | 'table';
+    type: 'text' | 'image' | 'table' | 'page';
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     /** Main content */
     content: string;
     /** Relative path in ZIP */
@@ -447,7 +452,7 @@ interface BaseChunk {
  * Minimal chunk representation emitted in chunks_slim.json (legacy).
  */
 interface SlimChunk {
-    type: 'text' | 'image' | 'table';
+    type: 'text' | 'image' | 'table' | 'page';
     path: string;
     content: string;
 }
@@ -483,10 +488,16 @@ interface TableChunk extends BaseChunk {
     /** Save table HTML to disk */
     save(directory: string): Promise<string>;
 }
+/**
+ * Page chunk
+ */
+interface PageChunk extends BaseChunk {
+    type: 'page';
+}
 /**
  * Union type of all chunk types
  */
-type Chunk = TextChunk | ImageChunk | TableChunk;
+type Chunk = TextChunk | ImageChunk | TableChunk | PageChunk;
 /**
  * Complete parse result
  */
@@ -517,6 +528,8 @@ interface ParseResult {
     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 */
@@ -602,6 +615,7 @@ declare class HttpClient {
 declare abstract class BaseResource {
     protected httpClient: HttpClient;
     constructor(httpClient: HttpClient);
+    protected endpoint(path: string): string;
 }
 
 /**
@@ -651,6 +665,7 @@ type RetrievalChannel = 'path' | 'content' | 'term';
  * Path filtering mode for retrieval queries.
  */
 type RetrievalFilterMode = 'delete' | 'keep';
+type RetrievalChunkType = 'text' | 'image' | 'table' | 'page';
 /**
  * Retrieval query parameters.
  */
@@ -669,8 +684,10 @@ interface RetrievalQueryParams {
      * - ``undefined`` / omitted — server default
      */
     useAgentic?: boolean;
-    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
-    dataType?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table, 7=page, 8=text+image+table */
+    dataType?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    /** Allowed chunk types. Overrides dataType when provided. */
+    chunkTypes?: RetrievalChunkType[];
     /** Path keywords for include/exclude filtering */
     signalPaths?: string[];
     /** Signal path filter mode */
@@ -705,14 +722,24 @@ interface RetrievalSource {
  * Canonical chunk result returned by retrieval query.
  */
 interface RetrievalResult {
+    /** Parser-provided chunk identifier when included by the API */
+    chunkId?: string;
     /** Knowledge content to use directly in the caller's answer */
     content: string;
-    /** Chunk type, for example text, image, or table */
+    /** Chunk type, for example text, image, table, or page */
     chunkType: string;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     /** Retrieval score returned by the API. Null when no score is available (agentic navigation-only results). */
     score: number | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string;
+    /** Source chunk path when returned by the API */
+    sourceChunkPath?: string | null;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Chunk metadata returned by the API */
+    metadata?: Record<string, unknown>;
     /** Source reference for this result */
     source: RetrievalSource;
 }
@@ -724,19 +751,25 @@ interface RetrievalReferencedChunk {
     chunkId: string;
     /** Stable document identifier */
     documentId: string;
-    /** Chunk type, for example text, image, or table */
+    /** Chunk type, for example text, image, table, or page */
     chunkType: string;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string | null;
     /** Human-readable section path */
     sectionPath: string;
+    /** Source chunk path when returned by the API */
+    sourceChunkPath?: string | null;
     /** Generated artifact file path for media chunks */
     filePath?: string | null;
     /** Published job identifier for the referenced chunk */
     jobId?: string | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string | null;
+    /** Chunk metadata returned by the API */
+    metadata?: Record<string, unknown>;
 }
 /**
- * Response from POST /v1/retrieval/query.
+ * Response from POST /v2/retrieval/query.
  *
  * Three PRIMARY output fields for downstream agent consumption:
  * - `evidenceText`: hierarchical evidence tree for LLM context
@@ -800,18 +833,44 @@ interface Document {
     archivedAt?: Date;
 }
 /**
- * Response from GET /v1/documents.
+ * 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';
+type DocumentChunkType = 'text' | 'image' | 'table' | 'page';
 /**
  * Pagination metadata returned by chunk list endpoints.
  */
@@ -826,7 +885,7 @@ interface DocumentChunkPagination {
     totalPages: number;
 }
 /**
- * Query parameters for GET /v1/documents/{document_id}/chunks.
+ * Query parameters for GET /v2/documents/{document_id}/chunks.
  */
 interface DocumentChunkListParams {
     /** Page number (default: 1) */
@@ -835,14 +894,14 @@ interface DocumentChunkListParams {
     pageSize?: number;
     /** Optional chunk type filter */
     chunkType?: DocumentChunkType;
-    /** Generate asset URLs for media chunks (default: false) */
+    /** Set true to include 7-day asset URLs for media chunks */
     includeAssetUrls?: boolean;
 }
 /**
- * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ * Query parameters for GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
  */
 interface DocumentChunkGetParams {
-    /** Generate asset URLs for media chunks (default: false) */
+    /** Set true to include 7-day asset URLs for media chunks */
     includeAssetUrls?: boolean;
 }
 /**
@@ -855,6 +914,8 @@ interface DocumentChunk {
     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 */
@@ -869,13 +930,13 @@ interface DocumentChunk {
     sortOrder: number;
     /** Chunk metadata returned by the API */
     metadata: Record<string, unknown>;
-    /** Generated asset URL when requested and available */
+    /** 7-day asset URL for media chunks when available */
     assetUrl?: string | null;
     /** Chunk creation timestamp */
     createdAt?: Date;
 }
 /**
- * Response from GET /v1/documents/{document_id}/chunks.
+ * Response from GET /v2/documents/{document_id}/chunks.
  */
 interface DocumentChunkListResponse {
     /** Stable document identifier */
@@ -892,7 +953,7 @@ interface DocumentChunkListResponse {
     pagination: DocumentChunkPagination;
 }
 /**
- * Response from GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ * Response from GET /v2/documents/{document_id}/chunks/{document_chunk_id}.
  */
 interface DocumentChunkResponse {
     /** Stable document identifier */
@@ -914,9 +975,7 @@ declare class Documents extends BaseResource {
     /**
      * List canonical documents in a namespace.
      */
-    list(params?: {
-        namespace?: string;
-    }): Promise<DocumentListResponse>;
+    list(params?: DocumentListParams): Promise<DocumentListResponse>;
     /**
      * Get one canonical document by ID.
      */
@@ -933,6 +992,8 @@ declare class Documents extends BaseResource {
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createDocumentListRequestConfig;
+    private normalizeDocumentListResponse;
     private createChunkListRequestConfig;
     private createChunkGetRequestConfig;
 }
@@ -1040,10 +1101,15 @@ interface KnowledgeReadChunk {
     position: number;
     chunkId: string;
     chunkType: KnowledgeChunkType;
+    /** Content source marker. Page chunks normally expose summaries as content. */
+    contentSource?: string;
     content: string;
+    /** Display-safe text. For page chunks this prefers metadata.summary. */
+    readableContent: string;
     sectionPath: string;
     sourceChunkPath: string;
     filePath?: string;
+    pageNumbers?: number[];
     metadata: Record<string, unknown>;
 }
 interface KnowledgeReadResponse {
@@ -1358,4 +1424,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 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 ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, 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, 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 };

package/dist/index.js

@@ -756,6 +756,9 @@ var BaseResource = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
+  endpoint(path3) {
+    return `/v2${path3.startsWith("/") ? path3 : `/${path3}`}`;
+  }
 };
 
 // src/lib/upload.ts
@@ -806,7 +809,7 @@ async function pollJobStatus(httpClient, jobId, options) {
     if (signal?.aborted) {
       throw new Error("Polling aborted");
     }
-    const jobResult = await httpClient.get(`/v1/jobs/${jobId}`);
+    const jobResult = await httpClient.get(`/v2/jobs/${jobId}`);
     enrichJobResult(jobResult);
     const elapsed = Date.now() - startTime;
     const elapsedSeconds = Math.floor(elapsed / 1e3);
@@ -1067,6 +1070,9 @@ function createParseResult(parts) {
     get tableChunks() {
       return chunks.filter((c) => c.type === "table");
     },
+    get pageChunks() {
+      return chunks.filter((c) => c.type === "page");
+    },
     get jobId() {
       return manifest.jobId;
     },
@@ -1144,6 +1150,17 @@ function buildTextChunk(chunkData) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "text",
+    contentSource: chunkData.contentSource ?? "content",
+    content: chunkData.content ?? "",
+    path: chunkData.path ?? "",
+    metadata: chunkData.metadata ?? {}
+  };
+}
+function buildPageChunk(chunkData) {
+  return {
+    chunkId: chunkData.chunkId ?? "",
+    type: "page",
+    contentSource: chunkData.contentSource ?? "summary",
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     metadata: chunkData.metadata ?? {}
@@ -1153,6 +1170,7 @@ function buildImageChunk(chunkData, filePath, imageBuffer) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "image",
+    contentSource: chunkData.contentSource,
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
@@ -1170,6 +1188,7 @@ function buildTableChunk(chunkData, filePath, html) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "table",
+    contentSource: chunkData.contentSource,
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
@@ -1184,6 +1203,9 @@ async function processChunk(zip, chunkData) {
   if (chunkData.type === "text") {
     return buildTextChunk(chunkData);
   }
+  if (chunkData.type === "page") {
+    return buildPageChunk(chunkData);
+  }
   if (chunkData.type === "image") {
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
@@ -1216,6 +1238,9 @@ async function processDirectoryChunk(directory, chunkData) {
   if (chunkData.type === "text") {
     return buildTextChunk(chunkData);
   }
+  if (chunkData.type === "page") {
+    return buildPageChunk(chunkData);
+  }
   if (chunkData.type === "image") {
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
@@ -1254,6 +1279,7 @@ function serializeChunks(chunks) {
       const rawChunk = {
         chunkId: chunk.chunkId,
         type: chunk.type,
+        contentSource: chunk.contentSource,
         content: chunk.content,
         path: chunk.path,
         metadata: chunk.metadata
@@ -1322,7 +1348,7 @@ var Jobs = class extends BaseResource {
    * Create a new parsing job
    */
   async create(params) {
-    const job = await this.httpClient.post("/v1/jobs", params);
+    const job = await this.httpClient.post(this.endpoint("/jobs"), params);
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -1332,7 +1358,7 @@ var Jobs = class extends BaseResource {
    * Get job status
    */
   async get(jobId) {
-    const jobResult = await this.httpClient.get(`/v1/jobs/${jobId}`);
+    const jobResult = await this.httpClient.get(this.endpoint(`/jobs/${jobId}`));
     enrichJobResult(jobResult);
     return jobResult;
   }
@@ -1428,7 +1454,7 @@ var Retrieval = class extends BaseResource {
    * Query published documents.
    */
   async query(params) {
-    return this.httpClient.post("/v1/retrieval/query", params);
+    return this.httpClient.post(this.endpoint("/retrieval/query"), params);
   }
 };
 
@@ -1438,25 +1464,24 @@ var Documents = class extends BaseResource {
    * List canonical documents in a namespace.
    */
   async list(params) {
-    const requestConfig = params?.namespace ? {
-      params: {
-        namespace: params.namespace
-      }
-    } : void 0;
-    return this.httpClient.get("/v1/documents", requestConfig);
+    const response = await this.httpClient.get(
+      this.endpoint("/documents"),
+      this.createDocumentListRequestConfig(params)
+    );
+    return this.normalizeDocumentListResponse(response);
   }
   /**
    * Get one canonical document by ID.
    */
   async get(documentId) {
-    return this.httpClient.get(`/v1/documents/${documentId}`);
+    return this.httpClient.get(this.endpoint(`/documents/${documentId}`));
   }
   /**
    * List current-revision chunks for one canonical document.
    */
   async listChunks(documentId, params) {
     return this.httpClient.get(
-      `/v1/documents/${documentId}/chunks`,
+      this.endpoint(`/documents/${documentId}/chunks`),
       this.createChunkListRequestConfig(params)
     );
   }
@@ -1465,7 +1490,7 @@ var Documents = class extends BaseResource {
    */
   async getChunk(documentId, documentChunkId, params) {
     return this.httpClient.get(
-      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.endpoint(`/documents/${documentId}/chunks/${documentChunkId}`),
       this.createChunkGetRequestConfig(params)
     );
   }
@@ -1473,7 +1498,39 @@ var Documents = class extends BaseResource {
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
-    return this.httpClient.post(`/v1/documents/${documentId}/archive`);
+    return this.httpClient.post(this.endpoint(`/documents/${documentId}/archive`));
+  }
+  createDocumentListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.namespace !== void 0) {
+      queryParams.namespace = params.namespace;
+    }
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  normalizeDocumentListResponse(response) {
+    const maybePaginatedResponse = response;
+    if (maybePaginatedResponse.pagination) {
+      return response;
+    }
+    const total = response.documents.length;
+    return {
+      ...response,
+      pagination: {
+        page: 1,
+        pageSize: total,
+        total,
+        totalPages: total > 0 ? 1 : 0
+      }
+    };
   }
   createChunkListRequestConfig(params) {
     if (!params) {
@@ -1489,18 +1546,18 @@ var Documents = class extends BaseResource {
     if (params.chunkType !== void 0) {
       queryParams.chunk_type = params.chunkType;
     }
-    if (params.includeAssetUrls === true) {
-      queryParams.include_asset_urls = true;
+    if (params.includeAssetUrls !== void 0) {
+      queryParams.include_asset_urls = params.includeAssetUrls;
     }
     return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
   }
   createChunkGetRequestConfig(params) {
-    if (params?.includeAssetUrls !== true) {
+    if (params?.includeAssetUrls === void 0) {
       return void 0;
     }
     return {
       params: {
-        include_asset_urls: true
+        include_asset_urls: params.includeAssetUrls
       }
     };
   }
@@ -1703,7 +1760,7 @@ function countChunkTypes(result) {
       counts[chunk.type] += 1;
       return counts;
     },
-    { text: 0, image: 0, table: 0 }
+    { text: 0, image: 0, table: 0, page: 0 }
   );
 }
 function toLocalKnowledgeDocument(stored) {
@@ -2030,19 +2087,40 @@ function createLocalDocumentIdForRemote(documentId) {
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
+    const readableContent = getReadableChunkContent(chunk);
     return {
       source: chunk,
       position: index + 1,
       chunkId: chunk.chunkId,
       chunkType: chunk.type,
+      contentSource: chunk.contentSource,
       content: chunk.content,
+      readableContent,
       sectionPath: normalizeSectionPath(chunk.path, result.manifest.sourceFileName),
       sourceChunkPath: chunk.path,
       filePath,
+      pageNumbers: getChunkPageNumbers(chunk.metadata),
       metadata: chunk.metadata
     };
   });
 }
+function getReadableChunkContent(chunk) {
+  if (chunk.type !== "page") {
+    return chunk.content;
+  }
+  const summary = chunk.metadata.summary;
+  return typeof summary === "string" && summary.trim().length > 0 ? summary : chunk.content;
+}
+function getChunkPageNumbers(metadata) {
+  const value = metadata.pageNums;
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const pageNumbers = value.filter(
+    (pageNumber) => Number.isInteger(pageNumber) && pageNumber > 0
+  );
+  return pageNumbers.length > 0 ? [...new Set(pageNumbers)].sort((left, right) => left - right) : void 0;
+}
 function getChunkFilePath2(chunk) {
   if (chunk.type === "image" || chunk.type === "table") {
     return chunk.filePath;
@@ -2116,7 +2194,7 @@ function createSectionFromChunk(pathValue, chunk) {
     startChunk: chunk.position,
     endChunk: chunk.position,
     chunkCount: 1,
-    typeCounts: { text: 0, image: 0, table: 0, [chunk.chunkType]: 1 },
+    typeCounts: { text: 0, image: 0, table: 0, page: 0, [chunk.chunkType]: 1 },
     children: []
   };
 }
@@ -2175,7 +2253,7 @@ function countIndexedTypes(chunks) {
       counts[chunk.chunkType] += 1;
       return counts;
     },
-    { text: 0, image: 0, table: 0 }
+    { text: 0, image: 0, table: 0, page: 0 }
   );
 }
 function isInSection(chunkSectionPath, sectionPath) {
@@ -2212,10 +2290,13 @@ function toReadChunk(chunk) {
     position: chunk.position,
     chunkId: chunk.chunkId,
     chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource,
     content: chunk.content,
+    readableContent: chunk.readableContent,
     sectionPath: chunk.sectionPath,
     sourceChunkPath: chunk.sourceChunkPath,
     filePath: chunk.filePath,
+    pageNumbers: chunk.pageNumbers,
     metadata: chunk.metadata
   };
 }
@@ -2267,6 +2348,7 @@ function toResultReference(result, documentByServerId) {
   return {
     localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
     documentId,
+    chunkId: result.chunkId,
     sectionPath: result.source.sectionPath ?? void 0,
     chunkType: result.chunkType,
     score: result.score
@@ -2277,6 +2359,7 @@ function toRemoteSearchResult(result, documentByServerId) {
   return {
     localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
     documentId,
+    chunkId: result.chunkId,
     chunkType: result.chunkType,
     content: result.content,
     score: result.score,

package/dist/index.mjs

@@ -696,6 +696,9 @@ var BaseResource = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
+  endpoint(path3) {
+    return `/v2${path3.startsWith("/") ? path3 : `/${path3}`}`;
+  }
 };
 
 // src/lib/upload.ts
@@ -746,7 +749,7 @@ async function pollJobStatus(httpClient, jobId, options) {
     if (signal?.aborted) {
       throw new Error("Polling aborted");
     }
-    const jobResult = await httpClient.get(`/v1/jobs/${jobId}`);
+    const jobResult = await httpClient.get(`/v2/jobs/${jobId}`);
     enrichJobResult(jobResult);
     const elapsed = Date.now() - startTime;
     const elapsedSeconds = Math.floor(elapsed / 1e3);
@@ -1007,6 +1010,9 @@ function createParseResult(parts) {
     get tableChunks() {
       return chunks.filter((c) => c.type === "table");
     },
+    get pageChunks() {
+      return chunks.filter((c) => c.type === "page");
+    },
     get jobId() {
       return manifest.jobId;
     },
@@ -1084,6 +1090,17 @@ function buildTextChunk(chunkData) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "text",
+    contentSource: chunkData.contentSource ?? "content",
+    content: chunkData.content ?? "",
+    path: chunkData.path ?? "",
+    metadata: chunkData.metadata ?? {}
+  };
+}
+function buildPageChunk(chunkData) {
+  return {
+    chunkId: chunkData.chunkId ?? "",
+    type: "page",
+    contentSource: chunkData.contentSource ?? "summary",
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     metadata: chunkData.metadata ?? {}
@@ -1093,6 +1110,7 @@ function buildImageChunk(chunkData, filePath, imageBuffer) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "image",
+    contentSource: chunkData.contentSource,
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
@@ -1110,6 +1128,7 @@ function buildTableChunk(chunkData, filePath, html) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "table",
+    contentSource: chunkData.contentSource,
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
@@ -1124,6 +1143,9 @@ async function processChunk(zip, chunkData) {
   if (chunkData.type === "text") {
     return buildTextChunk(chunkData);
   }
+  if (chunkData.type === "page") {
+    return buildPageChunk(chunkData);
+  }
   if (chunkData.type === "image") {
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
@@ -1156,6 +1178,9 @@ async function processDirectoryChunk(directory, chunkData) {
   if (chunkData.type === "text") {
     return buildTextChunk(chunkData);
   }
+  if (chunkData.type === "page") {
+    return buildPageChunk(chunkData);
+  }
   if (chunkData.type === "image") {
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
@@ -1194,6 +1219,7 @@ function serializeChunks(chunks) {
       const rawChunk = {
         chunkId: chunk.chunkId,
         type: chunk.type,
+        contentSource: chunk.contentSource,
         content: chunk.content,
         path: chunk.path,
         metadata: chunk.metadata
@@ -1262,7 +1288,7 @@ var Jobs = class extends BaseResource {
    * Create a new parsing job
    */
   async create(params) {
-    const job = await this.httpClient.post("/v1/jobs", params);
+    const job = await this.httpClient.post(this.endpoint("/jobs"), params);
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -1272,7 +1298,7 @@ var Jobs = class extends BaseResource {
    * Get job status
    */
   async get(jobId) {
-    const jobResult = await this.httpClient.get(`/v1/jobs/${jobId}`);
+    const jobResult = await this.httpClient.get(this.endpoint(`/jobs/${jobId}`));
     enrichJobResult(jobResult);
     return jobResult;
   }
@@ -1368,7 +1394,7 @@ var Retrieval = class extends BaseResource {
    * Query published documents.
    */
   async query(params) {
-    return this.httpClient.post("/v1/retrieval/query", params);
+    return this.httpClient.post(this.endpoint("/retrieval/query"), params);
   }
 };
 
@@ -1378,25 +1404,24 @@ var Documents = class extends BaseResource {
    * List canonical documents in a namespace.
    */
   async list(params) {
-    const requestConfig = params?.namespace ? {
-      params: {
-        namespace: params.namespace
-      }
-    } : void 0;
-    return this.httpClient.get("/v1/documents", requestConfig);
+    const response = await this.httpClient.get(
+      this.endpoint("/documents"),
+      this.createDocumentListRequestConfig(params)
+    );
+    return this.normalizeDocumentListResponse(response);
   }
   /**
    * Get one canonical document by ID.
    */
   async get(documentId) {
-    return this.httpClient.get(`/v1/documents/${documentId}`);
+    return this.httpClient.get(this.endpoint(`/documents/${documentId}`));
   }
   /**
    * List current-revision chunks for one canonical document.
    */
   async listChunks(documentId, params) {
     return this.httpClient.get(
-      `/v1/documents/${documentId}/chunks`,
+      this.endpoint(`/documents/${documentId}/chunks`),
       this.createChunkListRequestConfig(params)
     );
   }
@@ -1405,7 +1430,7 @@ var Documents = class extends BaseResource {
    */
   async getChunk(documentId, documentChunkId, params) {
     return this.httpClient.get(
-      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.endpoint(`/documents/${documentId}/chunks/${documentChunkId}`),
       this.createChunkGetRequestConfig(params)
     );
   }
@@ -1413,7 +1438,39 @@ var Documents = class extends BaseResource {
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
-    return this.httpClient.post(`/v1/documents/${documentId}/archive`);
+    return this.httpClient.post(this.endpoint(`/documents/${documentId}/archive`));
+  }
+  createDocumentListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.namespace !== void 0) {
+      queryParams.namespace = params.namespace;
+    }
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  normalizeDocumentListResponse(response) {
+    const maybePaginatedResponse = response;
+    if (maybePaginatedResponse.pagination) {
+      return response;
+    }
+    const total = response.documents.length;
+    return {
+      ...response,
+      pagination: {
+        page: 1,
+        pageSize: total,
+        total,
+        totalPages: total > 0 ? 1 : 0
+      }
+    };
   }
   createChunkListRequestConfig(params) {
     if (!params) {
@@ -1429,18 +1486,18 @@ var Documents = class extends BaseResource {
     if (params.chunkType !== void 0) {
       queryParams.chunk_type = params.chunkType;
     }
-    if (params.includeAssetUrls === true) {
-      queryParams.include_asset_urls = true;
+    if (params.includeAssetUrls !== void 0) {
+      queryParams.include_asset_urls = params.includeAssetUrls;
     }
     return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
   }
   createChunkGetRequestConfig(params) {
-    if (params?.includeAssetUrls !== true) {
+    if (params?.includeAssetUrls === void 0) {
       return void 0;
     }
     return {
       params: {
-        include_asset_urls: true
+        include_asset_urls: params.includeAssetUrls
       }
     };
   }
@@ -1643,7 +1700,7 @@ function countChunkTypes(result) {
       counts[chunk.type] += 1;
       return counts;
     },
-    { text: 0, image: 0, table: 0 }
+    { text: 0, image: 0, table: 0, page: 0 }
   );
 }
 function toLocalKnowledgeDocument(stored) {
@@ -1970,19 +2027,40 @@ function createLocalDocumentIdForRemote(documentId) {
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
+    const readableContent = getReadableChunkContent(chunk);
     return {
       source: chunk,
       position: index + 1,
       chunkId: chunk.chunkId,
       chunkType: chunk.type,
+      contentSource: chunk.contentSource,
       content: chunk.content,
+      readableContent,
       sectionPath: normalizeSectionPath(chunk.path, result.manifest.sourceFileName),
       sourceChunkPath: chunk.path,
       filePath,
+      pageNumbers: getChunkPageNumbers(chunk.metadata),
       metadata: chunk.metadata
     };
   });
 }
+function getReadableChunkContent(chunk) {
+  if (chunk.type !== "page") {
+    return chunk.content;
+  }
+  const summary = chunk.metadata.summary;
+  return typeof summary === "string" && summary.trim().length > 0 ? summary : chunk.content;
+}
+function getChunkPageNumbers(metadata) {
+  const value = metadata.pageNums;
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const pageNumbers = value.filter(
+    (pageNumber) => Number.isInteger(pageNumber) && pageNumber > 0
+  );
+  return pageNumbers.length > 0 ? [...new Set(pageNumbers)].sort((left, right) => left - right) : void 0;
+}
 function getChunkFilePath2(chunk) {
   if (chunk.type === "image" || chunk.type === "table") {
     return chunk.filePath;
@@ -2056,7 +2134,7 @@ function createSectionFromChunk(pathValue, chunk) {
     startChunk: chunk.position,
     endChunk: chunk.position,
     chunkCount: 1,
-    typeCounts: { text: 0, image: 0, table: 0, [chunk.chunkType]: 1 },
+    typeCounts: { text: 0, image: 0, table: 0, page: 0, [chunk.chunkType]: 1 },
     children: []
   };
 }
@@ -2115,7 +2193,7 @@ function countIndexedTypes(chunks) {
       counts[chunk.chunkType] += 1;
       return counts;
     },
-    { text: 0, image: 0, table: 0 }
+    { text: 0, image: 0, table: 0, page: 0 }
   );
 }
 function isInSection(chunkSectionPath, sectionPath) {
@@ -2152,10 +2230,13 @@ function toReadChunk(chunk) {
     position: chunk.position,
     chunkId: chunk.chunkId,
     chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource,
     content: chunk.content,
+    readableContent: chunk.readableContent,
     sectionPath: chunk.sectionPath,
     sourceChunkPath: chunk.sourceChunkPath,
     filePath: chunk.filePath,
+    pageNumbers: chunk.pageNumbers,
     metadata: chunk.metadata
   };
 }
@@ -2207,6 +2288,7 @@ function toResultReference(result, documentByServerId) {
   return {
     localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
     documentId,
+    chunkId: result.chunkId,
     sectionPath: result.source.sectionPath ?? void 0,
     chunkType: result.chunkType,
     score: result.score
@@ -2217,6 +2299,7 @@ function toRemoteSearchResult(result, documentByServerId) {
   return {
     localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
     documentId,
+    chunkId: result.chunkId,
     chunkType: result.chunkType,
     content: result.content,
     score: result.score,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-sdk",
-  "version": "0.9.0",
+  "version": "2.0.0",
   "description": "Official Node.js SDK for Knowhere document parsing API",
   "keywords": [
     "knowhere",