@vibedout/commerce 0.0.0-stage → 0.2.4

package/dist/discounts.mjs

@@ -0,0 +1,185 @@
+import { CommerceError, problem } from "./errors.mjs";
+import { i as isRecord } from "./internal-p2FS_A4L.mjs";
+import { o as isMinorUnits, r as allocateMinor, s as lineTotalMinor } from "./money-aFFtGd0E.mjs";
+//#region src/discounts.ts
+/**
+* What a discount did to each line (0.2.2). A discount port answers amounts for the order; a tax is worked on what each line costs after its
+* discount, and an invoice (a CFDI) states a discount per line. These are the two ways to know that amount: the discount says which lines it
+* came off ({@link AppliedDiscount.lines}), or it is spread over the lines in proportion to their totals.
+*
+* 0.2.4 makes that one notion for everyone who needs it: {@link attributeDiscounts} gives every discount its lines (the ones it said, else its
+* share of what the others left), and {@link lineDiscountsOf} adds them up per line. The tax port is asked with that, `computeTotals` keeps it on
+* each `PricedLine` and in `Totals.discounts`, `paymentRequestFrom` sends it to the payments port, and an order keeps it on its lines, so the
+* tax, the provider's page and the invoice all state the same discount on the same line.
+*/
+/**
+* `discountMinor` spread over the lines in proportion to their totals, in whole minor units that add up to it exactly (`allocateMinor`): what a
+* tax provider does when the discounts do not say which lines they came off. No line gives more than its total. Throws {@link CommerceError}
+* (`discount_exceeds_subtotal`) when the discount is more than the lines cost together.
+*
+* ```ts
+* spreadDiscount([{ unitAmountMinor: 3000, quantity: 1 }, { unitAmountMinor: 1000, quantity: 1 }], 1000); // [750, 250]
+* ```
+*/
+function spreadDiscount(lines, discountMinor) {
+	const totals = lines.map((line) => lineTotalMinor(line.unitAmountMinor, line.quantity));
+	if (!isMinorUnits(discountMinor)) throw new CommerceError("out_of_range", "a discount is a whole number of minor units, zero or more", "discountMinor");
+	if (discountMinor === 0) return totals.map(() => 0);
+	if (totals.length === 0) throw new CommerceError("discount_exceeds_subtotal", "there are no lines to take a discount from", "lines");
+	const sum = totals.reduce((total, amount) => total + amount, 0);
+	if (discountMinor > sum) throw new CommerceError("discount_exceeds_subtotal", `a discount of ${discountMinor} is more than the lines cost (${sum})`, "discountMinor");
+	return allocateMinor(discountMinor, totals);
+}
+/**
+* The problems with the attributions of `discounts` over `lines`: every discount that takes something off says which lines it came off, each
+* `index` is a line, the amounts are whole and add up to the discount's `amountMinor`, and no line is discounted by more than it costs. A
+* discount of 0 needs nothing. An empty list means {@link lineDiscountsFrom} can answer.
+*/
+function checkLineDiscounts(lines, discounts, path = "discounts") {
+	const out = [];
+	const taken = lines.map(() => 0);
+	for (const [at, discount] of discounts.entries()) {
+		const where = `${path}[${at}]`;
+		if (!isRecord(discount) || !isMinorUnits(discount.amountMinor)) {
+			out.push(problem("invalid_adjustment", where, "a discount has a whole amount of minor units, zero or more"));
+			continue;
+		}
+		if (discount.amountMinor === 0) continue;
+		if (!Array.isArray(discount.lines)) {
+			out.push(problem("invalid_adjustment", `${where}.lines`, "a discount that takes something off says which lines it came off"));
+			continue;
+		}
+		let sum = 0;
+		const seen = /* @__PURE__ */ new Set();
+		const parts = discount.lines;
+		for (const [position, part] of parts.entries()) {
+			const partPath = `${where}.lines[${position}]`;
+			const index = isRecord(part) ? part.index : void 0;
+			const amountMinor = isRecord(part) ? part.amountMinor : void 0;
+			if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0 || index >= lines.length) {
+				out.push(problem("invalid_adjustment", partPath, "index is the position of a line"));
+				continue;
+			}
+			if (!isMinorUnits(amountMinor)) {
+				out.push(problem("invalid_adjustment", partPath, "amountMinor is a whole number of minor units, zero or more"));
+				continue;
+			}
+			if (seen.has(index)) {
+				out.push(problem("invalid_adjustment", partPath, "a line appears once in a discount"));
+				continue;
+			}
+			seen.add(index);
+			sum += amountMinor;
+			taken[index] = taken[index] + amountMinor;
+		}
+		if (sum !== discount.amountMinor) out.push(problem("invalid_adjustment", `${where}.lines`, `the lines add up to ${sum}, the discount is ${discount.amountMinor}`));
+	}
+	for (const [index, line] of lines.entries()) if (isMinorUnits(line.unitAmountMinor) && Number.isSafeInteger(line.quantity) && line.quantity >= 1) {
+		const total = lineTotalMinor(line.unitAmountMinor, line.quantity);
+		if (taken[index] > total) out.push(problem("discount_exceeds_subtotal", `${path}.lines[${index}]`, `line ${index} is discounted by ${taken[index]}, it costs ${total}`));
+	}
+	return out;
+}
+/**
+* What the discounts took off each line, in the order of `lines`, or `undefined` when they do not say (a discount of the whole order, or
+* attributions that {@link checkLineDiscounts} refuses): then spread the total with {@link spreadDiscount}. Pass the result as
+* `TaxInput.lineDiscountsMinor`.
+*
+* ```ts
+* const perLine = lineDiscountsFrom(lines, applied) ?? spreadDiscount(lines, discountMinor);
+* ```
+*/
+function lineDiscountsFrom(lines, discounts) {
+	if (checkLineDiscounts(lines, discounts).length > 0) return void 0;
+	const taken = lines.map(() => 0);
+	for (const discount of discounts) {
+		if (discount.amountMinor === 0) continue;
+		for (const part of discount.lines ?? []) taken[part.index] = taken[part.index] + part.amountMinor;
+	}
+	return taken;
+}
+/**
+* The discounts with the lines each came off, every one that takes something off (0.2.4):
+*
+* - a discount that says its lines ({@link AppliedDiscount.lines}, valid by {@link checkLineDiscounts}) keeps them, as long as together no line
+*   is discounted by more than it costs;
+* - a discount that does not (a code for the whole order), or whose lines are not valid, is spread over what the others left of the lines in
+*   proportion to it, to the centavo (`allocateMinor`), in the order the discounts are given;
+* - when the attributions that were given would take more off a line than it costs, none of them is trusted and every discount is spread.
+*
+* With no discount that names its lines this is {@link spreadDiscount} of each, so a project that did not know about `lines` states what it did
+* before. A discount of 0 is left as given, without lines. The amounts are the discounts' own; the answer adds up to them exactly. Throws
+* {@link CommerceError}: `discount_exceeds_subtotal` when the discounts are more than the lines cost, `out_of_range` for an amount that is not whole.
+*
+* ```ts
+* const lines = [{ unitAmountMinor: 3000, quantity: 5 }, { unitAmountMinor: 1000, quantity: 1 }];
+* attributeDiscounts(lines, [{ title: "Pack", amountMinor: 1500, currency: "MXN", lines: [{ index: 0, amountMinor: 1500 }] }]);
+* // the pack discount stays on the first line; the exempt second line is not discounted
+* ```
+*/
+function attributeDiscounts(lines, discounts) {
+	const totals = lines.map((line) => lineTotalMinor(line.unitAmountMinor, line.quantity));
+	const stands = discounts.map((discount) => discount.amountMinor > 0 && discount.lines !== void 0 && checkLineDiscounts(lines, [discount]).length === 0);
+	const claimed = lines.map(() => 0);
+	for (const [at, discount] of discounts.entries()) {
+		if (!stands[at]) continue;
+		for (const part of discount.lines ?? []) claimed[part.index] = claimed[part.index] + part.amountMinor;
+	}
+	const consistent = claimed.every((amount, index) => amount <= totals[index]);
+	const taken = lines.map(() => 0);
+	if (consistent) for (let index = 0; index < lines.length; index++) taken[index] = claimed[index];
+	const out = [];
+	for (const [at, discount] of discounts.entries()) {
+		if (discount.amountMinor === 0) {
+			const { lines: _ignored, ...rest } = discount;
+			out.push(rest);
+			continue;
+		}
+		if (stands[at] && consistent) {
+			const parts = (discount.lines ?? []).filter((part) => part.amountMinor > 0).map((part) => ({
+				index: part.index,
+				amountMinor: part.amountMinor
+			})).sort((a, b) => a.index - b.index);
+			out.push({
+				...discount,
+				lines: parts
+			});
+			continue;
+		}
+		const room = totals.map((total, index) => total - taken[index]);
+		const left = room.reduce((sum, amount) => sum + amount, 0);
+		if (!isMinorUnits(discount.amountMinor)) throw new CommerceError("out_of_range", "a discount is a whole number of minor units, zero or more", "discountMinor");
+		if (discount.amountMinor > left) throw new CommerceError("discount_exceeds_subtotal", `a discount of ${discount.amountMinor} is more than the lines have left (${left})`, "discountMinor");
+		const shares = allocateMinor(discount.amountMinor, room);
+		const parts = [];
+		for (const [index, share] of shares.entries()) {
+			if (share === 0) continue;
+			parts.push({
+				index,
+				amountMinor: share
+			});
+			taken[index] = taken[index] + share;
+		}
+		out.push({
+			...discount,
+			lines: parts
+		});
+	}
+	return out;
+}
+/**
+* What the discounts took off each line, in the order of `lines`: always an answer ({@link attributeDiscounts} added up per line), where
+* {@link lineDiscountsFrom} answers nothing for a discount of the whole order. Pass it as `TaxInput.lineDiscountsMinor`; it is what an order
+* keeps on each line (`PricedLine.discountMinor`) and what a provider's page and an invoice state.
+*
+* ```ts
+* lineDiscountsOf(lines, applied); // [1500, 0]: the pack discount came off the keychain only
+* ```
+*/
+function lineDiscountsOf(lines, discounts) {
+	const perLine = lines.map(() => 0);
+	for (const discount of attributeDiscounts(lines, discounts)) for (const part of discount.lines ?? []) perLine[part.index] = perLine[part.index] + part.amountMinor;
+	return perLine;
+}
+//#endregion
+export { attributeDiscounts, checkLineDiscounts, lineDiscountsFrom, lineDiscountsOf, spreadDiscount };

