@vibedout/commerce 0.0.0-stage → 0.2.3

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,31 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { Q as StartPaymentInput, R as PaymentMethod, c as CommerceLocale, n as AdjustmentKind } from "./types-BzlVbRp1.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, so the provider's page and the order agree
+ * to the centavo. 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 };

package/dist/payments.mjs

@@ -0,0 +1,166 @@
+import { problem } from "./errors.mjs";
+import { a as isText, i as isRecord, r as isDisplayText } from "./internal-p2FS_A4L.mjs";
+import { a as isCurrencyCode, l as sumMinor, o as isMinorUnits, s as lineTotalMinor } from "./money-aFFtGd0E.mjs";
+import { ADJUSTMENT_KINDS, PAYMENT_METHODS } from "./types.mjs";
+//#region src/payments.ts
+/**
+* The payment request a checkout hands the payments port, and the check a payments port runs on one before it opens a provider's page.
+* The lines and adjustments must add up to the total: a provider charges what the request says, so a request that does not reconcile is
+* refused instead of charged.
+*/
+/** The longest title a payment line or adjustment may have: what a provider's page can show. */
+const MAX_TITLE = 200;
+const MAX_METADATA_ENTRIES = 20;
+const MAX_METADATA_VALUE = 500;
+/** A page the provider sends the payer back to: https, or http on the machine itself for development. */
+function isReturnUrl(value) {
+	if (typeof value !== "string" || value.length > 2048) return false;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (url.username !== "" || url.password !== "") return false;
+	if (url.protocol === "https:") return true;
+	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]");
+}
+/**
+* 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.
+*/
+function checkStartPayment(input) {
+	if (!isRecord(input)) return [problem("invalid_payment", "input", "a payment request is an object")];
+	const out = [];
+	const add = (code, path, message) => out.push(problem(code, path, message));
+	if (!isText(input.reference, 120)) add("invalid_payment", "reference", "reference is the order's id: 1 to 120 printable characters");
+	const currency = input.currency;
+	if (!isCurrencyCode(currency)) add("invalid_currency", "currency", "currency is an uppercase three-letter ISO 4217 code");
+	if (!isReturnUrl(input.successUrl)) add("invalid_payment", "successUrl", "successUrl is an https address (http only on localhost) with no login in it");
+	if (!isReturnUrl(input.cancelUrl)) add("invalid_payment", "cancelUrl", "cancelUrl is an https address (http only on localhost) with no login in it");
+	if (input.expiresAt !== void 0 && (typeof input.expiresAt !== "number" || !Number.isSafeInteger(input.expiresAt) || input.expiresAt <= 0)) add("invalid_payment", "expiresAt", "expiresAt is milliseconds since the epoch");
+	if (input.methods !== void 0) {
+		const methods = input.methods;
+		if (!Array.isArray(methods) || methods.length === 0 || methods.some((method) => !PAYMENT_METHODS.includes(method))) add("invalid_payment", "methods", `methods is a non-empty list of ${PAYMENT_METHODS.join(", ")}`);
+	}
+	if (input.payer !== void 0) {
+		const payer = input.payer;
+		if (!isRecord(payer) || payer.userId !== void 0 && !isText(payer.userId, 120) || payer.email !== void 0 && (!isText(payer.email, 254) || !payer.email.includes("@"))) add("invalid_payment", "payer", "payer is { userId?, email? }");
+	}
+	if (input.metadata !== void 0) {
+		const metadata = input.metadata;
+		const entries = isRecord(metadata) ? Object.entries(metadata) : void 0;
+		if (!entries || entries.length > MAX_METADATA_ENTRIES || entries.some(([key, value]) => !isText(key, 40) || typeof value !== "string" || value.length > MAX_METADATA_VALUE)) add("invalid_payment", "metadata", `metadata is at most ${MAX_METADATA_ENTRIES} strings under short names`);
+	}
+	const lineTotals = [];
+	if (!Array.isArray(input.lines) || input.lines.length === 0) add("invalid_payment", "lines", "a payment has at least one line");
+	else for (const [index, line] of input.lines.entries()) {
+		const path = `lines[${index}]`;
+		if (!isRecord(line) || !isDisplayText(line.title, MAX_TITLE)) add("invalid_payment", path, "a line has a title");
+		else if (line.currency !== currency) add("currency_mismatch", `${path}.currency`, "every line is in the request's currency");
+		else try {
+			lineTotals.push(lineTotalMinor(line.unitAmountMinor, line.quantity));
+		} catch {
+			add("invalid_payment", path, "a line has a whole price in minor units and a whole quantity of at least 1");
+		}
+	}
+	const adjustments = input.adjustments === void 0 ? [] : input.adjustments;
+	const signed = {
+		shipping: [],
+		tax: [],
+		discount: []
+	};
+	if (!Array.isArray(adjustments)) add("invalid_payment", "adjustments", "adjustments is a list");
+	else for (const [index, adjustment] of adjustments.entries()) {
+		const path = `adjustments[${index}]`;
+		if (!isRecord(adjustment) || !ADJUSTMENT_KINDS.includes(adjustment.kind) || !isDisplayText(adjustment.title, MAX_TITLE) || !isMinorUnits(adjustment.amountMinor)) add("invalid_payment", path, "an adjustment has a kind (shipping, tax or discount), a title and a whole amount of minor units, zero or more");
+		else if (adjustment.currency !== currency) add("currency_mismatch", `${path}.currency`, "every adjustment is in the request's currency");
+		else signed[adjustment.kind].push(adjustment.amountMinor);
+	}
+	if (!isMinorUnits(input.totalMinor)) add("invalid_payment", "totalMinor", "totalMinor is a whole number of minor units");
+	if (out.length > 0) return out;
+	const code = currency;
+	try {
+		const items = sumMinor(code, lineTotals);
+		const gross = sumMinor(code, [
+			items,
+			...signed.shipping,
+			...signed.tax
+		]);
+		const discount = sumMinor(code, signed.discount);
+		if (discount > items) add("payment_not_reconciled", "adjustments", `the discounts are larger than the items they are taken from (${discount} against ${items})`);
+		else if (gross - discount !== input.totalMinor) add("payment_not_reconciled", "totalMinor", `the lines and adjustments come to ${gross - discount} and the total says ${String(input.totalMinor)}`);
+		else if (input.totalMinor === 0) add("free_order", "totalMinor", "nothing to charge: a free order is paid without a provider");
+	} catch {
+		add("payment_not_reconciled", "lines", "the amounts are too large to add exactly");
+	}
+	return out;
+}
+const DEFAULT_LABELS = {
+	"es-MX": {
+		shipping: "Envío",
+		tax: "Impuestos",
+		discount: "Descuento"
+	},
+	en: {
+		shipping: "Shipping",
+		tax: "Tax",
+		discount: "Discount"
+	}
+};
+/**
+* The request for `totals`: its lines, and its shipping, added tax and discounts as adjustments, so the provider's page and the order agree
+* to the centavo. It does not check anything; {@link checkStartPayment} does, and a total of zero is a free order that starts no payment.
+*/
+function paymentRequestFrom(totals, parts) {
+	const labels = {
+		...DEFAULT_LABELS[parts.locale ?? "es-MX"],
+		...parts.labels
+	};
+	const currency = totals.currency;
+	const adjustments = [];
+	if (totals.shippingMinor > 0) adjustments.push({
+		kind: "shipping",
+		title: totals.shipping?.title ?? labels.shipping,
+		amountMinor: totals.shippingMinor,
+		currency
+	});
+	if (totals.taxMinor > 0) {
+		const named = totals.taxBreakdown.filter((part) => !part.included).map((part) => part.title).join(" + ");
+		adjustments.push({
+			kind: "tax",
+			title: named !== "" && named.length <= MAX_TITLE ? named : labels.tax,
+			amountMinor: totals.taxMinor,
+			currency
+		});
+	}
+	for (const discount of totals.discounts) if (discount.amountMinor > 0) adjustments.push({
+		kind: "discount",
+		title: discount.title || labels.discount,
+		amountMinor: discount.amountMinor,
+		currency
+	});
+	return {
+		reference: parts.reference,
+		lines: totals.lines.map((line) => ({
+			ref: line.ref,
+			title: line.title,
+			quantity: line.quantity,
+			unitAmountMinor: line.unitAmountMinor,
+			currency,
+			...line.taxCode === void 0 ? {} : { taxCode: line.taxCode }
+		})),
+		adjustments,
+		totalMinor: totals.totalMinor,
+		currency,
+		...parts.payer ? { payer: parts.payer } : {},
+		...parts.methods ? { methods: parts.methods } : {},
+		successUrl: parts.successUrl,
+		cancelUrl: parts.cancelUrl,
+		...parts.expiresAt === void 0 ? {} : { expiresAt: parts.expiresAt },
+		...parts.metadata ? { metadata: parts.metadata } : {}
+	};
+}
+//#endregion
+export { checkStartPayment, paymentRequestFrom };

