@niadra/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,2389 @@
+'use strict';
+
+// src/cache.ts
+var ContextCache = class {
+  constructor(options, now = Date.now) {
+    this.options = options;
+    this.now = now;
+  }
+  options;
+  now;
+  entries = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  epoch = 0;
+  get size() {
+    return this.entries.size;
+  }
+  /**
+   * Bumped by `clear()`. A request started before a purge carries the old epoch, and its
+   * answer is not stored: a revoked key must not repopulate the cache on its way out.
+   */
+  get generation() {
+    return this.epoch;
+  }
+  lookup(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    const age = this.now() - entry.confirmedAt;
+    if (age > this.options.maxStaleMs) {
+      this.entries.delete(key);
+      return null;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    let freshness = "expired";
+    if (age <= this.options.ttlMs) freshness = "fresh";
+    else if (age <= this.options.ttlMs + this.options.staleWhileRevalidateMs) freshness = "stale";
+    return { response: entry.response, freshness };
+  }
+  store(key, scope, response, generation = this.epoch) {
+    if (generation !== this.epoch) return;
+    const previous = this.entries.get(key);
+    const pending = previous?.response.etag === response.etag ? [...previous.pending] : [];
+    if (response.delta) pending.push(response.delta);
+    this.entries.delete(key);
+    this.entries.set(key, { response: { ...response, delta: null }, confirmedAt: this.now(), scope, pending });
+    while (this.entries.size > this.options.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) break;
+      this.entries.delete(oldest.value);
+    }
+  }
+  /**
+   * The deltas pending for `key`, joined, which then count as delivered: `null` when there are
+   * none, `undefined` when the key is not cached at all.
+   */
+  take(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    const delta = entry.pending.join("\n\n") || null;
+    entry.pending = [];
+    return delta;
+  }
+  delete(key) {
+    this.entries.delete(key);
+  }
+  /** Drops every pack of one conversation or task. */
+  deleteScope(scope) {
+    for (const [key, entry] of this.entries) {
+      if (entry.scope === scope) this.entries.delete(key);
+    }
+  }
+  clear() {
+    this.entries.clear();
+    this.epoch++;
+  }
+  /**
+   * Runs `load` for a key unless a request for the same key is already in flight, in which
+   * case every caller shares that one request. This is what keeps a burst of turns in one
+   * conversation, or a stale entry read by many callers, down to a single refresh.
+   */
+  dedupe(key, load) {
+    const running = this.inflight.get(key);
+    if (running) return running;
+    const started = load().finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, started);
+    return started;
+  }
+};
+
+// src/errors.ts
+var NiadraError = class extends Error {
+  name = "NiadraError";
+};
+var NiadraConfigError = class extends NiadraError {
+  name = "NiadraConfigError";
+};
+var NiadraValidationError = class extends NiadraError {
+  name = "NiadraValidationError";
+};
+var NiadraTimeoutError = class extends NiadraError {
+  constructor(timeoutMs) {
+    super(`request timed out after ${timeoutMs} ms`);
+    this.timeoutMs = timeoutMs;
+  }
+  timeoutMs;
+  name = "NiadraTimeoutError";
+};
+var NiadraConnectionError = class extends NiadraError {
+  name = "NiadraConnectionError";
+};
+var NiadraAbortError = class extends NiadraError {
+  name = "NiadraAbortError";
+};
+var NiadraAPIError = class extends NiadraError {
+  name = "NiadraAPIError";
+  status;
+  code;
+  requestId;
+  problem;
+  /** How long the server asked callers to wait, from `Retry-After`, when it said so. */
+  retryAfterMs;
+  constructor(status, problem, requestId, retryAfterMs = null) {
+    const code = problem?.code ?? `http_${status}`;
+    const detail = problem?.detail ? `: ${problem.detail}` : "";
+    super(`${status} ${code}${detail}`);
+    this.status = status;
+    this.code = code;
+    this.problem = problem;
+    this.requestId = requestId ?? problem?.request_id ?? null;
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var NiadraAuthenticationError = class extends NiadraAPIError {
+  name = "NiadraAuthenticationError";
+};
+var NiadraPermissionError = class extends NiadraAPIError {
+  name = "NiadraPermissionError";
+};
+var NiadraRateLimitError = class extends NiadraAPIError {
+  name = "NiadraRateLimitError";
+};
+function apiErrorFor(status, problem, requestId, retryAfterMs) {
+  if (status === 401) return new NiadraAuthenticationError(status, problem, requestId, retryAfterMs);
+  if (status === 403) return new NiadraPermissionError(status, problem, requestId, retryAfterMs);
+  if (status === 429) return new NiadraRateLimitError(status, problem, requestId, retryAfterMs);
+  return new NiadraAPIError(status, problem, requestId, retryAfterMs);
+}
+function toNiadraError(error) {
+  if (error instanceof NiadraError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new NiadraError(message, { cause: error });
+}
+
+// src/handles.ts
+function build(type, value, scope, options) {
+  const handle = { type, value };
+  if (scope !== void 0) handle.scope = scope;
+  if (options?.subjectKind !== void 0) handle.subject_kind = options.subjectKind;
+  return handle;
+}
+var handles = {
+  /** A phone number in E.164 form, such as `+5511987654321`. */
+  phone: (e164, options) => build("phone_e164", e164, void 0, options),
+  email: (address, options) => build("email", address, void 0, options),
+  /** The WhatsApp id (`wa_id`) the Cloud API reports for a contact. */
+  waId: (value, options) => build("wa_id", value, void 0, options),
+  waJid: (value, options) => build("wa_jid", value, void 0, options),
+  waLid: (value, options) => build("wa_lid", value, void 0, options),
+  /** A business-scoped WhatsApp user id; `businessAccount` is the WhatsApp Business account it belongs to. */
+  waBsuid: (value, businessAccount, options) => build("wa_bsuid", value, businessAccount, options),
+  /** The user id in your own app or site. */
+  appUserId: (value, options) => build("app_user_id", value, void 0, options),
+  /** The id of a person or organization in a system of record; `system` names that system, such as `crm`. */
+  systemId: (value, system, options) => build("system_id", value, system, options),
+  /** An HMAC of a national document number; `country` is its ISO 3166-1 alpha-2 code. */
+  govIdHmac: (value, country, options) => build("gov_id_hmac", value, country, options),
+  /** An HMAC of a company registry number. Identifies an organization. */
+  orgRegistryHmac: (value, country) => build("org_registry_hmac", value, country, { subjectKind: "account" }),
+  /** An e-mail domain, such as `acme.com`. Identifies an organization. */
+  emailDomain: (domain) => build("email_domain", domain, void 0, { subjectKind: "account" }),
+  /** An anonymous visitor or device id, before the person is known. */
+  anonId: (value, options) => build("anon_id", value, void 0, options)
+};
+function toObjectRef(object) {
+  if (typeof object !== "string") return object;
+  const first = object.indexOf(":");
+  const second = first < 0 ? -1 : object.indexOf(":", first + 1);
+  if (first <= 0 || second <= first + 1 || second === object.length - 1) {
+    throw new NiadraValidationError("object must look like `type:namespace:id`");
+  }
+  return { type: object.slice(0, first), namespace: object.slice(first + 1, second), id: object.slice(second + 1) };
+}
+
+// src/context.ts
+var VIEW = /^(voice|chat|brief|full|custom|account|partner|task:[a-z0-9_]{1,40})$/;
+var MAX_QUERY = 2e3;
+function buildContextRequest(params) {
+  if (params.subject === void 0 === (params.object === void 0)) {
+    throw new NiadraValidationError("pass exactly one of `subject` or `object`");
+  }
+  if (params.conversation_id && params.task_id) {
+    throw new NiadraValidationError("pass `conversation_id` or `task_id`, not both");
+  }
+  if (params.view !== void 0 && !VIEW.test(params.view)) {
+    throw new NiadraValidationError("unknown view; task views look like `task:billing`");
+  }
+  if (params.query !== void 0 && params.query.length > MAX_QUERY) {
+    throw new NiadraValidationError(`query is longer than ${MAX_QUERY} characters`);
+  }
+  const request = { view: params.view ?? "chat" };
+  if (params.subject) request.subject = params.subject;
+  if (params.object !== void 0) request.object = toObjectRef(params.object);
+  if (params.about) request.about = params.about;
+  if (params.verification) request.verification = params.verification;
+  if (params.conversation_id) request.conversation_id = params.conversation_id;
+  if (params.task_id) request.task_id = params.task_id;
+  if (params.query) request.query = params.query;
+  if (params.delta) request.delta = true;
+  if (params.target) request.target = params.target;
+  return request;
+}
+function cacheScope(request) {
+  if (request.conversation_id) return `conversation:${request.conversation_id}`;
+  if (request.task_id) return `task:${request.task_id}`;
+  return null;
+}
+function cacheKey(request) {
+  return JSON.stringify([
+    request.subject ?? null,
+    request.object ?? null,
+    request.about ?? null,
+    request.view ?? "chat",
+    request.verification ?? "V0",
+    request.conversation_id ?? null,
+    request.task_id ?? null,
+    request.query ?? null,
+    request.target ?? null
+  ]);
+}
+function mergeNotModified(cached, fresh) {
+  return {
+    ...fresh,
+    not_modified: false,
+    text: cached.text ?? null,
+    variables: cached.variables,
+    version: cached.version,
+    etag: cached.etag,
+    manifest_hash: cached.manifest_hash ?? null,
+    withheld: cached.withheld,
+    cache: cached.cache ?? null
+  };
+}
+function resultFrom(response, source, error = null) {
+  const text = response.path === "holdout" ? "" : response.text ?? "";
+  return { text, suffix: renderSuffix(response), variables: response.variables, source, response, error };
+}
+function emptyResult(error) {
+  return { text: "", suffix: "", variables: {}, source: "none", response: null, error };
+}
+function renderSuffix(response) {
+  if (response.path === "holdout") return "";
+  return [response.delta ?? "", renderLive(response)].filter(Boolean).join("\n\n");
+}
+function renderLive(response) {
+  if (response.path === "holdout" || response.live.length === 0) return "";
+  const complete = response.live_complete ? "" : ' complete="false"';
+  const lines = response.live.map(renderLiveTurn).join("\n");
+  return `<live_turns source="niadra"${complete}>
+${lines}
+</live_turns>`;
+}
+function renderLiveTurn(turn) {
+  return `[${utcSeconds(turn.at)}] ${turn.channel} \xB7 ${turn.speaker}: ${turn.text}`;
+}
+function utcSeconds(at) {
+  const ms = Date.parse(at);
+  return Number.isNaN(ms) ? at : `${new Date(ms).toISOString().slice(0, 19)}Z`;
+}
+
+// src/ids.ts
+var lastMs = -1;
+var counter = 0;
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues) {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return bytes;
+}
+function uuidv7(now = Date.now()) {
+  let ms = now;
+  if (ms <= lastMs) {
+    ms = lastMs;
+    counter = counter + 1 & 4095;
+    if (counter === 0) ms += 1;
+  } else {
+    counter = (randomBytes(2)[0] ?? 0) & 127;
+  }
+  lastMs = ms;
+  const bytes = randomBytes(16);
+  const high = Math.floor(ms / 2 ** 16);
+  const low = ms % 2 ** 16;
+  bytes[0] = high >>> 24 & 255;
+  bytes[1] = high >>> 16 & 255;
+  bytes[2] = high >>> 8 & 255;
+  bytes[3] = high & 255;
+  bytes[4] = low >>> 8 & 255;
+  bytes[5] = low & 255;
+  bytes[6] = 112 | counter >>> 8 & 15;
+  bytes[7] = counter & 255;
+  bytes[8] = 128 | (bytes[8] ?? 0) & 63;
+  let hex = "";
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// src/types/events.ts
+var MAX_EVENT_TEXT = 2e5;
+var MAX_BATCH_ITEMS = 500;
+var MAX_MEDIA_BYTES = 500 * 1024 * 1024;
+
+// src/items.ts
+var FEEDBACK_ACTIONS = [
+  "retract_fact",
+  "correct_fact",
+  "resolve_open_item",
+  "conversation_outcome"
+];
+var SHORT = 256;
+function fail(message) {
+  throw new NiadraValidationError(message);
+}
+function iso(value) {
+  if (value === void 0) return (/* @__PURE__ */ new Date()).toISOString();
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) fail("invalid Date");
+    return value.toISOString();
+  }
+  if (Number.isNaN(Date.parse(value))) fail("timestamps must be ISO 8601");
+  return value;
+}
+function short(value, field) {
+  if (value === void 0 || value === null) return;
+  if (value.length === 0 || value.length > SHORT) fail(`${field} must be 1 to ${SHORT} characters`);
+}
+function limit(list, max, field) {
+  if (list && list.length > max) fail(`${field} takes at most ${max} entries`);
+}
+function speakerRef(speaker) {
+  return typeof speaker === "string" ? { role: speaker } : speaker;
+}
+function checkCloses(closes) {
+  if (!closes) return;
+  const byId = Boolean(closes.item_id);
+  const byObject = Boolean(closes.object && closes.operation);
+  if (byId === byObject) fail("closes takes either item_id, or object and operation");
+}
+function checkContent(content) {
+  if (!content) return;
+  if ((content.text?.length ?? 0) > MAX_EVENT_TEXT) fail(`content.text is longer than ${MAX_EVENT_TEXT}`);
+  if ((content.transcript?.length ?? 0) > MAX_EVENT_TEXT) {
+    fail(`content.transcript is longer than ${MAX_EVENT_TEXT}`);
+  }
+}
+function buildEvent(input) {
+  if (input.text !== void 0 && input.content) fail("pass `text` or `content`, not both");
+  const kind = input.kind ?? "message";
+  const speaker = speakerRef(input.speaker);
+  const content = input.text !== void 0 ? { type: "text", text: input.text } : input.content ?? null;
+  short(input.channel, "channel");
+  checkContent(content);
+  limit(input.handles, 16, "handles");
+  limit(input.subjects, 8, "subjects");
+  limit(input.object_refs, 16, "object_refs");
+  limit(input.conversation_aliases, 8, "conversation_aliases");
+  if (kind === "action" && !input.action) fail("an action event needs the `action` block");
+  if (kind !== "action" && input.action) fail("`action` is only valid when kind is `action`");
+  if (kind === "system_event" && !input.canonical_type) fail("a system event needs `canonical_type`");
+  if (kind === "message" && !(content?.text || content?.media_ref || content?.transcript)) {
+    fail("a message needs text, a transcript or a media reference");
+  }
+  if (!hasTarget(input)) fail("an event needs at least one handle, subject or object");
+  if (input.action) {
+    short(input.action.operation, "action.operation");
+    if ((input.action.result?.length ?? 0) > 2e3) fail("action.result is longer than 2000");
+    checkCloses(input.action.closes);
+  }
+  const event = {
+    type: "event",
+    kind,
+    idempotency_key: input.idempotency_key ?? uuidv7(),
+    channel: input.channel,
+    speaker,
+    occurred_at: iso(input.occurred_at)
+  };
+  if (content) event.content = content;
+  const direction = input.direction ?? (kind === "message" ? defaultDirection(speaker.role) : void 0);
+  if (direction) event.direction = direction;
+  if (input.object_refs) event.object_refs = input.object_refs.map(toObjectRef);
+  if (input.canonical_type) event.canonical_type = input.canonical_type;
+  if (input.fields) event.fields = input.fields;
+  if (input.action) event.action = input.action;
+  copyOptional(event, input);
+  assertSerializable(event);
+  return event;
+}
+function buildAction(input) {
+  const { operation, result, purpose, closes, corrects_action_id, speaker, ...base } = input;
+  const action = { operation };
+  if (result !== void 0) action.result = result;
+  if (purpose !== void 0) action.purpose = purpose;
+  if (closes !== void 0) action.closes = closes;
+  if (corrects_action_id !== void 0) action.corrects_action_id = corrects_action_id;
+  return buildEvent({ ...base, kind: "action", speaker: speaker ?? "ai_agent", action });
+}
+function buildIdentify(input) {
+  if (input.handles.length < 2 || input.handles.length > 16) fail("identify takes 2 to 16 handles");
+  const item = {
+    type: "identify",
+    idempotency_key: input.idempotency_key ?? uuidv7(),
+    handles: input.handles,
+    method: input.method ?? "explicit_identify",
+    subject_kind: input.subject_kind ?? "person",
+    occurred_at: iso(input.occurred_at)
+  };
+  if (input.conversation_id) item.conversation_id = input.conversation_id;
+  return item;
+}
+function buildVerify(input) {
+  if (!input.handle) fail("verify needs the handle whose possession was proven");
+  if (input.conversation_id && input.task_id) fail("pass `conversation_id` or `task_id`, not both");
+  const item = {
+    type: "verify",
+    idempotency_key: input.idempotency_key ?? uuidv7(),
+    method: input.method,
+    level: input.level,
+    handle: input.handle,
+    occurred_at: iso(input.occurred_at)
+  };
+  if (input.conversation_id) item.conversation_id = input.conversation_id;
+  if (input.task_id) item.task_id = input.task_id;
+  if (input.valid_until) item.valid_until = iso(input.valid_until);
+  return item;
+}
+function buildHandoff(input) {
+  short(input.conversation_id, "conversation_id");
+  const item = {
+    type: "handoff",
+    idempotency_key: input.idempotency_key ?? uuidv7(),
+    conversation_id: input.conversation_id,
+    target: input.target,
+    mode: input.mode ?? "warm",
+    occurred_at: iso(input.occurred_at)
+  };
+  if (input.target_source) item.target_source = input.target_source;
+  if (input.reason) item.reason = input.reason;
+  return item;
+}
+function buildFeedback(input) {
+  if (!FEEDBACK_ACTIONS.includes(input.action)) fail(`action must be one of ${FEEDBACK_ACTIONS.join(", ")}`);
+  if ((input.value?.length ?? 0) > 2e3) fail("value is longer than 2000");
+  if ((input.reason?.length ?? 0) > 500) fail("reason is longer than 500");
+  const request = {
+    idempotency_key: input.idempotency_key ?? uuidv7(),
+    subject: input.subject,
+    action: input.action
+  };
+  if (input.fact_id) request.fact_id = input.fact_id;
+  if (input.open_item_id) request.open_item_id = input.open_item_id;
+  if (input.conversation_id) request.conversation_id = input.conversation_id;
+  if (input.value) request.value = input.value;
+  if (input.reason) request.reason = input.reason;
+  return request;
+}
+function buildConversationEnded(conversationId) {
+  return {
+    type: "conversation.ended",
+    idempotency_key: uuidv7(),
+    conversation_id: conversationId,
+    occurred_at: iso(void 0)
+  };
+}
+function buildTaskEnded(taskId) {
+  return { type: "task.ended", idempotency_key: uuidv7(), task_id: taskId, occurred_at: iso(void 0) };
+}
+function hasTarget(event) {
+  return [event.handles, event.subjects, event.object_refs].some((list) => (list?.length ?? 0) > 0);
+}
+function defaultDirection(role) {
+  if (role === "customer") return "inbound";
+  if (role === "ai_agent" || role === "human_agent") return "outbound";
+  return void 0;
+}
+function copyOptional(event, input) {
+  if (input.conversation_id) event.conversation_id = input.conversation_id;
+  if (input.conversation_aliases?.length) event.conversation_aliases = input.conversation_aliases;
+  if (input.task_id) event.task_id = input.task_id;
+  if (input.handles?.length) event.handles = input.handles;
+  if (input.subjects?.length) event.subjects = input.subjects;
+  if (input.visibility) event.visibility = input.visibility;
+  if (input.verification_hint) event.verification_hint = input.verification_hint;
+  if (input.corrects_event_id) event.corrects_event_id = input.corrects_event_id;
+  if (input.voice) event.voice = input.voice;
+  if (input.context_stamp) {
+    const { etag, injected_at } = input.context_stamp;
+    event.context_stamp = etag ? { etag, injected_at: iso(injected_at) } : { injected_at: iso(injected_at) };
+  }
+}
+function assertSerializable(event) {
+  try {
+    JSON.stringify(event);
+  } catch {
+    fail("event is not JSON-serializable (check `fields` for BigInt or circular values)");
+  }
+}
+var SessionState = class {
+  etag = null;
+  deltas = [];
+  stamp = null;
+  firstInjection = null;
+  firstAgentTurn = null;
+  last = null;
+  /** After the first pack, every read also asks what changed since. */
+  get wantsDelta() {
+    return this.etag !== null;
+  }
+  get lastContext() {
+    return this.last;
+  }
+  get contextStamp() {
+    return this.stamp;
+  }
+  get timings() {
+    return { contextInjectedAt: this.firstInjection, firstAgentTurnAt: this.firstAgentTurn };
+  }
+  /** Folds one `context()` result into the session and returns it with every delta since the pin. */
+  absorb(result) {
+    const response = result.response;
+    if (result.source === "none" || !response) {
+      this.reset();
+    } else if (response.etag !== this.etag) {
+      this.etag = response.etag;
+      this.deltas = [];
+    } else if (response.delta && !this.deltas.includes(response.delta)) {
+      this.deltas = [...this.deltas, response.delta].slice(-20);
+    }
+    const absorbed = response ? withDeltas(result, response, this.deltas) : result;
+    this.last = absorbed;
+    return absorbed;
+  }
+  /** Starts over from the next pack the server pins, as after a raised verification level. */
+  reset() {
+    this.etag = null;
+    this.deltas = [];
+  }
+  markInjected(context, at) {
+    const etag = (context ?? this.last)?.response?.etag;
+    this.firstInjection ??= at;
+    this.stamp = etag ? { etag, injected_at: at.toISOString() } : { injected_at: at.toISOString() };
+  }
+  /** Notes an agent turn and returns the stamp it carries, if context went in before it. */
+  agentTurn() {
+    this.firstAgentTurn ??= /* @__PURE__ */ new Date();
+    return this.stamp;
+  }
+  /** The stamp for an action, which only the AI agent took on the injected context. */
+  actionStamp(speaker) {
+    const role = typeof speaker === "string" ? speaker : speaker?.role ?? "ai_agent";
+    return role === "ai_agent" ? this.stamp : null;
+  }
+};
+function withDeltas(result, response, deltas) {
+  const merged = { ...response, delta: deltas.join("\n\n") || null };
+  return { ...result, response: merged, suffix: renderSuffix(merged) };
+}
+
+// src/conversation.ts
+var Conversation = class {
+  constructor(client, params, hooks) {
+    this.client = client;
+    this.params = params;
+    this.hooks = hooks;
+    this.id = params.conversation_id ?? uuidv7();
+    this.channel = params.channel;
+    this.subject = params.subject;
+    this.level = params.verification ?? "V0";
+    this.view = params.view ?? (params.channel === "voice" ? "voice" : "chat");
+  }
+  client;
+  params;
+  hooks;
+  id;
+  channel;
+  subject;
+  level;
+  view;
+  state = new SessionState();
+  ending = null;
+  /** The level in force for this conversation, raised by a successful `verify()`. */
+  get verification() {
+    return this.level;
+  }
+  /**
+   * 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() {
+    return this.state.timings;
+  }
+  /** What the agent's next turn and action carry: the last `markInjected()`, or `null`. */
+  get contextStamp() {
+    return this.state.contextStamp;
+  }
+  /** The last result `context()` returned for this conversation. */
+  get lastContext() {
+    return this.state.lastContext;
+  }
+  /** Where `wrap()` reports what it swallowed: the client's logger. */
+  get logger() {
+    return this.client.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.
+   */
+  async context(options = {}) {
+    const { query, ...requestOptions } = options;
+    const params = {
+      subject: this.subject,
+      view: this.view,
+      verification: this.level,
+      conversation_id: this.id,
+      ...this.params.about ? { about: this.params.about } : {},
+      ...this.params.target ? { target: this.params.target } : {}
+    };
+    if (query) return this.client.context({ ...params, query }, requestOptions);
+    if (this.state.wantsDelta) params.delta = true;
+    return this.state.absorb(await this.client.context(params, requestOptions));
+  }
+  /**
+   * 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, at = /* @__PURE__ */ new Date()) {
+    this.state.markInjected(context, at);
+  }
+  /** Captures what the customer said. */
+  customer(text, options = {}) {
+    return this.turn("customer", text, options);
+  }
+  /** Captures what the AI agent said, stamped with the context its prompt carried. */
+  agent(text, options = {}) {
+    const stamp = this.state.agentTurn();
+    return this.turn("ai_agent", text, stamp ? { context_stamp: stamp, ...options } : options);
+  }
+  /** Captures what a human attendant said, for example after a handoff. */
+  human(text, options = {}) {
+    return this.turn("human_agent", text, options);
+  }
+  /** Records any event in this conversation. The customer's handle is attached unless you pass your own. */
+  track(event) {
+    return this.client.track({ ...this.bind(event), ...event, channel: event.channel ?? this.channel });
+  }
+  /** Records an action the agent took during this conversation, stamped like its turns. */
+  action(event) {
+    const stamp = this.state.actionStamp(event.speaker);
+    return this.client.action({
+      ...this.bind(event),
+      ...stamp ? { context_stamp: stamp } : {},
+      ...event,
+      channel: event.channel ?? this.channel
+    });
+  }
+  /**
+   * Records that the customer proved who they are, and raises the level for later reads.
+   * `handle` defaults to the conversation's subject.
+   */
+  async verify(params) {
+    const result = await this.client.verify({
+      method: params.method,
+      level: params.level,
+      handle: params.handle ?? this.subject,
+      conversation_id: this.id
+    });
+    if (result.ok) {
+      this.level = params.level;
+      this.state.reset();
+    }
+    return result;
+  }
+  /** Records a transfer to a human or another agent. */
+  handoff(params) {
+    return this.client.handoff({ ...params, conversation_id: this.id });
+  }
+  /**
+   * 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() {
+    const read = () => this.level;
+    const binding = {
+      conversation_id: this.id,
+      voice: this.view === "voice",
+      get verification() {
+        return read();
+      }
+    };
+    if (this.params.about) binding.about = this.params.about;
+    return this.client.tools(this.subject, binding);
+  }
+  /** Emits `conversation.ended` and drops the conversation's cached packs. Safe to call twice. */
+  end() {
+    this.ending ??= this.hooks.endConversation(this.id);
+    return this.ending;
+  }
+  bind(event) {
+    const own = hasTarget(event);
+    return own ? { conversation_id: this.id } : { conversation_id: this.id, handles: [this.subject] };
+  }
+  turn(role, text, options) {
+    const transcript = options.stt_confidence !== void 0;
+    const content = transcript ? { type: "audio", transcript: text, stt_confidence: options.stt_confidence ?? null } : { type: "text", text };
+    const event = {
+      channel: this.channel,
+      conversation_id: this.id,
+      handles: [this.subject],
+      speaker: options.speaker_id ? { role, id: options.speaker_id } : { role },
+      content
+    };
+    if (options.idempotency_key) event.idempotency_key = options.idempotency_key;
+    if (options.occurred_at) event.occurred_at = options.occurred_at;
+    if (options.visibility) event.visibility = options.visibility;
+    if (options.voice) event.voice = options.voice;
+    if (options.context_stamp) event.context_stamp = options.context_stamp;
+    return this.client.track(event);
+  }
+};
+
+// src/exit.ts
+var registered = /* @__PURE__ */ new Set();
+var installedOn = null;
+function nodeProcess() {
+  const candidate = globalThis.process;
+  if (!candidate?.versions?.node) return null;
+  if (typeof candidate.on !== "function" || typeof candidate.removeListener !== "function") return null;
+  return candidate;
+}
+function onBeforeExit() {
+  for (const ref of registered) {
+    const client = ref.deref();
+    if (client) {
+      client.flush().catch(() => void 0);
+    } else {
+      registered.delete(ref);
+    }
+  }
+}
+function registerExitFlush(client) {
+  const proc = nodeProcess();
+  if (!proc || typeof WeakRef === "undefined") return () => void 0;
+  const ref = new WeakRef(client);
+  registered.add(ref);
+  if (!installedOn) {
+    proc.on("beforeExit", onBeforeExit);
+    installedOn = proc;
+  }
+  return () => {
+    registered.delete(ref);
+    if (registered.size === 0 && installedOn) {
+      installedOn.removeListener("beforeExit", onBeforeExit);
+      installedOn = null;
+    }
+  };
+}
+
+// src/media.ts
+async function prepareUpload(params) {
+  if (!params.content_type || params.content_type.length > 256) {
+    throw new NiadraValidationError("content_type must be 1 to 256 characters");
+  }
+  const bytes = await readBytes(params.data);
+  if (bytes.byteLength === 0 || bytes.byteLength > MAX_MEDIA_BYTES) {
+    throw new NiadraValidationError(`media must be 1 byte to ${MAX_MEDIA_BYTES} bytes`);
+  }
+  const request = {
+    content_type: params.content_type,
+    size_bytes: bytes.byteLength,
+    sha256: await sha256Hex(bytes)
+  };
+  if (params.subject) request.subject = params.subject;
+  return { bytes, request };
+}
+function checkUploadURL(url, baseURL) {
+  const protocol = new URL(url).protocol;
+  if (protocol === "https:" || protocol === "http:" && new URL(baseURL).protocol === "http:") return;
+  throw new NiadraValidationError("the upload URL is not HTTPS");
+}
+async function readBytes(data) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (data instanceof Uint8Array) {
+    return isPlain(data) ? data : new Uint8Array(data);
+  }
+  return new Uint8Array(await data.arrayBuffer());
+}
+function isPlain(view) {
+  return view.buffer instanceof ArrayBuffer;
+}
+async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new NiadraValidationError("uploadMedia() needs Web Crypto, which this runtime lacks");
+  const digest = new Uint8Array(await subtle.digest("SHA-256", bytes));
+  let hex = "";
+  for (const byte of digest) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+
+// src/objects.ts
+function objectPath(object) {
+  const ref = toObjectRef(object);
+  const segments = [ref.type, ref.namespace, ref.id];
+  if (segments.some((segment) => !segment || segment.includes("/"))) {
+    throw new NiadraValidationError("object type, namespace and id must be non-empty and cannot contain a slash");
+  }
+  return `/v1/objects/${segments.map(encodeURIComponent).join("/")}`;
+}
+
+// src/key.ts
+var PREFIX = "nia_sk_";
+var DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+var KEY_ID = /^[A-Za-z0-9]+$/;
+function parseApiKey(apiKey) {
+  if (!apiKey.startsWith(PREFIX)) return null;
+  const parts = apiKey.slice(PREFIX.length).split("_");
+  if (parts.length < 5) return null;
+  const [mode, region, space, keyId] = parts;
+  const secret = parts.slice(4).join("_");
+  if (mode !== "live" && mode !== "test") return null;
+  if (!DNS_LABEL.test(region) || !DNS_LABEL.test(space)) return null;
+  if (!KEY_ID.test(keyId) || secret.length === 0) return null;
+  return { mode, region, space, keyId };
+}
+function baseURLFromKey(key) {
+  return `https://${key.space}.${key.region}.api.niadra.com`;
+}
+
+// src/logger.ts
+var noop = () => void 0;
+var consoleLogger = {
+  debug: noop,
+  warn: (message, ...details) => {
+    console.warn(`[niadra] ${message}`, ...details);
+  },
+  error: (message, ...details) => {
+    console.error(`[niadra] ${message}`, ...details);
+  }
+};
+var silentLogger = { debug: noop, warn: noop, error: noop };
+
+// src/options.ts
+var DEFAULT_TIMEOUTS = {
+  context: 300,
+  contextVoice: 150,
+  navigation: 600,
+  navigationVoice: 300,
+  write: 5e3,
+  token: 2e3,
+  upload: 6e4
+};
+var DEFAULT_CACHE = {
+  ttlMs: 1e4,
+  staleWhileRevalidateMs: 10 * 6e4,
+  maxStaleMs: 30 * 6e4,
+  maxEntries: 1e3
+};
+var DEFAULT_QUEUE = {
+  flushAt: 15,
+  flushIntervalMs: 1e3,
+  maxBatchSize: 100,
+  maxQueueSize: 1e4,
+  maxAttempts: 3,
+  retryDelayMs: 250,
+  maxRetryDelayMs: 5e3
+};
+
+// src/queue.ts
+var HEARTBEAT_WINDOW_MS = 6e4;
+var EventQueue = class {
+  constructor(send, options, logger, now = Date.now) {
+    this.send = send;
+    this.options = options;
+    this.logger = logger;
+    this.now = now;
+    this.windowStart = now();
+  }
+  send;
+  options;
+  logger;
+  now;
+  items = [];
+  timer = null;
+  tail = Promise.resolve();
+  closed = false;
+  droppedSinceWarning = 0;
+  windowStart;
+  sentInWindow = 0;
+  /** Items waiting to be sent, not counting a batch already in flight. */
+  get size() {
+    return this.items.length;
+  }
+  /** Queues one item. Returns `false`, and settles it with an error, when the queue is full or closed. */
+  push(item, settle) {
+    if (this.closed || this.items.length >= this.options.maxQueueSize) {
+      this.droppedSinceWarning++;
+      if (this.droppedSinceWarning === 1) {
+        this.logger.warn(this.closed ? "client is shut down; dropping events" : "event queue is full; dropping events");
+      }
+      settle?.(new NiadraError(this.closed ? "client is shut down" : "event queue is full"));
+      return false;
+    }
+    this.droppedSinceWarning = 0;
+    this.items.push({ item, settle });
+    if (this.items.length >= this.options.flushAt) {
+      this.flushInBackground();
+    } else {
+      this.schedule();
+    }
+    return true;
+  }
+  /**
+   * Sends everything queued so far and resolves when it is done. Concurrent calls are
+   * serialized behind the batch already in flight rather than sending in parallel.
+   */
+  flush() {
+    this.cancelTimer();
+    const run = this.tail.then(() => this.drain());
+    this.tail = run.catch(() => void 0);
+    return run;
+  }
+  /**
+   * Starts a flush without waiting for it. Item failures are logged and settled inside the
+   * drain, so only an unexpected error reaches this catch.
+   */
+  flushInBackground() {
+    this.flush().catch((error) => {
+      this.logger.error(`event flush failed: ${toNiadraError(error).message}`);
+    });
+  }
+  /** Flushes, then refuses new items. */
+  async close() {
+    const report = await this.flush();
+    this.closed = true;
+    this.cancelTimer();
+    return report;
+  }
+  async drain() {
+    const report = { sent: 0, failed: 0, errors: [] };
+    while (this.items.length > 0) {
+      const batch = this.items.splice(0, this.options.maxBatchSize);
+      const heartbeat = this.heartbeat();
+      const wire = batch.map((pending) => pending.item);
+      if (heartbeat) wire.push(heartbeat);
+      await this.sendBatch(batch, wire, report);
+    }
+    return report;
+  }
+  async sendBatch(batch, wire, report) {
+    let response;
+    try {
+      response = await this.send(wire);
+    } catch (error) {
+      const failure = toNiadraError(error);
+      report.failed += batch.length;
+      report.errors.push(failure);
+      this.logger.warn(`dropped ${batch.length} events after retries: ${failure.message}`);
+      for (const pending of batch) pending.settle?.(failure);
+      return;
+    }
+    const rejected = /* @__PURE__ */ new Map();
+    for (const itemError of response.errors) {
+      const detail = itemError.detail ? `: ${itemError.detail}` : "";
+      rejected.set(itemError.index, new NiadraValidationError(`${itemError.code}${detail}`));
+    }
+    if (rejected.size > 0) {
+      const codes = [...new Set(response.errors.map((e) => e.code))].join(", ");
+      this.logger.warn(`server rejected ${rejected.size} of ${wire.length} items (${codes})`);
+    }
+    batch.forEach((pending, index) => {
+      const error = rejected.get(index) ?? null;
+      if (error) {
+        report.failed++;
+        report.errors.push(error);
+      } else {
+        report.sent++;
+        this.sentInWindow++;
+      }
+      pending.settle?.(error);
+    });
+  }
+  /**
+   * Once a minute, the next batch carries the number of items sent in the previous window.
+   * The server uses it to tell a source that went quiet from one whose events are being lost.
+   */
+  heartbeat() {
+    const now = this.now();
+    if (now - this.windowStart < HEARTBEAT_WINDOW_MS) return null;
+    const item = {
+      type: "heartbeat",
+      window_start: new Date(this.windowStart).toISOString(),
+      sent: this.sentInWindow
+    };
+    this.windowStart = now;
+    this.sentInWindow = 0;
+    return item;
+  }
+  schedule() {
+    if (this.timer !== null) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flushInBackground();
+    }, this.options.flushIntervalMs);
+    unref(this.timer);
+  }
+  cancelTimer() {
+    if (this.timer === null) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+function unref(timer) {
+  if (typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function") {
+    timer.unref();
+  }
+}
+
+// src/task.ts
+var Task = class {
+  constructor(client, params, hooks) {
+    this.client = client;
+    this.params = params;
+    this.hooks = hooks;
+    this.id = params.task_id ?? uuidv7();
+    this.object = params.object ?? null;
+    this.level = params.verification;
+  }
+  client;
+  params;
+  hooks;
+  id;
+  object;
+  level;
+  state = new SessionState();
+  ending = null;
+  /** When context first went into the prompt, and when the agent first acted. */
+  get timings() {
+    return this.state.timings;
+  }
+  /** What the agent's next turn and action carry: the last `markInjected()`, or `null`. */
+  get contextStamp() {
+    return this.state.contextStamp;
+  }
+  /** The last result `context()` returned for this task. */
+  get lastContext() {
+    return this.state.lastContext;
+  }
+  /** Where `wrap()` reports what it swallowed: the client's logger. */
+  get logger() {
+    return this.client.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.
+   */
+  async context(options = {}) {
+    const { query, ...requestOptions } = options;
+    const target = this.object ? { object: this.object } : this.params.subject ? { subject: this.params.subject } : {};
+    const params = {
+      ...target,
+      view: this.params.view ?? "brief",
+      task_id: this.id,
+      ...this.params.about ? { about: this.params.about } : {},
+      ...this.level ? { verification: this.level } : {},
+      ...this.params.target ? { target: this.params.target } : {}
+    };
+    if (query) return this.client.context({ ...params, query }, requestOptions);
+    if (this.state.wantsDelta) params.delta = true;
+    return this.state.absorb(await this.client.context(params, requestOptions));
+  }
+  /** Records that `context` (by default the last one this task returned) went into the prompt. */
+  markInjected(context, at = /* @__PURE__ */ new Date()) {
+    this.state.markInjected(context, at);
+  }
+  /** Captures what the agent answered, stamped with the context its prompt carried. */
+  agent(text, options = {}) {
+    const stamp = this.state.agentTurn();
+    const event = {
+      ...this.bind({}),
+      speaker: options.speaker_id ? { role: "ai_agent", id: options.speaker_id } : "ai_agent",
+      text
+    };
+    const context_stamp = options.context_stamp ?? stamp;
+    if (context_stamp) event.context_stamp = context_stamp;
+    if (options.idempotency_key) event.idempotency_key = options.idempotency_key;
+    if (options.occurred_at) event.occurred_at = options.occurred_at;
+    if (options.visibility) event.visibility = options.visibility;
+    return this.track(event);
+  }
+  /**
+   * 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.
+   */
+  async verify(params) {
+    const handle = params.handle ?? this.params.subject;
+    const result = await this.hooks.verifyTask({ method: params.method, level: params.level, handle, task_id: this.id });
+    if (result.ok) {
+      this.level = params.level;
+      this.state.reset();
+    }
+    return result;
+  }
+  /** Records an event in this task, attaching the task's subject and object unless you pass your own. */
+  track(event) {
+    return this.client.track({ ...this.bind(event), ...event, channel: event.channel ?? this.params.channel });
+  }
+  /** Records an action taken in a system of record, such as `credit` on an invoice, stamped like its turns. */
+  action(event) {
+    const stamp = this.state.actionStamp(event.speaker);
+    return this.client.action({
+      ...this.bind(event),
+      ...stamp ? { context_stamp: stamp } : {},
+      ...event,
+      channel: event.channel ?? this.params.channel
+    });
+  }
+  /**
+   * 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() {
+    const subject = this.params.subject;
+    if (!subject) return null;
+    const read = () => this.level ?? "V0";
+    const binding = {
+      task_id: this.id,
+      voice: this.params.view === "voice",
+      get verification() {
+        return read();
+      }
+    };
+    if (this.params.about) binding.about = this.params.about;
+    return this.client.tools(subject, binding);
+  }
+  /** Emits `task.ended` and drops the task's cached packs. Safe to call twice. */
+  end() {
+    this.ending ??= this.hooks.endTask(this.id);
+    return this.ending;
+  }
+  bind(event) {
+    const own = hasTarget(event);
+    const bound = {
+      task_id: this.id
+    };
+    if (own) return bound;
+    if (this.params.subject) bound.handles = [this.params.subject];
+    if (this.object) bound.object_refs = [this.object];
+    return bound;
+  }
+};
+
+// src/tools.ts
+var TOOL_NAMES = {
+  search: "search_customer_history",
+  timeline: "get_customer_timeline",
+  open: "open_history_item"
+};
+var ITEM_KINDS = ["episode", "fact", "open_item", "action", "system_event", "object", "trait"];
+var period = {
+  since: { type: "string", format: "date-time", description: "Only items at or after this ISO 8601 time." },
+  until: { type: "string", format: "date-time", description: "Only items before this ISO 8601 time." },
+  channels: {
+    type: "array",
+    items: { type: "string" },
+    description: "Only these channels, such as whatsapp, voice, email."
+  },
+  item_kinds: {
+    type: "array",
+    items: { type: "string", enum: ITEM_KINDS },
+    description: "Only these kinds of history items."
+  }
+};
+var TOOL_DEFINITIONS = [
+  {
+    type: "function",
+    function: {
+      name: TOOL_NAMES.search,
+      description: "Search this customer's past conversations, actions and system events by meaning and keywords. Use it when the customer refers to something that happened before and the details are not in the customer context you already have. Do not use it for facts already listed there. The result also says how often the same kind of issue came back. To read one result in full, call open_history_item.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "What to look for, in the customer's own terms." },
+          ...period,
+          categories: { type: "array", items: { type: "string" }, description: "Only these topics." },
+          outcome: { type: "string", description: "Only items with this outcome, such as resolved." }
+        },
+        required: ["query"],
+        additionalProperties: false
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: TOOL_NAMES.timeline,
+      description: "List this customer's history in chronological order, one line per item. Use it when you need the sequence of events, for example what happened since a given date. Prefer search_customer_history when you are looking for something specific.",
+      parameters: {
+        type: "object",
+        properties: {
+          ...period,
+          limit: { type: "integer", minimum: 1, maximum: 100, description: "How many items. Defaults to 20." },
+          cursor: { type: "string", description: "The next_cursor of a previous page." }
+        },
+        additionalProperties: false
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: TOOL_NAMES.open,
+      description: "Open one history item returned by search_customer_history or get_customer_timeline: its summary, what was requested, commitments made by either side, the outcome and the resolution. Only use ids returned by those tools.",
+      parameters: {
+        type: "object",
+        properties: { id: { type: "string", description: "The item id." } },
+        required: ["id"],
+        additionalProperties: false
+      }
+    }
+  }
+];
+function parseArgs(args) {
+  if (typeof args !== "string") return args;
+  if (args.trim() === "") return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(args);
+  } catch {
+    throw new NiadraValidationError("tool arguments are not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new NiadraValidationError("tool arguments must be a JSON object");
+  }
+  return parsed;
+}
+function str(args, name) {
+  const value = args[name];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function strings(args, name) {
+  const value = args[name];
+  if (!Array.isArray(value)) return void 0;
+  const list = value.filter((entry) => typeof entry === "string");
+  return list.length > 0 ? list : void 0;
+}
+function filtersFrom(args) {
+  const filters = {};
+  const since = str(args, "since");
+  const until = str(args, "until");
+  const channels = strings(args, "channels");
+  const categories = strings(args, "categories");
+  const kinds = strings(args, "item_kinds")?.filter(
+    (kind) => ITEM_KINDS.includes(kind)
+  );
+  const outcome = str(args, "outcome");
+  if (since) filters.since = since;
+  if (until) filters.until = until;
+  if (channels) filters.channels = channels;
+  if (categories) filters.categories = categories;
+  if (kinds?.length) filters.item_kinds = kinds;
+  if (outcome) filters.outcome = outcome;
+  return filters;
+}
+function bindTools(subject, binding, navigator, strict) {
+  const voice = binding.voice ?? false;
+  const names = new Set(Object.values(TOOL_NAMES));
+  async function run(name, args) {
+    switch (name) {
+      case TOOL_NAMES.search: {
+        const query = str(args, "query");
+        if (!query) throw new NiadraValidationError("search_customer_history needs a query");
+        const request = { subject, query, filters: filtersFrom(args) };
+        applyBinding(request, binding);
+        if (binding.task_id) request.task_id = binding.task_id;
+        const result = await navigator.search(request, voice);
+        return result.error ? result : { data: compactSearch(result.data), error: null };
+      }
+      case TOOL_NAMES.timeline: {
+        const request = { subject, filters: filtersFrom(args) };
+        applyBinding(request, binding);
+        const cursor = str(args, "cursor");
+        if (cursor) request.cursor = cursor;
+        const limit2 = args.limit;
+        if (typeof limit2 === "number" && Number.isInteger(limit2)) request.limit = Math.min(100, Math.max(1, limit2));
+        return navigator.timeline(request, voice);
+      }
+      case TOOL_NAMES.open: {
+        const id = str(args, "id");
+        if (!id) throw new NiadraValidationError("open_history_item needs an id");
+        return navigator.open(id, binding, voice);
+      }
+      default:
+        throw new NiadraValidationError(`unknown tool: ${name}`);
+    }
+  }
+  return {
+    definitions: TOOL_DEFINITIONS.map((definition) => cloneDefinition(definition)),
+    has: (name) => names.has(name),
+    async call(name, rawArgs) {
+      let result;
+      try {
+        result = await run(name, parseArgs(rawArgs));
+      } catch (error) {
+        if (strict) throw error;
+        return JSON.stringify({ error: "invalid_call", detail: error.message });
+      }
+      if (result.error) {
+        if (strict) throw result.error;
+        return JSON.stringify({ error: "unavailable", detail: "customer history is unavailable right now" });
+      }
+      return JSON.stringify(result.data);
+    }
+  };
+}
+function applyBinding(request, binding) {
+  if (binding.about) request.about = binding.about;
+  if (binding.verification) request.verification = binding.verification;
+  if (binding.conversation_id) request.conversation_id = binding.conversation_id;
+}
+function compactSearch(response) {
+  const { tokens_used: _, ...rest } = response;
+  return rest;
+}
+function cloneDefinition(definition) {
+  return JSON.parse(JSON.stringify(definition));
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/transport.ts
+var RETRYABLE_WRITE_STATUS = /* @__PURE__ */ new Set([408, 421, 429, 500, 502, 503, 504]);
+var READ_421_ATTEMPTS = 3;
+var READ_POLICY = { kind: "read", maxAttempts: READ_421_ATTEMPTS };
+var Transport = class {
+  constructor(config) {
+    this.config = config;
+    this.baseURL = config.baseURL.replace(/\/+$/, "");
+  }
+  config;
+  baseURL;
+  async request(spec) {
+    return spec.retry.kind === "read" ? this.read(spec, spec.retry) : this.write(spec, spec.retry);
+  }
+  async read(spec, policy) {
+    const deadline = new Deadline(spec.timeoutMs, spec.signal);
+    try {
+      for (let attempt = 1; ; attempt++) {
+        try {
+          return await this.send(spec, deadline);
+        } catch (error) {
+          if (isStatus(error, 421) && attempt < policy.maxAttempts && !deadline.expired) continue;
+          throw error;
+        }
+      }
+    } finally {
+      deadline.clear();
+    }
+  }
+  async write(spec, policy) {
+    return this.retrying(spec.timeoutMs, policy, spec.signal, (deadline) => this.send(spec, deadline));
+  }
+  /**
+   * Sends media bytes to the signed URL `POST /v1/media/uploads` returned, with the write retry
+   * rules. Only the headers the reservation named go along: the signature covers them (content
+   * type, and the digest the store checks the body against), and the key must never reach a
+   * host other than the API.
+   */
+  async upload(spec) {
+    await this.retrying(
+      spec.timeoutMs,
+      spec.retry,
+      spec.signal,
+      (deadline) => this.exchange(
+        spec.url,
+        { method: "PUT", headers: spec.headers, body: spec.body, signal: deadline.signal },
+        deadline
+      )
+    );
+  }
+  async retrying(timeoutMs, policy, signal, attempt) {
+    for (let count = 1; ; count++) {
+      const deadline = new Deadline(timeoutMs, signal);
+      try {
+        return await attempt(deadline);
+      } catch (error) {
+        if (count >= policy.maxAttempts || !isTransient(error)) throw error;
+        const delay = retryDelay(error, count, policy.baseDelayMs, policy.maxDelayMs);
+        await sleep(delay, signal);
+      } finally {
+        deadline.clear();
+      }
+    }
+  }
+  async send(spec, deadline) {
+    const headers = {
+      accept: "application/json, application/problem+json",
+      authorization: `Bearer ${this.config.apiKey}`,
+      "x-niadra-sdk": `js/${VERSION}`,
+      ...this.config.defaultHeaders,
+      ...spec.headers
+    };
+    const init = { method: spec.method, headers, signal: deadline.signal };
+    if (spec.body !== void 0) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(spec.body);
+    }
+    return this.exchange(this.url(spec.path, spec.query), init, deadline);
+  }
+  async exchange(url, init, deadline) {
+    let response;
+    try {
+      response = await this.config.fetch(url, init);
+    } catch (error) {
+      throw deadline.explain(error);
+    }
+    const requestId = response.headers.get("x-request-id");
+    let payload;
+    try {
+      payload = await readBody(response);
+    } catch (error) {
+      throw deadline.explain(error);
+    }
+    if (!response.ok) {
+      throw apiErrorFor(
+        response.status,
+        asProblem(payload),
+        requestId,
+        parseRetryAfter(response.headers.get("retry-after"))
+      );
+    }
+    return { status: response.status, data: payload, requestId };
+  }
+  url(path, query) {
+    const url = `${this.baseURL}${path}`;
+    if (!query) return url;
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value !== void 0) params.set(name, value);
+    }
+    const encoded = params.toString();
+    return encoded ? `${url}?${encoded}` : url;
+  }
+};
+var Deadline = class {
+  constructor(timeoutMs, outer) {
+    this.timeoutMs = timeoutMs;
+    this.outer = outer;
+    this.signal = this.controller.signal;
+    this.timer = setTimeout(() => {
+      this.timedOut = true;
+      this.controller.abort();
+    }, timeoutMs);
+    const onAbort = () => {
+      this.controller.abort();
+    };
+    if (outer?.aborted) this.controller.abort();
+    outer?.addEventListener("abort", onAbort, { once: true });
+    this.detach = () => {
+      outer?.removeEventListener("abort", onAbort);
+    };
+  }
+  timeoutMs;
+  outer;
+  signal;
+  controller = new AbortController();
+  timer;
+  detach;
+  timedOut = false;
+  get expired() {
+    return this.signal.aborted;
+  }
+  clear() {
+    clearTimeout(this.timer);
+    this.detach();
+  }
+  explain(error) {
+    if (this.timedOut) return new NiadraTimeoutError(this.timeoutMs);
+    if (this.outer?.aborted) return new NiadraAbortError("request aborted by the caller", { cause: error });
+    if (error instanceof NiadraError) return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new NiadraConnectionError(`connection failed: ${message}`, { cause: error });
+  }
+};
+async function readBody(response) {
+  const text = await response.text();
+  if (text.length === 0) return null;
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.includes("json")) return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function asProblem(payload) {
+  if (typeof payload !== "object" || payload === null) return null;
+  const candidate = payload;
+  if (typeof candidate.code !== "string" || typeof candidate.status !== "number") return null;
+  return candidate;
+}
+function isStatus(error, status) {
+  return error instanceof NiadraAPIError && error.status === status;
+}
+function isTransient(error) {
+  if (error instanceof NiadraTimeoutError || error instanceof NiadraConnectionError) return true;
+  return error instanceof NiadraAPIError && RETRYABLE_WRITE_STATUS.has(error.status);
+}
+function retryDelay(error, attempt, baseMs, maxMs) {
+  if (isStatus(error, 421)) return 0;
+  if (error instanceof NiadraAPIError && error.retryAfterMs !== null) return Math.min(error.retryAfterMs, maxMs);
+  const ceiling = Math.min(maxMs, baseMs * 2 ** (attempt - 1));
+  return Math.round(ceiling / 2 + Math.random() * ceiling / 2);
+}
+function parseRetryAfter(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(header);
+  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+function sleep(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new NiadraAbortError("request aborted by the caller"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/client.ts
+function readEnv(name) {
+  const env = globalThis.process?.env;
+  const value = env?.[name];
+  return value === "" ? void 0 : value;
+}
+function describe(error) {
+  if (error instanceof NiadraAPIError) {
+    return error.requestId ? `${error.message} (request ${error.requestId})` : error.message;
+  }
+  return `${error.name}: ${error.message}`;
+}
+var Niadra = class {
+  /** `false` when the client was built without a usable key and sends nothing. */
+  enabled;
+  core;
+  timeouts;
+  strict;
+  /** Where the client reports what it swallows in fail-open mode. */
+  logger;
+  disabledReason;
+  unregisterExit = () => void 0;
+  constructor(options = {}) {
+    this.strict = options.strict ?? false;
+    this.logger = options.logger ?? consoleLogger;
+    this.timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+    const setup = this.setup(options);
+    if (setup instanceof NiadraConfigError) {
+      if (this.strict) throw setup;
+      this.logger.warn(`${setup.message}; the client is disabled and will send nothing`);
+      this.core = null;
+      this.enabled = false;
+      this.disabledReason = setup;
+      return;
+    }
+    this.core = setup;
+    this.enabled = true;
+    this.disabledReason = null;
+    if (options.flushOnExit ?? true) this.unregisterExit = registerExitFlush(this);
+  }
+  setup(options) {
+    const apiKey = options.apiKey ?? readEnv("NIADRA_API_KEY");
+    if (!apiKey) return new NiadraConfigError("no API key: pass `apiKey` or set NIADRA_API_KEY");
+    let baseURL = options.baseURL ?? readEnv("NIADRA_BASE_URL");
+    if (!baseURL) {
+      const parsed = parseApiKey(apiKey);
+      if (!parsed) {
+        return new NiadraConfigError(
+          "the API key does not look like nia_sk_<live|test>_<region>_<space>_<key_id>_<secret>; pass `baseURL` to use it anyway"
+        );
+      }
+      baseURL = baseURLFromKey(parsed);
+    }
+    const fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch.bind(globalThis) : void 0);
+    if (!fetchImpl) return new NiadraConfigError("no fetch implementation: pass `fetch` on this runtime");
+    const transport = new Transport({
+      baseURL,
+      apiKey,
+      fetch: fetchImpl,
+      defaultHeaders: options.defaultHeaders ?? {}
+    });
+    const queueOptions = { ...DEFAULT_QUEUE, ...options.queue };
+    queueOptions.maxBatchSize = Math.min(queueOptions.maxBatchSize, 499);
+    const queue = new EventQueue(
+      (items) => this.sendBatch(transport, items, queueOptions.maxAttempts, queueOptions),
+      queueOptions,
+      this.logger
+    );
+    const cache = options.cache === false ? null : new ContextCache({ ...DEFAULT_CACHE, ...options.cache });
+    const writes = {
+      kind: "write",
+      maxAttempts: queueOptions.maxAttempts,
+      baseDelayMs: queueOptions.retryDelayMs,
+      maxDelayMs: queueOptions.maxRetryDelayMs
+    };
+    return { transport, queue, cache, baseURL, writes };
+  }
+  /**
+   * 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.
+   */
+  async context(params, options = {}) {
+    if (!this.core) return emptyResult(this.disabledReason);
+    let request;
+    try {
+      request = buildContextRequest(params);
+    } catch (error) {
+      return this.contextFailure(toNiadraError(error), null);
+    }
+    const timeout = options.timeout ?? (request.view === "voice" ? this.timeouts.contextVoice : this.timeouts.context);
+    const cache = options.cache === false ? null : this.core.cache;
+    const scope = cacheScope(request);
+    if (!cache || !scope) {
+      try {
+        const response = await this.fetchContext(this.core, request, timeout, options.signal, options.headers);
+        return resultFrom(response, "network");
+      } catch (error) {
+        const failure = toNiadraError(error);
+        this.observeAuth(failure, null);
+        return this.contextFailure(failure, null);
+      }
+    }
+    const key = cacheKey(request);
+    const hit = cache.lookup(key);
+    if (hit?.freshness === "fresh") return resultFrom(delivered(hit.response, cache.take(key)), "cache");
+    if (hit?.freshness === "stale") {
+      this.revalidate(this.core, cache, key, scope, request, timeout, options.headers).catch((error) => {
+        this.logger.debug(`background context refresh failed: ${describe(toNiadraError(error))}`);
+      });
+      return resultFrom(delivered(hit.response, cache.take(key)), "stale");
+    }
+    try {
+      const pending = this.revalidate(this.core, cache, key, scope, request, timeout, options.headers);
+      const { response, source } = await abortable(pending, options.signal);
+      return resultFrom(delivered(response, cache.take(key)), source);
+    } catch (error) {
+      const failure = toNiadraError(error);
+      const fallback = cache.lookup(key);
+      return this.contextFailure(failure, fallback ? delivered(fallback.response, cache.take(key)) : null);
+    }
+  }
+  /**
+   * 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.
+   */
+  async search(params, options = {}) {
+    return this.navigate(() => {
+      if (!params.query || params.query.length > 2e3) {
+        throw new NiadraValidationError("query must be 1 to 2000 characters");
+      }
+      return this.readSpec("POST", "/v1/history/search", params, this.timeouts.navigation, options);
+    });
+  }
+  /** The customer's history in chronological order, one line per item, paginated by cursor. */
+  async timeline(params, options = {}) {
+    return this.navigate(
+      () => this.readSpec("POST", "/v1/history/timeline", params, this.timeouts.navigation, options)
+    );
+  }
+  /**
+   * 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.
+   */
+  async open(id, params = {}, options = {}) {
+    return this.navigate(() => {
+      if (!id) throw new NiadraValidationError("open() needs an item id");
+      const path = `/v1/history/items/${encodeURIComponent(id)}`;
+      const spec = this.readSpec("GET", path, void 0, this.timeouts.navigation, options);
+      spec.query = {
+        verification: params.verification,
+        conversation_id: params.conversation_id,
+        task_id: params.task_id
+      };
+      return spec;
+    });
+  }
+  /**
+   * 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");
+   */
+  async objectState(object, options = {}) {
+    return this.navigate(() => this.readSpec("GET", objectPath(object), void 0, this.timeouts.navigation, options));
+  }
+  /**
+   * 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.
+   */
+  async objectTimeline(object, params = {}, options = {}) {
+    return this.navigate(() => {
+      const limit2 = params.limit ?? 20;
+      if (!Number.isInteger(limit2) || limit2 < 1 || limit2 > 100) {
+        throw new NiadraValidationError("limit must be between 1 and 100");
+      }
+      const path = `${objectPath(object)}/timeline`;
+      const spec = this.readSpec("GET", path, void 0, this.timeouts.navigation, options);
+      spec.query = { cursor: params.cursor, limit: String(limit2) };
+      return spec;
+    });
+  }
+  /**
+   * 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, binding = {}) {
+    const navigator = {
+      search: (params, voice) => this.search(params, this.voiceBudget(voice)),
+      timeline: (params, voice) => this.timeline(params, this.voiceBudget(voice)),
+      open: (id, bound, voice) => {
+        const scope = {};
+        if (bound.verification) scope.verification = bound.verification;
+        if (bound.conversation_id) scope.conversation_id = bound.conversation_id;
+        if (bound.task_id) scope.task_id = bound.task_id;
+        return this.open(id, scope, this.voiceBudget(voice));
+      }
+    };
+    return bindTools(subject, binding, navigator, this.strict);
+  }
+  /**
+   * 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.
+   */
+  async subjectToken(params, options = {}) {
+    return this.navigate(() => this.readSpec("POST", "/v1/subject-tokens", params, this.timeouts.token, options));
+  }
+  /**
+   * 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) {
+    return this.enqueue(() => buildEvent(event));
+  }
+  /**
+   * 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) {
+    return this.enqueue(() => buildAction(event));
+  }
+  /**
+   * 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) {
+    return this.sendNow(() => buildIdentify(params));
+  }
+  /**
+   * 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) {
+    return this.verifyWith(params);
+  }
+  /**
+   * 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`.
+   */
+  async feedback(params) {
+    const core = this.core;
+    if (!core) return { ok: false, idempotency_key: null, error: this.disabledError() };
+    let key = null;
+    try {
+      const request = buildFeedback(params);
+      key = request.idempotency_key;
+      const response = await core.transport.request({
+        method: "POST",
+        path: "/v1/feedback",
+        body: request,
+        headers: { "idempotency-key": key },
+        timeoutMs: this.timeouts.write,
+        retry: core.writes
+      });
+      const [rejected] = response.data?.errors ?? [];
+      if (rejected) {
+        throw new NiadraValidationError(`${rejected.code}${rejected.detail ? `: ${rejected.detail}` : ""}`);
+      }
+      return { ok: true, idempotency_key: key, error: null };
+    } catch (error) {
+      return { ok: false, idempotency_key: key, error: this.swallow(error, "feedback") };
+    }
+  }
+  /**
+   * 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 } });
+   */
+  async uploadMedia(params, options = {}) {
+    const core = this.core;
+    if (!core) return { data: null, error: this.disabledError() };
+    try {
+      const { bytes, request } = await prepareUpload(params);
+      const reserved = await core.transport.request({
+        method: "POST",
+        path: "/v1/media/uploads",
+        body: request,
+        timeoutMs: this.timeouts.write,
+        retry: core.writes,
+        signal: options.signal
+      });
+      const media_ref = reserved.data?.media_ref;
+      if (typeof media_ref !== "string") throw new NiadraError("unexpected response from /v1/media/uploads");
+      const url = reserved.data?.upload_url;
+      if (url) {
+        checkUploadURL(url, core.baseURL);
+        await core.transport.upload({
+          url,
+          body: bytes,
+          headers: uploadHeaders(reserved.data?.upload_headers, request.content_type),
+          timeoutMs: this.timeouts.upload,
+          retry: core.writes,
+          signal: options.signal
+        });
+      }
+      return {
+        data: {
+          media_ref,
+          media_sha256: request.sha256,
+          content_type: request.content_type,
+          size_bytes: request.size_bytes,
+          expires_at: reserved.data?.expires_at ?? null
+        },
+        error: null
+      };
+    } catch (error) {
+      return { data: null, error: this.swallow(error, "media upload") };
+    }
+  }
+  /** Records a transfer to a human or another agent. Sent right away, so the receiver can read context at once. */
+  handoff(params) {
+    return this.sendNow(() => buildHandoff(params));
+  }
+  /**
+   * A helper for one customer conversation: pins the pack across turns, captures turns and
+   * emits `conversation.ended` when you call `end()`.
+   */
+  conversation(params) {
+    return new Conversation(this, params, {
+      endConversation: (id) => this.endScope(buildConversationEnded(id), `conversation:${id}`)
+    });
+  }
+  /** A helper for one internal-agent task: binds `task_id` to reads and writes and emits `task.ended`. */
+  task(params) {
+    return new Task(this, params, {
+      endTask: (id) => this.endScope(buildTaskEnded(id), `task:${id}`),
+      verifyTask: (verify) => this.verifyWith(verify)
+    });
+  }
+  /**
+   * 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.
+   */
+  async flush() {
+    if (!this.core) return;
+    const report = await this.core.queue.flush();
+    const [first] = report.errors;
+    if (this.strict && first) throw first;
+  }
+  /**
+   * 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.
+   */
+  async shutdown() {
+    this.unregisterExit();
+    if (!this.core) return;
+    const report = await this.core.queue.close();
+    this.core.cache?.clear();
+    const [first] = report.errors;
+    if (this.strict && first) throw first;
+  }
+  async verifyWith(params) {
+    const result = await this.sendNow(() => buildVerify(params));
+    if (result.ok) {
+      if (params.conversation_id) this.forgetScope(`conversation:${params.conversation_id}`);
+      if (params.task_id) this.forgetScope(`task:${params.task_id}`);
+    }
+    return result;
+  }
+  /** Throws under `strict`; otherwise logs what failed, never with content, and returns the error. */
+  swallow(error, what) {
+    const failure = toNiadraError(error);
+    this.observeAuth(failure, null);
+    if (this.strict) throw failure;
+    this.logger.warn(`${what} failed: ${describe(failure)}`);
+    return failure;
+  }
+  voiceBudget(voice) {
+    return voice ? { timeout: this.timeouts.navigationVoice } : {};
+  }
+  readSpec(method, path, body, defaultTimeout, options) {
+    const spec = {
+      method,
+      path,
+      timeoutMs: options.timeout ?? defaultTimeout,
+      retry: READ_POLICY,
+      signal: options.signal,
+      headers: options.headers
+    };
+    if (body !== void 0) spec.body = body;
+    return spec;
+  }
+  async navigate(build2) {
+    if (!this.core) return { data: null, error: this.disabledError() };
+    try {
+      const response = await this.core.transport.request(build2());
+      return { data: response.data, error: null };
+    } catch (error) {
+      const failure = toNiadraError(error);
+      this.observeAuth(failure, null);
+      if (this.strict) throw failure;
+      this.logger.warn(`read failed: ${describe(failure)}`);
+      return { data: null, error: failure };
+    }
+  }
+  async fetchContext(core, request, timeout, signal, headers) {
+    const response = await core.transport.request(
+      this.readSpec("POST", "/v1/context", request, timeout, { signal, headers })
+    );
+    return normalizeContext(response.data);
+  }
+  /**
+   * 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.
+   */
+  revalidate(core, cache, key, scope, request, timeout, headers) {
+    return cache.dedupe(key, async () => {
+      const cached = cache.lookup(key);
+      const generation = cache.generation;
+      const body = cached ? { ...request, known_etag: cached.response.etag } : request;
+      try {
+        const response = await this.fetchContext(core, body, timeout, void 0, headers);
+        if (response.degraded && !response.not_modified && cached) {
+          return { response: cached.response, source: "fallback" };
+        }
+        const merged = response.not_modified && cached ? mergeNotModified(cached.response, response) : response;
+        cache.store(key, scope, merged, generation);
+        return { response: merged, source: "network" };
+      } catch (error) {
+        this.observeAuth(toNiadraError(error), key);
+        throw error;
+      }
+    });
+  }
+  contextFailure(error, fallback) {
+    if (this.strict) throw error;
+    if (fallback) {
+      this.logger.warn(`context request failed, serving the last good pack: ${describe(error)}`);
+      return resultFrom(fallback, "fallback", error);
+    }
+    this.logger.warn(`context unavailable: ${describe(error)}`);
+    return emptyResult(error);
+  }
+  /**
+   * 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.
+   */
+  observeAuth(error, key) {
+    const cache = this.core?.cache;
+    if (!cache) return;
+    if (error instanceof NiadraAuthenticationError) cache.clear();
+    else if (error instanceof NiadraPermissionError && key) cache.delete(key);
+  }
+  forgetScope(scope) {
+    this.core?.cache?.deleteScope(scope);
+  }
+  disabledError() {
+    return this.disabledReason ?? new NiadraConfigError("client is disabled");
+  }
+  enqueue(build2) {
+    if (!this.core) return null;
+    let item;
+    try {
+      item = build2();
+    } catch (error) {
+      const failure = toNiadraError(error);
+      if (this.strict) throw failure;
+      this.logger.warn(`event dropped: ${failure.message}`);
+      return null;
+    }
+    const accepted = this.core.queue.push(item);
+    return accepted && "idempotency_key" in item ? item.idempotency_key : null;
+  }
+  sendNow(build2) {
+    const core = this.core;
+    if (!core) return Promise.resolve({ ok: false, idempotency_key: null, error: this.disabledError() });
+    let item;
+    try {
+      item = build2();
+    } catch (error) {
+      const failure = toNiadraError(error);
+      if (this.strict) return Promise.reject(failure);
+      this.logger.warn(`write dropped: ${failure.message}`);
+      return Promise.resolve({ ok: false, idempotency_key: null, error: failure });
+    }
+    return new Promise((resolve, reject) => {
+      const key = item.idempotency_key;
+      core.queue.push(item, (error) => {
+        if (!error) resolve({ ok: true, idempotency_key: key, error: null });
+        else if (this.strict) reject(error);
+        else resolve({ ok: false, idempotency_key: key, error });
+      });
+      core.queue.flushInBackground();
+    });
+  }
+  async endScope(item, scope) {
+    const result = await this.sendNow(() => item);
+    this.forgetScope(scope);
+    return result;
+  }
+  async sendBatch(transport, items, maxAttempts, backoff) {
+    try {
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/batch",
+        body: { items },
+        timeoutMs: this.timeouts.write,
+        retry: { kind: "write", maxAttempts, baseDelayMs: backoff.retryDelayMs, maxDelayMs: backoff.maxRetryDelayMs }
+      });
+      const data = response.data;
+      return { accepted: data?.accepted ?? items.length, duplicates: data?.duplicates ?? 0, errors: data?.errors ?? [] };
+    } catch (error) {
+      const failure = toNiadraError(error);
+      this.observeAuth(failure, null);
+      throw failure;
+    }
+  }
+};
+function normalizeContext(data) {
+  if (typeof data !== "object" || data === null) throw new NiadraError("unexpected response from /v1/context");
+  const body = data;
+  if (typeof body.etag !== "string" || typeof body.path !== "string" || !body.verification) {
+    throw new NiadraError("unexpected response from /v1/context");
+  }
+  return {
+    ...body,
+    etag: body.etag,
+    path: body.path,
+    verification: body.verification,
+    version: body.version ?? "",
+    not_modified: body.not_modified ?? false,
+    variables: body.variables ?? {},
+    coverage: body.coverage ?? [],
+    live: body.live ?? [],
+    live_complete: body.live_complete ?? true,
+    timing: body.timing ?? {},
+    withheld: body.withheld ?? 0,
+    degraded: body.degraded ?? false
+  };
+}
+function uploadHeaders(named, contentType) {
+  return named && Object.keys(named).length > 0 ? { ...named } : { "content-type": contentType };
+}
+function delivered(response, taken) {
+  return taken === void 0 ? response : { ...response, delta: taken };
+}
+function abortable(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(new NiadraAbortError("request aborted by the caller"));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      reject(new NiadraAbortError("request aborted by the caller"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error instanceof Error ? error : new NiadraError(String(error)));
+      }
+    );
+  });
+}
+
+// src/wrap.ts
+var INSTRUCTION_ROLES = /* @__PURE__ */ new Set(["system", "developer"]);
+var INTERCEPTED = ["create", "parse"];
+function wrap(client, session) {
+  const resolve = typeof session === "function" ? session : () => session;
+  const chat = property(client, "chat");
+  if (!isRecord(chat) || !isRecord(chat.completions)) {
+    throw new TypeError("wrap() expects an OpenAI-compatible client with chat.completions");
+  }
+  const overrides = { chat: wrapChat(chat, resolve) };
+  const beta = property(client, "beta");
+  const betaChat = isRecord(beta) ? beta.chat : void 0;
+  if (isRecord(beta) && isRecord(betaChat) && isRecord(betaChat.completions)) {
+    overrides.beta = overlay(beta, { chat: wrapChat(betaChat, resolve) });
+  }
+  return overlay(client, overrides);
+}
+function injectContext(context, messages) {
+  const result = [...messages];
+  if (context.text) {
+    let position = 0;
+    while (position < result.length && INSTRUCTION_ROLES.has(roleOf(result[position]))) position++;
+    result.splice(position, 0, { role: "system", content: context.text });
+  }
+  if (context.suffix) result.push({ role: "system", content: context.suffix });
+  return result;
+}
+function wrapChat(chat, resolve) {
+  const completions = chat.completions;
+  const overrides = {};
+  for (const name of INTERCEPTED) {
+    const method = completions[name];
+    if (typeof method === "function") overrides[name] = intercept(method.bind(completions), resolve);
+  }
+  return overlay(chat, { completions: overlay(completions, overrides) });
+}
+function intercept(original, resolve) {
+  return (body, ...rest) => {
+    let session;
+    try {
+      session = resolve();
+    } catch {
+      session = null;
+    }
+    if (!session || !isRecord(body)) return original(body, ...rest);
+    const answer = new Answer(session, body.stream === true);
+    const started = prepare(session, body).then((prepared) => ({ call: original(prepared, ...rest) }));
+    return new PendingCall(started, answer);
+  };
+}
+async function prepare(session, body) {
+  try {
+    const context = await session.context();
+    if (!Array.isArray(body.messages)) return body;
+    const messages = injectContext(context, body.messages);
+    if (context.text || context.suffix || context.response?.path === "holdout") session.markInjected(context);
+    return { ...body, messages };
+  } catch (error) {
+    session.logger.warn(`could not inject context (${errorName(error)})`);
+    return body;
+  }
+}
+var PendingCall = class {
+  constructor(started, answer) {
+    this.started = started;
+    this.answer = answer;
+    started.catch(() => void 0);
+  }
+  started;
+  answer;
+  result = null;
+  then(onfulfilled, onrejected) {
+    return this.value().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.value().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.value().finally(onfinally);
+  }
+  async withResponse() {
+    const { call } = await this.started;
+    const withResponse = property(call, "withResponse");
+    if (typeof withResponse !== "function") throw new TypeError("this client's calls have no withResponse()");
+    const settled = await withResponse.call(call);
+    if (!isRecord(settled)) return settled;
+    return { ...settled, data: this.answer.parsed(settled.data) };
+  }
+  async asResponse() {
+    const { call } = await this.started;
+    const asResponse = property(call, "asResponse");
+    if (typeof asResponse !== "function") throw new TypeError("this client's calls have no asResponse()");
+    return asResponse.call(call);
+  }
+  value() {
+    this.result ??= this.started.then(({ call }) => call).then((value) => this.answer.parsed(value));
+    return this.result;
+  }
+};
+var Answer = class {
+  constructor(session, stream) {
+    this.session = session;
+    this.stream = stream;
+  }
+  session;
+  stream;
+  recorded = false;
+  /** What to hand back in place of `value`. Never throws. */
+  parsed(value) {
+    try {
+      if (!this.stream) {
+        this.record(messageText(value));
+        return value;
+      }
+      return isAsyncIterable(value) ? captureStream(value, (text) => {
+        this.record(text);
+      }) : value;
+    } catch (error) {
+      this.session.logger.warn(`could not capture the model's answer (${errorName(error)})`);
+      return value;
+    }
+  }
+  record(text) {
+    if (this.recorded || !text) return;
+    this.recorded = true;
+    try {
+      this.session.agent(text);
+    } catch (error) {
+      this.session.logger.warn(`could not record the model's answer (${errorName(error)})`);
+    }
+  }
+};
+function captureStream(stream, done) {
+  const parts = [];
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    done(parts.join(""));
+  };
+  return new Proxy(stream, {
+    get(target, prop) {
+      if (prop === Symbol.asyncIterator) {
+        return () => {
+          const inner = target[Symbol.asyncIterator]();
+          return {
+            async next() {
+              try {
+                const step = await inner.next();
+                if (step.done) finish();
+                else parts.push(deltaText(step.value));
+                return step;
+              } catch (error) {
+                finish();
+                throw error;
+              }
+            },
+            async return(value2) {
+              finish();
+              return inner.return ? inner.return(value2) : { done: true, value: value2 };
+            }
+          };
+        };
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function firstChoice(value) {
+  const choices = property(value, "choices");
+  if (!Array.isArray(choices)) return void 0;
+  return choices.find(
+    (choice) => isRecord(choice) && (choice.index === void 0 || choice.index === 0)
+  );
+}
+function messageText(response) {
+  const content = property(firstChoice(response)?.message, "content");
+  return typeof content === "string" && content ? content : null;
+}
+function deltaText(chunk) {
+  const content = property(firstChoice(chunk)?.delta, "content");
+  return typeof content === "string" ? content : "";
+}
+function overlay(target, overrides) {
+  return new Proxy(target, {
+    get(obj, prop) {
+      if (Object.prototype.hasOwnProperty.call(overrides, prop)) return overrides[prop];
+      const value = Reflect.get(obj, prop, obj);
+      return typeof value === "function" ? value.bind(obj) : value;
+    }
+  });
+}
+function property(value, name) {
+  return isRecord(value) ? value[name] : void 0;
+}
+function isRecord(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+function isAsyncIterable(value) {
+  return isRecord(value) && typeof value[Symbol.asyncIterator] === "function";
+}
+function roleOf(message) {
+  const role = property(message, "role");
+  return typeof role === "string" ? role : "";
+}
+function errorName(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+
+exports.Conversation = Conversation;
+exports.DEFAULT_CACHE = DEFAULT_CACHE;
+exports.DEFAULT_QUEUE = DEFAULT_QUEUE;
+exports.DEFAULT_TIMEOUTS = DEFAULT_TIMEOUTS;
+exports.MAX_BATCH_ITEMS = MAX_BATCH_ITEMS;
+exports.MAX_EVENT_TEXT = MAX_EVENT_TEXT;
+exports.MAX_MEDIA_BYTES = MAX_MEDIA_BYTES;
+exports.Niadra = Niadra;
+exports.NiadraAPIError = NiadraAPIError;
+exports.NiadraAbortError = NiadraAbortError;
+exports.NiadraAuthenticationError = NiadraAuthenticationError;
+exports.NiadraConfigError = NiadraConfigError;
+exports.NiadraConnectionError = NiadraConnectionError;
+exports.NiadraError = NiadraError;
+exports.NiadraPermissionError = NiadraPermissionError;
+exports.NiadraRateLimitError = NiadraRateLimitError;
+exports.NiadraTimeoutError = NiadraTimeoutError;
+exports.NiadraValidationError = NiadraValidationError;
+exports.TOOL_DEFINITIONS = TOOL_DEFINITIONS;
+exports.TOOL_NAMES = TOOL_NAMES;
+exports.Task = Task;
+exports.VERSION = VERSION;
+exports.baseURLFromKey = baseURLFromKey;
+exports.consoleLogger = consoleLogger;
+exports.handles = handles;
+exports.injectContext = injectContext;
+exports.parseApiKey = parseApiKey;
+exports.renderLive = renderLive;
+exports.renderSuffix = renderSuffix;
+exports.silentLogger = silentLogger;
+exports.toObjectRef = toObjectRef;
+exports.uuidv7 = uuidv7;
+exports.wrap = wrap;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map