tempest-react-sdk 0.83.0 → 0.84.0

package/dist/tempest-react-sdk.d.ts

@@ -3138,8 +3138,96 @@ export declare function capitalize(value: string): string;
  */
 export declare function Card({ title, actions, footer, flush, interactive, elevation, className, children, ...props }: CardProps): JSX.Element;
 
+/**
+ * PT-BR text for every `status_detail` Mercado Pago's Orders API documents.
+ *
+ * Ported from Mercado Pago's "Status da transação" table
+ * (`developers/pt/docs/checkout-api-orders/payment-management/status/transaction-status`,
+ * read on 2026-11-14), rewritten for the payer: the provider's descriptions are
+ * addressed to the integrator. `rejected_by_issuer` is the decline the backend
+ * pinned in the sandbox (holder `OTHE`, HTTP 402); the others come from the
+ * table. `high_risk` deliberately does not say "fraud" — telling the payer the
+ * anti-fraud system flagged them helps exactly the person it should not.
+ *
+ * A test pins every key, so a code dropped or renamed here fails instead of
+ * silently falling back to the generic text.
+ */
+export declare const CARD_STATUS_DETAIL_MESSAGES: Readonly<Record<string, string>>;
+
+/** A card charge — `CardCharge` in the backend. */
+export declare interface CardCharge {
+    /** Provider that owns the charge. */
+    provider: string;
+    /** The charge's id at the provider. */
+    provider_charge_id: string;
+    /** The service's own identifier. */
+    reference: string;
+    /** Amount charged, in cents. */
+    amount_cents: number;
+    /** How much went back to the payer, in cents. A partial refund keeps `status` at `paid`. */
+    refunded_cents: number;
+    /** ISO 4217 code. */
+    currency: string;
+    /**
+     * Canonical state. A declined card is `"failed"` — returned, not raised: the
+     * backend answers the decline as a charge, with the reason in `status_detail`.
+     */
+    status: PaymentStatus;
+    /** The provider's raw state. */
+    provider_status: string;
+    /** The provider's reason — `rejected_by_issuer`, `waiting_capture`, `accredited`. */
+    status_detail: string | null;
+    /** Card brand. */
+    payment_method_id: string | null;
+    /** Installments charged. */
+    installments: number | null;
+    /** Each installment, interest included, in cents. */
+    installment_amount_cents: number | null;
+    /** What the payer owes with interest, in cents. Not proof of payment — read `status`. */
+    payer_total_cents: number | null;
+    /** The provider's payload as decoded. */
+    raw?: Record<string, unknown>;
+}
+
+/**
+ * The body a service needs to charge a tokenized card — `CardChargeRequest` in
+ * the backend, minus nothing: `card_token`, `payment_method_id` and
+ * `installments` are exactly what {@link useMercadoPagoCard}'s `tokenize`
+ * returns, and the card number is never part of it.
+ */
+export declare interface CardChargeRequest {
+    /** The price in cents. With installments, still the price: the provider adds the interest. */
+    amount_cents: number;
+    /** The service's own identifier — also the create's idempotency key. */
+    reference: string;
+    /** Single-use token produced in the browser. */
+    card_token: string;
+    /** Card brand as the provider names it (`visa`, `master`, …). */
+    payment_method_id: string;
+    /** Installments the payer chose. Default `1` on the backend. */
+    installments?: number;
+    /** `false` only authorizes; the charge comes back `authorized`. Default `true`. */
+    capture?: boolean;
+    /** Free text, where the provider supports it. */
+    description?: string | null;
+    /** Who is paying. */
+    payer?: PaymentPayer | null;
+}
+
 export declare type CardElevation = "flat" | "default" | "raised" | "elevated";
 
+/** One installment choice, in the shape a `<Select>` needs. */
+export declare interface CardInstallmentOption {
+    /** Number of installments — the value to submit. */
+    installments: number;
+    /** The provider's own text, e.g. `"2 parcelas de R$ 54,82 (R$ 109,64)"`. Show it verbatim. */
+    recommendedMessage: string;
+    /** Each installment, interest included, in cents. */
+    installmentAmountCents: number;
+    /** What the payer owes in total, interest included, in cents. */
+    totalAmountCents: number;
+}
+
 export declare interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     title?: ReactNode;
     actions?: ReactNode;
@@ -3151,6 +3239,34 @@ export declare interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>,
     elevation?: CardElevation;
 }
 
