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.

13.9 KB
Raw Blame
// Tests for the productized speech package: POST /api/v1/ai/tts + /api/v1/ai/asr.
//
// Contract under test:
//   • Free tier: a per-IP DAILY quota (10 TTS / 5 ASR) served on the free NVIDIA
//     NIM lanes; above it the request falls through to the x402 402 challenge.
//   • Env gating is honest: a missing NVIDIA key answers 503 not_configured
//     naming the exact var — never a 500, never a fake response.
//   • Input is validated at the boundary (bad body 400, oversize 413, bad
//     Content-Type 415) BEFORE any lane is tried or any payment is prompted.
//   • The catalog (api/v1/_catalog.js) lists both endpoints.
//
// The NIM boundary (the @grpc/grpc-js transport) is fixtured with captured Riva
// response shapes — none of OUR code (ai-speech, asr-nvidia, tts-nvidia, the
// routes) is mocked.

import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vitest';
import { Readable } from 'node:stream';

// ── NIM transport (gRPC) fixture ──────────────────────────────────────────────
const grpcState = vi.hoisted(() => ({
	synthesize: null, // (req, md, opts, cb)
	recognize: null, // (req, md, opts, cb)
	synthCalls: [],
	recogCalls: [],
}));

vi.mock('@grpc/grpc-js', () => {
	class Metadata {
		constructor() {
			this.map = {};
		}
		set(k, v) {
			this.map[k] = v;
		}
		get(k) {
			return this.map[k];
		}
	}
	class RivaSpeechSynthesis {
		synthesize(request, metadata, opts, cb) {
			grpcState.synthCalls.push({ request, metadata });
			grpcState.synthesize(request, metadata, opts, cb);
		}
	}
	class RivaSpeechRecognition {
		recognize(request, metadata, opts, cb) {
			grpcState.recogCalls.push({ request, metadata });
			grpcState.recognize(request, metadata, opts, cb);
		}
	}
	const grpc = {
		Metadata,
		credentials: { createSsl: () => ({ ssl: true }) },
		loadPackageDefinition: () => ({
			nvidia: { riva: { tts: { RivaSpeechSynthesis }, asr: { RivaSpeechRecognition } } },
		}),
	};
	return { default: grpc };
});

vi.mock('@grpc/proto-loader', () => ({
	default: { fromJSON: () => ({ mockPackageDefinition: true }) },
}));

// Captured Riva shapes.
const PCM_BYTES = Buffer.alloc(2000, 0x42); // clearly not RIFF
function grpcTtsSuccess() {
	grpcState.synthesize = (_r, _m, _o, cb) => cb(null, { audio: PCM_BYTES });
}
function grpcAsrSuccess(transcript = 'schedule the deploy for friday') {
	grpcState.recognize = (_r, _m, _o, cb) =>
		cb(null, {
			results: [
				{
					alternatives: [{ transcript, confidence: 0.94, language_code: ['en-US'] }],
					audio_processed: 2.1,
				},
			],
		});
}

// ── env ───────────────────────────────────────────────────────────────────────
const ENV_KEYS = [
	'NVIDIA_API_KEY',
	'NVIDIA_ASR_FUNCTION_ID',
	'X402_PAY_TO_SOLANA',
	'X402_ASSET_MINT_SOLANA',
	'X402_FEE_PAYER_SOLANA',
];
const ORIGINAL_ENV = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));

// ── request/response harness ──────────────────────────────────────────────────
function makeReq({ method = 'POST', url = '/api/v1/ai/tts', headers = {}, body }) {
	const buf = body == null ? Buffer.alloc(0) : Buffer.isBuffer(body) ? body : Buffer.from(body);
	const req = Readable.from(buf.length ? [buf] : []);
	req.method = method;
	req.url = url;
	req.headers = { 'content-length': String(buf.length), ...headers };
	return req;
}

