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.

13.0 KB
Raw Blame
// @three-ws/names — ENS + SNS resolution, *.threews.sol subdomain minting, and
// pay-by-name. A thin client over the public /api/sns, /api/sns-subdomain,
// /api/threews/subdomain, /api/x402/pay-by-name, and /api/agents/ens endpoints.
// See README.md for the full reference.

import { createHttp, ThreeWsError } from './http.js';

export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';

// Matches the platform's name validators. `.eth` routes to the ENS resolver,
// everything else (a `.sol` domain or a bare label) routes to the .sol registry.
const ETH_RE = /^(?:[a-z0-9-]+\.)+eth$/i;
const SOL_NAME_RE = /^[a-z0-9-]{1,63}(?:\.[a-z0-9-]{1,63})*(?:\.sol)?$/i;
const ADDR_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const PAY_MODES = ['prep', 'send'];

/**
 * Create a Names client bound to a base URL, fetch, and optional auth.
 * For most callers the default exports (`resolve()`, `payByName()`, …) are
 * enough; use this to reuse configuration — a payment-aware fetch, a custom
 * origin, or a bearer token — across many calls.
 */
export function createNames(options = {}) {
	const request = createHttp(options);
	const defaultToken = options.apiKey || options.token || null;

	// A per-call bearer token overrides the client default. Both land in the
	// Authorization header the http core already understands.
	function authHeaders(token, extra) {
		const h = { ...(extra || {}) };
		const bearer = token || defaultToken;
		if (bearer) h.authorization = `Bearer ${bearer}`;
		return h;
	}

	/** Resolve a name to an address. `.eth` → ENS, `.sol`/bare label → SNS. */
	async function resolve(name, opts = {}) {
		const trimmed = String(name || '').trim();
		if (!trimmed) {
			throw new ThreeWsError('resolve() needs a non-empty name.', { code: 'invalid_input' });
		}
		if (ETH_RE.test(trimmed)) {
			const lower = trimmed.toLowerCase();
			let res;
			try {
				res = await request(`/api/agents/ens/${encodeURIComponent(lower)}`, { signal: opts.signal });
			} catch (err) {
				// An unregistered `.eth` is a routine answer, not a fault: the ENS
				// endpoint reports it as a 404 while the `.sol` lane reports the same
				// miss as `resolved: false` at 200. Normalize here so one `resolve()`
				// has one contract across both registries, and a caller never has to
				// try/catch to ask "does this name exist".
				if (err?.status === 404 && err?.code === 'not_found') {
					// `raw` stays the untouched wire body, here the 404 envelope, so a
					// caller can still see exactly what the registry said.
					return { ...shapeEns({ name: lower }), raw: err.body ?? null };
				}
				throw err;
			}
			return shapeEns(res);
		}
		if (!SOL_NAME_RE.test(trimmed)) {
			throw new ThreeWsError(
				`Invalid name "${trimmed}". Expected a .eth name, a .sol domain, or a bare [a-z0-9-] label.`,
				{ code: 'invalid_input' },
			);
		}
		const res = await request('/api/sns', {
			query: prune({ name: trimmed, domains: domainsFlag(opts) }),
			signal: opts.signal,
		});
		return shapeSns(res);
	}

	/** Find the primary `.sol` for a wallet. Wraps GET /api/sns?address=. */
	async function reverseLookup(address, opts = {}) {
		const addr = String(address || '').trim();
		if (!ADDR_RE.test(addr)) {
			throw new ThreeWsError('reverseLookup() needs a base58 Solana address.', { code: 'invalid_input' });
		}
		const res = await request('/api/sns', {
			query: prune({ address: addr, domains: domainsFlag(opts) }),
			signal: opts.signal,
		});
		return shapeSns(res);
	}

	/** Check whether `<label>.threews.sol` is free. Wraps GET /api/sns-subdomain?label=. */
	async function checkSubdomain(label, opts = {}) {
		const clean = String(label || '').trim();
		if (!clean) {
			throw new ThreeWsError('checkSubdomain() needs a label.', { code: 'invalid_input' });
		}
		const res = await request('/api/sns-subdomain', { query: { label: clean }, signal: opts.signal });
		return shapeAvailability(res);
	}

	/** Mint `<label>.threews.sol` for an agent. Wraps POST /api/sns-subdomain. Requires auth. */
	async function mintSubdomain(input = {}) {
		const agentId = typeof input.agentId === 'string' ? input.agentId.trim() : '';
		if (!agentId) {
			throw new ThreeWsError('mintSubdomain() needs an `agentId`.', { code: 'invalid_input' });
		}
		if (input.ownerAddress != null && !ADDR_RE.test(String(input.ownerAddress).trim())) {
			throw new ThreeWsError('ownerAddress must be a base58 Solana public key.', { code: 'invalid_input' });
		}
		if (input.space != null && !(Number.isInteger(input.space) && input.space >= 1000 && input.space <= 10000)) {
			throw new ThreeWsError('space must be an integer between 1000 and 10000.', { code: 'invalid_input' });
		}
		const body = prune({
			agent_id: agentId,
			label: input.label,
			owner_address: input.ownerAddress,
			space: input.space,
		});
		const res = await request('/api/sns-subdomain', {
			method: 'POST',
			body,
			headers: authHeaders(input.token, input.headers),
			signal: input.signal,
		});
		return shapeMint(res);
	}

	/** Claim `<username>.threews.sol` for the signed-in user. Wraps POST /api/threews/subdomain. */
	async function claimSubdomain(input = {}) {
		const label = typeof input.label === 'string' ? input.label.trim() : '';
		if (!label) {
			throw new ThreeWsError('claimSubdomain() needs a `label` (your username).', { code: 'invalid_input' });
		}
		if (input.ownerWallet != null && !ADDR_RE.test(String(input.ownerWallet).trim())) {
			throw new ThreeWsError('ownerWallet must be a base58 Solana public key.', { code: 'invalid_input' });
		}
		const body = prune({ label, owner_wallet: input.ownerWallet });
		const res = await request('/api/threews/subdomain', {
			method: 'POST',
			body,
			headers: authHeaders(input.token, input.headers),
			signal: input.signal,
		});
		return shapeClaim(res);
	}

	/** Drop the local `<label>.threews.sol` claim. Wraps DELETE /api/threews/subdomain. */
	async function releaseSubdomain(label, opts = {}) {
		const clean = String(label || '').trim();
		if (!clean) {
			throw new ThreeWsError('releaseSubdomain() needs a label.', { code: 'invalid_input' });
		}
		const res = await request('/api/threews/subdomain', {
			method: 'DELETE',
			query: { label: clean },
			headers: authHeaders(opts.token, opts.headers),
			signal: opts.signal,
		});
		return unwrap(res);
	}

	/** Resolve a payee by name (no payment). Wraps GET /api/x402/pay-by-name?name=. */
	async function resolvePayee(name, opts = {}) {
		const clean = String(name || '').trim();
		if (!clean) {
			throw new ThreeWsError('resolvePayee() needs a name.', { code: 'invalid_input' });
		}
		const res = await request('/api/x402/pay-by-name', { query: { name: clean }, signal: opts.signal });
		return shapePayee(unwrap(res));
	}

	/** Pay a recipient by name in USDC. Wraps POST /api/x402/pay-by-name. */
	async function payByName(name, amountUsdc, opts = {}) {
		const clean = String(name || '').trim();
		if (!clean) {
			throw new ThreeWsError('payByName() needs a name.', { code: 'invalid_input' });
		}
		const amount = Number(amountUsdc);
		if (!Number.isFinite(amount) || amount <= 0 || amount > 10000) {
			throw new ThreeWsError('amountUsdc must be a number > 0 and ≤ 10000.', { code: 'invalid_input' });
		}
		const mode = normalizeEnum(opts.mode, PAY_MODES, 'mode') || 'prep';

		if (mode === 'prep') {
			if (!opts.payerWallet || !ADDR_RE.test(String(opts.payerWallet).trim())) {
				throw new ThreeWsError('prep mode needs a base58 `payerWallet`.', { code: 'invalid_input' });
			}
		} else {
			if (!opts.agentId || typeof opts.agentId !== 'string') {
				throw new ThreeWsError('send mode needs an `agentId`.', { code: 'invalid_input' });
			}
		}

		const body = prune({
			name: clean,
			amount_usdc: amountUsdc,
			mode,
			payer_wallet: opts.payerWallet,
			agent_id: opts.agentId,
			expected_address: opts.expectedAddress,
			message: opts.message,
		});
		const res = await request('/api/x402/pay-by-name', {
			method: 'POST',
			body,
			headers: authHeaders(opts.token, opts.headers),
			signal: opts.signal,
		});
		return shapePay(unwrap(res), mode);
	}

	return {
		resolve,
		reverseLookup,
		checkSubdomain,
		mintSubdomain,
		claimSubdomain,
		releaseSubdomain,
		resolvePayee,
		payByName,
	};
}

