tempest-react-sdk 0.64.0 → 0.66.0

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

@@ -99,6 +99,17 @@ import { useWatch } from 'react-hook-form';
 import { WheelEventHandler } from 'react';
 import { z } from 'zod';
 
+/**
+ * What every formatter prints when it has nothing to print.
+ *
+ * An em dash rather than an empty string, because in a table those are two
+ * different claims: a blank cell reads as "this column does not apply here",
+ * while `—` reads as "this value is missing". `formatDurationMs` in `/perf` has
+ * answered this way since it shipped, and `formatPercent` joined it in 0.65.0;
+ * this constant is what stops the third answer from appearing.
+ */
+export declare const ABSENT_TEXT = "\u2014";
+
 /**
  * A pluggable access-control strategy. Implementations decide whether a given
  * action is allowed, returning a plain boolean, a {@link CanResult}, or a
@@ -597,6 +608,33 @@ export declare interface ApiClient {
     put<T>(path: string, options?: RequestOptions): Promise<T>;
     patch<T>(path: string, options?: RequestOptions): Promise<T>;
     delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Download a binary body through the full client pipeline.
+     *
+     * Same base URL, `getToken` header, 401 refresh-and-replay, `onUnauthorized`,
+     * logging, timeout and retry policy as {@link ApiClient.request} — only the
+     * decoding differs. Without it every download left the client: a hand-rolled
+     * `fetch` that re-declares the `Authorization` header and re-implements the
+     * error handling, and that has no refresh, which is the client's reason to
+     * exist.
+     *
+     * @param path - Path joined onto the client's base URL.
+     * @param options - The same options `request` takes; `method` defaults to GET.
+     * @returns The response body as a `Blob`.
+     * @throws TempestApiError On any non-2xx response, carrying the status.
+     */
+    blob(path: string, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Download a binary body as an `ArrayBuffer`, for the callers a `Blob` does
+     * not serve — a decoder, a hash, a typed array fed to WebGL or to
+     * `onnxruntime-web`.
+     *
+     * @param path - Path joined onto the client's base URL.
+     * @param options - The same options `request` takes; `method` defaults to GET.
+     * @returns The response body as an `ArrayBuffer`.
+     * @throws TempestApiError On any non-2xx response, carrying the status.
+     */
+    arrayBuffer(path: string, options?: RequestOptions): Promise<ArrayBuffer>;
     upload<T>(path: string, formData: FormData, method?: "POST" | "PUT" | "PATCH", options?: Omit<RequestOptions, "body" | "method">): Promise<T>;
 }
 
@@ -625,6 +663,25 @@ export declare interface ApiClientConfig {
     prefix?: string;
     /** Returns the current bearer token (or null/undefined). Called per request. */
     getToken?: () => string | null | undefined;
+    /**
+     * Origins besides `baseURL`'s that may receive the `getToken` credential.
+     *
+     * Since 0.66.0 the bearer token is scoped to the origin of `baseURL`. A
+     * request to any other origin still goes out — it just goes without the
+     * header. That matters because a path may be an absolute URL, in which case
+     * it overrides `baseURL` completely, so the destination of a credentialed
+     * request could be decided by a value the app read off the network: a
+     * pagination link, a `download_url`, a `Location`.
+     *
+     * List the second host here when it genuinely needs the API's token — a CDN
+     * behind the same identity, a sibling service. An origin compares as an
+     * origin (`"https://cdn.acme.com"`), so path and trailing slash are
+     * ignored.
+     *
+     * A relative `baseURL` needs nothing here: a relative target resolves
+     * against the document and cannot cross an origin.
+     */
+    trustedOrigins?: readonly string[];
     /**
      * Per-request correlation id sent as the `X-Request-ID` header, matching the
      * Tempest FastAPI SDK `RequestIDMiddleware`. Defaults to a generated id.
@@ -3233,8 +3290,23 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  * is the signal to clear the session. Without `refresh`, the first `401` calls
  * it directly.
  *
+ * **Binary bodies** have their own methods — `blob()` and `arrayBuffer()` — which
+ * run the same pipeline and skip the parse. `request()` no longer decodes an
+ * unknown `Content-Type` as text either: it returns a `Blob` and says so once in
+ * a development build, because reading `image/jpeg` as UTF-8 destroyed the bytes
+ * on the way in.
+ *
+ * **The bearer token is scoped to `baseURL`'s origin** since 0.66.0. A path may
+ * be an absolute URL, which overrides the base entirely, so without a scope the
+ * destination of a credentialed request could come from a value read off the
+ * network. A request to another origin still goes out; it goes without the
+ * header, and a development build says so once. Declare the exceptions in
+ * {@link ApiClientConfig.trustedOrigins}.
+ *
  * **Retries** are off unless you set `retry`. See {@link ApiClientConfig.retry}
- * for the built-in policy; it never replays a write.
+ * for the built-in policy; it never replays a write. A single call overrides it
+ * with {@link RequestOptions.retry}, and opts out of auth entirely with
+ * {@link RequestOptions.skipAuth}.
  *
  * **Logging** is off unless you pass a `logger`. With one, every finished attempt
  * writes a line — `debug` under 400, `warn` from 400 up, plus a `warn` when
@@ -3253,7 +3325,8 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  * });
  *
  * @param config - Base URL plus the optional auth, retry and fetch hooks.
- * @returns A client with `request`/`get`/`post`/`put`/`patch`/`delete`/`upload`.
+ * @returns A client with `request`/`get`/`post`/`put`/`patch`/`delete`/`blob`/
+ * `arrayBuffer`/`upload`.
  */
 export declare function createApiClient(config: ApiClientConfig): ApiClient;
 
@@ -3595,7 +3668,7 @@ export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): Fea
  * const packed = createJsonStorage(compressedStorageCodec);
  *
  * @param codec - Encoder pair. Defaults to plain JSON.
