@endora-commerce/mod-delivery-methods 0.100.0

package/dist/migrations/20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js

@@ -0,0 +1,72 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Shipping-method adapter framework + Shipment record (feature 035 — Metoda
+ * Dostawy).
+ *
+ * Extends the existing `delivery_methods` entry into a configurable,
+ * adapter-backed shipping method and introduces the `shipments` record:
+ *
+ *   delivery_methods:
+ *     + adapter            — registry key of the ShippingAdapter realising the
+ *                            logic (backfilled from the existing `code`)
+ *     + status_on_success  — Order-status reference applied on a successful
+ *                            shipment generation (seed `shipped`)
+ *     + status_on_failure  — Order-status reference applied on a failed
+ *                            shipment generation (seed `in_fulfilment`)
+ *
+ *   shipments (new):
+ *     a first-class generation attempt against an Order — order_id,
+ *     delivery_method_id, status (pending|success|failure), external_reference,
+ *     provider_details, failure_reason, attempt_no, timestamps.
+ *
+ * `price` reuses the existing `delivery_methods.cost` column (no new column).
+ * Seed status mappings reuse the current hard-coded order `status` enum until
+ * the Orders module ships a configurable registry (see research.md R3/R10).
+ */
+export class Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments extends Migration {
+    async up() {
+        // delivery_methods — add nullable, backfill, then tighten to NOT NULL.
+        // `adapter` carries a NOT NULL DEFAULT '' so that generic insert paths that
+        // predate the framework (sales-channel/membership fixtures, legacy seeds)
+        // keep working: a row with an empty adapter is simply not selectable — it
+        // never resolves to a registered adapter (FR-003) — while adapter-backed
+        // rows always set it explicitly.
+        this.addSql(`
+      alter table "delivery_methods"
+        add column "adapter" varchar(64) not null default '',
+        add column "status_on_success" varchar(64) not null default 'shipment_sent',
+        add column "status_on_failure" varchar(64) not null default 'processing';
+    `);
+        // Backfill existing rows: adapter mirrors the existing code.
+        this.addSql(`update "delivery_methods" set "adapter" = "code" where "adapter" = '';`);
+        // shipments — first-class shipment-generation attempt record.
+        this.addSql(`
+      create table "shipments" (
+        "id" uuid not null,
+        "order_id" uuid not null,
+        "delivery_method_id" uuid not null,
+        "status" varchar(32) not null default 'pending',
+        "external_reference" varchar(255) null,
+        "provider_details" jsonb null,
+        "failure_reason" text null,
+        "attempt_no" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "shipments_pkey" primary key ("id"),
+        constraint "shipments_status_check" check ("status" in ('pending', 'success', 'failure'))
+      );
+    `);
+        this.addSql(`create index "shipments_order_id_index" on "shipments" ("order_id");`);
+        this.addSql(`create index "shipments_status_index" on "shipments" ("status");`);
+    }
+    async down() {
+        this.addSql(`drop table if exists "shipments";`);
+        this.addSql(`
+      alter table "delivery_methods"
+        drop column "adapter",
+        drop column "status_on_success",
+        drop column "status_on_failure";
+    `);
+    }
+}
+//# sourceMappingURL=20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js.map

package/dist/migrations/20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js","sourceRoot":"","sources":["../../src/migrations/20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,yEAA0E,SAAQ,SAAS;IAC7F,KAAK,CAAC,EAAE;QACf,uEAAuE;QACvE,4EAA4E;QAC5E,0EAA0E;QAC1E,0EAA0E;QAC1E,yEAAyE;QACzE,iCAAiC;QACjC,IAAI,CAAC,MAAM,CAAC;;;;;KAKX,CAAC,CAAC;QACH,6DAA6D;QAC7D,IAAI,CAAC,MAAM,CAAC,wEAAwE,CAAC,CAAC;QAEtF,8DAA8D;QAC9D,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;KAeX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,sEAAsE,CAAC,CAAC;QACpF,IAAI,CAAC,MAAM,CAAC,kEAAkE,CAAC,CAAC;IAClF,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,mCAAmC,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC;;;;;KAKX,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.d.ts

