tempest-react-sdk 0.84.0 → 0.86.0

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

@@ -5725,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
@@ -7381,7 +7383,10 @@ export declare function describeAppError(error: unknown, context?: Record<string
  * 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
+ * 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.
@@ -10996,6 +11001,12 @@ export { LoaderFunctionArgs }
  * 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
@@ -11009,7 +11020,12 @@ export declare function loadMercadoPago(options?: LoadMercadoPagoOptions): Promi
 
 /** Options for {@link loadMercadoPago}. */
 export declare interface LoadMercadoPagoOptions {
-    /** Script URL. Default {@link MERCADO_PAGO_SCRIPT_URL}; override only for a proxy you control. */
+    /**
+     * 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;
@@ -11541,6 +11557,24 @@ export declare interface MercadoPagoCardContainers {
 /** 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;
@@ -11594,9 +11628,7 @@ export declare interface MercadoPagoInstallmentsEntry {
 export declare interface MercadoPagoLike {
     fields: {
         create(type: MercadoPagoFieldType, options?: MercadoPagoFieldOptions): MercadoPagoFieldLike;
-        createCardToken(data: MercadoPagoCardTokenData): Promise<{
-            id: string;
-        }>;
+        createCardToken(data: MercadoPagoCardTokenData): Promise<MercadoPagoCardToken>;
     };
     getInstallments(params: {
         amount: string;
@@ -12461,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;
 }
@@ -12471,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.
@@ -12510,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.
      *
@@ -12565,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. */
@@ -13922,6 +14093,11 @@ export declare interface PixCharge {
  * 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.
@@ -17829,7 +18005,12 @@ export declare interface TempestAuth<TUser, TCredentials> {
      * 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>;
     /**
@@ -17850,9 +18031,20 @@ export declare interface TempestAuth<TUser, TCredentials> {
      * 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.
+     *   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. */
@@ -17884,6 +18076,29 @@ export declare interface TempestAuth<TUser, TCredentials> {
      * 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.
@@ -20564,7 +20779,16 @@ export declare function useMediaQuery(query: string): boolean;
  * 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.
+ * 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
@@ -20626,7 +20850,10 @@ export declare interface UseMercadoPagoCardResult {
      * 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.
+     * 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>;
 }
@@ -21278,7 +21505,10 @@ export declare interface UsePasskeySignInResult<TResult> extends PasskeyCapabili
  * 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.
+ * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",
@@ -249,6 +249,12 @@
     "node": ">=22.12"
   },
   "overrides": {
+    "@microsoft/api-extractor": {
+      "minimatch": "^11.0.1"
+    },
+    "@typescript-eslint/typescript-estree": {
+      "minimatch": "^11.0.1"
+    },
     "rolldown": "1.2.14"
   }
 }

package/template/package.json

@@ -24,7 +24,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.4",
-    "eslint": "^10.8.0",
+    "eslint": "^10.15.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.3",
     "eslint-plugin-simple-import-sort": "^14.0.0",
@@ -34,5 +34,10 @@
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.65.0",
     "vite": "^8.3.3"
+  },
+  "overrides": {
+    "@typescript-eslint/typescript-estree": {
+      "minimatch": "^11.0.1"
+    }
   }
 }