@vibedout/commerce 0.0.0-stage → 0.2.3

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 StartPaymentResult, A as LineHoldResult, B as PortContext, C as HoldStatus, D as LineAvailability, E as LineAsk, F as PAYMENT_METHODS, G as SettleResult, H as PortProviders, I as PaymentAdjustment, J as ShippingRatesPort, K as ShippingRate, L as PaymentLine, M as LineSnapshot, N as LineSource, O as LineHold, P as MAX_HOLD_MS, Q as StartPaymentInput, R as PaymentMethod, S as HoldResult, T as LINE_AVAILABILITIES, U as ResolvedLine, V as PortName, W as STOCK_TRACKINGS, X as ShortLine, Y as ShortAsk, Z as SnapshotValue, _ as Fulfilment, a as CancelPaymentResult, at as TaxInput, b as HoldLine, c as CommerceLocale, ct as Money, d as DiscountInput, et as StockLevel, f as DiscountPort, g as FindLineSource, h as FULFILMENTS, i as CancelPaymentFailure, it as TaxBreakdown, j as LineSettleResult, k as LineHoldRequest, l as DISCOUNT_REJECTIONS, m as DiscountResult, n as AdjustmentKind, nt as StockSubject, o as CartAsk, ot as TaxPort, p as DiscountRejection, q as ShippingRatesInput, r as AppliedDiscount, rt as StockTracking, s as CartLine, st as TaxResult, t as ADJUSTMENT_KINDS, tt as StockPort, u as Destination, v as HOLD_STATUSES, w as HoldingLineSource, x as HoldRequest, y as Hold, z as PaymentsPort } from "./types-BzlVbRp1.mjs";
+import { DiscountableLine, checkLineDiscounts, lineDiscountsFrom, 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, snapshotText } 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, 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, SnapshotValue, StartPaymentInput, StartPaymentResult, StockLevel, StockPort, StockSubject, StockTracking, TaxBreakdown, TaxInput, TaxPort, TaxResult, Totals, TotalsInput, TotalsResult, UnlistedPortMethods, allocateMinor, assertTotals, basisPointsOf, blockedProblem, blockedReason, checkLineDiscounts, checkPortProvider, checkResolvedLine, checkResolvedLines, checkStartPayment, computeTotals, holdLinesFrom, holdsCapacity, isCurrencyCode, isDisplayText, isMinorUnits, isPortName, lineDiscountsFrom, lineTotalMinor, partitionLines, paymentRequestFrom, problem, resolveCart, resolveLines, snapshotText, 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 { checkLineDiscounts, lineDiscountsFrom, 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 } 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, basisPointsOf, blockedProblem, blockedReason, checkLineDiscounts, checkPortProvider, checkResolvedLine, checkResolvedLines, checkStartPayment, computeTotals, holdLinesFrom, holdsCapacity, isCurrencyCode, isDisplayText, isMinorUnits, isPortName, lineDiscountsFrom, lineTotalMinor, partitionLines, paymentRequestFrom, problem, resolveCart, resolveLines, snapshotText, 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 { B as PortContext, E as LineAsk, N as LineSource, U as ResolvedLine, b as HoldLine, g as FindLineSource, nt as StockSubject, o as CartAsk, s as CartLine, w as HoldingLineSource } from "./types-BzlVbRp1.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 };

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 };