@omnicross/core 0.2.0 → 0.3.0

package/dist/search/api.js

@@ -0,0 +1,766 @@
+import {
+  createEgressGuardedDispatcher,
+  findEgressDenial,
+  getSearchProxyDispatcher,
+  resolveSearchProxySettings,
+  validateEgressUrl
+} from "../chunk-DBBR6RHF.js";
+
+// src/search/api/rotator.ts
+var ApiKeyRotator = class {
+  index = 0;
+  /**
+   * Pick the next key from a comma-separated list, advancing the counter.
+   *
+   * Returns `''` when nothing is configured — never `undefined`, so callers
+   * have one falsy case to test rather than two.
+   */
+  pick(rawKeyString) {
+    const keys = splitKeys(rawKeyString);
+    if (keys.length === 0) return "";
+    if (keys.length === 1) return keys[0];
+    if (this.index >= keys.length) this.index = 0;
+    const selected = keys[this.index];
+    this.index = (this.index + 1) % keys.length;
+    return selected;
+  }
+  /** Reset the rotation counter, e.g. after a configuration update. */
+  reset() {
+    this.index = 0;
+  }
+  /** How many usable keys the string holds. */
+  countKeys(rawKeyString) {
+    return splitKeys(rawKeyString).length;
+  }
+  /**
+   * Every configured key.
+   *
+   * Not in the Elftia original: redaction has to strip EVERY key a provider
+   * could have sent, not just the one this request rotated onto, or a key
+   * echoed by an upstream error survives whenever the counter has moved on.
+   */
+  allKeys(rawKeyString) {
+    return splitKeys(rawKeyString);
+  }
+};
+function splitKeys(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((key) => key.trim()).filter((key) => key.length > 0);
+}
+
+// src/search/api/transport.ts
+import { SearchProviderError } from "@omnicross/contracts/search-types";
+import { fetch as undiciFetch } from "undici";
+
+// src/search/api/types.ts
+var SEARCH_API_TRANSPORT_ID = "undici";
+
+// src/search/api/transport.ts
+var API_MAX_REDIRECTS = 5;
+var DEFAULT_API_TIMEOUT_MS = 15e3;
+var API_RESPONSE_BYTES = 2 * 1024 * 1024;
+var MAX_UPSTREAM_TEXT = 300;
+function createSearchApiTransport(options = {}) {
+  const policy = options.egressPolicy;
+  const fetchImpl = options.fetch ?? createUndiciApiFetch(options.env, policy, options.resolveProxyDispatcher);
+  const maxRedirects = options.maxRedirects ?? API_MAX_REDIRECTS;
+  return async (request) => {
+    const context = {
+      providerId: request.providerId,
+      label: request.label,
+      secrets: request.secrets ?? [],
+      host: "unknown-host"
+    };
+    const initialUrl = assertEgressAllowed(request.url, policy, context);
+    context.host = initialUrl.hostname;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(request.signal?.reason);
+    request.signal?.addEventListener("abort", onAbort, { once: true });
+    if (request.signal?.aborted) onAbort();
+    const timeoutMs = request.timeoutMs ?? DEFAULT_API_TIMEOUT_MS;
+    let deadlineExpired = false;
+    const timer = setTimeout(() => {
+      deadlineExpired = true;
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const response = await fetchWithValidatedRedirects(
+        fetchImpl,
+        initialUrl,
+        request,
+        controller.signal,
+        maxRedirects,
+        policy,
+        context
+      );
+      const rawText = await readJsonBodyWithLimit(response, context);
+      assertStatusOk(response.status, rawText, context);
+      return parseJsonPayload(rawText, context);
+    } catch (error) {
+      const denial = findEgressDenial(error);
+      if (denial) throw denial;
+      if (request.signal?.aborted) {
+        throw apiError("cancelled", `${context.label} search was cancelled by the caller`, {
+          stage: "fetch",
+          context,
+          retryable: false,
+          cause: error
+        });
+      }
+      if (deadlineExpired) {
+        throw apiError(
+          "timeout",
+          `${context.label} search exceeded its ${timeoutMs}ms budget`,
+          { stage: "fetch", context, retryable: true, cause: error }
+        );
+      }
+      throw asApiError(error, context, "connect");
+    } finally {
+      clearTimeout(timer);
+      request.signal?.removeEventListener("abort", onAbort);
+    }
+  };
+}
+var defaultSearchApiTransport = createSearchApiTransport();
+function selectApiDispatcher(env, policy, override) {
+  if (override?.resolveProxyDispatcher) {
+    const dispatcher = override.resolveProxyDispatcher(override.url);
+    if (dispatcher) return { dispatcher, proxied: true };
+  }
+  const proxy = resolveSearchProxySettings(env);
+  if (proxy) return { dispatcher: getSearchProxyDispatcher(proxy), proxied: true };
+  return { dispatcher: createEgressGuardedDispatcher(policy), proxied: false };
+}
+function createUndiciApiFetch(env, policy, resolveProxyDispatcher) {
+  return async (url, init) => {
+    const { dispatcher } = selectApiDispatcher(env, policy, { url, resolveProxyDispatcher });
+    return await undiciFetch(
+      url,
+      { ...init, dispatcher }
+    );
+  };
+}
+async function fetchWithValidatedRedirects(fetchImpl, initialUrl, request, signal, maxRedirects, policy, context) {
+  let currentUrl = initialUrl;
+  let method = request.method;
+  let body = request.jsonBody === void 0 ? void 0 : JSON.stringify(request.jsonBody);
+  const carriedHeaders = { ...request.headers };
+  for (let redirects = 0; redirects <= maxRedirects; redirects += 1) {
+    context.host = currentUrl.hostname;
+    const headers = { ...carriedHeaders };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    let response;
+    try {
+      response = await fetchImpl(currentUrl.href, {
+        method,
+        headers,
+        body,
+        signal,
+        redirect: "manual"
+      });
+    } catch (error) {
+      const denial = findEgressDenial(error);
+      if (denial) throw denial;
+      if (isAbortError(error)) throw error;
+      throw apiError("upstream_unavailable", networkFailureMessage(error, context), {
+        stage: "connect",
+        context,
+        retryable: true,
+        cause: error
+      });
+    }
+    if (response.status < 300 || response.status >= 400) return response;
+    const location = response.headers.get("location");
+    if (!location) return response;
+    void response.body?.cancel().catch(() => void 0);
+    if (redirects === maxRedirects) throw tooManyRedirects(maxRedirects, context);
+    let nextUrl;
+    try {
+      nextUrl = new URL(location, currentUrl);
+    } catch {
+      throw apiError("upstream_unavailable", `${context.label} sent an unusable redirect target`, {
+        stage: "redirect",
+        context,
+        retryable: false
+      });
+    }
+    assertEgressAllowed(nextUrl, policy, context);
+    if (nextUrl.origin !== currentUrl.origin) stripCredentialHeaders(carriedHeaders);
+    if (response.status === 303 || (response.status === 301 || response.status === 302) && method === "POST") {
+      method = "GET";
+      body = void 0;
+    }
+    currentUrl = nextUrl;
+  }
+  throw tooManyRedirects(maxRedirects, context);
+}
+var CREDENTIAL_HEADERS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization"
+]);
+function stripCredentialHeaders(headers) {
+  for (const name of Object.keys(headers)) {
+    if (CREDENTIAL_HEADERS.has(name.toLowerCase())) delete headers[name];
+  }
+}
+function assertEgressAllowed(url, policy, context) {
+  try {
+    return validateEgressUrl(url, policy, context.providerId);
+  } catch (error) {
+    if (!(error instanceof SearchProviderError) && !isTaxonomyError(error)) throw error;
+    const denial = error;
+    throw apiError(denial.code, denial.message, {
+      stage: "egress",
+      context: { ...context, host: denial.details?.host ?? context.host },
+      retryable: false,
+      cause: denial,
+      details: denial.details
+    });
+  }
+}
+function tooManyRedirects(maxRedirects, context) {
+  return apiError("upstream_unavailable", `too many redirects (>${maxRedirects})`, {
+    stage: "redirect",
+    context,
+    retryable: false,
+    details: { maxRedirects: String(maxRedirects) }
+  });
+}
+async function readJsonBodyWithLimit(response, context) {
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const chunks = [];
+  let totalBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    totalBytes += value.byteLength;
+    if (totalBytes > API_RESPONSE_BYTES) {
+      await reader.cancel().catch(() => void 0);
+      throw apiError(
+        "upstream_unavailable",
+        `${context.label} response exceeded the ${API_RESPONSE_BYTES} byte cap`,
+        {
+          stage: "body-cap",
+          context,
+          retryable: false,
+          details: { maxResponseBytes: String(API_RESPONSE_BYTES) }
+        }
+      );
+    }
+    chunks.push(value);
+  }
+  const merged = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0));
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8").decode(merged);
+}
+function assertStatusOk(status, rawText, context) {
+  if (status >= 200 && status < 300) return;
+  const detail = sanitizeUpstreamText(rawText, context.secrets);
+  const suffix = detail ? ` - ${detail}` : "";
+  const details = { status: String(status) };
+  if (status === 401 || status === 403) {
+    throw apiError(
+      "auth_failed",
+      `${context.label} rejected the credentials (HTTP ${status})${suffix}`,
+      { stage: "fetch", context, retryable: false, details }
+    );
+  }
+  if (status === 429) {
+    throw apiError("rate_limited", `${context.label} rate limited the request (HTTP ${status})${suffix}`, {
+      stage: "fetch",
+      context,
+      retryable: true,
+      details
+    });
+  }
+  throw apiError("upstream_unavailable", `${context.label} search failed: ${status}${suffix}`, {
+    stage: "fetch",
+    context,
+    // 5xx may pass on a retry; a 4xx that is not auth or quota will not.
+    retryable: status >= 500,
+    details
+  });
+}
+function parseJsonPayload(rawText, context) {
+  try {
+    return JSON.parse(rawText);
+  } catch (error) {
+    throw apiError("parse_failed", `${context.label} returned a body that is not valid JSON`, {
+      stage: "parse",
+      context,
+      retryable: false,
+      cause: error
+    });
+  }
+}
+function requireResultArray(payload, field, providerId, label) {
+  const value = typeof payload === "object" && payload !== null ? payload[field] : void 0;
+  if (Array.isArray(value)) return value;
+  throw new SearchProviderError(
+    "parse_failed",
+    `${label} response is missing its "${field}" array`,
+    {
+      providerId,
+      retryable: false,
+      details: { transport: SEARCH_API_TRANSPORT_ID, stage: "parse" }
+    }
+  );
+}
+function payloadText(value) {
+  return typeof value === "string" ? value : "";
+}
+function apiConfigMissing(providerId, message) {
+  return new SearchProviderError("config_missing", message, {
+    providerId,
+    retryable: false,
+    details: { transport: SEARCH_API_TRANSPORT_ID, stage: "config" }
+  });
+}
+function apiError(code, message, init) {
+  return new SearchProviderError(code, message, {
+    providerId: init.context.providerId,
+    retryable: init.retryable,
+    cause: init.cause,
+    // transport/stage/host last so a caller-supplied `details` cannot shadow them.
+    details: {
+      ...init.details,
+      host: init.context.host,
+      transport: SEARCH_API_TRANSPORT_ID,
+      stage: init.stage
+    }
+  });
+}
+function asApiError(value, context, fallbackStage) {
+  const denial = findEgressDenial(value);
+  if (denial) return denial;
+  if (value instanceof SearchProviderError) return value;
+  if (isTaxonomyError(value)) return value;
+  return apiError("upstream_unavailable", describeError(value, context), {
+    stage: fallbackStage,
+    context,
+    retryable: true,
+    cause: value
+  });
+}
+function isTaxonomyError(value) {
+  return value instanceof Error && typeof value.code === "string" && value.name === "SearchProviderError";
+}
+function describeError(value, context) {
+  const raw = value instanceof Error && value.message ? value.message : `${context.label} search failed`;
+  return sanitizeUpstreamText(raw, context.secrets) || `${context.label} search failed`;
+}
+function networkFailureMessage(error, context) {
+  const code = nestedErrorCode(error);
+  const suffix = code ? ` (${code})` : "";
+  return `${context.label} request failed${suffix}`;
+}
+function nestedErrorCode(error) {
+  let current = error;
+  for (let depth = 0; depth < 4 && current instanceof Error; depth += 1) {
+    const code = current.code;
+    if (typeof code === "string" && /^[A-Z][A-Z0-9_]+$/.test(code)) return code;
+    current = current.cause;
+  }
+  return void 0;
+}
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+var CREDENTIAL_NAMES = "api_?key|access_?token|refresh_?token|token|password|passwd|secret|authorization";
+var CREDENTIAL_FIELD = new RegExp(`("(?:${CREDENTIAL_NAMES})"\\s*:\\s*")(?:[^"\\\\]|\\\\.)*(")`, "gi");
+var ESCAPED_CREDENTIAL_FIELD = new RegExp(
+  `(\\\\"(?:${CREDENTIAL_NAMES})\\\\"\\s*:\\s*\\\\")(?:(?!\\\\").)*(\\\\")`,
+  "gi"
+);
+var AUTH_SCHEME_VALUE = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]+/gi;
+var ABSOLUTE_URL = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
+function sanitizeUpstreamText(text, secrets = []) {
+  if (!text) return "";
+  let out = text.replace(ESCAPED_CREDENTIAL_FIELD, "$1[redacted]$2");
+  out = out.replace(CREDENTIAL_FIELD, "$1[redacted]$2");
+  out = redactSecretValues(out, secrets);
+  out = out.replace(AUTH_SCHEME_VALUE, "$1 [redacted]");
+  out = out.replace(ABSOLUTE_URL, "[url]");
+  out = out.replace(/\s+/g, " ").trim();
+  return out.length > MAX_UPSTREAM_TEXT ? `${out.slice(0, MAX_UPSTREAM_TEXT)}\u2026` : out;
+}
+function redactSecretValues(text, secrets) {
+  let out = text;
+  for (const secret of secrets) {
+    if (!secret) continue;
+    out = out.split(secret).join("[redacted]");
+    const encoded = encodeURIComponent(secret);
+    if (encoded !== secret) out = out.split(encoded).join("[redacted]");
+  }
+  return out;
+}
+
+// src/search/api/JinaReaderClient.ts
+var JINA_READER_HOST = "https://r.jina.ai";
+var LABEL = "Jina Reader";
+var JinaReaderClient = class {
+  constructor(config = {}, transport = defaultSearchApiTransport, providerId = "jina") {
+    this.config = config;
+    this.transport = transport;
+    this.providerId = providerId;
+  }
+  config;
+  transport;
+  providerId;
+  rotator = new ApiKeyRotator();
+  /**
+   * Read one URL.
+   *
+   * The key is OPTIONAL, as in the baseline: the reader answers unauthenticated
+   * requests at a lower rate limit.
+   */
+  async readUrl(url, options = {}) {
+    const headers = { Accept: "application/json" };
+    const apiKey = this.rotator.pick(this.config.apiKey);
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    const payload = await this.transport({
+      url: `${JINA_READER_HOST}/${encodeURIComponent(url)}`,
+      method: "GET",
+      headers,
+      providerId: this.providerId,
+      label: LABEL,
+      timeoutMs: options.timeout,
+      signal: options.signal,
+      secrets: this.rotator.allKeys(this.config.apiKey)
+    });
+    return toReadResult(url, payload);
+  }
+};
+function toReadResult(url, payload) {
+  const root = payload ?? {};
+  const nested = root.data ?? {};
+  const title = payloadText(nested.title) || payloadText(root.title);
+  const content = payloadText(nested.content) || payloadText(root.content);
+  return {
+    url,
+    ...title ? { title } : {},
+    ...content ? { content } : {}
+  };
+}
+
+// src/search/api/JinaSearchProvider.ts
+var JINA_PROVIDER_ID = "jina";
+var JINA_DEFAULT_HOST = "https://s.jina.ai";
+var JINA_DEFAULT_MAX_RESULTS = 5;
+var LABEL2 = "Jina";
+var JinaSearchProvider = class {
+  constructor(config = {}, transport = defaultSearchApiTransport, reader) {
+    this.config = config;
+    this.transport = transport;
+    this.reader = reader ?? new JinaReaderClient(config, transport, JINA_PROVIDER_ID);
+  }
+  config;
+  transport;
+  id = JINA_PROVIDER_ID;
+  rotator = new ApiKeyRotator();
+  reader;
+  async search(query, options = {}) {
+    const apiHost = this.config.apiHost || JINA_DEFAULT_HOST;
+    const maxResults = options.maxResults || JINA_DEFAULT_MAX_RESULTS;
+    const headers = { Accept: "application/json" };
+    const apiKey = this.rotator.pick(this.config.apiKey);
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    if (options.fetchPageContent) headers["X-Engine"] = "direct";
+    const payload = await this.transport({
+      url: `${apiHost}/${encodeURIComponent(query)}`,
+      method: "GET",
+      headers,
+      providerId: this.id,
+      label: LABEL2,
+      timeoutMs: options.timeout,
+      signal: options.signal,
+      secrets: this.rotator.allKeys(this.config.apiKey)
+    });
+    return requireResultArray(payload, "data", this.id, LABEL2).slice(0, maxResults).map((item) => toResult(item));
+  }
+  /** Read one URL through the split-out reader client. */
+  readUrl(url, options) {
+    return this.reader.readUrl(url, options);
+  }
+};
+function toResult(item) {
+  const record = item ?? {};
+  return {
+    title: payloadText(record.title),
+    url: payloadText(record.url),
+    // The baseline's quirk, preserved: Jina returns a snippet under either
+    // name depending on the engine that produced the row.
+    content: payloadText(record.content) || payloadText(record.description)
+  };
+}
+
+// src/search/api/SearxngSearchProvider.ts
+var SEARXNG_PROVIDER_ID = "searxng";
+var SEARXNG_DEFAULT_MAX_RESULTS = 5;
+var LABEL3 = "Searxng";
+var SearxngSearchProvider = class {
+  constructor(config, transport = defaultSearchApiTransport) {
+    this.config = config;
+    this.transport = transport;
+  }
+  config;
+  transport;
+  id = SEARXNG_PROVIDER_ID;
+  async search(query, options = {}) {
+    if (!this.config.apiHost) throw apiConfigMissing(this.id, `${LABEL3} API host is required`);
+    const maxResults = options.maxResults || SEARXNG_DEFAULT_MAX_RESULTS;
+    const params = new URLSearchParams({ q: query, format: "json", pageno: "1" });
+    const headers = { Accept: "application/json" };
+    const { basicAuthUsername, basicAuthPassword } = this.config;
+    const credentials = basicAuthUsername && basicAuthPassword ? Buffer.from(`${basicAuthUsername}:${basicAuthPassword}`).toString("base64") : void 0;
+    if (credentials) headers.Authorization = `Basic ${credentials}`;
+    const payload = await this.transport({
+      url: `${this.config.apiHost}/search?${params.toString()}`,
+      method: "GET",
+      headers,
+      providerId: this.id,
+      label: LABEL3,
+      timeoutMs: options.timeout,
+      signal: options.signal,
+      // The encoded blob AND its parts: an upstream error could echo either.
+      secrets: [credentials, basicAuthUsername, basicAuthPassword]
+    });
+    return requireResultArray(payload, "results", this.id, LABEL3).slice(0, maxResults).map((item) => toResult2(item));
+  }
+};
+function toResult2(item) {
+  const record = item ?? {};
+  return {
+    title: payloadText(record.title),
+    url: payloadText(record.url),
+    content: payloadText(record.content)
+  };
+}
+
+// src/search/api/TavilySearchProvider.ts
+var TAVILY_PROVIDER_ID = "tavily";
+var TAVILY_DEFAULT_HOST = "https://api.tavily.com";
+var TAVILY_DEFAULT_MAX_RESULTS = 5;
+var LABEL4 = "Tavily";
+var TavilySearchProvider = class {
+  constructor(config, transport = defaultSearchApiTransport) {
+    this.config = config;
+    this.transport = transport;
+  }
+  config;
+  transport;
+  id = TAVILY_PROVIDER_ID;
+  rotator = new ApiKeyRotator();
+  async search(query, options = {}) {
+    const apiKey = this.rotator.pick(this.config.apiKey);
+    if (!apiKey) throw apiConfigMissing(this.id, `${LABEL4} API key is required`);
+    const apiHost = this.config.apiHost || TAVILY_DEFAULT_HOST;
+    const maxResults = options.maxResults || TAVILY_DEFAULT_MAX_RESULTS;
+    const payload = await this.transport({
+      url: `${apiHost}/search`,
+      method: "POST",
+      jsonBody: {
+        api_key: apiKey,
+        query,
+        max_results: maxResults,
+        search_depth: "advanced",
+        include_answer: false,
+        include_raw_content: false
+      },
+      providerId: this.id,
+      label: LABEL4,
+      timeoutMs: options.timeout,
+      signal: options.signal,
+      secrets: this.rotator.allKeys(this.config.apiKey)
+    });
+    return requireResultArray(payload, "results", this.id, LABEL4).map((item) => toResult3(item));
+  }
+};
+function toResult3(item) {
+  const record = item ?? {};
+  return {
+    title: payloadText(record.title),
+    url: payloadText(record.url),
+    content: payloadText(record.content)
+  };
+}
+
+// src/search/api/ZhipuSearchProvider.ts
+var ZHIPU_PROVIDER_ID = "zhipu";
+var ZAI_PROVIDER_ID = "z.ai";
+var ZHIPU_DEFAULT_HOSTS = Object.freeze({
+  [ZHIPU_PROVIDER_ID]: "https://open.bigmodel.cn/api/paas/v4",
+  [ZAI_PROVIDER_ID]: "https://api.z.ai/api/paas/v4"
+});
+var ZHIPU_DEFAULT_MAX_RESULTS = 10;
+function normalizeZhipuApiUrl(apiHost) {
+  const url = apiHost.replace(/\/+$/, "");
+  if (url.endsWith("/web_search")) return url;
+  if (/\/v\d+$/.test(url)) return `${url}/web_search`;
+  return `${url}/v4/web_search`;
+}
+var ZhipuSearchProvider = class {
+  constructor(id, config, transport = defaultSearchApiTransport) {
+    this.config = config;
+    this.transport = transport;
+    this.id = id;
+  }
+  config;
+  transport;
+  id;
+  rotator = new ApiKeyRotator();
+  async search(query, options = {}) {
+    const apiKey = this.rotator.pick(this.config.apiKey);
+    if (!apiKey) throw apiConfigMissing(this.id, `${this.id} API key is required`);
+    const defaultHost = ZHIPU_DEFAULT_HOSTS[this.id] ?? ZHIPU_DEFAULT_HOSTS[ZHIPU_PROVIDER_ID];
+    const apiHost = this.config.apiHost || defaultHost;
+    const maxResults = options.maxResults || ZHIPU_DEFAULT_MAX_RESULTS;
+    const payload = await this.transport({
+      url: normalizeZhipuApiUrl(apiHost),
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}` },
+      jsonBody: { search_query: query, search_engine: "search_pro", count: maxResults },
+      providerId: this.id,
+      label: this.id,
+      timeoutMs: options.timeout,
+      signal: options.signal,
+      secrets: this.rotator.allKeys(this.config.apiKey)
+    });
+    return requireResultArray(payload, "search_result", this.id, this.id).slice(0, maxResults).map((item) => toResult4(item));
+  }
+};
+function toResult4(item) {
+  const record = item ?? {};
+  return {
+    title: payloadText(record.title),
+    // `link`, not `url` — the wire contract, not a typo.
+    url: payloadText(record.link),
+    content: payloadText(record.content)
+  };
+}
+
+// src/search/api/contributions.ts
+var SHARED_API_CAPABILITIES = {
+  supportsRegion: false,
+  supportsLanguage: false,
+  supportsTimeRange: false,
+  supportsCancellation: true
+};
+var TAVILY_CAPABILITIES = Object.freeze({
+  ...SHARED_API_CAPABILITIES,
+  requiresApiKey: true,
+  supportsUrlRead: false
+});
+var JINA_CAPABILITIES = Object.freeze({
+  ...SHARED_API_CAPABILITIES,
+  // The search endpoint answers unauthenticated requests (rate-limited), so a
+  // key is an upgrade, not a requirement.
+  requiresApiKey: false,
+  supportsUrlRead: true
+});
+var SEARXNG_CAPABILITIES = Object.freeze({
+  ...SHARED_API_CAPABILITIES,
+  requiresApiKey: false,
+  supportsUrlRead: false
+});
+var ZHIPU_CAPABILITIES = Object.freeze({
+  ...SHARED_API_CAPABILITIES,
+  requiresApiKey: true,
+  supportsUrlRead: false
+});
+function apiSearchContributions(configs, options = {}) {
+  const transport = createSearchApiTransport({
+    fetch: options.fetchImpl,
+    egressPolicy: options.egressPolicy,
+    resolveProxyDispatcher: options.resolveProxyDispatcher
+  });
+  const contributions = [];
+  if (configs.tavily) {
+    contributions.push({
+      id: TAVILY_PROVIDER_ID,
+      source: "builtin",
+      kind: "api",
+      provider: new TavilySearchProvider(configs.tavily, transport),
+      capabilities: { ...TAVILY_CAPABILITIES }
+    });
+  }
+  if (configs.jina) {
+    contributions.push({
+      id: JINA_PROVIDER_ID,
+      source: "builtin",
+      kind: "api",
+      provider: new JinaSearchProvider(configs.jina, transport),
+      capabilities: { ...JINA_CAPABILITIES }
+    });
+  }
+  if (configs.searxng) {
+    contributions.push({
+      id: SEARXNG_PROVIDER_ID,
+      source: "builtin",
+      kind: "api",
+      provider: new SearxngSearchProvider(configs.searxng, transport),
+      capabilities: { ...SEARXNG_CAPABILITIES }
+    });
+  }
+  if (configs.zhipu) {
+    contributions.push({
+      id: ZHIPU_PROVIDER_ID,
+      source: "builtin",
+      kind: "api",
+      provider: new ZhipuSearchProvider(ZHIPU_PROVIDER_ID, configs.zhipu, transport),
+      capabilities: { ...ZHIPU_CAPABILITIES }
+    });
+  }
+  if (configs["z.ai"]) {
+    contributions.push({
+      id: ZAI_PROVIDER_ID,
+      source: "builtin",
+      kind: "api",
+      provider: new ZhipuSearchProvider(ZAI_PROVIDER_ID, configs["z.ai"], transport),
+      capabilities: { ...ZHIPU_CAPABILITIES }
+    });
+  }
+  return contributions;
+}
+export {
+  API_MAX_REDIRECTS,
+  API_RESPONSE_BYTES,
+  ApiKeyRotator,
+  DEFAULT_API_TIMEOUT_MS,
+  JINA_CAPABILITIES,
+  JINA_DEFAULT_HOST,
+  JINA_DEFAULT_MAX_RESULTS,
+  JINA_PROVIDER_ID,
+  JINA_READER_HOST,
+  JinaReaderClient,
+  JinaSearchProvider,
+  SEARCH_API_TRANSPORT_ID,
+  SEARXNG_CAPABILITIES,
+  SEARXNG_DEFAULT_MAX_RESULTS,
+  SEARXNG_PROVIDER_ID,
+  SearxngSearchProvider,
+  TAVILY_CAPABILITIES,
+  TAVILY_DEFAULT_HOST,
+  TAVILY_DEFAULT_MAX_RESULTS,
+  TAVILY_PROVIDER_ID,
+  TavilySearchProvider,
+  ZAI_PROVIDER_ID,
+  ZHIPU_CAPABILITIES,
+  ZHIPU_DEFAULT_HOSTS,
+  ZHIPU_DEFAULT_MAX_RESULTS,
+  ZHIPU_PROVIDER_ID,
+  ZhipuSearchProvider,
+  apiConfigMissing,
+  apiSearchContributions,
+  createSearchApiTransport,
+  defaultSearchApiTransport,
+  normalizeZhipuApiUrl,
+  requireResultArray,
+  sanitizeUpstreamText
+};