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.

14.1 KB
Raw Blame
/**
 * Tests for POST /api/v1/ai/image (api/v1/ai/image.js).
 *
 * The endpoint is a free-quota funnel over the platform's text→image lanes: the
 * first N images/day per IP are free (payment bypassed), then callers fall
 * through to the x402 pay-per-image lane. What's tested here is the endpoint's
 * own logic — validation, the free→402 fall-through, the honest no-lane 503, and
 * safety-refusal mapping — with the payment rail and the text→image lane stubbed
 * at their module boundaries (each has its own suite). The provider boundaries
 * (lane success shape, Vertex refusal shape) use the REAL captured shapes from
 * api/_mcp3d/text-to-image.js and api/_mcp3d/vertex-imagen.js.
 */

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

beforeAll(() => {
	Object.assign(process.env, {
		APP_ORIGIN: 'https://three.ws',
		X402_PAY_TO_BASE: '0x0000000000000000000000000000000000000001',
		X402_ASSET_ADDRESS_BASE: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
		X402_ADVERTISE_BASE: 'true',
	});
});

// Stub payment verify/settle — the 402 challenge, buildRequirements, and bazaar
// schema stay real; only the facilitator round-trips are faked.
vi.mock('../../api/_lib/x402-spec.js', async (importActual) => {
	const actual = await importActual();
	return {
		...actual,
		verifyPayment: vi.fn(async () => ({ ok: true, requirement: { network: 'base', amount: '20000' }, payer: '0xpayer' })),
		settlePayment: vi.fn(async () => ({ settled: true, transaction: '0xtx', network: 'base' })),
		encodePaymentResponseHeader: vi.fn(() => 'stub-payment-response'),
	};
});

// Deterministic client IP; keep the real limiters (permissive in-memory in test).
vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
	const actual = await importActual();
	return { ...actual, clientIp: () => '203.0.113.9' };
});

// Text→image lane — controlled per test. Default: a real NIM FLUX success shape
// (see nimFluxImage return, api/_mcp3d/text-to-image.js).
const laneState = vi.hoisted(() => ({
	impl: async () => ({ imageUrl: 'https://cdn.example/forge/refs/abc.jpg', model: 'black-forest-labs/flux.1-schnell' }),
}));
vi.mock('../../api/_mcp3d/text-to-image.js', () => ({
	textToImage: (...args) => laneState.impl(...args),
}));

// Free-quota module — controlled per test.
const quotaState = vi.hoisted(() => ({ allowed: true, consumed: 0, reserveGranted: true }));
vi.mock('../../api/_lib/ai-image-quota.js', () => ({
	freePerDay: () => 5,
	peekFreeQuota: vi.fn(async () => ({
		allowed: quotaState.allowed,
		used: quotaState.allowed ? 0 : 5,
		limit: 5,
		remaining: quotaState.allowed ? 5 : 0,
		resetAt: '2026-07-08T00:00:00.000Z',
	})),
	reserveFreeQuota: vi.fn(async () => {
		if (!quotaState.reserveGranted) {
			return { granted: false, counted: false, used: 5, limit: 5, remaining: 0, resetAt: '2026-07-08T00:00:00.000Z' };
		}
		quotaState.consumed += 1;
		return { granted: true, counted: true, used: quotaState.consumed, limit: 5, remaining: 5 - quotaState.consumed, resetAt: '2026-07-08T00:00:00.000Z' };
	}),
	releaseFreeQuota: vi.fn(async () => {
		quotaState.consumed -= 1;
	}),
	__resetFreeQuota: () => {},
}));

const { default: handler } = await import('../../api/v1/ai/image.js');
const { CATALOG } = await import('../../api/v1/_catalog.js');

function makeRes() {
	return {
		statusCode: 200,
		headers: {},
		body: null,
		setHeader(name, value) { this.headers[String(name).toLowerCase()] = value; },
		getHeader(name) { return this.headers[String(name).toLowerCase()]; },
		end(body) { this.body = body ?? null; },
	};
}

