mollie-ecommerce 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,256 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) — pre-1.0, breaking
+changes go in the minor slot.
+
+Entries from 0.5.0 onwards are generated by
+[changesets](https://github.com/changesets/changesets) at release time;
+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
+
+- Publish built JavaScript instead of TypeScript source. The package now ships
+  `dist/` — ESM plus type declarations, bundled with
+  [tsdown](https://tsdown.dev) — so it works on Node, Bun, Deno and bundlers
+  alike.
+  
+  Shipping source made the package Bun-only in practice: Node refuses to strip
+  types for anything under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`),
+  and many bundlers skip transpiling dependencies. It also meant every consumer
+  typechecked the library's internals under their own `tsconfig`; now they get
+  declarations we checked ourselves.
+  
+  `zod` and `mollie-api-typescript` stay external, so nothing is duplicated.
+  Import paths are unchanged. The `mollie-ecommerce/conformance` entry still
+  needs Bun, since it builds on `bun:test`.
+
+## 0.4.0 — 2026-11-04
+
+**Breaking.** `createCommerce` no longer performs storage work, and the package
+no longer ships storage adapters. It opens no transaction, issues no query, and
+knows nothing about tables: it calls seven handlers you fulfil, and persistence
+is yours — your migrations, your pool, your naming.
+
+### Added
+
+- `CommerceStorage` — the handler contract: `loadSkus`, `findOrder`,
+  `findOrderByPaymentId`, `findOrderByIdempotencyKey`, `listOrders`, plus the
+  two write handlers `createOrder` (order and stock together, returning
+  `{ status: "out_of_stock", shortages }` rather than throwing) and
+  `mutateOrder` (read, apply a mutation, persist atomically with any
+  `releaseStock`). Atomicity and concurrency are now the handler's contract,
+  documented per handler.
+- `examples/memory-storage.ts` — a complete handler implementation over two
+  maps, published with the package as a copy-paste starting point, and covered
+  by this repo's lifecycle tests so it cannot drift.
+- `describeCommerceStorage` in `mollie-ecommerce/conformance` — 11
+  contract tests for a handler implementation, covering the cases that are easy
+  to get subtly wrong: a shortage must not persist the order, `releaseStock`
+  must land in the same write as its mutation, and a throwing mutator must
+  leave nothing behind.
+- **Runtime contract enforcement, always on.** `createCommerce` validates every
+  argument and return value crossing the storage boundary with
+  [zod](https://zod.dev), failing at the offending call with
+  `CommerceError("storage_contract")` instead of corrupting an order later.
+  Roughly 2µs per order, and nothing to switch on. It also checks what a schema
+  cannot express:
+  `loadSkus` returning only requested SKUs and none twice, `createOrder`
+  returning the order it was given with a version, and `mutateOrder` calling
+  the mutator and returning a *higher* version — a silent lost write is
+  otherwise invisible. Validated values pass through unchanged, never zod's
+  parsed copy. The checks are internal — there is nothing to import or switch
+  on — and `describeCommerceStorage` runs the same ones, so conformance
+  verifies what production enforces.
+- Exported zod schemas for everything crossing the boundary — `OrderSchema`,
+  `SkuSchema`, `MoneySchema`, `OrderQuerySchema` and the rest — useful for
+  validating rows you rebuilt from JSON columns. A compile-time check keeps
+  them in step with the TypeScript types.
+- `createCommerce({ onStorageError })` and `withStorageErrorHandler` — one
+  place to see errors thrown inside handlers. Return a `CommerceError` to
+  translate a driver error into the library's vocabulary (a serialization
+  failure into `version_conflict`, a unique violation into `duplicate_order`),
+  return nothing to observe only, or throw your own. The context names the
+  handler and what it was working on, including contract violations. It cannot
+  swallow an error.
+- `storageError` — helpers for the errors a handler is expected to raise:
+  `outOfStock`, `orderNotFound`, `versionConflict`, `duplicateOrder` and
+  `failed`, so handlers speak the same vocabulary as the rest of the library
+  and your error mapping only needs `CommerceError.code`.
+- `createOrder` may now **throw** `storageError.outOfStock(shortages)` instead
+  of returning `{ status: "out_of_stock" }`. Both reach the caller as
+  `out_of_stock`, and throwing is usually simpler since a transaction aborts by
+  throwing anyway. `describeCommerceStorage` accepts either.
+- `CommerceError` accepts `{ cause }`, so a handler can wrap a driver error
+  without losing it.
+- `CommerceError` code `storage_contract`.
+- README: a "Persistence" section with the contract and a worked example, a
+  "Reference schema" section (the SQL the test suites use, as a starting point
+  you own), and a revised map of how the data sits next to your catalog.
+
+### Fixed
+
+- A failed compensating write no longer hides the error that caused it. If
+  `createPayment` fails and releasing the stock fails too, the thrown error is
+  a `storage_error` that says the reservation is still held, carrying the
+  gateway error as its `cause` and both in `details` — previously the storage
+  error replaced the gateway one, losing the reason the payment failed.
+
+### Changed
+
+- New dependency: `zod` (^4), for the exported schemas and the internal
+  contract checks.
+- The standalone `versionConflict()` helper is now `storageError.versionConflict`.
+
+### Removed
+
+- **All storage adapters and their exports.** `InMemoryDatabase`,
+  `SqliteDatabase`, the Postgres stores, `storageFromDatabase`, the `Database`
+  / `SkuStore` / `OrderStore` ports, the row mappers, `SCHEMA_SQL`,
+  `describeDatabase`, and the `./storage/*` subpaths are gone from the package.
+  They live on under `test/` as fixtures, so the lifecycle suite still runs
+  against in-memory, SQLite and Postgres storage.
+- `createCommerce({ db })`. Pass `storage` instead; to keep the old behavior,
+  copy `test/storage/from-database.ts` into your project.
+
+### Changed
+
+- `commerce.db` → `commerce.storage`, exposing the handlers you passed in.
+- The `./conformance` subpath replaces `./storage/conformance`.
+
+## 0.3.0 — 2026-11-03
+
+**Breaking.** The sellable unit is now a SKU rather than a product, because a
+product has no single price or stock level and a purchasable variant does. This
+removes the need to model variants at all: register one SKU per combination and
+keep products, options and images in your own catalog.
+
+### Changed
+
+- `Product` → `Sku`, with a new optional `productId` grouping key (indexed,
+  never interpreted by the library) and `ProductKind` → `SkuKind`. `kind` now
+  lives per SKU, so one product can ship physically and download digitally.
+- `CartItem.productId` → `skuId`; `refund({ lines })` takes `{ skuId }`;
+  `OrderLine.productId` → `skuId`, plus an optional `productId` copied from the
+  SKU at purchase time.
+- `Database.products` → `Database.skus`; `ProductStore` → `SkuStore`;
+  `ProductQuery` → `SkuQuery`, which gained a `productId` filter for listing a
+  product's variants. Adapter classes follow: `InMemorySkuStore`,
+  `SqliteSkuStore`, `PostgresSkuStore`.
+- `StockChange.productId` → `skuId`; `StockShortage.productId` → `skuId`.
+- Error codes `product_not_found` → `sku_not_found` and `product_inactive` →
+  `sku_inactive`.
+- Row mappers `productToRow` / `rowToProduct` → `skuToRow` / `rowToSku`;
+  `ProductRow` → `SkuRow` with a `product_id` column.
+- Database schema: table `products` → `skus`, with a nullable `product_id`
+  column and a `skus_product_id` index.
+
+### Migration
+
+Rename the table and add the grouping column; existing rows need no other
+change, since every other column keeps its name and meaning:
+
+```sql
+ALTER TABLE products RENAME TO skus;
+ALTER TABLE skus ADD COLUMN product_id TEXT;
+CREATE INDEX IF NOT EXISTS skus_product_id ON skus (product_id);
+```
+
+Stored orders need no migration: `OrderLine.productId` becomes `skuId`, and the
+JSON already holds the id of the thing that was sold. If you want old orders to
+read back with the new field name:
+
+```sql
+-- Postgres
+UPDATE orders SET lines = replace(lines, '"productId"', '"skuId"');
+```
+
+In code, rename `productId` to `skuId` at your call sites — your existing
+product ids are valid SKU ids, so nothing needs re-keying. To adopt variants,
+add one SKU per combination and set `productId` on each.
+
+## 0.2.0 — 2026-11-03
+
+### Added
+
+- **Postgres storage** (`mollie-ecommerce/storage/postgres`):
+  `createPostgresDatabase(pool)`, `PostgresProductStore`,
+  `PostgresOrderStore`, and `applyPostgresSchema`. The module imports no
+  driver — you pass a connection, so anything with node-postgres' shape works
+  (`query(sql, params) → { rows }` plus `connect()`). Transactions check out
+  one connection and run `BEGIN`/`COMMIT` on it; a nested call joins the
+  outer transaction instead of taking a second connection.
+- `aggregateStock` helper, exported for storage adapters.
+- README: a "Using Postgres" guide (driver install, schema and migrations,
+  pool and pooler behavior, column-type rationale, conformance verification,
+  operating notes) and an end-to-end "real-world shop" walkthrough covering
+  checkout, webhook, redirect return, fulfillment, and reconciliation.
+
+### Fixed
+
+- **`reserveStock` could oversell when the same product appeared twice in one
+  call.** The in-memory and SQLite adapters checked each entry against the
+  full stock independently and then decremented both, so `[{mug, 2}, {mug, 2}]`
+  against a stock of 3 succeeded and left −1. All adapters now aggregate
+  repeated product ids via `aggregateStock`, and the conformance suite covers
+  it. Checkout was never affected, since it merges cart lines first; direct
+  callers of the port were.
+
+### Changed
+
+- `describeDatabase` now runs 18 contract tests (was 17), and the lifecycle
+  suite runs against all three storage adapters. Postgres is exercised with
+  [PGlite](https://pglite.dev) through a pool shim, plus a compile-time guard
+  that node-postgres satisfies the adapter's ports — both devDependencies
+  only.
+
+## 0.1.0 — 2026-11-03
+
+First release. Pre-1.0, so the public API may still change in minor versions
+(see [Versioning](README.md#versioning)).
+
+### Added
+
+- `createCommerce({ gateway, db, ... })` — the commerce API: `checkout`,
+  `syncOrder`, `handleWebhook`, `refund`, `markReady`, `markShipped`,
+  `markDelivered`, `markReturned`, `cancelOrder`, `getOrder`, `findOrders`.
+- Product and order model: `Product`, `Order`, `OrderLine`, `Refund`,
+  `Customer`, with payment state mirroring Mollie's and a separate delivery
+  state machine (`not_started → ready → shipped → delivered → returned`, plus
+  `canceled`).
+- `Money` as integer minor units plus currency, converted to and from Mollie's
+  decimal strings at the API boundary (`money`, `add`, `subtract`, `multiply`,
+  `sum`, `toMollieAmount`, `fromMollieAmount`, `formatMoney`).
+- Idempotent checkout: replaying an `idempotencyKey` returns the original order
+  instead of charging twice.
+- Stock reservation at checkout, released exactly once when a payment is
+  canceled, expires, or fails — or on `markReturned({ restock: true })`.
+- `createMollieGateway({ apiKey })` over `mollie-api-typescript`, and
+  `FakePaymentGateway` for tests and local development.
+- Storage ports (`Database`, `ProductStore`, `OrderStore`) with optimistic
+  concurrency, batched reads, atomic stock, and transactions.
+- `InMemoryDatabase`, `SqliteDatabase` (`bun:sqlite`), row mappers plus
+  `SCHEMA_SQL`, and `describeDatabase` — 17 contract tests to verify your own
+  adapter.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mollie-ecommerce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.