@cavi-ai/api-client 0.1.0

package/src/providers/hermes/env-config.ts

@@ -0,0 +1,58 @@
+import {
+  resolveHttpSurfaceConfigFromEnv,
+  type HttpApiEnvSource,
+  type HttpApiSurfaceConfig,
+} from "../../core/env/config.js";
+
+export const HERMES_HTTP_API_ENV_KEYS = {
+  baseUrl: "HERMES_API_BASE_URL",
+  authToken: "HERMES_API_AUTH_TOKEN",
+  clientId: "HERMES_API_CLIENT_ID",
+} as const;
+
+export const HERMES_HTTP_API_ENV_ALIASES = {
+  baseUrl: [
+    "EXPO_PUBLIC_HERMES_API_BASE_URL",
+    "VITE_HERMES_API_BASE_URL",
+    "GATEWAY_API_BASE_URL",
+    "EXPO_PUBLIC_GATEWAY_API_BASE_URL",
+    "VITE_GATEWAY_API_BASE_URL",
+  ],
+  authToken: [
+    "EXPO_PUBLIC_HERMES_API_AUTH_TOKEN",
+    "VITE_HERMES_API_AUTH_TOKEN",
+    "GATEWAY_API_AUTH_TOKEN",
+    "EXPO_PUBLIC_GATEWAY_TOKEN",
+    "EXPO_PUBLIC_GATEWAY_API_AUTH_TOKEN",
+    "VITE_GATEWAY_API_AUTH_TOKEN",
+  ],
+  clientId: [
+    "EXPO_PUBLIC_HERMES_API_CLIENT_ID",
+    "VITE_HERMES_API_CLIENT_ID",
+    "GATEWAY_API_CLIENT_ID",
+    "EXPO_PUBLIC_GATEWAY_CLIENT_ID",
+    "EXPO_PUBLIC_GATEWAY_API_CLIENT_ID",
+    "VITE_GATEWAY_API_CLIENT_ID",
+  ],
+} as const;
+
+export type ResolveHermesHttpApiConfigOptions = {
+  defaults?: Partial<HttpApiSurfaceConfig>;
+  trimValues?: boolean;
+  includeAliases?: boolean;
+};
+
+export function resolveHermesHttpApiConfigFromEnv(
+  env: HttpApiEnvSource,
+  options: ResolveHermesHttpApiConfigOptions = {},
+): HttpApiSurfaceConfig {
+  return resolveHttpSurfaceConfigFromEnv(
+    env,
+    {
+      keys: HERMES_HTTP_API_ENV_KEYS,
+      aliases: HERMES_HTTP_API_ENV_ALIASES,
+      fallback: { baseUrl: "http://127.0.0.1:8787", clientId: "cavi-api-client" },
+    },
+    options,
+  );
+}

package/src/providers/hermes/index.ts

@@ -0,0 +1,11 @@
+export * from "./client.js";
+export * from "./agent-config.js";
+export * from "./chat-run.js";
+export * from "./env-config.js";
+export * from "./media.js";
+export * from "./provider-module.js";
+export * from "./sse-run-event-provider.js";
+export * from "./team-registry.js";
+export * from "./team-registry-config.js";
+export * from "./websocket.js";
+export * from "./wiki.js";

package/src/providers/hermes/media.ts

@@ -0,0 +1,12 @@
+import { GatewayMediaApiClient } from "../../core/gateway/resources/media.js";
+import { HERMES_MEDIA_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export class HermesMediaApiClient extends GatewayMediaApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: HERMES_MEDIA_API_ENDPOINTS,
+      surface: "hermes-media-api",
+    });
+  }
+}

package/src/providers/hermes/provider-module.ts

