@usewhisper/sdk 3.0.0 → 3.2.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

@@ -215,6 +215,7 @@ interface RuntimeClientOptions {
     compatMode?: CompatMode;
     timeouts?: Partial<TimeoutBudgets>;
     retryPolicy?: RetryPolicy;
+    fetchImpl?: typeof fetch;
 }
 interface RuntimeResponse<T> {
     data: T;
@@ -324,6 +325,8 @@ declare class RuntimeClient {
     private readonly timeouts;
     private readonly diagnostics;
     private readonly inFlight;
+    private readonly sendApiKeyHeader;
+    private readonly fetchImpl;
     constructor(options: RuntimeClientOptions, diagnostics?: DiagnosticsStore);
     getDiagnosticsStore(): DiagnosticsStore;
     getCompatMode(): CompatMode;
@@ -332,6 +335,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;
@@ -411,11 +416,13 @@ interface MemoryWriteAck$1 {
     success: boolean;
     mode?: "async" | "sync";
     trace_id?: string;
+    memory_id?: string;
     job_id?: string;
     status_url?: string;
     accepted_at?: string;
     visibility_sla_ms?: number;
     pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
     queued?: boolean;
     event_id?: string;
     created?: number;
@@ -496,6 +503,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;
@@ -613,6 +623,7 @@ interface WhisperClientConfig {
     baseUrl?: string;
     project?: string;
     compatMode?: CompatMode;
+    fetch?: typeof fetch;
     timeouts?: Partial<TimeoutBudgets>;
     retryPolicy?: RetryPolicy;
     cache?: {
@@ -654,6 +665,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 +1010,65 @@ 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>;
+    ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+    strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+    profile_config?: Record<string, any>;
+    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;
@@ -1082,6 +1155,20 @@ interface MemoryWriteAck {
     pending_visibility?: boolean;
     [key: string]: any;
 }
+interface MemoryWriteResult {
+    id: string;
+    success: boolean;
+    path: "sota" | "legacy";
+    fallback_used: boolean;
+    mode?: "async" | "sync";
+    memory_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -1139,12 +1226,35 @@ 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;
+        ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+        strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+        profile_config?: Record<string, any>;
+    }): 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;
         content: string;
         metadata?: Record<string, any>;
         file_path?: string;
+        ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+        strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+        profile_config?: Record<string, any>;
     }>): Promise<{
         ingested: number;
     }>;
@@ -1169,12 +1279,7 @@ declare class WhisperContext {
         async?: boolean;
         write_mode?: "async" | "sync";
         allow_legacy_fallback?: boolean;
-    }): Promise<{
-        id: string;
-        success: boolean;
-        path: "sota" | "legacy";
-        fallback_used: boolean;
-    }>;
+    }): Promise<MemoryWriteResult>;
     addMemoriesBulk(params: {
         project?: string;
         memories: Array<{
@@ -1299,6 +1404,9 @@ declare class WhisperContext {
         memories: any[];
         count: number;
     }>;
+    getMemory(memoryId: string): Promise<{
+        memory: any;
+    }>;
     getMemoryVersions(memoryId: string): Promise<{
         memory_id: string;
         versions: any[];
@@ -1539,16 +1647,28 @@ 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<{
-            id: string;
-            success: boolean;
-            path: "sota" | "legacy";
-            fallback_used: boolean;
-        }>;
+        add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<MemoryWriteResult>;
         addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
         extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
         extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
@@ -1574,6 +1694,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 +1802,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 MemoryWriteResult, 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

@@ -215,6 +215,7 @@ interface RuntimeClientOptions {
     compatMode?: CompatMode;
     timeouts?: Partial<TimeoutBudgets>;
     retryPolicy?: RetryPolicy;
+    fetchImpl?: typeof fetch;
 }
 interface RuntimeResponse<T> {
     data: T;
@@ -324,6 +325,8 @@ declare class RuntimeClient {
     private readonly timeouts;
     private readonly diagnostics;
     private readonly inFlight;
+    private readonly sendApiKeyHeader;
+    private readonly fetchImpl;
     constructor(options: RuntimeClientOptions, diagnostics?: DiagnosticsStore);
     getDiagnosticsStore(): DiagnosticsStore;
     getCompatMode(): CompatMode;
@@ -332,6 +335,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;
@@ -411,11 +416,13 @@ interface MemoryWriteAck$1 {
     success: boolean;
     mode?: "async" | "sync";
     trace_id?: string;
+    memory_id?: string;
     job_id?: string;
     status_url?: string;
     accepted_at?: string;
     visibility_sla_ms?: number;
     pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
     queued?: boolean;
     event_id?: string;
     created?: number;
@@ -496,6 +503,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;
@@ -613,6 +623,7 @@ interface WhisperClientConfig {
     baseUrl?: string;
     project?: string;
     compatMode?: CompatMode;
+    fetch?: typeof fetch;
     timeouts?: Partial<TimeoutBudgets>;
     retryPolicy?: RetryPolicy;
     cache?: {
@@ -654,6 +665,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 +1010,65 @@ 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>;
+    ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+    strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+    profile_config?: Record<string, any>;
+    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;
@@ -1082,6 +1155,20 @@ interface MemoryWriteAck {
     pending_visibility?: boolean;
     [key: string]: any;
 }
+interface MemoryWriteResult {
+    id: string;
+    success: boolean;
+    path: "sota" | "legacy";
+    fallback_used: boolean;
+    mode?: "async" | "sync";
+    memory_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -1139,12 +1226,35 @@ 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;
+        ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+        strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+        profile_config?: Record<string, any>;
+    }): 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;
         content: string;
         metadata?: Record<string, any>;
         file_path?: string;
+        ingestion_profile?: "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+        strategy_override?: "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+        profile_config?: Record<string, any>;
     }>): Promise<{
         ingested: number;
     }>;
@@ -1169,12 +1279,7 @@ declare class WhisperContext {
         async?: boolean;
         write_mode?: "async" | "sync";
         allow_legacy_fallback?: boolean;
-    }): Promise<{
-        id: string;
-        success: boolean;
-        path: "sota" | "legacy";
-        fallback_used: boolean;
-    }>;
+    }): Promise<MemoryWriteResult>;
     addMemoriesBulk(params: {
         project?: string;
         memories: Array<{
@@ -1299,6 +1404,9 @@ declare class WhisperContext {
         memories: any[];
         count: number;
     }>;
+    getMemory(memoryId: string): Promise<{
+        memory: any;
+    }>;
     getMemoryVersions(memoryId: string): Promise<{
         memory_id: string;
         versions: any[];
@@ -1539,16 +1647,28 @@ 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<{
-            id: string;
-            success: boolean;
-            path: "sota" | "legacy";
-            fallback_used: boolean;
-        }>;
+        add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<MemoryWriteResult>;
         addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
         extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
         extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
@@ -1574,6 +1694,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 +1802,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 MemoryWriteResult, 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,8 @@ var RuntimeClient = class {
   timeouts;
   diagnostics;
   inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
+  fetchImpl;
   constructor(options, diagnostics) {
     if (!options.apiKey) {
       throw new RuntimeClientError({
@@ -205,6 +208,8 @@ var RuntimeClient = class {
       ...DEFAULT_TIMEOUTS,
       ...options.timeouts || {}
     };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.fetchImpl = options.fetchImpl || fetch;
     this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
   }
   getDiagnosticsStore() {
@@ -248,6 +253,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,14 +329,15 @@ var RuntimeClient = class {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
+        const response = await this.fetchImpl(`${this.baseUrl}${normalizedEndpoint}`, {
           method,
           signal: controller.signal,
           keepalive: method !== "GET",
           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,
@@ -1023,7 +1039,7 @@ var MemoryModule = class {
   async add(params) {
     const project = this.resolveProject(params.project);
     const queueEnabled = this.options.queueEnabled !== false;
-    const useQueue = queueEnabled && params.write_mode !== "sync" && params.async !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
     if (useQueue) {
       const queued = await this.queue.enqueue({
         project,
@@ -1068,14 +1084,18 @@ var MemoryModule = class {
           metadata: params.metadata,
           document_date: params.document_date,
           event_date: params.event_date,
-          write_mode: "sync"
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
         }
       });
       this.invalidate(project, params.user_id, params.session_id);
       return {
         success: true,
         mode: "sync",
-        trace_id: response.traceId
+        trace_id: response.trace_id || response.traceId,
+        memory_id: response.memory_id || response.memory?.id,
+        semantic_status: response.semantic_status || response.memory?.semantic_status,
+        pending_visibility: Boolean(response.pending_visibility),
+        visibility_sla_ms: response.visibility_sla_ms
       };
     } catch (error) {
       if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
@@ -1113,7 +1133,7 @@ var MemoryModule = class {
       });
     }
     const queueEnabled = this.options.queueEnabled !== false;
-    const useQueue = queueEnabled && params.write_mode !== "sync" && params.async !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
     if (useQueue) {
       const queued = await Promise.all(
         params.memories.map(
@@ -1157,7 +1177,7 @@ var MemoryModule = class {
             ...memory,
             memory_type: toSotaType(memory.memory_type)
           })),
-          write_mode: "sync"
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
         }
       });
       for (const memory of params.memories) {
@@ -1318,6 +1338,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({
@@ -1568,7 +1610,8 @@ var WhisperClient = class _WhisperClient {
         baseUrl: config.baseUrl,
         compatMode: config.compatMode || "fallback",
         timeouts: config.timeouts,
-        retryPolicy: config.retryPolicy
+        retryPolicy: config.retryPolicy,
+        fetchImpl: config.fetch
       },
       this.diagnosticsStore
     );
@@ -1672,6 +1715,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 +2389,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 +2633,72 @@ 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;
+    if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
+    if (params.strategy_override) config.strategy_override = params.strategy_override;
+    if (params.profile_config) config.profile_config = params.profile_config;
+    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`, {
@@ -2649,15 +2759,42 @@ var WhisperContext = class _WhisperContext {
             importance: params.importance,
             metadata: params.metadata,
             async: params.async,
-            write_mode: params.write_mode
+            write_mode: params.write_mode || (params.async === true ? "async" : "sync")
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
+        const mode = direct?.mode === "async" ? "async" : direct?.mode === "sync" ? "sync" : void 0;
+        const memoryId = direct?.memory?.id || direct?.memory_id || (mode !== "async" ? direct?.id : void 0);
+        const jobId = direct?.job_id || (mode === "async" ? direct?.id : void 0);
+        const id2 = memoryId || jobId || "";
         if (id2) {
-          return { id: id2, success: true, path: "sota", fallback_used: false };
+          return {
+            id: id2,
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...memoryId ? { memory_id: memoryId } : {},
+            ...jobId ? { job_id: jobId } : {},
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {},
+            ...direct?.semantic_status ? { semantic_status: direct.semantic_status } : {}
+          };
         }
         if (direct?.success === true) {
-          return { id: "", success: true, path: "sota", fallback_used: false };
+          return {
+            id: "",
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {},
+            ...direct?.semantic_status ? { semantic_status: direct.semantic_status } : {}
+          };
         }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
@@ -2685,7 +2822,15 @@ var WhisperContext = class _WhisperContext {
           message: "Memory create succeeded but no memory id was returned by the API"
         });
       }
-      return { id, success: true, path: "legacy", fallback_used: true };
+      return {
+        id,
+        success: true,
+        path: "legacy",
+        fallback_used: true,
+        mode: "sync",
+        memory_id: id,
+        semantic_status: "ready"
+      };
     });
   }
   async addMemoriesBulk(params) {
@@ -2884,6 +3029,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 +3221,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 +3237,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,8 @@ var RuntimeClient = class {
   timeouts;
   diagnostics;
   inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
+  fetchImpl;
   constructor(options, diagnostics) {
     if (!options.apiKey) {
       throw new RuntimeClientError({
@@ -156,6 +159,8 @@ var RuntimeClient = class {
       ...DEFAULT_TIMEOUTS,
       ...options.timeouts || {}
     };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.fetchImpl = options.fetchImpl || fetch;
     this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
   }
   getDiagnosticsStore() {
@@ -199,6 +204,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,14 +280,15 @@ var RuntimeClient = class {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
+        const response = await this.fetchImpl(`${this.baseUrl}${normalizedEndpoint}`, {
           method,
           signal: controller.signal,
           keepalive: method !== "GET",
           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,
@@ -974,7 +990,7 @@ var MemoryModule = class {
   async add(params) {
     const project = this.resolveProject(params.project);
     const queueEnabled = this.options.queueEnabled !== false;
-    const useQueue = queueEnabled && params.write_mode !== "sync" && params.async !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
     if (useQueue) {
       const queued = await this.queue.enqueue({
         project,
@@ -1019,14 +1035,18 @@ var MemoryModule = class {
           metadata: params.metadata,
           document_date: params.document_date,
           event_date: params.event_date,
-          write_mode: "sync"
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
         }
       });
       this.invalidate(project, params.user_id, params.session_id);
       return {
         success: true,
         mode: "sync",
-        trace_id: response.traceId
+        trace_id: response.trace_id || response.traceId,
+        memory_id: response.memory_id || response.memory?.id,
+        semantic_status: response.semantic_status || response.memory?.semantic_status,
+        pending_visibility: Boolean(response.pending_visibility),
+        visibility_sla_ms: response.visibility_sla_ms
       };
     } catch (error) {
       if (this.client.getCompatMode() !== "fallback" || !isEndpointNotFound(error)) {
@@ -1064,7 +1084,7 @@ var MemoryModule = class {
       });
     }
     const queueEnabled = this.options.queueEnabled !== false;
-    const useQueue = queueEnabled && params.write_mode !== "sync" && params.async !== false;
+    const useQueue = queueEnabled && (params.write_mode === "async" || params.async === true);
     if (useQueue) {
       const queued = await Promise.all(
         params.memories.map(
@@ -1108,7 +1128,7 @@ var MemoryModule = class {
             ...memory,
             memory_type: toSotaType(memory.memory_type)
           })),
-          write_mode: "sync"
+          write_mode: params.write_mode === "async" || params.async === true ? "async" : "sync"
         }
       });
       for (const memory of params.memories) {
@@ -1269,6 +1289,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({
@@ -1519,7 +1561,8 @@ var WhisperClient = class _WhisperClient {
         baseUrl: config.baseUrl,
         compatMode: config.compatMode || "fallback",
         timeouts: config.timeouts,
-        retryPolicy: config.retryPolicy
+        retryPolicy: config.retryPolicy,
+        fetchImpl: config.fetch
       },
       this.diagnosticsStore
     );
@@ -1623,6 +1666,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 +2340,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 +2584,72 @@ 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;
+    if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
+    if (params.strategy_override) config.strategy_override = params.strategy_override;
+    if (params.profile_config) config.profile_config = params.profile_config;
+    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`, {
@@ -2600,15 +2710,42 @@ var WhisperContext = class _WhisperContext {
             importance: params.importance,
             metadata: params.metadata,
             async: params.async,
-            write_mode: params.write_mode
+            write_mode: params.write_mode || (params.async === true ? "async" : "sync")
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
+        const mode = direct?.mode === "async" ? "async" : direct?.mode === "sync" ? "sync" : void 0;
+        const memoryId = direct?.memory?.id || direct?.memory_id || (mode !== "async" ? direct?.id : void 0);
+        const jobId = direct?.job_id || (mode === "async" ? direct?.id : void 0);
+        const id2 = memoryId || jobId || "";
         if (id2) {
-          return { id: id2, success: true, path: "sota", fallback_used: false };
+          return {
+            id: id2,
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...memoryId ? { memory_id: memoryId } : {},
+            ...jobId ? { job_id: jobId } : {},
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {},
+            ...direct?.semantic_status ? { semantic_status: direct.semantic_status } : {}
+          };
         }
         if (direct?.success === true) {
-          return { id: "", success: true, path: "sota", fallback_used: false };
+          return {
+            id: "",
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {},
+            ...direct?.semantic_status ? { semantic_status: direct.semantic_status } : {}
+          };
         }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
@@ -2636,7 +2773,15 @@ var WhisperContext = class _WhisperContext {
           message: "Memory create succeeded but no memory id was returned by the API"
         });
       }
-      return { id, success: true, path: "legacy", fallback_used: true };
+      return {
+        id,
+        success: true,
+        path: "legacy",
+        fallback_used: true,
+        mode: "sync",
+        memory_id: id,
+        semantic_status: "ready"
+      };
     });
   }
   async addMemoriesBulk(params) {
@@ -2835,6 +2980,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 +3172,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 +3188,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.2.0",
+  "whisperContractVersion": "2026.03.09",
   "scripts": {
     "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
     "prepublishOnly": "npm run build"