+/** What the non-card part of the form supplies when tokenizing. */
+export declare interface CardTokenizeInput {
+    /** Name printed on the card. */
+    cardholderName: string;
+    /** Installments chosen from {@link UseMercadoPagoCardResult.installmentOptions}. */
+    installments: number;
+    /** Document type (`"CPF"`, `"CNPJ"`). */
+    identificationType?: string;
+    /** Document number, digits only. */
+    identificationNumber?: string;
+}
+
+/**
+ * Everything the backend needs to charge the card — and nothing more.
+ *
+ * Maps onto the backend's `CardChargeRequest` as `card_token: token` plus the
+ * other two fields unchanged. No card number, expiry or CVV: those never left
+ * Mercado Pago's iframes.
+ */
+export declare interface CardTokenResult {
+    /** Single-use card token. */
+    token: string;
+    /** Card brand as Mercado Pago names it (`visa`, `master`, …). */
+    payment_method_id: string;
+    /** Installments chosen. */
+    installments: number;
+}
+
 /**
  * Horizontal content slider showing one slide at a time.
  *
@@ -4933,6 +5049,10 @@ export declare function createLinkStatsSampler(options?: LinkStatsSamplerOptions
  * `clear()` forgets every record under the prefix. Call it from
  * `onSessionEnd`: a record outlives the session that wrote it, and only
  * completing the upload or `abort({ discard: true })` removes it otherwise.
+ * It also ends every handle built over a storage with the same prefix: a run
+ * in flight stops with {@link ResumableUploadSupersededError} (`"cleared"`),
+ * and a paused one's next `resume()` starts a new upload with a fresh
+ * `Idempotency-Key` (since 0.84.0, #528).
  *
  * @param prefix - Key prefix. Default `"tempest-upload:"`.
  * @returns A storage that no-ops when `localStorage` is unavailable.
@@ -7255,6 +7375,35 @@ export declare interface DescribeApiErrorOptions extends Partial<ApiErrorStrings
  */
 export declare function describeAppError(error: unknown, context?: Record<string, unknown>): AppErrorDescription;
 