package/dist/errors-DGzIIflf.d.mts

@@ -0,0 +1,24 @@
+//#region src/errors.d.ts
+/**
+ * What can be wrong, as data. A check of untrusted input (a buyer's asks, the lines a source returns, a payment request) returns a list of
+ * {@link CommerceProblem} and never throws; a route maps `code` to its own error. Only the low-level helpers of `./money` throw, with a
+ * {@link CommerceError} that carries the same codes.
+ */
+declare const PROBLEM_CODES: readonly ["invalid_asks", "invalid_ref", "invalid_quantity", "invalid_options", "duplicate_ref", "invalid_source", "unknown_source", "invalid_lines", "line_count_mismatch", "line_ref_mismatch", "line_quantity_mismatch", "invalid_line", "invalid_title", "invalid_price", "invalid_currency", "invalid_availability", "invalid_max_quantity", "invalid_fulfilment", "invalid_stock_subject", "invalid_snapshot", "sold_out", "not_orderable", "not_found", "over_max_quantity", "empty_order", "currency_mismatch", "out_of_range", "invalid_adjustment", "discount_exceeds_subtotal", "tax_breakdown_mismatch", "invalid_payment", "payment_not_reconciled", "free_order", "invalid_port"];
+type ProblemCode = (typeof PROBLEM_CODES)[number];
+interface CommerceProblem {
+  code: ProblemCode;
+  /** Where, in the shape of the input: `asks[1].quantity`, `lines[0].unitAmountMinor`, `total`. */
+  path: string;
+  /** For a log or a developer, in English. A person-facing text is the caller's, chosen by `code`. */
+  message: string;
+}
+/** Thrown by the low-level money helpers and by `assertTotals`. `code` is the first problem's; `problems` has at least one entry. */
+declare class CommerceError extends Error {
+  readonly code: ProblemCode;
+  readonly problems: readonly CommerceProblem[];
+  constructor(code: ProblemCode, message: string, path?: string, problems?: readonly CommerceProblem[]);
+}
+declare const problem: (code: ProblemCode, path: string, message: string) => CommerceProblem;
+//#endregion
+export { problem as a, ProblemCode as i, CommerceProblem as n, PROBLEM_CODES as r, CommerceError as t };