function makeRes() {
	const chunks = [];
	return {
		statusCode: 200,
		_h: {},
		writableEnded: false,
		headersSent: false,
		setHeader(k, v) {
			this._h[k.toLowerCase()] = v;
		},
		getHeader(k) {
			return this._h[k.toLowerCase()];
		},
		write(c) {
			chunks.push(Buffer.from(c));
		},
		end(c) {
			if (c) chunks.push(Buffer.from(c));
			this.writableEnded = true;
		},
		body() {
			return Buffer.concat(chunks);
		},
		json() {
			return JSON.parse(this.body().toString('utf8'));
		},
	};
}

let ttsHandler;
let asrHandler;
async function callTts(req) {
	const res = makeRes();
	await ttsHandler(req, res);
	return res;
}
async function callAsr(req) {
	const res = makeRes();
	await asrHandler(req, res);
	return res;
}

function jsonReq(url, obj, extraHeaders = {}) {
	return makeReq({
		method: 'POST',
		url,
		headers: { 'content-type': 'application/json', ...extraHeaders },
		body: JSON.stringify(obj),
	});
}

let ipCounter = 0;
// Production sits behind Google's load balancer, which appends `<client>, <lb>` to
// X-Forwarded-For — so that is what a distinct caller looks like on the wire. (The
// old `x-vercel-forwarded-for` is caller-settable on GCP and clientIp ignores it.)
const LB_HOP = '35.191.0.1';
function freshIp() {
	return { 'x-forwarded-for': `10.20.30.${++ipCounter}, ${LB_HOP}` };
}

beforeAll(async () => {
	// Warm the cold import of the x402-heavy route modules once (see vitest.config.js).
	ttsHandler = (await import('../../api/v1/ai/tts.js')).default;
	asrHandler = (await import('../../api/v1/ai/asr.js')).default;
}, 240_000);

beforeEach(() => {
	grpcState.synthesize = () => {
		throw new Error('grpc synthesize called without a test stub');
	};
	grpcState.recognize = () => {
		throw new Error('grpc recognize called without a test stub');
	};
	grpcState.synthCalls.length = 0;
	grpcState.recogCalls.length = 0;
	process.env.NVIDIA_API_KEY = 'nvapi-test-key';
	process.env.NVIDIA_ASR_FUNCTION_ID = 'test-asr-fn-id';
	// Minimal x402 config so the 402 fall-through can build a Solana accept.
	process.env.X402_PAY_TO_SOLANA = 'THREEsynthetic1111111111111111111111111PayTo';
	process.env.X402_ASSET_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
	process.env.X402_FEE_PAYER_SOLANA = 'THREEsynthetic1111111111111111111111111PayTo';
});

afterEach(() => {
	for (const k of ENV_KEYS) {
		if (ORIGINAL_ENV[k] === undefined) delete process.env[k];
		else process.env[k] = ORIGINAL_ENV[k];
	}
});

