@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/personal-knowledge.d.ts

@@ -0,0 +1,120 @@
+/** The context header used by the v1 register and search contracts. */
+export declare const PERSONAL_KNOWLEDGE_CONTEXT_HEADER = "X-Brainbase-Personal-Context";
+export declare const PERSONAL_KNOWLEDGE_CONTEXT_VERSION_HEADER = "X-Brainbase-Personal-Context-Version";
+/** Short alias retained for consumers that call this a personal context header. */
+export declare const PERSONAL_CONTEXT_HEADER = "X-Brainbase-Personal-Context";
+export declare const PERSONAL_KNOWLEDGE_CONTRACT_VERSION: 1;
+export declare const PERSONAL_KNOWLEDGE_LOCAL_DIRECTORY = "personal-knowledge-v1";
+export type PersonalKnowledgeScope = 'personal_owned' | 'organization_private';
+export type PersonalKnowledgeStorageMode = 'local' | 'managed_cloud';
+export interface PersonalKnowledgeContext {
+    contract_version: typeof PERSONAL_KNOWLEDGE_CONTRACT_VERSION;
+    scope: PersonalKnowledgeScope;
+    owner_person_id: string;
+    organization_id: string | null;
+    source_id: string;
+}
+export declare class PersonalKnowledgeContextError extends Error {
+    readonly code: string;
+    readonly field?: string;
+    constructor(message: string, code?: string, field?: string);
+}
+/** Validate and return a copy of a strict v1 context object. */
+export declare function validatePersonalKnowledgeContext(value: unknown): PersonalKnowledgeContext;
+export declare const assertPersonalKnowledgeContext: typeof validatePersonalKnowledgeContext;
+/** Encode a trusted expected context for `X-Brainbase-Personal-Context`. */
+export declare function encodePersonalKnowledgeContextHeader(value: unknown): string;
+export declare const encodeExpectedPersonalKnowledgeContextHeader: typeof encodePersonalKnowledgeContextHeader;
+/** Decode and strictly validate a v1 context header. */
+export declare function decodePersonalKnowledgeContextHeader(value: unknown): PersonalKnowledgeContext;
+export declare const decodeExpectedPersonalKnowledgeContextHeader: typeof decodePersonalKnowledgeContextHeader;
+/** Assert that two contexts identify exactly the same source of truth. */
+export declare function assertPersonalKnowledgeContextMatch(expected: unknown, actual: unknown): PersonalKnowledgeContext;
+export interface PersonalKnowledgeEvent {
+    event_id: string;
+    body: string;
+    body_hash: string;
+    occurred_at?: string;
+    captured_at?: string;
+    source?: unknown;
+    source_pointer?: unknown;
+    parent_episode_id?: string | null;
+    permission_snapshot?: Record<string, unknown>;
+    sensitivity?: string;
+    kind?: string;
+    type?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type PersonalKnowledgeEventInput = Omit<PersonalKnowledgeEvent, 'body_hash'> & {
+    body_hash?: string;
+    content?: string;
+};
+/** Normalize a caller event without allowing caller-controlled identity fields. */
+export declare function normalizePersonalKnowledgeEvent(value: unknown): PersonalKnowledgeEvent;
+export declare function normalizePersonalKnowledgeSearchInput(query: string, limit?: number): {
+    query: string;
+    limit: number;
+};
+export interface PersonalKnowledgeContextEnvelope {
+    context: PersonalKnowledgeContext;
+}
+export interface PersonalKnowledgeRegisterEnvelope extends PersonalKnowledgeContextEnvelope {
+    event: PersonalKnowledgeEvent;
+}
+export interface PersonalKnowledgeSearchEnvelope extends PersonalKnowledgeContextEnvelope {
+    results: PersonalKnowledgeEvent[];
+}
+export interface PersonalKnowledgeStore {
+    readonly mode: 'local';
+    readonly dataDir: string;
+    getContext(): Promise<PersonalKnowledgeContextEnvelope>;
+    register(event: PersonalKnowledgeEventInput): Promise<PersonalKnowledgeRegisterEnvelope>;
+    search(query: string, limit?: number): Promise<PersonalKnowledgeSearchEnvelope>;
+}
+export interface PersonalKnowledgeStoreOptions {
+    /** Parent Personal OS directory. The v1 store always uses a child directory. */
+    dataDir?: string;
+    /** Trusted context from configuration; never a model-controlled MCP argument. */
+    context?: PersonalKnowledgeContext;
+    ownerPersonId?: string;
+    sourceId?: string;
+}
+export declare function createLocalPersonalKnowledgeStore(options?: PersonalKnowledgeStoreOptions): PersonalKnowledgeStore;
+export declare const createPersonalKnowledgeStore: typeof createLocalPersonalKnowledgeStore;
+export interface PersonalKnowledgeClientOptions {
+    mode: PersonalKnowledgeStorageMode;
+    apiUrl: string;
+    expectedContext: PersonalKnowledgeContext;
+    token?: string;
+    getToken?: () => Promise<string>;
+    tokenManager?: {
+        getToken(): Promise<string>;
+    };
+    fetch?: FetchLike;
+}
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare class PersonalKnowledgeClientError extends Error {
+    readonly status: number | null;
+    readonly responseBody: unknown;
+    constructor(message: string, options?: {
+        status?: number | null;
+        responseBody?: unknown;
+    });
+}
+export declare function normalizePersonalKnowledgeApiUrl(apiUrl: string, mode: PersonalKnowledgeStorageMode): string;
+export declare class PersonalKnowledgeClient {
+    readonly mode: PersonalKnowledgeStorageMode;
+    readonly apiUrl: string;
+    readonly expectedContext: PersonalKnowledgeContext;
+    private readonly getToken;
+    private readonly fetchImpl;
+    constructor(options: PersonalKnowledgeClientOptions);
+    getContext(): Promise<PersonalKnowledgeContextEnvelope>;
+    register(input: PersonalKnowledgeEventInput): Promise<PersonalKnowledgeRegisterEnvelope>;
+    search(query: string, limit?: number): Promise<PersonalKnowledgeSearchEnvelope>;
+    private request;
+}
+export declare function createPersonalKnowledgeClient(options: PersonalKnowledgeClientOptions): PersonalKnowledgeClient;
+export {};