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
// GET /api/users/me/feed — the platform activity feed: reverse-chronological
// creation events (avatars, agents, coin launches, forged 3D models, saved
// worlds, Material Studio restyles) plus follow activity, merged from the
// same public records every profile page already exposes (no separate event
// log to keep in sync).
//
// ?scope=following (default) — only accounts the signed-in viewer follows.
// Requires a session; anonymous callers get 401
// so the client can route to sign-in.
// ?scope=all — platform-wide recent activity. No session
// required — this is what /community and a
// first-time visitor's feed use.
// ?limit=… (1..50, default 30)
// ?before=<iso timestamp> — cursor for the next page (pass the last
// item's created_at back for infinite scroll).
// A value that is not a parseable timestamp is
// rejected with 400 validation_error.
//
// Every item: { kind, id, created_at, actor{username,display_name,avatar_url},
// title, subtitle?, href, image?, external?, isRemix?, isVariant? }
// and, for kind:'follow' only, a `target` shaped like `actor`. `isRemix` is
// kind:'model' only (a forge derived from another creation), `isVariant` is
// kind:'restyle' only (a seeded colorway fan-out rather than an instructed
// restyle); both exist so a client picks its verb from a flag, not from prose.
// `actor.username` is null for an anonymous creation (forge_creations, dioramas,
// or material_restyles made while signed out). The client renders those without
// a profile link rather than inventing one.
//
// Kinds emitted: avatar | agent | coin | model | world | restyle | follow. All
// seven honour the `before` cursor and the scope filter; the restyle and follow
// queries are additionally fail-soft (`.catch(() => [])`) so a deployment whose
// material_restyles / user_follows migration has not landed still serves a feed.
import { sql } from '../../_lib/db.js';
import { cors, json, method, wrap, error, rateLimited } from '../../_lib/http.js';
import { getSessionUser } from '../../_lib/auth.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { publicUrl, thumbnailUrl } from '../../_lib/r2.js';
import { listRecentCreations } from '../../_lib/forge-store.js';
import { listDioramas } from '../../_lib/diorama-store.js';
import { listRecentRestyles } from '../../_lib/material-restyle-store.js';
const SITE = 'https://three.ws';
function actorFrom(r, { username = 'username', displayName = 'display_name', avatar = 'avatar_url' } = {}) {
const u = r[username];
if (!u) return { username: null, display_name: 'A three.ws creator', avatar_url: null };
const a = r[avatar];
return {
username: u,
display_name: r[displayName] || u,
avatar_url: a ? (a.startsWith('http') ? a : publicUrl(a)) : null,
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const url = new URL(req.url, 'http://x');
const scope = url.searchParams.get('scope') === 'all' ? 'all' : 'following';
const limit = Math.min(50, Math.max(1, parseInt(url.searchParams.get('limit'), 10) || 30));
const perKind = limit;
const followPerKind = Math.max(3, Math.ceil(limit / 4));
const rl = await limits.authedReadIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// The cursor is compared against `created_at` inside every kind's query, so a
// value Postgres cannot cast to a timestamptz aborts the whole fan-out and
// surfaces as a 500 on what is really a malformed request. Validate it here
// and hand the queries a normalized ISO string.
const beforeParam = (url.searchParams.get('before') || '').trim();
if (beforeParam && !Number.isFinite(Date.parse(beforeParam))) {
return error(res, 400, 'validation_error', 'before must be an ISO 8601 timestamp');
}
const before = beforeParam ? new Date(beforeParam).toISOString() : undefined;
const viewer = await getSessionUser(req).catch(() => null);
if (scope === 'following' && !viewer) {
return error(res, 401, 'unauthorized', 'sign in to view your feed');
}
if (scope === 'following') {
const [{ following_count }] = await sql`
select count(*)::int as following_count from user_follows where follower_id = ${viewer.id}
`.catch(() => [{ following_count: 0 }]);
if (following_count === 0) {
return json(res, 200, { items: [], following_count: 0, scope, next: null });
}
const [avatarRows, agentRows, coinRows, modelRows, worldRows, restyleRaw, followRows] = await Promise.all([
sql`
select a.id, a.name, a.thumbnail_key, a.created_at,
u.username, u.display_name, u.avatar_url
from avatars a
join user_follows f on f.following_id = a.owner_id and f.follower_id = ${viewer.id}
join users u on u.id = a.owner_id and u.deleted_at is null and u.username is not null
where a.visibility = 'public' and a.deleted_at is null
${before ? sql`and a.created_at < ${before}` : sql``}
order by a.created_at desc
limit ${perKind}
`,
sql`
select a.id, a.name, a.description, a.profile_image_url, a.avatar_url, a.created_at,
u.username, u.display_name, u.avatar_url as actor_avatar
from agent_identities a
join user_follows f on f.following_id = a.user_id and f.follower_id = ${viewer.id}
join users u on u.id = a.user_id and u.deleted_at is null and u.username is not null
where a.is_public = true and a.deleted_at is null
${before ? sql`and a.created_at < ${before}` : sql``}
order by a.created_at desc
limit ${perKind}
`,
sql`
select a.id as agent_id, a.name as agent_name, a.profile_image_url, a.avatar_url,
a.meta->'token' as token, a.created_at,
u.username, u.display_name, u.avatar_url as actor_avatar
from agent_identities a
join user_follows f on f.following_id = a.user_id and f.follower_id = ${viewer.id}
join users u on u.id = a.user_id and u.deleted_at is null and u.username is not null
where a.is_public = true and a.deleted_at is null
and a.meta->'token'->>'mint' is not null
${before ? sql`and a.created_at < ${before}` : sql``}
order by coalesce(a.meta->'token'->>'launched_at', a.created_at::text) desc
limit ${perKind}
`,
sql`
select fc.id, fc.prompt, fc.glb_url, fc.preview_image_url, fc.model_category,
fc.parent_creation_id, fc.created_at,
u.username, u.display_name, u.avatar_url
from forge_creations fc
join user_follows f on f.following_id = fc.user_id and f.follower_id = ${viewer.id}
join users u on u.id = fc.user_id and u.deleted_at is null and u.username is not null
where fc.status = 'done' and fc.glb_url is not null
and (fc.outcome is null or fc.outcome != 'rejected')
${before ? sql`and fc.created_at < ${before}` : sql``}
order by fc.created_at desc
limit ${perKind}
`,
sql`
select d.id, d.title, d.mood, d.created_at,
d.doc->'objects' as objects,
u.username, u.display_name, u.avatar_url
from dioramas d
join user_follows f on f.following_id = d.user_id and f.follower_id = ${viewer.id}
join users u on u.id = d.user_id and u.deleted_at is null and u.username is not null
where d.user_id is not null
${before ? sql`and d.created_at < ${before}` : sql``}
order by d.created_at desc
limit ${perKind}
`,
// Fail-soft: the material_restyles migration may not have landed on
// every deployment yet — a missing table must never 500 the feed.
sql`
select mr.id, mr.action, mr.label, mr.instruction, mr.preset,
mr.result_url, mr.created_at,
u.username, u.display_name, u.avatar_url
from material_restyles mr
join user_follows f on f.following_id = mr.user_id and f.follower_id = ${viewer.id}
join users u on u.id = mr.user_id and u.deleted_at is null and u.username is not null
where mr.user_id is not null
${before ? sql`and mr.created_at < ${before}` : sql``}
order by mr.created_at desc
limit ${perKind}
`.catch(() => []),
sql`
select f.created_at,
uf.username as follower_username, uf.display_name as follower_display, uf.avatar_url as follower_avatar,
ut.username as target_username, ut.display_name as target_display, ut.avatar_url as target_avatar
from user_follows f
join user_follows vf on vf.following_id = f.follower_id and vf.follower_id = ${viewer.id}
join users uf on uf.id = f.follower_id and uf.deleted_at is null and uf.username is not null
join users ut on ut.id = f.following_id and ut.deleted_at is null and ut.username is not null
where f.follower_id != ${viewer.id}
${before ? sql`and f.created_at < ${before}` : sql``}
order by f.created_at desc
limit ${followPerKind}
`.catch(() => []),
]);
const items = mergeItems({
avatarRows,
agentRows,
coinRows,
modelRows,
worldRows,
restyleRows: restyleRaw.map((r) => ({
id: r.id,
created_at: r.created_at,
glb_url: r.result_url,
prompt: r.instruction || r.preset || null,
action: r.action,
category: r.action === 'variants' ? 'colorway variant' : 'AI restyle',
username: r.username,
display_name: r.display_name,
avatar_url: r.avatar_url,
})),
followRows,
});
items.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
const page = items.slice(0, limit);
res.setHeader('Cache-Control', 'private, no-store');
return json(res, 200, {
items: page,
following_count,
scope,
next: page.length === limit ? page[page.length - 1].created_at : null,
});
}
// scope === 'all': platform-wide recent activity, no follow graph, no auth.
const [avatarRows, agentRows, coinRows, modelRows, worldRows, restyleRecent, followRows] = await Promise.all([
sql`
select a.id, a.name, a.thumbnail_key, a.created_at,
u.username, u.display_name, u.avatar_url
from avatars a
join users u on u.id = a.owner_id and u.deleted_at is null and u.username is not null
where a.visibility = 'public' and a.deleted_at is null
${before ? sql`and a.created_at < ${before}` : sql``}
order by a.created_at desc
limit ${perKind}
`,
sql`
select a.id, a.name, a.description, a.profile_image_url, a.avatar_url, a.created_at,
u.username, u.display_name, u.avatar_url as actor_avatar
from agent_identities a
join users u on u.id = a.user_id and u.deleted_at is null and u.username is not null
where a.is_public = true and a.deleted_at is null
${before ? sql`and a.created_at < ${before}` : sql``}
order by a.created_at desc
limit ${perKind}
`,
sql`
select a.id as agent_id, a.name as agent_name, a.profile_image_url, a.avatar_url,
a.meta->'token' as token, a.created_at,
u.username, u.display_name, u.avatar_url as actor_avatar
from agent_identities a
join users u on u.id = a.user_id and u.deleted_at is null and u.username is not null
where a.is_public = true and a.deleted_at is null
and a.meta->'token'->>'mint' is not null
${before ? sql`and a.created_at < ${before}` : sql``}
order by coalesce(a.meta->'token'->>'launched_at', a.created_at::text) desc
limit ${perKind}
`,
listRecentCreations({ limit: perKind, before }),
listDioramas({ scope: 'recent', limit: perKind, before }),
listRecentRestyles({ limit: perKind, before }),
sql`
select f.created_at,
uf.username as follower_username, uf.display_name as follower_display, uf.avatar_url as follower_avatar,
ut.username as target_username, ut.display_name as target_display, ut.avatar_url as target_avatar
from user_follows f
join users uf on uf.id = f.follower_id and uf.deleted_at is null and uf.username is not null
join users ut on ut.id = f.following_id and ut.deleted_at is null and ut.username is not null
where true
${before ? sql`and f.created_at < ${before}` : sql``}
order by f.created_at desc
limit ${followPerKind}
`.catch(() => []),
]);
const items = mergeItems({
avatarRows,
agentRows,
coinRows,
modelRows: modelRows.map((m) => ({
id: m.id,
created_at: m.createdAt,
glb_url: m.glbUrl,
preview_image_url: m.previewImageUrl,
model_category: m.category,
isRemix: m.isRemix,
username: m.username,
display_name: m.displayName,
avatar_url: m.avatarUrl,
})),
worldRows: worldRows.map((w) => ({
id: w.id,
created_at: w.createdAt,
title: w.title,
mood: w.mood,
objects: w.thumbnailGlb ? [{ glbUrl: w.thumbnailGlb }] : [],
username: w.creatorUsername,
display_name: w.creatorDisplayName || w.creatorUsername,
avatar_url: w.creatorAvatarUrl,
})),
restyleRows: restyleRecent.map((r) => ({
id: r.id,
created_at: r.createdAt,
glb_url: r.glbUrl,
prompt: r.prompt,
action: r.action,
category: r.category,
username: r.username,
display_name: r.displayName,
avatar_url: r.avatarUrl,
})),
followRows,
});
items.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
const page = items.slice(0, limit);
res.setHeader('Cache-Control', 'public, s-maxage=15, stale-while-revalidate=60');
return json(res, 200, {
items: page,
scope,
next: page.length === limit ? page[page.length - 1].created_at : null,
});
});
function mergeItems({ avatarRows, agentRows, coinRows, modelRows, worldRows, restyleRows = [], followRows }) {
const items = [];
for (const r of avatarRows) {
items.push({
kind: 'avatar',
id: r.id,
created_at: r.created_at,
actor: actorFrom(r),
title: r.name,
href: `/avatars/${r.id}`,
image: thumbnailUrl(r.thumbnail_key),
});
}
for (const r of agentRows) {
items.push({
kind: 'agent',
id: r.id,
created_at: r.created_at,
actor: actorFrom(r, { avatar: 'actor_avatar' }),
title: r.name,
subtitle: r.description || null,
href: `/agents/${r.id}`,
image: r.profile_image_url || r.avatar_url || null,
});
}
for (const r of coinRows) {
const t = r.token || {};
if (!t.mint) continue;
items.push({
kind: 'coin',
id: t.mint,
created_at: t.launched_at || r.created_at,
actor: actorFrom(r, { avatar: 'actor_avatar' }),
title: t.name || r.agent_name,
subtitle: t.symbol ? `$${String(t.symbol).replace(/^\$/, '')}` : null,
href: t.pumpfun_url || t.explorer_url || `/agents/${r.agent_id}`,
external: Boolean(t.pumpfun_url || t.explorer_url),
image: t.image || r.profile_image_url || r.avatar_url || null,
});
}
for (const r of modelRows) {
items.push({
kind: 'model',
id: r.id,
created_at: r.created_at,
actor: actorFrom(r),
title: r.prompt,
subtitle: r.model_category && r.model_category !== 'other' ? r.model_category : null,
href: `${SITE}/viewer?src=${encodeURIComponent(r.glb_url)}`,
image: r.preview_image_url || null,
isRemix: Boolean(r.parent_creation_id ?? r.isRemix),
});
}
for (const r of worldRows) {
const objects = Array.isArray(r.objects) ? r.objects : [];
items.push({
kind: 'world',
id: r.id,
created_at: r.created_at,
actor: actorFrom(r),
title: r.title,
subtitle: r.mood || null,
href: `${SITE}/diorama?id=${r.id}`,
image: objects.find((o) => o && o.glbUrl)?.glbUrl || null,
});
}
for (const r of restyleRows) {
items.push({
kind: 'restyle',
id: r.id,
created_at: r.created_at,
actor: actorFrom(r),
title: r.prompt || (r.action === 'variants' ? 'Colorway variant' : 'Restyled model'),
subtitle: r.category || null,
// Mirrors `isRemix` on kind:'model': the one bit of render metadata a
// client needs to pick the verb ("made a colorway variant" vs
// "restyled a model") without string-matching the subtitle.
isVariant: r.action === 'variants',
href: `${SITE}/viewer?src=${encodeURIComponent(r.glb_url)}`,
// result_url is a GLB, not a raster image — render the kind glyph
// instead of a guaranteed-broken <img>.
image: null,
});
}
for (const r of followRows) {
items.push({
kind: 'follow',
id: `${r.follower_username}-${r.target_username}-${new Date(r.created_at).getTime()}`,
created_at: r.created_at,
actor: actorFrom(r, { username: 'follower_username', displayName: 'follower_display', avatar: 'follower_avatar' }),
target: actorFrom(r, { username: 'target_username', displayName: 'target_display', avatar: 'target_avatar' }),
title: r.target_display || r.target_username,
href: `/u/${r.target_username}`,
image: r.target_avatar ? (r.target_avatar.startsWith('http') ? r.target_avatar : publicUrl(r.target_avatar)) : null,
});
}
return items;
}