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.8 KB
Raw Blame
/**
 * GET /api/animations/library — full motion library manifest proxy.
 *
 * The endpoint proxies the R2-hosted library manifest (published by
 * scripts/mixamo-all.mjs --upload). Contract under test:
 *   - pre-launch (manifest object missing) → 200 { clips: [], total: 0 },
 *     never an error, so the gallery/embed/studio feature-detect by emptiness;
 *   - published manifest ({ clips: [...] } shape) → clips passed through with
 *     total derived server-side;
 *   - bare-array manifest (legacy shape) → also accepted;
 *   - non-GET → 405.
 */

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

const readManifest = vi.fn();
vi.mock('../api/_lib/r2.js', () => ({ getPublicObjectBuffer: (...a) => readManifest(...a) }));

const { default: handler } = await import('../api/animations/library.js');

function fakeReq(method = 'GET', url = '/api/animations/library') {
	return { method, url, headers: {} };
}

function fakeRes() {
	const headers = {};
	return {
		statusCode: 0,
		body: undefined,
		ended: false,
		setHeader(k, v) { headers[String(k).toLowerCase()] = v; },
		getHeader(k) { return headers[String(k).toLowerCase()]; },
		end(b) { this.body = b; this.ended = true; },
		_headers: headers,
	};
}

const CLIP = {
	name: 'mx-hip-hop-dancing',
	label: 'Hip Hop Dancing',
	icon: '💃',
	loop: true,
	duration: 4.4,
	bytes: 1174283,
	url: 'https://cdn.example/animations/library/clips/mx-hip-hop-dancing.json',
	source: 'Quaternius Universal Animation Library 2',
	license: 'CC0 1.0 Universal',
};

