@usewhisper/sdk 1.0.1 → 2.0.0

package/index.js

@@ -20,11 +20,173 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // ../src/sdk/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Whisper: () => Whisper,
   WhisperContext: () => WhisperContext,
+  WhisperDefault: () => whisper_agent_default,
   WhisperError: () => WhisperError,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+
+// ../src/sdk/whisper-agent.ts
+var Whisper = class {
+  client;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.orgId) clientConfig.orgId = options.orgId;
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      orgId: options.orgId || "",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:"
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const result = await this.client.query({
+      project: options?.project ?? this.options.project,
+      query,
+      top_k: options?.limit ?? this.options.contextLimit,
+      include_memories: true,
+      user_id: options?.userId ?? this.userId,
+      session_id: options?.sessionId ?? this.sessionId
+    });
+    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results: result.results,
+      count: result.meta.total
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
+  }
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
+    try {
+      const result = await this.client.ingestSession({
+        project: options?.project ?? this.options.project,
+        session_id: options?.sessionId ?? this.sessionId ?? "default",
+        user_id: options?.userId ?? this.userId,
+        messages: messages.filter((m) => m.role !== "system").map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      });
+      return {
+        success: true,
+        extracted: result?.memories_created ?? 0
+      };
+    } catch (error) {
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
+    }
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+};
+var whisper_agent_default = Whisper;
+
+// ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
   status;