// A real Readable stream (not a plain async-iterable object) so it matches
// production `req` semantics — the shared readBody() helper (api/_lib/http.js)
// reads via `.on('data'/'end')`, which only a real stream implements.
function makeReq({ method = 'POST', url = '/api/v1/ai/image', headers = {}, body = null } = {}) {
	const payload = body == null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
	const buf = Buffer.from(payload, 'utf8');
	const req = Readable.from(buf.length ? [buf] : []);
	req.method = method;
	req.url = url;
	req.headers = { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9', 'content-length': String(buf.length), ...headers };
	return req;
}

const LANE_ENV = ['NVIDIA_API_KEY', 'GOOGLE_CLOUD_PROJECT', 'GCP_SERVICE_ACCOUNT_JSON', 'REPLICATE_API_TOKEN', 'VERTEX_IMAGEN_ENABLED', 'X402_PRICE_AI_IMAGE'];
const savedEnv = {};
beforeEach(() => {
	for (const k of LANE_ENV) savedEnv[k] = process.env[k];
	quotaState.allowed = true;
	quotaState.consumed = 0;
	quotaState.reserveGranted = true;
	laneState.impl = async () => ({ imageUrl: 'https://cdn.example/forge/refs/abc.jpg', model: 'black-forest-labs/flux.1-schnell' });
	// A configured lane by default so the happy paths run.
	process.env.NVIDIA_API_KEY = 'nvapi-test';
});
afterEach(() => {
	for (const k of LANE_ENV) {
		if (savedEnv[k] === undefined) delete process.env[k];
		else process.env[k] = savedEnv[k];
	}
	vi.restoreAllMocks();
});

describe('catalog registration', () => {
	it('registers v1.ai.image as a public POST route', () => {
		const entry = CATALOG.find((e) => e.id === 'v1.ai.image');
		expect(entry).toBeTruthy();
		expect(entry.method).toBe('POST');
		expect(entry.path).toBe('/api/v1/ai/image');
		expect(entry.auth).toBe('public');
	});
});

describe('validation (free path, fresh IP)', () => {
	it('rejects an empty prompt with 400 and no charge', async () => {
		const res = makeRes();
		await handler(makeReq({ body: { prompt: '' } }), res);
		expect(res.statusCode).toBe(400);
		expect(JSON.parse(res.body).error).toBe('invalid_prompt');
	});

	it('rejects an oversized prompt with 400', async () => {
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'x'.repeat(2001) } }), res);
		expect(res.statusCode).toBe(400);
		expect(JSON.parse(res.body).error).toBe('prompt_too_long');
	});

	it('rejects an unsupported aspect_ratio with 400', async () => {
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl', aspect_ratio: '5:1' } }), res);
		expect(res.statusCode).toBe(400);
		expect(JSON.parse(res.body).error).toBe('invalid_aspect_ratio');
	});

	it('rejects a non-integer seed with 400', async () => {
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl', seed: 1.5 } }), res);
		expect(res.statusCode).toBe(400);
		expect(JSON.parse(res.body).error).toBe('invalid_seed');
	});

	it('does not spend a quota slot on a validation error', async () => {
		const { reserveFreeQuota } = await import('../../api/_lib/ai-image-quota.js');
		const res = makeRes();
		await handler(makeReq({ body: { prompt: '' } }), res);
		expect(reserveFreeQuota).not.toHaveBeenCalled();
	});
});

describe('free path success', () => {
	it('serves an image free, shapes { url, provider, width, height }, and spends a slot', async () => {
		const { reserveFreeQuota } = await import('../../api/_lib/ai-image-quota.js');
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine', aspect_ratio: '16:9', seed: 42 } }), res);
		expect(res.statusCode).toBe(200);
		const body = JSON.parse(res.body);
		expect(body.url).toBe('https://cdn.example/forge/refs/abc.jpg');
		expect(body.provider).toBe('nvidia-nim');
		expect(body.width).toBe(1344);
		expect(body.height).toBe(768);
		expect(body.aspect_ratio).toBe('16:9');
		expect(body.seed).toBe(42);
		expect(body.free).toBe(true);
		expect(reserveFreeQuota).toHaveBeenCalledTimes(1);
	});

	it('forwards the seed to the lane', async () => {
		const spy = vi.fn(async () => ({ imageUrl: 'https://cdn.example/x.jpg', model: 'black-forest-labs/flux.1-schnell' }));
		laneState.impl = spy;
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl', seed: 7 } }), res);
		expect(spy).toHaveBeenCalledWith('a brass owl', expect.objectContaining({ aspectRatio: '1:1', seed: 7 }));
	});
});

describe('free quota reservation', () => {
	it('refunds the reserved slot when the lane fails to deliver an image', async () => {
		const { releaseFreeQuota } = await import('../../api/_lib/ai-image-quota.js');
		laneState.impl = async () => ({ imageUrl: null, model: 'black-forest-labs/flux.1-schnell' });
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl' } }), res);
		expect(res.statusCode).toBe(502);
		expect(releaseFreeQuota).toHaveBeenCalledTimes(1);
		expect(quotaState.consumed).toBe(0);
	});

	it('refuses to generate when a concurrent request already took the last free slot', async () => {
		quotaState.reserveGranted = false;
		const spy = vi.fn(async () => ({ imageUrl: 'https://cdn.example/x.jpg', model: 'm' }));
		laneState.impl = spy;
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl' } }), res);
		expect(res.statusCode).toBe(429);
		expect(spy).not.toHaveBeenCalled();
	});
});

describe('quota fall-through to x402', () => {
	it('emits a 402 quoting $0.02 once the free quota is exhausted', async () => {
		quotaState.allowed = false;
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(res.statusCode).toBe(402);
		const body = JSON.parse(res.body);
		expect((body.accepts || []).map((a) => a.amount)).toContain('20000');
	});
});

