@maximem/synap-js-sdk 0.4.2 → 0.4.4

package/dist/index.d.cts

@@ -245,7 +245,8 @@ interface HttpTransportOptions {
     credentials: Credentials;
     baseUrl?: string;
     timeouts?: Partial<TimeoutConfig>;
-    retryPolicy?: Partial<RetryPolicy>;
+    /** `null` disables retries entirely, as Python's `retry_policy=None` does. */
+    retryPolicy?: Partial<RetryPolicy> | null;
     keepAlive?: KeepAliveOptions & {
         heartbeatIntervalMs?: number;
     };
@@ -299,8 +300,27 @@ declare class HttpTransport {
     currentCredentials(): Credentials;
     /** Write back identity resolved from `GET /api/v1/auth/whoami`. */
     updateCredentials(patch: Partial<Credentials>): void;
+    /**
+     * The instance's scoping mode, from whoami. Lives here rather than on the
+     * client because every interface factory already receives the transport,
+     * and it is per-client, so a module-level global would be wrong the moment a
+     * process holds two clients.
+     *
+     * undefined means the server did not report it, which is true of any
+     * deployment older than the field, and must mean "enforce nothing".
+     */
+    userContextIsolation: string | undefined;
+    /** Refuse a customer_id on a B2C instance, at the call site. */
+    checkCustomerId(customerId: unknown, where: string): void;
     setTimeouts(timeouts: Partial<TimeoutConfig>): void;
-    /** `null` restores the default policy, matching Python's `retry_policy=None`. */
+    /**
+     * `null` DISABLES retries, matching Python.
+     *
+     * Python's `SDKConfig(retry_policy=None)` leaves `self.retry_policy` unset and
+     * `max_attempts` falls to 1 (http_client.py:180). We restored the default
+     * policy instead, so a caller following the "Disabling Retries" documentation
+     * got three attempts and no way to turn them off.
+     */
     setRetryPolicy(policy: Partial<RetryPolicy> | null): void;
     close(): void;
     request<T = unknown>(name: EndpointName, options?: RequestOptions): Promise<T>;
@@ -477,6 +497,23 @@ interface FetchOptions {
     precisionLevel?: string;
     /** Sent only when explicitly false, matching the Python controllers. */
     include_conversation_context?: boolean;
+    /**
+     * `"in-conversation"` (default) or `"conversation-summary"`.
+     *
+     * Summary mode returns a caller profile plus previous-conversation
+     * summaries. USER SCOPE ONLY: the other three routes reject it with 422.
+     */
+    context_mode?: string;
+    contextMode?: string;
+    /** Summary mode only. Include the caller profile. */
+    include_profile?: boolean;
+    includeProfile?: boolean;
+    /** Summary mode only. Previous conversations to summarise, 0 to 20. */
+    last_n_conversations?: number;
+    lastNConversations?: number;
+    /** Explicit scope ladder. Sent as `scope` when supplied. */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 
 /**
@@ -555,12 +592,37 @@ interface CreateMemoryOptions {
     mode?: IngestMode | string;
     metadata?: Json;
 }
+/**
+ * Mirrors Python's `CreateMemoryResponse`.
+ *
+ * The first four fields are required there (Pydantic would raise if the server
+ * omitted one), so they are required here too. Declaring `ingestion_id` optional
+ * made the commonest two-line pattern in the docs fail to compile under strict
+ * TypeScript: `wait_for_completion(result.ingestion_id)` cannot take
+ * `string | undefined`.
+ */
 interface CreateMemoryResult {
-    ingestion_id?: string;
-    status?: string;
+    ingestion_id: string;
+    document_id: string;
+    status: string;
+    /** ISO-8601. Python types this as a datetime. */
+    queued_at: string;
+    error_message?: string | null;
     memories_created?: number;
     [key: string]: unknown;
 }
+/**
+ * Result of `memories.batch_create`, mirroring Python's `BatchCreateResponse`.
+ * It was `Json`, so `results` came back as `unknown` and could not be iterated.
+ */
+interface BatchCreateResult {
+    batch_id: string;
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: CreateMemoryResult[];
+    [key: string]: unknown;
+}
 interface BatchCreateOptions {
     documents: CreateMemoryOptions[];
     fail_fast?: boolean;
@@ -568,7 +630,7 @@ interface BatchCreateOptions {
 }
 interface MemoriesInterface {
     create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
-    batch_create(options: BatchCreateOptions): Promise<Json>;
+    batch_create(options: BatchCreateOptions): Promise<BatchCreateResult>;
     create_from_file(options: CreateFromFileOptions): Promise<CreateMemoryResult>;
     get(memoryId: string): Promise<Json>;
     update(options: UpdateMemoryOptions): Promise<Json>;
@@ -664,20 +726,45 @@ interface IngestTranscriptOptions {
     ended_at?: string | Date;
     endedAt?: string | Date;
 }
+/**
+ * Compaction levels, mirroring Python's `CompactionLevel` enum. The JS SDK
+ * exported no equivalent, so `compaction_level` was an untyped `string` and a
+ * typo reached the server instead of the compiler.
+ */
+declare const COMPACTION_LEVELS: readonly ["low", "medium", "high", "adaptive", "aggressive", "balanced", "conservative"];
+type CompactionLevel = (typeof COMPACTION_LEVELS)[number];
 interface CompactOptions {
     conversation_id?: string;
     conversationId?: string;
     strategy?: string;
-    compaction_level?: string;
-    compactionLevel?: string;
+    compaction_level?: CompactionLevel | string;
+    compactionLevel?: CompactionLevel | string;
     target_tokens?: number;
     targetTokens?: number;
     force?: boolean;
 }
+/**
+ * Result of `conversation.ingest_transcript`, mirroring Python's
+ * `TranscriptIngestResponse`. It was `Json` here, so `ingestion_id` came back
+ * as `unknown` and could not be handed to `wait_for_completion` without a cast.
+ */
+interface TranscriptIngestResult {
+    conversation_id: string;
+    /** The raw client-supplied id, echoed back. */
+    external_conversation_id: string;
+    /** Always set on a 2xx, including the `duplicate` branch. */
+    ingestion_id: string;
+    status: 'queued' | 'duplicate';
+    turns_recorded: number;
+    summary_status: 'in_progress' | 'already_compacted' | 'skipped';
+    /** ISO-8601. */
+    queued_at: string;
+    [key: string]: unknown;
+}
 interface ConversationNamespace {
     record_message(options: RecordMessageOptions): Promise<Json>;
     record_messages_batch(messages: RecordMessageOptions[]): Promise<Json>;
-    ingest_transcript(options: IngestTranscriptOptions): Promise<Json>;
+    ingest_transcript(options: IngestTranscriptOptions): Promise<TranscriptIngestResult>;
     context: {
         fetch(options?: FetchOptions): Promise<RawContext>;
         get_context_for_prompt(options?: {
@@ -750,13 +837,71 @@ interface EstimateOptions {
     mode?: string;
 }
 interface CreditsNamespace {
-    get_balance(): Promise<Json>;
-    get_ledger(options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<Json>;
-    estimate(options: EstimateOptions): Promise<Json>;
-    redeem(code: string): Promise<Json>;
+    get_balance(): Promise<CreditBalance>;
+    get_ledger(options?: LedgerOptions): Promise<CreditLedgerPage>;
+    estimate(options: EstimateOptions): Promise<CreditEstimate>;
+    redeem(code: string): Promise<RedeemResult>;
+}
+/**
+ * Return types for the credits namespace, mirroring Python's dataclasses in
+ * `maximem_synap/credits.py`. These were all `Json` (`Record<string, unknown>`)
+ * before, so every field read was `unknown` and no documented example compiled.
+ */
+interface CreditBucket {
+    source_type: string;
+    balance: number;
+    /** ISO-8601, or null when the bucket does not expire. */
+    expires_at: string | null;
+}
+interface CreditBalance {
+    client_id: string;
+    balance_credits: number;
+    warning_low: boolean;
+    buckets: CreditBucket[];
+    [key: string]: unknown;
+}
+interface CreditLedgerEntry {
+    ledger_id: string;
+    entry_type: string;
+    delta: number;
+    metric_type: string | null;
+    category: string | null;
+    /** ISO-8601. */
+    created_at: string;
+}
+interface CreditLedgerPage {
+    entries: CreditLedgerEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+    [key: string]: unknown;
+}
+interface CreditEstimate {
+    credits_estimate: number;
+    [key: string]: unknown;
+}
+interface RedeemResult {
+    redemption_id: string;
+    credits_granted: number;
+    new_balance_credits: number;
+    /** ISO-8601, or null when the granted credits do not expire. */
+    expires_at: string | null;
+    [key: string]: unknown;
+}
+/** Options for `credits.get_ledger`. Mirrors Python's keyword arguments. */
+interface LedgerOptions {
+    /** Filter to one ledger entry type. */
+    entry_type?: string;
+    entryType?: string;
+    /** Inclusive lower bound. ISO-8601 string or Date. Sent as `from`. */
+    from_time?: string | Date;
+    fromTime?: string | Date;
+    /** Inclusive upper bound. ISO-8601 string or Date. Sent as `to`. */
+    to_time?: string | Date;
+    toTime?: string | Date;
+    /** Defaults to 100, as in Python. */
+    limit?: number;
+    offset?: number;
 }
 
 /**
@@ -826,6 +971,15 @@ interface SendMessageOptions {
     event_type?: string;
     eventType?: string;
     metadata?: Record<string, string>;
+    /**
+     * Report a tool call on the stream. Python's `send_message` takes both, and
+     * the proto has `tool_name` / `tool_args_json`; the JS surface simply never
+     * exposed them, so a tool call could not be reported from JavaScript.
+     */
+    tool_name?: string;
+    toolName?: string;
+    tool_args?: Record<string, unknown>;
+    toolArgs?: Record<string, unknown>;
     search_queries?: string[];
     searchQueries?: string[];
     context_types?: string[];
@@ -980,10 +1134,16 @@ type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
  */
 
 interface SynapClientOptions {
-    apiKey?: string;
-    clientId?: string;
-    instanceId?: string;
-    baseUrl?: string;
+    /**
+     * The four identity fields are `| undefined` rather than plain optional so a
+     * consumer with `exactOptionalPropertyTypes` can pass `process.env.X`
+     * directly, which is what every example does. Undefined already means "fall
+     * back to the environment" at runtime; this makes the type say so.
+     */
+    apiKey?: string | undefined;
+    clientId?: string | undefined;
+    instanceId?: string | undefined;
+    baseUrl?: string | undefined;
     timeouts?: HttpTransportOptions['timeouts'];
     retryPolicy?: HttpTransportOptions['retryPolicy'];
     keepAlive?: HttpTransportOptions['keepAlive'];
@@ -1289,9 +1449,15 @@ declare class InsufficientCreditsError extends SynapPermanentError {
     static readonly errorCode: SynapErrorCode;
     readonly balanceCredits: number | null;
     readonly requiredCredits: number | null;
+    /** Where the balance can be viewed. Python calls this `recovery_url`. */
+    readonly recoveryUrl: string | null;
+    /** Where a redeem code can be entered. Python calls this `redeem_url`. */
+    readonly redeemUrl: string | null;
     constructor(message: string, options?: SynapErrorOptions & {
         balanceCredits?: number | null;
         requiredCredits?: number | null;
+        recoveryUrl?: string | null;
+        redeemUrl?: string | null;
     });
 }
 declare class InvalidInputError extends SynapPermanentError {
@@ -1488,4 +1654,4 @@ interface SynapSdkLike {
     };
 }
 
-export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };

package/dist/index.d.ts

@@ -245,7 +245,8 @@ interface HttpTransportOptions {
     credentials: Credentials;
     baseUrl?: string;
     timeouts?: Partial<TimeoutConfig>;
-    retryPolicy?: Partial<RetryPolicy>;
+    /** `null` disables retries entirely, as Python's `retry_policy=None` does. */
+    retryPolicy?: Partial<RetryPolicy> | null;
     keepAlive?: KeepAliveOptions & {
         heartbeatIntervalMs?: number;
     };
@@ -299,8 +300,27 @@ declare class HttpTransport {
     currentCredentials(): Credentials;
     /** Write back identity resolved from `GET /api/v1/auth/whoami`. */
     updateCredentials(patch: Partial<Credentials>): void;
+    /**
+     * The instance's scoping mode, from whoami. Lives here rather than on the
+     * client because every interface factory already receives the transport,
+     * and it is per-client, so a module-level global would be wrong the moment a
+     * process holds two clients.
+     *
+     * undefined means the server did not report it, which is true of any
+     * deployment older than the field, and must mean "enforce nothing".
+     */
+    userContextIsolation: string | undefined;
+    /** Refuse a customer_id on a B2C instance, at the call site. */
+    checkCustomerId(customerId: unknown, where: string): void;
     setTimeouts(timeouts: Partial<TimeoutConfig>): void;
-    /** `null` restores the default policy, matching Python's `retry_policy=None`. */
+    /**
+     * `null` DISABLES retries, matching Python.
+     *
+     * Python's `SDKConfig(retry_policy=None)` leaves `self.retry_policy` unset and
+     * `max_attempts` falls to 1 (http_client.py:180). We restored the default
+     * policy instead, so a caller following the "Disabling Retries" documentation
+     * got three attempts and no way to turn them off.
+     */
     setRetryPolicy(policy: Partial<RetryPolicy> | null): void;
     close(): void;
     request<T = unknown>(name: EndpointName, options?: RequestOptions): Promise<T>;
@@ -477,6 +497,23 @@ interface FetchOptions {
     precisionLevel?: string;
     /** Sent only when explicitly false, matching the Python controllers. */
     include_conversation_context?: boolean;
+    /**
+     * `"in-conversation"` (default) or `"conversation-summary"`.
+     *
+     * Summary mode returns a caller profile plus previous-conversation
+     * summaries. USER SCOPE ONLY: the other three routes reject it with 422.
+     */
+    context_mode?: string;
+    contextMode?: string;
+    /** Summary mode only. Include the caller profile. */
+    include_profile?: boolean;
+    includeProfile?: boolean;
+    /** Summary mode only. Previous conversations to summarise, 0 to 20. */
+    last_n_conversations?: number;
+    lastNConversations?: number;
+    /** Explicit scope ladder. Sent as `scope` when supplied. */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 
 /**
@@ -555,12 +592,37 @@ interface CreateMemoryOptions {
     mode?: IngestMode | string;
     metadata?: Json;
 }
+/**
+ * Mirrors Python's `CreateMemoryResponse`.
+ *
+ * The first four fields are required there (Pydantic would raise if the server
+ * omitted one), so they are required here too. Declaring `ingestion_id` optional
+ * made the commonest two-line pattern in the docs fail to compile under strict
+ * TypeScript: `wait_for_completion(result.ingestion_id)` cannot take
+ * `string | undefined`.
+ */
 interface CreateMemoryResult {
-    ingestion_id?: string;
-    status?: string;
+    ingestion_id: string;
+    document_id: string;
+    status: string;
+    /** ISO-8601. Python types this as a datetime. */
+    queued_at: string;
+    error_message?: string | null;
     memories_created?: number;
     [key: string]: unknown;
 }
+/**
+ * Result of `memories.batch_create`, mirroring Python's `BatchCreateResponse`.
+ * It was `Json`, so `results` came back as `unknown` and could not be iterated.
+ */
+interface BatchCreateResult {
+    batch_id: string;
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: CreateMemoryResult[];
+    [key: string]: unknown;
+}
 interface BatchCreateOptions {
     documents: CreateMemoryOptions[];
     fail_fast?: boolean;
@@ -568,7 +630,7 @@ interface BatchCreateOptions {
 }
 interface MemoriesInterface {
     create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
-    batch_create(options: BatchCreateOptions): Promise<Json>;
+    batch_create(options: BatchCreateOptions): Promise<BatchCreateResult>;
     create_from_file(options: CreateFromFileOptions): Promise<CreateMemoryResult>;
     get(memoryId: string): Promise<Json>;
     update(options: UpdateMemoryOptions): Promise<Json>;
@@ -664,20 +726,45 @@ interface IngestTranscriptOptions {
     ended_at?: string | Date;
     endedAt?: string | Date;
 }
+/**
+ * Compaction levels, mirroring Python's `CompactionLevel` enum. The JS SDK
+ * exported no equivalent, so `compaction_level` was an untyped `string` and a
+ * typo reached the server instead of the compiler.
+ */
+declare const COMPACTION_LEVELS: readonly ["low", "medium", "high", "adaptive", "aggressive", "balanced", "conservative"];
+type CompactionLevel = (typeof COMPACTION_LEVELS)[number];
 interface CompactOptions {
     conversation_id?: string;
     conversationId?: string;
     strategy?: string;
-    compaction_level?: string;
-    compactionLevel?: string;
+    compaction_level?: CompactionLevel | string;
+    compactionLevel?: CompactionLevel | string;
     target_tokens?: number;
     targetTokens?: number;
     force?: boolean;
 }
+/**
+ * Result of `conversation.ingest_transcript`, mirroring Python's
+ * `TranscriptIngestResponse`. It was `Json` here, so `ingestion_id` came back
+ * as `unknown` and could not be handed to `wait_for_completion` without a cast.
+ */
+interface TranscriptIngestResult {
+    conversation_id: string;
+    /** The raw client-supplied id, echoed back. */
+    external_conversation_id: string;
+    /** Always set on a 2xx, including the `duplicate` branch. */
+    ingestion_id: string;
+    status: 'queued' | 'duplicate';
+    turns_recorded: number;
+    summary_status: 'in_progress' | 'already_compacted' | 'skipped';
+    /** ISO-8601. */
+    queued_at: string;
+    [key: string]: unknown;
+}
 interface ConversationNamespace {
     record_message(options: RecordMessageOptions): Promise<Json>;
     record_messages_batch(messages: RecordMessageOptions[]): Promise<Json>;
-    ingest_transcript(options: IngestTranscriptOptions): Promise<Json>;
+    ingest_transcript(options: IngestTranscriptOptions): Promise<TranscriptIngestResult>;
     context: {
         fetch(options?: FetchOptions): Promise<RawContext>;
         get_context_for_prompt(options?: {
@@ -750,13 +837,71 @@ interface EstimateOptions {
     mode?: string;
 }
 interface CreditsNamespace {
-    get_balance(): Promise<Json>;
-    get_ledger(options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<Json>;
-    estimate(options: EstimateOptions): Promise<Json>;
-    redeem(code: string): Promise<Json>;
+    get_balance(): Promise<CreditBalance>;
+    get_ledger(options?: LedgerOptions): Promise<CreditLedgerPage>;
+    estimate(options: EstimateOptions): Promise<CreditEstimate>;
+    redeem(code: string): Promise<RedeemResult>;
+}
+/**
+ * Return types for the credits namespace, mirroring Python's dataclasses in
+ * `maximem_synap/credits.py`. These were all `Json` (`Record<string, unknown>`)
+ * before, so every field read was `unknown` and no documented example compiled.
+ */
+interface CreditBucket {
+    source_type: string;
+    balance: number;
+    /** ISO-8601, or null when the bucket does not expire. */
+    expires_at: string | null;
+}
+interface CreditBalance {
+    client_id: string;
+    balance_credits: number;
+    warning_low: boolean;
+    buckets: CreditBucket[];
+    [key: string]: unknown;
+}
+interface CreditLedgerEntry {
+    ledger_id: string;
+    entry_type: string;
+    delta: number;
+    metric_type: string | null;
+    category: string | null;
+    /** ISO-8601. */
+    created_at: string;
+}
+interface CreditLedgerPage {
+    entries: CreditLedgerEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+    [key: string]: unknown;
+}
+interface CreditEstimate {
+    credits_estimate: number;
+    [key: string]: unknown;
+}
+interface RedeemResult {
+    redemption_id: string;
+    credits_granted: number;
+    new_balance_credits: number;
+    /** ISO-8601, or null when the granted credits do not expire. */
+    expires_at: string | null;
+    [key: string]: unknown;
+}
+/** Options for `credits.get_ledger`. Mirrors Python's keyword arguments. */
+interface LedgerOptions {
+    /** Filter to one ledger entry type. */
+    entry_type?: string;
+    entryType?: string;
+    /** Inclusive lower bound. ISO-8601 string or Date. Sent as `from`. */
+    from_time?: string | Date;
+    fromTime?: string | Date;
+    /** Inclusive upper bound. ISO-8601 string or Date. Sent as `to`. */
+    to_time?: string | Date;
+    toTime?: string | Date;
+    /** Defaults to 100, as in Python. */
+    limit?: number;
+    offset?: number;
 }
 
 /**
@@ -826,6 +971,15 @@ interface SendMessageOptions {
     event_type?: string;
     eventType?: string;
     metadata?: Record<string, string>;
+    /**
+     * Report a tool call on the stream. Python's `send_message` takes both, and
+     * the proto has `tool_name` / `tool_args_json`; the JS surface simply never
+     * exposed them, so a tool call could not be reported from JavaScript.
+     */
+    tool_name?: string;
+    toolName?: string;
+    tool_args?: Record<string, unknown>;
+    toolArgs?: Record<string, unknown>;
     search_queries?: string[];
     searchQueries?: string[];
     context_types?: string[];
@@ -980,10 +1134,16 @@ type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
  */
 
 interface SynapClientOptions {
-    apiKey?: string;
-    clientId?: string;
-    instanceId?: string;
-    baseUrl?: string;
+    /**
+     * The four identity fields are `| undefined` rather than plain optional so a
+     * consumer with `exactOptionalPropertyTypes` can pass `process.env.X`
+     * directly, which is what every example does. Undefined already means "fall
+     * back to the environment" at runtime; this makes the type say so.
+     */
+    apiKey?: string | undefined;
+    clientId?: string | undefined;
+    instanceId?: string | undefined;
+    baseUrl?: string | undefined;
     timeouts?: HttpTransportOptions['timeouts'];
     retryPolicy?: HttpTransportOptions['retryPolicy'];
     keepAlive?: HttpTransportOptions['keepAlive'];
@@ -1289,9 +1449,15 @@ declare class InsufficientCreditsError extends SynapPermanentError {
     static readonly errorCode: SynapErrorCode;
     readonly balanceCredits: number | null;
     readonly requiredCredits: number | null;
+    /** Where the balance can be viewed. Python calls this `recovery_url`. */
+    readonly recoveryUrl: string | null;
+    /** Where a redeem code can be entered. Python calls this `redeem_url`. */
+    readonly redeemUrl: string | null;
     constructor(message: string, options?: SynapErrorOptions & {
         balanceCredits?: number | null;
         requiredCredits?: number | null;
+        recoveryUrl?: string | null;
+        redeemUrl?: string | null;
     });
 }
 declare class InvalidInputError extends SynapPermanentError {
@@ -1488,4 +1654,4 @@ interface SynapSdkLike {
     };
 }
 
-export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };