@niadra/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1441 @@
+/**
+ * The contract vocabulary. Every value here travels through the public API unchanged and
+ * never changes meaning within `/v1`, so the SDK mirrors it as string literal unions.
+ */
+/** What an event records: something said, something a system reported, or something an agent did. */
+type EventKind = "message" | "system_event" | "action";
+/** Who produced a turn. */
+type Speaker = "customer" | "ai_agent" | "human_agent" | "system";
+/** `internal` events (notes between agents, system traces) never reach a customer-facing view. */
+type Visibility = "public" | "internal";
+/** Subjects are people by default; accounts and partners are organizations. */
+type SubjectKind = "person" | "account" | "partner";
+/**
+ * How a handle identifies a subject. Scoped types (`wa_bsuid`, `system_id`, `gov_id_hmac`,
+ * `org_registry_hmac`) need `scope` so the same value in two namespaces never collides.
+ */
+type HandleType = "phone_e164" | "wa_id" | "wa_jid" | "wa_lid" | "wa_bsuid" | "email" | "gov_id_hmac" | "app_user_id" | "system_id" | "org_registry_hmac" | "email_domain" | "anon_id";
+/** How an `identify` call learned that several handles belong together. */
+type AssertionMethod = "explicit_identify" | "otp" | "login" | "system_import" | "same_event" | "co_occurrence" | "channel_rotation" | "accepted_suggestion" | "external_resolver" | "declared";
+/**
+ * Session verification level. `V0` is an unverified contact and `V4` the strongest proof;
+ * `no_customer` marks internal work with no customer on the other side.
+ */
+type Verification = "V0" | "V1" | "V2" | "V3" | "V4" | "no_customer";
+/** How a customer proved who they are in a `verify` call. */
+type VerifyMethod = "otp_whatsapp" | "otp_sms" | "login" | "kba" | "network_attestation" | "human_agent";
+/**
+ * Which read tier answered a `context()` call. `holdout` means the conversation fell in the
+ * control group: the pack is intentionally empty and the SDK treats it as a normal answer.
+ */
+type DeliveryPath = "t0" | "t1" | "t2" | "t3" | "t4" | "holdout" | "not_modified";
+/** Kinds of history items the navigation calls can filter on. */
+type HistoryItemKind = "episode" | "fact" | "open_item" | "action" | "system_event" | "object" | "trait";
+/**
+ * The shape of the pack. Channel views (`voice`, `chat`) size it for the medium; `account`
+ * and `partner` read an organization; `task:<name>` views serve internal agents.
+ */
+type View = "voice" | "chat" | "brief" | "full" | "custom" | "account" | "partner" | `task:${string}`;
+
+/**
+ * An identifier of a subject in some channel or system: a phone number, an e-mail address,
+ * a CRM id. Handles carry personal data, so the SDK only ever sends them in request bodies.
+ */
+interface Handle {
+    type: HandleType;
+    /** Up to 320 characters. Phones are E.164 (`+5511987654321`). */
+    value: string;
+    /**
+     * Namespace for scoped identifiers: the WhatsApp Business account for `wa_bsuid`, the
+     * system for `system_id`, the country for `gov_id_hmac`.
+     */
+    scope?: string | null;
+    /** Defaults to `person` on the server, except for organization-only handle types. */
+    subject_kind?: SubjectKind | null;
+}
+/** A business object in a system of record, such as `invoice` / `erp` / `0823`. */
+interface ObjectRef {
+    type: string;
+    namespace: string;
+    id: string;
+}
+/** A participant of an event other than the speaker, for example the account a person acts for. */
+interface Subject {
+    kind: SubjectKind;
+    role?: string | null;
+    /** Between 1 and 16 handles. */
+    handles: Handle[];
+}
+/** Whether a source is still sending. `silent` means it stopped, so the pack may be missing recent turns. */
+interface SourceCoverage {
+    source_id: string;
+    status: "ok" | "silent" | (string & {});
+    last_event_at?: string | null;
+}
+/** RFC 9457 problem details, as returned with `application/problem+json`. */
+interface Problem {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string | null;
+    /** Stable code from the versioned error catalog, such as `rate_limited` or `wrong_cell`. */
+    code: string;
+    request_id?: string | null;
+}
+
+/**
+ * Base class of every error the SDK produces. In the default fail-open mode these errors are
+ * logged and returned in results rather than thrown; with `strict: true` they are thrown.
+ */
+declare class NiadraError extends Error {
+    readonly name: string;
+}
+/** The client was built without a usable API key, or with an option the SDK cannot honour. */
+declare class NiadraConfigError extends NiadraError {
+    readonly name = "NiadraConfigError";
+}
+/** A request failed validation before it left the process. Nothing was sent. */
+declare class NiadraValidationError extends NiadraError {
+    readonly name = "NiadraValidationError";
+}
+/** The request did not finish within its time budget. */
+declare class NiadraTimeoutError extends NiadraError {
+    readonly timeoutMs: number;
+    readonly name = "NiadraTimeoutError";
+    constructor(timeoutMs: number);
+}
+/** The network call failed before an HTTP response arrived (DNS, TLS, reset connection). */
+declare class NiadraConnectionError extends NiadraError {
+    readonly name = "NiadraConnectionError";
+}
+/** The request was cancelled through the caller's `AbortSignal`. */
+declare class NiadraAbortError extends NiadraError {
+    readonly name = "NiadraAbortError";
+}
+/**
+ * The API answered with an error status. `code` comes from the problem document when the
+ * server sent one; `requestId` is what Niadra support needs to find the call.
+ */
+declare class NiadraAPIError extends NiadraError {
+    readonly name: string;
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    readonly problem: Problem | null;
+    /** How long the server asked callers to wait, from `Retry-After`, when it said so. */
+    readonly retryAfterMs: number | null;
+    constructor(status: number, problem: Problem | null, requestId: string | null, retryAfterMs?: number | null);
+}
+/** 401: the key is missing, malformed, rotated or revoked. */
+declare class NiadraAuthenticationError extends NiadraAPIError {
+    readonly name = "NiadraAuthenticationError";
+}
+/** 403: the key is valid but lacks the scope, or its source was cut off. */
+declare class NiadraPermissionError extends NiadraAPIError {
+    readonly name = "NiadraPermissionError";
+}
+/** 429: over the rate limit. Batches wait `retryAfterMs` before trying again. */
+declare class NiadraRateLimitError extends NiadraAPIError {
+    readonly name = "NiadraRateLimitError";
+}
+
+/** The read side: `POST /v1/context` and the history navigation calls. */
+
+/** The model that will read the pack, so the server can aim at its prompt-cache floor. */
+interface TargetModel {
+    provider: string;
+    model: string;
+}
+/** Body of `POST /v1/context`. Exactly one of `subject` or `object` is required. */
+interface ContextRequest {
+    subject?: Handle | null;
+    object?: ObjectRef | null;
+    /** The account or partner the person acts for. */
+    about?: Handle | null;
+    view?: View;
+    verification?: Verification;
+    conversation_id?: string | null;
+    task_id?: string | null;
+    query?: string | null;
+    delta?: boolean;
+    target?: TargetModel | null;
+    known_etag?: string | null;
+}
+interface VerificationResult {
+    requested: Verification;
+    effective: Verification;
+    /** Why `effective` is lower than `requested`: `source_ceiling` or `not_proven`. */
+    reason?: string | null;
+}
+/** A recent turn from another channel that the compiled pack has not absorbed yet. */
+interface LiveTurn {
+    at: string;
+    channel: string;
+    kind: EventKind;
+    speaker: string;
+    text: string;
+    source_id: string;
+}
+/** Where a prompt-cache breakpoint may go, and whether caching this pack is worth it. */
+interface CacheDirectives {
+    /** Character offsets into `text` where a cache breakpoint may be placed. */
+    breakpoints: number[];
+    ttl_seconds?: number | null;
+    floor_tokens?: number | null;
+    cacheable: boolean;
+    /** Stable cache salt for self-hosted inference engines. */
+    salt: string;
+}
+/** Body of a `POST /v1/context` response. */
+interface ContextResponse {
+    /** `true` when `known_etag` still matches; `text` is then omitted. */
+    not_modified: boolean;
+    text?: string | null;
+    variables: Record<string, string>;
+    version: string;
+    etag: string;
+    manifest_hash?: string | null;
+    as_of?: string | null;
+    lag_seconds?: number | null;
+    coverage: SourceCoverage[];
+    verification: VerificationResult;
+    /** How many items policy or verification kept out of the pack. */
+    withheld: number;
+    live: LiveTurn[];
+    live_complete: boolean;
+    delta?: string | null;
+    cache?: CacheDirectives | null;
+    timing: Record<string, number>;
+    path: DeliveryPath;
+    degraded: boolean;
+}
+interface HistoryFilters {
+    since?: string | null;
+    until?: string | null;
+    channels?: string[];
+    categories?: string[];
+    item_kinds?: HistoryItemKind[];
+    outcome?: string | null;
+    object?: ObjectRef | null;
+}
+/** Body of `POST /v1/history/search`. */
+interface SearchRequest {
+    subject: Handle;
+    about?: Handle | null;
+    /** Between 1 and 2,000 characters. */
+    query: string;
+    filters?: HistoryFilters;
+    /** Token budget for the answer, between 50 and 4,000. Defaults to 800. */
+    max_tokens?: number;
+    verification?: Verification;
+    conversation_id?: string | null;
+    task_id?: string | null;
+}
+interface HistoryItem {
+    id: string;
+    kind: string;
+    text: string;
+    at: string;
+    channel?: string | null;
+    source_id?: string | null;
+    outcome?: string | null;
+    confidence?: number | null;
+    origin_event_id?: string | null;
+}
+/** How often the same kind of issue came back, computed by the same rule as the recurring-complaint pattern. */
+interface Recurrence {
+    category: string;
+    occurrences: number;
+    window_days: number;
+    last_at?: string | null;
+    last_outcome?: string | null;
+    last_resolution?: string | null;
+}
+interface SearchResponse {
+    items: HistoryItem[];
+    recurrence?: Recurrence | null;
+    withheld: number;
+    as_of?: string | null;
+    tokens_used: number;
+    /** `text_only` when semantic search was unavailable and only keyword matching ran. */
+    degraded?: string | null;
+}
+/** Body of `POST /v1/history/timeline`. */
+interface TimelineRequest {
+    subject: Handle;
+    about?: Handle | null;
+    filters?: HistoryFilters;
+    cursor?: string | null;
+    /** Between 1 and 100. Defaults to 20. */
+    limit?: number;
+    verification?: Verification;
+    conversation_id?: string | null;
+}
+interface TimelineResponse {
+    items: HistoryItem[];
+    next_cursor?: string | null;
+    withheld: number;
+    as_of?: string | null;
+}
+/** A commitment recorded in an episode, made by the company or by the customer. */
+interface Commitment {
+    by: "company" | "customer";
+    what: string;
+    due_at?: string | null;
+    status: string;
+}
+/** One history item opened in full: structured summary, outcome and commitments. */
+interface OpenedItem {
+    id: string;
+    kind: "episode" | "object";
+    summary: string;
+    requested?: string | null;
+    promises: Commitment[];
+    outcome?: string | null;
+    resolution?: string | null;
+    derived: HistoryItem[];
+    timeline: HistoryItem[];
+    /** Literal transcript excerpt. Only returned to keys with an elevated scope. */
+    excerpt?: string | null;
+    as_of?: string | null;
+}
+/** The derived state of a business object, from `GET /v1/objects/{type}/{namespace}/{id}`. */
+interface ObjectState {
+    ref: ObjectRef;
+    state: Record<string, unknown>;
+    as_of: string;
+    source_id: string;
+    record_ref?: string | null;
+    open_items: HistoryItem[];
+}
+/** System events and agent actions about one object, newest first; never conversation content. */
+interface ObjectTimeline {
+    ref: ObjectRef;
+    items: HistoryItem[];
+    next_cursor?: string | null;
+    as_of?: string | null;
+}
+/** A function-calling tool definition in the JSON Schema shape most model APIs accept. */
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
+/** Arguments of `context()`. Pass exactly one of `subject` or `object`. */
+interface ContextParams {
+    /** The customer, by any handle the server knows. */
+    subject?: Handle;
+    /** A business object, such as an invoice, when the task is about the object rather than a person. */
+    object?: ObjectRef | string;
+    /** The account or partner the person acts for. Requires an active link between the two. */
+    about?: Handle;
+    /** Defaults to `chat`. */
+    view?: View;
+    /**
+     * The level proven in this conversation. The server may answer with a lower effective level
+     * when the source's ceiling is lower; see `response.verification`.
+     */
+    verification?: Verification;
+    /** Enables the per-conversation cache and the server's pinning of the pack. */
+    conversation_id?: string;
+    /** For internal agents: the task plays the role of the conversation. */
+    task_id?: string;
+    /** What the turn is about, so selection can favour relevant history. Up to 2,000 characters. */
+    query?: string;
+    /** Ask only for what changed since this source last read the subject. */
+    delta?: boolean;
+    /** The model that will read the pack, so the server can size it for that model's prompt cache. */
+    target?: TargetModel;
+}
+/** Per-call options shared by every read method. */
+interface RequestOptions {
+    /** Overrides the method's default time budget, in milliseconds. */
+    timeout?: number | undefined;
+    /** Cancels the wait. A request shared with other callers keeps running for them. */
+    signal?: AbortSignal | undefined;
+    /** Extra headers, such as a W3C `traceparent`. */
+    headers?: Record<string, string> | undefined;
+}
+interface ContextOptions extends RequestOptions {
+    /** Pass `false` to skip the per-conversation cache for this call. */
+    cache?: boolean | undefined;
+}
+/**
+ * Where a `context()` result came from.
+ *
+ * - `network`: a response the server just sent (or confirmed unchanged).
+ * - `cache`: a pack younger than the cache TTL; no request was made.
+ * - `stale`: an older pack returned at once while a background request refreshes it.
+ * - `fallback`: the request failed and this is the last good pack for the conversation.
+ * - `none`: nothing was available; `text` is empty and `error` says why.
+ */
+type ContextSource = "network" | "cache" | "stale" | "fallback" | "none";
+/** What `context()` resolves to. Always usable: on failure `text` is an empty string. */
+interface ContextResult {
+    /** The pack, ready for the system prompt. Empty when there is nothing to inject. */
+    text: string;
+    /**
+     * The parts that change turn by turn and belong at the end of the prompt, after the
+     * conversation: the delta and the live turns from other channels. Empty when there are none.
+     */
+    suffix: string;
+    /** Named values from the pack, for templates that place them individually. */
+    variables: Record<string, string>;
+    source: ContextSource;
+    /** The response this result was built from; `null` when `source` is `none`. */
+    response: ContextResponse | null;
+    /** What went wrong, when `source` is `fallback` or `none`. */
+    error: NiadraError | null;
+}
+/**
+ * Renders the delta and the live turns for the end of the prompt. Kept outside the pinned
+ * pack so that the prompt prefix stays byte-identical across turns and the model provider's
+ * prompt cache keeps hitting. Returns an empty string when there is nothing to add.
+ */
+declare function renderSuffix(response: ContextResponse): string;
+/**
+ * Renders the live turns (recent turns from other channels that the pack has not absorbed
+ * yet) as one tagged block, or an empty string when there are none. `complete="false"` tells
+ * the model the list may be missing turns because the server could not read all of them.
+ */
+declare function renderLive(response: ContextResponse): string;
+
+/**
+ * The write side: items of `POST /v1/batch`. A batch mixes item types, and one bad item never
+ * fails the batch; the server answers 207 with one error per rejected item.
+ */
+
+/** Longest text the server accepts in `content.text` or `content.transcript`. */
+declare const MAX_EVENT_TEXT = 200000;
+/** Largest batch the server accepts. */
+declare const MAX_BATCH_ITEMS = 500;
+/** Largest file `POST /v1/media/uploads` reserves room for: 500 MiB. */
+declare const MAX_MEDIA_BYTES: number;
+interface SpeakerRef {
+    role: Speaker;
+    /** Agent or attendant id inside the source. */
+    id?: string | null;
+}
+interface Content {
+    type?: "text" | "audio" | "image" | "file";
+    text?: string | null;
+    /** Reference returned by `/v1/media/uploads`; the media itself never travels in the event. */
+    media_ref?: string | null;
+    /** Lowercase hex SHA-256 of the media. */
+    media_sha256?: string | null;
+    transcript?: string | null;
+    /** Speech-to-text confidence between 0 and 1. Low-confidence agent turns are not measured. */
+    stt_confidence?: number | null;
+}
+interface VoiceInfo {
+    ani?: string | null;
+    dnis?: string | null;
+    trunk?: string | null;
+    network_attestation?: "A" | "B" | "C" | null;
+    answered_at?: string | null;
+    ended_at?: string | null;
+    end_reason?: string | null;
+    recording_ref?: string | null;
+    turn_offset_ms?: number | null;
+}
+/**
+ * The open item an action fulfils. Pass either `item_id`, or `object` together with the
+ * canonical `operation`; the server rejects any other combination.
+ */
+interface Closes {
+    item_id?: string | null;
+    object?: ObjectRef | null;
+    operation?: string | null;
+}
+interface ActionInfo {
+    /** Canonical operation, such as `credit` or `reschedule`. */
+    operation: string;
+    /** What happened, up to 2,000 characters. */
+    result?: string | null;
+    purpose?: string | null;
+    closes?: Closes | null;
+    corrects_action_id?: string | null;
+}
+/**
+ * Which context the agent's prompt carried and when it went in. Set on the agent's own turns
+ * and actions, so measurement can tell a context that arrived after the agent spoke from one
+ * it had and did not use.
+ */
+interface ContextStamp {
+    /** The etag of the pack in the prompt; absent when the prompt carried no pack. */
+    etag?: string | null;
+    injected_at: string;
+}
+/** A message, a system event or an agent action, exactly as sent on the wire. */
+interface EventItem {
+    type: "event";
+    kind: EventKind;
+    idempotency_key: string;
+    channel: string;
+    conversation_id?: string | null;
+    conversation_aliases?: string[];
+    task_id?: string | null;
+    handles?: Handle[];
+    subjects?: Subject[];
+    object_refs?: ObjectRef[];
+    speaker: SpeakerRef;
+    direction?: "inbound" | "outbound" | null;
+    content?: Content | null;
+    occurred_at: string;
+    visibility?: Visibility;
+    verification_hint?: Verification | null;
+    /** System events only, such as `invoice.credited`. */
+    canonical_type?: string | null;
+    /** Structured fields of a system event. */
+    fields?: Record<string, unknown>;
+    action?: ActionInfo | null;
+    corrects_event_id?: string | null;
+    voice?: VoiceInfo | null;
+    context_stamp?: ContextStamp | null;
+}
+/** States that several handles belong to the same subject. */
+interface IdentifyItem {
+    type: "identify";
+    idempotency_key: string;
+    /** Between 2 and 16 handles. */
+    handles: Handle[];
+    method: AssertionMethod;
+    subject_kind: SubjectKind;
+    conversation_id?: string | null;
+    occurred_at: string;
+}
+/** Raises the verification level of one conversation or task. The server never infers it. */
+interface VerifyItem {
+    type: "verify";
+    idempotency_key: string;
+    method: VerifyMethod;
+    level: Verification;
+    conversation_id?: string | null;
+    task_id?: string | null;
+    handle: Handle;
+    valid_until?: string | null;
+    occurred_at: string;
+}
+interface ConversationEndedItem {
+    type: "conversation.ended";
+    idempotency_key: string;
+    conversation_id: string;
+    occurred_at: string;
+}
+interface TaskEndedItem {
+    type: "task.ended";
+    idempotency_key: string;
+    task_id: string;
+    occurred_at: string;
+}
+/** A transfer to a human or another agent. */
+interface HandoffItem {
+    type: "handoff";
+    idempotency_key: string;
+    conversation_id: string;
+    target: "human" | "agent";
+    target_source?: string | null;
+    reason?: string | null;
+    mode: "warm" | "cold";
+    occurred_at: string;
+}
+/** Periodic counter the SDK sends so the server can tell a quiet source from a broken one. */
+interface HeartbeatItem {
+    type: "heartbeat";
+    window_start: string;
+    sent: number;
+}
+type BatchItem = EventItem | IdentifyItem | VerifyItem | ConversationEndedItem | TaskEndedItem | HandoffItem | HeartbeatItem;
+interface BatchRequest {
+    items: BatchItem[];
+}
+interface ItemError {
+    /** Position of the rejected item in the batch that was sent. */
+    index: number;
+    code: string;
+    detail?: string | null;
+}
+interface BatchResponse {
+    accepted: number;
+    duplicates: number;
+    errors: ItemError[];
+}
+/** Body of `POST /v1/media/uploads`. */
+interface MediaUploadRequest {
+    content_type: string;
+    /** Between 1 byte and 500 MiB. */
+    size_bytes: number;
+    /** Lowercase hex SHA-256 of the bytes. */
+    sha256: string;
+    /** Whose media it is. Stored under that person, so erasing them erases it too. */
+    subject?: Handle | null;
+}
+/** Where to send the bytes: a short-lived signed URL, and the reference events carry afterwards. */
+interface MediaUploadResponse {
+    media_ref: string;
+    upload_url: string;
+    /** Send exactly these headers with the bytes; the store refuses anything else. */
+    upload_headers?: Record<string, string>;
+    expires_at: string;
+}
+type FeedbackAction = "retract_fact" | "correct_fact" | "resolve_open_item" | "conversation_outcome";
+/** Body of `POST /v1/feedback`. The server records it as a `feedback.<action>` system event. */
+interface FeedbackRequest {
+    idempotency_key: string;
+    subject: Handle;
+    action: FeedbackAction;
+    fact_id?: string | null;
+    open_item_id?: string | null;
+    conversation_id?: string | null;
+    /** Up to 2,000 characters. */
+    value?: string | null;
+    /** Up to 500 characters. */
+    reason?: string | null;
+}
+
+/**
+ * Turns what callers pass to `track()`, `identify()` and friends into batch items, applying the
+ * same shape rules the server enforces. Catching a malformed event here means it is dropped
+ * with a log line instead of occupying the queue and coming back as a 207 error.
+ */
+
+/** An ISO 8601 string or a `Date`. */
+type Timestamp = string | Date;
+/** Fields shared by everything `track()` records. */
+interface EventBase {
+    /** Where it happened, such as `whatsapp`, `voice`, `app` or `erp`. */
+    channel: string;
+    /** Provider message id, when there is one; otherwise the SDK mints a UUIDv7. */
+    idempotency_key?: string;
+    conversation_id?: string | null;
+    /** Other ids the same conversation has in other systems. Up to 8. */
+    conversation_aliases?: string[];
+    task_id?: string | null;
+    /** Up to 16. An event needs at least one handle, subject or object. */
+    handles?: Handle[];
+    /** Up to 8. */
+    subjects?: Subject[];
+    /** Up to 16. Accepts `type:namespace:id` strings. */
+    object_refs?: (ObjectRef | string)[];
+    /** Defaults to now. */
+    occurred_at?: Timestamp;
+    visibility?: Visibility;
+    verification_hint?: Verification | null;
+    corrects_event_id?: string | null;
+    voice?: VoiceInfo | null;
+    /**
+     * Which context the agent acted on, for the agent's own turns and actions. Conversations and
+     * tasks set it from `markInjected()`.
+     */
+    context_stamp?: ContextStamp | null;
+}
+/** An event for `track()`. `kind` defaults to `message`. */
+interface TrackEvent extends EventBase {
+    kind?: EventKind;
+    /** Who produced it. A bare role is shorthand for `{ role }`. */
+    speaker: SpeakerRef | Speaker;
+    /** Defaults to `inbound` for customer messages and `outbound` for agent messages. */
+    direction?: "inbound" | "outbound" | null;
+    content?: Content | null;
+    /** Shorthand for `content: { type: "text", text }`. Cannot be combined with `content`. */
+    text?: string;
+    /** Required for `system_event`, such as `invoice.credited`. */
+    canonical_type?: string | null;
+    fields?: Record<string, unknown>;
+    /** Required for `action`, and only valid there. */
+    action?: ActionInfo | null;
+}
+/** An agent action for `action()`: what an agent did in a system of record. */
+interface ActionEvent extends EventBase {
+    /** Canonical operation, such as `credit` or `reschedule`. */
+    operation: string;
+    /** What happened, up to 2,000 characters. */
+    result?: string | null;
+    purpose?: string | null;
+    /** The open item this action fulfils, which the server then marks resolved. */
+    closes?: Closes | null;
+    corrects_action_id?: string | null;
+    /** Defaults to `ai_agent`. */
+    speaker?: SpeakerRef | Speaker;
+}
+interface IdentifyParams {
+    /** Between 2 and 16 handles that belong to the same subject. */
+    handles: Handle[];
+    /** Defaults to `explicit_identify`. */
+    method?: AssertionMethod;
+    /** Defaults to `person`. */
+    subject_kind?: SubjectKind;
+    conversation_id?: string | null;
+    occurred_at?: Timestamp;
+    idempotency_key?: string;
+}
+interface VerifyParams {
+    /** The handle whose possession was proven. */
+    handle: Handle;
+    method: VerifyMethod;
+    /** The level reached. It applies to this conversation or task only. */
+    level: Verification;
+    conversation_id?: string | null;
+    task_id?: string | null;
+    /** When the proof stops counting. */
+    valid_until?: Timestamp | null;
+    occurred_at?: Timestamp;
+    idempotency_key?: string;
+}
+interface HandoffParams {
+    conversation_id: string;
+    target: "human" | "agent";
+    /** The source that takes over, when it is integrated with Niadra. */
+    target_source?: string | null;
+    reason?: string | null;
+    /** `warm` when the receiver gets a briefing. Defaults to `warm`. */
+    mode?: "warm" | "cold";
+    occurred_at?: Timestamp;
+    idempotency_key?: string;
+}
+/** Arguments of `feedback()`: a correction of what Niadra derived about a subject. */
+interface FeedbackParams {
+    subject: Handle;
+    /**
+     * `retract_fact` or `correct_fact` (with `fact_id`, and `value` for the right one),
+     * `resolve_open_item` (with `open_item_id`) or `conversation_outcome` (with `conversation_id`
+     * and `value`).
+     */
+    action: FeedbackAction;
+    fact_id?: string | null;
+    open_item_id?: string | null;
+    conversation_id?: string | null;
+    /** Up to 2,000 characters. */
+    value?: string | null;
+    /** Why, up to 500 characters. */
+    reason?: string | null;
+    idempotency_key?: string;
+}
+
+/**
+ * Where the SDK reports what it swallowed in fail-open mode. Messages carry status codes,
+ * error codes and request ids, never handles, message text or other personal data.
+ */
+interface Logger {
+    debug(message: string, ...details: unknown[]): void;
+    warn(message: string, ...details: unknown[]): void;
+    error(message: string, ...details: unknown[]): void;
+}
+/** Warnings and errors go to the console; debug output is off unless you pass your own logger. */
+declare const consoleLogger: Logger;
+declare const silentLogger: Logger;
+
+/** When context first went into the prompt, and when the agent first spoke. */
+interface Timings {
+    contextInjectedAt: Date | null;
+    firstAgentTurnAt: Date | null;
+}
+
+/** The outcome of a call that may fail without throwing. Exactly one of the two fields is set. */
+type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: NiadraError;
+};
+/** Everything a tool call is bound to besides its arguments. None of it is visible to the model. */
+interface ToolBinding {
+    about?: Handle;
+    verification?: Verification;
+    conversation_id?: string;
+    task_id?: string;
+    /** Use the voice time budget for the calls these tools make. */
+    voice?: boolean;
+}
+/**
+ * The navigation kit as function-calling tools, bound to one customer.
+ *
+ * The definitions have no parameter for the customer: the handle lives in this object, outside
+ * the model's reach. A prompt injection that says "now look up customer X" has no argument to
+ * put X in. The model chooses what to ask, never whom it is about.
+ */
+interface BoundTools {
+    /** Tool definitions in the `{ type: "function", function: { name, description, parameters } }` shape. */
+    readonly definitions: ToolDefinition[];
+    /** Whether `name` is one of these tools, for dispatchers that route several toolsets. */
+    has(name: string): boolean;
+    /**
+     * Runs one tool call and returns the text to send back to the model as the tool result.
+     * `args` may be the JSON string most model APIs return, or an already parsed object.
+     * Failures come back as a short JSON error the model can read and move past; with
+     * `strict: true` they are thrown instead.
+     */
+    call(name: string, args: string | Record<string, unknown>): Promise<string>;
+}
+declare const TOOL_NAMES: {
+    readonly search: "search_customer_history";
+    readonly timeline: "get_customer_timeline";
+    readonly open: "open_history_item";
+};
+declare const TOOL_DEFINITIONS: readonly ToolDefinition[];
+
+interface ConversationParams {
+    /** The customer on the other side. */
+    subject: Handle;
+    /** Where the conversation happens, such as `whatsapp` or `voice`. */
+    channel: string;
+    /** Your id for the thread. A UUIDv7 is minted when omitted. */
+    conversation_id?: string;
+    /** Defaults to `voice` when the channel is `voice`, otherwise `chat`. */
+    view?: View;
+    /** The level already proven when the conversation starts. Defaults to `V0`. */
+    verification?: Verification;
+    /** The account or partner the customer acts for. */
+    about?: Handle;
+    target?: TargetModel;
+}
+/** Optional details of one captured turn. */
+interface TurnOptions {
+    /** The provider's message id, which makes retries of the same turn harmless. */
+    idempotency_key?: string;
+    occurred_at?: Timestamp;
+    /** The agent or attendant id inside your system. */
+    speaker_id?: string;
+    visibility?: Visibility;
+    /** Marks the text as a speech-to-text transcript with this confidence, between 0 and 1. */
+    stt_confidence?: number;
+    voice?: VoiceInfo;
+    /** Overrides the stamp an agent turn would carry from `markInjected()`. */
+    context_stamp?: ContextStamp;
+}
+type ConversationEvent = Omit<TrackEvent, "channel" | "conversation_id"> & {
+    channel?: string;
+};
+type ConversationAction = Omit<ActionEvent, "channel" | "conversation_id"> & {
+    channel?: string;
+};
+interface ConversationHooks {
+    endConversation(id: string): Promise<WriteResult>;
+}
+/**
+ * One customer conversation.
+ *
+ * The server pins the pack to the conversation: every turn gets the same bytes, so the prompt
+ * prefix stays byte-identical and the model provider's prompt cache keeps hitting. After the
+ * first pack, each read also asks for the delta, what changed since this agent last looked
+ * (a new open item, an action another agent took). The server sends each delta once, so the
+ * conversation keeps them, in order, in `suffix`, with the live turns, for the end of the
+ * prompt. A successful `verify()` starts over from the pack the server pins for the new level.
+ *
+ * Call `markInjected()` when the pack goes into the prompt; the agent's later turns and actions
+ * carry that moment and the pack's etag as `context_stamp`. `wrap()` does it for you.
+ *
+ * @example
+ * const convo = niadra.conversation({ subject: handles.waId("5511987654321"), channel: "whatsapp" });
+ * convo.customer(inbound.text, { idempotency_key: inbound.id });
+ * const ctx = await convo.context();
+ * convo.markInjected(ctx);
+ * const reply = await llm(ctx.text, history, ctx.suffix);
+ * convo.agent(reply);
+ */
+declare class Conversation {
+    private readonly client;
+    private readonly params;
+    private readonly hooks;
+    readonly id: string;
+    readonly channel: string;
+    readonly subject: Handle;
+    private level;
+    private readonly view;
+    private readonly state;
+    private ending;
+    constructor(client: Niadra, params: ConversationParams, hooks: ConversationHooks);
+    /** The level in force for this conversation, raised by a successful `verify()`. */
+    get verification(): Verification;
+    /**
+     * When context first went into the prompt, and when the agent first spoke. Context injected
+     * after the agent's first turn is the "late context" signal the usage measurement reports.
+     */
+    get timings(): Timings;
+    /** What the agent's next turn and action carry: the last `markInjected()`, or `null`. */
+    get contextStamp(): ContextStamp | null;
+    /** The last result `context()` returned for this conversation. */
+    get lastContext(): ContextResult | null;
+    /** Where `wrap()` reports what it swallowed: the client's logger. */
+    get logger(): Logger;
+    /**
+     * The pack for this turn: the pinned `text`, and a `suffix` with every delta since the pin
+     * and the current live turns. A read with `query` is compiled for that query and never
+     * pinned, so it leaves the conversation's deltas alone.
+     */
+    context(options?: ContextOptions & {
+        query?: string;
+    }): Promise<ContextResult>;
+    /**
+     * Records that `context` (by default the last one this conversation returned) went into the
+     * prompt. Call it each time you build the prompt; `timings.contextInjectedAt` keeps the first.
+     */
+    markInjected(context?: ContextResult | null, at?: Date): void;
+    /** Captures what the customer said. */
+    customer(text: string, options?: TurnOptions): string | null;
+    /** Captures what the AI agent said, stamped with the context its prompt carried. */
+    agent(text: string, options?: TurnOptions): string | null;
+    /** Captures what a human attendant said, for example after a handoff. */
+    human(text: string, options?: TurnOptions): string | null;
+    /** Records any event in this conversation. The customer's handle is attached unless you pass your own. */
+    track(event: ConversationEvent): string | null;
+    /** Records an action the agent took during this conversation, stamped like its turns. */
+    action(event: ConversationAction): string | null;
+    /**
+     * Records that the customer proved who they are, and raises the level for later reads.
+     * `handle` defaults to the conversation's subject.
+     */
+    verify(params: {
+        method: VerifyMethod;
+        level: Verification;
+        handle?: Handle;
+    }): Promise<WriteResult>;
+    /** Records a transfer to a human or another agent. */
+    handoff(params: {
+        target: "human" | "agent";
+        target_source?: string;
+        reason?: string;
+        mode?: "warm" | "cold";
+    }): Promise<WriteResult>;
+    /**
+     * The navigation kit bound to this customer and conversation. The verification level is
+     * read at each call, so tools created before a `verify()` pick up the new level.
+     */
+    tools(): BoundTools;
+    /** Emits `conversation.ended` and drops the conversation's cached packs. Safe to call twice. */
+    end(): Promise<WriteResult>;
+    private bind;
+    private turn;
+}
+
+/** Arguments of `uploadMedia()`. */
+interface UploadParams {
+    /** The file itself. It is read into memory once, to hash it and send it. */
+    data: Uint8Array | ArrayBuffer | Blob;
+    /** Such as `audio/wav` or `image/png`. Storage checks it against the signed URL. */
+    content_type: string;
+    /**
+     * Whose file it is, whenever you know. It is then stored under that person, so erasing them
+     * erases it, even if no event ever references it.
+     */
+    subject?: Handle;
+}
+/** A file handed to Niadra. Put `media_ref` and `media_sha256` in the event's `content`. */
+interface MediaUpload {
+    media_ref: string;
+    media_sha256: string;
+    content_type: string;
+    size_bytes: number;
+    expires_at: string | null;
+}
+
+/** Paging of `objectTimeline()`. */
+interface ObjectTimelineParams {
+    /** `next_cursor` from the previous page. */
+    cursor?: string;
+    /** Between 1 and 100. Defaults to 20. */
+    limit?: number;
+}
+
+/**
+ * Per-method time budgets in milliseconds. They are the SDK's own and deliberately short:
+ * managed agent platforms allow 7 to 10 seconds per turn and self-hosted frameworks allow no
+ * limit at all, so a slow memory call must never become a slow agent.
+ */
+interface Timeouts {
+    /** `context()` for every view except `voice`. */
+    context: number;
+    /** `context()` with `view: "voice"`, where the budget is a fraction of a spoken turn. */
+    contextVoice: number;
+    /** `search()`, `timeline()` and `open()`. */
+    navigation: number;
+    /** Navigation calls made through a voice conversation or voice-bound tools. */
+    navigationVoice: number;
+    /** Each attempt of a batch upload. Writes happen off the hot path, so this one is generous. */
+    write: number;
+    /** `subjectToken()`, usually called once when a session starts. */
+    token: number;
+    /** Each attempt of sending media bytes to storage in `uploadMedia()`, off the hot path. */
+    upload: number;
+}
+declare const DEFAULT_TIMEOUTS: Timeouts;
+/** How `context()` reuses packs inside a conversation. */
+interface CacheOptions {
+    /** A pack younger than this is returned without any request. */
+    ttlMs: number;
+    /**
+     * After `ttlMs`, the cached pack is still returned at once for this long while a single
+     * background request refreshes it.
+     */
+    staleWhileRevalidateMs: number;
+    /**
+     * Oldest pack the SDK will fall back to when a request fails. Older packs are dropped
+     * rather than shown to a model as if they were current.
+     */
+    maxStaleMs: number;
+    /** Least recently used packs are evicted past this many conversations. */
+    maxEntries: number;
+}
+declare const DEFAULT_CACHE: CacheOptions;
+/** How `track()` and the other write methods batch events on their way to `POST /v1/batch`. */
+interface QueueOptions {
+    /** Send as soon as this many items are waiting. */
+    flushAt: number;
+    /** Send whatever is waiting at least this often. */
+    flushIntervalMs: number;
+    /** Items per request. The server accepts up to 500. */
+    maxBatchSize: number;
+    /** Items held in memory before new ones are dropped. Keeps a long outage from exhausting memory. */
+    maxQueueSize: number;
+    /** Attempts per batch, including the first. 4xx answers other than 408, 421 and 429 are never retried. */
+    maxAttempts: number;
+    /** First backoff delay; each retry doubles it, with full jitter, up to `maxRetryDelayMs`. */
+    retryDelayMs: number;
+    maxRetryDelayMs: number;
+}
+declare const DEFAULT_QUEUE: QueueOptions;
+interface ClientOptions {
+    /**
+     * A source key, `nia_sk_<live|test>_<region>_<space>_<key_id>_<secret>`. Defaults to the
+     * `NIADRA_API_KEY` environment variable where one exists. Without a key the client is a
+     * no-op: every method resolves with an empty result and nothing is sent.
+     */
+    apiKey?: string | undefined;
+    /**
+     * Overrides the address derived from the key, for the local emulator or a private endpoint.
+     * Defaults to `NIADRA_BASE_URL`, then to `https://<space>.<region>.api.niadra.com`.
+     */
+    baseURL?: string | undefined;
+    timeouts?: Partial<Timeouts>;
+    /** Pass `false` to send every `context()` call to the server. */
+    cache?: Partial<CacheOptions> | false;
+    queue?: Partial<QueueOptions>;
+    /**
+     * Throw errors instead of logging them and resolving with an empty result. Meant for tests
+     * and development, where a silent failure hides a broken integration.
+     */
+    strict?: boolean;
+    /** Flush queued events when a Node process is about to exit. Defaults to `true`. */
+    flushOnExit?: boolean;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: typeof fetch;
+    logger?: Logger;
+    /** Extra headers sent with every request. */
+    defaultHeaders?: Record<string, string>;
+}
+
+interface TaskParams {
+    /** Your id for the task. A UUIDv7 is minted when omitted. */
+    task_id?: string;
+    /** The internal agent or system doing the work, such as `billing-agent`. */
+    channel: string;
+    /** The person the task is about. Pass this, `object`, or both. */
+    subject?: Handle;
+    /** The business object the task is about, as an `ObjectRef` or `type:namespace:id`. */
+    object?: ObjectRef | string;
+    about?: Handle;
+    /** A task view such as `task:billing`. Defaults to `brief`. */
+    view?: View;
+    verification?: Verification;
+    target?: TargetModel;
+}
+type TaskEvent = Omit<TrackEvent, "channel" | "task_id"> & {
+    channel?: string;
+};
+type TaskAction = Omit<ActionEvent, "channel" | "task_id"> & {
+    channel?: string;
+};
+interface TaskHooks {
+    endTask(id: string): Promise<WriteResult>;
+    /** `verify()` for a task, which may have no subject to default the handle to. */
+    verifyTask(params: Omit<VerifyParams, "handle"> & {
+        handle: Handle | undefined;
+    }): Promise<WriteResult>;
+}
+/**
+ * One unit of work by an internal agent: a collection run, a ticket triage, a refund. The task
+ * plays the role a conversation plays for customer-facing agents: the server pins its pack,
+ * deltas arrive and are kept the same way, it scopes the context cache, groups the events for
+ * billing and closes with `task.ended`. Without `end()`, the server closes the task after 10
+ * minutes of inactivity.
+ */
+declare class Task {
+    private readonly client;
+    private readonly params;
+    private readonly hooks;
+    readonly id: string;
+    private readonly object;
+    private level;
+    private readonly state;
+    private ending;
+    constructor(client: Niadra, params: TaskParams, hooks: TaskHooks);
+    /** When context first went into the prompt, and when the agent first acted. */
+    get timings(): Timings;
+    /** What the agent's next turn and action carry: the last `markInjected()`, or `null`. */
+    get contextStamp(): ContextStamp | null;
+    /** The last result `context()` returned for this task. */
+    get lastContext(): ContextResult | null;
+    /** Where `wrap()` reports what it swallowed: the client's logger. */
+    get logger(): Logger;
+    /**
+     * Context for the task, centered on its object when it has one, otherwise on its subject.
+     * Resolves with an empty result, never rejects, unless the client is strict.
+     */
+    context(options?: ContextOptions & {
+        query?: string;
+    }): Promise<ContextResult>;
+    /** Records that `context` (by default the last one this task returned) went into the prompt. */
+    markInjected(context?: ContextResult | null, at?: Date): void;
+    /** Captures what the agent answered, stamped with the context its prompt carried. */
+    agent(text: string, options?: TurnOptions): string | null;
+    /**
+     * Records that the person the task is about proved who they are, and reads at the new level
+     * from then on. `handle` defaults to the task's subject.
+     */
+    verify(params: {
+        method: VerifyMethod;
+        level: Verification;
+        handle?: Handle;
+    }): Promise<WriteResult>;
+    /** Records an event in this task, attaching the task's subject and object unless you pass your own. */
+    track(event: TaskEvent): string | null;
+    /** Records an action taken in a system of record, such as `credit` on an invoice, stamped like its turns. */
+    action(event: TaskAction): string | null;
+    /**
+     * The navigation kit bound to the task's subject, or `null` for a task about an object only.
+     * The verification level is read at each call, so tools created before a `verify()` pick up
+     * the new level.
+     */
+    tools(): BoundTools | null;
+    /** Emits `task.ended` and drops the task's cached packs. Safe to call twice. */
+    end(): Promise<WriteResult>;
+    private bind;
+}
+
+/**
+ * Body of `POST /v1/subject-tokens`. The token binds one customer to a session so that an MCP
+ * connection, or any client you hand it to, can read that customer and no other.
+ */
+interface SubjectTokenRequest {
+    subject: Handle;
+    about?: Handle | null;
+    conversation_id?: string | null;
+    task_id?: string | null;
+    verification?: Verification;
+}
+/** A signed token valid for 15 minutes. Treat it as a credential: it reads this customer's memory. */
+interface SubjectToken {
+    token: string;
+    expires_at: string;
+}
+
+/** What `identify()`, `verify()`, `handoff()` and the `end()` helpers resolve to. */
+type WriteResult = {
+    ok: true;
+    idempotency_key: string;
+    error: null;
+} | {
+    ok: false;
+    idempotency_key: string | null;
+    error: NiadraError;
+};
+/** Scope of `open()`: the same verification and conversation the rest of the session uses. */
+interface OpenParams {
+    verification?: Verification;
+    conversation_id?: string;
+    task_id?: string;
+}
+/**
+ * The Niadra client.
+ *
+ * Reads (`context`, `search`, `timeline`, `open`) run on the agent's hot path with short time
+ * budgets of their own. Writes (`track` and friends) go through an in-memory queue and never
+ * block the caller. By default every method is fail-open: an outage, a timeout or a bad
+ * argument is logged and the method resolves with an empty result, so the agent keeps
+ * working without memory rather than not working at all. Pass `strict: true` to throw instead.
+ *
+ * Create one client per process and share it; it holds the queue, the cache and the
+ * connection pool.
+ *
+ * @example
+ * const niadra = new Niadra({ apiKey: process.env.NIADRA_API_KEY });
+ * const ctx = await niadra.context({ subject: handles.phone("+5511987654321"), conversation_id: "wa-8812" });
+ */
+declare class Niadra {
+    /** `false` when the client was built without a usable key and sends nothing. */
+    readonly enabled: boolean;
+    private readonly core;
+    private readonly timeouts;
+    private readonly strict;
+    /** Where the client reports what it swallows in fail-open mode. */
+    readonly logger: Logger;
+    private readonly disabledReason;
+    private unregisterExit;
+    constructor(options?: ClientOptions);
+    private setup;
+    /**
+     * The customer's context pack, to place in the system prompt before calling the model.
+     *
+     * Inside a conversation (`conversation_id` or `task_id`), packs are cached: a recent one is
+     * returned without a request, an older one is returned at once while a single background
+     * request refreshes it, and when a request fails the last good pack is returned instead.
+     * A 401 or 403 is not an outage: it drops the cached packs, so revoking a key also stops
+     * what the process had already cached from reaching the model.
+     *
+     * A plain read and a `delta` read of one conversation share the cached pack. The server
+     * sends each delta once, and so does the cache, even one a background refresh brought in;
+     * `conversation()` and `task()` keep them across turns.
+     *
+     * Never rejects unless `strict` is set. On failure `text` is empty and `error` is set.
+     */
+    context(params: ContextParams, options?: ContextOptions): Promise<ContextResult>;
+    /**
+     * Searches the customer's history by keywords and meaning, with filters by period, channel,
+     * topic and kind. The answer includes how often the same kind of issue came back.
+     */
+    search(params: SearchRequest, options?: RequestOptions): Promise<Result<SearchResponse>>;
+    /** The customer's history in chronological order, one line per item, paginated by cursor. */
+    timeline(params: TimelineRequest, options?: RequestOptions): Promise<Result<TimelineResponse>>;
+    /**
+     * Opens one history item from `search()` or `timeline()`: summary, request, commitments,
+     * outcome and resolution. The literal transcript excerpt only comes back to keys with an
+     * elevated scope.
+     */
+    open(id: string, params?: OpenParams, options?: RequestOptions): Promise<Result<OpenedItem>>;
+    /**
+     * The derived state of a business object: what its systems of record reported last, `as_of`
+     * when, and its open items, under this source's purpose.
+     *
+     * @example
+     * const { data: invoice } = await niadra.objectState("invoice:erp:0823");
+     */
+    objectState(object: ObjectRef | string, options?: RequestOptions): Promise<Result<ObjectState>>;
+    /**
+     * System events and agent actions about one object, newest first, one line each and never
+     * conversation content. Pass `next_cursor` back as `cursor` to go on.
+     */
+    objectTimeline(object: ObjectRef | string, params?: ObjectTimelineParams, options?: RequestOptions): Promise<Result<ObjectTimeline>>;
+    /**
+     * The navigation kit as function-calling tools with the customer bound outside the model's
+     * reach. Hand `definitions` to any model API and pass its tool calls to `call()`.
+     *
+     * @example
+     * const kit = niadra.tools(handles.phone("+5511987654321"), { conversation_id: "wa-8812" });
+     * const output = await kit.call(toolCall.function.name, toolCall.function.arguments);
+     */
+    tools(subject: Handle, binding?: ToolBinding): BoundTools;
+    /**
+     * Mints a signed, 15-minute token that binds one customer to a session. Your backend calls
+     * this and hands the token to the MCP connection, so tools served over MCP can only ever
+     * read that customer. Resolves with `data: null` on failure.
+     */
+    subjectToken(params: SubjectTokenRequest, options?: RequestOptions): Promise<Result<SubjectToken>>;
+    /**
+     * Records a message, a system event or an agent action. Returns at once with the event's
+     * idempotency key, or `null` when the event was dropped: invalid, unserializable, the queue
+     * full or the client disabled. Delivery happens in the background; `flush()` waits for it.
+     */
+    track(event: TrackEvent): string | null;
+    /**
+     * Records what an agent did in a system of record, such as a credit or a reschedule.
+     * With `closes`, the action also resolves the open item it fulfils.
+     */
+    action(event: ActionEvent): string | null;
+    /**
+     * States that several handles belong to the same subject. Sent right away rather than on the
+     * next batch, so the next `context()` call already sees the merged profile.
+     */
+    identify(params: IdentifyParams): Promise<WriteResult>;
+    /**
+     * Raises the verification level of one conversation or task after the customer proved who
+     * they are. Sent right away, and drops the conversation's cached packs, because a pack
+     * compiled for the old level may be missing what the new level allows.
+     */
+    verify(params: VerifyParams): Promise<WriteResult>;
+    /**
+     * Corrects what Niadra derived about a subject: retracts or corrects a fact, resolves an open
+     * item, or records how a conversation ended. Sent right away; the server records it as an
+     * event, so the correction is audited like any other. A rejected correction resolves with
+     * `ok: false`.
+     */
+    feedback(params: FeedbackParams): Promise<WriteResult>;
+    /**
+     * Hands a file to Niadra, such as a call recording, and returns the reference its event
+     * carries. Media never travels inside an event: this reserves an upload, sends the bytes
+     * straight to storage over a short-lived signed URL, and resolves with `media_ref` and
+     * `media_sha256` for the event's `content`.
+     *
+     * @example
+     * const { data } = await niadra.uploadMedia({ data: recording, content_type: "audio/wav" });
+     * if (data) convo.track({ speaker: "customer", content: { type: "audio", media_ref: data.media_ref, media_sha256: data.media_sha256 } });
+     */
+    uploadMedia(params: UploadParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<Result<MediaUpload>>;
+    /** Records a transfer to a human or another agent. Sent right away, so the receiver can read context at once. */
+    handoff(params: HandoffParams): Promise<WriteResult>;
+    /**
+     * A helper for one customer conversation: pins the pack across turns, captures turns and
+     * emits `conversation.ended` when you call `end()`.
+     */
+    conversation(params: ConversationParams): Conversation;
+    /** A helper for one internal-agent task: binds `task_id` to reads and writes and emits `task.ended`. */
+    task(params: TaskParams): Task;
+    /**
+     * Sends every queued event and resolves when done. Call it before a serverless function
+     * returns, or pass it to `waitUntil()` on edge runtimes. Rejects only with `strict` set.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes, stops the background timer and releases the exit hook. Events tracked after
+     * this are dropped. Call it from your own SIGTERM handler in long-running services.
+     */
+    shutdown(): Promise<void>;
+    private verifyWith;
+    /** Throws under `strict`; otherwise logs what failed, never with content, and returns the error. */
+    private swallow;
+    private voiceBudget;
+    private readSpec;
+    private navigate;
+    private fetchContext;
+    /**
+     * One request for a key, shared by every caller that needs it meanwhile. It sends the
+     * cached ETag, so an unchanged pack costs a `not_modified` answer instead of the full text.
+     * The caller's signal is deliberately not passed down: other callers may be waiting too.
+     */
+    private revalidate;
+    private contextFailure;
+    /**
+     * 401 means the key itself is no longer valid, so every cached pack goes. 403 is specific to
+     * what was asked, so only that pack goes.
+     */
+    private observeAuth;
+    private forgetScope;
+    private disabledError;
+    private enqueue;
+    private sendNow;
+    private endScope;
+    private sendBatch;
+}
+
+/**
+ * `wrap()` for OpenAI-compatible clients: the official `openai` package and any client with its
+ * `chat.completions.create(body, options)` shape.
+ *
+ * Each `chat.completions.create` and `chat.completions.parse` call made through the wrapper,
+ * streaming or not, gets the conversation's pack as a system message right after the caller's
+ * leading system or developer messages, and the suffix (deltas and live turns) as a system
+ * message at the end. The pack goes after the caller's instructions because those are the same
+ * for every customer: kept first, they stay the cacheable prefix of the prompt. The injection is
+ * stamped on the conversation, and the model's answer is recorded as the agent's turn.
+ *
+ * Nothing the wrapper does can fail the model call: a context that cannot be fetched is left
+ * out, and a failure to record the answer is logged, without content, and swallowed.
+ */
+
+/** What `wrap()` needs from a conversation or a task. Both implement it. */
+interface WrapSession {
+    context(): Promise<ContextResult>;
+    markInjected(context?: ContextResult | null): void;
+    agent(text: string): string | null;
+    readonly logger: Logger;
+}
+/** A session, or a function that finds the one the current call belongs to (`null` passes the call through). */
+type SessionSource = WrapSession | (() => WrapSession | null | undefined);
+/**
+ * Returns a proxy of an OpenAI-compatible client that injects the conversation's context and
+ * records the model's answers. The client itself is never modified.
+ *
+ * `.withResponse()` keeps working on intercepted calls and records the answer too;
+ * `.asResponse()` returns the raw HTTP response, whose body the SDK cannot read, so nothing is
+ * recorded then. Streams are recorded when they end, or when the caller stops reading them.
+ *
+ * @example
+ * const openai = wrap(new OpenAI(), convo);
+ * const completion = await openai.chat.completions.create({ model: "gpt-4.1", messages });
+ */
+declare function wrap<C extends object>(client: C, session: SessionSource): C;
+/**
+ * Places the pack after the leading system or developer messages and the suffix at the end.
+ * Returns a new array; `messages` is left as it was.
+ */
+declare function injectContext(context: ContextResult, messages: readonly unknown[]): unknown[];
+
+interface HandleOptions {
+    /** Overrides the subject kind the server would infer from the handle type. */
+    subjectKind?: SubjectKind;
+}
+/**
+ * Builders for the handle types the API accepts. They only assemble the object; the value is
+ * normalized and validated on the server, which is the single source of truth for matching.
+ *
+ * @example
+ * niadra.context({ subject: handles.phone("+5511987654321"), conversation_id: "wa-8812" })
+ */
+declare const handles: {
+    /** A phone number in E.164 form, such as `+5511987654321`. */
+    readonly phone: (e164: string, options?: HandleOptions) => Handle;
+    readonly email: (address: string, options?: HandleOptions) => Handle;
+    /** The WhatsApp id (`wa_id`) the Cloud API reports for a contact. */
+    readonly waId: (value: string, options?: HandleOptions) => Handle;
+    readonly waJid: (value: string, options?: HandleOptions) => Handle;
+    readonly waLid: (value: string, options?: HandleOptions) => Handle;
+    /** A business-scoped WhatsApp user id; `businessAccount` is the WhatsApp Business account it belongs to. */
+    readonly waBsuid: (value: string, businessAccount: string, options?: HandleOptions) => Handle;
+    /** The user id in your own app or site. */
+    readonly appUserId: (value: string, options?: HandleOptions) => Handle;
+    /** The id of a person or organization in a system of record; `system` names that system, such as `crm`. */
+    readonly systemId: (value: string, system: string, options?: HandleOptions) => Handle;
+    /** An HMAC of a national document number; `country` is its ISO 3166-1 alpha-2 code. */
+    readonly govIdHmac: (value: string, country: string, options?: HandleOptions) => Handle;
+    /** An HMAC of a company registry number. Identifies an organization. */
+    readonly orgRegistryHmac: (value: string, country: string) => Handle;
+    /** An e-mail domain, such as `acme.com`. Identifies an organization. */
+    readonly emailDomain: (domain: string) => Handle;
+    /** An anonymous visitor or device id, before the person is known. */
+    readonly anonId: (value: string, options?: HandleOptions) => Handle;
+};
+/**
+ * Accepts an `ObjectRef` or the `type:namespace:id` shorthand. The id may itself contain
+ * colons (`invoice:erp:2026:0823`); only the first two separate the parts.
+ */
+declare function toObjectRef(object: ObjectRef | string): ObjectRef;
+
+/** The parts of a source key the SDK needs to find the right endpoint. */
+interface ParsedApiKey {
+    /** `live` keys reach production spaces, `test` keys reach sandbox spaces. */
+    mode: "live" | "test";
+    /** Data region, such as `sa-east-1`. */
+    region: string;
+    /** The space (project and environment) the key belongs to. */
+    space: string;
+    keyId: string;
+}
+/**
+ * Parses `nia_sk_<live|test>_<region>_<space>_<key_id>_<secret>`.
+ *
+ * Region and space become DNS labels in the base URL, so they are held to lowercase letters,
+ * digits and inner hyphens. The secret is everything after the fifth underscore and is never
+ * returned. Returns `null` for anything that does not match, rather than guessing.
+ */
+declare function parseApiKey(apiKey: string): ParsedApiKey | null;
+/**
+ * The stable address of a space: `https://<space>.<region>.api.niadra.com`. It never names a
+ * cell; when a space moves between cells, the old cell answers 421 and the SDK retries.
+ */
+declare function baseURLFromKey(key: ParsedApiKey): string;
+
+/**
+ * A UUIDv7 (RFC 9562): time-ordered, so keys minted by one process sort in the order the
+ * events happened. A 12-bit counter keeps keys monotonic within the same millisecond.
+ */
+declare function uuidv7(now?: number): string;
+
+declare const VERSION = "0.1.0";
+
+export { type ActionEvent, type ActionInfo, type AssertionMethod, type BatchItem, type BatchRequest, type BatchResponse, type BoundTools, type CacheDirectives, type CacheOptions, type ClientOptions, type Closes, type Commitment, type Content, type ContextOptions, type ContextParams, type ContextRequest, type ContextResponse, type ContextResult, type ContextSource, type ContextStamp, Conversation, type ConversationAction, type ConversationEndedItem, type ConversationEvent, type ConversationParams, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, type DeliveryPath, type EventItem, type EventKind, type FeedbackAction, type FeedbackParams, type FeedbackRequest, type Handle, type HandleType, type HandoffItem, type HandoffParams, type HeartbeatItem, type HistoryFilters, type HistoryItem, type HistoryItemKind, type IdentifyItem, type IdentifyParams, type ItemError, type LiveTurn, type Logger, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, type MediaUpload, type MediaUploadRequest, type MediaUploadResponse, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, type ObjectRef, type ObjectState, type ObjectTimeline, type ObjectTimelineParams, type OpenParams, type OpenedItem, type ParsedApiKey, type Problem, type QueueOptions, type Recurrence, type RequestOptions, type Result, type SearchRequest, type SearchResponse, type SessionSource, type SourceCoverage, type Speaker, type SpeakerRef, type Subject, type SubjectKind, type SubjectToken, type SubjectTokenRequest, TOOL_DEFINITIONS, TOOL_NAMES, type TargetModel, Task, type TaskAction, type TaskEndedItem, type TaskEvent, type TaskParams, type TimelineRequest, type TimelineResponse, type Timeouts, type Timestamp, type Timings, type ToolBinding, type ToolDefinition, type TrackEvent, type TurnOptions, type UploadParams, VERSION, type Verification, type VerificationResult, type VerifyItem, type VerifyMethod, type VerifyParams, type View, type Visibility, type VoiceInfo, type WrapSession, type WriteResult, baseURLFromKey, consoleLogger, handles, injectContext, parseApiKey, renderLive, renderSuffix, silentLogger, toObjectRef, uuidv7, wrap };