package/dist/ports.d.mts

@@ -0,0 +1,40 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { H as PortProviders, V as PortName } from "./types-BzlVbRp1.mjs";
+//#region src/ports.d.ts
+type MethodsOf<K extends PortName> = Extract<keyof PortProviders[K], string>;
+/**
+ * The methods every provider of each port has. The type below fails to compile when this list and {@link OPTIONAL_PORT_METHODS} miss one or
+ * name one that is gone.
+ */
+declare const PORT_METHODS: {
+  readonly "line-source": readonly ["resolve"];
+  readonly stock: readonly ["availability", "hold", "commit", "release"];
+  readonly payments: readonly ["start"];
+  readonly tax: readonly ["compute"];
+  readonly "shipping-rates": readonly ["quote"];
+  readonly discount: readonly ["apply"];
+};
+/**
+ * The methods a provider may leave out (added after a port's first version, so an older provider still is one). A caller checks that it is
+ * there before it calls it; when it is there, it must be a function.
+ */
+declare const OPTIONAL_PORT_METHODS: {
+  readonly "line-source": readonly ["hold", "commit", "release"];
+  readonly stock: readonly ["fulfil", "uncommit"];
+  readonly payments: readonly ["cancel"];
+  readonly tax: readonly [];
+  readonly "shipping-rates": readonly [];
+  readonly discount: readonly [];
+};
+/** `never` while {@link PORT_METHODS} and {@link OPTIONAL_PORT_METHODS} list every method of every port between them. */
+type UnlistedPortMethods = { [K in PortName]: Exclude<MethodsOf<K>, (typeof PORT_METHODS)[K][number] | (typeof OPTIONAL_PORT_METHODS)[K][number]>; }[PortName];
+/** The port names, in the order the engine lists them (`WORKER_PORTS`). */
+declare const PORT_NAMES: PortName[];
+declare const isPortName: (value: unknown) => value is PortName;
+/**
+ * The methods `value` lacks to be a provider of `port`, the optional ones it has that are not functions, and the ones missing from a set it
+ * has only part of (`hold` without `commit` and `release`). An empty list means it has them all (it does not run them).
+ */
+declare function checkPortProvider(port: PortName, value: unknown, path?: string): CommerceProblem[];
+//#endregion
+export { OPTIONAL_PORT_METHODS, PORT_METHODS, PORT_NAMES, UnlistedPortMethods, checkPortProvider, isPortName };

