@endora-commerce/mod-shipments 0.100.0

package/dist/backend/services/shipment-read.service.js

@@ -0,0 +1,38 @@
+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 class ShipmentReadService {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    async findById(id) {
+        const row = await this.emFactory().findOne(Shipment, { id });
+        return row ? toShipmentRecord(row) : null;
+    }
+    async findByExternalReference(reference) {
+        const row = await this.emFactory().findOne(Shipment, { externalReference: reference }, { orderBy: { createdAt: 'desc', attemptNo: 'desc' } });
+        return row ? toShipmentRecord(row) : null;
+    }
+}
+export function toShipmentRecord(shipment) {
+    return {
+        id: shipment.id,
+        orderId: shipment.orderId,
+        deliveryMethodId: shipment.deliveryMethodId,
+        status: shipment.status,
+        externalReference: shipment.externalReference ?? null,
+        providerDetails: shipment.providerDetails ?? null,
+        failureReason: shipment.failureReason ?? null,
+        attemptNo: shipment.attemptNo,
+        createdAt: shipment.createdAt,
+        updatedAt: shipment.updatedAt,
+    };
+}
+//# sourceMappingURL=shipment-read.service.js.map

package/dist/backend/services/shipment-read.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-read.service.js","sourceRoot":"","sources":["../../../src/backend/services/shipment-read.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,uBAAuB,CAAC,SAAiB;QAC7C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CACxC,QAAQ,EACR,EAAE,iBAAiB,EAAE,SAAS,EAAE,EAChC,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CACtD,CAAC;QACF,OAAO,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAkB;IACjD,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;QAC3C,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB,IAAI,IAAI;QACrD,eAAe,EAAE,QAAQ,CAAC,eAAe,IAAI,IAAI;QACjD,aAAa,EAAE,QAAQ,CAAC,aAAa,IAAI,IAAI;QAC7C,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,79 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { DeliveryMethodReadPort, OrderReadPort, ShippingAdapterRegistryPort } from '@endora-commerce/contracts';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { Shipment } from '../entities/shipment.entity.js';
+import type { ShippingEventBus } from './events.js';
+/**
+ * What a `pending_manual` shipment says about itself, in one place so the row,
+ * the audit entry and the tests cannot drift apart (issue #250).
+ *
+ * English and persisted, like the payment side's refund reasons: this is the
+ * record of what happened, not a rendered string. The admin translates the
+ * *state* and shows this sentence as the detail that names the module — which
+ * is the one thing the operator needs and no translation can supply.
+ */
+export declare function carrierNotContactedReason(moduleId: string): string;
+/**
+ * ShipmentService (feature 035, FR-021/FR-024).
+ *
+ * `createShipment` raises `shipment_created`: it opens a pending Shipment
+ * against the Order, invokes the method adapter's `onShipmentCreated`, and
+ * emits `shipment.created.v1`. It is also the retry path (FR-024): called again
+ * after a failure it appends attempt n+1 and leaves the prior rows intact,
+ * refusing only once an attempt has succeeded. `listForOrder` powers the admin
+ * view.
+ *
+ * Issue #257 — there used to be a second attempt-opening path, `openRetry`, and
+ * it asked no adapter in any state, not only while a carrier module was off. It
+ * is gone rather than repaired: no admin surface reached it, its own contract
+ * described it as "equivalent to calling the generate route again", and the
+ * equivalence was false in the one way that mattered — the row appeared, the
+ * status read `pending`, and no carrier had heard of the parcel. Repairing it
+ * would have left a second copy of `createShipment` to keep honest forever;
+ * deleting it leaves one path, which is the one every caller already used.
+ *
+ * Feature 075 Phase C — the order and the delivery method are read over their
+ * owners' ports. Only the `Shipment` rows are this module's to write, and only
+ * those stay inside the transaction: the two reads are of rows nothing in this
+ * operation modifies, so moving them onto the owner's `EntityManager` costs no
+ * consistency. Both fail closed when their owner is off, which is right — a
+ * shipment opened against an order the platform will not read is a parcel with
+ * no addressee.
+ *
+ * Issue #250 — the adapter registry is a contribution point, so an adapter
+ * whose owner is switched off is filtered out at enumeration rather than
+ * throwing (D-39). That gate is right; what used to follow it was not. The
+ * hook was skipped and the row was still written `pending`, so a shipment with
+ * no label, no tracking number and no carrier that knew about it read exactly
+ * like one the carrier had accepted. It now opens `pending_manual` — the state
+ * the platform already uses on the payment side for "the money did not move,
+ * a person has to finish this" — with the module named in `failureReason` and
+ * an audit row recording the attempt.
+ */
+export declare class ShipmentService {
+    private readonly emFactory;
+    private readonly registry;
+    private readonly orderRead;
+    private readonly deliveryMethodRead;
+    private readonly auditLog;
+    private readonly events?;
+    constructor(emFactory: () => EntityManager, registry: ShippingAdapterRegistryPort, orderRead: OrderReadPort, deliveryMethodRead: DeliveryMethodReadPort, auditLog: AuditPort, events?: ShippingEventBus | undefined);
+    createShipment(orderId: string): Promise<Shipment>;
+    /**
+     * The order's shipment attempts — for the admin panel.
+     *
+     * The `orderRead` call is the tenant boundary, not a convenience: `Shipment`
+     * is `@GlobalEntity`, so `em.find(Shipment, { orderId })` carries no filter
+     * and answers for every order on the platform, while `Order` is `@OrgScoped`
+     * and this port reads it through a filtered EntityManager. An
+     * assignment-scoped administrator therefore gets `null` here and no tracking
+     * number from an organization they are not assigned to.
+     *
+     * `createShipment` above has always made this read for its own reasons and so
+     * was never exposed; this one had no reason to make it, which is exactly how
+     * the gap arrived. 404 rather than 403 — an out-of-scope order must read the
+     * same as one that is not there.
+     */
+    listForOrder(orderId: string): Promise<Shipment[]>;
+}
+//# sourceMappingURL=shipment-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/shipment-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACb,2BAA2B,EAC5B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBALP,SAAS,EAAE,MAAM,aAAa,EAC9B,QAAQ,EAAE,2BAA2B,EACrC,SAAS,EAAE,aAAa,EACxB,kBAAkB,EAAE,sBAAsB,EAC1C,QAAQ,EAAE,SAAS,EACnB,MAAM,CAAC,EAAE,gBAAgB,YAAA;IAGtC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0HxD;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAQzD"}

