@openlup/platform 0.20.0 → 0.22.0

package/dist/payments/postgresPaymentTruth.js

@@ -0,0 +1,126 @@
+import { paymentReconciliationFingerprint, paymentTruthFingerprint, } from "./paymentTruth.js";
+const INGEST = `SELECT public.payment_truth_ingest_event(
+  $1,$2,$3,$4::uuid,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14) AS response`;
+const RECONCILE = `SELECT public.payment_truth_record_reconciliation(
+  $1::uuid,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10,$11,$12) AS response`;
+const SWEEP = "SELECT public.payment_truth_sweep_open_events($1,$2) AS response";
+const READ = "SELECT public.payment_truth_readback($1::uuid,false) AS response";
+/** Direct-PG caller for the provider-neutral payment truth public forward. */
+export function createPostgresPaymentTruthPort(executor, options) {
+    const dunningTemplateSlug = required(options.dunningTemplateSlug, "payment_truth_dunning_template_required");
+    const recoveryUrlPath = required(options.recoveryUrlPath, "payment_truth_recovery_path_required");
+    const recoveryTemplateSlug = required(options.recoveryTemplateSlug, "payment_truth_recovery_template_required");
+    return {
+        async ingestEvent(input) {
+            const response = first(await executor.query(INGEST, [
+                input.sourceEventId,
+                paymentTruthFingerprint(input),
+                input.idempotencyKey,
+                input.settlementIntentId,
+                input.outcome,
+                input.amountMinor,
+                input.currency,
+                input.occurredAt,
+                input.failure?.classification ?? null,
+                input.failure?.reason ?? null,
+                JSON.stringify(input.evidence),
+                dunningTemplateSlug,
+                recoveryUrlPath,
+                recoveryTemplateSlug,
+            ]));
+            return readback(response?.response);
+        },
+        async recordReconciliation(input) {
+            const response = first(await executor.query(RECONCILE, [
+                input.eventId,
+                input.idempotencyKey,
+                paymentReconciliationFingerprint(input),
+                input.evidenceStatus,
+                input.outcome,
+                input.occurredAt,
+                input.failure?.classification ?? null,
+                input.failure?.reason ?? null,
+                JSON.stringify(input.evidence),
+                dunningTemplateSlug,
+                recoveryUrlPath,
+                recoveryTemplateSlug,
+            ]));
+            return readback(response?.response);
+        },
+        async sweepOpenEvents(input) {
+            const response = record(first(await executor.query(SWEEP, [input.now, input.limit]))?.response);
+            return {
+                claimed: integer(response.claimed),
+                settledIgnored: integer(response.settledIgnored),
+                eventIds: Array.isArray(response.eventIds)
+                    ? response.eventIds.filter((value) => typeof value === "string")
+                    : [],
+            };
+        },
+        async readEvent(eventId) {
+            const value = first(await executor.query(READ, [eventId]))?.response;
+            return value === null || value === undefined ? null : readback(value);
+        },
+    };
+}
+function readback(value) {
+    const root = record(value);
+    const event = record(root.event);
+    const effects = record(root.effects);
+    const financial = record(root.financial);
+    const outcome = event.outcome;
+    const state = event.state;
+    if (typeof event.id !== "string"
+        || typeof event.sourceEventId !== "string"
+        || typeof event.fingerprint !== "string"
+        || (state !== "open" && state !== "settled")
+        || (outcome !== "captured" && outcome !== "refused" && outcome !== "indeterminate")
+        || typeof event.replayed !== "boolean"
+        || typeof effects.paymentResultRecorded !== "boolean"
+        || typeof effects.dunningOpened !== "boolean"
+        || typeof effects.accountingRequested !== "boolean"
+        || !Number.isSafeInteger(financial.amountMinor)
+        || typeof financial.currency !== "string")
+        throw new Error("payment_truth_readback_invalid");
+    return {
+        event: {
+            id: event.id,
+            sourceEventId: event.sourceEventId,
+            fingerprint: event.fingerprint,
+            state,
+            outcome,
+            replayed: event.replayed,
+        },
+        effects: {
+            paymentResultRecorded: effects.paymentResultRecorded,
+            dunningOpened: effects.dunningOpened,
+            accountingRequested: effects.accountingRequested,
+        },
+        financial: {
+            settlementStatus: nullableString(financial.settlementStatus),
+            orderStatus: nullableString(financial.orderStatus),
+            subscriptionStatus: nullableString(financial.subscriptionStatus),
+            accountingStatus: nullableString(financial.accountingStatus),
+            amountMinor: financial.amountMinor,
+            currency: financial.currency,
+        },
+    };
+}
+function first(result) {
+    return result.rows[0] ?? null;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function integer(value) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+function nullableString(value) {
+    return typeof value === "string" ? value : null;
+}
+function required(value, error) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(error);
+    return trimmed;
+}

