@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/verifiedIngress.js

@@ -0,0 +1,220 @@
+import { projectVerifiedEvidence } from "./verifiedEvidenceProjection.js";
+const PAYMENT_WEBHOOK_EVENT_TYPES = [
+    "payment.succeeded",
+    "payment.failed",
+    "payment.refunded",
+    "payment.requires_action",
+    "payment.disputed",
+    "setup.succeeded",
+    "setup.failed",
+    "setup.requires_action",
+];
+/** Verified ingress boundary; persistence and transport response writing belong to the host. */
+export function createVerifiedPaymentIngress({ provider, verifyPort, paymentControlPort, methodRefPort, afterProcessed, createPorts, resolveMethodOwner, refundEvidencePolicy = "require-evidence", operationalEvents = () => { }, }) {
+    return { async receive(input) {
+            let evidence;
+            try {
+                evidence = await verifyPort.verifyAndNormalize(input);
+            }
+            catch {
+                return { status: 400, data: { error: "Invalid provider webhook signature" } };
+            }
+            if (evidence.kind === "refusal") {
+                return evidence.reason === "unsupported-event"
+                    ? { status: 200, data: { provider, acknowledged: true, skipped: "unsupported_event" } }
+                    : { status: 400, data: { error: "Invalid provider webhook signature" } };
+            }
+            const verifiedEvidence = evidence;
+            let event;
+            const res = { status: 503, data: {} };
+            const sendSuccess = (target, data) => { target.status = 200; target.data = data; };
+            const sendBffError = (target, code, error) => {
+                target.status = code === "BAD_REQUEST" ? 400 : code === "CONFLICT" ? 409 : 503;
+                target.data = { error };
+            };
+            await processEvent();
+            return res;
+            async function processEvent() {
+                try {
+                    try {
+                        event = projectVerifiedEvidence(verifiedEvidence, input, refundEvidencePolicy);
+                    }
+                    catch (error) {
+                        if (error instanceof Error && error.message === "payment_control_result_amount_mismatch")
+                            throw error;
+                        sendBffError(res, "BAD_REQUEST", "Invalid provider webhook evidence");
+                        return;
+                    }
+                    if (event.provider !== provider) {
+                        sendBffError(res, "BAD_REQUEST", "Provider webhook route mismatch");
+                        return;
+                    }
+                    if (verifiedEvidence.kind === "method" && verifiedEvidence.reusableMethod && resolveMethodOwner) {
+                        const owner = await resolveMethodOwner(verifiedEvidence);
+                        event = projectVerifiedEvidence(verifiedEvidence, input, refundEvidencePolicy, owner ?? undefined);
+                    }
+                    const ports = createPorts
+                        ? await createPorts(event)
+                        : { paymentControlPort: paymentControlPort, methodRefPort, afterProcessed };
+                    if (!ports.paymentControlPort)
+                        throw new Error("Provider webhook port unavailable");
+                    const ingested = await ports.paymentControlPort.ingestPaymentEvent(event);
+                    if (ingested.occurredAt)
+                        event = { ...event, occurredAt: ingested.occurredAt };
+                    const resultStatus = mapResultStatus(event, refundEvidencePolicy);
+                    if (resultStatus && ingested.paymentIntentId && ports.paymentControlPort.applyPaymentResult) {
+                        await ports.paymentControlPort.applyPaymentResult({
+                            idempotencyKey: `provider-webhook:${provider}:${event.providerEventId}:apply`,
+                            paymentIntentId: ingested.paymentIntentId,
+                            paymentEventId: ingested.paymentEventId,
+                            resultStatus,
+                            occurredAt: event.occurredAt,
+                            failureReason: event.eventType === "payment.failed" ? "provider_webhook_failed" : null,
+                        });
+                    }
+                    else if (isMoneyMoved(resultStatus) && !ingested.paymentIntentId && !ingested.replayed) {
+                        // Operator policy: payments should only originate at the storefront
+                        // checkout. A money-moved provider event (succeeded / refunded /
+                        // disputed) that matched no local intent is an out-of-band payment
+                        // (provider panel payment-link, dashboard link/invoice, wallet, card
+                        // terminal). It is recorded in inbound_provider_events and ACKed, but
+                        // there is no order to settle, invoice, or fulfill — the safe no-op above
+                        // is intentional and preserved. Emit a vendor-neutral, non-paging
+                        // reconciliation signal so the money is never silently lost.
+                        // Fires once per unique provider event (`!replayed`): the ingest RPC is
+                        // idempotent on (provider, provider_event_id), so PSP re-delivery is a
+                        // natural throttle.
+                        operationalEvents({
+                            name: "provider_payment_unmatched_out_of_band",
+                            domain: "payment",
+                            surface: "webhook",
+                            details: {
+                                provider,
+                                providerPaymentId: event.providerPaymentId,
+                                eventType: event.eventType,
+                                resultStatus,
+                                amountMinor: event.amountMinor ?? null,
+                                currency: event.currency ?? null,
+                                occurredAt: event.occurredAt,
+                            },
+                        });
+                    }
+                    if (ports.methodRefPort) {
+                        await ports.methodRefPort.upsertFromWebhook(event);
+                    }
+                    if (ports.afterProcessed) {
+                        await ports.afterProcessed({ event, ingested, resultStatus });
+                    }
+                    // Reached only when every setup mutation above resolved (a throw 5xx's →
+                    // provider redelivers into a still-'received' row). Runs on replays too,
+                    // so redelivery self-heals rows stuck from before this closer existed.
+                    if (resultStatus === null && event.eventType.startsWith("setup.") && ports.paymentControlPort.markSetupEventProcessed) {
+                        await ports.paymentControlPort.markSetupEventProcessed({ paymentEventId: ingested.paymentEventId });
+                    }
+                    sendSuccess(res, {
+                        provider,
+                        providerEventId: event.providerEventId,
+                        paymentEventId: ingested.paymentEventId,
+                        replayed: ingested.replayed,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    // A genuine idempotency conflict (same key, different payload) is a client
+                    // 409, not a transient 5xx — a 503 would make the provider retry a request
+                    // that can never succeed. The method-ref RPC raises this on a fingerprint
+                    // mismatch (SQLSTATE 23505).
+                    if (/payment_method_ref_idempotency_conflict|commerce_idempotency_conflict|\b23505\b/.test(message)) {
+                        sendBffError(res, "CONFLICT", "Webhook idempotency conflict");
+                        return;
+                    }
+                    // A `succeeded` result that arrives AFTER the provisional-subscription
+                    // sweep has already terminalized the intent (cancelled/refunded/…) is
+                    // rejected by `apply_result` with `payment_control_result_terminal_intent`
+                    // (ERRCODE 22023). The money question is already settled from the control
+                    // plane's perspective, so this is a "no work left to do" outcome, not a
+                    // transient upstream failure — ACK 200 so the provider stops
+                    // retrying for days (retry-storm / charge-without-fulfillment risk). We
+                    // match the RPC's exception text specifically, NOT the bare 22023 code,
+                    // because 22023 is also raised for genuine mismatches (amount / currency /
+                    // intent-not-found) that must still surface as 503.
+                    if (event && /payment_control_result_terminal_intent/.test(message)) {
+                        operationalEvents({
+                            name: "provider_payment_result_after_terminal_intent",
+                            domain: "payment",
+                            surface: "webhook",
+                            details: {
+                                provider,
+                                providerEventId: event.providerEventId,
+                                providerPaymentId: event.providerPaymentId,
+                                eventType: event.eventType,
+                                occurredAt: event.occurredAt,
+                            },
+                        });
+                        sendSuccess(res, {
+                            provider,
+                            providerEventId: event.providerEventId,
+                            acknowledged: true,
+                            skipped: "result_terminal_intent",
+                        });
+                        return;
+                    }
+                    // The event cannot be attributed to the intent's exact active attempt:
+                    // either it named another attempt (the slow-webhook shape and possible
+                    // double charge) or ingest could not correlate it at all. Neither answer
+                    // changes on redelivery, so ACK 200 instead of creating an endless retry
+                    // loop. The durable inbound event and this reason route operator recovery.
+                    // Match named reasons only, never the shared 22023 SQLSTATE.
+                    if (event && /payment_control_result_attempt_(?:mismatch|unresolved)/.test(message)) {
+                        const reason = message.includes("payment_control_result_attempt_unresolved")
+                            ? "attempt_unresolved"
+                            : "attempt_mismatch";
+                        operationalEvents({
+                            name: "provider_payment_result_attempt_mismatch",
+                            domain: "payment",
+                            surface: "webhook",
+                            // `providerPaymentId`, not `providerEventId`, is the operator's handle:
+                            // the detail allowlist carries the former and drops the latter, and it
+                            // is the value `ingest_event` correlated the attempt from.
+                            details: {
+                                provider,
+                                providerPaymentId: event.providerPaymentId,
+                                eventType: event.eventType,
+                                resultStatus: mapResultStatus(event, refundEvidencePolicy),
+                                occurredAt: event.occurredAt,
+                                reason,
+                            },
+                        });
+                        sendSuccess(res, {
+                            provider,
+                            providerEventId: event.providerEventId,
+                            acknowledged: true,
+                            skipped: "result_attempt_mismatch",
+                        });
+                        return;
+                    }
+                    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Provider webhook processing failed");
+                }
+            }
+        } };
+}
+function mapResultStatus(event, refundEvidencePolicy) {
+    if (event.eventType === "payment.succeeded")
+        return "succeeded";
+    if (event.eventType === "payment.failed")
+        return "failed";
+    if (event.eventType === "payment.refunded") {
+        if (refundEvidencePolicy === "require-evidence" && (event.refundKind == null || !event.providerPaymentId.trim() || !Number.isSafeInteger(event.amountMinor) || (event.amountMinor ?? 0) <= 0 || !event.currency?.trim()))
+            return null;
+        return event.refundKind === "partial" ? "partially_refunded" : "refunded";
+    }
+    if (event.eventType === "payment.disputed")
+        return "disputed";
+    return null;
+}
+// "Money moved" for reconciliation purposes: a settled charge, a refund, or a
+// chargeback/dispute. `failed` (no money moved) and `null` (setup / non-money
+// events) are excluded — an unmatched failed/setup event needs no reconciliation.
+function isMoneyMoved(resultStatus) {
+    return resultStatus !== null && resultStatus !== "failed";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.20.0",
+    "@openlup/core": "0.21.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -175,6 +175,26 @@
       "types": "./dist/shipping/contracts/index.d.ts",
       "import": "./dist/shipping/contracts/index.js",
       "default": "./dist/shipping/contracts/index.js"
+    },
+    "./payments": {
+      "types": "./dist/payments/index.d.ts",
+      "import": "./dist/payments/index.js",
+      "default": "./dist/payments/index.js"
+    },
+    "./payments/contracts": {
+      "types": "./dist/payments/contracts/index.d.ts",
+      "import": "./dist/payments/contracts/index.js",
+      "default": "./dist/payments/contracts/index.js"
+    },
+    "./payments/stripe": {
+      "types": "./dist/payments/stripe/index.d.ts",
+      "import": "./dist/payments/stripe/index.js",
+      "default": "./dist/payments/stripe/index.js"
+    },
+    "./payments/tpay": {
+      "types": "./dist/payments/tpay/index.d.ts",
+      "import": "./dist/payments/tpay/index.js",
+      "default": "./dist/payments/tpay/index.js"
     }
   },
   "repository": {

package/release-gates.json

@@ -355,6 +355,66 @@
       ],
       "entrypoint": "dist/shipping/contracts/index.d.ts",
       "snapshot": "api/shipping-contracts.api.md"
+    },
+    "./payments": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/payments/preparedAttempt.test.ts",
+        "test/payments/verifiedIngress.test.ts",
+        "test/payments/refundEvidence.test.ts",
+        "test/payments/truth.test.ts",
+        "test/payments/reconciliation.test.ts",
+        "test/payments/adapterConformance.test.ts",
+        "test/payments/postgresPaymentTruth.test.ts"
+      ],
+      "entrypoint": "dist/payments/index.d.ts",
+      "snapshot": "api/payments.api.md"
+    },
+    "./payments/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/payments/contracts.test.ts",
+        "test/payments/verifiedIngress.test.ts",
+        "test/payments/refundEvidence.test.ts",
+        "test/payments/truth.test.ts",
+        "test/payments/reconciliation.test.ts",
+        "test/payments/adapterConformance.test.ts",
+        "test/payments/postgresPaymentTruth.test.ts"
+      ],
+      "entrypoint": "dist/payments/contracts/index.d.ts",
+      "snapshot": "api/payments-contracts.api.md"
+    },
+    "./payments/stripe": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/payments/stripe/conformance.test.ts",
+        "test/payments/stripe/factory.test.ts",
+        "test/payments/stripe/stripeWebhookNormalizer.test.ts",
+        "test/payments/stripe/stripeSandboxPaymentExecutionAdapter.test.ts"
+      ],
+      "entrypoint": "dist/payments/stripe/index.d.ts",
+      "snapshot": "api/payments-stripe.api.md"
+    },
+    "./payments/tpay": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/payments/tpay/factory.test.ts",
+        "test/payments/tpay/conformance.test.ts",
+        "test/payments/tpay/webhookNormalizer.test.ts",
+        "test/payments/tpay/tpayPaymentExecutionAdapter.test.ts"
+      ],
+      "entrypoint": "dist/payments/tpay/index.d.ts",
+      "snapshot": "api/payments-tpay.api.md"
     }
   },
   "pack": {
@@ -370,8 +430,8 @@
     "maxUnpackedBytes": 5734400,
     "maxFiles": 2100,
     "baseline": {
-      "version": "0.19.0",
-      "packedBytes": 805872
+      "version": "0.20.0",
+      "packedBytes": 809376
     },
     "browserEntries": {
       "./catalog/contracts": 4096,
@@ -380,7 +440,8 @@
       "./inventory/contracts": 32,
       "./pricing/contracts": 416,
       "./promotions/contracts": 32,
-      "./shipping/contracts": 32
+      "./shipping/contracts": 32,
+      "./payments/contracts": 32
     }
   }
 }