@cogenta/commerce 0.2.0 → 0.4.3

package/dist/admin/router.js

@@ -1,7 +1,12 @@
 import { CogentaError, isCogentaError } from '@cogenta/core';
+import { applyProductsImport, exportProductsCsv, previewProductsImport } from '../catalog/csv.js';
 import { COUPON_KINDS } from '../coupon/store.js';
+import { ordersToCsv } from '../order/csv.js';
 import { ORDER_STATUSES } from '../order/types.js';
-import { COMMERCE_ANONYMOUS } from './permissions.js';
+import { SHIPPING_KINDS } from '../shipping/store.js';
+import { SUBSCRIPTION_STATUSES, } from '../subscription/store.js';
+import { taxFor } from '../tax/store.js';
+import { COMMERCE_ANONYMOUS, COMMERCE_PERMISSIONS } from './permissions.js';
 const STATUS_BY_CODE = {
     UNAUTHENTICATED: 401,
     FORBIDDEN: 403,
@@ -14,11 +19,16 @@ const STATUS_BY_CODE = {
     COMMERCE_INVOICE_NOT_FOUND: 404,
     COMMERCE_SUBSCRIPTION_NOT_FOUND: 404,
     COMMERCE_SHIPPING_METHOD_UNKNOWN: 404,
+    COMMERCE_TAX_RULE_UNKNOWN: 404,
+    COMMERCE_CUSTOMER_NOT_FOUND: 404,
+    COMMERCE_CREDIT_NOTE_NOT_FOUND: 404,
     COMMERCE_PRODUCT_INVALID: 400,
+    COMMERCE_TRACKING_INVALID: 400,
     COMMERCE_SKU_TAKEN: 409,
     COMMERCE_INVOICE_ALREADY_ISSUED: 409,
     COMMERCE_CART_CLOSED: 409,
     COMMERCE_ORDER_TRANSITION_INVALID: 409,
+    COMMERCE_ORDER_LOCKED: 409,
     COMMERCE_INVOICE_SEQUENCE_CONFLICT: 409,
     COMMERCE_AMOUNT_INVALID: 400,
     COMMERCE_CURRENCY_INVALID: 400,
@@ -26,12 +36,19 @@ const STATUS_BY_CODE = {
     COMMERCE_QUANTITY_INVALID: 400,
     COMMERCE_COUPON_INVALID: 400,
     COMMERCE_COUPON_EXHAUSTED: 409,
+    COMMERCE_COUPON_CUSTOMER_EXHAUSTED: 409,
+    COMMERCE_COUPON_NOT_APPLICABLE: 400,
     COMMERCE_TAX_RULE_INVALID: 400,
     COMMERCE_SHIPPING_UNAVAILABLE: 400,
     COMMERCE_SUBSCRIPTION_INVALID: 400,
     COMMERCE_REFUND_EXCEEDS_PAYMENT: 400,
     COMMERCE_PAYMENT_UNSUPPORTED: 400,
     COMMERCE_PAYMENT_SIGNATURE_INVALID: 403,
+    // The driver registry's own vocabulary (fiche 34 task 3's "tester la
+    // connexion") — a bad gateway on the far side, never this server's fault.
+    DRIVER_UNAVAILABLE: 502,
+    DRIVER_UNKNOWN: 502,
+    DRIVER_INIT_FAILED: 502,
 };
 function errorResponse(error) {
     if (isCogentaError(error)) {
@@ -73,6 +90,100 @@ function readString(body, key) {
     }
     return value;
 }
+function readOptionalString(body, key) {
+    const value = body[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function readOptionalInt(body, key) {
+    const value = body[key];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+function readOptionalBool(body, key) {
+    const value = body[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+/**
+ * Reads a field that is legitimately nullable — a threshold, a compare-at
+ * price, a dimension — and tells "absent" (leave the current value alone)
+ * from "explicitly null" (clear it) from "a real value" (set it), the same
+ * three-way distinction `CatalogStore.updateVariant` itself already needs
+ * (its own `input.x === undefined ? current.x : input.x` guards).
+ */
+function optionalField(body, key, parse) {
+    if (!(key in body))
+        return {};
+    return { [key]: parse(body[key]) };
+}
+function nullableInt(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'number' && Number.isInteger(value))
+        return value;
+    throw new CogentaError({
+        code: 'COMMERCE_QUANTITY_INVALID',
+        message: 'This field must be a whole number, or null to clear it.',
+        hint: 'Send an integer, or null.',
+    });
+}
+function nullableContentRef(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'object' &&
+        value !== null &&
+        typeof value.collection === 'string' &&
+        typeof value.entryId === 'string') {
+        const record = value;
+        return { collection: record.collection, entryId: record.entryId };
+    }
+    throw new CogentaError({
+        code: 'COMMERCE_PRODUCT_INVALID',
+        message: '"contentRef" must be { collection, entryId }, or null to unlink.',
+        hint: 'Send { "collection": "…", "entryId": "…" }, or null.',
+    });
+}
+/** A product's gallery — an array of media ids, or absent (left alone). */
+function mediaIdArray(value) {
+    if (!Array.isArray(value)) {
+        throw new CogentaError({
+            code: 'COMMERCE_PRODUCT_INVALID',
+            message: '"imageMediaIds" must be an array of media ids.',
+            hint: 'Send an array of strings, in the order the gallery should show them.',
+        });
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+/** A variant's own single photo — a media id, or `null` to clear it. */
+function nullableMediaId(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    throw new CogentaError({
+        code: 'COMMERCE_PRODUCT_INVALID',
+        message: '"imageMediaId" must be a media id, or null to clear it.',
+        hint: 'Send a media library id, or null.',
+    });
+}
+function nullableIsoString(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string' && value.trim() !== '')
+        return value;
+    throw new CogentaError({
+        code: 'COMMERCE_PRODUCT_INVALID',
+        message: 'This field must be an ISO date string, or null to clear it.',
+        hint: 'Send a date such as "2026-09-01T00:00:00.000Z", or null.',
+    });
+}
+/** A query-string integer, or `undefined` for anything that is not a positive whole number. */
+function parsePositiveInt(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+/** Same cap `@cogenta/api`'s redirect router uses for its own CSV import/export (fiche 51 task 6). */
+const MAX_CSV_ROWS = 5000;
 function readInt(body, key) {
     const value = body[key];
     if (typeof value !== 'number' || !Number.isInteger(value)) {
@@ -84,9 +195,52 @@ function readInt(body, key) {
     }
     return value;
 }
+/**
+ * Reads `body.shippingAddress` (fiche 52 task 1), if present. `undefined`
+ * means "this request said nothing about the address" (leave it alone on an
+ * update); an explicit `null` on the wire is honoured too, by returning
+ * `null` — "clear the address" — rather than being swallowed by `undefined`.
+ */
+function readShippingAddress(body) {
+    const value = body.shippingAddress;
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const address = readObject(value);
+    return {
+        line1: readString(address, 'line1'),
+        city: readString(address, 'city'),
+        postalCode: readString(address, 'postalCode'),
+        line2: readOptionalString(address, 'line2') ?? null,
+        recipient: readOptionalString(address, 'recipient') ?? null,
+        phone: readOptionalString(address, 'phone') ?? null,
+    };
+}
 export function createCommerceAdminRouter(options) {
     const basePath = (options.basePath ?? '/api/commerce').replace(/\/+$/u, '');
     const { permissions } = options;
+    /**
+     * A customer's own fiche (fiche 52 task 3): their record plus every order
+     * they placed and what they spent on it. `orders.list({ customerId })`
+     * already exists and is already permission-agnostic at the store layer, so
+     * this is aggregation, not a new query engine.
+     */
+    async function customerDetail(customer) {
+        const orders = await options.orders.list({ customerId: customer.id, limit: 500 });
+        const spendable = orders.filter((order) => order.status !== 'cancelled' && order.status !== 'refunded');
+        const totalSpentMinor = spendable.reduce((sum, order) => sum + order.totalMinor, 0);
+        const subscriptions = options.subscriptions === undefined
+            ? []
+            : (await options.subscriptions.list()).filter((subscription) => subscription.customerId === customer.id);
+        return {
+            customer,
+            orders,
+            totalSpentMinor,
+            currency: spendable[0]?.currency ?? orders[0]?.currency ?? null,
+            subscriptions,
+        };
+    }
     return {
         handle: async (request, actor = COMMERCE_ANONYMOUS) => {
             try {
@@ -98,21 +252,48 @@ export function createCommerceAdminRouter(options) {
                     .split('/')
                     .filter((segment) => segment !== '');
                 const method = request.method.toUpperCase();
+                // ---- permissions ----------------------------------------------------
+                // Read-only, and deliberately not gated behind a write permission: it
+                // describes the vocabulary and the role grants this very layer
+                // enforces (fiche 19's permission matrix), never anything that could
+                // itself move money or edit the catalogue.
+                if (segments.length === 1 && segments[0] === 'permissions') {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return {
+                            status: 200,
+                            body: { permissions: COMMERCE_PERMISSIONS, roles: permissions.roles },
+                        };
+                    }
+                }
                 // ---- products -----------------------------------------------------
                 if (segments[0] === 'products' && segments.length === 1) {
                     if (method === 'GET') {
                         permissions.assert('commerce.read', actor);
                         const query = request.query ?? {};
+                        // One row over the requested page: `hasMore` is then simply
+                        // "did the extra row show up", never a second `count(*)` query
+                        // (fiche 51 task 2 — the same technique `media-client.ts`'s
+                        // cursor pagination already uses, adapted to this offset-based
+                        // list rather than inventing a cursor for it).
+                        const requestedLimit = parsePositiveInt(query.limit) ?? 25;
+                        const offset = parsePositiveInt(query.offset) ?? 0;
+                        const sort = query.sort === 'title' || query.sort === 'handle' ? query.sort : 'createdAt';
+                        const direction = query.direction === 'asc' ? 'asc' : 'desc';
+                        const page = await options.catalog.listProducts({
+                            ...(query.status === 'active' || query.status === 'archived'
+                                ? { status: query.status }
+                                : {}),
+                            ...(query.q === undefined || query.q === '' ? {} : { search: query.q }),
+                            sort,
+                            direction,
+                            limit: requestedLimit + 1,
+                            offset,
+                        });
+                        const hasMore = page.length > requestedLimit;
                         return {
                             status: 200,
-                            body: {
-                                products: await options.catalog.listProducts({
-                                    ...(query.status === 'active' || query.status === 'archived'
-                                        ? { status: query.status }
-                                        : {}),
-                                    ...(query.q === undefined ? {} : { search: query.q }),
-                                }),
-                            },
+                            body: { products: hasMore ? page.slice(0, requestedLimit) : page, hasMore },
                         };
                     }
                     if (method === 'POST') {
@@ -123,10 +304,59 @@ export function createCommerceAdminRouter(options) {
                             body: await options.catalog.createProduct({
                                 handle: readString(body, 'handle'),
                                 title: readString(body, 'title'),
+                                ...optionalField(body, 'imageMediaIds', mediaIdArray),
                             }),
                         };
                     }
                 }
+                // The catalogue's CSV export (fiche 51 task 6) — checked ahead of the
+                // generic `/products/:id` route below, the same way `export`/`import`
+                // are ordered ahead of `:id` on `@cogenta/api`'s redirect router.
+                if (segments[0] === 'products' && segments[1] === 'export' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        const products = await options.catalog.listProducts({ limit: MAX_CSV_ROWS });
+                        const variantsByProduct = new Map(await Promise.all(products.map(async (product) => [product.id, await options.catalog.listVariants(product.id)])));
+                        return {
+                            status: 200,
+                            body: {
+                                csv: exportProductsCsv(products, variantsByProduct),
+                                filename: 'products.csv',
+                            },
+                        };
+                    }
+                }
+                if (segments[0] === 'products' && segments[1] === 'import' && segments.length === 2) {
+                    if (method === 'POST') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const csv = readString(body, 'csv');
+                        const apply = body.apply === true;
+                        return {
+                            status: 200,
+                            body: apply
+                                ? await applyProductsImport(csv, options.catalog, MAX_CSV_ROWS)
+                                : await previewProductsImport(csv, options.catalog, MAX_CSV_ROWS),
+                        };
+                    }
+                }
+                // The reverse of `contentRef` — what the content editor's own
+                // cross-link (fiche 51 task 1) asks to find "is there a commercial
+                // record for the entry I am looking at right now".
+                if (segments[0] === 'products' && segments[1] === 'by-content' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        const collection = request.query?.collection;
+                        const entryId = request.query?.entryId;
+                        if (collection === undefined || entryId === undefined) {
+                            return { status: 200, body: { product: null } };
+                        }
+                        return {
+                            status: 200,
+                            body: { product: await options.catalog.readProductByContentRef(collection, entryId) },
+                        };
+                    }
+                }
                 if (segments[0] === 'products' && segments.length === 2) {
                     const id = segments[1] ?? '';
                     if (method === 'GET') {
@@ -136,7 +366,11 @@ export function createCommerceAdminRouter(options) {
                             return notFound('product');
                         return {
                             status: 200,
-                            body: { product, variants: await options.catalog.listVariants(id) },
+                            body: {
+                                product,
+                                variants: await options.catalog.listVariants(id),
+                                terms: await options.catalog.listProductTerms(id),
+                            },
                         };
                     }
                     if (method === 'PATCH') {
@@ -150,6 +384,11 @@ export function createCommerceAdminRouter(options) {
                                 ...(body.status === 'active' || body.status === 'archived'
                                     ? { status: body.status }
                                     : {}),
+                                // Fiche 51 task 1: `null` unlinks, an object links, absence
+                                // leaves it alone — the same three-way distinction the
+                                // nullable variant fields above already need.
+                                ...optionalField(body, 'contentRef', nullableContentRef),
+                                ...optionalField(body, 'imageMediaIds', mediaIdArray),
                             }),
                         };
                     }
@@ -159,7 +398,48 @@ export function createCommerceAdminRouter(options) {
                         return { status: 204, body: null };
                     }
                 }
+                // A product's classification against a taxonomy the site declares
+                // (fiche 51 task 3, ADR-0022). Governed by `commerce.catalog.write`
+                // — the same permission as every other catalogue edit — rather than
+                // contract A's `canTerm`: categorising a product is catalogue work,
+                // and reusing contract A's term permission here would couple this
+                // router to a second, unrelated permission layer for one field.
+                if (segments[0] === 'products' && segments[2] === 'terms' && segments.length === 3) {
+                    if (method === 'PUT') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const taxonomy = readString(body, 'taxonomy');
+                        const termIds = Array.isArray(body.termIds)
+                            ? body.termIds.filter((value) => typeof value === 'string')
+                            : [];
+                        return {
+                            status: 200,
+                            body: {
+                                terms: await options.catalog.setProductTerms(segments[1] ?? '', taxonomy, termIds),
+                            },
+                        };
+                    }
+                }
                 // ---- variants -----------------------------------------------------
+                // Checked ahead of the generic `/variants/:id` route below, the same
+                // ordering discipline as `products/export` above.
+                if (segments[0] === 'variants' && segments[1] === 'low-stock' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return { status: 200, body: { variants: await options.catalog.listLowStock() } };
+                    }
+                }
+                if (segments[0] === 'variants' &&
+                    segments[2] === 'stock-movements' &&
+                    segments.length === 3) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return {
+                            status: 200,
+                            body: { movements: await options.catalog.listStockMovements(segments[1] ?? '') },
+                        };
+                    }
+                }
                 if (segments[0] === 'products' && segments[2] === 'variants' && segments.length === 3) {
                     if (method === 'POST') {
                         permissions.assert('commerce.catalog.write', actor);
@@ -173,6 +453,19 @@ export function createCommerceAdminRouter(options) {
                                 priceMinor: readInt(body, 'priceMinor'),
                                 currency: readString(body, 'currency'),
                                 ...(typeof body.onHand === 'number' ? { onHand: body.onHand } : {}),
+                                ...(typeof body.allowBackorder === 'boolean'
+                                    ? { allowBackorder: body.allowBackorder }
+                                    : {}),
+                                ...(typeof body.weightGrams === 'number' ? { weightGrams: body.weightGrams } : {}),
+                                ...(typeof body.taxCategory === 'string' ? { taxCategory: body.taxCategory } : {}),
+                                ...optionalField(body, 'lowStockThreshold', nullableInt),
+                                ...optionalField(body, 'compareAtPriceMinor', nullableInt),
+                                ...optionalField(body, 'saleStartsAt', nullableIsoString),
+                                ...optionalField(body, 'saleEndsAt', nullableIsoString),
+                                ...optionalField(body, 'widthMm', nullableInt),
+                                ...optionalField(body, 'heightMm', nullableInt),
+                                ...optionalField(body, 'depthMm', nullableInt),
+                                ...optionalField(body, 'imageMediaId', nullableMediaId),
                             }),
                         };
                     }
@@ -191,6 +484,17 @@ export function createCommerceAdminRouter(options) {
                                 ...(typeof body.allowBackorder === 'boolean'
                                     ? { allowBackorder: body.allowBackorder }
                                     : {}),
+                                ...(typeof body.weightGrams === 'number' ? { weightGrams: body.weightGrams } : {}),
+                                ...(typeof body.taxCategory === 'string' ? { taxCategory: body.taxCategory } : {}),
+                                ...(typeof body.position === 'number' ? { position: body.position } : {}),
+                                ...optionalField(body, 'lowStockThreshold', nullableInt),
+                                ...optionalField(body, 'compareAtPriceMinor', nullableInt),
+                                ...optionalField(body, 'saleStartsAt', nullableIsoString),
+                                ...optionalField(body, 'saleEndsAt', nullableIsoString),
+                                ...optionalField(body, 'widthMm', nullableInt),
+                                ...optionalField(body, 'heightMm', nullableInt),
+                                ...optionalField(body, 'depthMm', nullableInt),
+                                ...optionalField(body, 'imageMediaId', nullableMediaId),
                             }),
                         };
                     }
@@ -214,18 +518,95 @@ export function createCommerceAdminRouter(options) {
                     }
                 }
                 // ---- orders -------------------------------------------------------
+                // Checked before the generic list/detail routes below, since both
+                // share the `orders`/length-1 or length-2 shape: an accounting CSV
+                // export (fiche 52 task 7) is not an order whose id happens to be
+                // "export.csv".
+                if (segments[0] === 'orders' && segments[1] === 'export.csv' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        const query = request.query ?? {};
+                        const status = query.status;
+                        const q = query.q;
+                        const orders = await options.orders.list({
+                            ...(ORDER_STATUSES.includes(status ?? '')
+                                ? { status: status }
+                                : {}),
+                            // Audit T-COM-03: `q` already narrows `GET /orders` (the list
+                            // route above) by reference/e-mail — the export ignored it
+                            // entirely, so a search that found three orders on screen
+                            // still exported all of them.
+                            ...(q === undefined || q === '' ? {} : { search: q }),
+                            ...(query.from === undefined ? {} : { placedFrom: query.from }),
+                            ...(query.to === undefined ? {} : { placedTo: query.to }),
+                            limit: 5000,
+                        });
+                        const rows = [];
+                        for (const order of orders) {
+                            const invoice = await options.invoices?.readByOrder(order.id);
+                            rows.push({ order, invoiceNumber: invoice?.number ?? null });
+                        }
+                        return { status: 200, body: ordersToCsv(rows) };
+                    }
+                }
                 if (segments[0] === 'orders' && segments.length === 1 && method === 'GET') {
                     permissions.assert('commerce.read', actor);
-                    const status = request.query?.status;
+                    const query = request.query ?? {};
+                    const status = query.status;
+                    const q = query.q;
                     return {
                         status: 200,
                         body: {
-                            orders: await options.orders.list(ORDER_STATUSES.includes(status ?? '')
-                                ? { status: status }
-                                : {}),
+                            orders: await options.orders.list({
+                                ...(ORDER_STATUSES.includes(status ?? '')
+                                    ? { status: status }
+                                    : {}),
+                                ...(q === undefined || q === '' ? {} : { search: q }),
+                                // Advanced filters (fiche 52 task 7): an inclusive placed-at
+                                // date range, on top of the status/search this route already had.
+                                ...(query.from === undefined ? {} : { placedFrom: query.from }),
+                                ...(query.to === undefined ? {} : { placedTo: query.to }),
+                            }),
                         },
                     };
                 }