@@ -332,13 +494,40 @@ var WhisperContext = class _WhisperContext {
   async addMemory(params) {
     const projectRef = this.getRequiredProject(params.project);
     return this.withProjectRefFallback(projectRef, async (project) => {
+      const toSotaType = (memoryType) => {
+        switch (memoryType) {
+          case "episodic":
+            return "event";
+          case "semantic":
+            return "factual";
+          case "procedural":
+            return "instruction";
+          default:
+            return memoryType;
+        }
+      };
+      const toLegacyType = (memoryType) => {
+        switch (memoryType) {
+          case "event":
+            return "episodic";
+          case "instruction":
+            return "procedural";
+          case "preference":
+          case "relationship":
+          case "opinion":
+          case "goal":
+            return "semantic";
+          default:
+            return memoryType;
+        }
+      };
       try {
         const direct = await this.request("/v1/memory", {
           method: "POST",
           body: JSON.stringify({
             project,
             content: params.content,
-            memory_type: params.memory_type,
+            memory_type: toSotaType(params.memory_type),
             user_id: params.user_id,
             session_id: params.session_id,
             agent_id: params.agent_id,
@@ -346,28 +535,37 @@ var WhisperContext = class _WhisperContext {
             metadata: params.metadata
           })
         });
-        const id = direct?.memory?.id || direct?.id || direct?.memory_id;
-        if (id) {
-          return { id, success: true };
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        if (id2) {
+          return { id: id2, success: true, path: "sota", fallback_used: false };
+        }
+      } catch (error) {
+        if (params.allow_legacy_fallback === false) {
+          throw error;
         }
-      } catch {
       }
-      await this.request("/v1/memory/ingest/session", {
+      const legacy = await this.request("/v1/memories", {
         method: "POST",
         body: JSON.stringify({
           project,
-          session_id: params.session_id || `single-${Date.now()}`,
+          content: params.content,
+          memory_type: toLegacyType(params.memory_type),
           user_id: params.user_id,
-          messages: [
-            {
-              role: "user",
-              content: params.content,
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            }
-          ]
+          session_id: params.session_id,
+          agent_id: params.agent_id,
+          importance: params.importance,
+          metadata: params.metadata,
+          expires_in_seconds: params.expires_in_seconds
         })
       });
-      return { id: `session-${Date.now()}`, success: true };
+      const id = legacy?.memory?.id || legacy?.id || legacy?.memory_id;
+      if (!id) {
+        throw new WhisperError({
+          code: "REQUEST_FAILED",
+          message: "Memory create succeeded but no memory id was returned by the API"
+        });
+      }
+      return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
   async searchMemories(params) {
@@ -526,6 +724,23 @@ var WhisperContext = class _WhisperContext {
     });
     return this.request(`/v1/cost/breakdown?${query}`);
   }
+  /**
+   * 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.
+   */
+  async semanticSearch(params) {
+    return this.request("/v1/search/semantic", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async searchFiles(params) {
+    return this.request("/v1/search/files", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
   async getCostSavings(params = {}) {
     const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
     const query = new URLSearchParams({
@@ -587,6 +802,8 @@ var WhisperContext = class _WhisperContext {
 var index_default = WhisperContext;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Whisper,
   WhisperContext,
+  WhisperDefault,
   WhisperError
 });

package/index.mjs

@@ -1,3 +1,161 @@
+// ../src/sdk/whisper-agent.ts
+var Whisper = class {
+  client;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.orgId) clientConfig.orgId = options.orgId;
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      orgId: options.orgId || "",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:"
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const result = await this.client.query({
+      project: options?.project ?? this.options.project,
+      query,
+      top_k: options?.limit ?? this.options.contextLimit,
+      include_memories: true,
+      user_id: options?.userId ?? this.userId,
+      session_id: options?.sessionId ?? this.sessionId
+    });
+    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results: result.results,
+      count: result.meta.total
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
+  }
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
+    try {
+      const result = await this.client.ingestSession({
+        project: options?.project ?? this.options.project,
+        session_id: options?.sessionId ?? this.sessionId ?? "default",
+        user_id: options?.userId ?? this.userId,
+        messages: messages.filter((m) => m.role !== "system").map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      });
+      return {
+        success: true,
+        extracted: result?.memories_created ?? 0
+      };
+    } catch (error) {
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
+    }
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+};
+var whisper_agent_default = Whisper;
+
 // ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
@@ -306,13 +464,40 @@ var WhisperContext = class _WhisperContext {
   async addMemory(params) {
     const projectRef = this.getRequiredProject(params.project);
     return this.withProjectRefFallback(projectRef, async (project) => {
+      const toSotaType = (memoryType) => {
+        switch (memoryType) {
+          case "episodic":
+            return "event";
+          case "semantic":
+            return "factual";
+          case "procedural":
+            return "instruction";
+          default:
+            return memoryType;
+        }
+      };
+      const toLegacyType = (memoryType) => {
+        switch (memoryType) {
+          case "event":
+            return "episodic";
+          case "instruction":
+            return "procedural";
+          case "preference":
+          case "relationship":
+          case "opinion":
+          case "goal":
+            return "semantic";
+          default:
+            return memoryType;
+        }
+      };
       try {
         const direct = await this.request("/v1/memory", {
           method: "POST",
           body: JSON.stringify({
             project,
             content: params.content,
-            memory_type: params.memory_type,
+            memory_type: toSotaType(params.memory_type),
             user_id: params.user_id,
             session_id: params.session_id,
             agent_id: params.agent_id,
@@ -320,28 +505,37 @@ var WhisperContext = class _WhisperContext {
             metadata: params.metadata
           })
         });
-        const id = direct?.memory?.id || direct?.id || direct?.memory_id;
-        if (id) {
-          return { id, success: true };
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        if (id2) {
+          return { id: id2, success: true, path: "sota", fallback_used: false };
+        }
+      } catch (error) {
+        if (params.allow_legacy_fallback === false) {
+          throw error;
         }
-      } catch {
       }
-      await this.request("/v1/memory/ingest/session", {
+      const legacy = await this.request("/v1/memories", {
         method: "POST",
         body: JSON.stringify({
           project,
-          session_id: params.session_id || `single-${Date.now()}`,
+          content: params.content,
+          memory_type: toLegacyType(params.memory_type),
           user_id: params.user_id,
-          messages: [
-            {
-              role: "user",
-              content: params.content,
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            }
-          ]
+          session_id: params.session_id,
+          agent_id: params.agent_id,
+          importance: params.importance,
+          metadata: params.metadata,
+          expires_in_seconds: params.expires_in_seconds
         })
       });
-      return { id: `session-${Date.now()}`, success: true };
+      const id = legacy?.memory?.id || legacy?.id || legacy?.memory_id;
+      if (!id) {
+        throw new WhisperError({
+          code: "REQUEST_FAILED",
+          message: "Memory create succeeded but no memory id was returned by the API"
+        });
+      }
+      return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
   async searchMemories(params) {
@@ -500,6 +694,23 @@ var WhisperContext = class _WhisperContext {
     });
     return this.request(`/v1/cost/breakdown?${query}`);
   }
+  /**
+   * 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.
+   */
+  async semanticSearch(params) {
+    return this.request("/v1/search/semantic", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async searchFiles(params) {
+    return this.request("/v1/search/files", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
   async getCostSavings(params = {}) {
     const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
     const query = new URLSearchParams({
@@ -560,7 +771,9 @@ var WhisperContext = class _WhisperContext {
 };
 var index_default = WhisperContext;
 export {
+  Whisper,
   WhisperContext,
+  whisper_agent_default as WhisperDefault,
   WhisperError,
   index_default as default
 };

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "@usewhisper/sdk",
-  "version": "1.0.1",
-  "scripts": {
-    "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
-    "prepublishOnly": "npm run build"
-  },
-  "description": "TypeScript SDK for Whisper Context API - Add reliable context to your AI agents",
-  "main": "index.js",
-  "module": "index.mjs",
-  "types": "index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js"
-    }
-  },
-  "files": [
-    "index.js",
-    "index.mjs",
-    "index.d.ts",
-    "index.d.mts",
-    "README.md"
-  ],
-  "keywords": [
-    "whisper",
-    "context",
-    "ai",
-    "llm",
-    "rag",
-    "embeddings",
-    "vector-search",
-    "knowledge-graph",
-    "semantic-search"
-  ],
-  "author": "Whisper",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Alixus/"
-  },
-  "homepage": "https://usewhisper.dev",
-  "bugs": {
-    "url": "https://github.com/Alinxus/whisper/issues"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.7.0"
-  },
-  "peerDependencies": {},
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@usewhisper/sdk",
+  "version": "2.0.0",
+  "scripts": {
+    "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
+    "prepublishOnly": "npm run build"
+  },
+  "description": "TypeScript SDK for Whisper Context API - Add reliable context to your AI agents",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "index.d.mts",
+    "README.md"
+  ],
+  "keywords": [
+    "whisper",
+    "context",
+    "ai",
+    "llm",
+    "rag",
+    "embeddings",
+    "vector-search",
+    "knowledge-graph",
+    "semantic-search"
+  ],
+  "author": "Whisper",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alixus/"
+  },
+  "homepage": "https://usewhisper.dev",
+  "bugs": {
+    "url": "https://github.com/Alinxus/whisper/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}