@usewhisper/sdk 1.1.0 → 2.1.0

package/index.mjs

@@ -1,3 +1,319 @@
+// ../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.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",
+      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:",
+      autoExtract: options.autoExtract ?? true,
+      autoExtractMinConfidence: options.autoExtractMinConfidence ?? 0.65,
+      maxMemoriesPerCapture: options.maxMemoriesPerCapture ?? 5
+    };
+  }
+  /**
+   * 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 {
+      if (this.options.autoExtract) {
+        const extraction = await this.client.extractMemories({
+          project: options?.project ?? this.options.project,
+          message: content,
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          enable_pattern: true,
+          enable_inference: true,
+          min_confidence: this.options.autoExtractMinConfidence
+        });
+        const extractedMemories = (extraction.all || []).filter((m) => (m.confidence || 0) >= this.options.autoExtractMinConfidence).slice(0, this.options.maxMemoriesPerCapture);
+        if (extractedMemories.length > 0) {
+          const bulk = await this.client.addMemoriesBulk({
+            project: options?.project ?? this.options.project,
+            async: false,
+            memories: extractedMemories.map((m) => ({
+              content: m.content,
+              memory_type: m.memoryType,
+              user_id: options?.userId ?? this.userId,
+              session_id: options?.sessionId ?? this.sessionId,
+              importance: Math.max(0.5, Math.min(1, m.confidence || 0.7)),
+              confidence: m.confidence || 0.7,
+              entity_mentions: m.entityMentions || [],
+              event_date: m.eventDate || void 0,
+              metadata: {
+                extracted: true,
+                extraction_method: extraction.extractionMethod,
+                extraction_reasoning: m.reasoning,
+                inferred: Boolean(m.inferred)
+              }
+            }))
+          });
+          const memoryIds = this.extractMemoryIdsFromBulkResponse(bulk);
+          return {
+            success: true,
+            memoryId: memoryIds[0],
+            memoryIds: memoryIds.length > 0 ? memoryIds : void 0,
+            extracted: extractedMemories.length
+          };
+        }
+      }
+      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 };
+    }
+  }
+  /**
+   * Run a full agent turn with automatic memory read (before) + write (after).
+   */
+  async runTurn(params) {
+    const contextResult = await this.getContext(params.userMessage, {
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project,
+      limit: params.limit
+    });
+    const prompt = contextResult.context ? `${contextResult.context}
+
+User: ${params.userMessage}` : params.userMessage;
+    const response = await params.generate(prompt);
+    const captureResult = await this.captureSession(
+      [
+        { role: "user", content: params.userMessage },
+        { role: "assistant", content: response }
+      ],
+      {
+        userId: params.userId,
+        sessionId: params.sessionId,
+        project: params.project
+      }
+    );
+    return {
+      response,
+      context: contextResult.context,
+      count: contextResult.count,
+      extracted: captureResult.extracted
+    };
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+  extractMemoryIdsFromBulkResponse(bulkResponse) {
+    const ids = [];
+    if (Array.isArray(bulkResponse?.memories)) {
+      for (const memory of bulkResponse.memories) {
+        if (memory?.id) ids.push(memory.id);
+      }
+    }
+    if (bulkResponse?.memory?.id) {
+      ids.push(bulkResponse.memory.id);
+    }
+    if (bulkResponse?.id) {
+      ids.push(bulkResponse.id);
+    }
+    return Array.from(new Set(ids));
+  }
+};
+var whisper_agent_default = Whisper;
+
+// ../src/sdk/middleware.ts
+var WhisperAgentMiddleware = class {
+  whisper;
+  promptBuilder;
+  constructor(config) {
+    this.whisper = new Whisper(config);
+    this.promptBuilder = config.promptBuilder || (({ context, userMessage }) => {
+      if (!context) return userMessage;
+      return `${context}
+
+User: ${userMessage}`;
+    });
+  }
+  async beforeTurn(params) {
+    const contextResult = await this.whisper.getContext(params.userMessage, {
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project,
+      limit: params.contextLimit
+    });
+    const prompt = this.promptBuilder({
+      context: contextResult.context,
+      userMessage: params.userMessage
+    });
+    return {
+      prompt,
+      context: contextResult.context,
+      contextCount: contextResult.count
+    };
+  }
+  async afterTurn(params) {
+    return this.whisper.captureSession(
+      [
+        { role: "user", content: params.userMessage },
+        { role: "assistant", content: params.assistantMessage }
+      ],
+      {
+        userId: params.userId,
+        sessionId: params.sessionId,
+        project: params.project
+      }
+    );
+  }
+  async wrapGenerate(params) {
+    const before = await this.beforeTurn(params);
+    const response = await params.generate(before.prompt);
+    const after = await this.afterTurn({
+      userMessage: params.userMessage,
+      assistantMessage: response,
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project
+    });
+    return {
+      response,
+      prompt: before.prompt,
+      context: before.context,
+      contextCount: before.contextCount,
+      extracted: after.extracted
+    };
+  }
+  raw() {
+    return this.whisper;
+  }
+};
+function createAgentMiddleware(config) {
+  return new WhisperAgentMiddleware(config);
+}
+
 // ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