@@ -0,0 +1,24 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Fix the built-in in-person pickup delivery method's adapter binding.
+ *
+ * Migration 052 introduced the adapter framework and backfilled every existing
+ * `delivery_methods` row with `adapter = code`. For the platform's bundled
+ * in-person pickup method (code `in_person_pickup`) this produced the adapter
+ * key `in_person_pickup`, which is NOT a registered ShippingAdapter — the
+ * bundled pickup adapter registers under `personal_pickup`
+ * (`built-in-adapters.ts`). As a result the eligibility filter
+ * (`shipping-method-eligibility.ts`) silently dropped the method from every
+ * storefront checkout, since an unregistered-adapter row never resolves
+ * (FR-003).
+ *
+ * The dev seed already pairs `in_person_pickup` with the `personal_pickup`
+ * adapter for fresh installs; this migration repoints any pre-existing,
+ * backfilled rows to the same registered adapter so the pickup method becomes
+ * selectable at checkout.
+ */
+export declare class Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260611T140416_delivery_methods_fix_in_person_pickup_adapter.d.ts.map

package/dist/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140416_delivery_methods_fix_in_person_pickup_adapter.d.ts","sourceRoot":"","sources":["../../src/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,+DAAgE,SAAQ,SAAS;IAC7E,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}

package/dist/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js

@@ -0,0 +1,28 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Fix the built-in in-person pickup delivery method's adapter binding.
+ *
+ * Migration 052 introduced the adapter framework and backfilled every existing
+ * `delivery_methods` row with `adapter = code`. For the platform's bundled
+ * in-person pickup method (code `in_person_pickup`) this produced the adapter
+ * key `in_person_pickup`, which is NOT a registered ShippingAdapter — the
+ * bundled pickup adapter registers under `personal_pickup`
+ * (`built-in-adapters.ts`). As a result the eligibility filter
+ * (`shipping-method-eligibility.ts`) silently dropped the method from every
+ * storefront checkout, since an unregistered-adapter row never resolves
+ * (FR-003).
+ *
+ * The dev seed already pairs `in_person_pickup` with the `personal_pickup`
+ * adapter for fresh installs; this migration repoints any pre-existing,
+ * backfilled rows to the same registered adapter so the pickup method becomes
+ * selectable at checkout.
+ */
+export class Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter extends Migration {
+    async up() {
+        this.addSql(`update "delivery_methods" set "adapter" = 'personal_pickup' where "code" = 'in_person_pickup' and "adapter" = 'in_person_pickup';`);
+    }
+    async down() {
+        this.addSql(`update "delivery_methods" set "adapter" = 'in_person_pickup' where "code" = 'in_person_pickup' and "adapter" = 'personal_pickup';`);
+    }
+}
+//# sourceMappingURL=20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js.map

package/dist/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js","sourceRoot":"","sources":["../../src/migrations/20260611T140416_delivery_methods_fix_in_person_pickup_adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,+DAAgE,SAAQ,SAAS;IACnF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CACT,mIAAmI,CACpI,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CACT,mIAAmI,CACpI,CAAC;IACJ,CAAC;CACF"}

package/dist/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.d.ts

@@ -0,0 +1,27 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `sales_channel_delivery_methods` sales-channel bridge — the delivery methods available in a channel.
+ *
+ * It was created by the platform's frozen `Migration20260430T170044CoreSalesChannelsPromote`
+ * until `specs/120-migration-closure-bridge-ownership/` Phase 2. Under D-226 a
+ * bridge between an always-present near side (`sales_channels`, a kernel table)
+ * and a switchable far side belongs to the far side, so this module creates it:
+ * an instance that does not install `delivery_methods` no longer has a migration corpus
+ * naming a table nothing builds.
+ *
+ * `if not exists`, because every database that has already applied the frozen
+ * migration has this table. The storage keys on the class name and holds no
+ * checksum, so nothing is re-offered there and this migration is the no-op it
+ * reads as; on a fresh database it is the creation.
+ *
+ * The statements are the frozen ones verbatim — same columns, same primary key,
+ * same two foreign keys, same index — so the two paths reach one schema. Its
+ * position needs nothing declared: `sales_channels` is the kernel's and
+ * `delivery_methods` is created inside the frozen prefix, which every
+ * above-watermark migration runs after.
+ */
+export declare class Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260912T094638_delivery_methods_sales_channel_delivery_methods.d.ts.map

package/dist/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T094638_delivery_methods_sales_channel_delivery_methods.d.ts","sourceRoot":"","sources":["../../src/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kEAAmE,SAAQ,SAAS;IAChF,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.js

