@usewhisper/sdk 2.2.1 → 3.0.0

package/index.d.mts

@@ -182,6 +182,559 @@ declare class Whisper {
     private fallbackCaptureViaAddMemory;
 }
 
+type CompatMode = "fallback" | "strict";
+type OperationType = "search" | "writeAck" | "bulk" | "profile" | "session" | "query" | "get";
+interface TimeoutBudgets {
+    searchMs: number;
+    writeAckMs: number;
+    bulkMs: number;
+    profileMs: number;
+    sessionMs: number;
+}
+interface RetryPolicy {
+    maxAttemptsByOperation?: Partial<Record<OperationType, number>>;
+    retryableStatusCodes?: number[];
+    retryOnNetworkError?: boolean;
+    maxBackoffMs?: number;
+    baseBackoffMs?: number;
+}
+interface RuntimeRequestOptions {
+    endpoint: string;
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    body?: Record<string, unknown> | undefined;
+    headers?: Record<string, string> | undefined;
+    operation: OperationType;
+    idempotent?: boolean;
+    traceId?: string;
+    dedupeKeyExtra?: string;
+}
+interface RuntimeClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    sdkVersion?: string;
+    compatMode?: CompatMode;
+    timeouts?: Partial<TimeoutBudgets>;
+    retryPolicy?: RetryPolicy;
+}
+interface RuntimeResponse<T> {
+    data: T;
+    status: number;
+    traceId: string;
+}
+interface DiagnosticsRecord {
+    id: string;
+    startedAt: string;
+    endedAt: string;
+    traceId: string;
+    spanId: string;
+    operation: OperationType;
+    method: string;
+    endpoint: string;
+    status?: number;
+    durationMs: number;
+    success: boolean;
+    deduped?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+}
+
+type DiagnosticsSubscriber = (record: DiagnosticsRecord) => void;
+declare class DiagnosticsStore {
+    private readonly maxEntries;
+    private readonly records;
+    private readonly subscribers;
+    constructor(maxEntries?: number);
+    add(record: DiagnosticsRecord): void;
+    getLast(limit?: number): DiagnosticsRecord[];
+    snapshot(): {
+        total: number;
+        success: number;
+        failure: number;
+        avgDurationMs: number;
+        lastTraceId?: string;
+    };
+    subscribe(fn: DiagnosticsSubscriber): () => void;
+}
+
+interface QueuedWrite {
+    eventId: string;
+    project: string;
+    userId?: string;
+    sessionId?: string;
+    payload: {
+        content: string;
+        memory_type?: string;
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        importance?: number;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+        document_date?: string;
+        event_date?: string;
+    };
+    createdAt: string;
+}
+interface QueueStore {
+    load(): Promise<QueuedWrite[]>;
+    save(items: QueuedWrite[]): Promise<void>;
+}
+interface WriteQueueStatus {
+    queued: number;
+    flushing: boolean;
+    lastFlushAt?: string;
+    lastFlushCount: number;
+}
+type FlushHandler = (items: QueuedWrite[]) => Promise<void>;
+declare class WriteQueue {
+    private readonly flushHandler;
+    private readonly store;
+    private readonly maxBatchSize;
+    private readonly flushIntervalMs;
+    private readonly maxAttempts;
+    private readonly queue;
+    private flushTimer;
+    private flushing;
+    private lastFlushAt?;
+    private lastFlushCount;
+    constructor(args: {
+        flushHandler: FlushHandler;
+        store?: QueueStore;
+        maxBatchSize?: number;
+        flushIntervalMs?: number;
+        maxAttempts?: number;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): WriteQueueStatus;
+    enqueue(input: Omit<QueuedWrite, "eventId" | "createdAt"> & {
+        eventId?: string;
+    }): Promise<QueuedWrite>;
+    flush(): Promise<void>;
+    private makeEventId;
+    private bindProcessHooks;
+}
+
+declare class RuntimeClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly sdkVersion;
+    private readonly compatMode;
+    private readonly retryPolicy;
+    private readonly timeouts;
+    private readonly diagnostics;
+    private readonly inFlight;
+    constructor(options: RuntimeClientOptions, diagnostics?: DiagnosticsStore);
+    getDiagnosticsStore(): DiagnosticsStore;
+    getCompatMode(): CompatMode;
+    private timeoutFor;
+    private maxAttemptsFor;
+    private shouldRetryStatus;
+    private backoff;
+    private runtimeName;
+    private createRequestFingerprint;
+    request<T>(options: RuntimeRequestOptions): Promise<RuntimeResponse<T>>;
+    private performRequest;
+}
+
+interface SearchCacheKeyInput {
+    project: string;
+    userId?: string;
+    sessionId?: string;
+    query: string;
+    topK: number;
+    profile: string;
+    includePending: boolean;
+}
+declare class SearchResponseCache<T = unknown> {
+    private readonly ttlMs;
+    private readonly capacity;
+    private readonly byKey;
+    private readonly scopeIndex;
+    constructor(ttlMs?: number, capacity?: number);
+    makeScopeKey(project: string, userId?: string, sessionId?: string): string;
+    makeKey(input: SearchCacheKeyInput): string;
+    get(key: string): T | null;
+    set(key: string, scopeKey: string, value: T): void;
+    invalidateScope(scopeKey: string): number;
+    private evictIfNeeded;
+    private deleteByKey;
+}
+
+type MemoryKind$1 = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction" | "episodic" | "semantic" | "procedural";
+interface MemoryLatencyBreakdown$1 {
+    cache_ms: number;
+    embed_ms: number;
+    vector_ms: number;
+    lexical_ms: number;
+    merge_ms: number;
+    total_ms: number;
+}
+interface MemorySearchResult {
+    memory: {
+        id: string;
+        content: string;
+        type: string;
+        entities?: string[];
+        confidence?: number;
+        version?: number;
+        temporal?: {
+            document_date?: string | null;
+            event_date?: string | null;
+            valid_from?: string | null;
+            valid_until?: string | null;
+        };
+    };
+    similarity: number;
+    relations?: Array<Record<string, unknown>>;
+    chunk?: {
+        id: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface MemorySearchResponse$1 {
+    results: MemorySearchResult[];
+    count: number;
+    query: string;
+    trace_id?: string;
+    latency_ms?: number;
+    latency_breakdown?: MemoryLatencyBreakdown$1;
+    fallback?: "vector" | "lexical";
+    mode?: "fast" | "balanced" | "quality";
+    profile?: "fast" | "balanced" | "quality";
+    include_pending?: boolean;
+    pending_overlay_count?: number;
+    cache_hit?: boolean;
+}
+interface MemoryWriteAck$1 {
+    success: boolean;
+    mode?: "async" | "sync";
+    trace_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    queued?: boolean;
+    event_id?: string;
+    created?: number;
+    errors?: string[];
+}
+
+interface MemoryModuleOptions {
+    defaultProject?: string;
+    cacheEnabled?: boolean;
+    queueEnabled?: boolean;
+}
+declare class MemoryModule {
+    private readonly client;
+    private readonly cache;
+    private readonly queue;
+    private readonly options;
+    constructor(client: RuntimeClient, cache: SearchResponseCache<MemorySearchResponse$1>, queue: WriteQueue, options?: MemoryModuleOptions);
+    private resolveProject;
+    private invalidate;
+    add(params: {
+        project?: string;
+        content: string;
+        memory_type?: MemoryKind$1;
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        importance?: number;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+        document_date?: string;
+        event_date?: string;
+        write_mode?: "async" | "sync";
+        async?: boolean;
+    }): Promise<MemoryWriteAck$1>;
+    addBulk(params: {
+        project?: string;
+        memories: Array<{
+            content: string;
+            memory_type?: MemoryKind$1;
+            user_id?: string;
+            session_id?: string;
+            agent_id?: string;
+            importance?: number;
+            confidence?: number;
+            metadata?: Record<string, unknown>;
+            document_date?: string;
+            event_date?: string;
+        }>;
+        write_mode?: "async" | "sync";
+        async?: boolean;
+    }): Promise<MemoryWriteAck$1>;
+    search(params: {
+        project?: string;
+        query: string;
+        user_id?: string;
+        session_id?: string;
+        top_k?: number;
+        memory_type?: MemoryKind$1;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse$1>;
+    getUserProfile(params: {
+        project?: string;
+        user_id: string;
+        include_pending?: boolean;
+        memory_types?: string;
+    }): Promise<{
+        user_id: string;
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    getSessionMemories(params: {
+        project?: string;
+        session_id: string;
+        include_pending?: boolean;
+        limit?: number;
+    }): Promise<{
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    update(memoryId: string, params: {
+        content: string;
+        reasoning?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    delete(memoryId: string): Promise<{
+        success: boolean;
+        deleted: string;
+    }>;
+    flag(params: {
+        memoryId: string;
+        reason: string;
+        severity?: "low" | "medium" | "high";
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+
+type SessionState = "created" | "active" | "suspended" | "resumed" | "ended" | "archived";
+declare class SessionModule {
+    private readonly memory;
+    private readonly defaultProject?;
+    private readonly sessions;
+    constructor(memory: MemoryModule, defaultProject?: string | undefined);
+    private resolveProject;
+    private ensure;
+    start(params: {
+        userId: string;
+        project?: string;
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        sessionId: string;
+        state: SessionState;
+        createdAt: string;
+    }>;
+    event(params: {
+        sessionId: string;
+        type: string;
+        content: string;
+        parentEventId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        eventId: string;
+        sequence: number;
+    }>;
+    suspend(params: {
+        sessionId: string;
+    }): Promise<{
+        sessionId: string;
+        state: SessionState;
+    }>;
+    resume(params: {
+        sessionId: string;
+    }): Promise<{
+        sessionId: string;
+        state: SessionState;
+    }>;
+    end(params: {
+        sessionId: string;
+    }): Promise<{
+        sessionId: string;
+        state: SessionState;
+    }>;
+    archive(params: {
+        sessionId: string;
+    }): Promise<{
+        sessionId: string;
+        state: SessionState;
+    }>;
+}
+
+declare class ProfileModule {
+    private readonly memory;
+    constructor(memory: MemoryModule);
+    getUserProfile(params: {
+        project?: string;
+        user_id: string;
+        include_pending?: boolean;
+        memory_types?: string;
+    }): Promise<{
+        user_id: string;
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    getSessionMemories(params: {
+        project?: string;
+        session_id: string;
+        include_pending?: boolean;
+        limit?: number;
+    }): Promise<{
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+}
+
+declare class AnalyticsModule {
+    private readonly diagnostics;
+    private readonly queue;
+    constructor(diagnostics: DiagnosticsStore, queue: WriteQueue);
+    diagnosticsSnapshot(): {
+        total: number;
+        success: number;
+        failure: number;
+        avgDurationMs: number;
+        lastTraceId?: string;
+    };
+    queueStatus(): WriteQueueStatus;
+}
+
+interface WhisperClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    project?: string;
+    compatMode?: CompatMode;
+    timeouts?: Partial<TimeoutBudgets>;
+    retryPolicy?: RetryPolicy;
+    cache?: {
+        enabled?: boolean;
+        ttlMs?: number;
+        capacity?: number;
+    };
+    queue?: {
+        enabled?: boolean;
+        maxBatchSize?: number;
+        flushIntervalMs?: number;
+        maxAttempts?: number;
+        persistence?: "memory" | "storage" | "file";
+        filePath?: string;
+    };
+    telemetry?: {
+        enabled?: boolean;
+        maxEntries?: number;
+    };
+}
+interface RunContext {
+    project?: string;
+    userId?: string;
+    sessionId?: string;
+    traceId?: string;
+}
+declare class WhisperClient {
+    private readonly config;
+    readonly diagnostics: {
+        getLast: (limit?: number) => ReturnType<DiagnosticsStore["getLast"]>;
+        subscribe: (fn: Parameters<DiagnosticsStore["subscribe"]>[0]) => ReturnType<DiagnosticsStore["subscribe"]>;
+        snapshot: () => ReturnType<DiagnosticsStore["snapshot"]>;
+    };
+    readonly queue: {
+        flush: () => Promise<void>;
+        status: () => ReturnType<WriteQueue["status"]>;
+    };
+    readonly memory: {
+        add: (params: Parameters<MemoryModule["add"]>[0]) => Promise<MemoryWriteAck$1>;
+        addBulk: (params: Parameters<MemoryModule["addBulk"]>[0]) => Promise<MemoryWriteAck$1>;
+        search: (params: Parameters<MemoryModule["search"]>[0]) => Promise<MemorySearchResponse$1>;
+        getUserProfile: (params: Parameters<MemoryModule["getUserProfile"]>[0]) => ReturnType<MemoryModule["getUserProfile"]>;
+        getSessionMemories: (params: Parameters<MemoryModule["getSessionMemories"]>[0]) => ReturnType<MemoryModule["getSessionMemories"]>;
+        update: (memoryId: string, params: {
+            content: string;
+            reasoning?: string;
+        }) => Promise<{
+            success: boolean;
+        }>;
+        delete: (memoryId: string) => Promise<{
+            success: boolean;
+            deleted: string;
+        }>;
+        flag: (params: {
+            memoryId: string;
+            reason: string;
+            severity?: "low" | "medium" | "high";
+        }) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly session: {
+        start: (params: Parameters<SessionModule["start"]>[0]) => ReturnType<SessionModule["start"]>;
+        event: (params: Parameters<SessionModule["event"]>[0]) => ReturnType<SessionModule["event"]>;
+        suspend: (params: Parameters<SessionModule["suspend"]>[0]) => ReturnType<SessionModule["suspend"]>;
+        resume: (params: Parameters<SessionModule["resume"]>[0]) => ReturnType<SessionModule["resume"]>;
+        end: (params: Parameters<SessionModule["end"]>[0]) => ReturnType<SessionModule["end"]>;
+    };
+    readonly profile: {
+        getUserProfile: (params: Parameters<ProfileModule["getUserProfile"]>[0]) => ReturnType<ProfileModule["getUserProfile"]>;
+        getSessionMemories: (params: Parameters<ProfileModule["getSessionMemories"]>[0]) => ReturnType<ProfileModule["getSessionMemories"]>;
+    };
+    readonly analytics: {
+        diagnosticsSnapshot: () => ReturnType<AnalyticsModule["diagnosticsSnapshot"]>;
+        queueStatus: () => ReturnType<AnalyticsModule["queueStatus"]>;
+    };
+    private readonly runtimeClient;
+    private readonly diagnosticsStore;
+    private readonly searchCache;
+    private readonly writeQueue;
+    private readonly memoryModule;
+    private readonly sessionModule;
+    private readonly profileModule;
+    private readonly analyticsModule;
+    constructor(config: WhisperClientConfig);
+    static fromEnv(overrides?: Partial<WhisperClientConfig>): WhisperClient;
+    withRunContext(context: RunContext): {
+        memory: {
+            add: (params: Omit<Parameters<MemoryModule["add"]>[0], "project" | "user_id" | "session_id"> & {
+                project?: string;
+                user_id?: string;
+                session_id?: string;
+                memory_type?: MemoryKind$1;
+            }) => Promise<MemoryWriteAck$1>;
+            search: (params: Omit<Parameters<MemoryModule["search"]>[0], "project" | "user_id" | "session_id"> & {
+                project?: string;
+                user_id?: string;
+                session_id?: string;
+            }) => Promise<MemorySearchResponse$1>;
+        };
+        session: {
+            event: (params: Omit<Parameters<SessionModule["event"]>[0], "sessionId"> & {
+                sessionId?: string;
+            }) => Promise<{
+                success: boolean;
+                eventId: string;
+                sequence: number;
+            }>;
+        };
+        queue: {
+            flush: () => Promise<void>;
+            status: () => ReturnType<WriteQueue["status"]>;
+        };
+        diagnostics: {
+            getLast: (limit?: number) => ReturnType<DiagnosticsStore["getLast"]>;
+            subscribe: (fn: Parameters<DiagnosticsStore["subscribe"]>[0]) => ReturnType<DiagnosticsStore["subscribe"]>;
+            snapshot: () => ReturnType<DiagnosticsStore["snapshot"]>;
+        };
+    };
+    shutdown(): Promise<void>;
+}
+
 interface AgentMiddlewareConfig extends WhisperOptions {
     /**
      * Build the prompt passed to the model.
@@ -240,6 +793,98 @@ declare class WhisperAgentMiddleware {
 }
 declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
 
+interface LangChainMemoryAdapterOptions {
+    project?: string;
+    userId: string;
+    sessionId?: string;
+    memoryKey?: string;
+    topK?: number;
+    profile?: "fast" | "balanced" | "quality";
+}
+/**
+ * Lightweight adapter matching LangChain memory contract shape.
+ * Compatible with BaseMemory-style integrations:
+ * - loadMemoryVariables
+ * - saveContext
+ * - clear
+ */
+declare class LangChainMemoryAdapter {
+    private readonly client;
+    private readonly options;
+    readonly memoryKeys: string[];
+    private readonly memoryKey;
+    constructor(client: WhisperClient, options: LangChainMemoryAdapterOptions);
+    loadMemoryVariables(_inputValues: Record<string, unknown>): Promise<Record<string, string>>;
+    saveContext(inputValues: Record<string, unknown>, outputValues: Record<string, unknown>): Promise<void>;
+    clear(): Promise<void>;
+}
+declare function createLangChainMemoryAdapter(client: WhisperClient, options: LangChainMemoryAdapterOptions): LangChainMemoryAdapter;
+
+interface LangGraphCheckpointConfig {
+    configurable: {
+        thread_id: string;
+        checkpoint_ns?: string;
+        checkpoint_id?: string;
+    };
+}
+interface LangGraphCheckpointTuple {
+    config: LangGraphCheckpointConfig;
+    checkpoint: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    parent_config?: LangGraphCheckpointConfig | null;
+}
+interface LangGraphCheckpointListOptions {
+    limit?: number;
+    before?: {
+        checkpointId?: string;
+        updatedAt?: string;
+    };
+    sort?: "asc" | "desc";
+    filter?: {
+        checkpointNs?: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface LangGraphCheckpointSearchOptions {
+    threadId: string;
+    query: string;
+    checkpointNs?: string;
+    topK?: number;
+    includePending?: boolean;
+    profile?: "fast" | "balanced" | "quality";
+}
+interface LangGraphCheckpointAdapterOptions {
+    project?: string;
+    userIdPrefix?: string;
+    defaultCheckpointNs?: string;
+}
+/**
+ * LangGraph checkpoint adapter over Whisper memory APIs.
+ * Phase 5a: get/put/list.
+ * Phase 5b: checkpoint_ns fidelity, richer list/search filtering, schema-hard parsing.
+ */
+declare class LangGraphCheckpointAdapter {
+    private readonly client;
+    private readonly localByKey;
+    private readonly localByThread;
+    private readonly options;
+    constructor(client: WhisperClient, options?: LangGraphCheckpointAdapterOptions);
+    private getUserId;
+    private resolveCheckpointNs;
+    private makeLocalKey;
+    private normalizeTuple;
+    private parseCheckpointTupleFromRow;
+    private upsertLocal;
+    private mergeWithLocal;
+    private applyListFilters;
+    private fetchThreadRecords;
+    get(config: LangGraphCheckpointConfig): Promise<LangGraphCheckpointTuple | undefined>;
+    put(config: LangGraphCheckpointConfig, checkpoint: Record<string, unknown>, metadata?: Record<string, unknown>, parentConfig?: LangGraphCheckpointConfig | null): Promise<LangGraphCheckpointConfig>;
+    list(config: LangGraphCheckpointConfig, options?: LangGraphCheckpointListOptions): Promise<LangGraphCheckpointTuple[]>;
+    search(params: LangGraphCheckpointSearchOptions): Promise<LangGraphCheckpointTuple[]>;
+}
+declare function createLangGraphCheckpointAdapter(client: WhisperClient, options?: LangGraphCheckpointAdapterOptions): LangGraphCheckpointAdapter;
+
 interface MemoryGraphNode {
     id: string;
     label?: string;
@@ -260,10 +905,6 @@ interface MemoryGraphPayload {
  */
 declare function memoryGraphToMermaid(graph: MemoryGraphPayload): string;
 
-/**
- * Whisper Context SDK
- * TypeScript SDK for the Whisper Context API
- */
 interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
@@ -461,6 +1102,7 @@ declare class WhisperContext {
     private defaultProject?;
     private timeoutMs;
     private retryConfig;
+    private runtimeClient;
     private projectRefToId;
     private projectCache;
     private projectCacheExpiresAt;
@@ -473,6 +1115,7 @@ declare class WhisperContext {
     private withProjectRefFallback;
     private classifyError;
     private isEndpointNotFoundError;
+    private inferOperation;
     private request;
     query(params: QueryParams): Promise<QueryResult>;
     createProject(params: {
@@ -1036,4 +1679,4 @@ declare class WhisperContext {
     };
 }
 
-export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };
+export { type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };