tempest-react-sdk 0.65.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
@@ -652,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.
@@ -3266,8 +3296,17 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  * 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
@@ -6443,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;
@@ -6463,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`.
@@ -6481,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
@@ -6512,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
@@ -6556,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.
@@ -6583,6 +6675,19 @@ 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.
  *
@@ -6601,10 +6706,10 @@ export declare function formatDurationMs(value: number): string;
  * @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, options?: FormatPercentOptions): string;
+export declare function formatPercent(value: number | null | undefined, options?: FormatPercentOptions): string;
 
 /** How {@link formatPercent} renders a fraction. */
-export declare interface FormatPercentOptions {
+export declare interface FormatPercentOptions extends FormatFallbackOptions {
     /**
      * Decimal places to show, fixed (padded as well as truncated).
      *
@@ -7866,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;
 
@@ -11670,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.
@@ -11825,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;
     /**
@@ -14617,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. */