@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/organization-graph.js

@@ -64,7 +64,8 @@ export function createOrganizationGraphClient(config) {
     return {
         search: (input) => searchOrganizationGraph(normalized, input),
         importPortableGraph: (bundle) => importPortableGraph(normalized, bundle),
-        readPortableGraph: () => readPortableGraph(normalized)
+        readPortableGraph: () => readPortableGraph(normalized),
+        listPortableGraphs: () => listPortableGraphs(normalized)
     };
 }
 /** Forward the existing Graph retrieval input unchanged inside the request envelope. */
@@ -100,6 +101,21 @@ export async function readPortableGraph(config) {
     }
     return readback;
 }
+/** List the token owner's snapshots. The organization decides the owner; no project or Graph ID is sent. */
+export async function listPortableGraphs(config) {
+    const value = await requestJson(config, 'GET', route(config, 'list'));
+    const fields = ['graph_id', 'project_code', 'digest', 'created_at'];
+    if (!isRecord(value) || typeof value.truncated !== 'boolean' || !Array.isArray(value.bundles)
+        || value.bundles.some((entry) => !isRecord(entry) || fields.some((field) => typeof entry[field] !== 'string' || entry[field].trim() === ''))) {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned an invalid bundle list');
+    }
+    return {
+        truncated: value.truncated,
+        bundles: value.bundles.map((entry) => ({
+            graphId: entry.graph_id, projectCode: entry.project_code, digest: entry.digest, createdAt: entry.created_at
+        }))
+    };
+}
 /** Validate the privacy boundary before any upload leaves the local process. */
 export function assertPortableGraphBundle(bundle) {
     validatePortableGraph(bundle);
@@ -110,7 +126,7 @@ function parseGraphRetrievalResponse(value) {
         || (value.schemaVersion !== 1 && value.schemaVersion !== 2)
         || (value.status !== 'ok' && value.status !== 'migration_required')
         || typeof value.migrationRequired !== 'boolean'
-        || value.authority !== 'organization_graph'
+        || (value.authority !== 'owner_private' && value.authority !== 'organization_graph')
         || typeof value.query !== 'string'
         || typeof value.asOf !== 'string'
         || !['semantic', 'lexical', 'seed'].includes(String(value.method))
@@ -135,7 +151,10 @@ function parseGraphRetrievalResponse(value) {
         || value.absenceConfirmed !== false) {
         throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned a response outside the OSS GraphRetrievalResponse contract');
     }
-    return value;
+    // This route searches only the token owner's own snapshot (the owner-private
+    // area), never the organization's shared Graph. A service from before the
+    // owner_private label answered organization_graph for the same area.
+    return { ...value, authority: 'owner_private' };
 }
 function parseImportResult(value) {
     if (!isRecord(value)
@@ -271,7 +290,8 @@ async function withTimeout(operation, controller, timeoutMs) {
 function route(config, suffix, query) {
     const base = new URL(config.url);
     const prefix = base.pathname.replace(/\/+$/u, '');
-    const routePath = `${prefix}/api/info/graph/portable/${encodeURIComponent(config.graphId)}${suffix ? `/${suffix}` : ''}`;
+    const graphPath = suffix === 'list' ? '' : `/${encodeURIComponent(config.graphId)}${suffix ? `/${suffix}` : ''}`;
+    const routePath = `${prefix}/api/info/graph/portable${graphPath}`;
     const endpoint = new URL(routePath || '/', base.origin);
     for (const [key, value] of Object.entries(query ?? {}))
         endpoint.searchParams.set(key, value);

package/dist/personal-knowledge.d.ts

@@ -0,0 +1,132 @@
+/** 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 LocalPersonalKnowledgeSnapshot extends PersonalKnowledgeContextEnvelope {
+    events: PersonalKnowledgeEvent[];
+}
+/**
+ * Read the local v1 store without creating it. Returns undefined when the
+ * store has never been created; a half-created store is an error.
+ */
+export declare function readLocalPersonalKnowledgeEvents(options?: {
+    dataDir?: string;
+}): Promise<LocalPersonalKnowledgeSnapshot | undefined>;
+/** True when the value is a timestamp the v1 event contract accepts. */
+export declare function isPersonalKnowledgeTimestamp(value: unknown): value is string;
+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 {};