@ontos-ai/knowhere-sdk 0.7.0 → 0.8.0

package/README.md

@@ -147,6 +147,10 @@ For granular control over the job lifecycle:
 const job = await client.jobs.create({
   sourceType: 'file',
   fileName: 'document.pdf',
+  documentMetadata: {
+    createdByClient: 'cli',
+    sourceFileName: 'document.pdf',
+  },
   parsingParams: { model: 'advanced', ocrEnabled: true },
 });
 
@@ -168,19 +172,23 @@ 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.
+finishes. `client.jobs.create(...)` may return a planned `documentId`; persist
+`jobResult.documentId` after publication as the canonical value 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',
+  documentMetadata: {
+    createdByClient: 'notebook',
+    title: 'Support manual',
+  },
 });
 
 const jobResult = await client.jobs.wait(job.jobId);
-const documentId = jobResult.documentId;
+const documentId = jobResult.documentId ?? job.documentId;
 
 if (!documentId) {
   throw new Error('Expected documentId after successful publication.');

package/dist/index.d.mts

@@ -46,6 +46,8 @@ interface Job {
     dataId?: string;
     /** Retrieval namespace for the canonical document */
     namespace?: string;
+    /** Planned stable document identifier for this job, when returned by the API */
+    documentId?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Presigned URL for file upload (if sourceType is 'file') */
@@ -154,6 +156,10 @@ interface WebhookConfig {
     /** Webhook URL to notify on job completion */
     url: string;
 }
+/**
+ * Client-provided display metadata copied onto the published document.
+ */
+type DocumentMetadata = Record<string, unknown>;
 /**
  * Job creation parameters
  */
@@ -170,6 +176,8 @@ interface CreateJobParams {
     namespace?: string;
     /** Existing document identifier when updating a published document */
     documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
     /** Webhook configuration */
@@ -236,6 +244,8 @@ interface ParseParams {
     namespace?: string;
     /** Existing document identifier when updating a published document */
     documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
     /** Additional fragment description */
     addFragDesc?: string;
     /** Knowledge base directory */
@@ -780,6 +790,8 @@ interface Document {
     currentJobResultId?: string;
     /** Original source file name */
     sourceFileName?: string;
+    /** Client-provided display metadata copied from the publishing job */
+    documentMetadata?: Record<string, unknown>;
     /** Document creation timestamp */
     createdAt?: Date;
     /** Last update timestamp */
@@ -1330,4 +1342,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, 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 KnowledgeCacheJobResultParams, type KnowledgeChunkType, 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 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 KnowledgeCacheJobResultParams, type KnowledgeChunkType, 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 };

package/dist/index.d.ts

@@ -46,6 +46,8 @@ interface Job {
     dataId?: string;
     /** Retrieval namespace for the canonical document */
     namespace?: string;
+    /** Planned stable document identifier for this job, when returned by the API */
+    documentId?: string;
     /** Job creation timestamp */
     createdAt: Date;
     /** Presigned URL for file upload (if sourceType is 'file') */
@@ -154,6 +156,10 @@ interface WebhookConfig {
     /** Webhook URL to notify on job completion */
     url: string;
 }
+/**
+ * Client-provided display metadata copied onto the published document.
+ */
+type DocumentMetadata = Record<string, unknown>;
 /**
  * Job creation parameters
  */
@@ -170,6 +176,8 @@ interface CreateJobParams {
     namespace?: string;
     /** Existing document identifier when updating a published document */
     documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
     /** Webhook configuration */
@@ -236,6 +244,8 @@ interface ParseParams {
     namespace?: string;
     /** Existing document identifier when updating a published document */
     documentId?: string;
+    /** Display metadata to copy onto the published document */
+    documentMetadata?: DocumentMetadata;
     /** Additional fragment description */
     addFragDesc?: string;
     /** Knowledge base directory */
@@ -780,6 +790,8 @@ interface Document {
     currentJobResultId?: string;
     /** Original source file name */
     sourceFileName?: string;
+    /** Client-provided display metadata copied from the publishing job */
+    documentMetadata?: Record<string, unknown>;
     /** Document creation timestamp */
     createdAt?: Date;
     /** Last update timestamp */
@@ -1330,4 +1342,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, 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 KnowledgeCacheJobResultParams, type KnowledgeChunkType, 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 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 KnowledgeCacheJobResultParams, type KnowledgeChunkType, 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 };

package/dist/index.js

@@ -1322,11 +1322,7 @@ var Jobs = class extends BaseResource {
    * Create a new parsing job
    */
   async create(params) {
-    const job = await this.httpClient.post(
-      "/v1/jobs",
-      params
-    );
-    delete job.documentId;
+    const job = await this.httpClient.post("/v1/jobs", params);
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -2343,6 +2339,7 @@ var Knowhere = class {
       dataId: params.dataId,
       namespace: params.namespace,
       documentId: params.documentId,
+      documentMetadata: params.documentMetadata,
       parsingParams: buildParsingParams(params),
       webhook
     });

package/dist/index.mjs

@@ -1262,11 +1262,7 @@ var Jobs = class extends BaseResource {
    * Create a new parsing job
    */
   async create(params) {
-    const job = await this.httpClient.post(
-      "/v1/jobs",
-      params
-    );
-    delete job.documentId;
+    const job = await this.httpClient.post("/v1/jobs", params);
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -2283,6 +2279,7 @@ var Knowhere = class {
       dataId: params.dataId,
       namespace: params.namespace,
       documentId: params.documentId,
+      documentMetadata: params.documentMetadata,
       parsingParams: buildParsingParams(params),
       webhook
     });

package/package.json

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