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
// Unit tests for /api/ibm/vision — IBM Granite Vision multimodal endpoint.
//
// Covers every path without any real network calls:
// GET — subject list (DB rows, empty DB, DB error, method guard)
// POST — watsonx unconfigured, input validation, SSRF allowlist, server-side
// image fetch, all three subject types, hint wiring, structured result,
// raw-prose fallback, Granite errors, and usage pass-through.
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { Readable } from 'node:stream';
// ── Shared mutable state threaded through all mock factories ──────────────────
const state = {
wxConfigured: false,
dbRows: [],
fetchOk: true,
fetchStatus: 200,
fetchContentType: 'image/jpeg',
fetchBody: Buffer.alloc(200), // tiny valid image
graniteText:
'{"appearance":"A sleek cobalt android.","vibe":"calm, precise","persona":"A reliable guide.","suggested_name":"Cobalt","bio":"Your co-pilot.","tone_tags":["calm","precise"],"voice":"warm and measured"}',
graniteThrows: false,
graniteThrowMsg: 'watsonx 404: not found',
};
// ── Mocks ──────────────────────────────────────────────────────────────────────
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
publicIp: vi.fn(async () => ({ success: true })),
watsonxEmbedGlobal: vi.fn(async () => ({ success: true })),
},
clientIp: vi.fn(() => '127.0.0.1'),
}));
vi.mock('../../api/_lib/db.js', () => ({
sql: vi.fn(async () => state.dbRows),
isDbUnavailableError: () => false,
isDbCapacityError: () => false,
}));
vi.mock('../../api/_lib/watsonx.js', () => ({
watsonxConfig: vi.fn(() =>
state.wxConfigured
? {
configured: true,
url: 'https://wx',
projectId: 'proj',
apiVersion: '2024-05-31',
chatModel: 'ibm/granite-3-8b-instruct',
embedModel: 'ibm/granite-embedding-278m-multilingual',
}
: { configured: false },
),
watsonxChatComplete: vi.fn(async () => {
if (state.graniteThrows) throw new Error(state.graniteThrowMsg);
return {
text: state.graniteText,
model: 'ibm/granite-vision-3-2-2b',
usage: { prompt_tokens: 120, completion_tokens: 80, total_tokens: 200 },
};
}),
}));
vi.mock('../../api/_lib/r2.js', () => ({
publicUrl: vi.fn((key) => `https://cdn.example.com/${key}`),
// thumbnailUrl mirrors r2.js: null for a missing key or the legacy *_og.png form.
thumbnailUrl: vi.fn((key) =>
!key || /^https?:\/\/.*_og\.png$/i.test(key) ? null : `https://cdn.example.com/${key}`,
),
}));
// Mock global fetch for server-side image fetching.
global.fetch = vi.fn(async () => {
if (!state.fetchOk) {
return {
ok: false,
status: state.fetchStatus,
headers: { get: () => null },
arrayBuffer: async () => new ArrayBuffer(0),
};
}
const body = state.fetchBody;
// A chunked response with no content-length, the shape a host uses to hide how
// much it is about to send. `streamChunks` yields those chunks so the handler's
// running byte cap is exercised on the stream rather than on a header.
if (state.streamChunks) {
const chunks = state.streamChunks;
return {
ok: true,
status: 200,
headers: {
get(h) {
if (h === 'content-type') return state.fetchContentType;
return null; // no content-length
},
},
body: (async function* () {
for (const c of chunks) yield c;
})(),
arrayBuffer: async () => Buffer.concat(chunks).buffer,
};
}
return {
ok: true,
status: 200,
headers: {
get(h) {
if (h === 'content-type') return state.fetchContentType;
if (h === 'content-length') return String(body.length);
return null;
},
},
arrayBuffer: async () =>
body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength),
};
});
// Import AFTER all mocks are set up.
const handler = (await import('../../api/ibm/vision.js')).default;
import { allowedImageHost, buildPrompt, parseVision, VISION_MODEL } from '../../api/ibm/vision.js';
// ── Test helpers ──────────────────────────────────────────────────────────────
const TINY_PNG =
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
// `rawBody` sends the exact bytes instead of JSON.stringify(body), so a test can
// post literal `null` or a bare string: valid JSON that is not an object.
function makeReq({ method = 'GET', url = '/api/ibm/vision', body = null, rawBody = null } = {}) {
const payload = rawBody ?? (body ? JSON.stringify(body) : null);
const base = payload ? Readable.from([Buffer.from(payload)]) : Readable.from([]);
base.method = method;
base.url = url;
base.headers = {
host: 'localhost',
'content-type': 'application/json',
origin: 'http://localhost:3000',
};
return base;
}
function makeRes() {
return {
statusCode: 200,
headers: {},
body: '',
writableEnded: false,
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
getHeader(k) {
return this.headers[k.toLowerCase()];
},
end(chunk) {
if (chunk !== undefined) this.body += chunk;
this.writableEnded = true;
},
};
}
async function invoke(reqOpts) {
const res = makeRes();
await handler(makeReq(reqOpts), res);
return {
status: res.statusCode,
body: res.body ? JSON.parse(res.body) : null,
headers: res.headers,
};
}
beforeEach(() => {
state.wxConfigured = false;
state.dbRows = [];
state.fetchOk = true;
state.fetchStatus = 200;
state.fetchContentType = 'image/jpeg';
state.fetchBody = Buffer.alloc(200);
state.streamChunks = null;
state.graniteText =
'{"appearance":"A sleek cobalt android.","vibe":"calm, precise","persona":"A reliable guide.","suggested_name":"Cobalt","bio":"Your co-pilot.","tone_tags":["calm","precise"],"voice":"warm and measured"}';
state.graniteThrows = false;
state.graniteThrowMsg = 'watsonx 502: upstream error';
});
// ── GET /api/ibm/vision ───────────────────────────────────────────────────────
describe('GET /api/ibm/vision — subjects', () => {
it('returns 200 with empty subjects and visionModel when DB has no rows', async () => {
const { status, body } = await invoke({ method: 'GET' });
expect(status).toBe(200);
expect(body.subjects).toEqual([]);
expect(typeof body.visionModel).toBe('string');
expect(body.visionModel).toContain('granite');
});
it('maps DB rows to subjects with cdn URLs', async () => {
state.dbRows = [
{
id: 'id-1',
slug: 'cobalt',
name: 'Cobalt',
storage_key: 'avatars/cobalt.glb',
thumbnail_key: 'thumbs/cobalt.jpg',
featured: true,
view_count: 42,
},
];
const { status, body } = await invoke({ method: 'GET' });
expect(status).toBe(200);
expect(body.subjects).toHaveLength(1);
const s = body.subjects[0];
expect(s.id).toBe('id-1');
expect(s.name).toBe('Cobalt');
expect(s.thumbnail).toContain('thumbs/cobalt.jpg');
expect(s.model_url).toContain('avatars/cobalt.glb');
expect(s.slug).toBe('cobalt');
});
it('returns empty subjects (not 500) when DB throws', async () => {
const { sql } = await import('../../api/_lib/db.js');
sql.mockRejectedValueOnce(new Error('DB unavailable'));
const { status, body } = await invoke({ method: 'GET' });
expect(status).toBe(200);
expect(body.subjects).toEqual([]);
// Same shape as the success path, so a client reading the model name off
// the degraded response does not get undefined.
expect(body.visionModel).toBe(VISION_MODEL);
});
it('returns 405 for unsupported methods', async () => {
const { status } = await invoke({ method: 'DELETE' });
expect(status).toBe(405);
});
});
// ── POST /api/ibm/vision — auth ────────────────────────────────────────────────
describe('POST /api/ibm/vision — watsonx gate', () => {
it('returns 503 watsonx_unavailable when watsonx is not configured', async () => {
state.wxConfigured = false;
const { status, body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(status).toBe(503);
expect(body.error).toBe('watsonx_unavailable');
expect(body.error_description).toMatch(/WATSONX_API_KEY/i);
});
});
// ── POST /api/ibm/vision — input validation ─────────────────────────────────────
describe('POST /api/ibm/vision — input validation', () => {
beforeEach(() => {
state.wxConfigured = true;
});
it('returns 400 bad_image when neither image nor imageUrl is provided', async () => {
const { status, body } = await invoke({ method: 'POST', body: { hint: 'hello' } });
expect(status).toBe(400);
expect(body.error).toBe('bad_image');
});
// `null` and `"hi"` parse as valid JSON, so readJson hands them straight back
// on the raw-stream path. Reading .image off a non-object used to throw a
// TypeError that wrap() sanitized into a 500 internal_error; malformed input
// belongs in the documented 400 contract.
it.each([
['null', 'null'],
['a bare string', '"hi"'],
['a number', '42'],
])('returns 400 bad_image for a JSON body that is %s', async (_label, rawBody) => {
const { status, body } = await invoke({ method: 'POST', rawBody });
expect(status).toBe(400);
expect(body.error).toBe('bad_image');
});
it('returns 400 bad_image when image data URL has empty data portion', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { image: 'data:image/png;base64,' },
});
expect(status).toBe(400);
expect(body.error).toBe('bad_image');
});
it('returns 413 image_too_large when data URL exceeds 6 MB', async () => {
// 6MB / 0.75 ≈ 8MB of base64
const big = 'data:image/png;base64,' + 'A'.repeat(8_500_000);
const { status, body } = await invoke({ method: 'POST', body: { image: big } });
expect(status).toBe(413);
expect(body.error).toBe('image_too_large');
});
it('returns 400 bad_image when imageUrl uses http (not https)', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'http://pub-abc.r2.dev/img.jpg' },
});
expect(status).toBe(400);
expect(body.error).toBe('bad_image');
});
it('returns 400 image_host_not_allowed for an arbitrary external host', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://evil.example.com/img.jpg' },
});
expect(status).toBe(400);
expect(body.error).toBe('image_host_not_allowed');
});
it('returns 400 image_host_not_allowed for internal metadata endpoint (SSRF)', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://169.254.169.254/latest/meta-data/' },
});
expect(status).toBe(400);
expect(body.error).toBe('image_host_not_allowed');
});
});
// ── POST /api/ibm/vision — server-side image fetch ───────────────────────────────
describe('POST /api/ibm/vision — server-side image fetch', () => {
beforeEach(() => {
state.wxConfigured = true;
});
it('fetches an allowlisted imageUrl and sends it to Granite', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/avatar.jpg', subject: 'avatar' },
});
expect(status).toBe(200);
expect(global.fetch).toHaveBeenCalledWith(
expect.stringContaining('pub-test.r2.dev'),
expect.objectContaining({ signal: expect.any(AbortSignal) }),
);
expect(body.vision.suggested_name).toBe('Cobalt');
});
it('returns 502 image_fetch_failed when upstream fetch fails', async () => {
state.fetchOk = false;
state.fetchStatus = 503;
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/avatar.jpg' },
});
expect(status).toBe(502);
expect(body.error).toBe('image_fetch_failed');
});
it('returns 415 not_an_image when fetched URL is not an image', async () => {
state.fetchContentType = 'text/html';
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/page.html' },
});
expect(status).toBe(415);
expect(body.error).toBe('not_an_image');
});
// Several allowlisted hosts serve user-supplied content. A content-length
// header is a hint such a host can simply omit, so the 6MB ceiling has to hold
// on the stream: buffering first and measuring afterwards means the oversized
// body is already resident in memory by the time it is rejected.
it('returns 413 image_too_large for an oversized body with no content-length', async () => {
const chunk = Buffer.alloc(1024 * 1024); // 1MB per chunk
state.streamChunks = Array.from({ length: 8 }, () => chunk); // 8MB total
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/huge.jpg' },
});
expect(status).toBe(413);
expect(body.error).toBe('image_too_large');
});
it('stops reading an oversized body instead of draining it', async () => {
const chunk = Buffer.alloc(1024 * 1024);
let pulled = 0;
state.streamChunks = {
[Symbol.iterator]: function* () {
for (let i = 0; i < 64; i++) {
pulled++;
yield chunk;
}
},
};
const { status } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/endless.jpg' },
});
expect(status).toBe(413);
// 6MB cap: the read stops on the chunk that crosses it, not 64MB later.
expect(pulled).toBeLessThanOrEqual(7);
});
it('accepts a streamed body that stays under the cap', async () => {
state.streamChunks = [Buffer.alloc(1024), Buffer.alloc(2048)];
const { status, body } = await invoke({
method: 'POST',
body: { imageUrl: 'https://pub-test.r2.dev/small.jpg' },
});
expect(status).toBe(200);
expect(body.vision.suggested_name).toBe('Cobalt');
});
});
// ── POST /api/ibm/vision — Granite Vision call ────────────────────────────────
describe('POST /api/ibm/vision — Granite Vision result', () => {
beforeEach(() => {
state.wxConfigured = true;
});
it('returns a structured identity when Granite returns valid JSON', async () => {
const { status, body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(status).toBe(200);
expect(body.vision.structured).toBe(true);
expect(body.vision.suggested_name).toBe('Cobalt');
expect(body.vision.bio).toBe('Your co-pilot.');
expect(body.vision.tone_tags).toEqual(['calm', 'precise']);
expect(body.vision.voice).toBe('warm and measured');
});
it('includes the model name in the response', async () => {
const { body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(body.model).toBe('ibm/granite-vision-3-2-2b');
});
it('passes usage through to the response', async () => {
const { body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(body.usage).toMatchObject({
prompt_tokens: 120,
completion_tokens: 80,
total_tokens: 200,
});
});
it('does not include "raw" when result is structured', async () => {
const { body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(body.raw).toBeUndefined();
});
it('returns raw fallback (structured:false) when Granite returns prose', async () => {
state.graniteText =
'This avatar appears to be a futuristic character with a calm demeanor.';
const { status, body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(status).toBe(200);
expect(body.vision.structured).toBe(false);
expect(body.raw).toMatch(/futuristic character/);
});
it('recovers JSON from a code-fenced response', async () => {
state.graniteText =
'```json\n{"appearance":"A bot.","vibe":"calm","persona":"Helpful.","suggested_name":"Bot","bio":"Here to help.","tone_tags":["calm"],"voice":"steady"}\n```';
const { body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(body.vision.structured).toBe(true);
expect(body.vision.suggested_name).toBe('Bot');
});
it('uses the avatar prompt by default (subject omitted)', async () => {
const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
await invoke({ method: 'POST', body: { image: TINY_PNG } });
const calls = watsonxChatComplete.mock.calls;
const lastCall = calls[calls.length - 1];
const messages = lastCall[1].messages;
expect(messages[0].content).toMatch(/casting director/i);
});
it('uses the token prompt when subject is "token"', async () => {
const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
await invoke({ method: 'POST', body: { image: TINY_PNG, subject: 'token' } });
const calls = watsonxChatComplete.mock.calls;
const lastCall = calls[calls.length - 1];
const messages = lastCall[1].messages;
expect(messages[0].content).toMatch(/brand analyst/i);
});
it('uses the generic image prompt when subject is "image"', async () => {
const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
await invoke({ method: 'POST', body: { image: TINY_PNG, subject: 'image' } });
const calls = watsonxChatComplete.mock.calls;
const lastCall = calls[calls.length - 1];
const messages = lastCall[1].messages;
expect(messages[0].content).toMatch(/art director/i);
});
it('defaults unknown subject to avatar', async () => {
const { status, body } = await invoke({
method: 'POST',
body: { image: TINY_PNG, subject: 'spacecraft' },
});
expect(status).toBe(200);
expect(body.subject).toBe('avatar');
});
it('weaves the hint into the user message', async () => {
const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
await invoke({ method: 'POST', body: { image: TINY_PNG, hint: 'a rogue detective' } });
const calls = watsonxChatComplete.mock.calls;
const lastCall = calls[calls.length - 1];
const userContent = lastCall[1].messages[1].content;
const textBlock = userContent.find((b) => b.type === 'text');
expect(textBlock.text).toContain('a rogue detective');
});
it('embeds the image as a data URL in the image_url block', async () => {
const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
await invoke({ method: 'POST', body: { image: TINY_PNG } });
const calls = watsonxChatComplete.mock.calls;
const lastCall = calls[calls.length - 1];
const userContent = lastCall[1].messages[1].content;
const imgBlock = userContent.find((b) => b.type === 'image_url');
expect(imgBlock.image_url.url).toMatch(/^data:image\//);
});
it('returns 502 vision_failed when Granite throws', async () => {
state.graniteThrows = true;
state.graniteThrowMsg = 'watsonx 502: quota exceeded';
const { status, body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(status).toBe(502);
expect(body.error).toBe('vision_failed');
});
it('returns 502 model_unavailable when Granite reports model not found', async () => {
state.graniteThrows = true;
state.graniteThrowMsg = 'watsonx 404: model not found in this region';
const { status, body } = await invoke({ method: 'POST', body: { image: TINY_PNG } });
expect(status).toBe(502);
expect(body.error).toBe('model_unavailable');
});
});
// ── Unit: parseVision ─────────────────────────────────────────────────────────
describe('parseVision — identity parser', () => {
it('parses a clean JSON blob', () => {
const v = parseVision(
'{"appearance":"Blue bot.","vibe":"calm","persona":"A guide.","suggested_name":"Bot","bio":"Here for you.","tone_tags":["calm","helpful"],"voice":"warm"}',
);
expect(v.structured).toBe(true);
expect(v.suggested_name).toBe('Bot');
expect(v.tone_tags).toEqual(['calm', 'helpful']);
});
it('strips leading and trailing prose around the JSON', () => {
const v = parseVision(
'Sure, here it is: {"suggested_name":"Echo","bio":"test","appearance":"","vibe":"","persona":"","tone_tags":[],"voice":""} Hope that helps!',
);
expect(v.structured).toBe(true);
expect(v.suggested_name).toBe('Echo');
});
it('splits a comma-joined string into tone_tags array', () => {
const v = parseVision(
'{"appearance":"x","vibe":"x","persona":"x","suggested_name":"x","bio":"x","tone_tags":"calm, curious, witty","voice":"x"}',
);
expect(v.tone_tags).toEqual(['calm', 'curious', 'witty']);
});
it('clamps fields to their max lengths', () => {
const v = parseVision(
`{"appearance":"x","vibe":"x","persona":"x","suggested_name":"${'A'.repeat(100)}","bio":"${'B'.repeat(300)}","tone_tags":[],"voice":"${'C'.repeat(200)}"}`,
);
expect(v.suggested_name.length).toBeLessThanOrEqual(60);
expect(v.bio.length).toBeLessThanOrEqual(200);
expect(v.voice.length).toBeLessThanOrEqual(120);
});
it('returns structured:false for empty input', () => {
expect(parseVision('').structured).toBe(false);
expect(parseVision(null).structured).toBe(false);
expect(parseVision('no json here').structured).toBe(false);
});
it('returns structured:false for invalid JSON', () => {
expect(parseVision('{broken json}').structured).toBe(false);
});
});
// ── Unit: allowedImageHost ─────────────────────────────────────────────────────
describe('allowedImageHost — SSRF allowlist', () => {
const allow = [
'pub-abc.r2.dev',
'three.ws',
'ipfs.io',
'arweave.net',
'pump.mypinata.cloud',
'bafyb.ipfs.dweb.link',
'user.githubusercontent.com',
];
const deny = [
'localhost',
'127.0.0.1',
'169.254.169.254',
'evil.com',
'10.0.0.1',
'metadata.google.internal',
];
for (const h of allow) it(`allows ${h}`, () => expect(allowedImageHost(h)).toBe(true));
for (const h of deny) it(`rejects ${h}`, () => expect(allowedImageHost(h)).toBe(false));
});
// ── Unit: buildPrompt ─────────────────────────────────────────────────────────
describe('buildPrompt — prompt builder', () => {
it('returns a casting-director system prompt for avatar subject', () => {
const { system } = buildPrompt('avatar', '');
expect(system).toMatch(/casting director/i);
});
it('returns a brand-analyst system prompt for token subject', () => {
const { system } = buildPrompt('token', '');
expect(system).toMatch(/brand analyst/i);
});
it('returns an art-director system prompt for image subject', () => {
const { system } = buildPrompt('image', '');
expect(system).toMatch(/art director/i);
});
it('injects the hint into the user message', () => {
const { user } = buildPrompt('avatar', 'a grumpy wizard');
expect(user).toContain('a grumpy wizard');
});
it('omits the hint line when hint is empty', () => {
const { user } = buildPrompt('avatar', '');
expect(user).not.toContain('adds:');
});
});
// ── Unit: VISION_MODEL ────────────────────────────────────────────────────────
describe('VISION_MODEL', () => {
it('defaults to the Granite Vision 3.2 model', () => {
expect(VISION_MODEL).toMatch(/granite-vision/);
});
});