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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
test(cosmos): cover the world-generation endpoint's request contract
nirholas53922c187dca
diff --git a/tests/api/cosmos-endpoint.test.js b/tests/api/cosmos-endpoint.test.jsnew file mode 100644index 000000000..2336452eb--- /dev/null+++ b/tests/api/cosmos-endpoint.test.js@@ -0,0 +1,169 @@+// /api/cosmos: the text→world lane behind /cosmos.+//+// The contract under test is what the BROWSER is allowed to see. The upstream+// gateway answers a retired model with `Function '<uuid>': Not found for account+// '<id>'`, and that string was rendered verbatim in the page's error banner: an+// operator detail (with the account id in it) offered to the user as something to+// retry. So: every failure maps to lane copy the caller can act on, a retired lane+// reports 503 so the page lands in its designed offline state, and the poll never+// hands back provider diagnostics.+//+// The provider module is stubbed at the seam; no network, no live NVCF spend.++import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+import { Readable } from 'node:stream';++const textToWorld = vi.fn();+const status = vi.fn();+const configured = vi.fn(() => true);++vi.mock('../../api/_providers/nvidia-cosmos.js', () => ({+ nvidiaCosmosConfigured: (...a) => configured(...a),+ createNvidiaCosmosProvider: () => ({ textToWorld, status }),+}));++function makeReq({ method = 'POST', url = '/api/cosmos', body = null } = {}) {+ const raw = body == null ? '' : JSON.stringify(body);+ const stream = Readable.from(raw ? [Buffer.from(raw)] : []);+ stream.method = method;+ stream.url = url;+ stream.headers = { 'content-type': 'application/json', host: 'three.ws' };+ stream.socket = { remoteAddress: '127.0.0.1' };+ return stream;+}++function makeRes() {+ return {+ statusCode: 200,+ _h: {},+ writableEnded: false,+ headersSent: false,+ setHeader(k, v) {+ this._h[k.toLowerCase()] = v;+ },+ getHeader(k) {+ return this._h[k.toLowerCase()];+ },+ end(b) {+ this._body = b;+ this.writableEnded = true;+ },+ };+}++async function dispatch(req) {+ const res = makeRes();+ const mod = await import('../../api/cosmos.js');+ await mod.default(req, res);+ return { status: res.statusCode, body: res._body ? JSON.parse(res._body) : null };+}++// The exact upstream body the live account received on the retired model.+const RETIRED_DETAIL = "Function '01327741-a1cb-4bdb-a31e-5391c8ca48c2': Not found for account 'umJDGCKdQZeA'";++beforeEach(() => {+ vi.spyOn(console, 'warn').mockImplementation(() => {});+ configured.mockReturnValue(true);+ textToWorld.mockReset();+ status.mockReset();+});++afterEach(() => {+ vi.restoreAllMocks();+});++describe('/api/cosmos: submit failures never leak upstream detail', () => {+ it('answers a retired lane with 503 lane_unavailable and page-ready copy', async () => {+ textToWorld.mockRejectedValue(+ Object.assign(new Error(RETIRED_DETAIL), { code: 'lane_unavailable', status: 503, providerStatus: 404 }),+ );+ const res = await dispatch(makeReq({ body: { prompt: 'a neon tokyo street in the rain' } }));++ expect(res.status).toBe(503);+ expect(res.body.error).toBe('lane_unavailable');+ expect(res.body.message).toMatch(/offline right now/i);+ expect(JSON.stringify(res.body)).not.toContain('01327741');+ expect(JSON.stringify(res.body)).not.toContain('umJDGCKdQZeA');+ });++ it('maps an unclassified provider failure to 502 with generic copy', async () => {+ textToWorld.mockRejectedValue(Object.assign(new Error(RETIRED_DETAIL), { code: 'provider_error' }));+ const res = await dispatch(makeReq({ body: { prompt: 'a desert canyon at dusk' } }));++ expect(res.status).toBe(502);+ expect(res.body.error).toBe('provider_error');+ expect(res.body.message).not.toContain('Function');+ });++ it('keeps the retry hint on a rate limit', async () => {+ textToWorld.mockRejectedValue(+ Object.assign(new Error('slow down'), { code: 'rate_limited', retryAfter: 12 }),+ );+ const res = await dispatch(makeReq({ body: { prompt: 'a snowy mountain pass' } }));++ expect(res.status).toBe(429);+ expect(res.body.retry_after).toBe(12);+ });++ it('reports an unconfigured deployment as 503 without starting a job', async () => {+ configured.mockReturnValue(false);+ const res = await dispatch(makeReq({ body: { prompt: 'a bioluminescent forest' } }));++ expect(res.status).toBe(503);+ expect(res.body.error).toBe('unconfigured');+ expect(textToWorld).not.toHaveBeenCalled();+ });++ it('still rejects a too-short prompt before touching the provider', async () => {+ const res = await dispatch(makeReq({ body: { prompt: 'a' } }));+ expect(res.status).toBe(400);+ expect(res.body.error).toBe('invalid_prompt');+ expect(textToWorld).not.toHaveBeenCalled();+ });++ it('hands back the job handle on an accepted submit', async () => {+ textToWorld.mockResolvedValue({ taskId: 'req-world-42' });+ const res = await dispatch(makeReq({ body: { prompt: 'a golden savanna at sunset', seed: 7 } }));++ expect(res.status).toBe(202);+ expect(res.body.job_id).toBe('req-world-42');+ expect(textToWorld).toHaveBeenCalledWith({ prompt: 'a golden savanna at sunset', seed: 7 });+ });+});++describe('/api/cosmos: the poll hands back status, never diagnostics', () => {+ const JOB = 'req-world-4242424242424242';++ it('blanks the provider error while the job is still running', async () => {+ status.mockResolvedValue({ status: 'running', error: 'NVIDIA Cosmos poll returned 500' });+ const res = await dispatch(makeReq({ method: 'GET', url: `/api/cosmos?job=${JOB}` }));++ expect(res.status).toBe(200);+ expect(res.body.status).toBe('running');+ expect(res.body.error).toBeNull();+ });++ it('replaces a failure detail with copy the page can render', async () => {+ status.mockResolvedValue({ status: 'failed', error: 'failed to persist video: bucket unreachable' });+ const res = await dispatch(makeReq({ method: 'GET', url: `/api/cosmos?job=${JOB}` }));++ expect(res.body.status).toBe('failed');+ expect(res.body.error).toMatch(/could not finish this world/i);+ expect(res.body.error).not.toContain('bucket');+ });++ it('returns the durable clip URL on completion', async () => {+ status.mockResolvedValue({ status: 'done', resultVideoUrl: 'https://cdn.three.ws/forge/cosmos/a.mp4' });+ const res = await dispatch(makeReq({ method: 'GET', url: `/api/cosmos?job=${JOB}` }));++ expect(res.body.status).toBe('done');+ expect(res.body.video_url).toBe('https://cdn.three.ws/forge/cosmos/a.mp4');+ expect(res.body.error).toBeNull();+ });++ it('rejects a malformed job id without calling the provider', async () => {+ const res = await dispatch(makeReq({ method: 'GET', url: '/api/cosmos?job=nope' }));+ expect(res.status).toBe(400);+ expect(status).not.toHaveBeenCalled();+ });+});