@vibedout/commerce 0.0.0-stage → 0.2.4

package/dist/lines.mjs

@@ -0,0 +1,385 @@
+import { problem } from "./errors.mjs";
+import { a as isText, i as isRecord, n as UNSAFE, r as isDisplayText, t as SUBJECT_TYPE } from "./internal-p2FS_A4L.mjs";
+import { a as isCurrencyCode, o as isMinorUnits } from "./money-aFFtGd0E.mjs";
+import { FULFILMENTS, LINE_AVAILABILITIES } from "./types.mjs";
+//#region src/lines.ts
+/**
+* Checks at the two edges of a line source: what the browser asks for, and what a source answers. Both return a list of problems and never
+* throw, because the first is hostile input and the second is code another feature wrote (or a project edited). A checkout runs
+* {@link validateAsks} on the request body and {@link resolveLines} on the way to a price, so a wrong line stops there and not in the total.
+*/
+const DEFAULT_ASK_LIMITS = {
+	maxLines: 50,
+	maxQuantity: 99,
+	maxRefLength: 120,
+	maxOptions: 10
+};
+/** The longest ref or stock subject id there is: `maxRefLength` of {@link AskLimits} is cut to this, so a line can always be checked. */
+const MAX_REF_LENGTH = 1024;
+/** What a line's snapshot may weigh as JSON, in bytes: it is copied into every order line. */
+const MAX_SNAPSHOT_BYTES = 2048;
+const MAX_TITLE_LENGTH = 200;
+const MAX_OPTION_KEY_LENGTH = 40;
+const MAX_OPTION_VALUE_LENGTH = 200;
+const MAX_SNAPSHOT_DEPTH = 6;
+const FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const OPTION_KEY = /^[A-Za-z][A-Za-z0-9_.-]*$/;
+const TAX_CODE = /^[A-Za-z0-9]{1,20}$/;
+/** A non-empty string of printable characters with no space at either end. */
+function isPlainText(value, maxLength) {
+	return isText(value, maxLength) && value === value.trim();
+}
+/** A line source's key: dotted lowercase words (`catalog.variant`), what `block.json` allows and the pattern pack's registry finds. */
+const SOURCE_KEY = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
+const MAX_SOURCE_KEY_LENGTH = 80;
+/** The name of an ask in a repeat check: a ref with its options in a fixed order (and its source, in a cart). */
+const askKey = (source, ref, options) => `${source ?? ""}\u0000${ref}\u0000${JSON.stringify(Object.entries(options ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))}`;
+/** The one reader behind {@link validateAsks} and {@link validateCartAsks}: the list, each ask's shape, and the repeats. */
+function readAsks(input, limits, how) {
+	const max = {
+		...DEFAULT_ASK_LIMITS,
+		...limits
+	};
+	max.maxRefLength = Math.min(max.maxRefLength, MAX_REF_LENGTH);
+	if (!Array.isArray(input)) return {
+		ok: false,
+		problems: [problem("invalid_asks", "asks", "asks must be a list")]
+	};
+	if (input.length === 0) return {
+		ok: false,
+		problems: [problem("invalid_asks", "asks", "ask for at least one thing")]
+	};
+	if (input.length > max.maxLines) return {
+		ok: false,
+		problems: [problem("invalid_asks", "asks", `at most ${max.maxLines} lines`)]
+	};
+	const problems = [];
+	const asks = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, raw] of input.entries()) {
+		const path = `asks[${index}]`;
+		if (!isRecord(raw)) {
+			problems.push(problem("invalid_asks", path, `each ask is an object with ${how.cart ? "a source, " : ""}a ref and a quantity`));
+			continue;
+		}
+		const { ref, quantity, options, source } = raw;
+		let valid = true;
+		if (how.cart) {
+			if (typeof source !== "string" || source.length > MAX_SOURCE_KEY_LENGTH || !SOURCE_KEY.test(source)) {
+				problems.push(problem("invalid_source", `${path}.source`, "source is the key of a line source: dotted lowercase words (catalog.variant)"));
+				valid = false;
+			} else if (how.find && how.find(source) === void 0) {
+				problems.push(problem("unknown_source", `${path}.source`, `nothing sells through ${source}`));
+				valid = false;
+			}
+		}
+		if (!isPlainText(ref, max.maxRefLength)) {
+			problems.push(problem("invalid_ref", `${path}.ref`, `ref is 1 to ${max.maxRefLength} printable characters with no space at either end`));
+			valid = false;
+		}
+		if (typeof quantity !== "number" || !Number.isSafeInteger(quantity) || quantity < 1 || quantity > max.maxQuantity) {
+			problems.push(problem("invalid_quantity", `${path}.quantity`, `quantity is a whole number from 1 to ${max.maxQuantity}`));
+			valid = false;
+		}
+		let cleanOptions;
+		if (options !== void 0) {
+			const read = readOptions(options, max, `${path}.options`);
+			if (Array.isArray(read)) {
+				problems.push(...read);
+				valid = false;
+			} else cleanOptions = read;
+		}
+		if (!valid) continue;
+		const key = askKey(how.cart ? source : void 0, ref, cleanOptions);
+		if (seen.has(key)) {
+			problems.push(problem("duplicate_ref", `${path}.ref`, "the same thing is asked for twice: send one line with the total quantity"));
+			continue;
+		}
+		seen.add(key);
+		const ask = {
+			ref,
+			quantity,
+			...cleanOptions ? { options: cleanOptions } : {}
+		};
+		asks.push(how.cart ? {
+			source,
+			...ask
+		} : ask);
+	}
+	return problems.length > 0 ? {
+		ok: false,
+		problems
+	} : {
+		ok: true,
+		asks
+	};
+}
+/**
+* Reads the `asks` of a request body. What comes out has exactly `ref`, `quantity` and (when given) `options`: anything else the browser sent,
+* a `price` above all, is dropped, never read. A repeated ref is refused (the client sums its own quantities).
+*/
+function validateAsks(input, limits = {}) {
+	const read = readAsks(input, limits, { cart: false });
+	return read.ok ? {
+		ok: true,
+		asks: read.asks
+	} : read;
+}
+/**
+* Reads the lines of a cart: a list of `{ source, ref, quantity, options? }` (the same limits as {@link validateAsks}: 1 to 50 lines,
+* quantities 1 to 99, refs of 1 to 120 printable characters) and gives back exactly those fields, in the order sent. It is the check a cart's
+* `complete` runs on its lines BEFORE any price is asked and any place is held, so a hostile or stale cart costs nothing and holds nothing.
+*
+* - `invalid_source`: the source is not a key (dotted lowercase words, at most 80 characters), so it is never looked up;
+* - `unknown_source`: with {@link CartAskOptions.find}, nothing is registered under the key;
+* - `duplicate_ref`: the same source, ref and options twice (the same ref under two sources, or with other options, is two lines);
+* - what {@link validateAsks} refuses for a ref, a quantity or the options, at the same paths (`asks[2].quantity`).
+*
+* Anything else in an ask, a price above all, is dropped and never read. Whether the thing exists and can be bought is the source's answer,
+* not this check's: price the result with {@link resolveCart}.
+*
+* ```ts
+* const read = validateCartAsks(cart.lines, { find: (key) => { const found = linePort<LineSource>(key); return found.ok ? found.port : undefined; } });
+* if (!read.ok) return refuse(read.problems);
+* const priced = await resolveCart(find, ctx, read.asks);
+* ```
+*/
+function validateCartAsks(input, options = {}) {
+	const { find, ...limits } = options;
+	return readAsks(input, limits, {
+		cart: true,
+		find
+	});
+}
+function readOptions(value, max, path) {
+	if (!isRecord(value)) return [problem("invalid_options", path, "options is an object of strings")];
+	const entries = Object.entries(value);
+	if (entries.length > max.maxOptions) return [problem("invalid_options", path, `at most ${max.maxOptions} options`)];
+	const out = {};
+	for (const [key, option] of entries) {
+		if (key.length > MAX_OPTION_KEY_LENGTH || !OPTION_KEY.test(key) || FORBIDDEN_KEYS.has(key)) return [problem("invalid_options", `${path}.${key.slice(0, 20)}`, "an option name is letters, digits, dot, dash or underscore, starting with a letter")];
+		if (typeof option !== "string" || option.length > MAX_OPTION_VALUE_LENGTH || UNSAFE.test(option)) return [problem("invalid_options", `${path}.${key}`, `an option value is a string of at most ${MAX_OPTION_VALUE_LENGTH} printable characters`)];
+		out[key] = option;
+	}
+	return out;
+}
+/** Why a value cannot be written to JSON and read back the same, or `undefined` when it can. */
+function notJson(value, depth, path) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return void 0;
+	if (typeof value === "number") return Number.isFinite(value) ? void 0 : "a number that is not finite";
+	if (depth >= MAX_SNAPSHOT_DEPTH) return `nested more than ${MAX_SNAPSHOT_DEPTH} levels`;
+	if (typeof value !== "object") return `a ${typeof value}`;
+	if (path.has(value)) return "a cycle";
+	const proto = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) return "an object that is not plain";
+	path.add(value);
+	for (const item of Array.isArray(value) ? value : Object.values(value)) {
+		const reason = notJson(item, depth + 1, path);
+		if (reason) return reason;
+	}
+	path.delete(value);
+}
+/** The problems with one line, judged on its own: its shape and the values it may hold. Does not look at the ask it answers. */
+function checkResolvedLine(line, path = "line") {
+	if (!isRecord(line)) return [problem("invalid_line", path, "a line is an object")];
+	const out = [];
+	const add = (code, field, message) => out.push(problem(code, `${path}.${field}`, message));
+	if (!isPlainText(line.ref, 1024)) add("invalid_ref", "ref", "ref is the ask's ref");
+	if (!isDisplayText(line.title, MAX_TITLE_LENGTH)) add("invalid_title", "title", `title is 1 to ${MAX_TITLE_LENGTH} printable characters`);
+	if (typeof line.quantity !== "number" || !Number.isSafeInteger(line.quantity) || line.quantity < 1) add("invalid_quantity", "quantity", "quantity is a whole number of at least 1");
+	if (!isMinorUnits(line.unitAmountMinor)) add("invalid_price", "unitAmountMinor", "a price is a whole number of minor units, zero or more");
+	if (!isCurrencyCode(line.currency)) add("invalid_currency", "currency", "currency is an uppercase three-letter ISO 4217 code");
+	if (!LINE_AVAILABILITIES.includes(line.availability)) add("invalid_availability", "availability", `availability is one of ${LINE_AVAILABILITIES.join(", ")}`);
+	else if (line.availability === "not_found" && line.unitAmountMinor !== 0) add("invalid_price", "unitAmountMinor", "a line that is not found has no price: it is 0");
+	if (line.maxQuantity !== void 0 && (typeof line.maxQuantity !== "number" || !Number.isSafeInteger(line.maxQuantity) || line.maxQuantity < 1)) add("invalid_max_quantity", "maxQuantity", "maxQuantity is a whole number of at least 1 when given (a line with none left is sold_out)");
+	if (line.taxCode !== void 0 && (typeof line.taxCode !== "string" || !TAX_CODE.test(line.taxCode))) add("invalid_line", "taxCode", "taxCode is 1 to 20 letters or digits when given");
+	if (typeof line.taxIncluded !== "boolean") add("invalid_line", "taxIncluded", "taxIncluded is true or false");
+	if (!FULFILMENTS.includes(line.fulfilment)) add("invalid_fulfilment", "fulfilment", `fulfilment is one of ${FULFILMENTS.join(", ")}`);
+	if (line.stock !== void 0) {
+		const stock = line.stock;
+		if (!isRecord(stock) || !isText(stock.subjectType, 80) || !SUBJECT_TYPE.test(stock.subjectType) || !isPlainText(stock.subjectId, 1024)) add("invalid_stock_subject", "stock", "stock is { subjectType, subjectId }: a dotted lowercase type (catalog.variant) and printable text");
+	}
+	if (!isRecord(line.snapshot)) add("invalid_snapshot", "snapshot", "snapshot is an object");
+	else {
+		const reason = notJson(line.snapshot, 0, /* @__PURE__ */ new Set());
+		if (reason) add("invalid_snapshot", "snapshot", `snapshot must survive JSON unchanged: it holds ${reason}`);
+		else if (new TextEncoder().encode(JSON.stringify(line.snapshot)).length > 2048) add("invalid_snapshot", "snapshot", `snapshot is more than ${MAX_SNAPSHOT_BYTES} bytes as JSON`);
+	}
+	return out;
+}
+/** The problems with a source's whole answer to `asks`: one line per ask, in order, each valid and echoing its ask's ref and quantity. */
+function checkResolvedLines(asks, lines, path = "lines") {
+	if (!Array.isArray(lines)) return [problem("invalid_lines", path, "a source returns a list of lines")];
+	if (lines.length !== asks.length) return [problem("line_count_mismatch", path, `${asks.length} asked, ${lines.length} returned: a source answers every ask, in order`)];
+	const out = [];
+	for (const [index, line] of lines.entries()) {
+		const at = `${path}[${index}]`;
+		const shape = checkResolvedLine(line, at);
+		out.push(...shape);
+		if (!isRecord(line)) continue;
+		const ask = asks[index];
+		if (line.ref !== ask.ref) out.push(problem("line_ref_mismatch", `${at}.ref`, `answered ${String(line.ref)} to ${ask.ref}: lines come back in the order asked`));
+		if (line.quantity !== ask.quantity) out.push(problem("line_quantity_mismatch", `${at}.quantity`, "a source echoes the quantity asked and never changes it"));
+	}
+	return out;
+}
+/**
+* Asks a source for the lines and checks the answer, so nothing a source gets wrong reaches a total. The source is given frozen copies, so
+* one that sorts or edits its input in place fails loudly instead of corrupting the caller's order. A source that throws is not caught: that
+* is a fault, not a problem with the answer.
+*/
+async function resolveLines(source, ctx, asks) {
+	const given = Object.freeze(asks.map((ask) => Object.freeze({
+		ref: ask.ref,
+		quantity: ask.quantity,
+		...ask.options ? { options: Object.freeze({ ...ask.options }) } : {}
+	})));
+	const lines = await source.resolve(ctx, given);
+	const problems = checkResolvedLines(asks, lines);
+	return problems.length > 0 ? {
+		ok: false,
+		problems
+	} : {
+		ok: true,
+		lines: [...lines]
+	};
+}
+/** No currency (ISO 4217 `XXX`): the price of a line that is not sold here, which is 0 and never charged. */
+const NO_CURRENCY = "XXX";
+/** `text` cut to `max` UTF-16 units with an ellipsis, never in the middle of a character. */
+function cut(text, max) {
+	if (text.length <= max) return text;
+	let out = "";
+	for (const character of text) {
+		if (out.length + character.length > max - 1) break;
+		out += character;
+	}
+	return `${out}\u2026`;
+}
+/** The line for an ask whose source is not there (a feature that was removed, a key nobody registered): not sold, like a ref no source has. */
+const notSoldHere = (ask, source) => ({
+	source,
+	ref: ask.ref,
+	title: cut(ask.ref, MAX_TITLE_LENGTH),
+	quantity: ask.quantity,
+	unitAmountMinor: 0,
+	currency: NO_CURRENCY,
+	availability: "not_found",
+	taxIncluded: true,
+	fulfilment: "none",
+	snapshot: {}
+});
+/**
+* Prices a cart whose lines name different sources: each source is asked once, for its own asks in the cart's order (through
+* {@link resolveLines}, so its answer is checked and it is given frozen copies without the `source` key), the sources at the same time, and
+* the lines come back one per ask in the cart's order, each with its `source`.
+*
+* - An ask whose source `find` does not have (a feature that was removed, a key nobody registered, an empty key) is a `not_found` line with a
+*   price of 0 in no currency (`XXX`), as a ref no source has: the cart shows it as no longer sold and totals the rest (`partitionLines`).
+* - A source that answers wrong makes the whole answer `{ ok: false, problems }`, listed source by source; a problem with one line has the cart's
+*   line as its path (`lines[3].unitAmountMinor`), one with a source's whole answer (`line_count_mismatch`) the path `lines`, and every message
+*   starts with the source's key. A source that throws is not caught.
+* - The asks are not checked here: check them where they come in (`validateAsks` for the ref, quantity and options; the registry's lookup
+*   finds only a key that was registered). A line not sold here shows its ref as its title.
+*
+* ```ts
+* const cart = await resolveCart((key) => { const found = linePort<LineSource>(key); return found.ok ? found.port : undefined; }, ctx, asks);
+* if (!cart.ok) throw new Error(cart.problems[0]?.message);
+* const { chargeable, blocked } = partitionLines(cart.lines);
+* ```
+*/
+async function resolveCart(find, ctx, asks) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const [index, ask] of asks.entries()) {
+		const key = typeof ask.source === "string" ? ask.source : "";
+		groups.set(key, [...groups.get(key) ?? [], index]);
+	}
+	const answers = await Promise.all([...groups].map(async ([key, indexes]) => {
+		const found = key === "" ? void 0 : find(key);
+		if (typeof found?.resolve !== "function") return {
+			key,
+			indexes,
+			result: void 0
+		};
+		return {
+			key,
+			indexes,
+			result: await resolveLines(found, ctx, indexes.map((index) => asks[index]))
+		};
+	}));
+	const lines = new Array(asks.length);
+	const problems = [];
+	for (const { key, indexes, result } of answers) if (result === void 0) for (const index of indexes) lines[index] = notSoldHere(asks[index], key);
+	else if (!result.ok) for (const found of result.problems) {
+		const path = found.path.replace(/^lines\[(\d+)\]/, (_match, at) => `lines[${indexes[Number(at)]}]`);
+		problems.push(problem(found.code, path, `${key}: ${found.message}`));
+	}
+	else result.lines.forEach((resolved, at) => {
+		lines[indexes[at]] = {
+			...resolved,
+			source: key
+		};
+	});
+	return problems.length > 0 ? {
+		ok: false,
+		problems
+	} : {
+		ok: true,
+		lines
+	};
+}
+/**
+* Whether a source holds its own places (`hold`, `commit` and `release` are all there), so a checkout holds its asks beside the stock. A source
+* with only some of the three is `false`, and a checkout would not hold its places: `checkPortProvider` and the line-source harness (its `holds`
+* check) report such a source.
+*/
+function holdsCapacity(source) {
+	return typeof source.hold === "function" && typeof source.commit === "function" && typeof source.release === "function";
+}
+/** Why a (valid) line cannot be charged now, or `undefined` when it can. */
+function blockedReason(line) {
+	if (line.availability !== "available") return line.availability;
+	if (line.maxQuantity !== void 0 && line.quantity > line.maxQuantity) return "over_max_quantity";
+}
+function blockedProblem(line, path) {
+	const reason = blockedReason(line);
+	if (!reason) return void 0;
+	return problem(reason, path, reason === "over_max_quantity" ? `only ${line.maxQuantity} of ${line.ref} can be taken` : `${line.ref} is ${reason.replace("_", " ")}`);
+}
+/**
+* Splits valid lines into those that can be charged and those that cannot, with the reason: a cart shows the second group ("sold out", "only 2
+* left") and totals the first. The lines keep their type, so a cart's lines keep their `source`.
+*/
+function partitionLines(lines) {
+	const chargeable = [];
+	const blocked = [];
+	for (const [index, line] of lines.entries()) {
+		const reason = blockedReason(line);
+		if (reason) blocked.push({
+			index,
+			line,
+			reason
+		});
+		else chargeable.push(line);
+	}
+	return {
+		chargeable,
+		blocked
+	};
+}
+/**
+* The lines to hold for these (resolved or priced) lines: each line that names a stock subject, with its quantity. Hold with this and not with
+* the `ref`: a hold on a subject inventory does not know is taken as untracked, always available, with no error.
+*/
+function holdLinesFrom(lines) {
+	return lines.flatMap((line) => line.stock ? [{
+		subject: { ...line.stock },
+		quantity: line.quantity
+	}] : []);
+}
+//#endregion
+export { DEFAULT_ASK_LIMITS, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, blockedProblem, blockedReason, checkResolvedLine, checkResolvedLines, holdLinesFrom, holdsCapacity, partitionLines, resolveCart, resolveLines, validateAsks, validateCartAsks };

