@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/stripe/stripeFailureEvidence.js

@@ -0,0 +1,82 @@
+import { isPaymentRetryAdviceCode } from "@openlup/core/payment";
+import { evidenceRecord, evidenceToken, failureEvidencePayload, serializeFailureEvidence } from "./paymentFailureEvidence.js";
+/** Reads only one current PaymentIntent/error, never an arbitrary historical Charge. */
+export function stripeFailureEvidence(input, options) {
+    const object = evidenceRecord(input);
+    const thrown = object.type === "StripeCardError";
+    const intent = thrown ? evidenceRecord(object.payment_intent) : object;
+    const error = thrown ? object : evidenceRecord(intent.last_payment_error);
+    if (!thrown && !options.confirmedFailureEvent && Object.keys(error).length === 0)
+        return null;
+    const refusalVerified = thrown || options.confirmedFailureEvent === true
+        || (intent.status === "requires_payment_method" && Object.keys(error).length > 0
+            && (error.type === "card_error" || error.code === "card_declined" || Boolean(intent.latest_charge)));
+    const errorMethod = evidenceRecord(error.payment_method);
+    const currentMethod = evidenceRecord(intent.payment_method);
+    const errorMethodId = typeof error.payment_method === "string" ? error.payment_method : errorMethod.id;
+    const currentMethodId = typeof intent.payment_method === "string" ? intent.payment_method : currentMethod.id;
+    const conflictingMethod = Boolean(errorMethodId && currentMethodId && errorMethodId !== currentMethodId)
+        || Boolean(errorMethod.type && currentMethod.type && errorMethod.type !== currentMethod.type);
+    const actualMethod = errorMethod.type ?? currentMethod.type;
+    const cardContract = options.knownCardOnlyRequest === true
+        || (Array.isArray(intent.payment_method_types) && intent.payment_method_types.length === 1
+            && intent.payment_method_types[0] === "card");
+    const flow = evidenceRecord(intent.metadata).providerFlow;
+    const operation = flow === "off_session_payment" ? "stored_method_payment"
+        : intent.setup_future_usage === "off_session" ? "recurring_setup"
+            : intent.setup_future_usage === null && flow === "one_time_payment" ? "one_time_payment" : null;
+    const methodKind = actualMethod === "card" || actualMethod === "blik" ? actualMethod
+        : actualMethod == null && cardContract ? "card" : null;
+    const method = methodKind
+        ? { kind: methodKind, recoveryMethodKey: methodKind, interaction: operation === "stored_method_payment" ? "stored_instrument" : "new_instrument" } : null;
+    const latestCharge = typeof intent.latest_charge === "string" ? intent.latest_charge : evidenceRecord(intent.latest_charge).id;
+    const errorCharge = typeof error.charge === "string" ? error.charge : evidenceRecord(error.charge).id;
+    // A last error tied to another charge cannot explain the currently observed charge.
+    const conflictingEvidence = conflictingMethod || Boolean(latestCharge && errorCharge && latestCharge !== errorCharge);
+    return serializeFailureEvidence({
+        version: 1, source: options.source,
+        disposition: conflictingEvidence ? "unreadable" : Object.keys(error).length ? "present" : "absent",
+        refusalVerified: refusalVerified && !conflictingEvidence, providerPaymentId: evidenceToken(intent.id),
+        providerChargeId: evidenceToken(errorCharge ?? latestCharge),
+        code: conflictingEvidence ? null : evidenceToken(error.code),
+        declineCode: conflictingEvidence ? null : evidenceToken(error.decline_code),
+        adviceCode: conflictingEvidence ? null : evidenceToken(error.advice_code),
+        adviceOrigin: "provider", operation: conflictingEvidence ? null : operation, method: conflictingEvidence ? null : method,
+        methodSource: actualMethod != null ? "provider" : cardContract ? "execution_contract" : "unknown",
+    });
+}
+const SAFE_CAUSES = {
+    insufficient_funds: "insufficient_funds", expired_card: "expired_card",
+    incorrect_cvc: "invalid_payment_data", invalid_cvc: "invalid_payment_data",
+    incorrect_number: "invalid_payment_data", invalid_number: "invalid_payment_data",
+    invalid_expiry_month: "invalid_payment_data", invalid_expiry_year: "invalid_payment_data",
+    authentication_required: "authentication_required",
+    card_not_supported: "operation_unsupported", currency_not_supported: "operation_unsupported",
+    transaction_not_allowed: "operation_unsupported",
+};
+const RESTRICTED = new Set(["fraudulent", "highest_risk_level", "lost_card", "stolen_card", "merchant_blacklist"]);
+/** UI evidence only: does not call or alter the shared failure taxonomy. */
+export function normalizeStripeFailureEvidence(input) {
+    const evidence = serializeFailureEvidence(input);
+    const code = evidence.declineCode ?? evidence.code;
+    const restricted = code !== null && RESTRICTED.has(code);
+    const readable = evidence.refusalVerified && evidence.disposition === "present";
+    // A refused BLIK registration names its operation, not a setup cause: no code
+    // read here distinguishes a refused agreement from a mistyped or expired code.
+    const cause = readable && !restricted && code && Object.hasOwn(SAFE_CAUSES, code)
+        ? SAFE_CAUSES[code] : "generic_decline";
+    return {
+        refusalVerified: evidence.refusalVerified, cause,
+        certainty: cause === "generic_decline" ? "unknown" : "verified",
+        disclosure: restricted ? "restricted" : "safe", method: evidence.method, operation: evidence.operation,
+        advice: readable && evidence.adviceOrigin === "provider" && evidence.adviceCode !== null && isPaymentRetryAdviceCode(evidence.adviceCode)
+            ? { code: evidence.adviceCode, scope: evidence.method?.kind === "card" ? "instrument" : "unknown" } : null,
+    };
+}
+/** Preserve the existing webhook projection and append only failure diagnostics. */
+export function stripeWebhookPayload(input, object) {
+    return { provider: "stripe", ...input,
+        ...(input.eventType === "payment_intent.payment_failed"
+            ? failureEvidencePayload(stripeFailureEvidence(object, { source: "webhook", confirmedFailureEvent: true })) : {}),
+    };
+}

