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
// api/spotlight/[action]: Agent Spotlight, the community showcase.
//
// GET /api/spotlight/list?sort=trending|new|top&category=&tag=&q=&limit=&offset=&featured=1
// GET /api/spotlight/get?id=<uuid>
// GET /api/spotlight/categories (per-category counts + headline totals)
// GET /api/spotlight/eligible (auth: the caller's showcasable agents)
// POST /api/spotlight/submit { agentId, title, tagline, story?, demoUrl?, category, tags[] }
// POST /api/spotlight/vote { id } (toggle)
// POST /api/spotlight/remove { id } (submitter or agent owner)
// GET /api/spotlight/stories (consented entries with a verified result, by category)
// POST /api/spotlight/consent { id, consent } (agent owner: feature as a story, or withdraw)
// POST /api/spotlight/moderate { id, action: 'hide'|'unhide', reason? } (admin)
//
// Reads are public and CDN-cached; writes need a session plus CSRF. The ranking
// and every query live in api/_lib/spotlight-store.js; this file is the HTTP
// boundary and nothing else.
import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';
import { requireCsrf } from '../_lib/csrf.js';
import { getSessionUser } from '../_lib/auth.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { isUuid } from '../_lib/validate.js';
import { requireAdmin } from '../_lib/admin.js';
import { logAudit } from '../_lib/audit.js';
import { verifiedMetrics, shapeVerified } from '../_lib/spotlight-metrics.js';
import {
CATEGORIES,
SORTS,
agentIsPublic,
bumpViews,
categoryCounts,
countEntries,
eligibleAgents,
entryExists,
getEntry,
isCategory,
listEntries,
listStoryEntries,
ownsAgent,
setEntryVisibility,
setStoryConsent,
showcaseConfigured,
showcaseTotals,
softDeleteEntry,
toggleVote,
upsertEntry,
} from '../_lib/spotlight-store.js';
const MAX_LIMIT = 48;
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
if (!showcaseConfigured()) {
return error(res, 503, 'not_configured', 'the showcase needs a database; none is configured here');
}
switch (actionOf(req)) {
case 'list':
return await handleList(req, res);
case 'get':
return await handleGet(req, res);
case 'categories':
return await handleCategories(req, res);
case 'eligible':
return await handleEligible(req, res);
case 'submit':
return await handleSubmit(req, res);
case 'vote':
return await handleVote(req, res);
case 'remove':
return await handleRemove(req, res);
case 'stories':
return await handleStories(req, res);
case 'consent':
return await handleConsent(req, res);
case 'moderate':
return await handleModerate(req, res);
default:
return error(res, 404, 'not_found', `unknown spotlight action "${actionOf(req)}"`);
}
});
function actionOf(req) {
const fromQuery = req.query?.action;
if (fromQuery && fromQuery !== '[action]') return String(fromQuery).toLowerCase();
return (new URL(req.url, 'http://x').pathname.split('/').pop() || '').toLowerCase();
}
function queryOf(req) {
return new URL(req.url, 'http://x').searchParams;
}
// A viewer is optional on every read: signed in, their own votes come back
// marked; signed out, the page still renders in full. A broken session cookie
// must therefore never turn a public read into a 401.
async function viewer(req) {
try {
const user = await getSessionUser(req);
return user?.id || null;
} catch {
return null;
}
}
/* ── reads ────────────────────────────────────────────────────────────────── */
async function handleList(req, res) {
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const p = queryOf(req);
const sort = SORTS.has(p.get('sort')) ? p.get('sort') : 'trending';
const rawCategory = (p.get('category') || '').toLowerCase();
const category = isCategory(rawCategory) ? rawCategory : null;
const tag = (p.get('tag') || '').trim().toLowerCase().slice(0, 40) || null;
const q = (p.get('q') || '').trim().slice(0, 100) || null;
const limit = Math.min(MAX_LIMIT, Math.max(1, Number(p.get('limit') || 24) | 0));
const offset = Math.max(0, Math.min(5000, Number(p.get('offset') || 0) | 0));
const featuredOnly = p.get('featured') === '1';
const viewerId = await viewer(req);
const [entries, total] = await Promise.all([
listEntries({ sort, category, tag, q, limit, offset, viewerId, featuredOnly }),
countEntries({ category, tag, q }),
]);
// A signed-in read is personalised (voted_by_me), so it must never land in a
// shared cache. Anonymous reads are identical for everyone and cache freely.
const cache = viewerId
? { 'Cache-Control': 'private, no-store' }
: { 'Cache-Control': 'public, max-age=30, stale-while-revalidate=120' };
return json(
res,
200,
{
entries,
count: entries.length,
total,
has_more: offset + entries.length < total,
next_offset: offset + entries.length < total ? offset + entries.length : null,
sort,
category,
generated_at: new Date().toISOString(),
},
cache,
);
}
async function handleGet(req, res) {
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const id = queryOf(req).get('id') || '';
if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
const viewerId = await viewer(req);
const entry = await getEntry(id, { viewerId });
if (!entry) return error(res, 404, 'not_found', 'no such showcase entry');
void bumpViews(id);
entry.verified = await entryVerified(entry.agent.id);
return json(res, 200, { entry }, { 'Cache-Control': 'private, no-store' });
}
// Verified results for one entry's agent. A failure here degrades to null (the
// page shows "results unavailable") rather than failing the whole entry: the
// write-up is still worth reading while a metrics table is unreachable.
async function entryVerified(agentId) {
try {
const metrics = await verifiedMetrics([agentId]);
return shapeVerified(metrics.get(agentId));
} catch (err) {
console.error('[spotlight] verified metrics failed:', err?.message || err);
return null;
}
}
async function handleStories(req, res) {
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const candidates = await listStoryEntries({ limit: 60 });
const metrics = await verifiedMetrics(candidates.map((e) => e.agent.id));
const stories = [];
for (const e of candidates) {
const verified = shapeVerified(metrics.get(e.agent.id));
// Consent alone is not enough: a story needs a result anyone can check.
if (!verified.qualifies) continue;
stories.push({ ...e, verified });
}
const groups = CATEGORIES.map((c) => ({
...c,
entries: stories.filter((s) => s.category === c.slug),
})).filter((g) => g.entries.length);
return json(
res,
200,
{
groups,
total: stories.length,
consented: candidates.length,
method:
'Only entries whose agent owner opted in appear here, and only when the agent has a verified result: a coin launched (pump_agent_mints), service income (agent_revenue_events and completed agent_hires, USDC at 1:1), or creator fees (the agent earnings read model). Every figure is computed server-side from those tables; none is typed by the builder.',
generated_at: new Date().toISOString(),
},
{ 'Cache-Control': 'public, max-age=60, stale-while-revalidate=300' },
);
}
async function handleCategories(req, res) {
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [categories, totals] = await Promise.all([categoryCounts(), showcaseTotals()]);
return json(
res,
200,
{ categories, totals },
{ 'Cache-Control': 'public, max-age=60, stale-while-revalidate=300' },
);
}
async function handleEligible(req, res) {
if (!method(req, res, ['GET'])) return;
const user = await sessionOr401(req, res, 'sign in to see which of your agents you can showcase');
if (!user) return;
const rl = await limits.authedReadIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const agents = await eligibleAgents(user.id);
return json(res, 200, { agents, categories: CATEGORIES }, { 'Cache-Control': 'private, no-store' });
}
/* ── writes ───────────────────────────────────────────────────────────────── */
async function handleSubmit(req, res) {
if (!method(req, res, ['POST'])) return;
const user = await sessionOr401(req, res, 'sign in to submit an agent to the showcase');
if (!user) return;
if (!(await requireCsrf(req, res, user.id))) return;
const rl = await limits.showcaseWrite(user.id);
if (!rl.success) return rateLimited(res, rl, 'too many showcase submissions; slow down');
const body = await readJson(req, 32_000);
const agentId = String(body?.agentId || '').trim();
if (!isUuid(agentId)) return error(res, 400, 'bad_request', 'agentId must be a uuid');
if (!(await ownsAgent(agentId, user.id))) {
return error(res, 403, 'forbidden', 'you can only showcase an agent you own');
}
if ((await agentIsPublic(agentId)) !== true) {
return error(
res,
409,
'agent_not_public',
'make the agent public before showcasing it: the showcase only lists agents visitors can open',
);
}
const title = trimmed(body?.title);
const tagline = trimmed(body?.tagline);
const story = trimmed(body?.story) || null;
const category = String(body?.category || '').toLowerCase();
const demoUrl = normalizeDemoUrl(body?.demoUrl);
if (demoUrl === false) {
return error(res, 400, 'bad_request', 'demoUrl must be an http(s) link');
}
if (!title || title.length < 3 || title.length > 90) {
return error(res, 400, 'bad_request', 'title must be 3 to 90 characters');
}
if (!tagline || tagline.length < 10 || tagline.length > 160) {
return error(res, 400, 'bad_request', 'tagline must be 10 to 160 characters');
}
if (story && story.length > 4000) {
return error(res, 400, 'bad_request', 'story must be 4000 characters or fewer');
}
if (!isCategory(category)) {
return error(res, 400, 'bad_request', `category must be one of: ${CATEGORIES.map((c) => c.slug).join(', ')}`);
}
const tags = normalizeTags(body?.tags);
if (tags === false) return error(res, 400, 'bad_request', 'tags must be up to 6 short labels');
// Off unless the owner explicitly ticked it: only a literal true consents.
const featureStory = body?.featureStory === true;
const id = await upsertEntry({
agentId,
userId: user.id,
title,
tagline,
story,
demoUrl: demoUrl || null,
category,
tags,
featureStory,
});
if (!id) return error(res, 500, 'write_failed', 'the entry could not be saved');
const entry = await getEntry(id, { viewerId: user.id });
return json(res, 200, { entry }, { 'Cache-Control': 'private, no-store' });
}
async function handleVote(req, res) {
if (!method(req, res, ['POST'])) return;
const user = await sessionOr401(req, res, 'sign in to upvote an agent');
if (!user) return;
if (!(await requireCsrf(req, res, user.id))) return;
const rl = await limits.showcaseVote(user.id);
if (!rl.success) return rateLimited(res, rl, 'too many votes; slow down');
const body = await readJson(req, 2_000);
const id = String(body?.id || '').trim();
if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
if (!(await entryExists(id))) return error(res, 404, 'not_found', 'no such showcase entry');
const result = await toggleVote(id, user.id);
return json(res, 200, result, { 'Cache-Control': 'private, no-store' });
}
async function handleRemove(req, res) {
if (!method(req, res, ['POST'])) return;
const user = await sessionOr401(req, res, 'sign in to remove a showcase entry');
if (!user) return;
if (!(await requireCsrf(req, res, user.id))) return;
const body = await readJson(req, 2_000);
const id = String(body?.id || '').trim();
if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
const removed = await softDeleteEntry(id, user.id);
if (!removed) {
return error(res, 403, 'forbidden', 'only the submitter or the agent owner can remove an entry');
}
return json(res, 200, { removed: true }, { 'Cache-Control': 'private, no-store' });
}
async function handleConsent(req, res) {
if (!method(req, res, ['POST'])) return;
const user = await sessionOr401(req, res, 'sign in to feature your agent as a story');
if (!user) return;
if (!(await requireCsrf(req, res, user.id))) return;
const rl = await limits.showcaseWrite(user.id);
if (!rl.success) return rateLimited(res, rl, 'too many showcase changes; slow down');
const body = await readJson(req, 2_000);
const id = String(body?.id || '').trim();
if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
if (typeof body?.consent !== 'boolean') return error(res, 400, 'bad_request', 'consent must be true or false');
const result = await setStoryConsent(id, user.id, body.consent);
if (!result) {
return error(res, 403, 'forbidden', 'only the owner of the agent can feature it as a story');
}
logAudit({
userId: user.id,
action: body.consent ? 'spotlight_story_consent' : 'spotlight_story_withdraw',
resourceId: id,
req,
});
return json(res, 200, result, { 'Cache-Control': 'private, no-store' });
}
async function handleModerate(req, res) {
if (!method(req, res, ['POST'])) return;
const admin = await requireAdmin(req, res);
if (!admin) return;
if (!(await requireCsrf(req, res, admin.id))) return;
const body = await readJson(req, 4_000);
const id = String(body?.id || '').trim();
if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
const action = String(body?.action || '');
if (action !== 'hide' && action !== 'unhide') {
return error(res, 400, 'bad_request', "action must be 'hide' or 'unhide'");
}
const reason = trimmed(body?.reason) || null;
if (reason && reason.length > 280) return error(res, 400, 'bad_request', 'reason must be 280 characters or fewer');
const row = await setEntryVisibility(id, { hidden: action === 'hide', adminId: admin.id, reason });
if (!row) return error(res, 404, 'not_found', 'no such showcase entry');
logAudit({
userId: admin.id,
action: action === 'hide' ? 'spotlight_hide' : 'spotlight_unhide',
resourceId: id,
meta: reason ? { reason } : null,
req,
});
return json(
res,
200,
{ id: row.id, status: row.status, hidden_at: row.hidden_at, hidden_reason: row.hidden_reason },
{ 'Cache-Control': 'private, no-store' },
);
}
/* ── input helpers ────────────────────────────────────────────────────────── */
async function sessionOr401(req, res, message) {
let user = null;
try {
user = await getSessionUser(req);
} catch {
user = null;
}
if (!user) {
error(res, 401, 'unauthorized', message);
return null;
}
return user;
}
function trimmed(v) {
return typeof v === 'string' ? v.trim() : '';
}
// Returns a normalized URL string, '' for "not supplied", or false for invalid.
// Only http(s) is accepted: the value is rendered as a link on a public page, so
// javascript:, data: and friends have to be rejected at the boundary, not
// escaped at the sink.
function normalizeDemoUrl(raw) {
const value = trimmed(raw);
if (!value) return '';
if (value.length > 500) return false;
let url;
try {
url = new URL(value);
} catch {
return false;
}
if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
return url.toString();
}
// Up to 6 lowercase, hyphenatable labels. Returns false on anything that cannot
// be coerced into that shape rather than silently dropping the caller's input.
function normalizeTags(raw) {
if (raw == null) return [];
if (!Array.isArray(raw)) return false;
if (raw.length > 6) return false;
const out = [];
for (const t of raw) {
if (typeof t !== 'string') return false;
const tag = t.trim().toLowerCase().replace(/\s+/g, '-');
if (!tag) continue;
if (tag.length > 24 || !/^[a-z0-9][a-z0-9-]*$/.test(tag)) return false;
if (!out.includes(tag)) out.push(tag);
}
return out;
}