package/dist/ports.mjs

@@ -0,0 +1,73 @@
+import { problem } from "./errors.mjs";
+//#region src/ports.ts
+/**
+* What a provider of each port must have, as data a feature's test can check: `checkPortProvider("stock", fxStock)` lists the methods the
+* export is missing. The compiler already checks a provider typed as `PortProviders["stock"]`; this is for the one that is not (a provider
+* assembled by a factory, or written in plain JavaScript) and for the registry's own test.
+*/
+/**
+* The methods every provider of each port has. The type below fails to compile when this list and {@link OPTIONAL_PORT_METHODS} miss one or
+* name one that is gone.
+*/
+const PORT_METHODS = {
+	"line-source": ["resolve"],
+	stock: [
+		"availability",
+		"hold",
+		"commit",
+		"release"
+	],
+	payments: ["start"],
+	tax: ["compute"],
+	"shipping-rates": ["quote"],
+	discount: ["apply"]
+};
+/**
+* The methods a provider may leave out (added after a port's first version, so an older provider still is one). A caller checks that it is
+* there before it calls it; when it is there, it must be a function.
+*/
+const OPTIONAL_PORT_METHODS = {
+	"line-source": [
+		"hold",
+		"commit",
+		"release"
+	],
+	stock: ["fulfil", "uncommit"],
+	payments: ["cancel"],
+	tax: [],
+	"shipping-rates": [],
+	discount: []
+};
+/** Optional methods that come as a set: a provider has every one of a set or none (a line source that holds its places commits and releases them). */
+const TOGETHER = { "line-source": [[
+	"hold",
+	"commit",
+	"release"
+]] };
+/** The port names, in the order the engine lists them (`WORKER_PORTS`). */
+const PORT_NAMES = Object.keys(PORT_METHODS);
+const isPortName = (value) => typeof value === "string" && Object.hasOwn(PORT_METHODS, value);
+/**
+* The methods `value` lacks to be a provider of `port`, the optional ones it has that are not functions, and the ones missing from a set it
+* has only part of (`hold` without `commit` and `release`). An empty list means it has them all (it does not run them).
+*/
+function checkPortProvider(port, value, path = port) {
+	if (!isPortName(port)) return [problem("invalid_port", path, `${String(port)} is not a port`)];
+	if (typeof value !== "object" && typeof value !== "function") return [problem("invalid_port", path, `a ${port} provider is an object with ${PORT_METHODS[port].join(", ")}`)];
+	if (value === null) return [problem("invalid_port", path, `a ${port} provider is an object with ${PORT_METHODS[port].join(", ")}`)];
+	const methods = value;
+	const missing = PORT_METHODS[port].filter((method) => typeof methods[method] !== "function").map((method) => problem("invalid_port", `${path}.${method}`, `a ${port} provider has a ${method} method`));
+	const wrong = OPTIONAL_PORT_METHODS[port].filter((method) => methods[method] !== void 0 && typeof methods[method] !== "function").map((method) => problem("invalid_port", `${path}.${method}`, `${method} is optional, and a function when a ${port} provider has it`));
+	const partial = (TOGETHER[port] ?? []).flatMap((set) => {
+		const absent = set.filter((method) => methods[method] === void 0);
+		if (absent.length === 0 || absent.length === set.length) return [];
+		return absent.map((method) => problem("invalid_port", `${path}.${method}`, `a ${port} provider with any of ${set.join(", ")} has all of them`));
+	});
+	return [
+		...missing,
+		...wrong,
+		...partial
+	];
+}
+//#endregion
+export { OPTIONAL_PORT_METHODS, PORT_METHODS, PORT_NAMES, checkPortProvider, isPortName };

