@openlup/core 0.0.0 → 0.7.0

package/dist/payment/paymentFailureTaxonomyContracts.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The vocabulary a refused payment is classified into, and the retry decision
+ * each class implies.
+ *
+ * The classes answer one question — *may this instrument be charged again, and
+ * by whom* — and nothing else. They are deliberately not a copy of any acquirer's
+ * code list: an adapter translates its own codes into the neutral evidence in
+ * {@link PaymentFailureEvidence}, and only that evidence reaches this kernel.
+ *
+ * `indeterminate` means the CLASS is unknown, never that the OUTCOME is unknown.
+ * A refusal whose money movement is itself ambiguous must be resolved by the
+ * idempotency and attempt-fingerprint layer before anything here is consulted;
+ * this kernel cannot make a repeat charge safe.
+ */
+/**
+ * Ordered strongest-refusal-first. The order is documentation only — the
+ * classifier resolves a class from evidence, never from this array's index.
+ */
+/** @beta */
+export declare const PAYMENT_FAILURE_CLASSES: readonly ["hard_do_not_retry", "mandate_dead", "sca_required", "fix_and_retry_customer_action", "soft_retry_delayed", "soft_retryable", "indeterminate"];
+/** @beta */
+export type PaymentFailureClass = (typeof PAYMENT_FAILURE_CLASSES)[number];
+/**
+ * The retry verdict the network or issuer returned with the refusal. These three
+ * values are scheme-standard advice, not one acquirer's vocabulary, which is why
+ * a neutral kernel may name them.
+ */
+/** @beta */
+export declare const PAYMENT_RETRY_ADVICE_CODES: readonly ["do_not_try_again", "try_again_later", "confirm_card_data"];
+/** @beta */
+export type PaymentRetryAdviceCode = (typeof PAYMENT_RETRY_ADVICE_CODES)[number];
+/**
+ * Neutral assertions an adapter makes about a refusal it already understands.
+ *
+ * The array order IS the resolution order used when several hints are asserted
+ * at once: the strictest reading wins, so a refusal that is both dead and merely
+ * slow is never scheduled for a background retry.
+ */
+/** @beta */
+export declare const PAYMENT_FAILURE_HINTS: readonly ["credentialDead", "mandateUnsupported", "authenticationRequired", "dataInvalid", "limitExceeded", "transient"];
+/** @beta */
+export type PaymentFailureHint = (typeof PAYMENT_FAILURE_HINTS)[number];
+/**
+ * Everything the kernel is allowed to look at. Every field is optional: an
+ * adapter that knows nothing supplies nothing and gets `indeterminate`, which is
+ * an honest answer rather than a guess.
+ */
+/** @beta */
+export interface PaymentFailureEvidence {
+    /** The issuer or network retry verdict, when one was returned. Recognized values are {@link PaymentRetryAdviceCode}; anything else is ignored rather than guessed at. */
+    adviceCode?: string;
+    /** The acquirer's own refusal code, kept opaque here. It contributes a class only through a caller-supplied hint table — this kernel embeds no code lists. */
+    declineCode?: string;
+    /** Neutral assertions the adapter is willing to make about the refusal. */
+    neutralReasonHints?: readonly PaymentFailureHint[];
+    /** The internal reason string already persisted with the attempt, if the failure travelled through the control plane before being classified. */
+    failureReasonKey?: string;
+}
+/** What a retry is allowed to look like for a class. */
+/** @beta */
+export type PaymentRetryProfile = "standard" | "delayed" | "none" | "on_session_only";
+/**
+ * The consequence of a class, as data. This record does not schedule anything and
+ * does not know the current ladder; it states what a scheduler is permitted to do.
+ */
+/** @beta */
+export interface PaymentFailureDecision {
+    retryAllowed: boolean;
+    retryProfile: PaymentRetryProfile;
+    customerActionRequired: boolean;
+    methodReplacementRequired: boolean;
+}
+/**
+ * The frozen decision for a class. Frozen so a consumer cannot quietly widen
+ * `retryAllowed` for one call site and leave every other reader believing the
+ * table still holds.
+ */
+/** @beta */
+export declare function failureClassDecision(failureClass: PaymentFailureClass): PaymentFailureDecision;
+/**
+ * What a payer can be TOLD about a refused or impossible charge.
+ *
+ * Coarser than {@link PAYMENT_FAILURE_CLASSES} on purpose: a payer acts on
+ * remedies and there are fewer remedies than classes. Every class whose real
+ * content is "we do not know why" collapses into `unknown`, which exists so a
+ * caller can say nothing rather than guess — a surface rendering `unknown` must
+ * render exactly what it rendered before consulting this vocabulary.
+ *
+ * `method_missing` is the one cause no class produces: it belongs to the
+ * pre-renewal rails, which read a stored method that does not exist rather than a
+ * refusal that happened. It lives here so both kinds of surface quote one
+ * vocabulary instead of two.
+ */
+/** @beta */
+export declare const PAYMENT_FAILURE_CUSTOMER_CAUSES: readonly ["needs_confirmation", "method_cannot_recur", "method_dead", "method_data_invalid", "method_missing", "unknown"];
+/** @beta */
+export type PaymentFailureCustomerCause = (typeof PAYMENT_FAILURE_CUSTOMER_CAUSES)[number];
+/**
+ * The cause a payer may be told, for a class that may not have been recorded.
+ *
+ * Takes `string | null` rather than {@link PaymentFailureClass} on purpose: the
+ * caller reads a nullable column written by an older deployment, and an
+ * unrecognized value must degrade to `unknown` exactly like a missing one.
+ */
+/** @beta */
+export declare function customerCauseForFailureClass(failureClass: string | null | undefined): PaymentFailureCustomerCause;

