@endora-commerce/mod-payments 0.100.0

package/dist/backend/index.js

@@ -0,0 +1,318 @@
+import { lazyPort } from '@endora-commerce/platform/kernel';
+import { builtInPaymentAdapters } from './adapters/built-in-adapters.js';
+import { Payment } from './entities/payment.entity.js';
+import { ReceivePaymentHandler, } from './services/receive-payment-handler.js';
+import { PaymentService } from './services/payment-service.js';
+import { PaymentRetryService } from './services/payment-retry-service.js';
+import { PaymentReadService } from './services/payment-read-port.js';
+import { PaymentReferenceService } from './services/payment-reference-port.js';
+import { PaymentPlacementApplyService } from './services/payment-placement-apply-port.js';
+import { PaymentRefundProvider } from './services/payment-refund.js';
+import { gatewayRefundRegistry } from './services/registry-singleton.js';
+import { PaymentEmailNotifier } from './services/payment-email-notifier.js';
+import { resolvePaymentEmailRenderer } from './services/payment-email-renderer.js';
+import { registerPaymentsRoutes } from './routes.js';
+import { registerPaymentsCustomerRoutes } from './routes.customer.js';
+import { PAYMENT_STATUS_CHANGED_DEFAULT } from './email-templates/transactional-defaults.js';
+export function registerModule(ctx) {
+    ctx.di.register({
+        /**
+         * The refund-handler table, as the container's value — the delivery-side
+         * twin of `payment_methods`' `paymentAdapterRegistry`, and registered the
+         * same way and for the same reason (feature 075, Phase P).
+         *
+         * **Ungated, and the only name over this registry** (D-99.7). It used to
+         * have a gated twin, `gatewayRefundRegistryPort`, for the *pull* direction —
+         * "which handler settles this refund" — but that question is asked inside
+         * this module, by `PaymentRefundProvider`, and no module ever resolved the
+         * port. A *push* must not be gated: the four gateways contribute their
+         * handler from a boot hook, and a gate there would refuse the contribution
+         * rather than defer it, so a gateway would silently stay unregistered until
+         * the next restart after an operator switched `payments` back on. That
+         * asymmetry is now stated in the contract rather than only here, because a
+         * rule in a comment ships in no package. The absent-owner policy sits inside
+         * the registry, where the whole design puts it: a handler whose module is
+         * off is skipped at enumeration and the obligation lands on
+         * `pending_manual` (D-71), which a gate over the push would drop instead of
+         * record.
+         */
+        gatewayRefundRegistry: ctx.asFunction(() => gatewayRefundRegistry).singleton(),
+        // Contribution point, defaulted to no sender: a deployment without a
+        // transactional-email surface sends nothing rather than failing to settle.
+        paymentEmailSender: ctx
+            .asFunction(() => () => undefined)
+            .singleton(),
+        paymentEmailNotifier: ctx
+            .asFunction(({ emFactory }) => new PaymentEmailNotifier({
+            emFactory,
+            orderRead: lazyPort(ctx, 'orderReadPort'),
+            customerAccountRead: lazyPort(ctx, 'customerAccountReadPort'),
+            // Read per call: a root contributes the sender after
+            // `transactional_emails` announces it, which is later than this.
+            getTransactionalEmailSender: () => ctx.cradle().paymentEmailSender(),
+        }))
+            .singleton(),
+    });
+    ctx.di.providePort('paymentService', ctx
+        .asFunction(({ emFactory }) => new PaymentService(emFactory, lazyPort(ctx, 'orderReadPort')))
+        .singleton());
+    /**
+     * The buyer's own retry (issue #264), as this module's own service rather
+     * than a route body.
+     *
+     * It is not a published port: nothing outside this module calls it, and the
+     * one surface it has is the HTTP route below. The adapter registry is read
+     * per call — an operator can switch a gateway off between two requests, and
+     * the registry filters its enumeration on the contributor's effective state.
+     */
+    ctx.di.register({
+        paymentRetryService: ctx
+            .asFunction(() => new PaymentRetryService({
+            orderRead: lazyPort(ctx, 'orderReadPort'),
+            customerAccountRead: lazyPort(ctx, 'customerAccountReadPort'),
+            // Lazily, even though this module owns it: capturing a gate into a
+            // singleton is a gate that keeps answering after an operator
+            // switches the owner off.
+            paymentService: lazyPort(ctx, 'paymentService'),
+            // The terminality read (feature 085 Phase D): the same port the
+            // settlement handler writes through, resolved for its read half.
+            orderTransition: lazyPort(ctx, 'orderTransitionPort'),
+            paymentAdapterRegistry: () => ctx.cradle().paymentAdapterRegistry,
+            // No `catch` around the port call, for the reason `orders` and
+            // `carts` give at the same seam: a disabled-module throw read as
+            // "no restriction" would be fail-open on a path whose job is to
+            // restrict.
+            assertOrganizationCanTransact: async (organizationId) => {
+                await ctx.cradle().organizationReadPort.assertCanTransact(organizationId);
+            },
+        }))
+            .singleton(),
+    });
+    /**
+     * How a return settlement refunds a payment (feature 046 R5), as this
+     * module's port instead of a class both roots constructed (T143c).
+     *
+     * `PaymentRefundProvider` resolves the order's PSP adapter out of
+     * `gatewayRefundRegistry` — this module's registry — so a root's instance
+     * refunded through a switched-off `payments`. The bridge `returns` receives
+     * forwards to this name per settlement, which is where the gate belongs.
+     */
+    ctx.di.providePort('paymentRefundPort', ctx
+        .asFunction(() => new PaymentRefundProvider(lazyPort(ctx, 'orderReadPort'), lazyPort(ctx, 'paymentMethodReadPort')))
+        .singleton());
+    // ---------------------------------------------------------------------------
+    // Feature 075, Phase P — the published surface.
+    //
+    // `paymentReadPort` replaces sixteen hand-written `em.findOne(Payment, …)`
+    // calls in the four gateways, and `receivePaymentPort` is the ingress they
+    // already share, now expressed without the `Payment` entity in its result
+    // type.
+    //
+    // **The refund registry is published under its push name only** (D-99.7). It
+    // once had a second, gated registration here — `gatewayRefundRegistryPort`,
+    // over the same instance — which nothing ever resolved, while the doc block in
+    // `@endora-commerce/contracts` described the *push* seam above it. An out-of-tree gateway
+    // reading only the published contracts would have resolved the gate from its
+    // boot hook and exited 1. The contract now names `gatewayRefundRegistry`, the
+    // ungated registration above, and says why it is ungated; the pull is
+    // intra-module and unpublished.
+    // ---------------------------------------------------------------------------
+    ctx.di.providePort('paymentReadPort', ctx.asFunction(({ emFactory }) => new PaymentReadService(emFactory)).singleton());
+    /**
+     * The payment row order placement opens, on **placement's** `EntityManager`
+     * (feature 080, T048; D-169, D-179).
+     *
+     * `orders` wrote it with this module's `Payment` class until T048 — the last
+     * cross-module entity-class reach in the tree. D-168 leaves a packaged
+     * `payments` no entity class for a stranger to name, so what crosses is now
+     * this module's own interface and the statement belongs to the module that
+     * owns the table. `PaymentPlacementApplyPort` stays out of
+     * `@endora-commerce/contracts` because it takes a MikroORM `EntityManager` and
+     * FR-034 keeps that package free of them — and it is declared on
+     * **`@endora-commerce/mod-orders/ports`**, not this module's own, which is
+     * D-171.1 and not an accident. The two modules reach each other, so only one
+     * npm edge can exist (a mutual devDependency between two module packages is a
+     * build deadlock, `noEmitOnError` making the loser emit nothing), and it runs
+     * in the direction of the binding manifest edge: this module declares `orders`
+     * in its `dependencies`, so `mod-payments` build-depending on `mod-orders`
+     * adds no claim its manifest does not already make.
+     *
+     * The licence is conditional and the condition is **this** module's:
+     * `PaymentPlacementApplyService` names the interface at its `implements`
+     * clause, and the registration below carries the explicit type argument. Those
+     * are the two places `tsc` checks conformance — TS2420 and TS2345 — and both
+     * resolve the interface wherever it was declared. Dropping either turns the
+     * seam into D-77's rejected alternative, which is what
+     * `check:port-shape`'s `declared-elsewhere-without-implements` refuses.
+     *
+     * It is a **gated** registration like every other name here, and that gate is
+     * the half `orders` writing the row itself could never have. The reachable
+     * consequence is narrow, because `assertPaymentMethodUsable` already refuses a
+     * method whose adapter this module contributes while this module is absent —
+     * D-179 measured that and found checkout already fail-closed, where no money
+     * is at stake. What that guard deliberately tolerates is a method whose
+     * adapter **no** module ever registered, and such a placement went on writing
+     * a row into this module's own table with an operator having switched it off:
+     * issue #188's shape, which the gate closes. `orders` declares the edge
+     * `refuses-without` and wraps the call in no `catch`.
+     */
+    ctx.di.providePort('paymentPlacementApplyPort', ctx.asFunction(() => new PaymentPlacementApplyService()).singleton());
+    /**
+     * The write side of `findByExternalReference`, published for the four
+     * gateways that were doing it with this module's entity and their own
+     * `EntityManager`.
+     *
+     * A port, not a registration: unlike the registry above, this is a pull with
+     * a failure mode. A gateway that has just opened a PaymentIntent and cannot
+     * record its identifier has to hear so — the provider object is live, and an
+     * event it sends would arrive with nothing on this side able to resolve it.
+     */
+    ctx.di.providePort('paymentReferencePort', ctx
+        .asFunction(({ emFactory }) => new PaymentReferenceService(emFactory))
+        .singleton());
+    ctx.di.providePort('paymentEmailRendererPort', ctx
+        .asFunction(() => ({
+        render: (rendererKey, emailContext) => resolvePaymentEmailRenderer(rendererKey)(emailContext),
+    }))
+        .singleton());
+    ctx.di.providePort('receivePaymentPort', ctx
+        .asFunction(() => {
+        const handler = () => ctx.cradle().receivePaymentHandler;
+        return {
+            receive: (input) => handler().receive(input),
+            reflectRefund: (input) => handler().reflectRefund(input),
+        };
+    })
+        .singleton());
+    /**
+     * The settlement handler, with the two cross-module reads it used to make
+     * with somebody else's entity now made through their ports (feature 075,
+     * C-W3).
+     *
+     * Both edges were ledgered as blocked on this constructor: the four gateways
+     * built their own handler, so it could take no port they could not build.
+     * They resolve `receivePaymentPort` since the C-W3 gateway cuts, so this is
+     * the only construction left and `ctx` is in hand.
+     *
+     * **The `Order` entity import inside the handler is gone since feature 080's
+     * T048**, and the seam it stood for is not: `payments_order_fk` still holds
+     * the payment row and the order's payment status co-transactional (D-78 point
+     * 2), so the write still runs on the settlement's own `EntityManager` — it is
+     * `orderPaymentStatusApplyPort` that performs it now, an interface `orders`
+     * declares in its `ports/` directory precisely because an `EntityManager`
+     * parameter bars it from `@endora-commerce/contracts` (FR-034). D-168 leaves a
+     * packaged `orders` no entity class for this module to name, which is what
+     * made the conversion due before that module moves.
+     *
+     * The three `orders`/`payment_methods` ports this constructor takes are not
+     * three of a kind, and the difference is which transaction each runs in:
+     * `paymentMethodReadPort` is a read of a row the settlement never writes,
+     * `orderPaymentStatusApplyPort` is the co-transactional write above, and
+     * `orderTransitionPort` is called after the commit.
+     *
+     * **`orderTransitionPort` replaces two of the three names this used to take**
+     * (feature 085 Phase D). `orderStatusAnnouncePort` goes because the transition
+     * seam emits the templated `.after` events itself, so announcing beside it
+     * would double every subscriber's reaction; `paymentOrderStatusRegistry` goes
+     * because "is this a status code" was never the question the ingress needed
+     * answered, and the port answers the real one — may this order go there —
+     * against the configured graph.
+     */
+    ctx.di.providePort('receivePaymentHandler', ctx
+        .asFunction(({ emFactory, eventBus }) => new ReceivePaymentHandler(emFactory, lazyPort(ctx, 'paymentMethodReadPort'), lazyPort(ctx, 'orderTransitionPort'), lazyPort(ctx, 'orderPaymentStatusApplyPort'), ctx.log, eventBus))
+        .singleton());
+    ctx.subscribe('payment.received.v1', async (payload) => {
+        const { orderId } = payload;
+        await ctx.cradle().paymentEmailNotifier.notify(orderId, 'paid', null);
+    });
+    ctx.subscribe('payment.failed.v1', async (payload) => {
+        const { orderId, failureReason } = payload;
+        await ctx
+            .cradle()
+            .paymentEmailNotifier.notify(orderId, 'failed', failureReason ?? null);
+    });
+    ctx.routes(async (app) => {
+        const { requireAdmin } = ctx.cradle();
+        await registerPaymentsRoutes(app, {
+            requireAdmin,
+            // Lazily, even though the module owns both ports: route *registration*
+            // runs inside `buildServer` whatever the module's effective state is, so
+            // destructuring the gates here would stop the next start instead of
+            // stopping the routes (D-40).
+            receiveHandler: lazyPort(ctx, 'receivePaymentHandler'),
+            paymentService: lazyPort(ctx, 'paymentService'),
+        });
+        await registerPaymentsCustomerRoutes(app, {
+            requireCustomer: (req, reply) => ctx.cradle().requireCustomer(req, reply),
+            resolveCustomerAccountId: (req) => ctx.cradle().customerAccountIdResolver(req),
+            // Resolvable here, unlike the two above: this is a plain registration
+            // rather than a gate, and every port it holds is lazy.
+            retryService: ctx.cradle().paymentRetryService,
+        });
+    });
+    /**
+     * The default subject and content for the 1 transactional email this
+     * module declares in its manifest (T143a).
+     *
+     * These were fourteen `emailDefaultsRegistry.register(...)` calls in
+     * `composition.ts`, each importing a template constant out of the module that
+     * owns it — a root reaching into seven modules to hand their own content to
+     * an eighth. Each module registers its own now.
+     *
+     * `ctx.onBoot` rather than a registration: the registry is *read* once, by
+     * `transactional_emails`' boot reconciler inside its plugin body. Boot hooks
+     * run during composition and plugin bodies only when the Fastify app is
+     * built, so this always lands first — by construction, not by ordering luck.
+     */
+    ctx.onBoot(async () => {
+        const defaults = lazyPort(ctx, 'emailDefaultsPort');
+        defaults.register('payment_status_changed', PAYMENT_STATUS_CHANGED_DEFAULT, 'payments');
+    });
+    /**
+     * The four payment kinds this module implements, pushed into the registry
+     * `payment_methods` holds (T143a).
+     *
+     * `ctx.onBoot` rather than a registration, for the reason the other
+     * push-at-boot contributions give: the registry is *read* — by the
+     * payment-method admin surface, by storefront eligibility and by
+     * order placement — and a registration declares without resolving.
+     *
+     * It belongs in this module rather than in a root even though the registry is
+     * a deliberate **process** singleton (`payment_methods/services/registry-singleton.ts`,
+     * which the four gateway modules import directly from their install hooks).
+     * The singleton decides *where* a descriptor lands, not *who* may declare
+     * one, and this module owns the adapter classes.
+     *
+     * Each one names this module as it lands (issue #96): the registry filters
+     * its enumeration on the contributing module's effective state, so an entry
+     * that does not know who contributed it is an entry that keeps being offered
+     * to a buyer after an operator switches its owner off. Re-registration by the
+     * same owner is silent, which is what the old `isRegistered` guard was
+     * really for — the test suite performs several hundred compositions against
+     * this one process singleton.
+     */
+    ctx.onBoot(() => {
+        const registry = ctx.cradle().paymentAdapterRegistry;
+        for (const adapter of builtInPaymentAdapters()) {
+            registry.register(adapter, 'payments');
+        }
+    });
+}
+/**
+ * The module's persisted entity classes, on the `./backend` subpath, as one
+ * array and **no named class export** (D-168).
+ *
+ * This is the shape the platform reads when the package is *installed*: the
+ * boot-time loader (`src/packages/package-runtime.ts`, `exported['entities']`)
+ * and the static declaration reader (`scripts/lib/package-declarations.ts`),
+ * which is the third source of `check:module-boundary`'s `table->owner` map and
+ * the package pass of `check-entity-tenant-classification`. A missing array is
+ * answered with `[]` — zero entities registered, no error anywhere.
+ *
+ * One class, and the one that used to cross a boundary: `orders` constructed
+ * `Payment` directly until T048, which was the last cross-module entity-class
+ * reach in the tree. What crosses now is `PaymentPlacementApplyPort`, and D-168
+ * leaves a stranger no supported spelling for the class itself.
+ */
+export const entities = [Payment];
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

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

