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.

8.8 KB
Raw Blame
/**
 * Crawler page for avatar detail (/avatars/:id)
 * ---------------------------------------------
 * GET /api/avatar-detail-og?id=<avatarId>
 *
 * Wired via vercel.json: when a crawler User-Agent hits /avatars/<uuid>, a
 * "has" condition rewrites to this endpoint. Real browsers never reach it, so
 * this is the only version of the page a search engine or a link unfurler ever
 * sees. It therefore has to carry the avatar's real content, not just meta
 * tags: see the header of api/_lib/crawler-page.js for why a spinner plus a
 * <noscript> block collapsed 45k avatar URLs into a single duplicate cluster.
 *
 * Mirrors api/agent-detail-og.js.
 */

import { sql } from './_lib/db.js';
import { cors, method, wrap } from './_lib/http.js';
import { env } from './_lib/env.js';
import { isUuid } from './_lib/validate.js';
import { esc, isSearchCrawler, renderCrawlerPage, renderCrawlerNotFound } from './_lib/crawler-page.js';
import { isIndexableAvatar } from './_lib/indexable-entity.js';
import { publicUrlOrNull } from './_lib/r2.js';
import { creationJsonLd } from './_lib/creation-jsonld.js';

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
	// Crawler-only SSR read. Without this, a POST answered with a page instead
	// of the 405 the advertised Allow set promises.
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, 'http://x');
	const avatarId = url.searchParams.get('id');
	const origin = env.APP_ORIGIN || 'https://three.ws';
	const ua = req.headers?.['user-agent'];
	// Only a non-indexing scraper gets bounced to the app. An indexing crawler
	// runs that script, lands back on this same URL behind the same UA branch,
	// and loops on an identical response.
	const redirect = !isSearchCrawler(ua);

	// Demo and legacy ids are not uuids. They still resolve in the app, so keep
	// the bounce and a valid unfurl, but keep them out of the index rather than
	// inventing a page for an entity we cannot read.
	if (!avatarId || !isUuid(avatarId)) {
		return generic(res, origin, avatarId, redirect);
	}

	let avatar;
	try {
		[avatar] = await sql`
			SELECT a.id, a.name, a.description, a.alt_text, a.tags, a.model_category,
			       a.view_count, a.fork_count, a.parent_avatar_id,
			       a.storage_key, a.size_bytes,
			       a.created_at, a.updated_at,
			       u.username AS owner_username, u.display_name AS owner_display_name
			FROM avatars a
			LEFT JOIN users u ON u.id = a.owner_id AND u.deleted_at IS NULL
			WHERE a.id = ${avatarId} AND a.deleted_at IS NULL AND a.visibility = 'public'
			LIMIT 1
		`;
	} catch {
		// A read failure is ours, not the URL's. 503 asks the crawler to come
		// back; a 404 or a redirect here would drop a live page from the index.
		return unavailable(res, origin);
	}

	if (!avatar) {
		// Agents and avatars have separate uuid spaces and links cross over
		// (see resolveEntity in src/avatar-page.js). Send the crawler to the
		// path that actually holds the entity instead of reporting nothing.
		let agent = null;
		try {
			[agent] = await sql`
				SELECT id FROM agent_identities
				WHERE id = ${avatarId} AND deleted_at IS NULL LIMIT 1
			`;
		} catch {
			return unavailable(res, origin);
		}
		if (agent) {
			res.statusCode = 301;
			res.setHeader('location', `${origin}/agents/${avatarId}`);
			res.setHeader('cache-control', 'public, max-age=300');
			res.end();
			return;
		}
		return gone(res, origin);
	}

	const title = avatar.name || 'Avatar';
	const baseDesc =
		avatar.description ||
		avatar.alt_text ||
		'A 3D avatar on three.ws - rigged, animated, and ready to become an agent.';
	const tags = Array.isArray(avatar.tags) ? avatar.tags : [];
	const tagSuffix = tags.length
		? ` Tags: ${tags.slice(0, 4).join(', ')}${tags.length > 4 ? '…' : ''}.`
		: '';
	const byline = avatar.owner_username ? ` By @${avatar.owner_username}.` : '';
	const desc = baseDesc + byline + tagSuffix;

	// Unfurl with the rendered avatar card (api/avatar-og.js) - the avatar's own
	// turntable render with name plate, from real data. The card endpoint falls
	// back to the brand image if it can't render.
	const ogImage = `${origin}/api/avatars/${encodeURIComponent(avatarId)}/og`;
	const pageUrl = `${origin}/avatars/${avatarId}`;

	const facts = [];
	if (avatar.owner_username) {
		const u = esc(avatar.owner_username);
		facts.push({ term: 'Creator', detail: `<a href="/u/${u}" rel="author">@${u}</a>` });
	}
	if (avatar.model_category) facts.push({ term: 'Category', detail: esc(avatar.model_category) });
	if (avatar.parent_avatar_id) {
		const parent = esc(avatar.parent_avatar_id);
		facts.push({ term: 'Remixed from', detail: `<a href="/avatars/${parent}">the original avatar</a>` });
	}
	if (Number(avatar.fork_count) > 0) {
		facts.push({ term: 'Remixes', detail: `${Number(avatar.fork_count)} on three.ws` });
	}
	if (Number(avatar.view_count) > 0) {
		facts.push({ term: 'Views', detail: String(Number(avatar.view_count)) });
	}
	if (avatar.created_at) facts.push({ term: 'Published', detail: isoDay(avatar.created_at) });

	res.statusCode = 200;
	res.setHeader('content-type', 'text/html; charset=utf-8');
	res.setHeader('cache-control', 'public, max-age=60, s-maxage=600, stale-while-revalidate=3600');
	res.end(
		renderCrawlerPage({
			title,
			desc,
			pageUrl,
			ogImage,
			origin,
			ogType: 'profile',
			frameButton: `Meet ${title}`,
			redirect,
			// An untouched onboarding row is identical to every other one, so it
			// unfurls and renders but never asks to be indexed.
			noindex: !isIndexableAvatar(avatar),
			trail: [
				{ name: 'Home', path: '/' },
				{ name: 'Gallery', path: '/gallery' },
				{ name: title, path: `/avatars/${avatarId}` },
			],
			facts,
			tags: tags.slice(0, 12).map((tag) => ({
				label: tag,
				href: `/gallery?tag=${encodeURIComponent(tag)}`,
			})),
			actions: [
				{ label: 'View in AR', href: `/avatars/${avatarId}/ar`, primary: true },
				{ label: 'Browse the gallery', href: '/gallery' },
				{ label: 'Create your own', href: '/create' },
			],
			related: [
				{ label: 'Avatar gallery', href: '/gallery' },
				{ label: 'Animation library', href: '/animations' },
				{ label: 'Build an embeddable widget', href: '/studio' },
				{ label: 'Agent directory', href: '/agents' },
			],
			// The GLB, its rendered PNG, creator, date and terms, in the shape
			// every creation page shares (api/_lib/creation-jsonld.js). The query
			// above only returns public avatars, so the file URL is public too.
			jsonLd: creationJsonLd({
				origin,
				pageUrl,
				name: title,
				description: desc,
				glbUrl: publicUrlOrNull(avatar.storage_key),
				glbSizeBytes: avatar.size_bytes,
				image: ogImage,
				creator: avatar.owner_username
					? { username: avatar.owner_username, displayName: avatar.owner_display_name }
					: null,
				dateCreated: avatar.created_at,
				dateModified: avatar.updated_at,
				keywords: tags,
			}),
		}),
	);
});

