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.

15.1 KB
Raw Blame
// 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 };