@endora-commerce/mod-shipments 0.100.0

package/dist/backend/services/auto-shipment-on-paid.js

@@ -0,0 +1,58 @@
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { Shipment } from '../entities/shipment.entity.js';
+/**
+ * Creates a shipment when payment settles and the order's shipping adapter
+ * opts in via `shouldAutoCreateOnPaid()` (feature 068).
+ *
+ * Wired from `shipments/backend.ts` through `ctx.subscribe('payment.received.v1')`
+ * — never via a bare `eventBus.on` (issue #107). Best-effort: ordinary failures
+ * are swallowed so payment settlement is never blocked; `ModuleDisabledError`
+ * is re-thrown so fail-closed stays fail-closed.
+ *
+ * The order and the delivery method are read over their owners' ports, exactly
+ * as `ShipmentService` reads them (feature 075 Phase C): both rows are ones this
+ * operation does not modify, so nothing is lost by leaving them on the owner's
+ * EntityManager, and both fail closed when their owner is off.
+ */
+export class AutoShipmentOnPaidNotifier {
+    emFactory;
+    registry;
+    orderRead;
+    deliveryMethodRead;
+    shipmentService;
+    constructor(emFactory, registry, orderRead, deliveryMethodRead, shipmentService) {
+        this.emFactory = emFactory;
+        this.registry = registry;
+        this.orderRead = orderRead;
+        this.deliveryMethodRead = deliveryMethodRead;
+        this.shipmentService = shipmentService;
+    }
+    /** Exposed for unit tests. */
+    async maybeCreate(orderId) {
+        try {
+            const order = await this.orderRead.findById(orderId);
+            if (!order)
+                return;
+            const method = await this.deliveryMethodRead.findById(order.deliveryMethodId);
+            const adapterKey = method?.adapter ?? order.deliveryMethodId;
+            const adapter = this.registry.get(adapterKey);
+            if (!adapter?.shouldAutoCreateOnPaid)
+                return;
+            if (!(await adapter.shouldAutoCreateOnPaid()))
+                return;
+            const em = this.emFactory();
+            const latest = await em.findOne(Shipment, { orderId }, { orderBy: { attemptNo: 'desc' } });
+            if (latest && (latest.status === 'pending' || latest.status === 'success'))
+                return;
+            await this.shipmentService.createShipment(orderId);
+        }
+        catch (error) {
+            // Narrow tolerance, on purpose: `payment.received.v1` must settle the
+            // payment whatever the carrier says, so an ordinary adapter failure is
+            // left to the operator's "Generate shipment" button. A switched-off
+            // module is not an ordinary failure and is re-thrown first.
+            rethrowIfModuleDisabled(error);
+        }
+    }
+}
+//# sourceMappingURL=auto-shipment-on-paid.js.map

package/dist/backend/services/auto-shipment-on-paid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-shipment-on-paid.js","sourceRoot":"","sources":["../../../src/backend/services/auto-shipment-on-paid.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAG1D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,0BAA0B;IAElB;IACA;IACA;IACA;IACA;IALnB,YACmB,SAA8B,EAC9B,QAAqC,EACrC,SAAwB,EACxB,kBAA0C,EAC1C,eAAgC;QAJhC,cAAS,GAAT,SAAS,CAAqB;QAC9B,aAAQ,GAAR,QAAQ,CAA6B;QACrC,cAAS,GAAT,SAAS,CAAe;QACxB,uBAAkB,GAAlB,kBAAkB,CAAwB;QAC1C,oBAAe,GAAf,eAAe,CAAiB;IAChD,CAAC;IAEJ,8BAA8B;IAC9B,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrD,IAAI,CAAC,KAAK;gBAAE,OAAO;YAEnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAC9E,MAAM,UAAU,GAAG,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,gBAAgB,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC9C,IAAI,CAAC,OAAO,EAAE,sBAAsB;gBAAE,OAAO;YAC7C,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,sBAAsB,EAAE,CAAC;gBAAE,OAAO;YAEtD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAC7B,QAAQ,EACR,EAAE,OAAO,EAAE,EACX,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CACnC,CAAC;YACF,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC;gBAAE,OAAO;YAEnF,MAAM,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,sEAAsE;YACtE,uEAAuE;YACvE,oEAAoE;YACpE,4DAA4D;YAC5D,uBAAuB,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF"}

