@openlup/platform 0.19.0 → 0.21.0

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;

package/dist/payments/stripe/stripeSandboxPaymentExecutionAdapter.js

@@ -0,0 +1,220 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { declineFromError, declinedExecutionFacts } from "./executionDecline.js";
+import { noIssuerWasAsked } from "./stripeIntentConfirmationEvidence.js";
+/** The one place this adapter spells its own provider identity. */
+export const PROVIDER_KIND = "stripe";
+export function createStripeSandboxPaymentExecutionAdapter({ client, defaultFlow = "one_time_payment", }) {
+    return {
+        async execute(input) {
+            const flow = stripeFlow(input.providerFlow ?? defaultFlow);
+            // A reusable-mandate PaymentIntent (setup_future_usage) requires a Stripe
+            // Customer. Ensure-or-create one for the client when none was passed.
+            let customerRef = input.customerRef;
+            if (!customerRef && input.saveForFutureUse && input.clientId && client.ensureCustomer) {
+                customerRef = await client.ensureCustomer({ clientId: input.clientId, metadata: { clientId: input.clientId } }, 
+                // A provider attempt is per click; a Stripe Customer is per OpenLup
+                // client. A stable key avoids orphan Customers when checkout recovery
+                // is reloaded before the first method webhook stores the reference.
+                { idempotencyKey: `openlup:stripe:customer:${input.clientId}` });
+            }
+            const created = flow === "setup_reusable_method"
+                ? await client.createSetupIntent({
+                    customer: customerRef,
+                    paymentMethod: input.paymentMethodRef,
+                    usage: "off_session",
+                    metadata: metadataFor(input, flow),
+                }, { idempotencyKey: input.providerIdempotencyKey })
+                : await client.createPaymentIntent({
+                    amount: input.amountMinor,
+                    currency: input.currency.toLowerCase(),
+                    customer: customerRef,
+                    paymentMethod: input.paymentMethodRef,
+                    offSession: flow === "off_session_payment" ? true : undefined,
+                    setupFutureUsage: input.saveForFutureUse ? "off_session" : undefined,
+                    metadata: metadataFor(input, flow),
+                }, { idempotencyKey: input.providerIdempotencyKey }).catch((error) => {
+                    // An off-session charge is confirmed inside this call, so the payer's
+                    // issuer can refuse it here and nowhere else. That refusal is a FACT,
+                    // not an ambiguous call: rethrowing it makes the renewal orchestrator
+                    // record an indeterminate outcome, which applies no result, opens no
+                    // dunning case and tells the customer nothing. Every other error class
+                    // — network, auth, config, rate limit — keeps throwing, because after
+                    // those the charge may still have been accepted and only the
+                    // fail-closed path is safe.
+                    const decline = flow === "off_session_payment" ? declineFromError(error) : null;
+                    if (!decline)
+                        throw error;
+                    return decline;
+                });
+            if ("decline" in created)
+                return { ...executionResultBase(input, flow), ...declinedExecutionFacts(created) };
+            const intent = created;
+            return {
+                ...executionResultBase(input, flow),
+                providerAttemptId: intent.id,
+                providerSessionId: intent.id,
+                attemptStatus: attemptStatusFromStripe(intent),
+                nextActionKind: nextActionKindFromStripe(intent),
+                // `clientSecret` is the single canonical exit for the FE to confirm with
+                // the provider's browser SDK. It MUST NOT be persisted or duplicated
+                // into `responsePayload` (the latter is logged); the consumer reads it
+                // once from the top-level result and discards.
+                clientSecret: intent.client_secret ?? null,
+                customerProviderRef: intent.customer ?? null,
+                paymentMethodRef: intent.payment_method ?? null,
+                webhookExpected: true,
+                recoveryRequired: intent.status === "requires_action" && flow === "off_session_payment",
+                responsePayload: {
+                    providerStatus: intent.status,
+                    providerAttemptId: intent.id,
+                    providerSessionIdPresent: Boolean(intent.client_secret),
+                    latestChargePresent: Boolean(intent.latest_charge),
+                    customerRefPresent: Boolean(intent.customer),
+                    paymentMethodRefPresent: Boolean(intent.payment_method),
+                    ...failureEvidencePayload(intent.diagnosticFailureEvidence),
+                },
+            };
+        },
+    };
+}
+export function parseStripePaymentWebhookEvent(rawPayload) {
+    const eventId = readString(rawPayload, "id");
+    const eventType = readString(rawPayload, "type");
+    const data = readObject(rawPayload, "data");
+    const object = readObject(data, "object");
+    const providerPaymentId = readString(object, "id");
+    const amount = readOptionalNumber(object, "amount_received") ?? readOptionalNumber(object, "amount");
+    const currency = readOptionalString(object, "currency")?.toUpperCase();
+    return {
+        provider_event_id: eventId,
+        event_type: canonicalStripeEventType(eventType, object),
+        payment_provider_id: providerPaymentId,
+        amount_minor: amount,
+        next_action_kind: nextActionKindFromStripe({
+            status: readOptionalString(object, "status") ?? "",
+            next_action: readOptionalObject(object, "next_action"),
+        }) ?? undefined,
+        raw_payload: {
+            provider: PROVIDER_KIND,
+            eventId,
+            eventType,
+            providerPaymentId,
+            amountMinor: amount,
+            currency,
+        },
+    };
+}
+/** The facts every result of this adapter carries, whatever the provider answered. */
+function executionResultBase(input, flow) {
+    return {
+        provider: PROVIDER_KIND,
+        requestPayload: {
+            providerIdempotencyKey: input.providerIdempotencyKey,
+            providerRequestFingerprint: input.providerRequestFingerprint,
+            providerFlow: flow,
+            amountMinor: input.amountMinor,
+            currency: input.currency,
+            orderRef: input.orderRef,
+        },
+    };
+}
+function stripeFlow(flow) {
+    if (flow === "one_time_payment" || flow === "setup_reusable_method" || flow === "off_session_payment") {
+        return flow;
+    }
+    throw new Error(`Unsupported Stripe provider flow: ${flow}`);
+}
+function metadataFor(input, flow) {
+    const metadata = {
+        source: "openlup.payment-control",
+        paymentIntentId: input.paymentIntentId,
+        orderRef: input.orderRef,
+        providerRequestFingerprint: input.providerRequestFingerprint,
+        providerFlow: flow,
+    };
+    if (input.clientId)
+        metadata.clientId = input.clientId;
+    if (input.mode === "subscription_cycle")
+        metadata.mode = input.mode;
+    return metadata;
+}
+/**
+ * What the durable attempt row is allowed to claim about this execution.
+ *
+ * Takes the intent, not just its status, because the two states sharing
+ * `requires_payment_method` differ only in what else is on the object: a fresh
+ * intent the payer never confirmed, and one an issuer has just refused (which
+ * carries a payment error and usually a charge).
+ *
+ * `processing` claims money is moving, and a catch-all used to reach it — so a
+ * never-confirmed intent was recorded as a charge in flight, and a payer was
+ * told their payment was already processing when no issuer had been asked.
+ * `sent_to_provider` is the truth: the request reached the provider, no outcome
+ * is known. It belongs to every live-attempt set the platform keeps, so the
+ * correction costs no watchdog coverage, and it is fail-closed at the
+ * provider-attempt admission gate exactly as `processing` is — admission does
+ * not widen by one state.
+ *
+ * The catch-all stays `processing` on purpose: an unrecognised provider status is
+ * not evidence that nothing happened.
+ */
+function attemptStatusFromStripe(intent) {
+    if (intent.status === "requires_action" || intent.status === "requires_confirmation") {
+        return "requires_action";
+    }
+    if (noIssuerWasAsked(intent))
+        return "sent_to_provider";
+    return "processing";
+}
+function nextActionKindFromStripe(intent) {
+    if (intent.status !== "requires_action" && intent.status !== "requires_confirmation")
+        return null;
+    if (intent.next_action?.type === "redirect_to_url")
+        return "redirect";
+    if (intent.next_action?.type === "use_stripe_sdk")
+        return "3ds_challenge";
+    return "sca_required";
+}
+function canonicalStripeEventType(stripeEventType, object) {
+    if (stripeEventType === "payment_intent.succeeded")
+        return "payment.succeeded";
+    if (stripeEventType === "payment_intent.payment_failed" || stripeEventType === "payment_intent.canceled") {
+        return "payment.failed";
+    }
+    if (stripeEventType === "payment_intent.requires_action")
+        return "payment.requires_action";
+    if (stripeEventType === "charge.refunded")
+        return "payment.refunded";
+    if (stripeEventType.startsWith("charge.dispute."))
+        return "payment.disputed";
+    const status = readOptionalString(object, "status");
+    if (status === "requires_action")
+        return "payment.requires_action";
+    throw new Error(`Unsupported Stripe webhook event: ${stripeEventType}`);
+}
+function readObject(value, key) {
+    const raw = value[key];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Stripe payload missing object ${key}`);
+    }
+    return raw;
+}
+function readOptionalObject(value, key) {
+    const raw = value[key];
+    return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+}
+function readString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new Error(`Stripe payload missing string ${key}`);
+    }
+    return raw;
+}
+function readOptionalString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+function readOptionalNumber(value, key) {
+    const raw = value[key];
+    return typeof raw === "number" ? raw : undefined;
+}

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

@@ -0,0 +1,14 @@
+import { type ProviderWebhookWithMethodLifecycle } from "./methodFacts.js";
+/**
+ * Convert a verified raw Stripe webhook payload into the plural handler's
+ * `NormalizedProviderPaymentWebhook` shape.
+ *
+ * Reusable method extraction (Wave C): populated for `setup_intent.succeeded`
+ * always, and for `payment_intent.succeeded` when `setup_future_usage` was
+ * requested at PaymentIntent creation. Requires `metadata.clientId` to be set
+ * (the adapter does this when the runtime caller passes `clientId` through
+ * `PaymentExecutionInput`). When metadata is missing, `reusableMethod` stays
+ * null and the plural handler skips the method-ref upsert — safe degradation
+ * rather than crashing the webhook.
+ */
+export declare function normalizeStripeWebhookEvent(rawPayload: Record<string, unknown>): ProviderWebhookWithMethodLifecycle;