@telemai/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,749 @@
+// src/errors.ts
+var TelemError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "TelemError";
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+};
+var TimeoutError = class extends TelemError {
+  constructor(message, cause) {
+    super(message, { code: "timeout", cause });
+    this.name = "TimeoutError";
+  }
+};
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://router.telem.ai";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+var BLANK = /^[ \t\n\r\v\f\u00a0\ufeff\u3000]+|[ \t\n\r\v\f\u00a0\ufeff\u3000]+$/g;
+function trimBlank(value) {
+  return value.replace(BLANK, "");
+}
+function csvEnv(raw) {
+  if (raw === void 0) return void 0;
+  const items = raw.split(",").map(trimBlank).filter((item) => item !== "");
+  return items.length ? items : void 0;
+}
+function readCredentials(env) {
+  try {
+    const proc = globalThis.process;
+    if (typeof proc?.getBuiltinModule !== "function") return {};
+    const home = trimBlank(env.HOME || env.USERPROFILE || "");
+    const dir = trimBlank(env.TELEM_CONFIG_DIR || "") || home && `${home}/.telem`;
+    if (!dir) return {};
+    const path = `${dir.replace(/[/\\]+$/, "")}/credentials.json`;
+    const bytes = proc.getBuiltinModule("node:fs").readFileSync(path);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const data = JSON.parse(text.replace(/^\ufeff/, ""));
+    if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+    const out = {};
+    for (const key of ["apiKey", "baseUrl"]) {
+      const value = data[key];
+      if (typeof value !== "string") continue;
+      const trimmed = trimBlank(value);
+      if (trimmed) out[key] = trimmed;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function invalidOption(message) {
+  return new TelemError(message, { code: "invalid_request" });
+}
+function resolveConfig(options) {
+  const opts = typeof options === "string" ? { apiKey: options } : options;
+  const env = globalThis.process?.env ?? {};
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (typeof timeoutMs !== "number" || !(timeoutMs > 0)) {
+    throw invalidOption(`timeoutMs must be a positive number of milliseconds (Infinity for no timeout), got ${String(timeoutMs)}`);
+  }
+  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+    throw invalidOption(`maxRetries must be a whole number of retries, got ${String(maxRetries)}`);
+  }
+  const send = opts.fetch ?? globalThis.fetch;
+  if (typeof send !== "function") {
+    throw invalidOption("no fetch on this runtime: pass one with the `fetch` option");
+  }
+  let apiKey = opts.apiKey || env.TELEM_API_KEY || void 0;
+  let baseUrl = opts.baseUrl || env.TELEM_BASE_URL || void 0;
+  if (apiKey === void 0 || baseUrl === void 0) {
+    const credentials = readCredentials(env);
+    apiKey = apiKey ?? credentials.apiKey;
+    baseUrl = baseUrl ?? credentials.baseUrl;
+  }
+  const resolvedBaseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  let scheme;
+  try {
+    scheme = new URL(resolvedBaseUrl).protocol;
+  } catch {
+    scheme = void 0;
+  }
+  if (scheme !== "http:" && scheme !== "https:") {
+    throw invalidOption(`baseUrl must be an http(s) URL, got ${JSON.stringify(resolvedBaseUrl)}`);
+  }
+  return {
+    apiKey,
+    baseUrl: resolvedBaseUrl,
+    timeoutMs,
+    maxRetries,
+    userAgent: opts.userAgent || `telem-sdk-js/${VERSION}`,
+    fetch: send,
+    sleep: opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    // Search defaults: constructor option, else env var, else unset. Only `undefined`
+    // is unset — `[]`/`false` are explicit values sent to the server verbatim.
+    // numResults/includeRaw/providerOverrides are per-call intent and are not read
+    // here at all, so passing one as a client default is inert.
+    defaults: {
+      tier: opts.tier ?? (env.TELEM_TIER || void 0),
+      fields: opts.fields ?? csvEnv(env.TELEM_FIELDS),
+      providersInclude: opts.providersInclude ?? csvEnv(env.TELEM_PROVIDERS_INCLUDE),
+      providersExclude: opts.providersExclude ?? csvEnv(env.TELEM_PROVIDERS_EXCLUDE),
+      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0)
+    }
+  };
+}
+
+// src/http.ts
+var MAX_DELAY_MS = 3e4;
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
+var BASE_DELAY_MS = 500;
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asObject(value) {
+  return isObject(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function invalidRequest(message) {
+  return new TelemError(message, { code: "invalid_request" });
+}
+function stringList(items, empty, what) {
+  const list = asArray(items);
+  if (!list.length) throw invalidRequest(empty);
+  for (const item of list) {
+    if (typeof item !== "string") {
+      throw invalidRequest(`${what} must be strings, got ${item === null ? "null" : typeof item}`);
+    }
+    if (item === "") throw invalidRequest(`${what} must not be empty`);
+  }
+  return list;
+}
+function errorEnvelope(body) {
+  if (!isObject(body)) return void 0;
+  if (isObject(body.error)) return body.error;
+  if (isObject(body.detail)) return body.detail;
+  return void 0;
+}
+function detailFromBody(body) {
+  if (!isObject(body)) return void 0;
+  const envelope = errorEnvelope(body);
+  if (envelope && typeof envelope.message === "string" && envelope.message) {
+    return envelope.message;
+  }
+  const detail = body.detail;
+  if (typeof detail === "string" && detail) return detail;
+  if (Array.isArray(detail) && detail.length) {
+    const messages = detail.map((item) => isObject(item) && typeof item.msg === "string" ? item.msg : void 0).filter((message) => message !== void 0);
+    return messages.join(", ") || JSON.stringify(detail);
+  }
+  return void 0;
+}
+function codeFromBody(body) {
+  const envelope = errorEnvelope(body);
+  return envelope && typeof envelope.code === "string" ? envelope.code : void 0;
+}
+function isResponseLike(value) {
+  return isObject(value) && typeof value.text === "function" && typeof value.status === "number" && typeof value.headers?.get === "function";
+}
+var NotAResponse = class extends Error {
+};
+function defaultMessage(status) {
+  if (status === 400) return "Bad request";
+  if (status === 401 || status === 403) return "Authentication failed";
+  if (status === 404) return "Not found";
+  return `Unexpected status code ${status}`;
+}
+function statusError(status, body) {
+  return new TelemError(detailFromBody(body) ?? defaultMessage(status), {
+    status,
+    code: codeFromBody(body),
+    details: body
+  });
+}
+function connectionError(url, cause) {
+  const error = cause;
+  const detail = typeof error?.cause?.message === "string" && error.cause.message || typeof error?.message === "string" && error.message || String(cause);
+  return new TelemError(`could not reach ${url}: ${detail}`, {
+    code: "connection_error",
+    cause
+  });
+}
+function isRetryable(status) {
+  return status >= 500 || status === 429;
+}
+function backoff(attempt) {
+  return Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+}
+function retryDelay(retryAfter, attempt) {
+  if (retryAfter !== null && /^\s*\d+\s*$/.test(retryAfter)) {
+    return Math.min(Number(retryAfter) * 1e3, MAX_DELAY_MS);
+  }
+  return backoff(attempt);
+}
+async function request(config, method, path, body) {
+  const url = `${config.baseUrl}/${path.replace(/^\/+/, "")}`;
+  const headers = { "User-Agent": config.userAgent };
+  if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+  const init = { method, headers };
+  if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    try {
+      init.body = JSON.stringify(body);
+    } catch (cause) {
+      throw invalidRequest(`request body is not JSON: ${cause?.message ?? String(cause)}`);
+    }
+  }
+  for (let attempt = 0; ; attempt++) {
+    const signal = Number.isFinite(config.timeoutMs) ? AbortSignal.timeout(Math.min(config.timeoutMs, MAX_TIMEOUT_MS)) : void 0;
+    let onAbort = () => {
+    };
+    const deadline = signal && new Promise((_, reject) => {
+      onAbort = () => reject(signal.reason);
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const race = (work) => deadline ? Promise.race([work, deadline]) : work;
+    let received;
+    try {
+      const response = await race(config.fetch(url, { ...init, signal }));
+      if (!isResponseLike(response)) throw new NotAResponse();
+      const text = await race(response.text());
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+      received = {
+        status: response.status,
+        retryAfter: response.headers.get("retry-after"),
+        body: parsed
+      };
+    } catch (cause) {
+      if (cause instanceof NotAResponse) {
+        throw new TelemError("the injected fetch returned something that is not a Response", {
+          code: "connection_error"
+        });
+      }
+      if (signal?.aborted) {
+        throw new TimeoutError(`request to ${url} timed out after ${config.timeoutMs}ms`, cause);
+      }
+      if (attempt >= config.maxRetries) throw connectionError(url, cause);
+      await config.sleep(backoff(attempt));
+      continue;
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
+    if (received.status >= 200 && received.status < 300) return received.body;
+    if (isRetryable(received.status) && attempt < config.maxRetries) {
+      await config.sleep(retryDelay(received.retryAfter, attempt));
+      continue;
+    }
+    throw statusError(received.status, received.body);
+  }
+}
+
+// src/trajectory.ts
+var NS_TRAJECTORY = "443866ab-1b45-5ed8-979e-52fdad07b810";
+var NONE = "none";
+var RESERVED_METADATA = /* @__PURE__ */ new Set([
+  "message_history",
+  "session_key",
+  "fingerprint",
+  "node_key",
+  "kind",
+  "parent_node_key",
+  "ancestors"
+]);
+var ENCODER = new TextEncoder();
+var NAMESPACE_BYTES = Uint8Array.from(
+  NS_TRAJECTORY.replaceAll("-", "").match(/../g) ?? [],
+  (pair) => parseInt(pair, 16)
+);
+function hex(bytes) {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+async function digest(algorithm, bytes) {
+  return new Uint8Array(await crypto.subtle.digest(algorithm, bytes));
+}
+async function sha256(value) {
+  return hex(await digest("SHA-256", ENCODER.encode(value)));
+}
+function lp(value) {
+  return `${ENCODER.encode(value).length}:${value}`;
+}
+async function uuid5(name) {
+  const encoded = ENCODER.encode(name);
+  const input = new Uint8Array(NAMESPACE_BYTES.length + encoded.length);
+  input.set(NAMESPACE_BYTES);
+  input.set(encoded, NAMESPACE_BYTES.length);
+  const bytes = (await digest("SHA-1", input)).slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const chars = hex(bytes);
+  return [
+    chars.slice(0, 8),
+    chars.slice(8, 12),
+    chars.slice(12, 16),
+    chars.slice(16, 20),
+    chars.slice(20)
+  ].join("-");
+}
+async function fingerprint(harness, conversationId) {
+  return await sha256(lp(harness) + lp(conversationId));
+}
+async function sessionKey(harness, conversationId, windowId) {
+  const name = lp(harness) + lp(await sha256(conversationId)) + lp(windowId) + lp(NONE);
+  return await uuid5(name);
+}
+async function eventNodeKey(harness, session, messageId, toolCallId) {
+  const name = lp(harness) + lp(session) + lp(messageId) + lp(toolCallId) + lp("event");
+  return await uuid5(name);
+}
+async function snapshotNodeKey(harness, conversationId, messageId) {
+  const name = lp(harness) + lp(await sha256(conversationId)) + lp(messageId) + lp("snap");
+  return await uuid5(name);
+}
+async function contentAnchor(...parts) {
+  return await sha256(parts.map(lp).join(""));
+}
+var HISTORY_TEXT_CAP = 128e3;
+function cap(value) {
+  if (value.length <= HISTORY_TEXT_CAP) return value;
+  return Array.from(value).slice(0, HISTORY_TEXT_CAP).join("");
+}
+function pyStr(value) {
+  if (typeof value === "string") return value;
+  if (value === null) return "None";
+  if (value === true) return "True";
+  if (value === false) return "False";
+  return String(value);
+}
+function messageText(content) {
+  if (typeof content === "string") return cap(content);
+  if (Array.isArray(content)) {
+    const pieces = [];
+    for (const block of content) {
+      if (typeof block === "string") pieces.push(block);
+      else if (isObject(block) && typeof block.text === "string") pieces.push(block.text);
+    }
+    return cap(pieces.join("\n"));
+  }
+  return content === null || content === void 0 ? "" : cap(pyStr(content));
+}
+async function windowAnchor(messages) {
+  const first = messages[0];
+  if (first === void 0) return NONE;
+  return await contentAnchor(
+    first.role === void 0 ? "" : pyStr(first.role),
+    messageText(first.content)
+  );
+}
+async function buildMetadata(args) {
+  const [session, fp] = await Promise.all([
+    sessionKey(args.harness, args.conversationId, args.windowId),
+    fingerprint(args.harness, args.conversationId)
+  ]);
+  return {
+    message_history: args.history,
+    session_key: session,
+    fingerprint: fp,
+    node_key: await eventNodeKey(args.harness, session, args.messageId, args.toolCallId),
+    parent_node_key: parentNodeKey(args.ancestors),
+    ancestors: args.ancestors
+  };
+}
+async function buildSnapshot(args) {
+  const [session, fp, node] = await Promise.all([
+    sessionKey(args.harness, args.conversationId, args.windowId),
+    fingerprint(args.harness, args.conversationId),
+    snapshotNodeKey(args.harness, args.conversationId, args.messageId)
+  ]);
+  return {
+    session_key: session,
+    fingerprint: fp,
+    node_key: node,
+    parent_node_key: parentNodeKey(args.ancestors),
+    context: args.context,
+    spawned_at: args.spawnedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function parentNodeKey(ancestors) {
+  return ancestors.at(-1)?.node_key ?? null;
+}
+var TRAJECTORY = /* @__PURE__ */ Symbol.for("telem.trajectory");
+function withTrajectory(options, envelope) {
+  return { ...options, [TRAJECTORY]: envelope };
+}
+function wireMetadata(options, kind) {
+  const metadata = {};
+  for (const [key, value] of Object.entries(options.metadata ?? {})) {
+    if (!RESERVED_METADATA.has(key)) metadata[key] = value;
+  }
+  const envelope = options[TRAJECTORY];
+  if (envelope !== void 0) Object.assign(metadata, envelope, { kind });
+  const sessionId = metadata.session_key === void 0 ? options.session : void 0;
+  return { metadata, sessionId };
+}
+
+// src/methods/fetch.ts
+function fetchBody(url, options) {
+  const urls = stringList(
+    typeof url === "string" ? [url] : url,
+    "fetch() requires at least one URL",
+    "fetch() urls"
+  );
+  const { metadata, sessionId } = wireMetadata(options, "fetch");
+  const body = { urls, metadata };
+  const block = {};
+  if (options.providers !== void 0) block.providers = options.providers;
+  if (options.inlineContent !== void 0) block.inline_content = options.inlineContent;
+  if (options.inlineMaxChars !== void 0) block.inline_max_chars = options.inlineMaxChars;
+  if (options.contentFormat !== void 0) block.content_format = options.contentFormat;
+  if (Object.keys(block).length) body.options = block;
+  if (sessionId !== void 0) body.session_id = sessionId;
+  return body;
+}
+function fetchResult(run) {
+  const row = asObject(asArray(asObject(run.output_payload).fetched_results)[0]);
+  return {
+    url: row.url || run.query || "",
+    canonicalUrl: row.canonical_url ?? null,
+    title: row.title || "",
+    status: row.status || run.status || "",
+    content: row.content ?? null,
+    contentTruncated: row.content_truncated ?? null,
+    contentFormat: row.content_format ?? null,
+    contentSha256: row.content_sha256 ?? null,
+    contentType: row.content_type ?? null,
+    contentRef: row.content_ref ?? null,
+    provider: row.provider || "",
+    httpStatus: row.http_status ?? null,
+    fetchedAt: row.fetched_at ?? null,
+    // Key presence, not truthiness: a row that really reported 0 ms keeps its 0.
+    latencyMs: ("latency_ms" in row ? row.latency_ms : run.latency_ms) ?? null,
+    providerMetadata: row.provider_metadata ?? null,
+    error: row.error || run.error || null,
+    batchIndex: run.batch_index ?? 0,
+    raw: row
+  };
+}
+function buildFetchResponse(interaction) {
+  const body = asObject(interaction);
+  const runs = asArray(body.preprocessor_runs).filter((run) => isObject(run) && run.preprocessor_name === "web_fetch").sort((left, right) => (left.batch_index || 0) - (right.batch_index || 0));
+  return {
+    results: runs.map(fetchResult),
+    sessionId: String(body.session_id ?? ""),
+    interactionId: String(body.interaction_id ?? ""),
+    status: body.status ?? "",
+    raw: body
+  };
+}
+async function fetchUrls(config, url, options) {
+  const body = fetchBody(url, options);
+  return buildFetchResponse(await request(config, "POST", "/v1/fetch", body));
+}
+
+// src/methods/providers.ts
+async function providers(config) {
+  const body = await request(config, "GET", "/v1/preprocessors");
+  return asArray(asObject(body).preprocessors).filter(isObject).map((entry) => ({
+    name: entry.name ?? "",
+    type: entry.type ?? "",
+    activeByDefault: entry.active_by_default ?? false,
+    description: entry.description ?? null,
+    method: entry.method ?? null,
+    url: entry.url ?? null,
+    normalized: entry.normalized ?? false,
+    tiers: asArray(entry.tiers)
+  }));
+}
+
+// src/methods/search.ts
+var MIN_SCHEMA_VERSION = 2;
+function searchBlock(defaults, options) {
+  const fromCallTier = options.tier !== void 0;
+  const fromCallFields = options.fields !== void 0;
+  let tier = fromCallTier ? options.tier : defaults.tier;
+  let fields = fromCallFields ? options.fields : defaults.fields;
+  if (tier !== void 0 && fields !== void 0) {
+    if (fromCallTier && !fromCallFields) fields = void 0;
+    else tier = void 0;
+  }
+  let include = options.providersInclude ?? defaults.providersInclude;
+  let exclude = options.providersExclude ?? defaults.providersExclude;
+  if (include !== void 0 && exclude !== void 0) {
+    const excluded = new Set(exclude);
+    include = include.filter((name) => !excluded.has(name));
+    exclude = void 0;
+  }
+  const includeFullContent = options.includeFullContent ?? defaults.includeFullContent;
+  const providers2 = {};
+  if (include !== void 0) providers2.include = include;
+  if (exclude !== void 0) providers2.exclude = exclude;
+  const block = {};
+  if (tier !== void 0) block.tier = tier;
+  if (fields !== void 0) block.fields = fields;
+  if (Object.keys(providers2).length) block.providers = providers2;
+  if (options.providerOverrides !== void 0) block.provider_overrides = options.providerOverrides;
+  if (options.numResults !== void 0) block.num_results = options.numResults;
+  if (options.includeRaw !== void 0) block.include_raw = options.includeRaw;
+  if (options.rerank !== void 0) block.rerank = options.rerank;
+  if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
+  return block;
+}
+function userInput(query) {
+  if (typeof query === "string") {
+    if (query === "") throw invalidRequest("search() requires a non-empty query");
+    return { query };
+  }
+  const queries = stringList(query, "search() requires at least one query", "search() queries");
+  if (queries.length === 1) return { query: queries[0] };
+  return queries.map((item) => ({ query: item }));
+}
+function searchBody(config, query, options) {
+  const { metadata, sessionId } = wireMetadata(options, "search");
+  if (options.goal !== void 0) metadata.goal = options.goal;
+  if (options.context !== void 0) metadata.context = options.context;
+  const body = {
+    user_input: userInput(query),
+    postprocessor_names: [],
+    metadata
+  };
+  const block = searchBlock(config.defaults, options);
+  if (Object.keys(block).length) body.search = block;
+  if (sessionId !== void 0) body.session_id = sessionId;
+  return body;
+}
+function assertV2(data) {
+  let observed;
+  if (isObject(data)) {
+    const version = data.normalized_schema_version;
+    if (typeof version === "number" && Number.isInteger(version) && version >= MIN_SCHEMA_VERSION) {
+      return;
+    }
+    observed = version === void 0 ? "undefined" : JSON.stringify(version);
+  } else {
+    observed = Array.isArray(data) ? "array" : data === null ? "null" : typeof data;
+  }
+  throw new TelemError(
+    `server echoed normalized_schema_version=${observed}; expected >= ${MIN_SCHEMA_VERSION} \u2014 the server pre-dates the V2 normalized contract, or is a dev deployment with no adapter-backed search providers configured; point the SDK at a provider-configured V2 deployment`,
+    { code: "unsupported_server_version" }
+  );
+}
+function searchResults(envelope, provider) {
+  return asArray(envelope.results).filter(isObject).map((row) => ({
+    url: row.url || "",
+    title: row.title || "",
+    summary: row.summary ?? null,
+    excerpt: row.excerpt ?? null,
+    fullContent: row.full_content ?? null,
+    publishDate: row.publish_date ?? null,
+    rank: row.rank ?? null,
+    thumbnail: row.thumbnail ?? null,
+    favicon: row.favicon ?? null,
+    source: row.source ?? null,
+    enrichments: row.enrichments ?? null,
+    fetchMeta: row.fetch_meta ?? null,
+    provider,
+    raw: row
+  }));
+}
+function providerRun(run) {
+  const row = asObject(run);
+  const envelope = asObject(row.output_payload);
+  const provider = row.preprocessor_name ?? "";
+  return {
+    // -- from the run row --
+    provider,
+    status: row.status ?? "",
+    error: row.error ?? null,
+    latencyMs: row.latency_ms ?? null,
+    preprocessorRunId: row.id ? String(row.id) : null,
+    query: row.query ?? "",
+    batchIndex: row.batch_index ?? 0,
+    raw: row.raw_payload ?? null,
+    // -- from the envelope interior --
+    results: searchResults(envelope, provider),
+    tier: envelope.tier ?? null,
+    fields: asArray(envelope.fields),
+    answer: envelope.answer ?? null,
+    entities: envelope.entities ?? null,
+    related: envelope.related ?? null,
+    verticals: envelope.verticals ?? null,
+    usage: envelope.usage ?? null,
+    warnings: asArray(envelope.warnings)
+  };
+}
+function buildSearchResponse(interaction) {
+  const body = asObject(interaction);
+  const byProvider = asArray(body.preprocessor_runs).map(providerRun);
+  return {
+    results: byProvider.flatMap((run) => run.results),
+    byProvider,
+    sessionId: String(body.session_id ?? ""),
+    interactionId: String(body.interaction_id ?? ""),
+    status: body.status ?? "",
+    normalizedSchemaVersion: body.normalized_schema_version ?? null,
+    raw: body
+  };
+}
+async function search(config, query, options) {
+  const body = searchBody(config, query, options);
+  const data = await request(config, "POST", "/v1/interactions", body);
+  assertV2(data);
+  return buildSearchResponse(data);
+}
+
+// src/methods/sessions.ts
+function sessionsFrom(body) {
+  return asArray(asObject(body).sessions).filter(isObject).map((entry) => ({
+    id: String(entry.id ?? ""),
+    createdAt: entry.created_at ?? null,
+    updatedAt: entry.updated_at ?? null,
+    interactionCount: entry.interaction_count ?? 0,
+    latestInteractionAt: entry.latest_interaction_at ?? null,
+    raw: entry
+  }));
+}
+function resultsFrom(body) {
+  const data = asObject(body);
+  return {
+    sessionId: String(data.session_id ?? ""),
+    query: data.query || "",
+    goal: data.goal || "",
+    context: data.context || "",
+    previousPreprocessorResults: asArray(data.previous_preprocessor_results),
+    raw: data
+  };
+}
+function createSessions(config) {
+  const path = (sessionId, suffix) => {
+    if (!sessionId || /^\.+$/.test(sessionId)) throw invalidRequest("a session id is required");
+    return `/v1/sessions/${encodeURIComponent(sessionId)}/${suffix}`;
+  };
+  return {
+    /**
+     * List the caller's sessions, most recent first.
+     *
+     * Requires an API key: sessions are per-caller, and a keyless client gets the
+     * server's 401 as a `TelemError` with `status: 401`. There is no client-side
+     * pre-flight check.
+     *
+     * @returns One summary per session, in the server's own order.
+     */
+    async list() {
+      return sessionsFrom(await request(config, "GET", "/v1/sessions"));
+    },
+    /**
+     * Fetch the aggregated websearch preprocessor results for a session.
+     *
+     * @param sessionId - The session id.
+     * @returns The session's query, goal and context plus the per-step results.
+     */
+    async results(sessionId) {
+      const route = path(sessionId, "websearch-preprocessor-results");
+      return resultsFrom(await request(config, "GET", route));
+    }
+  };
+}
+
+// src/index.ts
+var Telem = class {
+  /** Resolved API key, or `undefined` for an anonymous client. */
+  apiKey;
+  /** Resolved base URL, trailing slash stripped. */
+  baseUrl;
+  /** Resolved per-request timeout in milliseconds. */
+  timeoutMs;
+  /** Resolved retry budget (attempts after the first). */
+  maxRetries;
+  /** The session read surface: `list()` and `results(id)`. */
+  sessions;
+  #config;
+  /**
+   * @param options - An API key string, or an options object. Anything left unset
+   *   resolves from `TELEM_*` env vars, then `~/.telem/credentials.json` (credentials
+   *   only, read lazily), then the defaults.
+   */
+  constructor(options = {}) {
+    const config = resolveConfig(options);
+    this.#config = config;
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl;
+    this.timeoutMs = config.timeoutMs;
+    this.maxRetries = config.maxRetries;
+    this.sessions = createSessions(config);
+  }
+  /**
+   * Run a web search.
+   *
+   * @param query - One query, or an array of queries batched into one interaction.
+   * @param options - Per-call options; each overrides the matching client default.
+   *   `null` and `undefined` both mean none.
+   * @returns The flattened results plus the per-provider breakdown.
+   */
+  async search(query, options) {
+    return await search(this.#config, query, options ?? {});
+  }
+  /**
+   * Fetch the readable content of one or more URLs.
+   *
+   * @param url - One URL, or an array of URLs fetched in one request.
+   * @param options - Per-call fetch options. `null` and `undefined` both mean none.
+   * @returns One result per requested URL, in request order.
+   */
+  async fetch(url, options) {
+    return await fetchUrls(this.#config, url, options ?? {});
+  }
+  /**
+   * List the search providers this deployment can run.
+   *
+   * @returns One entry per configured provider, in the server's own order.
+   */
+  async providers() {
+    return await providers(this.#config);
+  }
+};
+var index_default = Telem;
+export {
+  RESERVED_METADATA,
+  Telem,
+  TelemError,
+  TimeoutError,
+  buildMetadata,
+  buildSnapshot,
+  contentAnchor,
+  index_default as default,
+  eventNodeKey,
+  fingerprint,
+  sessionKey,
+  snapshotNodeKey,
+  windowAnchor,
+  withTrajectory
+};