package/dist/payments/stripe/stripeIntentConfirmationEvidence.d.ts

@@ -0,0 +1,28 @@
+import type { StripeIntentLike } from "./stripeSandboxPaymentExecutionAdapter.js";
+/**
+ * `requires_payment_method` on an intent that was never confirmed: no payment
+ * method attached, no charge, no payment error. The provider object exists —
+ * the request reached the provider and was accepted — but the payer never
+ * submitted an instrument, so no issuer was ever asked to approve anything.
+ *
+ * Both absences beside the status are load-bearing. A payment method attached
+ * but not yet confirmed means a charge may be seconds from moving; a charge or a
+ * payment error means an issuer HAS been asked and answered. Either presence
+ * makes this claim false, and the claim is used to decide what a durable row
+ * says about the payer's money, so it must stay narrow rather than convenient.
+ *
+ * Shared deliberately. The execution rail asserts it to record what a fresh
+ * intent is, and the reconciliation rail asserts it to answer a payer who is
+ * still standing in the checkout. Those are two readings of ONE provider state,
+ * and two copies of the predicate would let them drift into disagreeing about
+ * whether the same intent had been attempted — the kind of drift that is only
+ * discovered by a payer being told the wrong thing about their own payment.
+ *
+ * ⛔ Not to be widened into "the payer has gone" (abandonment). That is a
+ * separate verdict, passed on a payer who is no longer present, and it
+ * deliberately asserts fewer absences so a real refusal is never mislabelled as
+ * abandonment. Merging the two would put one predicate under two opposite
+ * pressures: this one must stay narrow so no live charge is called idle, that
+ * one must stay broad so no refusal is silently dropped out of dunning.
+ */
+export declare function noIssuerWasAsked(intent: StripeIntentLike): boolean;

package/dist/payments/stripe/stripeIntentConfirmationEvidence.js

