@elizaos/plugin-elizacloud 2.0.0-alpha.8 → 2.0.11-beta.7

package/src/cloud-voice-catalog.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Unit tests for `fetchCloudVoiceCatalog`.
+ *
+ * The catalog merges two upstream endpoints (`getApiElevenlabsVoices` for
+ * premade voices and `getApiElevenlabsVoicesUser` for user-cloned voices)
+ * and caches the result in memory. These tests cover:
+ *   - Normalization across the heterogeneous upstream shapes.
+ *   - Cache hits within the TTL (no second SDK call).
+ *   - Empty-array return when the runtime isn't cloud-connected (no SDK call
+ *     at all, since the gate runs before the HTTP fetch).
+ *   - Per-endpoint failure isolation (one endpoint erroring still surfaces
+ *     the other's voices).
+ *
+ * The SDK client is swapped via `setCloudVoiceClientFactoryForTesting` so
+ * the tests never hit the real network and never need a working
+ * `createElizaCloudClient`. After each test we restore the factory.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  type CloudVoiceClient,
+  fetchCloudVoiceCatalog,
+  resetCloudVoiceCatalogCacheForTesting,
+  setCloudVoiceClientFactoryForTesting,
+} from "./cloud-voice-catalog";
+
+interface RuntimeOptions {
+  connected?: boolean;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+function makeRuntime(opts: RuntimeOptions = {}): IAgentRuntime {
+  const apiKey = opts.apiKey ?? "test-cloud-key";
+  const baseUrl = opts.baseUrl ?? "https://cloud.test.local/api/v1";
+  const enabled = opts.connected === false ? "false" : "true";
+  const settings: Record<string, string | null> = {
+    ELIZAOS_CLOUD_API_KEY: opts.connected === false ? null : apiKey,
+    ELIZAOS_CLOUD_ENABLED: enabled,
+    ELIZAOS_CLOUD_BASE_URL: baseUrl,
+  };
+  return {
+    getSetting: (key: string) => settings[key] ?? undefined,
+  } as unknown as IAgentRuntime;
+}
+
+interface FakeRoutesCallLog {
+  premade: number;
+  user: number;
+}
+
+function makeFakeClient(payloads: {
+  premade?: unknown;
+  user?: unknown;
+  premadeError?: Error;
+  userError?: Error;
+}): { client: CloudVoiceClient; calls: FakeRoutesCallLog } {
+  const calls: FakeRoutesCallLog = { premade: 0, user: 0 };
+  const client: CloudVoiceClient = {
+    routes: {
+      async getApiElevenlabsVoices<T = unknown>(): Promise<T> {
+        calls.premade += 1;
+        if (payloads.premadeError) throw payloads.premadeError;
+        return payloads.premade as T;
+      },
+      async getApiElevenlabsVoicesUser<T = unknown>(): Promise<T> {
+        calls.user += 1;
+        if (payloads.userError) throw payloads.userError;
+        return payloads.user as T;
+      },
+    },
+  };
+  return { client, calls };
+}
+
+const PREMADE_VOICES_PAYLOAD = {
+  voices: [
+    {
+      voice_id: "EXAVITQu4vr4xnSDxMaL",
+      name: "Sarah",
+      preview_url: "https://cdn.example/sarah.mp3",
+      category: "premade",
+      labels: { gender: "female", language: "en" },
+    },
+    {
+      voice_id: "21m00Tcm4TlvDq8ikWAM",
+      name: "Rachel",
+      preview_url: "https://cdn.example/rachel.mp3",
+      category: "premade",
+      labels: { gender: "female" },
+    },
+    // Bare ID — should still normalize.
+    { id: "minimal-id-voice" },
+    // Malformed entries should be dropped.
+    {},
+    null,
+    "not-an-object",
+  ],
+};
+
+const USER_VOICES_PAYLOAD = [
+  {
+    voice_id: "user-clone-1",
+    name: "My Clone",
+    category: "cloned",
+    labels: { gender: "male", language_code: "es" },
+  },
+  // Duplicate of a premade ID — premade should be deduped out, but the user
+  // entry should win (it comes first in the merge).
+  {
+    voice_id: "EXAVITQu4vr4xnSDxMaL",
+    name: "Sarah (clone)",
+  },
+];
+
+describe("fetchCloudVoiceCatalog", () => {
+  beforeEach(() => {
+    resetCloudVoiceCatalogCacheForTesting();
+  });
+  afterEach(() => {
+    setCloudVoiceClientFactoryForTesting(null);
+    resetCloudVoiceCatalogCacheForTesting();
+  });
+
+  it("returns an empty array when the runtime is not cloud-connected (no SDK calls)", async () => {
+    const { client, calls } = makeFakeClient({
+      premade: PREMADE_VOICES_PAYLOAD,
+      user: USER_VOICES_PAYLOAD,
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const voices = await fetchCloudVoiceCatalog(makeRuntime({ connected: false }));
+    expect(voices).toEqual([]);
+    // The gate runs before the HTTP fetch, so neither endpoint is called.
+    expect(calls.premade).toBe(0);
+    expect(calls.user).toBe(0);
+  });
+
+  it("normalizes premade + user voices and dedupes by id (user wins)", async () => {
+    const { client, calls } = makeFakeClient({
+      premade: PREMADE_VOICES_PAYLOAD,
+      user: USER_VOICES_PAYLOAD,
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const voices = await fetchCloudVoiceCatalog(makeRuntime());
+
+    expect(calls.premade).toBe(1);
+    expect(calls.user).toBe(1);
+
+    // Expected order: user voices first (clone + dupe), then unique premade.
+    const ids = voices.map((v) => v.id);
+    expect(ids).toEqual([
+      "user-clone-1",
+      "EXAVITQu4vr4xnSDxMaL", // dupe — user copy wins
+      "21m00Tcm4TlvDq8ikWAM",
+      "minimal-id-voice",
+    ]);
+
+    // User clone normalization.
+    const userClone = voices.find((v) => v.id === "user-clone-1");
+    expect(userClone).toMatchObject({
+      id: "user-clone-1",
+      name: "My Clone",
+      gender: "male",
+      category: "cloned",
+      language: "es",
+    });
+
+    // Premade normalization.
+    const rachel = voices.find((v) => v.id === "21m00Tcm4TlvDq8ikWAM");
+    expect(rachel).toMatchObject({
+      id: "21m00Tcm4TlvDq8ikWAM",
+      name: "Rachel",
+      preview: "https://cdn.example/rachel.mp3",
+      gender: "female",
+      category: "premade",
+    });
+
+    // Dedupe: the user copy of Sarah (cloned) wins over the premade entry.
+    const sarah = voices.find((v) => v.id === "EXAVITQu4vr4xnSDxMaL");
+    expect(sarah?.name).toBe("Sarah (clone)");
+
+    // Bare-id entry has a fallback display name.
+    const minimal = voices.find((v) => v.id === "minimal-id-voice");
+    expect(minimal?.name).toBe("minimal-id-voice");
+  });
+
+  it("caches results within the 1h TTL — second call does not refetch", async () => {
+    const { client, calls } = makeFakeClient({
+      premade: PREMADE_VOICES_PAYLOAD,
+      user: USER_VOICES_PAYLOAD,
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const runtime = makeRuntime();
+    const a = await fetchCloudVoiceCatalog(runtime);
+    const b = await fetchCloudVoiceCatalog(runtime);
+    expect(a).toBe(b);
+    expect(calls.premade).toBe(1);
+    expect(calls.user).toBe(1);
+  });
+
+  it("uses different cache entries per runtime base URL + API key", async () => {
+    const { client, calls } = makeFakeClient({
+      premade: PREMADE_VOICES_PAYLOAD,
+      user: USER_VOICES_PAYLOAD,
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    await fetchCloudVoiceCatalog(makeRuntime({ apiKey: "key-1" }));
+    await fetchCloudVoiceCatalog(makeRuntime({ apiKey: "key-2" }));
+    // Each runtime gets its own cache slot — both fetched once.
+    expect(calls.premade).toBe(2);
+    expect(calls.user).toBe(2);
+  });
+
+  it("isolates per-endpoint failures — one endpoint erroring still returns the other's voices", async () => {
+    const { client } = makeFakeClient({
+      premade: PREMADE_VOICES_PAYLOAD,
+      userError: new Error("user endpoint down"),
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const voices = await fetchCloudVoiceCatalog(makeRuntime());
+    // Only premade voices come back; the user endpoint failure is swallowed.
+    expect(voices.map((v) => v.id).sort()).toEqual(
+      ["21m00Tcm4TlvDq8ikWAM", "EXAVITQu4vr4xnSDxMaL", "minimal-id-voice"].sort(),
+    );
+  });
+
+  it("returns empty array when both endpoints fail", async () => {
+    const { client } = makeFakeClient({
+      premadeError: new Error("premade endpoint down"),
+      userError: new Error("user endpoint down"),
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const voices = await fetchCloudVoiceCatalog(makeRuntime());
+    expect(voices).toEqual([]);
+  });
+
+  it("accepts bare-array payloads (some upstream variants return arrays)", async () => {
+    const { client } = makeFakeClient({
+      premade: [{ voice_id: "premade-1", name: "Premade One" }],
+      user: { items: [{ voice_id: "user-1", name: "User One" }] },
+    });
+    setCloudVoiceClientFactoryForTesting(() => client);
+
+    const voices = await fetchCloudVoiceCatalog(makeRuntime());
+    expect(voices.map((v) => v.id).sort()).toEqual(["premade-1", "user-1"]);
+  });
+});

package/src/cloud-voice-catalog.ts

@@ -0,0 +1,246 @@
+/**
+ * Cloud-routed ElevenLabs voice catalog.
+ *
+ * The Eliza Cloud SDK exposes two voice-listing endpoints:
+ *   - `GET /api/elevenlabs/voices` — ElevenLabs **premade** voices (shared).
+ *   - `GET /api/elevenlabs/voices/user` — voices cloned / saved by the
+ *     authenticated user.
+ *
+ * We expose the union of both to consumers so the dashboard, the agent, and
+ * any other client see the full set of voices the user can actually use.
+ *
+ * Results are cached in-memory for {@link CACHE_TTL_MS} (1 hour). The cache
+ * is keyed by the runtime's cloud base URL + API key so multi-tenant or
+ * test-isolated runtimes don't share entries. On any fetch error we return
+ * a normalized empty list rather than throwing — callers can decide whether
+ * to surface a UI hint.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { isCloudConnected, logger, toRuntimeSettings } from "@elizaos/core";
+import { getApiKey, getBaseURL } from "./utils/config";
+import { createElizaCloudClient } from "./utils/sdk-client";
+
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface CloudVoiceCatalogEntry {
+  id: string;
+  name: string;
+  gender?: string;
+  preview?: string;
+  category?: string;
+  language?: string;
+}
+
+/**
+ * Narrow interface the catalog actually uses. Lets tests substitute a
+ * fake without rebuilding the full SDK surface.
+ */
+export interface CloudVoiceClient {
+  routes: {
+    getApiElevenlabsVoices<T = unknown>(options?: {
+      query?: Record<string, unknown>;
+    }): Promise<T>;
+    getApiElevenlabsVoicesUser<T = unknown>(options?: {
+      query?: Record<string, unknown>;
+    }): Promise<T>;
+  };
+}
+
+type ClientFactory = (runtime: IAgentRuntime) => CloudVoiceClient;
+
+let clientFactory: ClientFactory = (runtime) =>
+  createElizaCloudClient(runtime) as unknown as CloudVoiceClient;
+
+/**
+ * Test seam: substitute the SDK client factory. Pass `null` to reset to
+ * the real `createElizaCloudClient`. Production code should never call
+ * this.
+ */
+export function setCloudVoiceClientFactoryForTesting(
+  factory: ClientFactory | null,
+): void {
+  if (factory === null) {
+    clientFactory = (runtime) =>
+      createElizaCloudClient(runtime) as unknown as CloudVoiceClient;
+  } else {
+    clientFactory = factory;
+  }
+}
+
+interface CacheEntry {
+  fetchedAt: number;
+  voices: CloudVoiceCatalogEntry[];
+}
+
+/** Module-level cache. Keyed by `${baseUrl}|${apiKey}`. */
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Test seam: drop the in-memory cache. Production code should never call
+ * this; the TTL handles eviction by itself.
+ */
+export function resetCloudVoiceCatalogCacheForTesting(): void {
+  cache.clear();
+}
+
+function cacheKeyFor(runtime: IAgentRuntime): string {
+  const baseUrl = getBaseURL(runtime) || "";
+  const apiKey = getApiKey(runtime) || "";
+  return `${baseUrl}|${apiKey}`;
+}
+
+function pickString(
+  record: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const v = record[key];
+  return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
+function pickStringFromAny(
+  record: Record<string, unknown>,
+  ...keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const v = pickString(record, key);
+    if (v) return v;
+  }
+  return undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+/**
+ * Best-effort normalizer for the heterogeneous shapes the upstream returns.
+ *
+ * ElevenLabs's premade voices include `labels: { gender, accent, ... }`,
+ * `preview_url`, `category`. User-cloned voices look very similar but may
+ * omit some fields. We accept any shape that has at least a `voice_id`
+ * (or `id`) and produce a uniform record.
+ */
+function normalizeVoiceEntry(raw: unknown): CloudVoiceCatalogEntry | null {
+  const record = asRecord(raw);
+  if (!record) return null;
+  const id = pickStringFromAny(record, "voice_id", "voiceId", "id");
+  if (!id) return null;
+
+  const name =
+    pickStringFromAny(record, "name", "display_name", "displayName") ?? id;
+  const preview = pickStringFromAny(
+    record,
+    "preview_url",
+    "previewUrl",
+    "preview",
+  );
+  const category = pickStringFromAny(record, "category");
+
+  // `labels` is the canonical ElevenLabs metadata block.
+  const labels = asRecord(record.labels);
+  const gender =
+    pickStringFromAny(record, "gender") ??
+    (labels ? pickStringFromAny(labels, "gender") : undefined);
+  const language =
+    pickStringFromAny(record, "language", "language_code", "languageCode") ??
+    (labels
+      ? pickStringFromAny(labels, "language", "language_code", "languageCode")
+      : undefined);
+
+  return {
+    id,
+    name,
+    ...(gender ? { gender } : {}),
+    ...(preview ? { preview } : {}),
+    ...(category ? { category } : {}),
+    ...(language ? { language } : {}),
+  };
+}
+
+/**
+ * Some endpoints return `{ voices: [...] }`, others return a bare array.
+ * Accept both.
+ */
+function extractVoiceArray(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) return payload;
+  const record = asRecord(payload);
+  if (!record) return [];
+  for (const key of ["voices", "data", "items", "results"]) {
+    const v = record[key];
+    if (Array.isArray(v)) return v;
+  }
+  return [];
+}
+
+function dedupeById(entries: CloudVoiceCatalogEntry[]): CloudVoiceCatalogEntry[] {
+  const seen = new Set<string>();
+  const out: CloudVoiceCatalogEntry[] = [];
+  for (const entry of entries) {
+    if (seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    out.push(entry);
+  }
+  return out;
+}
+
+async function fetchEndpointVoices(
+  runtime: IAgentRuntime,
+  endpoint: "premade" | "user",
+): Promise<CloudVoiceCatalogEntry[]> {
+  try {
+    const client = clientFactory(runtime);
+    const payload =
+      endpoint === "premade"
+        ? await client.routes.getApiElevenlabsVoices<unknown>()
+        : await client.routes.getApiElevenlabsVoicesUser<unknown>();
+    const raw = extractVoiceArray(payload);
+    const normalized: CloudVoiceCatalogEntry[] = [];
+    for (const entry of raw) {
+      const v = normalizeVoiceEntry(entry);
+      if (v) normalized.push(v);
+    }
+    return normalized;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.debug(
+      `[ELIZAOS_CLOUD] voice catalog ${endpoint} fetch failed: ${message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Fetch the user-visible voice catalog from Eliza Cloud (premade + cloned).
+ *
+ * Returns an empty array when:
+ *   - Eliza Cloud isn't connected (no API key / not enabled).
+ *   - Both upstream endpoints fail (network, auth, etc.).
+ *
+ * Results are cached for {@link CACHE_TTL_MS} per runtime. Subsequent calls
+ * within that window are served from memory.
+ */
+export async function fetchCloudVoiceCatalog(
+  runtime: IAgentRuntime,
+): Promise<CloudVoiceCatalogEntry[]> {
+  if (!isCloudConnected(toRuntimeSettings(runtime))) {
+    return [];
+  }
+  const key = cacheKeyFor(runtime);
+  const now = Date.now();
+  const cached = cache.get(key);
+  if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.voices;
+  }
+
+  const [premade, user] = await Promise.all([
+    fetchEndpointVoices(runtime, "premade"),
+    fetchEndpointVoices(runtime, "user"),
+  ]);
+
+  // User voices first so cloned voices appear before the shared premade
+  // list — most users care about their own clones.
+  const merged = dedupeById([...user, ...premade]);
+  cache.set(key, { fetchedAt: now, voices: merged });
+  return merged;
+}

package/src/index.browser.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from "@elizaos/core";
+
+export const elizaOSCloudPlugin: Plugin = {
+  name: "elizaOSCloud",
+  description:
+    "ElizaOS Cloud browser facade. Node-only routes and services are exported from the node entry.",
+};
+
+// Browser-side unavailable facades for the named exports that ship from the Node
+// entry. The renderer needs the names to statically resolve so the bundler
+// doesn't fail with MISSING_EXPORT. These functions are never executed in
+// the browser since the consumers are server-side routes; in eliza local-mode
+// the bundled `app-core/dist/api/server.js` imports them at module-load time.
+const unavailableBrowserExport = (): undefined => undefined;
+
+export function getCloudSecret(
+  _key?: "ELIZAOS_CLOUD_API_KEY" | "ELIZAOS_CLOUD_ENABLED",
+): string | undefined {
+  return undefined;
+}
+
+export function clearCloudSecrets(): void {}
+
+export const ensureCloudTtsApiKeyAlias = unavailableBrowserExport;
+export const handleCloudTtsPreviewRoute = unavailableBrowserExport;
+export const mirrorCompatHeaders = unavailableBrowserExport;
+export const normalizeCloudSiteUrl = unavailableBrowserExport;
+export const scrubCloudSecretsFromEnv = unavailableBrowserExport;
+export const __resetCloudBaseUrlCache = unavailableBrowserExport;
+export const resolveCloudTtsBaseUrl = unavailableBrowserExport;
+export const resolveElevenLabsApiKeyForCloudMode = unavailableBrowserExport;
+// `resolveCloudApiBaseUrl` is referenced statically by plugin-wallet's
+// browser bundle (the cloud-routing fallback path). The renderer doesn't
+// run the Node-side resolver; the consumer just needs the name to bind
+// so Rolldown's MISSING_EXPORT check passes.
+export const resolveCloudApiBaseUrl = (): undefined => undefined;
+
+export * from "./types";
+export default elizaOSCloudPlugin;

package/src/index.node.ts

@@ -0,0 +1,69 @@
+import pluginDefault from "./index.js";
+
+export * from "./index.js";
+export default pluginDefault;
+
+// Node-only route handlers (depend on node:os and other node built-ins).
+export { handleCloudBillingRoute } from "./routes/cloud-billing-routes";
+export { handleCloudCompatRoute } from "./routes/cloud-compat-routes";
+export { handleCloudRelayRoute } from "./routes/cloud-relay-routes";
+export {
+  type CloudRouteState,
+  handleCloudRoute,
+} from "./routes/cloud-routes-autonomous";
+export {
+  handleCloudCodingContainerRoute,
+  type CloudCodingContainerRouteState,
+} from "./routes/cloud-coding-container-routes";
+export type { CloudConfigLike } from "./routes/cloud-routes-autonomous";
+export { handleCloudStatusRoutes } from "./routes/cloud-status-routes";
+export { runCloudSetup, type CloudSetupResult } from "./cloud-setup";
+export { ClackObserver } from "./cloud/clack-observer";
+export { NullCloudSetupObserver } from "./cloud/null-observer";
+export type {
+  AvailabilityResult,
+  CloudSetupObserver,
+  ConfirmPrompt,
+  ProvisionSuccessInfo,
+  SelectChoiceOption,
+  SelectChoicePrompt,
+} from "./cloud/setup-observer";
+export { CloudManager, type CloudManagerCallbacks } from "./cloud/cloud-manager";
+export {
+  getOrCreateClientAddressKey,
+  persistCloudWalletCache,
+  provisionCloudWalletsBestEffort,
+} from "./cloud/cloud-wallet";
+export {
+  normalizeCloudSecret,
+  resolveCloudApiKey,
+} from "./cloud/cloud-api-key";
+export {
+  isCloudAuthApiKeyService,
+  normalizeCloudApiKey,
+  type CloudAuthApiKeyService,
+} from "./cloud/auth-service-types";
+export {
+  clearCloudSecrets,
+  getCloudSecret,
+  scrubCloudSecretsFromEnv,
+} from "./lib/cloud-secrets";
+export {
+  __resetCloudBaseUrlCache,
+  ensureCloudTtsApiKeyAlias,
+  handleCloudTtsPreviewRoute,
+  mirrorCompatHeaders,
+  resolveCloudTtsBaseUrl,
+  resolveElevenLabsApiKeyForCloudMode,
+} from "./lib/server-cloud-tts";
+export {
+  fetchCloudVoiceCatalog,
+  resetCloudVoiceCatalogCacheForTesting,
+  setCloudVoiceClientFactoryForTesting,
+  type CloudVoiceCatalogEntry,
+  type CloudVoiceClient,
+} from "./cloud-voice-catalog";
+export {
+  CloudTtsUnavailableError,
+  type CloudTextToSpeechParams,
+} from "./models/speech";