describe('no-lane honesty', () => {
	// Keyless Pollinations is always behind the keyed rungs, so "no key at all"
	// is no longer "no lane": the request still runs, and the health surface is
	// where the absent keyed lanes are named (see the GET ?health=1 case).
	it('still serves with no keyed lane set, through the keyless rung', async () => {
		delete process.env.NVIDIA_API_KEY;
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(res.statusCode).toBe(200);
	});
});

describe('provider safety refusal', () => {
	it('maps a Vertex/Gemini content block to 422 without retrying', async () => {
		// Real captured refusal shape: generateViaGemini throws this exact message
		// when candidates carry a finishReason and no image part.
		laneState.impl = async () => {
			throw new Error('Vertex Gemini returned no image data (finishReason: IMAGE_SAFETY)');
		};
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'something blocked' } }), res);
		expect(res.statusCode).toBe(422);
		expect(JSON.parse(res.body).error).toBe('content_refused');
	});
});

describe('GET surfaces', () => {
	it('serves a discovery doc with free-tier + price on plain GET', async () => {
		const res = makeRes();
		await handler(makeReq({ method: 'GET' }), res);
		expect(res.statusCode).toBe(200);
		const body = JSON.parse(res.body);
		expect(body.route).toBe('/api/v1/ai/image');
		expect(body.free_tier.images_per_day_per_ip).toBe(5);
		expect(body.price_usdc).toBe('0.020000');
	});

	// Keyless Pollinations means the image surface is never "unconfigured":
	// with no key at all it still answers 200 and names the keyed lanes missing.
	it('reports per-lane health on GET ?health=1 with no keyed lane: still configured via the keyless rung', async () => {
		delete process.env.NVIDIA_API_KEY;
		const res = makeRes();
		await handler(makeReq({ method: 'GET', url: '/api/v1/ai/image?health=1' }), res);
		expect(res.statusCode).toBe(200);
		const body = JSON.parse(res.body);
		expect(body.configured).toBe(true);
		expect(body.lanes.pollinations.configured).toBe(true);
		expect(body.lanes.nim.status).toBe('unconfigured');
		expect(body.missing_env).toContain('NVIDIA_API_KEY');
	});

	it('probes a configured Replicate lane as reachable on GET ?health=1', async () => {
		delete process.env.NVIDIA_API_KEY;
		process.env.REPLICATE_API_TOKEN = 'r8_test';
		globalThis.fetch = vi.fn(async () => new Response('{}', { status: 200 }));
		const res = makeRes();
		await handler(makeReq({ method: 'GET', url: '/api/v1/ai/image?health=1' }), res);
		expect(res.statusCode).toBe(200);
		const body = JSON.parse(res.body);
		expect(body.configured).toBe(true);
		expect(body.healthy).toBe(true);
		expect(body.lanes.replicate.status).toBe('ok');
	});
});

// When object storage rejects the write, the lane still draws the image and
// image-persist.js hands back an inline data URI so our own 3D workers keep
// running. This endpoint's contract is a durable https URL a third party can
// fetch, so it cannot pass that through, but it also must not report it as a
// failed generation. That opaque 502 is what a rejected R2 credential looked
// like for hours on 2026-09-09 and again from 03:15 UTC on 2026-09-11.
describe('object storage outage', () => {
	const INLINE = 'data:image/jpeg;base64,/9j/4AAQSkZJRg==';

	it('answers 503 storage_unavailable when the image could only be stored inline', async () => {
		laneState.impl = async () => ({ imageUrl: INLINE, model: 'black-forest-labs/flux.1-schnell' });
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(res.statusCode).toBe(503);
		const body = JSON.parse(res.body);
		// The code is the contract a caller reacts to: retry later, and do not
		// rewrite the prompt. (5xx descriptions on this route are redacted to a
		// support ref by design; the sentence reaches the operator via the log.)
		expect(body.error).toBe('storage_unavailable');
		expect(body.ref).toBeTruthy();
	});

	it('never leaks the inline bytes into the response', async () => {
		laneState.impl = async () => ({ imageUrl: INLINE, model: 'black-forest-labs/flux.1-schnell' });
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(res.body).not.toContain('data:image/');
	});

	it('does not burn a free-quota slot on a storage failure', async () => {
		laneState.impl = async () => ({ imageUrl: INLINE, model: 'black-forest-labs/flux.1-schnell' });
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(quotaState.consumed).toBe(0);
	});

	it('still reports a genuinely empty lane result as generation_failed', async () => {
		laneState.impl = async () => ({ imageUrl: null, model: 'black-forest-labs/flux.1-schnell' });
		const res = makeRes();
		await handler(makeReq({ body: { prompt: 'a brass owl figurine' } }), res);
		expect(res.statusCode).toBe(502);
		expect(JSON.parse(res.body).error).toBe('generation_failed');
	});
});