@cavi-ai/api-client 0.1.0

package/src/core/gateway/jobs.ts

@@ -0,0 +1,178 @@
+export type GatewayJobStatus =
+  | "queued"
+  | "running"
+  | "completed"
+  | "succeeded"
+  | "failed"
+  | "cancelled"
+  | "canceled"
+  | "stopping"
+  | "stopped"
+  | string;
+
+export type GatewayJobLike = {
+  status?: GatewayJobStatus | null;
+  error?: unknown;
+};
+
+export const GATEWAY_JOB_SUCCESS_STATUSES = [
+  "completed",
+  "succeeded",
+  "success",
+] as const;
+
+export const GATEWAY_JOB_TERMINAL_STATUSES = [
+  ...GATEWAY_JOB_SUCCESS_STATUSES,
+  "failed",
+  "error",
+  "cancelled",
+  "canceled",
+  "stopped",
+] as const;
+
+export type GatewayJobWaitUpdate<TJob extends GatewayJobLike> = {
+  attempt: number;
+  elapsedMs: number;
+  job: TJob;
+};
+
+export type GatewayJobSleep = (
+  delayMs: number,
+  signal?: AbortSignal,
+) => Promise<void>;
+
+export type GatewayJobWaitOptions<TJob extends GatewayJobLike> = {
+  fetchJob: () => Promise<TJob>;
+  intervalMs?: number;
+  timeoutMs?: number;
+  maxAttempts?: number;
+  signal?: AbortSignal;
+  onUpdate?: (update: GatewayJobWaitUpdate<TJob>) => void;
+  isTerminal?: (job: TJob) => boolean;
+  sleep?: GatewayJobSleep;
+  now?: () => number;
+};
+
+export class GatewayJobTimeoutError<TJob extends GatewayJobLike> extends Error {
+  readonly name = "GatewayJobTimeoutError";
+  readonly attempts: number;
+  readonly elapsedMs: number;
+  readonly lastJob: TJob | null;
+
+  constructor(params: {
+    attempts: number;
+    elapsedMs: number;
+    lastJob: TJob | null;
+  }) {
+    super(
+      `gateway job: timed out after ${params.attempts} attempt${
+        params.attempts === 1 ? "" : "s"
+      }`,
+    );
+    this.attempts = params.attempts;
+    this.elapsedMs = params.elapsedMs;
+    this.lastJob = params.lastJob;
+  }
+}
+
+export class GatewayJobAbortError extends Error {
+  readonly name = "GatewayJobAbortError";
+  readonly reason: unknown;
+
+  constructor(reason?: unknown) {
+    super("gateway job: wait aborted");
+    this.reason = reason;
+  }
+}
+
+function normalizeStatus(status: GatewayJobStatus | null | undefined): string {
+  return typeof status === "string" ? status.trim().toLowerCase() : "";
+}
+
+function assertPositiveInteger(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+    throw new Error(`gateway job: ${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw new GatewayJobAbortError(signal.reason);
+  }
+}
+
+function defaultSleep(delayMs: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  let abort: (() => void) | null = null;
+  return new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(resolve, delayMs);
+    abort = (): void => {
+      clearTimeout(timeout);
+      reject(new GatewayJobAbortError(signal?.reason));
+    };
+
+    signal?.addEventListener("abort", abort, { once: true });
+  }).finally(() => {
+    if (abort) signal?.removeEventListener("abort", abort);
+  });
+}
+
+export function isGatewayJobSuccessfulStatus(
+  status: GatewayJobStatus | null | undefined,
+): boolean {
+  const normalized = normalizeStatus(status);
+  return GATEWAY_JOB_SUCCESS_STATUSES.includes(
+    normalized as (typeof GATEWAY_JOB_SUCCESS_STATUSES)[number],
+  );
+}
+
+export function isGatewayJobTerminalStatus(
+  status: GatewayJobStatus | null | undefined,
+): boolean {
+  const normalized = normalizeStatus(status);
+  return GATEWAY_JOB_TERMINAL_STATUSES.includes(
+    normalized as (typeof GATEWAY_JOB_TERMINAL_STATUSES)[number],
+  );
+}
+
+export async function waitForGatewayJob<TJob extends GatewayJobLike>(
+  options: GatewayJobWaitOptions<TJob>,
+): Promise<TJob> {
+  const intervalMs = assertPositiveInteger(options.intervalMs ?? 1_000, "intervalMs");
+  const timeoutMs = options.timeoutMs === undefined
+    ? 60_000
+    : assertPositiveInteger(options.timeoutMs, "timeoutMs");
+  const maxAttempts = options.maxAttempts === undefined
+    ? null
+    : assertPositiveInteger(options.maxAttempts, "maxAttempts");
+  const isTerminal = options.isTerminal ??
+    ((job: TJob): boolean => isGatewayJobTerminalStatus(job.status));
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  let attempts = 0;
+  let lastJob: TJob | null = null;
+
+  while (true) {
+    throwIfAborted(options.signal);
+    attempts += 1;
+    const job = await options.fetchJob();
+    lastJob = job;
+    const elapsedMs = Math.max(0, now() - startedAt);
+    options.onUpdate?.({ attempt: attempts, elapsedMs, job });
+
+    if (isTerminal(job)) {
+      return job;
+    }
+
+    if (maxAttempts !== null && attempts >= maxAttempts) {
+      throw new GatewayJobTimeoutError({ attempts, elapsedMs, lastJob });
+    }
+    if (elapsedMs >= timeoutMs) {
+      throw new GatewayJobTimeoutError({ attempts, elapsedMs, lastJob });
+    }
+
+    await sleep(Math.min(intervalMs, timeoutMs - elapsedMs), options.signal);
+  }
+}

package/src/core/gateway/portal/config-patch.ts

@@ -0,0 +1,136 @@
+import { PORTAL_CLIENT_ID_HEADER } from "../../http/types.js";
+import { GATEWAY_PORTAL_API_ENDPOINTS } from "../../../contracts/paths.js";
+
+/**
+ * Shared HTTP contract for portal dashboard config updates (POST).
+ * Any client (mobile, web, scripts) may call {@link postPortalConfigPatch} against
+ * the portal config surface once the gateway implements the route.
+ */
+
+export const PORTAL_CONFIG_PATCH_CONTRACT = "PORTAL_CONFIG_PATCH_V1" as const;
+export const PORTAL_CONFIG_PATCH_CONTRACT_VERSION = 1 as const;
+
+/** Optional header some gateways require for audit / routing. */
+export const PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER = PORTAL_CLIENT_ID_HEADER;
+
+export type PortalConfigPatchRequestBody = {
+  contract: typeof PORTAL_CONFIG_PATCH_CONTRACT;
+  v: typeof PORTAL_CONFIG_PATCH_CONTRACT_VERSION;
+  /** Gateway-defined scope (e.g. `readiness`, `snapshot.thresholds`). */
+  scope: string;
+  /** Nested object; build from flat UI keys with {@link unflattenPortalConfigPatchKeys}. */
+  patch: Record<string, unknown>;
+};
+
+export type PostPortalConfigPatchParams = {
+  httpBase: string;
+  /** Bearer secret without the `Bearer ` prefix. */
+  authToken: string;
+  /** URL segment only, e.g. `portal-a`. */
+  portalSlug: string;
+  scope: string;
+  patch: Record<string, unknown>;
+  /** Sent as {@link PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER} when non-empty. */
+  clientId?: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+};
+
+export class PortalConfigPatchError extends Error {
+  readonly status: number;
+  readonly responseBody: string | null;
+
+  constructor(status: number, message: string, responseBody: string | null) {
+    super(message);
+    this.name = "PortalConfigPatchError";
+    this.status = status;
+    this.responseBody = responseBody;
+  }
+}
+
+export function portalConfigPatchPath(portalSlug: string): string {
+  const slug = portalSlug.trim().replace(/^\/+/u, "").replace(/\/+$/u, "");
+  if (!slug || slug.includes("/")) {
+    throw new Error(`portalConfigPatchPath: invalid portal slug "${portalSlug}"`);
+  }
+  return GATEWAY_PORTAL_API_ENDPOINTS.config(slug);
+}
+
+/**
+ * Turns flat keys like `foo › bar` into `{ foo: { bar: value } }`.
+ */
+export function unflattenPortalConfigPatchKeys(
+  flat: Record<string, unknown>,
+  separator = " › ",
+): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  for (const [path, value] of Object.entries(flat)) {
+    const parts = path
+      .split(separator)
+      .map((p) => p.trim())
+      .filter((p) => p.length > 0);
+    if (!parts.length) continue;
+    let cur: Record<string, unknown> = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const p = parts[i]!;
+      const next = cur[p];
+      if (next && typeof next === "object" && !Array.isArray(next)) {
+        cur = next as Record<string, unknown>;
+      } else {
+        const nested: Record<string, unknown> = {};
+        cur[p] = nested;
+        cur = nested;
+      }
+    }
+    const leaf = parts[parts.length - 1]!;
+    cur[leaf] = value;
+  }
+  return root;
+}
+
+export async function postPortalConfigPatch(
+  params: PostPortalConfigPatchParams,
+): Promise<unknown> {
+  const base = params.httpBase.trim().replace(/\/+$/u, "");
+  const url = `${base}${portalConfigPatchPath(params.portalSlug)}`;
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${params.authToken}`,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+  const cid = params.clientId?.trim();
+  if (cid) {
+    headers[PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER] = cid;
+  }
+  const body: PortalConfigPatchRequestBody = {
+    contract: PORTAL_CONFIG_PATCH_CONTRACT,
+    v: PORTAL_CONFIG_PATCH_CONTRACT_VERSION,
+    scope: params.scope,
+    patch: params.patch,
+  };
+  const fetchFn = params.fetchImpl ?? fetch;
+  const res = await fetchFn(url, {
+    method: "POST",
+    signal: params.signal,
+    headers,
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const hint =
+      res.status === 404 || res.status === 501
+        ? " (gateway may not expose the portal.config surface yet)"
+        : "";
+    throw new PortalConfigPatchError(
+      res.status,
+      `Portal config PATCH failed: HTTP ${res.status}${hint}`,
+      text.length ? text : null,
+    );
+  }
+  if (!text) return { ok: true as const };
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return { ok: true as const, raw: text };
+  }
+}

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

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

package/src/core/gateway/providers/factory.ts

@@ -0,0 +1,77 @@
+import { GatewayAgentConfigApiClient } from "../agent/config.js";
+import { GatewayApiClient } from "../client/client.js";
+import { GatewayMediaApiClient } from "../resources/media.js";
+import { GatewaySseRunEventProvider } from "../run/sse-run-event-provider.js";
+import { GatewayWikiApiClient } from "../resources/wiki.js";
+import { GatewayWebSocketClient } from "../../ws/index.js";
+import type { HttpApiClientOptions } from "../../http/types.js";
+import { resolveGatewayProviderModule } from "./registry.js";
+import type {
+  CreateGatewaySseRunEventProviderOptions,
+  GatewayProviderKind,
+  ResolveGatewayProviderOptions,
+} from "./types.js";
+import type { GatewayWebSocketClientOptions } from "../../ws/index.js";
+
+export function resolveGatewayProviderKind(
+  options: ResolveGatewayProviderOptions = {},
+): GatewayProviderKind {
+  return resolveGatewayProviderModule(options)?.kind ?? "gateway";
+}
+
+export function createGatewayApiClient(
+  clientOptions: HttpApiClientOptions,
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewayApiClient {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createApiClient?.(clientOptions) ?? new GatewayApiClient(clientOptions);
+}
+
+export function createGatewayWebSocketClient(
+  wsUrl: string,
+  authToken: string | null,
+  clientOptions: GatewayWebSocketClientOptions = {},
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewayWebSocketClient {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createWebSocketClient?.(wsUrl, authToken, clientOptions) ??
+    new GatewayWebSocketClient(wsUrl, authToken, clientOptions);
+}
+
+export const createGatewayRpcClient = createGatewayWebSocketClient;
+
+export function createGatewaySseRunEventProvider(
+  options: CreateGatewaySseRunEventProviderOptions,
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewaySseRunEventProvider {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createSseRunEventProvider?.(options) ??
+    new GatewaySseRunEventProvider(options);
+}
+
+export function createGatewayMediaClient(
+  clientOptions: HttpApiClientOptions,
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewayMediaApiClient {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createMediaClient?.(clientOptions) ??
+    new GatewayMediaApiClient(clientOptions);
+}
+
+export function createGatewayWikiClient(
+  clientOptions: HttpApiClientOptions,
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewayWikiApiClient {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createWikiClient?.(clientOptions) ??
+    new GatewayWikiApiClient(clientOptions);
+}
+
+export function createGatewayAgentConfigClient(
+  clientOptions: HttpApiClientOptions,
+  providerOptions: ResolveGatewayProviderOptions = {},
+): GatewayAgentConfigApiClient {
+  const provider = resolveGatewayProviderModule(providerOptions);
+  return provider?.createAgentConfigClient?.(clientOptions) ??
+    new GatewayAgentConfigApiClient(clientOptions);
+}

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

@@ -0,0 +1,4 @@
+export * from "./factory.js";
+export * from "./normalize.js";
+export * from "./registry.js";
+export * from "./types.js";

package/src/core/gateway/providers/normalize.ts

@@ -0,0 +1,7 @@
+export function normalizeGatewayProviderToken(
+  value: string | null | undefined,
+): string | null {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return null;
+  return normalized === "generic" ? "gateway" : normalized;
+}

package/src/core/gateway/providers/registry.ts

@@ -0,0 +1,96 @@
+import { normalizeGatewayProviderToken } from "./normalize.js";
+import {
+  GATEWAY_PROVIDER_ENV_KEYS,
+  type CreateGatewayProviderRegistryOptions,
+  type GatewayProviderModule,
+  type GatewayProviderRegistry,
+  type ResolveGatewayProviderOptions,
+} from "./types.js";
+
+function providerModuleKeys(module: GatewayProviderModule): readonly string[] {
+  const keys = new Set<string>();
+  for (const key of [module.kind, ...(module.aliases ?? [])]) {
+    const normalized = normalizeGatewayProviderToken(key);
+    if (normalized) {
+      keys.add(normalized);
+    }
+  }
+  return [...keys];
+}
+
+export function createGatewayProviderRegistry(
+  options: CreateGatewayProviderRegistryOptions = {},
+): GatewayProviderRegistry {
+  const modules = [...(options.modules ?? [])];
+  const byKey = new Map<string, GatewayProviderModule>();
+  for (const module of modules) {
+    for (const key of providerModuleKeys(module)) {
+      if (byKey.has(key) && options.allowOverrides !== true) {
+        throw new Error(`Duplicate gateway provider key "${key}"`);
+      }
+      byKey.set(key, module);
+    }
+  }
+  return {
+    resolveProvider(provider) {
+      const normalized = normalizeGatewayProviderToken(provider);
+      return normalized ? (byKey.get(normalized) ?? null) : null;
+    },
+    listProviders() {
+      return [...modules];
+    },
+  };
+}
+
+function gatewayProviderRegistryFromOptions(
+  options: ResolveGatewayProviderOptions,
+): GatewayProviderRegistry {
+  const providerModules = options.providerModules ?? [];
+  if (options.registry && providerModules.length === 0) {
+    return options.registry;
+  }
+  if (options.registry) {
+    return createGatewayProviderRegistry({
+      modules: [...options.registry.listProviders(), ...providerModules],
+      allowOverrides: options.allowProviderOverrides,
+    });
+  }
+  return createGatewayProviderRegistry({
+    modules: providerModules,
+    allowOverrides: options.allowProviderOverrides,
+  });
+}
+
+export function requestedGatewayProvider(
+  options: ResolveGatewayProviderOptions,
+): string | null {
+  const explicit = options.provider?.trim();
+  if (explicit) return explicit;
+
+  for (const key of GATEWAY_PROVIDER_ENV_KEYS) {
+    const fromEnv = options.env?.[key]?.trim();
+    if (fromEnv) return fromEnv;
+  }
+
+  return options.defaultProvider?.trim() || null;
+}
+
+export function resolveGatewayProviderModule(
+  options: ResolveGatewayProviderOptions = {},
+): GatewayProviderModule | null {
+  const requested = requestedGatewayProvider(options);
+  if (!requested || isGenericGatewayProviderToken(requested)) {
+    return null;
+  }
+  const registry = gatewayProviderRegistryFromOptions(options);
+  const provider = registry.resolveProvider(requested);
+  if (!provider) {
+    throw new Error(`Unknown gateway provider "${requested}"`);
+  }
+  return provider;
+}
+
+function isGenericGatewayProviderToken(provider: string): boolean {
+  const normalized = normalizeGatewayProviderToken(provider);
+  return normalized === "gateway" || normalized === "generic" || normalized === "core";
+}

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

@@ -0,0 +1,73 @@
+import type { GatewayAgentConfigApiClient } from "../agent/config.js";
+import type { GatewayApiClient } from "../client/client.js";
+import type { GatewayMediaApiClient } from "../resources/media.js";
+import type {
+  GatewaySseRunEventProvider,
+  GatewaySseRunEventProviderOptions,
+} from "../run/sse-run-event-provider.js";
+import type { GatewayWikiApiClient } from "../resources/wiki.js";
+import type { HttpApiClientOptions } from "../../http/types.js";
+import type {
+  GatewayWebSocketClient,
+  GatewayWebSocketClientOptions,
+} from "../../ws/index.js";
+
+export type GatewayProviderKind =
+  | "hermes"
+  | "openclaw"
+  | (string & {});
+
+export const GATEWAY_PROVIDER_ENV_KEYS = [
+  "CAVI_GATEWAY_PROVIDER",
+  "GATEWAY_PROVIDER",
+] as const;
+
+export type GatewayProviderEnv = Record<string, string | undefined>;
+
+export type CreateGatewaySseRunEventProviderOptions =
+  GatewaySseRunEventProviderOptions & {
+    sessionKey?: string;
+  };
+
+export interface GatewayProviderFactories {
+  createApiClient?: (clientOptions: HttpApiClientOptions) => GatewayApiClient;
+  createWebSocketClient?: (
+    wsUrl: string,
+    authToken: string | null,
+    clientOptions: GatewayWebSocketClientOptions,
+  ) => GatewayWebSocketClient;
+  createSseRunEventProvider?: (
+    options: CreateGatewaySseRunEventProviderOptions,
+  ) => GatewaySseRunEventProvider;
+  createMediaClient?: (clientOptions: HttpApiClientOptions) => GatewayMediaApiClient;
+  createWikiClient?: (clientOptions: HttpApiClientOptions) => GatewayWikiApiClient;
+  createAgentConfigClient?: (
+    clientOptions: HttpApiClientOptions,
+  ) => GatewayAgentConfigApiClient;
+}
+
+export interface GatewayProviderModule extends GatewayProviderFactories {
+  kind: GatewayProviderKind;
+  aliases?: readonly string[];
+}
+
+export interface GatewayProviderRegistry {
+  resolveProvider(
+    provider: string | null | undefined,
+  ): GatewayProviderModule | null;
+  listProviders(): readonly GatewayProviderModule[];
+}
+
+export type CreateGatewayProviderRegistryOptions = {
+  modules?: readonly GatewayProviderModule[] | null;
+  allowOverrides?: boolean;
+};
+
+export type ResolveGatewayProviderOptions = {
+  provider?: GatewayProviderKind | string | null;
+  env?: GatewayProviderEnv;
+  defaultProvider?: GatewayProviderKind | string | null;
+  registry?: GatewayProviderRegistry | null;
+  providerModules?: readonly GatewayProviderModule[] | null;
+  allowProviderOverrides?: boolean;
+};

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

@@ -0,0 +1,2 @@
+export * from "./media.js";
+export * from "./wiki.js";