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.

test(portal): cover the build endpoint end to end

nirholas65a324aea677
diff --git a/tests/portal-endpoint.test.js b/tests/portal-endpoint.test.js
new file mode 100644
index 000000000..4af31bb5b
--- /dev/null
+++ b/tests/portal-endpoint.test.js
@@ -0,0 +1,165 @@
+// The endpoint's own contract: what it answers, what it refuses, and what it
+// hands to the GLB exporter. The network and the cache are mocked at the module
+// boundary (no site is fetched here); the layout, the exporter and the error
+// mapping are the real implementations.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';
+
+const limiterOk = { success: true, reset: Date.now() + 60_000, limit: 10, remaining: 9 };
+const limiterHit = { success: false, reset: Date.now() + 60_000, limit: 10, remaining: 0 };
+const limits = {
+ portalBuildIp: vi.fn(async () => limiterOk),
+ portalBuildGlobal: vi.fn(async () => limiterOk),
+ portalExportIp: vi.fn(async () => limiterOk),
+};
+vi.mock('../api/_lib/rate-limit.js', () => ({
+ limits,
+ clientIp: () => '203.0.113.7',
+}));
+
+// A cache that always misses, so every test exercises the real build path.
+vi.mock('../api/_lib/cache.js', () => ({
+ cacheWrapLastGood: async (_key, _ttl, load) => ({ value: await load(), stale: false }),
+}));
+
+const fetchState = { outline: null, error: null };
+vi.mock('../api/_lib/portal/fetch-site.js', async (importOriginal) => {
+ const mod = await importOriginal();
+ return {
+ ...mod,
+ outlineForUrl: vi.fn(async () => {
+ if (fetchState.error) throw fetchState.error;
+ return fetchState.outline;
+ }),
+ };
+});
+
+const { PortalFetchError } = await import('../api/_lib/portal/fetch-site.js');
+const handler = (await import('../api/portal.js')).default;
+
+function makeRes() {
+ const res = {
+ statusCode: 200,
+ headers: {},
+ body: null,
+ setHeader(k, v) {
+ this.headers[k.toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return this.headers[k.toLowerCase()];
+ },
+ end(payload) {
+ this.body = payload;
+ this.ended = true;
+ return this;
+ },
+ };
+ return res;
+}
+
+const call = async (url) => {
+ const req = { method: 'GET', url, headers: { host: 'three.ws' } };
+ const res = makeRes();
+ await handler(req, res);
+ return res;
+};
+
+const json = (res) => JSON.parse(String(res.body));
+
+const OUTLINE = {
+ version: 1,
+ url: 'https://site.test/',
+ canonical: 'https://site.test/',
+ host: 'site.test',
+ title: 'Site',
+ description: 'desc',
+ siteName: null,
+ themeColor: '#3366ff',
+ image: null,
+ icon: null,
+ lang: 'en',
+ words: 90,
+ linkCounts: { internal: 1, external: 0 },
+ sections: [
+ { id: 'intro', level: 1, heading: 'Intro', summary: 'hello', words: 90, paragraphs: 3, codeBlocks: 1, links: [{ href: 'https://site.test/a', text: 'a', internal: true }], images: [] },
+ ],
+};
+
+beforeEach(() => {
+ fetchState.outline = OUTLINE;
+ fetchState.error = null;
+ limits.portalBuildIp.mockResolvedValue(limiterOk);
+ limits.portalBuildGlobal.mockResolvedValue(limiterOk);
+ limits.portalExportIp.mockResolvedValue(limiterOk);
+});
+
+describe('GET /api/portal', () => {
+ it('returns the outline and the world it built', async () => {
+ const res = await call('/api/portal?url=site.test');
+ expect(res.statusCode).toBe(200);
+ const body = json(res);
+ expect(body.ok).toBe(true);
+ expect(body.world.meta.host).toBe('site.test');
+ expect(body.world.buildings).toHaveLength(1);
+ expect(body.outline.title).toBe('Site');
+ expect(body.user_agent).toContain('ThreeWSPortalBot');
+ });
+
+ it('honours include=world and include=outline', async () => {
+ expect(json(await call('/api/portal?url=site.test&include=world')).outline).toBeUndefined();
+ expect(json(await call('/api/portal?url=site.test&include=outline')).world).toBeUndefined();
+ });
+
+ it('rejects an address that is not a web address', async () => {
+ const res = await call('/api/portal?url=' + encodeURIComponent('ftp://files.test/x'));
+ expect(res.statusCode).toBe(400);
+ expect(json(res).error).toBe('invalid_url');
+ });
+
+ it('asks for a url when none is given', async () => {
+ expect((await call('/api/portal')).statusCode).toBe(400);
+ });
+
+ it('passes a fetch failure through with its own code and status', async () => {
+ fetchState.error = new PortalFetchError('robots_disallowed', 'site.test asks crawlers not to read this page.', 403);
+ const res = await call('/api/portal?url=site.test');
+ expect(res.statusCode).toBe(403);
+ expect(json(res).error).toBe('robots_disallowed');
+ });
+
+ it('rate limits a new build per address, with a retry hint', async () => {
+ limits.portalBuildIp.mockResolvedValue(limiterHit);
+ const res = await call('/api/portal?url=site.test');
+ expect(res.statusCode).toBe(429);
+ expect(json(res).error).toBe('rate_limited');
+ expect(Number(res.getHeader('retry-after'))).toBeGreaterThan(0);
+ });
+
+ it('brakes fleet-wide when the global bucket is spent', async () => {
+ limits.portalBuildGlobal.mockResolvedValue(limiterHit);
+ expect((await call('/api/portal?url=site.test')).statusCode).toBe(429);
+ });
+
+ it('exports a real GLB, named after the site', async () => {
+ const res = await call('/api/portal?url=site.test&format=glb');
+ expect(res.statusCode).toBe(200);
+ expect(res.getHeader('content-type')).toBe('model/gltf-binary');
+ expect(res.getHeader('content-disposition')).toContain('portal-site.test.glb');
+ expect(Buffer.from(res.body).subarray(0, 4).toString()).toBe('glTF');
+ });
+
+ it('rate limits the export separately from the build', async () => {
+ limits.portalExportIp.mockResolvedValue(limiterHit);
+ const res = await call('/api/portal?url=site.test&format=glb');
+ expect(res.statusCode).toBe(429);
+ });
+
+ it('answers a CORS preflight, since the SDK runs on other origins', async () => {
+ const req = { method: 'OPTIONS', url: '/api/portal?url=site.test', headers: { origin: 'https://elsewhere.test' } };
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBeLessThan(300);
+ expect(res.getHeader('access-control-allow-origin')).toBeTruthy();
+ });
+});