- * @returns A store with `get` / `set` / `remove`.
+ * @returns A store with `get` / `set` / `getRaw` / `setRaw` / `remove`.
  *
  * @tempest-limits empty-catch — every method is best-effort by contract:
  * `localStorage` throws on quota exhaustion, in Safari private mode, and when a
@@ -5390,6 +5463,23 @@ export declare const DEFAULT_PUSH_TO_TALK_KEY = "Space";
  */
 export declare const DEFAULT_VOICE_CHAIN: VoiceChainSettings;
 
+/**
+ * The default instruction for a browser that cannot be prompted.
+ *
+ * Written out rather than left to the app because every app wrote the same two
+ * sentences, and getting them wrong is invisible: an iOS user who is told to
+ * look for an "Install" menu never finds one, because Safari puts it behind the
+ * Share sheet.
+ *
+ * On an Android fork the copy also offers the `intent://` link the SDK already
+ * builds — reopening the page in Chrome is the only path that reaches a real
+ * install on a browser whose menu has no install entry at all.
+ *
+ * @param input - The resolved method and the optional Chrome intent.
+ * @returns The instruction, or `null` when the method needs none.
+ */
+export declare function defaultInstallHint({ method, openInChromeIntent }: InstallHintInput): ReactNode;
+
 /**
  * Identity helper that types a declarative route tree. Use it so editors give
  * autocomplete and type-checking on every node; the array is returned as-is.
@@ -6392,13 +6482,19 @@ export declare interface FormActionsProps extends HTMLAttributes<HTMLDivElement>
  * controls the fractional digits for scaled units (default 1); `0` bytes
  * always renders as `"0 B"`.
  *
+ * An absent or unrepresentable count renders as `"—"`. It used to render as
+ * **`"NaN undefined"`**: `Math.log(NaN)` walks the exponent off the end of the
+ * unit table, so the unit itself came out `undefined` — the size was not merely
+ * unreadable, it claimed a unit that does not exist.
+ *
  * @example
  * formatBytes(0);       // "0 B"
  * formatBytes(1536);    // "1.5 KB"
  * formatBytes(1048576); // "1 MB"
  * formatBytes(1536, 2); // "1.50 KB"
+ * formatBytes(null);    // "—"
  */
-export declare function formatBytes(bytes: number, decimals?: number): string;
+export declare function formatBytes(bytes: number | null | undefined, decimals?: number, options?: FormatFallbackOptions): string;
 
 /** Format an 11-digit Brazilian CEP-like value as `00000-000`. */
 export declare function formatCEP(value: string): string;
@@ -6412,12 +6508,17 @@ export declare function formatCNPJ(value: string): string;
  * Wraps `Intl.NumberFormat` with `notation: "compact"`. The `locale` defaults
  * to `"en-US"`.
  *
