@cavi-ai/api-client 0.1.0

package/src/core/http/client.ts

@@ -0,0 +1,271 @@
+import {
+  IDEMPOTENCY_KEY_HEADER,
+  PORTAL_CLIENT_ID_HEADER,
+  type HttpApiClientOptions,
+  type HttpApiHttpMethod,
+  type HttpApiRequestInit,
+  type HttpApiTrace,
+  type HttpApiTransport,
+} from "./types.js";
+import { HttpApiError } from "./errors.js";
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_CLIENT_ID = "cavi-api-client";
+
+function normalizeBaseUrl(baseUrl: string, allowRelative = false): string {
+  const trimmed = baseUrl.trim();
+  if (!trimmed && allowRelative) return "";
+  if (!trimmed) throw new Error("Missing baseUrl for HTTP API client");
+  return trimmed.replace(/\/+$/, "");
+}
+
+function normalizePath(path: string): string {
+  const trimmed = path.trim();
+  if (!trimmed) return "/";
+  return trimmed.charAt(0) === "/" ? trimmed : `/${trimmed}`;
+}
+
+function normalizeBasePath(basePath?: string): string {
+  if (!basePath) return "";
+  const path = normalizePath(basePath).replace(/\/+$/, "");
+  return path === "/" ? "" : path;
+}
+
+function previewErrorBody(body: string): string {
+  return body.length > 500 ? `${body.slice(0, 500)}…` : body;
+}
+
+function buildUrl(baseUrl: string, basePath: string, path: string): string {
+  return `${baseUrl}${basePath}${normalizePath(path)}`;
+}
+
+function buildRequestBody(init?: HttpApiRequestInit): BodyInit | undefined {
+  if (!init) return undefined;
+  if ("rawBody" in init && init.rawBody !== undefined) return init.rawBody;
+  if (!("body" in init) || init.body === undefined) return undefined;
+  return JSON.stringify(init.body);
+}
+
+function createRequestAbortSignal(
+  timeoutMs: number,
+  inputSignal?: AbortSignal,
+): { signal: AbortSignal; cleanup: () => void } {
+  const controller = new AbortController();
+  const abort = (reason?: unknown): void => {
+    if (controller.signal.aborted) return;
+    if (reason !== undefined) {
+      controller.abort(reason);
+      return;
+    }
+    controller.abort();
+  };
+  const abortFromInputSignal = (): void => abort(inputSignal?.reason);
+
+  if (inputSignal?.aborted) {
+    abortFromInputSignal();
+  } else {
+    inputSignal?.addEventListener("abort", abortFromInputSignal, { once: true });
+  }
+
+  const timeout = setTimeout(() => abort(), timeoutMs);
+
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      inputSignal?.removeEventListener("abort", abortFromInputSignal);
+    },
+  };
+}
+
+export class BaseHttpApiClient {
+  readonly surface: HttpApiTrace["surface"];
+  readonly baseUrl: string;
+  readonly basePath: string;
+  readonly authToken: string;
+  readonly clientId: string;
+  readonly defaultTimeoutMs: number;
+  readonly cache: RequestCache;
+  readonly credentials?: RequestCredentials;
+
+  private readonly fetchImpl: typeof fetch;
+  private readonly onTrace?: (trace: HttpApiTrace) => void;
+
+  constructor(surface: HttpApiTrace["surface"], options: HttpApiClientOptions) {
+    this.surface = surface;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl, options.allowRelativeBaseUrl);
+    this.basePath = normalizeBasePath(options.basePath);
+    this.authToken = options.auth?.bearerToken?.trim() ?? "";
+    this.clientId = options.auth?.clientId?.trim() || DEFAULT_CLIENT_ID;
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.cache = options.cache ?? "no-store";
+    this.credentials = options.credentials;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.onTrace = options.onTrace;
+  }
+
+  protected resolvePath(path: string): string {
+    return normalizePath(path);
+  }
+
+  protected resolveUrl(path: string): string {
+    return buildUrl(this.baseUrl, this.basePath, path);
+  }
+
+  protected buildHeaders(init?: HttpApiRequestInit): Record<string, string> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      [PORTAL_CLIENT_ID_HEADER]: this.clientId,
+      ...(init?.headers ?? {}),
+    };
+
+    if (this.authToken) {
+      headers.Authorization = `Bearer ${this.authToken}`;
+    }
+    if (init?.idempotencyKey) {
+      headers[IDEMPOTENCY_KEY_HEADER] = init.idempotencyKey;
+    }
+    if (init && "body" in init && init.body !== undefined) {
+      headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+    }
+    return headers;
+  }
+
+  protected buildBody(init?: HttpApiRequestInit): BodyInit | undefined {
+    return buildRequestBody(init);
+  }
+
+  protected buildFetchInit(
+    method: HttpApiHttpMethod,
+    headers: Record<string, string>,
+    body: BodyInit | undefined,
+    signal: AbortSignal,
+    init?: HttpApiRequestInit,
+  ): RequestInit {
+    return {
+      method,
+      headers,
+      body,
+      cache: init?.cache ?? this.cache,
+      credentials: init?.credentials ?? this.credentials,
+      signal,
+    };
+  }
+
+  protected emitTrace(trace: HttpApiTrace): void {
+    try {
+      this.onTrace?.(trace);
+    } catch {
+      // Trace observers must not change request behavior.
+    }
+  }
+
+  protected async requestRaw(path: string, init?: HttpApiRequestInit): Promise<Response> {
+    const normalizedPath = this.resolvePath(path);
+    const method: HttpApiHttpMethod = init?.method ?? "GET";
+    const startedAt = Date.now();
+    const timeoutMs = init?.timeoutMs ?? this.defaultTimeoutMs;
+    const abortSignal = createRequestAbortSignal(timeoutMs, init?.signal);
+    const headers = this.buildHeaders(init);
+    const body = this.buildBody(init);
+    const url = this.resolveUrl(normalizedPath);
+
+    try {
+      const response = await this.fetchImpl(
+        url,
+        this.buildFetchInit(method, headers, body, abortSignal.signal, init),
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        this.emitTrace({
+          at: Date.now(),
+          surface: this.surface,
+          method,
+          path: normalizedPath,
+          url,
+          ok: false,
+          status: response.status,
+          durationMs: Date.now() - startedAt,
+          error: previewErrorBody(errorText),
+        });
+        throw new HttpApiError({
+          message: `${method} ${normalizedPath} failed with HTTP ${response.status}`,
+          path: normalizedPath,
+          url,
+          method,
+          status: response.status,
+          body: errorText,
+        });
+      }
+
+      this.emitTrace({
+        at: Date.now(),
+        surface: this.surface,
+        method,
+        path: normalizedPath,
+        url,
+        ok: true,
+        status: response.status,
+        durationMs: Date.now() - startedAt,
+      });
+
+      return response;
+    } catch (error) {
+      if (error instanceof HttpApiError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      this.emitTrace({
+        at: Date.now(),
+        surface: this.surface,
+        method,
+        path: normalizedPath,
+        url,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        error: message,
+      });
+      throw new HttpApiError({
+        message: `${method} ${normalizedPath} failed: ${message}`,
+        path: normalizedPath,
+        url,
+        method,
+        status: 0,
+        body: "",
+      });
+    } finally {
+      abortSignal.cleanup();
+    }
+  }
+
+  protected async requestJson<TResponse>(path: string, init?: HttpApiRequestInit): Promise<TResponse> {
+    const response = await this.requestRaw(path, init);
+    const text = await response.text();
+    if (!text.trim()) {
+      return {} as TResponse;
+    }
+    try {
+      return JSON.parse(text) as TResponse;
+    } catch {
+      throw new HttpApiError({
+        message: `${init?.method ?? "GET"} ${this.resolvePath(path)} returned invalid JSON`,
+        path: this.resolvePath(path),
+        url: this.resolveUrl(path),
+        method: init?.method ?? "GET",
+        status: response.status,
+        body: text,
+      });
+    }
+  }
+
+  protected async requestBlob(path: string, init?: HttpApiRequestInit): Promise<Blob> {
+    const response = await this.requestRaw(path, init);
+    return response.blob();
+  }
+
+  createTransport(): HttpApiTransport {
+    return <TResponse>(path: string, init?: HttpApiRequestInit): Promise<TResponse> =>
+      this.requestJson<TResponse>(path, init);
+  }
+}

