@endora-commerce/mod-shipments 0.100.0

package/dist/manifest.js

@@ -0,0 +1,63 @@
+import { defineModuleManifest, defineModuleSettingsManifest } from '@endora-commerce/contracts';
+export const shipmentsSettingsManifest = defineModuleSettingsManifest({
+    moduleCode: 'shipments',
+    groups: [{ code: 'shipments', name: 'Shipments' }],
+    settings: [
+        {
+            code: 'shipments.enabled',
+            name: 'Shipments enabled',
+            description: 'Switches the shipment lifecycle on or off: creating a shipment for an order (which is also how a failed one is retried), the carrier receive_shipment ingress and the per-order shipment history. Nothing is dropped — every shipment, its status transitions and its carrier references stay in the database, and an order mid-fulfilment resumes exactly where it was.',
+            groupCode: 'shipments',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+    ],
+});
+/**
+ * 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 const manifest = defineModuleManifest({
+    id: 'shipments',
+    docs: { dir: 'docs' },
+    name: 'Shipments',
+    description: 'Shipment record and the order_created / shipment_created / receive_shipment lifecycle.',
+    version: '1.0.0',
+    // Feature 075 Phase C — `customer_accounts` joins the three that were already
+    // here: the shipment-created e-mail resolves its recipient over
+    // `customerAccountReadPort` instead of reading the `CustomerAccount` entity.
+    dependencies: [
+        'customer_accounts',
+        'delivery_methods',
+        'orders',
+        'transactional_emails',
+    ],
+    // Feature 073 (Constitution XVII) — the operator's activation control. It
+    // only became real in T124: until this module registered its own routes there
+    // was no seam for a gate to sit on.
+    activation: { settingCode: 'shipments.enabled', default: true },
+    settings: shipmentsSettingsManifest,
+    // Feature 047 — admin-editable transactional email owned by this module.
+    transactionalEmails: [
+        {
+            code: 'shipment_created',
+            name: 'Shipment created',
+            group: 'shipments',
+            variables: [{ key: 'order.businessId', label: 'Order number', sampleValue: 'ORD-1042' }],
+        },
+    ],
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAEhG,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC;IACpE,UAAU,EAAE,WAAW;IACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAClD,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,mBAAmB;YACzB,IAAI,EAAE,mBAAmB;YACzB,WAAW,EACT,0WAA0W;YAC5W,SAAS,EAAE,WAAW;YACtB,SAAS,EAAE,SAAS;YACpB,YAAY,EAAE,IAAI;SACnB;KACF;CACF,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,WAAW;IACf,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,wFAAwF;IACrG,OAAO,EAAE,OAAO;IAChB,8EAA8E;IAC9E,gEAAgE;IAChE,6EAA6E;IAC7E,YAAY,EAAE;QACZ,mBAAmB;QACnB,kBAAkB;QAClB,QAAQ;QACR,sBAAsB;KACvB;IACD,0EAA0E;IAC1E,8EAA8E;IAC9E,oCAAoC;IACpC,UAAU,EAAE,EAAE,WAAW,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC/D,QAAQ,EAAE,yBAAyB;IACnC,yEAAyE;IACzE,mBAAmB,EAAE;QACnB;YACE,IAAI,EAAE,kBAAkB;YACxB,IAAI,EAAE,kBAAkB;YACxB,KAAK,EAAE,WAAW;YAClB,SAAS,EAAE,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;SACzF;KACF;CACF,CAAC,CAAC"}

package/dist/migrations/20260817T194652_shipments_order_fk.d.ts

@@ -0,0 +1,32 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `shipments.order_id` gains the foreign key it never had (D-90).
+ *
+ * `receive-shipment-handler.ts` moves the shipment row and the order's status
+ * inside one `em.transactional`, so a carrier callback records both or neither.
+ * D-78 point 2 rules such a seam permanent — kept on the caller's
+ * `EntityManager` and *declared* — and what makes the declaration honest is a
+ * constraint. `payments` has carried exactly that since the core commerce init
+ * (`payments_order_fk`, `on delete restrict`); this column was created with a
+ * primary key, a status check and two indexes and no constraint at all
+ * (`delivery_methods/migrations/20260611T140354_…`, which is also why the module
+ * that owns the entity has never owned its schema).
+ *
+ * `on delete restrict` for the same reason `payments` uses it: an order with
+ * shipments against it is not a row anyone should be able to delete out from
+ * under them.
+ *
+ * The table accepted unconstrained `order_id`s from 2026-06-11 until this
+ * migration, so the constraint is preceded by an explicit orphan report. An
+ * operator whose data has orphans gets a sentence naming the count and the
+ * first ten values, not a bare `23503` from Postgres — the orphans are a data
+ * question with a name, not a migration that will not apply.
+ *
+ * `shipments` already declares `orders` in its manifest `dependencies`, so this
+ * adds no edge to the module graph and nothing to the migration order.
+ */
+export declare class Migration20260817T194652ShipmentsOrderFk extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260817T194652_shipments_order_fk.d.ts.map

package/dist/migrations/20260817T194652_shipments_order_fk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260817T194652_shipments_order_fk.d.ts","sourceRoot":"","sources":["../../src/migrations/20260817T194652_shipments_order_fk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,wCAAyC,SAAQ,SAAS;IACtD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260817T194652_shipments_order_fk.js

@@ -0,0 +1,66 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `shipments.order_id` gains the foreign key it never had (D-90).
+ *
+ * `receive-shipment-handler.ts` moves the shipment row and the order's status
+ * inside one `em.transactional`, so a carrier callback records both or neither.
+ * D-78 point 2 rules such a seam permanent — kept on the caller's
+ * `EntityManager` and *declared* — and what makes the declaration honest is a
+ * constraint. `payments` has carried exactly that since the core commerce init
+ * (`payments_order_fk`, `on delete restrict`); this column was created with a
+ * primary key, a status check and two indexes and no constraint at all
+ * (`delivery_methods/migrations/20260611T140354_…`, which is also why the module
+ * that owns the entity has never owned its schema).
+ *
+ * `on delete restrict` for the same reason `payments` uses it: an order with
+ * shipments against it is not a row anyone should be able to delete out from
+ * under them.
+ *
+ * The table accepted unconstrained `order_id`s from 2026-06-11 until this
+ * migration, so the constraint is preceded by an explicit orphan report. An
+ * operator whose data has orphans gets a sentence naming the count and the
+ * first ten values, not a bare `23503` from Postgres — the orphans are a data
+ * question with a name, not a migration that will not apply.
+ *
+ * `shipments` already declares `orders` in its manifest `dependencies`, so this
+ * adds no edge to the module graph and nothing to the migration order.
+ */
+export class Migration20260817T194652ShipmentsOrderFk extends Migration {
+    async up() {
+        this.addSql(`
+      do $$
+      declare
+        orphan_count bigint;
+        sample text;
+      begin
+        select count(*) into orphan_count
+          from "shipments" s
+          left join "orders" o on o."id" = s."order_id"
+         where o."id" is null;
+
+        if orphan_count > 0 then
+          select string_agg(x."order_id"::text, ', ') into sample
+            from (
+              select distinct s."order_id"
+                from "shipments" s
+                left join "orders" o on o."id" = s."order_id"
+               where o."id" is null
+               limit 10
+            ) x;
+          raise exception
+            'shipments_order_fk cannot be added: % orphaned shipments.order_id value(s) reference no orders row (first ten: %). Delete those shipments or restore the missing orders, then re-run the migration.',
+            orphan_count, sample;
+        end if;
+      end $$;
+    `);
+        this.addSql(`
+      alter table "shipments"
+        add constraint "shipments_order_fk" foreign key ("order_id")
+          references "orders" ("id") on delete restrict;
+    `);
+    }
+    async down() {
+        this.addSql(`alter table "shipments" drop constraint if exists "shipments_order_fk";`);
+    }
+}
+//# sourceMappingURL=20260817T194652_shipments_order_fk.js.map

package/dist/migrations/20260817T194652_shipments_order_fk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260817T194652_shipments_order_fk.js","sourceRoot":"","sources":["../../src/migrations/20260817T194652_shipments_order_fk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,wCAAyC,SAAQ,SAAS;IAC5D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;KAyBX,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,yEAAyE,CAAC,CAAC;IACzF,CAAC;CACF"}

package/dist/migrations/20260819T171006_shipments_status_pending_manual.d.ts

@@ -0,0 +1,19 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `shipments.status` gains `pending_manual` (issue #250).
+ *
+ * A shipment opened while the module contributing its carrier adapter is not
+ * present was written as `pending` and was then indistinguishable from a
+ * shipment the carrier had actually been asked for. The fourth value is what
+ * makes that row say so; the check constraint is what keeps the set of values
+ * a single decision instead of a convention.
+ *
+ * The constraint was created by `delivery_methods` when this table was still
+ * part of that module's schema; the table has been `shipments`' own since the
+ * `shipments_order_fk` migration, so the widening belongs here.
+ */
+export declare class Migration20260819T171006ShipmentsStatusPendingManual extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260819T171006_shipments_status_pending_manual.d.ts.map

package/dist/migrations/20260819T171006_shipments_status_pending_manual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260819T171006_shipments_status_pending_manual.d.ts","sourceRoot":"","sources":["../../src/migrations/20260819T171006_shipments_status_pending_manual.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,qBAAa,oDAAqD,SAAQ,SAAS;IAClE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAYrC"}

package/dist/migrations/20260819T171006_shipments_status_pending_manual.js

@@ -0,0 +1,32 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `shipments.status` gains `pending_manual` (issue #250).
+ *
+ * A shipment opened while the module contributing its carrier adapter is not
+ * present was written as `pending` and was then indistinguishable from a
+ * shipment the carrier had actually been asked for. The fourth value is what
+ * makes that row say so; the check constraint is what keeps the set of values
+ * a single decision instead of a convention.
+ *
+ * The constraint was created by `delivery_methods` when this table was still
+ * part of that module's schema; the table has been `shipments`' own since the
+ * `shipments_order_fk` migration, so the widening belongs here.
+ */
+export class Migration20260819T171006ShipmentsStatusPendingManual extends Migration {
+    async up() {
+        this.addSql(`alter table "shipments" drop constraint if exists "shipments_status_check";`);
+        this.addSql(`alter table "shipments" add constraint "shipments_status_check" ` +
+            `check ("status" in ('pending', 'pending_manual', 'success', 'failure'));`);
+    }
+    async down() {
+        // A rollback removes the vocabulary, not the rows. `pending_manual` folds
+        // back to `pending`, which is where those shipments sat before this
+        // migration and is the only pre-existing value that still describes them:
+        // they are open, and nothing was rejected.
+        this.addSql(`update "shipments" set "status" = 'pending' where "status" = 'pending_manual';`);
+        this.addSql(`alter table "shipments" drop constraint if exists "shipments_status_check";`);
+        this.addSql(`alter table "shipments" add constraint "shipments_status_check" ` +
+            `check ("status" in ('pending', 'success', 'failure'));`);
+    }
+}
+//# sourceMappingURL=20260819T171006_shipments_status_pending_manual.js.map

package/dist/migrations/20260819T171006_shipments_status_pending_manual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260819T171006_shipments_status_pending_manual.js","sourceRoot":"","sources":["../../src/migrations/20260819T171006_shipments_status_pending_manual.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,oDAAqD,SAAQ,SAAS;IACxE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,6EAA6E,CAAC,CAAC;QAC3F,IAAI,CAAC,MAAM,CACT,kEAAkE;YAChE,0EAA0E,CAC7E,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,0EAA0E;QAC1E,oEAAoE;QACpE,0EAA0E;QAC1E,2CAA2C;QAC3C,IAAI,CAAC,MAAM,CAAC,gFAAgF,CAAC,CAAC;QAC9F,IAAI,CAAC,MAAM,CAAC,6EAA6E,CAAC,CAAC;QAC3F,IAAI,CAAC,MAAM,CACT,kEAAkE;YAChE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * **Two classes, listed in ascending timestamp, and both stamped after
+ * `BASELINE_THROUGH`** — so they are ordered by the manifest `dependencies`
+ * graph rather than by the frozen historical prefix, and this is one of the two
+ * modules in the first batch where that path actually runs. A timestamp orders
+ * this module's own migrations and nothing else (feature 081):
+ * `…T194652_shipments_order_fk` adds `shipments.order_id -> orders.id`, and what
+ * puts this block after `orders`' is `shipments`' manifest `dependencies`, never
+ * the stamp. A foreign key needs the **table**, never the owner's entity class
+ * (D-169), which is what lets that constraint stand while `./backend` publishes
+ * no entity class by name.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260817T194652ShipmentsOrderFk } from './20260817T194652_shipments_order_fk.js';
+import { Migration20260819T171006ShipmentsStatusPendingManual } from './20260819T171006_shipments_status_pending_manual.js';
+export declare const migrations: (typeof Migration20260817T194652ShipmentsOrderFk)[];
+export { Migration20260817T194652ShipmentsOrderFk, Migration20260819T171006ShipmentsStatusPendingManual, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,wCAAwC,EAAE,MAAM,yCAAyC,CAAC;AACnG,OAAO,EAAE,oDAAoD,EAAE,MAAM,sDAAsD,CAAC;AAE5H,eAAO,MAAM,UAAU,qDAGtB,CAAC;AAEF,OAAO,EACL,wCAAwC,EACxC,oDAAoD,GACrD,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,38 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * **Two classes, listed in ascending timestamp, and both stamped after
+ * `BASELINE_THROUGH`** — so they are ordered by the manifest `dependencies`
+ * graph rather than by the frozen historical prefix, and this is one of the two
+ * modules in the first batch where that path actually runs. A timestamp orders
+ * this module's own migrations and nothing else (feature 081):
+ * `…T194652_shipments_order_fk` adds `shipments.order_id -> orders.id`, and what
+ * puts this block after `orders`' is `shipments`' manifest `dependencies`, never
+ * the stamp. A foreign key needs the **table**, never the owner's entity class
+ * (D-169), which is what lets that constraint stand while `./backend` publishes
+ * no entity class by name.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260817T194652ShipmentsOrderFk } from './20260817T194652_shipments_order_fk.js';
+import { Migration20260819T171006ShipmentsStatusPendingManual } from './20260819T171006_shipments_status_pending_manual.js';
+export const migrations = [
+    Migration20260817T194652ShipmentsOrderFk,
+    Migration20260819T171006ShipmentsStatusPendingManual,
+];
+export { Migration20260817T194652ShipmentsOrderFk, Migration20260819T171006ShipmentsStatusPendingManual, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,wCAAwC,EAAE,MAAM,yCAAyC,CAAC;AACnG,OAAO,EAAE,oDAAoD,EAAE,MAAM,sDAAsD,CAAC;AAE5H,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,wCAAwC;IACxC,oDAAoD;CACrD,CAAC;AAEF,OAAO,EACL,wCAAwC,EACxC,oDAAoD,GACrD,CAAC"}

package/docs/shipments.md

@@ -0,0 +1,96 @@
+---
+title: shipments
+description: The retryable Shipment record and its lifecycle — the delivery-side twin of payments
+---
+
+# `shipments`
+
+The `Shipment` record and its lifecycle. The
+delivery-side twin of `payments`: the shipping-method *catalog* and adapter
+registry live in [`delivery_methods`](./delivery_methods.md); this module owns
+the first-class, retryable `Shipment` and the `receive_shipment` ingress.
+
+## Entity
+
+`Shipment` — one shipment-generation attempt against an Order:
+`orderId`, `deliveryMethodId`, `status` (`pending` → `success` | `failure`, plus
+`pending_manual`), `externalReference`, `providerDetails` (JSONB),
+`failureReason`, `attemptNo`, timestamps. An Order may have many Shipments
+(failed-generation retries; a future split into multiple parcels). The `status`
+here is the shipment-process status, distinct from the Order status the method
+maps to.
+
+### `pending_manual` — the carrier was never asked
+
+A shipment opens `pending_manual` when the adapter its delivery method names is
+contributed by a module that is **not present** — switched off by the operator,
+or not available in this deployment. The registry filters that adapter out at
+enumeration (the contribution-point policy), so nothing is sent: no label,
+no tracking number, no pickup. The row records what happened rather than looking
+like every other shipment:
+
+- `status = 'pending_manual'`, which is the same word — and the same instruction
+  to the same operator — as a refund the platform could not settle automatically: *a human has to finish this*;
+- `failureReason` names the module, e.g. `The "my_carrier" 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.`;
+- an audit entry `shipment.carrier_not_contacted` on the shipment, written
+  co-transactionally with the row;
+- **no** `shipment_created` e-mail. The notifier answers
+  `{ sent: false, reason: 'carrier_not_contacted' }` and logs it — telling a
+  buyer their order has shipped when nothing was handed to anyone is worse than
+  telling them nothing, and it is not a message anyone can take back.
+
+It is deliberately **not** `failure` — nothing was rejected, because nothing was
+sent — and deliberately not plain `pending`, which means a carrier that knows
+about the shipment has yet to report back.
+
+A delivery method whose adapter key **nobody ever contributed** is untouched: it
+keeps opening `pending`, because there is no module to switch on and an offline
+method has always been finished by hand. The two are told apart by
+`ShippingAdapterRegistry.absentOwnerFor`, not by `get()` — which answers
+`undefined` for both.
+
+**Recovery is an operator action, not an automatic sweep.** Switching the module
+back on changes nothing about the shipments already opened; the operator
+generates the shipment again (`POST /api/v1/admin/orders/:id/shipments`), which
+appends a new attempt and asks the carrier. Reacting to the activation setting
+would mean the platform calling a carrier for parcels an operator may already
+have handled by hand, without anyone asking it to. The Delivery tab of the order
+surfaces the state, the reason and the button.
+
+There used to be a second endpoint here, `POST .../shipments/retry`, and it
+has been deleted: it appended attempt n+1 and contacted no adapter in any state,
+so an operator who used it got a fresh `pending` row that nothing had been asked
+about. Retrying **is** generating again — the generate endpoint appends the next
+attempt, refuses only once one has succeeded, and asks the carrier for it.
+
+## Lifecycle
+
+| Event | Trigger | Effect |
+| --- | --- | --- |
+| `order_created` | Order created (storefront / admin / API) | The shipping adapter's `onOrderCreated` fires. Offline adapters are no-ops; **no** Shipment is opened here. |
+| `shipment_created` | Admin "Generate shipment" / API | A `pending` Shipment is opened (`attemptNo = max+1`); the adapter's `onShipmentCreated` runs; `shipment.created.v1` is emitted, carrying the state the row opened in. With the adapter's module absent the row opens `pending_manual` and no adapter is called — see above. |
+| `receive_shipment` | Carrier/adapter ingress | The Shipment is resolved; the Order moves to the method's `statusOnSuccess` / `statusOnFailure`; `shipment.received.v1` / `shipment.failed.v1` is emitted. |
+
+`receive_shipment` is **idempotent**: a success after a terminal `success` is a
+no-op; a failure after success is rejected (409, no downgrade); a missing /
+already-resolved reference is rejected without corrupting records. A failed
+generation is retried by generating again, which opens the next Shipment attempt
+and asks the carrier for it, leaving prior attempts intact.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `POST /api/v1/admin/orders/:id/shipments` | admin (`orders:write`) | Generate a shipment (`shipment_created`) — and retry a failed one, by generating the next attempt |
+| `GET /api/v1/admin/orders/:id/shipments` | admin (`orders:read`) | Full shipment history for the order |
+| `POST /api/v1/shipments/receive` | adapter/carrier ingress (admin-guarded for MVP) | `receive_shipment` outcome ingress |
+
+## Order-status mapping
+
+On a `receive_shipment` outcome the handler writes `orders.status` directly
+(bypassing the `transitionStatus` state graph) to the method's `statusOnSuccess`
+/ `statusOnFailure`, validated through the `OrderStatusRegistry` port owned by
+`delivery_methods`. Emitted events flow on the in-process `EventBus` inside the
+handler's transactional scope, so a rolled-back transaction never dispatches.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@endora-commerce/mod-shipments",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Shipment record and the order_created / shipment_created / receive_shipment lifecycle.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "shipments"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/shipments"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "fastify": "^5.12.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}