package/dist/errors.d.mts

@@ -0,0 +1,2 @@
+import { a as problem, i as ProblemCode, n as CommerceProblem, r as PROBLEM_CODES, t as CommerceError } from "./errors-DGzIIflf.mjs";
+export { CommerceError, CommerceProblem, PROBLEM_CODES, ProblemCode, problem };

package/dist/errors.mjs

@@ -0,0 +1,64 @@
+//#region src/errors.ts
+/**
+* What can be wrong, as data. A check of untrusted input (a buyer's asks, the lines a source returns, a payment request) returns a list of
+* {@link CommerceProblem} and never throws; a route maps `code` to its own error. Only the low-level helpers of `./money` throw, with a
+* {@link CommerceError} that carries the same codes.
+*/
+const PROBLEM_CODES = [
+	"invalid_asks",
+	"invalid_ref",
+	"invalid_quantity",
+	"invalid_options",
+	"duplicate_ref",
+	"invalid_source",
+	"unknown_source",
+	"invalid_lines",
+	"line_count_mismatch",
+	"line_ref_mismatch",
+	"line_quantity_mismatch",
+	"invalid_line",
+	"invalid_title",
+	"invalid_price",
+	"invalid_currency",
+	"invalid_availability",
+	"invalid_max_quantity",
+	"invalid_fulfilment",
+	"invalid_stock_subject",
+	"invalid_snapshot",
+	"sold_out",
+	"not_orderable",
+	"not_found",
+	"over_max_quantity",
+	"empty_order",
+	"currency_mismatch",
+	"out_of_range",
+	"invalid_adjustment",
+	"discount_exceeds_subtotal",
+	"tax_breakdown_mismatch",
+	"invalid_payment",
+	"payment_not_reconciled",
+	"free_order",
+	"invalid_port"
+];
+/** Thrown by the low-level money helpers and by `assertTotals`. `code` is the first problem's; `problems` has at least one entry. */
+var CommerceError = class extends Error {
+	code;
+	problems;
+	constructor(code, message, path = "", problems) {
+		super(message);
+		this.name = "CommerceError";
+		this.code = code;
+		this.problems = problems ?? [{
+			code,
+			path,
+			message
+		}];
+	}
+};
+const problem = (code, path, message) => ({
+	code,
+	path,
+	message
+});
+//#endregion
+export { CommerceError, PROBLEM_CODES, problem };

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import { a as problem, i as ProblemCode, n as CommerceProblem, r as PROBLEM_CODES, t as CommerceError } from "./errors-DGzIIflf.mjs";
+import { $ as StartPaymentInput, A as LineHoldRequest, B as PaymentsPort, C as HoldStatus, D as LineAvailability, E as LineAsk, F as MAX_HOLD_MS, G as STOCK_TRACKINGS, H as PortName, I as PAYMENT_METHODS, J as ShippingRatesInput, K as SettleResult, L as PaymentAdjustment, M as LineSettleResult, N as LineSnapshot, O as LineDiscountPart, P as LineSource, Q as SnapshotValue, R as PaymentLine, S as HoldResult, T as LINE_AVAILABILITIES, U as PortProviders, V as PortContext, W as ResolvedLine, X as ShortAsk, Y as ShippingRatesPort, Z as ShortLine, _ as Fulfilment, a as CancelPaymentResult, at as TaxBreakdown, b as HoldLine, c as CommerceLocale, ct as TaxResult, d as DiscountInput, et as StartPaymentResult, f as DiscountPort, g as FindLineSource, h as FULFILMENTS, i as CancelPaymentFailure, it as StockTracking, j as LineHoldResult, k as LineHold, l as DISCOUNT_REJECTIONS, lt as Money, m as DiscountResult, n as AdjustmentKind, nt as StockPort, o as CartAsk, ot as TaxInput, p as DiscountRejection, q as ShippingRate, r as AppliedDiscount, rt as StockSubject, s as CartLine, st as TaxPort, t as ADJUSTMENT_KINDS, tt as StockLevel, u as Destination, v as HOLD_STATUSES, w as HoldingLineSource, x as HoldRequest, y as Hold, z as PaymentMethod } from "./types-BUyLunnB.mjs";
+import { DiscountableLine, attributeDiscounts, checkLineDiscounts, lineDiscountsFrom, lineDiscountsOf, spreadDiscount } from "./discounts.mjs";
+import { AskLimits, AsksResult, BlockedLine, BlockedReason, CartAskOptions, CartAsksResult, CartResult, DEFAULT_ASK_LIMITS, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, ResolveResult, blockedProblem, blockedReason, checkResolvedLine, checkResolvedLines, holdLinesFrom, holdsCapacity, partitionLines, resolveCart, resolveLines, validateAsks, validateCartAsks } from "./lines.mjs";
+import { MAX_RATE_BP, ROUNDINGS, Rounding, allocateMinor, basisPointsOf, isCurrencyCode, isMinorUnits, lineTotalMinor, subtractMinor, sumMinor, taxIncludedIn } from "./money.mjs";
+import { ChosenShipping, PricedLine, Totals, TotalsInput, TotalsResult, assertTotals, computeTotals } from "./totals.mjs";
+import { PaymentRequestParts, checkStartPayment, paymentRequestFrom } from "./payments.mjs";
+import { OPTIONAL_PORT_METHODS, PORT_METHODS, PORT_NAMES, UnlistedPortMethods, checkPortProvider, isPortName } from "./ports.mjs";
+import { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, SnapshotKey, SnapshotTextKey, snapshotText, snapshotWeightG } from "./snapshot.mjs";
+//#region src/internal.d.ts
+/** A non-empty title for a person, at most `max` long, with no space at either end. */
+declare const isDisplayText: (value: unknown, max: number) => value is string;
+//#endregion
+export { ADJUSTMENT_KINDS, AdjustmentKind, AppliedDiscount, AskLimits, AsksResult, BlockedLine, BlockedReason, CancelPaymentFailure, CancelPaymentResult, CartAsk, CartAskOptions, CartAsksResult, CartLine, CartResult, ChosenShipping, CommerceError, CommerceLocale, CommerceProblem, DEFAULT_ASK_LIMITS, DISCOUNT_REJECTIONS, Destination, DiscountInput, DiscountPort, DiscountRejection, DiscountResult, DiscountableLine, FULFILMENTS, FindLineSource, Fulfilment, HOLD_STATUSES, Hold, HoldLine, HoldRequest, HoldResult, HoldStatus, HoldingLineSource, LINE_AVAILABILITIES, LineAsk, LineAvailability, LineDiscountPart, LineHold, LineHoldRequest, LineHoldResult, LineSettleResult, LineSnapshot, LineSource, MAX_HOLD_MS, MAX_RATE_BP, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, MAX_SNAPSHOT_TEXT, type Money, OPTIONAL_PORT_METHODS, PAYMENT_METHODS, PORT_METHODS, PORT_NAMES, PROBLEM_CODES, PaymentAdjustment, PaymentLine, PaymentMethod, PaymentRequestParts, PaymentsPort, PortContext, PortName, PortProviders, PricedLine, ProblemCode, ROUNDINGS, ResolveResult, ResolvedLine, Rounding, SNAPSHOT_KEYS, STOCK_TRACKINGS, SettleResult, ShippingRate, ShippingRatesInput, ShippingRatesPort, ShortAsk, ShortLine, SnapshotKey, SnapshotTextKey, SnapshotValue, StartPaymentInput, StartPaymentResult, StockLevel, StockPort, StockSubject, StockTracking, TaxBreakdown, TaxInput, TaxPort, TaxResult, Totals, TotalsInput, TotalsResult, UnlistedPortMethods, allocateMinor, assertTotals, attributeDiscounts, basisPointsOf, blockedProblem, blockedReason, checkLineDiscounts, checkPortProvider, checkResolvedLine, checkResolvedLines, checkStartPayment, computeTotals, holdLinesFrom, holdsCapacity, isCurrencyCode, isDisplayText, isMinorUnits, isPortName, lineDiscountsFrom, lineDiscountsOf, lineTotalMinor, partitionLines, paymentRequestFrom, problem, resolveCart, resolveLines, snapshotText, snapshotWeightG, spreadDiscount, subtractMinor, sumMinor, taxIncludedIn, validateAsks, validateCartAsks };