@@ -0,0 +1,26 @@
+import type { GatewayProviderModule } from "../../core/gateway/providers/index.js";
+import { HermesAgentConfigApiClient } from "./agent-config.js";
+import { HermesApiClient } from "./client.js";
+import { HermesMediaApiClient } from "./media.js";
+import { HermesSseRunEventProvider } from "./sse-run-event-provider.js";
+import { HermesWebSocketClient } from "./websocket.js";
+import { HermesWikiApiClient } from "./wiki.js";
+
+export const HERMES_PROVIDER_MODULE: GatewayProviderModule = {
+  kind: "hermes",
+  aliases: ["hermes-api-server"],
+  createApiClient: (clientOptions) => new HermesApiClient(clientOptions),
+  createWebSocketClient: (wsUrl, authToken, clientOptions) =>
+    new HermesWebSocketClient(wsUrl, authToken, clientOptions),
+  createSseRunEventProvider: (options) => {
+    const sessionKey = options.sessionKey?.trim();
+    if (!sessionKey) {
+      throw new Error("createGatewaySseRunEventProvider: Hermes requires sessionKey");
+    }
+    return new HermesSseRunEventProvider({ ...options, sessionKey });
+  },
+  createMediaClient: (clientOptions) => new HermesMediaApiClient(clientOptions),
+  createWikiClient: (clientOptions) => new HermesWikiApiClient(clientOptions),
+  createAgentConfigClient: (clientOptions) =>
+    new HermesAgentConfigApiClient(clientOptions),
+};

package/src/providers/hermes/sse-run-event-provider.ts

@@ -0,0 +1,47 @@
+import { HERMES_API_ENDPOINTS } from "../../contracts/paths.js";
+import {
+  GatewaySseRunEventProvider as CoreGatewaySseRunEventProvider,
+  type GatewaySseRunEventHeaderResolver,
+  type GatewaySseRunEventProviderOptions,
+} from "../../core/gateway/run/sse-run-event-provider.js";
+
+export type HermesSseRunEventProviderOptions = GatewaySseRunEventProviderOptions & {
+  /** Required for `X-Hermes-Session-Key` on both the SSE request and the poll fallback. */
+  sessionKey: string;
+};
+export type {
+  GatewaySseRunEventHeaderResolver,
+  GatewaySseRunEventProviderOptions,
+};
+
+/**
+ * Subscribes to the Hermes run-event SSE stream and emits
+ * canonical run-stream events. Falls back to status polling
+ * when SSE is unsupported by the server.
+ *
+ * The caller is responsible for starting the run and
+ * supplying the resulting `run_id` to {@link subscribe}.
+ *
+ * Tool events are emitted when the underlying Hermes payload contains
+ * tool-shaped fields (`tool_name`, `function_name`, etc.). When the Hermes API
+ * does not natively emit tool events, compose this provider with
+ * {@link RunPreviewPollProvider} via `createRunStreamWithToolFallback`.
+ */
+export class HermesSseRunEventProvider extends CoreGatewaySseRunEventProvider {
+  constructor(options: HermesSseRunEventProviderOptions) {
+    const sessionKey = options.sessionKey.trim();
+    if (!sessionKey) {
+      throw new Error("HermesSseRunEventProvider requires sessionKey");
+    }
+    super({
+      ...options,
+      endpoints: options.endpoints ?? HERMES_API_ENDPOINTS,
+      resolveHeaders: (params) => ({
+        ...(options.resolveHeaders?.(params) ?? {}),
+        "X-Hermes-Session-Key": sessionKey,
+      }),
+    });
+  }
+}
+
+export const GatewaySseRunEventProvider = CoreGatewaySseRunEventProvider;

package/src/providers/hermes/team-registry-config.ts

@@ -0,0 +1,2 @@
+export { TEAM_REGISTRY_CONFIG } from "../../extensions/cavi/registry/team-registry-config.js";
+export type { TeamRegistryConfig } from "../../extensions/cavi/registry/team-registry.js";

package/src/providers/hermes/team-registry.ts

@@ -0,0 +1,12 @@
+import {
+  createTeamRegistry,
+  type TeamRegistry,
+  type TeamRegistryConfig,
+} from "../../extensions/cavi/registry/team-registry.js";
+import { TEAM_REGISTRY_CONFIG } from "./team-registry-config.js";
+
+export function createHermesTeamRegistry(
+  config: TeamRegistryConfig = TEAM_REGISTRY_CONFIG,
+): TeamRegistry {
+  return createTeamRegistry(config, { provider: "hermes" });
+}

package/src/providers/hermes/websocket.ts

