@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.2

package/dist/oauth.d.ts

@@ -0,0 +1,268 @@
+import { type TokenProvider } from './token-provider.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+import { type KnowledgeMcpProviderContractV12 } from './internal/serving-contracts/index.js';
+import { type KnowledgeMcpProviderContractV11, type MaterialOutboxWindow, type KnowledgeMcpProviderContractV3, type KnowledgeMcpProviderContractV6, type KnowledgeMcpProviderContractV7, type KnowledgeMcpProviderContractV8, type KnowledgeMcpProviderContractV9, type KnowledgeMcpProviderContractV10, type OAuthMaterialPageResponse, type OAuthMaterialRoutePageResponse, type OAuthMaterialPartitionsResponse, type OAuthMaterialPartitionPageResponse, type OAuthMaterialPresentationResponse, type ServingDecision } from './internal/serving-contracts/index.js';
+export interface KnowledgeOAuthFileClientOptions {
+    baseUrl: string;
+    token?: string;
+    tokenProvider?: TokenProvider;
+    projectRef: string;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+}
+export interface OAuthFileDescriptor {
+    contentHash: string;
+    mediaType: string;
+    byteLength: number;
+}
+export type OAuthFileResult = {
+    decision: ServingDecision;
+    descriptor: OAuthFileDescriptor;
+    content: Buffer;
+} | {
+    decision: ServingDecision;
+    error: string;
+};
+export declare class KnowledgeOAuthFileClient {
+    readonly projectRef: string;
+    private readonly root;
+    private readonly credentials;
+    private readonly fetchImpl;
+    private providerPromise;
+    private materialProviderPromise;
+    private agentMaterialProviderPromise;
+    private searchMaterialProviderPromise;
+    private routeMaterialProviderPromise;
+    private syncMaterialProviderPromise;
+    private capabilityProviderPromise;
+    private partitionMaterialProviderPromise;
+    constructor(options: KnowledgeOAuthFileClientOptions);
+    /** 公开 v3 元数据无需凭据；读取失败时清除缓存以便下次重试。 */
+    discover(): Promise<KnowledgeMcpProviderContractV3>;
+    discoverMaterials(): Promise<KnowledgeMcpProviderContractV6>;
+    /** Explicit v7 Agent discovery leaves the stable v6 HTTP file contract untouched. */
+    discoverAgentMaterials(): Promise<KnowledgeMcpProviderContractV7>;
+    /** v8 only describes the bounded descriptive index; result coverage is reported per query. */
+    discoverSearchMaterials(): Promise<KnowledgeMcpProviderContractV8>;
+    discoverRouteMaterials(): Promise<KnowledgeMcpProviderContractV9>;
+    discoverPartitionedMaterials(): Promise<KnowledgeMcpProviderContractV10>;
+    discoverMaterialSync(): Promise<KnowledgeMcpProviderContractV11>;
+    discoverMaterialCapabilities(): Promise<KnowledgeMcpProviderContractV12>;
+    private capabilityGet;
+    getMaterialCapabilities(ref: string): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        material: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        };
+        projectRef: string;
+    }>;
+    pageMaterialCapabilities(options?: {
+        limit?: number;
+        after?: string;
+        resourceType?: string;
+        sourceProjectKey?: string;
+        refPrefix?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        }[];
+        nextAfter: string | null;
+        projectRef: string;
+    }>;
+    pageMaterialMedia(ref: string, options?: {
+        afterOrdinal?: number;
+        limit?: number;
+        documentRef?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        ref: string;
+        sourceContentHash: string;
+        documentRef: string | null;
+        documentContentHash: string | null;
+        state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+        items: {
+            ordinal: number;
+            kind: "IMAGE" | "AUDIO" | "VIDEO";
+            sourceUrl: string;
+            canonicalUrl: string | null;
+            availability: "UNAVAILABLE" | "MIRRORED" | "REMOTE_ONLY";
+            mediaRef: string | null;
+            contentHash: string | null;
+            mediaType: string | null;
+            byteLength: number | null;
+            state: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "DENIED" | "REMOTE_ONLY";
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            } | null;
+        }[];
+        nextAfterOrdinal: number | null;
+        projectRef: string;
+    }>;
+    getMaterialIndexStatus(options?: {
+        afterSourceKey?: string;
+        afterNodeId?: string;
+        sourceProjectKey?: string;
+        limit?: number;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        indexedFields: ["TITLE", "SUMMARY"];
+        bodyIndexed: false;
+        semanticIndexed: false;
+        items: {
+            sourceProjectKey: string;
+            nodeId: string;
+            directoryThroughSeq: number;
+            searchThroughSeq: number | null;
+            observedMaxSeq: number | null;
+            checkpointUpdatedAt: string | null;
+            state: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_CHECKPOINT";
+        }[];
+        nextAfter: {
+            sourceProjectKey: string;
+            nodeId: string;
+        } | null;
+        projectRef: string;
+    }>;
+    openMaterialStream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+    getMaterialOutboxWindow(): Promise<MaterialOutboxWindow>;
+    private partitionGet;
+    pageMaterialPartitions(options?: {
+        afterRouteId?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPartitionsResponse>;
+    pageMaterialPartition(partition: 'OWNER' | 'LEGACY', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPartitionPageResponse>;
+    searchMaterials(query: string, options?: {
+        afterId?: number;
+        limit?: number;
+        resourceType?: string;
+        sourceProjectKey?: string;
+    }): Promise<{
+        schemaVersion: 1;
+        projectRef: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        order: "INDEX_ROWID_ASC";
+        indexState: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_LAST_OBSERVATION";
+        configuredSourceCount: number;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            title: string;
+            summary: string;
+        }[];
+        nextAfterId: number | null;
+    }>;
+    pageMaterials(resourceType: 'all' | 'artifact' | 'evidence' | 'reference', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPageResponse>;
+    pageAllMaterials(options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPageResponse>;
+    pageRouteMaterials(routeId: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialRoutePageResponse>;
+    getMaterialPresentation(ref: string): Promise<OAuthMaterialPresentationResponse>;
+    getMaterial(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    private read;
+    getContent(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    /** 原始 Evidence 文件只代表已采集证据，不自动获得知识审核或 currentness 许可。 */
+    getEvidenceFile(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    getMedia(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+}