package/dist/index.mjs

@@ -0,0 +1,11 @@
+import { CommerceError, PROBLEM_CODES, problem } from "./errors.mjs";
+import { r as isDisplayText } from "./internal-p2FS_A4L.mjs";
+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";
+import { attributeDiscounts, checkLineDiscounts, lineDiscountsFrom, lineDiscountsOf, spreadDiscount } from "./discounts.mjs";
+import { ADJUSTMENT_KINDS, DISCOUNT_REJECTIONS, FULFILMENTS, HOLD_STATUSES, LINE_AVAILABILITIES, MAX_HOLD_MS, PAYMENT_METHODS, STOCK_TRACKINGS } from "./types.mjs";
+import { DEFAULT_ASK_LIMITS, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, blockedProblem, blockedReason, checkResolvedLine, checkResolvedLines, holdLinesFrom, holdsCapacity, partitionLines, resolveCart, resolveLines, validateAsks, validateCartAsks } from "./lines.mjs";
+import { checkStartPayment, paymentRequestFrom } from "./payments.mjs";
+import { OPTIONAL_PORT_METHODS, PORT_METHODS, PORT_NAMES, checkPortProvider, isPortName } from "./ports.mjs";
+import { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, snapshotText, snapshotWeightG } from "./snapshot.mjs";
+import { assertTotals, computeTotals } from "./totals.mjs";
+export { ADJUSTMENT_KINDS, CommerceError, DEFAULT_ASK_LIMITS, DISCOUNT_REJECTIONS, FULFILMENTS, HOLD_STATUSES, LINE_AVAILABILITIES, MAX_HOLD_MS, MAX_RATE_BP, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, MAX_SNAPSHOT_TEXT, OPTIONAL_PORT_METHODS, PAYMENT_METHODS, PORT_METHODS, PORT_NAMES, PROBLEM_CODES, ROUNDINGS, SNAPSHOT_KEYS, STOCK_TRACKINGS, allocateMinor, assertTotals, attributeDiscounts, basisPointsOf, blockedProblem, blockedReason, checkLineDiscounts, checkPortProvider, checkResolvedLine, checkResolvedLines, checkStartPayment, computeTotals, holdLinesFrom, holdsCapacity, isCurrencyCode, isDisplayText, isMinorUnits, isPortName, lineDiscountsFrom, lineDiscountsOf, lineTotalMinor, partitionLines, paymentRequestFrom, problem, resolveCart, resolveLines, snapshotText, snapshotWeightG, spreadDiscount, subtractMinor, sumMinor, taxIncludedIn, validateAsks, validateCartAsks };