package/dist/backend/services/shipment-service.js

@@ -0,0 +1,203 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { Shipment } from '../entities/shipment.entity.js';
+/**
+ * What a `pending_manual` shipment says about itself, in one place so the row,
+ * the audit entry and the tests cannot drift apart (issue #250).
+ *
+ * English and persisted, like the payment side's refund reasons: this is the
+ * record of what happened, not a rendered string. The admin translates the
+ * *state* and shows this sentence as the detail that names the module — which
+ * is the one thing the operator needs and no translation can supply.
+ */
+export function carrierNotContactedReason(moduleId) {
+    return (`The "${moduleId}" module is not switched on here, so the carrier was never ` +
+        `asked to create this shipment. Switch the module back on and generate the ` +
+        `shipment again.`);
+}
+/**
+ * ShipmentService (feature 035, FR-021/FR-024).
+ *
+ * `createShipment` raises `shipment_created`: it opens a pending Shipment
+ * against the Order, invokes the method adapter's `onShipmentCreated`, and
+ * emits `shipment.created.v1`. It is also the retry path (FR-024): called again
+ * after a failure it appends attempt n+1 and leaves the prior rows intact,
+ * refusing only once an attempt has succeeded. `listForOrder` powers the admin
+ * view.
+ *
+ * Issue #257 — there used to be a second attempt-opening path, `openRetry`, and
+ * it asked no adapter in any state, not only while a carrier module was off. It
+ * is gone rather than repaired: no admin surface reached it, its own contract
+ * described it as "equivalent to calling the generate route again", and the
+ * equivalence was false in the one way that mattered — the row appeared, the
+ * status read `pending`, and no carrier had heard of the parcel. Repairing it
+ * would have left a second copy of `createShipment` to keep honest forever;
+ * deleting it leaves one path, which is the one every caller already used.
+ *
+ * Feature 075 Phase C — the order and the delivery method are read over their
+ * owners' ports. Only the `Shipment` rows are this module's to write, and only
+ * those stay inside the transaction: the two reads are of rows nothing in this
+ * operation modifies, so moving them onto the owner's `EntityManager` costs no
+ * consistency. Both fail closed when their owner is off, which is right — a
+ * shipment opened against an order the platform will not read is a parcel with
+ * no addressee.
+ *
+ * Issue #250 — the adapter registry is a contribution point, so an adapter
+ * whose owner is switched off is filtered out at enumeration rather than
+ * throwing (D-39). That gate is right; what used to follow it was not. The
+ * hook was skipped and the row was still written `pending`, so a shipment with
+ * no label, no tracking number and no carrier that knew about it read exactly
+ * like one the carrier had accepted. It now opens `pending_manual` — the state
+ * the platform already uses on the payment side for "the money did not move,
+ * a person has to finish this" — with the module named in `failureReason` and
+ * an audit row recording the attempt.
+ */
+export class ShipmentService {
+    emFactory;
+    registry;
+    orderRead;
+    deliveryMethodRead;
+    auditLog;
+    events;
+    constructor(emFactory, registry, orderRead, deliveryMethodRead, auditLog, events) {
+        this.emFactory = emFactory;
+        this.registry = registry;
+        this.orderRead = orderRead;
+        this.deliveryMethodRead = deliveryMethodRead;
+        this.auditLog = auditLog;
+        this.events = events;
+    }
+    async createShipment(orderId) {
+        // command-coverage-ignore: creates a pending shipment attempt + invokes the
+        // delivery adapter; fulfilment mechanics — the order "shipped" transition is
+        // audited in the orders flow.
+        const run = async () => {
+            const em = this.emFactory();
+            return em.transactional(async (tx) => {
+                const order = await this.orderRead.findById(orderId);
+                if (!order) {
+                    throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Order not found.');
+                }
+                const latest = await tx.findOne(Shipment, { orderId }, { orderBy: { attemptNo: 'desc' } });
+                if (latest && latest.status === 'success') {
+                    throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, 'Order already has a successful shipment; nothing to generate.');
+                }
+                const method = await this.deliveryMethodRead.findById(order.deliveryMethodId);
+                const adapterKey = method?.adapter ?? order.deliveryMethodId;
+                const adapter = this.registry.get(adapterKey);
+                // Told apart deliberately: an adapter nobody ever contributed is an
+                // offline method that has always been finished by hand, and it keeps
+                // opening `pending`. Only a contributed adapter whose module is absent
+                // produces `pending_manual` — because only that one names a module an
+                // operator can switch back on.
+                const absentCarrierModule = adapter ? null : this.registry.absentOwnerFor(adapterKey);
+                const shipment = tx.create(Shipment, {
+                    orderId,
+                    deliveryMethodId: order.deliveryMethodId,
+                    status: absentCarrierModule ? 'pending_manual' : 'pending',
+                    ...(absentCarrierModule
+                        ? { failureReason: carrierNotContactedReason(absentCarrierModule) }
+                        : {}),
+                    attemptNo: (latest?.attemptNo ?? 0) + 1,
+                });
+                await tx.persistAndFlush(shipment);
+                // Invoke the adapter's shipment_created hook. Status stays pending until
+                // receive_shipment; a synchronous `generated` result still deposits the
+                // tracking number on the row so admin can see it before terminal ingress.
+                // Carrier references (ShipX id, etc.) must be applied on *this*
+                // transactional EM — a forked emFactory inside the adapter cannot see
+                // the uncommitted row and would silently skip the write.
+                if (adapter) {
+                    const started = await adapter.onShipmentCreated({
+                        orderId,
+                        shipmentId: shipment.id,
+                        deliveryMethodId: order.deliveryMethodId,
+                        attemptNo: shipment.attemptNo,
+                    });
+                    if (started.kind === 'pending' || started.kind === 'generated') {
+                        // `externalReference` is the explicit carrier reference and wins;
+                        // `trackingNumber` on a `generated` result is the older spelling an
+                        // adapter that names no reference still relies on.
+                        const reference = started.externalReference !== undefined
+                            ? (started.externalReference ?? null)
+                            : started.kind === 'generated' && started.trackingNumber
+                                ? started.trackingNumber
+                                : undefined;
+                        if (reference !== undefined) {
+                            shipment.externalReference = reference;
+                        }
+                        if (started.providerDetails) {
+                            shipment.providerDetails = started.providerDetails;
+                        }
+                        if (reference !== undefined || started.providerDetails !== undefined) {
+                            // `persistAndFlush` and not `flush`: the row is already managed by
+                            // this transaction, so the two are equivalent here, and this is the
+                            // spelling every other write in the method uses.
+                            await tx.persistAndFlush(shipment);
+                        }
+                    }
+                }
+                else if (absentCarrierModule) {
+                    // Co-transactional with the row it describes (Principle XIII): the
+                    // shipment and the record of why it is unfinished commit together or
+                    // not at all. `recordAuditFromContext` rather than the Command Bus
+                    // for the reason its own docblock gives — this write already owns a
+                    // transaction the bus would have to fork out of.
+                    recordAuditFromContext(this.auditLog, tx, {
+                        action: 'shipment.carrier_not_contacted',
+                        objectType: 'shipment',
+                        objectId: shipment.id,
+                        stateAfter: {
+                            orderId,
+                            adapter: adapterKey,
+                            absentModule: absentCarrierModule,
+                            attemptNo: shipment.attemptNo,
+                            status: shipment.status,
+                        },
+                    });
+                }
+                if (this.events) {
+                    this.events.emit('shipment.created.v1', {
+                        eventId: randomUUID(),
+                        occurredAt: new Date().toISOString(),
+                        orderId,
+                        shipmentId: shipment.id,
+                        deliveryMethodId: order.deliveryMethodId,
+                        adapter: adapterKey,
+                        attemptNo: shipment.attemptNo,
+                        status: shipment.status,
+                    });
+                }
+                return { shipment, adapterKey };
+            });
+        };
+        const result = this.events ? await this.events.run(run) : await run();
+        return result.shipment;
+    }
+    /**
+     * The order's shipment attempts — for the admin panel.
+     *
+     * The `orderRead` call is the tenant boundary, not a convenience: `Shipment`
+     * is `@GlobalEntity`, so `em.find(Shipment, { orderId })` carries no filter
+     * and answers for every order on the platform, while `Order` is `@OrgScoped`
+     * and this port reads it through a filtered EntityManager. An
+     * assignment-scoped administrator therefore gets `null` here and no tracking
+     * number from an organization they are not assigned to.
+     *
+     * `createShipment` above has always made this read for its own reasons and so
+     * was never exposed; this one had no reason to make it, which is exactly how
+     * the gap arrived. 404 rather than 403 — an out-of-scope order must read the
+     * same as one that is not there.
+     */
+    async listForOrder(orderId) {
+        const order = await this.orderRead.findById(orderId);
+        if (!order) {
+            throw new HttpError(404, ERROR_CODES.ORDER_NOT_FOUND, 'Order not found.');
+        }
+        const em = this.emFactory();
+        return em.find(Shipment, { orderId }, { orderBy: { attemptNo: 'asc' } });
+    }
+}
+//# sourceMappingURL=shipment-service.js.map

