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.

11.8 KB
Raw Blame
// Knock persistence: doors, the knock log, and the block list.
//
// Every write is scoped to a user id the caller already authenticated. The two
// public reads (a door by handle, the directory) deliberately return only what
// a stranger is allowed to see: the price, the greeting, and the owner's
// display identity. A payout address is never in a public payload.

import { sql } from '../db.js';
import { DEFAULT_PRICE_ATOMICS, KNOCK_STATUSES, normalizeHandle } from './policy.js';

const DOOR_COLUMNS = sql`
	user_id, open, price_atomics::text as price_atomics, pay_to_solana, pay_to_base,
	escrow_enabled, escrow_window_hours,
	headline, greeting, max_chars, daily_cap, listed, created_at, updated_at
`;

/**
 * The owner's own door. Provisions a closed default row on first read so the
 * settings page always has something real to render and save against.
 */
export async function getDoor(userId) {
	const [row] = await sql`select ${DOOR_COLUMNS} from knock_doors where user_id = ${userId}`;
	if (row) return row;
	const [created] = await sql`
		insert into knock_doors (user_id, price_atomics)
		values (${userId}, ${DEFAULT_PRICE_ATOMICS.toString()})
		on conflict (user_id) do update set updated_at = now()
		returning ${DOOR_COLUMNS}
	`;
	return created;
}

export async function updateDoor(userId, patch) {
	await getDoor(userId);
	const [row] = await sql`
		update knock_doors set
			open          = coalesce(${patch.open ?? null}, open),
			price_atomics = coalesce(${patch.price_atomics ?? null}, price_atomics),
			pay_to_solana = ${patch.pay_to_solana === undefined ? sql`pay_to_solana` : patch.pay_to_solana},
			pay_to_base   = ${patch.pay_to_base === undefined ? sql`pay_to_base` : patch.pay_to_base},
			headline      = ${patch.headline === undefined ? sql`headline` : patch.headline},
			greeting      = ${patch.greeting === undefined ? sql`greeting` : patch.greeting},
			max_chars     = coalesce(${patch.max_chars ?? null}, max_chars),
			daily_cap     = coalesce(${patch.daily_cap ?? null}, daily_cap),
			listed        = coalesce(${patch.listed ?? null}, listed),
			escrow_enabled = coalesce(${patch.escrow_enabled ?? null}, escrow_enabled),
			escrow_window_hours = coalesce(${patch.escrow_window_hours ?? null}, escrow_window_hours),
			updated_at    = now()
		where user_id = ${userId}
		returning ${DOOR_COLUMNS}
	`;
	return row;
}

/**
 * A door as a stranger sees it, looked up by @username.
 * Returns null when the handle matches nobody or that account never opened one,
 * so the public endpoint answers the same 404 either way and a probe cannot use
 * it to enumerate which accounts exist.
 */
export async function publicDoorByHandle(handle) {
	const username = normalizeHandle(handle);
	if (!username) return null;
	const [row] = await sql`
		select u.id as user_id, u.username, u.display_name, u.avatar_url, u.verified_type,
		       d.open, d.price_atomics::text as price_atomics, d.headline, d.greeting,
		       d.max_chars, d.daily_cap, d.listed,
		       d.escrow_enabled, d.escrow_window_hours,
		       -- The owner's Solana address, and ONLY when they turned the
		       -- escrowed lane on. It is half of their on-chain door address,
		       -- which a stranger has to derive before they can escrow
		       -- anything. api/knock/door.js ships the derived address rather
		       -- than this one, so a payout address still never appears in a
		       -- public body; the account it points at is public because the
		       -- owner opted into publishing it.
		       case when d.escrow_enabled then d.pay_to_solana end as escrow_owner,
		       d.pay_to_solana is not null as has_solana_payout,
		       d.pay_to_base is not null as has_base_payout
		from users u
		join knock_doors d on d.user_id = u.id
		where lower(u.username) = ${username} and u.deleted_at is null and d.open
	`;
	return row || null;
}

