@endora-commerce/mod-payments 0.100.0

package/dist/manifest.js

@@ -0,0 +1,182 @@
+import { defineModuleErrorCodes, defineModuleManifest, defineModuleSettingsManifest, } from '@endora-commerce/contracts';
+/**
+ * The error codes this module declares (D-182,
+ * `specs/090-module-owned-error-codes/`).
+ *
+ * Branded, so a typo at a raise site is a compile error rather than a code that
+ * travels the whole path and renders raw to whoever reads it. They live in this
+ * file because it is the one the package publishes at its root subpath: a
+ * sibling module under `src/` is reachable through no subpath at all, so the
+ * raise sites could name it and a consumer branching on the code could not.
+ *
+ * Declaring them in `errorCodes` below is a separate act and is what routes the
+ * sentence to this package's own `i18n/` bundle; the reasoning for the three is
+ * written there.
+ */
+export const paymentsErrorCodes = defineModuleErrorCodes([
+    'PAYMENT_NOT_DUE',
+    'PAYMENT_ORDER_CLOSED',
+    'PAYMENT_ADAPTER_UNAVAILABLE',
+]);
+export const paymentsSettingsManifest = defineModuleSettingsManifest({
+    moduleCode: 'payments',
+    groups: [{ code: 'payments', name: 'Payments' }],
+    settings: [
+        {
+            code: 'payments.enabled',
+            name: 'Payments enabled',
+            // The description used to describe the settlement half only, and stopped
+            // exactly where an operator most needs it: it never said that this module
+            // contributes every built-in payment adapter, so switching it off empties
+            // checkout's payment list and the shop stops taking orders. An operator
+            // cannot learn a switch's consequence from anywhere but the switch.
+            description: 'Switches the whole payment capability on or off. While it is off the platform offers no payment method at all: this module contributes the four built-in payment adapters (bank transfer, in-person pickup, credit limit and the gateway placeholder), so every payment method configured against one of them disappears from checkout and an order naming it is refused. Unless another installed integration supplies a payment method of its own, that means the shop stops taking orders. The settlement lifecycle stops with it: the receive_payment ingress, both retry paths (the operator\'s and the buyer\'s), the per-order payment history and the payment-status e-mail. Nothing is dropped — every payment, its status transitions and its provider references stay in the database, an order mid-settlement keeps its record, and every payment method, permission and setting comes back exactly as configured when you switch it on again. It is not an uninstall, and it is not the way to switch off a single payment provider: a gateway integration depends on this module, so the platform refuses to switch this off while such an integration is still on — switch that integration off instead.',
+            groupCode: 'payments',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+    ],
+});
+/**
+ * Payments module — manifest backfill (Module Lifecycle, feature 018).
+ *
+ * Predates the lifecycle system; this manifest is the static record
+ * required so the module participates in the registry. No install /
+ * uninstall hook today — the module's schema is owned by earlier
+ * platform-wide migrations.
+ */
+export const manifest = defineModuleManifest({
+    id: 'payments',
+    name: 'Payments',
+    // What renders beside the activation control on `/platform/modules` is this
+    // string, not the activation Setting's — the Setting's description is served
+    // in the settings DTO and rendered on no screen today. So the consequence has
+    // to be legible here too, in one sentence: 'Payment driver abstraction and PSP
+    // integrations' told an operator nothing about what flipping the switch does.
+    description: 'The platform payment capability: the built-in payment adapters (bank transfer, in-person pickup, credit limit, gateway), the payment record every order carries, and the settlement lifecycle that PSP integrations plug into. Switched off, checkout offers no payment method and the shop takes no orders.',
+    version: '1.0.0',
+    // Feature 075 Phase C — `customer_accounts` joins the five that were already
+    // here: the payment-status e-mail resolves its recipient over
+    // `customerAccountReadPort` instead of reading the `CustomerAccount` entity.
+    // `orders` was already declared, which D-78 point 2 requires of the one
+    // co-transactional seam kept in `receive-payment-handler.ts` — the FK
+    // `payments_order_fk` had required it anyway.
+    // `organizations` joins for the buyer's retry route (issue #264): a suspended
+    // or blocked Organization may not pay an order any more than it may place
+    // one, and the guard is `organizationReadPort.assertCanTransact`. It is
+    // already transitively before this module through `orders`, so the entry
+    // changes no install or migration order — it states the edge.
+    dependencies: [
+        'auth',
+        'customer_accounts',
+        'delivery_methods',
+        'orders',
+        'organizations',
+        'payment_methods',
+        'transactional_emails',
+    ],
+    // Feature 073 (Constitution XVII) — the operator's activation control. It only
+    // became real in T126: until this module registered its own routes there was
+    // no seam for a gate to sit on.
+    activation: { settingCode: 'payments.enabled', default: true },
+    // This module owns its authority. It shipped owning none, enforcing
+    // `catalog:read` / `catalog:write` on all three of its admin routes — which
+    // meant an operator who could edit a product could read every payment's
+    // provider payload and, through the settlement ingress, declare an arbitrary
+    // payment successful, moving the order's payment status with no money having
+    // moved. Both codes were real, declared and enforced, so the permission
+    // inventory's two directions were clean over it, and D-173's `foreign-gate`
+    // sweep passes it deliberately (`catalog` is `nonDeactivatable`, so the
+    // availability coupling that sweep asks about can never bite).
+    //
+    // A pair rather than one `payments:manage`: reading an order's payment
+    // history is support and finance work, opening a retry and declaring a
+    // settlement are money operations, and an operator organisation separates
+    // them. No third code for the ingress, though it is the most dangerous of the
+    // three routes: `POST /api/v1/payments/receive` is explicitly transitional
+    // pending a signed PSP-webhook auth path, and a code minted for it now is one
+    // that has to be migrated out of every role later — the situation
+    // `PERMISSION_CATALOGUE` records as unfixable-in-place for
+    // `integrations:manage` and `audit_log:read`. Revisit the split when that
+    // webhook path lands, which is the moment the question is answerable.
+    //
+    // No manifest `action` goes with these, and that is a decision rather than an
+    // omission: this module has no screen. Its only admin surface is a tab on an
+    // `orders` route, so a palette action would have to declare `orders:read` as
+    // its `requiredPermission` to agree with the gate on its own `targetRoute` —
+    // the `ACTION_PERMISSION_DISAGREEMENTS` shape `check:action-route-permissions`
+    // exists to refuse. The honest discovery entry for the payment history is
+    // `orders`' own.
+    permissions: [
+        { code: 'payments:read', label: 'View payments' },
+        { code: 'payments:write', label: 'Record and retry payments' },
+    ],
+    settings: paymentsSettingsManifest,
+    // Feature 090 / D-182 — the error codes this module owns, and the first three
+    // this package has ever declared. It is not a Phase 3 migration: the prefix
+    // chain routes nothing to `payments` and this module held no bundle at all,
+    // so these are new codes rather than a family changing hands.
+    //
+    // All three are the buyer's own payment-retry refusals, and every one of them
+    // wore `VALIDATION_FAILED` with a prose sentence. That is the one code
+    // `localizeErrorEnvelope` returns *before* translating — the code is
+    // overloaded and several services carry machine-readable tokens in its
+    // message — so a Polish buyer trying to pay a declined order was answered in
+    // the raise site's English, whichever language they asked for. Same defect as
+    // the order-cancellation route, one route over: the buyer's *retry* control
+    // beside their *cancel* control.
+    //
+    // **Three codes and not one**, which is the question that had to be answered
+    // before any of them was minted. The cancellation repair collapsed four
+    // branches into one code because they were one `throw` behind a conjunction
+    // and the buyer was told the same sentence either way. These are three
+    // separate raise sites behind three orthogonal predicates, and the buyer's
+    // next move differs in each:
+    //
+    //   * `PAYMENT_NOT_DUE` — the money is not the buyer's to pay: the order is
+    //     paid, drawn against a credit limit (`deferred`), or refunded. Nothing
+    //     to do.
+    //   * `PAYMENT_ORDER_CLOSED` — the order's lifecycle status is terminal, so
+    //     somebody cancelled it and the stock is already released. The buyer who
+    //     still wants the goods places a new order.
+    //   * `PAYMENT_ADAPTER_UNAVAILABLE` — the order is open and the money is
+    //     still owed; the shop can no longer *start* a session for the method it
+    //     was placed with. The buyer contacts the shop, and an operator repairs a
+    //     configuration.
+    //
+    // The first two are orthogonal rather than alternative: an order can be
+    // unpaid and cancelled, or paid and open, so neither implies the other. The
+    // third is reached only once both have passed.
+    //
+    // `PAYMENT_ADAPTER_UNAVAILABLE` names the adapter rather than the method on
+    // purpose. The registry it fails on is this module's; `PAYMENT_METHOD_*` is
+    // the family `payment_methods` would reach for, and two modules declaring one
+    // code routes it to neither of them (D-182's collision rule).
+    //
+    // No `tokens`: none of the three raise sites passes a fourth argument, so
+    // `refusalToken` has nothing to read, and the bundle keys are flat.
+    errorCodes: [
+        { code: paymentsErrorCodes.PAYMENT_NOT_DUE },
+        { code: paymentsErrorCodes.PAYMENT_ORDER_CLOSED },
+        { code: paymentsErrorCodes.PAYMENT_ADAPTER_UNAVAILABLE },
+    ],
+    // The bundle those sentences live in. This module shipped none until now —
+    // it has no admin screen of its own — so the directory and this declaration
+    // arrive together.
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    // Feature 047 — admin-editable transactional email owned by this module.
+    transactionalEmails: [
+        {
+            code: 'payment_status_changed',
+            name: 'Payment status changed',
+            group: 'payments',
+            variables: [
+                { key: 'order.businessId', label: 'Order number', sampleValue: 'ORD-1042' },
+                { key: 'payment.statusLabel', label: 'Payment status', sampleValue: 'Paid' },
+                { key: 'payment.failureReason', label: 'Failure reason', sampleValue: 'Card declined' },
+            ],
+        },
+    ],
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/migrations/20260925T115728_payments_refunded_amount.d.ts

@@ -0,0 +1,28 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `payments.refunded_amount` — the cumulative refunded amount the `Payment`
+ * entity maps (`refundedAmount`), created by the module that maps it.
+ *
+ * Until feature 134 (feature 134, research D14) the
+ * only migration creating this column was `stripe`'s
+ * `Migration20260715T103358StripePaymentRefundedAmount`: an instance without
+ * `stripe` could not insert a payment, and `stripe`'s hard uninstall dropped a
+ * column this module reads and writes. That migration keeps its class name and
+ * has both bodies emptied; this one replaces it.
+ *
+ * **`if not exists`**, because the column is already present on every database
+ * that ran `stripe`'s migration, and there this must be a no-op that keeps
+ * every value.
+ *
+ * **`down()` is deliberately empty.** The `payments` table is created by the
+ * platform's frozen `core_commerce_init`, which a hard uninstall of this module
+ * never reverts, so the table and its rows outlive this module. Dropping the
+ * column would reset every surviving payment's refunded amount to zero on the
+ * next install, and nothing would report it: a down that removes one column
+ * from rows that survive is data loss, not a revert.
+ */
+export declare class Migration20260925T115728PaymentsRefundedAmount extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260925T115728_payments_refunded_amount.d.ts.map

package/dist/migrations/20260925T115728_payments_refunded_amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260925T115728_payments_refunded_amount.d.ts","sourceRoot":"","sources":["../../src/migrations/20260925T115728_payments_refunded_amount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,8CAA+C,SAAQ,SAAS;IAC5D,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260925T115728_payments_refunded_amount.js

@@ -0,0 +1,32 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `payments.refunded_amount` — the cumulative refunded amount the `Payment`
+ * entity maps (`refundedAmount`), created by the module that maps it.
+ *
+ * Until feature 134 (feature 134, research D14) the
+ * only migration creating this column was `stripe`'s
+ * `Migration20260715T103358StripePaymentRefundedAmount`: an instance without
+ * `stripe` could not insert a payment, and `stripe`'s hard uninstall dropped a
+ * column this module reads and writes. That migration keeps its class name and
+ * has both bodies emptied; this one replaces it.
+ *
+ * **`if not exists`**, because the column is already present on every database
+ * that ran `stripe`'s migration, and there this must be a no-op that keeps
+ * every value.
+ *
+ * **`down()` is deliberately empty.** The `payments` table is created by the
+ * platform's frozen `core_commerce_init`, which a hard uninstall of this module
+ * never reverts, so the table and its rows outlive this module. Dropping the
+ * column would reset every surviving payment's refunded amount to zero on the
+ * next install, and nothing would report it: a down that removes one column
+ * from rows that survive is data loss, not a revert.
+ */
+export class Migration20260925T115728PaymentsRefundedAmount extends Migration {
+    async up() {
+        this.addSql(`alter table "payments" add column if not exists "refunded_amount" numeric(14,2) not null default '0';`);
+    }
+    async down() {
+        // Intentionally empty — see the class comment.
+    }
+}
+//# sourceMappingURL=20260925T115728_payments_refunded_amount.js.map

package/dist/migrations/20260925T115728_payments_refunded_amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260925T115728_payments_refunded_amount.js","sourceRoot":"","sources":["../../src/migrations/20260925T115728_payments_refunded_amount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,8CAA+C,SAAQ,SAAS;IAClE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CACT,uGAAuG,CACxG,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,+CAA+C;IACjD,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260925T115728PaymentsRefundedAmount } from './20260925T115728_payments_refunded_amount.js';
+export declare const migrations: (typeof Migration20260925T115728PaymentsRefundedAmount)[];
+export { Migration20260925T115728PaymentsRefundedAmount, };
+//# 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,8CAA8C,EAAE,MAAM,+CAA+C,CAAC;AAE/G,eAAO,MAAM,UAAU,2DAEtB,CAAC;AAEF,OAAO,EACL,8CAA8C,GAC/C,CAAC"}

package/dist/migrations/index.js

@@ -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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260925T115728PaymentsRefundedAmount } from './20260925T115728_payments_refunded_amount.js';
+export const migrations = [
+    Migration20260925T115728PaymentsRefundedAmount,
+];
+export { Migration20260925T115728PaymentsRefundedAmount, };
+//# 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,8CAA8C,EAAE,MAAM,+CAA+C,CAAC;AAE/G,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,8CAA8C;CAC/C,CAAC;AAEF,OAAO,EACL,8CAA8C,GAC/C,CAAC"}

package/docs/payments.md

@@ -0,0 +1,69 @@
+---
+title: payments
+description: Payment driver dispatch + settlement events
+---
+
+# `payments`
+
+Payment driver dispatch + settlement events. The module owns the driver
+port (`gateway-adapter-port.ts`) and concrete in-tree drivers; per-vendor
+adapters live in dedicated integration modules.
+
+## Drivers
+
+| Driver | Behaviour |
+| --- | --- |
+| `bank-transfer-driver.ts` | Returns `NextAction.kind='awaiting_transfer'`; settlement happens out-of-band when the operator marks the order paid |
+| `pickup-driver.ts` | `NextAction.kind='none'` for cash-on-pickup |
+| `credit-limit-driver.ts` | Calls `CreditLimitService.reserve` inside the order-placement transaction |
+| `gateway-adapter-port.ts` | Interface stub for external gateways; per-vendor implementations live outside the core |
+
+## Public surface
+
+Three admin routes, gated on this module's own permission codes:
+
+| Verb + Path | Permission | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/orders/:id/payments` | `payments:read` | Full payment history for one order, including each attempt's provider payload |
+| `POST /api/v1/admin/orders/:id/payments/retry` | `payments:write` | Opens the next `Payment` attempt on an order |
+| `POST /api/v1/payments/receive` | `payments:write` | The `receive_payment` settlement ingress: declares a payment succeeded or failed |
+
+The pair is deliberate. Reading an order's payment history is support and
+finance work; opening a retry and declaring a settlement are money operations,
+and an operator organisation separates the two. There is no third code for the
+settlement ingress even though it is the most dangerous of the three, because
+that route is transitional pending a signed PSP-webhook auth path — see the
+reasoning in `manifest.ts`.
+
+Until `payments` declared these, all three routes were gated on `catalog:read`
+and `catalog:write`, so an operator who could edit a product could read every
+payment's provider payload and mark an arbitrary payment settled. **Upgrading:
+a role that was reading payment data through `catalog:read` must be granted
+`payments:read` explicitly on `/admin-roles`** — there is no migration, because
+one granting `payments:read` to every holder of `catalog:read` would reproduce
+exactly the over-grant this change removes.
+
+The ingress body bounds its `providerDetails` to a flat map of scalars
+(`operatorProviderDetailsSchema`): the column is persisted verbatim and served
+back in full, so what an operator may write into it is bounded by our schema
+rather than by the caller's payload. Gateway integrations build the payload in
+code and are not subject to that bound.
+
+Beyond the routes, orders consume the drivers via
+`order-service.ts#placeOrder()`, and admin payment-status mutations go through
+`/api/v1/admin/orders/:id/payment-status`, which `orders` owns.
+
+The buyer's own retry (`POST /api/v1/orders/:orderId/payments/retry`) is a
+customer route and authorises through `requireCustomer`, not a permission.
+
+## Events emitted
+
+`payment.settled.v1`, `payment.failed.v1`, `payment.refunded.v1`.
+
+## Extension points
+
+- **New gateway** — implement `gateway-adapter-port.ts`, register the
+  driver in the composition root, expose a configuration through the
+  `integrations` module.
+- **Fraud / 3DS hooks** — slot in front of the driver's `reserve` call
+  before the order-placement transaction commits.

package/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "errors.PAYMENT_NOT_DUE": "This order is not awaiting payment.",
+  "errors.PAYMENT_ORDER_CLOSED": "This order is closed and can no longer be paid.",
+  "errors.PAYMENT_ADAPTER_UNAVAILABLE": "The payment method this order was placed with is no longer available."
+}

package/i18n/pl.json

@@ -0,0 +1,5 @@
+{
+  "errors.PAYMENT_NOT_DUE": "To zamówienie nie oczekuje na płatność.",
+  "errors.PAYMENT_ORDER_CLOSED": "To zamówienie zostało zamknięte i nie można go już opłacić.",
+  "errors.PAYMENT_ADAPTER_UNAVAILABLE": "Metoda płatności wybrana przy składaniu tego zamówienia nie jest już dostępna."
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@endora-commerce/mod-payments",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "The platform payment capability: the built-in payment adapters (bank transfer, in-person pickup, credit limit, gateway), the payment record every order carries, and the settlement lifecycle that PSP integrations plug into. Switched off, checkout offers no payment method and the shop takes no orders.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "payments"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/payments"
+  },
+  "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"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/mod-orders": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/mod-orders": "0.100.0",
+    "@endora-commerce/platform": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-payments — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";