@ai-matrx/api 0.1.9 → 0.1.11

package/dist/{chunk-PMGKZ4FT.cjs → chunk-2ZHIYXHV.cjs}

@@ -1,9 +1,92 @@
 'use strict';
 
-var chunk2SXAAKGV_cjs = require('./chunk-2SXAAKGV.cjs');
+var chunkPKYPPATQ_cjs = require('./chunk-PKYPPATQ.cjs');
 var uuid = require('@ai-matrx/kit/uuid');
 var credentials = require('@ai-matrx/auth/credentials');
 
+// src/core/protocol.ts
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+var V2_COVERED_AI_PATH_TEMPLATES = [
+  "/ai/manual",
+  "/ai/chat",
+  "/ai/agents/{agent_id}",
+  "/ai/agent/{agent_id}",
+  // singular alias — behaves identically
+  "/ai/conversations/{conversation_id}",
+  "/ai/conversation/{conversation_id}",
+  // singular alias
+  "/ai/prompts/{prompt_id}",
+  // saved-prompt execution
+  "/ai/mandates/{mandate_key}"
+  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
+];
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
+}
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
+}
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
+}
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
+}
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
+}
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return chunkPKYPPATQ_cjs.resilientFetch(url, init, fetchOpts);
+  let result;
+  try {
+    result = await chunkPKYPPATQ_cjs.resilientFetch(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort = chunkPKYPPATQ_cjs.isNetError(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort) throw err;
+    logDowngrade(String(err));
+    return chunkPKYPPATQ_cjs.resilientFetch(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  const status = result.response.status;
+  if (status === 404 || status === 405 || status >= 500) {
+    logDowngrade(`HTTP ${status}`, status);
+    return chunkPKYPPATQ_cjs.resilientFetch(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  return result;
+}
+function aiVersionPathOverrides(version) {
+  if (version !== "v2") return {};
+  const map = {};
+  for (const template of V2_COVERED_AI_PATH_TEMPLATES) {
+    map[template] = toV2Path(template);
+  }
+  return map;
+}
+
 // src/core/backend-errors.ts
 var BackendApiError = class extends Error {
   /** Machine-readable error code */
@@ -824,7 +907,177 @@ var DEPLOYMENTS = {
   }
 };
 var DOMAINS = ["account", "agents", "ai", "apps", "architecture", "audio", "chat", "code", "commerce", "communications", "computer", "content", "crm", "data", "education", "files", "human-resources", "integrations", "intelligence", "knowledge", "legal", "marketing", "masterwork", "media", "platform", "publish", "web", "workflows"];
+var WIRE_FETCH_OPTION_KEYS = [
+  "redirect",
+  "cache",
+  "credentials",
+  "mode",
+  "keepalive",
+  "referrerPolicy",
+  "integrity",
+  "priority"
+];
+var SESSION_READY_TIMEOUT_MS = 3e3;
 var DEFAULT_CONNECT_TIMEOUT_MS = 15e3;
+function isBodyInit(body) {
+  return typeof body === "string" || typeof Blob !== "undefined" && body instanceof Blob || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+async function waitForSessionReady(credentials, timeoutMs = SESSION_READY_TIMEOUT_MS) {
+  const ready = credentials?.ready;
+  if (!ready) return;
+  let timer;
+  try {
+    await Promise.race([
+      ready.call(credentials).catch(() => void 0),
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, Math.max(0, timeoutMs));
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+function headerBag(headers) {
+  return { ...headers ?? {} };
+}
+function hasHeader(headers, name) {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === lower);
+}
+function encodeBody(method, body, headers) {
+  const upper = method.toUpperCase();
+  if (body === void 0 || upper === "GET" || upper === "HEAD") return void 0;
+  if (isBodyInit(body)) return body;
+  if (!hasHeader(headers, "content-type")) headers["Content-Type"] = "application/json";
+  return JSON.stringify(body);
+}
+function bodySize(body) {
+  if (body === void 0) return 0;
+  if (typeof body === "string") return new TextEncoder().encode(body).byteLength;
+  if (typeof Blob !== "undefined" && body instanceof Blob) return body.size;
+  if (body instanceof ArrayBuffer) return body.byteLength;
+  if (ArrayBuffer.isView(body)) return body.byteLength;
+  return 0;
+}
+function parseXhrHeaders(raw) {
+  const headers = new Headers();
+  for (const line of raw.trim().split(/[\r\n]+/)) {
+    const index = line.indexOf(":");
+    if (index <= 0) continue;
+    try {
+      headers.append(line.slice(0, index).trim(), line.slice(index + 1).trim());
+    } catch {
+    }
+  }
+  return headers;
+}
+function sendWithXhr(url, init, signal, totalTimeoutMs, onUploadProgress) {
+  const controller = new AbortController();
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(init.method, url, true);
+    xhr.responseType = "arraybuffer";
+    for (const [name, value] of Object.entries(init.headers)) xhr.setRequestHeader(name, value);
+    if (totalTimeoutMs !== null && totalTimeoutMs > 0) xhr.timeout = totalTimeoutMs;
+    let lastLoaded = 0;
+    xhr.upload.onprogress = (event) => {
+      const loaded = Math.max(lastLoaded, event.loaded);
+      lastLoaded = loaded;
+      onUploadProgress({ loaded, total: event.lengthComputable ? event.total : 0 });
+    };
+    const onAbort = () => xhr.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    xhr.onload = () => {
+      cleanup();
+      const status = xhr.status === 0 ? 200 : xhr.status;
+      const nullBody = status === 204 || status === 205 || status === 304;
+      const response = new Response(nullBody ? null : xhr.response, {
+        status,
+        statusText: xhr.statusText,
+        headers: parseXhrHeaders(xhr.getAllResponseHeaders())
+      });
+      resolve({ response, controller });
+    };
+    xhr.onerror = () => {
+      cleanup();
+      reject(new TypeError(`Network failure uploading to ${url}`));
+    };
+    xhr.ontimeout = () => {
+      cleanup();
+      reject(new DOMException(`Upload to ${url} exceeded ${totalTimeoutMs}ms`, "TimeoutError"));
+    };
+    xhr.onabort = () => {
+      cleanup();
+      reject(new DOMException("The upload was cancelled.", "AbortError"));
+    };
+    if (signal?.aborted) {
+      xhr.abort();
+      return;
+    }
+    xhr.send(init.body ?? null);
+  });
+}
+async function sendOnWire(request, auth = {}) {
+  const method = request.method.toUpperCase();
+  const headers = headerBag(request.headers);
+  const body = encodeBody(method, request.body, headers);
+  await waitForSessionReady(auth.credentials, auth.readyTimeoutMs);
+  const credentialHeaders = auth.credentials ? credentials.credentialToHeaders(await auth.credentials.get()) : {};
+  const attempt = (sendHeaders) => {
+    if (request.signal?.aborted) return Promise.reject(new chunkPKYPPATQ_cjs.AbortedError(request.signal.reason));
+    const merged = { ...sendHeaders };
+    if (request.onUploadProgress && body !== void 0) {
+      if (typeof XMLHttpRequest !== "undefined" && !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream)) {
+        return sendWithXhr(
+          request.url,
+          { method, headers: merged, body },
+          request.signal,
+          request.totalTimeoutMs ?? null,
+          request.onUploadProgress
+        );
+      }
+    }
+    return fetchWithMatrxProtocolFallback(
+      request.url,
+      { ...request.fetchOptions, method, headers: merged, ...body !== void 0 ? { body } : {} },
+      {
+        ...request.signal ? { signal: request.signal } : {},
+        connectTimeoutMs: request.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+        totalTimeoutMs: request.totalTimeoutMs !== void 0 ? request.totalTimeoutMs : null,
+        throwOnHttpError: false,
+        ...request.onProtocolDowngrade ? { onDowngrade: request.onProtocolDowngrade } : {}
+      }
+    ).then((result) => {
+      if (request.onUploadProgress && body !== void 0) {
+        const total = bodySize(body);
+        request.onUploadProgress({ loaded: total, total });
+      }
+      return result;
+    });
+  };
+  const over = Object.fromEntries(
+    Object.entries(request.overHeaders ?? {}).filter(([name]) => name.toLowerCase() !== "content-type")
+  );
+  const firstHeaders = { ...headers, ...credentialHeaders, ...over };
+  const idempotent = method === "GET" || method === "HEAD";
+  const attempts = Math.max(1, request.retryAttempts ?? 1);
+  const first = idempotent && attempts > 1 && !request.stream ? await chunkPKYPPATQ_cjs.withRetry(() => attempt(firstHeaders), {
+    attempts,
+    retryOn: chunkPKYPPATQ_cjs.isTransportFailure,
+    ...request.signal ? { signal: request.signal } : {}
+  }) : await attempt(firstHeaders);
+  if (first.response.status !== 401 || !auth.refreshCredentials) return first;
+  if (!await auth.refreshCredentials()) return first;
+  await first.response.body?.cancel().catch(() => void 0);
+  const retryHeaders = { ...headers };
+  Object.assign(retryHeaders, auth.credentials ? credentials.credentialToHeaders(await auth.credentials.get()) : {}, over);
+  return attempt(retryHeaders);
+}
+
+// src/api.ts
+var DEFAULT_CONNECT_TIMEOUT_MS2 = 15e3;
 function defaultRequestId() {
   const c = globalThis.crypto;
   if (c?.randomUUID) return c.randomUUID();
@@ -853,9 +1106,6 @@ function queryString(query) {
   }
   return parts.length ? `?${parts.join("&")}` : "";
 }
-function isBodyInit(body) {
-  return typeof body === "string" || typeof Blob !== "undefined" && body instanceof Blob || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
-}
 function acceptFor(stream) {
   switch (stream) {
     case "ndjson":
@@ -921,43 +1171,27 @@ function createApi(options = {}) {
       Accept: acceptFor(op.s),
       [credentials.MATRX_HEADERS.requestId]: requestId
     };
-    let body;
-    if (args?.body !== void 0 && op.m !== "GET" && op.m !== "HEAD") {
-      if (isBodyInit(args.body)) {
-        body = args.body;
-      } else {
-        body = JSON.stringify(args.body);
-        headers["Content-Type"] = "application/json";
-      }
-    }
-    const credentialHeaders = credentials.credentialToHeaders(await credentials$1.get());
-    Object.assign(headers, credentialHeaders);
     if (orgId !== null) headers[credentials.MATRX_HEADERS.organization] = orgId;
     options.onRequest?.({ operation: op.n, method: op.m, url, requestId, deployment: op.d });
-    const attempt = (sendHeaders = headers) => chunk2SXAAKGV_cjs.resilientFetch(
-      url,
-      { method: op.m, headers: sendHeaders, ...body !== void 0 ? { body } : {} },
+    const { response, controller } = await sendOnWire(
       {
+        url,
+        method: op.m,
+        headers,
+        body: args?.body,
         ...call?.signal ? { signal: call.signal } : {},
-        connectTimeoutMs: call?.connectTimeoutMs ?? options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+        connectTimeoutMs: call?.connectTimeoutMs ?? options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS2,
         totalTimeoutMs: call?.totalTimeoutMs !== void 0 ? call.totalTimeoutMs : options.totalTimeoutMs ?? null,
-        throwOnHttpError: false
+        stream: Boolean(op.s),
+        retryAttempts,
+        ...call?.onUploadProgress ? { onUploadProgress: call.onUploadProgress } : {}
+      },
+      {
+        credentials: credentials$1,
+        ...options.readyTimeoutMs !== void 0 ? { readyTimeoutMs: options.readyTimeoutMs } : {},
+        ...options.refreshCredentials ? { refreshCredentials: options.refreshCredentials } : {}
       }
     );
-    const idempotent = op.m === "GET" || op.m === "HEAD";
-    const { response, controller } = idempotent && retryAttempts > 1 && !op.s ? await chunk2SXAAKGV_cjs.withRetry(() => attempt(), {
-      attempts: retryAttempts,
-      retryOn: chunk2SXAAKGV_cjs.isTransportFailure,
-      ...call?.signal ? { signal: call.signal } : {}
-    }) : await attempt();
-    if (response.status === 401 && options.refreshCredentials && await options.refreshCredentials()) {
-      const retryHeaders = { ...headers };
-      for (const name of Object.keys(credentialHeaders)) delete retryHeaders[name];
-      Object.assign(retryHeaders, credentials.credentialToHeaders(await credentials$1.get()));
-      const retried = await attempt(retryHeaders);
-      if (!retried.response.ok) throw await errorFrom(retried.response, interpolate(op.p, args?.path));
-      return { response: retried.response, requestId, controller: retried.controller };
-    }
     if (!response.ok) throw await errorFrom(response, interpolate(op.p, args?.path));
     return { response, requestId, controller };
   };
@@ -1029,9 +1263,14 @@ exports.CONTRACT_SHA256 = CONTRACT_SHA256;
 exports.DEFAULT_MATRX_NDJSON_READ_AHEAD = DEFAULT_MATRX_NDJSON_READ_AHEAD;
 exports.DEPLOYMENTS = DEPLOYMENTS;
 exports.DOMAINS = DOMAINS;
+exports.MATRX_AI_API_VERSION_DEFAULT = MATRX_AI_API_VERSION_DEFAULT;
 exports.MatrxApiError = MatrxApiError;
 exports.OrganizationContextError = OrganizationContextError;
 exports.StreamTransportError = StreamTransportError;
+exports.V2_COVERED_AI_PATH_TEMPLATES = V2_COVERED_AI_PATH_TEMPLATES;
+exports.WIRE_FETCH_OPTION_KEYS = WIRE_FETCH_OPTION_KEYS;
+exports.aiVersionPathOverrides = aiVersionPathOverrides;
+exports.applyAiApiVersion = applyAiApiVersion;
 exports.applyOrganizationContextHeader = applyOrganizationContextHeader;
 exports.assertOrganizationMatchesOperation = assertOrganizationMatchesOperation;
 exports.assertQueryOrganizationMatchesContext = assertQueryOrganizationMatchesContext;
@@ -1042,9 +1281,12 @@ exports.createOrganizationOperation = createOrganizationOperation;
 exports.describeBackendFailure = describeBackendFailure;
 exports.extractMatrxErrorCode = extractMatrxErrorCode;
 exports.extractMatrxErrorMessage = extractMatrxErrorMessage;
+exports.fetchWithMatrxProtocolFallback = fetchWithMatrxProtocolFallback;
 exports.getUserMessage = getUserMessage;
+exports.isCoveredAiPath = isCoveredAiPath;
 exports.isGenericUserMessage = isGenericUserMessage;
 exports.isStreamTransportLost = isStreamTransportLost;
+exports.isV2Path = isV2Path;
 exports.normalizeMatrxStreamEnvelope = normalizeMatrxStreamEnvelope;
 exports.openJsonOrStream = openJsonOrStream;
 exports.openStream = openStream;
@@ -1057,4 +1299,7 @@ exports.parseStreamError = parseStreamError;
 exports.readMatrxNdjsonStream = readMatrxNdjsonStream;
 exports.readMatrxSseStream = readMatrxSseStream;
 exports.requireOrganizationContext = requireOrganizationContext;
+exports.sendOnWire = sendOnWire;
+exports.toV1FallbackUrl = toV1FallbackUrl;
+exports.toV2Path = toV2Path;
 exports.unwrapUpstreamError = unwrapUpstreamError;