package/dist/backend/routes.customer.d.ts

@@ -0,0 +1,20 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { PaymentRetryService } from './services/payment-retry-service.js';
+/**
+ * The buyer's own payment surface (issue #264).
+ *
+ *   POST /api/v1/orders/:orderId/payments/retry — pay an unpaid order again
+ *
+ * It sits in this module rather than in `orders` because the attempt row and
+ * the adapter dispatch are this module's, and because `payments` already
+ * declares `orders` — the reverse edge would close a cycle. It is the customer
+ * twin of `POST /api/v1/admin/orders/:id/payments/retry`, and both run through
+ * the same `PaymentService.openRetry`.
+ */
+export interface PaymentsCustomerRoutesDeps {
+    requireCustomer: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    resolveCustomerAccountId: (req: FastifyRequest) => string;
+    retryService: PaymentRetryService;
+}
+export declare function registerPaymentsCustomerRoutes(app: FastifyInstance, deps: PaymentsCustomerRoutesDeps): Promise<void>;
+//# sourceMappingURL=routes.customer.d.ts.map

package/dist/backend/routes.customer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.customer.d.ts","sourceRoot":"","sources":["../../src/backend/routes.customer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC,eAAe,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,wBAAwB,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC;IAC1D,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED,wBAAsB,8BAA8B,CAClD,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/backend/routes.customer.js

