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
// Internal helper: publish to X on behalf of a three.ws user.
// Handles: tier-aware quota, token refresh, dedup, cadence guard, threads,
// optional link-back, and post logging.
import { sql } from './db.js';
import { env } from './env.js';
import { encryptToken, decryptToken } from '../auth/x/[action].js';
import { X_POST_REQUIRED_SCOPES, missingScopes } from './x-scopes.js';
import { fetchUpstream } from './upstream-fetch.js';
// Every X call shares one breaker ('x:post') so a dead X API fails fast
// instead of paying a deadline per step, and each step gets its own deadline.
// The media flow is up to six sequential calls (INIT, APPENDs, FINALIZE,
// STATUS polls) so it also carries one overall budget, passed as the caller
// signal that fetchUpstream composes with the per-call timeout.
const X_BREAKER = 'x:post';
const X_TOKEN_TIMEOUT_MS = 10_000;
const X_TWEET_TIMEOUT_MS = 15_000;
const X_MEDIA_STEP_TIMEOUT_MS = 30_000;
export const X_MEDIA_TOTAL_TIMEOUT_MS = 90_000;
export const FREE_MONTHLY_QUOTA = 5;
export const PRO_MONTHLY_QUOTA = 100;
export const MAX_TWEET_LEN = 280;
export const DEDUP_WINDOW_DAYS = 7;
export const FREE_MIN_INTERVAL = 30; // minutes between posts
export const PRO_MIN_INTERVAL = 5;
class XPostError extends Error {
constructor(code, message, status = 400, extra = {}) {
super(message);
this.code = code;
this.status = status;
this.extra = extra;
}
}
export async function getUserTier(userId) {
const r = await sql`
select plan, active_until from subscriptions
where user_id = ${userId} and status = 'active' and active_until > now()
limit 1
`;
if (!r.length) return { tier: 'free', quota: FREE_MONTHLY_QUOTA, min_interval_min: FREE_MIN_INTERVAL };
return {
tier: r[0].plan,
active_until: r[0].active_until,
quota: PRO_MONTHLY_QUOTA,
min_interval_min: PRO_MIN_INTERVAL,
};
}
export async function refreshIfNeeded(conn) {
const expiresAt = conn.expires_at ? new Date(conn.expires_at).getTime() : 0;
if (expiresAt - Date.now() > 60_000) return decryptToken(conn.access_token);
if (!conn.refresh_token) throw new XPostError('reauth_required', 'refresh_token missing, reconnect X account', 401);
const refreshToken = decryptToken(conn.refresh_token);
const creds = Buffer.from(`${env.X_OAUTH_CLIENT_ID}:${env.X_OAUTH_CLIENT_SECRET}`).toString('base64');
const r = await fetchUpstream('https://api.twitter.com/2/oauth2/token', {
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded', authorization: `Basic ${creds}` },
body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: env.X_OAUTH_CLIENT_ID }).toString(),
}, { name: X_BREAKER, timeoutMs: X_TOKEN_TIMEOUT_MS, attempts: 1, okWhen: () => true });
if (!r.ok) throw new XPostError('reauth_required', `X token refresh failed: ${await r.text()}`, 401);
const tok = await r.json();
const newExpiresAt = new Date(Date.now() + (tok.expires_in ?? 7200) * 1000).toISOString();
const access = encryptToken(tok.access_token);
const refresh = tok.refresh_token ? encryptToken(tok.refresh_token) : conn.refresh_token;
if (conn.source === 'agent') {
await sql`
update agent_x_connections
set access_token = ${access}, refresh_token = ${refresh}, expires_at = ${newExpiresAt}, updated_at = now()
where agent_id = ${conn.agent_id}
`;
} else {
await sql`
update social_connections
set access_token = ${access}, refresh_token = ${refresh}, expires_at = ${newExpiresAt}, updated_at = now()
where id = ${conn.id}
`;
}
return tok.access_token;
}
export async function postOne({ accessToken, text, replyTo, mediaIds = null }) {
const body = {};
if (text) body.text = text;
if (replyTo) body.reply = { in_reply_to_tweet_id: replyTo };
if (mediaIds && mediaIds.length) body.media = { media_ids: mediaIds };
const r = await fetchUpstream('https://api.twitter.com/2/tweets', {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${accessToken}` },
body: JSON.stringify(body),
}, { name: X_BREAKER, timeoutMs: X_TWEET_TIMEOUT_MS, attempts: 1, okWhen: () => true });
if (!r.ok) throw new XPostError('tweet_failed', `X API error: ${(await r.text()).slice(0, 200)}`, 502);
return (await r.json()).data;
}
// Chunked upload of a screenshot / clip to X's v2 media endpoint, returning the
// media_id to attach to a tweet. Single endpoint, command-driven (INIT → APPEND
// → FINALIZE → STATUS), authenticated with the connected user's OAuth2 token —
// which must carry the `media.write` scope (granted on connect, see auth/x).
// Video is processed asynchronously, so we poll STATUS until it succeeds.
const X_MEDIA_UPLOAD_URL = 'https://api.x.com/2/media/upload';
const X_MEDIA_CHUNK_BYTES = 4 * 1024 * 1024; // 4 MB — X's per-APPEND ceiling
function mediaCategoryFor(mimeType) {
if (mimeType.startsWith('video/')) return 'tweet_video';
if (mimeType === 'image/gif') return 'tweet_gif';
return 'tweet_image';
}
export async function uploadMediaV2({ accessToken, buffer, mimeType, deadlineMs = X_MEDIA_TOTAL_TIMEOUT_MS }) {
const overall = new AbortController();
const timer = setTimeout(() => overall.abort(), deadlineMs);
try {
return await uploadMediaSteps({ accessToken, buffer, mimeType, signal: overall.signal });
} catch (err) {
if (err instanceof XPostError) throw err;
if (overall.signal.aborted) {
throw new XPostError('media_upload_failed', `media upload exceeded its ${Math.round(deadlineMs / 1000)}s budget`, 504);
}
throw new XPostError('media_upload_failed', `media upload failed: ${err?.message || err}`, 502);
} finally {
clearTimeout(timer);
}
}
async function uploadMediaSteps({ accessToken, buffer, mimeType, signal }) {
const total = buffer.length;
const auth = { authorization: `Bearer ${accessToken}` };
const step = { name: X_BREAKER, timeoutMs: X_MEDIA_STEP_TIMEOUT_MS, attempts: 2, okWhen: () => true };
const initForm = new FormData();
initForm.set('command', 'INIT');
initForm.set('media_type', mimeType);
initForm.set('total_bytes', String(total));
initForm.set('media_category', mediaCategoryFor(mimeType));
const initRes = await fetchUpstream(X_MEDIA_UPLOAD_URL, { method: 'POST', headers: auth, body: initForm, signal }, step);
if (!initRes.ok)
throw new XPostError('media_upload_failed', `media INIT failed: ${(await initRes.text()).slice(0, 200)}`, 502);
const initJson = await initRes.json();
const mediaId = initJson?.data?.id || initJson?.data?.media_id_string || initJson?.media_id_string;
if (!mediaId) throw new XPostError('media_upload_failed', 'media INIT returned no id', 502);
let segment = 0;
for (let offset = 0; offset < total; offset += X_MEDIA_CHUNK_BYTES) {
const chunk = buffer.subarray(offset, Math.min(offset + X_MEDIA_CHUNK_BYTES, total));
const appendForm = new FormData();
appendForm.set('command', 'APPEND');
appendForm.set('media_id', mediaId);
appendForm.set('segment_index', String(segment));
appendForm.set('media', new Blob([chunk], { type: 'application/octet-stream' }), 'chunk');
const appendRes = await fetchUpstream(X_MEDIA_UPLOAD_URL, { method: 'POST', headers: auth, body: appendForm, signal }, step);
if (!appendRes.ok)
throw new XPostError('media_upload_failed', `media APPEND ${segment} failed: ${(await appendRes.text()).slice(0, 200)}`, 502);
segment++;
}
const finalizeForm = new FormData();
finalizeForm.set('command', 'FINALIZE');
finalizeForm.set('media_id', mediaId);
const finalizeRes = await fetchUpstream(X_MEDIA_UPLOAD_URL, { method: 'POST', headers: auth, body: finalizeForm, signal }, step);
if (!finalizeRes.ok)
throw new XPostError('media_upload_failed', `media FINALIZE failed: ${(await finalizeRes.text()).slice(0, 200)}`, 502);
const finalizeJson = await finalizeRes.json();
let info = finalizeJson?.data?.processing_info || finalizeJson?.processing_info || null;
// Async transcode (video): poll STATUS until the asset is ready or fails.
let tries = 0;
while (info && (info.state === 'pending' || info.state === 'in_progress') && tries < 30 && !signal.aborted) {
await new Promise((r) => setTimeout(r, Math.min((info.check_after_secs || 1) * 1000, 5000)));
if (signal.aborted) break;
const statusRes = await fetchUpstream(`${X_MEDIA_UPLOAD_URL}?command=STATUS&media_id=${mediaId}`, { headers: auth, signal }, step);
if (!statusRes.ok) break;
const statusJson = await statusRes.json();
info = statusJson?.data?.processing_info || statusJson?.processing_info || null;
tries++;
}
if (info && info.state === 'failed')
throw new XPostError('media_processing_failed', info?.error?.message || 'media processing failed', 502);
return mediaId;
}
/**
* The X account a post goes out through. An agent with its own connected
* account (agent_x_connections) posts as itself; every other post uses the
* owner's account (social_connections). `source` tells the write paths which
* table the counters and refreshed tokens belong to.
*/
export async function resolveXConnection({ userId, agentId = null }) {
if (agentId) {
const [own] = await sql`
select agent_id, user_id, provider_uid, username, access_token, refresh_token, expires_at,
scopes, posts_this_month, month_resets_at, last_posted_at, connected_at
from agent_x_connections
where agent_id = ${agentId} and user_id = ${userId} and disconnected_at is null
limit 1
`;
if (own) return { ...own, source: 'agent' };
}
const [owner] = await sql`
select * from social_connections
where user_id = ${userId} and provider = 'x' and disconnected_at is null
limit 1
`;
return owner ? { ...owner, source: 'owner' } : null;
}
async function resetMonthIfDue(conn) {
if (new Date(conn.month_resets_at) > new Date()) return;
if (conn.source === 'agent') {
await sql`
update agent_x_connections
set posts_this_month = 0, month_resets_at = date_trunc('month', now()) + interval '1 month'
where agent_id = ${conn.agent_id}
`;
} else {
await sql`
update social_connections
set posts_this_month = 0, month_resets_at = date_trunc('month', now()) + interval '1 month'
where id = ${conn.id}
`;
}
conn.posts_this_month = 0;
}
async function recordPostedCount(conn, count) {
if (conn.source === 'agent') {
await sql`
update agent_x_connections
set posts_this_month = posts_this_month + ${count}, last_posted_at = now(), updated_at = now()
where agent_id = ${conn.agent_id}
`;
} else {
await sql`
update social_connections
set posts_this_month = posts_this_month + ${count}, last_posted_at = now(), updated_at = now()
where id = ${conn.id}
`;
}
}
// Publish a single tweet (text) or a thread (threadParts).
// Counts each tweet against the user's monthly quota.
// Optionally appends a link to https://three.ws/avatars/<agentId> on the final tweet.
export async function publishTweet({ userId, agentId = null, kind = null, text, threadParts = null, replyTo = null, appendLink = false, mediaBuffer = null, mediaMimeType = null }) {
if (!env.X_OAUTH_CLIENT_ID || !env.X_OAUTH_CLIENT_SECRET) {
throw new XPostError('not_configured', 'X OAuth is not configured', 501);
}
const hasMedia = mediaBuffer && mediaBuffer.length > 0 && mediaMimeType;
const parts = Array.isArray(threadParts) && threadParts.length
? threadParts.map((s) => String(s || '').trim()).filter(Boolean)
: [String(text || '').trim()].filter(Boolean);
if (!parts.length) throw new XPostError('validation_error', 'text required', 400);
for (const p of parts) {
if (p.length > MAX_TWEET_LEN) throw new XPostError('validation_error', `each tweet must be ≤${MAX_TWEET_LEN} chars`, 400);
}
const tier = await getUserTier(userId);
const conn = await resolveXConnection({ userId, agentId });
if (!conn) throw new XPostError('not_connected', 'X account not connected', 400);
// A connection made for memory seeding only carries read scopes. Say so, and
// point at the reconnect that fixes it, instead of spending the user's quota
// check and cadence guard on a call X will reject as unauthorized.
const missingWrite = missingScopes(conn.scopes, X_POST_REQUIRED_SCOPES);
if (missingWrite.length) {
throw new XPostError(
'insufficient_scope',
'this X connection is read-only; reconnect X with posting access to publish',
400,
{
missing_scopes: missingWrite,
connect_url:
conn.source === 'agent'
? `/api/auth/x/connect?scope=full&target=agent&agent_id=${encodeURIComponent(agentId)}`
: '/api/auth/x/connect?scope=full',
},
);
}
// Reset monthly counter if month boundary crossed.
await resetMonthIfDue(conn);
if (conn.posts_this_month + parts.length > tier.quota) {
throw new XPostError('quota_exceeded', `${tier.tier} tier limit of ${tier.quota} posts/month reached`, 402, {
posts_used: conn.posts_this_month,
quota: tier.quota,
tier: tier.tier,
month_resets_at: conn.month_resets_at,
upgrade_url: '/pricing',
});
}
// Cadence guard.
if (conn.last_posted_at) {
const elapsedMin = (Date.now() - new Date(conn.last_posted_at).getTime()) / 60_000;
if (elapsedMin < tier.min_interval_min) {
const wait = Math.ceil(tier.min_interval_min - elapsedMin);
throw new XPostError('rate_limited', `please wait ${wait} more min before posting again`, 429, {
retry_after_minutes: wait,
tier: tier.tier,
upgrade_url: tier.tier === 'free' ? '/pricing' : undefined,
});
}
}
// Dedup on first part of thread. Skipped for media posts: a user sharing
// several distinct screenshots / clips of the same avatar reuses the same
// caption legitimately, so identical text alone must not block them.
if (!hasMedia) {
const head = parts[0];
const dup = await sql`
select 1 from x_posts
where user_id = ${userId} and text = ${head}
and created_at > now() - ${`${DEDUP_WINDOW_DAYS} days`}::interval
limit 1
`;
if (dup.length) throw new XPostError('duplicate', `same text posted within the last ${DEDUP_WINDOW_DAYS} days`, 409);
}
// Append link-back to agent page on final tweet (if it fits).
if (appendLink && agentId) {
const link = `https://three.ws/avatars/${agentId}`;
const last = parts[parts.length - 1];
if (!last.includes(link)) {
const candidate = `${last}\n\n${link}`;
if (candidate.length <= MAX_TWEET_LEN) parts[parts.length - 1] = candidate;
}
}
const accessToken = await refreshIfNeeded(conn);
// Upload media once and attach to the first (head) tweet only.
const mediaIds = hasMedia
? [await uploadMediaV2({ accessToken, buffer: mediaBuffer, mimeType: mediaMimeType })]
: null;
const published = [];
let prevId = replyTo;
for (let i = 0; i < parts.length; i++) {
const part = parts[i];
const d = await postOne({ accessToken, text: part, replyTo: prevId, mediaIds: i === 0 ? mediaIds : null });
published.push(d);
await sql`
insert into x_posts (user_id, agent_id, tweet_id, text, reply_to_tweet_id, kind)
values (${userId}, ${agentId}, ${d.id}, ${part}, ${prevId}, ${kind})
`;
prevId = d.id;
}
await recordPostedCount(conn, published.length);
const head0 = published[0];
return {
tweet_id: head0.id,
url: `https://x.com/${conn.username}/status/${head0.id}`,
username: conn.username,
account: conn.source,
thread: published.length > 1 ? published.map((p) => p.id) : undefined,
posts_used: conn.posts_this_month + published.length,
quota: tier.quota,
tier: tier.tier,
};
}
export { XPostError };