@openlup/platform 0.20.0 → 0.21.0

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

@@ -0,0 +1,53 @@
+import { type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+import type { PaymentExecutionResult } from "./donorContracts.js";
+/**
+ * Normalization of a refusal the provider throws instead of returning.
+ *
+ * Split from the execution adapter because it is a different job: the adapter
+ * creates intents and reports what came back, this reads an exception and
+ * decides whether it is evidence of a refusal at all — the decision that keeps a
+ * possibly-paid charge out of the terminal `failed` path.
+ */
+/**
+ * The provider's error type for an issuer refusal, spelled exactly as the SDK
+ * sets it. Exported so the decline branch and its proofs cannot drift apart.
+ */
+export declare const PROVIDER_DECLINE_ERROR_TYPE = "StripeCardError";
+/** What the adapter learned from a refusal: the fact itself plus its correlation handle. */
+export interface ExecutionDecline {
+    diagnosticFailureEvidence?: PaymentFailureEvidence;
+    decline: NonNullable<PaymentExecutionResult["providerDecline"]>;
+    /** The intent the provider had already created, when the refusal names one. */
+    providerAttemptId: string | null;
+    providerStatus: string | null;
+}
+/** The half of an execution result a refusal determines; the adapter owns the rest. */
+type DeclinedExecutionFacts = Omit<PaymentExecutionResult, "provider" | "requestPayload">;
+/**
+ * Reads an issuer refusal out of a thrown provider error, or returns null.
+ *
+ * Deliberately narrow: only the provider's own refusal type qualifies. Codes
+ * alone would not — an infrastructure error can also carry a `code`, and
+ * treating one as a decline would apply a terminal `failed` result to a charge
+ * that may have gone through.
+ */
+export declare function declineFromError(error: unknown): ExecutionDecline | null;
+/**
+ * Turns a refusal into attempt facts, DELIBERATELY without a correlation handle.
+ *
+ * `attemptStatus` stays non-terminal by contract — only the control plane makes
+ * terminal transitions, and it does so from `providerDecline`.
+ *
+ * The refused intent's id is reported ONLY inside `responsePayload`, never as
+ * `providerAttemptId`. That is not an oversight: event ingest matches a callback
+ * to an attempt by `provider_attempt_id`, and the control plane's failed branch
+ * has no guard against applying `failed` to an already-failed intent. So a
+ * correlation handle would let the provider's later failure callback re-apply the
+ * same refusal under its own idempotency key — advancing the retry ladder a
+ * second rung, rewriting the failure reason, and sending the customer a second
+ * dunning email minutes after the first. Until that branch is idempotent
+ * (planned PR-0c), a refusal this rail already reported must stay uncorrelated,
+ * and the callback must stay inert.
+ */
+export declare function declinedExecutionFacts(declined: ExecutionDecline): DeclinedExecutionFacts;
+export {};

package/dist/payments/stripe/executionDecline.js

@@ -0,0 +1,107 @@
+import { stripeFailureEvidence } from "./stripeFailureEvidence.js";
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+/**
+ * Normalization of a refusal the provider throws instead of returning.
+ *
+ * Split from the execution adapter because it is a different job: the adapter
+ * creates intents and reports what came back, this reads an exception and
+ * decides whether it is evidence of a refusal at all — the decision that keeps a
+ * possibly-paid charge out of the terminal `failed` path.
+ */
+/**
+ * The provider's error type for an issuer refusal, spelled exactly as the SDK
+ * sets it. Exported so the decline branch and its proofs cannot drift apart.
+ */
+export const PROVIDER_DECLINE_ERROR_TYPE = "StripeCardError";
+/** Used when the provider refuses without naming a code of its own. */
+const UNSPECIFIED_DECLINE_CODE = "provider_declined";
+/**
+ * Reads an issuer refusal out of a thrown provider error, or returns null.
+ *
+ * Deliberately narrow: only the provider's own refusal type qualifies. Codes
+ * alone would not — an infrastructure error can also carry a `code`, and
+ * treating one as a decline would apply a terminal `failed` result to a charge
+ * that may have gone through.
+ */
+export function declineFromError(error) {
+    if (!error || typeof error !== "object")
+        return null;
+    const raw = error;
+    if (raw.type !== PROVIDER_DECLINE_ERROR_TYPE)
+        return null;
+    const intent = raw.payment_intent && typeof raw.payment_intent === "object"
+        ? raw.payment_intent
+        : null;
+    const declineCode = readOptionalString(raw, "decline_code");
+    const adviceCode = readOptionalString(raw, "advice_code");
+    // Translated here, where the code vocabulary is owned, so the control plane
+    // classifies the refusal without ever seeing an acquirer code.
+    const neutralReasonHints = declineCodeHints(declineCode);
+    const evidence = stripeFailureEvidence(raw, { source: "execution" });
+    return {
+        ...(evidence ? { diagnosticFailureEvidence: evidence } : {}),
+        decline: {
+            code: readOptionalString(raw, "code") ?? UNSPECIFIED_DECLINE_CODE,
+            // Reserved for a payer bank that cannot hold a reusable mandate at all.
+            // A refused charge on an already-registered method proves the opposite,
+            // so this rail never claims it.
+            mandateUnsupported: false,
+            ...(declineCode ? { declineCode } : {}),
+            ...(adviceCode ? { adviceCode } : {}),
+            ...(neutralReasonHints.length > 0 ? { neutralReasonHints } : {}),
+        },
+        providerAttemptId: intent ? readOptionalString(intent, "id") ?? null : null,
+        providerStatus: intent ? readOptionalString(intent, "status") ?? null : null,
+    };
+}
+/**
+ * Turns a refusal into attempt facts, DELIBERATELY without a correlation handle.
+ *
+ * `attemptStatus` stays non-terminal by contract — only the control plane makes
+ * terminal transitions, and it does so from `providerDecline`.
+ *
+ * The refused intent's id is reported ONLY inside `responsePayload`, never as
+ * `providerAttemptId`. That is not an oversight: event ingest matches a callback
+ * to an attempt by `provider_attempt_id`, and the control plane's failed branch
+ * has no guard against applying `failed` to an already-failed intent. So a
+ * correlation handle would let the provider's later failure callback re-apply the
+ * same refusal under its own idempotency key — advancing the retry ladder a
+ * second rung, rewriting the failure reason, and sending the customer a second
+ * dunning email minutes after the first. Until that branch is idempotent
+ * (planned PR-0c), a refusal this rail already reported must stay uncorrelated,
+ * and the callback must stay inert.
+ */
+export function declinedExecutionFacts(declined) {
+    const { decline, providerAttemptId, providerStatus } = declined;
+    return {
+        providerAttemptId: null,
+        providerSessionId: null,
+        attemptStatus: "processing",
+        nextActionKind: null,
+        providerDecline: decline,
+        clientSecret: null,
+        customerProviderRef: null,
+        paymentMethodRef: null,
+        // This rail already reported the refusal synchronously; the callback that
+        // repeats it must not be waited for, and must not be able to land twice.
+        webhookExpected: false,
+        recoveryRequired: false,
+        responsePayload: {
+            // Forensics only. This payload is stored on the attempt but nothing joins
+            // on it, so an operator can still trace the refused intent by hand without
+            // the ingest matcher ever finding it.
+            providerStatus,
+            providerAttemptId,
+            providerDeclined: true,
+            ...failureEvidencePayload(declined.diagnosticFailureEvidence),
+            // Codes only, never the provider's message: that text is free-form and can
+            // carry payer-identifying detail, and this payload is persisted and logged.
+            providerErrorCodes: [decline.code, decline.declineCode, decline.adviceCode].filter((code) => Boolean(code)),
+        },
+    };
+}
+function readOptionalString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}

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

