@openlup/platform 0.20.0 → 0.21.0

package/src/payments/stripe/stripePaymentReconciliationProvider.ts

@@ -0,0 +1,263 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import type {
+  ProviderReconciliationStatus,
+} from "./donorContracts.js";
+import type {
+  PaymentProviderRecoveryProvider,
+  ProviderRecoveryAction,
+} from "./donorContracts.js";
+import { classifyDecline } from "./classifyDecline.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+import { noIssuerWasAsked } from "./stripeIntentConfirmationEvidence.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 function createStripePaymentReconciliationProvider(
+  client: StripePaymentIntentReader & Partial<StripePaymentIntentSearcher>,
+): PaymentProviderRecoveryProvider {
+  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: ProviderRecoveryAction | null = 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): Promise<ProviderReconciliationStatus> {
+          return normalizeStripeIntent(await cancel(input.providerPaymentId));
+        },
+      }
+      : {}),
+    ...(search
+      ? {
+        async findPaymentByLocalIntent(input): Promise<"found" | "absent"> {
+          const result = await search({
+            key: "paymentIntentId",
+            value: input.attempt.paymentIntentId,
+            limit: 1,
+          });
+          return result.ids.length > 0 ? "found" : "absent";
+        },
+      }
+      : {}),
+  };
+}
+
+export function normalizeStripeIntent(intent: StripeIntentLike): ProviderReconciliationStatus {
+  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: StripeIntentLike): boolean {
+  return intent.status === "requires_payment_method"
+    && !intent.last_payment_error
+    && !intent.latest_charge;
+}
+
+function embeddedAction(clientSecret: unknown): ProviderRecoveryAction | null {
+  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: StripeIntentLike): Record<string, unknown> {
+  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: string | null | undefined): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function stripeConfiguredMoneyMatches(
+  intent: StripeIntentLike,
+  attempt: { amountMinor: number; currency: string },
+): boolean {
+  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: string): ProviderReconciliationStatus["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: StripeIntentLike): string | null {
+  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: StripeIntentLike): number | null {
+  // 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/src/payments/stripe/stripeRefundEvidence.ts

@@ -0,0 +1,19 @@
+/** A Charge observation is cumulative; its amount never replaces payment amount. */
+export function stripeRefundEvidence(eventType: string, charge: Record<string, unknown>): {
+  refundKind: "full" | "partial" | null;
+  snapshot: { chargeId: string; amountRefundedMinor: number } | null;
+} {
+  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/src/payments/stripe/stripeSandboxPaymentExecutionAdapter.ts

@@ -0,0 +1,283 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { declineFromError, declinedExecutionFacts } from "./executionDecline.js";
+import { noIssuerWasAsked } from "./stripeIntentConfirmationEvidence.js";
+import type { PaymentExecutionPort } from "./donorContracts.js";
+import type {
+  CanonicalPaymentEvent,
+  PaymentExecutionInput,
+  PaymentExecutionResult,
+  PaymentNextActionKind,
+  PaymentProviderFlow,
+} from "./donorContracts.js";
+
+/** The one place this adapter spells its own provider identity. */
+export const PROVIDER_KIND = "stripe" as const;
+
+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 function createStripeSandboxPaymentExecutionAdapter({
+  client,
+  defaultFlow = "one_time_payment",
+}: StripeSandboxAdapterOptions): PaymentExecutionPort {
+  return {
+    async execute(input: PaymentExecutionInput): Promise<PaymentExecutionResult> {
+      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: unknown) => {
+            // 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: Record<string, unknown>): CanonicalPaymentEvent {
+  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: PaymentExecutionInput,
+  flow: string,
+): Pick<PaymentExecutionResult, "provider" | "requestPayload"> {
+  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: PaymentProviderFlow): "one_time_payment" | "setup_reusable_method" | "off_session_payment" {
+  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: PaymentExecutionInput, flow: string): Record<string, string> {
+  const metadata: Record<string, string> = {
+    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: StripeIntentLike,
+): NonNullable<PaymentExecutionResult["attemptStatus"]> {
+  if (intent.status === "requires_action" || intent.status === "requires_confirmation") {
+    return "requires_action";
+  }
+  if (noIssuerWasAsked(intent)) return "sent_to_provider";
+  return "processing";
+}
+
+function nextActionKindFromStripe(intent: Pick<StripeIntentLike, "status" | "next_action">): PaymentNextActionKind | null {
+  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: string,
+  object: Record<string, unknown>,
+): CanonicalPaymentEvent["event_type"] {
+  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: Record<string, unknown>, key: string): Record<string, unknown> {
+  const raw = value[key];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Stripe payload missing object ${key}`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function readOptionalObject(value: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const raw = value[key];
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : null;
+}
+
+function readString(value: Record<string, unknown>, key: string): string {
+  const raw = value[key];
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`Stripe payload missing string ${key}`);
+  }
+  return raw;
+}
+
+function readOptionalString(value: Record<string, unknown>, key: string): string | undefined {
+  const raw = value[key];
+  return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+
+function readOptionalNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const raw = value[key];
+  return typeof raw === "number" ? raw : undefined;
+}