+                // A shopkeeper-entered order (fiche 52 task 5) — a phone order, a
+                // trade-show sale, or a correction. `placeManual` reuses `place()`
+                // internally (see `order/store.ts`), so this route never duplicates
+                // stock-taking, pricing or coupon logic.
+                if (segments[0] === 'orders' && segments.length === 1 && method === 'POST') {
+                    permissions.assert('commerce.order.write', actor);
+                    const body = readObject(request.body);
+                    const rawLines = body.lines;
+                    if (!Array.isArray(rawLines) || rawLines.length === 0) {
+                        throw new CogentaError({
+                            code: 'COMMERCE_AMOUNT_INVALID',
+                            message: '"lines" is required and must be a non-empty array.',
+                            hint: 'Each line needs { variantId, quantity }.',
+                        });
+                    }
+                    const lines = rawLines.map((entry) => {
+                        const line = readObject(entry);
+                        return { variantId: readString(line, 'variantId'), quantity: readInt(line, 'quantity') };
+                    });
+                    const customerName = readOptionalString(body, 'customerName');
+                    const shippingAddress = readShippingAddress(body);
+                    const outcome = await options.orders.placeManual({
+                        email: readString(body, 'email'),
+                        currency: readString(body, 'currency'),
+                        lines,
+                        actorId: actor.id,
+                        ...(customerName === undefined ? {} : { customerName }),
+                        ...(shippingAddress === undefined ? {} : { shippingAddress }),
+                    });
+                    if (outcome.kind === 'placed') {
+                        if (options.orderEmails !== undefined) {
+                            await options.orderEmails.enqueue(outcome.order.id, 'confirmation');
+                        }
+                        return { status: 201, body: outcome };
+                    }
+                    return { status: 200, body: outcome };
+                }
                 if (segments[0] === 'orders' && segments.length === 2 && method === 'GET') {
                     permissions.assert('commerce.read', actor);
                     const order = await options.orders.read(segments[1] ?? '');
@@ -240,6 +621,22 @@ export function createCommerceAdminRouter(options) {
                         },
                     };
                 }
