mollie-ecommerce 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -9,6 +9,25 @@ Entries from 0.5.0 onwards are generated by
 unreleased changes live as files in [`.changeset/`](.changeset) until then.
 Earlier entries were written by hand.
 
+## 0.6.0
+
+### Minor Changes
+
+- db922a7: Add `createWebhookHandler` on a new `mollie-ecommerce/http` entry point: a
+  `Request → Response` handler for the Mollie webhook, holding the logic every
+  consumer would otherwise write identically.
+  
+  It parses Mollie's form body, maps failures to the status code Mollie acts on
+  (2xx for a payment that is not yours, 503 for a Mollie or storage outage so the
+  redelivery recovers it, 500 for a bug), and retries the `version_conflict` a
+  concurrent duplicate delivery causes. Your side plugs in through `onOrder` —
+  enqueue only, Mollie is waiting — and `onError`, which receives the chosen
+  status so alerting can tell "Mollie will retry" from "this is on the floor".
+  
+  `commerce.handleWebhook(paymentId)` is unchanged and remains the operation; the
+  handler is a convenience over it, on its own entry so the main one stays free of
+  HTTP. `req`/`res` frameworks keep calling `handleWebhook` directly.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -20,14 +20,15 @@ bun add mollie-ecommerce
 Ships as ESM with type declarations, so Node 20+, Bun, Deno and bundlers all
 work. Two runtime dependencies: the Mollie SDK and [zod](https://zod.dev).
 
-One exception: `mollie-ecommerce/conformance` — the contract test suite for
-your storage — builds on `bun:test`, so that entry point needs
-[Bun](https://bun.com).
+Two more entry points, both optional: `mollie-ecommerce/http` for the Mollie
+webhook handler, and `mollie-ecommerce/conformance` for the contract test suite
+for your storage. The conformance entry builds on `bun:test`, so it needs
+[Bun](https://bun.com); the main and `http` entries do not.
 
 ```bash
 # Working on the library itself
 bun install
-bun run check     # typecheck + 161 tests
+bun run check     # typecheck + 172 tests
 bun run build     # bundle dist/ with tsdown
 bun run example   # the full lifecycle, no Mollie account needed
 ```
@@ -194,6 +195,11 @@ order up by payment id, then does the same work as `syncOrder`. Returns `null`
 for a payment this shop doesn't know — respond 2xx anyway, or Mollie retries
 forever. The state always comes from the API, never from the request body.
 
+This is the commerce operation; `createWebhookHandler` from
+`mollie-ecommerce/http` turns it into an HTTP handler with the status codes and
+the duplicate-delivery retry already handled. See
+[the webhook](#2-the-mollie-webhook).
+
 ### `refund(input) → { order, refund }`
 
 Refunds a paid order: in full, by amount, or by line. Moves money only — see
@@ -359,27 +365,63 @@ function customerMessage(error: CommerceError): string {
 
 Mollie posts `id=tr_...` form-encoded and nothing else — no status, so the
 state has to come from the API, which is exactly what `handleWebhook` does.
-Two rules matter: **always answer 2xx** (any other status makes Mollie retry,
-forever for a payment you will never recognize), and **answer fast** — do your
-own slow work (emails, invoices, ERP calls) after responding.
+`mollie-ecommerce/http` wraps it in a `Request → Response` handler that carries
+the parts every integration has to get right the same way:
 
 ```ts
+import { createWebhookHandler } from "mollie-ecommerce/http";
 import { commerce } from "./shop.ts";
+import { queue } from "./queue.ts";
+
+export const postMollieWebhook = createWebhookHandler({
+  commerce,
+  // Enqueue only — Mollie is waiting. Emails, invoices and ERP calls happen
+  // after the response, in your worker.
+  onOrder: (order) => {
+    if (order.payment.state === "paid") {
+      queue.push({ type: "order.paid", orderId: order.id });
+    }
+  },
+  onError: (error, { paymentId, status }) =>
+    log.error({ err: error, paymentId, willRetry: status >= 500 }, "mollie webhook"),
+});
+```
 
-export async function postMollieWebhook(request: Request): Promise<Response> {
-  const form = await request.formData();
-  const paymentId = String(form.get("id") ?? "");
-  if (!paymentId) return new Response("missing id", { status: 400 });
+It is a plain `(Request) => Promise<Response>`, so routing stays yours:
 
-  const order = await commerce.handleWebhook(paymentId);
-  if (!order) return new Response("ok"); // not ours — still 200
-  if (order.payment.state === "paid" && order.delivery.state === "ready") {
-    queue.push({ type: "order.paid", orderId: order.id }); // email, invoice, picking slip
-  }
-  return new Response("ok");
-}
+```ts
+Bun.serve({ routes: { "/mollie-webhook": { POST: postMollieWebhook } } });
+app.post("/mollie-webhook", (c) => postMollieWebhook(c.req.raw));   // Hono
+export { postMollieWebhook as POST };                              // Next.js route file
 ```
 
+For a `req`/`res` framework like Express, skip the handler and call
+`commerce.handleWebhook(paymentId)` directly — it stays the operation, and the
+handler is only a convenience over it.
+
+**What the handler decides for you.** To Mollie, 2xx means "absorbed, stop" and
+anything else means "retry", so the status is not a formality — it is how a
+payment either converges or gets silently dropped:
+
+| Situation | Answer | Why |
+| --- | --- | --- |
+| no `id` in the body | 200 | not Mollie, or a probe; retrying conjures nothing |
+| payment unknown here | 200 | a non-2xx retries forever for an order that will never exist |
+| `order_not_found` | 200 | the order vanished mid-flight; no state left to converge on |
+| `gateway_error`, `storage_error` | 503 | transient — the redelivery *is* the recovery |
+| `version_conflict` | retried, then 503 | a duplicate delivery won the write race |
+| `storage_contract`, anything else | 500 | a bug; Mollie's remaining retries recover it once fixed |
+
+That last distinction is the one worth internalising even if you route the
+webhook yourself: answering 2xx to a database blip tells Mollie the payment was
+handled and you will never hear about it again.
+
+Two more Mollie facts the handler folds in. **There is nothing to verify** —
+Mollie does not sign webhooks, which is why the state is re-read from the API
+instead; a forged body cannot move an order. And **refunds and chargebacks
+arrive on this same route**, carrying the same payment id, so one route is all
+you need.
+
 Mollie cannot reach `localhost`, so tunnel the URL in development
 (`bunx untun tunnel http://localhost:3000`, ngrok, or Cloudflare Tunnel) and
 pass it as `webhookUrl`.
@@ -1109,14 +1151,20 @@ how you find out whether yours still conforms.
 - **Digital orders self-deliver.** No physical lines means `delivered` on payment. Disable with `autoDeliverDigital: false`.
 - **Refund state is optimistic.** Mollie returns `pending`; `syncOrder` reconciles `amountRefunded` from the payment.
 - **The webhook URL must be publicly reachable.** Mollie cannot call `localhost`; tunnel it in development.
+- **Webhook status codes are load-bearing.** 2xx means "absorbed", anything else means "retry", so a transient failure answered 2xx drops the payment. `createWebhookHandler` maps them for you.
 - **No expiry sweeper.** Mollie expires unpaid payments and calls your webhook. To free stock sooner, run `findOrders({ paymentState: ["created", "open", "pending"] })` on a schedule and call `syncOrder`.
 
 ## Contributing
 
-Bug reports, storage adapters, and documentation fixes are all welcome — see
-[CONTRIBUTING.md](CONTRIBUTING.md). Security issues go through
+Bug reports, storage implementations, and documentation fixes are all welcome —
+see [CONTRIBUTING.md](CONTRIBUTING.md). Security issues go through
 [SECURITY.md](SECURITY.md), not the public tracker.
 
+Releases are automated: every change carries a
+[changeset](https://github.com/changesets/changesets), those collect into a
+`release: version packages` PR, and merging it publishes to npm — but only once
+CI is green on `main`.
+
 ## License
 
 [MIT](LICENSE)

package/dist/commerce-D26DAG-Y.d.ts

@@ -0,0 +1,381 @@
+import { A as Money, S as OrderLine, T as Sku, d as OrderQuery, f as PaymentGateway, g as StockShortage, o as Clock, t as CommerceStorage, u as IdGenerator, w as Refund, x as Order, y as Customer } from "./storage-handlers-Ce9E1a0L.js";
+type CommerceErrorCode = "sku_not_found" | "sku_inactive" | "out_of_stock" | "order_not_found" | "empty_cart" | "currency_mismatch" | "not_payable" | "not_refundable" | "refund_too_large" | "invalid_delivery_transition" | "gateway_error" |
+/** Someone else updated the order first; reload and retry. */
+"version_conflict" | "duplicate_order" | "storage_error" |
+/** A storage handler broke its contract — see `checkedStorage`. */
+"storage_contract";
+declare class CommerceError extends Error {
+  readonly code: CommerceErrorCode;
+  readonly details?: Record<string, unknown> | undefined;
+  constructor(code: CommerceErrorCode, message: string, details?: Record<string, unknown> | undefined,
+  /** Standard `Error` options, so `{ cause }` survives for your logs. */
+  options?: ErrorOptions);
+}
+/**
+ * Errors a storage handler is expected to raise, pre-shaped so your handlers
+ * speak the same vocabulary the rest of the library does — and so your
+ * application's error mapping only ever has to know `CommerceError.code`.
+ *
+ * ```ts
+ * async mutateOrder(orderId, apply) {
+ *   const order = await db.loadOrder(orderId);
+ *   if (!order) throw storageError.orderNotFound(orderId);
+ *   // …
+ *   if (!written) throw storageError.versionConflict(orderId, order.version);
+ * }
+ * ```
+ *
+ * Throwing anything else is fine too: it travels out through whichever
+ * `commerce.*` method was running, and `onStorageError` can translate it.
+ */
+declare const storageError: {
+  /**
+   * Not enough stock. `createOrder` may either return
+   * `{ status: "out_of_stock", shortages }` or throw this — whichever suits
+   * your implementation, since aborting a transaction usually means throwing.
+   *
+   * @param shortages What fell short, as `reserveStock` reported it.
+   */
+  outOfStock(shortages: StockShortage[]): CommerceError;
+  /**
+   * The order a handler was asked for does not exist. `mutateOrder` must throw
+   * this; the read handlers return `null` instead.
+   *
+   * @param orderId The id that was not found.
+   */
+  orderNotFound(orderId: string): CommerceError;
+  /**
+   * Someone else wrote the order first, so this write was refused rather than
+   * allowed to overwrite. Callers are expected to re-read and retry.
+   *
+   * @param orderId The contested order.
+   * @param expected The version the write was based on.
+   * @param actual The version found in storage, if you know it.
+   */
+  versionConflict(orderId: string, expected?: number, actual?: number): CommerceError;
+  /**
+   * An order already exists with that id, payment id, or idempotency key —
+   * typically a unique-index violation from `createOrder`.
+   *
+   * @param orderId The order being inserted.
+   * @param cause The driver error, kept for your logs.
+   */
+  duplicateOrder(orderId: string, cause?: unknown): CommerceError;
+  /**
+   * Storage failed for a reason the library has no opinion about: a dropped
+   * connection, a timeout, a disk error.
+   *
+   * @param message What went wrong, for your logs.
+   * @param cause The underlying error.
+   */
+  failed(message: string, cause?: unknown): CommerceError;
+};
+/** Which handler failed, and what it was working on. */
+type StorageErrorContext = {
+  handler: keyof CommerceStorage;
+  /** Present when the call targeted one order. */
+  orderId?: string;
+  /** Present for `loadSkus`. */
+  skuIds?: string[];
+  /** Present for the lookups that take a key. */
+  key?: string;
+};
+/**
+ * Handles an error thrown inside a storage handler.
+ *
+ * - Return a {@link CommerceError} to **translate** it — a driver's unique
+ *   violation into `duplicate_order`, a deadlock into `version_conflict` — and
+ *   that is what callers of `commerce.*` will see.
+ * - Return nothing to **observe only**: log it, count it, and let the original
+ *   error through untouched.
+ * - Throw to replace it with anything you like.
+ *
+ * It never swallows: there is no way to make a failed write look like a
+ * success, because the commerce layer would then persist nothing and carry on.
+ */
+type StorageErrorHandler = (error: unknown, context: StorageErrorContext) => CommerceError | void | Promise<CommerceError | void>;
+type CommerceOptions = {
+  /**
+   * Payment provider. `createMollieGateway()` for production,
+   * `new FakePaymentGateway()` for tests and local development.
+   */
+  gateway: PaymentGateway;
+  /**
+   * The storage handlers to fulfil. See {@link CommerceStorage} — seven
+   * functions, with no transactions or queries on this side of the boundary.
+   *
+   * Every argument and return value is validated against the contract (see
+   * `checkedStorage`), so a handler that drifts fails immediately and says
+   * which field was wrong.
+   */
+  storage: CommerceStorage;
+  /**
+   * Called when a storage handler throws, before the error reaches your
+   * caller. Return a {@link CommerceError} to translate it, return nothing to
+   * just observe it, or throw your own. Contract violations
+   * (`storage_contract`) pass through here as well.
+   *
+   * ```ts
+   * onStorageError: (error, { handler, orderId }) => {
+   *   log.error({ err: error, handler, orderId }, "storage failed");
+   *   if (isDeadlock(error)) return new CommerceError("version_conflict", "retry", { orderId });
+   * }
+   * ```
+   */
+  onStorageError?: StorageErrorHandler;
+  /**
+   * Where Mollie returns the customer after paying. Required by Mollie for
+   * most payment methods; override per checkout if it varies.
+   */
+  redirectUrl?: string;
+  /** Where Mollie returns the customer if they abandon the payment. */
+  cancelUrl?: string;
+  /**
+   * Public URL Mollie posts status changes to. Without it you get no status
+   * updates and must poll {@link Commerce.syncOrder} yourself. Cannot be
+   * `localhost`.
+   */
+  webhookUrl?: string;
+  /**
+   * Move delivery straight to `delivered` when an order with no physical lines
+   * is paid. Default `true`.
+   */
+  autoDeliverDigital?: boolean;
+  /**
+   * Decrement SKU stock at checkout and give it back if the payment dies.
+   * Default `true`. Set `false` if you track stock elsewhere.
+   */
+  reserveStock?: boolean;
+  /** Override the clock, e.g. to freeze timestamps in tests. */
+  clock?: Clock;
+  /** Override id generation. Receives a prefix such as `"ord"`. */
+  generateId?: IdGenerator;
+};
+type CartItem = {
+  /** The SKU being bought — one purchasable variant. */
+  skuId: string;
+  /** Defaults to 1. Repeated SKUs are merged into one line. */
+  quantity?: number;
+};
+type CheckoutInput = {
+  /** At least one item. Prices, stock, and currency are validated. */
+  items: CartItem[];
+  customer?: Customer;
+  /**
+   * Payment description shown on the customer's statement. Defaults to a
+   * generated summary; Mollie truncates it per payment method.
+   */
+  description?: string;
+  /** Overrides {@link CommerceOptions.redirectUrl} for this order. */
+  redirectUrl?: string;
+  /** Overrides {@link CommerceOptions.cancelUrl} for this order. */
+  cancelUrl?: string;
+  /** Overrides {@link CommerceOptions.webhookUrl} for this order. */
+  webhookUrl?: string;
+  /**
+   * Makes checkout replay-safe: calling again with the same key returns the
+   * original order instead of charging twice. Also sent to Mollie.
+   */
+  idempotencyKey?: string;
+};
+type CheckoutResult = {
+  order: Order;
+  /** Redirect the customer here to pay. Absent only if Mollie returns none. */
+  checkoutUrl?: string;
+  /** True when an existing order was returned for a repeated idempotency key. */
+  replayed: boolean;
+};
+type RefundInput = {
+  orderId: string;
+  /**
+   * Exact amount to refund. Mutually exclusive with `lines`; omit both to
+   * refund everything still refundable.
+   */
+  amount?: Money;
+  /**
+   * Refund by order line instead of by amount. Quantity defaults to the whole
+   * line. Only the money is affected — stock is not restored.
+   */
+  lines?: {
+    skuId: string;
+    quantity?: number;
+  }[];
+  /** Forwarded to Mollie as the refund description, and stored on the order. */
+  reason?: string;
+  /** Prevents a retried request from refunding twice. */
+  idempotencyKey?: string;
+};
+type RefundResult = {
+  /** The order after the refund was applied. */
+  order: Order;
+  /** The refund that was just created. */
+  refund: Refund;
+};
+type ShipInput = {
+  orderId: string;
+  carrier?: string;
+  trackingCode?: string;
+};
+type ReturnInput = {
+  orderId: string;
+  /** Put the goods back into stock. Does not move money — refund separately. */
+  restock?: boolean;
+};
+/**
+ * Builds the commerce API: checkout, payment reconciliation, refunds, and the
+ * delivery lifecycle, over any storage and any payment gateway.
+ *
+ * ```ts
+ * const commerce = createCommerce({
+ *   gateway: createMollieGateway({ apiKey: process.env.MOLLIE_API_KEY }),
+ *   db: new SqliteDatabase({ filename: "./shop.sqlite" }),
+ *   redirectUrl: "https://shop.example/thanks",
+ *   webhookUrl: "https://shop.example/mollie-webhook",
+ * });
+ * ```
+ *
+ * Every method throws {@link CommerceError} with a machine-readable `code`.
+ * No gateway call happens inside a storage write handler, so the transactions
+ * you open there stay short.
+ */
+declare function createCommerce(options: CommerceOptions): {
+  /**
+   * Starts an order: prices the cart from the catalog, reserves stock, and
+   * creates a Mollie payment. Send the customer to `checkoutUrl`.
+   *
+   * The order is persisted before the payment is created, so a gateway
+   * failure leaves a `failed` order rather than a lost cart — and its stock
+   * reservation is released.
+   *
+   * @param input.items Cart items; `[{ skuId, quantity? }]`, quantity defaults to 1.
+   * @param input.customer Optional `{ email?, locale? }`.
+   * @param input.description Payment description; defaults to a generated summary.
+   * @param input.redirectUrl Overrides the configured redirect URL.
+   * @param input.cancelUrl Overrides the configured cancel URL.
+   * @param input.webhookUrl Overrides the configured webhook URL.
+   * @param input.idempotencyKey Replaying this key returns the first order instead of charging again.
+   * @returns `{ order, checkoutUrl, replayed }`.
+   * @throws `empty_cart` no items, or a quantity below 1.
+   * @throws `sku_not_found` an item references an unknown SKU.
+   * @throws `sku_inactive` a SKU has `active: false`.
+   * @throws `out_of_stock` insufficient stock; nothing is reserved.
+   * @throws `currency_mismatch` the cart mixes currencies.
+   */
+  checkout: (input: CheckoutInput) => Promise<CheckoutResult>;
+  /**
+   * Re-reads the payment from Mollie and folds it into the order: payment
+   * state, refunded amount, and the delivery/stock consequences. Idempotent.
+   *
+   * Use it when you cannot receive webhooks, when the customer returns to
+   * your redirect URL, or to reconcile on a schedule.
+   *
+   * @param orderId The order to refresh.
+   * @returns The updated order; unchanged if no payment exists yet.
+   * @throws `order_not_found` no such order.
+   * @throws `gateway_error` Mollie could not be reached.
+   */
+  syncOrder: (orderId: string) => Promise<Order>;
+  /**
+   * Handles a Mollie webhook, which carries only a payment id and no status.
+   * Looks the order up, then does the same work as {@link syncOrder}.
+   *
+   * Respond 2xx even for `null`: a non-2xx makes Mollie retry a payment you
+   * will never recognize.
+   *
+   * @param paymentId The `id` Mollie posted (`tr_...`).
+   * @returns The updated order, or `null` if the payment is unknown here.
+   */
+  handleWebhook: (paymentId: string) => Promise<Order | null>;
+  /**
+   * Refunds a paid order, in full, by amount, or by line. Mollie usually
+   * reports refunds as `pending`; {@link syncOrder} reconciles the final
+   * state. Does not restock — see {@link markReturned}.
+   *
+   * @param input.orderId The order to refund.
+   * @param input.amount Exact amount; mutually exclusive with `lines`.
+   * @param input.lines Lines to refund as `[{ skuId, quantity? }]`; quantity defaults to the whole line.
+   * @param input.reason Refund description, forwarded to Mollie.
+   * @param input.idempotencyKey Prevents a retry from refunding twice.
+   * @returns `{ order, refund }`.
+   * @throws `order_not_found` no such order.
+   * @throws `not_refundable` the order is not paid, or the amount is not positive.
+   * @throws `refund_too_large` more than `total − amountRefunded`, or more units than the line holds.
+   * @throws `currency_mismatch` the amount's currency is not the order's.
+   */
+  refund: (input: RefundInput) => Promise<RefundResult>;
+  /**
+   * Marks the order ready to fulfil. Paying already does this, so you only
+   * need it when `reserveStock`/payment flows are bypassed.
+   *
+   * @param orderId The order to advance.
+   * @returns The updated order.
+   * @throws `invalid_delivery_transition` not reachable from the current state.
+   */
+  markReady: (orderId: string) => Promise<Order>;
+  /**
+   * Marks the order shipped and records the carrier and tracking code.
+   *
+   * @param input.orderId The order being shipped.
+   * @param input.carrier Carrier name, e.g. `"PostNL"`. Keeps the existing value if omitted.
+   * @param input.trackingCode Tracking code. Keeps the existing value if omitted.
+   * @returns The updated order.
+   * @throws `invalid_delivery_transition` the order is not `ready`.
+   */
+  markShipped: (input: ShipInput) => Promise<Order>;
+  /**
+   * Marks the order delivered. Digital-only orders reach this automatically
+   * when paid, unless `autoDeliverDigital` is off.
+   *
+   * @param orderId The delivered order.
+   * @returns The updated order.
+   * @throws `invalid_delivery_transition` the order is not `ready` or `shipped`.
+   */
+  markDelivered: (orderId: string) => Promise<Order>;
+  /**
+   * Records a return. Moves no money — call {@link refund} for that.
+   *
+   * @param input.orderId The returned order.
+   * @param input.restock `true` to put the goods back into stock.
+   * @returns The updated order.
+   * @throws `invalid_delivery_transition` the order was never shipped or delivered.
+   */
+  markReturned: (input: ReturnInput) => Promise<Order>;
+  /**
+   * Cancels an unpaid order: cancels the Mollie payment when it is still
+   * cancelable, releases the stock, and cancels the delivery.
+   *
+   * @param orderId The order to cancel.
+   * @returns The updated order.
+   * @throws `order_not_found` no such order.
+   * @throws `not_payable` the order is already paid — refund it instead.
+   */
+  cancelOrder: (orderId: string) => Promise<Order>;
+  /**
+   * Reads one order, including its lines, refunds, and both state machines.
+   *
+   * @param orderId The order to read.
+   * @returns The order, or `null` if it does not exist.
+   */
+  getOrder: (orderId: string) => Promise<Order | null>;
+  /**
+   * Lists orders, newest-created last.
+   *
+   * @param query Optional filters: `paymentState`, `deliveryState`,
+   * `customerEmail`, `createdAfter`, `createdBefore`, `limit`, `offset`.
+   * State filters accept one value or an array.
+   * @returns Matching orders.
+   */
+  findOrders: (query?: OrderQuery) => Promise<Order[]>;
+  /**
+   * The storage handlers in use, as resolved from `storage` or `db`. Exposed
+   * for wrapping and testing; catalog writes go to your own storage, not
+   * through here.
+   */
+  storage: CommerceStorage;
+};
+type Commerce = ReturnType<typeof createCommerce>;
+/** Freezes a catalog SKU into an order line at the given quantity. */
+declare function lineFromSku(sku: Sku, quantity: number): OrderLine;
+/** Default payment description. Mollie truncates, so keep it identifiable. */
+declare function describeOrder(order: Order): string;
+export { storageError as _, CommerceOptions as a, ReturnInput as c, describeOrder as d, lineFromSku as f, CommerceErrorCode as g, CommerceError as h, Commerce as i, ShipInput as l, StorageErrorHandler as m, CheckoutInput as n, RefundInput as o, StorageErrorContext as p, CheckoutResult as r, RefundResult as s, CartItem as t, createCommerce as u };

package/dist/conformance.js

@@ -1,4 +1,5 @@
-import { E as money, t as checkedStorage, v as CommerceError } from "./storage-guards-Bct0v7l9.js";
+import { t as CommerceError } from "./errors-DJU7-Bnk.js";
+import { t as checkedStorage, w as money } from "./storage-guards-C3g_KlQm.js";
 import { beforeEach, expect, test } from "bun:test";
 // src/conformance.ts
 /**

package/dist/errors-DJU7-Bnk.js

@@ -0,0 +1,86 @@
+// src/errors.ts
+var CommerceError = class extends Error {
+	code;
+	details;
+	constructor(code, message, details, options) {
+		super(message, options);
+		this.code = code;
+		this.details = details;
+		this.name = "CommerceError";
+	}
+};
+/**
+* Errors a storage handler is expected to raise, pre-shaped so your handlers
+* speak the same vocabulary the rest of the library does — and so your
+* application's error mapping only ever has to know `CommerceError.code`.
+*
+* ```ts
+* async mutateOrder(orderId, apply) {
+*   const order = await db.loadOrder(orderId);
+*   if (!order) throw storageError.orderNotFound(orderId);
+*   // …
+*   if (!written) throw storageError.versionConflict(orderId, order.version);
+* }
+* ```
+*
+* Throwing anything else is fine too: it travels out through whichever
+* `commerce.*` method was running, and `onStorageError` can translate it.
+*/
+const storageError = {
+	/**
+	* Not enough stock. `createOrder` may either return
+	* `{ status: "out_of_stock", shortages }` or throw this — whichever suits
+	* your implementation, since aborting a transaction usually means throwing.
+	*
+	* @param shortages What fell short, as `reserveStock` reported it.
+	*/
+	outOfStock(shortages) {
+		const first = shortages[0];
+		return new CommerceError("out_of_stock", first ? `sku ${first.skuId} is out of stock` : "out of stock", { shortages });
+	},
+	/**
+	* The order a handler was asked for does not exist. `mutateOrder` must throw
+	* this; the read handlers return `null` instead.
+	*
+	* @param orderId The id that was not found.
+	*/
+	orderNotFound(orderId) {
+		return new CommerceError("order_not_found", `no order ${orderId}`, { orderId });
+	},
+	/**
+	* Someone else wrote the order first, so this write was refused rather than
+	* allowed to overwrite. Callers are expected to re-read and retry.
+	*
+	* @param orderId The contested order.
+	* @param expected The version the write was based on.
+	* @param actual The version found in storage, if you know it.
+	*/
+	versionConflict(orderId, expected, actual) {
+		return new CommerceError("version_conflict", `order ${orderId} was modified concurrently${expected === void 0 ? "" : actual === void 0 ? ` (expected version ${expected})` : ` (expected version ${expected}, found ${actual})`}`, {
+			orderId,
+			expected,
+			actual
+		});
+	},
+	/**
+	* An order already exists with that id, payment id, or idempotency key —
+	* typically a unique-index violation from `createOrder`.
+	*
+	* @param orderId The order being inserted.
+	* @param cause The driver error, kept for your logs.
+	*/
+	duplicateOrder(orderId, cause) {
+		return new CommerceError("duplicate_order", `order ${orderId} already exists`, { orderId }, { cause });
+	},
+	/**
+	* Storage failed for a reason the library has no opinion about: a dropped
+	* connection, a timeout, a disk error.
+	*
+	* @param message What went wrong, for your logs.
+	* @param cause The underlying error.
+	*/
+	failed(message, cause) {
+		return new CommerceError("storage_error", message, void 0, { cause });
+	}
+};
+export { storageError as n, CommerceError as t };