Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

11.1 KB
Raw Blame
// Unit tests for the shared ElevenLabs client (api/_lib/elevenlabs.js).
// fetch and the @elevenlabs/elevenlabs-js SDK are mocked so these run with no
// network and no API key — they pin the contract the TTS proxy + agent-voice
// endpoints depend on (cache behavior, error→status mapping, best-effort delete).

import { vi, describe, it, expect, beforeEach, afterAll } from 'vitest';

// SDK mock — hoisted so vi.mock's factory can reference it.
const { ivcCreate } = vi.hoisted(() => ({ ivcCreate: vi.fn() }));
vi.mock('@elevenlabs/elevenlabs-js', () => ({
	// Plain function (constructable) that returns the client shape; an arrow or
	// vi.fn impl can't be used with `new`.
	ElevenLabsClient: function ElevenLabsClient() {
		return { voices: { ivc: { create: ivcCreate } } };
	},
}));

import {
	DEFAULT_TTS_MODEL,
	TTS_MODELS,
	isValidModel,
	normalizeVoiceSettings,
	elevenApiKey,
	isConfigured,
	resolveElevenKey,
	listVoices,
	invalidateVoiceCache,
	createClonedVoice,
	deleteVoice,
} from '../api/_lib/elevenlabs.js';

const realFetch = global.fetch;
afterAll(() => {
	global.fetch = realFetch;
});

function voicesResponse(voices) {
	return { ok: true, status: 200, json: async () => ({ voices }) };
}

beforeEach(() => {
	process.env.ELEVENLABS_API_KEY = 'sk_test_key';
	global.fetch = vi.fn();
	ivcCreate.mockReset();
	invalidateVoiceCache();
	vi.useRealTimers();
});

describe('config gate', () => {
	it('reflects ELEVENLABS_API_KEY presence', () => {
		expect(isConfigured()).toBe(true);
		expect(elevenApiKey()).toBe('sk_test_key');
		delete process.env.ELEVENLABS_API_KEY;
		expect(isConfigured()).toBe(false);
		expect(elevenApiKey()).toBeNull();
	});

	it('defaults to the low-latency flash model', () => {
		expect(DEFAULT_TTS_MODEL).toBe('eleven_flash_v2_5');
	});
});

describe('resolveElevenKey (BYOK)', () => {
	const reqWith = (key) => ({ headers: key === undefined ? {} : { 'x-eleven-key': key } });

	it('prefers a valid x-eleven-key header over the platform key', () => {
		expect(resolveElevenKey(reqWith('sk_user_own_key'))).toEqual({
			apiKey: 'sk_user_own_key',
			byok: true,
		});
	});

	it('falls back to the platform key when no header is sent', () => {
		expect(resolveElevenKey(reqWith(undefined))).toEqual({
			apiKey: 'sk_test_key',
			byok: false,
		});
	});

	it('rejects malformed user keys (whitespace inside, control chars, oversized)', () => {
		for (const bad of ['has space', 'ctrl\x01char', 'x'.repeat(300), '', '   ']) {
			expect(resolveElevenKey(reqWith(bad))).toEqual({ apiKey: 'sk_test_key', byok: false });
		}
	});

	it('returns a null key when neither a user key nor the platform key exists', () => {
		delete process.env.ELEVENLABS_API_KEY;
		expect(resolveElevenKey(reqWith(undefined))).toEqual({ apiKey: null, byok: false });
	});

	it('trims surrounding whitespace on the user key', () => {
		expect(resolveElevenKey(reqWith('  sk_padded  '))).toEqual({
			apiKey: 'sk_padded',
			byok: true,
		});
	});
});

describe('listVoices with a BYOK key', () => {
	it('bypasses the shared cache in both directions', async () => {
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'plat', name: 'Platform' }]));
		await listVoices();
		expect(global.fetch).toHaveBeenCalledTimes(1);

		// A user key must not be served the platform's cached catalog...
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'mine', name: 'Mine' }]));
		const user = await listVoices({ apiKey: 'sk_user_own_key' });
		expect(user.cached).toBe(false);
		expect(user.voices[0].voice_id).toBe('mine');
		expect(global.fetch).toHaveBeenCalledTimes(2);
		expect(global.fetch.mock.calls[1][1].headers['xi-api-key']).toBe('sk_user_own_key');

		// ...and must not have poisoned the platform cache on the way through.
		const plat = await listVoices();
		expect(plat.cached).toBe(true);
		expect(plat.voices[0].voice_id).toBe('plat');
	});
});