@@ -0,0 +1,44 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `sales_channel_delivery_methods` sales-channel bridge — the delivery methods available in a channel.
+ *
+ * It was created by the platform's frozen `Migration20260430T170044CoreSalesChannelsPromote`
+ * until `specs/120-migration-closure-bridge-ownership/` Phase 2. Under D-226 a
+ * bridge between an always-present near side (`sales_channels`, a kernel table)
+ * and a switchable far side belongs to the far side, so this module creates it:
+ * an instance that does not install `delivery_methods` no longer has a migration corpus
+ * naming a table nothing builds.
+ *
+ * `if not exists`, because every database that has already applied the frozen
+ * migration has this table. The storage keys on the class name and holds no
+ * checksum, so nothing is re-offered there and this migration is the no-op it
+ * reads as; on a fresh database it is the creation.
+ *
+ * The statements are the frozen ones verbatim — same columns, same primary key,
+ * same two foreign keys, same index — so the two paths reach one schema. Its
+ * position needs nothing declared: `sales_channels` is the kernel's and
+ * `delivery_methods` is created inside the frozen prefix, which every
+ * above-watermark migration runs after.
+ */
+export class Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods extends Migration {
+    async up() {
+        this.addSql(`
+      create table if not exists "sales_channel_delivery_methods" (
+        "sales_channel_id" uuid not null,
+        "delivery_method_id" uuid not null,
+        constraint "sales_channel_delivery_methods_pkey"
+          primary key ("sales_channel_id", "delivery_method_id"),
+        constraint "sales_channel_delivery_methods_channel_fk"
+          foreign key ("sales_channel_id") references "sales_channels" ("id") on delete cascade,
+        constraint "sales_channel_delivery_methods_delivery_method_fk"
+          foreign key ("delivery_method_id") references "delivery_methods" ("id") on delete cascade
+      );
+    `);
+        this.addSql('create index if not exists "sales_channel_delivery_methods_delivery_method_id_index" ' +
+            'on "sales_channel_delivery_methods" ("delivery_method_id");');
+    }
+    async down() {
+        this.addSql('drop table if exists "sales_channel_delivery_methods" cascade;');
+    }
+}
+//# sourceMappingURL=20260912T094638_delivery_methods_sales_channel_delivery_methods.js.map