package/dist/backend/services/events.d.ts

@@ -0,0 +1,40 @@
+import type { ShipmentStatus } from '@endora-commerce/contracts';
+import type { EventBase, EventBus } from '@endora-commerce/platform/events';
+/**
+ * Shipping domain events (feature 035). Emitted on the in-process EventBus
+ * inside the handler's transactional scope, so a rolled-back transaction never
+ * dispatches. The delivery-side twin of the payment.* events.
+ */
+export interface ShippingEvents extends Record<string, EventBase> {
+    'shipment.created.v1': EventBase & {
+        orderId: string;
+        shipmentId: string;
+        deliveryMethodId: string;
+        adapter: string;
+        attemptNo: number;
+        /**
+         * The state the row was opened in (issue #250). A subscriber that acts as
+         * if the carrier had been asked — the customer's "your order has shipped"
+         * e-mail is the one in this module — has to be able to tell a
+         * `pending_manual` shipment from a `pending` one, and the event is where
+         * it can, without re-reading the row it was just told about.
+         */
+        status: ShipmentStatus;
+    };
+    'shipment.received.v1': EventBase & {
+        orderId: string;
+        shipmentId: string;
+        adapter: string;
+        externalReference: string | null;
+        attemptNo: number;
+    };
+    'shipment.failed.v1': EventBase & {
+        orderId: string;
+        shipmentId: string;
+        adapter: string;
+        failureReason: string | null;
+        attemptNo: number;
+    };
+}
+export type ShippingEventBus = EventBus<ShippingEvents>;
+//# sourceMappingURL=events.d.ts.map

package/dist/backend/services/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/backend/services/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAC/D,qBAAqB,EAAE,SAAS,GAAG;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB;;;;;;WAMG;QACH,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC;IACF,sBAAsB,EAAE,SAAS,GAAG;QAClC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,oBAAoB,EAAE,SAAS,GAAG;QAChC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC"}

package/dist/backend/services/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/backend/services/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/backend/services/events.ts"],"names":[],"mappings":""}

package/dist/backend/services/receive-shipment-handler.d.ts