package/dist/payment/paymentFailureTaxonomyContracts.js

@@ -0,0 +1,177 @@
+/**
+ * The vocabulary a refused payment is classified into, and the retry decision
+ * each class implies.
+ *
+ * The classes answer one question — *may this instrument be charged again, and
+ * by whom* — and nothing else. They are deliberately not a copy of any acquirer's
+ * code list: an adapter translates its own codes into the neutral evidence in
+ * {@link PaymentFailureEvidence}, and only that evidence reaches this kernel.
+ *
+ * `indeterminate` means the CLASS is unknown, never that the OUTCOME is unknown.
+ * A refusal whose money movement is itself ambiguous must be resolved by the
+ * idempotency and attempt-fingerprint layer before anything here is consulted;
+ * this kernel cannot make a repeat charge safe.
+ */
+/**
+ * Ordered strongest-refusal-first. The order is documentation only — the
+ * classifier resolves a class from evidence, never from this array's index.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_CLASSES = [
+    /** The credential is dead or the refusal is final: lost, stolen, reported fraudulent, closed account, or an authorization the payer revoked. Another attempt cannot succeed and still costs scheme fees. */
+    "hard_do_not_retry",
+    /** The stored mandate, alias, or standing consent no longer works even though the instrument may. Re-registration or a replacement method is required; a scheduled retry against the same stored reference repeats the same refusal. */
+    "mandate_dead",
+    /** Strong authentication is required. A retry is only meaningful through an on-session or hosted confirmation the payer can answer; a blind background retry cannot clear it. */
+    "sca_required",
+    /** Submitted data is wrong: number, security code, expiry, or address. Never retry automatically — the same wrong data produces the same refusal and, repeated, looks like enumeration. */
+    "fix_and_retry_customer_action",
+    /** Retriable, but only after a longer wait: a velocity, frequency, or amount limit was exceeded and needs time to decay. */
+    "soft_retry_delayed",
+    /** Transient: insufficient funds, a processing error, an unreachable issuer, or an explicit try-again-later verdict. A scheduled retry is the correct response. */
+    "soft_retryable",
+    /** Unclassifiable from the evidence supplied. Treated as soft with the default schedule, which is the conservative choice only because the retry ladder is bounded elsewhere. */
+    "indeterminate",
+];
+/**
+ * The retry verdict the network or issuer returned with the refusal. These three
+ * values are scheme-standard advice, not one acquirer's vocabulary, which is why
+ * a neutral kernel may name them.
+ */
+/** @beta */
+export const PAYMENT_RETRY_ADVICE_CODES = [
+    "do_not_try_again",
+    "try_again_later",
+    "confirm_card_data",
+];
+/**
+ * Neutral assertions an adapter makes about a refusal it already understands.
+ *
+ * The array order IS the resolution order used when several hints are asserted
+ * at once: the strictest reading wins, so a refusal that is both dead and merely
+ * slow is never scheduled for a background retry.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_HINTS = [
+    /** The instrument itself is finished: reported lost or stolen, flagged as fraud, closed, or the payer withdrew authorization. */
+    "credentialDead",
+    /** The payer's bank cannot honour the stored reusable reference, whatever the instrument's own state. */
+    "mandateUnsupported",
+    /** The refusal is an authentication demand, not a decline of the money. */
+    "authenticationRequired",
+    /** A submitted value was rejected as wrong rather than refused as unaffordable. */
+    "dataInvalid",
+    /** A velocity, frequency, or amount limit was hit; the same charge may pass once the limit decays. */
+    "limitExceeded",
+    /** An ordinary temporary refusal with no further detail. */
+    "transient",
+];
+const DECISIONS = Object.freeze({
+    hard_do_not_retry: Object.freeze({
+        retryAllowed: false,
+        retryProfile: "none",
+        customerActionRequired: true,
+        methodReplacementRequired: true,
+    }),
+    mandate_dead: Object.freeze({
+        retryAllowed: false,
+        retryProfile: "none",
+        customerActionRequired: true,
+        methodReplacementRequired: true,
+    }),
+    sca_required: Object.freeze({
+        retryAllowed: true,
+        retryProfile: "on_session_only",
+        customerActionRequired: true,
+        methodReplacementRequired: false,
+    }),
+    fix_and_retry_customer_action: Object.freeze({
+        retryAllowed: false,
+        retryProfile: "none",
+        customerActionRequired: true,
+        methodReplacementRequired: false,
+    }),
+    soft_retry_delayed: Object.freeze({
+        retryAllowed: true,
+        retryProfile: "delayed",
+        customerActionRequired: false,
+        methodReplacementRequired: false,
+    }),
+    soft_retryable: Object.freeze({
+        retryAllowed: true,
+        retryProfile: "standard",
+        customerActionRequired: false,
+        methodReplacementRequired: false,
+    }),
+    indeterminate: Object.freeze({
+        retryAllowed: true,
+        retryProfile: "standard",
+        customerActionRequired: false,
+        methodReplacementRequired: false,
+    }),
+});
+/**
+ * The frozen decision for a class. Frozen so a consumer cannot quietly widen
+ * `retryAllowed` for one call site and leave every other reader believing the
+ * table still holds.
+ */
+/** @beta */
+export function failureClassDecision(failureClass) {
+    return DECISIONS[failureClass];
+}
+/**
+ * What a payer can be TOLD about a refused or impossible charge.
+ *
+ * Coarser than {@link PAYMENT_FAILURE_CLASSES} on purpose: a payer acts on
+ * remedies and there are fewer remedies than classes. Every class whose real
+ * content is "we do not know why" collapses into `unknown`, which exists so a
+ * caller can say nothing rather than guess — a surface rendering `unknown` must
+ * render exactly what it rendered before consulting this vocabulary.
+ *
+ * `method_missing` is the one cause no class produces: it belongs to the
+ * pre-renewal rails, which read a stored method that does not exist rather than a
+ * refusal that happened. It lives here so both kinds of surface quote one
+ * vocabulary instead of two.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_CUSTOMER_CAUSES = [
+    /** Authentication is owed; the instrument may be fine, nobody was present. */
+    "needs_confirmation",
+    /** Stored consent cannot back an unattended charge, whatever the instrument. */
+    "method_cannot_recur",
+    /** The instrument is finished; another attempt on it cannot succeed. */
+    "method_dead",
+    /** Stored details rejected as wrong, not refused as unaffordable. */
+    "method_data_invalid",
+    /** No usable stored method. Pre-renewal state only, never a refusal. */
+    "method_missing",
+    /** Nothing may be claimed. Surfaces must add no sentence at all. */
+    "unknown",
+];
+const CUSTOMER_CAUSES = Object.freeze({
+    hard_do_not_retry: "method_dead",
+    mandate_dead: "method_cannot_recur",
+    sca_required: "needs_confirmation",
+    fix_and_retry_customer_action: "method_data_invalid",
+    // The soft readings say only that a retry is allowed, which is not a cause
+    // anybody can act on; `indeterminate` says outright that nothing is known.
+    // Naming a cause here would invent an issuer verdict.
+    soft_retry_delayed: "unknown",
+    soft_retryable: "unknown",
+    indeterminate: "unknown",
+});
+/**
+ * The cause a payer may be told, for a class that may not have been recorded.
+ *
+ * Takes `string | null` rather than {@link PaymentFailureClass} on purpose: the
+ * caller reads a nullable column written by an older deployment, and an
+ * unrecognized value must degrade to `unknown` exactly like a missing one.
+ */
+/** @beta */
+export function customerCauseForFailureClass(failureClass) {
+    if (failureClass === null || failureClass === undefined)
+        return "unknown";
+    return Object.prototype.hasOwnProperty.call(CUSTOMER_CAUSES, failureClass)
+        ? CUSTOMER_CAUSES[failureClass]
+        : "unknown";
+}

