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
// The Materialize quote engine: the only place a print price is ever computed.
//
// Pure by construction. It takes a printability report (api/_lib/print/analyze.js),
// a material id, a target height, a quantity and a destination, and returns an
// itemization or a named rejection. No I/O, no clock beyond the expiry stamp, no
// database. Every surface that shows a buyer a number reads that number from
// here: the page, the operator console, the x402 challenge and the order row all
// call this function or read the itemization it produced. Nothing recomputes.
//
// Scaling is the heart of it. The analyzer measures the mesh at its native glTF
// size; the buyer chooses a height in millimetres. Volume goes as the cube of the
// scale factor and wall thickness goes linearly, so a figure that is too thin for
// resin at 60 mm is fine at 120 mm and costs eight times as much. Both facts are
// derived here, and both are shown to the buyer rather than being applied behind
// the price.
import { readFileSync } from 'node:fs';
import { createHmac, timingSafeEqual } from 'node:crypto';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { env } from '../env.js';
const HERE = dirname(fileURLToPath(import.meta.url));
// Fields that exist for the owner tuning prices, not for the buyer reading them.
// The public catalog handler and every itemization strip these.
const INTERNAL_KEYS = new Set(['_sources', '_note', '_marginNote', '_quantityNote', '_volumetricNote', 'marginFraction']);
let cached = null;
function catalogPath() {
// In dev and tests this module sits in api/_lib/print/; in the Cloud Run image
// the whole repo is present, so the repo-relative path is the reliable one.
return join(HERE, '..', '..', '..', 'data', 'print-catalog.json');
}
/** The full catalog, including owner-only fields. Read once per process. */
export function loadCatalog({ force = false } = {}) {
if (!cached || force) cached = JSON.parse(readFileSync(catalogPath(), 'utf8'));
return cached;
}
function stripInternal(value) {
if (Array.isArray(value)) return value.map(stripInternal);
if (value && typeof value === 'object') {
const out = {};
for (const [k, v] of Object.entries(value)) {
if (INTERNAL_KEYS.has(k)) continue;
out[k] = stripInternal(v);
}
return out;
}
return value;
}
/** The buyer-facing catalog: same data, minus margin and sourcing notes. */
export function publicCatalog(catalog = loadCatalog()) {
return stripInternal(catalog);
}
export function findMaterial(materialId, catalog = loadCatalog()) {
return catalog.materials.find((m) => m.id === materialId) || null;
}
export function findFinish(material, finishId) {
if (!material) return null;
if (!finishId) return material.finishes.find((f) => f.default) || material.finishes[0] || null;
return material.finishes.find((f) => f.id === finishId) || null;
}
/** Destination country to shipping zone, falling back to the zone marked default. */
export function zoneForCountry(country, catalog = loadCatalog()) {
const code = String(country || '').trim().toUpperCase();
const zones = catalog.shipping.zones;
return zones.find((z) => z.countries.includes(code)) || zones.find((z) => z.default) || zones[zones.length - 1];
}
function round(value, places = 2) {
const f = 10 ** places;
return Math.round((value + Number.EPSILON) * f) / f;
}
/**
* What one unit weighs and how much box it takes, at the ordered size. Shipping
* is charged on whichever is larger, which is why both are computed here rather
* than in the shipping line.
*/
function unitPhysicals({ report, material, scale, volumeCm3, catalog }) {
const packMm = catalog.shipping.packagingMm;
const box = {
x: report.bbox_mm.x * scale + packMm * 2,
y: report.bbox_mm.y * scale + packMm * 2,
z: report.bbox_mm.z * scale + packMm * 2,
};
return {
massGrams: volumeCm3 * material.densityGramsPerCm3,
boxCm3: (box.x / 10) * (box.y / 10) * (box.z / 10),
boxMm: { x: round(box.x, 1), y: round(box.y, 1), z: round(box.z, 1) },
};
}
/**
* The heights at which THIS mesh can actually be printed in THIS material.
*
* The catalog's own min/max are a property of the machine; this narrows them by
* the two properties of the mesh: its widest axis has to fit the bed, and its
* thinnest wall has to survive at the chosen scale. The /materialize size slider
* is bounded by this, which is why a buyer moving it never lands on a rejection
* they could not have predicted.
*
* `limitedBy` names which constraint bit, so the UI can label the end of the
* track ("as tall as the bed allows") instead of just stopping.
*
* @returns {{ minHeightMm: number, maxHeightMm: number, feasible: boolean,
* limitedBy: { min: string, max: string } }}
*/
export function fitHeightRange({ report, material }) {
const heightMm = report?.bbox_mm?.y;
if (!(heightMm > 0)) {
return { minHeightMm: material.minHeightMm, maxHeightMm: material.maxHeightMm, feasible: false, limitedBy: { min: 'material', max: 'material' } };
}
let minHeightMm = material.minHeightMm;
let minLimit = 'material';
// Wall thickness scales linearly with height, so the smallest printable height
// is the one where the thinnest measured wall reaches the material's minimum.
if (report.min_wall_mm > 0) {
const wallFloor = (material.minWallMm / report.min_wall_mm) * heightMm;
if (wallFloor > minHeightMm) {
minHeightMm = wallFloor;
minLimit = 'wall';
}
}
let maxHeightMm = material.maxHeightMm;
let maxLimit = 'material';
for (const axis of ['x', 'z']) {
const span = report.bbox_mm?.[axis];
if (!(span > 0)) continue;
// Uniform scale: the height at which this axis exactly fills the bed.
const cap = (material.maxBoundingBoxMm[axis] / span) * heightMm;
if (cap < maxHeightMm) {
maxHeightMm = cap;
maxLimit = 'build_volume';
}
}
return {
minHeightMm: round(minHeightMm, 1),
maxHeightMm: round(maxHeightMm, 1),
feasible: maxHeightMm >= minHeightMm,
limitedBy: { min: minLimit, max: maxLimit },
};
}
/**
* Every reason a mesh cannot be printed in a material, with the fix attached.
* A rejection that only says "no" makes the buyer guess; each one here names the
* measured number, the required number, and the action that resolves it.
*/
function constraintFailures({ report, material, targetHeightMm, scale }) {
const failures = [];
const scaledWall = report.min_wall_mm === null || report.min_wall_mm === undefined
? null
: report.min_wall_mm * scale;
if (targetHeightMm < material.minHeightMm) {
failures.push({
code: 'below_min_height',
message: `${material.name} cannot hold detail below ${material.minHeightMm} mm tall.`,
fix: `Raise the size to at least ${material.minHeightMm} mm.`,
measured: round(targetHeightMm, 1),
required: material.minHeightMm,
});
}
if (targetHeightMm > material.maxHeightMm) {
failures.push({
code: 'above_max_height',
message: `${material.name} builds up to ${material.maxHeightMm} mm tall.`,
fix: `Lower the size to ${material.maxHeightMm} mm or under, or choose a material with a larger bed.`,
measured: round(targetHeightMm, 1),
required: material.maxHeightMm,
});
}
const box = material.maxBoundingBoxMm;
for (const axis of ['x', 'z']) {
const value = report.bbox_mm[axis] * scale;
if (value > box[axis]) {
// The fix is a number, not an instruction to fiddle: the tallest this
// model can be printed in this material before its widest axis runs out
// of bed. A slider that already clamps to fitHeightRange() rarely lands
// here, but a deep link or an agent request can.
const fits = Math.floor(fitHeightRange({ report, material }).maxHeightMm);
failures.push({
code: 'exceeds_build_volume',
message: `At this size the model is ${round(value, 1)} mm across, over the ${box[axis]} mm build volume for ${material.name}.`,
fix: fits >= material.minHeightMm
? `Print it at ${fits} mm tall or under, or choose a material with a larger build volume.`
: 'This model is too wide for this material at any printable height; choose a material with a larger build volume.',
measured: round(value, 1),
required: box[axis],
});
break;
}
}
if (scaledWall !== null && scaledWall < material.minWallMm) {
failures.push({
code: 'walls_too_thin',
message: `The thinnest wall would be ${round(scaledWall, 2)} mm, under the ${material.minWallMm} mm ${material.name} needs.`,
fix: `Repair thickens thin walls automatically, or print at ${Math.ceil((material.minWallMm / scaledWall) * targetHeightMm)} mm tall or larger.`,
measured: round(scaledWall, 2),
required: material.minWallMm,
});
}
if (material.requiresTexture && !report.has_textures) {
failures.push({
code: 'no_colour_data',
message: `${material.name} prints the model's own colours, and this model carries no texture.`,
fix: 'Choose a single-colour material, or print a textured version of this model.',
measured: report.color_source || 'none',
required: 'texture',
});
}
return failures;
}
/**
* Every material measured against THIS mesh: the height range it can actually be
* printed at, and, when none exists, the reason in the buyer's words.
*
* The /materialize material cards render straight off this, so a card that cannot
* take the model says why on its face rather than failing after it is clicked.
*/
export function materialFits({ report, catalog = loadCatalog() }) {
return catalog.materials.map((material) => {
const fit = fitHeightRange({ report, material });
let blocked = null;
if (material.requiresTexture && !report.has_textures) {
blocked = `${material.name} prints the model's own colours, and this model has no texture.`;
} else if (!fit.feasible) {
blocked = fit.limitedBy.max === 'build_volume'
? `This model is too wide for the ${material.name} build volume at any height that keeps its walls printable.`
: `This model cannot hold a ${material.minWallMm} mm wall anywhere in the ${material.minHeightMm} to ${material.maxHeightMm} mm range ${material.name} prints.`;
}
return {
id: material.id,
name: material.name,
class: material.class,
minHeightMm: fit.minHeightMm,
maxHeightMm: fit.maxHeightMm,
limitedBy: fit.limitedBy,
quoteOnRequest: Boolean(material.quoteOnRequest),
hollowSupported: Boolean(material.hollow?.supported),
blocked,
};
});
}
/**
* Materials that would accept this mesh at this height. A rejection hands the
* buyer this list so the next click is a working order rather than a retry.
*/
function alternativesFor({ report, targetHeightMm, catalog, excludeId }) {
const out = [];
for (const material of catalog.materials) {
if (material.id === excludeId) continue;
const scale = targetHeightMm / report.bbox_mm.y;
if (constraintFailures({ report, material, targetHeightMm, scale }).length) continue;
out.push({ id: material.id, name: material.name, class: material.class });
}
return out;
}
/**
* Price a print.
*
* @param {object} args
* @param {object} args.report printability report, version 1
* @param {string} args.materialId
* @param {string} [args.finishId]
* @param {number} args.targetHeightMm
* @param {number} [args.quantity]
* @param {string} args.country ISO-3166 alpha-2 destination
* @param {boolean} [args.hollow] hollow when the material supports it
* @param {number} [args.holderDiscountBps] from api/_lib/three-tier.js, capped here
* @returns {{ ok: true, quote: object } | { ok: false, rejection: object }}
*/
export function quotePrint({
report,
materialId,
finishId = null,
targetHeightMm,
quantity = 1,
country,
hollow = false,
holderDiscountBps = 0,
catalog = loadCatalog(),
}) {
if (!report || report.version !== 1 || !report.bbox_mm?.y || !(report.volume_cm3 > 0)) {
return { ok: false, rejection: { code: 'invalid_report', message: 'A version-1 printability report with a positive volume is required to quote.', failures: [] } };
}
const material = findMaterial(materialId, catalog);
if (!material) {
return { ok: false, rejection: { code: 'unknown_material', message: `No material with id "${materialId}".`, failures: [] } };
}
const finish = findFinish(material, finishId);
if (!finish) {
return { ok: false, rejection: { code: 'unknown_finish', message: `No finish "${finishId}" for ${material.name}.`, failures: [] } };
}
// An explicit 0, -3 or "many" is a caller error worth naming; only an absent
// quantity defaults to one. Coercing a bad value silently would quote a
// different order than the one that was asked for.
const qty = quantity === null || quantity === undefined ? 1 : Math.floor(Number(quantity));
if (!Number.isFinite(qty) || !(qty >= 1 && qty <= 500)) {
return { ok: false, rejection: { code: 'invalid_quantity', message: 'Quantity must be between 1 and 500.', failures: [] } };
}
const height = Number(targetHeightMm);
if (!(height > 0)) {
return { ok: false, rejection: { code: 'invalid_height', message: 'A positive target height in millimetres is required.', failures: [] } };
}
const scale = height / report.bbox_mm.y;
const failures = constraintFailures({ report, material, targetHeightMm: height, scale });
if (failures.length) {
return {
ok: false,
rejection: {
code: failures[0].code,
message: failures[0].message,
failures,
alternatives: alternativesFor({ report, targetHeightMm: height, catalog, excludeId: material.id }),
},
};
}
// Volume scales with the cube of the linear scale; surface area with the square.
const solidVolumeCm3 = report.volume_cm3 * scale ** 3;
const surfaceCm2 = (report.surface_area_cm2 ?? 0) * scale ** 2;
const canHollow = Boolean(hollow && material.hollow?.supported);
// A shell's volume is its surface times its wall thickness, which is the same
// number the prepare step's erosion produces to within the wall's own curvature.
// Never above the solid it came from, and never below a floor that keeps a tiny
// print from quoting as free.
const hollowVolumeCm3 = canHollow
? Math.min(solidVolumeCm3, Math.max(surfaceCm2 * (material.hollow.wallMm / 10), solidVolumeCm3 * 0.15))
: solidVolumeCm3;
const volumeCm3 = round(hollowVolumeCm3, 3);
const physicals = unitPhysicals({ report, material, scale, volumeCm3, catalog });
const lines = [];
const setup = round(material.setupFee, 2);
lines.push({
id: 'setup',
label: `Build setup, ${material.name}`,
detail: 'Machine preparation and file staging, charged once per model.',
amount: setup,
});
const materialAmount = round(material.ratePerCm3 * volumeCm3 * qty, 2);
lines.push({
id: 'material',
label: material.name,
detail: `${volumeCm3} cm3 at ${material.ratePerCm3.toFixed(2)} USDC per cm3${canHollow ? `, hollowed to a ${material.hollow.wallMm} mm wall` : ''}${qty > 1 ? ` x ${qty}` : ''}.`,
amount: materialAmount,
volumeCm3,
estimate: Boolean(material.rateEstimate),
});
const finishAmount = round((finish.fee || 0) * qty, 2);
if (finishAmount > 0) {
lines.push({
id: 'finish',
label: finish.name,
detail: qty > 1 ? `Applied to all ${qty} pieces.` : 'Applied after printing.',
amount: finishAmount,
});
}
const discountable = setup + materialAmount + finishAmount;
const breaks = catalog.pricing.quantityBreaks
.filter((b) => qty >= b.minQuantity)
.sort((a, b) => b.discountBps - a.discountBps);
let quantityAmount = 0;
if (breaks.length) {
quantityAmount = -round((discountable * breaks[0].discountBps) / 10_000, 2);
lines.push({
id: 'quantity_break',
label: `Quantity break, ${breaks[0].minQuantity}+`,
detail: `One setup and one prepared file serve the whole run, so ${breaks[0].discountBps / 100} percent comes off.`,
amount: quantityAmount,
});
}
const cappedBps = Math.max(0, Math.min(Number(holderDiscountBps) || 0, catalog.pricing.holderDiscount.maxBps));
let holderAmount = 0;
if (cappedBps > 0) {
holderAmount = -round(((discountable + quantityAmount) * cappedBps) / 10_000, 2);
lines.push({
id: 'holder_discount',
label: `$THREE holder discount, ${cappedBps / 100} percent`,
detail: 'Applied to setup, material and finish. Shipping is passed through at cost.',
amount: holderAmount,
bps: cappedBps,
});
}
const zone = zoneForCountry(country, catalog);
const volumetricKg = (physicals.boxCm3 * qty) / catalog.shipping.volumetricDivisor;
const realKg = (physicals.massGrams * qty) / 1000;
const chargeableKg = Math.max(catalog.shipping.minChargeableKg, volumetricKg, realKg);
const shippingAmount = round(zone.baseFee + zone.perKg * chargeableKg, 2);
lines.push({
id: 'shipping',
label: `Shipping to ${zone.name}`,
detail: `${round(chargeableKg, 2)} chargeable kg${volumetricKg > realKg ? ' (volumetric)' : ''}, ${zone.transitDays} days in transit.`,
amount: shippingAmount,
zone: zone.id,
});
const subtotal = round(lines.reduce((sum, l) => sum + l.amount, 0), 2);
const minimum = catalog.pricing.minOrderUsdc;
let total = subtotal;
if (subtotal < minimum) {
const topUp = round(minimum - subtotal, 2);
lines.push({
id: 'minimum',
label: 'Order minimum',
detail: `Every order carries a ${minimum} USDC floor; this one came in under it.`,
amount: topUp,
});
total = minimum;
}
const leadTimeDays = material.leadTimeDays + (finish.leadTimeDays || 0) + zone.transitDays;
return {
ok: true,
quote: {
version: 1,
currency: catalog.currency,
chain: catalog.chain,
material: { id: material.id, name: material.name, class: material.class },
finish: { id: finish.id, name: finish.name },
targetHeightMm: round(height, 1),
quantity: qty,
hollow: canHollow,
country: String(country || '').trim().toUpperCase() || null,
shippingZone: zone.id,
geometry: {
scale: round(scale, 6),
volumeCm3,
solidVolumeCm3: round(solidVolumeCm3, 3),
massGramsEach: round(physicals.massGrams, 1),
boxMm: physicals.boxMm,
chargeableKg: round(chargeableKg, 2),
minWallAtSizeMm: report.min_wall_mm === null || report.min_wall_mm === undefined ? null : round(report.min_wall_mm * scale, 2),
},
lines,
subtotal,
total,
leadTimeDays,
quoteOnRequest: Boolean(material.quoteOnRequest),
estimate: Boolean(material.rateEstimate),
},
};
}
// Quote tokens. Same construction and the same secret as the forge job handles:
// an HMAC over a compact payload, prefix-tagged so a token's kind is readable
// before it is verified. The token carries every priced parameter, so checkout
// re-derives what it charges from the token and never from the request body.
const TOKEN_PREFIX = 'pq1';
function sign(payload) {
return createHmac('sha256', env.JWT_SECRET).update(payload).digest('base64url');
}
/**
* @param {object} quote the itemization from quotePrint
* @param {{ reportHash: string, sourceUrl?: string, creationId?: string, ttlSeconds?: number }} context
*/
export function signQuote(quote, context) {
const ttl = context.ttlSeconds ?? loadCatalog().pricing.quoteTtlSeconds;
const body = {
v: 1,
m: quote.material.id,
f: quote.finish.id,
h: quote.targetHeightMm,
q: quote.quantity,
w: quote.hollow ? 1 : 0,
c: quote.country,
t: quote.total,
g: quote.geometry.volumeCm3,
l: quote.leadTimeDays,
r: context.reportHash,
u: context.sourceUrl || null,
i: context.creationId || null,
// The wallet whose $THREE tier priced this quote, when that tier came from
// a self-declared payer wallet rather than a session. Checkout must then be
// paid FROM that wallet, or anyone could quote at a whale's discount.
pw: context.discountWallet || null,
exp: Math.floor(Date.now() / 1000) + ttl,
};
const payload = Buffer.from(JSON.stringify(body), 'utf8').toString('base64url');
return `${TOKEN_PREFIX}.${payload}.${sign(payload)}`;
}
/**
* Verify and decode a quote token. Returns null for anything that is not a
* currently-valid token this server signed, which is the single check checkout
* makes before it charges: a tampered price, a stale price and a forged token
* all fail here identically.
*/
export function verifyQuote(token, { now = Date.now() } = {}) {
if (typeof token !== 'string' || !token.startsWith(`${TOKEN_PREFIX}.`)) return null;
const parts = token.split('.');
if (parts.length !== 3) return null;
const [, payload, signature] = parts;
if (!payload || !signature) return null;
try {
const expected = Buffer.from(sign(payload), 'utf8');
const actual = Buffer.from(signature, 'utf8');
if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return null;
const body = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
if (body.v !== 1 || !body.exp || body.exp * 1000 < now) return null;
return {
materialId: body.m,
finishId: body.f,
targetHeightMm: body.h,
quantity: body.q,
hollow: body.w === 1,
country: body.c,
total: body.t,
volumeCm3: body.g,
leadTimeDays: body.l,
reportHash: body.r,
sourceUrl: body.u,
creationId: body.i,
discountWallet: body.pw || null,
expiresAt: body.exp * 1000,
};
} catch {
return null;
}
}