+                // Corrects the e-mail/address before payment (fiche 52 task 5,
+                // "modification pré-paiement") — locked by `OrderStore.update` once
+                // the order is no longer `pending`.
+                if (segments[0] === 'orders' && segments.length === 2 && method === 'PATCH') {
+                    permissions.assert('commerce.order.write', actor);
+                    const body = readObject(request.body);
+                    const email = readOptionalString(body, 'email');
+                    const shippingAddress = readShippingAddress(body);
+                    return {
+                        status: 200,
+                        body: await options.orders.update(segments[1] ?? '', {
+                            ...(email === undefined ? {} : { email }),
+                            ...(shippingAddress === undefined ? {} : { shippingAddress }),
+                        }, { actorId: actor.id }),
+                    };
+                }
                 if (segments[0] === 'orders' && segments[2] === 'status' && segments.length === 3) {
                     if (method === 'PUT') {
                         permissions.assert('commerce.order.write', actor);
@@ -252,12 +649,52 @@ export function createCommerceAdminRouter(options) {
                                 hint: `Use one of: ${ORDER_STATUSES.join(', ')}.`,
                             });
                         }
+                        const updated = await options.orders.transition(segments[1] ?? '', to, {
+                            actorId: actor.id,
+                            ...(typeof body.note === 'string' ? { note: body.note } : {}),
+                        });
+                        return { status: 200, body: updated };
+                    }
+                }
+                // Shipment tracking (fiche 52 task 4). Setting it on a paid order
+                // also moves the order to `shipped` (see `OrderStore.setTracking`),
+                // which is what fires the shipment e-mail below.
+                if (segments[0] === 'orders' && segments[2] === 'tracking' && segments.length === 3) {
+                    if (method === 'PUT') {
+                        permissions.assert('commerce.order.write', actor);
+                        const body = readObject(request.body);
+                        const url = readOptionalString(body, 'url');
+                        const before = await options.orders.read(segments[1] ?? '');
+                        const updated = await options.orders.setTracking(segments[1] ?? '', {
+                            carrier: readString(body, 'carrier'),
+                            number: readString(body, 'number'),
+                            ...(url === undefined ? {} : { url }),
+                        }, { actorId: actor.id });
+                        if (before?.status === 'paid' && updated.status === 'shipped' && options.orderEmails) {
+                            await options.orderEmails.enqueue(updated.id, 'shipment');
+                        }
+                        return { status: 200, body: updated };
+                    }
+                }
+                if (segments[0] === 'orders' && segments[2] === 'emails' && segments.length === 3) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        if (options.orderEmails === undefined)
+                            return { status: 200, body: { emails: [] } };
                         return {
                             status: 200,
-                            body: await options.orders.transition(segments[1] ?? '', to, {
-                                actorId: actor.id,
-                                ...(typeof body.note === 'string' ? { note: body.note } : {}),
-                            }),
+                            body: { emails: await options.orderEmails.listForOrder(segments[1] ?? '') },
+                        };
+                    }
+                }
+                if (segments[0] === 'orders' && segments[2] === 'credit-notes' && segments.length === 3) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        if (options.creditNotes === undefined)
+                            return { status: 200, body: { creditNotes: [] } };
+                        return {
+                            status: 200,
+                            body: { creditNotes: await options.creditNotes.listForOrder(segments[1] ?? '') },
                         };
                     }
                 }
