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
// @ts-check
// The Materialize order state machine: the one module allowed to move a print
// order from one status to the next.
//
// The database carries the vocabulary as a check constraint so no handler can
// invent a state; the legal MOVES live here, next to the events they emit,
// because a transition is never just a column write. Every accepted move
// appends a print_order_events row (the timeline is that table, never a mutated
// column) and, where the buyer is a signed-in human, publishes one user
// notification. An illegal move throws rather than silently no-ops, because a
// silently ignored transition is how an order goes quiet forever.
//
// Reaching `shipped` also issues the order's certificate: the SHA-256 of the
// printed bytes, the edition number, and a Solana memo attesting both
// (api/_lib/print/certificate.js). That side effect is deliberately hung off
// the transition rather than polled, so the certificate exists the moment the
// box does. It is fail-soft: a certificate that cannot attest right now is
// retried by api/cron/print-orders-sync.js, and a shipment is never blocked by
// an RPC having a bad minute.
//
// createOrder() opens an order from a verified quote token and nothing else:
// the price, the geometry and the material all come out of the token's signed
// payload, never out of the request, so neither checkout lane can be talked
// into a price this server did not sign.
import { sql } from './db.js';
import { publishUserEvent } from './feed.js';
import { issueCertificateForOrder } from './print/certificate.js';
import { assertEditionAvailable } from './print/editions.js';
/** Every status the print_orders check constraint accepts. */
export const PRINT_STATUSES = Object.freeze([
'created', 'quoted', 'paid', 'screening', 'submitted', 'printing',
'quality_check', 'shipped', 'delivered', 'rejected', 'canceled', 'refunded',
]);
/** Statuses nothing moves out of. */
export const TERMINAL_STATUSES = Object.freeze(['delivered', 'rejected', 'canceled', 'refunded']);
/**
* The whitelist, as data. Read it as "from this status, only these are legal".
* Anything absent is illegal, including a same-status write.
* @type {Readonly<Record<string, readonly string[]>>}
*/
export const LEGAL_TRANSITIONS = Object.freeze({
created: ['quoted', 'canceled'],
quoted: ['paid', 'canceled'],
// A paid order is screened before a provider ever sees it; a failed screen
// goes to rejected, which is the refund path's entry point.
paid: ['screening', 'canceled', 'refunded'],
screening: ['submitted', 'rejected', 'refunded'],
submitted: ['printing', 'quality_check', 'canceled', 'refunded'],
printing: ['quality_check', 'refunded'],
quality_check: ['shipped', 'printing', 'refunded'],
shipped: ['delivered', 'refunded'],
delivered: [],
rejected: ['refunded'],
canceled: ['refunded'],
refunded: [],
});
/** Who caused a transition. Matches the print_order_events actor constraint. */
export const ACTORS = Object.freeze(['system', 'operator', 'provider', 'buyer']);
/** Typed failure so handlers map a cause to a status code. */
export class PrintStoreError extends Error {
/**
* @param {string} code
* @param {string} message
* @param {Record<string, unknown>} [extra]
*/
constructor(code, message, extra = {}) {
super(message);
this.name = 'PrintStoreError';
this.code = code;
Object.assign(this, extra);
}
}
/**
* @param {string} from
* @param {string} to
* @returns {boolean}
*/
export function canTransition(from, to) {
return (LEGAL_TRANSITIONS[from] || []).includes(to);
}
/** @param {string} id */
export async function getOrder(id) {
const [row] = await sql`select * from print_orders where id = ${id} limit 1`;
return row || null;
}
/** The order plus its timeline, oldest first. @param {string} id */
export async function getOrderWithEvents(id) {
const order = await getOrder(id);
if (!order) return null;
const events = await sql`
select status, note, actor, created_at
from print_order_events where order_id = ${id} order by created_at asc
`;
return { ...order, events };
}
/**
* Append a timeline row. Exported because an operator note about an order that
* did not change status is still part of its story.
* @param {{ orderId: string, status: string, note?: string|null, actor?: string, actorId?: string|null }} input
*/
export async function appendEvent({ orderId, status, note = null, actor = 'system', actorId = null }) {
const who = ACTORS.includes(actor) ? actor : 'system';
const [row] = await sql`
insert into print_order_events (order_id, status, note, actor, actor_id)
values (${orderId}, ${status}, ${note}, ${who}, ${actorId})
returning id, status, note, actor, created_at
`;
return row;
}
/** Human-readable line for the buyer's notification bell. */
function notificationLine(status) {
switch (status) {
case 'paid': return 'Payment received. Your print is queued for screening.';
case 'screening': return 'Your model is being checked for printability and safety.';
case 'submitted': return 'Your print has been sent to the production floor.';
case 'printing': return 'Your print is on the printer.';
case 'quality_check': return 'Your print is finished and in quality check.';
case 'shipped': return 'Your print has shipped, with its certificate of authenticity.';
case 'delivered': return 'Your print was delivered.';
case 'rejected': return 'Your print could not be produced. A refund is being arranged.';
case 'canceled': return 'Your print order was canceled.';
case 'refunded': return 'Your print order was refunded.';
default: return null;
}
}
/**
* Move an order to a new status.
*
* @param {object} input
* @param {string} input.orderId
* @param {string} input.to target status
* @param {string} [input.note] timeline note
* @param {string} [input.actor] system | operator | provider | buyer
* @param {string|null} [input.actorId] the operator's user id, when actor is 'operator'
* @param {Record<string, unknown>} [input.patch] columns to write with the move
* (tracking_number, carrier, provider, provider_order_id, submitted_at,
* payment_signature, payment_chain, payment_amount_atomics)
* @returns {Promise<{ order: any, event: any, certificate: any|null }>}
*/
export async function transition({ orderId, to, note = null, actor = 'system', actorId = null, patch = {} }) {
if (!PRINT_STATUSES.includes(to)) {
throw new PrintStoreError('unknown_status', `${to} is not a print order status`);
}
const order = await getOrder(orderId);
if (!order) throw new PrintStoreError('order_not_found', `no print order ${orderId}`);
if (!canTransition(order.status, to)) {
throw new PrintStoreError(
'illegal_transition',
`a print order cannot go from ${order.status} to ${to}`,
{ from: order.status, to },
);
}
// Scarcity is enforced where the price is set, so a sold-out edition is
// refused before a buyer is ever asked for money.
//
// An order printing a bare GLB is skipped, not failed: editions are numbered
// against a creation, and an upload that belongs to no creation belongs to no
// series, so there is nothing for it to be sold out of. Without this guard the
// series key is underivable and a perfectly valid direct-upload order 500s at
// the moment it is quoted.
if (to === 'quoted' && order.creation_id) {
await assertEditionAvailable({
creationId: order.creation_id,
quantity: order.quantity || 1,
});
}
const [updated] = await sql`
update print_orders set
status = ${to},
provider = coalesce(${patch.provider ?? null}, provider),
provider_order_id = coalesce(${patch.provider_order_id ?? null}, provider_order_id),
tracking_number = coalesce(${patch.tracking_number ?? null}, tracking_number),
carrier = coalesce(${patch.carrier ?? null}, carrier),
lead_time_days = coalesce(${patch.lead_time_days ?? null}, lead_time_days),
payment_signature = coalesce(${patch.payment_signature ?? null}, payment_signature),
payment_chain = coalesce(${patch.payment_chain ?? null}, payment_chain),
payment_amount_atomics = coalesce(${patch.payment_amount_atomics ?? null}, payment_amount_atomics),
submitted_at = case when ${to} = 'submitted' then coalesce(submitted_at, now()) else submitted_at end,
-- Stamped by the move itself rather than by the caller, so the paid
-- time is always the time the order actually became paid.
paid_at = case when ${to} = 'paid' then coalesce(paid_at, now()) else paid_at end,
stall_alerted_at = null,
updated_at = now()
where id = ${orderId} and status = ${order.status}
returning *
`;
// The status guard in the WHERE clause is the concurrency lock: whoever
// moved the order first wins, and the loser is told what actually happened
// rather than overwriting it.
if (!updated) {
const current = await getOrder(orderId);
throw new PrintStoreError(
'transition_raced',
`this order moved to ${current?.status} while the change to ${to} was in flight`,
{ from: order.status, to, current: current?.status ?? null },
);
}
const event = await appendEvent({ orderId, status: to, note, actor, actorId });
let certificate = null;
if (to === 'shipped') {
try {
const issued = await issueCertificateForOrder({ orderId });
certificate = issued.certificate;
} catch (err) {
// A shipment is a physical fact; it is never rolled back because a
// certificate could not be minted. The sweep picks this up.
console.error('[print-store] certificate issuance failed for', orderId, err?.message);
await appendEvent({
orderId,
status: to,
note: `certificate issuance deferred: ${String(err?.message || err).slice(0, 300)}`,
actor: 'system',
});
}
}
if (updated.user_id) {
const line = notificationLine(to);
if (line) {
publishUserEvent(updated.user_id, {
type: 'print_update',
status: to,
order_id: orderId,
message: line,
certificate_id: certificate?.id ?? null,
link: certificate?.id ? `/cert/${certificate.id}` : `/materialize/orders/${orderId}`,
});
}
}
return { order: updated, event, certificate };
}
// ── Order creation ───────────────────────────────────────────────────────────
// Both checkout lanes land here. Everything money hangs off (material, height,
// quantity, volume, total) is read from the VERIFIED quote token, never from
// the request body, so a caller who edits a price in flight gets the price this
// server signed or nothing at all. The handlers verify the token; this function
// refuses to open an order without the decoded payload it produces.
/** Shipping fields we store, and the only ones. Anything else is dropped. */
const SHIPPING_FIELDS = Object.freeze([
'name', 'line1', 'line2', 'city', 'region', 'postal_code', 'country', 'phone',
]);
const SHIPPING_REQUIRED = Object.freeze(['name', 'line1', 'city', 'postal_code', 'country']);
const SHIPPING_MAX_LEN = 120;
/**
* Normalize a shipping address down to the minimum this platform is willing to
* hold. PII discipline is a schema decision, not a policy document: a field
* that is never accepted is a field that can never leak.
*
* @param {Record<string, unknown>} input
* @returns {{ name: string, line1: string, line2: string|null, city: string,
* region: string|null, postal_code: string, country: string, phone: string|null }}
*/
export function normalizeShipping(input) {
if (!input || typeof input !== 'object') {
throw new PrintStoreError('shipping_required', 'a shipping address is required');
}
/** @type {Record<string, string|null>} */
const out = {};
for (const field of SHIPPING_FIELDS) {
const raw = input[field];
const value = raw == null ? '' : String(raw).trim().slice(0, SHIPPING_MAX_LEN);
out[field] = value || null;
}
for (const field of SHIPPING_REQUIRED) {
if (!out[field]) {
throw new PrintStoreError('shipping_incomplete', `shipping.${field} is required`, { field });
}
}
out.country = String(out.country).toUpperCase();
if (!/^[A-Z]{2}$/.test(out.country)) {
throw new PrintStoreError('shipping_incomplete', 'shipping.country must be an ISO 3166-1 alpha-2 code', {
field: 'country',
});
}
return /** @type {any} */ (out);
}
/**
* Open a print order in `created`. The caller transitions it to `quoted` once
* the row exists, so the edition check that guards scarcity runs against a real
* order rather than against a request.
*
* Exactly one of userId (a signed-in human) or payerWallet (an agent that paid
* over x402) must be present; the DB carries that as a check constraint and
* this refuses it earlier, with a message a handler can return.
*
* @param {object} input
* @param {string|null} [input.userId]
* @param {string|null} [input.payerWallet]
* @param {object} input.quote the decoded, verified quote-token payload
* @param {object} input.itemization the full itemization the buyer was shown
* @param {object} input.report the printability report at order time
* @param {string} input.sourceGlbUrl
* @param {string|null} [input.creationId]
* @param {object} input.shipping already through normalizeShipping()
* @param {string|null} [input.paymentReference] Solana Pay reference pubkey
* @param {string|null} [input.paymentChain]
*/
export async function createOrder({
userId = null,
payerWallet = null,
quote,
itemization,
report,
sourceGlbUrl,
creationId = null,
shipping,
paymentReference = null,
paymentChain = null,
}) {
if (!userId && !payerWallet) {
throw new PrintStoreError('owner_required', 'an order needs either a session user or a payer wallet');
}
if (!quote || !quote.materialId || !(Number(quote.total) > 0)) {
throw new PrintStoreError('quote_required', 'a verified quote token is required to open an order');
}
if (!sourceGlbUrl) {
throw new PrintStoreError('source_required', 'an order needs the model it is printing');
}
const [row] = await sql`
insert into print_orders (
user_id, payer_wallet, creation_id, source_glb_url, analysis,
material_id, target_height_mm, quantity, quote, price_usdc,
shipping, status, payment_reference, payment_chain, quote_expires_at
) values (
${userId}, ${payerWallet}, ${creationId}, ${sourceGlbUrl},
${JSON.stringify(report ?? {})}::jsonb,
${quote.materialId}, ${quote.targetHeightMm}, ${quote.quantity},
${JSON.stringify(itemization ?? {})}::jsonb, ${quote.total},
${JSON.stringify(shipping)}::jsonb, 'created',
${paymentReference}, ${paymentChain},
${quote.expiresAt ? new Date(quote.expiresAt).toISOString() : null}
)
returning *
`;
await appendEvent({
orderId: row.id,
status: 'created',
note: `${quote.quantity} x ${quote.materialId} at ${quote.targetHeightMm} mm, ${quote.total} USDC`,
actor: userId ? 'buyer' : 'system',
actorId: userId,
});
return row;
}
/**
* A buyer's own orders, newest first. Never returns another account's rows: the
* only selector is the caller's own user id.
* @param {string} userId
* @param {{ limit?: number }} [opts]
*/
export async function listOrdersForUser(userId, { limit = 50 } = {}) {
const capped = Math.min(Math.max(Number(limit) || 50, 1), 100);
return sql`
select id, status, material_id, target_height_mm, quantity, price_usdc,
tracking_number, carrier, lead_time_days, created_at, updated_at
from print_orders
where user_id = ${userId}
order by created_at desc
limit ${capped}
`;
}
/**
* The order behind a Solana Pay reference, for the confirm path. The reference
* is unique, so this is a lookup rather than a search.
* @param {string} reference
*/
export async function getOrderByPaymentReference(reference) {
const [row] = await sql`select * from print_orders where payment_reference = ${reference} limit 1`;
return row || null;
}