package/dist/payments/preparedAttempt.d.ts

@@ -0,0 +1,6 @@
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { PreparedAttemptExecutionInput, PreparedAttemptExecutionResult, PreparedAttemptFailurePolicy } from "./contracts/preparedAttempt.js";
+/** Interactive ordering only; the caller binds nominal trust and native errors. */
+export declare function executePreparedAttemptMechanism<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult & {
+    nextActionKind: N | null;
+}, P extends string, N extends string, E extends Error>(input: PreparedAttemptExecutionInput<I, R, P, N>, policy: PreparedAttemptFailurePolicy<E, N>): Promise<PreparedAttemptExecutionResult<R>>;

package/dist/payments/preparedAttempt.js

@@ -0,0 +1,70 @@
+import { finalizePreparedProviderAttempt } from "./preparedAttemptFinalization.js";
+/** Interactive ordering only; the caller binds nominal trust and native errors. */
+export async function executePreparedAttemptMechanism(input, policy) {
+    // Reject deterministic local input/config errors before persisting a durable
+    // attempt. Only an actual PSP dispatch may create an indeterminate attempt.
+    input.executionPort.validateInput?.(input.executionInput);
+    const preparedAttempt = await input.paymentPort.prepareProviderAttempt({
+        idempotencyKey: input.prepareIdempotencyKey,
+        paymentIntentId: input.paymentIntentId,
+        provider: input.provider,
+        providerIdempotencyKey: input.providerIdempotencyKey,
+        providerRequestFingerprint: input.providerRequestFingerprint,
+        providerFlow: input.providerFlow,
+        paymentMethodRef: input.paymentMethodRef ?? null,
+        requestPayload: input.prepareRequestPayload,
+    });
+    if (preparedAttempt.replayed) {
+        throw policy.replayError(preparedAttempt);
+    }
+    let execution;
+    try {
+        execution = await input.executionPort.execute(input.executionInput);
+        input.validateExecution?.(execution);
+    }
+    catch (error) {
+        if (policy.isTrustedNoCharge(error)) {
+            policy.logRetry(error, preparedAttempt);
+            try {
+                execution = await input.executionPort.execute(input.executionInput);
+                input.validateExecution?.(execution);
+            }
+            catch (retryError) {
+                if (policy.isTrustedNoCharge(retryError)) {
+                    throw policy.exhaustedError(retryError, error, preparedAttempt);
+                }
+                throw policy.executionError(retryError, preparedAttempt);
+            }
+        }
+        else {
+            throw policy.executionError(error, preparedAttempt);
+        }
+    }
+    let finalizedAttempt;
+    try {
+        const finalizeInput = {
+            idempotencyKey: input.finalizeIdempotencyKey,
+            paymentIntentId: input.paymentIntentId,
+            paymentAttemptId: preparedAttempt.paymentAttemptId,
+            providerIdempotencyKey: input.providerIdempotencyKey,
+            providerRequestFingerprint: input.providerRequestFingerprint,
+            providerAttemptId: execution.providerAttemptId,
+            providerSessionId: execution.providerSessionId,
+            attemptStatus: execution.attemptStatus,
+            nextActionKind: execution.nextActionKind,
+            requestPayload: execution.requestPayload,
+            responsePayload: execution.responsePayload,
+        };
+        finalizedAttempt = await finalizePreparedProviderAttempt(() => input.paymentPort.finalizeProviderAttempt(finalizeInput));
+    }
+    catch (error) {
+        throw policy.finalizationError(error, preparedAttempt);
+    }
+    return {
+        execution,
+        attempt: {
+            paymentAttemptId: finalizedAttempt.paymentAttemptId,
+            status: finalizedAttempt.status,
+        },
+    };
+}