package/dist/payment/paymentRecovery.d.ts

@@ -0,0 +1,26 @@
+import { type PaymentAttemptStatus } from "./paymentControlTypes.js";
+import type { PaymentRecoveryAction, PaymentRecoveryCandidate, PaymentRecoveryEvidence, PaymentRecoveryOperation } from "./paymentRecoveryContracts.js";
+/** @beta */
+export interface PaymentRecoveryAttempt {
+    id: string;
+    status: PaymentAttemptStatus;
+    evidence: PaymentRecoveryEvidence | null;
+}
+/** @beta */
+export interface PaymentRecoveryGuidance extends PaymentRecoveryEvidence {
+    version: 1;
+    paymentAttemptId: string;
+    consecutiveRefusals: 0 | 1 | 2 | null;
+    emphasis: "normal" | "recommended";
+    actions: readonly PaymentRecoveryAction[];
+}
+/** Only an authoritative failed attempt can become refusal guidance. @beta */
+export declare function derivePaymentRecoveryGuidance(input: {
+    paymentState: "failed" | "paid" | "pending" | "expired";
+    activeAttemptId: string | null;
+    /** Newest first, ordered by durable creation identity; never browser clicks. */
+    attempts: readonly PaymentRecoveryAttempt[];
+    historyComplete: boolean;
+}): PaymentRecoveryGuidance | null;
+/** Filter with currently implemented, eligible choices; this never enables a rail. @beta */
+export declare function availablePaymentRecoveryActions(guidance: PaymentRecoveryGuidance, candidates: readonly PaymentRecoveryCandidate[], operation: PaymentRecoveryOperation): PaymentRecoveryAction[];