package/dist/backend/services/shipment-service.js.map

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

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

@@ -0,0 +1,23 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { ShipmentUsagePort } from '@endora-commerce/contracts';
+/**
+ * The read behind `shipmentUsagePort` — see the port's contract for why the
+ * question belongs to this module and what its caller does when the module is
+ * off (feature 075, the `delivery_methods` shard).
+ *
+ * One `count`, on this module's own `EntityManager`. Deliberately not a method
+ * on {@link ShipmentService}: that service opens shipment attempts and calls
+ * carriers, and a delete guard has no business resolving an adapter registry,
+ * an order port and a delivery-method port to ask how many rows exist.
+ */
+export declare class ShipmentUsageService implements ShipmentUsagePort {
+    private readonly emFactory;
+    constructor(emFactory: () => EntityManager);
+    /**
+     * Every status counts, `failure` and `pending_manual` included: a failed
+     * attempt is still history an operator can open, and it still names the
+     * method it was attempted with.
+     */
+    countForDeliveryMethod(deliveryMethodId: string): Promise<number>;
+}
+//# sourceMappingURL=shipment-usage.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-usage.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/shipment-usage.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM,aAAa;IAE3D;;;;OAIG;IACG,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGxE"}

package/dist/backend/services/shipment-usage.service.js