@@ -282,12 +719,35 @@ export function createCommerceAdminRouter(options) {
                     if (method === 'POST') {
                         permissions.assert('commerce.order.refund', actor);
                         const body = readObject(request.body);
+                        // "Motif obligatoire" (fiche 52 task 6) — a real reason, not an
+                        // optional courtesy, for money leaving the business.
+                        const reason = readString(body, 'reason');
+                        const refund = await options.payments.refund(segments[1] ?? '', readInt(body, 'amountMinor'), { actorId: actor.id, reason });
+                        // A credit note per refund, automatically — the same gate as
+                        // invoicing (billing configured), since a credit note without a
+                        // seller address is not a usable accounting document either.
+                        const creditNote = options.creditNotes === undefined
+                            ? null
+                            : await options.creditNotes.issue({
+                                orderId: refund.orderId,
+                                refundId: refund.id,
+                                amountMinor: refund.amountMinor,
+                                reason,
+                                actorId: actor.id,
+                            });
+                        return { status: 200, body: { refund, creditNote } };
+                    }
+                }
+                // So the screen can show what is left to refund (fiche 52 task 6) —
+                // reads the exact list `PaymentStore.refund`'s own over-refund guard
+                // sums, never a second computation of "how much was already
+                // refunded".
+                if (segments[0] === 'payments' && segments[2] === 'refunds' && segments.length === 3) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
                         return {
                             status: 200,
-                            body: await options.payments.refund(segments[1] ?? '', readInt(body, 'amountMinor'), {
-                                actorId: actor.id,
-                                ...(typeof body.reason === 'string' ? { reason: body.reason } : {}),
-                            }),
+                            body: { refunds: await options.payments.listRefunds(segments[1] ?? '') },
                         };
                     }
                 }