package/src/core/http/contracts.ts

@@ -0,0 +1,9 @@
+/** Human-readable HTTP contract line for envelopes and diagnostics. */
+export function describeHttpContract(
+  method: string,
+  path: string,
+  bodyHint?: string,
+): string {
+  const base = `${method} ${path}`;
+  return bodyHint ? `${base} ${bodyHint}` : base;
+}

package/src/core/http/errors.ts

@@ -0,0 +1,26 @@
+import type { HttpApiHttpMethod } from "./types.js";
+
+export class HttpApiError extends Error {
+  readonly path: string;
+  readonly url: string;
+  readonly method: HttpApiHttpMethod;
+  readonly status: number;
+  readonly body: string;
+
+  constructor(params: {
+    message: string;
+    path: string;
+    url: string;
+    method: HttpApiHttpMethod;
+    status: number;
+    body: string;
+  }) {
+    super(params.message);
+    this.name = "HttpApiError";
+    this.path = params.path;
+    this.url = params.url;
+    this.method = params.method;
+    this.status = params.status;
+    this.body = params.body;
+  }
+}

package/src/core/http/gateway-error.ts

@@ -0,0 +1,38 @@
+import {
+  cleanGatewayErrorText,
+  extractGatewayErrorDetails,
+  formatGatewayHttpErrorMessage,
+  parseGatewayErrorText,
+} from "../gateway/client/error-details.js";
+
+export {
+  cleanGatewayErrorText,
+  extractGatewayErrorDetails,
+  parseGatewayErrorText,
+};
+
+export class GatewayHttpError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+
+  constructor(message: string, status: number, code: string | null = null) {
+    super(message);
+    this.name = "GatewayHttpError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function buildGatewayHttpError(params: {
+  label: string;
+  status: number;
+  statusText: string;
+  message?: string | null;
+  code?: string | null;
+}): GatewayHttpError {
+  return new GatewayHttpError(
+    formatGatewayHttpErrorMessage(params),
+    params.status,
+    cleanGatewayErrorText(params.code),
+  );
+}