+/**
+ * Turn a card charge from the backend into what the payer should read.
+ *
+ * The **status** decides the outcome; `status_detail` only refines the sentence.
+ * That ordering is the point: `waiting_capture` arrives as `authorized` and
+ * reads as "reserved, not charged", never as paid, and a detail this table does
+ * not know falls back to the status's generic text instead of guessing. A
+ * decline reason only refines a `failed` charge, and a pending reason only a
+ * charge that is not `failed`, so a detail that contradicts its status cannot
+ * put "recusado" and "reservado" on the same screen.
+ *
+ * A decline is data here, not an exception. The backend returns a declined card
+ * as a `CardCharge` with `status: "failed"` — Mercado Pago answers it with HTTP
+ * 402 and the backend reads that as a result — so the checkout renders the
+ * reason the same way it renders an approval. If your own endpoint chooses to
+ * answer a decline with a non-2xx status, parse its body and pass it here; do
+ * not show it as a network error, because it is not one.
+ *
+ * @param charge - The charge, or just its `status` and `status_detail`.
+ * @param messages - Overrides per `status_detail`, merged over
+ *   {@link CARD_STATUS_DETAIL_MESSAGES} — for another language or tone.
+ * @returns Tone, title, message and whether the payer can retry.
+ *
+ * @example
+ * const outcome = describeCardCharge(charge);
+ * <Alert variant={outcome.tone} title={outcome.title} description={outcome.message} />
+ */
+export declare function describeCardCharge(charge: Pick<CardCharge, "status" | "status_detail">, messages?: Readonly<Record<string, string>>): PaymentOutcome;
+
 /**
  * One filter, in words: `"Status é Pago"`.
  *
@@ -8666,6 +8815,21 @@ export declare interface FormatPhoneOptions {
     mobile?: boolean;
 }
 
+/**
+ * `mm:ss` under an hour, `h:mm:ss` above — a Pix can live for 24 h.
+ *
+ * The default countdown format of `PixCheckout`, exported so an app that
+ * renders its own Pix screen shows the same clock.
+ *
+ * @param ms - Milliseconds left. Rounded up, so the last second reads `00:01`.
+ * @returns The formatted remaining time.
+ *
+ * @example
+ * formatPixRemaining(65_000); // "01:05"
+ * formatPixRemaining(3_725_000); // "1:02:05"
+ */
+export declare function formatPixRemaining(ms: number): string;
+
 export declare function FormField<TValues extends FieldValues = FieldValues, TName extends FieldPath<TValues> = FieldPath<TValues>>({ name, label, helperText, required, control, children }: FormFieldProps<TValues, TName>): JSX.Element;
 
 export declare interface FormFieldChildProps {
@@ -9944,6 +10108,23 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/**
+ * Whether a checkout has nothing left to wait for.
+ *
+ * `paid`, `expired`, `cancelled`, `refunded`, `charged_back` and `failed` end the
+ * flow the payer is looking at, so a status poll stops there. `pending`,
+ * `authorized`, `in_analysis` and `unknown` do not: each is a state the backend
+ * will still move. `paid` can later become `refunded`, but that is no longer
+ * something the checkout screen waits for.
+ *
+ * @param status - The charge's canonical state.
+ * @returns `true` when following the charge further is pointless.
+ *
+ * @example
+ * if (isFinalPaymentStatus(charge.status)) stopPolling();
+ */
+export declare function isFinalPaymentStatus(status: PaymentStatus): boolean;
+
 /**
  * Whether this environment can present anything fullscreen at all.
  *
@@ -10807,6 +10988,33 @@ export { LoaderFunction }
 
 export { LoaderFunctionArgs }
 
+/**
+ * Load MercadoPago.js once per document and resolve its constructor.
+ *
+ * Concurrent and repeated calls share one `<script>` tag and one promise, so a
+ * checkout that remounts never injects the script twice. A failed load is
+ * forgotten instead of cached — the next call tries again, which is what a
+ * payer on a flaky connection needs — and the dead tag is removed.
+ *
+ * @param options - Script URL and target document.
+ * @returns The `MercadoPago` constructor.
+ * @throws {Error} When the script fails to load, or loads without defining
+ *   `window.MercadoPago`.
+ *
+ * @example
+ * const MercadoPago = await loadMercadoPago();
+ * const mp = new MercadoPago(import.meta.env.VITE_MP_PUBLIC_KEY, { locale: "pt-BR" });
+ */
+export declare function loadMercadoPago(options?: LoadMercadoPagoOptions): Promise<MercadoPagoConstructor>;
+
+/** Options for {@link loadMercadoPago}. */
+export declare interface LoadMercadoPagoOptions {
+    /** Script URL. Default {@link MERCADO_PAGO_SCRIPT_URL}; override only for a proxy you control. */
+    src?: string;
+    /** Document to inject into. Default the global `document`. */
+    document?: Document;
+}
+
 export declare type LocalStorageOptions<T> = {
     serialize?: (value: T) => string;
     deserialize?: (raw: string) => T;
@@ -11306,6 +11514,107 @@ export declare interface MenubarProps extends HTMLAttributes<HTMLDivElement> {
     portal?: boolean;
 }
 
+/**
+ * The official MercadoPago.js v2 script.
+ *
+ * Loaded from Mercado Pago's own host, never bundled or vendored: the PCI DSS
+ * self-assessment that keeps a merchant in the lightest scope (SAQ A) requires
+ * the card fields to come straight from the processor, and Mercado Pago ships
+ * the script unversioned so fixes reach every merchant without a rebuild. It is
+ * also why this is not an npm dependency — there is no package to pin.
+ *
+ * A Content-Security-Policy needs `script-src https://sdk.mercadopago.com` and,
+ * for the Secure Fields iframes and the API calls the script makes,
+ * `frame-src https://secure-fields.mercadopago.com https://api-static.mercadopago.com`
+ * plus `connect-src https://api.mercadopago.com https://api.mercadolibre.com`
+ * (hosts read from the script itself, `js_version` 2.83.6, on 2026-11-14).
+ */
+export declare const MERCADO_PAGO_SCRIPT_URL = "https://sdk.mercadopago.com/js/v2";
+
+/** Element ids the three Secure Fields mount into. */
+export declare interface MercadoPagoCardContainers {
+    cardNumber: string;
+    expirationDate: string;
+    securityCode: string;
+}
+
+/** Lifecycle of the Secure Fields. */
+export declare type MercadoPagoCardStatus = "loading" | "ready" | "error";
+
+/** Non-card data the token is bound to. */
+export declare interface MercadoPagoCardTokenData {
+    cardholderName: string;
+    identificationType?: string;
+    identificationNumber?: string;
+}
+
+/** The `MercadoPago` global the script defines. */
+export declare type MercadoPagoConstructor = new (publicKey: string, options?: {
+    locale?: string;
+}) => MercadoPagoLike;
+
+/** One mounted Secure Field — the subset of MercadoPago.js this module calls. */
+export declare interface MercadoPagoFieldLike {
+    /** Mounts the iframe into the element with this id. */
+    mount(containerId: string): unknown;
+    /** Removes the iframe. */
+    unmount(): unknown;
+    /** Subscribes to a field event (`binChange`, `validityChange`, `error`, …). */
+    on(event: string, listener: (payload: unknown) => void): unknown;
+}
+
+/** Options for one Secure Field, as MercadoPago.js accepts them. */
+export declare interface MercadoPagoFieldOptions {
+    /** Placeholder shown inside the iframe. */
+    placeholder?: string;
+    /** Inline style applied inside the iframe (font, colour, size). */
+    style?: Record<string, string>;
+}
+
+/** The Secure Fields this module mounts. */
+export declare type MercadoPagoFieldType = "cardNumber" | "expirationDate" | "securityCode";
+
+/** One entry of the `getInstallments` answer. */
+export declare interface MercadoPagoInstallmentsEntry {
+    payment_method_id: string;
+    payment_type_id?: string;
+    issuer?: {
+        id?: string | number | null;
+    } | null;
+    payer_costs: MercadoPagoPayerCost[];
+}
+
+/**
+ * The subset of a `new MercadoPago(publicKey)` instance this module calls.
+ *
+ * Declared here instead of depending on `@mercadopago/sdk-js`, matching how the
+ * SDK treats every injected provider: tests pass a fake with this shape, and an
+ * app never pays for typings it does not use.
+ */
+export declare interface MercadoPagoLike {
+    fields: {
+        create(type: MercadoPagoFieldType, options?: MercadoPagoFieldOptions): MercadoPagoFieldLike;
+        createCardToken(data: MercadoPagoCardTokenData): Promise<{
+            id: string;
+        }>;
+    };
+    getInstallments(params: {
+        amount: string;
+        bin: string;
+        paymentTypeId?: string;
+    }): Promise<MercadoPagoInstallmentsEntry[]>;
+}
+
+/** One installment option, as `getInstallments` returns it. */
+export declare interface MercadoPagoPayerCost {
+    installments: number;
+    installment_rate: number;
+    installment_amount: number;
+    total_amount: number;
+    /** Ready-made text, e.g. `"2 parcelas de R$ 54,82 (R$ 109,64)"`. */
+    recommended_message: string;
+}
+
 /**
  * A point projected onto the unit Web Mercator plane. Both axes are in `[0, 1]`
  * — `x` grows east, `y` grows south (screen convention).
@@ -12225,9 +12534,9 @@ export declare interface OfflineQueryPersistenceOptions {
     /**
      * Who is signed in right now — a stable, non-secret id such as the user id;
      * `null`/`undefined` when nobody is. Read on every write, which stamps the
-     * snapshot with a one-way fingerprint of it (never the id itself), and on
+     * snapshot with a one-way fingerprint of it (never the id itself), on
      * `restore()`, which hydrates only a snapshot stamped with the same
-     * fingerprint.
+     * fingerprint, and on cache changes until the handle is bound.
      *
      * `clear()` on logout already deletes the snapshot; this covers the session
      * that ends without it — a token that expired, a crash, a tab closed while
@@ -12240,11 +12549,14 @@ export declare interface OfflineQueryPersistenceOptions {
      * the principal after a `/me` round trip would otherwise wipe its own cache
      * on every cold start. The next write replaces it.
      *
-     * The handle is bound to the first signed-in owner it writes or restores.
-     * Once bound, a write under another owner — nobody, because the token
-     * expired without `clear()`, or a second account on the same tab — deletes
-     * the snapshot instead of stamping the bound owner's cached responses with
-     * the new owner (#563); the same owner coming back writes again. Writes
+     * The handle is bound to the first signed-in owner it sees on a cache
+     * change, a write or a restore — the cache change is what pins the owner of
+     * data that a throttled write would otherwise stamp with whoever is signed
+     * in a second later (#580). Once bound, a write under another owner —
+     * nobody, because the token expired without `clear()`, or a second account
+     * on the same tab — deletes the snapshot instead of stamping the bound
+     * owner's cached responses with the new owner (#563); the same owner coming
+     * back writes again. Writes
      * before anyone signs in stay anonymous and are restored while nobody is,
      * so an app that persists logged-out data keeps doing so. An anonymous
      * snapshot written by 0.82.0 is not restored (it may hold an expired
@@ -13213,6 +13525,57 @@ export { PathMatch }
 
 export { PathPattern }
 
+/** What a card charge means to the payer, ready to render. */
+export declare interface PaymentOutcome {
+    /** The canonical state the outcome was derived from. */
+    status: PaymentStatus;
+    /** Tone for the surrounding `Alert`/`Badge`. */
+    tone: PaymentOutcomeTone;
+    /** Short headline. */
+    title: string;
+    /** One sentence telling the payer what happened and what to do. */
+    message: string;
+    /** Whether the payer can fix it from the checkout (another card, other data). */
+    canRetry: boolean;
+}
+
+/** Visual tone of an outcome, matching `Alert`'s variants. */
+export declare type PaymentOutcomeTone = "success" | "info" | "warning" | "danger" | "neutral";
+
+/** Who is paying — `PixPayer` in the backend, shared by Pix and card requests. */
+export declare interface PaymentPayer {
+    /** Full name. */
+    name?: string | null;
+    /** CPF or CNPJ, digits or formatted. */
+    tax_id?: string | null;
+    /** E-mail. Mercado Pago requires it on a card charge (`payer.email`). */
+    email?: string | null;
+    /** Phone number. */
+    phone?: string | null;
+}
+
+/**
+ * The payment contract as the `tempest-fastapi-sdk` backend serialises it.
+ *
+ * Every shape here is the JSON a service built on that SDK answers with — the
+ * Pydantic schemas in `tempest_fastapi_sdk/integrations/payment/base.py`, dumped
+ * with `model_dump(mode="json")`. The field names stay in snake_case because
+ * `BaseSchema` declares no alias generator, so that is what crosses the wire;
+ * renaming them here would make every app write a mapper that can drift.
+ *
+ * Datetimes arrive as ISO 8601 strings and money as integer cents, never as a
+ * float: the backend refuses floats for money on purpose, and so does this side.
+ */
+/**
+ * The canonical state of a charge — `PaymentStatusEnum` in the backend.
+ *
+ * `"unknown"` is a real state, not a fallback: the backend uses it for a
+ * provider state its version does not classify, keeping the provider's own
+ * string in `provider_status`. A screen should show it as "we are checking",
+ * never as paid or failed.
+ */
+export declare type PaymentStatus = "pending" | "authorized" | "paid" | "expired" | "cancelled" | "refunded" | "charged_back" | "in_analysis" | "failed" | "unknown";
+
 /** Raw PCM ready to be wrapped in a RIFF container. */
 export declare interface PcmAudio {
     /** One `Float32Array` per channel, samples in −1…1. */
@@ -13512,6 +13875,100 @@ export declare type PinInputSize = "sm" | "md" | "lg";
 
 export declare type PinInputType = "numeric" | "alphanumeric";
 
+/** A Pix charge — `PixCharge` in the backend. */
+export declare interface PixCharge {
+    /** Provider that owns the charge (`"mercado_pago"`, `"openpix"`, …). */
+    provider: string;
+    /** The charge's id at the provider. */
+    provider_charge_id: string;
+    /** The service's own identifier for the charge. */
+    reference: string;
+    /** Amount in cents. */
+    amount_cents: number;
+    /** ISO 4217 code; `"BRL"` for Pix. */
+    currency: string;
+    /** Canonical state — the only field a screen branches on. */
+    status: PaymentStatus;
+    /** The provider's raw state, for support and logs. */
+    provider_status: string;
+    /** EMV copia-e-cola string. */
+    br_code: string | null;
+    /** QR as a Base64 PNG, without the `data:` prefix (Mercado Pago fills it). */
+    qr_code_base64: string | null;
+    /** QR as a URL (OpenPix fills it instead of the Base64). */
+    qr_code_image_url: string | null;
+    /** Pix end-to-end id, once the provider reports one. */
+    end_to_end_id: string | null;
+    /** When the charge stops being payable, ISO 8601. */
+    expires_at: string | null;
+    /** When it settled, ISO 8601. */
+    paid_at: string | null;
+    /** The provider's payload as decoded. A screen should not read it. */
+    raw?: Record<string, unknown>;
+}
+
+/**
+ * The payer's Pix screen: amount, QR, copia-e-cola, countdown and the state the
+ * backend reports.
+ *
+ * Presentational and controlled. It renders `charge` and never changes it, so
+ * the decision that a Pix was paid stays where it can be made — on the backend,
+ * re-reading the order. Feed it from {@link usePixCharge} or from your own
+ * stream.
+ *
+ * The QR comes from `qr_code_base64` when the provider sent one (Mercado Pago),
+ * and is otherwise drawn locally from `br_code` (OpenPix sends a URL instead,
+ * and fetching it would hand the payload to an image host for nothing). The
+ * copia-e-cola line is always next to it: a QR cannot be scanned by the phone
+ * that is showing it, which is where a mobile checkout puts it.
+ *
+ * When the countdown reaches zero while the backend still says `pending`, the
+ * screen hides the QR and says it is **confirming** — not "expired". A payment
+ * sent in the last second can still settle, and only the backend knows.
+ *
+ * @example
+ * const { charge } = usePixCharge(created, { refresh: (signal) => readCharge(created.provider_charge_id, signal) });
+ * <PixCheckout charge={charge} />
+ */
+export declare function PixCheckout({ charge, qrSize, labels, formatRemaining, onCopied, footer, className, ...rest }: PixCheckoutProps): JSX.Element;
+
+/** Strings the screen renders, so an app can translate them. */
+export declare interface PixCheckoutLabels {
+    /** Accessible name of the QR. */
+    qr: string;
+    /** Heading over the copia-e-cola line. */
+    copyHint: string;
+    /** Copy button, idle. */
+    copy: string;
+    /** Copy button, just clicked. */
+    copied: string;
+    /** Prefix of the countdown, e.g. "Expira em". */
+    expiresIn: string;
+    /** Shown when the deadline passed but the backend has not said "expired" yet. */
+    confirming: string;
+    /** Title and description per terminal or waiting state. */
+    states: Record<PaymentStatus, {
+        title: string;
+        description: string;
+    }>;
+}
+
+export declare interface PixCheckoutProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The charge as the backend reports it — pair with {@link usePixCharge} to follow it. */
+    charge: PixCharge;
+    /** Rendered side of the QR in px. Default `220`. */
+    qrSize?: number;
+    labels?: Partial<Omit<PixCheckoutLabels, "states">> & {
+        states?: Partial<PixCheckoutLabels["states"]>;
+    };
+    /** Formats the countdown. Default {@link formatPixRemaining}. */
+    formatRemaining?: (ms: number) => string;
+    /** Called after the copia-e-cola reaches the clipboard. */
+    onCopied?: () => void;
+    /** Rendered under the status, e.g. a "gerar novo Pix" button for a final state. */
+    footer?: ReactNode;
+}
+
 /** A pixel coordinate inside the plotting viewport. */
 export declare interface PixelPoint {
     x: number;
@@ -14911,8 +15368,11 @@ export declare interface ResumableUploadOptions {
      * It is read again before every chunk and every record write: when it
      * names someone else mid-run, the run stops with
      * {@link ResumableUploadSupersededError} (`"principal"`) before the new
-     * account's token reaches the previous one's upload URL. Without it, call
-     * `abort()` on the uploads in progress from `onSessionEnd`.
+     * account's token reaches the previous one's upload URL. Without it,
+     * `createLocalUploadStorage().clear()` from `onSessionEnd` stops the runs in
+     * flight and, since 0.84.0, makes a paused handle start over with a fresh
+     * `Idempotency-Key`; with a custom `storage`, call `abort()` on the uploads
+     * in progress there instead.
      */
     getPrincipal?: () => string | number | null | undefined;
     /**
@@ -17356,10 +17816,45 @@ export declare interface TempestAuth<TUser, TCredentials> {
     /**
      * Refresh the access token (deduplicated across concurrent callers).
      *
+     * When both the access token held and the one redeemed are JWTs with a
+     * `sub` claim and the subjects differ, the redeemed credential — a refresh
+     * cookie another sign-in replaced — belongs to another account. That is
+     * an account switch, not a rotation: the held session ends with
+     * `onSessionEnd` `"switch"`, the new one gets a lineage of its own and its
+     * user is loaded, exactly as `login()` would; `refresh()` resolves with it
+     * installed, and a `401` replay of the previous account's request rejects
+     * with {@link SessionSupersededError} instead of going out as the new one
+     * (#579). With opaque tokens there is no subject to compare, and the
+     * redemption counts as a rotation — call `restore()` where a sign-in may
+     * have happened outside `login()`.
+     *
      * @throws {SessionSupersededError} When the session ended or changed while
      *   the refresh was in flight; its tokens were discarded.
      */
     refresh: () => Promise<void>;
+    /**
+     * Redeem the refresh credential as a **new sign-in**: whatever it signs in
+     * replaces the session installed now, like `login()` with no credentials.
+     *
+     * For the point where the app knows a sign-in happened outside `login()`
+     * — the OAuth or magic-link callback that set the refresh cookie. The
+     * session held, if any, ends with `onSessionEnd` `"switch"` only once the
+     * redemption succeeded, the new one gets a lineage of its own, and the
+     * user is loaded (`parseUser`, then `mePath`). A failed redemption leaves
+     * the held session untouched.
+     *
+     * `refresh()` cannot make that call on its own when tokens are opaque: a
+     * rotation of the same account and another account's cookie look alike,
+     * and comparing `mePath` users would cost a request per rotation and
+     * reopen #544. So the boot keeps `refresh()` — a reload must not end the
+     * session — and the callback uses this. Called where no sign-in happened,
+     * it costs a needless switch: an upload bound to the session starts over.
+     *
+     * @returns The user of the new session, or null.
+     * @throws {SessionSupersededError} When a `logout()` or `login()` moved
+     *   the session while it was in flight; the new tokens are discarded.
+     */
+    restore: () => Promise<TUser | null>;
     /** The current access token, or null. */
     getToken: () => string | null;
     /**
@@ -17382,6 +17877,11 @@ export declare interface TempestAuth<TUser, TCredentials> {
      * answered one constant for every account, and an upload bound by
      * `getToken: auth.getToken` was resumed by the next account restored the
      * same way.
+     *
+     * A `refresh()` that redeems another account while a session is installed
+     * changes the key too, when JWT subjects tell the accounts apart; with
+     * opaque tokens `restore()` is the call that does (#579). Until 0.83.0 such
+     * a redemption kept the previous account's key.
      */
     sessionKey: () => string | null;
     /**
@@ -18517,8 +19017,9 @@ export declare interface UploadProgressEvent {
  *
  * An `XMLHttpRequest` cannot refuse a redirect; see
  * {@link UploadWithProgressOptions.redirect} for what follows one, what the
- * helper still refuses, and the `fetch` path that trades progress for never
- * following.
+ * helper still refuses, the `fetch` path that trades progress for never
+ * following, and when that path is the default (fixed headers and no
+ * `onProgress`, since 0.84.0).
  *
  * @returns The parsed JSON response, or the raw text when the response is not JSON.
  */
@@ -18574,30 +19075,41 @@ export declare interface UploadWithProgressOptions {
      */
     requestId?: () => string;
     /**
-     * What to do when the server answers with a redirect. Default `"follow"`.
+     * What to do when the server answers with a redirect. When unset, the
+     * helper picks: `"error"` when {@link headers} carry anything besides the
+     * headers it exempts (`Authorization`, `X-Request-ID`, `Content-Type` and
+     * `X-CSRF-Token`) **and** no {@link onProgress} was given, `"follow"`
+     * otherwise (since 0.84.0). A value passed here always wins.
      *
      * - `"follow"` — the `XMLHttpRequest` path, with byte-level progress. The
      *   browser follows every redirect and offers no way to stop it: measured
-     *   in Chrome 150 (#570), a same-origin upload answered `301`/`302`/`303`/
-     *   `307`/`308` towards another origin delivered `X-Api-Key` from
-     *   {@link headers} and the SDK's own `X-CSRF-Token` there on all five, and
-     *   the body on `307`/`308`; only `Authorization` was stripped. What this
-     *   path does enforce (since 0.83.0): an answer from another origin than
-     *   the one the request was sent to is never the result — it rejects with
+     *   in Chrome 150, and again in Chromium 153, Firefox 155 and WebKit 26.6
+     *   (#570), a same-origin upload answered `301`/`302`/`303`/`307`/`308`
+     *   towards another origin delivered `X-Api-Key` from {@link headers} and
+     *   the SDK's own `X-CSRF-Token` there on all five, and the body on
+     *   `307`/`308`; only `Authorization` was stripped. What this path does
+     *   enforce (since 0.83.0): an answer from another origin than the one the
+     *   request was sent to is never the result — it rejects with
      *   `code: "REDIRECT_REFUSED"`, so that host cannot hand the app a URL to
      *   store. Until 0.82.0 it resolved with the other host's body.
      * - `"error"` — goes out over `fetch` with `redirect: "manual"`, and a
      *   redirect rejects with `code: "REDIRECT_REFUSED"` before anything is
      *   sent to the other host. The cost: `fetch` reports no upload progress,
-     *   so `onProgress` fires once, when the server confirms the whole body. A
+     *   so `onProgress` fires once, when the server confirms the whole body,
+     *   and a same-origin redirect (FastAPI's trailing-slash `307`) is refused
+     *   too — a browser hands it back opaque, with no readable `Location`. A
      *   streamed `fetch` body would report progress, but Chrome refuses one
      *   over HTTP/1.1 (`TypeError: Failed to fetch`, measured) and Firefox and
      *   Safari do not support it.
      *
-     * Use `"error"` when {@link headers} carry a credential (an `X-Api-Key`) and
-     * the server behind `url` could redirect; sending the bearer through
-     * {@link getToken} keeps `"follow"` safe for it, because the browser strips
-     * `Authorization` on a cross-origin redirect.
+     * Why the default depends on `onProgress`: progress is the only thing the
+     * XHR path buys, and the leak is its price. A caller that asked for no
+     * progress paid that price for nothing, so its fixed headers get the
+     * treatment `createApiClient` (#560) and `createResumableUpload` (#568)
+     * give theirs. A caller that wants progress keeps it, and the guarantee is
+     * one `redirect: "error"` away. Sending the bearer through
+     * {@link getToken} keeps `"follow"` safe for it, because the browser
+     * strips `Authorization` on a cross-origin redirect.
      */
     redirect?: "follow" | "error";
 }
@@ -20030,6 +20542,95 @@ export declare interface UseMediaPermissionResult {
  */
 export declare function useMediaQuery(query: string): boolean;
 
+/**
+ * Card tokenization with MercadoPago.js **Secure Fields**, plus installments by BIN.
+ *
+ * The card number, expiry and CVV are typed into iframes served by Mercado Pago,
+ * so they never exist in this page's DOM, in React state, in a callback argument
+ * or in a log line — not even transiently. That is the property the PCI DSS
+ * scoping depends on: a page that renders its own `<input>` for the number and
+ * calls `createCardToken` with it has handled cardholder data and is in the
+ * heavier SAQ A-EP scope, however quickly it discards the value. The backend
+ * never sees the card either: it receives the token, the brand and the
+ * installments, which is exactly `CardChargeRequest`.
+ *
+ * The only digits the hook learns are the BIN (first 6–8), which Mercado Pago's
+ * `binChange` event exposes precisely so the page can quote installments; it is
+ * used for the lookup and not returned. Installment options come from the
+ * provider with its own `recommended_message`, because interest starts at 2x
+ * (measured in the sandbox) and the total the payer sees has to be the
+ * provider's number, not one recomputed here.
+ *
+ * The containers must be in the DOM when the hook's effect runs — render the
+ * three empty elements in the same component. The fields are created once per
+ * `publicKey`; changing the containers, locale or loader afterwards does not
+ * remount them.
+ *
+ * @tempest-limits empty-catch — `unmount()` throws when MercadoPago.js already
+ * tore the iframe down (a container removed by React first). The cleanup has
+ * nothing left to undo in that case and nowhere useful to report it.
+ *
+ * @param options - Public key, amount, container ids and an injectable loader.
+ * @returns Field status, brand, installment options and `tokenize`.
+ *
+ * @example
+ * const card = useMercadoPagoCard({
+ *   publicKey: import.meta.env.VITE_MP_PUBLIC_KEY,
+ *   amountCents: 10964,
+ *   containers: { cardNumber: "mp-number", expirationDate: "mp-expiry", securityCode: "mp-cvv" },
+ * });
+ * const { token, payment_method_id, installments } = await card.tokenize({
+ *   cardholderName: "APRO",
+ *   installments: 1,
+ *   identificationType: "CPF",
+ *   identificationNumber: "12345678909",
+ * });
+ */
+export declare function useMercadoPagoCard(options: UseMercadoPagoCardOptions): UseMercadoPagoCardResult;
+
+/** Options for {@link useMercadoPagoCard}. */
+export declare interface UseMercadoPagoCardOptions {
+    /**
+     * The application's **Public Key** — never the access token. It is meant to
+     * be public: it can only tokenize, and the token is useless without the
+     * access token that stays on the backend.
+     */
+    publicKey: string;
+    /** The price in cents, used to quote installments. */
+    amountCents: number;
+    /** Ids of the empty elements the card number, expiry and CVV iframes mount into. */
+    containers: MercadoPagoCardContainers;
+    /** MercadoPago.js locale. Default `"pt-BR"`. */
+    locale?: string;
+    /** Per-field options (placeholder, inline style). */
+    fieldOptions?: Partial<Record<MercadoPagoFieldType, MercadoPagoFieldOptions>>;
+    /** Loads the constructor. Default {@link loadMercadoPago}; tests pass a fake. */
+    load?: () => Promise<MercadoPagoConstructor>;
+}
+
+/** Return value of {@link useMercadoPagoCard}. */
+export declare interface UseMercadoPagoCardResult {
+    /** `"ready"` once all three fields are mounted. */
+    status: MercadoPagoCardStatus;
+    /** Why loading or mounting failed. */
+    error: Error | null;
+    /** Brand detected from the BIN, or `null` until the payer types enough digits. */
+    paymentMethodId: string | null;
+    /** Installment choices for the current BIN and amount; empty until known. */
+    installmentOptions: CardInstallmentOption[];
+    /** `true` while the installments for a new BIN are being fetched. */
+    installmentsLoading: boolean;
+    /** Why the installment lookup failed, if it did. */
+    installmentsError: Error | null;
+    /**
+     * Ask Mercado Pago for a card token. Throws when the fields are not ready,
+     * the BIN has not been identified, or `installments` is not one of the
+     * offered options — each of which would otherwise surface later as an
+     * opaque `400` from the backend.
+     */
+    tokenize: (input: CardTokenizeInput) => Promise<CardTokenResult>;
+}
+
 /**
  * Acquire a microphone `MediaStream`, classified errors included, and release it
  * properly.
@@ -20663,6 +21264,59 @@ export declare interface UsePasskeySignInResult<TResult> extends PasskeyCapabili
     reset: () => void;
 }
 
+/**
+ * Follow a Pix charge until the backend says it is final.
+ *
+ * The browser never decides that a Pix was paid: there is no client-side signal
+ * that could prove it, and a screen that infers "paid" from a countdown or a
+ * copy click is a screen that ships goods for free. This hook only relays what
+ * the app's `refresh`/`subscribe` report, and stops polling once the status is
+ * final (`paid`, `expired`, `cancelled`, `refunded`, `charged_back`, `failed`).
+ *
+ * Polling is sequential — the next request starts `intervalMs` after the
+ * previous one settled — so a slow backend is never hit by overlapping reads.
+ * A failed read keeps the last good charge and is exposed as `error`; the poll
+ * goes on, because a dropped request is not a payment state.
+ *
+ * Passing a charge with a different `provider_charge_id` restarts the follow.
+ *
+ * @param initial - The charge as created.
+ * @param options - `refresh`, `subscribe` and the poll period.
+ * @returns The latest charge and the last read error.
+ *
+ * @example
+ * const { charge } = usePixCharge(created, {
+ *   refresh: (signal) => api.get<PixCharge>(`/api/pix/${created.provider_charge_id}`, { signal }),
+ * });
+ * return <PixCheckout charge={charge} />;
+ */
+export declare function usePixCharge(initial: PixCharge, options?: UsePixChargeOptions): UsePixChargeResult;
+
+/** Options for {@link usePixCharge}. */
+export declare interface UsePixChargeOptions {
+    /**
+     * Re-reads the charge from **your backend** — which re-reads it from the
+     * provider. Called every `intervalMs` until the charge is final. The signal
+     * aborts when the component unmounts or the charge changes.
+     */
+    refresh?: (signal: AbortSignal) => Promise<PixCharge>;
+    /**
+     * Pushes updates instead of polling — an SSE stream, a WebSocket. Receives
+     * the emitter and returns its own cleanup. Can be combined with `refresh`.
+     */
+    subscribe?: (emit: (charge: PixCharge) => void) => () => void;
+    /** Poll period in ms. Default `5000`. */
+    intervalMs?: number;
+}
+
+/** Return value of {@link usePixCharge}. */
+export declare interface UsePixChargeResult {
+    /** The latest charge the backend reported. */
+    charge: PixCharge;
+    /** The last `refresh` failure, cleared by the next success. Polling continues after it. */
+    error: Error | null;
+}
+
 /**
  * Poll an async factory on a fixed interval. Skips overlapping requests if a
  * prior call has not finished. Pause via `disabled` or `stopWhen`.