@usewhisper/sdk 3.0.0 → 3.1.0

package/README.md

@@ -14,7 +14,7 @@ npm install @usewhisper/sdk
 import { WhisperContext } from '@usewhisper/sdk';
 
 const whisper = new WhisperContext({ 
-  apiKey: 'wsk_your_api_key_here'
+  apiKey: 'wsk_your_api_key_here'
 });
 
 // Create a project
@@ -48,7 +48,7 @@ Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
 
 ```typescript
 const whisper = new WhisperContext({
-  apiKey: 'wsk_...',  // Your API key
+  apiKey: 'wsk_...',  // Your API key
   baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
 });
 ```

package/index.d.mts

@@ -324,6 +324,7 @@ declare class RuntimeClient {
     private readonly timeouts;
     private readonly diagnostics;
     private readonly inFlight;
+    private readonly sendApiKeyHeader;
     constructor(options: RuntimeClientOptions, diagnostics?: DiagnosticsStore);
     getDiagnosticsStore(): DiagnosticsStore;
     getCompatMode(): CompatMode;
@@ -332,6 +333,8 @@ declare class RuntimeClient {
     private shouldRetryStatus;
     private backoff;
     private runtimeName;
+    private apiKeyOnlyPrefixes;
+    private shouldAttachApiKeyHeader;
     private createRequestFingerprint;
     request<T>(options: RuntimeRequestOptions): Promise<RuntimeResponse<T>>;
     private performRequest;
@@ -496,6 +499,9 @@ declare class MemoryModule {
         memories: Array<Record<string, unknown>>;
         count: number;
     }>;
+    get(memoryId: string): Promise<{
+        memory: Record<string, unknown>;
+    }>;
     update(memoryId: string, params: {
         content: string;
         reasoning?: string;
@@ -654,6 +660,9 @@ declare class WhisperClient {
         add: (params: Parameters<MemoryModule["add"]>[0]) => Promise<MemoryWriteAck$1>;
         addBulk: (params: Parameters<MemoryModule["addBulk"]>[0]) => Promise<MemoryWriteAck$1>;
         search: (params: Parameters<MemoryModule["search"]>[0]) => Promise<MemorySearchResponse$1>;
+        get: (memoryId: string) => Promise<{
+            memory: Record<string, unknown>;
+        }>;
         getUserProfile: (params: Parameters<MemoryModule["getUserProfile"]>[0]) => ReturnType<MemoryModule["getUserProfile"]>;
         getSessionMemories: (params: Parameters<MemoryModule["getSessionMemories"]>[0]) => ReturnType<MemoryModule["getSessionMemories"]>;
         update: (memoryId: string, params: {
@@ -996,6 +1005,62 @@ interface Source {
     createdAt: string;
     updatedAt: string;
 }
+interface VideoSourceMetadata {
+    source_kind: "video";
+    video_url: string;
+    platform: "youtube" | "loom" | "generic";
+    duration_seconds?: number;
+    published_at?: string;
+    channel_or_author?: string;
+}
+interface VideoIngestionStatus {
+    source_id: string;
+    status: string;
+    stage: "extracting" | "transcribing" | "segmenting" | "enriching" | "indexing" | "completed" | "failed";
+    sync_job_id?: string | null;
+    progress?: {
+        current: number;
+        total: number;
+        message: string;
+    } | null;
+    duration_seconds?: number | null;
+    chunks_indexed?: number | null;
+    decisions_detected?: number | null;
+    entities_extracted?: string[];
+    last_error?: string | null;
+    updated_at?: string;
+}
+type CanonicalSourceType = "github" | "web" | "pdf" | "local" | "slack";
+interface CanonicalSourceCreateParams {
+    type: CanonicalSourceType;
+    name?: string;
+    auto_index?: boolean;
+    metadata?: Record<string, string>;
+    owner?: string;
+    repo?: string;
+    branch?: string;
+    paths?: string[];
+    url?: string;
+    crawl_depth?: number;
+    include_paths?: string[];
+    exclude_paths?: string[];
+    file_path?: string;
+    path?: string;
+    glob?: string;
+    max_files?: number;
+    workspace_id?: string;
+    channel_ids?: string[];
+    since?: string;
+    token?: string;
+    auth_ref?: string;
+}
+interface CanonicalSourceCreateResult {
+    source_id: string;
+    status: "queued" | "indexing" | "ready" | "failed";
+    job_id: string | null;
+    index_started: boolean;
+    warnings: string[];
+}
 interface Memory {
     id: string;
     projectId: string;
@@ -1139,6 +1204,23 @@ declare class WhisperContext {
         sync_schedule?: string;
     }): Promise<Source>;
     syncSource(sourceId: string): Promise<any>;
+    addSourceByType(projectId: string, params: {
+        type: "video";
+        url: string;
+        auto_sync?: boolean;
+        tags?: string[];
+        platform?: "youtube" | "loom" | "generic";
+        language?: string;
+        allow_stt_fallback?: boolean;
+        max_duration_minutes?: number;
+        name?: string;
+    }): Promise<{
+        source_id: string;
+        sync_job_id?: string | null;
+        status: "processing" | "queued" | "created";
+    }>;
+    getSourceStatus(sourceId: string): Promise<VideoIngestionStatus>;
+    createCanonicalSource(project: string, params: CanonicalSourceCreateParams): Promise<CanonicalSourceCreateResult>;
     ingest(projectId: string, documents: Array<{
         id?: string;
         title: string;
@@ -1299,6 +1381,9 @@ declare class WhisperContext {
         memories: any[];
         count: number;
     }>;
+    getMemory(memoryId: string): Promise<{
+        memory: any;
+    }>;
     getMemoryVersions(memoryId: string): Promise<{
         memory_id: string;
         versions: any[];
@@ -1539,8 +1624,25 @@ declare class WhisperContext {
             config: Record<string, any>;
             sync_schedule?: string;
         }) => Promise<Source>;
+        addSource: (projectId: string, params: {
+            type: "video";
+            url: string;
+            auto_sync?: boolean;
+            tags?: string[];
+            platform?: "youtube" | "loom" | "generic";
+            language?: string;
+            allow_stt_fallback?: boolean;
+            max_duration_minutes?: number;
+            name?: string;
+        }) => Promise<{
+            source_id: string;
+            sync_job_id?: string | null;
+            status: "processing" | "queued" | "created";
+        }>;
         sync: (sourceId: string) => Promise<any>;
         syncSource: (sourceId: string) => Promise<any>;
+        status: (sourceId: string) => Promise<VideoIngestionStatus>;
+        getStatus: (sourceId: string) => Promise<VideoIngestionStatus>;
     };
     readonly memory: {
         add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<{
@@ -1574,6 +1676,9 @@ declare class WhisperContext {
             memories: any[];
             count: number;
         }>;
+        get: (memoryId: string) => Promise<{
+            memory: any;
+        }>;
         getVersions: (memoryId: string) => Promise<{
             memory_id: string;
             versions: any[];
@@ -1679,4 +1784,4 @@ declare class WhisperContext {
     };
 }
 
-export { type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };

package/index.d.ts

@@ -324,6 +324,7 @@ declare class RuntimeClient {
     private readonly timeouts;
     private readonly diagnostics;
     private readonly inFlight;
+    private readonly sendApiKeyHeader;
     constructor(options: RuntimeClientOptions, diagnostics?: DiagnosticsStore);
     getDiagnosticsStore(): DiagnosticsStore;
     getCompatMode(): CompatMode;
@@ -332,6 +333,8 @@ declare class RuntimeClient {
     private shouldRetryStatus;
     private backoff;
     private runtimeName;
+    private apiKeyOnlyPrefixes;
+    private shouldAttachApiKeyHeader;
     private createRequestFingerprint;
     request<T>(options: RuntimeRequestOptions): Promise<RuntimeResponse<T>>;
     private performRequest;
@@ -496,6 +499,9 @@ declare class MemoryModule {
         memories: Array<Record<string, unknown>>;
         count: number;
     }>;
+    get(memoryId: string): Promise<{
+        memory: Record<string, unknown>;
+    }>;
     update(memoryId: string, params: {
         content: string;
         reasoning?: string;
@@ -654,6 +660,9 @@ declare class WhisperClient {
         add: (params: Parameters<MemoryModule["add"]>[0]) => Promise<MemoryWriteAck$1>;
         addBulk: (params: Parameters<MemoryModule["addBulk"]>[0]) => Promise<MemoryWriteAck$1>;
         search: (params: Parameters<MemoryModule["search"]>[0]) => Promise<MemorySearchResponse$1>;
+        get: (memoryId: string) => Promise<{
+            memory: Record<string, unknown>;
+        }>;
         getUserProfile: (params: Parameters<MemoryModule["getUserProfile"]>[0]) => ReturnType<MemoryModule["getUserProfile"]>;
         getSessionMemories: (params: Parameters<MemoryModule["getSessionMemories"]>[0]) => ReturnType<MemoryModule["getSessionMemories"]>;
         update: (memoryId: string, params: {
@@ -996,6 +1005,62 @@ interface Source {
     createdAt: string;
     updatedAt: string;
 }
+interface VideoSourceMetadata {
+    source_kind: "video";
+    video_url: string;
+    platform: "youtube" | "loom" | "generic";
+    duration_seconds?: number;
+    published_at?: string;
+    channel_or_author?: string;
+}
+interface VideoIngestionStatus {
+    source_id: string;
+    status: string;
+    stage: "extracting" | "transcribing" | "segmenting" | "enriching" | "indexing" | "completed" | "failed";
+    sync_job_id?: string | null;
+    progress?: {
+        current: number;
+        total: number;
+        message: string;
+    } | null;
+    duration_seconds?: number | null;
+    chunks_indexed?: number | null;
+    decisions_detected?: number | null;
+    entities_extracted?: string[];
+    last_error?: string | null;
+    updated_at?: string;
+}
+type CanonicalSourceType = "github" | "web" | "pdf" | "local" | "slack";
+interface CanonicalSourceCreateParams {
+    type: CanonicalSourceType;
+    name?: string;
+    auto_index?: boolean;
+    metadata?: Record<string, string>;
+    owner?: string;
+    repo?: string;
+    branch?: string;
+    paths?: string[];
+    url?: string;
+    crawl_depth?: number;
+    include_paths?: string[];
+    exclude_paths?: string[];
+    file_path?: string;
+    path?: string;
+    glob?: string;
+    max_files?: number;
+    workspace_id?: string;
+    channel_ids?: string[];
+    since?: string;
+    token?: string;
+    auth_ref?: string;
+}
+interface CanonicalSourceCreateResult {
+    source_id: string;
+    status: "queued" | "indexing" | "ready" | "failed";
+    job_id: string | null;
+    index_started: boolean;
+    warnings: string[];
+}
 interface Memory {
     id: string;
     projectId: string;
@@ -1139,6 +1204,23 @@ declare class WhisperContext {
         sync_schedule?: string;
     }): Promise<Source>;
     syncSource(sourceId: string): Promise<any>;
+    addSourceByType(projectId: string, params: {
+        type: "video";
+        url: string;
+        auto_sync?: boolean;
+        tags?: string[];
+        platform?: "youtube" | "loom" | "generic";
+        language?: string;
+        allow_stt_fallback?: boolean;
+        max_duration_minutes?: number;
+        name?: string;
+    }): Promise<{
+        source_id: string;
+        sync_job_id?: string | null;
+        status: "processing" | "queued" | "created";
+    }>;
+    getSourceStatus(sourceId: string): Promise<VideoIngestionStatus>;
+    createCanonicalSource(project: string, params: CanonicalSourceCreateParams): Promise<CanonicalSourceCreateResult>;
     ingest(projectId: string, documents: Array<{
         id?: string;
         title: string;
@@ -1299,6 +1381,9 @@ declare class WhisperContext {
         memories: any[];
         count: number;
     }>;
+    getMemory(memoryId: string): Promise<{
+        memory: any;
+    }>;
     getMemoryVersions(memoryId: string): Promise<{
         memory_id: string;
         versions: any[];
@@ -1539,8 +1624,25 @@ declare class WhisperContext {
             config: Record<string, any>;
             sync_schedule?: string;
         }) => Promise<Source>;
+        addSource: (projectId: string, params: {
+            type: "video";
+            url: string;
+            auto_sync?: boolean;
+            tags?: string[];
+            platform?: "youtube" | "loom" | "generic";
+            language?: string;
+            allow_stt_fallback?: boolean;
+            max_duration_minutes?: number;
+            name?: string;
+        }) => Promise<{
+            source_id: string;
+            sync_job_id?: string | null;
+            status: "processing" | "queued" | "created";
+        }>;
         sync: (sourceId: string) => Promise<any>;
         syncSource: (sourceId: string) => Promise<any>;
+        status: (sourceId: string) => Promise<VideoIngestionStatus>;
+        getStatus: (sourceId: string) => Promise<VideoIngestionStatus>;
     };
     readonly memory: {
         add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<{
@@ -1574,6 +1676,9 @@ declare class WhisperContext {
             memories: any[];
             count: number;
         }>;
+        get: (memoryId: string) => Promise<{
+            memory: any;
+        }>;
         getVersions: (memoryId: string) => Promise<{
             memory_id: string;
             versions: any[];
@@ -1679,4 +1784,4 @@ declare class WhisperContext {
     };
 }
 
-export { type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };

package/index.js

@@ -134,6 +134,7 @@ var DEFAULT_TIMEOUTS = {
   sessionMs: 2500
 };
 var DEFAULT_RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504];
+var DEFAULT_API_KEY_ONLY_PREFIXES = ["/v1/memory", "/v1/context/query"];
 var DEFAULT_RETRY_ATTEMPTS = {
   search: 3,
   writeAck: 2,
@@ -182,6 +183,7 @@ var RuntimeClient = class {
   timeouts;
   diagnostics;
   inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
   constructor(options, diagnostics) {
     if (!options.apiKey) {
       throw new RuntimeClientError({
@@ -205,6 +207,7 @@ var RuntimeClient = class {
       ...DEFAULT_TIMEOUTS,
       ...options.timeouts || {}
     };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
     this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
   }
   getDiagnosticsStore() {
@@ -248,6 +251,16 @@ var RuntimeClient = class {
     const maybeWindow = globalThis.window;
     return maybeWindow && typeof maybeWindow === "object" ? "browser" : "node";
   }
+  apiKeyOnlyPrefixes() {
+    const raw = process.env.WHISPER_API_KEY_ONLY_PREFIXES;
+    if (!raw || !raw.trim()) return DEFAULT_API_KEY_ONLY_PREFIXES;
+    return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  shouldAttachApiKeyHeader(endpoint) {
+    if (this.sendApiKeyHeader) return true;
+    const prefixes = this.apiKeyOnlyPrefixes();
+    return prefixes.some((prefix) => endpoint === prefix || endpoint.startsWith(`${prefix}/`));
+  }
   createRequestFingerprint(options) {
     const normalizedEndpoint = normalizeEndpoint(options.endpoint);
     const authFingerprint = stableHash(this.apiKey.replace(/^Bearer\s+/i, ""));
@@ -314,6 +327,7 @@ var RuntimeClient = class {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
         const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
           method,
           signal: controller.signal,
@@ -321,7 +335,7 @@ var RuntimeClient = class {
           headers: {
             "Content-Type": "application/json",
             Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
-            "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, ""),
+            ...attachApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
             "x-trace-id": traceId,
             "x-span-id": spanId,
             "x-sdk-version": this.sdkVersion,
@@ -1318,6 +1332,28 @@ var MemoryModule = class {
     });
     return response.data;
   }
+  async get(memoryId) {
+    try {
+      const response = await this.client.request({
+        endpoint: `/v1/memory/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return response.data;
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      const legacy = await this.client.request({
+        endpoint: `/v1/memories/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return legacy.data;
+    }
+  }
   async update(memoryId, params) {
     try {
       await this.client.request({
@@ -1672,6 +1708,7 @@ var WhisperClient = class _WhisperClient {
       add: (params) => this.memoryModule.add(params),
       addBulk: (params) => this.memoryModule.addBulk(params),
       search: (params) => this.memoryModule.search(params),
+      get: (memoryId) => this.memoryModule.get(memoryId),
       getUserProfile: (params) => this.memoryModule.getUserProfile(params),
       getSessionMemories: (params) => this.memoryModule.getSessionMemories(params),
       update: (memoryId, params) => this.memoryModule.update(memoryId, params),
@@ -2345,7 +2382,7 @@ var WhisperContext = class _WhisperContext {
     });
     warnDeprecatedOnce2(
       "whisper_context_class",
-      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+      "[Whisper SDK] WhisperContext is deprecated in v3 and scheduled for removal in v4. Prefer WhisperClient for runtime features and future contract compatibility."
     );
   }
   withProject(project) {
@@ -2589,6 +2626,69 @@ var WhisperContext = class _WhisperContext {
   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)
+    });
+  }
+  async getSourceStatus(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
+  }
+  async createCanonicalSource(project, params) {
+    const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
+    const config = {};
+    if (params.type === "github") {
+      if (!params.owner || !params.repo) throw new WhisperError({ code: "REQUEST_FAILED", message: "github source requires owner and repo" });
+      config.owner = params.owner;
+      config.repo = params.repo;
+      if (params.branch) config.branch = params.branch;
+      if (params.paths) config.paths = params.paths;
+    } else if (params.type === "web") {
+      if (!params.url) throw new WhisperError({ code: "REQUEST_FAILED", message: "web source requires url" });
+      config.url = params.url;
+      if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
+      if (params.include_paths) config.include_paths = params.include_paths;
+      if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
+    } else if (params.type === "pdf") {
+      if (!params.url && !params.file_path) throw new WhisperError({ code: "REQUEST_FAILED", message: "pdf source requires url or file_path" });
+      if (params.url) config.url = params.url;
+      if (params.file_path) config.file_path = params.file_path;
+    } else if (params.type === "local") {
+      if (!params.path) throw new WhisperError({ code: "REQUEST_FAILED", message: "local source requires path" });
+      config.path = params.path;
+      if (params.glob) config.glob = params.glob;
+      if (params.max_files !== void 0) config.max_files = params.max_files;
+    } else {
+      config.channel_ids = params.channel_ids || [];
+      if (params.since) config.since = params.since;
+      if (params.workspace_id) config.workspace_id = params.workspace_id;
+      if (params.token) config.token = params.token;
+      if (params.auth_ref) config.auth_ref = params.auth_ref;
+    }
+    if (params.metadata) config.metadata = params.metadata;
+    config.auto_index = params.auto_index ?? true;
+    const created = await this.addSource(project, {
+      name: params.name || `${params.type}-source-${Date.now()}`,
+      connector_type,
+      config
+    });
+    let status = "queued";
+    let jobId = null;
+    if (params.auto_index ?? true) {
+      const syncRes = await this.syncSource(created.id);
+      status = "indexing";
+      jobId = String(syncRes?.id || syncRes?.job_id || "");
+    }
+    return {
+      source_id: created.id,
+      status,
+      job_id: jobId,
+      index_started: params.auto_index ?? true,
+      warnings: []
+    };
+  }
   async ingest(projectId, documents) {
     const resolvedProjectId = await this.resolveProjectId(projectId);
     return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
@@ -2884,6 +2984,16 @@ var WhisperContext = class _WhisperContext {
       }
     });
   }
+  async getMemory(memoryId) {
+    try {
+      return await this.request(`/v1/memory/${memoryId}`);
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      return this.request(`/v1/memories/${memoryId}`);
+    }
+  }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
@@ -3066,8 +3176,11 @@ var WhisperContext = class _WhisperContext {
   };
   sources = {
     add: (projectId, params) => this.addSource(projectId, params),
+    addSource: (projectId, params) => this.addSourceByType(projectId, params),
     sync: (sourceId) => this.syncSource(sourceId),
-    syncSource: (sourceId) => this.syncSource(sourceId)
+    syncSource: (sourceId) => this.syncSource(sourceId),
+    status: (sourceId) => this.getSourceStatus(sourceId),
+    getStatus: (sourceId) => this.getSourceStatus(sourceId)
   };
   memory = {
     add: (params) => this.addMemory(params),
@@ -3079,6 +3192,7 @@ var WhisperContext = class _WhisperContext {
     ingestSession: (params) => this.ingestSession(params),
     getSessionMemories: (params) => this.getSessionMemories(params),
     getUserProfile: (params) => this.getUserProfile(params),
+    get: (memoryId) => this.getMemory(memoryId),
     getVersions: (memoryId) => this.getMemoryVersions(memoryId),
     update: (memoryId, params) => this.updateMemory(memoryId, params),
     delete: (memoryId) => this.deleteMemory(memoryId),

package/index.mjs

@@ -85,6 +85,7 @@ var DEFAULT_TIMEOUTS = {
   sessionMs: 2500
 };
 var DEFAULT_RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504];
+var DEFAULT_API_KEY_ONLY_PREFIXES = ["/v1/memory", "/v1/context/query"];
 var DEFAULT_RETRY_ATTEMPTS = {
   search: 3,
   writeAck: 2,
@@ -133,6 +134,7 @@ var RuntimeClient = class {
   timeouts;
   diagnostics;
   inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
   constructor(options, diagnostics) {
     if (!options.apiKey) {
       throw new RuntimeClientError({
@@ -156,6 +158,7 @@ var RuntimeClient = class {
       ...DEFAULT_TIMEOUTS,
       ...options.timeouts || {}
     };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
     this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
   }
   getDiagnosticsStore() {
@@ -199,6 +202,16 @@ var RuntimeClient = class {
     const maybeWindow = globalThis.window;
     return maybeWindow && typeof maybeWindow === "object" ? "browser" : "node";
   }
+  apiKeyOnlyPrefixes() {
+    const raw = process.env.WHISPER_API_KEY_ONLY_PREFIXES;
+    if (!raw || !raw.trim()) return DEFAULT_API_KEY_ONLY_PREFIXES;
+    return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  shouldAttachApiKeyHeader(endpoint) {
+    if (this.sendApiKeyHeader) return true;
+    const prefixes = this.apiKeyOnlyPrefixes();
+    return prefixes.some((prefix) => endpoint === prefix || endpoint.startsWith(`${prefix}/`));
+  }
   createRequestFingerprint(options) {
     const normalizedEndpoint = normalizeEndpoint(options.endpoint);
     const authFingerprint = stableHash(this.apiKey.replace(/^Bearer\s+/i, ""));
@@ -265,6 +278,7 @@ var RuntimeClient = class {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
         const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
           method,
           signal: controller.signal,
@@ -272,7 +286,7 @@ var RuntimeClient = class {
           headers: {
             "Content-Type": "application/json",
             Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
-            "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, ""),
+            ...attachApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
             "x-trace-id": traceId,
             "x-span-id": spanId,
             "x-sdk-version": this.sdkVersion,
@@ -1269,6 +1283,28 @@ var MemoryModule = class {
     });
     return response.data;
   }
+  async get(memoryId) {
+    try {
+      const response = await this.client.request({
+        endpoint: `/v1/memory/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return response.data;
+    } catch (error) {
+      if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
+        throw error;
+      }
+      const legacy = await this.client.request({
+        endpoint: `/v1/memories/${memoryId}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return legacy.data;
+    }
+  }
   async update(memoryId, params) {
     try {
       await this.client.request({
@@ -1623,6 +1659,7 @@ var WhisperClient = class _WhisperClient {
       add: (params) => this.memoryModule.add(params),
       addBulk: (params) => this.memoryModule.addBulk(params),
       search: (params) => this.memoryModule.search(params),
+      get: (memoryId) => this.memoryModule.get(memoryId),
       getUserProfile: (params) => this.memoryModule.getUserProfile(params),
       getSessionMemories: (params) => this.memoryModule.getSessionMemories(params),
       update: (memoryId, params) => this.memoryModule.update(memoryId, params),
@@ -2296,7 +2333,7 @@ var WhisperContext = class _WhisperContext {
     });
     warnDeprecatedOnce2(
       "whisper_context_class",
-      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+      "[Whisper SDK] WhisperContext is deprecated in v3 and scheduled for removal in v4. Prefer WhisperClient for runtime features and future contract compatibility."
     );
   }
   withProject(project) {
@@ -2540,6 +2577,69 @@ var WhisperContext = class _WhisperContext {
   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)
+    });
+  }
+  async getSourceStatus(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
+  }
+  async createCanonicalSource(project, params) {
+    const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
+    const config = {};
+    if (params.type === "github") {
+      if (!params.owner || !params.repo) throw new WhisperError({ code: "REQUEST_FAILED", message: "github source requires owner and repo" });
+      config.owner = params.owner;
+      config.repo = params.repo;
+      if (params.branch) config.branch = params.branch;
+      if (params.paths) config.paths = params.paths;
+    } else if (params.type === "web") {
+      if (!params.url) throw new WhisperError({ code: "REQUEST_FAILED", message: "web source requires url" });
+      config.url = params.url;
+      if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
+      if (params.include_paths) config.include_paths = params.include_paths;
+      if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
+    } else if (params.type === "pdf") {
+      if (!params.url && !params.file_path) throw new WhisperError({ code: "REQUEST_FAILED", message: "pdf source requires url or file_path" });
+      if (params.url) config.url = params.url;
+      if (params.file_path) config.file_path = params.file_path;
+    } else if (params.type === "local") {
+      if (!params.path) throw new WhisperError({ code: "REQUEST_FAILED", message: "local source requires path" });
+      config.path = params.path;
+      if (params.glob) config.glob = params.glob;
+      if (params.max_files !== void 0) config.max_files = params.max_files;
+    } else {
+      config.channel_ids = params.channel_ids || [];
+      if (params.since) config.since = params.since;
+      if (params.workspace_id) config.workspace_id = params.workspace_id;
+      if (params.token) config.token = params.token;
+      if (params.auth_ref) config.auth_ref = params.auth_ref;
+    }
+    if (params.metadata) config.metadata = params.metadata;
+    config.auto_index = params.auto_index ?? true;
+    const created = await this.addSource(project, {
+      name: params.name || `${params.type}-source-${Date.now()}`,
+      connector_type,
+      config
+    });
+    let status = "queued";
+    let jobId = null;
+    if (params.auto_index ?? true) {
+      const syncRes = await this.syncSource(created.id);
+      status = "indexing";
+      jobId = String(syncRes?.id || syncRes?.job_id || "");
+    }
+    return {
+      source_id: created.id,
+      status,
+      job_id: jobId,
+      index_started: params.auto_index ?? true,
+      warnings: []
+    };
+  }
   async ingest(projectId, documents) {
     const resolvedProjectId = await this.resolveProjectId(projectId);
     return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
@@ -2835,6 +2935,16 @@ var WhisperContext = class _WhisperContext {
       }
     });
   }
+  async getMemory(memoryId) {
+    try {
+      return await this.request(`/v1/memory/${memoryId}`);
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      return this.request(`/v1/memories/${memoryId}`);
+    }
+  }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
@@ -3017,8 +3127,11 @@ var WhisperContext = class _WhisperContext {
   };
   sources = {
     add: (projectId, params) => this.addSource(projectId, params),
+    addSource: (projectId, params) => this.addSourceByType(projectId, params),
     sync: (sourceId) => this.syncSource(sourceId),
-    syncSource: (sourceId) => this.syncSource(sourceId)
+    syncSource: (sourceId) => this.syncSource(sourceId),
+    status: (sourceId) => this.getSourceStatus(sourceId),
+    getStatus: (sourceId) => this.getSourceStatus(sourceId)
   };
   memory = {
     add: (params) => this.addMemory(params),
@@ -3030,6 +3143,7 @@ var WhisperContext = class _WhisperContext {
     ingestSession: (params) => this.ingestSession(params),
     getSessionMemories: (params) => this.getSessionMemories(params),
     getUserProfile: (params) => this.getUserProfile(params),
+    get: (memoryId) => this.getMemory(memoryId),
     getVersions: (memoryId) => this.getMemoryVersions(memoryId),
     update: (memoryId, params) => this.updateMemory(memoryId, params),
     delete: (memoryId) => this.deleteMemory(memoryId),

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@usewhisper/sdk",
-  "version": "3.0.0",
+  "version": "3.1.0",
+  "whisperContractVersion": "2026.03.09",
   "scripts": {
     "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
     "prepublishOnly": "npm run build"