@cogenta/commerce 0.2.0 → 0.4.3

package/dist/order/notify.d.ts

@@ -0,0 +1,65 @@
+import { type EmailTransport, type ReportChannelMessage } from '@cogenta/channels';
+import { type DatabaseHandle } from '@cogenta/core';
+import type { OrderStore } from './store.js';
+import type { Order } from './types.js';
+/**
+ * Transactional order e-mail (fiche 52 task 2): "réutiliser l'adaptateur
+ * e-mail existant de `@cogenta/channels`... modèles éditables, file avec
+ * reprise, journal visible sur la commande."
+ *
+ * Reused, never reinvented — the same discipline `@cogenta/forms`'s
+ * `notify.ts` already applies: this file builds `ReportChannelMessage`s and
+ * hands them to `createEmailAdapter`; it never writes its own MIME or
+ * subject/body HTML. `ReportChannelMessage` (not `AlertChannelMessage`) is
+ * the fit: a real subject line and structured key figures for a customer
+ * reading their own order, not an operator's "action attendue" framing.
+ *
+ * A confirmation and a shipment notice are the two kinds this fiche's
+ * acceptance criteria name ("commande → confirmation e-mail → expédition →
+ * notification"). The queue is persisted (`cogenta_commerce_order_emails`)
+ * rather than fire-and-forget like forms' notifier, because this fiche
+ * explicitly asks for "une file avec reprise" — a transient SMTP/file-write
+ * failure must not silently lose an order confirmation.
+ */
+export declare const ORDER_EMAIL_KINDS: readonly ['confirmation', 'shipment'];
+export type OrderEmailKind = (typeof ORDER_EMAIL_KINDS)[number];
+export type OrderEmailStatus = 'pending' | 'sent' | 'failed';
+export interface OrderEmailRecord {
+    readonly id: string;
+    readonly orderId: string;
+    readonly kind: OrderEmailKind;
+    readonly toEmail: string;
+    readonly status: OrderEmailStatus;
+    readonly attempts: number;
+    readonly lastError: string | null;
+    readonly createdAt: string;
+    readonly sentAt: string | null;
+}
+export interface OrderEmailQueueDependencies {
+    readonly orders: OrderStore;
+    readonly transport: EmailTransport;
+}
+export interface OrderEmailQueue {
+    /** Queues one e-mail for the next `flushDue()`. Never sends synchronously. */
+    enqueue(orderId: string, kind: OrderEmailKind): Promise<OrderEmailRecord>;
+    listForOrder(orderId: string): Promise<readonly OrderEmailRecord[]>;
+    /**
+     * Sends every `pending` e-mail, up to `limit`. A failure is retried on the
+     * next call until `MAX_ATTEMPTS`, after which it becomes terminally
+     * `failed` — visible on `listForOrder` and, either way, noted on the
+     * order's own history (`OrderStore.record`), which is this fiche's "journal
+     * visible sur la commande".
+     */
+    flushDue(limit?: number): Promise<{
+        readonly sent: number;
+        readonly failed: number;
+    }>;
+}
+/** How many delivery attempts before an e-mail is given up on for good. */
+export declare const MAX_ATTEMPTS = 5;
+/** Exported for testability — the exact message a confirmation renders as. */
+export declare function buildConfirmationMessage(order: Order): ReportChannelMessage;
+/** Exported for testability — the exact message a shipment notice renders as. */
+export declare function buildShipmentMessage(order: Order): ReportChannelMessage;
+export declare function createOrderEmailQueue(db: DatabaseHandle, dependencies: OrderEmailQueueDependencies, now?: () => number): OrderEmailQueue;
+//# sourceMappingURL=notify.d.ts.map

package/dist/order/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/order/notify.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAgB,KAAK,cAAc,EAA0B,MAAM,eAAe,CAAA;AAIzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,YAAI,cAAc,EAAE,UAAU,CAAU,CAAA;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACzE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAA;IACnE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtF;AAED,2EAA2E;AAC3E,eAAO,MAAM,YAAY,IAAI,CAAA;AA2C7B,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,oBAAoB,CAgB3E;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,oBAAoB,CAmBvE;AAMD,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,cAAc,EAClB,YAAY,EAAE,2BAA2B,EACzC,GAAG,GAAE,MAAM,MAAiB,GAC3B,eAAe,CAgGjB"}

