@cavi-ai/api-client 0.1.0

package/src/core/gateway/client/fetch.ts

@@ -0,0 +1,180 @@
+import { requirePortalClientId, PORTAL_CLIENT_ID_HEADER } from "../../http/client-id.js";
+import { HttpApiError } from "../../http/errors.js";
+import {
+  buildGatewayHttpError,
+  parseGatewayErrorText,
+} from "../../http/gateway-error.js";
+import {
+  createRawHttpApiClient,
+  toHttpRequestInit,
+} from "../../http/raw-client.js";
+import type { HttpApiTrace } from "../../http/types.js";
+
+export type GatewayHttpFetchOptions = Omit<RequestInit, "headers"> & {
+  httpBaseUrl: string;
+  clientId: string;
+  authToken: string | null;
+  /** Shown in thrown errors, e.g. "Gateway API". */
+  apiLabel: string;
+  headers?: Record<string, string>;
+  sessionAuthMode?: boolean;
+  surface?: HttpApiTrace["surface"];
+  fetchImpl?: typeof fetch;
+};
+
+export function buildGatewayAuthHeaders(
+  clientId: string,
+  authToken: string | null,
+  options?: {
+    includeBearerToken?: boolean;
+  },
+): Record<string, string> {
+  const includeBearerToken = options?.includeBearerToken ?? true;
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    [PORTAL_CLIENT_ID_HEADER]: requirePortalClientId(clientId),
+  };
+  if (includeBearerToken && authToken) {
+    headers.Authorization = `Bearer ${authToken}`;
+  }
+  return headers;
+}
+
+export function resolveGatewayRequestCredentials(
+  sessionAuthMode: boolean | null | undefined,
+): RequestCredentials | undefined {
+  return sessionAuthMode ? "same-origin" : undefined;
+}
+
+async function parseGatewayJsonResponse<T>(
+  res: Response,
+  endpoint: string,
+  apiLabel: string,
+): Promise<T> {
+  const contentType = res.headers.get("content-type") ?? "";
+  const text = await res.text();
+
+  if (!res.ok) {
+    const details = parseGatewayErrorText(text, contentType);
+    throw buildGatewayHttpError({
+      label: apiLabel,
+      status: res.status,
+      statusText: res.statusText,
+      message: details.message,
+      code: details.code,
+    });
+  }
+
+  if (!contentType.includes("application/json")) {
+    const trimmed = text.trimStart().toLowerCase();
+    const htmlHint =
+      trimmed.startsWith("<!doctype") || trimmed.startsWith("<html")
+        ? ` (received HTML - check ${endpoint} gateway wiring)`
+        : "";
+
+    throw new Error(
+      `Expected JSON from ${endpoint}, got ${contentType || "unknown"}${htmlHint}`,
+    );
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Invalid JSON from ${endpoint}.`);
+  }
+}
+
+function throwGatewayHttpErrorFromCore(
+  error: HttpApiError,
+  apiLabel: string,
+): never {
+  const details = parseGatewayErrorText(error.body, "application/json");
+  throw buildGatewayHttpError({
+    label: apiLabel,
+    status: error.status,
+    statusText: "",
+    message: details.message,
+    code: details.code,
+  });
+}
+
+export async function requestGatewayRaw(
+  path: string,
+  options: GatewayHttpFetchOptions,
+): Promise<Response> {
+  const {
+    httpBaseUrl,
+    clientId,
+    authToken,
+    apiLabel,
+    headers: extraHeaders,
+    sessionAuthMode,
+    surface,
+    fetchImpl,
+    ...init
+  } = options;
+  const credentials = resolveGatewayRequestCredentials(sessionAuthMode);
+  const client = createRawHttpApiClient({
+    surface: surface ?? "gateway-api",
+    baseUrl: httpBaseUrl,
+    authToken: sessionAuthMode ? null : authToken,
+    clientId,
+    credentials,
+    fetchImpl,
+  });
+
+  try {
+    return await client.raw(
+      path,
+      toHttpRequestInit(
+        {
+          ...init,
+          ...(credentials ? { credentials } : {}),
+        },
+        extraHeaders,
+      ),
+    );
+  } catch (error) {
+    if (error instanceof HttpApiError && error.status > 0) {
+      throwGatewayHttpErrorFromCore(error, apiLabel);
+    }
+    throw error;
+  }
+}
+
+export async function fetchGatewayJson<T>(
+  path: string,
+  options: GatewayHttpFetchOptions,
+): Promise<T> {
+  const res = await requestGatewayRaw(path, options);
+  return parseGatewayJsonResponse<T>(res, path, options.apiLabel);
+}
+
+export async function fetchGatewayExpectOk(
+  path: string,
+  options: GatewayHttpFetchOptions,
+): Promise<void> {
+  await requestGatewayRaw(path, options);
+}
+
+export async function fetchGatewayBlob(
+  path: string,
+  options: GatewayHttpFetchOptions,
+): Promise<Blob> {
+  const res = await requestGatewayRaw(path, options);
+  return res.blob();
+}
+
+export async function fetchGatewayFormDataJson<T>(
+  path: string,
+  options: Omit<GatewayHttpFetchOptions, "body" | "method"> & {
+    body: FormData;
+  },
+): Promise<T> {
+  const res = await requestGatewayRaw(path, {
+    ...options,
+    method: "POST",
+    body: options.body,
+  });
+  return parseGatewayJsonResponse<T>(res, path, options.apiLabel);
+}

package/src/core/gateway/client/index.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./capabilities.js";
+export * from "./error-details.js";
+export * from "./fetch.js";
+export * from "./runtime-targets.js";

package/src/core/gateway/client/runtime-targets.ts

@@ -0,0 +1,132 @@
+import { resolveGatewayTargets } from "../../ws/targets.js";
+
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+const DEFAULT_LOCAL_GATEWAY_WS_URL = "ws://127.0.0.1:18789/ws";
+
+export type ResolveGatewayRuntimeTargetOptions = {
+  configuredGatewayBaseUrl?: string | null;
+  windowOrigin?: string | null;
+  fallbackWsUrl?: string;
+};
+
+export function normalizeGatewayBaseUrl(
+  rawGatewayBaseUrl: string | null | undefined,
+): string | null {
+  const trimmed = rawGatewayBaseUrl?.trim() ?? "";
+  if (!trimmed) {
+    return null;
+  }
+  return trimmed.replace(/\/+$/u, "");
+}
+
+function loopbackEquivalenceKey(url: URL): string | null {
+  const proto = url.protocol.toLowerCase();
+  if (proto !== "http:" && proto !== "https:") {
+    return null;
+  }
+  if (!LOOPBACK_HOSTNAMES.has(url.hostname.toLowerCase())) {
+    return null;
+  }
+  const effectivePort = url.port || (proto === "https:" ? "443" : "80");
+  return `${proto}//loopback:${effectivePort}`;
+}
+
+export function sameGatewayDaemon(
+  leftBaseUrl: string | null | undefined,
+  rightBaseUrl: string | null | undefined,
+): boolean {
+  const left = normalizeGatewayBaseUrl(leftBaseUrl);
+  const right = normalizeGatewayBaseUrl(rightBaseUrl);
+  if (!left || !right) {
+    return false;
+  }
+  if (left === right) {
+    return true;
+  }
+
+  let leftUrl: URL;
+  let rightUrl: URL;
+  try {
+    leftUrl = new URL(left);
+    rightUrl = new URL(right);
+  } catch {
+    return false;
+  }
+
+  const leftLoopback = loopbackEquivalenceKey(leftUrl);
+  const rightLoopback = loopbackEquivalenceKey(rightUrl);
+  return (
+    leftLoopback !== null &&
+    rightLoopback !== null &&
+    leftLoopback === rightLoopback
+  );
+}
+
+function originToWsUrl(origin: string): string {
+  const wsProtocol = origin.startsWith("https") ? "wss:" : "ws:";
+  const url = new URL(origin);
+  return `${wsProtocol}//${url.host}/ws`;
+}
+
+export function resolveGatewayRuntimeHttpBase(
+  gatewayBaseUrl: string,
+  options: ResolveGatewayRuntimeTargetOptions = {},
+): string {
+  const normalizedGatewayBaseUrl = normalizeGatewayBaseUrl(gatewayBaseUrl);
+  const configuredGatewayBaseUrl = normalizeGatewayBaseUrl(
+    options.configuredGatewayBaseUrl,
+  );
+  const windowOrigin = options.windowOrigin?.trim() || null;
+
+  if (
+    normalizedGatewayBaseUrl &&
+    configuredGatewayBaseUrl &&
+    windowOrigin &&
+    sameGatewayDaemon(normalizedGatewayBaseUrl, configuredGatewayBaseUrl)
+  ) {
+    return windowOrigin;
+  }
+
+  if (!normalizedGatewayBaseUrl) {
+    return windowOrigin ?? "";
+  }
+
+  return resolveGatewayTargets(normalizedGatewayBaseUrl).httpBase;
+}
+
+export function resolveGatewayRuntimeWsUrl(
+  gatewayBaseUrl: string,
+  options: ResolveGatewayRuntimeTargetOptions = {},
+): string {
+  const normalizedGatewayBaseUrl = normalizeGatewayBaseUrl(gatewayBaseUrl);
+  const configuredGatewayBaseUrl = normalizeGatewayBaseUrl(
+    options.configuredGatewayBaseUrl,
+  );
+  const windowOrigin = options.windowOrigin?.trim() || null;
+
+  if (
+    normalizedGatewayBaseUrl &&
+    configuredGatewayBaseUrl &&
+    windowOrigin &&
+    sameGatewayDaemon(normalizedGatewayBaseUrl, configuredGatewayBaseUrl)
+  ) {
+    return originToWsUrl(windowOrigin);
+  }
+
+  if (!normalizedGatewayBaseUrl) {
+    return windowOrigin
+      ? originToWsUrl(windowOrigin)
+      : (options.fallbackWsUrl ?? DEFAULT_LOCAL_GATEWAY_WS_URL);
+  }
+
+  return resolveGatewayTargets(normalizedGatewayBaseUrl).wsUrl;
+}
+
+export function resolveGatewayRuntimeHttpUrl(
+  gatewayBaseUrl: string,
+  pathname: string,
+  options: ResolveGatewayRuntimeTargetOptions = {},
+): string {
+  const normalizedPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return `${resolveGatewayRuntimeHttpBase(gatewayBaseUrl, options)}${normalizedPath}`;
+}

package/src/core/gateway/envelope/envelope.ts

@@ -0,0 +1,204 @@
+import { GatewayHttpError } from "../../http/gateway-error.js";
+import type {
+  ContractGap,
+  ContractGapReason,
+  DataEnvelope,
+  MutationResult,
+} from "./types.js";
+
+export type {
+  ConnectivityDomain,
+  ConnectivityStatus,
+  ContractGap,
+  ContractGapReason,
+  DataEnvelope,
+  DataSourceMode,
+  MutationResult,
+} from "./types.js";
+
+export function fallbackGap(
+  area: string,
+  expectedContract: string,
+  note: string,
+  reason?: ContractGapReason,
+  httpStatus?: number,
+): ContractGap {
+  return {
+    area,
+    expectedContract,
+    note,
+    reason,
+    httpStatus,
+  };
+}
+
+function normalizeErrorMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).trim();
+}
+
+function isBackendFailureMessage(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes("unavailable") ||
+    normalized.includes("not available") ||
+    normalized.includes("fetch failed") ||
+    normalized.includes("failed to fetch") ||
+    normalized.includes("network error") ||
+    normalized.includes("networkerror") ||
+    normalized.includes("econn") ||
+    normalized.includes("timed out") ||
+    normalized.includes("timeout") ||
+    normalized.includes("refused")
+  );
+}
+
+function isTransportFailureMessage(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes("not connected") ||
+    normalized.includes("gateway client not connected") ||
+    normalized.includes("socket") ||
+    normalized.includes("websocket")
+  );
+}
+
+export function classifyFallbackError(error: unknown): {
+  message: string;
+  reason: ContractGapReason;
+  httpStatus?: number;
+} {
+  if (error instanceof GatewayHttpError) {
+    if (error.status === 404) {
+      return {
+        message: "The current gateway does not expose one or more required routes yet.",
+        reason: "endpoint-not-found",
+        httpStatus: 404,
+      };
+    }
+    if (error.status === 502 || error.status === 503) {
+      return {
+        message: `Backend unavailable (${error.status}).`,
+        reason: "backend-unavailable",
+        httpStatus: error.status,
+      };
+    }
+    return {
+      message: `Gateway request failed with ${error.status}.`,
+      reason: "backend-unavailable",
+      httpStatus: error.status,
+    };
+  }
+
+  const msg = normalizeErrorMessage(error);
+  // Gateway returns `unknown method: …` when the running binary predates a WS handler.
+  // Treat as unavailable so dashboards degrade to mock data + contract gap instead of hard-failing queries.
+  if (/unknown method\b/i.test(msg)) {
+    return {
+      message: `Gateway RPC not supported: ${msg}`,
+      reason: "backend-unavailable",
+    };
+  }
+  if (isTransportFailureMessage(msg)) {
+    return {
+      message: `Transport disconnected: ${msg}.`,
+      reason: "transport-disconnected",
+    };
+  }
+  if (isBackendFailureMessage(msg)) {
+    return {
+      message: error instanceof TypeError
+        ? "The gateway request failed before a response was received."
+        : `Backend unavailable: ${msg}.`,
+      reason: "backend-unavailable",
+    };
+  }
+  if (error instanceof TypeError) {
+    return {
+      message: `Runtime: ${msg}.`,
+      reason: "unknown",
+    };
+  }
+
+  return {
+    message: `Runtime: ${msg}.`,
+    reason: "unknown",
+  };
+}
+
+/** @deprecated Use {@link classifyFallbackError} for structured diagnostics. */
+export function describeFallbackReason(error: unknown): string {
+  return classifyFallbackError(error).message;
+}
+
+export async function withFallback<TData>(params: {
+  run: () => Promise<TData>;
+  fallback: TData;
+  area: string;
+  expectedContract: string;
+  note: string;
+}): Promise<DataEnvelope<TData>> {
+  try {
+    const data = await params.run();
+    return {
+      data,
+      source: "gateway",
+      fetchedAt: Date.now(),
+      contractGaps: [],
+    };
+  } catch (error) {
+    if (
+      error instanceof GatewayHttpError &&
+      (error.status === 401 || error.status === 403)
+    ) {
+      throw error;
+    }
+
+    const classified = classifyFallbackError(error);
+    if (classified.reason === "unknown") {
+      throw error;
+    }
+    return {
+      data: params.fallback,
+      source: "mock",
+      fetchedAt: Date.now(),
+      contractGaps: [
+        fallbackGap(
+          params.area,
+          params.expectedContract,
+          `${params.note}. ${classified.message}`,
+          classified.reason,
+          classified.httpStatus,
+        ),
+      ],
+    };
+  }
+}
+
+export async function withMutationResult<TData>(params: {
+  run: () => Promise<TData>;
+  fallback: () => TData;
+  area: string;
+  expectedContract: string;
+  note: string;
+}): Promise<MutationResult<TData>> {
+  try {
+    const data = await params.run();
+    return {
+      data,
+      source: "gateway",
+      appliedAt: Date.now(),
+      contractGaps: [],
+    };
+  } catch (error) {
+    if (
+      error instanceof GatewayHttpError &&
+      (error.status === 401 || error.status === 403)
+    ) {
+      throw error;
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `${params.note}. ${params.expectedContract} unavailable: ${reason}`, { cause: error },
+    );
+  }
+}