package/src/core/http/index.ts

@@ -0,0 +1,9 @@
+export * from "./client-id.js";
+export * from "./client.js";
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./gateway-error.js";
+export * from "./json-client.js";
+export * from "./raw-client.js";
+export * from "./redaction.js";
+export * from "./types.js";

package/src/core/http/json-client.ts

@@ -0,0 +1,90 @@
+import { BaseHttpApiClient } from "./client.js";
+import { HttpApiError } from "./errors.js";
+import type { HttpApiRequestInit, HttpApiTrace } from "./types.js";
+import {
+  buildGatewayHttpError,
+  parseGatewayErrorText,
+} from "./gateway-error.js";
+
+export function withQuery(
+  path: string,
+  params: Record<string, string | number | undefined>,
+): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) {
+      continue;
+    }
+    search.set(key, String(value));
+  }
+  const query = search.toString();
+  return query ? `${path}?${query}` : path;
+}
+
+export type JsonHttpRequest = <TData>(
+  path: string,
+  init?: HttpApiRequestInit,
+) => Promise<TData>;
+
+export class JsonHttpApiClient extends BaseHttpApiClient {
+  request<TData>(path: string, init?: HttpApiRequestInit): Promise<TData> {
+    return this.requestJsonBody<TData>(path, init);
+  }
+
+  private async requestJsonBody<TData>(
+    path: string,
+    init?: HttpApiRequestInit,
+  ): Promise<TData> {
+    try {
+      const response = await this.requestRaw(path, init);
+      const text = await response.text();
+      if (response.status === 204 || !text.trim()) {
+        return {} as TData;
+      }
+      try {
+        return JSON.parse(text) as TData;
+      } catch {
+        throw new Error(`Invalid JSON from ${path}.`);
+      }
+    } catch (error) {
+      if (error instanceof HttpApiError && error.status > 0) {
+        const details = parseGatewayErrorText(error.body, "application/json");
+        throw buildGatewayHttpError({
+          label: error.path,
+          status: error.status,
+          statusText: "",
+          message: details.message,
+          code: details.code,
+        });
+      }
+      throw error;
+    }
+  }
+}
+
+export function createJsonHttpRequest(opts: {
+  surface: HttpApiTrace["surface"];
+  httpBase: string;
+  authToken: string | null;
+  clientId?: string | null;
+  credentials?: RequestCredentials;
+  cache?: RequestCache;
+}): JsonHttpRequest {
+  const client = new JsonHttpApiClient(opts.surface, {
+    baseUrl: opts.httpBase,
+    allowRelativeBaseUrl: true,
+    auth: {
+      bearerToken: opts.authToken,
+      clientId: opts.clientId,
+    },
+    credentials: opts.credentials,
+    cache: opts.cache,
+  });
+
+  return async function requestJson<TData>(
+    path: string,
+    init?: HttpApiRequestInit,
+  ): Promise<TData> {
+    return await client.request<TData>(path, init);
+  };
+}