@@ -0,0 +1,32 @@
+/**
+ * `requires_payment_method` on an intent that was never confirmed: no payment
+ * method attached, no charge, no payment error. The provider object exists —
+ * the request reached the provider and was accepted — but the payer never
+ * submitted an instrument, so no issuer was ever asked to approve anything.
+ *
+ * Both absences beside the status are load-bearing. A payment method attached
+ * but not yet confirmed means a charge may be seconds from moving; a charge or a
+ * payment error means an issuer HAS been asked and answered. Either presence
+ * makes this claim false, and the claim is used to decide what a durable row
+ * says about the payer's money, so it must stay narrow rather than convenient.
+ *
+ * Shared deliberately. The execution rail asserts it to record what a fresh
+ * intent is, and the reconciliation rail asserts it to answer a payer who is
+ * still standing in the checkout. Those are two readings of ONE provider state,
+ * and two copies of the predicate would let them drift into disagreeing about
+ * whether the same intent had been attempted — the kind of drift that is only
+ * discovered by a payer being told the wrong thing about their own payment.
+ *
+ * ⛔ Not to be widened into "the payer has gone" (abandonment). That is a
+ * separate verdict, passed on a payer who is no longer present, and it
+ * deliberately asserts fewer absences so a real refusal is never mislabelled as
+ * abandonment. Merging the two would put one predicate under two opposite
+ * pressures: this one must stay narrow so no live charge is called idle, that
+ * one must stay broad so no refusal is silently dropped out of dunning.
+ */
+export function noIssuerWasAsked(intent) {
+    return intent.status === "requires_payment_method"
+        && !intent.payment_method
+        && !intent.latest_charge
+        && !intent.last_payment_error;
+}

package/dist/payments/stripe/stripePaymentReconciliationProvider.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderReconciliationStatus } from "./donorContracts.js";
+import type { PaymentProviderRecoveryProvider } from "./donorContracts.js";
+import type { StripeIntentLike } from "./stripeSandboxPaymentExecutionAdapter.js";
+export interface StripePaymentIntentReader {
+    retrievePaymentIntent(paymentIntentId: string): Promise<StripeIntentLike>;
+    cancelPaymentIntent?(paymentIntentId: string): Promise<StripeIntentLike>;
+}
+export interface StripePaymentIntentSearcher {
+    /**
+     * Search Stripe PaymentIntents by a metadata key/value pair (GET
+     * /v1/payment_intents/search). Every intent the payment-control adapter
+     * creates carries metadata.paymentIntentId = <local intent uuid>
+     * (stripeSandboxPaymentExecutionAdapter metadataFor), so this is the
+     * intent-correlated absence probe for prepared attempts that never recorded
+     * a provider payment id.
+     */
+    searchPaymentIntentsByMetadata(input: {
+        key: string;
+        value: string;
+        limit?: number;
+    }): Promise<{
+        ids: string[];
+    }>;
+}
+export declare function createStripePaymentReconciliationProvider(client: StripePaymentIntentReader & Partial<StripePaymentIntentSearcher>): PaymentProviderRecoveryProvider;
+export declare function normalizeStripeIntent(intent: StripeIntentLike): ProviderReconciliationStatus;
+/**
+ * The disposition of a failed intent nobody actually refused.
+ *
+ * Deliberately NOT a taxonomy class. The kernel classifies REFUSALS — it answers
+ * "may this instrument be charged again, and by whom" — and an absence of
+ * attempt is not a refusal, so an "abandonment" class would be a category error
+ * inside a vocabulary whose every other member describes an issuer's verdict.
+ */
+export declare const ABANDONED_BEFORE_CONFIRMATION = "abandoned_before_confirmation";

package/dist/payments/stripe/stripePaymentReconciliationProvider.js