describe('isValidModel / TTS_MODELS', () => {
	it('accepts catalog models and rejects everything else', () => {
		expect(isValidModel('eleven_flash_v2_5')).toBe(true);
		expect(isValidModel('eleven_turbo_v2_5')).toBe(true);
		expect(isValidModel('gpt-4o-tts')).toBe(false);
		expect(isValidModel(null)).toBe(false);
		expect(isValidModel(undefined)).toBe(false);
	});

	it('exposes the default model in the catalog', () => {
		expect(TTS_MODELS.some((m) => m.id === DEFAULT_TTS_MODEL)).toBe(true);
		for (const m of TTS_MODELS)
			expect(m).toMatchObject({ id: expect.any(String), label: expect.any(String) });
	});
});

describe('normalizeVoiceSettings', () => {
	it('returns null for null input (use defaults)', () => {
		expect(normalizeVoiceSettings(null)).toBeNull();
		expect(normalizeVoiceSettings(undefined)).toBeNull();
	});

	it('fills recommended defaults for an empty object', () => {
		expect(normalizeVoiceSettings({})).toEqual({
			stability: 0.5,
			similarity_boost: 0.75,
			style: 0.5,
			use_speaker_boost: true,
		});
	});

	it('clamps numeric fields to 0..1 and falls back on non-numbers', () => {
		expect(
			normalizeVoiceSettings({ stability: 2, similarity_boost: -1, style: 'nope' }),
		).toEqual({
			stability: 1,
			similarity_boost: 0,
			style: 0.5,
			use_speaker_boost: true,
		});
	});

	it('coerces use_speaker_boost to a boolean', () => {
		expect(normalizeVoiceSettings({ use_speaker_boost: false }).use_speaker_boost).toBe(false);
		expect(normalizeVoiceSettings({ use_speaker_boost: 0 }).use_speaker_boost).toBe(false);
	});

	it('rejects non-object input with a 400', () => {
		expect(() => normalizeVoiceSettings('x')).toThrowError(/must be an object/);
		expect(() => normalizeVoiceSettings([])).toThrow();
		try {
			normalizeVoiceSettings(5);
		} catch (e) {
			expect(e.status).toBe(400);
		}
	});
});

describe('listVoices', () => {
	it('throws a 503 when unconfigured, without hitting the network', async () => {
		delete process.env.ELEVENLABS_API_KEY;
		await expect(listVoices()).rejects.toMatchObject({ status: 503 });
		expect(global.fetch).not.toHaveBeenCalled();
	});

	it('maps the upstream payload to safe public fields', async () => {
		global.fetch.mockResolvedValue(
			voicesResponse([
				{
					voice_id: 'v1',
					name: 'Rachel',
					category: 'premade',
					labels: { accent: 'american' },
					preview_url: 'https://x/preview.mp3',
					secret_internal_field: 'should-not-leak',
				},
			]),
		);
		const { voices, cached } = await listVoices();
		expect(cached).toBe(false);
		expect(voices).toEqual([
			{
				voice_id: 'v1',
				name: 'Rachel',
				category: 'premade',
				labels: { accent: 'american' },
				preview_url: 'https://x/preview.mp3',
			},
		]);
		expect(voices[0]).not.toHaveProperty('secret_internal_field');
	});

	it('serves a warm cache hit without refetching', async () => {
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'v1', name: 'A' }]));
		await listVoices();
		const second = await listVoices();
		expect(second.cached).toBe(true);
		expect(global.fetch).toHaveBeenCalledTimes(1);
	});

	it('refetches after the cache is invalidated', async () => {
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'v1', name: 'A' }]));
		await listVoices();
		invalidateVoiceCache();
		await listVoices();
		expect(global.fetch).toHaveBeenCalledTimes(2);
	});

	it('force:true bypasses the cache', async () => {
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'v1', name: 'A' }]));
		await listVoices();
		await listVoices({ force: true });
		expect(global.fetch).toHaveBeenCalledTimes(2);
	});

	it('expires the cache after the TTL', async () => {
		vi.useFakeTimers();
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'v1', name: 'A' }]));
		await listVoices();
		vi.advanceTimersByTime(4 * 60 * 1000);
		expect((await listVoices()).cached).toBe(true);
		vi.advanceTimersByTime(2 * 60 * 1000); // now > 5-min TTL
		expect((await listVoices()).cached).toBe(false);
		expect(global.fetch).toHaveBeenCalledTimes(2);
	});

	it('throws a 502 on a non-ok upstream response', async () => {
		global.fetch.mockResolvedValue({ ok: false, status: 429, json: async () => ({}) });
		await expect(listVoices()).rejects.toMatchObject({ status: 502 });
	});

	it('throws a 502 when fetch itself rejects', async () => {
		global.fetch.mockRejectedValue(new Error('ECONNRESET'));
		await expect(listVoices()).rejects.toMatchObject({ status: 502 });
	});
});