// ── TTS ─────────────────────────────────────────────────────────────────────
describe('POST /api/v1/ai/tts', () => {
	it('GET ?voices=1 lists voices free (no lane call)', async () => {
		const res = await callTts(makeReq({ method: 'GET', url: '/api/v1/ai/tts?voices=1', headers: freshIp() }));
		expect(res.statusCode).toBe(200);
		const data = res.json().data;
		expect(Array.isArray(data.voices)).toBe(true);
		expect(data.voices.length).toBeGreaterThan(0);
		expect(data.default).toBe('nova');
		expect(grpcState.synthCalls).toHaveLength(0);
	});

	it('serves the free tier on the NIM lane and returns base64 WAV', async () => {
		grpcTtsSuccess();
		const res = await callTts(jsonReq('/api/v1/ai/tts', { text: 'Deploy finished', voice: 'nova' }, freshIp()));
		expect(res.statusCode).toBe(200);
		const data = res.json().data;
		expect(data.tier).toBe('free');
		expect(data.content_type).toBe('audio/wav');
		expect(data.characters).toBe('Deploy finished'.length);
		const audio = Buffer.from(data.audio, 'base64');
		expect(audio.subarray(0, 4).toString('ascii')).toBe('RIFF');
		expect(audio.length).toBe(44 + PCM_BYTES.length);
		expect(grpcState.synthCalls).toHaveLength(1);
	});

	it('rejects empty text with 400 before any lane call', async () => {
		const res = await callTts(jsonReq('/api/v1/ai/tts', { text: '   ' }, freshIp()));
		expect(res.statusCode).toBe(400);
		expect(res.json().error).toBe('bad_request');
		expect(grpcState.synthCalls).toHaveLength(0);
	});

	it('rejects invalid JSON with 400', async () => {
		const res = await callTts(
			makeReq({ url: '/api/v1/ai/tts', headers: { 'content-type': 'application/json', ...freshIp() }, body: '{not json' }),
		);
		expect(res.statusCode).toBe(400);
		expect(grpcState.synthCalls).toHaveLength(0);
	});

	it('rejects text over the paid ceiling with 400 text_too_long', async () => {
		const res = await callTts(jsonReq('/api/v1/ai/tts', { text: 'a'.repeat(5000) }, freshIp()));
		expect(res.statusCode).toBe(400);
		expect(res.json().error).toBe('text_too_long');
	});

	it('text over the free char cap (≤4096) falls through to the 402 challenge', async () => {
		const res = await callTts(jsonReq('/api/v1/ai/tts', { text: 'b'.repeat(600) }, freshIp()));
		expect(res.statusCode).toBe(402);
		expect(grpcState.synthCalls).toHaveLength(0);
	});

	it('falls through to 402 once the daily free quota is exhausted', async () => {
		grpcTtsSuccess();
		const ip = { 'x-forwarded-for': `10.99.99.10, ${LB_HOP}` };
		for (let i = 0; i < 10; i++) {
			const ok = await callTts(jsonReq('/api/v1/ai/tts', { text: `call ${i}` }, ip));
			expect(ok.statusCode).toBe(200);
		}
		const over = await callTts(jsonReq('/api/v1/ai/tts', { text: 'one too many' }, ip));
		expect(over.statusCode).toBe(402);
	});

	it('returns 503 not_configured (naming NVIDIA_API_KEY) when the lane is absent', async () => {
		delete process.env.NVIDIA_API_KEY;
		const res = await callTts(jsonReq('/api/v1/ai/tts', { text: 'anyone there?' }, freshIp()));
		expect(res.statusCode).toBe(503);
		expect(res.json().error).toBe('not_configured');
		expect(res.json().error_description).toContain('NVIDIA_API_KEY');
		expect(grpcState.synthCalls).toHaveLength(0);
	});
});

