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.

7.5 KB
Raw Blame
// Unified API gateway — the single entry contract for the versioned three.ws
// API (/api/v1/*).
//
// three.ws exposes 700+ capability endpoints under /api. This module bundles
// them into ONE coherent product API: every /api/v1 route is a thin handler
// that declares its auth requirement, OAuth scope, and a capability function —
// the gateway provides everything else exactly once, so the surface stays
// consistent no matter which capability sits behind it:
//
//   • Auth      — three.ws API key (`Authorization: Bearer sk_live_…`), OAuth
//                 access token, or browser session. One contract, three rails.
//   • Scopes    — declared per endpoint, enforced for key/OAuth callers.
//   • Limits    — per-principal rate limiting (key › user › IP) with standard
//                 RateLimit-* headers, via api/_lib/rate-limit.js `apiV1`.
//   • Metering  — every call recorded to usage_events (api/_lib/usage.js), so a
//                 single dashboard/billing view spans the whole API.
//   • Envelope  — success → { data }, failure → { error, error_description }
//                 (the same shape the rest of the API already uses), with 5xx
//                 sanitized via api/_lib/http.js `wrap`.
//
// A handler returns its payload (wrapped in `{ data }` with 200) or writes the
// response itself (e.g. a redirect / binary) and returns nothing. To fail a
// request, throw an Error with `.status` and `.code` — `wrap` formats it.

import {
	cors,
	json,
	error,
	method as methodGuard,
	readJson,
	rateLimited,
	setRateLimitHeaders,
	wrap,
} from './http.js';
import {
	authenticateBearer,
	extractBearer,
	getSessionUser,
	hasScope,
} from './auth.js';
import { limits, clientIp } from './rate-limit.js';
import { recordEvent } from './usage.js';
import { devPlanGate } from './dev-plans/quota.js';

/**
 * Throw a client-facing error the gateway will render as
 * `{ error: <code>, error_description: <message> }` at the given status.
 * @param {number} status
 * @param {string} code
 * @param {string} message
 */
export function fail(status, code, message) {
	// `expose` marks this as an author-written contract error, so wrap() may echo
	// the code and message even on a 5xx. Errors that merely bubble up (a Postgres
	// SQLSTATE, an ECONNREFUSED) carry no such marker and stay redacted.
	throw Object.assign(new Error(message), { status, code, expose: true });
}

/**
 * Define a versioned API endpoint.
 *
 * @param {object} spec
 * @param {string} spec.name                  Stable usage/billing identifier, e.g. "v1.sentiment".
 * @param {string|string[]} spec.method       Allowed HTTP method(s).
 * @param {'public'|'optional'|'required'} spec.auth  Auth requirement.
 * @param {string} [spec.scope]               OAuth scope required for key/OAuth callers (auth: required|optional).
 * @param {(ctx: GatewayCtx) => Promise<any>|any} spec.handler
 * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse) => Promise<void>}
 *
 * @typedef {object} GatewayCtx
 * @property {import('http').IncomingMessage} req
 * @property {import('http').ServerResponse} res
 * @property {Principal|null} principal  Resolved caller (null for anonymous public calls).
 * @property {Record<string, any>} body  Parsed JSON body (POST/PUT/PATCH), else {}.
 * @property {Record<string, string>} query  Parsed query-string params.
 * @property {string} ip
 *
 * @typedef {object} Principal
 * @property {string} userId
 * @property {'session'|'apikey'|'oauth'} source
 * @property {string} scope
 * @property {string} [apiKeyId]
 * @property {string} [clientId]
 */
export function defineEndpoint(spec) {
	const methods = Array.isArray(spec.method) ? spec.method : [spec.method];
	const writeMethods = methods.some((m) => ['POST', 'PUT', 'PATCH'].includes(m));

	return wrap(async (req, res) => {
		if (cors(req, res, { methods: [...methods, 'OPTIONS'].join(','), origins: '*' })) return;
		if (!methodGuard(req, res, methods)) return;

		const started = Date.now();
		const ip = clientIp(req);

		// ── auth ──────────────────────────────────────────────────────────────
		let principal = null;
		if (spec.auth === 'required' || spec.auth === 'optional') {
			const session = await getSessionUser(req);
			if (session) {
				// A signed-in owner acting on their own account holds every scope.
				principal = { userId: session.id, source: 'session', scope: 'all' };
			} else {
				const bearer = await authenticateBearer(extractBearer(req), { ip });
				if (bearer) {
					principal = {
						userId: bearer.userId,
						source: bearer.source,
						scope: bearer.scope || '',
						apiKeyId: bearer.apiKeyId,
						clientId: bearer.clientId,
					};
				}
			}

			if (spec.auth === 'required' && !principal) {
				return error(
					res,
					401,
					'unauthorized',
					'authenticate with a three.ws API key (`Authorization: Bearer sk_live_…`) or sign in — create a key at /dashboard/developers',
				);
			}
			if (
				principal &&
				principal.source !== 'session' &&
				spec.scope &&
				!hasScope(principal.scope, spec.scope)
			) {
				return error(
					res,
					403,
					'insufficient_scope',
					`this endpoint requires the "${spec.scope}" scope`,
				);
			}
		}

		// ── plan gate (per account) › anonymous IP limit ───────────────────────
		// A signed-in account gets its developer plan's burst, concurrency and
		// monthly quota on every v1 route (api/_lib/dev-plans/quota.js). A key or
		// OAuth token spends quota; an owner browsing their own dashboard is held
		// to the same ceilings but does not spend the calls they are paying for.
		let gate = null;
		if (principal?.userId) {
			gate = await devPlanGate({ userId: principal.userId, res, countsAgainstQuota: principal.source !== 'session' });
			if (!gate.ok) return;
		} else {
			const rl = await limits.apiV1(`ip:${ip}`);
			setRateLimitHeaders(res, rl);
			if (!rl.success) return rateLimited(res, rl);
		}

		// ── body + query ───────────────────────────────────────────────────────
		const body = writeMethods && req.method !== 'GET' ? await readJson(req) : {};
		const query = Object.fromEntries(new URL(req.url, 'http://internal').searchParams);

		const ctx = { req, res, principal, body, query, ip };

		// ── dispatch + meter ─────────────────────────────────────────────────────
		// `meta` is what the per-key analytics read (api/_lib/dev-plans/analytics.js):
		// the route, the caller's address, the plan and the HTTP status.
		const meter = (status, httpStatus) =>
			recordEvent({
				kind: 'api',
				tool: spec.name,
				userId: principal?.userId,
				apiKeyId: principal?.apiKeyId,
				clientId: principal?.clientId,
				status,
				latencyMs: Date.now() - started,
				meta: { route: spec.name, method: req.method, ip, plan: gate?.sub?.planId ?? null, http_status: httpStatus },
			});

		let payload;
		try {
			payload = await spec.handler(ctx);
		} catch (err) {
			meter('error', err?.status || 500);
			throw err; // wrap() renders the envelope (4xx descriptive, 5xx sanitized)
		} finally {
			gate?.release?.();
		}
		meter('ok', 200);

		// Handler may have already responded (redirect / streamed / binary).
		if (res.writableEnded || res.headersSent) return;
		return json(res, 200, { data: payload });
	});
}