+ * An absent or unrepresentable value renders as `"—"`. The `null` case is the
+ * one that matters: `Intl` coerces it to zero, so a count the backend left out
+ * used to read as **`"0"`** — a number the reader has no reason to doubt.
+ *
  * @example
  * formatCompactNumber(1234);            // "1.2K"
  * formatCompactNumber(5600000);         // "5.6M"
  * formatCompactNumber(1234, "pt-BR");   // "1,2 mil"
+ * formatCompactNumber(null);            // "—"
  */
-export declare function formatCompactNumber(value: number, locale?: string): string;
+export declare function formatCompactNumber(value: number | null | undefined, locale?: string, options?: FormatFallbackOptions): string;
 
 /**
  * Apply the Brazilian CPF mask `XXX.XXX.XXX-XX`.
@@ -6430,18 +6531,50 @@ export declare function formatCPF(value: string): string;
 /**
  * Format a number as Brazilian Real currency.
  *
- * @param value - The amount in BRL.
+ * An absent or unrepresentable amount renders as `"—"` rather than as a number.
+ * That branch is a data-correctness fix, not cosmetics: `Intl` coerces `null` to
+ * zero, so an amount the backend left out used to reach the screen as
+ * **`"R$ 0,00"`** — a plausible figure a reader has no way to question — and
+ * `undefined` as `"R$ NaN"`.
+ *
+ * @example
+ * ```typescript
+ * formatCurrency(1234.56);                      // "R$ 1.234,56"
+ * formatCurrency(null);                         // "—"
+ * formatCurrency(null, { fallback: "sem valor" }); // "sem valor"
+ * ```
+ *
+ * @param value - The amount in BRL, or `null`/`undefined` when there is none.
+ * @param options - Text to render when there is nothing to format.
  * @returns A locale-formatted string, e.g. "R$ 1.234,56".
  */
-export declare function formatCurrency(value: number): string;
+export declare function formatCurrency(value: number | null | undefined, options?: FormatFallbackOptions): string;
 
 /**
  * Format an ISO date or Date instance as `dd/MM/yyyy`.
  *
- * @param value - ISO string or Date.
- * @returns Formatted date string, or empty string when input is invalid.
+ * Absent input answers `"—"`. It used to **throw**: `new Date(null)` is epoch and
+ * `null.getTime` is a `TypeError`, so a nullable column — which is every
+ * `deleted_at`, `expires_at` and half the `updated_at` a FastAPI backend sends —
+ * took the screen down instead of rendering a gap.
+ *
+ * A value that is present and unparseable still answers `""`, deliberately: on a
+ * screen that reads a log, "nobody filled this in" and "what they filled in is
+ * broken" are different findings, and the second is the one worth chasing.
+ *
+ * @example
+ * ```typescript
+ * formatDate("2026-05-16T12:00:00Z"); // "16/05/2026"
+ * formatDate(null);                   // "—"
+ * formatDate("banana");               // ""
+ * ```
+ *
+ * @param value - ISO string, Date, or `null`/`undefined`.
+ * @param options - Text to render when the value is absent.
+ * @returns Formatted date string, the fallback when absent, or empty string when
+ *   the value is present and invalid.
  */
-export declare function formatDate(value: string | Date): string;
+export declare function formatDate(value: string | Date | null | undefined, options?: FormatFallbackOptions): string;
 
 /**
  * Format an ISO date or Date instance as `yyyy-MM-dd`, the value an
@@ -6461,19 +6594,29 @@ export declare function formatDate(value: string | Date): string;
  * @example
  * <input type="date" defaultValue={formatDateForInput(order.createdAt)} />
  *
- * @param value - ISO string or Date.
+ * Absent input answers `""` here — **not** the em dash the reading formatters
+ * use — because that is what an input reads as "no value"; an em dash would
+ * arrive as content the user has to delete before typing a date.
+ *
+ * @param value - ISO string, Date, or `null`/`undefined`.
+ * @param options - Text for an absent value; defaults to `""`.
  * @returns The `yyyy-MM-dd` value, or an empty string when the input is invalid —
  *   which is what a date input reads as "no value", unlike `"Invalid Date"`.
  */
-export declare function formatDateForInput(value: string | Date): string;
+export declare function formatDateForInput(value: string | Date | null | undefined, options?: FormatFallbackOptions): string;
 
 /**
  * Format an ISO date or Date instance as `dd/MM/yyyy HH:mm`.
  *
- * @param value - ISO string or Date.
- * @returns Formatted datetime string, or empty string when input is invalid.
+ * Same contract as {@link formatDate}: absent answers the fallback (`"—"` by
+ * default) instead of throwing, and present-but-invalid answers `""`.
+ *
+ * @param value - ISO string, Date, or `null`/`undefined`.
+ * @param options - Text to render when the value is absent.
+ * @returns Formatted datetime string, the fallback when absent, or empty string
+ *   when the value is present and invalid.
  */
