@opengeni/documents 0.2.72 → 0.3.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { Settings } from "@opengeni/config";
-import type { AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, FileAsset, KnowledgeSourceKind } from "@opengeni/contracts";
+import type { AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentAuthorityKind, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, DocumentVisibility, FileAsset, KnowledgeSourceKind } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 import type { ObjectStorage } from "@opengeni/storage";
 export declare const DEFAULT_DOCUMENT_PARSER = "liteparse";
@@ -9,6 +9,7 @@ export declare const DEFAULT_DOCUMENT_CHUNK_SIZE = 1200;
 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_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.";
@@ -82,6 +83,11 @@ export type DocumentAccessFilter = {
      */
     agentOnly?: boolean | undefined;
 };
+export type DocumentAuthority = {
+    kind: DocumentAuthorityKind;
+    workspaceId: string | null;
+    subjectId: string | null;
+};
 export type DocumentInventoryStatusCounts = Record<DocumentStatus, number>;
 export type DocumentInventorySourceKindCounts = Record<KnowledgeSourceKind, number>;
 export type DocumentInventory = {
@@ -110,6 +116,7 @@ export type DocumentInventoryInput = {
     access?: DocumentAccessFilter | undefined;
 };
 export type DocumentSearchInput = {
+    accountId: string;
     workspaceId: string;
     query: string;
     baseIds?: string[] | undefined;
@@ -119,6 +126,12 @@ export type DocumentSearchInput = {
     aclTags?: string[] | undefined;
     access?: DocumentAccessFilter | undefined;
 };
+export type EffectiveDocumentSearchInput = Omit<DocumentSearchInput, "access"> & {
+    /** Immutable human subject accepted for the logical request/turn. */
+    initiatingSubjectId: string;
+    /** Agent retrieval additionally enforces documents.agent_access. */
+    surface: "human" | "agent";
+};
 export type DocumentIndexHooks = {
     beforeEmbed?: (input: {
         accountId: string;
@@ -243,6 +256,8 @@ export declare function addDocumentToBase(db: Database, input: AddDocumentReques
     workspaceId: string;
     baseId: string;
     createdBy?: string | null | undefined;
+    initiatingSubjectId?: string | null | undefined;
+    organizationAuthorityGranted?: boolean | undefined;
     curationStatus?: DocumentCurationStatus | undefined;
     access?: DocumentAccessFilter | undefined;
 }): Promise<Document>;
@@ -256,6 +271,7 @@ export declare function moveDocumentToBase(db: Database, input: {
     workspaceId: string;
     documentId: string;
     targetBaseId?: string | null | undefined;
+    organizationAuthorityGranted?: boolean | undefined;
     access?: DocumentAccessFilter | undefined;
 }): Promise<Document>;
 export declare function deleteDocumentFromBase(db: Database, input: {
@@ -263,19 +279,32 @@ export declare function deleteDocumentFromBase(db: Database, input: {
     workspaceId: string;
     baseId: string;
     documentId: string;
+    organizationAuthorityGranted?: boolean | undefined;
     access?: DocumentAccessFilter | undefined;
 }): Promise<void>;
 export declare function listDocuments(db: Database, workspaceId: string, baseId: string, access?: DocumentAccessFilter): Promise<Document[]>;
 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): Promise<Document>;
-export declare function indexDocumentNow(db: Database, objectStorage: ObjectStorage, workspaceId: string, documentId: string, services?: DocumentServices, hooks?: DocumentIndexHooks): Promise<Document>;
+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>;
 export declare function searchDocuments(db: Database, input: DocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<DocumentSearchResult[]>;
-export declare function getDocumentChunk(db: Database, workspaceId: string, chunkId: string, access?: DocumentAccessFilter): Promise<DocumentSearchResult | null>;
+/**
+ * Canonical effective retrieval composition for API, SDK, and MCP surfaces.
+ * Callers supply the already-authorized immutable initiating subject; no
+ * 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[]>;
+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;
+    legacyVisibility?: DocumentVisibility | undefined;
+    workspaceId: string;
+    initiatingSubjectId?: string | null | undefined;
+}): DocumentAuthority;
 /** Whether a single already-fetched document is readable by this human viewer. */
-export declare function canViewDocument(document: Pick<DocumentAccessRecord, "visibility" | "createdBy">, viewerSubjectId: string | null | undefined): boolean;
+export declare function canViewDocument(document: Pick<DocumentAccessRecord, "authorityKind" | "authoritySubjectId">, viewerSubjectId: string | null | undefined): boolean;
 type DocumentAccessRecord = {
-    visibility: string;
-    createdBy: string | null;
+    authorityKind: string;
+    authoritySubjectId: string | null;
     agentAccess: boolean;
 };
 export declare function parseDocumentBytes(bytes: Uint8Array, file: FileAsset, parser?: DocumentParser): Promise<ParsedDocument>;