@vibedout/commerce 0.0.0-stage → 0.2.3

package/dist/testing.d.mts

@@ -0,0 +1,237 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { $ as StartPaymentResult, B as PortContext, D as LineAvailability, N as LineSource, Q as StartPaymentInput, d as DiscountInput, f as DiscountPort, nt as StockSubject, ot as TaxPort, tt as StockPort, u as Destination, w as HoldingLineSource, z as PaymentsPort } from "./types-BzlVbRp1.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 };