/** The payout addresses, read only on the settle path. Never in a public body. */
export async function payoutFor(userId) {
	const [row] = await sql`
		select d.pay_to_solana, d.pay_to_base, u.wallet_address
		from knock_doors d join users u on u.id = d.user_id
		where d.user_id = ${userId}
	`;
	return row || null;
}

/** Open, listed doors, cheapest first so the browsable page starts reachable. */
export async function listDirectory({ limit = 60 } = {}) {
	return sql`
		select u.username, u.display_name, u.avatar_url, u.verified_type,
		       d.price_atomics::text as price_atomics, d.headline, d.updated_at,
		       (select count(*)::int from knock_messages m
		         where m.recipient_user_id = d.user_id and m.status = 'replied') as replies
		from knock_doors d
		join users u on u.id = d.user_id
		where d.open and d.listed and u.deleted_at is null and u.username is not null
		order by d.price_atomics asc, d.updated_at desc
		limit ${limit}
	`;
}

export async function knocksToday(userId) {
	const [row] = await sql`
		select count(*)::int as count from knock_messages
		where recipient_user_id = ${userId} and created_at >= date_trunc('day', now() at time zone 'utc')
	`;
	return row?.count ?? 0;
}

export async function isBlocked(userId, keys) {
	if (!keys?.length) return false;
	const [row] = await sql`
		select 1 from knock_blocks
		where user_id = ${userId} and lower(subject) = any(${keys})
		limit 1
	`;
	return Boolean(row);
}

/**
 * Record a knock. Returns null when `request_id` has already been used by this
 * recipient, which is how a retried POST after a settled payment stays one
 * knock instead of two.
 */
export async function recordKnock(userId, knock) {
	// escrow_* is a cache of what the chain says (api/_lib/knock/escrow.js), so
	// the inbox can show a countdown without an RPC read per row. Null on both
	// non-escrow lanes, which is how a reader tells the three apart.
	const [row] = await sql`
		insert into knock_messages
			(recipient_user_id, sender_name, sender_url, sender_kind, payer_wallet, network,
			 tx_hash, amount_atomics, asset, subject, message, companion_event_id, request_id,
			 escrow_knock, escrow_expires_at, escrow_state)
		values (${userId}, ${knock.senderName}, ${knock.senderUrl ?? null}, ${knock.senderKind ?? 'unknown'},
		        ${knock.payerWallet ?? null}, ${knock.network ?? null}, ${knock.txHash ?? null},
		        ${String(knock.amountAtomics ?? 0)}, ${knock.asset ?? null}, ${knock.subject ?? null},
		        ${knock.message}, ${knock.companionEventId ?? null}, ${knock.requestId ?? null},
		        ${knock.escrowKnock ?? null},
		        ${knock.escrowExpiresAt ? new Date(knock.escrowExpiresAt * 1000) : null},
		        ${knock.escrowState ?? null})
		on conflict (recipient_user_id, request_id) where request_id is not null do nothing
		returning id, sender_name, sender_url, sender_kind, payer_wallet, network, tx_hash,
		          amount_atomics::text as amount_atomics, asset, subject, message, status,
		          companion_event_id, created_at, escrow_knock, escrow_expires_at, escrow_state
	`;
	return row || null;
}

/**
 * Has this exact on-chain knock already bought a message?
 *
 * One escrowed knock buys exactly one delivery. The unique index on
 * escrow_knock is what actually enforces it; this read is so a replay gets a
 * clean "already delivered" with the original row instead of a constraint
 * violation surfacing as a 500.
 */
export async function findByEscrowKnock(escrowKnock) {
	if (!escrowKnock) return null;
	const [row] = await sql`
		select id, recipient_user_id, sender_name, subject, message, status, created_at,
		       escrow_knock, escrow_expires_at, escrow_state
		  from knock_messages
		 where escrow_knock = ${escrowKnock}
		 limit 1
	`;
	return row || null;
}

/**
 * Write back what the chain now says about an escrowed knock.
 *
 * Called after re-reading the account, so a row that says `pending` in the
 * inbox cannot keep saying it after the money has already gone back.
 */
