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.

18.2 KB
Raw Blame
// Self-serve plan changes: quotes, checkouts, confirmation and receipts.
//
// An upgrade is priced pro rata: the difference between the two plans' prices
// times the fraction of the current period still ahead, so moving up on day 20
// of 30 costs a third of the difference. Coming from Free starts a fresh
// 30-day period at the full price. A renewal extends the period by 30 days at
// the full price. A downgrade is never charged: it is scheduled and takes
// effect when the period ends (scheduleDevPlanChange).
//
// Three ways to pay:
//   credits  debited from the account balance in the same request.
//   USDC     the user's own wallet signs a transfer this module builds.
//   THREE    the same, at the discount the plan config sets.
// The server never signs anything. For a wallet payment the checkout holds the
// exact recipient, amount and asset the user is shown before they sign, and
// confirmation reads the landed transaction back from the chain.

import { PublicKey, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
import {
	TOKEN_PROGRAM_ID,
	ASSOCIATED_TOKEN_PROGRAM_ID,
	getAssociatedTokenAddressSync,
	createAssociatedTokenAccountIdempotentInstruction,
	createTransferCheckedInstruction,
} from '@solana/spl-token';
import { sql } from '../db.js';
import { debitCredits } from '../credits.js';
import { insertNotification } from '../notify.js';
import { sendEmail } from '../email.js';
import { logAudit } from '../audit.js';
import { getTokenPriceUsd } from '../token/price.js';
import { usdToUsdcAtomics } from '../subscription-pricing.js';
import { assetConfig, treasuryWallet, assertWallet, verifyPassPayment } from '../premium.js';
import { solanaConnection } from '../solana/connection.js';
import { blockhashKey, getRecentBlockhashInfo } from '../solana/read-guards.js';
import {
	DEFAULT_DEV_PLAN_ID,
	DEV_PLAN_PERIOD_MS,
	DEV_PLAN_PAY_ASSETS,
	DEV_PLAN_MANAGE_URL,
	devPlanById,
	threeDiscountBps,
} from './config.js';
import { getDevSubscription, setDevSubscription, scheduleDevPlan, invalidateDevSubscription } from './subscription.js';

export const DEV_PLAN_CHECKOUT_TTL_MS = 10 * 60_000;
const SIG_RE = /^[1-9A-HJ-NP-Za-km-z]{64,96}$/;

function fail(status, code, message, extra = {}) {
	return Object.assign(new Error(message), { status, code, expose: true, ...extra });
}

function cents(n) {
	return Math.round(n * 100) / 100;
}

function assertAsset(asset) {
	if (!DEV_PLAN_PAY_ASSETS.includes(asset)) throw fail(400, 'bad_asset', `asset must be one of: ${DEV_PLAN_PAY_ASSETS.join(', ')}`);
	return asset;
}

/**
 * Price a move to `planId` for the account's current subscription. Pure given
 * the subscription, so the dashboard can show the exact number before any
 * checkout exists.
 */
export function quoteDevPlanChange(sub, planId, asset = 'credits', now = new Date()) {
	assertAsset(asset);
	const target = devPlanById(planId);
	const current = sub.plan;
	if (!target.purchasable) throw fail(400, 'not_purchasable', `the ${target.name} plan cannot be bought here`);
	if (target.rank < current.rank) throw fail(400, 'downgrade_not_charged', 'a downgrade is scheduled for the end of the period, not bought; use the schedule endpoint');
	const periodStart = sub.periodStart.getTime();
	const periodEnd = sub.periodEnd.getTime();
	const nowMs = now.getTime();
	let kind;
	let amountUsd;
	let nextStart;
	let nextEnd;
	let remainingFraction = null;
	if (target.rank === current.rank) {
		kind = 'renew';
		amountUsd = target.priceUsd;
		nextStart = new Date(periodEnd);
		nextEnd = new Date(periodEnd + DEV_PLAN_PERIOD_MS);
	} else if (current.priceUsd === 0) {
		kind = 'upgrade';
		amountUsd = target.priceUsd;
		nextStart = now;
		nextEnd = new Date(nowMs + DEV_PLAN_PERIOD_MS);
	} else {
		kind = 'upgrade';
		remainingFraction = Math.min(1, Math.max(0, (periodEnd - nowMs) / (periodEnd - periodStart)));
		amountUsd = (target.priceUsd - current.priceUsd) * remainingFraction;
		nextStart = sub.periodStart;
		nextEnd = sub.periodEnd;
	}
	const discountBps = asset === 'THREE' ? threeDiscountBps() : 0;
	const listUsd = cents(amountUsd);
	amountUsd = cents(amountUsd * (1 - discountBps / 10_000));
	return {
		kind,
		asset,
		plan: target,
		from: current.id,
		amountUsd,
		listUsd,
		discountBps,
		remainingFraction,
		periodStart: nextStart,
		periodEnd: nextEnd,
		renewWith: asset,
	};
}

async function priceInAsset(asset, amountUsd) {
	if (asset === 'credits') return { atomics: null, assetUsd: null, priceSource: 'credits' };
	if (asset === 'USDC') return { atomics: BigInt(usdToUsdcAtomics(amountUsd)), assetUsd: null, priceSource: 'parity' };
	const { priceUsd, source } = await getTokenPriceUsd({});
	if (!Number.isFinite(priceUsd) || priceUsd <= 0) throw fail(503, 'price_unavailable', '$THREE price unavailable right now; pay in USDC or credits, or retry shortly');
	const { decimals } = assetConfig('THREE');
	return { atomics: BigInt(Math.ceil((amountUsd / priceUsd) * 10 ** decimals)), assetUsd: priceUsd, priceSource: source };
}

async function buildTransferTx({ wallet, asset, atomics, payTo }) {
	const { mint, decimals } = assetConfig(asset);
	const buyer = new PublicKey(wallet);
	const dest = new PublicKey(payTo);
	const mintKey = new PublicKey(mint);
	const fromAta = getAssociatedTokenAddressSync(mintKey, buyer, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
	const toAta = getAssociatedTokenAddressSync(mintKey, dest, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
	const instructions = [
		createAssociatedTokenAccountIdempotentInstruction(buyer, toAta, dest, mintKey, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID),
		createTransferCheckedInstruction(fromAta, mintKey, toAta, buyer, atomics, decimals, [], TOKEN_PROGRAM_ID),
	];
	const conn = solanaConnection();
	const { blockhash } = await getRecentBlockhashInfo(conn, blockhashKey({ network: 'mainnet' }));
	const message = new TransactionMessage({ payerKey: buyer, recentBlockhash: blockhash, instructions }).compileToV0Message();
	return Buffer.from(new VersionedTransaction(message).serialize()).toString('base64');
}

function publicCheckout(row) {
	return {
		id: row.id,
		plan: row.plan_id,
		kind: row.kind,
		asset: row.asset,
		wallet: row.wallet,
		pay_to: row.pay_to,
		chain: row.asset === 'credits' ? null : 'solana',
		amount_usd: Number(row.amount_usd),
		amount_atomics: row.amount_atomics == null ? null : String(row.amount_atomics),
		asset_usd: row.asset_usd == null ? null : Number(row.asset_usd),
		period_start: row.period_start,
		period_end: row.period_end,
		status: row.status,
		tx_signature: row.tx_signature,
		expires_at: row.expires_at,
		created_at: row.created_at,
	};
}

export function publicReceipt(row) {
	return {
		id: row.id,
		checkout_id: row.checkout_id,
		plan: row.plan_id,
		kind: row.kind,
		asset: row.asset,
		amount_usd: Number(row.amount_usd),
		amount_atomics: row.amount_atomics == null ? null : String(row.amount_atomics),
		tx_signature: row.tx_signature,
		ledger_id: row.ledger_id,
		period_start: row.period_start,
		period_end: row.period_end,
		created_at: row.created_at,
	};
}

/**
 * Open a checkout. Credits settle immediately and the result carries the
 * receipt. A wallet asset returns the unsigned transfer for the user to sign,
 * together with the recipient, amount and asset it moves.
 */
export async function createDevPlanCheckout({ userId, planId, asset, wallet = null, req = null }) {
	assertAsset(asset);
	const sub = await getDevSubscription(userId, { fresh: true });
	const quote = quoteDevPlanChange(sub, planId, asset);
	if (asset !== 'credits') assertWallet(wallet);
	let payTo = null;
	if (asset !== 'credits') {
		try {
			payTo = treasuryWallet();
			assetConfig(asset);
		} catch (err) {
			throw fail(503, 'payments_not_configured', `${asset} payments are not available right now; pay with credits or try again shortly`);
		}
	}
	const priced = await priceInAsset(asset, quote.amountUsd);
	const expiresAt = new Date(Date.now() + DEV_PLAN_CHECKOUT_TTL_MS).toISOString();

	sql`delete from dev_plan_checkouts where status = 'pending' and expires_at < now() - interval '7 days'`.catch(() => {});

	const [row] = await sql`
		insert into dev_plan_checkouts
			(user_id, plan_id, kind, asset, wallet, pay_to, amount_usd, amount_atomics, asset_usd, price_source, period_start, period_end, expires_at)
		values
			(${userId}, ${quote.plan.id}, ${quote.kind}, ${asset}, ${wallet}, ${payTo}, ${quote.amountUsd},
			 ${priced.atomics == null ? null : priced.atomics.toString()}, ${priced.assetUsd}, ${priced.priceSource},
			 ${quote.periodStart.toISOString()}, ${quote.periodEnd.toISOString()}, ${expiresAt})
		returning *
	`;

	if (asset === 'credits') {
		let ledgerId = null;
		if (quote.amountUsd > 0) {
			try {
				const debit = await debitCredits({
					userId,
					amountUsd: quote.amountUsd,
					action: `dev_plan_${quote.kind}`,
					refType: 'dev_plan_checkout',
					refId: row.id,
					idempotencyKey: `devplan:checkout:${row.id}`,
					meta: { plan: quote.plan.id, kind: quote.kind, from: quote.from },
				});
				ledgerId = debit.ledgerId || null;
			} catch (err) {
				await sql`update dev_plan_checkouts set status = 'failed' where id = ${row.id}`;
				if (err?.status === 402) {
					throw fail(402, 'insufficient_credits', `this ${quote.kind} costs $${quote.amountUsd.toFixed(2)} in credits and the balance is $${Number(err.available_usd ?? 0).toFixed(2)}`, {
						required_usd: quote.amountUsd,
						available_usd: Number(err.available_usd ?? 0),
						top_up_url: '/dashboard/billing',
					});
				}
				throw err;
			}
		}
		const receipt = await applyDevPlanCheckout(row, { ledgerId, req });
		return { checkout: publicCheckout({ ...row, status: 'paid' }), receipt, tx_base64: null };
	}

	const txBase64 = await buildTransferTx({ wallet, asset, atomics: priced.atomics, payTo });
	return { checkout: publicCheckout(row), receipt: null, tx_base64: txBase64 };
}

function receiptEmail({ plan, kind, asset, amountUsd, periodStart, periodEnd, txSignature }) {
	const verb = kind === 'renew' ? 'renewed' : 'upgraded to';
	const period = `${new Date(periodStart).toISOString().slice(0, 10)} to ${new Date(periodEnd).toISOString().slice(0, 10)}`;
	const subject = `Receipt: three.ws API ${plan.name} plan`;
	const text = [
		`Your developer API plan was ${verb} ${plan.name}.`,
		`Amount: $${amountUsd.toFixed(2)} paid in ${asset === 'THREE' ? '$THREE' : asset}.`,
		`Period: ${period}.`,
		`Included calls: ${plan.includedCalls.toLocaleString('en-US')} per period, ${plan.burstPerMinute.toLocaleString('en-US')} per minute, ${plan.concurrent} concurrent.`,
		txSignature ? `Transaction: https://solscan.io/tx/${txSignature}` : null,
		`Manage your plan: https://three.ws${DEV_PLAN_MANAGE_URL}`,
	].filter(Boolean).join('\n');
	const html = `<p>Your developer API plan was ${verb} <strong>${plan.name}</strong>.</p>
<p>Amount: <strong>$${amountUsd.toFixed(2)}</strong> paid in ${asset === 'THREE' ? '$THREE' : asset}.<br>Period: ${period}.</p>
<p>Included calls: ${plan.includedCalls.toLocaleString('en-US')} per period, ${plan.burstPerMinute.toLocaleString('en-US')} per minute, ${plan.concurrent} concurrent.</p>
${txSignature ? `<p>Transaction: <a href="https://solscan.io/tx/${txSignature}">${txSignature}</a></p>` : ''}
<p><a href="https://three.ws${DEV_PLAN_MANAGE_URL}">Manage your plan</a></p>`;
	return { subject, text, html };
}

/** Move the account onto the checkout's plan, write the receipt, tell the user. */
export async function applyDevPlanCheckout(checkout, { txSignature = null, ledgerId = null, req = null } = {}) {
	const plan = devPlanById(checkout.plan_id);
	const amountUsd = Number(checkout.amount_usd);
	await setDevSubscription(checkout.user_id, {
		planId: plan.id,
		periodStart: new Date(checkout.period_start),
		periodEnd: new Date(checkout.period_end),
		renewWith: checkout.asset,
		paidUsd: amountUsd,
	});
	const [receipt] = await sql`
		insert into dev_plan_receipts (user_id, checkout_id, plan_id, kind, asset, amount_usd, amount_atomics, tx_signature, ledger_id, period_start, period_end)
		values (${checkout.user_id}, ${checkout.id}, ${plan.id}, ${checkout.kind}, ${checkout.asset}, ${amountUsd},
			${checkout.amount_atomics == null ? null : String(checkout.amount_atomics)}, ${txSignature}, ${ledgerId},
			${checkout.period_start}, ${checkout.period_end})
		on conflict (checkout_id) do update set checkout_id = excluded.checkout_id
		returning *
	`;
	await sql`update dev_plan_checkouts set status = 'paid', tx_signature = coalesce(${txSignature}, tx_signature) where id = ${checkout.id}`;
	invalidateDevSubscription(checkout.user_id);
	logAudit({ userId: checkout.user_id, action: `dev_plan_${checkout.kind}`, resourceId: checkout.id, meta: { plan: plan.id, asset: checkout.asset, amount_usd: amountUsd }, req });
	insertNotification(checkout.user_id, 'dev_plan_changed', {
		plan: plan.id,
		kind: checkout.kind,
		amount_usd: amountUsd,
		asset: checkout.asset,
		period_end: checkout.period_end,
		manage_url: DEV_PLAN_MANAGE_URL,
	});
	try {
		const [u] = await sql`select email from users where id = ${checkout.user_id} limit 1`;
		if (u?.email && !u.email.endsWith('.invalid')) {
			const mail = receiptEmail({ plan, kind: checkout.kind, asset: checkout.asset, amountUsd, periodStart: checkout.period_start, periodEnd: checkout.period_end, txSignature });
			await sendEmail({ to: u.email, ...mail });
		}
	} catch (err) {
		console.warn('[dev-plans] receipt email failed:', err?.message);
	}
	return publicReceipt(receipt);
}

/**
 * Record a plan purchase that already settled over x402 (api/billing/agent-upgrade.js).
 * The payment is the proof, so there is no pending checkout to confirm: the row
 * is written as paid and the plan applied in one step. Idempotent on the
 * settlement signature, so a replayed paid retry returns the same receipt and
 * never extends the period twice.
 */
export async function recordX402DevPlanPayment({ userId, planId, payer, payTo = null, txSignature, amountAtomics, req = null }) {
	if (!txSignature) throw fail(500, 'settlement_missing', 'the payment settled without a transaction signature');
	const [existing] = await sql`select * from dev_plan_receipts where tx_signature = ${txSignature} and user_id = ${userId} limit 1`;
	if (existing) return publicReceipt(existing);
	const [taken] = await sql`select id from dev_plan_checkouts where tx_signature = ${txSignature} limit 1`;
	if (taken) throw fail(409, 'signature_already_used', 'this payment already funded a different plan change');
	const sub = await getDevSubscription(userId, { fresh: true });
	const quote = quoteDevPlanChange(sub, planId, 'USDC');
	const [row] = await sql`
		insert into dev_plan_checkouts
			(user_id, plan_id, kind, asset, wallet, pay_to, amount_usd, amount_atomics, price_source, period_start, period_end, status, tx_signature, expires_at)
		values
			(${userId}, ${quote.plan.id}, ${quote.kind}, 'USDC', ${payer || null}, ${payTo}, ${quote.amountUsd},
			 ${amountAtomics == null ? null : String(amountAtomics)}, 'x402', ${quote.periodStart.toISOString()}, ${quote.periodEnd.toISOString()},
			 'pending', ${txSignature}, now())
		returning *
	`;
	return applyDevPlanCheckout(row, { txSignature, req });
}

/**
 * Confirm a wallet checkout from its landed transaction. Idempotent: the same
 * signature always returns the same receipt. Returns { status: 'paid', receipt }
 * or { status: 'pending', reason } while the chain is still confirming.
 */
export async function confirmDevPlanCheckout({ userId, checkoutId, txSignature, req = null }) {
	if (!SIG_RE.test(String(txSignature || ''))) throw fail(400, 'bad_signature', 'tx_signature must be a base58 Solana transaction signature');
	const [existing] = await sql`select * from dev_plan_receipts where tx_signature = ${txSignature} and user_id = ${userId} limit 1`;
	if (existing) return { status: 'paid', receipt: publicReceipt(existing) };
	const [checkout] = await sql`select * from dev_plan_checkouts where id = ${checkoutId} and user_id = ${userId} limit 1`;
	if (!checkout) throw fail(404, 'not_found', 'checkout not found');
	if (checkout.status === 'paid') {
		const [receipt] = await sql`select * from dev_plan_receipts where checkout_id = ${checkout.id} limit 1`;
		return { status: 'paid', receipt: receipt ? publicReceipt(receipt) : null };
	}
	if (checkout.asset === 'credits') throw fail(400, 'not_a_wallet_checkout', 'a credits checkout settles when it is created');
	if (new Date(checkout.expires_at).getTime() + 30 * 60_000 < Date.now()) throw fail(410, 'checkout_expired', 'this checkout expired; open a new one and sign the new transfer');
	const [taken] = await sql`select id from dev_plan_checkouts where tx_signature = ${txSignature} and id <> ${checkout.id} limit 1`;
	if (taken) throw fail(409, 'signature_already_used', 'this transaction already paid for a different checkout');
	const verdict = await verifyPassPayment({ wallet: checkout.wallet, asset: checkout.asset, amount_atomics: checkout.amount_atomics }, txSignature);
	if (!verdict.ok) {
		if (verdict.pending) return { status: 'pending', reason: verdict.reason };
		throw fail(400, 'payment_not_verified', verdict.reason);
	}
	const receipt = await applyDevPlanCheckout(checkout, { txSignature, req });
	return { status: 'paid', receipt };
}

/**
 * Schedule a lower plan (or Free) for the end of the period, or clear a
 * scheduled change by naming the current plan.
 */
export async function scheduleDevPlanChange({ userId, planId, req = null }) {
	const sub = await getDevSubscription(userId, { fresh: true });
	const target = devPlanById(planId);
	if (target.rank > sub.plan.rank) throw fail(400, 'upgrade_is_bought', 'an upgrade takes effect now through a checkout, not a schedule');
	if (sub.plan.id === DEFAULT_DEV_PLAN_ID) throw fail(400, 'already_free', 'the account is on the Free plan; there is nothing to schedule');
	const scheduled = target.rank === sub.plan.rank ? null : target.id;
	const next = await scheduleDevPlan(userId, scheduled);
	logAudit({ userId, action: 'dev_plan_schedule', resourceId: userId, meta: { scheduled, from: sub.plan.id }, req });
	return next;
}

export async function listDevPlanReceipts(userId, limit = 50) {
	const rows = await sql`
		select * from dev_plan_receipts where user_id = ${userId}
		order by created_at desc limit ${Math.min(200, Math.max(1, limit))}
	`;
	return rows.map(publicReceipt);
}

export async function getDevPlanCheckout(userId, checkoutId) {
	const [row] = await sql`select * from dev_plan_checkouts where id = ${checkoutId} and user_id = ${userId} limit 1`;
	return row ? publicCheckout(row) : null;
}