@maximem/synap-js-sdk 0.4.3 → 0.4.5

package/dist/index.d.ts

@@ -234,6 +234,12 @@ interface TimeoutConfig {
     connect: number;
     read: number;
     write: number;
+    /**
+     * gRPC stream idle timeout. Not used by the HTTP transport; the stream
+     * client reads it. Present so a config object round-trips between the two
+     * SDKs, and because Python's TimeoutConfig has it.
+     */
+    streamIdle: number;
 }
 declare const DEFAULT_TIMEOUTS: TimeoutConfig;
 interface Credentials {
@@ -245,7 +251,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;
     };
@@ -312,7 +319,14 @@ declare class HttpTransport {
     /** 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>;
@@ -489,6 +503,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>;
 }
 
 /**
@@ -567,12 +598,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;
@@ -580,7 +636,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>;
@@ -676,20 +732,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?: {
@@ -762,13 +843,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;
 }
 
 /**
@@ -838,6 +977,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[];
@@ -845,6 +993,16 @@ interface SendMessageOptions {
 }
 interface RecordThinkingOptions {
     content: string;
+    /**
+     * Ordinal of this thought within the current turn. Sent as a `step_index`
+     * metadata key, which is how Python's `record_thinking` transmits it: the
+     * proto has no dedicated field.
+     */
+    step_index?: number;
+    stepIndex?: number;
+    /** Free-form label for the kind of reasoning. Sent as `thought_type`. */
+    thought_type?: string;
+    thoughtType?: string;
     conversation_id?: string;
     conversationId?: string;
     user_id?: string;
@@ -991,11 +1149,30 @@ type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
  * They return different shapes on purpose. See gotcha G-B.
  */
 
+/** Levels the SDK emits. Mirrors the subset of Python's logging it uses. */
+type SynapLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Receives every diagnostic the SDK would otherwise write to the console.
+ *
+ * Python routes these through the stdlib `logging` module, which is why it
+ * takes `log_level` and `logger`. There is no global logger in JavaScript, so
+ * the SDK takes the sink directly instead of a level plus a framework.
+ */
+type SynapLogger = (level: SynapLogLevel, message: string) => void;
 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;
+    /** Python spells this `api_base_url`; both are accepted so one config
+     *  object works against either SDK. */
+    api_base_url?: string | undefined;
     timeouts?: HttpTransportOptions['timeouts'];
     retryPolicy?: HttpTransportOptions['retryPolicy'];
     keepAlive?: HttpTransportOptions['keepAlive'];
@@ -1007,6 +1184,29 @@ interface SynapClientOptions {
      */
     heartbeat?: boolean;
     fetchImpl?: typeof fetch;
+    /**
+     * Splice locally-recorded turns into the next conversation-scope fetch, so a
+     * just-written turn is visible before the server compacts. Defaults to true,
+     * matching Python's `st_verbatim_overlay`. `SYNAP_ST_VERBATIM_OVERLAY`
+     * overrides this either way.
+     */
+    st_verbatim_overlay?: boolean;
+    stVerbatimOverlay?: boolean;
+    /**
+     * Let the SDK answer `get_context_for_prompt` and `get_compacted` from its
+     * own short-term store when the conversation is warm, skipping the cloud
+     * round trip. Off by default. `SYNAP_SDK_ST_AUTHORITATIVE` also enables it.
+     *
+     * This is the COST switch. `st_verbatim_overlay` is the correctness one and
+     * is independent of it.
+     */
+    sdk_st_authoritative?: boolean;
+    sdkStAuthoritative?: boolean;
+    /**
+     * Where the SDK's diagnostics go. Defaults to `console.warn` prefixed with
+     * `[synap]`. Pass a no-op to silence them, or your own logger to route them.
+     */
+    logger?: SynapLogger;
     /**
      * Bypass the process registry and build a genuinely separate client.
      *
@@ -1040,8 +1240,8 @@ interface ConfigureOptions {
     session_timeout_minutes?: number;
     /** Accepted and ignored. Python-only. */
     log_level?: string;
-    /** Accepted and ignored. Python-only. */
-    logger?: unknown;
+    /** Replaces the diagnostic sink, same as the constructor option. */
+    logger?: SynapLogger;
 }
 /** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
 interface UnifiedFetchOptions {
@@ -1167,11 +1367,12 @@ declare class SynapClient {
      * initialization: the transport and cache are already built by then and a
      * half-applied config is worse than a rejected one.
      *
-     * The Python-only keys (`storage_path`, `cache_backend`,
-     * `session_timeout_minutes`, `logger`) are accepted and ignored rather than
-     * rejected, because this SDK has no SQLite cache backend and no global
-     * logger to swap. Ignoring them keeps a shared config object portable
-     * between the two SDKs.
+     * `logger` is honoured here as well as on the constructor. The remaining
+     * Python-only keys (`storage_path`, `cache_backend`,
+     * `session_timeout_minutes`, `log_level`) are accepted and ignored rather
+     * than rejected, because this SDK has no SQLite cache backend and no global
+     * logging framework whose level there would be to set. Ignoring them keeps
+     * a shared config object portable between the two SDKs.
      */
     configure(options?: ConfigureOptions): void;
     /**
@@ -1301,9 +1502,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 {
@@ -1500,4 +1707,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, type SynapLogLevel, type SynapLogger, 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 };