@@ -303,6 +763,40 @@ export function createCommerceAdminRouter(options) {
                         },
                     };
                 }
+                // A customer's own fiche (fiche 52 task 3): the record plus its
+                // orders and spend, aggregated here rather than inside
+                // `CustomerStore` — `CustomerStore` knows nothing about orders, and
+                // it should stay that way (a customer without a single sale is still
+                // a valid customer record).
+                if (segments[0] === 'customers' && segments.length === 2 && method === 'GET') {
+                    permissions.assert('commerce.read', actor);
+                    const customer = await options.customers.read(segments[1] ?? '');
+                    if (customer === null)
+                        return notFound('customer');
+                    return { status: 200, body: await customerDetail(customer) };
+                }
+                // GDPR export (fiche 52 task 3) — the same read permission as the
+                // rest of the back office already exposes this data through, bundled
+                // into one downloadable record rather than requiring several calls.
+                if (segments[0] === 'customers' && segments[2] === 'export' && segments.length === 3) {
+                    if (method === 'POST' || method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        const customer = await options.customers.read(segments[1] ?? '');
+                        if (customer === null)
+                            return notFound('customer');
+                        return { status: 200, body: await customerDetail(customer) };
+                    }
+                }
+                // GDPR erasure of the customer record (fiche 52 task 3) — see
+                // `CustomerStore.anonymize`'s own comment on why orders themselves
+                // are left untouched. Gated behind the same permission as any other
+                // action on a customer's order data.
+                if (segments[0] === 'customers' && segments[2] === 'anonymize' && segments.length === 3) {
+                    if (method === 'POST') {
+                        permissions.assert('commerce.order.write', actor);
+                        return { status: 200, body: await options.customers.anonymize(segments[1] ?? '') };
+                    }
+                }
                 // ---- invoices -----------------------------------------------------
                 // The PDF, checked before the metadata route below since both start
                 // with the same three segments. Its body is the raw bytes, not JSON —
@@ -323,6 +817,23 @@ export function createCommerceAdminRouter(options) {
                         return { status: 200, body: await options.invoices.pdf(invoice.id) };
                     }
                 }
+                // A real preview PDF for an order that may never be invoiced (fiche
+                // 54 task 2) — same shape and same `application/pdf` handling as the
+                // route above, checked first for the same reason: both start with
+                // the same three segments. `commerce.read`, not
+                // `commerce.invoice.issue`, because nothing here claims a number or
+                // writes a row (see `InvoiceStore.preview`'s own comment).
+                if (segments[0] === 'orders' &&
+                    segments[2] === 'invoice' &&
+                    segments[3] === 'preview' &&
+                    segments.length === 4) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        if (options.invoices === undefined)
+                            return notFound('invoice');
+                        return { status: 200, body: await options.invoices.preview(segments[1] ?? '') };
+                    }
+                }
                 if (segments[0] === 'orders' && segments[2] === 'invoice' && segments.length === 3) {
                     if (method === 'GET') {
                         permissions.assert('commerce.read', actor);
@@ -385,10 +896,26 @@ export function createCommerceAdminRouter(options) {
                                 ...(typeof body.maxRedemptions === 'number'
                                     ? { maxRedemptions: body.maxRedemptions }
                                     : {}),
+                                ...(typeof body.maxRedemptionsPerCustomer === 'number'
+                                    ? { maxRedemptionsPerCustomer: body.maxRedemptionsPerCustomer }
+                                    : {}),
+                                ...(Array.isArray(body.restrictedProductIds)
+                                    ? {
+                                        restrictedProductIds: body.restrictedProductIds.filter((id) => typeof id === 'string'),
+                                    }
+                                    : {}),
                             }),
                         };
                     }
                 }