// A module-level default client for the zero-config path: `import { resolve }`.
let shared = null;
function defaultClient() {
	return (shared ||= createNames());
}

/** Resolve a name to an address. `.eth` → ENS, `.sol`/bare label → SNS. */
export function resolve(name, opts) {
	return defaultClient().resolve(name, opts);
}
/** Find the primary `.sol` for a wallet. */
export function reverseLookup(address, opts) {
	return defaultClient().reverseLookup(address, opts);
}
/** Check whether `<label>.threews.sol` is free. */
export function checkSubdomain(label, opts) {
	return defaultClient().checkSubdomain(label, opts);
}
/** Mint `<label>.threews.sol` for an agent (requires auth). */
export function mintSubdomain(input) {
	return defaultClient().mintSubdomain(input);
}
/** Claim `<username>.threews.sol` for the signed-in user. */
export function claimSubdomain(input) {
	return defaultClient().claimSubdomain(input);
}
/** Drop the local `<label>.threews.sol` claim. */
export function releaseSubdomain(label, opts) {
	return defaultClient().releaseSubdomain(label, opts);
}
/** Resolve a payee by name (no payment). */
export function resolvePayee(name, opts) {
	return defaultClient().resolvePayee(name, opts);
}
/** Pay a recipient by name in USDC. */
export function payByName(name, amountUsdc, opts) {
	return defaultClient().payByName(name, amountUsdc, opts);
}