@@ -0,0 +1,16 @@
+import {
+  GatewayWebSocketClient,
+  type GatewayWebSocketClientOptions,
+} from "../../core/ws/index.js";
+
+export type HermesWebSocketClientOptions = GatewayWebSocketClientOptions;
+
+export class HermesWebSocketClient extends GatewayWebSocketClient {
+  constructor(
+    wsUrl: string,
+    authToken: string | null,
+    options: HermesWebSocketClientOptions = {},
+  ) {
+    super(wsUrl, authToken, options);
+  }
+}

package/src/providers/hermes/wiki.ts

@@ -0,0 +1,12 @@
+import { GatewayWikiApiClient } from "../../core/gateway/resources/wiki.js";
+import { HERMES_WIKI_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export class HermesWikiApiClient extends GatewayWikiApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: HERMES_WIKI_API_ENDPOINTS,
+      surface: "hermes-wiki-api",
+    });
+  }
+}

package/src/providers/openclaw/agent-config.ts

@@ -0,0 +1,12 @@
+import { GatewayAgentConfigApiClient } from "../../core/gateway/agent/config.js";
+import { OPENCLAW_AGENT_CONFIG_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export class OpenClawAgentConfigApiClient extends GatewayAgentConfigApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: OPENCLAW_AGENT_CONFIG_API_ENDPOINTS,
+      surface: "openclaw-agent-config-api",
+    });
+  }
+}

package/src/providers/openclaw/client.ts

@@ -0,0 +1,21 @@
+import {
+  GatewayApiClient,
+  type GatewayCapabilities,
+  type GatewayRunStatus,
+} from "../../core/gateway/client/client.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export type OpenClawCapabilities = GatewayCapabilities & {
+  object?: "openclaw.api_server.capabilities" | string;
+  platform?: "openclaw" | string;
+};
+
+export type OpenClawRunStatus = GatewayRunStatus & {
+  object?: "openclaw.run" | string;
+};
+
+export class OpenClawApiClient extends GatewayApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, "openclaw-api");
+  }
+}

package/src/providers/openclaw/index.ts

@@ -0,0 +1,9 @@
+export * from "./client.js";
+export * from "./agent-config.js";
+export * from "./media.js";
+export * from "./provider-module.js";
+export * from "./sse-run-event-provider.js";
+export * from "./team-registry.js";
+export * from "./team-registry-config.js";
+export * from "./websocket.js";
+export * from "./wiki.js";

package/src/providers/openclaw/media.ts

@@ -0,0 +1,12 @@
+import { GatewayMediaApiClient } from "../../core/gateway/resources/media.js";
+import { OPENCLAW_MEDIA_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export class OpenClawMediaApiClient extends GatewayMediaApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: OPENCLAW_MEDIA_API_ENDPOINTS,
+      surface: "openclaw-media-api",
+    });
+  }
+}

package/src/providers/openclaw/provider-module.ts

@@ -0,0 +1,20 @@
+import type { GatewayProviderModule } from "../../core/gateway/providers/index.js";
+import { OpenClawAgentConfigApiClient } from "./agent-config.js";
+import { OpenClawApiClient } from "./client.js";
+import { OpenClawMediaApiClient } from "./media.js";
+import { OpenClawSseRunEventProvider } from "./sse-run-event-provider.js";
+import { OpenClawWebSocketClient } from "./websocket.js";
+import { OpenClawWikiApiClient } from "./wiki.js";
+
+export const OPENCLAW_PROVIDER_MODULE: GatewayProviderModule = {
+  kind: "openclaw",
+  aliases: ["open-claw"],
+  createApiClient: (clientOptions) => new OpenClawApiClient(clientOptions),
+  createWebSocketClient: (wsUrl, authToken, clientOptions) =>
+    new OpenClawWebSocketClient(wsUrl, authToken, clientOptions),
+  createSseRunEventProvider: (options) => new OpenClawSseRunEventProvider(options),
+  createMediaClient: (clientOptions) => new OpenClawMediaApiClient(clientOptions),
+  createWikiClient: (clientOptions) => new OpenClawWikiApiClient(clientOptions),
+  createAgentConfigClient: (clientOptions) =>
+    new OpenClawAgentConfigApiClient(clientOptions),
+};