@@ -0,0 +1,93 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type ReceiveShipment } from '@endora-commerce/contracts';
+import type { DeliveryMethodReadPort, OrderTransitionPort } from '@endora-commerce/contracts';
+import { Shipment } from '../entities/shipment.entity.js';
+import type { ShippingEventBus } from './events.js';
+export interface ReceiveShipmentResult {
+    shipmentId: string;
+    status: Shipment['status'];
+    /**
+     * Where the order stands once the ingress is done with it, which since
+     * feature 085 Phase D is the lifecycle's answer rather than this handler's:
+     * the target the method configured when the graph permitted it, the order's
+     * unchanged status when it did not, and `null` when the ingress asked for no
+     * move at all (a repeated callback, or a method with no status configured).
+     */
+    orderStatus: string | null;
+    idempotent: boolean;
+}
+/**
+ * The one message this handler logs, as little of a logger as it needs.
+ *
+ * `ctx.log` satisfies it structurally, so `shipments/backend.ts` passes the
+ * module's own logger and a test passes a recorder. `payments` declares the
+ * same shape at its twin seam; neither module imports the other's.
+ */
+export interface CarrierCallbackLogger {
+    warn(details: object, message: string): void;
+}
+/**
+ * ReceiveShipmentHandler (feature 035, FR-022/FR-023/FR-025).
+ *
+ * Resolves a Shipment from the ingress payload, applies the outcome, and asks
+ * the order lifecycle for the move the method's `statusOnSuccess` /
+ * `statusOnFailure` names. Idempotent: a success after a terminal `success` is
+ * a no-op; a failure after `success` is rejected (no downgrade). Resolves a
+ * late event even when the adapter has since been de-registered (it keys on the
+ * persisted Shipment, not the live registry).
+ *
+ * **The lifecycle answers; this handler does not decide** (feature 085 Phase
+ * D). It used to assign `order.status` after asking an `OrderStatusRegistry`
+ * whether the code existed, which is a different question from whether the
+ * order may go there — so a carrier callback wrote transitions the configured
+ * graph forbids while an operator making the same move by hand was refused, and
+ * the change was audited nowhere. The order row is no longer read here at all:
+ * the port carries the move, the audit entry, the side-effects and the
+ * templated `order.status.*.after` announcement.
+ */
+export declare class ReceiveShipmentHandler {
+    private readonly emFactory;
+    private readonly deliveryMethodRead;
+    /**
+     * The lifecycle write (feature 085 Phase D), **called after this handler's
+     * transaction has committed** and never inside it: the port takes its own
+     * `EntityManager`, so a call from inside would write the order on a
+     * different pooled connection whose commit the enclosing rollback cannot
+     * reach (issue #200). A crash in between leaves the shipment recorded and
+     * the order unmoved, which an operator can see and repeat.
+     */
+    private readonly orderTransition;
+    /** Where a refused transition is recorded; see {@link CarrierCallbackLogger}. */
+    private readonly log;
+    private readonly events?;
+    constructor(emFactory: () => EntityManager, deliveryMethodRead: DeliveryMethodReadPort, 
+    /**
+     * The lifecycle write (feature 085 Phase D), **called after this handler's
+     * transaction has committed** and never inside it: the port takes its own
+     * `EntityManager`, so a call from inside would write the order on a
+     * different pooled connection whose commit the enclosing rollback cannot
+     * reach (issue #200). A crash in between leaves the shipment recorded and
+     * the order unmoved, which an operator can see and repeat.
+     */
+    orderTransition: OrderTransitionPort, 
+    /** Where a refused transition is recorded; see {@link CarrierCallbackLogger}. */
+    log: CarrierCallbackLogger, events?: ShippingEventBus | undefined);
+    receive(input: ReceiveShipment): Promise<ReceiveShipmentResult>;
+    /**
+     * Ask the lifecycle for the move the configured setting names, and answer
+     * where the order ended up.
+     *
+     * Every refusal is a 200 for the carrier (contract §"What the caller does
+     * with each outcome"): a provider retries a non-2xx callback, and an order
+     * further along than the configured target must not be dragged backwards
+     * because a delivery attempt failed. So the refusal is recorded here and the
+     * shipment row stands.
+     *
+     * There is deliberately no `catch`. A `ModuleDisabledError` out of the port's
+     * gate is not a refusal — it is the owner being absent — and swallowing it
+     * would turn fail-closed into fail-open.
+     */
+    private moveOrder;
+    private resolveShipment;
+}
+//# sourceMappingURL=receive-shipment-handler.d.ts.map

package/dist/backend/services/receive-shipment-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive-shipment-handler.d.ts","sourceRoot":"","sources":["../../../src/backend/services/receive-shipment-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EACV,sBAAsB,EAEtB,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC3B;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAbP,SAAS,EAAE,MAAM,aAAa,EAC9B,kBAAkB,EAAE,sBAAsB;IAC3D;;;;;;;OAOG;IACc,eAAe,EAAE,mBAAmB;IACrD,iFAAiF;IAChE,GAAG,EAAE,qBAAqB,EAC1B,MAAM,CAAC,EAAE,gBAAgB,YAAA;IAGtC,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAyHrE;;;;;;;;;;;;;OAaG;YACW,SAAS;YA8BT,eAAe;CAkB9B"}

package/dist/backend/services/receive-shipment-handler.js

