@maximem/synap-js-sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,1477 @@
+import { a as AnticipationCacheSnapshot } from './anticipation-cache-BgkqcTPJ.js';
+export { b as ANY_SCOPE, A as AnticipationCache, c as AnticipationCacheOptions, B as BundleItem, C as ContextBundle, E as ExitReason, L as LookupParams, d as LookupResult, e as LookupTelemetry, S as SnapshotBundle, f as SnapshotItemPreview, g as SnapshotItemRecord } from './anticipation-cache-BgkqcTPJ.js';
+
+/**
+ * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
+ * Regenerate with synap/sdk/scripts/sync-contract.sh.
+ *
+ * The /api/v1 vs /v1 prefix split is intentional and load-bearing. See the
+ * contract file: normalising it 404s every affected call in production.
+ */
+interface EndpointSpec {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    readonly path: string;
+    /**
+     * Whether a retry after an ambiguous failure is safe.
+     *
+     * False here means a retry can double-ingest and therefore double-bill.
+     * See defect D / gotcha G-L in the migration plan.
+     */
+    readonly idempotent: boolean;
+}
+declare const ENDPOINTS: {
+    readonly whoami: {
+        readonly method: "GET";
+        readonly path: "/api/v1/auth/whoami";
+        readonly idempotent: true;
+    };
+    readonly memories_create: {
+        readonly method: "POST";
+        readonly path: "/api/v1/memories/create";
+        readonly idempotent: false;
+    };
+    readonly memories_batch: {
+        readonly method: "POST";
+        readonly path: "/api/v1/memories/batch";
+        readonly idempotent: false;
+    };
+    readonly memories_upload: {
+        readonly method: "POST";
+        readonly path: "/api/v1/memories/upload";
+        readonly idempotent: false;
+    };
+    readonly memories_status: {
+        readonly method: "GET";
+        readonly path: "/api/v1/memories/status/{ingestion_id}";
+        readonly idempotent: true;
+    };
+    readonly memories_get: {
+        readonly method: "GET";
+        readonly path: "/api/v1/memories/{memory_id}";
+        readonly idempotent: true;
+    };
+    readonly memories_update: {
+        readonly method: "PATCH";
+        readonly path: "/api/v1/memories/{memory_id}";
+        readonly idempotent: false;
+    };
+    readonly memories_delete: {
+        readonly method: "DELETE";
+        readonly path: "/api/v1/memories/{memory_id}";
+        readonly idempotent: true;
+    };
+    readonly context_fetch_user: {
+        readonly method: "POST";
+        readonly path: "/v1/context/user/fetch";
+        readonly idempotent: true;
+    };
+    readonly context_fetch_customer: {
+        readonly method: "POST";
+        readonly path: "/v1/context/customer/fetch";
+        readonly idempotent: true;
+    };
+    readonly context_fetch_client: {
+        readonly method: "POST";
+        readonly path: "/v1/context/client/fetch";
+        readonly idempotent: true;
+    };
+    readonly context_fetch_conversation: {
+        readonly method: "POST";
+        readonly path: "/v1/context/conversation/fetch";
+        readonly idempotent: true;
+    };
+    readonly context_for_prompt: {
+        readonly method: "GET";
+        readonly path: "/v1/conversations/{conversation_id}/context-for-prompt";
+        readonly idempotent: true;
+    };
+    readonly conversations_ingest: {
+        readonly method: "POST";
+        readonly path: "/v1/conversations/ingest";
+        readonly idempotent: false;
+    };
+    readonly conversations_messages: {
+        readonly method: "POST";
+        readonly path: "/v1/conversations/messages";
+        readonly idempotent: false;
+    };
+    readonly conversations_messages_batch: {
+        readonly method: "POST";
+        readonly path: "/v1/conversations/messages/batch";
+        readonly idempotent: false;
+    };
+    readonly conversations_compact: {
+        readonly method: "POST";
+        readonly path: "/v1/conversations/compact";
+        readonly idempotent: false;
+    };
+    readonly conversations_compacted: {
+        readonly method: "GET";
+        readonly path: "/v1/conversations/{conversation_id}/compacted";
+        readonly idempotent: true;
+    };
+    readonly conversations_compaction_status: {
+        readonly method: "GET";
+        readonly path: "/v1/conversations/{conversation_id}/compaction/status";
+        readonly idempotent: true;
+    };
+    readonly user_profile: {
+        readonly method: "GET";
+        readonly path: "/v1/users/{user_id}/profile";
+        readonly idempotent: true;
+    };
+    readonly credits_balance: {
+        readonly method: "GET";
+        readonly path: "/v1/credits/balance";
+        readonly idempotent: true;
+    };
+    readonly credits_ledger: {
+        readonly method: "GET";
+        readonly path: "/v1/credits/ledger";
+        readonly idempotent: true;
+    };
+    readonly credits_estimate: {
+        readonly method: "POST";
+        readonly path: "/v1/credits/estimate";
+        readonly idempotent: true;
+    };
+    readonly credits_redeem: {
+        readonly method: "POST";
+        readonly path: "/v1/credits/redeem";
+        readonly idempotent: false;
+    };
+    readonly telemetry_batch: {
+        readonly method: "POST";
+        readonly path: "/v1/telemetry/batch";
+        readonly idempotent: false;
+    };
+};
+type EndpointName = keyof typeof ENDPOINTS;
+/** Substitute `{placeholder}` segments. Values are URL-encoded.
+ *
+ * Encoding matters: an unencoded id containing `/` or `?` silently
+ * retargets the request at a different route.
+ */
+declare function resolvePath(name: EndpointName, params?: Readonly<Record<string, string | number>>): string;
+
+/**
+ * Retry policy, mirroring `maximem_synap/resilience/retry.py` plus the
+ * idempotency gate added there for defect D.
+ *
+ * ## Why idempotency is part of the retry decision
+ *
+ * The obvious retry rule is "retry transient errors". That rule double-bills.
+ *
+ * `POST /api/v1/memories/create` is metered ingestion. If the request reached
+ * the server, was processed, and the *response* was lost, a retry ingests the
+ * same content twice and bills for it twice. The client cannot tell that case
+ * apart from "the request never arrived" by looking at the error type alone.
+ *
+ * So retries are gated on two independent questions:
+ *
+ *   1. Is the error transient?          (worth retrying at all)
+ *   2. Is the outcome *knowable*?       (safe to retry a non-idempotent call)
+ *
+ * A connection error means the request provably never reached the application,
+ * so the outcome is known: nothing happened. A read timeout means the request
+ * may well have been processed. That is the ambiguous case, and for a
+ * non-idempotent method it is where we stop.
+ *
+ * The residual window -- server accepted the request, began processing, then
+ * died before responding -- cannot be closed from the client at all. Closing it
+ * requires a server-honoured idempotency key on the ingest route. Until that
+ * exists, this policy narrows the window rather than eliminating it.
+ */
+interface RetryPolicy {
+    maxAttempts: number;
+    /** Base delay in seconds. */
+    backoffBase: number;
+    /** Delay cap in seconds. */
+    backoffMax: number;
+    /** Randomise the delay to avoid a thundering herd. */
+    backoffJitter: boolean;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+interface RetryDecisionInput {
+    error: unknown;
+    /** 1-based. */
+    attempt: number;
+    policy: RetryPolicy;
+    method: string;
+    /**
+     * True when the request may have been processed by the server despite the
+     * error. Read timeouts and mid-flight disconnects are ambiguous; connection
+     * errors and definitive HTTP status responses are not.
+     */
+    outcomeUnknown: boolean;
+    /** Overrides idempotency for a route, e.g. a read-only POST. */
+    idempotent?: boolean;
+}
+interface RetryDecision {
+    retry: boolean;
+    /** Seconds to wait before the next attempt. */
+    delaySeconds: number;
+    reason: string;
+}
+declare function shouldRetry(input: RetryDecisionInput): RetryDecision;
+
+interface KeepAliveOptions {
+    keepAliveExpiryMs?: number;
+    maxConnections?: number;
+}
+
+/**
+ * Native HTTP transport.
+ *
+ * Port of `maximem_synap/transport/http_client.py`. Uses global `fetch` so the
+ * same code runs on Node, Edge, Workers and Bun, with an optional undici
+ * dispatcher on Node to restore Python's connection reuse (see keepalive.ts).
+ */
+
+declare const DEFAULT_BASE_URL = "https://synap-cloud-prod.maximem.ai";
+interface TimeoutConfig {
+    /** Seconds. Mirrors TimeoutConfig in the Python SDK. */
+    connect: number;
+    read: number;
+    write: number;
+}
+declare const DEFAULT_TIMEOUTS: TimeoutConfig;
+interface Credentials {
+    apiKey: string;
+    clientId: string;
+    instanceId: string;
+}
+interface HttpTransportOptions {
+    credentials: Credentials;
+    baseUrl?: string;
+    timeouts?: Partial<TimeoutConfig>;
+    retryPolicy?: Partial<RetryPolicy>;
+    keepAlive?: KeepAliveOptions & {
+        heartbeatIntervalMs?: number;
+    };
+    userAgent?: string;
+    /** Injected in tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+interface RequestOptions {
+    pathParams?: Record<string, string | number>;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Send `body` as-is instead of JSON-encoding it, and drop the JSON
+     * Content-Type so the runtime can set `multipart/form-data` with its own
+     * boundary. Setting Content-Type by hand for FormData produces a body the
+     * server cannot parse, because the boundary will not match.
+     */
+    rawBody?: boolean;
+    correlationId?: string;
+    /** Overrides the endpoint's declared idempotency. */
+    idempotent?: boolean;
+    signal?: AbortSignal;
+}
+declare class HttpTransport {
+    #private;
+    readonly baseUrl: string;
+    timeouts: TimeoutConfig;
+    retryPolicy: RetryPolicy;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    private readonly keepAliveOptions;
+    private readonly heartbeat;
+    private closed;
+    constructor(options: HttpTransportOptions);
+    /** Start keeping the connection warm. Opt-in: it is pointless in serverless. */
+    startHeartbeat(): void;
+    /**
+     * Release timers. Safe to call more than once.
+     *
+     * This is the supported shutdown path, deliberately explicit rather than
+     * hooked to `process.on('exit')`: those handlers leak a listener per client,
+     * never fire in Lambda, and `process` does not exist in Workers (gotcha G-I).
+     */
+    /**
+     * A COPY of the current credentials.
+     *
+     * A copy, not the live object: handing out the internal reference is how
+     * `client.transport.credentials.apiKey` became readable and mutable from
+     * outside in the first place.
+     */
+    currentCredentials(): Credentials;
+    /** Write back identity resolved from `GET /api/v1/auth/whoami`. */
+    updateCredentials(patch: Partial<Credentials>): void;
+    setTimeouts(timeouts: Partial<TimeoutConfig>): void;
+    /** `null` restores the default policy, matching Python's `retry_policy=None`. */
+    setRetryPolicy(policy: Partial<RetryPolicy> | null): void;
+    close(): void;
+    request<T = unknown>(name: EndpointName, options?: RequestOptions): Promise<T>;
+    private attempt;
+    private buildUrl;
+    private buildHeaders;
+    /** Unauthenticated and unmetered, exactly like the Python heartbeat. */
+    private pingHealth;
+}
+/**
+ * Whether the server may have processed the request despite this error.
+ *
+ * This is the input to the double-billing gate in retry.ts, so the bias is
+ * deliberate: anything we cannot positively rule out counts as ambiguous.
+ */
+declare function isOutcomeUnknown(error: unknown): boolean;
+
+/**
+ * Context shapes.
+ *
+ * There are deliberately TWO of these, and they are both live in production:
+ *
+ *  - **Raw snake_case** (`RawContext`), returned by the namespaced surface
+ *    (`client.user.context.fetch(...)`), which passes `result.context` through
+ *    untouched.
+ *  - **Normalised camelCase** (`NormalisedContext`), returned by the legacy
+ *    top-level methods (`client.fetchUserContext(...)`).
+ *
+ * Converging them would be a clean improvement and would also break one of the
+ * two sets of existing consumers, so it is a 2.0 change, not a port change.
+ * See gotcha G-B in the migration plan. Do not "tidy" this.
+ */
+type Json = Record<string, unknown>;
+interface RawContextItem {
+    id?: string;
+    item_id?: string;
+    content?: string;
+    confidence?: number;
+    source?: string;
+    extracted_at?: string | null;
+    metadata?: Json;
+    event_date?: string | null;
+    valid_until?: string | null;
+    temporal_category?: string | null;
+    temporal_confidence?: number;
+    [key: string]: unknown;
+}
+interface RawConversationContext {
+    summary?: string | null;
+    current_state?: Json;
+    current_state_json?: string;
+    key_extractions?: Json;
+    key_extractions_json?: string;
+    recent_turns?: unknown[];
+    compaction_id?: string | null;
+    compacted_at?: string | null;
+    conversation_id?: string | null;
+    [key: string]: unknown;
+}
+interface RawContext {
+    facts?: RawContextItem[];
+    preferences?: RawContextItem[];
+    episodes?: RawContextItem[];
+    emotions?: RawContextItem[];
+    temporal_events?: RawContextItem[];
+    conversation_context?: RawConversationContext | null;
+    metadata?: Json;
+    [key: string]: unknown;
+}
+interface TemporalFields {
+    eventDate: string | null;
+    validUntil: string | null;
+    temporalCategory: string | null;
+    temporalConfidence: number;
+}
+interface Fact extends TemporalFields {
+    id: string;
+    content: string;
+    confidence: number;
+    source: string;
+    extractedAt: string | null;
+    metadata: Json;
+}
+interface Preference extends TemporalFields {
+    id: string;
+    category: string;
+    content: string;
+    strength: number;
+    source: string;
+    extractedAt: string | null;
+    metadata: Json;
+}
+interface Episode extends TemporalFields {
+    id: string;
+    summary: string;
+    occurredAt: string | null;
+    significance: number;
+    participants: unknown[];
+    metadata: Json;
+}
+interface Emotion extends TemporalFields {
+    id: string;
+    emotionType: string;
+    intensity: number;
+    detectedAt: string | null;
+    context: string;
+    metadata: Json;
+}
+interface TemporalEvent {
+    id: string;
+    content: string;
+    eventDate: string | null;
+    validUntil: string | null;
+    /**
+     * Nullable despite the `''` default in the normaliser: `pickDefined` skips
+     * only `undefined`, so an explicit server `null` is preserved and the
+     * default never applies. The declared type follows the runtime, not the
+     * default.
+     */
+    temporalCategory: string | null;
+    temporalConfidence: number;
+    confidence: number;
+    source: string;
+    extractedAt: string | null;
+    metadata: Json;
+}
+interface ConversationContext {
+    summary: string | null;
+    currentState: Json;
+    keyExtractions: Json;
+    recentTurns: unknown[];
+    compactionId: string | null;
+    compactedAt: string | null;
+    conversationId: string | null;
+}
+interface ContextMetadata {
+    correlationId: string;
+    ttlSeconds: number;
+    source: string;
+    retrievedAt: string | null;
+    compactionApplied: boolean | null;
+}
+interface NormalisedContext {
+    facts: Fact[];
+    preferences: Preference[];
+    episodes: Episode[];
+    emotions: Emotion[];
+    temporalEvents: TemporalEvent[];
+    conversationContext: ConversationContext | null;
+    metadata: ContextMetadata;
+    rawResponse: Json;
+}
+/**
+ * Fetch options.
+ *
+ * Both spellings of every id are accepted. The removed wrapper did this
+ * (`pickDefined(args.user_id, args.userId)`) and callers depend on it, so
+ * rejecting one spelling would be a silent breaking change.
+ */
+interface FetchOptions {
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    search_query?: string[];
+    searchQuery?: string[];
+    max_results?: number;
+    maxResults?: number;
+    types?: string[];
+    mode?: string;
+    precision_level?: string;
+    precisionLevel?: string;
+    /** Sent only when explicitly false, matching the Python controllers. */
+    include_conversation_context?: boolean;
+}
+
+/**
+ * Flatten typed context collections into one memory list.
+ *
+ * A faithful port of `flatten_context_items` from the 0.3.x bridge, which is
+ * what `searchMemory` and `getMemories` returned. The per-type asymmetries are
+ * deliberate and are reproduced exactly:
+ *
+ *  - `memory` comes from a different field per type: fact/preference/temporal
+ *    event use `content`, episode uses `summary`, emotion uses `context`.
+ *  - `score` likewise: fact -> confidence, preference -> strength,
+ *    episode -> significance, emotion -> intensity, temporal event ->
+ *    temporal_confidence.
+ *  - **episode and emotion carry no `source` key at all.** The bridge simply
+ *    did not set one. Adding it would be an improvement and a shape change, so
+ *    it stays absent.
+ *  - Order is facts, preferences, episodes, emotions, temporal events.
+ */
+
+interface FlatMemory {
+    id: string;
+    memory: string;
+    score: number;
+    /** Absent for episodes and emotions, matching the 0.3.x bridge. */
+    source?: string;
+    metadata: Json;
+    context_type: 'fact' | 'preference' | 'episode' | 'emotion' | 'temporal_event';
+    event_date: string | null;
+    valid_until: string | null;
+    temporal_category: string | null;
+    temporal_confidence: number;
+}
+declare function flattenContextItems(context: RawContext): FlatMemory[];
+
+/**
+ * Memories namespace. Mirrors `maximem_synap.memories.interface.MemoriesInterface`.
+ *
+ * ## The request body is built the way Python builds it, on purpose
+ *
+ * Python constructs a pydantic `CreateMemoryRequest` and posts
+ * `model_dump(mode="json")`, which emits **every** field, nulls included, with
+ * defaults applied. It is tempting to omit unset keys instead and send a
+ * tidier body. Do not: the server sees a different request, and the difference
+ * that matters most is `document_type`.
+ *
+ * `document_type` defaults to `"ai-chat-conversation"`. Leaving it off is not
+ * neutral, because the extraction path is type-dependent and the
+ * `"document"` type extracts dramatically less from the same text. A body that
+ * merely looks cleaner is how you get "the JS SDK stores fewer memories than
+ * the Python one from identical input", which is slow and miserable to
+ * diagnose.
+ */
+
+/** Mirrors the Python DocumentType enum. */
+declare const DOCUMENT_TYPES: readonly ["ai-chat-conversation", "document", "email", "pdf", "image", "audio", "meeting-transcript"];
+type DocumentType = (typeof DOCUMENT_TYPES)[number];
+/** Mirrors the Python IngestMode enum. */
+declare const INGEST_MODES: readonly ["fast", "long-range"];
+type IngestMode = (typeof INGEST_MODES)[number];
+declare const DEFAULT_DOCUMENT_TYPE: DocumentType;
+declare const DEFAULT_INGEST_MODE: IngestMode;
+interface CreateMemoryOptions {
+    document: string;
+    user_id?: string | null;
+    userId?: string | null;
+    customer_id?: string | null;
+    customerId?: string | null;
+    document_type?: DocumentType | string;
+    documentType?: DocumentType | string;
+    document_id?: string | null;
+    documentId?: string | null;
+    /** ISO-8601 string or Date. Serialised the way Python serialises a datetime. */
+    document_created_at?: string | Date | null;
+    documentCreatedAt?: string | Date | null;
+    mode?: IngestMode | string;
+    metadata?: Json;
+}
+interface CreateMemoryResult {
+    ingestion_id?: string;
+    status?: string;
+    memories_created?: number;
+    [key: string]: unknown;
+}
+interface BatchCreateOptions {
+    documents: CreateMemoryOptions[];
+    fail_fast?: boolean;
+    failFast?: boolean;
+}
+interface MemoriesInterface {
+    create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
+    batch_create(options: BatchCreateOptions): Promise<Json>;
+    create_from_file(options: CreateFromFileOptions): Promise<CreateMemoryResult>;
+    get(memoryId: string): Promise<Json>;
+    update(options: UpdateMemoryOptions): Promise<Json>;
+    delete(memoryId: string): Promise<Json>;
+    status(ingestionId: string): Promise<Json>;
+    wait_for_completion(ingestionId: string, options?: WaitOptions): Promise<Json>;
+}
+/**
+ * Options for `create_from_file`.
+ *
+ * Exactly one of `file_path`, `file`, or `text` must be supplied, matching
+ * Python. `file_path` reads from disk and so is Node-only; `file` takes a
+ * Blob/File/Uint8Array and works anywhere, which is the portable route for
+ * Edge and Workers.
+ */
+interface CreateFromFileOptions {
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    /** "b2b" or "b2c". Defaults to "b2c", as in Python. */
+    relationship_type?: string;
+    relationshipType?: string;
+    /** Node-only: read this path from disk. Uses a lazy `node:fs` import. */
+    file_path?: string;
+    filePath?: string;
+    /** Portable alternative to `file_path`. Pass `filename` alongside a raw buffer. */
+    file?: Blob | Uint8Array | ArrayBuffer;
+    filename?: string;
+    /** Ingest raw text instead of a file. */
+    text?: string;
+    document_type?: string;
+    documentType?: string;
+    mode?: IngestMode | string;
+    metadata?: Json;
+}
+interface UpdateMemoryOptions {
+    memory_id?: string;
+    memoryId?: string;
+    document: string;
+    merge_strategy?: string;
+    mergeStrategy?: string;
+    document_type?: string;
+    documentType?: string;
+    metadata?: Json;
+}
+interface WaitOptions {
+    /** Seconds. Matches Python's default. */
+    timeout_seconds?: number;
+    timeoutSeconds?: number;
+    poll_interval_seconds?: number;
+    pollIntervalSeconds?: number;
+    signal?: AbortSignal;
+}
+
+/**
+ * Conversation namespace. Mirrors `ConversationInterface` and
+ * `ConversationContextInterface` in the Python SDK.
+ */
+
+interface RecordMessageOptions {
+    conversation_id?: string;
+    conversationId?: string;
+    role: string;
+    content: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Json;
+}
+interface TranscriptTurn {
+    role: string;
+    content: string;
+    [key: string]: unknown;
+}
+interface IngestTranscriptOptions {
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    transcript: string | TranscriptTurn[];
+    customer_id?: string;
+    customerId?: string;
+    conversation_type?: string;
+    conversationType?: string;
+    analysis?: Json;
+    metadata?: Json;
+    started_at?: string | Date;
+    startedAt?: string | Date;
+    ended_at?: string | Date;
+    endedAt?: string | Date;
+}
+interface CompactOptions {
+    conversation_id?: string;
+    conversationId?: string;
+    strategy?: string;
+    compaction_level?: string;
+    compactionLevel?: string;
+    target_tokens?: number;
+    targetTokens?: number;
+    force?: boolean;
+}
+interface ConversationNamespace {
+    record_message(options: RecordMessageOptions): Promise<Json>;
+    record_messages_batch(messages: RecordMessageOptions[]): Promise<Json>;
+    ingest_transcript(options: IngestTranscriptOptions): Promise<Json>;
+    context: {
+        fetch(options?: FetchOptions): Promise<RawContext>;
+        get_context_for_prompt(options?: {
+            conversation_id?: string;
+            conversationId?: string;
+            style?: string;
+        }): Promise<Json>;
+        compact(options: CompactOptions): Promise<Json>;
+        get_compacted(options: {
+            conversation_id?: string;
+            conversationId?: string;
+            version?: number;
+            format?: string;
+        }): Promise<Json | null>;
+        get_compaction_status(options: {
+            conversation_id?: string;
+            conversationId?: string;
+        } | string): Promise<Json>;
+        subscribe_to_compaction_updates(conversationId: string, callback: CompactionCallback): () => void;
+        unsubscribe_all_compaction_updates(conversationId?: string): number;
+    };
+}
+type CompactionCallback = (bundle: Json) => unknown;
+/**
+ * Called after a successful write with the ids that were written for.
+ *
+ * Backs `SYNAP_SDK_CACHE_INVALIDATE_ON_WRITE`. The cloud invalidates its own
+ * Redis caches on ingest, but that stops at the process boundary: without this
+ * the in-SDK anticipation cache keeps serving the pre-write view for the rest
+ * of its TTL. Python calls its equivalent from these same three write paths.
+ */
+type WriteInvalidator = (ids: {
+    userId?: string | undefined;
+    customerId?: string | undefined;
+}) => void;
+
+/** User namespace. Mirrors `UserInterface` in the Python SDK. */
+
+interface UserNamespace {
+    get_profile(options: {
+        user_id?: string;
+        userId?: string;
+        customer_id?: string;
+        customerId?: string;
+    } | string): Promise<Json>;
+    context: {
+        fetch(options?: FetchOptions): Promise<RawContext>;
+    };
+}
+
+/** Credits namespace. Mirrors `CreditsInterface` in the Python SDK. */
+
+interface EstimateOptions {
+    metric_type?: string;
+    metricType?: string;
+    units?: number;
+    item_count?: number;
+    itemCount?: number;
+    endpoint?: string;
+    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>;
+}
+
+/**
+ * Cache namespace. Mirrors `CacheInterface` in the Python SDK.
+ *
+ * This is a deliberately narrow facade over the AnticipationCache rather than
+ * the cache object itself. Exposing the instance directly leaked internals
+ * (`client.cache.now` was reachable) and gave JS a different surface from
+ * Python for no benefit. The cache is still reachable as
+ * `client.anticipationCache` for advanced use.
+ */
+
+interface CacheStats {
+    bundles: number;
+    items: number;
+    [key: string]: unknown;
+}
+interface CacheNamespace {
+    clear(): void;
+    clear_user(userId: string): void;
+    clear_customer(customerId: string): void;
+    stats(): CacheStats;
+}
+
+/**
+ * Instance namespace. Mirrors `InstanceInterface` in the Python SDK.
+ *
+ * Everything here rides the bidirectional gRPC Listen stream. The stream module
+ * is loaded through a lazy `import()` so that importing this SDK on Edge or in
+ * a Worker stays safe: grpc-js is built on `node:http2`/`node:net`/`node:tls`
+ * and a static import fails the BUILD there, not the call.
+ */
+
+interface ListenOptions {
+    /** Called with the attempt count each time the stream reconnects. */
+    on_reconnect?: (attempt: number) => void;
+    onReconnect?: (attempt: number) => void;
+    /** Called with a reason string when the stream drops. */
+    on_disconnect?: (reason: string) => void;
+    onDisconnect?: (reason: string) => void;
+    /**
+     * Called for every bundle that arrives. Bundles are ALSO stored in the
+     * anticipation cache automatically, so `fetch()` finds them without a round
+     * trip; this callback is for observing, not for wiring up storage.
+     */
+    on_context?: (bundle: Record<string, unknown>) => void;
+    onContext?: (bundle: Record<string, unknown>) => void;
+    /** Overrides `SYNAP_GRPC_HOST`. */
+    host?: string;
+    /** Overrides `SYNAP_GRPC_PORT`. */
+    port?: number;
+    /** Overrides `SYNAP_GRPC_USE_TLS`. Plaintext only makes sense against localhost. */
+    use_tls?: boolean;
+    useTls?: boolean;
+}
+interface SendMessageOptions {
+    content: string;
+    role?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    event_type?: string;
+    eventType?: string;
+    metadata?: Record<string, string>;
+    search_queries?: string[];
+    searchQueries?: string[];
+    context_types?: string[];
+    contextTypes?: string[];
+}
+interface RecordThinkingOptions {
+    content: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Record<string, string>;
+}
+interface InstanceNamespace {
+    listen(options?: ListenOptions): Promise<void>;
+    stop_listening(): Promise<void>;
+    send_message(options: SendMessageOptions): Promise<void>;
+    record_thinking(options: RecordThinkingOptions): Promise<void>;
+    /** Property, not a method, matching Python's InstanceInterface.is_listening. */
+    readonly is_listening: boolean;
+    /** Not in Python: lets the compaction subscriptions share this one stream. */
+    readonly _internal: InstanceInternals;
+}
+/** @internal Shared with the conversation namespace so both use one stream. */
+interface InstanceInternals {
+    onCompactionUpdate(conversationId: string, bundle: Record<string, unknown>): void;
+    setCompactionDispatcher(dispatch: (conversationId: string, bundle: Record<string, unknown>) => void): void;
+    isListening(): boolean;
+}
+
+/**
+ * Cross-scope merge + prompt formatting for `client.fetch()`.
+ *
+ * Ports Python's `UnifiedContextResponse.merge` and `format_for_prompt` from
+ * `models/context.py`. The formatted string is the part customers actually
+ * paste into a system prompt, so it is reproduced character for character:
+ * section order, the `- ` bullet, the `[scope: x]` / `strength: 0.8` bracket
+ * suffixes, the `## User Context` wrapper, and the blank-line joins. A
+ * cosmetic drift here shows up as a diff in every prompt a customer builds.
+ */
+
+/** The five item collections, in Python's iteration order. */
+declare const ITEM_COLLECTIONS: readonly ["facts", "preferences", "episodes", "emotions", "temporal_events"];
+type ItemCollection = (typeof ITEM_COLLECTIONS)[number];
+interface UnifiedContext {
+    facts: RawContextItem[];
+    preferences: RawContextItem[];
+    episodes: RawContextItem[];
+    emotions: RawContextItem[];
+    temporal_events: RawContextItem[];
+    /** item id -> the scope that supplied it. */
+    scope_map: Record<string, string>;
+    conversation_context: Json | null;
+    profile: Json | null;
+    conversations: Json[] | null;
+    formatted_context: string;
+    scopes_queried: string[];
+    total_items: number;
+    metadata: Json | null;
+}
+/**
+ * Merge per-scope responses, deduplicating by item id.
+ *
+ * First scope wins on a duplicate, so the caller's scope order is significant.
+ * An item with no usable id is kept rather than dropped: Python indexes
+ * `scope_map` by `item.id`, and a missing id there would collide every such
+ * item onto one key, so keeping-and-not-mapping is the closest faithful
+ * behaviour.
+ */
+declare function mergeScopeResults(scopeResults: ReadonlyArray<readonly [string, RawContext]>): UnifiedContext;
+interface FormatOptions {
+    includeScope?: boolean;
+    includeConversationContext?: boolean;
+}
+/**
+ * Render the merged context for prompt injection.
+ *
+ * Mirrors `UnifiedContextResponse.format_for_prompt`. Note the two different
+ * bracket styles: facts and episodes only ever carry `[scope: x]` appended
+ * directly, while preferences, emotions and temporal events build a joined
+ * extras list. That asymmetry is in Python and is preserved.
+ */
+declare function formatForPrompt(ctx: UnifiedContext, options?: FormatOptions): string;
+
+/**
+ * `client.as_tool(...)`: an LLM-ready tool definition for fetching context.
+ *
+ * Ports Python's `MaximemSynapSDK.as_tool` plus its three module helpers.
+ *
+ * The point of the helper is that the scope identifiers are CLOSED OVER rather
+ * than exposed in the JSON schema. The LLM chooses the query and the limits; it
+ * cannot choose whose memory to read. Handing the model a `user_id` parameter
+ * is how the per-user privacy filter gets dropped by accident, so the schema
+ * deliberately has no such field.
+ */
+
+type ToolScope = 'conversation' | 'user' | 'customer' | 'client' | 'unified';
+type ToolStyle = 'openai' | 'anthropic';
+interface AsToolOptions {
+    scope?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    name?: string;
+    description?: string;
+    style?: string;
+}
+type ToolHandler = (callArgs?: Json) => Promise<Json>;
+interface OpenAiToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Json;
+    };
+    handler: ToolHandler;
+}
+interface AnthropicToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Json;
+    handler: ToolHandler;
+}
+type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
+
+/**
+ * SynapClient: the public entry point.
+ *
+ * Exposes two surfaces, both live in production:
+ *
+ *  - **Namespaced, snake_case** (`client.user.context.fetch(...)`) is the
+ *    canonical surface and mirrors the Python SDK method for method. It
+ *    returns raw snake_case.
+ *  - **Top-level camelCase** (`client.fetchUserContext(...)`) is deprecated but
+ *    fully supported. It returns the normalised camelCase shape, and it exists
+ *    because the 0.3.x wrapper had it.
+ *
+ * They return different shapes on purpose. See gotcha G-B.
+ */
+
+interface SynapClientOptions {
+    apiKey?: string;
+    clientId?: string;
+    instanceId?: string;
+    baseUrl?: string;
+    timeouts?: HttpTransportOptions['timeouts'];
+    retryPolicy?: HttpTransportOptions['retryPolicy'];
+    keepAlive?: HttpTransportOptions['keepAlive'];
+    /**
+     * Keep the connection warm with a periodic /health ping.
+     *
+     * Off by default. A clear win for a long-lived process, pure waste in
+     * serverless where the container is frozen between requests anyway.
+     */
+    heartbeat?: boolean;
+    fetchImpl?: typeof fetch;
+}
+interface ScopedContext {
+    context: {
+        fetch: (options?: FetchOptions) => Promise<RawContext>;
+    };
+}
+/**
+ * Options for `configure()`.
+ *
+ * The Python-only keys are declared so a config object can be shared between
+ * the two SDKs without a type error. They are accepted and ignored: there is
+ * no SQLite cache backend and no global logger to replace here.
+ */
+interface ConfigureOptions {
+    timeouts?: HttpTransportOptions['timeouts'];
+    retryPolicy?: HttpTransportOptions['retryPolicy'] | null;
+    retry_policy?: HttpTransportOptions['retryPolicy'] | null;
+    /** Accepted and ignored. Python-only. */
+    storage_path?: string;
+    /** Accepted and ignored. Python-only. */
+    cache_backend?: string | null;
+    /** Accepted and ignored. Python-only. */
+    session_timeout_minutes?: number;
+    /** Accepted and ignored. Python-only. */
+    log_level?: string;
+    /** Accepted and ignored. Python-only. */
+    logger?: unknown;
+}
+/** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
+interface UnifiedFetchOptions {
+    conversation_id?: string;
+    user_id?: string;
+    customer_id?: string;
+    search_query?: string[];
+    max_results?: number;
+    types?: string[];
+    mode?: string;
+    precision_level?: string;
+    include_conversation_context?: boolean;
+    scopes?: string[];
+    include_scope_labels?: boolean;
+    context_mode?: string;
+    include_profile?: boolean;
+    last_n_conversations?: number;
+}
+declare class SynapClient {
+    #private;
+    readonly user: UserNamespace;
+    readonly customer: ScopedContext;
+    readonly client: ScopedContext;
+    readonly conversation: ConversationNamespace;
+    readonly memories: MemoriesInterface;
+    readonly credits: CreditsNamespace;
+    readonly cache: CacheNamespace;
+    readonly instance: InstanceNamespace;
+    constructor(options?: SynapClientOptions);
+    /** @deprecated Use `client.user.context.fetch()`. Note it returns raw snake_case. */
+    fetchUserContext(options?: FetchOptions): Promise<NormalisedContext>;
+    /** @deprecated Use `client.customer.context.fetch()`. */
+    fetchCustomerContext(options?: FetchOptions): Promise<NormalisedContext>;
+    /** @deprecated Use `client.client.context.fetch()`. */
+    fetchClientContext(options?: FetchOptions): Promise<NormalisedContext>;
+    /** @deprecated Use `client.conversation.context.get_context_for_prompt()`. */
+    getContextForPrompt(options?: {
+        conversationId?: string;
+        conversation_id?: string;
+        style?: string;
+    }): Promise<Json>;
+    /**
+     * @deprecated Use `client.user.context.fetch()` and read the typed collections.
+     *
+     * Flattens every context type into one list, exactly as the 0.3.x bridge did.
+     */
+    searchMemory(options: {
+        userId?: string;
+        user_id?: string;
+        customerId?: string;
+        customer_id?: string;
+        query: string;
+        maxResults?: number;
+        max_results?: number;
+        mode?: string;
+        conversationId?: string;
+        conversation_id?: string;
+        types?: string[];
+    }): Promise<{
+        results: FlatMemory[];
+        count: number;
+    }>;
+    /**
+     * @deprecated Use `client.user.context.fetch()` with an empty `search_query`.
+     *
+     * Note the default of 100, not 10: it matches the 0.3.x bridge.
+     */
+    getMemories(options: {
+        userId?: string;
+        user_id?: string;
+        customerId?: string;
+        customer_id?: string;
+        mode?: string;
+        conversationId?: string;
+        conversation_id?: string;
+        maxResults?: number;
+        max_results?: number;
+        types?: string[];
+    }): Promise<{
+        results: FlatMemory[];
+        count: number;
+    }>;
+    /** @deprecated Use `client.memories.create()`. */
+    addMemory(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
+    /**
+     * @deprecated Use `client.memories.delete(memoryId)`.
+     *
+     * The `{ userId }` form is gone: it relied on a process-local id list and so
+     * deleted nothing in serverless while reporting success (gotcha G-F).
+     */
+    deleteMemory(options: {
+        memoryId?: string;
+        memory_id?: string;
+    }): Promise<Json>;
+    /**
+     * Resolve `client_id` and `instance_id` from the API key.
+     *
+     * Mirrors Python's `initialize()`. Calling it is optional here (unlike
+     * Python, which raises "SDK not initialized" from `_ensure_initialized`)
+     * because every HTTP route authenticates on the API key alone. It matters
+     * for the anticipation cache: a bundle shared at client scope is filtered on
+     * `client_id`, and an empty one fails that filter for every bundle. That was
+     * a silent cache-scope bug in Python before whoami bootstrapping existed.
+     *
+     * Best-effort and idempotent. A whoami failure leaves whatever the
+     * constructor resolved and is not fatal.
+     */
+    initialize(): Promise<void>;
+    /**
+     * @deprecated Use `initialize()`, which is the Python name. `init()` was a
+     * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
+     * startup script keeps working.
+     */
+    init(): Promise<void>;
+    /** The resolved instance id. Empty until `initialize()` resolves it. */
+    get instance_id(): string;
+    /** The resolved client id. Empty until `initialize()` resolves it. */
+    get client_id(): string;
+    /**
+     * Update configuration before `initialize()`.
+     *
+     * Mirrors Python's `configure()`, including its refusal to reconfigure after
+     * 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.
+     */
+    configure(options?: ConfigureOptions): void;
+    /**
+     * Fetch and merge context across every scope with an identifier, in one call.
+     *
+     * Mirrors Python's `sdk.fetch()`. The three behaviours worth knowing:
+     *
+     *  - Scope fetches run in parallel and a FAILED scope is dropped with a
+     *    warning rather than failing the call, so partial context still gets
+     *    returned. The one exception is `InvalidInputError`: a bad request must
+     *    surface instead of degrading into a silently-empty context.
+     *  - `user_id` is threaded into the conversation-scope sub-fetch so the
+     *    anticipation cache can apply its per-user filter.
+     *  - The summary-mode parameters go ONLY to the user-scope sub-fetch. The
+     *    other three routes return 422 for `context_mode="conversation-summary"`,
+     *    and that rejection would be swallowed by the drop-failed-scope rule.
+     */
+    fetch(options?: UnifiedFetchOptions): Promise<UnifiedContext>;
+    /**
+     * An LLM-ready tool definition that fetches Synap context.
+     *
+     * Mirrors Python's `as_tool()`. The scope identifiers are closed over, so
+     * the model cannot choose whose memory to read.
+     */
+    as_tool(options?: AsToolOptions): ToolDefinition;
+    /**
+     * A read-only diagnostic view of the in-process anticipation cache.
+     *
+     * Mirrors Python's `anticipation_cache_snapshot()`. Returns the same
+     * snake_case shape, since this output gets logged and compared across SDKs.
+     */
+    anticipation_cache_snapshot(): AnticipationCacheSnapshot;
+    /** Release timers and connections. Safe to call more than once. */
+    shutdown(): Promise<void>;
+}
+
+/** Kept in sync with package.json by the release workflow. */
+declare const SDK_VERSION = "1.0.0-beta.0";
+
+/**
+ * Synap SDK error taxonomy.
+ *
+ * Mirrors `maximem_synap/models/errors.py` 1:1, including the four
+ * backward-compatibility aliases at the bottom. If you add an error to one
+ * SDK, add it to the other in the same change.
+ *
+ * ## Why every error carries a `.code`
+ *
+ * This package ships dual ESM + CJS. A consumer whose dependency graph pulls
+ * in both formats gets *two* copies of every class in this file, and then:
+ *
+ *     try { ... } catch (e) { if (e instanceof SynapError) { ... } }
+ *
+ * silently evaluates to `false` against the copy from the other format. Error
+ * handling stops working and nothing throws to tell you. `.code` is a plain
+ * string, so it is immune. Prefer it at package boundaries:
+ *
+ *     if (isSynapError(e) && e.code === 'rate_limit') { ... }
+ *
+ * `Symbol.hasInstance` is also wired up on the base class, so `instanceof`
+ * works across realms too -- but `.code` is the documented contract.
+ */
+/** Stable, format-independent discriminators. Never renumber or reuse. */
+type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
+interface SynapErrorOptions {
+    correlationId?: string | null;
+    cause?: unknown;
+}
+declare class SynapError extends Error {
+    /**
+     * The single declaration site for each subclass's code.
+     *
+     * It is `static` rather than a class field on purpose. Under
+     * `useDefineForClassFields` (the default at our ES2022 target) a class field
+     * is an *instance* property, so it is invisible from the constructor object.
+     * `Symbol.hasInstance` below only has the constructor to work with, so a
+     * field would leave it unable to tell `AuthenticationError` from
+     * `RateLimitError` -- it would report every Synap error as an instance of
+     * every other one.
+     */
+    static readonly errorCode: SynapErrorCode;
+    /** True for errors where a retry may succeed. Static for the same reason. */
+    static readonly isTransient: boolean;
+    /** Own, enumerable, so logs and JSON.stringify include it. */
+    readonly code: SynapErrorCode;
+    readonly correlationId: string | null;
+    readonly transient: boolean;
+    constructor(message: string, options?: SynapErrorOptions);
+    static [Symbol.hasInstance](instance: unknown): boolean;
+}
+/** Type guard that works across ESM/CJS copies and realms. */
+declare function isSynapError(e: unknown): e is SynapError;
+declare class SynapTransientError extends SynapError {
+    static readonly errorCode: SynapErrorCode;
+    static readonly isTransient: boolean;
+}
+declare class SynapPermanentError extends SynapError {
+    static readonly errorCode: SynapErrorCode;
+    static readonly isTransient: boolean;
+}
+declare class NetworkTimeoutError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class RateLimitError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, options?: SynapErrorOptions & {
+        retryAfterSeconds?: number | null;
+    });
+}
+declare class ServiceUnavailableError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class AgentUnavailableError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+    constructor(message?: string, options?: SynapErrorOptions);
+}
+/**
+ * The caller's credit wallet cannot cover this request.
+ *
+ * HTTP 402, and gRPC RESOURCE_EXHAUSTED with credit-related trailing metadata.
+ * Permanent by design: retrying without topping up burns quota and never
+ * succeeds. This is the error behind "the agent forgot" reports where retrieval
+ * silently returns nothing.
+ */
+declare class InsufficientCreditsError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+    readonly balanceCredits: number | null;
+    readonly requiredCredits: number | null;
+    constructor(message: string, options?: SynapErrorOptions & {
+        balanceCredits?: number | null;
+        requiredCredits?: number | null;
+    });
+}
+declare class InvalidInputError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+/**
+ * Raised by `validateInstanceId` before any network call, matching Python's
+ * `utils/validators.py`. The message text is identical in both SDKs.
+ */
+declare class InvalidInstanceIdError extends InvalidInputError {
+    static readonly errorCode: SynapErrorCode;
+}
+/** See the note on InvalidInstanceIdError. Raised by `validateConversationId`. */
+declare class InvalidConversationIdError extends InvalidInputError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class AuthenticationError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ContextNotFoundError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ConflictError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class TranscriptConflictError extends ConflictError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class SessionExpiredError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ListeningAlreadyActiveError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ListeningNotActiveError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare const SDKError: typeof SynapError;
+declare const TransientError: typeof SynapTransientError;
+declare const PermanentError: typeof SynapPermanentError;
+declare const ConnectionError: typeof NetworkTimeoutError;
+
+/**
+ * Scope-aware context fetching.
+ *
+ * Scopes are client > customer > user. `conversation_id` is NOT a tier: it
+ * groups turns within a scope. Passing it narrows an existing scope rather
+ * than selecting a different one.
+ */
+
+type Scope = 'user' | 'customer' | 'client' | 'conversation';
+
+/**
+ * BM25 scorer for the anticipation cache.
+ *
+ * A faithful port of `maximem_synap/cache/bm25.py`. Every tuned value comes
+ * from the shared behavior contract, so the two implementations cannot drift
+ * on parameters. What they *can* still drift on is arithmetic, which is what
+ * the shared conformance corpus is for.
+ */
+declare function stem(word: string): string;
+/** Tokenize, lowercase, remove stop words, and stem. Alias labels survive whole. */
+declare function tokenize(text: string | null | undefined): string[];
+/** Okapi BM25 scorer over a small in-memory corpus. */
+declare class BM25 {
+    static readonly IDF_FLOOR: number;
+    readonly k1: number;
+    readonly b: number;
+    readonly corpus: readonly (readonly string[])[];
+    readonly docCount: number;
+    readonly avgdl: number;
+    readonly docLens: readonly number[];
+    readonly idf: ReadonlyMap<string, number>;
+    constructor(corpus: readonly (readonly string[])[], k1?: number, b?: number);
+    score(queryTokens: readonly string[], docIdx: number): number;
+    scores(queryTokens: readonly string[]): number[];
+}
+
+/**
+ * Loader for the shared SDK behavior contract.
+ *
+ * The values here are tuned against measured eval failures and are shared,
+ * byte-identical, with the Python SDK. They live in data rather than code
+ * specifically so the two SDKs cannot drift. See
+ * `synap/sdk/CONTRACT/README.md`.
+ *
+ * `anticipation.json` is vendored into `src/` by
+ * `synap/sdk/scripts/sync-behavior.sh` and imported (not read from disk) so
+ * that the bundler inlines it. Reading it with `node:fs` at runtime would work
+ * in Node and break in every bundled target: Edge, Workers, and anything under
+ * webpack/turbopack, where `dist/` is rewritten and relative paths do not
+ * survive. It is the same failure mode as `@grpc/proto-loader` reading a
+ * `.proto` off disk (gotcha G-P).
+ */
+interface RecallPattern {
+    pattern: string;
+    flags: string;
+    note: string;
+}
+interface BehaviorContract {
+    version: number;
+    recall_bypass: {
+        note: string;
+        env_flag: string;
+        default: boolean;
+        patterns: RecallPattern[];
+    };
+    thresholds: {
+        bm25: {
+            value: number;
+            note: string;
+        };
+        novel_term: {
+            value: number;
+            note: string;
+        };
+        min_corpus_for_novel_gate: {
+            value: number;
+            note: string;
+        };
+        effective_floor: {
+            value: number;
+            note: string;
+        };
+        query_token_scale: {
+            value: number;
+            note: string;
+        };
+    };
+    coverage_gate: {
+        note: string;
+        env_flag: string;
+        default: number | null;
+        empty_query_coverage: number;
+    };
+    telemetry: {
+        rejected_items_cap: {
+            value: number;
+            note: string;
+        };
+        content_preview_chars: number;
+    };
+    bm25: {
+        k1: number;
+        b: number;
+        idf_floor: number;
+        min_token_len: number;
+        min_stem_len: number;
+        suffixes: string[];
+        stop_words: string[];
+        alias_token: {
+            pattern: string;
+            note: string;
+        };
+    };
+}
+declare const CONTRACT: BehaviorContract;
+declare const THRESHOLDS: {
+    readonly bm25: number;
+    readonly novelTerm: number;
+    readonly minCorpusForNovelGate: number;
+    /** Lower bound on the derived per-query threshold. */
+    readonly effectiveFloor: number;
+    /** Points of score allowed per query token when deriving the threshold. */
+    readonly queryTokenScale: number;
+};
+/** True when any query string looks like an explicit memory-recall ask. */
+declare function isRecallQuery(searchQuery: readonly (string | null | undefined)[] | null | undefined): boolean;
+
+/**
+ * @maximem/synap-js-sdk
+ *
+ * Native TypeScript SDK for Synap. No Python runtime required.
+ */
+
+/**
+ * The duck-typed contract the TS integrations rely on.
+ *
+ * `synap-mastra`, `synap-eve` and `synap-claude-agent-ts` each redeclare this
+ * shape locally today. Exporting it here means they can `import type` it
+ * instead, so a change to the client's surface breaks their build rather than
+ * their runtime.
+ */
+interface SynapSdkLike {
+    user: {
+        context: {
+            fetch: (options?: Record<string, unknown>) => Promise<unknown>;
+        };
+    };
+    customer: {
+        context: {
+            fetch: (options?: Record<string, unknown>) => Promise<unknown>;
+        };
+    };
+    client: {
+        context: {
+            fetch: (options?: Record<string, unknown>) => Promise<unknown>;
+        };
+    };
+    memories: {
+        create: (options: {
+            document: string;
+        } & Record<string, unknown>) => Promise<unknown>;
+    };
+}
+
+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 };