@ontos-ai/knowhere-sdk 0.3.0 → 0.4.0

package/README.md

@@ -104,7 +104,9 @@ const result = await client.parse({
 });
 ```
 
-`fileName` 会在 `file` 是本地文件路径时自动推断；当 `file` 是 `Buffer`、`Uint8Array` 或不带路径信息的流时必须显式提供。
+`fileName` is inferred automatically when `file` is a local file path. When
+`file` is a `Buffer`, `Uint8Array`, or a stream without path metadata, provide
+`fileName` explicitly.
 
 ### Advanced Options
 
@@ -222,10 +224,22 @@ const updateJob = await client.jobs.create({
 
 const documents = await client.documents.list({ namespace: 'support-center' });
 const document = await client.documents.get(documentId);
+const chunks = await client.documents.listChunks(documentId, {
+  page: 1,
+  pageSize: 50,
+  chunkType: 'text',
+});
 const archived = await client.documents.archive(documentId);
 
 console.log(documents.documents.length);
 console.log(document.status);
+console.log(chunks.pagination.total);
+if (chunks.chunks[0]) {
+  const chunk = await client.documents.getChunk(documentId, chunks.chunks[0].id, {
+    includeAssetUrls: true,
+  });
+  console.log(chunk.chunk.content);
+}
 console.log(archived.status);
 ```
 
@@ -290,7 +304,7 @@ Check out the [examples](./examples) directory for more usage examples:
 
 ```bash
 # Install dependencies
-npm install
+npm ci
 
 # Run tests
 npm test
@@ -316,6 +330,12 @@ npm run build
 See [docs/release-workflow.md](./docs/release-workflow.md) for the
 Changesets-based stable and beta release process.
 
+## Community
+
+- Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
 ## License
 
 [MIT](./LICENSE)

package/dist/index.d.mts

@@ -712,6 +712,104 @@ interface DocumentListResponse {
     /** Documents visible in the namespace */
     documents: Document[];
 }
+/**
+ * Document chunk types supported by document chunk endpoints.
+ */
+type DocumentChunkType = 'text' | 'image' | 'table';
+/**
+ * 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 /v1/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;
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkGetParams {
+    /** Generate asset URLs for media chunks (default: false) */
+    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;
+    /** 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>;
+    /** Generated asset URL when requested and available */
+    assetUrl?: string | null;
+    /** Chunk creation timestamp */
+    createdAt?: Date;
+}
+/**
+ * Response from GET /v1/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 /v1/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.
@@ -727,10 +825,20 @@ declare class Documents extends BaseResource {
      * Get one canonical document by ID.
      */
     get(documentId: string): Promise<Document>;
+    /**
+     * List current-revision chunks for one canonical document.
+     */
+    listChunks(documentId: string, params?: DocumentChunkListParams): Promise<DocumentChunkListResponse>;
+    /**
+     * Get one current-revision chunk for one canonical document.
+     */
+    getChunk(documentId: string, documentChunkId: string, params?: DocumentChunkGetParams): Promise<DocumentChunkResponse>;
     /**
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createChunkListRequestConfig;
+    private createChunkGetRequestConfig;
 }
 
 /**
@@ -902,4 +1010,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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, 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, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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

@@ -712,6 +712,104 @@ interface DocumentListResponse {
     /** Documents visible in the namespace */
     documents: Document[];
 }
+/**
+ * Document chunk types supported by document chunk endpoints.
+ */
+type DocumentChunkType = 'text' | 'image' | 'table';
+/**
+ * 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 /v1/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;
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkGetParams {
+    /** Generate asset URLs for media chunks (default: false) */
+    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;
+    /** 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>;
+    /** Generated asset URL when requested and available */
+    assetUrl?: string | null;
+    /** Chunk creation timestamp */
+    createdAt?: Date;
+}
+/**
+ * Response from GET /v1/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 /v1/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.
@@ -727,10 +825,20 @@ declare class Documents extends BaseResource {
      * Get one canonical document by ID.
      */
     get(documentId: string): Promise<Document>;
+    /**
+     * List current-revision chunks for one canonical document.
+     */
+    listChunks(documentId: string, params?: DocumentChunkListParams): Promise<DocumentChunkListResponse>;
+    /**
+     * Get one current-revision chunk for one canonical document.
+     */
+    getChunk(documentId: string, documentChunkId: string, params?: DocumentChunkGetParams): Promise<DocumentChunkResponse>;
     /**
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createChunkListRequestConfig;
+    private createChunkGetRequestConfig;
 }
 
 /**
@@ -902,4 +1010,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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, 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, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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

@@ -1219,12 +1219,59 @@ var Documents = class extends BaseResource {
   async get(documentId) {
     return this.httpClient.get(`/v1/documents/${documentId}`);
   }
+  /**
+   * List current-revision chunks for one canonical document.
+   */
+  async listChunks(documentId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks`,
+      this.createChunkListRequestConfig(params)
+    );
+  }
+  /**
+   * Get one current-revision chunk for one canonical document.
+   */
+  async getChunk(documentId, documentChunkId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.createChunkGetRequestConfig(params)
+    );
+  }
   /**
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
     return this.httpClient.post(`/v1/documents/${documentId}/archive`);
   }
+  createChunkListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    if (params.chunkType !== void 0) {
+      queryParams.chunk_type = params.chunkType;
+    }
+    if (params.includeAssetUrls === true) {
+      queryParams.include_asset_urls = true;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  createChunkGetRequestConfig(params) {
+    if (params?.includeAssetUrls !== true) {
+      return void 0;
+    }
+    return {
+      params: {
+        include_asset_urls: true
+      }
+    };
+  }
 };
 
 // src/client.ts

package/dist/index.mjs

@@ -1159,12 +1159,59 @@ var Documents = class extends BaseResource {
   async get(documentId) {
     return this.httpClient.get(`/v1/documents/${documentId}`);
   }
+  /**
+   * List current-revision chunks for one canonical document.
+   */
+  async listChunks(documentId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks`,
+      this.createChunkListRequestConfig(params)
+    );
+  }
+  /**
+   * Get one current-revision chunk for one canonical document.
+   */
+  async getChunk(documentId, documentChunkId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.createChunkGetRequestConfig(params)
+    );
+  }
   /**
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
     return this.httpClient.post(`/v1/documents/${documentId}/archive`);
   }
+  createChunkListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    if (params.chunkType !== void 0) {
+      queryParams.chunk_type = params.chunkType;
+    }
+    if (params.includeAssetUrls === true) {
+      queryParams.include_asset_urls = true;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  createChunkGetRequestConfig(params) {
+    if (params?.includeAssetUrls !== true) {
+      return void 0;
+    }
+    return {
+      params: {
+        include_asset_urls: true
+      }
+    };
+  }
 };
 
 // src/client.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Official Node.js SDK for Knowhere document parsing API",
   "keywords": [
     "knowhere",
@@ -60,17 +60,18 @@
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test:ci && npm run build"
   },
   "dependencies": {
-    "axios": "^1.6.0",
+    "axios": "^1.15.2",
     "jszip": "^3.10.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25.2.3",
     "@typescript-eslint/eslint-plugin": "^8.55.0",
     "@typescript-eslint/parser": "^8.55.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
+    "eslint": "^10.2.1",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",