@@ -0,0 +1,16 @@
+import type { PaymentAdapter, PaymentAdapterCapabilities } from "../contracts/index.js";
+import { type StripeSandboxClient } from "./stripeSandboxPaymentExecutionAdapter.js";
+import { type StripePaymentIntentReader } from "./stripePaymentReconciliationProvider.js";
+/** Host-owned client, credentials, SDK construction and mode policy. clock returns UTC seconds. */
+export interface StripePaymentAdapterConfig {
+    client: Omit<StripeSandboxClient, "createSetupIntent"> & Partial<Pick<StripeSandboxClient, "createSetupIntent">> & StripePaymentIntentReader;
+    webhookSigningSecrets: readonly string[];
+    mode: "live" | "test";
+    supportedCurrencies: readonly string[];
+    toleranceSeconds?: number;
+    clock?: () => number;
+}
+/** Observed protocol capabilities; account activation remains host-owned. */
+export declare const stripePaymentCapabilities: Readonly<PaymentAdapterCapabilities>;
+/** Explicit construction is the only activation point; importing performs no I/O. */
+export declare function createStripePaymentAdapter(config: StripePaymentAdapterConfig): PaymentAdapter;

package/dist/payments/stripe/index.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { classifyPaymentFailure, isPaymentRetryAdviceCode } from "@openlup/core/payment";
+import { createStripeSandboxPaymentExecutionAdapter } from "./stripeSandboxPaymentExecutionAdapter.js";
+import { createStripePaymentReconciliationProvider } from "./stripePaymentReconciliationProvider.js";
+import { normalizeStripeWebhookEvent } from "./stripeWebhookNormalizer.js";
+import { verifyStripeSignature } from "./webhookSignature.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+/** Observed protocol capabilities; account activation remains host-owned. */
+export const stripePaymentCapabilities = Object.freeze({
+    providerKind: "stripe",
+    captureFlows: Object.freeze([Object.freeze({ kind: "card_payment", handoff: "client-confirmed", methodFamilies: Object.freeze(["card", "wallet"]) })]),
+    requiresStoredMandateEvidence: false,
+    assessMandate: () => ({ chargeable: true }),
+    unattendedChargeFlow: "off_session_payment",
+    payerContext: Object.freeze({ requiresPayerBlock: false, customerRefFallsBackToContactEmail: false }),
+    methodHealth: Object.freeze({ requiresCustomerRef: true, requiredMethodKind: null, requiresPayerContact: false }),
+    terminalOutcomeReporting: Object.freeze({ kind: "status_field", silenceBecomesSuspectAfterMinutes: 360 }),
+    mandateUpsertIsSubscriptionScoped: false,
+    /** declared by the host through the adapter config */
+    supportedCurrencies: Object.freeze([]),
+    unattended: "supported", readback: "supported", close: "unsupported", exactAbsence: "unsupported",
+    refundObservation: "supported", refundCreate: "unsupported", authorizationCaptureSplit: "unsupported",
+});
+const refusal = (reason) => ({ kind: "refusal", reason });
+/** Explicit construction is the only activation point; importing performs no I/O. */
+export function createStripePaymentAdapter(config) {
+    if (config.mode !== "live" && config.mode !== "test")
+        throw new Error("Invalid payment mode");
+    const declaredCurrencies = config.supportedCurrencies;
+    if (!Array.isArray(declaredCurrencies) || declaredCurrencies.length === 0
+        || ![...declaredCurrencies].every(currency => typeof currency === "string" && currency.length === 3 && /^[A-Z]{3}$/u.test(currency))) {
+        throw new Error("Invalid supported currencies");
+    }
+    const supportedCurrencies = Object.freeze([...declaredCurrencies]);
+    const tolerance = config.toleranceSeconds ?? 300;
+    if (!Number.isFinite(tolerance) || tolerance < 0)
+        throw new Error("Invalid signature tolerance");
+    const secrets = [...config.webhookSigningSecrets];
+    const now = config.clock ?? (() => Math.floor(Date.now() / 1000));
+    const execution = createStripeSandboxPaymentExecutionAdapter({ client: {
+            createPaymentIntent: config.client.createPaymentIntent.bind(config.client),
+            createSetupIntent: inputSetup,
+            ensureCustomer: config.client.ensureCustomer?.bind(config.client),
+        } });
+    function inputSetup(...args) {
+        if (!config.client.createSetupIntent)
+            throw new Error("Method setup unsupported by injected client");
+        return config.client.createSetupIntent(...args);
+    }
+    const reader = createStripePaymentReconciliationProvider(config.client);
+    const validateInput = input => {
+        if (input.mode !== config.mode || !["initial", "recovery", "renewal-unattended"].includes(input.purpose)
+            || !input.attemptRef || !input.intentRef || !input.fingerprint || !input.providerIdempotencyKey
+            || !Number.isSafeInteger(input.money.amountMinor) || input.money.amountMinor <= 0
+            || !supportedCurrencies.includes(input.money.currency)
+            || input.customerAuthorization !== undefined
+            || (input.purpose === "renewal-unattended" && !input.storedMethod?.reference)) {
+            throw new Error("Unsupported payment input");
+        }
+    };
+    const read = async (input) => {
+        const base = { identity: input.identity, expectedMoney: input.expectedMoney, purpose: input.purpose };
+        if (input.identity.provider !== "stripe" || !input.identity.providerPaymentRef)
+            return { ...base, kind: "unsupported" };
+        try {
+            // Bind the response to the requested remote object before translating status.
+            const intent = await config.client.retrievePaymentIntent(input.identity.providerPaymentRef);
+            if (intent.id !== input.identity.providerPaymentRef || intent.amount !== input.expectedMoney.amountMinor
+                || intent.currency?.toUpperCase() !== input.expectedMoney.currency.toUpperCase()) {
+                return { ...base, kind: "unknown", reason: "indeterminate" };
+            }
+            const status = await createStripePaymentReconciliationProvider({ retrievePaymentIntent: async () => intent })
+                .readPayment({ providerPaymentId: input.identity.providerPaymentRef, purpose: input.purpose });
+            return readback(base, status);
+        }
+        catch {
+            return { ...base, kind: "unknown", reason: "indeterminate" };
+        }
+    };
+    return {
+        capabilities: { ...stripePaymentCapabilities, supportedCurrencies, close: config.client.cancelPaymentIntent ? "supported" : "unsupported" },
+        attemptPort: {
+            validateInput,
+            async execute(input) {
+                validateInput(input);
+                const result = await execution.execute({
+                    idempotencyKey: input.attemptRef, providerIdempotencyKey: input.providerIdempotencyKey,
+                    providerRequestFingerprint: input.fingerprint, paymentIntentId: input.intentRef,
+                    amountMinor: input.money.amountMinor, currency: input.money.currency,
+                    mode: input.purpose === "renewal-unattended" ? "subscription_cycle" : "one_time",
+                    orderRef: input.intentRef,
+                    providerFlow: input.purpose === "renewal-unattended" ? "off_session_payment" : "one_time_payment",
+                    paymentMethodRef: input.storedMethod?.reference,
+                });
+                return {
+                    outcome: result.providerDecline
+                        ? { kind: "decline", refusal: neutralDecline(result.providerDecline) }
+                        : { kind: "attempt", status: result.attemptStatus },
+                    // A synchronous issuer decline is not proof of a pre-dispatch refusal.
+                    dispatch: result.providerAttemptId ? { kind: "dispatched", providerPaymentRef: result.providerAttemptId } : { kind: "unknown" },
+                    ...(result.clientSecret ? { handoff: { kind: "client-confirmed", payload: result.clientSecret } } : {}),
+                    diagnostics: { webhookExpected: result.webhookExpected === true, recoveryRequired: result.recoveryRequired === true },
+                };
+            },
+        },
+        verifyPort: {
+            async verifyAndNormalize(input) {
+                const header = Object.entries(input.headers).find(([key]) => key.toLowerCase() === "stripe-signature")?.[1];
+                if (typeof header !== "string")
+                    return refusal("signature");
+                const parts = Object.fromEntries(header.split(",").map(part => part.split("=")).filter(([key, value]) => key && value));
+                const timestamp = Number(parts.t);
+                const current = now();
+                if (!parts.t || !parts.v1 || !Number.isFinite(timestamp) || !Number.isFinite(current))
+                    return refusal("signature");
+                // The preserved verifier supplies HMAC and comparison; this layer owns configurable freshness.
+                if (Math.abs(current - timestamp) > tolerance)
+                    return refusal("stale");
+                const rawBody = Buffer.from(input.rawBody).toString("utf8");
+                if (!Buffer.from(rawBody).equals(Buffer.from(input.rawBody)))
+                    return refusal("malformed");
+                if (!verifyStripeSignature({ rawBody, signatureHeader: header, endpointSecret: secrets, now: () => timestamp }))
+                    return refusal("signature");
+                try {
+                    const raw = JSON.parse(rawBody);
+                    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                        return refusal("malformed");
+                    const event = raw;
+                    if (typeof event.livemode === "boolean" && event.livemode !== (config.mode === "live"))
+                        return refusal("unsupported-event");
+                    return mapVerifiedStripeEvent(event);
+                }
+                catch {
+                    return refusal("malformed");
+                }
+            },
+        },
+        readbackPort: {
+            readPayment: read,
+            ...(reader.closePayment ? { close: async (input) => {
+                    const base = { identity: input.identity, expectedMoney: input.expectedMoney, purpose: input.purpose };
+                    if (input.identity.provider !== "stripe" || !input.identity.providerPaymentRef)
+                        return { ...base, kind: "unsupported" };
+                    try {
+                        // Check configured money and object identity before a destructive provider operation.
+                        const before = await read(input);
+                        if (before.kind === "unknown" || before.kind === "unsupported")
+                            return before;
+                        await reader.closePayment({ providerPaymentId: input.identity.providerPaymentRef });
+                        return read(input);
+                    }
+                    catch {
+                        return { ...base, kind: "unknown", reason: "indeterminate" };
+                    }
+                } } : {}),
+        },
+    };
+}
+function neutralDecline(decline) {
+    const hints = decline.neutralReasonHints ?? [];
+    const classified = classifyPaymentFailure({ adviceCode: decline.adviceCode, neutralReasonHints: hints });
+    return { code: classified.failureClass, hints,
+        ...(decline.adviceCode && isPaymentRetryAdviceCode(decline.adviceCode) ? { adviceCode: decline.adviceCode } : {}) };
+}
+function readback(base, status) {
+    if (status.status === "unknown" || status.amountMinor === null || !Number.isSafeInteger(status.amountMinor) || !status.currency) {
+        return { ...base, kind: "unknown", reason: "indeterminate" };
+    }
+    return { ...base, kind: status.status, observedMoney: { amountMinor: status.amountMinor, currency: status.currency }, providerOccurredAt: status.occurredAt };
+}
+/** Preserve donor money classifications in the neutral evidence union. */
+function mapStripeOutcome(eventType) {
+    switch (eventType) {
+        case "payment.succeeded": return "succeeded";
+        case "payment.failed": return "failed";
+        case "payment.refunded": return "refunded";
+        case "payment.requires_action": return "pending";
+        case "payment.disputed": return "disputed";
+        default: return null;
+    }
+}
+function mapVerifiedStripeEvent(raw) {
+    let normalized;
+    try {
+        normalized = normalizeStripeWebhookEvent(raw);
+    }
+    catch (error) {
+        return refusal(error instanceof Error && error.message.startsWith("Unsupported Stripe webhook event:") ? "unsupported-event" : "malformed");
+    }
+    const object = raw.data.object;
+    const occurred = typeof raw.created === "number" && Number.isFinite(raw.created)
+        ? normalized.occurredAt : typeof raw.created === "string" && Number.isFinite(Date.parse(raw.created)) ? normalized.occurredAt : null;
+    const metadata = object.metadata && typeof object.metadata === "object" ? object.metadata : {};
+    const intentRef = typeof metadata.paymentIntentId === "string" ? metadata.paymentIntentId : null;
+    const identity = { provider: "stripe", providerEventId: normalized.providerEventId,
+        providerOccurredAt: occurred };
+    let result;
+    if (normalized.methodLifecycle || normalized.eventType.startsWith("setup.")) {
+        const lifecycle = normalized.methodLifecycle;
+        const method = lifecycle?.providerMethodRef ?? (typeof object.payment_method === "string" ? object.payment_method
+            : object.payment_method && typeof object.payment_method === "object" ? object.payment_method.id : null);
+        if (typeof method !== "string" || !method)
+            return refusal("unsupported-event");
+        const outcomes = {
+            method_registered: "registered", method_updated: "updated", method_revoked: "revoked", method_expired: "expired", method_suspended: "suspended",
+            "setup.succeeded": "registered", "setup.failed": "failed", "setup.requires_action": "requires-action",
+        };
+        const outcome = outcomes[lifecycle?.kind ?? normalized.eventType];
+        if (!outcome)
+            return refusal("unsupported-event");
+        result = { ...identity, kind: "method", outcome, methodRef: method,
+            setupRef: typeof raw.type === "string" && raw.type.startsWith("setup_intent.") ? normalized.providerPaymentId : null, intentRef,
+            // Missing provider time must not turn the donor's epoch fallback into a lifecycle fact.
+            ...(lifecycle && occurred !== null ? { methodLifecycle: lifecycle } : {}) };
+    }
+    else {
+        const outcome = mapStripeOutcome(normalized.eventType);
+        if (!outcome)
+            return refusal("unsupported-event");
+        const money = Number.isSafeInteger(normalized.amountMinor) && normalized.amountMinor > 0 && normalized.currency
+            ? { amountMinor: normalized.amountMinor, currency: normalized.currency } : null;
+        const snapshot = normalized.rawPayload.stripeRefundSnapshot;
+        if (outcome === "refunded" && (!snapshot || !money))
+            return refusal("malformed");
+        result = { ...identity, kind: "money", providerPaymentRef: normalized.providerPaymentId, intentRef, attemptRef: null, outcome, money,
+            ...(snapshot && money ? { refund: { kind: "cumulative-snapshot", operationId: snapshot.chargeId,
+                    originalPaymentMoney: money, refundedMoney: { amountMinor: snapshot.amountRefundedMinor, currency: money.currency } } } : {}),
+            ...(outcome === "failed" && object.last_payment_error && typeof object.last_payment_error === "object"
+                ? { refusal: neutralDecline({ code: "provider_declined", mandateUnsupported: false,
+                        neutralReasonHints: declineCodeHints(object.last_payment_error.decline_code),
+                        adviceCode: typeof object.last_payment_error.advice_code === "string"
+                            ? object.last_payment_error.advice_code : undefined }) } : {}),
+        };
+    }
+    // The donor normalizer constructs this filtered carrier, never the raw body.
+    // Keep its reader dialect and provenance outside normalized event identity.
+    return { ...result, fingerprint: createHash("sha256").update(JSON.stringify(result)).digest("hex"),
+        providerAuditPayload: normalized.rawPayload };
+}

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

