@asteby/storefront-react 0.16.0 → 0.17.0

package/dist/payments.css

@@ -68,3 +68,22 @@
     display: none !important;
   }
 }
+
+/* "Updating the total": the card form stays mounted; this layer only dims it and blocks input meanwhile. */
+[data-sf-pay-card][data-sf-pay-updating] [data-sf-pay-container] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+/* Notice of a payment that did not end well (<PaymentRecovery>). Neutral spacing only; colors come from `classNames`. */
+[data-sf-pay-recovery] {
+  display: grid;
+  gap: 0.75rem;
+}
+[data-sf-pay-recovery] > p {
+  margin: 0;
+}
+[data-sf-pay-recovery] > div {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}

package/dist/payments.d.cts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject } from 'react';
-import { Money, PaymentAttemptResult, PaymentClient, PaymentOutcomeKind, PaymentOutcome, PaymentErrorView, PaymentMessages, PaymentErrorKind, PaymentOptionKey } from '@asteby/storefront';
-import { a as PayChoices } from './choices-DEPE9KRq.cjs';
-export { B as BuildPayChoicesOptions, P as PayChoice, b as PayErrorBody, c as PaymentCspMode, d as PaymentCspOptions, V as VoucherRowLabels, e as buildPayChoices, f as cashProviderData, g as checkoutToAttempt, h as choiceValue, p as parseChoice, i as payErrorResponse, j as paymentCsp, k as paymentCspHeaderName, l as paymentCspHeaders, m as paymentCspMode, n as paymentNonce, o as paymentNonceFromHeaders, v as voucherRows } from './choices-DEPE9KRq.cjs';
+import { Money, PaymentAttemptResult, PaymentClient, PaymentErrorClassKind, PaymentOutcomeKind, PaymentOutcome, PaymentErrorView, PaymentMessages, PaymentErrorKind, PaymentOptionKey } from '@asteby/storefront';
+import { h as PaymentRecoveryMessages, f as PaymentNoticeKind, P as PayChoice, a as PayChoices } from './csp-DZPuExzu.cjs';
+export { B as BuildPayChoicesOptions, b as PayErrorBody, c as PayErrorOptions, d as PaymentCspMode, e as PaymentCspOptions, g as PaymentRecoveryMessageKey, V as VoucherRowLabels, i as buildPayChoices, j as cashProviderData, k as checkoutToAttempt, l as choiceValue, p as parseChoice, m as payErrorResponse, n as paymentCsp, o as paymentCspHeaderName, q as paymentCspHeaders, r as paymentCspMode, s as paymentNonce, t as paymentNonceFromHeaders, u as paymentRecoveryMessages, v as safeHttpStatus, w as voucherRows } from './csp-DZPuExzu.cjs';
 
 /**
  * Replaceable ports of the embedded payment. The shop (or another provider)
@@ -37,6 +37,8 @@ type PaymentFormMountOptions = {
     colorScheme?: 'light' | 'dark';
     onReady: () => void;
     onError: (error: PaymentFormError) => void;
+    /** Aborted when this mount is no longer wanted (the form unmounted or was replaced). Adapters must not create after it. */
+    signal?: AbortSignal;
 };
 /** What a mounted form hands back at submit time. */
 type PaymentFormData = {
@@ -48,6 +50,13 @@ type PaymentFormData = {
 interface MountedPaymentForm {
     /** Tokenises the card inside the provider iframes. Rejects when the form is invalid (the provider shows the field errors). */
     collect(): Promise<PaymentFormData>;
+    /**
+     * Applies a new server total to the form that is already on screen, without remounting it. Rejects when the provider
+     * cannot (the hook then remounts, queued). Absent: the hook remounts on every total change.
+     */
+    update?(next: {
+        amount: Money;
+    }): Promise<void>;
     unmount(): void | Promise<void>;
 }
 interface PaymentFormAdapter {
@@ -89,7 +98,16 @@ declare class PaymentHttpError extends Error {
     readonly name = "PaymentHttpError";
     constructor(status: number, code: string, message?: string, 
     /** Raw `error.details` (e.g. the new `cost` of a `price_mismatch`); untrusted shape. */
-    details?: unknown | undefined);
+    details?: unknown | undefined, 
+    /** Optional classification from the shop's JSON body (`retryable`, `kind`). */
+    extra?: {
+        retryable?: boolean | undefined;
+        kind?: PaymentErrorClassKind | undefined;
+    });
+    /** `error.retryable` of the shop body: `true` repeat with the SAME key; `false` it is an answer. `undefined`: not said. */
+    readonly retryable: boolean | undefined;
+    /** `error.kind` of the shop body (`classifyPaymentError`). */
+    readonly kind: PaymentErrorClassKind | undefined;
 }
 type FetchTransportOptions = {
     fetch?: typeof fetch;
@@ -135,7 +153,11 @@ type PaymentEvent = {
 type UseEmbeddedPaymentOptions = {
     /** Provider data from `paymentMethods[].client`. `null`/absent: nothing to mount (status `idle`). */
     client: PaymentClient | null | undefined;
-    /** The total computed by the server. The Brick is remounted when it changes. Never calculate it in the shop. */
+    /**
+     * The total computed by the server. When it changes the form on screen is UPDATED in place (`MountedPaymentForm.update`)
+     * or, if the provider cannot, mounted again through the queue; never while a charge is in flight (applied after the
+     * answer). Never calculate it in the shop.
+     */
     amount: Money;
     transport: PaymentTransport;
     /** Mount only while the card option is selected. Default true. */
@@ -154,6 +176,12 @@ type UseEmbeddedPaymentOptions = {
     autoRetries?: number;
     /** Base delay for the backoff between automatic retries. Default 600. */
     retryDelayMs?: number;
+    /** Longest wait for the provider's `create` before the form is declared failed. Default `sdkTimeoutMs`. */
+    createTimeoutMs?: number;
+    /** After an UNKNOWN outcome ("verifying"), how long the hook keeps reading `refresh`, with growing waits. Default 120000. */
+    verifyTimeoutMs?: number;
+    /** First wait of that check (doubles up to 15 s). Default 2000. */
+    verifyIntervalMs?: number;
     /** Poll interval/timeout for a pending 3DS challenge or review when `transport.refresh` exists. */
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
@@ -187,6 +215,8 @@ type EmbeddedPaymentState = {
     attemptId: string | null;
     /** `true` while loading, mounting or processing. */
     busy: boolean;
+    /** `true` while the hook reads the payment state in the background after an unknown outcome. The attempt stays the same. */
+    verifying: boolean;
     /** Attach to the element the provider renders into. */
     containerRef: (el: HTMLElement | null) => void;
     containerId: string;
@@ -272,11 +302,182 @@ declare const PaymentBrick: react.ForwardRefExoticComponent<Omit<UseEmbeddedPaym
     style?: CSSProperties;
 } & react.RefAttributes<EmbeddedPaymentState>>;
 
+/**
+ * Mount queue for provider forms. Provider SDKs (Mercado Pago Bricks among them) resolve their container by id,
+ * asynchronously, and unmount asynchronously too. Without care, a remount races the previous unmount on the same node
+ * and the provider answers `container_not_found`, leaves an empty form, or draws two.
+ *
+ * Guarantees, per container element:
+ * - ONE mount at a time: a new mount waits for the previous one to finish tearing down (`await unmount`) before `create`.
+ * - Each mount gets its OWN inner node with a unique id, so the provider never looks for an id React already replaced.
+ * - A mount that was cancelled (`signal`) or whose container left the DOM never calls the provider; one that finishes
+ *   late is torn down instead of kept.
+ * - `create` has a time limit: a provider call that never resolves cannot freeze the chain.
+ */
+
+declare class PaymentMountCancelled extends Error {
+    readonly name = "PaymentMountCancelled";
+    constructor(message?: string);
+}
+declare class PaymentMountTimeout extends Error {
+    readonly name = "PaymentMountTimeout";
+    constructor(ms: number);
+}
+type MountQueueOptions = {
+    /** Longest wait for the provider's `create`. Default 10000. */
+    createTimeoutMs?: number;
+};
+/** Mounts `base` on `opts.container` through the queue. See the module comment for the guarantees. */
+declare function mountQueued(base: PaymentFormAdapter, opts: PaymentFormMountOptions, queue?: MountQueueOptions): Promise<MountedPaymentForm>;
+/** Wraps an adapter so every `mount` goes through the queue. The hook already does this for any adapter it uses. */
+declare function withMountQueue(adapter: PaymentFormAdapter, queue?: MountQueueOptions): PaymentFormAdapter;
+
+/**
+ * Browser transport to the shop's pay and status routes, with the retry policy a card payment needs.
+ *
+ * - A TRANSIENT failure (5xx, timeout, network, a proxy HTML page) is repeated up to `retries` times with the SAME
+ *   idempotency key (`request.idempotencyKey`): OPS then answers with the result of the first attempt. A payment whose
+ *   outcome is unknown is NEVER charged with another key.
+ * - If it is still unknown, the status route is read `statusPolls` times. A resolved answer (paid, failed, voucher,
+ *   challenge...) is returned; otherwise a network error is thrown and the hook keeps the SAME attempt (retry button
+ *   and background checks).
+ * - `retryable: false` (an answer from OPS) is ONE request: no repeat, no status read.
+ * - A body that is not JSON is treated as transient, never as a definitive error.
+ */
+
+/** What the screen is told while a payment is being repeated or checked, and when it ends with a problem. */
+type PaymentIssue = {
+    kind: 'confirming';
+    message: string;
+} | {
+    kind: 'verifying';
+    message: string;
+} | {
+    kind: PaymentErrorClassKind;
+    message: string;
+    retryable: boolean;
+    status: number;
+    code: string;
+};
+type ResilientTransportOptions = {
+    /** Same-origin route that charges the card (`handlers.pay`). */
+    payUrl: string;
+    /** Same-origin route that re-reads the payment (`handlers.status`). Enables the status checks and `refresh`. */
+    statusUrl: string;
+    /** Fields of the page form (delivery, contact, payment choice) that travel with the charge. */
+    fields: () => Record<string, string>;
+    /** Called with the state of the retry/verification and with the final problem; `null` clears it. */
+    onIssue?: (issue: PaymentIssue | null) => void;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** Automatic repeats after the first request. Default 2. */
+    retries?: number;
+    /** Wait before each repeat (ms); the last value repeats. Default `[800, 2000]`. */
+    backoffMs?: readonly number[];
+    /** Status reads before declaring the result "verifying". Default 3. */
+    statusPolls?: number;
+    /** Wait between status reads (ms). Default 2000. */
+    statusPollMs?: number;
+    /** Extra headers for both routes. */
+    headers?: Record<string, string>;
+    locale?: string;
+    messages?: Partial<PaymentRecoveryMessages>;
+};
+/** Has OPS decided? `pending` without an action, and `none`, are NOT decisions. */
+declare function isResolvedAttempt(result: PaymentAttemptResult): boolean;
+declare function createResilientTransport(opts: ResilientTransportOptions): PaymentTransport;
+
+type PaymentNotice = {
+    kind: PaymentNoticeKind;
+};
+/** Payment rows other than the in-page card: what the buyer can switch to. */
+declare function alternativeChoices(choices: readonly PayChoice[]): PayChoice[];
+/** Selects a payment row in the page form (the section's radios are the source of truth) and brings it into view. */
+declare function pickChoice(form: HTMLFormElement | null | undefined, value: string): void;
+type UsePaymentRecoveryOptions = {
+    /** Same `scope` as the payment section (usually the cart id): where the attempt key is kept. */
+    scope?: string;
+    /** Where the attempt key lives. Default `sessionStorage`; `null` = memory only. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** Automatic remounts of the secure form before showing the "form failed" notice. Default 2. */
+    formAutoRetries?: number;
+    /** The shop is closed (409 `store_not_ready`) or the like: re-read the page data. */
+    onRevalidate?: () => void;
+};
+type PaymentRecoveryState = {
+    notice: PaymentNotice | null;
+    setNotice: (notice: PaymentNotice | null) => void;
+    /** Use as `key` of `<PaymentMethodSection>`: a new value mounts a fresh section (and a fresh card form). */
+    sectionKey: number;
+    /** Pass to `createResilientTransport({ onIssue })`. */
+    onIssue: (issue: PaymentIssue | null) => void;
+    /** Pass to `<PaymentMethodSection onEvent>` (or compose it with your own handler). */
+    onEvent: (event: PaymentEvent) => void;
+    /** Last problem reported by the transport. */
+    lastIssue: {
+        current: PaymentIssue | null;
+    };
+    /**
+     * New attempt: a NEW idempotency key and a fresh form. Only after a definitive failure; returns `false` (and does
+     * nothing) while the outcome of the last charge is still unknown.
+     */
+    retry: () => boolean;
+    /** Clears the notice (e.g. after the buyer picked another way to pay). */
+    clear: () => void;
+};
+declare function usePaymentRecovery(options?: UsePaymentRecoveryOptions): PaymentRecoveryState;
+type PaymentRecoveryClassNames = Partial<Record<'root' | 'title' | 'body' | 'actions' | 'primary' | 'secondary', string>>;
+type PaymentRecoveryProps = {
+    notice: PaymentNotice | null;
+    /** Other ways to pay (`alternativeChoices(choices)`); they come from the published choices, never from this component. */
+    alternatives?: readonly PayChoice[];
+    /** "Retry payment": new key and fresh form (`usePaymentRecovery().retry`). */
+    onRetry: () => void;
+    /** A way to pay was picked. */
+    onPick: (choice: PayChoice) => void;
+    /** "Refresh my order": re-read the cart and checkout. */
+    onRefresh: () => void;
+    locale?: string;
+    messages?: Partial<PaymentRecoveryMessages>;
+    /** Text of the button of an alternative. Default: the `action.alternative` message with the row name. */
+    alternativeLabel?: (choice: PayChoice) => string;
+    classNames?: PaymentRecoveryClassNames;
+    testIds?: Partial<Record<'retry' | 'refresh', string>>;
+    /** Extra content after the buttons. */
+    children?: ReactNode;
+};
+/** Notice of a card payment that did not end well. `role="status"` while confirming, `role="alert"` (focused) otherwise. */
+declare function PaymentRecovery(props: PaymentRecoveryProps): react.JSX.Element | null;
+
+/**
+ * `shouldRevalidate` for the routes AROUND the checkout (root layout, header, cart badge...). The checkout page saves the
+ * chosen delivery with a `fetcher.submit` to its own route; by default a router then re-runs EVERY loader on the page
+ * (catalog, session, theme...), which is slow and makes the page jump while the buyer is paying. This keeps those loaders
+ * quiet for that submission and leaves everything else (their own forms, navigation) as the router decided.
+ *
+ * Do NOT use it on the checkout route itself: its loader must re-read the cart (the new total) after the submit.
+ * Framework-agnostic: it only reads the fields every router passes (`formMethod`, `formAction`, `defaultShouldRevalidate`).
+ */
+type RevalidateArgs = {
+    formMethod?: string | undefined;
+    formAction?: string | undefined;
+    defaultShouldRevalidate: boolean;
+};
+type CheckoutRevalidateOptions = {
+    /** Paths whose form submissions do not need the other loaders (e.g. `['/pagar']`). Matched on the pathname. */
+    paths: readonly string[];
+};
+declare function checkoutShouldRevalidate(options: CheckoutRevalidateOptions): (args: RevalidateArgs) => boolean;
+
 /** The `PaymentClient.kind` the addon `mercadopago` declares. */
 declare const MERCADOPAGO_BRICKS_KIND = "mercadopago_bricks";
 type MpController = {
     getFormData(): Promise<Record<string, unknown> | undefined | null>;
     unmount(): void | Promise<void>;
+    /** Card Payment Brick: changes the amount without recreating the form. Absent in old SDK builds. */
+    update?(settings: {
+        amount: number;
+    }): void | Promise<void>;
 };
 type MpBricks = {
     create(brick: string, containerId: string, settings: Record<string, unknown>): Promise<MpController>;
@@ -513,4 +714,4 @@ declare function readPaymentTheme(el: Element | null | undefined, tokens?: Recor
  */
 declare function readPaymentScheme(el: Element | null | undefined): 'light' | 'dark' | null;
 
-export { CASH_POINT_FIELD, type EmbeddedPaymentState, type EmbeddedPaymentStatus, type FetchTransportOptions, type LoadScriptOptions, MERCADOPAGO_BRICKS_KIND, type MercadoPagoAdapterOptions, type MercadoPagoCtor, type MountedPaymentForm, PAYMENT_CHOICE_FIELD, PAYMENT_THEME_TOKENS, PayChoices, PaymentBrick, type PaymentBrickHandle, type PaymentBrickProps, PaymentChallenge, type PaymentChallengeProps, type PaymentEvent, type PaymentFallbackReason, type PaymentFormAdapter, type PaymentFormData, type PaymentFormError, type PaymentFormMountOptions, PaymentHttpError, type PaymentMethodClassNames, type PaymentMethodMessages, PaymentMethodSection, type PaymentMethodSectionProps, type PaymentMethodTestIds, type PaymentSubmitRequest, type PaymentTransport, type UseEmbeddedPaymentOptions, VoucherCard, type VoucherCardProps, createFetchTransport, formFields, loadPaymentSdk, mercadoPagoBricksAdapter, paymentMethodMessages, readPaymentScheme, readPaymentTheme, resetPaymentSdkCache, sanitizeMercadoPagoFormData, useEmbeddedPayment };
+export { CASH_POINT_FIELD, type CheckoutRevalidateOptions, type EmbeddedPaymentState, type EmbeddedPaymentStatus, type FetchTransportOptions, type LoadScriptOptions, MERCADOPAGO_BRICKS_KIND, type MercadoPagoAdapterOptions, type MercadoPagoCtor, type MountQueueOptions, type MountedPaymentForm, PAYMENT_CHOICE_FIELD, PAYMENT_THEME_TOKENS, PayChoice, PayChoices, PaymentBrick, type PaymentBrickHandle, type PaymentBrickProps, PaymentChallenge, type PaymentChallengeProps, type PaymentEvent, type PaymentFallbackReason, type PaymentFormAdapter, type PaymentFormData, type PaymentFormError, type PaymentFormMountOptions, PaymentHttpError, type PaymentIssue, type PaymentMethodClassNames, type PaymentMethodMessages, PaymentMethodSection, type PaymentMethodSectionProps, type PaymentMethodTestIds, PaymentMountCancelled, PaymentMountTimeout, type PaymentNotice, PaymentNoticeKind, PaymentRecovery, type PaymentRecoveryClassNames, PaymentRecoveryMessages, type PaymentRecoveryProps, type PaymentRecoveryState, type PaymentSubmitRequest, type PaymentTransport, type ResilientTransportOptions, type RevalidateArgs, type UseEmbeddedPaymentOptions, type UsePaymentRecoveryOptions, VoucherCard, type VoucherCardProps, alternativeChoices, checkoutShouldRevalidate, createFetchTransport, createResilientTransport, formFields, isResolvedAttempt, loadPaymentSdk, mercadoPagoBricksAdapter, mountQueued, paymentMethodMessages, pickChoice, readPaymentScheme, readPaymentTheme, resetPaymentSdkCache, sanitizeMercadoPagoFormData, useEmbeddedPayment, usePaymentRecovery, withMountQueue };

package/dist/payments.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject } from 'react';
-import { Money, PaymentAttemptResult, PaymentClient, PaymentOutcomeKind, PaymentOutcome, PaymentErrorView, PaymentMessages, PaymentErrorKind, PaymentOptionKey } from '@asteby/storefront';
-import { a as PayChoices } from './choices-DEPE9KRq.js';
-export { B as BuildPayChoicesOptions, P as PayChoice, b as PayErrorBody, c as PaymentCspMode, d as PaymentCspOptions, V as VoucherRowLabels, e as buildPayChoices, f as cashProviderData, g as checkoutToAttempt, h as choiceValue, p as parseChoice, i as payErrorResponse, j as paymentCsp, k as paymentCspHeaderName, l as paymentCspHeaders, m as paymentCspMode, n as paymentNonce, o as paymentNonceFromHeaders, v as voucherRows } from './choices-DEPE9KRq.js';
+import { Money, PaymentAttemptResult, PaymentClient, PaymentErrorClassKind, PaymentOutcomeKind, PaymentOutcome, PaymentErrorView, PaymentMessages, PaymentErrorKind, PaymentOptionKey } from '@asteby/storefront';
+import { h as PaymentRecoveryMessages, f as PaymentNoticeKind, P as PayChoice, a as PayChoices } from './csp-DZPuExzu.js';
+export { B as BuildPayChoicesOptions, b as PayErrorBody, c as PayErrorOptions, d as PaymentCspMode, e as PaymentCspOptions, g as PaymentRecoveryMessageKey, V as VoucherRowLabels, i as buildPayChoices, j as cashProviderData, k as checkoutToAttempt, l as choiceValue, p as parseChoice, m as payErrorResponse, n as paymentCsp, o as paymentCspHeaderName, q as paymentCspHeaders, r as paymentCspMode, s as paymentNonce, t as paymentNonceFromHeaders, u as paymentRecoveryMessages, v as safeHttpStatus, w as voucherRows } from './csp-DZPuExzu.js';
 
 /**
  * Replaceable ports of the embedded payment. The shop (or another provider)
@@ -37,6 +37,8 @@ type PaymentFormMountOptions = {
     colorScheme?: 'light' | 'dark';
     onReady: () => void;
     onError: (error: PaymentFormError) => void;
+    /** Aborted when this mount is no longer wanted (the form unmounted or was replaced). Adapters must not create after it. */
+    signal?: AbortSignal;
 };
 /** What a mounted form hands back at submit time. */
 type PaymentFormData = {
@@ -48,6 +50,13 @@ type PaymentFormData = {
 interface MountedPaymentForm {
     /** Tokenises the card inside the provider iframes. Rejects when the form is invalid (the provider shows the field errors). */
     collect(): Promise<PaymentFormData>;
+    /**
+     * Applies a new server total to the form that is already on screen, without remounting it. Rejects when the provider
+     * cannot (the hook then remounts, queued). Absent: the hook remounts on every total change.
+     */
+    update?(next: {
+        amount: Money;
+    }): Promise<void>;
     unmount(): void | Promise<void>;
 }
 interface PaymentFormAdapter {
@@ -89,7 +98,16 @@ declare class PaymentHttpError extends Error {
     readonly name = "PaymentHttpError";
     constructor(status: number, code: string, message?: string, 
     /** Raw `error.details` (e.g. the new `cost` of a `price_mismatch`); untrusted shape. */
-    details?: unknown | undefined);
+    details?: unknown | undefined, 
+    /** Optional classification from the shop's JSON body (`retryable`, `kind`). */
+    extra?: {
+        retryable?: boolean | undefined;
+        kind?: PaymentErrorClassKind | undefined;
+    });
+    /** `error.retryable` of the shop body: `true` repeat with the SAME key; `false` it is an answer. `undefined`: not said. */
+    readonly retryable: boolean | undefined;
+    /** `error.kind` of the shop body (`classifyPaymentError`). */
+    readonly kind: PaymentErrorClassKind | undefined;
 }
 type FetchTransportOptions = {
     fetch?: typeof fetch;
@@ -135,7 +153,11 @@ type PaymentEvent = {
 type UseEmbeddedPaymentOptions = {
     /** Provider data from `paymentMethods[].client`. `null`/absent: nothing to mount (status `idle`). */
     client: PaymentClient | null | undefined;
-    /** The total computed by the server. The Brick is remounted when it changes. Never calculate it in the shop. */
+    /**
+     * The total computed by the server. When it changes the form on screen is UPDATED in place (`MountedPaymentForm.update`)
+     * or, if the provider cannot, mounted again through the queue; never while a charge is in flight (applied after the
+     * answer). Never calculate it in the shop.
+     */
     amount: Money;
     transport: PaymentTransport;
     /** Mount only while the card option is selected. Default true. */
@@ -154,6 +176,12 @@ type UseEmbeddedPaymentOptions = {
     autoRetries?: number;
     /** Base delay for the backoff between automatic retries. Default 600. */
     retryDelayMs?: number;
+    /** Longest wait for the provider's `create` before the form is declared failed. Default `sdkTimeoutMs`. */
+    createTimeoutMs?: number;
+    /** After an UNKNOWN outcome ("verifying"), how long the hook keeps reading `refresh`, with growing waits. Default 120000. */
+    verifyTimeoutMs?: number;
+    /** First wait of that check (doubles up to 15 s). Default 2000. */
+    verifyIntervalMs?: number;
     /** Poll interval/timeout for a pending 3DS challenge or review when `transport.refresh` exists. */
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
@@ -187,6 +215,8 @@ type EmbeddedPaymentState = {
     attemptId: string | null;
     /** `true` while loading, mounting or processing. */
     busy: boolean;
+    /** `true` while the hook reads the payment state in the background after an unknown outcome. The attempt stays the same. */
+    verifying: boolean;
     /** Attach to the element the provider renders into. */
     containerRef: (el: HTMLElement | null) => void;
     containerId: string;
@@ -272,11 +302,182 @@ declare const PaymentBrick: react.ForwardRefExoticComponent<Omit<UseEmbeddedPaym
     style?: CSSProperties;
 } & react.RefAttributes<EmbeddedPaymentState>>;
 
+/**
+ * Mount queue for provider forms. Provider SDKs (Mercado Pago Bricks among them) resolve their container by id,
+ * asynchronously, and unmount asynchronously too. Without care, a remount races the previous unmount on the same node
+ * and the provider answers `container_not_found`, leaves an empty form, or draws two.
+ *
+ * Guarantees, per container element:
+ * - ONE mount at a time: a new mount waits for the previous one to finish tearing down (`await unmount`) before `create`.
+ * - Each mount gets its OWN inner node with a unique id, so the provider never looks for an id React already replaced.
+ * - A mount that was cancelled (`signal`) or whose container left the DOM never calls the provider; one that finishes
+ *   late is torn down instead of kept.
+ * - `create` has a time limit: a provider call that never resolves cannot freeze the chain.
+ */
+
+declare class PaymentMountCancelled extends Error {
+    readonly name = "PaymentMountCancelled";
+    constructor(message?: string);
+}
+declare class PaymentMountTimeout extends Error {
+    readonly name = "PaymentMountTimeout";
+    constructor(ms: number);
+}
+type MountQueueOptions = {
+    /** Longest wait for the provider's `create`. Default 10000. */
+    createTimeoutMs?: number;
+};
+/** Mounts `base` on `opts.container` through the queue. See the module comment for the guarantees. */
+declare function mountQueued(base: PaymentFormAdapter, opts: PaymentFormMountOptions, queue?: MountQueueOptions): Promise<MountedPaymentForm>;
+/** Wraps an adapter so every `mount` goes through the queue. The hook already does this for any adapter it uses. */
+declare function withMountQueue(adapter: PaymentFormAdapter, queue?: MountQueueOptions): PaymentFormAdapter;
+
+/**
+ * Browser transport to the shop's pay and status routes, with the retry policy a card payment needs.
+ *
+ * - A TRANSIENT failure (5xx, timeout, network, a proxy HTML page) is repeated up to `retries` times with the SAME
+ *   idempotency key (`request.idempotencyKey`): OPS then answers with the result of the first attempt. A payment whose
+ *   outcome is unknown is NEVER charged with another key.
+ * - If it is still unknown, the status route is read `statusPolls` times. A resolved answer (paid, failed, voucher,
+ *   challenge...) is returned; otherwise a network error is thrown and the hook keeps the SAME attempt (retry button
+ *   and background checks).
+ * - `retryable: false` (an answer from OPS) is ONE request: no repeat, no status read.
+ * - A body that is not JSON is treated as transient, never as a definitive error.
+ */
+
+/** What the screen is told while a payment is being repeated or checked, and when it ends with a problem. */
+type PaymentIssue = {
+    kind: 'confirming';
+    message: string;
+} | {
+    kind: 'verifying';
+    message: string;
+} | {
+    kind: PaymentErrorClassKind;
+    message: string;
+    retryable: boolean;
+    status: number;
+    code: string;
+};
+type ResilientTransportOptions = {
+    /** Same-origin route that charges the card (`handlers.pay`). */
+    payUrl: string;
+    /** Same-origin route that re-reads the payment (`handlers.status`). Enables the status checks and `refresh`. */
+    statusUrl: string;
+    /** Fields of the page form (delivery, contact, payment choice) that travel with the charge. */
+    fields: () => Record<string, string>;
+    /** Called with the state of the retry/verification and with the final problem; `null` clears it. */
+    onIssue?: (issue: PaymentIssue | null) => void;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** Automatic repeats after the first request. Default 2. */
+    retries?: number;
+    /** Wait before each repeat (ms); the last value repeats. Default `[800, 2000]`. */
+    backoffMs?: readonly number[];
+    /** Status reads before declaring the result "verifying". Default 3. */
+    statusPolls?: number;
+    /** Wait between status reads (ms). Default 2000. */
+    statusPollMs?: number;
+    /** Extra headers for both routes. */
+    headers?: Record<string, string>;
+    locale?: string;
+    messages?: Partial<PaymentRecoveryMessages>;
+};
+/** Has OPS decided? `pending` without an action, and `none`, are NOT decisions. */
+declare function isResolvedAttempt(result: PaymentAttemptResult): boolean;
+declare function createResilientTransport(opts: ResilientTransportOptions): PaymentTransport;
+
+type PaymentNotice = {
+    kind: PaymentNoticeKind;
+};
+/** Payment rows other than the in-page card: what the buyer can switch to. */
+declare function alternativeChoices(choices: readonly PayChoice[]): PayChoice[];
+/** Selects a payment row in the page form (the section's radios are the source of truth) and brings it into view. */
+declare function pickChoice(form: HTMLFormElement | null | undefined, value: string): void;
+type UsePaymentRecoveryOptions = {
+    /** Same `scope` as the payment section (usually the cart id): where the attempt key is kept. */
+    scope?: string;
+    /** Where the attempt key lives. Default `sessionStorage`; `null` = memory only. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** Automatic remounts of the secure form before showing the "form failed" notice. Default 2. */
+    formAutoRetries?: number;
+    /** The shop is closed (409 `store_not_ready`) or the like: re-read the page data. */
+    onRevalidate?: () => void;
+};
+type PaymentRecoveryState = {
+    notice: PaymentNotice | null;
+    setNotice: (notice: PaymentNotice | null) => void;
+    /** Use as `key` of `<PaymentMethodSection>`: a new value mounts a fresh section (and a fresh card form). */
+    sectionKey: number;
+    /** Pass to `createResilientTransport({ onIssue })`. */
+    onIssue: (issue: PaymentIssue | null) => void;
+    /** Pass to `<PaymentMethodSection onEvent>` (or compose it with your own handler). */
+    onEvent: (event: PaymentEvent) => void;
+    /** Last problem reported by the transport. */
+    lastIssue: {
+        current: PaymentIssue | null;
+    };
+    /**
+     * New attempt: a NEW idempotency key and a fresh form. Only after a definitive failure; returns `false` (and does
+     * nothing) while the outcome of the last charge is still unknown.
+     */
+    retry: () => boolean;
+    /** Clears the notice (e.g. after the buyer picked another way to pay). */
+    clear: () => void;
+};
+declare function usePaymentRecovery(options?: UsePaymentRecoveryOptions): PaymentRecoveryState;
+type PaymentRecoveryClassNames = Partial<Record<'root' | 'title' | 'body' | 'actions' | 'primary' | 'secondary', string>>;
+type PaymentRecoveryProps = {
+    notice: PaymentNotice | null;
+    /** Other ways to pay (`alternativeChoices(choices)`); they come from the published choices, never from this component. */
+    alternatives?: readonly PayChoice[];
+    /** "Retry payment": new key and fresh form (`usePaymentRecovery().retry`). */
+    onRetry: () => void;
+    /** A way to pay was picked. */
+    onPick: (choice: PayChoice) => void;
+    /** "Refresh my order": re-read the cart and checkout. */
+    onRefresh: () => void;
+    locale?: string;
+    messages?: Partial<PaymentRecoveryMessages>;
+    /** Text of the button of an alternative. Default: the `action.alternative` message with the row name. */
+    alternativeLabel?: (choice: PayChoice) => string;
+    classNames?: PaymentRecoveryClassNames;
+    testIds?: Partial<Record<'retry' | 'refresh', string>>;
+    /** Extra content after the buttons. */
+    children?: ReactNode;
+};
+/** Notice of a card payment that did not end well. `role="status"` while confirming, `role="alert"` (focused) otherwise. */
+declare function PaymentRecovery(props: PaymentRecoveryProps): react.JSX.Element | null;
+
+/**
+ * `shouldRevalidate` for the routes AROUND the checkout (root layout, header, cart badge...). The checkout page saves the
+ * chosen delivery with a `fetcher.submit` to its own route; by default a router then re-runs EVERY loader on the page
+ * (catalog, session, theme...), which is slow and makes the page jump while the buyer is paying. This keeps those loaders
+ * quiet for that submission and leaves everything else (their own forms, navigation) as the router decided.
+ *
+ * Do NOT use it on the checkout route itself: its loader must re-read the cart (the new total) after the submit.
+ * Framework-agnostic: it only reads the fields every router passes (`formMethod`, `formAction`, `defaultShouldRevalidate`).
+ */
+type RevalidateArgs = {
+    formMethod?: string | undefined;
+    formAction?: string | undefined;
+    defaultShouldRevalidate: boolean;
+};
+type CheckoutRevalidateOptions = {
+    /** Paths whose form submissions do not need the other loaders (e.g. `['/pagar']`). Matched on the pathname. */
+    paths: readonly string[];
+};
+declare function checkoutShouldRevalidate(options: CheckoutRevalidateOptions): (args: RevalidateArgs) => boolean;
+
 /** The `PaymentClient.kind` the addon `mercadopago` declares. */
 declare const MERCADOPAGO_BRICKS_KIND = "mercadopago_bricks";
 type MpController = {
     getFormData(): Promise<Record<string, unknown> | undefined | null>;
     unmount(): void | Promise<void>;
+    /** Card Payment Brick: changes the amount without recreating the form. Absent in old SDK builds. */
+    update?(settings: {
+        amount: number;
+    }): void | Promise<void>;
 };
 type MpBricks = {
     create(brick: string, containerId: string, settings: Record<string, unknown>): Promise<MpController>;
@@ -513,4 +714,4 @@ declare function readPaymentTheme(el: Element | null | undefined, tokens?: Recor
  */
 declare function readPaymentScheme(el: Element | null | undefined): 'light' | 'dark' | null;
 
-export { CASH_POINT_FIELD, type EmbeddedPaymentState, type EmbeddedPaymentStatus, type FetchTransportOptions, type LoadScriptOptions, MERCADOPAGO_BRICKS_KIND, type MercadoPagoAdapterOptions, type MercadoPagoCtor, type MountedPaymentForm, PAYMENT_CHOICE_FIELD, PAYMENT_THEME_TOKENS, PayChoices, PaymentBrick, type PaymentBrickHandle, type PaymentBrickProps, PaymentChallenge, type PaymentChallengeProps, type PaymentEvent, type PaymentFallbackReason, type PaymentFormAdapter, type PaymentFormData, type PaymentFormError, type PaymentFormMountOptions, PaymentHttpError, type PaymentMethodClassNames, type PaymentMethodMessages, PaymentMethodSection, type PaymentMethodSectionProps, type PaymentMethodTestIds, type PaymentSubmitRequest, type PaymentTransport, type UseEmbeddedPaymentOptions, VoucherCard, type VoucherCardProps, createFetchTransport, formFields, loadPaymentSdk, mercadoPagoBricksAdapter, paymentMethodMessages, readPaymentScheme, readPaymentTheme, resetPaymentSdkCache, sanitizeMercadoPagoFormData, useEmbeddedPayment };
+export { CASH_POINT_FIELD, type CheckoutRevalidateOptions, type EmbeddedPaymentState, type EmbeddedPaymentStatus, type FetchTransportOptions, type LoadScriptOptions, MERCADOPAGO_BRICKS_KIND, type MercadoPagoAdapterOptions, type MercadoPagoCtor, type MountQueueOptions, type MountedPaymentForm, PAYMENT_CHOICE_FIELD, PAYMENT_THEME_TOKENS, PayChoice, PayChoices, PaymentBrick, type PaymentBrickHandle, type PaymentBrickProps, PaymentChallenge, type PaymentChallengeProps, type PaymentEvent, type PaymentFallbackReason, type PaymentFormAdapter, type PaymentFormData, type PaymentFormError, type PaymentFormMountOptions, PaymentHttpError, type PaymentIssue, type PaymentMethodClassNames, type PaymentMethodMessages, PaymentMethodSection, type PaymentMethodSectionProps, type PaymentMethodTestIds, PaymentMountCancelled, PaymentMountTimeout, type PaymentNotice, PaymentNoticeKind, PaymentRecovery, type PaymentRecoveryClassNames, PaymentRecoveryMessages, type PaymentRecoveryProps, type PaymentRecoveryState, type PaymentSubmitRequest, type PaymentTransport, type ResilientTransportOptions, type RevalidateArgs, type UseEmbeddedPaymentOptions, type UsePaymentRecoveryOptions, VoucherCard, type VoucherCardProps, alternativeChoices, checkoutShouldRevalidate, createFetchTransport, createResilientTransport, formFields, isResolvedAttempt, loadPaymentSdk, mercadoPagoBricksAdapter, mountQueued, paymentMethodMessages, pickChoice, readPaymentScheme, readPaymentTheme, resetPaymentSdkCache, sanitizeMercadoPagoFormData, useEmbeddedPayment, usePaymentRecovery, withMountQueue };