package/dist/order/notify.js

@@ -0,0 +1,180 @@
+import { createEmailAdapter, } from '@cogenta/channels';
+import { CogentaError, identifier, newId, sql } from '@cogenta/core';
+import { formatMoney } from '../money.js';
+import { toInt, toNullableText, toText } from '../rows.js';
+import { TABLES } from '../tables.js';
+/**
+ * Transactional order e-mail (fiche 52 task 2): "réutiliser l'adaptateur
+ * e-mail existant de `@cogenta/channels`... modèles éditables, file avec
+ * reprise, journal visible sur la commande."
+ *
+ * Reused, never reinvented — the same discipline `@cogenta/forms`'s
+ * `notify.ts` already applies: this file builds `ReportChannelMessage`s and
+ * hands them to `createEmailAdapter`; it never writes its own MIME or
+ * subject/body HTML. `ReportChannelMessage` (not `AlertChannelMessage`) is
+ * the fit: a real subject line and structured key figures for a customer
+ * reading their own order, not an operator's "action attendue" framing.
+ *
+ * A confirmation and a shipment notice are the two kinds this fiche's
+ * acceptance criteria name ("commande → confirmation e-mail → expédition →
+ * notification"). The queue is persisted (`cogenta_commerce_order_emails`)
+ * rather than fire-and-forget like forms' notifier, because this fiche
+ * explicitly asks for "une file avec reprise" — a transient SMTP/file-write
+ * failure must not silently lose an order confirmation.
+ */
+export const ORDER_EMAIL_KINDS = ['confirmation', 'shipment'];
+/** How many delivery attempts before an e-mail is given up on for good. */
+export const MAX_ATTEMPTS = 5;
+function decode(row) {
+    return {
+        id: toText(row.id, 'order_email.id'),
+        orderId: toText(row.order_id, 'order_email.order_id'),
+        kind: toText(row.kind, 'order_email.kind'),
+        toEmail: toText(row.to_email, 'order_email.to_email'),
+        status: toText(row.status, 'order_email.status'),
+        attempts: toInt(row.attempts, 'order_email.attempts'),
+        lastError: toNullableText(row.last_error),
+        createdAt: toText(row.created_at, 'order_email.created_at'),
+        sentAt: toNullableText(row.sent_at),
+    };
+}
+function money(order, amountMinor) {
+    return formatMoney({ amountMinor, currency: order.currency });
+}
+function addressLines(order) {
+    const lines = [
+        order.shippingRecipient,
+        order.shippingAddressLine1,
+        order.shippingAddressLine2,
+        [order.shippingPostalCode, order.shippingCity].filter((part) => part !== null).join(' '),
+        order.shippingCountry,
+    ].filter((line) => line !== null && line.trim() !== '');
+    return lines.length === 0 ? 'No delivery address on file.' : lines.join('\n');
+}
+/** Exported for testability — the exact message a confirmation renders as. */
+export function buildConfirmationMessage(order) {
+    return {
+        level: 'report',
+        title: `Order confirmation — ${order.reference}`,
+        keyFigures: [
+            { label: 'Reference', value: order.reference },
+            { label: 'Total', value: money(order, order.totalMinor) },
+        ],
+        sections: [
+            {
+                heading: 'Items',
+                body: order.lines.map((line) => `${line.quantity} × ${line.title}`).join('\n'),
+            },
+            { heading: 'Delivery address', body: addressLines(order) },
+        ],
+    };
+}
+/** Exported for testability — the exact message a shipment notice renders as. */
+export function buildShipmentMessage(order) {
+    return {
+        level: 'report',
+        title: `Your order has shipped — ${order.reference}`,
+        keyFigures: [
+            { label: 'Reference', value: order.reference },
+            { label: 'Carrier', value: order.trackingCarrier ?? 'Unspecified' },
+            { label: 'Tracking number', value: order.trackingNumber ?? 'Unspecified' },
+        ],
+        sections: [
+            {
+                heading: 'Delivery address',
+                body: addressLines(order),
+            },
+            ...(order.trackingUrl === null
+                ? []
+                : [{ heading: 'Track your parcel', body: order.trackingUrl }]),
+        ],
+    };
+}
+function buildMessage(order, kind) {
+    return kind === 'confirmation' ? buildConfirmationMessage(order) : buildShipmentMessage(order);
+}
+export function createOrderEmailQueue(db, dependencies, now = Date.now) {
+    const d = db.dialect;
+    const table = identifier(TABLES.orderEmails, d);
+    const stamp = () => new Date(now()).toISOString();
+    const adapter = createEmailAdapter({ transport: dependencies.transport });
+    async function read(id) {
+        const result = await db.query(sql `select * from ${table} where id = ${id}`);
+        const row = result.rows[0];
+        return row === undefined ? null : decode(row);
+    }
+    return {
+        enqueue: async (orderId, kind) => {
+            const order = await dependencies.orders.read(orderId);
+            if (order === null) {
+                throw new CogentaError({
+                    code: 'COMMERCE_ORDER_NOT_FOUND',
+                    message: 'This order does not exist.',
+                    hint: 'Check the order reference.',
+                });
+            }
+            const id = newId(now);
+            const at = stamp();
+            await db.query(sql `
+        insert into ${table} (id, order_id, kind, to_email, status, attempts, last_error, created_at, sent_at)
+        values (${id}, ${orderId}, ${kind}, ${order.email}, ${'pending'}, ${0}, ${null}, ${at}, ${null})`);
+            const created = await read(id);
+            if (created === null) {
+                throw new CogentaError({
+                    code: 'INTERNAL',
+                    message: 'The queued e-mail was not stored.',
+                    hint: 'Check that the commerce tables exist (ensureCommerceTables).',
+                });
+            }
+            return created;
+        },
+        listForOrder: async (orderId) => {
+            const result = await db.query(sql `select * from ${table} where order_id = ${orderId} order by created_at asc`);
+            return result.rows.map(decode);
+        },
+        flushDue: async (limit = 25) => {
+            const due = await db.query(sql `select * from ${table} where status = ${'pending'} order by created_at asc limit ${limit}`);
+            let sent = 0;
+            let failed = 0;
+            for (const row of due.rows.map(decode)) {
+                const order = await dependencies.orders.read(row.orderId);
+                if (order === null) {
+                    // The order it was for is gone — nothing left to describe or notify
+                    // about. Terminal, not retried.
+                    await db.query(sql `
+            update ${table} set status = ${'failed'}, attempts = attempts + 1,
+                                last_error = ${'The order no longer exists.'}
+            where id = ${row.id}`);
+                    failed += 1;
+                    continue;
+                }
+                try {
+                    await adapter.send({ id: row.toEmail }, buildMessage(order, row.kind));
+                    await db.query(sql `
+            update ${table} set status = ${'sent'}, attempts = attempts + 1, sent_at = ${stamp()}, last_error = ${null}
+            where id = ${row.id}`);
+                    await dependencies.orders.record(order.id, 'note', {
+                        note: `${row.kind === 'confirmation' ? 'Confirmation' : 'Shipment notification'} e-mail sent to ${row.toEmail}.`,
+                    });
+                    sent += 1;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    const attempts = row.attempts + 1;
+                    const givenUp = attempts >= MAX_ATTEMPTS;
+                    await db.query(sql `
+            update ${table} set status = ${givenUp ? 'failed' : 'pending'}, attempts = ${attempts}, last_error = ${message}
+            where id = ${row.id}`);
+                    if (givenUp) {
+                        await dependencies.orders.record(order.id, 'note', {
+                            note: `${row.kind === 'confirmation' ? 'Confirmation' : 'Shipment notification'} e-mail to ${row.toEmail} failed after ${String(attempts)} attempts: ${message}`,
+                        });
+                    }
+                    failed += 1;
+                }
+            }
+            return { sent, failed };
+        },
+    };
+}
+//# sourceMappingURL=notify.js.map

