@opengeni/documents 0.5.18 → 0.5.38

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { Settings } from "@opengeni/config";
-import type { AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentAuthorityKind, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, DocumentVisibility, FileAsset, KnowledgeSourceKind } from "@opengeni/contracts";
+import type { AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentAuthorityKind, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, DocumentVisibility, FileAsset, KnowledgeBrowseResponse, KnowledgeRecord, KnowledgeSearchResponse, KnowledgeSourceKind, ListIndexedDocumentsResponse } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 import type { ObjectStorage } from "@opengeni/storage";
+export { projectKnowledgeRecord } from "./knowledge-projection.js";
 export declare const DEFAULT_DOCUMENT_PARSER = "liteparse";
 export declare const DEFAULT_DOCUMENT_EMBEDDING_MODEL = "text-embedding-3-large";
 export declare const DEFAULT_DOCUMENT_EMBEDDING_DIMENSIONS = 3072;
@@ -10,6 +11,7 @@ export declare const DEFAULT_DOCUMENT_CHUNK_OVERLAP = 160;
 export declare const DEFAULT_DOCUMENT_CURATION_MODEL = "gpt-4o-mini";
 export declare const DOCUMENT_CURATION_MAX_INPUT_CHARS = 24000;
 export declare const DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES = 1024;
+export declare const DOCUMENT_INDEX_CHECKPOINT_MAX_CHARS = 1024;
 export declare const DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE = 0.75;
 export declare const DEFAULT_BASE_NAME = "Default";
 export declare const DEFAULT_BASE_DESCRIPTION = "Default base for dropped files and notes.";
@@ -134,6 +136,26 @@ export type EffectiveDocumentSearchInput = Omit<DocumentSearchInput, "access"> &
     /** Agent retrieval additionally enforces documents.agent_access. */
     surface: "human" | "agent";
 };