package/src/providers/openclaw/sse-run-event-provider.ts

@@ -0,0 +1,16 @@
+import {
+  GatewaySseRunEventProvider,
+  type GatewaySseRunEventProviderOptions,
+} from "../../core/gateway/run/sse-run-event-provider.js";
+import { GATEWAY_API_ENDPOINTS } from "../../contracts/paths.js";
+
+export type OpenClawSseRunEventProviderOptions = GatewaySseRunEventProviderOptions;
+
+export class OpenClawSseRunEventProvider extends GatewaySseRunEventProvider {
+  constructor(options: OpenClawSseRunEventProviderOptions) {
+    super({
+      ...options,
+      endpoints: options.endpoints ?? GATEWAY_API_ENDPOINTS,
+    });
+  }
+}

package/src/providers/openclaw/team-registry-config.ts

@@ -0,0 +1,2 @@
+export { TEAM_REGISTRY_CONFIG } from "../../extensions/cavi/registry/team-registry-config.js";
+export type { TeamRegistryConfig } from "../../extensions/cavi/registry/team-registry.js";

package/src/providers/openclaw/team-registry.ts

@@ -0,0 +1,12 @@
+import {
+  createTeamRegistry,
+  type TeamRegistry,
+  type TeamRegistryConfig,
+} from "../../extensions/cavi/registry/team-registry.js";
+import { TEAM_REGISTRY_CONFIG } from "./team-registry-config.js";
+
+export function createOpenClawTeamRegistry(
+  config: TeamRegistryConfig = TEAM_REGISTRY_CONFIG,
+): TeamRegistry {
+  return createTeamRegistry(config, { provider: "openclaw" });
+}

package/src/providers/openclaw/websocket.ts

@@ -0,0 +1,56 @@
+import {
+  GatewayWebSocketClient,
+  type GatewayWebSocketClientOptions,
+} from "../../core/ws/index.js";
+import type {
+  GatewayPreauthHandshakeEnv,
+  GatewayPreauthHandshakeEnvKeys,
+} from "../../core/gateway/rpc/index.js";
+
+export type OpenClawWebSocketClientOptions = GatewayWebSocketClientOptions;
+
+const OPENCLAW_PREAUTH_HANDSHAKE_ENV_KEYS: GatewayPreauthHandshakeEnvKeys = {
+  timeoutMs: "OPENCLAW_HANDSHAKE_TIMEOUT_MS",
+  testTimeoutMs: "OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS",
+  testFlag: "VITEST",
+};
+
+declare const process:
+  | {
+      env: Record<string, string | undefined>;
+    }
+  | undefined;
+
+function readOpenClawHandshakeEnv(): GatewayPreauthHandshakeEnv | undefined {
+  if (typeof process === "undefined") {
+    return undefined;
+  }
+  return {
+    OPENCLAW_HANDSHAKE_TIMEOUT_MS: process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS,
+    OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS:
+      process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS,
+    VITEST: process.env.VITEST,
+  };
+}
+
+function withOpenClawDefaults(
+  options: OpenClawWebSocketClientOptions,
+): OpenClawWebSocketClientOptions {
+  return {
+    ...options,
+    preauthHandshakeEnv:
+      options.preauthHandshakeEnv ?? readOpenClawHandshakeEnv(),
+    preauthHandshakeEnvKeys:
+      options.preauthHandshakeEnvKeys ?? OPENCLAW_PREAUTH_HANDSHAKE_ENV_KEYS,
+  };
+}
+
+export class OpenClawWebSocketClient extends GatewayWebSocketClient {
+  constructor(
+    wsUrl: string,
+    authToken: string | null,
+    options: OpenClawWebSocketClientOptions = {},
+  ) {
+    super(wsUrl, authToken, withOpenClawDefaults(options));
+  }
+}

package/src/providers/openclaw/wiki.ts

@@ -0,0 +1,12 @@
+import { GatewayWikiApiClient } from "../../core/gateway/resources/wiki.js";
+import { OPENCLAW_WIKI_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export class OpenClawWikiApiClient extends GatewayWikiApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: OPENCLAW_WIKI_API_ENDPOINTS,
+      surface: "openclaw-wiki-api",
+    });
+  }
+}