@ontos-ai/knowhere-sdk 0.7.0 → 0.9.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.');
@@ -305,6 +313,30 @@ console.log(serverSearch.references);
 Local grep and reads use the cached parse result, not server-side chunk scans.
 Search uses the Knowhere API retrieval query; local document IDs only help map
 returned server document IDs back to local cache IDs when available.
+If a search result only has a published `documentId`, or an async parse flow only
+has a completed `jobId`, read-oriented helpers can accept that remote identifier
+directly and will sync the result into the local cache before reading. For a
+`documentId`, the SDK resolves the document's current published `jobId` and then
+downloads the parser result ZIP through the same `cacheJobResult(...)` path:
+
+```typescript
+const remoteRead = await client.knowledge.readChunks({
+  documentId: 'doc_123',
+  sectionPath: 'Overview',
+  limit: 5,
+});
+
+const remoteOutline = await client.knowledge.getDocumentOutline({
+  documentId: 'doc_123',
+});
+
+const jobRead = await client.knowledge.readChunks({
+  jobId: jobResult.jobId,
+  localDocumentId: 'manual-v1',
+  limit: 5,
+});
+```
+
 The MCP package is a wrapper over this SDK interface; install it only when an
 agent host needs an MCP server. See the MCP package README for Codex, Claude
 Code, Claude Desktop, and generic stdio MCP host configuration examples.

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 */
@@ -984,6 +996,20 @@ interface KnowledgeCacheJobResultParams {
     localDocumentId?: string;
     verifyChecksum?: boolean;
 }