package/dist/payments/preparedAttemptFinalization.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Replays one local idempotent finalize after its response is lost. The caller
+ * closes over one immutable payload, so this cannot issue another PSP request.
+ */
+export declare function finalizePreparedProviderAttempt<T>(finalize: () => Promise<T>): Promise<T>;

package/dist/payments/preparedAttemptFinalization.js

@@ -0,0 +1,12 @@
+/**
+ * Replays one local idempotent finalize after its response is lost. The caller
+ * closes over one immutable payload, so this cannot issue another PSP request.
+ */
+export async function finalizePreparedProviderAttempt(finalize) {
+    try {
+        return await finalize();
+    }
+    catch {
+        return finalize();
+    }
+}

package/dist/payments/schemaCapabilities.d.ts

@@ -0,0 +1,10 @@
+/** Direct truth graph only; unsupported operations require a separate store. */
+export declare const paymentSchemaDescriptor: {
+    readonly truth: "supported";
+    readonly settlement: "supported";
+    readonly laterOnlyCycle: "supported";
+    readonly preparedDurableStore: "unsupported";
+    readonly methodSetup: "unsupported";
+    readonly absenceReopen: "unsupported";
+    readonly cumulativeRefund: "unsupported";
+};

package/dist/payments/schemaCapabilities.js

@@ -0,0 +1,10 @@
+/** Direct truth graph only; unsupported operations require a separate store. */
+export const paymentSchemaDescriptor = {
+    truth: "supported",
+    settlement: "supported",
+    laterOnlyCycle: "supported",
+    preparedDurableStore: "unsupported",
+    methodSetup: "unsupported",
+    absenceReopen: "unsupported",
+    cumulativeRefund: "unsupported",
+};

package/dist/payments/sql.d.ts

@@ -0,0 +1,20 @@
+/** Sparse projections of canonical units, never an install chain. */
+export declare const PAYMENT_MIGRATIONS: readonly [{
+    readonly id: "20260810180000_payment_settlement_rail";
+    readonly catalogPath: "db/platform/migrations/20260810180000_payment_settlement_rail.sql";
+    readonly position: 10;
+    readonly sha256: "af153aadedc09c07b25f69300d335d8928526cad126646c1b9bf25341f1c2d0e";
+    readonly url: URL;
+}, {
+    readonly id: "20260815150000_payment_truth_reconciliation";
+    readonly catalogPath: "db/platform/migrations/20260815150000_payment_truth_reconciliation.sql";
+    readonly position: 35;
+    readonly sha256: "dd38a601edc2f43f259eefc2cdb9af14fd37fe792a7f82e58c351bd373a88905";
+    readonly url: URL;
+}, {
+    readonly id: "20260826100000_late_payment_shifts_the_subscription_cycle";
+    readonly catalogPath: "db/platform/migrations/20260826100000_late_payment_shifts_the_subscription_cycle.sql";
+    readonly position: 56;
+    readonly sha256: "992540b0f49713d604859926624b3bef09d5075b68b604f069dcbd688328e452";
+    readonly url: URL;
+}];

package/dist/payments/sql.js