package/dist/payment/paymentRecovery.js

@@ -0,0 +1,73 @@
+import { isLiveAttemptStatus } from "./paymentControlTypes.js";
+/** Only an authoritative failed attempt can become refusal guidance. @beta */
+export function derivePaymentRecoveryGuidance(input) {
+    if (input.paymentState !== "failed" || !input.activeAttemptId)
+        return null;
+    if (input.attempts.some((attempt) => attempt.status === "succeeded"))
+        return null;
+    const current = input.attempts.find((attempt) => attempt.id === input.activeAttemptId);
+    if (!current || current.status !== "failed" || !current.evidence?.refusalVerified)
+        return null;
+    // A later local attempt makes this a stale observation even if a caller picked it.
+    if (input.attempts[0]?.id !== current.id)
+        return null;
+    const evidence = safeEvidence(current.evidence);
+    const count = evidence.cause !== "generic_decline" ? 0
+        : refusalStreak(input.attempts, evidence.method?.recoveryMethodKey, input.historyComplete);
+    const actions = evidence.cause === "expired_card"
+        ? ["change_instrument", "change_method"]
+        : evidence.cause === "invalid_payment_data" ? ["correct_data", "change_method"]
+            : evidence.cause === "authentication_required" ? ["authenticate", "change_method"]
+                : ["change_instrument", "change_method"];
+    if (evidence.advice?.code === "do_not_try_again" && evidence.advice.scope === "method") {
+        actions.splice(0, actions.length, "change_method");
+    }
+    return { ...evidence, version: 1, paymentAttemptId: current.id,
+        consecutiveRefusals: count, emphasis: count === 2 ? "recommended" : "normal", actions };
+}
+function safeEvidence(evidence) {
+    return evidence.disclosure === "restricted" || evidence.certainty !== "verified"
+        ? { ...evidence, cause: "generic_decline", certainty: "unknown" } : evidence;
+}
+function refusalStreak(attempts, methodKey, complete) {
+    if (!methodKey)
+        return null;
+    let count = 0;
+    const seen = new Set();
+    for (const attempt of attempts) {
+        if (seen.has(attempt.id))
+            continue;
+        seen.add(attempt.id);
+        if (isLiveAttemptStatus(attempt.status) || ["blocked_preflight", "cancelled", "expired"].includes(attempt.status))
+            continue;
+        const evidence = attempt.evidence;
+        if (!evidence?.refusalVerified || !evidence.method)
+            return null;
+        if (safeEvidence(evidence).cause !== "generic_decline" || evidence.method.recoveryMethodKey !== methodKey) {
+            return count > 0 ? 1 : null;
+        }
+        count += 1;
+        if (count >= 2)
+            return 2;
+    }
+    return complete && count === 1 ? 1 : null;
+}
+/** Filter with currently implemented, eligible choices; this never enables a rail. @beta */
+export function availablePaymentRecoveryActions(guidance, candidates, operation) {
+    const available = new Set();
+    for (const candidate of candidates) {
+        if (candidate.capability !== "supported" || !candidate.available || candidate.operation !== operation)
+            continue;
+        for (const action of candidate.actions) {
+            if (!guidance.actions.includes(action))
+                continue;
+            const sameChoice = candidate.method.recoveryMethodKey === guidance.method?.recoveryMethodKey;
+            if (action === "change_method" && sameChoice)
+                continue;
+            if (action === "change_instrument" && (!sameChoice || candidate.method.interaction !== "new_instrument"))
+                continue;
+            available.add(action);
+        }
+    }
+    return available.size ? [...available] : ["contact_support"];
+}