package/src/core/gateway/envelope/index.ts

@@ -0,0 +1,2 @@
+export * from "./envelope.js";
+export type * from "./types.js";

package/src/core/gateway/envelope/types.ts

@@ -0,0 +1,48 @@
+export type DataSourceMode = "gateway" | "mock";
+
+export type ContractGapReason =
+  | "backend-unavailable"
+  | "backend-not-configured"
+  | "endpoint-not-found"
+  | "auth-insufficient"
+  | "transport-disconnected"
+  | "unknown";
+
+export type ContractGap = {
+  area: string;
+  expectedContract: string;
+  note: string;
+  reason?: ContractGapReason;
+  httpStatus?: number;
+};
+
+export type DataEnvelope<TData> = {
+  data: TData;
+  source: DataSourceMode;
+  fetchedAt: number;
+  contractGaps: ContractGap[];
+};
+
+export type ConnectivityStatus =
+  | "live"
+  | "empty-but-valid"
+  | "mock-fallback"
+  | "conditional-unavailable"
+  | "not-loaded";
+
+export type ConnectivityDomain = {
+  domain: string;
+  label: string;
+  transport: "ws" | "http" | "mixed";
+  source: DataSourceMode | "not-loaded";
+  status: ConnectivityStatus;
+  contractGaps: readonly ContractGap[];
+  fetchedAt: number | null;
+};
+
+export type MutationResult<TData> = {
+  data: TData;
+  source: DataSourceMode;
+  appliedAt: number;
+  contractGaps: ContractGap[];
+};

package/src/core/gateway/index.ts

@@ -0,0 +1,10 @@
+export * from "./client/index.js";
+export * from "./agent/index.js";
+export * from "./run/index.js";
+export * from "./rpc/index.js";
+export * from "./snapshots/index.js";
+export * from "./resources/index.js";
+export * from "./envelope/index.js";
+export * from "./portal/index.js";
+export * from "./providers/index.js";
+export * from "./jobs.js";