@@ -0,0 +1,6 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const PAYMENT_MIGRATIONS = [
+    { id: "20260810180000_payment_settlement_rail", catalogPath: "db/platform/migrations/20260810180000_payment_settlement_rail.sql", position: 10, sha256: "af153aadedc09c07b25f69300d335d8928526cad126646c1b9bf25341f1c2d0e", url: new URL("../../sql/20260810180000_payment_settlement_rail.sql", import.meta.url) },
+    { id: "20260815150000_payment_truth_reconciliation", catalogPath: "db/platform/migrations/20260815150000_payment_truth_reconciliation.sql", position: 35, sha256: "dd38a601edc2f43f259eefc2cdb9af14fd37fe792a7f82e58c351bd373a88905", url: new URL("../../sql/20260815150000_payment_truth_reconciliation.sql", import.meta.url) },
+    { id: "20260826100000_late_payment_shifts_the_subscription_cycle", catalogPath: "db/platform/migrations/20260826100000_late_payment_shifts_the_subscription_cycle.sql", position: 56, sha256: "992540b0f49713d604859926624b3bef09d5075b68b604f069dcbd688328e452", url: new URL("../../sql/20260826100000_late_payment_shifts_the_subscription_cycle.sql", import.meta.url) },
+];

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

@@ -0,0 +1,46 @@
+import { type PaymentExecutionProviderDecline, type PaymentFailureClassification } from "@openlup/core/payment";
+export declare const DECLINE_FAILURE_REASONS: {
+    /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+    readonly mandateUnsupported: "blik_recurring_unsupported_bank";
+    /** Declined for a reason the provider did not distinguish. */
+    readonly generic: "provider_declined";
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export declare function declineFailureReason(decline: PaymentExecutionProviderDecline): string;
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export declare function classifyDecline(decline: PaymentExecutionProviderDecline, options?: {
+    failureReasonKey?: string;
+}): PaymentFailureClassification;

package/dist/payments/stripe/classifyDecline.js

@@ -0,0 +1,58 @@
+import { classifyPaymentFailure } from "@openlup/core/payment";
+export const DECLINE_FAILURE_REASONS = {
+    /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+    mandateUnsupported: "blik_recurring_unsupported_bank",
+    /** Declined for a reason the provider did not distinguish. */
+    generic: "provider_declined",
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export function declineFailureReason(decline) {
+    return decline.mandateUnsupported
+        ? DECLINE_FAILURE_REASONS.mandateUnsupported
+        : DECLINE_FAILURE_REASONS.generic;
+}
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export function classifyDecline(decline, options = {}) {
+    const asserted = [...(decline.neutralReasonHints ?? [])];
+    if (decline.mandateUnsupported)
+        asserted.push("mandateUnsupported");
+    return classifyPaymentFailure({
+        adviceCode: decline.adviceCode,
+        declineCode: decline.declineCode,
+        neutralReasonHints: asserted,
+        failureReasonKey: options.failureReasonKey ?? declineFailureReason(decline),
+    });
+}

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

@@ -0,0 +1,46 @@
+import type { PaymentFailureHint } from "@openlup/core/payment";
+/**
+ * This adapter's own translation from its opaque refusal codes to the neutral
+ * hints the failure taxonomy accepts.
+ *
+ * The table lives here, in the adapter that owns the codes, and never in the
+ * neutral kernel: the kernel classifies evidence, and this file is what turns
+ * one acquirer's vocabulary into that evidence.
+ *
+ * It follows the published scheme research collected for the dunning programme.
+ * The class these hints produce is DISPLAY-load-bearing: it reaches the payer as
+ * the sentence explaining why the charge could not happen. It is still not a
+ * cadence input (nothing in the retry ladder branches on it), so a wrong row
+ * here costs a wrong sentence, not a wrong charge.
+ *
+ * Precedence note: this table is consulted only when the refusal carries NO
+ * issuer advice code. Advice is the verdict of the party that would refuse the
+ * next attempt, so it outranks anything read locally.
+ *
+ * Two deliberate silences, both from the research:
+ *   - `do_not_honor` and `generic_decline` get NO entry. They are the issuer's
+ *     way of declining without saying why, and they arrive on refusals that are
+ *     dead and on refusals that clear on the next attempt alike. Guessing either
+ *     way would invent a verdict; falling through to `indeterminate` is honest.
+ *   - `restricted_card` IS mapped, to `credentialDead`, and the caveat is
+ *     recorded rather than hidden: the research reads it as "this instrument may
+ *     not be used for this transaction", which the payer's bank can lift, so the
+ *     instrument is not necessarily finished. It is mapped anyway because every
+ *     reading of it agrees that repeating the identical charge unattended cannot
+ *     clear it, and that is the whole content of the class.
+ *
+ * The same caveat applies to `card_not_supported`, `currency_not_supported` and
+ * `transaction_not_allowed`: the credential may be perfectly alive and the
+ * refusal still final for the charge as submitted. `credentialDead` is chosen
+ * for the CLASS it yields, not as a claim about the plastic.
+ */
+export declare const DECLINE_CODE_HINT_TABLE: Readonly<Record<string, readonly PaymentFailureHint[]>>;
+/**
+ * The hints this adapter asserts for one refusal code. Own-property lookup, so
+ * an inherited key (`constructor`, `toString`) is not a mapping.
+ *
+ * The table itself is exported too, for a reader that holds a stored code and
+ * has no adapter in the loop: the historical-corpus replay hands it straight to
+ * the kernel's `declineCodeHints` option.
+ */
+export declare function declineCodeHints(declineCode: string | undefined): readonly PaymentFailureHint[];

package/dist/payments/stripe/declineFailureHints.js

@@ -0,0 +1,87 @@
+/**
+ * This adapter's own translation from its opaque refusal codes to the neutral
+ * hints the failure taxonomy accepts.
+ *
+ * The table lives here, in the adapter that owns the codes, and never in the
+ * neutral kernel: the kernel classifies evidence, and this file is what turns
+ * one acquirer's vocabulary into that evidence.
+ *
+ * It follows the published scheme research collected for the dunning programme.
+ * The class these hints produce is DISPLAY-load-bearing: it reaches the payer as
+ * the sentence explaining why the charge could not happen. It is still not a
+ * cadence input (nothing in the retry ladder branches on it), so a wrong row
+ * here costs a wrong sentence, not a wrong charge.
+ *
+ * Precedence note: this table is consulted only when the refusal carries NO
+ * issuer advice code. Advice is the verdict of the party that would refuse the
+ * next attempt, so it outranks anything read locally.
+ *
+ * Two deliberate silences, both from the research:
+ *   - `do_not_honor` and `generic_decline` get NO entry. They are the issuer's
+ *     way of declining without saying why, and they arrive on refusals that are
+ *     dead and on refusals that clear on the next attempt alike. Guessing either
+ *     way would invent a verdict; falling through to `indeterminate` is honest.
+ *   - `restricted_card` IS mapped, to `credentialDead`, and the caveat is
+ *     recorded rather than hidden: the research reads it as "this instrument may
+ *     not be used for this transaction", which the payer's bank can lift, so the
+ *     instrument is not necessarily finished. It is mapped anyway because every
+ *     reading of it agrees that repeating the identical charge unattended cannot
+ *     clear it, and that is the whole content of the class.
+ *
+ * The same caveat applies to `card_not_supported`, `currency_not_supported` and
+ * `transaction_not_allowed`: the credential may be perfectly alive and the
+ * refusal still final for the charge as submitted. `credentialDead` is chosen
+ * for the CLASS it yields, not as a claim about the plastic.
+ */
+export const DECLINE_CODE_HINT_TABLE = Object.freeze({
+    approve_with_id: Object.freeze(["transient"]),
+    authentication_required: Object.freeze(["authenticationRequired"]),
+    card_not_supported: Object.freeze(["credentialDead"]),
+    card_velocity_exceeded: Object.freeze(["limitExceeded"]),
+    currency_not_supported: Object.freeze(["credentialDead"]),
+    expired_card: Object.freeze(["credentialDead"]),
+    fraudulent: Object.freeze(["credentialDead"]),
+    highest_risk_level: Object.freeze(["credentialDead"]),
+    incorrect_address: Object.freeze(["dataInvalid"]),
+    incorrect_cvc: Object.freeze(["dataInvalid"]),
+    incorrect_number: Object.freeze(["dataInvalid"]),
+    incorrect_zip: Object.freeze(["dataInvalid"]),
+    insufficient_funds: Object.freeze(["transient"]),
+    invalid_account: Object.freeze(["credentialDead"]),
+    invalid_amount: Object.freeze(["dataInvalid"]),
+    invalid_cvc: Object.freeze(["dataInvalid"]),
+    invalid_expiry_month: Object.freeze(["dataInvalid"]),
+    invalid_expiry_year: Object.freeze(["dataInvalid"]),
+    invalid_number: Object.freeze(["dataInvalid"]),
+    issuer_not_available: Object.freeze(["transient"]),
+    lost_card: Object.freeze(["credentialDead"]),
+    merchant_blacklist: Object.freeze(["credentialDead"]),
+    new_account_information_available: Object.freeze(["credentialDead"]),
+    pickup_card: Object.freeze(["credentialDead"]),
+    pin_try_exceeded: Object.freeze(["credentialDead"]),
+    processing_error: Object.freeze(["transient"]),
+    reenter_transaction: Object.freeze(["transient"]),
+    restricted_card: Object.freeze(["credentialDead"]),
+    revocation_of_all_authorizations: Object.freeze(["credentialDead"]),
+    revocation_of_authorization: Object.freeze(["credentialDead"]),
+    stolen_card: Object.freeze(["credentialDead"]),
+    stop_payment_order: Object.freeze(["credentialDead"]),
+    transaction_not_allowed: Object.freeze(["credentialDead"]),
+    try_again_later: Object.freeze(["transient"]),
+    withdrawal_count_limit_exceeded: Object.freeze(["limitExceeded"]),
+});
+/**
+ * The hints this adapter asserts for one refusal code. Own-property lookup, so
+ * an inherited key (`constructor`, `toString`) is not a mapping.
+ *
+ * The table itself is exported too, for a reader that holds a stored code and
+ * has no adapter in the loop: the historical-corpus replay hands it straight to
+ * the kernel's `declineCodeHints` option.
+ */
+export function declineCodeHints(declineCode) {
+    if (declineCode === undefined)
+        return [];
+    return Object.prototype.hasOwnProperty.call(DECLINE_CODE_HINT_TABLE, declineCode)
+        ? DECLINE_CODE_HINT_TABLE[declineCode]
+        : [];
+}

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

@@ -0,0 +1,120 @@
+/** Private structural contracts for the unchanged execution and observation slices. */
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { ProviderReadPurpose } from "../contracts/index.js";
+export type PaymentProviderFlow = "one_time_payment" | "setup_reusable_method" | "off_session_payment";
+export declare const PAYMENT_NEXT_ACTION_KINDS: readonly ["redirect", "3ds_challenge", "sca_required"];
+export type PaymentNextActionKind = (typeof PAYMENT_NEXT_ACTION_KINDS)[number];
+export interface PaymentExecutionInput extends PaymentExecutionBaseInput {
+    orderRef: string;
+    providerFlow?: PaymentProviderFlow;
+    customerRef?: string;
+    paymentMethodRef?: string;
+    saveForFutureUse?: boolean;
+    clientId?: string;
+}
+export interface PaymentExecutionResult extends PaymentExecutionBaseResult {
+    nextActionKind: PaymentNextActionKind | null;
+    clientSecret?: string | null;
+    customerProviderRef?: string | null;
+    paymentMethodRef?: string | null;
+    webhookExpected?: boolean;
+    recoveryRequired?: boolean;
+}
+export interface PaymentExecutionPort {
+    execute(input: PaymentExecutionInput): Promise<PaymentExecutionResult>;
+}
+export type PaymentWebhookEventType = "payment.succeeded" | "payment.failed" | "payment.refunded" | "payment.requires_action" | "payment.disputed" | "setup.succeeded" | "setup.failed" | "setup.requires_action";
+export interface CanonicalPaymentEvent {
+    provider_event_id: string;
+    event_type: PaymentWebhookEventType;
+    payment_provider_id: string;
+    amount_minor?: number;
+    next_action_kind?: PaymentNextActionKind;
+    raw_payload: Record<string, unknown>;
+}
+export interface NormalizedProviderPaymentWebhook {
+    provider: string;
+    providerEventId: string;
+    eventType: PaymentWebhookEventType;
+    providerPaymentId: string;
+    paymentIntentId?: string | null;
+    paymentAttemptId?: string | null;
+    amountMinor?: number | null;
+    currency?: string | null;
+    occurredAt: string;
+    refundKind?: "full" | "partial" | null;
+    rawPayload: Record<string, unknown>;
+    reusableMethod?: {
+        clientId: string;
+        subscriptionId?: string | null;
+        providerCustomerRef?: string | null;
+        providerMethodRef: string;
+        providerMandateRef?: string | null;
+        methodKind: "card";
+        status: "active";
+        consentSnapshot?: Record<string, unknown>;
+    } | null;
+}
+export interface ProviderReconciliationStatus {
+    status: "succeeded" | "failed" | "pending" | "unknown";
+    providerStatus: string;
+    occurredAt: string | null;
+    failureReason: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    rawPayload: Record<string, unknown>;
+}
+export interface ClaimedPaymentAttempt {
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentId: string;
+    orderId: string;
+    subscriptionId: string | null;
+    subscriptionCycleId: string | null;
+    provider: string;
+    providerPaymentId: string | null;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    attemptStatus: string;
+    intentStatus: string;
+    amountMinor: number;
+    currency: string;
+    orderMode: "one_time" | "subscription_cycle";
+    cycleRetryAttempt: number;
+    cycleNextRetryAt: string | null;
+    localUpdatedAt: string;
+}
+export type ProviderRecoveryAction = {
+    kind: "provider_embedded";
+    provider: string;
+    clientSecret: string;
+};
+export interface PaymentProviderRecoveryProvider {
+    resolvePaymentReference(input: {
+        providerAttemptId: string | null;
+        intentProviderPaymentId: string | null;
+        providerSessionId: string | null;
+    }): string | null;
+    readPayment(input: {
+        providerPaymentId: string;
+        attempt?: ClaimedPaymentAttempt;
+        purpose?: ProviderReadPurpose;
+    }): Promise<ProviderReconciliationStatus>;
+    readRecoveryPayment(input: {
+        providerPaymentId: string;
+        attempt: ClaimedPaymentAttempt;
+        purpose?: ProviderReadPurpose;
+    }): Promise<{
+        status: ProviderReconciliationStatus;
+        identityMatches: boolean;
+        configuredMoneyMatches: boolean;
+        manualReviewRequired: boolean;
+        clientAction: ProviderRecoveryAction | null;
+    }>;
+    closePayment?(input: {
+        providerPaymentId: string;
+    }): Promise<ProviderReconciliationStatus>;
+    findPaymentByLocalIntent?(input: {
+        attempt: ClaimedPaymentAttempt;
+    }): Promise<"found" | "absent">;
+}

package/dist/payments/stripe/donorContracts.js

@@ -0,0 +1 @@
+export const PAYMENT_NEXT_ACTION_KINDS = ["redirect", "3ds_challenge", "sca_required"];