package/dist/internal-p2FS_A4L.mjs

@@ -0,0 +1,22 @@
+//#region src/internal.ts
+/** Small checks the modules share. Not a public subpath. */
+/**
+* What an id, a ref, a key or an option value may not contain: control characters (C0 and C1), the invisible format characters (zero-width,
+* bidirectional overrides, the soft hyphen, the byte order mark), the line and paragraph separators and lone surrogates.
+*/
+const UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/u;
+/**
+* What a title shown to a person may not contain: the same, except the format characters a script or an emoji needs (the zero-width joiner of
+* a family emoji, the non-joiner of Persian, the directional marks of Arabic and Hebrew), which stay; the bidirectional overrides and isolates,
+* which can make a title read as something else, and the byte order mark go.
+*/
+const UNSAFE_DISPLAY = /[\p{Cc}\p{Zl}\p{Zp}\p{Cs}\u202a-\u202e\u2066-\u2069\ufeff]/u;
+/** A subject type of the stock port: dotted lowercase words (`catalog.variant`, `menu.item`), so `type:id` can be split back. */
+const SUBJECT_TYPE = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A non-empty string of printable characters (an id, a ref, a key), at most `max` long. */
+const isText = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && !UNSAFE.test(value);
+/** A non-empty title for a person, at most `max` long, with no space at either end. */
+const isDisplayText = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && value === value.trim() && !UNSAFE_DISPLAY.test(value);
+//#endregion
+export { isText as a, isRecord as i, UNSAFE as n, isDisplayText as r, SUBJECT_TYPE as t };