-export declare function formatDateTime(value: string | Date): string;
+export declare function formatDateTime(value: string | Date | null | undefined, options?: FormatFallbackOptions): string;
 
 /**
  * Format an ISO date or Date instance as `yyyy-MM-ddTHH:mm`, the value an
@@ -6505,7 +6648,7 @@ export declare function formatDateTime(value: string | Date): string;
  *   invalid — which is what a datetime input reads as "no value", unlike
  *   `"Invalid Date"`.
  */
-export declare function formatDateTimeForInput(value: string | Date): string;
+export declare function formatDateTimeForInput(value: string | Date | null | undefined, options?: FormatFallbackOptions): string;
 
 /**
  * Rendering helpers for the numbers a profiler produces.
@@ -6532,13 +6675,51 @@ export declare function formatDateTimeForInput(value: string | Date): string;
  */
 export declare function formatDurationMs(value: number): string;
 
+/** The text a formatter falls back to when the value cannot be rendered. */
+export declare interface FormatFallbackOptions {
+    /**
+     * Text for a value that is absent (`null`/`undefined`) or unrepresentable
+     * (`NaN`, `Infinity`). Defaults to {@link ABSENT_TEXT}.
+     *
+     * The formatters that feed an `<input>` default to `""` instead, because an
+     * input reads an empty string as "no value" and would render an em dash as
+     * content the user has to delete.
+     */
+    fallback?: string;
+}
+
 /**
- * Format a fraction (0-1) as a percentage with one decimal.
+ * Format a fraction (0-1) as a percentage.
+ *
+ * A non-finite input renders as `"—"` rather than `"NaN%"` or `"∞%"`, which is
+ * what `Intl.NumberFormat` produces and what a division by zero upstream puts on
+ * the screen. It matches `formatDurationMs`, which already answers that way.
+ *
+ * @example
+ * ```typescript
+ * formatPercent(0.9874);                // "98,7%"
+ * formatPercent(0.9874, { decimals: 2 }); // "98,74%"
+ * formatPercent(0 / 0);                 // "—"
+ * ```
  *
  * @param value - Fraction between 0 and 1.
- * @returns Formatted percent string, e.g. "12,5%".
+ * @param options - Rendering options; `decimals` defaults to 1.
+ * @returns Formatted percent string, e.g. "12,5%", or `"—"` for a non-finite input.
  */
-export declare function formatPercent(value: number): string;
+export declare function formatPercent(value: number | null | undefined, options?: FormatPercentOptions): string;
+
+/** How {@link formatPercent} renders a fraction. */
+export declare interface FormatPercentOptions extends FormatFallbackOptions {
+    /**
+     * Decimal places to show, fixed (padded as well as truncated).
+     *
+     * Defaults to `1`, which is what the function always did. Two is the case
+     * that produced this option: a confidence of 98,74% and one of 98,7% are the
+     * same number on a summary card and two different readings on a detail
+     * screen, so the precision belongs to the call site.
+     */
+    decimals?: number;
+}
 
 /**
  * Apply the Brazilian phone mask `(XX) XXXXX-XXXX` or `(XX) XXXX-XXXX`.
@@ -7277,11 +7458,15 @@ export declare interface InstallBackgroundSyncOptions {
 }
 
 /**
- * Dismissible bottom banner that invites the user to install the PWA. Wired to
- * {@link useBeforeInstallPrompt}: it renders only when the browser captured an
- * install prompt and the app is not already running standalone — so on
- * platforms that never fire `beforeinstallprompt` (e.g. iOS Safari) it stays
- * hidden and you can surface manual instructions elsewhere.
+ * Dismissible bottom banner that invites the user to install the PWA, wired to
+ * {@link useInstallPrompt}.
+ *
+ * Where the browser fires `beforeinstallprompt`, the button installs. Where it
+ * does not — iOS Safari, and the Android Chromium forks that strip the API — the
+ * banner shows that platform's instruction instead of disappearing. It used to
+ * disappear: built on `useBeforeInstallPrompt`, it rendered `null` exactly where
+ * the user has no other way to find the install entry, which is why every app
+ * kept a local copy of this component just to add the two missing paths.
  *
  * @tempest-limits empty-catch — persisting the dismissal is a courtesy, not the
  * feature. When `localStorage` refuses the write (quota, private mode) the banner
@@ -7295,7 +7480,7 @@ export declare interface InstallBackgroundSyncOptions {
  *     storageKey="famacha:install-dismissed"
  * />
  */