/** An id we cannot read: keep the unfurl useful, keep the URL out of the index. */
function generic(res, origin, avatarId, redirect) {
	const target = avatarId ? `/avatars/${encodeURIComponent(avatarId)}` : '/gallery';
	res.statusCode = 200;
	res.setHeader('content-type', 'text/html; charset=utf-8');
	res.setHeader('cache-control', 'public, max-age=60, s-maxage=600');
	res.end(
		renderCrawlerNotFound({
			heading: 'Avatar on three.ws',
			message:
				'Open this avatar in the three.ws studio to view it in 3D, animate it, and embed it anywhere.',
			origin,
			actions: [
				{ label: 'Open the studio', href: target },
				{ label: 'Browse the gallery', href: '/gallery' },
			],
			redirect: redirect ? target : '',
		}),
	);
}

/** Nothing public lives at this id. 404 so the URL leaves the index cleanly. */
function gone(res, origin) {
	res.statusCode = 404;
	res.setHeader('content-type', 'text/html; charset=utf-8');
	res.setHeader('cache-control', 'public, max-age=300');
	res.end(
		renderCrawlerNotFound({
			heading: 'This avatar is not public',
			message:
				'The avatar behind this link was removed, or its owner keeps it private. The gallery has thousands of others.',
			origin,
			actions: [
				{ label: 'Browse the gallery', href: '/gallery' },
				{ label: 'Create an avatar', href: '/create' },
			],
		}),
	);
}

/** Our read failed. Ask the crawler to retry rather than losing the page. */
function unavailable(res, origin) {
	res.statusCode = 503;
	res.setHeader('content-type', 'text/html; charset=utf-8');
	res.setHeader('retry-after', '120');
	res.setHeader('cache-control', 'no-store');
	res.end(
		renderCrawlerNotFound({
			heading: 'Avatar temporarily unavailable',
			message: 'three.ws could not load this avatar just now. Please try again in a moment.',
			origin,
			actions: [{ label: 'Browse the gallery', href: '/gallery' }],
		}),
	);
}

/** YYYY-MM-DD, the only precision a crawler page needs. */
function isoDay(v) {
	const t = v instanceof Date ? v : new Date(v);
	return Number.isNaN(t.getTime()) ? '' : t.toISOString().slice(0, 10);
}