+interface KnowledgeCacheDocumentParams {
+    /** Canonical Knowhere document identifier from published retrieval results. */
+    documentId: string;
+    /** Optional local cache identifier to use for the localized document copy. */
+    localDocumentId?: string;
+}
+interface KnowledgeDocumentReference {
+    /** Stable local identifier used by cached outline/read/grep methods. */
+    localDocumentId?: string;
+    /** Canonical Knowhere document identifier from published retrieval results. */
+    documentId?: string;
+    /** Server parse job identifier whose completed result should be cached before reading. */
+    jobId?: string;
+}
 interface KnowledgeSection {
     sectionPath: string;
     sectionTitle: string;
@@ -1002,8 +1028,7 @@ interface KnowledgeOutline {
     sections: KnowledgeSection[];
     sectionTree: KnowledgeSection[];
 }
-interface KnowledgeReadParams {
-    localDocumentId: string;
+interface KnowledgeReadParams extends KnowledgeDocumentReference {
     sectionPath?: string;
     startChunk?: number;
     endChunk?: number;
@@ -1026,8 +1051,7 @@ interface KnowledgeReadResponse {
     chunks: KnowledgeReadChunk[];
     nextChunk?: number;
 }
-interface KnowledgeGrepParams {
-    localDocumentId: string;
+interface KnowledgeGrepParams extends KnowledgeDocumentReference {
     pattern: string;
     isRegex?: boolean;
     isCaseSensitive?: boolean;
@@ -1099,13 +1123,17 @@ declare class Knowledge {
     getJobStatus(jobId: string): Promise<KnowledgeAsyncJobStatusResponse>;
     recoverPendingAsyncParseJobs(): Promise<KnowledgeStartupRecoveryResponse>;
     cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
+    cacheDocument(params: KnowledgeCacheDocumentParams): Promise<LocalKnowledgeParseResponse>;
     private resolveAsyncCache;
     listDocuments(): Promise<LocalKnowledgeDocument[]>;
-    getDocumentOutline(localDocumentId: string): Promise<KnowledgeOutline>;
+    getDocumentOutline(reference: string | KnowledgeDocumentReference): Promise<KnowledgeOutline>;
     readChunks(params: KnowledgeReadParams): Promise<KnowledgeReadResponse>;
     grepChunks(params: KnowledgeGrepParams): Promise<KnowledgeGrepResponse>;
     search(params: KnowledgeSearchParams): Promise<KnowledgeSearchResponse>;
     private resolveSearchDocuments;
+    private loadReadableResult;
+    private findLocalDocumentByRemoteId;
+    private getPublishedDocumentJobId;
 }
 
 interface StoredAsyncParseJob {
@@ -1330,4 +1358,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 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 };

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 */
@@ -984,6 +996,20 @@ interface KnowledgeCacheJobResultParams {
     localDocumentId?: string;
     verifyChecksum?: boolean;
 }
+interface KnowledgeCacheDocumentParams {
+    /** Canonical Knowhere document identifier from published retrieval results. */
+    documentId: string;
+    /** Optional local cache identifier to use for the localized document copy. */
+    localDocumentId?: string;
+}
+interface KnowledgeDocumentReference {
+    /** Stable local identifier used by cached outline/read/grep methods. */
+    localDocumentId?: string;
+    /** Canonical Knowhere document identifier from published retrieval results. */
+    documentId?: string;
+    /** Server parse job identifier whose completed result should be cached before reading. */
+    jobId?: string;
+}
 interface KnowledgeSection {
     sectionPath: string;
     sectionTitle: string;
@@ -1002,8 +1028,7 @@ interface KnowledgeOutline {
     sections: KnowledgeSection[];
     sectionTree: KnowledgeSection[];
 }
-interface KnowledgeReadParams {
-    localDocumentId: string;
+interface KnowledgeReadParams extends KnowledgeDocumentReference {
     sectionPath?: string;
     startChunk?: number;
     endChunk?: number;
@@ -1026,8 +1051,7 @@ interface KnowledgeReadResponse {
     chunks: KnowledgeReadChunk[];
     nextChunk?: number;
 }
-interface KnowledgeGrepParams {
-    localDocumentId: string;
+interface KnowledgeGrepParams extends KnowledgeDocumentReference {
     pattern: string;
     isRegex?: boolean;
     isCaseSensitive?: boolean;
@@ -1099,13 +1123,17 @@ declare class Knowledge {
     getJobStatus(jobId: string): Promise<KnowledgeAsyncJobStatusResponse>;
     recoverPendingAsyncParseJobs(): Promise<KnowledgeStartupRecoveryResponse>;
     cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
+    cacheDocument(params: KnowledgeCacheDocumentParams): Promise<LocalKnowledgeParseResponse>;
     private resolveAsyncCache;
     listDocuments(): Promise<LocalKnowledgeDocument[]>;
-    getDocumentOutline(localDocumentId: string): Promise<KnowledgeOutline>;
+    getDocumentOutline(reference: string | KnowledgeDocumentReference): Promise<KnowledgeOutline>;
     readChunks(params: KnowledgeReadParams): Promise<KnowledgeReadResponse>;
     grepChunks(params: KnowledgeGrepParams): Promise<KnowledgeGrepResponse>;
     search(params: KnowledgeSearchParams): Promise<KnowledgeSearchResponse>;
     private resolveSearchDocuments;
+    private loadReadableResult;
+    private findLocalDocumentByRemoteId;
+    private getPublishedDocumentJobId;
 }
 
 interface StoredAsyncParseJob {
@@ -1330,4 +1358,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 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 };

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);
     }
@@ -1510,6 +1506,9 @@ var Documents = class extends BaseResource {
   }
 };
 
+// src/knowledge/knowledge.ts
+var import_crypto2 = require("crypto");
+
 // src/knowledge/local-store.ts
 var import_crypto = require("crypto");
 var import_os = __toESM(require("os"));
@@ -1738,6 +1737,8 @@ var MAX_READ_LIMIT = 40;
 var DEFAULT_GREP_LIMIT = 20;
 var MAX_GREP_LIMIT = 50;
 var DEFAULT_CONTEXT_CHARS = 80;
+var SAFE_LOCAL_DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var REMOTE_DOCUMENT_ID_PATTERN = /^doc[_-]/;
 var Knowledge = class _Knowledge {
   client;
   store;
@@ -1793,6 +1794,19 @@ var Knowledge = class _Knowledge {
     });
     return { document, result };
   }
+  async cacheDocument(params) {
+    if (!params.documentId) {
+      throw new ValidationError("documentId is required");
+    }
+    const existing = await this.findLocalDocumentByRemoteId(
+      params.documentId
+    );
+    const jobId = await this.getPublishedDocumentJobId(params.documentId);
+    return this.cacheJobResult({
+      jobId,
+      localDocumentId: params.localDocumentId ?? existing?.localDocumentId ?? createLocalDocumentIdForRemote(params.documentId)
+    });
+  }
   async resolveAsyncCache(jobId, isDone, isFailed) {
     const trackedJob = await this.store.getAsyncParseJob(jobId);
     if (!trackedJob) {
@@ -1849,8 +1863,8 @@ var Knowledge = class _Knowledge {
   async listDocuments() {
     return this.store.listDocuments();
   }
-  async getDocumentOutline(localDocumentId) {
-    const { document, result } = await this.store.loadResult(localDocumentId);
+  async getDocumentOutline(reference) {
+    const { document, result } = await this.loadReadableResult(reference);
     const chunks = indexChunks(result);
     const sections = buildFlatSections(result, chunks);
     const sectionTree = result.docNav?.sections && result.docNav.sections.length > 0 ? result.docNav.sections.map(
@@ -1865,7 +1879,7 @@ var Knowledge = class _Knowledge {
     };
   }
   async readChunks(params) {
-    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const { document, result } = await this.loadReadableResult(params);
     const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
     const chunks = indexChunks(result).filter((chunk) => matchesReadScope(chunk, params));
     const selected = selectReadWindow(chunks, params, limit);
@@ -1881,7 +1895,7 @@ var Knowledge = class _Knowledge {
     if (!params.pattern) {
       throw new ValidationError("pattern is required");
     }
-    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const { document, result } = await this.loadReadableResult(params);
     const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
     const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
     const matcher = createMatcher(params);
@@ -1951,7 +1965,68 @@ var Knowledge = class _Knowledge {
     const requested = new Set(localDocumentIds);
     return documents.filter((document) => requested.has(document.localDocumentId));
   }
+  async loadReadableResult(reference) {
+    const normalized = normalizeDocumentReference(reference);
+    if (normalized.documentId) {
+      return this.cacheDocument({
+        documentId: normalized.documentId,
+        localDocumentId: normalized.localDocumentId
+      });
+    }
+    if (normalized.jobId) {
+      return this.cacheJobResult({
+        jobId: normalized.jobId,
+        localDocumentId: normalized.localDocumentId
+      });
+    }
+    if (!normalized.localDocumentId) {
+      throw new ValidationError("localDocumentId, documentId, or jobId is required");
+    }
+    const document = await this.store.getDocument(normalized.localDocumentId);
+    if (document) {
+      return this.store.loadResult(normalized.localDocumentId);
+    }
+    if (looksLikeRemoteDocumentId(normalized.localDocumentId)) {
+      return this.cacheDocument({
+        documentId: normalized.localDocumentId,
+        localDocumentId: createLocalDocumentIdForRemote(normalized.localDocumentId)
+      });
+    }
+    throw new Error(`Local Knowhere document not found: ${normalized.localDocumentId}`);
+  }
+  async findLocalDocumentByRemoteId(documentId) {
+    const documents = await this.store.listDocuments();
+    return documents.find((document) => document.documentId === documentId);
+  }
+  async getPublishedDocumentJobId(documentId) {
+    const response = await this.client.documents.listChunks(documentId, {
+      page: 1,
+      pageSize: 1
+    });
+    if (!response.jobId) {
+      throw new Error(
+        `Cannot sync server document ${documentId}: current published job id was not returned.`
+      );
+    }
+    return response.jobId;
+  }
 };
+function normalizeDocumentReference(reference) {
+  if (typeof reference === "string") {
+    return { localDocumentId: reference };
+  }
+  return reference;
+}
+function looksLikeRemoteDocumentId(value) {
+  return REMOTE_DOCUMENT_ID_PATTERN.test(value);
+}
+function createLocalDocumentIdForRemote(documentId) {
+  if (SAFE_LOCAL_DOCUMENT_ID_PATTERN.test(documentId) && !documentId.includes("..") && !documentId.includes("/") && !documentId.includes("\\")) {
+    return documentId;
+  }
+  const hash = (0, import_crypto2.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
+  return `remote_${hash}`;
+}
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
@@ -2343,6 +2418,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);
     }
@@ -1450,6 +1446,9 @@ var Documents = class extends BaseResource {
   }
 };
 
+// src/knowledge/knowledge.ts
+import { createHash as createHash2 } from "crypto";
+
 // src/knowledge/local-store.ts
 import { createHash } from "crypto";
 import os from "os";
@@ -1678,6 +1677,8 @@ var MAX_READ_LIMIT = 40;
 var DEFAULT_GREP_LIMIT = 20;
 var MAX_GREP_LIMIT = 50;
 var DEFAULT_CONTEXT_CHARS = 80;
+var SAFE_LOCAL_DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var REMOTE_DOCUMENT_ID_PATTERN = /^doc[_-]/;
 var Knowledge = class _Knowledge {
   client;
   store;
@@ -1733,6 +1734,19 @@ var Knowledge = class _Knowledge {
     });
     return { document, result };
   }
+  async cacheDocument(params) {
+    if (!params.documentId) {
+      throw new ValidationError("documentId is required");
+    }
+    const existing = await this.findLocalDocumentByRemoteId(
+      params.documentId
+    );
+    const jobId = await this.getPublishedDocumentJobId(params.documentId);
+    return this.cacheJobResult({
+      jobId,
+      localDocumentId: params.localDocumentId ?? existing?.localDocumentId ?? createLocalDocumentIdForRemote(params.documentId)
+    });
+  }
   async resolveAsyncCache(jobId, isDone, isFailed) {
     const trackedJob = await this.store.getAsyncParseJob(jobId);
     if (!trackedJob) {
@@ -1789,8 +1803,8 @@ var Knowledge = class _Knowledge {
   async listDocuments() {
     return this.store.listDocuments();
   }
-  async getDocumentOutline(localDocumentId) {
-    const { document, result } = await this.store.loadResult(localDocumentId);
+  async getDocumentOutline(reference) {
+    const { document, result } = await this.loadReadableResult(reference);
     const chunks = indexChunks(result);
     const sections = buildFlatSections(result, chunks);
     const sectionTree = result.docNav?.sections && result.docNav.sections.length > 0 ? result.docNav.sections.map(
@@ -1805,7 +1819,7 @@ var Knowledge = class _Knowledge {
     };
   }
   async readChunks(params) {
-    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const { document, result } = await this.loadReadableResult(params);
     const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
     const chunks = indexChunks(result).filter((chunk) => matchesReadScope(chunk, params));
     const selected = selectReadWindow(chunks, params, limit);
@@ -1821,7 +1835,7 @@ var Knowledge = class _Knowledge {
     if (!params.pattern) {
       throw new ValidationError("pattern is required");
     }
-    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const { document, result } = await this.loadReadableResult(params);
     const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
     const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
     const matcher = createMatcher(params);
@@ -1891,7 +1905,68 @@ var Knowledge = class _Knowledge {
     const requested = new Set(localDocumentIds);
     return documents.filter((document) => requested.has(document.localDocumentId));
   }
+  async loadReadableResult(reference) {
+    const normalized = normalizeDocumentReference(reference);
+    if (normalized.documentId) {
+      return this.cacheDocument({
+        documentId: normalized.documentId,
+        localDocumentId: normalized.localDocumentId
+      });
+    }
+    if (normalized.jobId) {
+      return this.cacheJobResult({
+        jobId: normalized.jobId,
+        localDocumentId: normalized.localDocumentId
+      });
+    }
+    if (!normalized.localDocumentId) {
+      throw new ValidationError("localDocumentId, documentId, or jobId is required");
+    }
+    const document = await this.store.getDocument(normalized.localDocumentId);
+    if (document) {
+      return this.store.loadResult(normalized.localDocumentId);
+    }
+    if (looksLikeRemoteDocumentId(normalized.localDocumentId)) {
+      return this.cacheDocument({
+        documentId: normalized.localDocumentId,
+        localDocumentId: createLocalDocumentIdForRemote(normalized.localDocumentId)
+      });
+    }
+    throw new Error(`Local Knowhere document not found: ${normalized.localDocumentId}`);
+  }
+  async findLocalDocumentByRemoteId(documentId) {
+    const documents = await this.store.listDocuments();
+    return documents.find((document) => document.documentId === documentId);
+  }
+  async getPublishedDocumentJobId(documentId) {
+    const response = await this.client.documents.listChunks(documentId, {
+      page: 1,
+      pageSize: 1
+    });
+    if (!response.jobId) {
+      throw new Error(
+        `Cannot sync server document ${documentId}: current published job id was not returned.`
+      );
+    }
+    return response.jobId;
+  }
 };
+function normalizeDocumentReference(reference) {
+  if (typeof reference === "string") {
+    return { localDocumentId: reference };
+  }
+  return reference;
+}
+function looksLikeRemoteDocumentId(value) {
+  return REMOTE_DOCUMENT_ID_PATTERN.test(value);
+}
+function createLocalDocumentIdForRemote(documentId) {
+  if (SAFE_LOCAL_DOCUMENT_ID_PATTERN.test(documentId) && !documentId.includes("..") && !documentId.includes("/") && !documentId.includes("\\")) {
+    return documentId;
+  }
+  const hash = createHash2("sha256").update(documentId).digest("hex").slice(0, 16);
+  return `remote_${hash}`;
+}
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
@@ -2283,6 +2358,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.9.0",
   "description": "Official Node.js SDK for Knowhere document parsing API",
   "keywords": [
     "knowhere",