@usewhisper/sdk 1.0.0 → 1.1.0

package/{index.d.cts → index.d.mts}

@@ -5,9 +5,17 @@
 interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
+    project?: string;
+    orgId?: string;
+    timeoutMs?: number;
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
 }
 interface QueryParams {
-    project: string;
+    project?: string;
     query: string;
     top_k?: number;
     threshold?: number;
@@ -87,10 +95,38 @@ interface Memory {
     createdAt: string;
     updatedAt: string;
 }
+type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
+declare class WhisperError extends Error {
+    code: WhisperErrorCode;
+    status?: number;
+    retryable: boolean;
+    details?: unknown;
+    constructor(args: {
+        code: WhisperErrorCode;
+        message: string;
+        status?: number;
+        retryable?: boolean;
+        details?: unknown;
+    });
+}
 declare class WhisperContext {
     private apiKey;
     private baseUrl;
+    private defaultProject?;
+    private orgId?;
+    private timeoutMs;
+    private retryConfig;
+    private projectRefToId;
+    private projectCache;
+    private projectCacheExpiresAt;
     constructor(config: WhisperConfig);
+    withProject(project: string): WhisperContext;
+    private getRequiredProject;
+    private refreshProjectCache;
+    private resolveProjectId;
+    private getProjectRefCandidates;
+    private withProjectRefFallback;
+    private classifyError;
     private request;
     query(params: QueryParams): Promise<QueryResult>;
     createProject(params: {
@@ -123,30 +159,40 @@ declare class WhisperContext {
     }>): Promise<{
         ingested: number;
     }>;
+    addContext(params: {
+        project?: string;
+        content: string;
+        title?: string;
+        metadata?: Record<string, any>;
+    }): Promise<{
+        ingested: number;
+    }>;
     addMemory(params: {
-        project: string;
+        project?: string;
         content: string;
-        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         user_id?: string;
         session_id?: string;
         agent_id?: string;
         importance?: number;
         metadata?: Record<string, any>;
         expires_in_seconds?: number;
-    }): Promise<Memory>;
+        allow_legacy_fallback?: boolean;
+    }): Promise<{
+        id: string;
+        success: boolean;
+        path: "sota" | "legacy";
+        fallback_used: boolean;
+    }>;
     searchMemories(params: {
-        project: string;
+        project?: string;
         query: string;
         user_id?: string;
         session_id?: string;
         agent_id?: string;
-        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         top_k?: number;
-    }): Promise<{
-        memories: Array<Memory & {
-            score: number;
-        }>;
-    }>;
+    }): Promise<any>;
     createApiKey(params: {
         name: string;
         scopes?: string[];
@@ -161,12 +207,9 @@ declare class WhisperContext {
         keys: any[];
     }>;
     getUsage(days?: number): Promise<any>;
-    /**
-     * SOTA Memory Search - Search memories with temporal and type filtering
-     */
     searchMemoriesSOTA(params: {
         query: string;
-        project: string;
+        project?: string;
         user_id?: string;
         session_id?: string;
         question_date?: string;
@@ -176,11 +219,8 @@ declare class WhisperContext {
         include_chunks?: boolean;
         include_relations?: boolean;
     }): Promise<any>;
-    /**
-     * Ingest Session - Create memories from a conversation
-     */
     ingestSession(params: {
-        project: string;
+        project?: string;
         session_id: string;
         user_id?: string;
         messages: Array<{
@@ -195,41 +235,29 @@ declare class WhisperContext {
         memories_invalidated: number;
         errors?: string[];
     }>;
-    /**
-     * Get Session Memories - Recent memories from a session
-     */
     getSessionMemories(params: {
         session_id: string;
-        project: string;
+        project?: string;
         limit?: number;
         since_date?: string;
     }): Promise<{
         memories: any[];
         count: number;
     }>;
-    /**
-     * Get User Profile - Long-term user preferences and facts
-     */
     getUserProfile(params: {
         user_id: string;
-        project: string;
+        project?: string;
         memory_types?: string;
     }): Promise<{
         user_id: string;
         memories: any[];
         count: number;
     }>;
-    /**
-     * Get Memory Versions - Version chain history
-     */
     getMemoryVersions(memoryId: string): Promise<{
         memory_id: string;
         versions: any[];
         count: number;
     }>;
-    /**
-     * Update Memory - Create a new version
-     */
     updateMemory(memoryId: string, params: {
         content: string;
         reasoning?: string;
@@ -238,36 +266,24 @@ declare class WhisperContext {
         new_memory_id: string;
         old_memory_id: string;
     }>;
-    /**
-     * Delete Memory - Soft delete
-     */
     deleteMemory(memoryId: string): Promise<{
         success: boolean;
         deleted: string;
     }>;
-    /**
-     * Get Memory Relations - Graph connections
-     */
     getMemoryRelations(memoryId: string): Promise<{
         memory_id: string;
         relations: any[];
         count: number;
     }>;
-    /**
-     * Oracle Search - Tree-guided document navigation with research mode
-     */
     oracleSearch(params: {
         query: string;
-        project: string;
+        project?: string;
         max_results?: number;
         mode?: "search" | "research";
         max_steps?: number;
     }): Promise<any>;
-    /**
-     * Autosubscribe - Auto-index project dependencies
-     */
     autosubscribe(params: {
-        project: string;
+        project?: string;
         source: {
             type: "github" | "local";
             owner?: string;
@@ -285,12 +301,9 @@ declare class WhisperContext {
         dependencies?: any[];
         auto_sync_enabled: boolean;
     }>;
-    /**
-     * Create Shared Context - Save and share a conversation
-     */
     createSharedContext(params: {
         session_id: string;
-        project: string;
+        project?: string;
         title?: string;
         include_memories?: boolean;
         include_chunks?: boolean;
@@ -304,9 +317,6 @@ declare class WhisperContext {
         messages_count: number;
         expires_at: string;
     }>;
-    /**
-     * Load Shared Context - View shared context (public endpoint)
-     */
     loadSharedContext(shareId: string): Promise<{
         share_id: string;
         title: string;
@@ -317,12 +327,9 @@ declare class WhisperContext {
         chunks?: any[];
         metadata: any;
     }>;
-    /**
-     * Resume from Shared Context - Fork shared context to new session
-     */
     resumeFromSharedContext(params: {
         share_id: string;
-        project: string;
+        project?: string;
         new_session_id?: string;
     }): Promise<{
         success: boolean;
@@ -331,20 +338,14 @@ declare class WhisperContext {
         messages_restored: number;
         chunks_restored: number;
     }>;
-    /**
-     * Consolidate Memories - Find and merge duplicates
-     */
     consolidateMemories(params: {
-        project: string;
+        project?: string;
         similarity_threshold?: number;
         auto_merge?: boolean;
         dry_run?: boolean;
     }): Promise<any>;
-    /**
-     * Update Importance Decay - Apply time-based relevance scoring
-     */
     updateImportanceDecay(params: {
-        project: string;
+        project?: string;
         decay_function?: "exponential" | "linear" | "logarithmic";
         half_life_days?: number;
         access_boost?: number;
@@ -357,16 +358,10 @@ declare class WhisperContext {
         memories_archived: number;
         config: any;
     }>;
-    /**
-     * Get Importance Statistics
-     */
-    getImportanceStats(project: string): Promise<{
+    getImportanceStats(project?: string): Promise<{
         project_id: string;
         statistics: any;
     }>;
-    /**
-     * Get Cache Statistics
-     */
     getCacheStats(): Promise<{
         cache_type: string;
         hit_rate: number;
@@ -378,11 +373,8 @@ declare class WhisperContext {
         average_latency_ms: number;
         uptime_seconds: number;
     }>;
-    /**
-     * Warm Cache - Preload common queries
-     */
     warmCache(params: {
-        project: string;
+        project?: string;
         queries: string[];
         ttl_seconds?: number;
     }): Promise<{
@@ -391,9 +383,6 @@ declare class WhisperContext {
         errors: string[];
         cache_size_increase_bytes: number;
     }>;
-    /**
-     * Clear Cache Pattern
-     */
     clearCache(params: {
         pattern?: string;
         clear_all?: boolean;
@@ -402,31 +391,224 @@ declare class WhisperContext {
         keys_cleared: number;
         bytes_freed: number;
     }>;
-    /**
-     * Get Cost Summary - Cost tracking overview
-     */
-    getCostSummary(params: {
+    getCostSummary(params?: {
         project?: string;
         start_date?: string;
         end_date?: string;
     }): Promise<any>;
-    /**
-     * Get Cost Breakdown - Detailed cost analysis
-     */
-    getCostBreakdown(params: {
+    getCostBreakdown(params?: {
         project?: string;
         group_by?: "model" | "task" | "day" | "hour";
         start_date?: string;
         end_date?: string;
     }): Promise<any>;
     /**
-     * Get Savings Report - Compare actual vs always-Opus costs
+     * Semantic search over raw documents without pre-indexing.
+     * Send file contents/summaries directly — the API embeds them in-memory and ranks by similarity.
+     * Perfect for AI agents to semantically explore a codebase on-the-fly.
      */
-    getCostSavings(params: {
+    semanticSearch(params: {
+        query: string;
+        documents: Array<{
+            id: string;
+            content: string;
+        }>;
+        top_k?: number;
+        threshold?: number;
+    }): Promise<{
+        results: Array<{
+            id: string;
+            score: number;
+            content: string;
+            snippet: string;
+        }>;
+        total_searched: number;
+        total_returned: number;
+        query: string;
+        latency_ms: number;
+    }>;
+    searchFiles(params: {
+        query: string;
+        path?: string;
+        mode?: "content" | "filename" | "both";
+        file_types?: string[];
+        max_results?: number;
+        context_lines?: number;
+        case_sensitive?: boolean;
+    }): Promise<{
+        results: Array<{
+            file: string;
+            matches: Array<{
+                line: number;
+                content: string;
+                context_before: string[];
+                context_after: string[];
+            }>;
+        }>;
+        total_files: number;
+        total_matches: number;
+        search_path: string;
+        mode: string;
+        latency_ms: number;
+        engine: "ripgrep" | "node";
+    }>;
+    getCostSavings(params?: {
         project?: string;
         start_date?: string;
         end_date?: string;
     }): Promise<any>;
+    readonly projects: {
+        create: (params: {
+            name: string;
+            description?: string;
+            settings?: Record<string, any>;
+        }) => Promise<Project>;
+        list: () => Promise<{
+            projects: Project[];
+        }>;
+        get: (id: string) => Promise<Project & {
+            sources: Source[];
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly sources: {
+        add: (projectId: string, params: {
+            name: string;
+            connector_type: string;
+            config: Record<string, any>;
+            sync_schedule?: string;
+        }) => Promise<Source>;
+        sync: (sourceId: string) => Promise<any>;
+        syncSource: (sourceId: string) => Promise<any>;
+    };
+    readonly memory: {
+        add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<{
+            id: string;
+            success: boolean;
+            path: "sota" | "legacy";
+            fallback_used: boolean;
+        }>;
+        search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
+        searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
+        ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
+            success: boolean;
+            memories_created: number;
+            relations_created: number;
+            memories_invalidated: number;
+            errors?: string[];
+        }>;
+        getSessionMemories: (params: Parameters<WhisperContext["getSessionMemories"]>[0]) => Promise<{
+            memories: any[];
+            count: number;
+        }>;
+        getUserProfile: (params: Parameters<WhisperContext["getUserProfile"]>[0]) => Promise<{
+            user_id: string;
+            memories: any[];
+            count: number;
+        }>;
+        getVersions: (memoryId: string) => Promise<{
+            memory_id: string;
+            versions: any[];
+            count: number;
+        }>;
+        update: (memoryId: string, params: Parameters<WhisperContext["updateMemory"]>[1]) => Promise<{
+            success: boolean;
+            new_memory_id: string;
+            old_memory_id: string;
+        }>;
+        delete: (memoryId: string) => Promise<{
+            success: boolean;
+            deleted: string;
+        }>;
+        getRelations: (memoryId: string) => Promise<{
+            memory_id: string;
+            relations: any[];
+            count: number;
+        }>;
+        consolidate: (params: Parameters<WhisperContext["consolidateMemories"]>[0]) => Promise<any>;
+        updateDecay: (params: Parameters<WhisperContext["updateImportanceDecay"]>[0]) => Promise<{
+            success: boolean;
+            memories_updated: number;
+            average_importance: number;
+            memories_archived: number;
+            config: any;
+        }>;
+        getImportanceStats: (project?: string) => Promise<{
+            project_id: string;
+            statistics: any;
+        }>;
+    };
+    readonly keys: {
+        create: (params: Parameters<WhisperContext["createApiKey"]>[0]) => Promise<{
+            key: string;
+            prefix: string;
+            name: string;
+        }>;
+        list: () => Promise<{
+            keys: any[];
+        }>;
+        getUsage: (days?: number) => Promise<any>;
+    };
+    readonly oracle: {
+        search: (params: Parameters<WhisperContext["oracleSearch"]>[0]) => Promise<any>;
+    };
+    readonly context: {
+        createShare: (params: Parameters<WhisperContext["createSharedContext"]>[0]) => Promise<{
+            success: boolean;
+            share_id: string;
+            share_url: string;
+            title: string;
+            memories_count: number;
+            messages_count: number;
+            expires_at: string;
+        }>;
+        loadShare: (shareId: string) => Promise<{
+            share_id: string;
+            title: string;
+            created_at: string;
+            expires_at: string;
+            memories: any[];
+            messages: any[];
+            chunks?: any[];
+            metadata: any;
+        }>;
+        resumeShare: (params: Parameters<WhisperContext["resumeFromSharedContext"]>[0]) => Promise<{
+            success: boolean;
+            session_id: string;
+            memories_restored: number;
+            messages_restored: number;
+            chunks_restored: number;
+        }>;
+    };
+    readonly optimization: {
+        getCacheStats: () => Promise<{
+            cache_type: string;
+            hit_rate: number;
+            total_requests: number;
+            hits: number;
+            misses: number;
+            size_bytes: number;
+            keys_count: number;
+            average_latency_ms: number;
+            uptime_seconds: number;
+        }>;
+        warmCache: (params: Parameters<WhisperContext["warmCache"]>[0]) => Promise<{
+            success: boolean;
+            queries_warmed: number;
+            errors: string[];
+            cache_size_increase_bytes: number;
+        }>;
+        clearCache: (params: Parameters<WhisperContext["clearCache"]>[0]) => Promise<{
+            success: boolean;
+            keys_cleared: number;
+            bytes_freed: number;
+        }>;
+        getCostSummary: (params?: Parameters<WhisperContext["getCostSummary"]>[0]) => Promise<any>;
+        getCostBreakdown: (params?: Parameters<WhisperContext["getCostBreakdown"]>[0]) => Promise<any>;
+        getCostSavings: (params?: Parameters<WhisperContext["getCostSavings"]>[0]) => Promise<any>;
+    };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperContext as default };
+export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperError, type WhisperErrorCode, WhisperContext as default };