@@ -0,0 +1,24 @@
+import { ERROR_CODES, OrganizationCannotTransactError } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+export async function registerPaymentsCustomerRoutes(app, deps) {
+    app.post('/api/v1/orders/:orderId/payments/retry', { preHandler: deps.requireCustomer }, async (request, reply) => {
+        const callerId = deps.resolveCustomerAccountId(request);
+        try {
+            const result = await deps.retryService.retryForCustomer({
+                orderId: request.params.orderId,
+                customerAccountId: callerId,
+            });
+            return reply.send({ data: result });
+        }
+        catch (err) {
+            // The same mapping placement uses for the same refusal, so a buyer of a
+            // suspended Organization is told the same thing whether they are
+            // placing an order or paying one.
+            if (err instanceof OrganizationCannotTransactError) {
+                throw new HttpError(423, ERROR_CODES.FORBIDDEN, 'Your Organization cannot transact in its current status.', { code: 'organization_cannot_transact', status: err.status });
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=routes.customer.js.map

package/dist/backend/routes.customer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.customer.js","sourceRoot":"","sources":["../../src/backend/routes.customer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAoB3D,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,GAAoB,EACpB,IAAgC;IAEhC,GAAG,CAAC,IAAI,CACN,wCAAwC,EACxC,EAAE,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,EACpC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC;gBACtD,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;gBAC/B,iBAAiB,EAAE,QAAQ;aAC5B,CAAC,CAAC;YACH,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,iEAAiE;YACjE,kCAAkC;YAClC,IAAI,GAAG,YAAY,+BAA+B,EAAE,CAAC;gBACnD,MAAM,IAAI,SAAS,CACjB,GAAG,EACH,WAAW,CAAC,SAAS,EACrB,0DAA0D,EAC1D,EAAE,IAAI,EAAE,8BAA8B,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAC7D,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/backend/routes.d.ts

@@ -0,0 +1,36 @@
+import type { FastifyInstance } from 'fastify';
+import type { ReceivePaymentHandler } from './services/receive-payment-handler.js';
+import type { PaymentService } from './services/payment-service.js';
+import type { RequireAdminFactory } from '@endora-commerce/platform/kernel';
+/**
+ * Payments routes (feature 034).
+ *
+ *   POST /api/v1/payments/receive            — receive_payment ingress (FR-022)
+ *   POST /api/v1/admin/orders/:id/payments/retry — open a retry Payment (FR-024)
+ *   GET  /api/v1/admin/orders/:id/payments   — full payment history (FR-026)
+ *
+ * The buyer's own retry is a separate file (`routes.customer.ts`, issue #264):
+ * it authorises differently, guards the Organization's ability to transact, and
+ * starts the gateway session this one deliberately does not.
+ *
+ * The ingress is admin-guarded for the MVP; a signed PSP-webhook auth path is a
+ * follow-up (the offline reference adapters are settled by an admin anyway).
+ *
+ * All three gate on this module's own codes. They used to gate on `catalog:read`
+ * and `catalog:write`, which meant an operator who could edit a product could
+ * read every payment's provider payload and declare an arbitrary payment
+ * settled. The reasoning for the pair, and for there being no third code for the
+ * ingress, is in `manifest.ts` beside the declaration.
+ *
+ * The ingress body is `receivePaymentRequestSchema` rather than
+ * `receivePaymentSchema`: the two differ only in `providerDetails`, which is
+ * bounded for the operator-supplied path and left open for the gateway modules
+ * that build the payload in code.
+ */
+export interface PaymentsRoutesDeps {
+    requireAdmin: RequireAdminFactory;
+    receiveHandler: ReceivePaymentHandler;
+    paymentService: PaymentService;
+}
+export declare function registerPaymentsRoutes(app: FastifyInstance, deps: PaymentsRoutesDeps): Promise<void>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/backend/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/backend/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,mBAAmB,CAAC;IAClC,cAAc,EAAE,qBAAqB,CAAC;IACtC,cAAc,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,IAAI,CAAC,CAoCf"}

package/dist/backend/routes.js

@@ -0,0 +1,44 @@
+import { receivePaymentRequestSchema } from '@endora-commerce/contracts';
+export async function registerPaymentsRoutes(app, deps) {
+    app.post('/api/v1/payments/receive', {
+        preHandler: deps.requireAdmin('payments:write'),
+        schema: { body: receivePaymentRequestSchema },
+    }, async (request) => {
+        const body = receivePaymentRequestSchema.parse(request.body);
+        const result = await deps.receiveHandler.receive(body);
+        return { data: result };
+    });
+    app.post('/api/v1/admin/orders/:id/payments/retry', { preHandler: deps.requireAdmin('payments:write') }, async (request, reply) => {
+        // `opened` is discarded here on purpose: the operator asked for the next
+        // attempt and gets it, whether it had to be created or was already open.
+        // The buyer-facing twin routes on that difference — see
+        // `routes.customer.ts` — because only it starts a provider session.
+        const { payment } = await deps.paymentService.openRetry(request.params.id);
+        reply.status(201);
+        return { data: serializePayment(payment) };
+    });
+    app.get('/api/v1/admin/orders/:id/payments', { preHandler: deps.requireAdmin('payments:read') }, async (request) => {
+        const payments = await deps.paymentService.listForOrder(request.params.id);
+        return { data: payments.map(serializePayment) };
+    });
+}
+function serializePayment(p) {
+    return {
+        id: p.id,
+        orderId: p.orderId,
+        paymentMethodId: p.paymentMethodId,
+        status: p.status,
+        amount: Number(p.amount),
+        refundedAmount: Number(p.refundedAmount ?? '0'),
+        refundedAt: p.providerDetails?.['refundedAt'] ?? null,
+        refundReference: p.providerDetails?.['refundReference'] ?? null,
+        updatedAt: p.updatedAt ? p.updatedAt.toISOString() : null,
+        currency: p.currency,
+        paidAt: p.paidAt ? p.paidAt.toISOString() : null,
+        externalReference: p.externalReference ?? null,
+        providerDetails: p.providerDetails ?? null,
+        failureReason: p.failureReason ?? null,
+        attemptNo: p.attemptNo,
+    };
+}
+//# sourceMappingURL=routes.js.map

package/dist/backend/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/backend/routes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAoCzE,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAoB,EACpB,IAAwB;IAExB,GAAG,CAAC,IAAI,CACN,0BAA0B,EAC1B;QACE,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC;QAC/C,MAAM,EAAE,EAAE,IAAI,EAAE,2BAA2B,EAAE;KAC9C,EACD,KAAK,EAAE,OAAO,EAAE,EAAE;QAChB,MAAM,IAAI,GAAG,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC,CACF,CAAC;IAEF,GAAG,CAAC,IAAI,CACN,yCAAyC,EACzC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,EAAE,EACnD,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QACvB,yEAAyE;QACzE,yEAAyE;QACzE,wDAAwD;QACxD,oEAAoE;QACpE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3E,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7C,CAAC,CACF,CAAC;IAEF,GAAG,CAAC,GAAG,CACL,mCAAmC,EACnC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,EAAE,EAClD,KAAK,EAAE,OAAO,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3E,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAClD,CAAC,CACF,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,CAczB;IACC,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,eAAe,EAAE,CAAC,CAAC,eAAe;QAClC,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,IAAI,GAAG,CAAC;QAC/C,UAAU,EAAG,CAAC,CAAC,eAAe,EAAE,CAAC,YAAY,CAAwB,IAAI,IAAI;QAC7E,eAAe,EAAG,CAAC,CAAC,eAAe,EAAE,CAAC,iBAAiB,CAAwB,IAAI,IAAI;QACvF,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;QACzD,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;QAChD,iBAAiB,EAAE,CAAC,CAAC,iBAAiB,IAAI,IAAI;QAC9C,eAAe,EAAE,CAAC,CAAC,eAAe,IAAI,IAAI;QAC1C,aAAa,EAAE,CAAC,CAAC,aAAa,IAAI,IAAI;QACtC,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC;AACJ,CAAC"}

package/dist/backend/services/gateway-refund-registry.d.ts

@@ -0,0 +1,122 @@
+import type { PaymentRefundInput, PaymentRefundResult } from '@endora-commerce/contracts';
+/**
+ * GatewayRefundRegistry (feature 049) — the generic seam through which a PSP
+ * vendor module (e.g. Stripe) fulfils refunds for `kind === 'gateway'` payments.
+ *
+ * Mirrors the PaymentAdapterRegistry pattern: a vendor module imports this
+ * process-wide singleton and registers its refund handler from its boot hook,
+ * so the platform has exactly one table of handlers however many times it is
+ * composed. `PaymentRefundProvider` consults it for gateway payments and falls
+ * back to `pending_manual` when no handler answers — keeping the `payments` and
+ * `returns` modules provider-agnostic.
+ *
+ * **Every entry names the module that contributed it (feature 074, FR-024).**
+ * This is a contribution registry in D-39's sense: the push is ungated — a boot
+ * hook runs whatever the contributing module's effective state is, and gating
+ * the push would make a deactivation survive as a permanently missing entry —
+ * so the presence question is answered *here*, at enumeration, keyed on the
+ * owner recorded with the entry. Until this shipped the registry recorded no
+ * owner and stated no policy, and D-44 §7 named it the one live instance of
+ * that gap: a switched-off gateway went on refunding through its own PSP API.
+ *
+ * **The policy this registry states: skip an absent owner's handler, and say
+ * so (D-71).** `get`, `resolve` and `list` answer as if it were not registered;
+ * `entry`, `ownerOf`, {@link GatewayRefundRegistry.absentOwnerFor} and `listAll`
+ * deliberately do not filter, because a settlement screen has to keep showing
+ * the handler *and* the reason it is unavailable — and because the caller has to
+ * be able to tell "switched off" from "never installed", which one empty
+ * `resolve` cannot. Three things decide the skip, and the money is on the other
+ * side of each:
+ *
+ *  1. A module that is off must not act. Refunding through a PSP the operator
+ *    switched off charges that PSP's API with that operator's credentials —
+ *    the opposite of "behaves as if never installed" (Principle XVII).
+ *  2. **The obligation is not dropped with the handler.** The caller has to say
+ *    what happens next, and the two situations it can be in are not the same
+ *    one: a deployment that never installed a PSP integration records
+ *    `pending_manual` and settles by hand, while a gateway an operator switched
+ *    off is a capability that is *supposed* to be there and can be back in one
+ *    click. D-71 rules the second a **refusal**, not an outcome — see
+ *    `PaymentRefundProvider`.
+ *  3. {@link resolve} answers with the sole registered handler when the order
+ *    names no adapter. Honouring an absent owner would route exactly those
+ *    refunds — the ones with the least information behind them — into a
+ *    switched-off gateway.
+ *
+ * Feature 075's Phase C took the cut Phase P set up: the two shapes `returns`
+ * declares are read from `@endora-commerce/contracts` now, so this file names no other
+ * module. The declaration itself stays here rather than being replaced by the
+ * package's structurally identical `GatewayRefundRegistryPort`, and the reason
+ * is `absentOwnerFor`: the published port is the **contribution** surface the
+ * gateways push into, and it deliberately does not carry the question D-71
+ * added — "which module *would* have handled this, but is switched off". That
+ * question is what keeps a refusal apart from `pending_manual`, and it is asked
+ * by this module's own `PaymentRefundProvider` over this module's own registry,
+ * which is not a cross-module call at all.
+ */
+export interface GatewayRefundHandler {
+    /** The payment adapter key this handler serves (e.g. `stripe`). */
+    readonly adapterKey: string;
+    refund(input: PaymentRefundInput): Promise<PaymentRefundResult>;
+}
+export interface RegistryLogger {
+    warn(message: string): void;
+}
+/** One contributed handler, with the module that contributed it. */
+export interface GatewayRefundEntry {
+    readonly handler: GatewayRefundHandler;
+    readonly module: string;
+}
+export declare class GatewayRefundRegistry {
+    private readonly log;
+    private readonly isModulePresent;
+    private readonly handlers;
+    /**
+     * @param log             collision warnings.
+     * @param isModulePresent the effective-state probe. Defaults to
+     *   always-present, so a registry a unit test builds for itself keeps
+     *   answering about the handlers that test registered; the process singleton
+     *   wires it to the kernel's effective state.
+     */
+    constructor(log?: RegistryLogger, isModulePresent?: (moduleId: string) => boolean);
+    register(handler: GatewayRefundHandler, moduleId: string): void;
+    unregister(adapterKey: string): void;
+    /** The contributed entry, presence-blind. Diagnostics read this. */
+    entry(adapterKey: string): GatewayRefundEntry | undefined;
+    /** The module that contributed `adapterKey`, or `null` when nobody did. */
+    ownerOf(adapterKey: string): string | null;
+    /**
+     * The module that would have handled this refund but is not present (D-71).
+     *
+     * The question a caller asks *after* {@link resolve} declined, because one
+     * empty `resolve` covers two situations that are not interchangeable: a
+     * gateway an operator switched off is a capability restorable in one click
+     * and must be **refused**, while an adapter nobody ever registered is a
+     * deployment with no PSP integration, which records the obligation and
+     * settles by hand.
+     *
+     * It mirrors `resolve`'s two arms exactly, which is why the unkeyed one is
+     * here at all: `resolve` answers with the sole registered handler when the
+     * order names no adapter, and point 3 of the docblock above says that is the
+     * worst arm to get wrong — the refunds with the least information behind
+     * them. Presence-blind in the same sense `ownerOf` is.
+     */
+    absentOwnerFor(adapterKey?: string | null): string | null;
+    /** The handler, or `undefined` when unregistered or its owner is absent. */
+    get(adapterKey: string): GatewayRefundHandler | undefined;
+    /**
+     * Resolve the handler for a gateway payment.
+     * - Known `adapterKey` → exact handler only (never guess another PSP).
+     * - Missing key → sole registered handler when exactly one exists.
+     *
+     * Both arms drop a handler whose owner is absent, and the second arm counts
+     * only the handlers that are available: with one gateway installed and
+     * switched off, "the sole registered handler" must not be it.
+     */
+    resolve(adapterKey?: string | null): GatewayRefundHandler | undefined;
+    /** Adapter keys whose owner is present (stable insertion order). */
+    list(): string[];
+    /** Every registered adapter key, presence-blind. */
+    listAll(): string[];
+}
+//# sourceMappingURL=gateway-refund-registry.d.ts.map

package/dist/backend/services/gateway-refund-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-refund-registry.d.ts","sourceRoot":"","sources":["../../../src/backend/services/gateway-refund-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,qBAAqB;IAW9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAXlC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;;;;;OAMG;gBAEgB,GAAG,GAAE,cAA8B,EACnC,eAAe,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAoB;IAG9E,QAAQ,CAAC,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAW/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIpC,oEAAoE;IACpE,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIzD,2EAA2E;IAC3E,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI1C;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI;IAczD,4EAA4E;IAC5E,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAMzD;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,oBAAoB,GAAG,SAAS;IAUrE,oEAAoE;IACpE,IAAI,IAAI,MAAM,EAAE;IAMhB,oDAAoD;IACpD,OAAO,IAAI,MAAM,EAAE;CAGpB"}