@@ -0,0 +1,203 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { Shipment } from '../entities/shipment.entity.js';
+/**
+ * ReceiveShipmentHandler (feature 035, FR-022/FR-023/FR-025).
+ *
+ * Resolves a Shipment from the ingress payload, applies the outcome, and asks
+ * the order lifecycle for the move the method's `statusOnSuccess` /
+ * `statusOnFailure` names. Idempotent: a success after a terminal `success` is
+ * a no-op; a failure after `success` is rejected (no downgrade). Resolves a
+ * late event even when the adapter has since been de-registered (it keys on the
+ * persisted Shipment, not the live registry).
+ *
+ * **The lifecycle answers; this handler does not decide** (feature 085 Phase
+ * D). It used to assign `order.status` after asking an `OrderStatusRegistry`
+ * whether the code existed, which is a different question from whether the
+ * order may go there — so a carrier callback wrote transitions the configured
+ * graph forbids while an operator making the same move by hand was refused, and
+ * the change was audited nowhere. The order row is no longer read here at all:
+ * the port carries the move, the audit entry, the side-effects and the
+ * templated `order.status.*.after` announcement.
+ */
+export class ReceiveShipmentHandler {
+    emFactory;
+    deliveryMethodRead;
+    orderTransition;
+    log;
+    events;
+    constructor(emFactory, deliveryMethodRead, 
+    /**
+     * The lifecycle write (feature 085 Phase D), **called after this handler's
+     * transaction has committed** and never inside it: the port takes its own
+     * `EntityManager`, so a call from inside would write the order on a
+     * different pooled connection whose commit the enclosing rollback cannot
+     * reach (issue #200). A crash in between leaves the shipment recorded and
+     * the order unmoved, which an operator can see and repeat.
+     */
+    orderTransition, 
+    /** Where a refused transition is recorded; see {@link CarrierCallbackLogger}. */
+    log, events) {
+        this.emFactory = emFactory;
+        this.deliveryMethodRead = deliveryMethodRead;
+        this.orderTransition = orderTransition;
+        this.log = log;
+        this.events = events;
+    }
+    async receive(input) {
+        // command-coverage-ignore: provider shipment-event ingestion — stamps the
+        // attempt result on the Shipment row, then asks `orderTransitionPort` for
+        // the lifecycle move, which records the `order.status_transition` audit
+        // entry co-transactionally with the status write it performs. The reason on
+        // this marker used to claim that audit while the handler assigned
+        // `order.status` itself and reached the orders flow at no point (feature
+        // 085, R3); Phase D made the claim true.
+        const em = this.emFactory();
+        const result = await em.transactional(async (tx) => {
+            const shipment = await this.resolveShipment(tx, input);
+            if (!shipment) {
+                throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Shipment not found for the given reference.');
+            }
+            // Idempotency / terminal-state guards (FR-025).
+            if (shipment.status === 'success') {
+                if (input.outcome === 'failure') {
+                    throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, 'Shipment is already generated; it cannot be marked failed.');
+                }
+                return {
+                    shipment,
+                    idempotent: true,
+                    emit: false,
+                    transition: null,
+                };
+            }
+            const method = await this.deliveryMethodRead.findById(shipment.deliveryMethodId);
+            let transition = null;
+            if (input.outcome === 'success') {
+                shipment.status = 'success';
+                if (input.externalReference !== undefined) {
+                    shipment.externalReference = input.externalReference ?? null;
+                }
+                if (input.providerDetails)
+                    shipment.providerDetails = input.providerDetails;
+                if (method?.statusOnSuccess) {
+                    transition = { to: method.statusOnSuccess, setting: 'status_on_success' };
+                }
+            }
+            else {
+                shipment.status = 'failure';
+                shipment.failureReason = input.failureReason ?? null;
+                if (input.providerDetails)
+                    shipment.providerDetails = input.providerDetails;
+                if (method?.statusOnFailure) {
+                    transition = { to: method.statusOnFailure, setting: 'status_on_failure' };
+                }
+            }
+            await tx.flush();
+            return {
+                shipment,
+                idempotent: false,
+                emit: true,
+                adapter: method?.adapter ?? shipment.deliveryMethodId,
+                transition,
+            };
+        });
+        /**
+         * After the commit, never inside the transaction above (feature 085 R4).
+         *
+         * The transaction holds the shipment row alone now. It used to hold the
+         * order's status with it, which was the ground D-90 gave for importing the
+         * `Order` entity here; the lifecycle move is a graph decision with guards
+         * and side-effects rather than a column, so it goes through the port and
+         * the entity import goes with it.
+         */
+        const orderStatus = result.transition
+            ? await this.moveOrder(result.shipment.orderId, result.transition.to, result.transition.setting, input.outcome === 'failure' ? (input.failureReason ?? null) : null)
+            : null;
+        if (result.emit && this.events) {
+            const base = { eventId: randomUUID(), occurredAt: new Date().toISOString() };
+            if (result.shipment.status === 'success') {
+                this.events.emit('shipment.received.v1', {
+                    ...base,
+                    orderId: result.shipment.orderId,
+                    shipmentId: result.shipment.id,
+                    adapter: result.adapter ?? '',
+                    externalReference: result.shipment.externalReference ?? null,
+                    attemptNo: result.shipment.attemptNo,
+                });
+            }
+            else {
+                this.events.emit('shipment.failed.v1', {
+                    ...base,
+                    orderId: result.shipment.orderId,
+                    shipmentId: result.shipment.id,
+                    adapter: result.adapter ?? '',
+                    failureReason: result.shipment.failureReason ?? null,
+                    attemptNo: result.shipment.attemptNo,
+                });
+            }
+            // The templated `order.status.*.after` events (feature 038, T026) are no
+            // longer emitted from here: `OrderTransitionService` emits them itself,
+            // for the transition it applied, with the same actor. Announcing again
+            // would double every subscriber's reaction to one carrier callback.
+        }
+        return {
+            shipmentId: result.shipment.id,
+            status: result.shipment.status,
+            orderStatus,
+            idempotent: result.idempotent,
+        };
+    }
+    /**
+     * Ask the lifecycle for the move the configured setting names, and answer
+     * where the order ended up.
+     *
+     * Every refusal is a 200 for the carrier (contract §"What the caller does
+     * with each outcome"): a provider retries a non-2xx callback, and an order
+     * further along than the configured target must not be dragged backwards
+     * because a delivery attempt failed. So the refusal is recorded here and the
+     * shipment row stands.
+     *
+     * There is deliberately no `catch`. A `ModuleDisabledError` out of the port's
+     * gate is not a refusal — it is the owner being absent — and swallowing it
+     * would turn fail-closed into fail-open.
+     */
+    async moveOrder(orderId, to, setting, reason) {
+        const outcome = await this.orderTransition.applyStatus({
+            orderId,
+            to,
+            actor: { kind: 'system', source: 'shipment' },
+            reason,
+        });
+        if (outcome.applied)
+            return outcome.to;
+        if (outcome.reason === 'already_there')
+            return outcome.from;
+        this.log.warn({
+            orderId,
+            from: outcome.from,
+            to,
+            setting,
+            refusal: outcome.reason,
+            detail: outcome.detail,
+        }, 'shipments: the requested order status was not applied; the order keeps the one it has');
+        return outcome.from;
+    }
+    async resolveShipment(tx, input) {
+        if (input.shipmentId) {
+            return tx.findOne(Shipment, { id: input.shipmentId });
+        }
+        if (input.orderId && input.externalReference) {
+            const byRef = await tx.findOne(Shipment, {
+                orderId: input.orderId,
+                externalReference: input.externalReference,
+            });
+            if (byRef)
+                return byRef;
+            // Fall back to the most recent open attempt for the order.
+            return tx.findOne(Shipment, { orderId: input.orderId }, { orderBy: { attemptNo: 'desc' } });
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=receive-shipment-handler.js.map

package/dist/backend/services/receive-shipment-handler.js.map

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

package/dist/backend/services/shipment-email-notifier.d.ts

@@ -0,0 +1,78 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { CustomerAccountReadPort, OrderReadPort, ShipmentStatus, TransactionalEmailSender } from '@endora-commerce/contracts';
+/**
+ * Why the shipment-created e-mail did — or did not — go out (issue #78).
+ *
+ * `notify` answered `void`, so a parcel whose customer was never told read
+ * exactly like one whose customer was: no sender wired, no order behind the id,
+ * no address on the customer, the three outcomes `send` reports since issue
+ * #67, and anything the bare `catch` absorbed all produced that same `void`.
+ */
+export type ShipmentEmailNotSentReason = 
+/**
+ * The shipment opened `pending_manual`: no carrier was asked for it, so
+ * there is no carrier, no label and no tracking number to tell the customer
+ * about (issue #250). Telling a buyer their order has shipped when nothing
+ * has been handed to anyone is worse than telling them nothing, and it is
+ * not recoverable — the correcting message is one nobody sends.
+ */
+'carrier_not_contacted'
+/** No transactional sender is wired in this composition. */
+ | 'no_sender'
+/** The event named an order this process cannot load. */
+ | 'order_not_found'
+/** The customer account carries no address to send to. */
+ | 'no_recipient'
+/** The operator switched the `shipment_created` e-mail off. */
+ | 'deactivated'
+/** No mailer is wired behind the sender. */
+ | 'no_transport'
+/** No `shipment_created` template exists yet. */
+ | 'no_definition'
+/** The send raised, and the shipment stays created. */
+ | 'failed';
+export type ShipmentEmailResult = {
+    sent: true;
+} | {
+    sent: false;
+    reason: ShipmentEmailNotSentReason;
+};
+/**
+ * Where a send that did not happen is reported. Injectable so a test can read
+ * it; defaults to `console.warn`, which is what the rest of this layer uses.
+ */
+export type ShipmentEmailLog = (message: string, context: Record<string, unknown>) => void;
+export interface ShipmentEmailNotifierDeps {
+    emFactory: () => EntityManager;
+    /**
+     * Feature 075 Phase C — the order and its buyer come from the ports their
+     * owners publish, not from `Order` and `CustomerAccount`. Both fail closed
+     * when their owner is off, and that is the right answer for a notification:
+     * an e-mail addressed from data the platform will not read is worse than no
+     * e-mail. `notify`'s `catch` re-throws `ModuleDisabledError` first, so the
+     * refusal reaches the subscriber rather than being logged as `failed`.
+     */
+    orderRead: OrderReadPort;
+    customerAccountRead: CustomerAccountReadPort;
+    getTransactionalEmailSender: () => TransactionalEmailSender | undefined;
+    log?: ShipmentEmailLog;
+}
+export declare class ShipmentEmailNotifier {
+    private readonly deps;
+    private readonly log;
+    constructor(deps: ShipmentEmailNotifierDeps);
+    /**
+     * Public since feature 072 (T124), and `attach(eventBus)` is gone with it.
+     * That method subscribed to the raw bus, which is how a shipment-created
+     * e-mail went out while this module was switched off; the module now
+     * subscribes through `ctx.subscribe`, which stops with it.
+     *
+     * **Best-effort, and now audible.** The subscriber that calls this has no
+     * result to inspect, so every non-sent path is written to the log as well as
+     * named in the return value; a shipment must not be un-created because the
+     * notification failed.
+     */
+    notify(orderId: string, shipmentId: string, status: ShipmentStatus): Promise<ShipmentEmailResult>;
+    private notSent;
+}
+//# sourceMappingURL=shipment-email-notifier.d.ts.map

package/dist/backend/services/shipment-email-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-email-notifier.d.ts","sourceRoot":"","sources":["../../../src/backend/services/shipment-email-notifier.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EACb,cAAc,EACd,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AAIpC;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B;AACpC;;;;;;GAMG;AACD,uBAAuB;AACzB,4DAA4D;GAC1D,WAAW;AACb,yDAAyD;GACvD,iBAAiB;AACnB,0DAA0D;GACxD,cAAc;AAChB,+DAA+D;GAC7D,aAAa;AACf,4CAA4C;GAC1C,cAAc;AAChB,iDAAiD;GAC/C,eAAe;AACjB,uDAAuD;GACrD,QAAQ,CAAC;AAEb,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE3F,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B;;;;;;;OAOG;IACH,SAAS,EAAE,aAAa,CAAC;IACzB,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,2BAA2B,EAAE,MAAM,wBAAwB,GAAG,SAAS,CAAC;IACxE,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACxB;AAED,qBAAa,qBAAqB;IAGpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;gBAEV,IAAI,EAAE,yBAAyB;IAI5D;;;;;;;;;;OAUG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,mBAAmB,CAAC;IAwC/B,OAAO,CAAC,OAAO;CAchB"}

package/dist/backend/services/shipment-email-notifier.js

@@ -0,0 +1,76 @@
+// Feature 047 — shipment_created transactional email. A net-new email: subscribes
+// to shipment.created.v1 and sends the admin-editable template to the order's
+// customer. Best-effort; event-bus dispatch isolates handler errors.
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { SalesChannel } from '@endora-commerce/platform/kernel';
+export class ShipmentEmailNotifier {
+    deps;
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? ((message, context) => console.warn(message, context));
+    }
+    /**
+     * Public since feature 072 (T124), and `attach(eventBus)` is gone with it.
+     * That method subscribed to the raw bus, which is how a shipment-created
+     * e-mail went out while this module was switched off; the module now
+     * subscribes through `ctx.subscribe`, which stops with it.
+     *
+     * **Best-effort, and now audible.** The subscriber that calls this has no
+     * result to inspect, so every non-sent path is written to the log as well as
+     * named in the return value; a shipment must not be un-created because the
+     * notification failed.
+     */
+    async notify(orderId, shipmentId, status) {
+        // First, and before any plumbing is consulted: this is a decision about the
+        // shipment, not about the mail. A `pending_manual` row is one no carrier
+        // was ever asked for, so "your order has shipped" would be false.
+        if (status === 'pending_manual') {
+            return this.notSent(orderId, shipmentId, 'carrier_not_contacted');
+        }
+        const sender = this.deps.getTransactionalEmailSender();
+        if (!sender)
+            return this.notSent(orderId, shipmentId, 'no_sender');
+        try {
+            const em = this.deps.emFactory();
+            const order = await this.deps.orderRead.findById(orderId);
+            if (!order)
+                return this.notSent(orderId, shipmentId, 'order_not_found');
+            const customer = await this.deps.customerAccountRead.findById(order.placedByCustomerAccountId);
+            if (!customer?.email)
+                return this.notSent(orderId, shipmentId, 'no_recipient');
+            const channel = await em.findOne(SalesChannel, { id: order.salesChannelId });
+            const outcome = await sender.send({
+                code: 'shipment_created',
+                salesChannelId: order.salesChannelId,
+                language: channel?.defaultLanguage ?? 'en-US',
+                to: customer.email,
+                messageId: `shipment_created:${shipmentId}`,
+                variables: { order: { businessId: order.businessId } },
+                meta: { orderId: order.id, shipmentId, kind: 'shipment_created' },
+            });
+            if (outcome.status !== 'sent')
+                return this.notSent(orderId, shipmentId, outcome.status);
+            return { sent: true };
+        }
+        catch (error) {
+            // A switched-off module is a presence answer about the whole operation,
+            // not a message that failed to render; absorbing it would report "sent
+            // nothing" where the truthful answer is "this capability is off".
+            rethrowIfModuleDisabled(error);
+            // Everything else is contained: the shipment exists and must not be
+            // undone because the message did not go out. It is named, though.
+            return this.notSent(orderId, shipmentId, 'failed', error);
+        }
+    }
+    notSent(orderId, shipmentId, reason, error) {
+        this.log('[shipments] the shipment-created e-mail was not sent', {
+            orderId,
+            shipmentId,
+            reason,
+            ...(error === undefined ? {} : { error: error instanceof Error ? error.message : error }),
+        });
+        return { sent: false, reason };
+    }
+}
+//# sourceMappingURL=shipment-email-notifier.js.map

package/dist/backend/services/shipment-email-notifier.js.map

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

package/dist/backend/services/shipment-read.service.d.ts

@@ -0,0 +1,19 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { ShipmentReadPort, ShipmentRecord } from '@endora-commerce/contracts';
+import { Shipment } from '../entities/shipment.entity.js';
+/**
+ * The reads behind `shipmentReadPort` — see the port's contract for why a
+ * carrier module asks them and what happens when this module is off.
+ *
+ * Deliberately not methods on {@link ShipmentService}: that service opens
+ * attempts and calls carriers, and a lookup by id has no business resolving an
+ * adapter registry, an order port and a delivery-method port to answer.
+ */
+export declare class ShipmentReadService implements ShipmentReadPort {
+    private readonly emFactory;
+    constructor(emFactory: () => EntityManager);
+    findById(id: string): Promise<ShipmentRecord | null>;
+    findByExternalReference(reference: string): Promise<ShipmentRecord | null>;
+}
+export declare function toShipmentRecord(shipment: Shipment): ShipmentRecord;
+//# sourceMappingURL=shipment-read.service.d.ts.map

package/dist/backend/services/shipment-read.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-read.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/shipment-read.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM,aAAa;IAErD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKpD,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;CAQjF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAanE"}