// ── shapers: snake_case envelopes → camelCase results, with a `.raw` escape hatch ──

// /api/sns answers in a { data: { … } } envelope; some endpoints answer bare.
function unwrap(res) {
	if (res && typeof res === 'object' && 'data' in res && res.data && typeof res.data === 'object') {
		return res.data;
	}
	return res;
}

// `allDomains` / `favoriteDomain` are only populated when the call asked for
// them with `{ domains: true }`; the endpoint omits both otherwise rather than
// paying for the SNS index lookup on every resolve.
function shapeSns(res) {
	const d = unwrap(res) || {};
	return {
		name: d.name ?? null,
		address: d.address ?? null,
		network: d.network || 'solana',
		resolved: Boolean(d.resolved),
		allDomains: Array.isArray(d.all_domains) ? d.all_domains : [],
		favoriteDomain: d.favorite_domain ?? null,
		domainsTruncated: Boolean(d.domains_truncated),
		raw: res,
	};
}

// The endpoint takes `domains=1`; anything falsy is left off the query entirely
// so the default resolve stays a single cache-friendly URL.
function domainsFlag(opts) {
	return opts && opts.domains ? '1' : undefined;
}

function shapeEns(res) {
	const d = res || {};
	const address = d.address ?? null;
	return {
		name: d.name ?? null,
		address,
		network: 'ethereum',
		resolved: Boolean(address),
		allDomains: [],
		favoriteDomain: null,
		domainsTruncated: false,
		agents: Array.isArray(d.agents) ? d.agents : [],
		raw: res,
	};
}

function shapeAvailability(res) {
	const d = unwrap(res) || {};
	return {
		label: d.label ?? null,
		parent: d.parent ?? null,
		fullName: d.full_name ?? d.full ?? null,
		available: Boolean(d.available),
		owner: d.owner ?? null,
		raw: res,
	};
}

function shapeMint(res) {
	const d = unwrap(res) || {};
	return {
		ok: Boolean(d.ok),
		agentId: d.agent_id ?? null,
		fullName: d.full_name ?? null,
		parent: d.parent ?? null,
		owner: d.owner ?? null,
		signature: d.signature ?? null,
		explorer: d.explorer ?? null,
		urlRecord: d.url_record ?? null,
		agentUrl: d.agent_url ?? null,
		raw: res,
	};
}

function shapeClaim(res) {
	const d = unwrap(res) || {};
	return {
		id: d.id ?? null,
		label: d.label ?? null,
		parent: d.parent ?? null,
		ownerWallet: d.owner_wallet ?? null,
		urlRecord: d.url_record ?? null,
		signature: d.signature ?? null,
		fullName: d.full ?? null,
		showcaseUrl: d.showcase_url ?? null,
		explorer: d.explorer ?? null,
		createdAt: d.created_at ?? null,
		raw: res,
	};
}

function shapePayee(d) {
	const v = d || {};
	return {
		name: v.resolved ?? null,
		address: v.address ?? null,
		source: v.source ?? null,
		resolved: v.resolved ?? null,
		claim: v.claim ?? null,
		raw: d,
	};
}

function shapePay(d, mode) {
	const v = d || {};
	if (mode === 'send') {
		return {
			mode: 'send',
			recipient: shapePayee(v.recipient),
			payer: v.payer ?? null,
			amountUsdc: v.amount_usdc ?? null,
			signature: v.signature ?? null,
			raw: d,
		};
	}
	return {
		mode: 'prep',
		recipient: shapePayee(v.recipient),
		amountUsdc: v.amount_usdc ?? null,
		txBase64: v.tx_base64 ?? null,
		blockhash: v.blockhash ?? null,
		lastValidBlockHeight: v.last_valid_block_height ?? null,
		mint: v.mint ?? null,
		raw: d,
	};
}

function normalizeEnum(value, allowed, label) {
	if (value === undefined || value === null) return undefined;
	if (!allowed.includes(value)) {
		throw new ThreeWsError(`Invalid ${label} "${value}". Expected one of: ${allowed.join(', ')}.`, { code: 'invalid_input' });
	}
	return value;
}

function prune(obj) {
	const out = {};
	for (const [k, v] of Object.entries(obj)) {
		if (v === undefined || v === null) continue;
		out[k] = v;
	}
	return out;
}