package/dist/lines.d.mts

@@ -0,0 +1,142 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { E as LineAsk, P as LineSource, V as PortContext, W as ResolvedLine, b as HoldLine, g as FindLineSource, o as CartAsk, rt as StockSubject, s as CartLine, w as HoldingLineSource } from "./types-BUyLunnB.mjs";
+//#region src/lines.d.ts
+interface AskLimits {
+  /** Lines in one request. */
+  maxLines: number;
+  /** One line's quantity. */
+  maxQuantity: number;
+  maxRefLength: number;
+  /** Options on one line. */
+  maxOptions: number;
+}
+declare const DEFAULT_ASK_LIMITS: AskLimits;
+/** The longest ref or stock subject id there is: `maxRefLength` of {@link AskLimits} is cut to this, so a line can always be checked. */
+declare const MAX_REF_LENGTH = 1024;
+/** What a line's snapshot may weigh as JSON, in bytes: it is copied into every order line. */
+declare const MAX_SNAPSHOT_BYTES = 2048;
+type AsksResult = {
+  ok: true;
+  asks: LineAsk[];
+} | {
+  ok: false;
+  problems: CommerceProblem[];
+};
+/**
+ * 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).
+ */
+declare function validateAsks(input: unknown, limits?: Partial<AskLimits>): AsksResult;
+type CartAsksResult = {
+  ok: true;
+  asks: CartAsk[];
+} | {
+  ok: false;
+  problems: CommerceProblem[];
+};
+interface CartAskOptions extends Partial<AskLimits> {
+  /**
+   * The registry's lookup (`(key) => linePort(key)...`, as {@link resolveCart} takes it). With it, an ask whose source nobody registered is
+   * refused as `unknown_source`, so a cart that names a feature that was removed stops before anything is held; without it only the key's
+   * shape is checked.
+   */
+  find?: FindLineSource;
+}
+/**
+ * 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);
+ * ```
+ */
+declare function validateCartAsks(input: unknown, options?: CartAskOptions): CartAsksResult;
+/** 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. */
+declare function checkResolvedLine(line: unknown, path?: string): CommerceProblem[];
+/** 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. */
+declare function checkResolvedLines(asks: readonly LineAsk[], lines: unknown, path?: string): CommerceProblem[];
+type ResolveResult = {
+  ok: true;
+  lines: ResolvedLine[];
+} | {
+  ok: false;
+  problems: CommerceProblem[];
+};
+/**
+ * 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.
+ */
+declare function resolveLines(source: LineSource, ctx: PortContext, asks: readonly LineAsk[]): Promise<ResolveResult>;
+type CartResult = {
+  ok: true;
+  lines: CartLine[];
+} | {
+  ok: false;
+  problems: CommerceProblem[];
+};
+/**
+ * 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);
+ * ```
+ */
+declare function resolveCart(find: FindLineSource, ctx: PortContext, asks: readonly CartAsk[]): Promise<CartResult>;
+/**
+ * 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.
+ */
+declare function holdsCapacity(source: LineSource): source is HoldingLineSource;
+type BlockedReason = "sold_out" | "not_orderable" | "not_found" | "over_max_quantity";
+/** Why a (valid) line cannot be charged now, or `undefined` when it can. */
+declare function blockedReason(line: ResolvedLine): BlockedReason | undefined;
+declare function blockedProblem(line: ResolvedLine, path: string): CommerceProblem | undefined;
+interface BlockedLine<Line extends ResolvedLine = ResolvedLine> {
+  /** The position in the list that was partitioned, which is the position of the ask. */
+  index: number;
+  line: Line;
+  reason: BlockedReason;
+}
+/**
+ * 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`.
+ */
+declare function partitionLines<Line extends ResolvedLine>(lines: readonly Line[]): {
+  chargeable: Line[];
+  blocked: BlockedLine<Line>[];
+};
+/**
+ * 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.
+ */
+declare function holdLinesFrom(lines: readonly {
+  stock?: StockSubject;
+  quantity: number;
+}[]): HoldLine[];
+//#endregion
+export { AskLimits, AsksResult, BlockedLine, BlockedReason, CartAskOptions, CartAsksResult, CartResult, DEFAULT_ASK_LIMITS, MAX_REF_LENGTH, MAX_SNAPSHOT_BYTES, ResolveResult, blockedProblem, blockedReason, checkResolvedLine, checkResolvedLines, holdLinesFrom, holdsCapacity, partitionLines, resolveCart, resolveLines, validateAsks, validateCartAsks };