describe('createClonedVoice', () => {
	it('throws a 503 when unconfigured', async () => {
		delete process.env.ELEVENLABS_API_KEY;
		await expect(createClonedVoice({ name: 'x', files: [] })).rejects.toMatchObject({
			status: 503,
		});
	});

	it('returns the voice id and verification flag on success', async () => {
		ivcCreate.mockResolvedValue({ voice_id: 'cloned-1', requires_verification: true });
		const res = await createClonedVoice({ name: 'Mine', files: ['f'] });
		expect(res).toEqual({ voiceId: 'cloned-1', requiresVerification: true });
	});

	it('defaults requiresVerification to false', async () => {
		ivcCreate.mockResolvedValue({ voice_id: 'cloned-2' });
		expect((await createClonedVoice({ name: 'Mine', files: ['f'] })).requiresVerification).toBe(
			false,
		);
	});

	it('preserves the upstream status code and body (e.g. 422 quota)', async () => {
		// ElevenLabsError exposes `statusCode` + `body`.
		ivcCreate.mockRejectedValue({ statusCode: 422, body: { detail: 'audio too short' } });
		await expect(createClonedVoice({ name: 'x', files: ['f'] })).rejects.toMatchObject({
			status: 422,
			upstreamBody: expect.stringContaining('audio too short'),
		});
	});

	it('falls back to 502 when the SDK error has no status', async () => {
		ivcCreate.mockRejectedValue(new Error('socket hang up'));
		await expect(createClonedVoice({ name: 'x', files: ['f'] })).rejects.toMatchObject({
			status: 502,
			upstreamBody: 'socket hang up',
		});
	});

	it('throws a 502 when the SDK returns no voice_id', async () => {
		ivcCreate.mockResolvedValue({});
		await expect(createClonedVoice({ name: 'x', files: ['f'] })).rejects.toMatchObject({
			status: 502,
		});
	});

	it('invalidates the voice cache so a new clone shows up immediately', async () => {
		global.fetch.mockResolvedValue(voicesResponse([{ voice_id: 'v1', name: 'A' }]));
		await listVoices(); // prime cache
		ivcCreate.mockResolvedValue({ voice_id: 'cloned-3' });
		await createClonedVoice({ name: 'New', files: ['f'] });
		await listVoices(); // must refetch
		expect(global.fetch).toHaveBeenCalledTimes(2);
	});
});

describe('deleteVoice (best-effort)', () => {
	it('no-ops without a key or voice id', async () => {
		delete process.env.ELEVENLABS_API_KEY;
		await deleteVoice('v1');
		expect(global.fetch).not.toHaveBeenCalled();
		process.env.ELEVENLABS_API_KEY = 'sk_test_key';
		await deleteVoice('');
		expect(global.fetch).not.toHaveBeenCalled();
	});

	it('issues a DELETE with the api key header', async () => {
		global.fetch.mockResolvedValue({ ok: true, status: 200 });
		await deleteVoice('v-del');
		expect(global.fetch).toHaveBeenCalledTimes(1);
		const [url, opts] = global.fetch.mock.calls[0];
		expect(url).toContain('/voices/v-del');
		expect(opts.method).toBe('DELETE');
		expect(opts.headers['xi-api-key']).toBe('sk_test_key');
	});

	it('never throws even if the upstream call fails', async () => {
		global.fetch.mockRejectedValue(new Error('network down'));
		await expect(deleteVoice('v-del')).resolves.toBeUndefined();
	});
});