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
// CoinCommunities server-side client — the ONLY place the API key lives.
//
// Each coin on three.ws is its own 3D world (/temporary?coin=<mint>); its
// CoinCommunities community is that world's live social layer. The browser
// never sees the API key: it talks to the api/community/* proxy, which calls
// CoinCommunities with the key held here. Realtime works the same way — the
// proxy mints a short-lived WS ticket and the browser opens the socket to
// CoinCommunities directly with it (see api/community/ws-ticket.js).
//
// Two credential tiers:
// CC_API_KEY — reads (feed, messages) + WS tickets.
// CC_SERVER_KEY + CC_SERVER_SECRET — server-side post attribution. Optional;
// absent → the Town composer stays in its
// designed locked state, reads still work.
import { configureApi, api } from '@coin-communities/sdk/node';
import { normalizeGatewayURL } from '../../src/ipfs.js';
import { getTrendingSlim } from './pump-trending.js';
// Solana mint addresses — base58, 32–44 chars. Communities are keyed by these.
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
// EVM addresses (Ethereum/Base/BSC/Robinhood Chain, etc.) — the CHAINS list in
// api/community/messages.js already names these as supported chain ids; this
// gate previously only accepted Solana, so every EVM-chain world's Town chat
// 400'd before the request ever reached CoinCommunities.
const EVM_RE = /^0x[a-fA-F0-9]{40}$/;
let _configured = false;
export function ccBaseUrl() {
return (process.env.CC_BASE_URL || 'https://api.coin-communities.xyz').replace(/\/+$/, '');
}
function ccApiKey() {
return process.env.CC_API_KEY || '';
}
function ccServerKey() {
return process.env.CC_SERVER_KEY || '';
}
function ccServerSecret() {
return process.env.CC_SERVER_SECRET || '';
}
/** Reads + WS tickets available. */
export function isConfigured() {
return Boolean(ccApiKey());
}
/** Server-side post attribution available (postMessageServer). */
export function canPostServer() {
return Boolean(ccServerKey() && ccServerSecret());
}
/** Validate a community token address before it ever reaches the API. */
export function isValidToken(token) {
return typeof token === 'string' && (BASE58_RE.test(token) || EVM_RE.test(token));
}
/**
* Solana-only variant, for surfaces backed by Solana-only machinery: pump.fun
* creator lookups, SPL balance reads, holder passes. Those cannot answer for an
* EVM-chain world, so they check this instead of isValidToken and say so.
*/
export function isSolanaToken(token) {
return typeof token === 'string' && BASE58_RE.test(token);
}
class UnconfiguredError extends Error {
constructor() {
super('CoinCommunities is not configured (set CC_API_KEY)');
this.code = 'cc_unconfigured';
}
}
export { UnconfiguredError };
/**
* Returns the configured `api` namespace. Configures the shared client once
* per cold start. Throws UnconfiguredError if no API key is set so callers can
* answer with a clean 503 rather than leaking a stack trace.
*/
export function cc() {
if (!isConfigured()) throw new UnconfiguredError();
if (!_configured) {
configureApi({ baseUrl: ccBaseUrl(), headers: { 'x-api-key': ccApiKey() } });
_configured = true;
}
return api;
}
/** Headers for server-key-pair operations (merged per-call over the api key). */
export function serverHeaders() {
return {
'x-server-key': ccServerKey(),
'x-server-secret': ccServerSecret(),
};
}
/** Capability snapshot the browser uses to decide which Town affordances to show. */
export function capabilities() {
const configured = isConfigured();
return {
configured,
// User posting (X sign-in → link wallet → postMessage) needs only the API
// key (plus a whitelisted OAuth redirect, which the dashboard owns).
canPostUser: configured,
// Server attribution (postMessageServer) needs the server key-pair.
canPostServer: canPostServer(),
// Either path means the composer should be live rather than locked.
canPost: configured || canPostServer(),
baseUrl: ccBaseUrl(),
defaultToken:
(isValidToken(process.env.CC_DEFAULT_TOKEN) && process.env.CC_DEFAULT_TOKEN) || null,
};
}
// ─── CoinCommunities user session (X-OAuth) ──────────────────────────────────
// A signed-in CoinCommunities user is identified by a JWT we keep in an
// httpOnly cookie scoped to the proxy path, so user-scoped writes (postMessage,
// wallet linking) are forwarded server-side without the token ever being
// readable by page scripts. The API key still rides every request globally.
const AT_COOKIE = 'cc_at';
const RT_COOKIE = 'cc_rt';
const AT_TTL = 60 * 60; // 1h — access token
const RT_TTL = 60 * 60 * 24 * 30; // 30d — refresh token
function cookieAttrs(maxAge) {
// Scoped to the proxy so it's never sent with page or unrelated API requests.
return `Path=/api/community; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`;
}
/** Persist a CoinCommunities user session to httpOnly cookies. */
export function setUserSession(res, { accessToken, refreshToken }) {
const cookies = [];
if (accessToken) cookies.push(`${AT_COOKIE}=${accessToken}; ${cookieAttrs(AT_TTL)}`);
if (refreshToken) cookies.push(`${RT_COOKIE}=${refreshToken}; ${cookieAttrs(RT_TTL)}`);
if (cookies.length) res.setHeader('set-cookie', cookies);
}
/** Clear the CoinCommunities user session cookies. */
export function clearUserSession(res) {
res.setHeader('set-cookie', [
`${AT_COOKIE}=; Path=/api/community; HttpOnly; Secure; SameSite=Lax; Max-Age=0`,
`${RT_COOKIE}=; Path=/api/community; HttpOnly; Secure; SameSite=Lax; Max-Age=0`,
]);
}
function readSessionCookie(req, name) {
const cookie = req.headers.cookie || '';
const m = cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
return m ? decodeURIComponent(m[1]) : null;
}
/** Read the current user's access token from the request cookies, if any. */
export function userToken(req) {
return readSessionCookie(req, AT_COOKIE);
}
/** Read the current user's refresh token from the request cookies, if any. */
export function userRefreshToken(req) {
return readSessionCookie(req, RT_COOKIE);
}
/** Per-call headers that attach a user's bearer JWT for user-scoped operations. */
export function userAuthHeaders(req) {
const token = userToken(req);
return token ? { Authorization: `Bearer ${token}` } : null;
}
/**
* True when the request carries any usable session cookie, access or refresh.
* Handlers that gate on "is this user signed in?" must use this rather than
* `userAuthHeaders(req)`: the access-token cookie expires out of the browser
* after 1h, so an hours-old but perfectly valid session has only `cc_rt` left
* and a bare `userAuthHeaders` check would call that user a stranger.
*/
export function hasUserSession(req) {
return Boolean(userToken(req) || userRefreshToken(req));
}
/**
* Mint a fresh access token from the refresh cookie and persist it. Returns the
* new bearer headers, or null when there is nothing to refresh with (or the
* refresh token itself is dead, in which case the stale cookies are cleared).
*/
async function refreshSession(req, res) {
const refreshToken = userRefreshToken(req);
if (!refreshToken || !isConfigured()) return null;
const { data, error } = await cc().refreshToken({ body: { refreshToken } });
if (error || !data?.accessToken) {
clearUserSession(res);
return null;
}
setUserSession(res, data);
return { Authorization: `Bearer ${data.accessToken}` };
}
/**
* Runs an authenticated CoinCommunities API call, transparently refreshing the
* session on a 401 and retrying once before giving up. The `cc_at` access-token
* cookie only lives 1h; without this, any signed-in player who comes back to
* `/play` after an hour gets treated as never having signed in at all, even
* though the 30-day `cc_rt` refresh token is still good.
*
* `call(headers)` should run one or more SDK calls with the given bearer
* headers and return `{ data, error }` (an upstream 401 on any of them should
* surface as `error.statusCode === 401`). Returns `{ data, error, headers }`;
* `headers` is null when there is no usable session (never signed in, or the
* refresh itself failed) — callers should treat that as "not logged in"
* regardless of `error`, since `error` may just be the original 401.
*/
export async function withAuthRefresh(req, res, call) {
const headers = userAuthHeaders(req);
if (!headers) {
// No access-token cookie at all. That is the *normal* state one hour after
// sign-in, since `cc_at` and the JWT inside it share a 1h lifetime: the
// browser drops the cookie and the request arrives carrying only `cc_rt`.
// Refresh from it before concluding the caller is signed out, otherwise the
// 30-day refresh token is never once used and every session dies at 1h.
const fresh = await refreshSession(req, res);
if (!fresh) return { data: null, error: null, headers: null };
const result = await call(fresh);
return { ...result, headers: fresh };
}
let result = await call(headers);
if (result?.error?.statusCode !== 401) return { ...result, headers };
const refreshed = await refreshSession(req, res);
if (!refreshed) return { ...result, headers: null };
result = await call(refreshed);
return { ...result, headers: refreshed };
}
/**
* Normalize a TopCommunity into the world-card shape the lobby renders. Keeps
* the browser ignorant of the upstream schema so a field rename upstream is a
* one-line change here.
*/
export function toWorldCard(c) {
return {
token: c.tokenAddress,
symbol: c.tokenSymbol || null,
image: normalizeGatewayURL(c.tokenHighResImageUrl || c.tokenImageUrl || '') || null,
chainId: c.chainId ?? null,
members: c.memberCount ?? 0,
posts: c.postCount ?? 0,
likes: c.totalLikes ?? 0,
latestPostAt: c.latestPostAt ?? null,
};
}
/**
* The live trending feed as world cards: the failover roster for every surface
* that ranks coin communities (the /temporary lobby, Coin Clash) when
* CoinCommunities is unconfigured or down. The cards carry `social: false`
* because there are no members, posts or likes to show, plus the coin's name
* and market cap so a client has a real number to render in their place.
* Resolves to null when the trending feed is unavailable too.
*/
export async function trendingWorldCards(limit) {
const { data } = await getTrendingSlim(limit);
if (!data) return null;
return data.map((t) => ({
token: t.mint,
symbol: t.symbol || null,
name: t.name || null,
image: t.logo || null,
chainId: null,
members: 0,
posts: 0,
likes: 0,
latestPostAt: null,
marketCapUsd: t.usd_market_cap ?? null,
social: false,
}));
}
/**
* Normalize a Message into the compact shape Town renders (rail rows + bubbles).
* Drops moderation internals the client doesn't need.
*/
export function toTownMessage(m) {
return {
id: m.id,
token: m.tokenAddress,
content: m.content,
mediaUrl: m.mediaUrl || null,
username: m.username || 'anon',
avatar: m.profileImageUrl || null,
twitterUrl: m.userTwitterUrl || null,
wallet: m.walletAddress || null,
followers: m.followerCount ?? 0,
likes: m.likeCount ?? 0,
replies: m.replyCount ?? 0,
createdAt: m.createdAt,
};
}