// ── ASR ─────────────────────────────────────────────────────────────────────
describe('POST /api/v1/ai/asr', () => {
	// Build a tiny valid WAV from raw PCM so parseWav strips it correctly.
	async function wavClip(pcmBytes = 3200, sampleRate = 16000) {
		const { pcmToWav } = await import('../../api/_lib/tts-nvidia.js');
		return pcmToWav(Buffer.alloc(pcmBytes, 0x01), { sampleRateHz: sampleRate });
	}

	it('GET returns the capability probe', async () => {
		const res = await callAsr(makeReq({ method: 'GET', url: '/api/v1/ai/asr', headers: freshIp() }));
		expect(res.statusCode).toBe(200);
		const data = res.json().data;
		expect(data.configured).toBe(true);
		expect(data.encodings).toEqual(expect.arrayContaining(['wav', 'pcm', 'flac', 'ogg']));
	});

	it('transcribes a base64 WAV on the free tier', async () => {
		grpcAsrSuccess('hello world');
		const wav = await wavClip();
		const res = await callAsr(jsonReq('/api/v1/ai/asr', { audio: wav.toString('base64'), format: 'wav' }, freshIp()));
		expect(res.statusCode).toBe(200);
		const data = res.json().data;
		expect(data.tier).toBe('free');
		expect(data.text).toBe('hello world');
		expect(data.confidence).toBeCloseTo(0.94, 5);
		expect(data.duration).toBeCloseTo(2.1, 5);
		expect(grpcState.recogCalls).toHaveLength(1);
	});

	it('rejects a JSON body with no audio (400)', async () => {
		const res = await callAsr(jsonReq('/api/v1/ai/asr', { language: 'en-US' }, freshIp()));
		expect(res.statusCode).toBe(400);
		expect(res.json().error).toBe('bad_request');
		expect(grpcState.recogCalls).toHaveLength(0);
	});

	it('rejects an unsupported audio Content-Type (415)', async () => {
		const res = await callAsr(
			makeReq({ url: '/api/v1/ai/asr', headers: { 'content-type': 'audio/webm', ...freshIp() }, body: Buffer.alloc(500, 1) }),
		);
		expect(res.statusCode).toBe(415);
		expect(res.json().error).toBe('unsupported_media_type');
		expect(grpcState.recogCalls).toHaveLength(0);
	});

	it('rejects oversize audio with 413', async () => {
		const big = Buffer.alloc(8 * 1024 * 1024 + 1024, 0x00); // > 8 MiB decoded cap
		const res = await callAsr(
			makeReq({ url: '/api/v1/ai/asr', headers: { 'content-type': 'audio/wav', ...freshIp() }, body: big }),
		);
		expect(res.statusCode).toBe(413);
		expect(res.json().error).toBe('payload_too_large');
		expect(grpcState.recogCalls).toHaveLength(0);
	});

	it('audio longer than the free 60s cap falls through to the 402 challenge', async () => {
		// 16 kHz mono s16 → 60s = 1,920,000 PCM bytes; make it clearly longer.
		const longWav = await wavClip(2_100_000, 16000);
		const res = await callAsr(jsonReq('/api/v1/ai/asr', { audio: longWav.toString('base64'), format: 'wav' }, freshIp()));
		expect(res.statusCode).toBe(402);
		expect(grpcState.recogCalls).toHaveLength(0);
	});

	it('falls through to 402 once the daily free quota is exhausted', async () => {
		grpcAsrSuccess('ok');
		const wav = await wavClip();
		const ip = { 'x-forwarded-for': `10.99.99.20, ${LB_HOP}` };
		const b64 = wav.toString('base64');
		for (let i = 0; i < 5; i++) {
			const ok = await callAsr(jsonReq('/api/v1/ai/asr', { audio: b64, format: 'wav' }, ip));
			expect(ok.statusCode).toBe(200);
		}
		const over = await callAsr(jsonReq('/api/v1/ai/asr', { audio: b64, format: 'wav' }, ip));
		expect(over.statusCode).toBe(402);
	});

	it('returns 503 not_configured (naming the ASR env) when the lane is absent', async () => {
		delete process.env.NVIDIA_ASR_FUNCTION_ID;
		const wav = await wavClip();
		const res = await callAsr(jsonReq('/api/v1/ai/asr', { audio: wav.toString('base64'), format: 'wav' }, freshIp()));
		expect(res.statusCode).toBe(503);
		expect(res.json().error).toBe('not_configured');
		expect(res.json().error_description).toContain('NVIDIA_ASR_FUNCTION_ID');
		expect(grpcState.recogCalls).toHaveLength(0);
	});
});

// ── Catalog ───────────────────────────────────────────────────────────────────
describe('catalog registration', () => {
	it('lists both speech endpoints in api/v1/_catalog.js', async () => {
		const { CATALOG } = await import('../../api/v1/_catalog.js');
		const tts = CATALOG.find((e) => e.id === 'v1.ai.tts');
		const asr = CATALOG.find((e) => e.id === 'v1.ai.asr');
		expect(tts).toBeTruthy();
		expect(tts.path).toBe('/api/v1/ai/tts');
		expect(tts.method).toBe('POST');
		expect(asr).toBeTruthy();
		expect(asr.path).toBe('/api/v1/ai/asr');
		expect(asr.method).toBe('POST');
	});
});