-export declare function InstallBanner({ title, description, installLabel, dismissLabel, icon, storageKey, onResult, className, }: InstallBannerProps): JSX.Element | null;
+export declare function InstallBanner({ title, description, installLabel, hintLabel, dismissLabel, icon, storageKey, declineCooldownMs, renderHint, manualFallbackDelayMs, onResult, className, }: InstallBannerProps): JSX.Element | null;
 
 export declare interface InstallBannerProps {
     /** Headline. Default `"Instale o app"`. */
@@ -7313,29 +7498,95 @@ export declare interface InstallBannerProps {
      * make dismissal last only for the current session (component state).
      */
     storageKey?: string;
+    /**
+     * How long, in ms, a dismissal lasts before the banner may return.
+     *
+     * Omitted, a dismissal written to `storageKey` is permanent, which is what
+     * the component always did and what a stored `"1"` keeps meaning. With a
+     * cooldown the dismissal is stored as a timestamp instead, so the banner
+     * comes back after the window — the same shape `useInstallPrompt` uses for
+     * its own decline.
+     */
+    declineCooldownMs?: number;
+    /**
+     * Install button label used when the browser cannot be prompted and the
+     * banner shows the manual instruction. Default `"Como instalar"`.
+     */
+    hintLabel?: string;
+    /**
+     * Replaces the instruction shown for the `"ios"` and `"manual"` methods.
+     *
+     * The default copy is in PT-BR and names the real menu entries.
+     */
+    renderHint?: RenderInstallHint;
+    /**
+     * How long, in ms, to wait for `beforeinstallprompt` before falling back to
+     * the manual instruction. Forwarded to {@link useInstallPrompt}; defaults to
+     * 3000 there.
+     */
+    manualFallbackDelayMs?: number;
     /** Called with the user's choice after the install prompt resolves. */
     onResult?: (outcome: InstallOutcome) => void;
     className?: string;
 }
 
 /**
- * Button wired to the PWA install prompt ({@link useBeforeInstallPrompt}).
- * Renders nothing when the app can't be installed — no prompt captured yet,
- * already installed, or running standalone — so you can drop it anywhere
- * without guarding visibility yourself.
+ * Button wired to PWA installation, through {@link useInstallPrompt}.
+ *
+ * Where the browser fires `beforeinstallprompt`, the click installs. Where it
+ * does not — iOS Safari, and the Android Chromium forks (Mi Browser, UC, Opera
+ * Mini, Huawei) that strip the API — the click reveals the instruction for that
+ * platform instead of the button disappearing.
+ *
+ * That disappearance was the defect: the component was built on
+ * `useBeforeInstallPrompt`, so it rendered `null` exactly where the user needs
+ * the most help, and every app re-implemented the iOS and manual paths locally.
+ * Nothing renders only when there is genuinely nothing to offer — already
+ * installed, running standalone, or inside the decline cooldown.
  *
  * Inherits every {@link Button} prop (`variant`, `size`, `leftIcon`, …).
  *
  * @example
  * <InstallButton variant="primary" leftIcon={<Download />} />
+ *
+ * @example
+ * <InstallButton renderHint={({ method }) => (method === "ios" ? <IOSSteps /> : <MenuSteps />)} />
  */
-export declare function InstallButton({ label, onResult, ...props }: InstallButtonProps): JSX.Element | null;
+export declare function InstallButton({ label, hintLabel, onResult, renderHint, manualFallbackDelayMs, wrapperClassName, ...props }: InstallButtonProps): JSX.Element | null;
 
 export declare interface InstallButtonProps extends Omit<ButtonProps, "onClick" | "children"> {
     /** Button label. Default `"Instalar app"`. */
     label?: ReactNode;
+    /**
+     * Label used when the browser cannot be prompted and the button reveals the
+     * manual instruction instead. Default `"Como instalar"`.
+     */
+    hintLabel?: ReactNode;
     /** Called with the user's choice after the install prompt resolves. */
     onResult?: (outcome: InstallOutcome) => void;
+    /**
+     * Replaces the instruction shown for the `"ios"` and `"manual"` methods.
+     *
+     * The default copy is in PT-BR and names the real menu entries. Pass this to
+     * translate it, to shorten it, or to point at a screenshot of your own.
+     */
+    renderHint?: RenderInstallHint;
+    /**
+     * How long, in ms, to wait for `beforeinstallprompt` before falling back to
+     * the manual instruction. Forwarded to {@link useInstallPrompt}; defaults to
+     * 3000 there.
+     */
+    manualFallbackDelayMs?: number;
+    /** Class applied to the wrapper that holds the button and the instruction. */
+    wrapperClassName?: string;
+}
+
+/** What an install affordance needs to render the instruction for a method. */
+export declare interface InstallHintInput {
+    /** The strategy `useInstallPrompt` resolved. */
+    method: InstallMethod;
+    /** An `intent://` URL that re-opens the page in Chrome on Android, if any. */
+    openInChromeIntent: string | null;
 }
 
 /**
@@ -7720,6 +7971,42 @@ declare type IssuePathSegment = PropertyKey | {
     readonly key: PropertyKey;
 };
 
+/**
+ * Whether a request to `target` may carry the caller's credential.
+ *
+ * The SDK writes `Authorization: Bearer` in three places, and until 0.66.0 none
+ * of them looked at where the request was going. That is only safe while every
+ * target URL is written by the app: a resumable upload takes its URL from the
+ * server's `Location` header, and `createApiClient` lets an absolute path
+ * override `baseURL` entirely, so a URL arriving over the network could decide
+ * which origin received the token — and the file bytes with it.
+ *
+ * Handing an upload off to object storage on another host is ordinary `tus`
+ * deployment, not an attack, which is exactly why the credential must be scoped
+ * rather than the request blocked: the upload still goes through, it just goes
+ * without the API's bearer token.
+ *
+ * Both sides are resolved against the document first, so a relative `baseURL`
+ * or `endpoint` — the shape behind a dev-server or reverse proxy — compares
+ * equal to the absolute URL the request actually goes to. Outside a browsing
+ * context a relative target resolves to nothing and is allowed: there is no
+ * origin for it to cross.
+ *
+ * @param target - The URL the request is about to go to.
+ * @param reference - The origin the credential belongs to, normally the
+ *     client's `baseURL` or the upload `endpoint`.
+ * @param trustedOrigins - Extra origins the app declared, for the legitimate
+ *     second host: a CDN, a signed upload endpoint.
+ * @returns Whether the credential may be attached.
+ *
+ * @example
+ * isTrustedCredentialTarget("https://api.acme.com/me", "https://api.acme.com");
+ * // true
+ * isTrustedCredentialTarget("https://cdn.other/u/1", "https://api.acme.com");
+ * // false
+ */
+export declare function isTrustedCredentialTarget(target: string, reference: string, trustedOrigins?: readonly string[]): boolean;
+
 /** True when `value` is a finite latitude in `[-90, 90]`. */
 export declare function isValidLatitude(value: number): boolean;
 
@@ -7748,6 +8035,10 @@ export declare interface JsonStorage {
     /**
      * Read and decode a key.
      *
+     * The value is decoded by the store's codec — JSON for {@link storage} —
+     * which is what makes a key written as a bare string unreadable here: it is
+     * not the shape this method writes. {@link JsonStorage.getRaw} reads those.
+     *
      * @typeParam T - The expected value shape.
      * @param key - Storage key.
      * @param fallback - Returned when the key is absent, unreadable, or corrupt.
@@ -7757,11 +8048,42 @@ export declare interface JsonStorage {
     /**
      * Encode and write a key.
      *
+     * The value is **encoded** — `set("theme", "dark")` stores `"dark"` with the
+     * quotes, not `dark`. That matters when an existing key is being adopted:
+     * whatever read it before will no longer recognise what this writes, and the
+     * old value will no longer parse here. {@link JsonStorage.setRaw} is the
+     * passthrough.
+     *
      * @typeParam T - The value being stored.
      * @param key - Storage key.
      * @param value - Any value the codec can represent.
      */
     set<T>(key: string, value: T): void;
+    /**
+     * Read a key exactly as `localStorage` holds it, with no decoding.
+     *
+     * The escape hatch {@link JsonStorage.get} cannot be: `get` runs the codec,
+     * so a key holding a bare `dark` — written by another library, by the app
+     * before it adopted this wrapper, or by the SDK's own `ThemeProvider` —
+     * fails to parse and comes back as the fallback. Reading that key is a
+     * different operation, not a variant of the same one.
+     *
+     * @param key - Storage key.
+     * @returns The stored string, or `null` when the key is absent or storage is
+     *   unavailable.
+     */
+    getRaw(key: string): string | null;
+    /**
+     * Write a string exactly as given, with no encoding.
+     *
+     * The counterpart of {@link JsonStorage.getRaw}, and what keeps adoption from
+     * being a silent migration: `set("theme", "dark")` stores `"dark"` **with the
+     * quotes**, which the app's previous reader no longer recognises.
+     *
+     * @param key - Storage key.
+     * @param value - The exact string to store.
+     */
+    setRaw(key: string, value: string): void;
     /**
      * Delete a key.
      *
@@ -11469,6 +11791,9 @@ export declare interface RelativeTimeProps extends HTMLAttributes<HTMLTimeElemen
  */
 export declare function removeById<T, V extends Partial<Record<keyof T, unknown>> = T>(idField?: keyof T): (current: T[] | undefined, item: V) => T[];
 
+/** Renders the instruction shown when the browser has no install prompt. */
+export declare type RenderInstallHint = (input: InstallHintInput) => ReactNode;
+
 export declare interface ReorderPayload {
     from: number;
     to: number;
@@ -11486,6 +11811,38 @@ export declare interface RequestOptions extends Omit<RequestInit, "body"> {
      * a `queryFn` and the request is cancelled on unmount and on refetch.
      */
     signal?: AbortSignal | null;
+    /**
+     * Send this request with no `Authorization` header, and never enter the
+     * refresh-and-replay cycle on a `401`.
+     *
+     * This is what login and refresh need: a route that must not carry the
+     * token it is about to obtain, and whose own `401` must surface rather than
+     * call `refresh()` again — which would recurse. Before 0.66.0 the only way
+     * to get it was a second client, which is why `createTempestAuth` used to
+     * build three.
+     */
+    skipAuth?: boolean;
+    /**
+     * Send the `Authorization` header, but let a `401` surface instead of
+     * refreshing and replaying.
+     *
+     * The narrower half of {@link skipAuth}, for a call that is authenticated
+     * but whose failure the caller wants to see — a token probe, a background
+     * poll that should not fight for the refresh lock.
+     */
+    skipAuthRetry?: boolean;
+    /**
+     * Retry policy for this request, overriding the client's.
+     *
+     * Replaces `config.retry` entirely rather than merging into it, the same
+     * way `config.retry` is read today: a merged `shouldRetry` would silently
+     * combine two policies that were each written to be complete.
+     *
+     * `false` turns retrying off for one call on a client that has it on;
+     * `true` or {@link RetryOptions} turns it on for one call on a client that
+     * does not.
+     */
+    retry?: boolean | RetryOptions;
     /**
      * Override the client's timeout for this request, in milliseconds. `null`
      * disables it, which is the escape hatch for a stream or a long poll.
@@ -11641,6 +11998,18 @@ export declare interface ResumableUploadOptions {
     headers?: Record<string, string>;
     /** Returns the current bearer token, read before each request. */
     getToken?: () => string | null | undefined;
+    /**
+     * Origins besides `endpoint`'s that may receive the `getToken` credential.
+     *
+     * Since 0.66.0 the bearer token is scoped to the origin of `endpoint`, and
+     * the creation response's `Location` no longer decides where it goes. A
+     * server that hands the upload to object storage on another host still
+     * works — the `PATCH` requests simply carry no `Authorization`, which is
+     * what a presigned storage URL expects anyway.
+     *
+     * List the storage origin here when it does need the API's token.
+     */
+    trustedOrigins?: readonly string[];
     /** Send cookies. Default `false`. */
     withCredentials?: boolean;
     /**
@@ -12163,26 +12532,63 @@ export declare interface SegmentedControlProps<TValue extends string = string> e
 }
 
 /**
- * Native `<select>` wrapper with label/helper/error slots. Either provide
- * `options` for a quick render, or pass `<option>` children directly.
+ * Native `<select>` wrapper. Either provide `options` for a quick render, or
+ * pass `<option>` children directly.
+ *
+ * Two variants:
+ *
+ * - `"field"` (default) — label, control, helper text and error slot, for a form.
+ * - `"chip"` — the control alone, sized to its content, for a settings row where
+ *   the icon and the label are already on the left and the control belongs on the
+ *   right. Rendering the full field there stacks two labelled fields inside one
+ *   list item, which is why every app ended up hand-rolling a native `<select>`
+ *   with `appearance: none` — and hand-rolling it loses the focus ring, the
+ *   disabled styling and the caret this component already solves.
+ *
+ * @example
+ * <Select label="Estado" options={states} placeholder="Selecione" />
+ *
+ * @example
+ * <ListTile title="Idioma" trailing={<Select variant="chip" aria-label="Idioma" options={langs} />} />
  */
 export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
 
-export declare interface SelectOption {
-    value: string | number;
-    label: string;
-    disabled?: boolean;
+/** What both variants of {@link Select} accept. */
+declare interface SelectBaseProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    options?: SelectOption[];
+    placeholder?: string;
+    wrapperClassName?: string;
+}
+
+/**
+ * The bare control, sized to its content.
+ *
+ * `aria-label` is required rather than optional, because the variant removes the
+ * only visible label the component had. A settings row names the control in the
+ * row's own text, which the `<select>` has no relationship to — so without this
+ * the screen reader announces a combobox with no name at all.
+ */
+declare interface SelectChipProps extends SelectBaseProps {
+    variant: "chip";
+    "aria-label": string;
 }
 
-export declare interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+/** The full form field: label, control, helper text and error slot. */
+declare interface SelectFieldProps extends SelectBaseProps {
+    variant?: "field";
     label?: string;
     helperText?: string;
     error?: string;
-    options?: SelectOption[];
-    placeholder?: string;
-    wrapperClassName?: string;
 }
 
+export declare interface SelectOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+}
+
+export declare type SelectProps = SelectFieldProps | SelectChipProps;
+
 /**
  * Minimal subset of `@sentry/browser` used by the adapter. Lets you pass
  * either the real SDK module (`import * as Sentry from "@sentry/browser"`)
@@ -13098,6 +13504,11 @@ export declare function stopAudio(): void;
 /**
  * Typed wrapper around `localStorage` that JSON-encodes values and silently
  * handles environments where storage is unavailable (SSR, private mode).
+ *
+ * `get`/`set` encode; `getRaw`/`setRaw` do not. Reach for the raw pair when the
+ * key is shared with something that does not speak JSON — an existing key in an
+ * app adopting this wrapper, a key another library owns, or the theme
+ * preference the SDK's own `ThemeProvider` stores as a bare string.
  */
 export declare const storage: JsonStorage;
 
@@ -14391,6 +14802,22 @@ export declare interface UploadWithProgressOptions {
     headers?: Record<string, string>;
     /** Returns the current bearer token. */
     getToken?: () => string | null | undefined;
+    /**
+     * Origin the `getToken` credential belongs to, normally the API's.
+     *
+     * Unlike `createApiClient`, this helper has no base URL to infer a scope
+     * from — the caller names the destination on every call. Set this when the
+     * `url` can come from somewhere other than your own code (a signed URL the
+     * API handed back, a value from a response body) and the token must not
+     * follow it off-origin. Left unset, the header goes wherever `url` points,
+     * which is the behaviour every version before 0.66.0 had.
+     */
+    credentialOrigin?: string;
+    /**
+     * Extra origins allowed to receive the credential, on top of
+     * {@link credentialOrigin}. Ignored when that one is unset.
+     */
+    trustedOrigins?: readonly string[];
     /** Send cookies. Defaults to false. */
     withCredentials?: boolean;
     /** Called on every `progress` event from the XHR upload channel. */
@@ -15229,6 +15656,12 @@ export declare function useIdle(timeout?: number): boolean;
  * mode, and applies a decline cooldown persisted in `localStorage`. The
  * resulting `method` tells the UI which install affordance to render.
  *
+ * Both sides of that persistence are best-effort: `localStorage` throws in
+ * Safari private mode and in a cross-origin frame with storage blocked, and an
+ * exception raised while resolving an install CTA would take the page down with
+ * it. A refused read means "no decline recorded"; a refused write means the CTA
+ * may come back next visit.
+ *
  * The decline persistence is pluggable through
  * {@link UseInstallPromptOptions.declineStorageKey} and
  * {@link UseInstallPromptOptions.declineCooldownMs} — no app-specific storage