@@ -0,0 +1,222 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { classifyDecline } from "./classifyDecline.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+import { noIssuerWasAsked } from "./stripeIntentConfirmationEvidence.js";
+export function createStripePaymentReconciliationProvider(client) {
+    const search = client.searchPaymentIntentsByMetadata?.bind(client);
+    const cancel = client.cancelPaymentIntent?.bind(client);
+    return {
+        resolvePaymentReference(input) {
+            return input.providerAttemptId ?? input.intentProviderPaymentId ?? input.providerSessionId;
+        },
+        async readRecoveryPayment(input) {
+            const intent = await client.retrievePaymentIntent(input.providerPaymentId);
+            let status = normalizeStripeIntent(intent);
+            let clientAction = null;
+            if (intent.status === "processing" || intent.status === "requires_capture") {
+                clientAction = null;
+            }
+            else if (input.purpose === "active_checkout" && noIssuerWasAsked(intent)) {
+                clientAction = embeddedAction(intent.client_secret);
+                // The status is lowered whether or not a form can be handed back. Our
+                // inability to reopen the card panel is a fact about US; it is not an
+                // issuer's refusal, and it must not be recorded as one.
+                status = { ...status, status: "pending" };
+            }
+            else if (intent.status === "requires_action" || intent.status === "requires_confirmation") {
+                clientAction = embeddedAction(intent.client_secret);
+                // Global reconciliation treats requires_action as terminal for
+                // off-session dunning. Buyer recovery is different: without a current
+                // client secret it is uncertain, not permission to open a new intent.
+                if (!clientAction || input.purpose === "active_checkout") {
+                    status = { ...status, status: "pending" };
+                }
+            }
+            return {
+                status,
+                identityMatches: intent.id === input.providerPaymentId,
+                configuredMoneyMatches: stripeConfiguredMoneyMatches(intent, input.attempt),
+                manualReviewRequired: false,
+                clientAction,
+            };
+        },
+        async readPayment(input) {
+            const intent = await client.retrievePaymentIntent(input.providerPaymentId);
+            const status = normalizeStripeIntent(intent);
+            // Same rule as the recovery read above, on the rail the buyer's own
+            // "check it now" travels: an intent no issuer has been asked about is
+            // unsettled, not refused. Only `active_checkout` gets this reading, so
+            // the reconciliation worker — which names no purpose — goes on
+            // terminalizing abandonment exactly as before.
+            return input.purpose === "active_checkout" && noIssuerWasAsked(intent)
+                ? { ...status, status: "pending" }
+                : status;
+        },
+        ...(cancel
+            ? {
+                async closePayment(input) {
+                    return normalizeStripeIntent(await cancel(input.providerPaymentId));
+                },
+            }
+            : {}),
+        ...(search
+            ? {
+                async findPaymentByLocalIntent(input) {
+                    const result = await search({
+                        key: "paymentIntentId",
+                        value: input.attempt.paymentIntentId,
+                        limit: 1,
+                    });
+                    return result.ids.length > 0 ? "found" : "absent";
+                },
+            }
+            : {}),
+    };
+}
+export function normalizeStripeIntent(intent) {
+    const status = normalizeStripeStatus(intent.status);
+    return {
+        status,
+        providerStatus: intent.status,
+        occurredAt: null,
+        failureReason: failureReason(intent),
+        amountMinor: readAmountMinor(intent),
+        currency: typeof intent.currency === "string" ? intent.currency.toUpperCase() : null,
+        rawPayload: {
+            provider: "stripe",
+            paymentIntentId: intent.id,
+            status: intent.status,
+            latestChargePresent: Boolean(intent.latest_charge),
+            nextActionType: intent.next_action?.type ?? null,
+            lastPaymentErrorCode: intent.last_payment_error?.code ?? null,
+            lastPaymentErrorType: intent.last_payment_error?.type ?? null,
+            ...failureCapture(intent),
+            ...failureEvidencePayload(intent.diagnosticFailureEvidence),
+        },
+    };
+}
+/**
+ * The disposition of a failed intent nobody actually refused.
+ *
+ * Deliberately NOT a taxonomy class. The kernel classifies REFUSALS — it answers
+ * "may this instrument be charged again, and by whom" — and an absence of
+ * attempt is not a refusal, so an "abandonment" class would be a category error
+ * inside a vocabulary whose every other member describes an issuer's verdict.
+ */
+export const ABANDONED_BEFORE_CONFIRMATION = "abandoned_before_confirmation";
+/**
+ * `requires_payment_method` on an intent that was never confirmed: no
+ * `last_payment_error`, no charge. The buyer closed the tab; no issuer was ever
+ * asked. Six of the fifteen production failure rows in the historical corpus are
+ * this state.
+ *
+ * Both absences are required before the claim is made. Presence of either is
+ * evidence an attempt happened, and mislabelling a real decline as abandonment
+ * would silently drop it out of dunning — the more expensive of the two errors.
+ */
+function abandonedBeforeConfirmation(intent) {
+    return intent.status === "requires_payment_method"
+        && !intent.last_payment_error
+        && !intent.latest_charge;
+}
+function embeddedAction(clientSecret) {
+    return typeof clientSecret === "string" && clientSecret.length > 0
+        ? { kind: "provider_embedded", provider: "stripe", clientSecret }
+        : null;
+}
+/**
+ * The refusal evidence this rail can state, and the class it produces.
+ *
+ * This rail births most production failure rows, and it used to keep only
+ * `last_payment_error.code` — the coarse bucket ("card_declined") — while
+ * dropping `decline_code`, the fine code the adapter's hint table is written
+ * against, and `advice_code`, the issuer's own retry verdict. With both gone the
+ * taxonomy had nothing to read here, so the programme's classification telemetry
+ * stayed empty no matter how many refusals arrived.
+ *
+ * Classification goes through the shared `classifyDecline` seam, the same one
+ * the synchronous decline path uses, so there is exactly one place a refusal
+ * becomes a class. Only neutral evidence crosses: this provider's own code
+ * vocabulary is translated here, by this adapter's table, and travels no further.
+ *
+ * The class does not stop here. Since wave 3i-b it reaches the attempt and the
+ * dunning case through the terminal write's two classification parameters, and
+ * from there it becomes the cause sentence the payer is shown. It remains no
+ * part of any retry cadence.
+ */
+function failureCapture(intent) {
+    if (normalizeStripeStatus(intent.status) !== "failed")
+        return {};
+    if (abandonedBeforeConfirmation(intent)) {
+        return { nonDeclineDisposition: ABANDONED_BEFORE_CONFIRMATION };
+    }
+    const declineCode = readCode(intent.last_payment_error?.decline_code);
+    const adviceCode = readCode(intent.last_payment_error?.advice_code);
+    const neutralReasonHints = declineCodeHints(declineCode);
+    const classification = classifyDecline({
+        // Correlation handle only — the kernel never reads it. The intent's own
+        // status is the provider-native fact when the refusal named no code.
+        code: readCode(intent.last_payment_error?.code) ?? intent.status,
+        // A read of an existing intent says nothing about whether the payer's bank
+        // can hold a reusable mandate, so this rail never claims it.
+        mandateUnsupported: false,
+        ...(declineCode ? { declineCode } : {}),
+        ...(adviceCode ? { adviceCode } : {}),
+        ...(neutralReasonHints.length > 0 ? { neutralReasonHints } : {}),
+    }, { failureReasonKey: failureReason(intent) ?? undefined });
+    return {
+        declineCode: declineCode ?? null,
+        adviceCode: adviceCode ?? null,
+        neutralReasonHints,
+        failureClass: classification.failureClass,
+        failureClassDecidedBy: classification.decidedBy,
+    };
+}
+function readCode(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stripeConfiguredMoneyMatches(intent, attempt) {
+    return typeof intent.amount === "number"
+        && Number.isFinite(intent.amount)
+        && intent.amount === attempt.amountMinor
+        && typeof intent.currency === "string"
+        && intent.currency.toUpperCase() === attempt.currency.toUpperCase();
+}
+function normalizeStripeStatus(status) {
+    if (status === "succeeded")
+        return "succeeded";
+    if (status === "requires_action" ||
+        status === "requires_confirmation" ||
+        status === "requires_payment_method" ||
+        status === "canceled") {
+        return "failed";
+    }
+    if (status === "processing" || status === "requires_capture")
+        return "pending";
+    return "unknown";
+}
+function failureReason(intent) {
+    const status = normalizeStripeStatus(intent.status);
+    if (status !== "failed")
+        return null;
+    return intent.last_payment_error?.code
+        ? `stripe_${intent.last_payment_error.code}`
+        : `stripe_${intent.status}`;
+}
+function readAmountMinor(intent) {
+    // amount_received is settlement truth only after success. For an incomplete,
+    // requires-payment-method, cancelled, or requires-capture intent Stripe
+    // legitimately returns 0 while `amount` still holds the configured amount.
+    // Comparing that zero to the local order created a false mismatch and made
+    // reconciliation 502-loop on an ordinary failed payment.
+    if (intent.status === "succeeded" && typeof intent.amount_received === "number" && Number.isFinite(intent.amount_received)) {
+        return intent.amount_received;
+    }
+    if (typeof intent.amount === "number" && Number.isFinite(intent.amount)) {
+        return intent.amount;
+    }
+    if (typeof intent.amount_received === "number" && Number.isFinite(intent.amount_received)) {
+        return intent.amount_received;
+    }
+    return null;
+}

package/dist/payments/stripe/stripeRefundEvidence.d.ts

@@ -0,0 +1,8 @@
+/** A Charge observation is cumulative; its amount never replaces payment amount. */
+export declare function stripeRefundEvidence(eventType: string, charge: Record<string, unknown>): {
+    refundKind: "full" | "partial" | null;
+    snapshot: {
+        chargeId: string;
+        amountRefundedMinor: number;
+    } | null;
+};

package/dist/payments/stripe/stripeRefundEvidence.js

@@ -0,0 +1,17 @@
+/** A Charge observation is cumulative; its amount never replaces payment amount. */
+export function stripeRefundEvidence(eventType, charge) {
+    if (eventType !== "charge.refunded")
+        return { refundKind: null, snapshot: null };
+    const amount = charge.amount;
+    const refunded = charge.amount_refunded;
+    const chargeId = charge.id;
+    if (typeof chargeId !== "string" || !chargeId.trim()
+        || typeof amount !== "number" || !Number.isSafeInteger(amount) || amount <= 0
+        || typeof refunded !== "number" || !Number.isSafeInteger(refunded) || refunded <= 0 || refunded > amount) {
+        return { refundKind: null, snapshot: null };
+    }
+    return {
+        refundKind: refunded === amount ? "full" : "partial",
+        snapshot: { chargeId, amountRefundedMinor: refunded },
+    };
+}

package/dist/payments/stripe/stripeSandboxPaymentExecutionAdapter.d.ts

@@ -0,0 +1,45 @@
+import type { PaymentExecutionPort } from "./donorContracts.js";
+import type { CanonicalPaymentEvent, PaymentProviderFlow } from "./donorContracts.js";
+/** The one place this adapter spells its own provider identity. */
+export declare const PROVIDER_KIND: "stripe";
+import type { StripeIntentLike } from "./stripeFailureEvidence.js";
+export type { StripeIntentLike } from "./stripeFailureEvidence.js";
+export interface StripeSandboxClient {
+    createPaymentIntent(input: {
+        amount: number;
+        currency: string;
+        customer?: string;
+        paymentMethod?: string;
+        offSession?: boolean;
+        setupFutureUsage?: "off_session";
+        metadata: Record<string, string>;
+    }, options: {
+        idempotencyKey: string;
+    }): Promise<StripeIntentLike>;
+    createSetupIntent(input: {
+        customer?: string;
+        paymentMethod?: string;
+        usage: "off_session";
+        metadata: Record<string, string>;
+    }, options: {
+        idempotencyKey: string;
+    }): Promise<StripeIntentLike>;
+    /**
+     * Ensure-or-create a provider Customer for the client. Required before a
+     * `setup_future_usage='off_session'` PaymentIntent (the provider rejects it
+     * without a customer). Idempotent via the idempotency key.
+     */
+    ensureCustomer?(input: {
+        clientId: string;
+        metadata: Record<string, string>;
+    }, options: {
+        idempotencyKey: string;
+    }): Promise<string>;
+    retrievePaymentIntent?(paymentIntentId: string): Promise<StripeIntentLike>;
+}
+export interface StripeSandboxAdapterOptions {
+    client: StripeSandboxClient;
+    defaultFlow?: Extract<PaymentProviderFlow, "one_time_payment" | "setup_reusable_method" | "off_session_payment">;
+}
+export declare function createStripeSandboxPaymentExecutionAdapter({ client, defaultFlow, }: StripeSandboxAdapterOptions): PaymentExecutionPort;
+export declare function parseStripePaymentWebhookEvent(rawPayload: Record<string, unknown>): CanonicalPaymentEvent;