// No beforeEach reset: every test installs its own mockResolvedValue/
// mockRejectedValue, which fully replaces the previous implementation.
// (vitest 4's mockReset() leaves the fn throwing the prior rejection value
// during the reset window, which fails the rejection tests spuriously.)
describe('GET /api/animations/library', () => {
	it('returns an empty library when the manifest has not been uploaded yet', async () => {
		const missing = Object.assign(new Error('no such key'), { name: 'NoSuchKey' });
		readManifest.mockRejectedValue(missing);
		const res = fakeRes();
		await handler(fakeReq(), res);
		expect(res.statusCode).toBe(200);
		expect(JSON.parse(res.body)).toEqual({ clips: [], total: 0, generated_at: null });
	});

	it('degrades to an empty library on storage errors instead of failing', async () => {
		readManifest.mockRejectedValue(new Error('socket hang up'));
		const res = fakeRes();
		await handler(fakeReq(), res);
		expect(res.statusCode).toBe(200);
		expect(JSON.parse(res.body).clips).toEqual([]);
	});

	it('passes through a published { clips } manifest and derives total', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({
			generated_at: '2026-07-04T00:00:00.000Z',
			total: 1,
			clips: [CLIP],
		})));
		const res = fakeRes();
		await handler(fakeReq(), res);
		expect(res.statusCode).toBe(200);
		const body = JSON.parse(res.body);
		expect(body.clips).toEqual([CLIP]);
		expect(body.total).toBe(1);
		expect(body.generated_at).toBe('2026-07-04T00:00:00.000Z');
		expect(res.getHeader('cache-control')).toContain('s-maxage=300');
	});

	it('accepts a bare-array manifest shape', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify([CLIP])));
		const res = fakeRes();
		await handler(fakeReq(), res);
		expect(JSON.parse(res.body).clips).toEqual([CLIP]);
	});

	it('rejects non-GET methods', async () => {
		readManifest.mockResolvedValue(Buffer.from('[]'));
		const res = fakeRes();
		await handler(fakeReq('POST'), res);
		expect(res.statusCode).toBe(405);
	});

	// ── Bounded pagination (opt-in via ?limit) ──────────────────────────────
	const CLIPS = Array.from({ length: 5 }, (_, i) => ({ ...CLIP, name: `mx-clip-${i}` }));

	it('pages a large manifest with ?limit and exposes next_offset', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?limit=2'), res);
		const body = JSON.parse(res.body);
		expect(body.total).toBe(5); // full catalog size, not the page size
		expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-0', 'mx-clip-1']);
		expect(body.offset).toBe(0);
		expect(body.next_offset).toBe(2);
	});

	it('honors ?offset and returns next_offset=null on the final page', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?limit=2&offset=4'), res);
		const body = JSON.parse(res.body);
		expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-4']);
		expect(body.offset).toBe(4);
		expect(body.next_offset).toBe(null);
	});

	it('returns an empty page (not an error) when offset runs past the end', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?limit=2&offset=99'), res);
		const body = JSON.parse(res.body);
		expect(body.clips).toEqual([]);
		expect(body.total).toBe(5);
		expect(body.next_offset).toBe(null);
	});

	it('omits pagination fields entirely when ?limit is absent (legacy contract)', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library'), res);
		const body = JSON.parse(res.body);
		expect(body).toEqual({ clips: CLIPS, total: 5, generated_at: null });
		expect('next_offset' in body).toBe(false);
	});

	// ── Name lookup (?name=) ────────────────────────────────────────────────
	// A pose deep-link and the embed viewer resolve ONE clip by name and cannot
	// use paging to do it: they do not know which page holds the name. Without
	// this they download the whole manifest per lookup, which is the response
	// that grows worst as the catalog does.

	it('returns only the named clip, with the full catalog total', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?name=mx-clip-3'), res);
		const body = JSON.parse(res.body);
		expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-3']);
		expect(body.total).toBe(5);
	});

	it('accepts several names, repeated and comma-separated', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(
			fakeReq('GET', '/api/animations/library?name=mx-clip-0,mx-clip-2&name=mx-clip-4'),
			res,
		);
		const body = JSON.parse(res.body);
		expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-0', 'mx-clip-2', 'mx-clip-4']);
	});

	it('returns an empty list for a name the library does not have', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?name=mx-nope'), res);
		const body = JSON.parse(res.body);
		expect(body.clips).toEqual([]);
		expect(body.total).toBe(5);
	});

	it('matches names exactly rather than by prefix or substring', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?name=mx-clip'), res);
		expect(JSON.parse(res.body).clips).toEqual([]);
	});

	it('caps how many names one request can ask for', async () => {
		const many = Array.from({ length: 80 }, (_, i) => ({ ...CLIP, name: `mx-many-${i}` }));
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: many })));
		const res = fakeRes();
		const query = many.map((c) => `name=${c.name}`).join('&');
		await handler(fakeReq('GET', `/api/animations/library?${query}`), res);
		const body = JSON.parse(res.body);
		expect(body.clips.length).toBe(50);
		expect(body.total).toBe(80);
	});

	// ── Facets (?facets=1) ──────────────────────────────────────────────────
	// The gallery needs exact totals to render its hero line and chips. Deriving
	// them client-side means holding the whole catalog in the browser, which is
	// the reason it used to download every page on load.

	it('counts the catalog by category and returns no clips', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({
			clips: [
				{ ...CLIP, name: 'mx-walking', label: 'Walking' },
				{ ...CLIP, name: 'mx-running', label: 'Running' },
				{ ...CLIP, name: 'mx-hip-hop-dancing', label: 'Hip Hop Dancing' },
			],
		})));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);
		const body = JSON.parse(res.body);
		expect(body.clips).toBeUndefined();
		expect(body.total).toBe(3);
		const counts = Object.fromEntries(body.categories.map((c) => [c.key, c.count]));
		expect(counts.locomotion).toBe(2);
		expect(counts.dance).toBe(1);
	});

	it('sums the facet counts to the catalog total', async () => {
		const clips = Array.from({ length: 40 }, (_, i) => ({ ...CLIP, name: `mx-clip-${i}`, label: `Clip ${i}` }));
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);
		const body = JSON.parse(res.body);
		expect(body.categories.reduce((n, c) => n + c.count, 0)).toBe(body.total);
	});

	it('reports every category, including the empty ones, so chips stay stable', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: [CLIP] })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);
		const body = JSON.parse(res.body);
		expect(body.categories.length).toBeGreaterThan(5);
		expect(body.categories.some((c) => c.count === 0)).toBe(true);
	});

	it('ignores an empty ?name= and falls through to the legacy full response', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));
		const res = fakeRes();
		await handler(fakeReq('GET', '/api/animations/library?name='), res);
		expect(JSON.parse(res.body).clips.length).toBe(5);
	});

	// ── License filter (defense in depth) ───────────────────────────────────
	// Adobe's Mixamo terms permit in-project playback but not redistributing raw
	// clip files, which is exactly what this endpoint does. No clip missing a
	// `license`, or whose `source` names Mixamo, may ever be served here,
	// regardless of what an uploader staged (prompts/finish/
	// 085-partners-02-animation-library-license.md).

	it('drops a clip with no license field', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({
			clips: [CLIP, { ...CLIP, name: 'no-license-clip', license: undefined }],
		})));
		const res = fakeRes();
		await handler(fakeReq(), res);
		const body = JSON.parse(res.body);
		expect(body.clips.map((c) => c.name)).toEqual(['mx-hip-hop-dancing']);
		expect(body.total).toBe(1);
	});

	it('drops a clip whose source names Mixamo even if it carries a license', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({
			clips: [CLIP, { ...CLIP, name: 'mixamo-clip', source: 'Mixamo', license: 'royalty-free' }],
		})));
		const res = fakeRes();
		await handler(fakeReq(), res);
		const body = JSON.parse(res.body);
		expect(body.clips.map((c) => c.name)).toEqual(['mx-hip-hop-dancing']);
	});

	it('keeps a properly licensed CC0 clip', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: [CLIP] })));
		const res = fakeRes();
		await handler(fakeReq(), res);
		const body = JSON.parse(res.body);
		expect(body.clips).toEqual([CLIP]);
	});
});