package/dist/order/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/order/notify.ts"],"names":[],"mappings":"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"}

package/dist/order/store.d.ts

@@ -4,12 +4,34 @@ import type { CatalogStore } from '../catalog/store.js';
 import type { StockShortfall } from '../catalog/types.js';
 import type { CouponStore } from '../coupon/store.js';
 import type { CustomerStore } from '../customer/store.js';
-import type { Order, OrderEvent, OrderEventKind, OrderStatus } from './types.js';
+import type { Order, OrderEvent, OrderEventKind, OrderStatus, OrderTracking, ShippingAddress } from './types.js';
 export interface PlaceOrderInput {
     readonly cartId: string;
     readonly email: string;
     readonly customerName?: string | null;
     readonly actorId?: string | null;
+    /** The delivery address (fiche 52 task 1). Absent for digital-only goods. */
+    readonly shippingAddress?: ShippingAddress | null;
+}
+export interface PlaceManualOrderLineInput {
+    readonly variantId: string;
+    readonly quantity: number;
+}
+/**
+ * A manual order — one a shopkeeper types in themselves (fiche 52 task 5):
+ * a phone order, a trade-show sale, a correction for a customer who paid by
+ * some other means entirely. Deliberately **not** a second placement path:
+ * it opens a real cart, adds the real lines to it, and calls the exact same
+ * `place()` this file already has, so stock-taking, coupon redemption and
+ * pricing are never duplicated — only reused.
+ */
+export interface PlaceManualOrderInput {
+    readonly email: string;
+    readonly customerName?: string | null;
+    readonly currency: string;
+    readonly lines: readonly PlaceManualOrderLineInput[];
+    readonly shippingAddress?: ShippingAddress | null;
+    readonly actorId?: string | null;
 }
 /**
  * Placing an order either produced one, or explains exactly what stopped it.
@@ -40,6 +62,17 @@ export interface OrderStoreDependencies {
 export interface OrderListOptions {
     readonly status?: OrderStatus;
     readonly customerId?: string;
+    /**
+     * A substring of the reference or the email, folded to lower case (fiche 36
+     * task 4 — the admin's global search finds an order "by number and email").
+     * Mirrors `CustomerStore.list`'s own `search` option, the established
+     * pattern for this kind of filter in this package.
+     */
+    readonly search?: string;
+    /** Placed at or after this instant (inclusive), ISO 8601 — fiche 52 task 7. */
+    readonly placedFrom?: string;
+    /** Placed at or before this instant (inclusive), ISO 8601 — fiche 52 task 7. */
+    readonly placedTo?: string;
     readonly limit?: number;
     readonly offset?: number;
 }