@@ -0,0 +1,26 @@
+import { Shipment } from '../entities/shipment.entity.js';
+/**
+ * The read behind `shipmentUsagePort` — see the port's contract for why the
+ * question belongs to this module and what its caller does when the module is
+ * off (feature 075, the `delivery_methods` shard).
+ *
+ * One `count`, on this module's own `EntityManager`. Deliberately not a method
+ * on {@link ShipmentService}: that service opens shipment attempts and calls
+ * carriers, and a delete guard has no business resolving an adapter registry,
+ * an order port and a delivery-method port to ask how many rows exist.
+ */
+export class ShipmentUsageService {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    /**
+     * Every status counts, `failure` and `pending_manual` included: a failed
+     * attempt is still history an operator can open, and it still names the
+     * method it was attempted with.
+     */
+    async countForDeliveryMethod(deliveryMethodId) {
+        return this.emFactory().count(Shipment, { deliveryMethodId });
+    }
+}
+//# sourceMappingURL=shipment-usage.service.js.map

package/dist/backend/services/shipment-usage.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipment-usage.service.js","sourceRoot":"","sources":["../../../src/backend/services/shipment-usage.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D;;;;OAIG;IACH,KAAK,CAAC,sBAAsB,CAAC,gBAAwB;QACnD,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAChE,CAAC;CACF"}