package/dist/payment/paymentRecoveryContracts.d.ts

@@ -0,0 +1,53 @@
+/** Checkout guidance describes evidence; it never authorizes another charge. */
+import type { PaymentRetryAdviceCode } from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export declare const PAYMENT_RECOVERY_CAUSES: readonly ["generic_decline", "insufficient_funds", "expired_card", "invalid_payment_data", "authentication_required", "operation_unsupported", "recurring_setup_failed"];
+/** @beta */
+export type PaymentRecoveryCause = (typeof PAYMENT_RECOVERY_CAUSES)[number];
+/** @beta */
+export declare const PAYMENT_RECOVERY_ACTIONS: readonly ["change_method", "change_instrument", "correct_data", "authenticate", "check_status", "review_order", "contact_support", "retry"];
+/** @beta */
+export type PaymentRecoveryAction = (typeof PAYMENT_RECOVERY_ACTIONS)[number];
+/** @beta */
+export type PaymentRecoveryOperation = "one_time_payment" | "recurring_setup" | "stored_method_payment";
+/** @beta */
+export interface PaymentRecoveryMethod {
+    /** A method identity, never an operator identity or an instrument fingerprint. */
+    kind: string;
+    /** Canonical visible choice; changing operator alone cannot change this key. */
+    recoveryMethodKey: string;
+    interaction: "new_instrument" | "stored_instrument";
+}
+/** @beta */
+export interface PaymentRecoveryAdvice {
+    code: PaymentRetryAdviceCode;
+    scope: "instrument" | "method" | "operation" | "unknown";
+}
+/** @beta */
+export interface PaymentRecoveryEvidence {
+    /** Established refusal, not merely an unconfirmed or locally failed request. */
+    refusalVerified: boolean;
+    cause: PaymentRecoveryCause;
+    certainty: "verified" | "unknown";
+    disclosure: "safe" | "restricted";
+    method: PaymentRecoveryMethod | null;
+    operation: PaymentRecoveryOperation | null;
+    advice: PaymentRecoveryAdvice | null;
+}
+/** @beta */
+export interface PaymentRecoveryCandidate {
+    method: PaymentRecoveryMethod;
+    operation: PaymentRecoveryOperation;
+    capability: "supported" | "unsupported" | "unknown";
+    /** Resolved deployment, merchant and client eligibility, not operator marketing. */
+    available: boolean;
+    actions: readonly PaymentRecoveryAction[];
+}
+/**
+ * Companion to execution capabilities. A caller injects provider normalizers;
+ * the kernel sees only their neutral outputs. An absent normalizer adds no facts.
+ * @beta
+ */
+export interface PaymentRecoveryNormalizer<TInput = unknown> {
+    normalize(input: TInput): PaymentRecoveryEvidence | null;
+}