@@ -55,6 +88,8 @@ export interface OrderStore {
      * sale that did not occur.
      */
     place(input: PlaceOrderInput): Promise<PlaceOrderOutcome>;
+    /** A shopkeeper-entered order (fiche 52 task 5) — see `PlaceManualOrderInput`. */
+    placeManual(input: PlaceManualOrderInput): Promise<PlaceOrderOutcome>;
     read(id: string): Promise<Order | null>;
     readByReference(reference: string): Promise<Order | null>;
     list(options?: OrderListOptions): Promise<readonly Order[]>;
@@ -69,6 +104,28 @@ export interface OrderStore {
         readonly note?: string;
         readonly actorId?: string | null;
     }, tx?: SqlExecutor): Promise<void>;
+    /**
+     * Corrects the e-mail and/or delivery address (fiche 52 task 5, "modification
+     * pré-paiement"). Only while `pending` — once an order is `paid`, whatever a
+     * courier or an invoice already refers to must not shift under it; a
+     * shopkeeper who needs to redirect a shipped parcel uses `setTracking`
+     * instead, or cancels and re-places the order.
+     */
+    update(id: string, patch: {
+        readonly email?: string;
+        readonly shippingAddress?: ShippingAddress | null;
+    }, options?: {
+        readonly actorId?: string | null;
+    }): Promise<Order>;
+    /**
+     * Records how a shipment actually went (fiche 52 task 4). Setting tracking
+     * on a `paid` order also transitions it to `shipped` — attaching a tracking
+     * number *is* what "we shipped it" means here — while a `shipped` order
+     * just gets its tracking corrected in place.
+     */
+    setTracking(id: string, tracking: OrderTracking, options?: {
+        readonly actorId?: string | null;
+    }): Promise<Order>;
 }
 export declare function referenceFrom(id: string): string;
 export declare function createOrderStore(db: DatabaseHandle, dependencies: OrderStoreDependencies, now?: () => number): OrderStore;