+                // Read before the generic /coupons/{code}/deactivate route below —
+                // "metrics" is not a coupon code, but the two paths share a shape.
+                if (segments[0] === 'coupons' && segments[1] === 'metrics' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return { status: 200, body: await options.coupons.metrics() };
+                    }
+                }
                 if (segments[0] === 'coupons' && segments[2] === 'deactivate' && segments.length === 3) {
                     if (method === 'POST') {
                         permissions.assert('commerce.catalog.write', actor);
@@ -415,13 +942,63 @@ export function createCommerceAdminRouter(options) {
                         return {
                             status: 200,
                             body: {
-                                subscriptions: await options.subscriptions.list(status === 'active' || status === 'paused' || status === 'cancelled'
-                                    ? { status }
+                                subscriptions: await options.subscriptions.list(SUBSCRIPTION_STATUSES.includes(status ?? '')
+                                    ? { status: status }
                                     : {}),
                             },
                         };
                     }
                 }
+                // Read before the generic /subscriptions/{id} route below — "metrics"
+                // is not a subscription id, but the two paths share a shape.
+                if (segments[0] === 'subscriptions' && segments[1] === 'metrics' && segments.length === 2) {
+                    if (options.subscriptions === undefined) {
+                        return {
+                            status: 404,
+                            body: {
+                                error: {
+                                    code: 'COMMERCE_SUBSCRIPTION_NOT_FOUND',
+                                    message: 'Subscriptions are not configured on this site.',
+                                },
+                            },
+                        };
+                    }
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return { status: 200, body: await options.subscriptions.metrics() };
+                    }
+                }
+                // A subscription's own billing history (`cycles`) and open dunning
+                // cycle, if any — fiche 53 tasks 1 and 3: pause/resume/cancel were
+                // already routed below, but nothing surfaced either of these.
+                if (segments[0] === 'subscriptions' && segments.length === 2) {
+                    if (options.subscriptions === undefined) {
+                        return {
+                            status: 404,
+                            body: {
+                                error: {
+                                    code: 'COMMERCE_SUBSCRIPTION_NOT_FOUND',
+                                    message: 'Subscriptions are not configured on this site.',
+                                },
+                            },
+                        };
+                    }
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        const id = segments[1] ?? '';
+                        const subscription = await options.subscriptions.read(id);
+                        if (subscription === null)
+                            return notFound('subscription');
+                        return {
+                            status: 200,
+                            body: {
+                                subscription,
+                                cycles: await options.subscriptions.cycles(id),
+                                dunning: await options.subscriptions.dunning(id),
+                            },
+                        };
+                    }
+                }
                 if (segments[0] === 'subscriptions' &&
                     segments.length === 3 &&
                     (segments[2] === 'pause' || segments[2] === 'resume' || segments[2] === 'cancel')) {
@@ -449,6 +1026,345 @@ export function createCommerceAdminRouter(options) {
                         return { status: 200, body: updated };
                     }
                 }
