tempest-react-sdk 0.83.0 → 0.85.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.
@@ -5605,8 +5725,10 @@ export declare interface CreateStorePersistOptions<T> {
  * mints and every rotation keeps — not by comparing users, which took two
  * sign-ins whose user had not loaded yet for the same account (#544). Two tabs
  * never redeem the same refresh token at once: the redemption runs under an
- * origin-wide Web Lock when the browser has one. `storage: "session"` is per
- * tab and behaves as before.
+ * origin-wide Web Lock when the browser has one, and a redemption installed as
+ * a sign-in — `restore()`, an account switch — holds a second one until it is
+ * installed, so no tab presents the token it spent meanwhile (#594).
+ * `storage: "session"` is per tab and behaves as before.
  *
  * Refreshes are collapsed per rotation, not just per overlap: a `401` whose
  * request left with a token that has since been replaced in the same session
@@ -7255,6 +7377,38 @@ 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 — and
+ * "know" means an own key of the table, so a status or detail named after an
+ * `Object.prototype` member (`toString`, `constructor`, `__proto__`) reads as
+ * `unknown` / unknown detail instead of a half-empty outcome. 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 +8820,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 +10113,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 +10993,44 @@ 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.
+ *
+ * Trust: an existing `window.MercadoPago` is used as is, and `src` is not
+ * checked. Neither is a boundary the page can enforce — whoever can define that
+ * global already runs script here, and an unversioned script has no integrity
+ * hash to pin — so the control is the page's CSP `script-src`, restricted to
+ * `https://sdk.mercadopago.com` or the proxy `src` points at.
+ *
+ * @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 that serves the **identical** MercadoPago.js — SAQ A
+     * depends on the fields coming from the processor unaltered. Not checked:
+     * the script is unversioned, so there is no stable integrity hash to pin.
+     */
+    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 +11530,123 @@ 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";
+
+/**
+ * What `fields.createCardToken` resolves with — the subset this module reads.
+ *
+ * The Secure Fields iframe posts the card to `POST /v1/card_tokens` and answers
+ * with that endpoint's JSON as is (read from the iframe served by
+ * `secure-fields.mercadopago.com` on 2026-11-14), so the shape is the card token
+ * resource: `CardTokenResponse` in Mercado Pago's own Node SDK (`mercadopago`
+ * 3.6.2), where every field is optional. `first_six_digits` is the BIN of the
+ * card that was actually tokenized, which is how {@link useMercadoPagoCard}
+ * binds the token to the brand it quoted.
+ */
+export declare interface MercadoPagoCardToken {
+    /** Single-use token id. */
+    id: string;
+    /** First six digits of the tokenized card. */
+    first_six_digits?: string;
+}
+
+/** 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<MercadoPagoCardToken>;
+    };
+    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).
@@ -12152,6 +12493,15 @@ export declare interface OfflineQueryClearOptions {
      * Default `false`: the client belongs to the app, which may want to keep
      * public queries (a catalog, feature flags) across sessions and drop only
      * the user-scoped keys with `removeQueries`.
+     *
+     * With `auth`, only the reset lets a new handle on the same client persist
+     * the next session. Without it the client still holds the ended session's
+     * responses, so `clear()` marks the client's session record ended and
+     * every handle on it deletes its row instead of writing, until the client
+     * is reset or a handle is created on it with empty caches. Before 0.85.0,
+     * `clear()` dropped that record, and the handle created at login stamped
+     * the previous account's responses with the new one (security audit
+     * run-13, C1).
      */
     resetClient?: boolean;
 }
@@ -12162,15 +12512,23 @@ export declare interface OfflineQueryPersistence {
      * Load the persisted snapshot into the `QueryClient`. Call once on boot,
      * before rendering queries, so cached data is available offline. A no-op
      * once {@link OfflineQueryPersistence.clear} has been called, and — with
-     * `getPrincipal` — for a snapshot written under another principal.
+     * `getPrincipal` — for a snapshot written under another principal or while
+     * `isPrincipalKnown` returns `false`; call it again once it is known.
      */
     restore: () => Promise<void>;
     /**
      * Write the current cache snapshot immediately (bypassing the throttle). A
-     * no-op once {@link OfflineQueryPersistence.clear} has been called.
+     * no-op once {@link OfflineQueryPersistence.clear} has been called, and,
+     * with `auth`, once {@link OfflineQueryPersistence.unsubscribe} has.
      */
     flush: () => Promise<void>;
-    /** Stop persisting and drop the pending write. Idempotent. */
+    /**
+     * Stop persisting and drop the pending write. Idempotent.
+     *
+     * With `auth`, a later `flush()` writes nothing: the handle no longer sees
+     * sessions installed and ended, so it cannot tell whose responses the
+     * cache holds (security audit run-13, N3).
+     */
     unsubscribe: () => void;
     /**
      * End the persisted session (e.g. on logout) and delete the snapshot.
@@ -12201,6 +12559,15 @@ export declare interface OfflineQueryPersistence {
      * user-scoped keys with `removeQueries`. Because persistence is already
      * off, that manual call can come before or after this one.
      *
+     * With `auth`, the reset decides whether the next session persists on the
+     * same client. With it, the client's session record is dropped after
+     * `queryClient.clear()`, and a handle created at login persists the new
+     * account. Without it, the client still holds this session's responses,
+     * so the record is marked ended — never dropped — and every handle on the
+     * client, a new one or one on another `key`, deletes its row instead of
+     * writing until the client is reset or a handle is created on it with
+     * empty caches (security audit run-13, C1).
+     *
      * Idempotent and safe to call concurrently; every call deletes the row
      * again.
      *
@@ -12225,9 +12592,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 +12607,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
@@ -12253,8 +12623,121 @@ export declare interface OfflineQueryPersistenceOptions {
      * Read synchronously. A non-string, non-number value (the `Promise` of an
      * `async` getter) or a getter that throws reads as nobody. Omit it to restore
      * every snapshot, as before 0.82.0.
+     *
+     * `null` and `undefined` both mean **nobody is signed in** — the same
+     * contract as every other `getPrincipal` in the SDK, so `() => user?.id`
+     * keeps working. "Not known yet" (a cookie session before `/me` answers) is
+     * a different state, and this getter cannot express it: pass
+     * {@link OfflineQueryPersistenceOptions.isPrincipalKnown} for it. Without
+     * that, a write that runs before `/me` stamps the signed-in user's
+     * responses as anonymous, and a logged-out boot hydrates them (#590).
+     *
+     * A handle that hydrated an anonymous snapshot deletes it, instead of
+     * writing, once someone signs in on it: the anonymous row may hold a
+     * previous account's responses written before its principal was known, and
+     * stamping them with the account now signed in is what handed them to it
+     * (#590). To keep persisting, end it with `clear({ resetClient: true })`
+     * and create a new handle: the in-memory client still holds what the
+     * deleted row held, and a new handle on it would stamp that with the
+     * account signed in. With {@link OfflineQueryPersistenceOptions.auth} a new
+     * handle on such a client keeps deleting until the client is reset; with
+     * `getPrincipal` alone, resetting it is up to the app.
      */
     getPrincipal?: () => string | number | null | undefined;
+    /**
+     * Whether `getPrincipal` already reflects the real session. Only read with
+     * `getPrincipal`; omitted, the principal is always known, as before.
+     *
+     * For an app that learns who is signed in only after a round trip — a
+     * cookie session resolved by `/me`, a token restored asynchronously —
+     * return `false` until that answer arrives, whatever it is. While it is
+     * `false`:
+     *
+     * - a write does not run and is re-armed for the next throttle window, so
+     *   the responses already in the cache are stamped with the real owner, not
+     *   as anonymous;
+     * - a cache change does not bind the handle;
+     * - `restore()` hydrates nothing — call it again once the principal is
+     *   known.
+     *
+     * Without it, `null` before `/me` reads as "nobody": a session that ends
+     * (tab closed) inside the first throttle window leaves the signed-in user's
+     * responses stamped anonymous, for the next logged-out boot to hydrate
+     * (#590).
+     *
+     * Read synchronously; a throw reads as not known, so it fails closed.
+     *
+     * With {@link OfflineQueryPersistenceOptions.auth} there is no need for
+     * it; when both are given, both must say known.
+     */
+    isPrincipalKnown?: () => boolean;
+    /**
+     * The auth preset whose session owns the cache — pass what
+     * `createTempestAuth` returned. The safe wiring for an app built on it:
+     *
+     * - the principal is `auth.sessionKey()` unless
+     *   {@link OfflineQueryPersistenceOptions.getPrincipal} is given, so the
+     *   cache belongs to one sign-in and survives reloads and token rotations
+     *   of it; a new sign-in of the same account starts cold;
+     * - the principal is known only while `auth.isSessionKnown()` says the
+     *   session is settled — not while a `login()`, `restore()` or the boot
+     *   `refresh()` is still deciding it — and, with a `getPrincipal` of your
+     *   own, only once it names someone whenever a session is installed (a
+     *   user id read from a profile that has not loaded yet is not "nobody");
+     * - every session installed while the `QueryClient`'s cache lives is
+     *   recorded — the preset notifies each install, and every cache change,
+     *   write and restore reads `sessionKey()` too — not only the one a cache
+     *   change happens to see. Once a second session, or nobody after one,
+     *   was installed — a sign-out in another tab, a `logout()` without
+     *   `clear()`, a second `login()` on top —, every write deletes the row
+     *   and `restore()` hydrates nothing: the cache may hold the ended
+     *   session's responses, including one the api client replayed with the
+     *   bearer of a `login()` or boot `refresh()` that started after the
+     *   request left with no token and ended before it landed (security audit
+     *   run-12, C1). Nobody followed by a session is not an end, and a
+     *   token rotation keeps the key;
+     * - that record belongs to the `QueryClient`, not to the handle, so a new
+     *   handle on the same client keeps deleting. Only a reset drops it:
+     *   `clear({ resetClient: true })`, after which nothing of the ended
+     *   session stays in memory, or creating a handle on a client with empty
+     *   caches. `clear()` without `resetClient` leaves the client as it is,
+     *   so it marks the record ended instead: no handle on that client
+     *   persists until it is reset (security audit run-13, C1);
+     * - a handle only records sessions while it observes them: after
+     *   `unsubscribe()` its `flush()` writes nothing, and a handle created on
+     *   a client that already holds responses cannot know which session
+     *   fetched them — create it before the first query, at boot;
+     *   A session that is not this preset (an object of your own) is only
+     *   read on cache changes, writes and restores, so a session installed
+     *   and ended between two of them goes unseen;
+     * - a `sessionKey()` that throws reads as not known, so nothing is written.
+     *
+     * It does not call `clear()` on session end by itself: `clear()` ends the
+     * handle, and the row is already deleted on the next write. Keep calling
+     * `clear()` on logout, which also stops persisting at once.
+     *
+     * Before it, a cookie app had to wire `isPrincipalKnown` by hand, and the
+     * doc saying so was the only guard: without it, a tab closed before `/me`
+     * answered left the signed-in account's responses stamped anonymous for
+     * the next signed-out boot to hydrate (#596). Call `restore()` after the
+     * boot `auth.refresh()` settles; called before, it hydrates only what
+     * nobody owns.
+     */
+    auth?: OfflineQuerySession;
+}
+
+/**
+ * The session a {@link persistQueryClientOffline} handle follows — what
+ * `createTempestAuth` returns satisfies it, so pass the preset as is.
+ *
+ * Structural on purpose: the query module does not import the auth preset,
+ * so an app that persists its cache without it pays nothing for it.
+ */
+export declare interface OfflineQuerySession {
+    /** The key of the session signed in now, or `null` when nobody is. */
+    sessionKey: () => string | null;
+    /** Whether that session is settled, see `TempestAuth.isSessionKnown`. */
+    isSessionKnown: () => boolean;
 }
 
 /** Maps each table name to the record type it stores. */
@@ -13213,6 +13696,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 +14046,105 @@ 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.
+ *
+ * A status this version does not know renders as `unknown` ("verificando"). Known
+ * means an own key of the state table, so a status named after an
+ * `Object.prototype` member (`toString`, `constructor`) is unknown too, instead
+ * of an empty state block.
+ *
+ * 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 +15544,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 +17992,61 @@ 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.
+     *   the refresh was in flight; its tokens were discarded. That includes a
+     *   `logout()` or `login()` landing after the redemption of another
+     *   account and before the switch: it wins over the switch (#591). And a
+     *   `login()` still in flight when the redemption brought another account:
+     *   the explicit sign-in wins, the switch is discarded and, in body mode,
+     *   its refresh token revoked (#595).
      */
     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.
+     *
+     * Two tabs restoring together redeem once (#594). The redemption holds an
+     * origin-wide sign-in lock until the session it brought is installed, so a
+     * tab that calls `restore()` meanwhile waits for it and adopts that
+     * session — its own, if any, ends with `onSessionEnd` `"switch"` and
+     * `elsewhere: true` — and a `refresh()` that waited behind it follows the
+     * new session instead of redeeming the refresh token it spent. Until
+     * 0.84.0 the waiting tab redeemed again: a spent token, which a backend
+     * with reuse detection answers by revoking the whole family, or none at
+     * all, since the restoring tab's teardown had already cleared it.
+     *
+     * @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. Also
+     *   when the other tab's sign-in it waited for left no session to adopt.
+     */
+    restore: () => Promise<TUser | null>;
     /** The current access token, or null. */
     getToken: () => string | null;
     /**
@@ -17382,8 +18069,36 @@ 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;
+    /**
+     * Whether the session this preset holds is settled — `false` while it is
+     * still being decided (#596).
+     *
+     * It is `false` while a `login()`, a `restore()` or an account switch is
+     * in flight (their user load included), and while a `refresh()` runs with
+     * no token installed — the boot restore from a refresh cookie. It is
+     * `true` otherwise, signed in or signed out: a signed-out answer is then
+     * the real one, not "the restore has not answered yet".
+     *
+     * What it is for: a store that persists per-account data across boots
+     * must not stamp it while the account is unknown. A cookie app reads
+     * nobody signed in until its restore answers, and the persisted query
+     * cache used to stamp the signed-in account's responses as anonymous in
+     * that window, for the next signed-out boot to hydrate.
+     * `persistQueryClientOffline({ auth })` reads it on its own.
+     *
+     * It says nothing about the user profile: a session restored by
+     * `refresh()` installs a token and a `sessionKey()` without loading the
+     * user. A principal read from the user is known only once that user is
+     * there, which `persistQueryClientOffline` also checks.
+     */
+    isSessionKnown: () => boolean;
     /**
      * Stop following the other tabs: removes the `storage` listener this
      * preset adds to `window`. Idempotent.
@@ -18517,8 +19232,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 +19290,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 +20757,107 @@ 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. A new `publicKey` remounts empty fields and forgets the previous
+ * BIN, brand and quote with them.
+ *
+ * `tokenize` binds the token to the quote: Mercado Pago's token carries
+ * `first_six_digits`, and a token whose digits are not the quoted BIN is
+ * refused. `binChange` is debounced inside the iframe, so a payer who swaps the
+ * card number and submits at once would otherwise send the new card with the
+ * old card's brand and installments. A token response without
+ * `first_six_digits` is not refused — there is nothing to compare — and the
+ * backend and Mercado Pago still validate the brand on the charge.
+ *
+ * @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. Also throws, after the token is created,
+     * when the token's `first_six_digits` is not the BIN the brand and
+     * installments were quoted for: the payer changed the card number after the
+     * quote, and charging it would send one card with another card's brand.
+     */
+    tokenize: (input: CardTokenizeInput) => Promise<CardTokenResult>;
+}
+
 /**
  * Acquire a microphone `MediaStream`, classified errors included, and release it
  * properly.
@@ -20663,6 +21491,62 @@ 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.
+ *
+ * An update for another `provider` or `provider_charge_id` is ignored, and a
+ * `paid` charge only moves on to `refunded` or `charged_back` — a late
+ * `expired` never replaces it. Passing a charge with a different `provider` or
+ * `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`.