package/dist/order/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/order/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/order/store.ts"],"names":[],"mappings":"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"}

package/dist/order/store.js

@@ -70,6 +70,16 @@ export function createOrderStore(db, dependencies, now = Date.now) {
             shippingRegion: toNullableText(row.shipping_region),
             shippingMethodId: toNullableText(row.shipping_method_id),
             shippingMethodLabel: toNullableText(row.shipping_method_label),
+            shippingAddressLine1: toNullableText(row.shipping_address_line1),
+            shippingAddressLine2: toNullableText(row.shipping_address_line2),
+            shippingCity: toNullableText(row.shipping_city),
+            shippingPostalCode: toNullableText(row.shipping_postal_code),
+            shippingRecipient: toNullableText(row.shipping_recipient),
+            shippingPhone: toNullableText(row.shipping_phone),
+            trackingCarrier: toNullableText(row.tracking_carrier),
+            trackingNumber: toNullableText(row.tracking_number),
+            trackingUrl: toNullableText(row.tracking_url),
+            shippedAt: toNullableText(row.shipped_at),
             subscriptionId: toNullableText(row.subscription_id),
             lines: await linesOf(id, executor),
             placedAt: toText(row.placed_at, 'order.placed_at'),
@@ -99,7 +109,7 @@ export function createOrderStore(db, dependencies, now = Date.now) {
               ${fields.fromStatus ?? null}, ${fields.toStatus ?? null},
               ${fields.actorId ?? null}, ${fields.note ?? null})`);
     }
-    return {
+    const store = {
         place: async (input) => {
             const priced = await dependencies.carts.price(input.cartId);
             const { cart, totals } = priced;
@@ -118,7 +128,13 @@ export function createOrderStore(db, dependencies, now = Date.now) {
             // one is the one that decides, because a coupon can expire or be
             // exhausted between adding it and paying.
             if (cart.couponCode !== null) {
-                const check = await dependencies.coupons.check(cart.couponCode, totals.subtotalMinor, cart.currency);
+                const productIds = [];
+                for (const line of cart.lines) {
+                    const variant = await dependencies.catalog.readVariant(line.variantId);
+                    if (variant !== null)
+                        productIds.push(variant.productId);
+                }
+                const check = await dependencies.coupons.check(cart.couponCode, totals.subtotalMinor, cart.currency, { customerId: customer.id, productIds });
                 if (check.kind !== 'ok') {
                     return { kind: 'coupon_refused', reason: couponRefusal(check).message };
                 }
@@ -152,17 +168,25 @@ export function createOrderStore(db, dependencies, now = Date.now) {
                             });
                         }
                     }
+                    const address = input.shippingAddress ?? null;
                     await tx.query(sql `
               insert into ${orders} (id, reference, customer_id, email, status, currency,
                                      subtotal_minor, discount_minor, shipping_minor, tax_minor, total_minor,
                                      coupon_code, shipping_country, shipping_region,
                                      shipping_method_id, shipping_method_label,
+                                     shipping_address_line1, shipping_address_line2, shipping_city,
+                                     shipping_postal_code, shipping_recipient, shipping_phone,
+                                     tracking_carrier, tracking_number, tracking_url, shipped_at,
                                      placed_at, updated_at, subscription_id)
               values (${id}, ${reference}, ${customer.id}, ${customer.email}, ${'pending'}, ${cart.currency},
                       ${totals.subtotalMinor}, ${totals.discountMinor}, ${totals.shippingMinor},
                       ${totals.taxMinor}, ${totals.totalMinor},
                       ${cart.couponCode}, ${cart.shippingCountry}, ${cart.shippingRegion},
-                      ${cart.shippingMethodId}, ${null}, ${at}, ${at}, ${null})`);
+                      ${cart.shippingMethodId}, ${null},
+                      ${address?.line1 ?? null}, ${address?.line2 ?? null}, ${address?.city ?? null},
+                      ${address?.postalCode ?? null}, ${address?.recipient ?? null}, ${address?.phone ?? null},
+                      ${null}, ${null}, ${null}, ${null},
+                      ${at}, ${at}, ${null})`);
                     for (const [position, line] of totals.lines.entries()) {
                         await tx.query(sql `
                 insert into ${orderLines} (id, order_id, variant_id, sku, title, quantity,
@@ -198,6 +222,25 @@ export function createOrderStore(db, dependencies, now = Date.now) {
                 throw error;
             }
         },
+        placeManual: async (input) => {
+            if (input.lines.length === 0)
+                return { kind: 'empty' };
+            const customer = await dependencies.customers.ensure(input.email, input.customerName);
+            const cart = await dependencies.carts.open({
+                currency: input.currency,
+                customerId: customer.id,
+            });
+            for (const line of input.lines) {
+                await dependencies.carts.addLine(cart.id, line.variantId, line.quantity);
+            }
+            return store.place({
+                cartId: cart.id,
+                email: input.email,
+                ...(input.customerName === undefined ? {} : { customerName: input.customerName }),
+                ...(input.actorId === undefined ? {} : { actorId: input.actorId }),
+                ...(input.shippingAddress === undefined ? {} : { shippingAddress: input.shippingAddress }),
+            });
+        },
         read: async (id) => read(id),
         readByReference: async (reference) => {
             const result = await db.query(sql `select * from ${orders} where reference = ${reference.trim().toUpperCase()}`);
@@ -205,16 +248,26 @@ export function createOrderStore(db, dependencies, now = Date.now) {
             return row === undefined ? null : decode(row);
         },
         list: async (options) => {
-            let statement = sql `select * from ${orders}`;
-            if (options?.status !== undefined && options.customerId !== undefined) {
-                statement = sql `${statement} where status = ${options.status} and customer_id = ${options.customerId}`;
+            const conditions = [];
+            if (options?.status !== undefined)
+                conditions.push(sql `status = ${options.status}`);
+            if (options?.customerId !== undefined) {
+                conditions.push(sql `customer_id = ${options.customerId}`);
             }
-            else if (options?.status !== undefined) {
-                statement = sql `${statement} where status = ${options.status}`;
+            const search = options?.search?.trim().toLowerCase();
+            if (search !== undefined && search !== '') {
+                conditions.push(sql `(lower(reference) like ${`%${search}%`} or lower(email) like ${`%${search}%`})`);
             }
-            else if (options?.customerId !== undefined) {
-                statement = sql `${statement} where customer_id = ${options.customerId}`;
+            if (options?.placedFrom !== undefined) {
+                conditions.push(sql `placed_at >= ${options.placedFrom}`);
             }
+            if (options?.placedTo !== undefined) {
+                conditions.push(sql `placed_at <= ${options.placedTo}`);
+            }
+            let statement = sql `select * from ${orders}`;
+            conditions.forEach((condition, index) => {
+                statement = sql `${statement} ${index === 0 ? sql `where` : sql `and`} ${condition}`;
+            });
             statement = sql `${statement} order by placed_at desc, id desc limit ${limit(options?.limit ?? 100)} offset ${limit(options?.offset ?? 0)}`;
             const result = await db.query(statement);
             const decoded = [];
@@ -287,7 +340,89 @@ export function createOrderStore(db, dependencies, now = Date.now) {
                 note: options?.note ?? null,
             });
         },
+        update: async (id, patch, options) => {
+            const current = await load(id);
+            if (current.status !== 'pending') {
+                throw new CogentaError({
+                    code: 'COMMERCE_ORDER_LOCKED',
+                    message: `This order is ${current.status}, and its e-mail and delivery address can no longer be edited.`,
+                    hint: 'Only a pending order — not yet paid — can be corrected here. Cancel and re-place it instead.',
+                    details: { orderId: id, status: current.status },
+                });
+            }
+            const address = patch.shippingAddress;
+            const at = stamp();
+            await db.query(sql `
+        update ${orders}
+        set email = ${patch.email ?? current.email},
+            shipping_address_line1 = ${address === undefined ? current.shippingAddressLine1 : (address?.line1 ?? null)},
+            shipping_address_line2 = ${address === undefined ? current.shippingAddressLine2 : (address?.line2 ?? null)},
+            shipping_city = ${address === undefined ? current.shippingCity : (address?.city ?? null)},
+            shipping_postal_code = ${address === undefined ? current.shippingPostalCode : (address?.postalCode ?? null)},
+            shipping_recipient = ${address === undefined ? current.shippingRecipient : (address?.recipient ?? null)},
+            shipping_phone = ${address === undefined ? current.shippingPhone : (address?.phone ?? null)},
+            updated_at = ${at}
+        where id = ${id}`);
+            await appendEvent(db, id, 'address_updated', {
+                actorId: options?.actorId ?? null,
+                note: 'Order details corrected before payment.',
+            });
+            return load(id);
+        },
+        setTracking: async (id, tracking, options) => {
+            const current = await load(id);
+            if (current.status !== 'paid' && current.status !== 'shipped') {
+                throw new CogentaError({
+                    code: 'COMMERCE_TRACKING_INVALID',
+                    message: `Tracking can only be recorded once an order is paid, and this one is ${current.status}.`,
+                    hint: 'Settle the payment first — an order cannot ship before it is paid for.',
+                    details: { orderId: id, status: current.status },
+                });
+            }
+            if (tracking.carrier.trim() === '' || tracking.number.trim() === '') {
+                throw new CogentaError({
+                    code: 'COMMERCE_TRACKING_INVALID',
+                    message: 'A carrier and a tracking number are both required.',
+                    hint: 'Fill in both fields, or wait until the shipment has a real tracking number.',
+                });
+            }
+            return db.transaction(async (tx) => {
+                const wasPaid = current.status === 'paid';
+                const at = stamp();
+                await tx.query(sql `
+            update ${orders}
+            set tracking_carrier = ${tracking.carrier},
+                tracking_number = ${tracking.number},
+                tracking_url = ${tracking.url ?? null},
+                shipped_at = ${current.shippedAt ?? at},
+                status = ${wasPaid ? 'shipped' : current.status},
+                updated_at = ${at}
+            where id = ${id}`);
+                await appendEvent(tx, id, 'tracking_added', {
+                    actorId: options?.actorId ?? null,
+                    note: `Tracking added: ${tracking.carrier} ${tracking.number}.`,
+                });
+                if (wasPaid) {
+                    await appendEvent(tx, id, 'status_changed', {
+                        fromStatus: 'paid',
+                        toStatus: 'shipped',
+                        actorId: options?.actorId ?? null,
+                        note: 'Shipped, tracking attached.',
+                    });
+                }
+                const updated = await read(id, tx);
+                if (updated === null) {
+                    throw new CogentaError({
+                        code: 'COMMERCE_ORDER_NOT_FOUND',
+                        message: 'This order disappeared while it was being updated.',
+                        hint: 'Refresh the order list.',
+                    });
+                }
+                return updated;
+            }, { immediate: true });
+        },
     };
+    return store;
 }
 /** Internal. Unwinds the placement transaction with a caller-facing outcome. */
 class PlacementRefused extends Error {