+                if (segments[0] === 'subscriptions' &&
+                    segments[2] === 'change-plan' &&
+                    segments.length === 3) {
+                    if (options.subscriptions === undefined) {
+                        return {
+                            status: 404,
+                            body: {
+                                error: {
+                                    code: 'COMMERCE_SUBSCRIPTION_NOT_FOUND',
+                                    message: 'Subscriptions are not configured on this site.',
+                                },
+                            },
+                        };
+                    }
+                    if (method === 'POST') {
+                        permissions.assert('commerce.order.write', actor);
+                        const body = readObject(request.body);
+                        const quantity = readOptionalInt(body, 'quantity');
+                        const prorate = readOptionalBool(body, 'prorate');
+                        return {
+                            status: 200,
+                            body: await options.subscriptions.changePlan(segments[1] ?? '', readString(body, 'variantId'), {
+                                ...(quantity === undefined ? {} : { quantity }),
+                                ...(prorate === undefined ? {} : { prorate }),
+                            }),
+                        };
+                    }
+                }
+                // ---- tax (fiche 34 task 1) ------------------------------------------
+                if (segments[0] === 'tax' && segments[1] === 'rules' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return { status: 200, body: { rules: await options.tax.listRules() } };
+                    }
+                    if (method === 'POST') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const taxCategory = readOptionalString(body, 'taxCategory');
+                        const includedInPrice = readOptionalBool(body, 'includedInPrice');
+                        const priority = readOptionalInt(body, 'priority');
+                        const active = readOptionalBool(body, 'active');
+                        return {
+                            status: 201,
+                            body: await options.tax.createRule({
+                                name: readString(body, 'name'),
+                                rateBp: readInt(body, 'rateBp'),
+                                country: readOptionalString(body, 'country') ?? null,
+                                region: readOptionalString(body, 'region') ?? null,
+                                ...(taxCategory === undefined ? {} : { taxCategory }),
+                                ...(includedInPrice === undefined ? {} : { includedInPrice }),
+                                ...(priority === undefined ? {} : { priority }),
+                                ...(active === undefined ? {} : { active }),
+                            }),
+                        };
+                    }
+                }
+                if (segments[0] === 'tax' && segments[1] === 'rules' && segments.length === 3) {
+                    if (method === 'PATCH') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const country = readOptionalString(body, 'country');
+                        const region = readOptionalString(body, 'region');
+                        const taxCategory = readOptionalString(body, 'taxCategory');
+                        const name = readOptionalString(body, 'name');
+                        const rateBp = readOptionalInt(body, 'rateBp');
+                        const includedInPrice = readOptionalBool(body, 'includedInPrice');
+                        const priority = readOptionalInt(body, 'priority');
+                        const active = readOptionalBool(body, 'active');
+                        return {
+                            status: 200,
+                            body: await options.tax.updateRule(segments[2] ?? '', {
+                                // `readOptionalString`/`readOptionalBool`/`readOptionalInt`
+                                // return `undefined` for an absent key, matching this
+                                // patch's own "leave unchanged" — an explicit `null` in the
+                                // request body (to clear country/region) is read directly
+                                // below rather than through those helpers, which cannot
+                                // tell "absent" and "null" apart.
+                                ...(country === undefined
+                                    ? body.country === null
+                                        ? { country: null }
+                                        : {}
+                                    : { country }),
+                                ...(region === undefined
+                                    ? body.region === null
+                                        ? { region: null }
+                                        : {}
+                                    : { region }),
+                                ...(taxCategory === undefined ? {} : { taxCategory }),
+                                ...(name === undefined ? {} : { name }),
+                                ...(rateBp === undefined ? {} : { rateBp }),
+                                ...(includedInPrice === undefined ? {} : { includedInPrice }),
+                                ...(priority === undefined ? {} : { priority }),
+                                ...(active === undefined ? {} : { active }),
+                            }),
+                        };
+                    }
+                    if (method === 'DELETE') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        await options.tax.deleteRule(segments[2] ?? '');
+                        return { status: 204, body: null };
+                    }
+                }
+                // A simulator that calls the exact resolver the checkout uses, never a
+                // second implementation of "which rule wins" (fiche 34 § pièges) — the
+                // whole point is that the screen can never show a different answer
+                // than the one an order actually gets.
+                if (segments[0] === 'tax' && segments[1] === 'simulate' && segments.length === 2) {
+                    if (method === 'POST') {
+                        permissions.assert('commerce.read', actor);
+                        const body = readObject(request.body);
+                        const country = readOptionalString(body, 'country');
+                        const zone = country === undefined
+                            ? null
+                            : { country, region: readOptionalString(body, 'region') ?? null };
+                        const rule = await options.tax.resolve(zone, readOptionalString(body, 'taxCategory') ?? 'standard');
+                        const outcome = taxFor(readInt(body, 'amountMinor'), rule);
+                        return { status: 200, body: { rule, outcome } };
+                    }
+                }
+                // ---- shipping (fiche 34 task 2) --------------------------------------
+                if (segments[0] === 'shipping' && segments[1] === 'methods' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        return { status: 200, body: { methods: await options.shipping.listMethods() } };
+                    }
+                    if (method === 'POST') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const kind = readOptionalString(body, 'kind');
+                        if (kind !== undefined && !SHIPPING_KINDS.includes(kind)) {
+                            throw new CogentaError({
+                                code: 'COMMERCE_SHIPPING_METHOD_UNKNOWN',
+                                message: `"${kind}" is not a shipping kind.`,
+                                hint: `Use one of: ${SHIPPING_KINDS.join(', ')}.`,
+                            });
+                        }
+                        const amountMinor = readOptionalInt(body, 'amountMinor');
+                        const perKgMinor = readOptionalInt(body, 'perKgMinor');
+                        const position = readOptionalInt(body, 'position');
+                        const active = readOptionalBool(body, 'active');
+                        return {
+                            status: 201,
+                            body: await options.shipping.createMethod({
+                                label: readString(body, 'label'),
+                                currency: readString(body, 'currency'),
+                                ...(kind === undefined ? {} : { kind: kind }),
+                                country: readOptionalString(body, 'country') ?? null,
+                                region: readOptionalString(body, 'region') ?? null,
+                                ...(amountMinor === undefined ? {} : { amountMinor }),
+                                ...(perKgMinor === undefined ? {} : { perKgMinor }),
+                                freeOverMinor: readOptionalInt(body, 'freeOverMinor') ?? null,
+                                carrier: readOptionalString(body, 'carrier') ?? null,
+                                ...(position === undefined ? {} : { position }),
+                                ...(active === undefined ? {} : { active }),
+                            }),
+                        };
+                    }
+                }
+                if (segments[0] === 'shipping' && segments[1] === 'methods' && segments.length === 3) {
+                    if (method === 'PATCH') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        const body = readObject(request.body);
+                        const label = readOptionalString(body, 'label');
+                        const country = readOptionalString(body, 'country');
+                        const region = readOptionalString(body, 'region');
+                        const kind = readOptionalString(body, 'kind');
+                        if (kind !== undefined && !SHIPPING_KINDS.includes(kind)) {
+                            throw new CogentaError({
+                                code: 'COMMERCE_SHIPPING_METHOD_UNKNOWN',
+                                message: `"${kind}" is not a shipping kind.`,
+                                hint: `Use one of: ${SHIPPING_KINDS.join(', ')}.`,
+                            });
+                        }
+                        const currency = readOptionalString(body, 'currency');
+                        const amountMinor = readOptionalInt(body, 'amountMinor');
+                        const perKgMinor = readOptionalInt(body, 'perKgMinor');
+                        const freeOverMinor = readOptionalInt(body, 'freeOverMinor');
+                        const carrier = readOptionalString(body, 'carrier');
+                        const position = readOptionalInt(body, 'position');
+                        const active = readOptionalBool(body, 'active');
+                        return {
+                            status: 200,
+                            body: await options.shipping.updateMethod(segments[2] ?? '', {
+                                ...(label === undefined ? {} : { label }),
+                                ...(country === undefined
+                                    ? body.country === null
+                                        ? { country: null }
+                                        : {}
+                                    : { country }),
+                                ...(region === undefined
+                                    ? body.region === null
+                                        ? { region: null }
+                                        : {}
+                                    : { region }),
+                                ...(kind === undefined ? {} : { kind: kind }),
+                                ...(currency === undefined ? {} : { currency }),
+                                ...(amountMinor === undefined ? {} : { amountMinor }),
+                                ...(perKgMinor === undefined ? {} : { perKgMinor }),
+                                ...(freeOverMinor === undefined
+                                    ? body.freeOverMinor === null
+                                        ? { freeOverMinor: null }
+                                        : {}
+                                    : { freeOverMinor }),
+                                ...(carrier === undefined
+                                    ? body.carrier === null
+                                        ? { carrier: null }
+                                        : {}
+                                    : { carrier }),
+                                ...(position === undefined ? {} : { position }),
+                                ...(active === undefined ? {} : { active }),
+                            }),
+                        };
+                    }
+                    if (method === 'DELETE') {
+                        permissions.assert('commerce.catalog.write', actor);
+                        await options.shipping.deleteMethod(segments[2] ?? '');
+                        return { status: 204, body: null };
+                    }
+                }
+                // Same discipline as the tax simulator: calls `available()`, the exact
+                // function checkout uses to price and offer methods, never a
+                // reimplementation. A method naming a carrier always reports it, so
+                // the screen can say "carrier rate, falls back to the stored rate if
+                // the courier's API does not answer" without guessing at runtime
+                // whether the fallback fired for *this* simulated shipment.
+                if (segments[0] === 'shipping' && segments[1] === 'simulate' && segments.length === 2) {
+                    if (method === 'POST') {
+                        permissions.assert('commerce.read', actor);
+                        const body = readObject(request.body);
+                        const country = readOptionalString(body, 'country');
+                        const zone = country === undefined
+                            ? null
+                            : { country, region: readOptionalString(body, 'region') ?? null };
+                        const basis = {
+                            weightGrams: readOptionalInt(body, 'weightGrams') ?? 0,
+                            subtotalMinor: readOptionalInt(body, 'subtotalMinor') ?? 0,
+                            currency: readString(body, 'currency'),
+                        };
+                        return { status: 200, body: { quotes: await options.shipping.available(zone, basis) } };
+                    }
+                }
+                // ---- payment (fiche 34 task 3) ---------------------------------------
+                // Presence and health only, never a key's value (fiche 34 § pièges:
+                // "un écran de paiement est une fuite de clé en puissance").
+                if (segments[0] === 'payment' && segments[1] === 'drivers' && segments.length === 2) {
+                    if (method === 'GET') {
+                        permissions.assert('commerce.read', actor);
+                        if (options.payment === undefined) {
+                            return { status: 200, body: { drivers: [], testMode: true, webhookUrl: null } };
+                        }
+                        const { registry, config } = options.payment;
+                        const drivers = await Promise.all(registry.list().map(async (driver) => ({
+                            name: driver.name,
+                            tier: driver.tier,
+                            settlesOffline: driver.name === 'manual',
+                            // "Configured" never means "reachable" — a key can be present
+                            // and wrong. `available()` is the same probe the registry uses
+                            // to choose a driver at startup, called again here on demand.
+                            configured: await driver.available(config).catch(() => false),
+                            selected: (config.driver ?? 'auto') === 'auto' ? undefined : config.driver === driver.name,
+                        })));
+                        return {
+                            status: 200,
+                            body: {
+                                drivers,
+                                testMode: options.payment.testMode,
+                                webhookUrl: options.payment.webhookUrl,
+                            },
+                        };
+                    }
+                }
+                // "Bouton tester la connexion" — actually calls the driver, and
+                // returns whatever it says, error included, rather than a boolean.
+                // fiche feedback: this used to gate on `commerce.read` — meaning any
+                // signed-in `viewer` could trigger a real `driver.init()`/`health()`
+                // probe against the site's live payment credentials. No key value
+                // ever leaks (the response is only `ok`/`message`), but *probing* a
+                // payment gateway on demand is a money-adjacent action, not a read;
+                // `commerce.payment.settle` is the closest of the six permissions
+                // (deliberately coarse, see permissions.ts) that already gates
+                // money-touching operations, so it's reused here rather than adding
+                // a seventh permission for one button.
+                if (segments[0] === 'payment' &&
+                    segments[1] === 'drivers' &&
+                    segments[3] === 'test-connection' &&
+                    segments.length === 4) {
+                    if (method === 'POST') {
+                        permissions.assert('commerce.payment.settle', actor);
+                        if (options.payment === undefined) {
+                            throw new CogentaError({
+                                code: 'COMMERCE_PAYMENT_UNSUPPORTED',
+                                message: 'Payment is not configured on this site.',
+                                hint: 'Pass a `payment` option to createCommerceAdminRouter.',
+                            });
+                        }
+                        const name = segments[2] ?? '';
+                        const driver = options.payment.registry.list().find((entry) => entry.name === name);
+                        if (driver === undefined) {
+                            throw new CogentaError({
+                                code: 'DRIVER_UNKNOWN',
+                                message: `No payment driver named "${name}".`,
+                                hint: `Available: ${options.payment.registry
+                                    .list()
+                                    .map((entry) => entry.name)
+                                    .join(', ')}.`,
+                            });
+                        }
+                        const reachable = await driver.available(options.payment.config);
+                        if (!reachable) {
+                            return {
+                                status: 200,
+                                body: {
+                                    ok: false,
+                                    message: `${name} is not reachable with the credentials configured on this server.`,
+                                },
+                            };
+                        }
+                        try {
+                            // `health()` reports on whatever `init()` last set up — see
+                            // `stripePaymentDriver`'s own comment — so the two are always
+                            // called back to back, never `health()` alone.
+                            await driver.init(options.payment.config);
+                            const health = await driver.health();
+                            return {
+                                status: 200,
+                                body: { ok: health.status === 'ok', message: health.message ?? null },
+                            };
+                        }
+                        catch (error) {
+                            return {
+                                status: 200,
+                                body: {
+                                    ok: false,
+                                    message: error instanceof Error ? error.message : String(error),
+                                },
+                            };
+                        }
+                    }
+                }
                 return { status: 405, body: { error: { code: 'INTERNAL', message: 'No such route.' } } };
             }
             catch (error) {
@@ -461,6 +1377,8 @@ const NOT_FOUND_CODES = {
     product: 'COMMERCE_PRODUCT_NOT_FOUND',
     order: 'COMMERCE_ORDER_NOT_FOUND',
     invoice: 'COMMERCE_INVOICE_NOT_FOUND',
+    subscription: 'COMMERCE_SUBSCRIPTION_NOT_FOUND',
+    customer: 'COMMERCE_CUSTOMER_NOT_FOUND',
 };
 function notFound(what) {
     return {