@unson/brainbase-mcp 0.24.1 → 0.26.0

package/dist/meeting-source-connection.d.ts

@@ -0,0 +1,265 @@
+import { type OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { AuthorizationServerMetadata, OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type MeetingSourceAccessDetail, type MeetingSourceCallTool, type MeetingSourceFailure, type MeetingSourceFailureReason, type MeetingSourceMeeting, type MeetingSourceProvider, type MeetingSourceSegment, type TactiqTranscriptBudget, type TactiqTranscriptRead } from './meeting-source-reader.js';
+import type { OrganizationConnectionBinding, OrganizationConnectionProviderAdapter } from './organization-connection.js';
+export type MeetingSourceCapability = 'meetings:list' | 'transcript:read';
+export type MeetingSourceConnectionStatus = 'pending' | 'connected' | 'reauth_required' | 'disabled' | 'revoked';
+export interface MeetingSourceConnectionRecord {
+    /** Issued by Brainbase. An external connection platform's ID lives only in `backend.ref`. */
+    connectionId: string;
+    tenantId: string;
+    provider: MeetingSourceProvider;
+    scope: 'personal' | 'org';
+    ownerPersonId: string | null;
+    orgId: string | null;
+    backend: {
+        kind: string;
+        ref: Record<string, string> | null;
+    };
+    capabilities: MeetingSourceCapability[];
+    status: MeetingSourceConnectionStatus;
+    revision: number;
+    lastVerifiedAt: string | null;
+}
+export declare class MeetingSourceConnectionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function createMeetingSourceConnectionId(): string;
+export declare function normalizeMeetingSourceConnectionRecord(value: unknown): MeetingSourceConnectionRecord;
+export interface StoredMeetingSourceCredentials {
+    provider: MeetingSourceProvider;
+    binding: OrganizationConnectionBinding;
+    serverUrl: string;
+    clientInformation: OAuthClientInformationMixed;
+    tokens: OAuthTokens | null;
+    connectedAt: string;
+}
+export interface PendingMcpAuthorization {
+    provider: MeetingSourceProvider;
+    binding: OrganizationConnectionBinding;
+    serverUrl: string;
+    authorizationServerUrl: string;
+    authorizationServerMetadata: AuthorizationServerMetadata | null;
+    clientInformation: OAuthClientInformationMixed;
+    codeVerifier: string;
+    redirectUrl: string;
+    resource: string | null;
+    createdAt: string;
+}
+export interface MeetingSourceCredentialStore {
+    read(connectionId: string): Promise<StoredMeetingSourceCredentials | null>;
+    write(connectionId: string, value: StoredMeetingSourceCredentials): Promise<void>;
+    remove(connectionId: string): Promise<void>;
+    savePendingAuthorization(stateHash: string, value: PendingMcpAuthorization): Promise<void>;
+    /** Returns the pending authorization once and forgets it. */
+    takePendingAuthorization(stateHash: string): Promise<PendingMcpAuthorization | null>;
+}
+export declare class MemoryMeetingSourceCredentialStore implements MeetingSourceCredentialStore {
+    private data;
+    read(connectionId: string): Promise<StoredMeetingSourceCredentials | null>;
+    write(connectionId: string, value: StoredMeetingSourceCredentials): Promise<void>;
+    remove(connectionId: string): Promise<void>;
+    savePendingAuthorization(stateHash: string, value: PendingMcpAuthorization): Promise<void>;
+    takePendingAuthorization(stateHash: string): Promise<PendingMcpAuthorization | null>;
+}
+/**
+ * One JSON file (mode 0600) holding credentials per connection ID. Writes go
+ * through a temporary file and a rename. Calls are serialized in-process.
+ */
+export declare class FileMeetingSourceCredentialStore implements MeetingSourceCredentialStore {
+    private readonly filePath;
+    private queue;
+    constructor(filePath: string);
+    read(connectionId: string): Promise<StoredMeetingSourceCredentials>;
+    write(connectionId: string, value: StoredMeetingSourceCredentials): Promise<void>;
+    remove(connectionId: string): Promise<void>;
+    savePendingAuthorization(stateHash: string, value: PendingMcpAuthorization): Promise<void>;
+    takePendingAuthorization(stateHash: string): Promise<PendingMcpAuthorization>;
+    private mutate;
+    private run;
+    private load;
+    private save;
+}
+export interface MeetingSourceConnectionNote {
+    capability: MeetingSourceCapability;
+    reason: MeetingSourceFailureReason | 'no_meetings';
+    message: string;
+    access?: MeetingSourceAccessDetail;
+}
+export interface MeetingSourceConnectionHealth {
+    status: 'connected' | 'reauth_required' | 'error';
+    capabilities: MeetingSourceCapability[];
+    checkedAt: string;
+    failure: MeetingSourceFailure | null;
+    notes: MeetingSourceConnectionNote[];
+}
+export interface ConnectionRuntime {
+    verify(connection: MeetingSourceConnectionRecord, options?: {
+        budget?: TactiqTranscriptBudget;
+    }): Promise<MeetingSourceConnectionHealth>;
+    callTool(connection: MeetingSourceConnectionRecord, tool: string, args: Record<string, unknown>): Promise<unknown>;
+    disconnect(connection: MeetingSourceConnectionRecord): Promise<void>;
+}
+/**
+ * Checks that a connection can actually list meetings and read the first page
+ * of a full transcript. Shared by every runtime so the result does not depend
+ * on how the connection is executed.
+ */
+export declare function probeMeetingSourceConnection(input: {
+    provider: MeetingSourceProvider;
+    callTool: MeetingSourceCallTool;
+    budget?: TactiqTranscriptBudget;
+    now?: () => Date;
+    lookbackMs?: number;
+}): Promise<MeetingSourceConnectionHealth>;
+export interface NativeMcpRuntimeOptions {
+    credentials: MeetingSourceCredentialStore;
+    /** MCP server URL per provider, used when the stored credentials have none. */
+    serverUrlFor?: (provider: MeetingSourceProvider) => string;
+    /** Replaces the Streamable HTTP transport, e.g. for tests. */
+    createTransport?: (input: {
+        url: URL;
+        authProvider: OAuthClientProvider;
+        connection: MeetingSourceConnectionRecord;
+    }) => Transport;
+    clientName?: string;
+    now?: () => Date;
+}
+/** Runs MCP tools with the SDK client, reading credentials through the credential port. */
+export declare class NativeMcpRuntime implements ConnectionRuntime {
+    private readonly options;
+    constructor(options: NativeMcpRuntimeOptions);
+    verify(connection: MeetingSourceConnectionRecord, options?: {
+        budget?: TactiqTranscriptBudget;
+    }): Promise<MeetingSourceConnectionHealth>;
+    callTool(connection: MeetingSourceConnectionRecord, tool: string, args: Record<string, unknown>): Promise<unknown>;
+    disconnect(connection: MeetingSourceConnectionRecord): Promise<void>;
+}
+export interface MeetingSourcePendingMeeting {
+    meeting: MeetingSourceMeeting;
+    reason: MeetingSourceFailureReason | 'delivery_failed';
+    message: string;
+    retryAt: string | null;
+    attempts: number;
+    firstSeenAt: string;
+}
+export interface MeetingSourceDeliveredMeeting {
+    digest: string;
+    version: number;
+    deliveredAt: string;
+}
+export interface MeetingSourceSyncState {
+    schemaVersion: 1;
+    connectionId: string;
+    provider: MeetingSourceProvider;
+    syncEnabled: boolean;
+    listedThrough: string | null;
+    pending: MeetingSourcePendingMeeting[];
+    unobtainable: Array<{
+        meetingId: string;
+        reason: string;
+        message: string;
+        decidedAt: string;
+    }>;
+    delivered: Record<string, MeetingSourceDeliveredMeeting>;
+    tactiqReads: TactiqTranscriptRead[];
+    lastAttemptAt: string | null;
+    lastSuccessAt: string | null;
+    lastError: {
+        reason: string;
+        message: string;
+        at: string;
+    } | null;
+}
+export interface MeetingSourceSyncStateStore {
+    load(connectionId: string): Promise<MeetingSourceSyncState | null>;
+    save(state: MeetingSourceSyncState): Promise<void>;
+}
+export interface MeetingSourceDelivery {
+    connectionId: string;
+    tenantId: string;
+    provider: MeetingSourceProvider;
+    scope: 'personal' | 'org';
+    ownerPersonId: string | null;
+    orgId: string | null;
+    meeting: MeetingSourceMeeting;
+    transcript: {
+        text: string;
+        segments: MeetingSourceSegment[];
+        digest: string;
+    };
+    version: number;
+    retrievedAt: string;
+}
+export type MeetingSourceDeliver = (delivery: MeetingSourceDelivery) => Promise<void>;
+export interface MeetingSourceSyncResult {
+    status: 'ok' | 'failed' | 'skipped';
+    skippedReason?: 'not_connected' | 'sync_disabled';
+    delivered: Array<{
+        meetingId: string;
+        version: number;
+    }>;
+    pending: number;
+    failure: {
+        reason: string;
+        message: string;
+    } | null;
+    state: MeetingSourceSyncState;
+}
+export declare function emptyMeetingSourceSyncState(connection: MeetingSourceConnectionRecord): MeetingSourceSyncState;
+export declare class MemoryMeetingSourceSyncStateStore implements MeetingSourceSyncStateStore {
+    private readonly states;
+    load(connectionId: string): Promise<MeetingSourceSyncState | null>;
+    save(state: MeetingSourceSyncState): Promise<void>;
+}
+export declare function syncMeetingSourceConnection(input: {
+    connection: MeetingSourceConnectionRecord;
+    runtime: ConnectionRuntime;
+    stateStore: MeetingSourceSyncStateStore;
+    deliver: MeetingSourceDeliver;
+    /** Re-fetch a past period. Does not move `listedThrough`. */
+    window?: {
+        since: string;
+        until: string;
+    };
+    recheckDelivered?: boolean;
+    now?: () => Date;
+    initialLookbackMs?: number;
+    overlapMs?: number;
+    maxAttempts?: number;
+}): Promise<MeetingSourceSyncResult>;
+export interface MeetingSourceListedMeeting {
+    connection: MeetingSourceConnectionRecord;
+    meeting: MeetingSourceMeeting;
+}
+export interface SameMeetingCandidate {
+    first: MeetingSourceListedMeeting;
+    second: MeetingSourceListedMeeting;
+    sharedParticipants: string[];
+}
+/**
+ * Suggests pairs that may be the same meeting. Only meetings of the same tenant
+ * and the same owner are compared; nothing is merged automatically.
+ */
+export declare function findSameMeetingCandidates(entries: readonly MeetingSourceListedMeeting[], options?: {
+    toleranceMs?: number;
+}): SameMeetingCandidate[];
+export interface McpOAuthConnectionAdapterOptions {
+    credentials: MeetingSourceCredentialStore;
+    serverUrlFor: (provider: MeetingSourceProvider) => string;
+    redirectUrl: string;
+    clientName?: string;
+    /** Overrides the scopes requested. Defaults to the protected resource's `scopes_supported`. */
+    scopeFor?: (provider: MeetingSourceProvider, supported: string[] | undefined) => string | undefined;
+    fetchFn?: typeof fetch;
+    now?: () => Date;
+    issueConnectionId?: () => string;
+}
+/**
+ * Implements the provider side of `@unson/brainbase-mcp/organization-connection`
+ * for MCP servers: discovery (RFC 9728 / RFC 8414), dynamic client
+ * registration, PKCE, and the token exchange. Readbacks never carry tokens.
+ */
+export declare function createMcpOAuthConnectionAdapter(options: McpOAuthConnectionAdapterOptions): OrganizationConnectionProviderAdapter;