package/dist/backend/services/shipping-email-renderer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shipping-method renderer registry for the transactional order-confirmation
+ * e-mail (feature 035, FR-016/FR-017). An adapter may register a custom e-mail
+ * renderer under a key (the adapter's `renderers.email`); when none is
+ * registered, the platform default text builder is used, so the shipping
+ * section always renders.
+ *
+ * E-mail bodies are plain text (see Mailer.MailerSendInput.text), so a renderer
+ * is a `(ctx) => string` builder rather than a React component.
+ */
+export interface ShippingEmailContext {
+    /** Resolved display name of the shipping method. */
+    name: string;
+    /** Flat surcharge (`price`) applied for this method (order currency). */
+    cost: number;
+    currency: string;
+}
+export type ShippingEmailRenderer = (ctx: ShippingEmailContext) => string;
+export declare const defaultShippingEmailRenderer: ShippingEmailRenderer;
+export declare function registerShippingEmailRenderer(key: string, renderer: ShippingEmailRenderer): void;
+export declare function resolveShippingEmailRenderer(rendererKey: string | null): ShippingEmailRenderer;
+//# sourceMappingURL=shipping-email-renderer.d.ts.map

package/dist/backend/services/shipping-email-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-email-renderer.d.ts","sourceRoot":"","sources":["../../../src/backend/services/shipping-email-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,MAAM,CAAC;AAE1E,eAAO,MAAM,4BAA4B,EAAE,qBACa,CAAC;AAIzD,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAEhG;AAED,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,qBAAqB,CAM9F"}

package/dist/backend/services/shipping-email-renderer.js

@@ -0,0 +1,14 @@
+export const defaultShippingEmailRenderer = (ctx) => `${ctx.name} — ${ctx.cost.toFixed(2)} ${ctx.currency}`;
+const registry = new Map();
+export function registerShippingEmailRenderer(key, renderer) {
+    registry.set(key, renderer);
+}
+export function resolveShippingEmailRenderer(rendererKey) {
+    if (rendererKey) {
+        const found = registry.get(rendererKey);
+        if (found)
+            return found;
+    }
+    return defaultShippingEmailRenderer;
+}
+//# sourceMappingURL=shipping-email-renderer.js.map

package/dist/backend/services/shipping-email-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-email-renderer.js","sourceRoot":"","sources":["../../../src/backend/services/shipping-email-renderer.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,4BAA4B,GAA0B,CAAC,GAAG,EAAE,EAAE,CACzE,GAAG,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE1D,MAAM,UAAU,6BAA6B,CAAC,GAAW,EAAE,QAA+B;IACxF,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,WAA0B;IACrE,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACxC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,200 @@
+export declare const shipmentsSettingsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+/**
+ * Shipments module (feature 035) — the Shipment entity and its
+ * generate/receive lifecycle. The delivery-side twin of `payments`.
+ *
+ * Generating is also retrying (FR-024): a second call after a failure appends
+ * attempt n+1 and asks the carrier for it. The separate retry route that used
+ * to sit beside it was deleted by issue #257 — it opened the row and asked
+ * nobody.
+ *
+ * The shipping-method *catalog* (adapter registry, reconciler, eligibility)
+ * lives in the sibling `delivery_methods` module; this module owns the
+ * first-class Shipment record and the `receive_shipment` ingress. Since feature
+ * 072 (T124) it registers its own services and routes through `backend.ts`;
+ * before that `orders/plugin.ts` constructed and mounted them, which is why
+ * switching this module off used to do nothing. No install/uninstall hook —
+ * schema is owned by migration 052.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;CAcpC,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BnB,CAAC"}