package/dist/payment/paymentRecoveryContracts.js

@@ -0,0 +1,10 @@
+/** @beta */
+export const PAYMENT_RECOVERY_CAUSES = [
+    "generic_decline", "insufficient_funds", "expired_card", "invalid_payment_data",
+    "authentication_required", "operation_unsupported", "recurring_setup_failed",
+];
+/** @beta */
+export const PAYMENT_RECOVERY_ACTIONS = [
+    "change_method", "change_instrument", "correct_data", "authenticate",
+    "check_status", "review_order", "contact_support", "retry",
+];

package/dist/payment/paymentStateMachine.d.ts

@@ -0,0 +1,28 @@
+import type { CanonicalPaymentControlEvent, PaymentAttemptAggregate, PaymentAttemptStatus, PaymentControlDecision, PaymentControlResult, PaymentIntentAggregate, PaymentIntentStatus } from "./paymentControlTypes.js";
+/** @beta */
+export declare function canTransitionPaymentIntent(from: PaymentIntentStatus, to: PaymentIntentStatus): boolean;
+/** @beta */
+export declare function canTransitionPaymentAttempt(from: PaymentAttemptStatus, to: PaymentAttemptStatus): boolean;
+/** @beta */
+export declare function transitionPaymentIntent(input: {
+    intent: PaymentIntentAggregate;
+    to: PaymentIntentStatus;
+    at: string;
+    failureReason?: string | null;
+}): PaymentControlResult<PaymentIntentAggregate>;
+/** @beta */
+export declare function transitionPaymentAttempt(input: {
+    attempt: PaymentAttemptAggregate;
+    to: PaymentAttemptStatus;
+    at: string;
+    providerAttemptId?: string | null;
+    nextActionKind?: string | null;
+    failureReason?: string | null;
+}): PaymentControlResult<PaymentAttemptAggregate>;
+/** @beta */
+export declare function applyProviderPaymentEvent(input: {
+    intent: PaymentIntentAggregate;
+    attempt: PaymentAttemptAggregate;
+    event: CanonicalPaymentControlEvent;
+    seenProviderEventIds?: readonly string[];
+}): PaymentControlResult<PaymentControlDecision>;

package/dist/payment/paymentStateMachine.js