package/src/core/http/raw-client.ts

@@ -0,0 +1,57 @@
+import { BaseHttpApiClient } from "./client.js";
+import type {
+  HttpApiHttpMethod,
+  HttpApiRequestInit,
+  HttpApiTrace,
+} from "./types.js";
+
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+function normalizeHttpMethod(method: string | undefined): HttpApiHttpMethod | undefined {
+  const normalized = method?.trim().toUpperCase();
+  return normalized && HTTP_METHODS.has(normalized)
+    ? (normalized as HttpApiHttpMethod)
+    : undefined;
+}
+
+export class RawHttpApiClient extends BaseHttpApiClient {
+  raw(path: string, init?: HttpApiRequestInit): Promise<Response> {
+    return this.requestRaw(path, init);
+  }
+}
+
+export function createRawHttpApiClient(params: {
+  surface: HttpApiTrace["surface"];
+  baseUrl: string;
+  authToken: string | null;
+  clientId?: string | null;
+  credentials?: RequestCredentials;
+  cache?: RequestCache;
+  fetchImpl?: typeof fetch;
+}): RawHttpApiClient {
+  return new RawHttpApiClient(params.surface, {
+    baseUrl: params.baseUrl,
+    allowRelativeBaseUrl: true,
+    auth: {
+      bearerToken: params.authToken,
+      clientId: params.clientId,
+    },
+    credentials: params.credentials,
+    cache: params.cache,
+    fetchImpl: params.fetchImpl,
+  });
+}
+
+export function toHttpRequestInit(
+  init: RequestInit | undefined,
+  headers?: Record<string, string>,
+): HttpApiRequestInit {
+  return {
+    method: normalizeHttpMethod(init?.method),
+    headers,
+    rawBody: init?.body ?? undefined,
+    signal: init?.signal ?? undefined,
+    cache: init?.cache ?? undefined,
+    credentials: init?.credentials ?? undefined,
+  };
+}

package/src/core/http/redaction.ts

@@ -0,0 +1,78 @@
+/**
+ * Single source of truth for scrubbing secrets out of values, text, and config
+ * keys before they are logged, previewed, or rendered.
+ *
+ * Gateway-agnostic: the same sensitivity rule governs HTTP request/response
+ * previews and config-path filtering so the two can never drift apart.
+ */
+
+export const REDACTION_PLACEHOLDER = "[REDACTED]";
+export const DEFAULT_PREVIEW_MAX_CHARS = 12_000;
+
+/**
+ * Matches a key segment that names a credential. Segments may be separated by
+ * `.`, `_`, or `-` (e.g. `model.api_key`, `auth-token`, `refreshToken`).
+ */
+export const SENSITIVE_KEY_PATTERN =
+  /(^|[._-])(api[_-]?key|secret|password|private[_-]?key|credential|authorization|auth[_-]?token|access[_-]?token|refresh[_-]?token|token|cookie)([._-]|$)/iu;
+
+const SENSITIVE_TEXT_PATTERN =
+  /((?:api[_-]?key|secret|password|private[_-]?key|credential|authorization|auth[_-]?token|access[_-]?token|refresh[_-]?token|token|cookie)["']?\s*[:=]\s*["']?)([^"',}\]\s&]+)/giu;
+
+const BEARER_TOKEN_PATTERN = /(Bearer\s+)([A-Za-z0-9._~+/=-]+)/gu;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isSensitiveKey(key: string): boolean {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
+
+export function redactSensitiveValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactSensitiveValue(entry));
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      isSensitiveKey(key) ? REDACTION_PLACEHOLDER : redactSensitiveValue(entry),
+    ]),
+  );
+}
+
+export function redactSensitiveText(text: string): string {
+  return text
+    .replace(SENSITIVE_TEXT_PATTERN, `$1${REDACTION_PLACEHOLDER}`)
+    .replace(BEARER_TOKEN_PATTERN, `$1${REDACTION_PLACEHOLDER}`);
+}
+
+function truncate(raw: string, maxChars: number): string {
+  return raw.length > maxChars ? `${raw.slice(0, maxChars)}...[truncated]` : raw;
+}
+
+export function stringifyRedacted(
+  value: unknown,
+  maxChars = DEFAULT_PREVIEW_MAX_CHARS,
+): string | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const raw =
+      typeof value === "string"
+        ? redactSensitiveText(value)
+        : JSON.stringify(redactSensitiveValue(value));
+    return truncate(raw, maxChars);
+  } catch {
+    return "[unserializable body]";
+  }
+}
+
+export function redactPreviewText(
+  text: string,
+  maxChars = DEFAULT_PREVIEW_MAX_CHARS,
+): string {
+  return truncate(redactSensitiveText(text), maxChars);
+}