package/dist/money-aFFtGd0E.mjs

@@ -0,0 +1,166 @@
+import { CommerceError } from "./errors.mjs";
+//#region ../money/src/index.ts
+/** Thrown for every amount this package refuses. A caller maps it onto its own error family. */
+var MoneyError = class extends Error {
+	code;
+	/** What was being read, as the caller named it (`"totalPrice"`). */
+	field;
+	constructor(code, message, field) {
+		super(message);
+		this.name = "MoneyError";
+		this.code = code;
+		this.field = field;
+	}
+};
+const CURRENCY = /^[A-Z]{3}$/;
+/** A whole, non-negative number of minor units with an uppercase three-letter currency. Zero is a valid amount here; use {@link assertMoney} to refuse it. */
+function isMoney(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return typeof v.amountMinor === "number" && Number.isSafeInteger(v.amountMinor) && v.amountMinor >= 0 && typeof v.currency === "string" && CURRENCY.test(v.currency);
+}
+/** The total of `items`, which must all be valid {@link Money} in one currency. `currency` names the total of an empty list. */
+function sumMoney(items, currency) {
+	const code = items[0]?.currency ?? currency;
+	if (code === void 0) throw new MoneyError("invalid_money", "sumMoney needs a currency for an empty list");
+	let total = 0;
+	for (const [index, item] of items.entries()) {
+		if (!isMoney(item)) throw new MoneyError("invalid_money", `sumMoney: items[${index}] is not a valid amount`, `items[${index}]`);
+		if (item.currency !== code) throw new MoneyError("currency_mismatch", `cannot add ${item.currency} to ${code}`);
+		total += item.amountMinor;
+	}
+	if (!Number.isSafeInteger(total)) throw new MoneyError("out_of_range", "the total is too large to hold exactly");
+	return {
+		amountMinor: total,
+		currency: code
+	};
+}
+//#endregion
+//#region src/money.ts
+/**
+* Minor-unit arithmetic for an order. Whole numbers only: a price, a quantity and every amount that crosses a port is a safe integer, a
+* currency is an uppercase ISO 4217 code, and two currencies are never added. The money type and the overflow-safe sum are
+* `@vibedout/money`'s; this file adds what an order needs on top (a line total, a subtraction that cannot go below zero, a rate applied in
+* whole numbers). The totals of a whole order are `./totals`.
+*/
+/** A whole, non-negative number of minor units that a JavaScript number holds exactly. */
+function isMinorUnits(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** An uppercase three-letter ISO 4217 code (`MXN`). */
+function isCurrencyCode(value) {
+	return isMoney({
+		amountMinor: 0,
+		currency: value
+	});
+}
+/** The price of `quantity` of something that costs `unitAmountMinor` each. Throws {@link CommerceError} for anything but whole numbers or a result a number cannot hold. */
+function lineTotalMinor(unitAmountMinor, quantity) {
+	if (!isMinorUnits(unitAmountMinor)) throw new CommerceError("invalid_price", "a price is a whole number of minor units, zero or more", "unitAmountMinor");
+	if (!Number.isSafeInteger(quantity) || quantity < 1) throw new CommerceError("invalid_quantity", "a quantity is a whole number of at least 1", "quantity");
+	const total = unitAmountMinor * quantity;
+	if (!Number.isSafeInteger(total)) throw new CommerceError("out_of_range", "the line total is too large to hold exactly", "unitAmountMinor");
+	return total;
+}
+/**
+* The sum of amounts in one currency, checked: every amount a whole number of minor units, and a result a number holds exactly. It is
+* `sumMoney` of `@vibedout/money`, which owns the overflow rule. Throws {@link CommerceError}.
+*/
+function sumMinor(currency, amounts) {
+	if (!isCurrencyCode(currency)) throw new CommerceError("invalid_currency", "a currency is an uppercase three-letter ISO 4217 code", "currency");
+	try {
+		return sumMoney(amounts.map((amountMinor) => ({
+			amountMinor,
+			currency
+		})), currency).amountMinor;
+	} catch (error) {
+		if (error instanceof MoneyError) throw new CommerceError(error.code === "out_of_range" ? "out_of_range" : "invalid_price", error.message);
+		throw error;
+	}
+}
+/** `from` minus `amount`, never below zero: a discount cannot be larger than what it discounts. Throws {@link CommerceError}. */
+function subtractMinor(from, amount) {
+	if (!isMinorUnits(from) || !isMinorUnits(amount)) throw new CommerceError("out_of_range", "both amounts are whole numbers of minor units, zero or more");
+	if (amount > from) throw new CommerceError("discount_exceeds_subtotal", `cannot take ${amount} from ${from}`);
+	return from - amount;
+}
+const ROUNDINGS = [
+	"half-up",
+	"down",
+	"up"
+];
+/** The highest rate there is: 1000%, 100000 basis points. A discount is at most 10000 (100%); a tax can be more (Mexican IEPS on tobacco is 160%). */
+const MAX_RATE_BP = 1e5;
+/** A rate in basis points: 16% is 1600, a whole number from 0 to {@link MAX_RATE_BP}. */
+const isRateBp = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= 1e5;
+/** `amount * numerator / denominator`, rounded, with BigInt for the product so a large amount does not lose a centavo to a float. */
+function scaled(amountMinor, numerator, denominator, rounding) {
+	if (!isMinorUnits(amountMinor)) throw new CommerceError("out_of_range", "an amount is a whole number of minor units, zero or more", "amountMinor");
+	if (!ROUNDINGS.includes(rounding)) throw new CommerceError("invalid_adjustment", `rounding is one of ${ROUNDINGS.join(", ")}`, "rounding");
+	const product = BigInt(amountMinor) * BigInt(numerator);
+	const divisor = BigInt(denominator);
+	const quotient = product / divisor;
+	const remainder = product % divisor;
+	const result = (rounding === "up" ? remainder > 0n : rounding === "half-up" ? remainder * 2n >= divisor : false) ? quotient + 1n : quotient;
+	if (result > BigInt(Number.MAX_SAFE_INTEGER)) throw new CommerceError("out_of_range", "the result is too large to hold exactly");
+	return Number(result);
+}
+/**
+* `rateBp` of an amount, in whole minor units: `basisPointsOf(10_000, 1600)` is 1600 (16% of 100.00). Use this and not `amount * 0.16`: a float
+* rounds a centavo the wrong way now and then (`(1.005).toFixed(2)` is "1.00"). A rate over 10000 (100%) is a tax such as IEPS; a result larger
+* than a number holds exactly is refused. Throws {@link CommerceError}.
+*/
+function basisPointsOf(amountMinor, rateBp, rounding = "half-up") {
+	if (!isRateBp(rateBp)) throw new CommerceError("invalid_adjustment", "a rate is a whole number of basis points from 0 to 100000 (16% is 1600)", "rateBp");
+	return scaled(amountMinor, rateBp, 1e4, rounding);
+}
+/**
+* The tax that is already inside a gross price: a shelf price of 116.00 with IVA at 16% holds 16.00 (`taxIncludedIn(11_600, 1600)`). It is
+* `gross * rate / (10000 + rate)`, so the net price is `subtractMinor(gross, tax)`. Throws {@link CommerceError}.
+*/
+function taxIncludedIn(grossMinor, rateBp, rounding = "half-up") {
+	if (!isRateBp(rateBp)) throw new CommerceError("invalid_adjustment", "a rate is a whole number of basis points from 0 to 100000 (16% is 1600)", "rateBp");
+	return scaled(grossMinor, rateBp, 1e4 + rateBp, rounding);
+}
+/**
+* `totalMinor` split over `weights` in proportion, in whole minor units that add up to `totalMinor` exactly: a discount spread over the lines
+* of an order (each line's total as its weight) for an invoice that states each line's discount (a CFDI does). Largest remainder: each share
+* is its exact proportion rounded down, and the centavos left go one each to the largest fractions, the earlier line first on a tie. When
+* the total is not more than the weights add up to, no share is more than its weight, so a discount never takes a line below zero; a weight
+* of 0 gets 0. The product is BigInt, so a large amount loses nothing. `@vibedout/payments` spreads a discount over the lines of a provider's
+* page by the same rule, so the invoice and the page agree line by line when the discount says nothing about its lines; a discount that does
+* (`AppliedDiscount.lines`, 0.2.2) is used as it says.
+*
+* ```ts
+* allocateMinor(1000, [3000, 1000]); // [750, 250]: 10.00 off a 30.00 and a 10.00 line
+* allocateMinor(100, [1, 1, 1]);     // [34, 33, 33]
+* ```
+*
+* Throws {@link CommerceError}: `out_of_range` for a total or a weight that is not a whole number of minor units, `invalid_adjustment` for no
+* weights, or something to split over weights that are all zero.
+*/
+function allocateMinor(totalMinor, weights) {
+	if (!isMinorUnits(totalMinor)) throw new CommerceError("out_of_range", "the amount to split is a whole number of minor units, zero or more", "totalMinor");
+	if (!Array.isArray(weights) || weights.length === 0) throw new CommerceError("invalid_adjustment", "an amount is split over at least one weight", "weights");
+	for (const [index, weight] of weights.entries()) if (!isMinorUnits(weight)) throw new CommerceError("out_of_range", "a weight is a whole number of minor units, zero or more", `weights[${index}]`);
+	const sum = weights.reduce((total, weight) => total + BigInt(weight), 0n);
+	if (sum === 0n) {
+		if (totalMinor === 0) return weights.map(() => 0);
+		throw new CommerceError("invalid_adjustment", `cannot split ${totalMinor} over weights that are all zero`, "weights");
+	}
+	const total = BigInt(totalMinor);
+	const shares = weights.map((weight) => BigInt(weight) * total / sum);
+	const order = weights.map((weight, index) => ({
+		index,
+		rest: BigInt(weight) * total % sum
+	})).sort((a, b) => a.rest === b.rest ? a.index - b.index : a.rest > b.rest ? -1 : 1);
+	let left = total - shares.reduce((sumOfShares, share) => sumOfShares + share, 0n);
+	for (const { index } of order) {
+		if (left === 0n) break;
+		shares[index] = shares[index] + 1n;
+		left -= 1n;
+	}
+	return shares.map((share) => Number(share));
+}
+//#endregion
+export { isCurrencyCode as a, subtractMinor as c, basisPointsOf as i, sumMinor as l, ROUNDINGS as n, isMinorUnits as o, allocateMinor as r, lineTotalMinor as s, MAX_RATE_BP as t, taxIncludedIn as u };

package/dist/money.d.mts

@@ -0,0 +1,50 @@
+//#region src/money.d.ts
+/** A whole, non-negative number of minor units that a JavaScript number holds exactly. */
+declare function isMinorUnits(value: unknown): value is number;
+/** An uppercase three-letter ISO 4217 code (`MXN`). */
+declare function isCurrencyCode(value: unknown): value is string;
+/** The price of `quantity` of something that costs `unitAmountMinor` each. Throws {@link CommerceError} for anything but whole numbers or a result a number cannot hold. */
+declare function lineTotalMinor(unitAmountMinor: number, quantity: number): number;
+/**
+ * The sum of amounts in one currency, checked: every amount a whole number of minor units, and a result a number holds exactly. It is
+ * `sumMoney` of `@vibedout/money`, which owns the overflow rule. Throws {@link CommerceError}.
+ */
+declare function sumMinor(currency: string, amounts: readonly number[]): number;
+/** `from` minus `amount`, never below zero: a discount cannot be larger than what it discounts. Throws {@link CommerceError}. */
+declare function subtractMinor(from: number, amount: number): number;
+declare const ROUNDINGS: readonly ["half-up", "down", "up"];
+/** What to do with the fraction of a centavo: `half-up` is the usual rule (0.5 goes up), `down` and `up` are for a rule that says so. */
+type Rounding = (typeof ROUNDINGS)[number];
+/** The highest rate there is: 1000%, 100000 basis points. A discount is at most 10000 (100%); a tax can be more (Mexican IEPS on tobacco is 160%). */
+declare const MAX_RATE_BP = 100000;
+/**
+ * `rateBp` of an amount, in whole minor units: `basisPointsOf(10_000, 1600)` is 1600 (16% of 100.00). Use this and not `amount * 0.16`: a float
+ * rounds a centavo the wrong way now and then (`(1.005).toFixed(2)` is "1.00"). A rate over 10000 (100%) is a tax such as IEPS; a result larger
+ * than a number holds exactly is refused. Throws {@link CommerceError}.
+ */
+declare function basisPointsOf(amountMinor: number, rateBp: number, rounding?: Rounding): number;
+/**
+ * The tax that is already inside a gross price: a shelf price of 116.00 with IVA at 16% holds 16.00 (`taxIncludedIn(11_600, 1600)`). It is
+ * `gross * rate / (10000 + rate)`, so the net price is `subtractMinor(gross, tax)`. Throws {@link CommerceError}.
+ */
+declare function taxIncludedIn(grossMinor: number, rateBp: number, rounding?: Rounding): number;
+/**
+ * `totalMinor` split over `weights` in proportion, in whole minor units that add up to `totalMinor` exactly: a discount spread over the lines
+ * of an order (each line's total as its weight) for an invoice that states each line's discount (a CFDI does). Largest remainder: each share
+ * is its exact proportion rounded down, and the centavos left go one each to the largest fractions, the earlier line first on a tie. When
+ * the total is not more than the weights add up to, no share is more than its weight, so a discount never takes a line below zero; a weight
+ * of 0 gets 0. The product is BigInt, so a large amount loses nothing. `@vibedout/payments` spreads a discount over the lines of a provider's
+ * page by the same rule, so the invoice and the page agree line by line when the discount says nothing about its lines; a discount that does
+ * (`AppliedDiscount.lines`, 0.2.2) is used as it says.
+ *
+ * ```ts
+ * allocateMinor(1000, [3000, 1000]); // [750, 250]: 10.00 off a 30.00 and a 10.00 line
+ * allocateMinor(100, [1, 1, 1]);     // [34, 33, 33]
+ * ```
+ *
+ * Throws {@link CommerceError}: `out_of_range` for a total or a weight that is not a whole number of minor units, `invalid_adjustment` for no
+ * weights, or something to split over weights that are all zero.
+ */
+declare function allocateMinor(totalMinor: number, weights: readonly number[]): number[];
+//#endregion
+export { MAX_RATE_BP, ROUNDINGS, Rounding, allocateMinor, basisPointsOf, isCurrencyCode, isMinorUnits, lineTotalMinor, subtractMinor, sumMinor, taxIncludedIn };

package/dist/money.mjs

@@ -0,0 +1,2 @@
+import { a as isCurrencyCode, c as subtractMinor, i as basisPointsOf, l as sumMinor, n as ROUNDINGS, o as isMinorUnits, r as allocateMinor, s as lineTotalMinor, t as MAX_RATE_BP, u as taxIncludedIn } from "./money-aFFtGd0E.mjs";
+export { MAX_RATE_BP, ROUNDINGS, allocateMinor, basisPointsOf, isCurrencyCode, isMinorUnits, lineTotalMinor, subtractMinor, sumMinor, taxIncludedIn };

package/dist/payments.d.mts

@@ -0,0 +1,32 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { $ as StartPaymentInput, c as CommerceLocale, n as AdjustmentKind, z as PaymentMethod } from "./types-BUyLunnB.mjs";
+import { Totals } from "./totals.mjs";
+//#region src/payments.d.ts
+/**
+ * The problems with a request to start a payment. A payments port runs this first and answers `invalid_request` when the list is not empty;
+ * a total of zero is `free_order` (the order is paid without a provider), not a charge. The discounts come off the lines: together they may
+ * not be more than the lines, whatever the shipping and the tax add.
+ */
+declare function checkStartPayment(input: unknown): CommerceProblem[];
+interface PaymentRequestParts {
+  /** The order's id. */
+  reference: string;
+  successUrl: string;
+  cancelUrl: string;
+  payer?: StartPaymentInput["payer"];
+  methods?: readonly PaymentMethod[];
+  expiresAt?: number;
+  metadata?: Readonly<Record<string, string>>;
+  /** The names of the three adjustments on the provider's page. Default by `locale`. */
+  labels?: Partial<Record<AdjustmentKind, string>>;
+  /** Picks the default labels. Default `es-MX`. */
+  locale?: CommerceLocale;
+}
+/**
+ * The request for `totals`: its lines, and its shipping, added tax and discounts as adjustments (each discount with the lines it came off,
+ * 0.2.4), so the provider's page and the order agree to the centavo, line by line. It does not check anything; {@link checkStartPayment} does, and a total of
+ * zero is a free order that starts no payment.
+ */
+declare function paymentRequestFrom(totals: Totals, parts: PaymentRequestParts): StartPaymentInput;
+//#endregion
+export { PaymentRequestParts, checkStartPayment, paymentRequestFrom };