@@ -0,0 +1,184 @@
+const intentTransitions = {
+    created: ["requires_action", "processing", "failed", "expired", "cancelled"],
+    requires_action: ["processing", "succeeded", "failed", "expired", "cancelled"],
+    processing: ["requires_action", "succeeded", "failed", "expired", "cancelled"],
+    failed: ["requires_action", "processing", "succeeded", "cancelled"],
+    expired: ["requires_action", "processing", "succeeded", "cancelled"],
+    cancelled: [],
+    succeeded: ["refunded", "partially_refunded", "disputed"],
+    partially_refunded: ["refunded", "disputed"],
+    refunded: ["disputed"],
+    disputed: [],
+};
+const attemptTransitions = {
+    created: ["blocked_preflight", "sent_to_provider", "requires_action", "processing", "failed", "cancelled", "expired"],
+    blocked_preflight: ["failed", "cancelled", "expired"],
+    sent_to_provider: ["requires_action", "processing", "succeeded", "failed", "cancelled", "expired"],
+    requires_action: ["processing", "succeeded", "failed", "cancelled", "expired"],
+    processing: ["requires_action", "succeeded", "failed", "cancelled", "expired"],
+    failed: ["succeeded"],
+    cancelled: ["succeeded"],
+    expired: ["succeeded"],
+    succeeded: [],
+};
+function success(value) {
+    return { ok: true, value };
+}
+function failure(reason, message) {
+    return { ok: false, reason, message };
+}
+/** @beta */
+export function canTransitionPaymentIntent(from, to) {
+    return from === to || intentTransitions[from].includes(to);
+}
+/** @beta */
+export function canTransitionPaymentAttempt(from, to) {
+    return from === to || attemptTransitions[from].includes(to);
+}
+/** @beta */
+export function transitionPaymentIntent(input) {
+    if (!canTransitionPaymentIntent(input.intent.status, input.to)) {
+        return failure("invalid_transition", `Cannot move payment intent from ${input.intent.status} to ${input.to}`);
+    }
+    return success({
+        ...input.intent,
+        status: input.to,
+        updatedAt: input.at,
+        failureReason: input.failureReason ?? (input.to === "failed" ? input.intent.failureReason ?? "provider_failed" : null),
+    });
+}
+/** @beta */
+export function transitionPaymentAttempt(input) {
+    if (!canTransitionPaymentAttempt(input.attempt.status, input.to)) {
+        return failure("invalid_transition", `Cannot move payment attempt from ${input.attempt.status} to ${input.to}`);
+    }
+    return success({
+        ...input.attempt,
+        status: input.to,
+        updatedAt: input.at,
+        providerAttemptId: input.providerAttemptId ?? input.attempt.providerAttemptId,
+        nextActionKind: input.nextActionKind ?? input.attempt.nextActionKind ?? null,
+        failureReason: input.failureReason ?? (input.to === "failed" ? input.attempt.failureReason ?? "provider_failed" : null),
+    });
+}
+function assertEventTargetsActiveAttempt(input) {
+    if (input.attempt.intentId !== input.intent.id || input.intent.activeAttemptId !== input.attempt.id) {
+        return failure("wrong_attempt", "Provider event must target the active local payment attempt");
+    }
+    return success(undefined);
+}
+function assertMoneyMatches(input) {
+    if (input.event.currency && input.event.currency !== input.intent.currency) {
+        return failure("currency_mismatch", "Provider event currency does not match the local payment intent");
+    }
+    if (input.event.amountMinor === undefined)
+        return success(undefined);
+    if (input.exactAmount && input.event.amountMinor !== input.intent.amountMinor) {
+        return failure("amount_mismatch", "Provider event amount does not match the local payment intent");
+    }
+    if (!input.exactAmount && (input.event.amountMinor < 1 || input.event.amountMinor > input.intent.amountMinor)) {
+        return failure("amount_mismatch", "Refund amount must be positive and not exceed the original payment amount");
+    }
+    return success(undefined);
+}
+function buildDecision(input) {
+    return success(input);
+}
+/** @beta */
+export function applyProviderPaymentEvent(input) {
+    if (input.seenProviderEventIds?.includes(input.event.providerEventId)) {
+        return buildDecision({ kind: "noop", reason: "duplicate_provider_event", ...input });
+    }
+    const targetCheck = assertEventTargetsActiveAttempt(input);
+    if (targetCheck.ok === false)
+        return failure(targetCheck.reason, targetCheck.message);
+    if (input.event.eventType === "payment.refunded")
+        return applyRefundEvent(input);
+    if (input.event.eventType === "payment.disputed")
+        return applyDisputeEvent(input);
+    const moneyCheck = assertMoneyMatches({ intent: input.intent, event: input.event, exactAmount: true });
+    if (moneyCheck.ok === false)
+        return failure(moneyCheck.reason, moneyCheck.message);
+    if (input.event.eventType === "payment.succeeded")
+        return applySuccessEvent(input);
+    if (input.event.eventType === "payment.failed")
+        return applyFailureEvent(input);
+    return applyRequiresActionEvent(input);
+}
+function applyRequiresActionEvent(input) {
+    const intent = transitionPaymentIntent({ intent: input.intent, to: "requires_action", at: input.event.occurredAt });
+    const attempt = transitionPaymentAttempt({
+        attempt: input.attempt,
+        to: "requires_action",
+        at: input.event.occurredAt,
+        providerAttemptId: input.event.providerPaymentId,
+        nextActionKind: input.event.nextActionKind ?? null,
+    });
+    if (intent.ok === false)
+        return failure(intent.reason, intent.message);
+    if (attempt.ok === false)
+        return failure(attempt.reason, attempt.message);
+    return buildDecision({ kind: "state_changed", reason: "provider_requires_action", intent: intent.value, attempt: attempt.value });
+}
+function applySuccessEvent(input) {
+    if (["cancelled", "refunded", "partially_refunded", "disputed"].includes(input.intent.status)) {
+        return failure("terminal_intent", `Cannot apply provider success after intent status ${input.intent.status}`);
+    }
+    if (input.intent.status === "succeeded" && input.attempt.status === "succeeded") {
+        return buildDecision({ kind: "noop", reason: "already_succeeded", ...input });
+    }
+    const recovered = input.intent.status === "failed" || input.intent.status === "expired";
+    const intent = transitionPaymentIntent({ intent: input.intent, to: "succeeded", at: input.event.occurredAt });
+    const attempt = transitionPaymentAttempt({
+        attempt: input.attempt,
+        to: "succeeded",
+        at: input.event.occurredAt,
+        providerAttemptId: input.event.providerPaymentId,
+        failureReason: null,
+    });
+    if (intent.ok === false)
+        return failure(intent.reason, intent.message);
+    if (attempt.ok === false)
+        return failure(attempt.reason, attempt.message);
+    return buildDecision({
+        kind: recovered ? "late_success_recovered" : "state_changed",
+        reason: recovered ? "late_success_after_failed_or_expired" : "provider_succeeded",
+        intent: { ...intent.value, providerPaymentId: input.event.providerPaymentId },
+        attempt: attempt.value,
+    });
+}
+function applyFailureEvent(input) {
+    if (["succeeded", "refunded", "partially_refunded", "disputed"].includes(input.intent.status)) {
+        return buildDecision({ kind: "noop", reason: "ignored_failure_after_success_or_terminal", ...input });
+    }
+    const reason = input.event.failureReason ?? "provider_failed";
+    const intent = transitionPaymentIntent({ intent: input.intent, to: "failed", at: input.event.occurredAt, failureReason: reason });
+    const attempt = transitionPaymentAttempt({ attempt: input.attempt, to: "failed", at: input.event.occurredAt, failureReason: reason });
+    if (intent.ok === false)
+        return failure(intent.reason, intent.message);
+    if (attempt.ok === false)
+        return failure(attempt.reason, attempt.message);
+    return buildDecision({ kind: "state_changed", reason: "provider_failed", intent: intent.value, attempt: attempt.value });
+}
+function applyRefundEvent(input) {
+    if (!["succeeded", "partially_refunded", "refunded"].includes(input.intent.status)) {
+        return failure("refund_requires_success", "Refund event requires a previously succeeded local payment intent");
+    }
+    const moneyCheck = assertMoneyMatches({ intent: input.intent, event: input.event, exactAmount: false });
+    if (moneyCheck.ok === false)
+        return failure(moneyCheck.reason, moneyCheck.message);
+    const status = input.event.amountMinor === input.intent.amountMinor ? "refunded" : "partially_refunded";
+    const intent = transitionPaymentIntent({ intent: input.intent, to: status, at: input.event.occurredAt });
+    if (intent.ok === false)
+        return failure(intent.reason, intent.message);
+    return buildDecision({ kind: "state_changed", reason: "provider_refunded", intent: intent.value, attempt: input.attempt });
+}
+function applyDisputeEvent(input) {
+    if (input.intent.status === "cancelled") {
+        return failure("terminal_intent", "Cannot dispute a cancelled local payment intent");
+    }
+    const intent = transitionPaymentIntent({ intent: input.intent, to: "disputed", at: input.event.occurredAt });
+    if (intent.ok === false)
+        return failure(intent.reason, intent.message);
+    return buildDecision({ kind: "state_changed", reason: "provider_disputed", intent: intent.value, attempt: input.attempt });
+}