package/src/core/http/types.ts

@@ -0,0 +1,59 @@
+export const PORTAL_CLIENT_ID_HEADER = "X-Portal-Client-Id" as const;
+export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key" as const;
+
+// A free-form surface label used only for tracing/observability. Core stays
+// surface-agnostic: callers (extensions/cavi, providers/*) pass whatever name
+// identifies their surface. (A `"literal" | string` union collapses to `string`
+// in TypeScript, so naming specific surfaces here bought no type safety — only
+// leaked domain names into core.)
+export type HttpApiClientSurface = string;
+
+export type HttpApiHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export type HttpApiRequestInit = {
+  method?: HttpApiHttpMethod;
+  body?: unknown;
+  rawBody?: BodyInit;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  idempotencyKey?: string;
+  cache?: RequestCache;
+  credentials?: RequestCredentials;
+};
+
+export type HttpApiTrace = {
+  at: number;
+  surface: HttpApiClientSurface;
+  method: HttpApiHttpMethod;
+  path: string;
+  url: string;
+  ok: boolean;
+  status?: number;
+  durationMs: number;
+  error?: string;
+};
+
+export type HttpApiTransport = <TResponse>(
+  path: string,
+  init?: HttpApiRequestInit,
+) => Promise<TResponse>;
+
+export type HttpApiClientAuth = {
+  bearerToken?: string | null;
+  clientId?: string | null;
+};
+
+export type HttpApiClientOptions = {
+  baseUrl: string;
+  basePath?: string;
+  allowRelativeBaseUrl?: boolean;
+  auth?: HttpApiClientAuth;
+  defaultTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  cache?: RequestCache;
+  credentials?: RequestCredentials;
+  onTrace?: (trace: HttpApiTrace) => void;
+};
+
+export { HttpApiError } from "./errors.js";

package/src/core/runtime/index.ts

@@ -0,0 +1 @@
+export * from "./paths.js";

package/src/core/runtime/paths.ts

@@ -0,0 +1,44 @@
+export function normalizeRuntimeBasePath(
+  rawBasePath: string | null | undefined,
+): string {
+  const trimmed = rawBasePath?.trim() ?? "/";
+  if (!trimmed || trimmed === "/" || trimmed === "./") {
+    return "";
+  }
+  const stripped = trimmed.replace(/^\/+|\/+$/g, "");
+  return stripped ? `/${stripped}` : "";
+}
+
+export function getBrowserWindowOrigin(): string | null {
+  return typeof window === "undefined" ? null : (window.location?.origin ?? null);
+}
+
+export function withRuntimeBasePath(
+  pathname: string,
+  rawBasePath: string | null | undefined,
+): string {
+  if (
+    /^https?:\/\//i.test(pathname) ||
+    pathname.startsWith("data:") ||
+    pathname.startsWith("blob:")
+  ) {
+    return pathname;
+  }
+  const normalizedPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  const basePath = normalizeRuntimeBasePath(rawBasePath);
+  if (
+    !basePath ||
+    normalizedPath === basePath ||
+    normalizedPath.startsWith(`${basePath}/`)
+  ) {
+    return normalizedPath;
+  }
+  return `${basePath}${normalizedPath}`;
+}
+
+export function resolvePublicRuntimeAsset(
+  pathname: string,
+  rawBasePath: string | null | undefined,
+): string {
+  return withRuntimeBasePath(pathname, rawBasePath);
+}

package/src/core/sse/index.ts

@@ -0,0 +1 @@
+export * from "./stream.js";