package/dist/snapshot.d.mts

@@ -0,0 +1,26 @@
+import { M as LineSnapshot } from "./types-BzlVbRp1.mjs";
+//#region src/snapshot.d.ts
+declare const SNAPSHOT_KEYS: {
+  /** The stock-keeping unit: the code a discount rule names and a person reads on a packing slip. */
+  readonly sku: "sku";
+  /** The id of the product the line is a variant of, in the source's own ids: a discount rule can cover every variant of a product. */
+  readonly productId: "productId";
+  /** The tax class the goods are in (`standard`, `zero`, `exempt`), which a tax provider maps to a rate. Not the SAT product key (`ResolvedLine.taxCode`). */
+  readonly taxClass: "taxClass";
+};
+type SnapshotKey = keyof typeof SNAPSHOT_KEYS;
+/** The longest value of any of these keys. */
+declare const MAX_SNAPSHOT_TEXT = 120;
+/**
+ * The text a source wrote under one of the {@link SNAPSHOT_KEYS}, or `undefined` when it wrote none, or something that is not a short string of
+ * printable characters. A reader never trusts the rest of the snapshot: this is the only way a feature in this family reads it.
+ *
+ * ```ts
+ * const sku = snapshotText(line, "sku"); // a rule for "TAG-CARD-GREVIEW" matches this line when it is that
+ * ```
+ */
+declare function snapshotText(line: {
+  snapshot?: LineSnapshot;
+}, key: SnapshotKey): string | undefined;
+//#endregion
+export { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, SnapshotKey, snapshotText };

package/dist/snapshot.mjs

@@ -0,0 +1,32 @@
+import { a as isText } from "./internal-p2FS_A4L.mjs";
+//#region src/snapshot.ts
+/**
+* What a line source writes in a line's `snapshot` so that the features that price and tax the line can find it without importing the source
+* (0.2.2). The snapshot is free-form (a source adds what its receipt needs); these keys are the few that other features read, so they are fixed
+* here and a source that sells goods writes them. A feature that finds none of them still works: a discount rule for a SKU matches nothing and a
+* tax provider uses its default class.
+*/
+const SNAPSHOT_KEYS = {
+	/** The stock-keeping unit: the code a discount rule names and a person reads on a packing slip. */
+	sku: "sku",
+	/** The id of the product the line is a variant of, in the source's own ids: a discount rule can cover every variant of a product. */
+	productId: "productId",
+	/** The tax class the goods are in (`standard`, `zero`, `exempt`), which a tax provider maps to a rate. Not the SAT product key (`ResolvedLine.taxCode`). */
+	taxClass: "taxClass"
+};
+/** The longest value of any of these keys. */
+const MAX_SNAPSHOT_TEXT = 120;
+/**
+* The text a source wrote under one of the {@link SNAPSHOT_KEYS}, or `undefined` when it wrote none, or something that is not a short string of
+* printable characters. A reader never trusts the rest of the snapshot: this is the only way a feature in this family reads it.
+*
+* ```ts
+* const sku = snapshotText(line, "sku"); // a rule for "TAG-CARD-GREVIEW" matches this line when it is that
+* ```
+*/
+function snapshotText(line, key) {
+	const value = line.snapshot?.[SNAPSHOT_KEYS[key]];
+	return isText(value, 120) ? value : void 0;
+}
+//#endregion
+export { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, snapshotText };