package/dist/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T094638_delivery_methods_sales_channel_delivery_methods.js","sourceRoot":"","sources":["../../src/migrations/20260912T094638_delivery_methods_sales_channel_delivery_methods.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,kEAAmE,SAAQ,SAAS;IACtF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;KAWX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,uFAAuF;YACrF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,gEAAgE,CAAC,CAAC;IAChF,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * 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 { Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments } from './20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js';
+import { Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter } from './20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js';
+import { Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods } from './20260912T094638_delivery_methods_sales_channel_delivery_methods.js';
+export declare const migrations: (typeof Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments)[];
+export { Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments, Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter, Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods, };
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yEAAyE,EAAE,MAAM,8EAA8E,CAAC;AACzK,OAAO,EAAE,+DAA+D,EAAE,MAAM,oEAAoE,CAAC;AACrJ,OAAO,EAAE,kEAAkE,EAAE,MAAM,sEAAsE,CAAC;AAE1J,eAAO,MAAM,UAAU,sFAItB,CAAC;AAEF,OAAO,EACL,yEAAyE,EACzE,+DAA+D,EAC/D,kEAAkE,GACnE,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,33 @@
+/**
+ * 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).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * 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 { Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments } from './20260611T140354_delivery_methods_shipping_methods_adapter_and_shipments.js';
+import { Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter } from './20260611T140416_delivery_methods_fix_in_person_pickup_adapter.js';
+import { Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods } from './20260912T094638_delivery_methods_sales_channel_delivery_methods.js';
+export const migrations = [
+    Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments,
+    Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter,
+    Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods,
+];
+export { Migration20260611T140354DeliveryMethodsShippingMethodsAdapterAndShipments, Migration20260611T140416DeliveryMethodsFixInPersonPickupAdapter, Migration20260912T094638DeliveryMethodsSalesChannelDeliveryMethods, };
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yEAAyE,EAAE,MAAM,8EAA8E,CAAC;AACzK,OAAO,EAAE,+DAA+D,EAAE,MAAM,oEAAoE,CAAC;AACrJ,OAAO,EAAE,kEAAkE,EAAE,MAAM,sEAAsE,CAAC;AAE1J,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yEAAyE;IACzE,+DAA+D;IAC/D,kEAAkE;CACnE,CAAC;AAEF,OAAO,EACL,yEAAyE,EACzE,+DAA+D,EAC/D,kEAAkE,GACnE,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The install-time seed surface `delivery_methods` publishes, and **nothing
+ * that exists at runtime** (feature 134, FR-064; D-168, D-169, D-171).
+ *
+ * `tsc` compiles this file to `export {};`. That is the property D-171 makes the
+ * boundary decision on — *a subpath is contract surface iff the module it
+ * resolves to exports no runtime binding* — so a consumer naming this subpath
+ * names a declaration and can name nothing else. The runtime half is one
+ * factory, `createDeliveryMethodSeeder`, on this package's `./backend`.
+ *
+ * ## Why this interface exists at all, and why it is here rather than in
+ * `packages/contracts`
+ *
+ * A module that ships its own carrier rows used to seed them with an `insert`
+ * into this module's table from its own migration — `inpost` and `dhl_parcel`
+ * each did, which is three `migration-foreign-writes` ledger keys and, **once a
+ * seeding module ships separately from the table's owner**, a hard schema
+ * dependency with no version range and no compile-time signal at all. That is
+ * the whole of the reason, and it holds for any pair of modules published from
+ * two places rather than for these two: an `insert` into a table another package
+ * owns is a dependency on that table's *shape*, and npm has no way to express
+ * one. The repair is that the seed is issued from the seeding module's
+ * `installHook` through this surface — **R11 / D-251 / FR-064**, the criterion
+ * any module may satisfy.
+ *
+ * It cannot live in `@endora-commerce/contracts`: every method takes a MikroORM
+ * `EntityManager`, that package is compiled by `admin` and `storefront`, and
+ * FR-034 keeps it free of `@mikro-orm` imports. That is exactly D-171's
+ * qualifying test — *does this signature stop the interface living in
+ * `packages/contracts`* — and it is why the `em` is a **required** first
+ * parameter on every method and never an optional one (D-169): an optional
+ * transactional `em` lets a caller hand a transaction to an implementation that
+ * ignores it and receive a silently non-atomic write.
+ *
+ * ## It carries no `Container name:` marker, deliberately
+ *
+ * This is not a container port and must not read as one. `ModuleLifecycleContext`
+ * is `{ em, redis, log, module }`, both orchestrator construction sites pass no
+ * container, and D-46 deleted `ctx.onInstall` because `module:install` composes
+ * nothing — so there is no cradle for a hook to resolve a name from, `lazyPort`
+ * is structurally unavailable here, and a documented container name would be a
+ * name nothing registers (`check:port-shape`'s signal 2, from the other side).
+ * The consumer's seam is the factory, not a resolution.
+ *
+ * ## No entity leaves by this door (D-168)
+ *
+ * {@link DeliveryMethodSeedRecord} is a published record and not the
+ * `DeliveryMethod` entity, type-only included. Handing a caller a managed entity
+ * hands it the ability to mutate a delivery method outside the seam, and to
+ * persist that change on whichever transaction it happens to hold.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql';
+/** The row values a seeding module supplies for its own delivery method. */
+export interface DeliveryMethodSeedDefaults {
+    /** Unique within `delivery_methods`; the seam's whole idempotence rests on it. */
+    code: string;
+    /** Translations by language tag, with a `default` key. */
+    name: Record<string, string>;
+    cost?: string;
+    currency?: string;
+    /**
+     * `'active'` when omitted. **Pass it explicitly when the module wants
+     * anything else**: `dhl_parcel` seeds `'inactive'`, and taking the default
+     * there would offer a shipping option to buyers that no operator chose
+     * (`foreign-write-repair.md` §2.4).
+     */
+    status?: 'active' | 'inactive';
+    statusOnSuccess?: string;
+    statusOnFailure?: string;
+}
+/** What the seam answers about a delivery method — a record, never the entity. */
+export interface DeliveryMethodSeedRecord {
+    readonly id: string;
+    readonly code: string;
+    readonly name: Record<string, string>;
+    readonly cost: string;
+    readonly currency: string;
+    readonly status: 'active' | 'inactive';
+    readonly adapter: string;
+    readonly statusOnSuccess: string;
+    readonly statusOnFailure: string;
+}
+/**
+ * Created-versus-found, which the caller needs and cannot derive.
+ *
+ * `created` is what a channel binding is guarded on: the seed binds **once, for
+ * the rows it creates**, and re-binding a method an operator deliberately
+ * unbound from every channel is issue #96 verbatim (`foreign-write-repair.md`
+ * §2.3).
+ */
+export interface DeliveryMethodSeedOutcome {
+    readonly row: DeliveryMethodSeedRecord;
+    readonly created: boolean;
+}
+export interface DeliveryMethodSeedApi {
+    /**
+     * Create this module's delivery-method row, or return the existing one
+     * untouched. Idempotent and prune-safe: a row matched by `code` keeps its
+     * admin-edited configuration and only a missing `adapter` link is backfilled.
+     */
+    ensureMethodForAdapter(em: EntityManager, adapterKey: string, defaults: DeliveryMethodSeedDefaults): Promise<DeliveryMethodSeedOutcome>;
+    /**
+     * Put the method in the system-default sales channel.
+     *
+     * **Call it only when `ensureMethodForAdapter` answered `created === true`.**
+     * Never as a reconcile: "unbound from every channel" is a state an operator is
+     * entitled to reach and to keep, and an unguarded call brings the method back
+     * with nothing saying so (issue #96).
+     *
+     * Answers whether a membership row was written — `false` when the method was
+     * already in that channel, and `false` when the platform has **no**
+     * system-default channel yet, which a database that has been migrated and never
+     * booted does not: the default channel is created at boot, and an install
+     * composes nothing. The row is then seeded and unbound, which is what the seed
+     * migration this replaced did in the same state.
+     */
+    bindToDefaultChannel(em: EntityManager, deliveryMethodId: string): Promise<boolean>;
+    /**
+     * Remove the method and, by cascade, its channel memberships.
+     *
+     * For a **hard** uninstall only (`if (!ctx.hard) return;`). A soft uninstall
+     * and a deactivation both keep the row: the registry filters the adapter's
+     * enumeration by its contributing module's effective state, so an off module
+     * is answered at the read and the operator's edits survive being switched back
+     * on (Principle XVII). Answers whether a row was removed.
+     */
+    removeMethodForAdapter(em: EntityManager, code: string): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kFAAkF;AAClF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,EAAE,wBAAwB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,sBAAsB,CACpB,EAAE,EAAE,aAAa,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,0BAA0B,GACnC,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpF;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E"}

package/dist/ports/index.js

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

package/dist/ports/index.js.map

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

package/docs/delivery_methods.md

@@ -0,0 +1,197 @@
+---
+title: delivery_methods
+description: Configured delivery options
+---
+
+# `delivery_methods`
+
+The platform's **shipping-method framework** (_Metoda Dostawy_).
+The module hosts a pluggable adapter registry over the delivery-method catalog,
+the delivery-side twin of `payment_methods`. The first-class `Shipment` record
+and its lifecycle live in the sibling [`shipments`](./shipments.md) module.
+Carrier integration modules register adapters into this framework. Which ones your
+instance has depends on what is installed, so they are named rather than linked
+here: a link to a sibling page is a broken link in every instance that does not
+install that module, which is what `onBrokenLinks: 'throw'` says about it.
+
+A delivery method is never hard-coded: the platform discovers methods from
+whichever **adapter modules** are installed and enabled. Enabling a recognised
+shipping-method adapter module auto-creates a configurable `delivery_methods`
+row visible at `/delivery-methods`.
+
+## Public surface
+
+Admin routes are gated by `delivery_methods:read` (reads) and
+`delivery_methods:write` (mutations) — the module's own codes since 2026-08-28.
+They were `catalog:read` / `catalog:write` until then, which meant whoever could
+edit a product could also decide how the shop ships, and delete a delivery
+method outright. A role that was relying on the catalogue codes for this screen
+has to be granted the new ones on `/admin-roles`; nothing grants them
+automatically, deliberately.
+
+| Verb + Path | Audience | Gate | Purpose |
+| --- | --- | --- | --- |
+| `GET /api/v1/delivery-methods` | anon | — | Eligible methods for the storefront checkout (active ∩ sales-channel ∩ Organization allow-list ∩ adapter registered ∩ `validateUseOnStorefront`) |
+| `GET /api/v1/admin/delivery-methods` | admin | `delivery_methods:read` | Full list with adapter, status mappings, sales channels, renderer key |
+| `PUT /api/v1/admin/delivery-methods/:code` | admin | `delivery_methods:write` | Upsert by code (name, cost/`price`, status, `statusOnSuccess`/`statusOnFailure`, sales channels) |
+| `DELETE /api/v1/admin/delivery-methods/:id` | admin | `delivery_methods:write` | Hard delete (guarded: rejected with 409 when a `Shipment` references the method — set status `inactive` instead) |
+
+The admin status selectors read their options from `GET /api/v1/admin/order-statuses`
+(owned by the payment-methods admin routes; shared `OrderStatusRegistry`). That
+route is gated `payment_methods:read` **or** `delivery_methods:read` — an any-of
+over the two editors that read it, so the code that opens this screen also opens
+its status selectors.
+
+## Entry fields
+
+A `delivery_methods` row carries: `code` (unique), `adapter` (registry key),
+per-language `name` (default + overrides), `cost` + `currency` (the `price`
+surcharge added to the order total), `status` (`active`/`inactive`),
+`statusOnSuccess` / `statusOnFailure` (Order-status references applied when
+shipment generation succeeds/fails). There is **no** `statusOnPending` and no
+`kind` column — a shipping method is identified by its `adapter` alone.
+
+`statusOnSuccess` / `statusOnFailure` reference Order statuses resolved through
+the `OrderStatusRegistry` port (enum-backed by the order `status` enum until the
+Orders module ships a configurable registry). Seed defaults: `shipped` /
+`in_fulfilment`.
+
+Sales-channel scoping reuses the generic `SalesChannelMembershipService`
+(`'delivery-method'`); per-Organization availability reuses
+`OrganizationRestrictionService` (`'delivery_method'`, opt-out blocklist).
+
+## How to build a shipping-method module
+
+A platform module is recognised as a shipping-method adapter **iff** it
+registers a `ShippingAdapter` in the process-wide `shippingAdapterRegistry`
+from its boot hook. No core change is required.
+
+1. **Implement the `ShippingAdapter` contract** (`@endora-commerce/contracts`):
+
+   ```ts
+   import type { ShippingAdapter } from '@endora-commerce/contracts';
+
+   export const myCarrierAdapter: ShippingAdapter = {
+     adapterKey: 'my_carrier',
+     // Extra conditions per surface; return a constant true when none apply.
+     validateUseOnStorefront: async () => true,
+     validateUseOnAdmin: async () => true,
+     validateUseInApi: async () => true,
+     // order_created: may start generation; safe to leave as a no-op.
+     onOrderCreated: async () => {},
+     // shipment_created: begin generation, return the next action.
+     onShipmentCreated: async () => ({ kind: 'pending' }),
+     // receive_shipment: map the ingress to a success/failure outcome.
+     onReceiveShipment: async (ctx) => ({
+       result: 'success',
+       externalReference: ctx.externalReference ?? null,
+     }),
+     // Optional renderer keys; absent ⇒ the platform default is used.
+     renderers: { storefront: 'my_carrier', email: 'my_carrier.email' },
+   };
+   ```
+
+2. **Contribute the adapter from the boot hook**, naming the owning module, and
+   ship the method row as a migration:
+
+   ```ts
+   import { shippingAdapterRegistry } from '.../delivery_methods/services/registry-singleton.js';
+
+   ctx.onBoot(() => {
+     shippingAdapterRegistry.register(myCarrierAdapter, 'my_carrier_module');
+   });
+   ```
+
+   The owner id is what lets the registry skip the adapter while its module is
+   absent, so a carrier an operator switches off stops being offered instead of
+   being offered and failing — the same defect the payment twin had, fixed on
+   both sides. The `delivery_methods` row itself is static reference data and
+   belongs in your module's migration; `DeliveryMethodReconciler` remains
+   available from an `installHook` for a row that must be created from code. No
+   uninstall hook is needed to withdraw the adapter — a module that is not
+   present is not enumerated.
+
+   The skip does not answer for an order **already placed** on your method: a
+   shipment can still be generated for it, and that shipment
+   opens `pending_manual` naming your module rather than reading like one you
+   accepted. You write no code for it — see *When the registry is read* below.
+
+   **Your hook pushes and returns.** It does not check what is already in the
+   table, does not check whether `delivery_methods` is present, and treats no
+   absence as an error — because nothing reads the registry while modules are
+   being composed. Boot hooks run whatever a module's effective state is; the
+   *enumeration* answers presence, not the registration. A throw in a boot hook
+   is not one adapter dropping out: `runBootHooks` re-throws it as
+   `ModuleCompositionError` and `index.ts` turns that into `process.exit(1)`, so
+   the operator's next start dies over a switch they were entitled to use. Nor
+   may a contributing hook probe `effectiveState` — the host already
+   filters at enumeration, and a probe at the push would make switching your
+   carrier back on require a restart. If your hook also *does work* (a
+   reconcile, a Redis or Postgres write), split it in two first: the working
+   half probes, the contributing half never does.
+
+3. **Optional renderers** — register custom renderers under the keys you
+   declared:
+   - Storefront: `registerShippingMethodRenderer(key, fn)` in
+     `storefront/lib/shipping-renderers/registry.tsx`.
+   - E-mail: `registerShippingEmailRenderer(key, fn)` in
+     `shipments/services/shipping-email-renderer.ts`.
+   When a renderer is missing for a surface, the platform default is used so the
+   method always renders.
+
+4. **Enable the module** from the admin module-lifecycle screen → a configurable
+   Delivery Method appears at `/delivery-methods`.
+
+The two bundled offline reference adapters — `manual_courier` (_Wysyłka własna_)
+and `personal_pickup` (_Odbiór osobisty_) — need no external carrier and are the
+worked example of the full lifecycle.
+
+## When the registry is read
+
+The `shippingAdapterRegistry` is a **process-wide singleton**
+(`delivery_methods/services/registry-singleton.ts`): one table of adapters per
+process, however many times the platform is composed. Contributions are pushed
+into it **once, during composition**. Every read of it happens **later, inside a
+request**:
+
+| Read | Where | What an absent adapter means there |
+| --- | --- | --- |
+| Storefront eligibility | `GET /api/v1/delivery-methods` → `ShippingMethodEligibilityService.filter` | the method is not offered |
+| Admin upsert guard | `PUT /api/v1/admin/delivery-methods/:code` → `isRegistered` | an explicitly supplied key nobody contributed is rejected (400); a contributed one whose owner is off is accepted, because the read is presence-blind on purpose |
+| Order placement | `orders` re-validates the chosen method, then fires `onOrderCreated` | a method whose owner is off answers 503 `MODULE_DISABLED`; an unregistered one skips the hook |
+| Shipment generation | `ShipmentService.create` → `onShipmentCreated` | the adapter hook is skipped and the `Shipment` opens **`pending_manual`** naming the absent module — never plain `pending`, which would read as a shipment the carrier had accepted |
+| Order-confirmation e-mail | the method's `renderers.email` key | the platform default renderer is used |
+
+Two things follow, and they are the reason this section exists rather than being
+left to be inferred. First, there is **no order to get right** between
+contributors: your adapter is visible to the first read whether it landed before
+or after anybody else's, so a boot hook has nothing to wait for and nothing to
+verify. Second, an absent or switched-off contributor is answered **at the
+read**, by the entry's recorded owner — never at the push. That is what makes
+this a contribution point rather than a gated port: the push is ungated
+on purpose, because gating it would turn one operator flip into a boot failure
+naming a module nobody touched.
+
+The presence filter splits the surface by who is asking. `get`, `resolve`,
+`list` and `isAvailable` skip an entry whose owning module is not effectively
+present — a buyer is never offered a carrier that cannot take the parcel, and
+`resolve` raises the ordinary `ModuleDisabledError`. `entry`, `ownerOf`,
+`isRegistered` and `listAll` deliberately do not, because `/delivery-methods`
+has to keep showing the method *and* the reason it is unavailable: switching a
+module off is not uninstalling it.
+
+`absentOwnerFor(adapterKey)` is the fifth reader and the only one that answers
+the *question* instead of exposing the table: it names the module that
+contributed the key and is not present, and `null` in every other case. It
+exists because `get()` collapses two situations an operator cannot act on
+identically — a key nobody ever contributed, and a key whose carrier module is
+switched off — and only the second one names something they can switch back on.
+`shipments` asks it to decide which state to open a `Shipment` in; the payment
+twin, `GatewayRefundRegistry.absentOwnerFor`, is the same reader for the same
+reason.
+
+## Lifecycle
+
+See [`shipments`](./shipments.md) for the `order_created` → `shipment_created`
+→ `receive_shipment` lifecycle, the `Shipment` entity, retries, and the
+order-status mapping.

package/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "nav.deliveryMethods.label": "Delivery methods",
+  "actions.openDeliveryMethods.label": "Delivery methods",
+  "actions.openDeliveryMethods.description": "Delivery & shipping methods"
+}