@usewhisper/sdk 3.2.0 → 3.3.0

package/index.d.mts

@@ -1197,9 +1197,13 @@ declare class WhisperContext {
     withProject(project: string): WhisperContext;
     private getRequiredProject;
     private refreshProjectCache;
+    private fetchResolvedProject;
+    resolveProject(projectRef?: string): Promise<Project>;
     private resolveProjectId;
     private getProjectRefCandidates;
     private withProjectRefFallback;
+    private shouldRetryWithResolvedProjectId;
+    private withProjectPathFallback;
     private classifyError;
     private isEndpointNotFoundError;
     private inferOperation;
@@ -1216,6 +1220,14 @@ declare class WhisperContext {
     getProject(id: string): Promise<Project & {
         sources: Source[];
     }>;
+    listSources(project?: string): Promise<{
+        project: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+        sources: Source[];
+    }>;
     deleteProject(id: string): Promise<{
         deleted: boolean;
     }>;

package/index.d.ts

@@ -1197,9 +1197,13 @@ declare class WhisperContext {
     withProject(project: string): WhisperContext;
     private getRequiredProject;
     private refreshProjectCache;
+    private fetchResolvedProject;
+    resolveProject(projectRef?: string): Promise<Project>;
     private resolveProjectId;
     private getProjectRefCandidates;
     private withProjectRefFallback;
+    private shouldRetryWithResolvedProjectId;
+    private withProjectPathFallback;
     private classifyError;
     private isEndpointNotFoundError;
     private inferOperation;
@@ -1216,6 +1220,14 @@ declare class WhisperContext {
     getProject(id: string): Promise<Project & {
         sources: Source[];
     }>;
+    listSources(project?: string): Promise<{
+        project: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+        sources: Source[];
+    }>;
     deleteProject(id: string): Promise<{
         deleted: boolean;
     }>;

package/index.js

@@ -2423,9 +2423,71 @@ var WhisperContext = class _WhisperContext {
       this.projectRefToId.set(p.slug, p.id);
       this.projectRefToId.set(p.name, p.id);
     }
+    if (this.defaultProject) {
+      const hasDefaultProject = this.projectCache.some(
+        (project) => project.id === this.defaultProject || project.slug === this.defaultProject || project.name === this.defaultProject
+      );
+      if (!hasDefaultProject) {
+        const resolvedDefault = await this.fetchResolvedProject(this.defaultProject);
+        if (resolvedDefault) {
+          this.projectCache = [...this.projectCache, resolvedDefault];
+          this.projectRefToId.set(resolvedDefault.id, resolvedDefault.id);
+          this.projectRefToId.set(resolvedDefault.slug, resolvedDefault.id);
+          this.projectRefToId.set(resolvedDefault.name, resolvedDefault.id);
+        }
+      }
+    }
     this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
     return this.projectCache;
   }
+  async fetchResolvedProject(projectRef) {
+    if (!projectRef) return null;
+    try {
+      const response = await this.request(`/v1/projects/resolve?project=${encodeURIComponent(projectRef)}`, { method: "GET" });
+      return response?.resolved || null;
+    } catch (error) {
+      if (error instanceof WhisperError && error.code === "PROJECT_NOT_FOUND") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async resolveProject(projectRef) {
+    const resolvedRef = this.getRequiredProject(projectRef);
+    const cachedProjects = await this.refreshProjectCache(false);
+    const cachedProject = cachedProjects.find(
+      (project) => project.id === resolvedRef || project.slug === resolvedRef || project.name === resolvedRef
+    );
+    if (cachedProject) {
+      return cachedProject;
+    }
+    const resolvedProject = await this.fetchResolvedProject(resolvedRef);
+    if (resolvedProject) {
+      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+      this.projectCache = [
+        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+        resolvedProject
+      ];
+      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+      return resolvedProject;
+    }
+    if (isLikelyProjectId(resolvedRef)) {
+      return {
+        id: resolvedRef,
+        orgId: "",
+        name: resolvedRef,
+        slug: resolvedRef,
+        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+      };
+    }
+    throw new WhisperError({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project '${resolvedRef}' not found`
+    });
+  }
   async resolveProjectId(projectRef) {
     if (this.projectRefToId.has(projectRef)) {
       return this.projectRefToId.get(projectRef);
@@ -2446,6 +2508,18 @@ var WhisperContext = class _WhisperContext {
     if (isLikelyProjectId(projectRef)) {
       return projectRef;
     }
+    const resolvedProject = await this.fetchResolvedProject(projectRef);
+    if (resolvedProject) {
+      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+      this.projectCache = [
+        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+        resolvedProject
+      ];
+      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+      return resolvedProject.id;
+    }
     throw new WhisperError({
       code: "PROJECT_NOT_FOUND",
       message: `Project '${projectRef}' not found`
@@ -2501,6 +2575,26 @@ var WhisperContext = class _WhisperContext {
       message: `Project '${projectRef}' not found`
     });
   }
+  shouldRetryWithResolvedProjectId(error) {
+    return error instanceof WhisperError && error.status === 404 && !this.isEndpointNotFoundError(error);
+  }
+  async withProjectPathFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!this.shouldRetryWithResolvedProjectId(error)) {
+        throw error;
+      }
+    }
+    const resolvedProjectId = await this.resolveProjectId(projectRef);
+    if (resolvedProjectId === projectRef) {
+      throw new WhisperError({
+        code: "PROJECT_NOT_FOUND",
+        message: `Project '${projectRef}' not found`
+      });
+    }
+    return execute(resolvedProjectId);
+  }
   classifyError(status, message) {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
@@ -2616,29 +2710,42 @@ var WhisperContext = class _WhisperContext {
     return projects;
   }
   async getProject(id) {
-    const projectId = await this.resolveProjectId(id);
-    return this.request(`/v1/projects/${projectId}`);
+    return this.withProjectPathFallback(
+      this.getRequiredProject(id),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}`)
+    );
+  }
+  async listSources(project) {
+    const projectRef = this.getRequiredProject(project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (resolvedProject) => this.request(`/v1/sources?project=${encodeURIComponent(resolvedProject)}`, { method: "GET" })
+    );
   }
   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)
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/sources`, {
+        method: "POST",
+        body: JSON.stringify(params)
+      })
+    );
   }
   async syncSource(sourceId) {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
   async addSourceByType(projectId, params) {
-    const resolvedProjectId = await this.resolveProjectId(projectId);
-    return this.request(`/v1/projects/${resolvedProjectId}/add_source`, {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/add_source`, {
+        method: "POST",
+        body: JSON.stringify(params)
+      })
+    );
   }
   async getSourceStatus(sourceId) {
     return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
@@ -2700,14 +2807,16 @@ var WhisperContext = class _WhisperContext {
     };
   }
   async ingest(projectId, documents) {
-    const resolvedProjectId = await this.resolveProjectId(projectId);
-    return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
-      method: "POST",
-      body: JSON.stringify({ documents })
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/ingest`, {
+        method: "POST",
+        body: JSON.stringify({ documents })
+      })
+    );
   }
   async addContext(params) {
-    const projectId = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const projectId = (await this.resolveProject(this.getRequiredProject(params.project))).id;
     return this.ingest(projectId, [
       {
         title: params.title || "Context",
@@ -3117,28 +3226,37 @@ var WhisperContext = class _WhisperContext {
     });
   }
   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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => 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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => 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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => this.request("/v1/memory/consolidate", {
+        method: "POST",
+        body: JSON.stringify({ ...params, project })
+      })
+    );
   }
   async updateImportanceDecay(params) {
     const project = await this.resolveProjectId(this.getRequiredProject(params.project));

package/index.mjs

@@ -2374,9 +2374,71 @@ var WhisperContext = class _WhisperContext {
       this.projectRefToId.set(p.slug, p.id);
       this.projectRefToId.set(p.name, p.id);
     }
+    if (this.defaultProject) {
+      const hasDefaultProject = this.projectCache.some(
+        (project) => project.id === this.defaultProject || project.slug === this.defaultProject || project.name === this.defaultProject
+      );
+      if (!hasDefaultProject) {
+        const resolvedDefault = await this.fetchResolvedProject(this.defaultProject);
+        if (resolvedDefault) {
+          this.projectCache = [...this.projectCache, resolvedDefault];
+          this.projectRefToId.set(resolvedDefault.id, resolvedDefault.id);
+          this.projectRefToId.set(resolvedDefault.slug, resolvedDefault.id);
+          this.projectRefToId.set(resolvedDefault.name, resolvedDefault.id);
+        }
+      }
+    }
     this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
     return this.projectCache;
   }
+  async fetchResolvedProject(projectRef) {
+    if (!projectRef) return null;
+    try {
+      const response = await this.request(`/v1/projects/resolve?project=${encodeURIComponent(projectRef)}`, { method: "GET" });
+      return response?.resolved || null;
+    } catch (error) {
+      if (error instanceof WhisperError && error.code === "PROJECT_NOT_FOUND") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async resolveProject(projectRef) {
+    const resolvedRef = this.getRequiredProject(projectRef);
+    const cachedProjects = await this.refreshProjectCache(false);
+    const cachedProject = cachedProjects.find(
+      (project) => project.id === resolvedRef || project.slug === resolvedRef || project.name === resolvedRef
+    );
+    if (cachedProject) {
+      return cachedProject;
+    }
+    const resolvedProject = await this.fetchResolvedProject(resolvedRef);
+    if (resolvedProject) {
+      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+      this.projectCache = [
+        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+        resolvedProject
+      ];
+      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+      return resolvedProject;
+    }
+    if (isLikelyProjectId(resolvedRef)) {
+      return {
+        id: resolvedRef,
+        orgId: "",
+        name: resolvedRef,
+        slug: resolvedRef,
+        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+      };
+    }
+    throw new WhisperError({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project '${resolvedRef}' not found`
+    });
+  }
   async resolveProjectId(projectRef) {
     if (this.projectRefToId.has(projectRef)) {
       return this.projectRefToId.get(projectRef);
@@ -2397,6 +2459,18 @@ var WhisperContext = class _WhisperContext {
     if (isLikelyProjectId(projectRef)) {
       return projectRef;
     }
+    const resolvedProject = await this.fetchResolvedProject(projectRef);
+    if (resolvedProject) {
+      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+      this.projectCache = [
+        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+        resolvedProject
+      ];
+      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+      return resolvedProject.id;
+    }
     throw new WhisperError({
       code: "PROJECT_NOT_FOUND",
       message: `Project '${projectRef}' not found`
@@ -2452,6 +2526,26 @@ var WhisperContext = class _WhisperContext {
       message: `Project '${projectRef}' not found`
     });
   }
+  shouldRetryWithResolvedProjectId(error) {
+    return error instanceof WhisperError && error.status === 404 && !this.isEndpointNotFoundError(error);
+  }
+  async withProjectPathFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!this.shouldRetryWithResolvedProjectId(error)) {
+        throw error;
+      }
+    }
+    const resolvedProjectId = await this.resolveProjectId(projectRef);
+    if (resolvedProjectId === projectRef) {
+      throw new WhisperError({
+        code: "PROJECT_NOT_FOUND",
+        message: `Project '${projectRef}' not found`
+      });
+    }
+    return execute(resolvedProjectId);
+  }
   classifyError(status, message) {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
@@ -2567,29 +2661,42 @@ var WhisperContext = class _WhisperContext {
     return projects;
   }
   async getProject(id) {
-    const projectId = await this.resolveProjectId(id);
-    return this.request(`/v1/projects/${projectId}`);
+    return this.withProjectPathFallback(
+      this.getRequiredProject(id),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}`)
+    );
+  }
+  async listSources(project) {
+    const projectRef = this.getRequiredProject(project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (resolvedProject) => this.request(`/v1/sources?project=${encodeURIComponent(resolvedProject)}`, { method: "GET" })
+    );
   }
   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)
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/sources`, {
+        method: "POST",
+        body: JSON.stringify(params)
+      })
+    );
   }
   async syncSource(sourceId) {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
   async addSourceByType(projectId, params) {
-    const resolvedProjectId = await this.resolveProjectId(projectId);
-    return this.request(`/v1/projects/${resolvedProjectId}/add_source`, {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/add_source`, {
+        method: "POST",
+        body: JSON.stringify(params)
+      })
+    );
   }
   async getSourceStatus(sourceId) {
     return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
@@ -2651,14 +2758,16 @@ var WhisperContext = class _WhisperContext {
     };
   }
   async ingest(projectId, documents) {
-    const resolvedProjectId = await this.resolveProjectId(projectId);
-    return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
-      method: "POST",
-      body: JSON.stringify({ documents })
-    });
+    return this.withProjectPathFallback(
+      this.getRequiredProject(projectId),
+      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/ingest`, {
+        method: "POST",
+        body: JSON.stringify({ documents })
+      })
+    );
   }
   async addContext(params) {
-    const projectId = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const projectId = (await this.resolveProject(this.getRequiredProject(params.project))).id;
     return this.ingest(projectId, [
       {
         title: params.title || "Context",
@@ -3068,28 +3177,37 @@ var WhisperContext = class _WhisperContext {
     });
   }
   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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => 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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => 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 })
-    });
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(
+      projectRef,
+      (project) => this.request("/v1/memory/consolidate", {
+        method: "POST",
+        body: JSON.stringify({ ...params, project })
+      })
+    );
   }
   async updateImportanceDecay(params) {
     const project = await this.resolveProjectId(this.getRequiredProject(params.project));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/sdk",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "whisperContractVersion": "2026.03.09",
   "scripts": {
     "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",