+export type ListEffectiveIndexedDocumentsInput = {
+    accountId: string;
+    workspaceId: string;
+    /** Immutable human subject accepted for the logical request/turn. */
+    initiatingSubjectId: string;
+    checkpoint?: string | undefined;
+    limit?: number | undefined;
+};
+export type EffectiveKnowledgeBrowseInput = {
+    accountId: string;
+    workspaceId: string;
+    /** Immutable human subject accepted for the logical request/turn. */
+    initiatingSubjectId: string;
+    /** Omit to browse top-level documents; pass a document record id for chunks. */
+    parentId?: string | undefined;
+    topic?: string | undefined;
+    sourceKinds?: KnowledgeSourceKind[] | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
+};
 export type DocumentIndexHooks = {
     beforeEmbed?: (input: {
         accountId: string;
@@ -156,7 +178,7 @@ export declare class RecursiveTextChunker implements DocumentChunker {
     chunk(parsed: ParsedDocument, file: FileAsset): DocumentChunk[];
 }
 export declare class OpenAIEmbeddingProvider implements DocumentEmbedder {
-    private client;
+    private clientPromise;
     private readonly apiKey;
     private readonly baseURL;
     constructor(args: {
@@ -195,7 +217,7 @@ export declare class HeuristicCurationProvider implements DocumentCurator {
     curate(input: DocumentCurationInput): Promise<DocumentCurationOutcome>;
 }
 export declare class OpenAICurationProvider implements DocumentCurator {
-    private client;
+    private clientPromise;
     private readonly apiKey;
     private readonly baseURL;
     private readonly defaultHeaders;
@@ -262,6 +284,7 @@ export declare function addDocumentToBase(db: Database, input: AddDocumentReques
     organizationAuthorityGranted?: boolean | undefined;
     curationStatus?: DocumentCurationStatus | undefined;
     access?: DocumentAccessFilter | undefined;
+    knowledgeSourceIdentity?: string | null | undefined;
 }): Promise<Document>;
 /**
  * Move a document and its indexed chunks to another base. With no explicit
@@ -285,6 +308,24 @@ export declare function deleteDocumentFromBase(db: Database, input: {
     access?: DocumentAccessFilter | undefined;
 }): Promise<void>;
 export declare function listDocuments(db: Database, workspaceId: string, baseId: string, access?: DocumentAccessFilter): Promise<Document[]>;
+/**
+ * List newly ready documents in the same effective scope used by agent
+ * retrieval. The opaque checkpoint is bound to the account, requesting
+ * workspace, and immutable initiating subject, so it cannot be reused across
+ * scheduled-task authority boundaries.
+ */
+export declare function listEffectiveIndexedDocuments(db: Database, input: ListEffectiveIndexedDocumentsInput): Promise<ListIndexedDocumentsResponse>;
+export declare function encodeDocumentIndexCheckpoint(input: {
+    accountId: string;
+    workspaceId: string;
+    initiatingSubjectId: string;
+    sequence: bigint;
+}): string;
+export declare function decodeDocumentIndexCheckpoint(value: string, scope: {
+    accountId: string;
+    workspaceId: string;
+    initiatingSubjectId: string;
+}): bigint;
 export declare function getDocument(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter): Promise<Document | null>;
 export declare function queueDocumentForReindex(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter, organizationAuthorityGranted?: boolean): Promise<Document>;
 export declare function indexDocumentNow(db: Database, objectStorage: ObjectStorage, workspaceId: string, documentId: string, services?: DocumentServices, hooks?: DocumentIndexHooks, access?: DocumentAccessFilter): Promise<Document>;
@@ -295,6 +336,36 @@ export declare function searchDocuments(db: Database, input: DocumentSearchInput
  * request/tool input can replace it with another user's personal authority.
  */
 export declare function searchEffectiveDocuments(db: Database, input: EffectiveDocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<DocumentSearchResult[]>;
+/**
+ * Agent-facing Knowledge search over the existing Documents evidence store.
+ * Search selects candidates only after authority filtering; this second read
+ * rechecks every exact chunk before projecting it, so a record revoked between
+ * ranking and response construction disappears rather than leaking stale data.
+ */
+export declare function searchEffectiveKnowledge(db: Database, input: EffectiveDocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<KnowledgeSearchResponse>;
+/** Fetch one stable Knowledge record with a fresh authorization check. */
+export declare function getEffectiveKnowledgeRecord(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    initiatingSubjectId: string;
+    id: string;
+}): Promise<KnowledgeRecord | null>;
+/**
+ * Browse top-level authorized documents or the chunks of one authorized
+ * document. The cursor is opaque and bound to the caller, workspace, parent,
+ * and filters. It can change pagination position but can never widen scope.
+ */
+export declare function browseEffectiveKnowledge(db: Database, input: EffectiveKnowledgeBrowseInput): Promise<KnowledgeBrowseResponse>;
+type KnowledgeBrowseCursorScope = {
+    accountId: string;
+    workspaceId: string;
+    initiatingSubjectId: string;
+    parentId: string | null;
+    topic: string | null;
+    sourceKinds: readonly string[];
+};
+export declare function encodeKnowledgeBrowseCursor(scope: KnowledgeBrowseCursorScope, position: bigint): string;
+export declare function decodeKnowledgeBrowseCursor(value: string, scope: KnowledgeBrowseCursorScope): bigint;
 export declare function getDocumentChunk(db: Database, accountId: string, workspaceId: string, chunkId: string, access?: DocumentAccessFilter): Promise<DocumentSearchResult | null>;
 export declare function resolveDocumentAuthority(input: {
     kind?: DocumentAuthorityKind | undefined;
@@ -321,4 +392,3 @@ type DocumentAccessRecord = {
 export declare function parseDocumentBytes(bytes: Uint8Array, file: FileAsset, parser?: DocumentParser): Promise<ParsedDocument>;
 export declare function chunkText(text: string, maxChars?: number, overlapChars?: number): string[];
 export declare function deterministicEmbedding(text: string, dimensions?: number): number[];
-export {};