export async function updateEscrowState(escrowKnock, state) {
	if (!escrowKnock) return null;
	const [row] = await sql`
		update knock_messages
		   set escrow_state = ${state}
		 where escrow_knock = ${escrowKnock}
		 returning id, escrow_knock, escrow_state
	`;
	return row || null;
}

export async function findByRequestId(userId, requestId) {
	if (!requestId) return null;
	const [row] = await sql`
		select id, sender_name, subject, message, status, amount_atomics::text as amount_atomics, created_at
		from knock_messages
		where recipient_user_id = ${userId} and request_id = ${requestId}
	`;
	return row || null;
}

export async function listInbox(userId, { limit = 30, before = null, status = null } = {}) {
	const beforeClause = before ? sql`and created_at < ${before}` : sql``;
	const statusClause = status ? sql`and status = ${status}` : sql``;
	return sql`
		select id, sender_name, sender_url, sender_kind, payer_wallet, network, tx_hash,
		       amount_atomics::text as amount_atomics, asset, subject, message, status,
		       reply_text, read_at, replied_at, created_at,
		       escrow_knock, escrow_expires_at, escrow_state
		from knock_messages
		where recipient_user_id = ${userId}
		${statusClause}
		${beforeClause}
		order by created_at desc
		limit ${limit}
	`;
}

export async function inboxTotals(userId) {
	const [row] = await sql`
		select count(*) filter (where status = 'pending')::int as pending,
		       count(*)::int as total,
		       -- An escrowed knock is not earned until it is answered. Counting
		       -- one that is still pending would show the owner money they
		       -- cannot spend and might never be paid, and counting a refunded
		       -- one would show them money that went back to the sender.
		       coalesce(sum(amount_atomics) filter (
		           where escrow_state is null or escrow_state = 'answered'
		       ), 0)::text as earned_atomics,
		       coalesce(sum(amount_atomics) filter (
		           where escrow_state = 'pending'
		       ), 0)::text as escrowed_atomics,
		       count(*) filter (where escrow_state = 'pending')::int as escrowed_pending
		from knock_messages where recipient_user_id = ${userId}
	`;
	return row || { pending: 0, total: 0, earned_atomics: '0', escrowed_atomics: '0', escrowed_pending: 0 };
}

export async function updateKnock(userId, id, { status = null, reply = null }) {
	const nextStatus = KNOCK_STATUSES.includes(status) ? status : null;
	const [row] = await sql`
		update knock_messages set
			status     = coalesce(${nextStatus}, status),
			reply_text = ${reply === null ? sql`reply_text` : reply},
			read_at    = ${nextStatus && nextStatus !== 'pending' ? sql`coalesce(read_at, now())` : sql`read_at`},
			replied_at = ${nextStatus === 'replied' ? sql`coalesce(replied_at, now())` : sql`replied_at`}
		where id = ${id} and recipient_user_id = ${userId}
		returning id, sender_name, sender_url, subject, message, status, reply_text,
		          amount_atomics::text as amount_atomics, payer_wallet, read_at, replied_at, created_at
	`;
	return row || null;
}

export async function getKnock(userId, id) {
	const [row] = await sql`
		select id, sender_name, sender_url, payer_wallet, subject, message, status,
		       amount_atomics::text as amount_atomics, companion_event_id, created_at
		from knock_messages where id = ${id} and recipient_user_id = ${userId}
	`;
	return row || null;
}

export async function listBlocks(userId) {
	return sql`
		select id, subject, note, created_at from knock_blocks
		where user_id = ${userId} order by created_at desc limit 200
	`;
}

export async function addBlock(userId, subject, note = null) {
	const clean = String(subject || '').trim().slice(0, 120);
	if (!clean) return null;
	const [row] = await sql`
		insert into knock_blocks (user_id, subject, note)
		values (${userId}, ${clean}, ${note})
		on conflict (user_id, lower(subject)) do nothing
		returning id, subject, note, created_at
	`;
	return row || null;
}

export async function removeBlock(userId, id) {
	const [row] = await sql`
		delete from knock_blocks where user_id = ${userId} and id = ${id} returning id
	`;
	return Boolean(row);
}