@vibedout/commerce 0.0.0-stage → 0.2.4

package/dist/payments.mjs

@@ -0,0 +1,193 @@
+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 { checkLineDiscounts } from "./discounts.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;
+	if (Array.isArray(input.adjustments) && Array.isArray(input.lines)) {
+		const lines = input.lines;
+		const named = input.adjustments.map((adjustment, index) => {
+			if (adjustment.lines !== void 0 && adjustment.kind !== "discount") add("invalid_payment", `adjustments[${index}].lines`, "only a discount says which lines it came off");
+			return adjustment.kind === "discount" && adjustment.lines !== void 0 ? {
+				title: adjustment.title,
+				currency: adjustment.currency,
+				amountMinor: adjustment.amountMinor,
+				lines: adjustment.lines
+			} : {
+				title: adjustment.title,
+				currency: adjustment.currency,
+				amountMinor: 0
+			};
+		});
+		for (const found of checkLineDiscounts(lines, named, "adjustments")) out.push(found.code === "discount_exceeds_subtotal" ? {
+			...found,
+			path: found.path.replace(/^adjustments\./, "")
+		} : found);
+		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 (each discount with the lines it came off,
+* 0.2.4), so the provider's page and the order agree to the centavo, line by line. It does not check anything; {@link checkStartPayment} does, and a total of
+* zero is a free order that starts no payment.
+*/
+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,
+		...discount.lines ? { lines: discount.lines.map((part) => ({
+			index: part.index,
+			amountMinor: part.amountMinor
+		})) } : {}
+	});
+	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 PortName, U as PortProviders } from "./types-BUyLunnB.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,41 @@
+import { N as LineSnapshot } from "./types-BUyLunnB.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";
+  /** The weight of one unit in grams (a number, not text: read it with {@link snapshotWeightG}). The shipping feature adds it up to weigh the parcel a cart's rates are quoted for. */
+  readonly weightG: "weightG";
+};
+type SnapshotKey = keyof typeof SNAPSHOT_KEYS;
+/** The keys that hold text; `weightG` holds a number. */
+type SnapshotTextKey = Exclude<SnapshotKey, "weightG">;
+/** 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: SnapshotTextKey): string | undefined;
+/**
+ * The grams one unit of the line weighs, when its source wrote them under `weightG` (0.2.4), else 0: a missing, negative or non-numeric value weighs nothing, so a
+ * source that does not know the weight never makes a parcel heavier by accident.
+ *
+ * ```ts
+ * const grams = lines.reduce((sum, line) => sum + snapshotWeightG(line) * line.quantity, 0);
+ * ```
+ */
+declare function snapshotWeightG(line: {
+  snapshot?: LineSnapshot;
+}): number;
+//#endregion
+export { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, SnapshotKey, SnapshotTextKey, snapshotText, snapshotWeightG };

package/dist/snapshot.mjs