@@ -28,11 +344,24 @@ function getBackoffDelay(attempt, base, max) {
 function isLikelyProjectId(projectRef) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(projectRef);
 }
+function normalizeBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
   defaultProject;
-  orgId;
   timeoutMs;
   retryConfig;
   projectRefToId = /* @__PURE__ */ new Map();
@@ -46,9 +375,8 @@ var WhisperContext = class _WhisperContext {
       });
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+    this.baseUrl = normalizeBaseUrl(config.baseUrl || "https://context.usewhisper.dev");
     this.defaultProject = config.project;
-    this.orgId = config.orgId;
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.retryConfig = {
       maxAttempts: config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
@@ -61,7 +389,6 @@ var WhisperContext = class _WhisperContext {
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       project,
-      orgId: this.orgId,
       timeoutMs: this.timeoutMs,
       retry: this.retryConfig
     });
@@ -178,20 +505,28 @@ var WhisperContext = class _WhisperContext {
   }
   async request(endpoint, options = {}) {
     const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
+    const normalizedEndpoint = normalizeEndpoint(endpoint);
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
       try {
-        const response = await fetch(`${this.baseUrl}${endpoint}`, {
+        const headers = {
+          "Content-Type": "application/json",
+          ...options.headers
+        };
+        const hasAuthHeader = Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+        const hasApiKeyHeader = Object.keys(headers).some((k) => k.toLowerCase() === "x-api-key");
+        if (!hasAuthHeader) {
+          headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        if (!hasApiKeyHeader) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
           ...options,
           signal: controller.signal,
-          headers: {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-            ...this.orgId ? { "X-Whisper-Org-Id": this.orgId } : {},
-            ...options.headers
-          }
+          headers
         });
         clearTimeout(timeout);
         if (!response.ok) {
@@ -380,6 +715,34 @@ var WhisperContext = class _WhisperContext {
       return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
+  async addMemoriesBulk(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/bulk", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractSessionMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract/session", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params,
+        project,
+        messages: params.messages.map((m) => ({
+          ...m,
+          timestamp: m.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      })
+    }));
+  }
   async searchMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
     return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
@@ -576,6 +939,9 @@ var WhisperContext = class _WhisperContext {
   };
   memory = {
     add: (params) => this.addMemory(params),
+    addBulk: (params) => this.addMemoriesBulk(params),
+    extract: (params) => this.extractMemories(params),
+    extractSession: (params) => this.extractSessionMemories(params),
     search: (params) => this.searchMemories(params),
     searchSOTA: (params) => this.searchMemoriesSOTA(params),
     ingestSession: (params) => this.ingestSession(params),
@@ -613,7 +979,11 @@ var WhisperContext = class _WhisperContext {
 };
 var index_default = WhisperContext;
 export {
+  Whisper,
+  WhisperAgentMiddleware,
   WhisperContext,
+  whisper_agent_default as WhisperDefault,
   WhisperError,
+  createAgentMiddleware,
   index_default as default
 };

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "@usewhisper/sdk",
-  "version": "1.1.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"
-  }
-}
+{
+  "name": "@usewhisper/sdk",
+  "version": "2.1.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"
+  }
+}