@ontos-ai/knowhere-sdk 0.2.1 → 0.3.1

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
 
@@ -163,6 +165,83 @@ const jobResult = await client.jobs.wait(job.jobId, {
 const result = await client.jobs.load(jobResult);
 ```
 
+### Retrieval and Document Lifecycle
+
+Published documents are queryable through the retrieval API after a job
+finishes. `client.jobs.create(...)` does not return a usable `documentId`;
+persist `jobResult.documentId` after publication if you need to update or
+archive the same document later.
+
+```typescript
+const job = await client.jobs.create({
+  sourceType: 'url',
+  sourceUrl: 'https://example.com/manual.pdf',
+  namespace: 'support-center',
+});
+
+const jobResult = await client.jobs.wait(job.jobId);
+const documentId = jobResult.documentId;
+
+if (!documentId) {
+  throw new Error('Expected documentId after successful publication.');
+}
+
+console.log(documentId);
+
+const response = await client.retrieval.query({
+  namespace: 'support-center',
+  query: 'How do I reset Bluetooth pairing?',
+  topK: 5,
+});
+
+for (const result of response.results) {
+  console.log(result.content);
+  console.log(result.score);
+  console.log(result.source.sourceFileName, result.source.sectionPath);
+}
+```
+
+Retrieval results use one canonical source object:
+
+```typescript
+result.content;
+result.chunkType;
+result.score;
+result.assetUrl;
+result.source.documentId;
+result.source.sourceFileName;
+result.source.sectionPath;
+```
+
+Use `documentId` to update or archive a document:
+
+```typescript
+const updateJob = await client.jobs.create({
+  sourceType: 'url',
+  sourceUrl: 'https://example.com/manual-v2.pdf',
+  documentId,
+});
+
+const documents = await client.documents.list({ namespace: 'support-center' });
+const document = await client.documents.get(documentId);
+const archived = await client.documents.archive(documentId);
+
+console.log(documents.documents.length);
+console.log(document.status);
+console.log(archived.status);
+```
+
+Follow-up queries can exclude documents or sections for one request:
+
+```typescript
+const followUp = await client.retrieval.query({
+  namespace: 'support-center',
+  query: 'battery charging',
+  excludeDocumentIds: ['doc_old'],
+  excludeSections: [{ documentId: 'doc_123', sectionPath: 'Appendix / Legal' }],
+});
+```
+
 ### Error Handling
 
 ```typescript
@@ -213,7 +292,7 @@ Check out the [examples](./examples) directory for more usage examples:
 
 ```bash
 # Install dependencies
-npm install
+npm ci
 
 # Run tests
 npm test
@@ -239,6 +318,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

@@ -41,6 +41,8 @@ interface Job {
     sourceType: string;
     /** Optional custom data identifier */
     dataId?: string;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Presigned URL for file upload (if sourceType is 'file') */
@@ -75,6 +77,10 @@ interface JobResult {
     sourceType: string;
     /** Optional custom data identifier */
     dataId?: string;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
+    /** Stable document identifier for retrieval/document lifecycle APIs */
+    documentId?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Processing progress information */
@@ -157,6 +163,10 @@ interface CreateJobParams {
     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;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
     /** Webhook configuration */
@@ -219,6 +229,10 @@ interface ParseParams {
     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;
     /** Additional fragment description */
     addFragDesc?: string;
     /** Knowledge base directory */
@@ -458,6 +472,10 @@ interface ParseResult {
     readonly tableChunks: TableChunk[];
     /** 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 */
@@ -566,12 +584,165 @@ declare class Jobs extends BaseResource {
     private resolveLoadJobResult;
 }
 
+/**
+ * Section exclusion for follow-up retrieval queries.
+ */
+interface RetrievalSectionExclusion {
+    /** Document containing the section to exclude */
+    documentId: string;
+    /** Human-readable section path to exclude */
+    sectionPath: string;
+}
+/**
+ * Supported retrieval channel names.
+ */
+type RetrievalChannel = 'path' | 'content' | 'term';
+/**
+ * Path filtering mode for retrieval queries.
+ */
+type RetrievalFilterMode = 'delete' | 'keep';
+/**
+ * Retrieval query parameters.
+ */
+interface RetrievalQueryParams {
+    /** Search query text */
+    query: string;
+    /** Retrieval namespace. Defaults to the server's default namespace when omitted. */
+    namespace?: string;
+    /** Maximum number of results to return */
+    topK?: number;
+    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
+    dataType?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Path keywords for include/exclude filtering */
+    signalPaths?: string[];
+    /** Signal path filter mode */
+    filterMode?: RetrievalFilterMode;
+    /** Retrieval channels to run. Defaults to all channels when omitted. */
+    channels?: RetrievalChannel[];
+    /** Per-channel weight overrides for reciprocal-rank fusion */
+    channelWeights?: Partial<Record<RetrievalChannel, number>>;
+    /** Enable LLM reranking after channel fusion */
+    rerank?: boolean;
+    /** Minimum retrieval score threshold after fusion */
+    threshold?: number;
+    /** Override the internal per-channel recall count */
+    internalRecallK?: number;
+    /** Documents to exclude for this request only */
+    excludeDocumentIds?: string[];
+    /** Document sections to exclude for this request only */
+    excludeSections?: RetrievalSectionExclusion[];
+}
+/**
+ * Caller-facing source reference attached to a retrieval result.
+ */
+interface RetrievalSource {
+    /** Stable document identifier */
+    documentId?: string;
+    /** Original source file name */
+    sourceFileName?: string;
+    /** Human-readable section path */
+    sectionPath?: string;
+}
+/**
+ * Canonical chunk result returned by retrieval query.
+ */
+interface RetrievalResult {
+    /** Knowledge content to use directly in the caller's answer */
+    content: string;
+    /** Chunk type, for example text, image, or table */
+    chunkType: string;
+    /** Retrieval score returned by the API */
+    score: number;
+    /** Presigned asset URL for media chunks when available */
+    assetUrl?: string;
+    /** Source reference for this result */
+    source: RetrievalSource;
+}
+/**
+ * Response from POST /v1/retrieval/query.
+ */
+interface RetrievalQueryResponse {
+    /** Namespace searched by the API */
+    namespace: string;
+    /** Echoed query text */
+    query: string;
+    /** Retrieval router path used by the API for this query */
+    routerUsed?: string;
+    /** Ranked retrieval results */
+    results: RetrievalResult[];
+}
+
+/**
+ * Resource for querying published retrieval documents.
+ */
+declare class Retrieval extends BaseResource {
+    /**
+     * Query published documents.
+     */
+    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;
+    /** Document creation timestamp */
+    createdAt?: Date;
+    /** Last update timestamp */
+    updatedAt?: Date;
+    /** Archive timestamp, when archived */
+    archivedAt?: Date;
+}
+/**
+ * Response from GET /v1/documents.
+ */
+interface DocumentListResponse {
+    /** Namespace listed by the API */
+    namespace: string;
+    /** Documents visible in the namespace */
+    documents: Document[];
+}
+
+/**
+ * Resource for canonical document lifecycle operations.
+ */
+declare class Documents extends BaseResource {
+    /**
+     * List canonical documents in a namespace.
+     */
+    list(params?: {
+        namespace?: string;
+    }): Promise<DocumentListResponse>;
+    /**
+     * Get one canonical document by ID.
+     */
+    get(documentId: string): Promise<Document>;
+    /**
+     * Archive one canonical document by ID.
+     */
+    archive(documentId: string): Promise<Document>;
+}
+
 /**
  * Main Knowhere SDK client
  */
 declare class Knowhere {
     /** Jobs resource for low-level API */
     readonly jobs: Jobs;
+    /** Retrieval resource for querying published documents */
+    readonly retrieval: Retrieval;
+    /** Documents resource for canonical document lifecycle operations */
+    readonly documents: Documents;
     private httpClient;
     /**
      * Create a new Knowhere client
@@ -731,4 +902,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 FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default };
+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 };

package/dist/index.d.ts

@@ -41,6 +41,8 @@ interface Job {
     sourceType: string;
     /** Optional custom data identifier */
     dataId?: string;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Presigned URL for file upload (if sourceType is 'file') */
@@ -75,6 +77,10 @@ interface JobResult {
     sourceType: string;
     /** Optional custom data identifier */
     dataId?: string;
+    /** Retrieval namespace for the canonical document */
+    namespace?: string;
+    /** Stable document identifier for retrieval/document lifecycle APIs */
+    documentId?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Processing progress information */
@@ -157,6 +163,10 @@ interface CreateJobParams {
     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;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
     /** Webhook configuration */
@@ -219,6 +229,10 @@ interface ParseParams {
     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;
     /** Additional fragment description */
     addFragDesc?: string;
     /** Knowledge base directory */
@@ -458,6 +472,10 @@ interface ParseResult {
     readonly tableChunks: TableChunk[];
     /** 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 */
@@ -566,12 +584,165 @@ declare class Jobs extends BaseResource {
     private resolveLoadJobResult;
 }
 
+/**
+ * Section exclusion for follow-up retrieval queries.
+ */
+interface RetrievalSectionExclusion {
+    /** Document containing the section to exclude */
+    documentId: string;
+    /** Human-readable section path to exclude */
+    sectionPath: string;
+}
+/**
+ * Supported retrieval channel names.
+ */
+type RetrievalChannel = 'path' | 'content' | 'term';
+/**
+ * Path filtering mode for retrieval queries.
+ */
+type RetrievalFilterMode = 'delete' | 'keep';
+/**
+ * Retrieval query parameters.
+ */
+interface RetrievalQueryParams {
+    /** Search query text */
+    query: string;
+    /** Retrieval namespace. Defaults to the server's default namespace when omitted. */
+    namespace?: string;
+    /** Maximum number of results to return */
+    topK?: number;
+    /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
+    dataType?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Path keywords for include/exclude filtering */
+    signalPaths?: string[];
+    /** Signal path filter mode */
+    filterMode?: RetrievalFilterMode;
+    /** Retrieval channels to run. Defaults to all channels when omitted. */
+    channels?: RetrievalChannel[];
+    /** Per-channel weight overrides for reciprocal-rank fusion */
+    channelWeights?: Partial<Record<RetrievalChannel, number>>;
+    /** Enable LLM reranking after channel fusion */
+    rerank?: boolean;
+    /** Minimum retrieval score threshold after fusion */
+    threshold?: number;
+    /** Override the internal per-channel recall count */
+    internalRecallK?: number;
+    /** Documents to exclude for this request only */
+    excludeDocumentIds?: string[];
+    /** Document sections to exclude for this request only */
+    excludeSections?: RetrievalSectionExclusion[];
+}
+/**
+ * Caller-facing source reference attached to a retrieval result.
+ */
+interface RetrievalSource {
+    /** Stable document identifier */
+    documentId?: string;
+    /** Original source file name */
+    sourceFileName?: string;
+    /** Human-readable section path */
+    sectionPath?: string;
+}
+/**
+ * Canonical chunk result returned by retrieval query.
+ */
+interface RetrievalResult {
+    /** Knowledge content to use directly in the caller's answer */
+    content: string;
+    /** Chunk type, for example text, image, or table */
+    chunkType: string;
+    /** Retrieval score returned by the API */
+    score: number;
+    /** Presigned asset URL for media chunks when available */
+    assetUrl?: string;
+    /** Source reference for this result */
+    source: RetrievalSource;
+}
+/**
+ * Response from POST /v1/retrieval/query.
+ */
+interface RetrievalQueryResponse {
+    /** Namespace searched by the API */
+    namespace: string;
+    /** Echoed query text */
+    query: string;
+    /** Retrieval router path used by the API for this query */
+    routerUsed?: string;
+    /** Ranked retrieval results */
+    results: RetrievalResult[];
+}
+
+/**
+ * Resource for querying published retrieval documents.
+ */
+declare class Retrieval extends BaseResource {
+    /**
+     * Query published documents.
+     */
+    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;
+    /** Document creation timestamp */
+    createdAt?: Date;
+    /** Last update timestamp */
+    updatedAt?: Date;
+    /** Archive timestamp, when archived */
+    archivedAt?: Date;
+}
+/**
+ * Response from GET /v1/documents.
+ */
+interface DocumentListResponse {
+    /** Namespace listed by the API */
+    namespace: string;
+    /** Documents visible in the namespace */
+    documents: Document[];
+}
+
+/**
+ * Resource for canonical document lifecycle operations.
+ */
+declare class Documents extends BaseResource {
+    /**
+     * List canonical documents in a namespace.
+     */
+    list(params?: {
+        namespace?: string;
+    }): Promise<DocumentListResponse>;
+    /**
+     * Get one canonical document by ID.
+     */
+    get(documentId: string): Promise<Document>;
+    /**
+     * Archive one canonical document by ID.
+     */
+    archive(documentId: string): Promise<Document>;
+}
+
 /**
  * Main Knowhere SDK client
  */
 declare class Knowhere {
     /** Jobs resource for low-level API */
     readonly jobs: Jobs;
+    /** Retrieval resource for querying published documents */
+    readonly retrieval: Retrieval;
+    /** Documents resource for canonical document lifecycle operations */
+    readonly documents: Documents;
     private httpClient;
     /**
      * Create a new Knowhere client
@@ -731,4 +902,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 FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default };
+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 };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   BadRequestError: () => BadRequestError,
   ChecksumError: () => ChecksumError,
   ConflictError: () => ConflictError,
+  Documents: () => Documents,
   GatewayTimeoutError: () => GatewayTimeoutError,
   InternalServerError: () => InternalServerError,
   InvalidStateError: () => InvalidStateError,
@@ -48,6 +49,7 @@ __export(index_exports, {
   PermissionDeniedError: () => PermissionDeniedError,
   PollingTimeoutError: () => PollingTimeoutError,
   RateLimitError: () => RateLimitError,
+  Retrieval: () => Retrieval,
   ServiceUnavailableError: () => ServiceUnavailableError,
   TimeoutError: () => TimeoutError,
   VERSION: () => VERSION,
@@ -344,6 +346,15 @@ function enrichJobResult(jobResult) {
   }
   return jobResult;
 }
+function enrichParseResult(parseResult2, scope) {
+  if (scope.namespace !== void 0) {
+    parseResult2.namespace = scope.namespace;
+  }
+  if (scope.documentId !== void 0) {
+    parseResult2.documentId = scope.documentId;
+  }
+  return parseResult2;
+}
 function sanitizePath(path2) {
   let sanitized = path2.replace(/^\/+/, "");
   sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
@@ -1075,7 +1086,11 @@ 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(
+      "/v1/jobs",
+      params
+    );
+    delete job.documentId;
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -1123,7 +1138,8 @@ var Jobs = class extends BaseResource {
     if (!jobResult.resultUrl) {
       throw new NotFoundError("Result URL not available");
     }
-    return parseResult(this.httpClient, jobResult.resultUrl, options);
+    const result = await parseResult(this.httpClient, jobResult.resultUrl, options);
+    return enrichParseResult(result, jobResult);
   }
   isHttpUrl(value) {
     return /^https?:\/\//i.test(value);
@@ -1174,6 +1190,43 @@ var Jobs = class extends BaseResource {
   }
 };
 
+// src/resources/retrieval.ts
+var Retrieval = class extends BaseResource {
+  /**
+   * Query published documents.
+   */
+  async query(params) {
+    return this.httpClient.post("/v1/retrieval/query", params);
+  }
+};
+
+// src/resources/documents.ts
+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);
+  }
+  /**
+   * Get one canonical document by ID.
+   */
+  async get(documentId) {
+    return this.httpClient.get(`/v1/documents/${documentId}`);
+  }
+  /**
+   * Archive one canonical document by ID.
+   */
+  async archive(documentId) {
+    return this.httpClient.post(`/v1/documents/${documentId}/archive`);
+  }
+};
+
 // src/client.ts
 function inferFileName(file, explicitFileName) {
   if (explicitFileName) {
@@ -1193,6 +1246,10 @@ function isReadStream2(file) {
 var Knowhere = class {
   /** Jobs resource for low-level API */
   jobs;
+  /** Retrieval resource for querying published documents */
+  retrieval;
+  /** Documents resource for canonical document lifecycle operations */
+  documents;
   httpClient;
   /**
    * Create a new Knowhere client
@@ -1216,6 +1273,8 @@ var Knowhere = class {
       httpsAgent: options.httpsAgent
     });
     this.jobs = new Jobs(this.httpClient);
+    this.retrieval = new Retrieval(this.httpClient);
+    this.documents = new Documents(this.httpClient);
   }
   /**
    * High-level API: Parse a document and return structured results
@@ -1273,6 +1332,8 @@ var Knowhere = class {
       sourceUrl: params.url,
       fileName: resolvedFileName,
       dataId: params.dataId,
+      namespace: params.namespace,
+      documentId: params.documentId,
       parsingParams: Object.keys(parsingParams).length > 0 ? parsingParams : void 0,
       webhook
     });
@@ -1292,7 +1353,7 @@ var Knowhere = class {
     const result = await this.jobs.load(jobResult, {
       verifyChecksum: params.verifyChecksum
     });
-    return result;
+    return enrichParseResult(result, jobResult);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1302,6 +1363,7 @@ var Knowhere = class {
   BadRequestError,
   ChecksumError,
   ConflictError,
+  Documents,
   GatewayTimeoutError,
   InternalServerError,
   InvalidStateError,
@@ -1315,6 +1377,7 @@ var Knowhere = class {
   PermissionDeniedError,
   PollingTimeoutError,
   RateLimitError,
+  Retrieval,
   ServiceUnavailableError,
   TimeoutError,
   VERSION,

package/dist/index.mjs

@@ -286,6 +286,15 @@ function enrichJobResult(jobResult) {
   }
   return jobResult;
 }
+function enrichParseResult(parseResult2, scope) {
+  if (scope.namespace !== void 0) {
+    parseResult2.namespace = scope.namespace;
+  }
+  if (scope.documentId !== void 0) {
+    parseResult2.documentId = scope.documentId;
+  }
+  return parseResult2;
+}
 function sanitizePath(path2) {
   let sanitized = path2.replace(/^\/+/, "");
   sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
@@ -1017,7 +1026,11 @@ 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(
+      "/v1/jobs",
+      params
+    );
+    delete job.documentId;
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -1065,7 +1078,8 @@ var Jobs = class extends BaseResource {
     if (!jobResult.resultUrl) {
       throw new NotFoundError("Result URL not available");
     }
-    return parseResult(this.httpClient, jobResult.resultUrl, options);
+    const result = await parseResult(this.httpClient, jobResult.resultUrl, options);
+    return enrichParseResult(result, jobResult);
   }
   isHttpUrl(value) {
     return /^https?:\/\//i.test(value);
@@ -1116,6 +1130,43 @@ var Jobs = class extends BaseResource {
   }
 };
 
+// src/resources/retrieval.ts
+var Retrieval = class extends BaseResource {
+  /**
+   * Query published documents.
+   */
+  async query(params) {
+    return this.httpClient.post("/v1/retrieval/query", params);
+  }
+};
+
+// src/resources/documents.ts
+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);
+  }
+  /**
+   * Get one canonical document by ID.
+   */
+  async get(documentId) {
+    return this.httpClient.get(`/v1/documents/${documentId}`);
+  }
+  /**
+   * Archive one canonical document by ID.
+   */
+  async archive(documentId) {
+    return this.httpClient.post(`/v1/documents/${documentId}/archive`);
+  }
+};
+
 // src/client.ts
 function inferFileName(file, explicitFileName) {
   if (explicitFileName) {
@@ -1135,6 +1186,10 @@ function isReadStream2(file) {
 var Knowhere = class {
   /** Jobs resource for low-level API */
   jobs;
+  /** Retrieval resource for querying published documents */
+  retrieval;
+  /** Documents resource for canonical document lifecycle operations */
+  documents;
   httpClient;
   /**
    * Create a new Knowhere client
@@ -1158,6 +1213,8 @@ var Knowhere = class {
       httpsAgent: options.httpsAgent
     });
     this.jobs = new Jobs(this.httpClient);
+    this.retrieval = new Retrieval(this.httpClient);
+    this.documents = new Documents(this.httpClient);
   }
   /**
    * High-level API: Parse a document and return structured results
@@ -1215,6 +1272,8 @@ var Knowhere = class {
       sourceUrl: params.url,
       fileName: resolvedFileName,
       dataId: params.dataId,
+      namespace: params.namespace,
+      documentId: params.documentId,
       parsingParams: Object.keys(parsingParams).length > 0 ? parsingParams : void 0,
       webhook
     });
@@ -1234,7 +1293,7 @@ var Knowhere = class {
     const result = await this.jobs.load(jobResult, {
       verifyChecksum: params.verifyChecksum
     });
-    return result;
+    return enrichParseResult(result, jobResult);
   }
 };
 export {
@@ -1243,6 +1302,7 @@ export {
   BadRequestError,
   ChecksumError,
   ConflictError,
+  Documents,
   GatewayTimeoutError,
   InternalServerError,
   InvalidStateError,
@@ -1256,6 +1316,7 @@ export {
   PermissionDeniedError,
   PollingTimeoutError,
   RateLimitError,
+  Retrieval,
   ServiceUnavailableError,
   TimeoutError,
   VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-sdk",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",