@@ -0,0 +1,46 @@
+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 weight of one unit in grams (a number, not text: read it with {@link snapshotWeightG}). The shipping feature adds it up to weigh the parcel a cart's rates are quoted for. */
+	weightG: "weightG"
+};
+/** 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;
+}
+/**
+* The grams one unit of the line weighs, when its source wrote them under `weightG` (0.2.4), else 0: a missing, negative or non-numeric value weighs nothing, so a
+* source that does not know the weight never makes a parcel heavier by accident.
+*
+* ```ts
+* const grams = lines.reduce((sum, line) => sum + snapshotWeightG(line) * line.quantity, 0);
+* ```
+*/
+function snapshotWeightG(line) {
+	const value = line.snapshot?.[SNAPSHOT_KEYS.weightG];
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+//#endregion
+export { MAX_SNAPSHOT_TEXT, SNAPSHOT_KEYS, snapshotText, snapshotWeightG };

package/dist/testing.d.mts

@@ -0,0 +1,237 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { $ as StartPaymentInput, B as PaymentsPort, D as LineAvailability, P as LineSource, V as PortContext, d as DiscountInput, et as StartPaymentResult, f as DiscountPort, nt as StockPort, rt as StockSubject, st as TaxPort, u as Destination, w as HoldingLineSource } from "./types-BUyLunnB.mjs";
+//#region src/testing/context.d.ts
+/** 2026-10-08 12:00 UTC: a fixed "now" for tests, so a hold that expires does so when the test says. */
+declare const TEST_NOW: number;
+/**
+ * A {@link PortContext} for a test double: a fixed clock, no environment, and a `db` whose every method throws, so a double that reaches for
+ * the database fails loudly. A port that really uses D1 is tested with the project's own `env.DB` instead.
+ */
+declare function testContext(overrides?: Partial<PortContext>): PortContext;
+//#endregion
+//#region src/testing/tools.d.ts
+/** The few matchers the suites use; vitest's `expect` fits. */
+type TestExpect = (value: unknown) => {
+  toBe(expected: unknown): void;
+  toEqual(expected: unknown): void;
+};
+/** What a conformance suite needs from a test runner: pass `{ describe, it, expect }` from vitest. */
+interface TestTools {
+  describe(name: string, fn: () => void): void;
+  it(name: string, fn: () => unknown, timeout?: number): void;
+  expect: TestExpect;
+}
+//#endregion
+//#region src/testing/discount-conformance.d.ts
+interface DiscountConformanceOptions {
+  /** Orders the provider's rules apply to, each named for the failure message. At least one. */
+  scenarios: readonly {
+    name: string;
+    input: DiscountInput;
+  }[];
+  /** An order that earns no discount: the answer's `applied` is empty. Optional. */
+  plain?: DiscountInput;
+  /** The context for a given clock. Default {@link testContext}; a provider that reads D1 passes one with the project's `env.DB`. */
+  context?: (now: number) => PortContext | Promise<PortContext>;
+}
+declare function runDiscountConformance(make: () => DiscountPort | Promise<DiscountPort>, tools: TestTools, options: DiscountConformanceOptions): void;
+//#endregion
+//#region src/testing/fake-discount.d.ts
+interface FlatDiscountOptions {
+  /** Percent off a line, in basis points: 10% is 1000. Default 1000. */
+  percentBp?: number;
+  /** A line gets the discount from this quantity. Default 5. */
+  fromQuantity?: number;
+  /** The title of the discount. Default `Volume discount`. */
+  title?: string;
+}
+/**
+ * A discount port for tests: `percentBp` off every line of at least `fromQuantity`, with the lines it came off named. It knows no code, so a
+ * code a buyer typed is `rejected` as `unknown`. The reference `runDiscountConformance` is written from.
+ */
+declare function createFlatDiscount(options?: FlatDiscountOptions): DiscountPort;
+//#endregion
+//#region src/testing/fake-tax.d.ts
+interface FlatTaxOptions {
+  /** The one rate, in basis points: 16% is 1600. Default 1600. */
+  rateBp?: number;
+  /** The tax's name in the breakdown. Default `IVA`. */
+  code?: string;
+}
+/**
+ * A tax port for tests: one rate for everything, worked per line on what is paid (the line after its discount: `lineDiscountsMinor` when it is
+ * given, else the discount spread in proportion), shipping taxed on top. A line whose price includes the tax contributes to `includedMinor`
+ * (the tax inside the price), the others and the shipping to `addedMinor`. The rate and rounding are the money helpers', so it is also the
+ * small reference the conformance suite is written from.
+ */
+declare function createFlatTax(options?: FlatTaxOptions): TaxPort;
+//#endregion
+//#region src/testing/slots.d.ts
+/** The places of each ref (`{ slot_a: 3 }`). A ref that is not here is not sold. */
+type SlotPlaces = Readonly<Record<string, number>>;
+interface MemorySlotsOptions {
+  /** The price of one place of every slot, in centavos. Default 10000 (100.00 MXN). */
+  unitAmountMinor?: number;
+}
+declare function createMemorySlots(places: SlotPlaces, options?: MemorySlotsOptions): HoldingLineSource;
+//#endregion
+//#region src/testing/line-hold-conformance.d.ts
+interface LineHoldConformanceOptions {
+  /** The context for a given clock. Default {@link testContext}; a source that keeps its places in D1 passes one with the project's `env.DB`. */
+  context?: (now: number) => PortContext | Promise<PortContext>;
+}
+declare function runLineHoldConformance(make: (places: SlotPlaces) => LineSource | Promise<LineSource>, tools: TestTools, options?: LineHoldConformanceOptions): void;
+//#endregion
+//#region src/testing/line-source.d.ts
+interface KnownRef {
+  ref: string;
+  /** What the source must charge for one. Leave out to check only that it is a valid price. */
+  unitAmountMinor?: number;
+  currency?: string;
+  /** Options to resolve this ref with (a size, a colour), for a source that has them. */
+  options?: Readonly<Record<string, string>>;
+}
+/**
+ * A source whose price the buyer legitimately chooses inside bounds the server sets (a donation, a tip, a deposit of the buyer's size). The
+ * amount travels in `options[option]`, in minor units, as a string of digits. The harness then checks that the bounds hold and that nothing
+ * but a whole number inside them is ever priced; every other option name is still a price the buyer may not set.
+ */
+interface BuyerPrice {
+  /** A ref in `known` whose `options` carry an amount (`{ amount: "5000" }`): the ref the amount is chosen on. */
+  ref: string;
+  /** The option the buyer puts the amount in. */
+  option: string;
+  /** The least and the most the source accepts, in minor units. Each must be accepted, and one either side refused. */
+  min: number;
+  max: number;
+}
+interface LineSourceFixtures {
+  /** The context the source runs in. Default {@link testContext}: a source that reads D1 passes its own, with the project's `env.DB`. */
+  ctx?: PortContext;
+  /** Refs that exist and can be bought. At least one. */
+  known: readonly KnownRef[];
+  /** Refs that exist but cannot be bought, with the availability the source must give them. */
+  unavailable?: readonly {
+    ref: string;
+    availability: Exclude<LineAvailability, "available" | "not_found">;
+  }[];
+  /** A ref that exists nowhere. Default `no-such-thing-here`. */
+  missingRef?: string;
+  /** For a source that lets the buyer pick the amount inside bounds (`donation.amount`). */
+  buyerPrice?: BuyerPrice;
+  /** More option names to try as a hostile price, beyond {@link PRICE_OPTION_NAMES}: the ones your source reads (`pledge`, `tip`). */
+  extraPriceOptions?: readonly string[];
+}
+declare const HARNESS_CHECKS: readonly ["empty", "shape", "order", "unknown", "unavailable", "server-prices", "no-mutation", "repeatable", "duplicates", "buyer-price", "holds"];
+type HarnessCheck = (typeof HARNESS_CHECKS)[number];
+interface HarnessFinding {
+  check: HarnessCheck;
+  message: string;
+  problems?: readonly CommerceProblem[];
+}
+/** Refs a hostile buyer sends. A source answers each with a `not_found` line, whatever it does with a ref. */
+declare const HOSTILE_REFS: readonly string[];
+/**
+ * The option names the harness tries as a browser's own price. A source may not read a price from any of them (except the one `buyerPrice`
+ * declares); add the names your source reads for other things with `extraPriceOptions`.
+ */
+declare const PRICE_OPTION_NAMES: readonly ["price", "amount", "unitAmountMinor", "unit_price", "total", "currency", "discount"];
+/** Runs the checks and returns what failed; an empty list is a source a checkout can rely on. */
+declare function checkLineSource(source: LineSource, fixtures: LineSourceFixtures, only?: readonly HarnessCheck[]): Promise<HarnessFinding[]>;
+/** The checks as a test suite: one `it` for each, failing with the findings. Run it in the feature's own tests, in workerd for a source that reads D1. */
+declare function runLineSourceConformance(source: LineSource, fixtures: LineSourceFixtures, tools: TestTools): void;
+//#endregion
+//#region src/testing/payments.d.ts
+type Failure = Extract<StartPaymentResult, {
+  ok: false;
+}>;
+interface FakePayments extends PaymentsPort {
+  /** Every distinct request that was accepted, in order. */
+  readonly started: readonly StartPaymentInput[];
+  /** Every reference whose payment was cancelled, in order, once each. */
+  readonly cancelled: readonly string[];
+  /** The next `start` answers with this failure, once. */
+  failNext(failure: Failure): void;
+  /** The payment of `reference` was paid, as a provider's event would say: it can no longer be cancelled or started again. */
+  markPaid(reference: string): void;
+  cancel: NonNullable<PaymentsPort["cancel"]>;
+}
+/**
+ * A payments port for tests: it checks each request the way a real one must (`checkStartPayment`), answers a payment id and a redirect URL,
+ * and is idempotent by `reference` (the same request again is the same payment; a different one under the same reference is refused). It
+ * cancels a payment that is not paid, once, and then refuses to start its reference again; `markPaid` stands in for the provider's event.
+ */
+declare function createFakePayments(): FakePayments;
+//#endregion
+//#region src/testing/payments-conformance.d.ts
+interface PaymentsConformanceOptions {
+  /** The context for a given clock. Default {@link testContext}; a provider that keeps payments in D1 passes one with the project's `env.DB`. */
+  context?: (now: number) => PortContext | Promise<PortContext>;
+  /**
+   * Leaves out the cases of `cancel`, for a provider that does not have that optional method. Without it, a provider with no `cancel` fails
+   * those cases and says why.
+   */
+  skipCancel?: boolean;
+  /** The start of every reference the suite makes (`<prefix>-<n>`), for a provider whose payments outlive one test. Default `conformance`. */
+  referencePrefix?: string;
+}
+declare function runPaymentsConformance(make: () => PaymentsPort | Promise<PaymentsPort>, tools: TestTools, options?: PaymentsConformanceOptions): void;
+//#endregion
+//#region src/testing/stock.d.ts
+/** How one subject is stocked. A subject that is not seeded is `none`: always available. */
+type StockSeedItem = {
+  tracking: "none";
+} | {
+  tracking: "toggle";
+  out?: boolean;
+  outUntil?: number | null;
+} | {
+  tracking: "count";
+  onHand: number;
+  allowOversell?: boolean;
+};
+/** Seeds by `subjectKey` (`catalog.variant:var_1`). */
+type StockSeed = Readonly<Record<string, StockSeedItem>>;
+declare const subjectKey: (subject: StockSubject) => string;
+interface MemoryStock extends StockPort {
+  fulfil: NonNullable<StockPort["fulfil"]>;
+  uncommit: NonNullable<StockPort["uncommit"]>;
+  /** The counts of every `count` subject: for a test to read what the port did. */
+  counts(): Record<string, {
+    onHand: number;
+    reserved: number;
+    committed: number;
+    available: number;
+  }>;
+}
+declare function createMemoryStock(seed?: StockSeed): MemoryStock;
+//#endregion
+//#region src/testing/stock-conformance.d.ts
+interface StockConformanceOptions {
+  /** The context for a given clock. Default {@link testContext}; a D1 provider passes one with the project's `env.DB`. */
+  context?: (now: number) => PortContext | Promise<PortContext>;
+  /**
+   * Leaves out the cases of `fulfil`, for a provider that does not have that optional method (it tracks no units on hand). Without it, a
+   * provider with no `fulfil` fails those cases and says why.
+   */
+  skipFulfil?: boolean;
+  /**
+   * Leaves out the cases of `uncommit`, for a provider that does not have that optional method. Without it, a provider with no `uncommit`
+   * fails those cases and says why.
+   */
+  skipUncommit?: boolean;
+}
+declare function runStockConformance(make: (seed: StockSeed) => StockPort | Promise<StockPort>, tools: TestTools, options?: StockConformanceOptions): void;
+//#endregion
+//#region src/testing/tax-conformance.d.ts
+interface TaxConformanceOptions {
+  /** The context for a given clock. Default {@link testContext}; a provider that reads D1 passes one with the project's `env.DB`. */
+  context?: (now: number) => PortContext | Promise<PortContext>;
+  /** A destination the provider can price; default none. The suite asks with and without. */
+  destination?: Destination;
+  /** The order's currency. Default `MXN`. */
+  currency?: string;
+}
+declare function runTaxConformance(make: () => TaxPort | Promise<TaxPort>, tools: TestTools, options?: TaxConformanceOptions): void;
+//#endregion
+export { type DiscountConformanceOptions, type FakePayments, type FlatDiscountOptions, type FlatTaxOptions, HARNESS_CHECKS, HOSTILE_REFS, type HarnessCheck, type HarnessFinding, type KnownRef, type LineHoldConformanceOptions, type LineSourceFixtures, type MemorySlotsOptions, type MemoryStock, PRICE_OPTION_NAMES, type PaymentsConformanceOptions, type SlotPlaces, type StockConformanceOptions, type StockSeed, type StockSeedItem, TEST_NOW, type TaxConformanceOptions, type TestExpect, type TestTools, checkLineSource, createFakePayments, createFlatDiscount, createFlatTax, createMemorySlots, createMemoryStock, runDiscountConformance, runLineHoldConformance, runLineSourceConformance, runPaymentsConformance, runStockConformance, runTaxConformance, subjectKey, testContext };