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
// Friends client — the browser-side data layer for the account-level friends
// system (Task 15). It owns the social-graph state (friends, incoming/outgoing
// requests, DM threads, unread counts), talks to the /api/friends endpoints, and
// reconciles live socket events with a polling backstop so the UI is correct
// whether or not the live channel is connected.
//
// Realtime is delivered over whichever Colyseus realm room the player is already
// connected to: the server pushes a 'social' message, the net wrapper forwards
// it here via handleSocial(), and we update state + emit 'change'. The presence
// ticket minted here is what lets that realm room publish the player's presence
// in the first place (see getPresenceTicket).
//
// The panel UI (game/friends-panel.js) is a pure view over this client.
import { apiFetch } from './api.js';
import { log } from './shared/log.js';
// Same auth-hint gate notifications.js uses: skip authenticated endpoints
// entirely while the visitor is anonymous instead of collecting 401s on every
// poll. The hint is set/cleared by the login flows (privy-login, email-auth);
// a stale-true hint still falls through to the 401 handling below.
const AUTH_HINT_KEY = '3dagent:auth-hint';
function isAuthedHint() {
try {
const raw = localStorage.getItem(AUTH_HINT_KEY);
return raw ? JSON.parse(raw)?.authed === true : false;
} catch { return false; }
}
// ── presence ticket ─────────────────────────────────────────────────────────
// Short-lived, account-scoped token the realm room verifies before publishing
// presence. Cached and refreshed lazily; the net layer calls getPresenceTicket()
// on every (re)connect, so an expired ticket self-heals on the next connection.
let _ticket = null;
let _ticketExpEpoch = 0;
export async function getPresenceTicket() {
if (!isAuthedHint()) return null; // anonymous players have no presence to publish
const now = Date.now() / 1000;
if (_ticket && _ticketExpEpoch - now > 60) return _ticket;
try {
const res = await apiFetch('/api/friends/presence-ticket', { allowAnonymous: true });
if (!res.ok) return null;
const { data } = await res.json();
if (!data?.token) return null;
_ticket = data.token;
_ticketExpEpoch = now + (Number(data.expiresIn) || 600);
return _ticket;
} catch {
return null;
}
}
const LIST_POLL_MS = 20_000; // presence + unread refresh while the panel is open
const THREAD_POLL_MS = 5_000; // open-thread refresh — backstop for the live push
export class FriendsClient {
constructor() {
this.friends = [];
this.incoming = [];
this.outgoing = [];
this.threads = new Map(); // friendId → [{id, from, to, body, ts, mine, read}]
this.openWith = null; // friendId of the thread currently shown, or null
this.loaded = false;
this.loadError = null;
this._listeners = new Set();
this._listTimer = null;
this._threadTimer = null;
this._active = false; // panel is open → poll
}
// ── subscription ───────────────────────────────────────────────────────
subscribe(fn) {
this._listeners.add(fn);
return () => this._listeners.delete(fn);
}
_emit() {
for (const fn of this._listeners) {
try {
fn(this);
} catch (e) {
log.error('[friends] listener threw:', e);
}
}
}
// Total unread across all friends — for the HUD badge.
get totalUnread() {
return this.friends.reduce((n, f) => n + (f.unread || 0), 0);
}
friend(id) {
return this.friends.find((f) => f.id === id) || null;
}
// ── lifecycle ────────────────────────────────────────────────────────────
// Called when the panel opens: load fresh and begin light polling for
// presence + unread changes. Idempotent.
activate() {
this._active = true;
this.refresh();
if (!this._listTimer) this._listTimer = setInterval(() => this.refresh(), LIST_POLL_MS);
}
// Called when the panel closes: stop polling. State is retained so reopening
// is instant; live events still arrive via handleSocial while closed.
deactivate() {
this._active = false;
this._stopListPoll();
this._stopThreadPoll();
}
_stopListPoll() {
if (this._listTimer) {
clearInterval(this._listTimer);
this._listTimer = null;
}
}
_stopThreadPoll() {
if (this._threadTimer) {
clearInterval(this._threadTimer);
this._threadTimer = null;
}
}
// ── graph ─────────────────────────────────────────────────────────────────
async refresh() {
if (!isAuthedHint()) {
// Same outcome as a 401, minus the network round-trip on every poll.
this.loadError = 'signin';
this.loaded = true;
this._emit();
return;
}
try {
const res = await apiFetch('/api/friends', { allowAnonymous: true });
if (res.status === 401) {
this.loadError = 'signin';
this.loaded = true;
this._emit();
return;
}
if (!res.ok) throw new Error(`friends ${res.status}`);
const { data } = await res.json();
const sig = graphSignature(data);
const first = !this.loaded;
// Coming back from a failed read is a repaint even when the graph is
// byte-identical to the last good one: the panel is showing an error
// card, and the signature check alone would leave it there forever
// because nothing about the data changed. Recovery is a state change.
const recovered = this.loadError === 'network';
this.friends = data.friends || [];
this.incoming = data.incoming || [];
this.outgoing = data.outgoing || [];
this.loaded = true;
this.loadError = null;
// Only repaint when something actually changed — a 20s presence/unread
// poll that returns identical state must not rebuild the panel (and reset
// a half-typed search / DM caret).
if (first || recovered || sig !== this._graphSig) {
this._graphSig = sig;
this._emit();
}
return;
} catch (err) {
this.loadError = 'network';
this.loaded = true;
log.warn('[friends] refresh failed:', err?.message);
}
this._emit();
}
async search(q) {
const term = String(q || '').trim();
if (term.length < 2) return [];
try {
const res = await apiFetch(`/api/friends/search?q=${encodeURIComponent(term)}`, {
allowAnonymous: true,
});
if (!res.ok) return [];
const { data } = await res.json();
return data.results || [];
} catch {
return [];
}
}
async _action(action, userId) {
const res = await apiFetch('/api/friends', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ action, userId }),
});
if (!res.ok) {
const body = await res.json().catch(() => ({}));
const err = new Error(body.error_description || 'request failed');
err.code = body.error;
throw err;
}
const { data } = await res.json();
await this.refresh();
return data;
}
sendRequest(userId) {
return this._action('request', userId);
}
accept(userId) {
return this._action('accept', userId);
}
decline(userId) {
return this._action('decline', userId);
}
remove(userId) {
return this._action('remove', userId);
}
mute(userId) {
return this._action('mute', userId);
}
unmute(userId) {
return this._action('unmute', userId);
}
// ── DM threads ────────────────────────────────────────────────────────────
async openThread(friendId) {
this.openWith = friendId;
await this.loadThread(friendId);
// Opening a thread reads it server-side; reflect that locally.
const f = this.friend(friendId);
if (f && f.unread) {
f.unread = 0;
this._emit();
}
this._stopThreadPoll();
if (this._active) {
this._threadTimer = setInterval(() => this.loadThread(friendId, { quiet: true }), THREAD_POLL_MS);
}
}
closeThread() {
this.openWith = null;
this._stopThreadPoll();
this._emit();
}
async loadThread(friendId, { quiet = false } = {}) {
try {
const res = await apiFetch(`/api/friends/messages?with=${encodeURIComponent(friendId)}`, {
allowAnonymous: true,
});
if (!res.ok) throw new Error(`thread ${res.status}`);
const { data } = await res.json();
const next = data.messages || [];
const prev = this.threads.get(friendId) || [];
const changed = next.length !== prev.length || next[next.length - 1]?.id !== prev[prev.length - 1]?.id;
this.threads.set(friendId, next);
// A quiet poll that found no new messages must not repaint — otherwise the
// open composer rebuilds every few seconds and steals the caret.
if (changed || !quiet) this._emit();
} catch (err) {
if (!quiet) log.warn('[friends] thread load failed:', err?.message);
}
}
// Send a DM. Optimism is avoided on purpose: the server enforces friendship,
// mutes, length, and rate limits, so we surface its result rather than
// guessing. The sent message is appended on success.
async sendDM(friendId, body) {
const text = String(body || '').trim();
if (!text) return;
const res = await apiFetch('/api/friends/messages', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ to: friendId, body: text }),
});
if (!res.ok) {
const b = await res.json().catch(() => ({}));
const err = new Error(b.error_description || 'could not send');
err.code = b.error;
throw err;
}
const { data } = await res.json();
if (data.message) {
const thread = this.threads.get(friendId) || [];
thread.push({ ...data.message, mine: true, read: true });
this.threads.set(friendId, thread);
this._emit();
}
return data;
}
// ── realtime ────────────────────────────────────────────────────────────
// Route a 'social' message forwarded from the realm-room socket. Live DMs are
// appended to the right thread (or bump the unread badge); friend-graph events
// trigger a refresh so requests/lists update without the user reopening.
handleSocial(msg) {
if (!msg || typeof msg !== 'object') return;
switch (msg.type) {
case 'dm': {
const m = msg.message;
if (!m) return;
const friendId = m.from;
const thread = this.threads.get(friendId) || [];
// Guard against the live push racing a poll that already fetched it.
if (!thread.some((x) => x.id === m.id)) {
thread.push({ ...m, mine: false, read: this.openWith === friendId });
this.threads.set(friendId, thread);
}
if (this.openWith === friendId) {
// Reading it now — clear server-side unread too.
this.loadThread(friendId, { quiet: true });
} else {
const f = this.friend(friendId);
if (f) f.unread = (f.unread || 0) + 1;
}
this._emit();
break;
}
case 'friend_request':
case 'friend_accept':
this.refresh();
break;
default:
break;
}
}
}
// Compact fingerprint of the graph payload so refresh() can skip a repaint when
// a poll returns identical state (presence, realm, unread, and membership).
function graphSignature(data) {
const f = (data.friends || []).map((x) => `${x.id}:${x.online ? 1 : 0}:${x.realm || ''}:${x.unread || 0}`).join('|');
const i = (data.incoming || []).map((x) => x.id).join('|');
const o = (data.outgoing || []).map((x) => x.id).join('|');
return `${f}#${i}#${o}`;
}
// One shared client per page — the panel and the net wiring both reference it.
let _client = null;
export function friendsClient() {
if (!_client) _client = new FriendsClient();
return _client;
}