@usewhisper/sdk 1.0.0 → 1.0.1

package/index.mjs

@@ -0,0 +1,566 @@
+// ../src/sdk/index.ts
+var WhisperError = class extends Error {
+  code;
+  status;
+  retryable;
+  details;
+  constructor(args) {
+    super(args.message);
+    this.name = "WhisperError";
+    this.code = args.code;
+    this.status = args.status;
+    this.retryable = args.retryable ?? false;
+    this.details = args.details;
+  }
+};
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 250;
+var DEFAULT_MAX_DELAY_MS = 2e3;
+var DEFAULT_TIMEOUT_MS = 15e3;
+var PROJECT_CACHE_TTL_MS = 3e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getBackoffDelay(attempt, base, max) {
+  const jitter = 0.8 + Math.random() * 0.4;
+  return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+}
+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);
+}
+var WhisperContext = class _WhisperContext {
+  apiKey;
+  baseUrl;
+  defaultProject;
+  orgId;
+  timeoutMs;
+  retryConfig;
+  projectRefToId = /* @__PURE__ */ new Map();
+  projectCache = [];
+  projectCacheExpiresAt = 0;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new WhisperError({
+        code: "INVALID_API_KEY",
+        message: "API key is required"
+      });
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = 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,
+      baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+      maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
+    };
+  }
+  withProject(project) {
+    return new _WhisperContext({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      project,
+      orgId: this.orgId,
+      timeoutMs: this.timeoutMs,
+      retry: this.retryConfig
+    });
+  }
+  getRequiredProject(project) {
+    const resolved = project || this.defaultProject;
+    if (!resolved) {
+      throw new WhisperError({
+        code: "MISSING_PROJECT",
+        message: "Project is required. Pass project in params or set a default project in WhisperContext config."
+      });
+    }
+    return resolved;
+  }
+  async refreshProjectCache(force = false) {
+    if (!force && Date.now() < this.projectCacheExpiresAt && this.projectCache.length > 0) {
+      return this.projectCache;
+    }
+    const response = await this.request("/v1/projects", { method: "GET" });
+    this.projectRefToId.clear();
+    this.projectCache = response.projects || [];
+    for (const p of this.projectCache) {
+      this.projectRefToId.set(p.id, p.id);
+      this.projectRefToId.set(p.slug, p.id);
+      this.projectRefToId.set(p.name, p.id);
+    }
+    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+    return this.projectCache;
+  }
+  async resolveProjectId(projectRef) {
+    if (this.projectRefToId.has(projectRef)) {
+      return this.projectRefToId.get(projectRef);
+    }
+    const projects = await this.refreshProjectCache(true);
+    const byDirect = projects.find((p) => p.id === projectRef);
+    if (byDirect) return byDirect.id;
+    const matches = projects.filter((p) => p.slug === projectRef || p.name === projectRef);
+    if (matches.length === 1) {
+      return matches[0].id;
+    }
+    if (matches.length > 1) {
+      throw new WhisperError({
+        code: "PROJECT_AMBIGUOUS",
+        message: `Project reference '${projectRef}' matched multiple projects. Use project id instead.`
+      });
+    }
+    if (isLikelyProjectId(projectRef)) {
+      return projectRef;
+    }
+    throw new WhisperError({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project '${projectRef}' not found`
+    });
+  }
+  async getProjectRefCandidates(projectRef) {
+    const candidates = /* @__PURE__ */ new Set([projectRef]);
+    try {
+      const projects = await this.refreshProjectCache(false);
+      const match = projects.find((p) => p.id === projectRef || p.slug === projectRef || p.name === projectRef);
+      if (match) {
+        candidates.add(match.id);
+        candidates.add(match.slug);
+        candidates.add(match.name);
+      } else if (isLikelyProjectId(projectRef)) {
+        const byId = projects.find((p) => p.id === projectRef);
+        if (byId) {
+          candidates.add(byId.slug);
+          candidates.add(byId.name);
+        }
+      }
+    } catch {
+    }
+    return Array.from(candidates).filter(Boolean);
+  }
+  async withProjectRefFallback(projectRef, execute) {
+    const refs = await this.getProjectRefCandidates(projectRef);
+    let lastError;
+    for (const ref of refs) {
+      try {
+        return await execute(ref);
+      } catch (error) {
+        lastError = error;
+        if (error instanceof WhisperError && error.code === "PROJECT_NOT_FOUND") {
+          continue;
+        }
+        throw error;
+      }
+    }
+    if (lastError instanceof Error) {
+      throw lastError;
+    }
+    throw new WhisperError({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project '${projectRef}' not found`
+    });
+  }
+  classifyError(status, message) {
+    if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
+      return { code: "INVALID_API_KEY", retryable: false };
+    }
+    if (status === 404 || /project not found/i.test(message)) {
+      return { code: "PROJECT_NOT_FOUND", retryable: false };
+    }
+    if (status === 408) {
+      return { code: "TIMEOUT", retryable: true };
+    }
+    if (status === 429) {
+      return { code: "RATE_LIMITED", retryable: true };
+    }
+    if (status !== void 0 && status >= 500) {
+      return { code: "TEMPORARY_UNAVAILABLE", retryable: true };
+    }
+    return { code: "REQUEST_FAILED", retryable: false };
+  }
+  async request(endpoint, options = {}) {
+    const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
+    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}`, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            ...this.orgId ? { "X-Whisper-Org-Id": this.orgId } : {},
+            ...options.headers
+          }
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+          let payload = null;
+          try {
+            payload = await response.json();
+          } catch {
+            payload = await response.text().catch(() => "");
+          }
+          const message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
+          const { code, retryable } = this.classifyError(response.status, message);
+          const err = new WhisperError({
+            code,
+            message,
+            status: response.status,
+            retryable,
+            details: payload
+          });
+          if (!retryable || attempt === maxAttempts - 1) {
+            throw err;
+          }
+          await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
+          continue;
+        }
+        return response.json();
+      } catch (error) {
+        clearTimeout(timeout);
+        const isAbort = error?.name === "AbortError";
+        const mapped = error instanceof WhisperError ? error : new WhisperError({
+          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          message: isAbort ? "Request timed out" : error?.message || "Network request failed",
+          retryable: true,
+          details: error
+        });
+        lastError = mapped;
+        if (!mapped.retryable || attempt === maxAttempts - 1) {
+          throw mapped;
+        }
+        await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
+      }
+    }
+    throw lastError instanceof Error ? lastError : new WhisperError({ code: "REQUEST_FAILED", message: "Request failed" });
+  }
+  async query(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/context/query", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async createProject(params) {
+    const project = await this.request("/v1/projects", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+    this.projectRefToId.set(project.id, project.id);
+    this.projectRefToId.set(project.slug, project.id);
+    this.projectRefToId.set(project.name, project.id);
+    this.projectCache = [
+      ...this.projectCache.filter((p) => p.id !== project.id),
+      project
+    ];
+    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+    return project;
+  }
+  async listProjects() {
+    const projects = await this.request("/v1/projects", { method: "GET" });
+    this.projectCache = projects.projects || [];
+    for (const p of projects.projects || []) {
+      this.projectRefToId.set(p.id, p.id);
+      this.projectRefToId.set(p.slug, p.id);
+      this.projectRefToId.set(p.name, p.id);
+    }
+    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+    return projects;
+  }
+  async getProject(id) {
+    const projectId = await this.resolveProjectId(id);
+    return this.request(`/v1/projects/${projectId}`);
+  }
+  async deleteProject(id) {
+    const projectId = await this.resolveProjectId(id);
+    return this.request(`/v1/projects/${projectId}`, { method: "DELETE" });
+  }
+  async addSource(projectId, params) {
+    const resolvedProjectId = await this.resolveProjectId(projectId);
+    return this.request(`/v1/projects/${resolvedProjectId}/sources`, {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async syncSource(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
+  }
+  async ingest(projectId, documents) {
+    const resolvedProjectId = await this.resolveProjectId(projectId);
+    return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
+      method: "POST",
+      body: JSON.stringify({ documents })
+    });
+  }
+  async addContext(params) {
+    const projectId = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.ingest(projectId, [
+      {
+        title: params.title || "Context",
+        content: params.content,
+        metadata: params.metadata || { source: "addContext" }
+      }
+    ]);
+  }
+  async addMemory(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        const direct = await this.request("/v1/memory", {
+          method: "POST",
+          body: JSON.stringify({
+            project,
+            content: params.content,
+            memory_type: params.memory_type,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            agent_id: params.agent_id,
+            importance: params.importance,
+            metadata: params.metadata
+          })
+        });
+        const id = direct?.memory?.id || direct?.id || direct?.memory_id;
+        if (id) {
+          return { id, success: true };
+        }
+      } catch {
+      }
+      await this.request("/v1/memory/ingest/session", {
+        method: "POST",
+        body: JSON.stringify({
+          project,
+          session_id: params.session_id || `single-${Date.now()}`,
+          user_id: params.user_id,
+          messages: [
+            {
+              role: "user",
+              content: params.content,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            }
+          ]
+        })
+      });
+      return { id: `session-${Date.now()}`, success: true };
+    });
+  }
+  async searchMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
+      method: "POST",
+      body: JSON.stringify({
+        query: params.query,
+        project,
+        user_id: params.user_id,
+        session_id: params.session_id,
+        memory_types: params.memory_type ? [params.memory_type] : void 0,
+        top_k: params.top_k || 10
+      })
+    }));
+  }
+  async createApiKey(params) {
+    return this.request("/v1/keys", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listApiKeys() {
+    return this.request("/v1/keys");
+  }
+  async getUsage(days = 30) {
+    return this.request(`/v1/usage?days=${days}`);
+  }
+  async searchMemoriesSOTA(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async ingestSession(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/ingest/session", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async getSessionMemories(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.limit && { limit: params.limit.toString() },
+      ...params.since_date && { since_date: params.since_date }
+    });
+    return this.request(`/v1/memory/session/${params.session_id}?${query}`);
+  }
+  async getUserProfile(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.memory_types && { memory_types: params.memory_types }
+    });
+    return this.request(`/v1/memory/profile/${params.user_id}?${query}`);
+  }
+  async getMemoryVersions(memoryId) {
+    return this.request(`/v1/memory/${memoryId}/versions`);
+  }
+  async updateMemory(memoryId, params) {
+    return this.request(`/v1/memory/${memoryId}`, {
+      method: "PUT",
+      body: JSON.stringify(params)
+    });
+  }
+  async deleteMemory(memoryId) {
+    return this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+  }
+  async getMemoryRelations(memoryId) {
+    return this.request(`/v1/memory/${memoryId}/relations`);
+  }
+  async oracleSearch(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/oracle/search", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async autosubscribe(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/autosubscribe", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async createSharedContext(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/context/share", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async loadSharedContext(shareId) {
+    return this.request(`/v1/context/shared/${shareId}`);
+  }
+  async resumeFromSharedContext(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/context/resume", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async consolidateMemories(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/memory/consolidate", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async updateImportanceDecay(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/memory/decay/update", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async getImportanceStats(project) {
+    const resolvedProject = await this.resolveProjectId(this.getRequiredProject(project));
+    return this.request(`/v1/memory/decay/stats?project=${resolvedProject}`);
+  }
+  async getCacheStats() {
+    return this.request("/v1/cache/stats");
+  }
+  async warmCache(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    return this.request("/v1/cache/warm", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    });
+  }
+  async clearCache(params) {
+    return this.request("/v1/cache/clear", {
+      method: "DELETE",
+      body: JSON.stringify(params)
+    });
+  }
+  async getCostSummary(params = {}) {
+    const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
+    const query = new URLSearchParams({
+      ...resolvedProject && { project: resolvedProject },
+      ...params.start_date && { start_date: params.start_date },
+      ...params.end_date && { end_date: params.end_date }
+    });
+    return this.request(`/v1/cost/summary?${query}`);
+  }
+  async getCostBreakdown(params = {}) {
+    const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
+    const query = new URLSearchParams({
+      ...resolvedProject && { project: resolvedProject },
+      ...params.group_by && { group_by: params.group_by },
+      ...params.start_date && { start_date: params.start_date },
+      ...params.end_date && { end_date: params.end_date }
+    });
+    return this.request(`/v1/cost/breakdown?${query}`);
+  }
+  async getCostSavings(params = {}) {
+    const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
+    const query = new URLSearchParams({
+      ...resolvedProject && { project: resolvedProject },
+      ...params.start_date && { start_date: params.start_date },
+      ...params.end_date && { end_date: params.end_date }
+    });
+    return this.request(`/v1/cost/savings?${query}`);
+  }
+  // Backward-compatible grouped namespaces.
+  projects = {
+    create: (params) => this.createProject(params),
+    list: () => this.listProjects(),
+    get: (id) => this.getProject(id),
+    delete: (id) => this.deleteProject(id)
+  };
+  sources = {
+    add: (projectId, params) => this.addSource(projectId, params),
+    sync: (sourceId) => this.syncSource(sourceId),
+    syncSource: (sourceId) => this.syncSource(sourceId)
+  };
+  memory = {
+    add: (params) => this.addMemory(params),
+    search: (params) => this.searchMemories(params),
+    searchSOTA: (params) => this.searchMemoriesSOTA(params),
+    ingestSession: (params) => this.ingestSession(params),
+    getSessionMemories: (params) => this.getSessionMemories(params),
+    getUserProfile: (params) => this.getUserProfile(params),
+    getVersions: (memoryId) => this.getMemoryVersions(memoryId),
+    update: (memoryId, params) => this.updateMemory(memoryId, params),
+    delete: (memoryId) => this.deleteMemory(memoryId),
+    getRelations: (memoryId) => this.getMemoryRelations(memoryId),
+    consolidate: (params) => this.consolidateMemories(params),
+    updateDecay: (params) => this.updateImportanceDecay(params),
+    getImportanceStats: (project) => this.getImportanceStats(project)
+  };
+  keys = {
+    create: (params) => this.createApiKey(params),
+    list: () => this.listApiKeys(),
+    getUsage: (days) => this.getUsage(days)
+  };
+  oracle = {
+    search: (params) => this.oracleSearch(params)
+  };
+  context = {
+    createShare: (params) => this.createSharedContext(params),
+    loadShare: (shareId) => this.loadSharedContext(shareId),
+    resumeShare: (params) => this.resumeFromSharedContext(params)
+  };
+  optimization = {
+    getCacheStats: () => this.getCacheStats(),
+    warmCache: (params) => this.warmCache(params),
+    clearCache: (params) => this.clearCache(params),
+    getCostSummary: (params) => this.getCostSummary(params),
+    getCostBreakdown: (params) => this.getCostBreakdown(params),
+    getCostSavings: (params) => this.getCostSavings(params)
+  };
+};
+var index_default = WhisperContext;
+export {
+  WhisperContext,
+  WhisperError,
+  index_default as default
+};

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@usewhisper/sdk",
-  "version": "1.0.0",
+  "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.cjs",
-  "module": "index.js",
+  "main": "index.js",
+  "module": "index.mjs",
   "types": "index.d.ts",
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.js",
-      "require": "./index.cjs"
+      "import": "./index.mjs",
+      "require": "./index.js"
     }
   },
   "files": [
     "index.js",
-    "index.cjs",
+    "index.mjs",
     "index.d.ts",
-    "index.d.cts",
+    "index.d.mts",
     "README.md"
   ],
   "keywords": [