tempest-react-sdk 0.41.0 → 0.42.1

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

@@ -564,13 +564,37 @@ export declare interface ApiClientConfig {
      * Return an empty string to disable the header.
      */
     requestId?: () => string;
-    /** Called on 401 responses. Use it to logout the user or trigger a refresh. */
+    /**
+     * Called when a request ends up unauthorized — a 401 with no `refresh`
+     * configured, a `refresh()` that threw, or a retry that came back 401 again
+     * after a refresh that resolved. Use it to end the session.
+     */
     onUnauthorized?: (response: Response) => void | Promise<void>;
     /**
      * Optional refresh hook. When provided and the original request returns 401,
      * the client awaits `refresh()` then retries the request once.
      */
     refresh?: () => Promise<void>;
+    /**
+     * Retry failed requests with exponential backoff. Off by default, so the
+     * client keeps failing fast unless you opt in.
+     *
+     * `true` uses the built-in policy, which is deliberately conservative: only
+     * idempotent methods (`GET`, `HEAD`, `OPTIONS`) and only failures a retry
+     * can plausibly fix — a network error, `408`, `425`, `429`, or any `5xx`. A
+     * `POST` is never retried on its own, so nothing gets duplicated.
+     *
+     * Pass {@link RetryOptions} to tune it. Supplying your own `shouldRetry`
+     * replaces the built-in policy entirely, method check included — that is the
+     * escape hatch for retrying a write you made idempotent with
+     * {@link generateIdempotencyKey}.
+     *
+     * Retries wrap the whole request, refresh included, and each attempt carries
+     * its own `X-Request-ID`. A `4xx` outside the three listed above is never
+     * retried: repeating an identical request cannot fix a bad payload or a
+     * permission the caller does not have.
+     */
+    retry?: boolean | RetryOptions;
     /** Whether to send cookies on cross-origin requests (default: false). */
     withCredentials?: boolean;
     /** Default headers merged into every request. */
@@ -716,27 +740,6 @@ export declare interface ApplyThemeOptions {
     target?: Document | ShadowRoot | HTMLElement;
 }
 
-/**
- * Apply a move and return the next value.
- *
- * Disabled rows are dropped here rather than at the call site, so no caller can
- * move one by pressing the bulk button — the check has to live where the
- * decision is made, not in each of the four places that trigger one.
- *
- * @param params.value - Current target ids.
- * @param params.moving - Ids being moved.
- * @param params.to - Destination pane.
- * @param params.items - The catalogue, to look disabled rows up.
- * @param params.order - Ids in catalogue order, so the result stays stable.
- * @returns The next value, in catalogue order.
- */
-export declare function applyTransferMove({ value, moving, to, items, }: {
-    value: readonly string[];
-    moving: readonly string[];
-    to: TransferSide;
-    items: readonly TransferItem[];
-}): string[];
-
 /**
  * Compose the Tempest app-wide providers in one place: error boundary →
  * TanStack Query → theme → i18n. Query and theme are on by default; i18n and
@@ -1548,28 +1551,6 @@ export declare const BREAKPOINTS: Record<Breakpoint, number>;
 
 export { BrowserRouter }
 
-/**
- * Parse an error body + response into the Tempest {@link ApiError} envelope.
- *
- * Reads `detail`/`message`, the programmatic `code`, and the correlation id
- * from `details.request_id` (falling back to the `X-Request-ID` header, then
- * the id the client sent).
- *
- * @param status - HTTP status code.
- * @param body - The parsed error body (object, string, or null).
- * @param headers - The response headers (for the `X-Request-ID` fallback).
- * @param sentRequestId - The id the client sent on the request, if any.
- * @returns A fully-populated `ApiError`.
- *
- * @tempest-limits param-count — the arguments are the response as it arrives
- * (`status`, `body`, `headers`) plus the id the request was sent with, and they are
- * passed at exactly one place: the client's response path. Exported from the package
- * root, so the rewrite would be breaking for callers that build their own errors.
- */
-export declare function buildApiError(status: number, body: unknown, headers?: Headers | {
-    get(name: string): string | null;
-}, sentRequestId?: string): ApiError;
-
 /**
  * Builds an `intent://` URL that re-opens the current page inside Chrome on
  * Android. When Chrome is missing, the fallback URL points to the Play Store so
@@ -2019,28 +2000,6 @@ export declare interface ChatRun {
 
 export declare type ChatSection = ChatDay | ChatRun;
 
-/** Labels the thread needs, per locale. */
-declare interface ChatStrings {
-    thread: string;
-    today: string;
-    yesterday: string;
-    you: string;
-    typingOne: (name: string) => string;
-    typingTwo: (a: string, b: string) => string;
-    typingMany: (n: number) => string;
-    sending: string;
-    sent: string;
-    read: string;
-    failed: string;
-    retry: string;
-    empty: string;
-    placeholder: string;
-    send: string;
-}
-
-/** Locale strings for the thread. */
-export declare function chatStrings(locale: "pt-BR" | "en"): ChatStrings;
-
 /**
  * Accessible checkbox. Supports a tri-state via `indeterminate` and pairs the
  * input with a label/description column for forms.
@@ -2116,27 +2075,6 @@ export declare function clamp(value: number, min: number, max: number): number;
 /** Clamp a latitude into the valid `[-90, 90]` range. */
 export declare function clampLatitude(latitude: number): number;
 
-/**
- * Map an unknown `getUserMedia` failure into a {@link MediaAccessError}.
- *
- * The order matters. A missing `navigator.mediaDevices` is almost never "this
- * browser cannot do audio" — it is a page served over plain HTTP, where the whole
- * API is simply absent. Reporting `unsupported` there sends the developer looking
- * for a polyfill for a problem an `https://` URL fixes, so the secure-context check
- * runs first and wins.
- *
- * The `DOMException.name` values are then collapsed into kinds an app can actually
- * branch on, because the raw names do not group the way a UI needs them:
- * `NotFoundError` and `OverconstrainedError` both mean "you will not get a device
- * with these constraints", and `NotReadableError` and `AbortError` both mean "the
- * hardware is busy" — most often another tab of the same app.
- *
- * @param err - Whatever `getUserMedia` (or a device query) rejected with.
- * @param device - Which device was being opened, for the message.
- * @returns A stable kind plus a message safe to show a user.
- */
-export declare function classifyMediaError(err: unknown, device?: MediaDeviceKindLabel): MediaAccessError;
-
 /**
  * Map a thrown WebAuthn failure onto a {@link PasskeyError}.
  *
@@ -2562,9 +2500,29 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
 /**
  * Create a typed HTTP client backed by `fetch`.
  *
- * Handles JSON serialization, query params, bearer auth via `getToken`,
- * automatic refresh + retry on 401 when `refresh` is supplied, and uploads
- * via `FormData`. Throws an `ApiError` on non-2xx responses.
+ * Handles JSON serialization, query params, bearer auth via `getToken`, uploads
+ * via `FormData`, and throws a typed `ApiError` on any non-2xx response.
+ *
+ * **Expired sessions.** A `401` with `refresh` configured awaits the refresh and
+ * replays the request once. `onUnauthorized` fires whenever that path ends
+ * unauthorized anyway — the refresh threw, or the replay came back `401` — which
+ * is the signal to clear the session. Without `refresh`, the first `401` calls
+ * it directly.
+ *
+ * **Retries** are off unless you set `retry`. See {@link ApiClientConfig.retry}
+ * for the built-in policy; it never replays a write.
+ *
+ * @example
+ * const api = createApiClient({
+ *     baseURL: import.meta.env.VITE_API_URL,
+ *     getToken: () => useAuthStore.getState().token,
+ *     refresh,
+ *     onUnauthorized: () => useAuthStore.getState().logout(),
+ *     retry: true,
+ * });
+ *
+ * @param config - Base URL plus the optional auth, retry and fetch hooks.
+ * @returns A client with `request`/`get`/`post`/`put`/`patch`/`delete`/`upload`.
  */
 export declare function createApiClient(config: ApiClientConfig): ApiClient;
 
@@ -3389,8 +3347,13 @@ export declare interface CreateStorePersistOptions<T> {
  * Turn-key auth preset wiring `createAuthStore` + `createRefreshQueue` +
  * `createApiClient` to the Tempest FastAPI SDK auth contract: login returns
  * `{ access_token, token_type }`, requests carry `Authorization: Bearer`, and a
- * `401` triggers a single deduplicated refresh + retry. Logout (or a failed
- * refresh) clears the session.
+ * `401` triggers a single deduplicated refresh + replay.
+ *
+ * The session is cleared whenever that path ends unauthorized anyway — the
+ * refresh threw, or the replay came back `401` — so a refresh token that the
+ * backend has revoked cannot leave the app holding a dead session. With
+ * `redirectTo` set, the browser also leaves the page; without it, clearing the
+ * store is enough for a `<RouteGuard>` to navigate on its own.
  *
  * @example
  * const auth = createTempestAuth<User, { email: string; password: string }>({
@@ -3442,6 +3405,23 @@ export declare interface CreateTempestAuthOptions<TUser> {
      * refresh token is stored, else `undefined` (cookie-based refresh).
      */
     refreshBody?: (refreshToken: string | null) => unknown;
+    /**
+     * Retry policy for `api`, forwarded to {@link createApiClient}. Off by
+     * default; `true` enables the conservative built-in policy, which never
+     * replays a write.
+     */
+    retry?: boolean | RetryOptions;
+    /**
+     * Where to send the browser when the session ends — a hard navigation via
+     * `window.location.assign`, after the store is cleared.
+     *
+     * **Prefer leaving this unset.** `logout()` already clears the store, so a
+     * `<RouteGuard when={isAuthenticated} redirectTo="/login">` wrapped around
+     * the protected area navigates on its own, which keeps the SPA alive and the
+     * router history intact. Reach for this only when the expiry can happen
+     * outside any guarded subtree and a full reload is acceptable.
+     */
+    redirectTo?: string;
 }
 
 /**
@@ -3931,17 +3911,6 @@ export declare interface DateRangePickerProps extends Omit<HTMLAttributes<HTMLDi
     weekStartsOn?: WeekStart_2;
 }
 
-/**
- * Label for a date heading: `"Hoje"`, `"Ontem"`, or the formatted date.
- *
- * @param date - Local midnight of the day being labelled.
- * @param params.now - Reference instant, so tests and SSR-free renders are stable.
- */
-export declare function dayLabel(date: number, { locale, now }?: {
-    locale?: "pt-BR" | "en";
-    now?: number;
-}): string;
-
 /** The visible time window of a day, in minutes from midnight. */
 export declare interface DayWindow {
     startMinute: number;
@@ -4299,16 +4268,6 @@ export declare interface DropzoneProps {
     className?: string;
 }
 
-/**
- * Look up the duration multiplier for a travel mode, falling back to `1.0`
- * for unknown modes. Mirrors `duration_factor` from `tempest-fastapi-sdk`.
- *
- * @param mode - Travel mode.
- * @param factors - Optional override map (partial merges over the defaults).
- * @returns The multiplier for `mode`.
- */
-export declare function durationFactor(mode: TravelMode, factors?: Partial<Record<TravelMode, number>>): number;
-
 /**
  * Mean Earth radius in kilometers. Same value used by `tempest-fastapi-sdk`
  * (`geo/distance.py`) so client and server distances agree.
@@ -5234,33 +5193,6 @@ export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
  */
 export declare function groupBy<T, K extends PropertyKey>(items: T[], key: (item: T) => K): Record<K, T[]>;
 
-/**
- * Turn a flat message list into the sections a thread renders: a date heading
- * whenever the local day changes, and runs of consecutive messages from the same
- * author.
- *
- * Grouping is what makes a thread readable — repeating the avatar and the name on
- * every line of a five-line burst turns a conversation into a list of receipts.
- * The run breaks on a different author, a different day, or a gap longer than
- * `windowMs`: a reply an hour later is a new beat in the conversation even when
- * nobody else spoke, and joining it to the earlier burst would put one timestamp
- * on messages an hour apart.
- *
- * Order is taken as given, oldest first, and never sorted here: a thread that
- * reorders what the server sent would fight optimistic inserts, where the
- * pending message is deliberately last.
- *
- * @param params.messages - Oldest first.
- * @param params.currentUserId - Author id treated as "own".
- * @param params.windowMs - Gap that still keeps a run together. Default 5 min.
- * @returns Sections in render order.
- */
-export declare function groupMessages({ messages, currentUserId, windowMs, }: {
-    messages: readonly ChatMessage[];
-    currentUserId?: string;
-    windowMs?: number;
-}): ChatSection[];
-
 /**
  * Minimal subset of [`@growthbook/growthbook`](https://docs.growthbook.io/lib/js)
  * used by the adapter. Pass a `GrowthBook` instance directly.
@@ -6827,12 +6759,6 @@ export declare interface MenubarProps extends HTMLAttributes<HTMLDivElement> {
     menus: MenubarMenu[];
 }
 
-/**
- * Web Mercator (EPSG:3857) latitude clamp. Latitudes beyond this diverge to
- * infinity in the projection, so tile maps cap here.
- */
-export declare const MERCATOR_MAX_LATITUDE = 85.05112878;
-
 /**
  * A point projected onto the unit Web Mercator plane. Both axes are in `[0, 1]`
  * — `x` grows east, `y` grows south (screen convention).
@@ -6847,20 +6773,6 @@ export declare type Messages = Record<string, string>;
 /** Lifecycle of a microphone stream. */
 export declare type MicrophoneStatus = "idle" | "requesting" | "ready" | "error";
 
-/**
- * The error for "the API is not here at all", which is a different question from
- * "the API rejected".
- *
- * `classifyMediaError` takes a thrown value; a missing `navigator.mediaDevices` never
- * threw one, and handing it `null` would come back `unknown` — the least actionable
- * kind there is. The two real causes are an insecure page (the fix is a URL) and an
- * engine that genuinely cannot capture (the fix is another browser), and telling them
- * apart is the whole point.
- *
- * @param device - Which device was being opened, for the message.
- */
-export declare function missingCaptureApiError(device?: MediaDeviceKindLabel): MediaAccessError;
-
 /**
  * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
  * header/body/footer. Locks body scroll while open.
@@ -7806,14 +7718,6 @@ export { Params }
 /** Query-param values accepted by the API client for a list request. */
 declare type ParamValue = string | number | boolean | undefined | null;
 
-/**
- * Parse a Markdown document into blocks.
- *
- * @param source - Raw Markdown.
- * @returns Block nodes in document order.
- */
-export declare function parseMarkdown(source: string): MarkdownBlock[];
-
 /**
  * Validate an unknown response payload against a zod schema.
  *
@@ -8172,14 +8076,6 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, keys:
  */
 export declare function pickAudioMimeType(preferred?: readonly string[]): string | null;
 
-/**
- * First container in `preferred` the browser can actually produce, or `null`.
- *
- * @param preferred - Candidates, best first.
- * @returns A supported MIME type, or `null` when none is.
- */
-export declare function pickRecordingMimeType(preferred: readonly string[]): string | null;
-
 /**
  * First video container in `preferred` the browser can actually produce, or `null`.
  *
@@ -8966,14 +8862,6 @@ export declare interface ResizableProps extends Omit<HTMLAttributes<HTMLDivEleme
 
 export declare type ResolvedTheme = "light" | "dark";
 
-/**
- * Normalise a language name onto a known grammar.
- *
- * @param language - Whatever the caller passed, e.g. `"ts"` or `"Shell"`.
- * @returns The grammar to use; `"plain"` when there is no match.
- */
-export declare function resolveLanguage(language: string | undefined): CodeLanguage;
-
 /**
  * Responsive value — either a single value applied at all breakpoints, or
  * an object with `mobile` / `tablet` / `desktop` overrides. Apps can mix
@@ -9285,28 +9173,6 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
-/**
- * URL vetting for links and images in rendered Markdown.
- *
- * This is the security boundary of the whole component. Markdown that arrives from
- * a user — a comment, a ticket description, a review — reaches the DOM as a real
- * `href`, and `javascript:alert(1)` in a link is script execution on click. So the
- * scheme is checked against an allowlist rather than a blocklist: a blocklist has
- * to enumerate `javascript:`, `JaVaScRiPt:`, `java\tscript:`, `&#106;avascript:`
- * and whatever comes next, and misses the one nobody thought of.
- */
-/**
- * The href to render, or `null` when the URL must not be linked.
- *
- * Relative URLs (`/docs`, `./x`, `#anchor`, `foo/bar`) are kept: they cannot carry
- * a scheme, so they cannot execute anything, and dropping them would break every
- * in-app link.
- *
- * @param raw - URL as written in the Markdown.
- * @returns A safe href, or `null`.
- */
-export declare function safeLinkUrl(raw: string): string | null;
-
 /** The ten steps of a Tempest tint scale, lightest to darkest. */
 export declare type ScaleStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 
@@ -9482,19 +9348,6 @@ export declare interface SegmentedControlProps<TValue extends string = string> e
  */
 export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
 
-/**
- * Pick the densest mode the payload qualifies for.
- *
- * Numeric packs 3 digits into 10 bits and alphanumeric 2 characters into 11, so
- * a phone number or an upper-case code encodes far smaller than the same string
- * as bytes — often a whole version smaller, which is a visibly coarser symbol
- * and therefore easier to scan.
- *
- * @param text - The payload.
- * @returns The narrowest mode that can represent it.
- */
-export declare function selectMode(text: string): QRMode;
-
 export declare interface SelectOption {
     value: string | number;
     label: string;
@@ -10040,25 +9893,6 @@ export declare interface SpinnerProps {
 
 export declare type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
 
-/**
- * Split the catalogue into the two panes.
- *
- * The selected ids are the single source of truth — the panes are derived, never
- * stored. Two stored lists drift the moment the catalogue changes under them: a
- * permission that is removed upstream lingers in whichever pane held it, and an
- * id that appears in both is a bug nobody can see.
- *
- * Order follows `items`, so both panes read in the catalogue's order rather than
- * in the order somebody happened to click.
- *
- * @param items - The whole catalogue.
- * @param value - Ids currently on the target side.
- */
-export declare function splitTransferSides(items: readonly TransferItem[], value: readonly string[]): {
-    source: TransferItem[];
-    target: TransferItem[];
-};
-
 /** Flex-based vertical or horizontal stack with a numeric `gap`. */
 export declare function Stack({ direction, gap, align, justify, wrap, className, style, children, ...props }: StackProps): JSX.Element;
 
@@ -10593,9 +10427,6 @@ export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAr
     wrapperClassName?: string;
 }
 
-/** The default `<style>` element id owned by {@link applyTheme}. */
-export declare const THEME_STYLE_ID = "tempest-theme";
-
 export declare interface ThemeContextValue {
     /** Raw user preference (light / dark / system). */
     theme: ThemeMode;
@@ -10712,9 +10543,6 @@ export declare function throttle<A extends unknown[]>(fn: (...args: A) => void,
     cancel: () => void;
 };
 
-/** Clock label for a single message — the time, not a relative phrase. */
-export declare function timeLabel(timestamp: number, locale?: "pt-BR" | "en"): string;
-
 /**
  * Vertical event timeline — activity feeds, order trackers, audit logs.
  * Each entry has a marker (color or custom icon), title, optional
@@ -10900,42 +10728,6 @@ export declare interface Token {
     value: string;
 }
 
-/**
- * Split source into coloured tokens.
- *
- * This is a **scanner, not a parser**: it recognises comments, strings, numbers,
- * keywords and punctuation by pattern, and knows nothing about scope, types or
- * grammar. That is a deliberate ceiling. A real parser per language is a
- * dependency the size of the rest of the SDK, and the payoff — being right about
- * the corner cases in a documentation snippet — is small. Where it is unsure it
- * emits `plain`, which renders as ordinary text rather than as something wrong.
- *
- * Unknown languages produce a single `plain` token, so an unhighlighted block is
- * a normal outcome and never an error.
- *
- * @param code - The source.
- * @param language - Grammar name or alias.
- * @returns Tokens covering the input exactly, in order.
- *
- * @example
- * tokenize("const x = 1;", "ts");
- * // [{kind: "keyword", value: "const"}, {kind: "plain", value: " x "}, …]
- */
-export declare function tokenize(code: string, language: string | undefined): Token[];
-
-/**
- * The same tokens, split at newlines so each line can be rendered on its own.
- *
- * Line numbers and highlighted lines both need a per-line structure, and a token
- * is free to span a line break — a block comment usually does. Splitting here
- * keeps that out of the component.
- *
- * @param code - The source.
- * @param language - Grammar name or alias.
- * @returns One token array per line. Always at least one line.
- */
-export declare function tokenizeLines(code: string, language: string | undefined): Token[][];
-
 /** What a token is painted as. */
 export declare type TokenKind = "plain" | "comment" | "string" | "number" | "keyword" | "literal" | "function" | "punctuation" | "tag" | "attribute" | "property";
 
@@ -11289,12 +11081,6 @@ export declare interface TruncateTextProps extends HTMLAttributes<HTMLDivElement
  */
 export declare function turnTime(timestamp: number, locale?: "pt-BR" | "en"): string;
 
-/** The tus protocol version this client speaks. */
-export declare const TUS_VERSION = "1.0.0";
-
-/** Sentence for the typing indicator, or `null` when nobody is typing. */
-export declare function typingLabel(names: readonly string[], locale?: "pt-BR" | "en"): string | null;
-
 /**
  * Remove duplicate items, keeping the first occurrence of each distinct key.
  *
@@ -13959,25 +13745,6 @@ export declare interface ViaCEPResult {
     siafi?: string;
 }
 
-/**
- * Container/codec candidates for video, best first.
- *
- * VP9 in WebM leads because it is the best quality per byte that Chromium and Firefox
- * both encode natively; VP8 is the fallback for older Chromium and for hardware that
- * refuses VP9. `video/mp4` is last and exists for Safari, which produces H.264 in MP4
- * and nothing else — and only since Safari 14.1.
- *
- * Every candidate carries **Opus or AAC audio in the same container**, because a
- * screen recording with the tab's audio dropped is a support ticket, not a
- * simplification. On a stream with no audio track the browser simply omits it.
- *
- * Ported from the intersection of what `MediaRecorder.isTypeSupported` accepts in
- * Chrome 120+, Firefox 115+ and Safari 17. Re-check against
- * <https://developer.mozilla.org/docs/Web/API/MediaRecorder/isTypeSupported> before
- * adding to the list.
- */
-export declare const VIDEO_MIME_CANDIDATES: readonly string[];
-
 /** Imperative video recorder. Same shape as the audio one. */
 export declare type VideoRecorderHandle = MediaRecorderHandle;