@@ -0,0 +1,26 @@
+import { type StripeIntentLike } from "./stripeFailureEvidence.js";
+type Reference = string | {
+    id: string;
+} | null;
+interface StripeIntentShape {
+    id: string;
+    status: string;
+    customer?: Reference;
+    payment_method?: Reference;
+    latest_charge?: Reference;
+    client_secret?: string | null;
+    next_action?: {
+        type?: string | null;
+    } | null;
+    amount?: number;
+    amount_received?: number;
+    currency?: string;
+    last_payment_error?: {
+        code?: string | null;
+        message?: string | null;
+        type?: string | null;
+    } | null;
+}
+export declare function mapStripeIntent(intent: StripeIntentShape, knownCardOnlyRequest?: boolean, source?: "execution" | "readback"): StripeIntentLike;
+export declare function mapSetupIntent(intent: StripeIntentShape): StripeIntentLike;
+export {};

package/dist/payments/stripe/intentMapper.js

@@ -0,0 +1,51 @@
+import { stripeFailureEvidence } from "./stripeFailureEvidence.js";
+export function mapStripeIntent(intent, knownCardOnlyRequest = false, source = "readback") {
+    const customer = typeof intent.customer === "string" ? intent.customer : intent.customer?.id ?? null;
+    const paymentMethod = typeof intent.payment_method === "string"
+        ? intent.payment_method
+        : intent.payment_method?.id ?? null;
+    const latestCharge = typeof intent.latest_charge === "string"
+        ? intent.latest_charge
+        : intent.latest_charge?.id ?? null;
+    const mapped = {
+        id: intent.id,
+        status: intent.status,
+        client_secret: intent.client_secret,
+        customer,
+        payment_method: paymentMethod,
+        latest_charge: latestCharge,
+        next_action: intent.next_action ? { type: intent.next_action.type ?? null } : null,
+    };
+    if (typeof intent.amount === "number")
+        mapped.amount = intent.amount;
+    if (typeof intent.amount_received === "number")
+        mapped.amount_received = intent.amount_received;
+    if (typeof intent.currency === "string")
+        mapped.currency = intent.currency;
+    if (intent.last_payment_error) {
+        mapped.last_payment_error = {
+            code: intent.last_payment_error.code ?? null,
+            message: intent.last_payment_error.message ?? null,
+            type: intent.last_payment_error.type ?? null,
+        };
+    }
+    const evidence = stripeFailureEvidence(intent, { source, knownCardOnlyRequest });
+    if (evidence)
+        mapped.diagnosticFailureEvidence = evidence;
+    return mapped;
+}
+export function mapSetupIntent(intent) {
+    const customer = typeof intent.customer === "string" ? intent.customer : intent.customer?.id ?? null;
+    const paymentMethod = typeof intent.payment_method === "string"
+        ? intent.payment_method
+        : intent.payment_method?.id ?? null;
+    return {
+        id: intent.id,
+        status: intent.status,
+        client_secret: intent.client_secret,
+        customer,
+        payment_method: paymentMethod,
+        latest_charge: null,
+        next_action: intent.next_action ? { type: intent.next_action.type ?? null } : null,
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { PaymentMethodReplacementFacts } from "@openlup/core/payment";
+import type { NormalizedProviderPaymentWebhook } from "./donorContracts.js";
+import type { PaymentMethodLifecycleEvent } from "@openlup/core/payment";
+export interface ProviderWebhookWithMethodLifecycle extends NormalizedProviderPaymentWebhook {
+    methodLifecycle?: PaymentMethodLifecycleEvent | null;
+}
+export declare const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export declare const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export declare const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+export declare function methodFactSnapshotKeys(facts: PaymentMethodReplacementFacts | null | undefined): Record<string, unknown>;

package/dist/payments/stripe/methodFacts.js

@@ -0,0 +1,12 @@
+export const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+export function methodFactSnapshotKeys(facts) {
+    if (!facts)
+        return {};
+    return {
+        ...(facts.schemeLabel ? { [METHOD_SCHEME_SNAPSHOT_KEY]: facts.schemeLabel } : {}),
+        ...(facts.lastDigits ? { [METHOD_LAST_DIGITS_SNAPSHOT_KEY]: facts.lastDigits } : {}),
+        ...(facts.expiresAt ? { [METHOD_EXPIRES_AT_SNAPSHOT_KEY]: facts.expiresAt } : {}),
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { PaymentRecoveryMethod, PaymentRecoveryOperation } from "@openlup/core/payment";
+export type FailureObservationSource = "execution" | "webhook" | "readback";
+export type FailureObservationDisposition = "present" | "absent" | "unreadable" | "read_failed" | "read_timeout";
+/** Protected provider facts, not a customer message or a retry-policy input. */
+export interface PaymentFailureEvidence {
+    version: 1;
+    source: FailureObservationSource;
+    disposition: FailureObservationDisposition;
+    refusalVerified: boolean;
+    providerPaymentId: string | null;
+    providerChargeId: string | null;
+    code: string | null;
+    declineCode: string | null;
+    adviceCode: string | null;
+    adviceOrigin: "provider" | "inferred" | "unknown";
+    operation: PaymentRecoveryOperation | null;
+    method: PaymentRecoveryMethod | null;
+    methodSource: "provider" | "execution_contract" | "unknown";
+}
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export declare function evidenceToken(value: unknown): string | null;
+export declare function evidenceRecord(value: unknown): Record<string, unknown>;
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export declare function serializeFailureEvidence(input: PaymentFailureEvidence): PaymentFailureEvidence;
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export declare function failureEvidencePayload(evidence: PaymentFailureEvidence | null | undefined): Record<string, unknown>;

package/dist/payments/stripe/paymentFailureEvidence.js

@@ -0,0 +1,33 @@
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export function evidenceToken(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_:.-]{1,96}$/.test(value) ? value : null;
+}
+export function evidenceRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : {};
+}
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export function serializeFailureEvidence(input) {
+    const method = input.method;
+    const kind = evidenceToken(method?.kind);
+    const recoveryMethodKey = evidenceToken(method?.recoveryMethodKey);
+    return {
+        version: 1,
+        source: input.source,
+        disposition: input.disposition,
+        refusalVerified: input.refusalVerified,
+        providerPaymentId: evidenceToken(input.providerPaymentId),
+        providerChargeId: evidenceToken(input.providerChargeId),
+        code: evidenceToken(input.code),
+        declineCode: evidenceToken(input.declineCode),
+        adviceCode: evidenceToken(input.adviceCode),
+        adviceOrigin: input.adviceOrigin,
+        operation: input.operation,
+        method: kind && recoveryMethodKey && method ? { kind, recoveryMethodKey, interaction: method.interaction } : null,
+        methodSource: kind && recoveryMethodKey ? input.methodSource : "unknown",
+    };
+}
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export function failureEvidencePayload(evidence) {
+    return evidence ? { failureEvidence: serializeFailureEvidence(evidence) } : {};
+}

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

@@ -0,0 +1,41 @@
+import { type PaymentRecoveryEvidence } from "@openlup/core/payment";
+import { type FailureObservationSource, type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+export interface StripeIntentLike {
+    id: string;
+    status: string;
+    amount?: number | null;
+    amount_received?: number | null;
+    currency?: string | null;
+    client_secret?: string | null;
+    customer?: string | null;
+    payment_method?: string | null;
+    latest_charge?: string | null;
+    next_action?: {
+        type?: string | null;
+    } | null;
+    last_payment_error?: {
+        code?: string | null;
+        message?: string | null;
+        type?: string | null;
+        decline_code?: string | null;
+        advice_code?: string | null;
+    } | null;
+    /** Kept separate: populating legacy fine fields would change renewal classification. */
+    diagnosticFailureEvidence?: PaymentFailureEvidence;
+}
+/** Reads only one current PaymentIntent/error, never an arbitrary historical Charge. */
+export declare function stripeFailureEvidence(input: unknown, options: {
+    source: FailureObservationSource;
+    confirmedFailureEvent?: boolean;
+    knownCardOnlyRequest?: boolean;
+}): PaymentFailureEvidence | null;
+/** UI evidence only: does not call or alter the shared failure taxonomy. */
+export declare function normalizeStripeFailureEvidence(input: PaymentFailureEvidence): PaymentRecoveryEvidence;
+/** Preserve the existing webhook projection and append only failure diagnostics. */
+export declare function stripeWebhookPayload(input: {
+    eventId: string;
+    eventType: string;
+    providerPaymentId: string;
+    amountMinor: number | null;
+    currency: string | null;
+}, object: unknown): Record<string, unknown>;