tempest-react-sdk 0.79.0 → 0.81.0

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

@@ -15,6 +15,7 @@ import { ComponentType } from 'react';
 import { CompositionEventHandler } from 'react';
 import { Control } from 'react-hook-form';
 import { Controller } from 'react-hook-form';
+import { ControllerFieldState } from 'react-hook-form';
 import { ControllerRenderProps } from 'react-hook-form';
 import { createBrowserRouter } from 'react-router';
 import { createHashRouter } from 'react-router';
@@ -768,6 +769,20 @@ export declare interface ApiClient {
      */
     arrayBuffer(path: string, options?: RequestOptions): Promise<ArrayBuffer>;
     upload<T>(path: string, formData: FormData, method?: "POST" | "PUT" | "PATCH", options?: Omit<RequestOptions, "body" | "method">): Promise<T>;
+    /**
+     * The absolute URL a request to `path` would hit, without sending one.
+     *
+     * For the consumers that cannot go through `fetch` but must land on the
+     * same host: an `EventSource`, an `<img src>`, a download link. Rebuilding
+     * the URL by hand duplicates `baseURL` and `prefix`, and a forgotten prefix
+     * is a silent 404. No credential is attached: the URL is a string, and a
+     * token placed in it would end up in every proxy log.
+     *
+     * @param path - Path joined onto the client's base URL and prefix.
+     * @param params - Query params to append; `undefined` and `null` are skipped.
+     * @returns The absolute URL.
+     */
+    url(path: string, params?: RequestOptions["params"]): string;
 }
 
 export declare interface ApiClientConfig {
@@ -856,7 +871,10 @@ export declare interface ApiClientConfig {
      * Never logs a body, a header, or the query string — a bearer token in
      * `Authorization`, a password in a login payload and an `access_token` query
      * param would all end up in whatever the sink writes to. What is logged is
-     * the method, the path as the call site wrote it, and the numbers.
+     * the method, the path and the numbers. The path is cut at the first `?` or
+     * `#`, and an absolute URL loses its `user:password@`, so a query written
+     * into the path (`"/files?access_token=…"`) or the signature of a presigned
+     * URL stays out just like `params` does.
      */
     logger?: ApiClientLogger;
     /**
@@ -1769,6 +1787,152 @@ export declare interface AudioRecording {
     durationMs: number;
 }
 
+/**
+ * An e-mail field: trimmed and lower-cased *before* it is validated.
+ *
+ * The order is the point. Validating first rejects `" ana@x.com"` pasted with a
+ * trailing space from a password manager, and a backend that compares e-mails
+ * case-sensitively creates a second account for `Ana@x.com`. An empty value gets
+ * its own sentence instead of "e-mail inválido", which reads like an accusation
+ * on a field the user simply has not reached yet.
+ *
+ * @returns A schema producing the normalized address.
+ */
+export declare function authEmail(): z.ZodPipe<z.ZodString, z.ZodEmail>;
+
+/**
+ * One entry of an auth form's `fields` list.
+ *
+ * The form is generated from this list, so the app declares *which* fields and
+ * *how they read* — never the markup, the wiring to react-hook-form or the error
+ * slot.
+ *
+ * @typeParam TName - The schema's keys, so a typo in `name` fails to compile.
+ */
+export declare interface AuthField<TName extends string = string> {
+    /** Key in the schema and in the submitted values. */
+    name: TName;
+    /** Visible label. Rich content works for `checkbox` (a terms link); keep it text for `pin`. */
+    label: ReactNode;
+    /** Control used to render it. Default `"text"`. */
+    type?: AuthFieldType;
+    /** Placeholder shown while the field is empty. */
+    placeholder?: string;
+    /**
+     * `autocomplete` token. Defaults per type: `email` → `"email"`, `password` →
+     * `"current-password"`, `phone` → `"tel"`. Sign-up and reset presets pass
+     * `"new-password"` so password managers offer to generate one.
+     */
+    autoComplete?: string;
+    /** Help text under the field, replaced by the error when there is one. */
+    helperText?: ReactNode;
+    /** Marks the control as required (visual hint + native attribute). */
+    required?: boolean;
+    /** `password` only: show the strength meter under the field. */
+    showStrength?: boolean;
+    /** `pin` only: number of cells. Default `6`. */
+    length?: number;
+    /** Render the control yourself — for a field none of the types covers. */
+    render?: (props: AuthFieldRenderProps) => ReactNode;
+}
+
+/** The field names a schema accepts. */
+export declare type AuthFieldName<TSchema extends z.ZodTypeAny> = Extract<keyof z.infer<TSchema>, string>;
+
+/** What a field's `render` receives: the react-hook-form binding plus the field's own config. */
+export declare interface AuthFieldRenderProps {
+    /** `name`, `value`, `onChange`, `onBlur` and `ref` — spread or wire them into the control. */
+    field: ControllerRenderProps<FieldValues, string>;
+    /** The field's validation state, including the server error mapped onto it. */
+    fieldState: ControllerFieldState;
+    /** The current error message, already resolved from `fieldState`. */
+    error?: string;
+    /** The config entry this field was declared with. */
+    config: AuthField;
+}
+
+/**
+ * Which SDK control renders a field.
+ *
+ * `text` and `email` → `Input`, `password` → `PasswordInput`, `phone` / `cpf` /
+ * `cnpj` → the masked inputs, `checkbox` → `Checkbox`, `pin` → `PinInput`. The
+ * list is closed on purpose: these are the controls an auth screen uses, and
+ * anything else goes through `render`.
+ */
+export declare type AuthFieldType = "text" | "email" | "password" | "phone" | "cpf" | "cnpj" | "checkbox" | "pin";
+
+/**
+ * A complete auth form generated from a list of field configs and a zod schema.
+ *
+ * Every hand-built login and sign-up screen repeated the same wiring: a
+ * `useZodForm`, one labelled input per field with its error slot, a password eye,
+ * a submit button disabled while the request runs, and a `catch` that copied the
+ * 422's field messages back onto the inputs. The app now declares *which* fields
+ * and *what happens on submit*; the rest is here, built on the SDK's own controls
+ * and its forms layer (`useZodForm` + `FormProvider` + `FormField`).
+ *
+ * Errors thrown by `onSubmit` are shown, never rethrown — a rethrow from a submit
+ * handler is an unhandled rejection with nowhere to go. A `TempestApiError` whose
+ * `fields` name fields of this form marks them; anything else, and any field
+ * message that matched no declared field, goes to an `Alert` above the fields,
+ * worded by `describeApiError`. Pass `onError` to log.
+ *
+ * @example
+ * const schema = z.object({ email: z.email("E-mail inválido") });
+ * <AuthForm
+ *     schema={schema}
+ *     fields={[{ name: "email", type: "email", label: "E-mail" }]}
+ *     submitLabel="Continuar"
+ *     onSubmit={async (values) => { await api.post("/auth/magic-link", { body: values }); }}
+ * />
+ */
+export declare function AuthForm<TSchema extends z.ZodTypeAny>({ schema, fields, onSubmit, submitLabel, defaultValues, beforeSubmit, afterSubmit, social, labels, errorOptions, onError, className, }: AuthFormProps<TSchema>): ReactNode;
+
+/** Fixed sentences of {@link AuthFormProps}, PT-BR by default. */
+export declare interface AuthFormLabels {
+    /** Text of the divider drawn above the `social` slot. Default `"ou"`. */
+    divider: string;
+    /**
+     * Fallback sentence of the error alert, when the thrown error carries nothing
+     * better. Default `"Não foi possível concluir agora. Tente de novo."`.
+     */
+    error: string;
+}
+
+export declare interface AuthFormProps<TSchema extends z.ZodTypeAny> {
+    /** Zod schema validating the values; its messages are what each field shows. */
+    schema: TSchema;
+    /** The fields, in display order. */
+    fields: readonly AuthField<AuthFieldName<TSchema>>[];
+    /**
+     * Called with the validated values. Throw to fail: a `TempestApiError` whose
+     * `fields` name fields of this form marks those fields; any other error shows
+     * an alert above the form.
+     */
+    onSubmit: (values: z.infer<TSchema>) => Promise<void> | void;
+    /** Submit button content. Default `"Enviar"`. */
+    submitLabel?: ReactNode;
+    /** Initial values. Fields left out start as `""` (`false` for checkboxes). */
+    defaultValues?: Partial<z.input<TSchema>>;
+    /** Content between the fields and the submit button — the "forgot password" link. */
+    beforeSubmit?: ReactNode;
+    /** Content after the submit button — the "no account? sign up" line. */
+    afterSubmit?: ReactNode;
+    /** Social sign-in buttons. Rendered under a divider reading `labels.divider`. */
+    social?: ReactNode;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<AuthFormLabels>;
+    /** Passed to `describeApiError` to word the alert — map error `codes`, `statuses`. */
+    errorOptions?: DescribeApiErrorOptions;
+    /** Called with every error `onSubmit` threw, after it is shown — for logging. */
+    onError?: (error: unknown) => void;
+    /** Class name for the `<form>`. */
+    className?: string;
+}
+
+/** The value object a schema produces, as react-hook-form sees it. */
+export declare type AuthFormValues<TSchema extends z.ZodTypeAny> = z.infer<TSchema> & FieldValues;
+
 /**
  * Router-agnostic auth gate. The caller decides what to render in either
  * branch — typically `<Outlet />` for protected layouts and `<Navigate />` for
@@ -1793,6 +1957,122 @@ export declare interface AuthGuardProps {
     fallback: ReactNode;
 }
 
+/**
+ * The layout shell of a sign-in, sign-up or password-recovery screen.
+ *
+ * Every app was hand-building the same page around its form: a colored top with
+ * the logo and a back button over a white sheet with rounded top corners on
+ * mobile, a 50/50 brand panel and form on desktop, a "Bem-vindo!" heading. This
+ * component is that page, so the app passes only the brand and the form.
+ *
+ * The switch between the two layouts is a JavaScript media query, not a CSS
+ * `@media` rule, because the breakpoint is a prop: a CSS media query cannot read a
+ * custom property. `useMediaQuery` evaluates synchronously on the first render, so
+ * a client-rendered page does not flash the wrong layout.
+ *
+ * @example
+ * <AuthPage brand={<img src="/logo.svg" alt="Acme" />} back="/" title="Bem-vindo!">
+ *     <LoginForm onSubmit={signIn} links={{ forgotPassword: "/recuperar", signUp: "/cadastro" }} />
+ * </AuthPage>
+ */
+export declare function AuthPage({ brand, title, subtitle, aside, variant, breakpoint, back, footer, headingLevel, as, children, className, style, ...props }: AuthPageProps): ReactNode;
+
+/** The brand panel of a `split` page — the colored half on desktop, the colored top on mobile. */
+export declare interface AuthPageAside {
+    /**
+     * Any CSS `background` value: a color, a token, a gradient, an image.
+     * Defaults to `var(--tempest-primary)`, so a themed app gets its brand color
+     * without passing anything.
+     */
+    background?: string;
+    /**
+     * Text color over that background. Defaults to `var(--tempest-text-on-primary)`,
+     * which is only right while the background is the primary color — set it
+     * together with a custom `background` so the back button and the app name
+     * keep their contrast.
+     */
+    color?: string;
+    /** Extra content under the brand on the panel: a tagline, an illustration. */
+    content?: ReactNode;
+}
+
+/** The back action, as an object when the label or the behavior is not the default. */
+export declare interface AuthPageBackAction {
+    /** Route to navigate to, rendered as a router `Link`. */
+    to?: string;
+    /** Visible label (and accessible name). Default `"Voltar"`. */
+    label?: string;
+    /** Click handler — used alone (a `<button>`) or together with `to`. */
+    onClick?: () => void;
+}
+
+/** Heading level of the page title. */
+export declare type AuthPageHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export declare interface AuthPageProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Logo and/or app name, shown on the brand panel (split) or at the top of the card. */
+    brand?: ReactNode;
+    /** Page title, rendered as a heading — e.g. `"Bem-vindo!"`. */
+    title?: ReactNode;
+    /** Line under the title — e.g. `"Entre com sua conta para continuar"`. */
+    subtitle?: ReactNode;
+    /** Brand panel colors and extra content. */
+    aside?: AuthPageAside;
+    /**
+     * `split` (default): colored top + rounded white sheet below `breakpoint`,
+     * 50/50 brand panel and form at or above it. `card`: one centered card at
+     * every width — the internal-panel login.
+     */
+    variant?: AuthPageVariant;
+    /**
+     * Viewport width, in px, at which `split` turns into two columns. Default
+     * `768`, the width every hand-built auth screen this replaces switched at —
+     * deliberately not the `1024` of `useBreakpoint`, which is about navigation
+     * chrome, not about whether a form fits beside a brand panel.
+     */
+    breakpoint?: number;
+    /** Back action: a route string, or an object with `to`/`label`/`onClick`. Omit to hide it. */
+    back?: string | AuthPageBackAction;
+    /** Content under the form, inside the sheet or card — legal text, a secondary link. */
+    footer?: ReactNode;
+    /** Heading level of `title`. Default `1`, since the auth screen is usually the whole page. */
+    headingLevel?: AuthPageHeadingLevel;
+    /**
+     * Root element. Default `"main"`, the page's main landmark. Use `"div"` when
+     * the page is rendered inside a layout that already owns a `<main>` — two
+     * nested main landmarks are an accessibility violation.
+     */
+    as?: "main" | "div";
+    /** The form — usually an `AuthForm` or one of its presets. */
+    children?: ReactNode;
+}
+
+/** How the page is laid out: brand panel beside the form, or one centered card. */
+export declare type AuthPageVariant = "split" | "card";
+
+/**
+ * A password field with the minimum length every Tempest backend enforces.
+ *
+ * @param message - Sentence shown below 8 characters.
+ * @returns The password schema.
+ */
+export declare function authPassword(message?: string): z.ZodString;
+
+/**
+ * Props every preset (`LoginForm`, `SignUpForm`, …) shares.
+ *
+ * `schema` and `fields` become optional — the preset ships both — and the slots
+ * around the submit button are the preset's to fill, from its `links`.
+ *
+ * @typeParam TSchema - The schema in use; the preset's default when none is passed.
+ */
+export declare interface AuthPresetProps<TSchema extends z.ZodTypeAny> extends Omit<AuthFormProps<TSchema>, "schema" | "fields" | "labels" | "beforeSubmit" | "afterSubmit"> {
+    /** Replaces the preset's schema. Pair it with `fields` when it adds or renames keys. */
+    schema?: TSchema;
+    /** Replaces the preset's field list. */
+    fields?: readonly AuthField<AuthFieldName<TSchema>>[];
+}
+
 export declare interface AuthState<TUser> {
     user: TUser | null;
     token: string | null;
@@ -2417,7 +2697,10 @@ export { BrowserRouter }
  *
  * A path that is itself an absolute URL wins over all of this, which is how a
  * client reaches a second host (a signed upload endpoint, a CDN) without a
- * second client.
+ * second client. Without `params` it is returned exactly as given: a signed
+ * URL covers its query, and a round trip through `URL` re-encodes characters
+ * outside the canonical form (`'` became `%27`, measured), which is a rewrite
+ * of a string the server signed.
  *
  * @example
  * buildApiUrl("https://api.example.com", "/auth/login", { prefix: "/api" });
@@ -4220,11 +4503,15 @@ export declare function createDataProvider(client: ApiClient, options?: DataProv
  * `onMessage`. Pass `withCredentials: true` when the backend authenticates via
  * cookies. Call `close()` from the returned controller to tear down.
  *
- * @param url - Full SSE endpoint URL.
+ * When `url` is a function it is called before every connection, so a
+ * reconnect presents a fresh credential instead of the one that expired. A
+ * resolution still pending when `close()` or `reconnect()` runs is discarded.
+ *
+ * @param url - Full SSE endpoint URL, or a function returning it per connection.
  * @param options - Stream configuration and callbacks.
  * @returns A controller exposing `close`, `reconnect` and the current `status`.
  */
-export declare function createEventStream<T = unknown>(url: string, options?: CreateEventStreamOptions<T>): EventStreamController;
+export declare function createEventStream<T = unknown>(url: EventStreamUrl, options?: CreateEventStreamOptions<T>): EventStreamController;
 
 export declare interface CreateEventStreamOptions<T> {
     /** Send cookies with the EventSource handshake. Default: false. */
@@ -4279,6 +4566,21 @@ export declare interface CreateEventStreamOptions<T> {
      * `isDevBuild()` to be able to answer, and this callback is the app's own.
      */
     onValidationError?: (issues: SchemaIssue[], raw: string) => void;
+    /**
+     * The URL function threw or rejected, so no connection was attempted.
+     *
+     * `onError` cannot carry this: it receives the `EventSource` `Event`, and a
+     * URL that never resolved never had an `EventSource`.
+     */
+    onUrlError?: (error: unknown) => void;
+    /**
+     * Whether a URL-resolution failure is worth another attempt. Default: always.
+     *
+     * Return `false` for failures no backoff can fix — a `401` or a `403` when
+     * fetching a ticket is a session decision, not a network blip — and the stream
+     * stops at `status: "error"` instead of spending `maxRetries` on it.
+     */
+    shouldRetryUrl?: (error: unknown) => boolean;
     onOpen?: () => void;
     onMessage?: (message: EventStreamMessage<T>) => void;
     onError?: (error: Event) => void;
@@ -5216,6 +5518,17 @@ export declare interface CreateStorePersistOptions<T> {
  * without a working revocation, that boot `refresh()` restores the previous
  * account for whoever uses the browser next.
  *
+ * With `storage: "local"` the session belongs to the **origin**, not the tab:
+ * every tab reads and writes the same keys and follows what another tab wrote
+ * — on the `storage` event and, before any refresh, `logout()` or ending of
+ * the session, by comparing the stored session with the one it holds. A
+ * rotation elsewhere is adopted; a logout or another account's login
+ * elsewhere ends the session here too, with `onSessionEnd` told it happened
+ * `elsewhere`. Before 0.81.0 a tab left open after logout kept account A and,
+ * on its next `401`, redeemed account B's refresh token from the shared
+ * storage, persisting `{ user: A, token: B }` (#524). `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
  * replays with the new token and refreshes nothing. Three expired requests take
@@ -5478,6 +5791,35 @@ export declare interface CreateThemeOptions {
     inverseSelector?: string;
 }
 
+/**
+ * Open the ticket-authenticated stream of the `tempest-fastapi-sdk` SSE router.
+ *
+ * `POST <prefix>/ticket` through the authenticated client, then
+ * `GET <prefix>/stream?ticket=…` — and again for every reconnect, because the
+ * ticket only opens streams for `expires_in` seconds and a reconnect after that
+ * with the old one is a `401`. A ticket request refused with a status no
+ * backoff fixes (`401`, `403 ACCOUNT_INACTIVE`) stops the stream at
+ * `status: "error"` and reaches `onUrlError`; pass `shouldRetryUrl` to replace
+ * {@link isRetriableTicketError}.
+ *
+ * The access token never enters the URL: it travels as the client's header (or
+ * cookie) on the ticket request, and the ticket in the URL opens that stream
+ * and nothing else.
+ *
+ * @example
+ * const stream = createTicketEventStream<Notification>({
+ *     client: api,
+ *     onMessage: ({ data }) => addNotification(data),
+ *     onUrlError: (error) => toast.error(describeApiError(error)),
+ * });
+ *
+ * @param options - Ticket source plus every {@link createEventStream} option.
+ * @returns The stream controller.
+ */
+export declare function createTicketEventStream<T = unknown>(options: CreateTicketEventStreamOptions<T>): EventStreamController;
+
+export declare type CreateTicketEventStreamOptions<T> = TicketEventStreamSource & CreateEventStreamOptions<T>;
+
 /**
  * Record a video stream — a camera, a screen share, or a `canvas.captureStream()`.
  *
@@ -6489,6 +6831,9 @@ export declare function deepMerge<T>(target: T, source: Partial<T>): T;
  */
 export declare const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings;
 
+/** PT-BR defaults of {@link AuthFormLabels}. */
+export declare const DEFAULT_AUTH_FORM_LABELS: AuthFormLabels;
+
 /**
  * What a scanner looks for when you do not say.
  *
@@ -7326,6 +7671,19 @@ export declare interface EventStreamMessage<T> {
 
 export declare type EventStreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
 
+/**
+ * Where the stream connects: a fixed URL, or a function resolved again before
+ * every connection, the first one and each reconnect.
+ *
+ * The function form exists for short-lived credentials carried in the URL,
+ * such as the `?ticket=` of the `tempest-fastapi-sdk` SSE router. `EventSource`
+ * cannot send headers, so the credential has to ride in the query, and one that
+ * expires makes a fixed URL a trap: the reconnect after the expiry presents the
+ * same dead credential, gets a `401`, and burns every retry on it while the user
+ * is still signed in.
+ */
+export declare type EventStreamUrl = string | (() => string | Promise<string>);
+
 /**
  * Finish a `tempest-fastapi-sdk` social login from the SPA's callback route.
  *
@@ -7812,6 +8170,51 @@ declare type FloatingActionButtonVariant = "primary" | "surface";
  */
 export declare function For<T>({ each, children, fallback }: ForProps<T>): ReactNode;
 
+/** Default fields of `ForgotPasswordForm`: the e-mail, with a line saying what happens next. */
+export declare const FORGOT_PASSWORD_FIELDS: readonly AuthField<"email">[];
+
+/**
+ * "Forgot password" form: the e-mail the reset link goes to.
+ *
+ * The confirmation screen after a successful submit is the app's call — most
+ * backends answer the same whether or not the address exists, so the copy
+ * belongs next to the backend's policy, not here.
+ *
+ * @example
+ * const [sent, setSent] = useState(false);
+ * <ForgotPasswordForm
+ *     onSubmit={async (values) => { await api.post("/auth/forgot-password", { body: values }); setSent(true); }}
+ *     links={{ signIn: "/login" }}
+ * />
+ */
+export declare function ForgotPasswordForm<TSchema extends z.ZodTypeAny = typeof forgotPasswordSchema>({ schema, fields, links, labels, submitLabel, ...props }: ForgotPasswordFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link ForgotPasswordForm}, PT-BR by default. */
+export declare interface ForgotPasswordFormLabels extends AuthFormLabels {
+    /** Default `"Lembrou a senha?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+}
+
+/** Routes the forgot-password form links to. */
+export declare interface ForgotPasswordFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface ForgotPasswordFormProps<TSchema extends z.ZodTypeAny = typeof forgotPasswordSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: ForgotPasswordFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<ForgotPasswordFormLabels>;
+}
+
+/** Default schema of `ForgotPasswordForm`: the e-mail the reset link goes to. */
+export declare const forgotPasswordSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+}, z.core.$strip>;
+
 /**
  * Form wrapper with a built-in layout variant. Replaces ad-hoc `<form>` +
  * `<Stack>` / `<Grid>` boilerplate; pair with [[FormRow]], [[FormSection]],
@@ -8868,6 +9271,43 @@ export declare interface InstallBackgroundSyncOptions {
      * persisting and replaying every header, credentials included.
      */
     credentialHeaders?: readonly string[];
+    /**
+     * Origins besides the worker's own that a replayed request may carry a
+     * credential header to — typically the API host when it is not the app's
+     * origin (`["https://api.acme.com"]`). Default `[]`: only the worker's origin.
+     *
+     * A credential re-applied at replay comes from the page, so it is the app's
+     * credential, whatever the request originally carried under the same header
+     * name. Before 0.81.0 the worker checked only the name, and a mutation to a
+     * third party that failed offline carrying that party's `Authorization` was
+     * replayed to it with the app's bearer (#523). Now, with the rule
+     * `isTrustedCredentialTarget` enforces on the live `ApiClient`:
+     * - an entry that carried a credential header to an origin outside this
+     *   scope is dropped before `beforeReplay` runs — re-sending it without the
+     *   credential would be a request the app never made, and with the app's
+     *   credential, a leak;
+     * - a request returned by `beforeReplay` (custom or default) that carries a
+     *   header from `credentialHeaders` to an origin outside this scope is
+     *   dropped instead of sent.
+     *
+     * Both drops warn once per origin per replay in development builds. Entries
+     * with no credential header are not affected: the browser attaches that
+     * origin's own cookies, as it did on the original attempt.
+     */
+    trustedOrigins?: readonly string[];
+    /**
+     * How an `"unknown"` owner is handled on an entry with no stripped
+     * credentials (see {@link BackgroundSyncOwnerPolicy}). Default `"strict"`.
+     *
+     * `"lenient"` restores the replay-as-is of 0.77.0 and earlier for an app without sign-in,
+     * where no page ever reports a principal. Do not use it with a cookie
+     * session: the browser attaches on replay the cookie of whoever is signed in
+     * at that moment, so a mutation queued by A whose owner was never stamped
+     * (issuing tab closed, empty `clientId`, stamp lost, legacy entry) goes out
+     * with B's session. Entries with stripped credentials ask the pages either
+     * way. Ignored when a custom `beforeReplay` is given.
+     */
+    ownerPolicy?: BackgroundSyncOwnerPolicy;
     /**
      * Prepare each queued request right before it is replayed: return the
      * request to send (typically with the current credentials applied) or
@@ -8895,20 +9335,11 @@ export declare interface InstallBackgroundSyncOptions {
      * `maxRetentionMinutes` (and warns once per replay in development builds) —
      * so a page that never calls {@link provideBackgroundSyncCredentials} leaves
      * every entry it queued `"unknown"`, and none of them is replayed.
-     */
-    /**
-     * How an `"unknown"` owner is handled on an entry with no stripped
-     * credentials (see {@link BackgroundSyncOwnerPolicy}). Default `"strict"`.
      *
-     * `"lenient"` restores the replay-as-is of 0.77.0 and earlier for an app without sign-in,
-     * where no page ever reports a principal. Do not use it with a cookie
-     * session: the browser attaches on replay the cookie of whoever is signed in
-     * at that moment, so a mutation queued by A whose owner was never stamped
-     * (issuing tab closed, empty `clientId`, stamp lost, legacy entry) goes out
-     * with B's session. Entries with stripped credentials ask the pages either
-     * way. Ignored when a custom `beforeReplay` is given.
+     * Whatever the hook returns is still held to `trustedOrigins`: a credential
+     * header bound for an origin outside the worker's own and `trustedOrigins` is
+     * never sent.
      */
-    ownerPolicy?: BackgroundSyncOwnerPolicy;
     beforeReplay?: (request: Request, context: BackgroundSyncReplayContext) => Request | null | Promise<Request | null>;
 }
 
@@ -9478,6 +9909,21 @@ export declare function isRejectionCloseCode(code: number): boolean;
  */
 export declare function isRetriableStatus(status: number): boolean;
 
+/**
+ * Whether a failure to obtain a ticket is worth another attempt.
+ *
+ * Only a failure the backoff can outlast is: no response at all, a timeout, a
+ * rate limit, a `5xx`. A `401` reached the caller after the client already
+ * tried its refresh, and a `403` (`ACCOUNT_INACTIVE`) is the backend saying no;
+ * both are session decisions, and retrying them only delays the error state the
+ * app has to show. Anything that is not an API error is a contract mismatch,
+ * which a retry cannot fix either.
+ *
+ * @param error - What the ticket request threw.
+ * @returns Whether to schedule a reconnect.
+ */
+export declare function isRetriableTicketError(error: unknown): boolean;
+
 export { isRouteErrorResponse }
 
 /** Whether `getDisplayMedia` is reachable at all. */
@@ -10227,6 +10673,64 @@ export declare interface LoggerSink {
     (entry: LogEntry): void;
 }
 
+/**
+ * Default fields of `LoginForm`: e-mail and password.
+ *
+ * Exported, like the other presets' lists, so an app extends the defaults
+ * (`[...LOGIN_FIELDS, { name: "remember", type: "checkbox", … }]`) instead of
+ * retyping them.
+ */
+export declare const LOGIN_FIELDS: readonly AuthField<"email" | "password">[];
+
+/**
+ * Sign-in form: e-mail and password, "forgot password" link, sign-up line and a
+ * slot for social buttons.
+ *
+ * `AuthForm` with the defaults every app wrote by hand: the e-mail trimmed and
+ * lower-cased before validation, `current-password` autocomplete so the saved
+ * password is offered, and the two links in the place users look for them. What
+ * happens on success — storing the session, redirecting — stays in `onSubmit`.
+ *
+ * @example
+ * <LoginForm
+ *     onSubmit={async (values) => { await auth.login(values); navigate("/"); }}
+ *     links={{ forgotPassword: "/recuperar-senha", signUp: "/cadastro" }}
+ *     social={<GoogleSignIn component={GoogleLogin} onSuccess={signInWithGoogle} />}
+ * />
+ */
+export declare function LoginForm<TSchema extends z.ZodTypeAny = typeof loginSchema>({ schema, fields, links, labels, submitLabel, ...props }: LoginFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link LoginForm}, PT-BR by default. */
+export declare interface LoginFormLabels extends AuthFormLabels {
+    /** Default `"Esqueceu a senha?"`. */
+    forgotPassword: string;
+    /** Default `"Não tem uma conta?"`. */
+    signUpPrompt: string;
+    /** Default `"Cadastre-se"`. */
+    signUp: string;
+}
+
+/** Routes the login form links to. Each link is rendered only when its route is set. */
+export declare interface LoginFormLinks {
+    /** "Esqueceu a senha?" link, above the submit button. */
+    forgotPassword?: string;
+    /** "Cadastre-se" link, under the form. */
+    signUp?: string;
+}
+
+export declare interface LoginFormProps<TSchema extends z.ZodTypeAny = typeof loginSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: LoginFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<LoginFormLabels>;
+}
+
+/** Default schema of `LoginForm`: normalized e-mail + password of at least 8 characters. */
+export declare const loginSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+}, z.core.$strip>;
+
 export declare type LogLevel = "debug" | "info" | "warn" | "error";
 
 /**
@@ -11610,9 +12114,22 @@ export declare interface OfflineSync<TPayload> {
     pendingCount: () => Promise<number>;
     /** The queued mutations in FIFO order. */
     listPending: () => Promise<OutboxEntry<TPayload>[]>;
-    /** Drop every queued mutation (e.g. on logout). */
+    /**
+     * Drop every queued mutation (e.g. on logout).
+     *
+     * Also ends the current session for any `flush` already in flight: that run
+     * delivers no further entry, pulls and applies nothing more and writes no
+     * watermark, and resolves with `interrupted: true`. A `flush` called after this
+     * starts a fresh run instead of joining the abandoned one.
+     */
     clearOutbox: () => Promise<void>;
-    /** Reset the pull watermark (e.g. on logout / account switch). */
+    /**
+     * Reset the pull watermark (e.g. on logout / account switch).
+     *
+     * Ends the current session for an in-flight `flush` exactly like
+     * {@link OfflineSync.clearOutbox}, so the run cannot write the ended
+     * session's watermark back after the reset.
+     */
     resetWatermark: () => void;
     /** Read the current reactive {@link SyncState} snapshot synchronously. */
     getState: () => SyncState;
@@ -12926,6 +13443,22 @@ export declare type PreloadableLazy<T extends AnyComponent> = ReturnType<typeof
     }>;
 };
 
+/**
+ * A pre-signed `POST` form, as `tempest-fastapi-sdk` >= 0.331.0 hands it out
+ * (`presigned_post_policy` / `SubjectObjectStorage.presign_post`).
+ *
+ * Snake case on purpose: this is the wire shape, so it parses straight from the
+ * response of the app's own route.
+ */
+export declare interface PresignedPost {
+    /** Where the form is posted: the bucket on S3/MinIO, or the API itself on the local backend. */
+    url: string;
+    /** Form fields to send before the file, in this order — `key`, `policy`, signature and the rest. */
+    fields: Record<string, string>;
+    /** Largest file the policy accepts, in bytes. */
+    max_bytes: number;
+}
+
 /** A model whose cached size should appear in the report. */
 export declare interface ProfiledModel {
     /** Label for the report row, e.g. `"detector"`. */
@@ -12996,9 +13529,15 @@ export declare function projectMercator(coord: Coordinate): MercatorPoint;
  * keeps an entry pending when one it stripped is missing), or `null` when there
  * is no session — the worker then drops the entry instead of replaying it
  * anonymously. A throw from `getHeaders` or `getPrincipal` is answered as an
- * explicit `{ error: true }`. The worker only applies headers whose names the
- * original request carried, so returning `Authorization` for every URL never
- * leaks it to a URL that did not receive it in the first place.
+ * explicit `{ error: true }`.
+ *
+ * The worker applies only the header names the original request carried, and
+ * only to the worker's own origin or the `trustedOrigins` given to
+ * {@link installBackgroundSync}: an entry bound for any other origin is dropped
+ * without asking this page. Matching the name is not enough on its own — a
+ * request to a third party carries *that party's* `Authorization`, and until
+ * 0.81.0 its replay received the app's bearer (#523). `getHeaders` still gets
+ * the URL, for an app whose trusted origins need different credentials.
  *
  * Pass `getPrincipal` to bind each entry to whoever queued it: the worker asks
  * the issuing tab right after queueing, asks every tab again before replaying,
@@ -13848,6 +14387,68 @@ export declare interface RequestOptions extends Omit<RequestInit, "body"> {
  */
 export declare function requestPersistentStorage(): Promise<boolean>;
 
+/** Default fields of `ResetPasswordForm`: new password (with strength meter) and confirmation. */
+export declare const RESET_PASSWORD_FIELDS: readonly AuthField<"password" | "confirmPassword">[];
+
+/**
+ * "Choose a new password" form: password and confirmation, with the mismatch
+ * reported under the confirmation field.
+ *
+ * The reset token stays out of the fields: it comes from the URL, and the app
+ * adds it in `onSubmit` — `{ ...values, token }` — where it also decides what an
+ * expired token looks like.
+ *
+ * @example
+ * const [params] = useSearchParams();
+ * <ResetPasswordForm
+ *     hints={["Pelo menos 8 caracteres"]}
+ *     onSubmit={async (values) => {
+ *         await api.post("/auth/reset-password", { body: { ...values, token: params.get("token") } });
+ *     }}
+ * />
+ */
+export declare function ResetPasswordForm<TSchema extends z.ZodTypeAny = typeof resetPasswordSchema>({ schema, fields, hints, links, labels, submitLabel, ...props }: ResetPasswordFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link ResetPasswordForm}, PT-BR by default. */
+export declare interface ResetPasswordFormLabels extends AuthFormLabels {
+    /** Default `"Lembrou a senha?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+    /** Accessible name of the hints list. Default `"Requisitos da senha"`. */
+    hints: string;
+}
+
+/** Routes the reset-password form links to. */
+export declare interface ResetPasswordFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface ResetPasswordFormProps<TSchema extends z.ZodTypeAny = typeof resetPasswordSchema> extends AuthPresetProps<TSchema> {
+    /**
+     * Password requirements listed above the submit button ("Pelo menos 8
+     * caracteres", "Uma letra maiúscula"). Kept as text the app writes, because
+     * only the backend knows its rules.
+     */
+    hints?: ReactNode[];
+    /** Where the links go. */
+    links?: ResetPasswordFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<ResetPasswordFormLabels>;
+}
+
+/**
+ * Default schema of `ResetPasswordForm`: new password and its confirmation.
+ *
+ * The mismatch is reported on `confirmPassword` (`path`), so the message lands
+ * under the field the user has to fix rather than in a form-level alert.
+ */
+export declare const resetPasswordSchema: z.ZodObject<{
+    password: z.ZodString;
+    confirmPassword: z.ZodString;
+}, z.core.$strip>;
+
 /**
  * A two-pane split layout with a draggable divider. The first pane is sized via
  * `flex-basis` as a percentage; the second pane fills the rest. Drag the divider
@@ -15484,6 +16085,9 @@ export declare interface SidebarSeparator {
     key: string;
 }
 
+/** Default fields of `SignUpForm`: name, e-mail and a password with strength meter. */
+export declare const SIGN_UP_FIELDS: readonly AuthField<"name" | "email" | "password">[];
+
 /**
  * Signature capture on a canvas — the "sign here" field of a delivery receipt,
  * a service order, a term of acceptance.
@@ -15555,6 +16159,59 @@ export declare interface SignaturePadProps {
     className?: string;
 }
 
+/**
+ * Sign-up form: name, e-mail and password by default, plus the "Já tem uma conta?"
+ * line.
+ *
+ * Apps differ most here — a phone, a CPF, a terms checkbox — so the usual call
+ * passes `fields` and a `schema` built with `signUpSchema.extend({...})`. The
+ * password defaults to `new-password` autocomplete, which is what makes a
+ * password manager offer to generate one.
+ *
+ * @example
+ * <SignUpForm
+ *     schema={signUpSchema.extend({ terms: z.literal(true, "Aceite os termos") })}
+ *     fields={[...SIGN_UP_FIELDS, { name: "terms", type: "checkbox", label: "Aceito os termos" }]}
+ *     onSubmit={async (values) => { await api.post("/auth/register", { body: values }); }}
+ *     links={{ signIn: "/login" }}
+ * />
+ */
+export declare function SignUpForm<TSchema extends z.ZodTypeAny = typeof signUpSchema>({ schema, fields, links, labels, submitLabel, ...props }: SignUpFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link SignUpForm}, PT-BR by default. */
+export declare interface SignUpFormLabels extends AuthFormLabels {
+    /** Default `"Já tem uma conta?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+}
+
+/** Routes the sign-up form links to. */
+export declare interface SignUpFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface SignUpFormProps<TSchema extends z.ZodTypeAny = typeof signUpSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: SignUpFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<SignUpFormLabels>;
+}
+
+/**
+ * Default schema of `SignUpForm`: name, e-mail and password.
+ *
+ * Exported so an app adds its own fields with `.extend()` instead of rewriting
+ * the three it shares with every other app — see the phone and terms example in
+ * the docs.
+ */
+export declare const signUpSchema: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+}, z.core.$strip>;
+
 /** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
 export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
 
@@ -15829,6 +16486,14 @@ export declare interface SpinnerProps {
 
 export declare type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
 
+/** Body of `POST <prefix>/ticket` on the `tempest-fastapi-sdk` SSE router. */
+export declare interface SseTicketResponse {
+    /** Signed stream ticket, presented as a query param when opening the stream. */
+    ticket: string;
+    /** Seconds the ticket is accepted for opening a stream. */
+    expires_in: number;
+}
+
 /** 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;
 
@@ -16052,6 +16717,16 @@ export declare interface SyncRunSummary {
     skipped: boolean;
     /** Last delivery error message seen this run, or `null` when none failed. */
     lastError: string | null;
+    /**
+     * `true` when {@link OfflineSync.clearOutbox} or {@link OfflineSync.resetWatermark}
+     * ended the session while this run was in flight, so it stopped early.
+     *
+     * The counts cover only what happened before the stop: a delivery already in
+     * progress at logout is still counted, but no later entry was sent, no further
+     * page was pulled or applied, and the watermark was not written. Absent on a
+     * run that went to completion.
+     */
+    interrupted?: true;
 }
 
 /**
@@ -16345,6 +17020,17 @@ export declare interface TempestAuth<TUser, TCredentials> {
     refresh: () => Promise<void>;
     /** The current access token, or null. */
     getToken: () => string | null;
+    /**
+     * Stop following the other tabs: removes the `storage` listener this
+     * preset adds to `window`. Idempotent.
+     *
+     * An app keeps one preset for the page's lifetime and never needs it; it
+     * exists for tests and hot-module reload, which build several presets in
+     * one window. A disposed preset still compares the shared storage with
+     * its session before every refresh, so it never redeems another tab's
+     * refresh token.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -16441,6 +17127,22 @@ declare interface TempestSessionEnd<TUser> {
      * call to fail and keep the local half of the teardown independent of it.
      */
     api: ApiClient;
+    /**
+     * Whether another tab of the origin ended or replaced the session, and this
+     * tab is only catching up (#524). With `storage: "local"` the session's
+     * keys are shared by every tab, so a `logout()` or a `login()` in one tab
+     * ends the session in all of them: `reason` is `"logout"` when the other
+     * tab left no session behind and `"switch"` when it installed another
+     * account.
+     *
+     * The other tab already ran this hook for the same session. Teardown that
+     * lives in this tab's memory (an in-memory cache, an open socket) still has
+     * to run here; teardown of state the origin shares (IndexedDB, Cache
+     * Storage, a push subscription) was done there, and on `"switch"` redoing
+     * it here would wipe what the new account already wrote — skip it when
+     * this is `true`.
+     */
+    elsewhere: boolean;
 }
 
 /** The token envelope returned by a Tempest FastAPI SDK login/refresh route. */
@@ -16581,6 +17283,20 @@ export declare function throttle<A extends unknown[]>(fn: (...args: A) => void,
     cancel: () => void;
 };
 
+/** Where the ticket comes from and how the stream URL is built. */
+export declare interface TicketEventStreamSource {
+    /**
+     * Authenticated client the ticket is requested through, so it carries the
+     * `Authorization` header or the session cookie, the CSRF header, and the
+     * 401 refresh-and-replay that a hand-rolled `fetch` would lose.
+     */
+    client: Pick<ApiClient, "post" | "url">;
+    /** Router prefix, relative to the client's base URL. Default: `"/sse"`. */
+    prefix?: string;
+    /** Query param the stream reads the ticket from. Default: `"ticket"`. */
+    ticketParam?: string;
+}
+
 /**
  * Vertical event timeline — activity feeds, order trackers, audit logs.
  * Each entry has a marker (color or custom icon), title, optional
@@ -17363,6 +18079,48 @@ export declare interface UpdateVariables {
  */
 export declare function uploadFingerprint(endpoint: string, file: Blob | File): string;
 
+/**
+ * Upload a file straight to storage through a pre-signed `POST` form, with the
+ * size ceiling the policy enforces.
+ *
+ * The form is built the way S3 requires: every `post.fields` entry in order,
+ * the file last in the `file` part — S3 ignores whatever follows the file.
+ *
+ * The request carries **no** credential and no custom header: no
+ * `Authorization`, no CSRF token, no `X-Request-ID`, no cookies. `post.url` is
+ * usually the storage host, outside the API's origin, and the signature in
+ * `fields` is the whole authorization. Without custom headers the request is a
+ * CORS "simple request", so it does not depend on the bucket's CORS rules
+ * allowing a preflight.
+ *
+ * A file larger than `post.max_bytes` is refused before anything is sent, with
+ * the same `413 FILE_TOO_LARGE` the server would answer. Server errors are
+ * normalized into one `TempestApiError` whichever backend answered: the S3 XML
+ * (`EntityTooLarge` → `FILE_TOO_LARGE`, `EntityTooSmall` → `FILE_TOO_SMALL`,
+ * `AccessDenied` → `SIGNED_URL_INVALID`, or `SIGNED_URL_EXPIRED` when the policy
+ * expired) or the local backend's JSON envelope, which already uses those codes.
+ *
+ * @example
+ * const post = await api.post<PresignedPost>("/avatars/upload-form");
+ * await uploadPresignedPost(post, file, { onProgress: (p) => setProgress(p.fraction) });
+ *
+ * @param post - The form the API handed out.
+ * @param file - The file or blob to upload.
+ * @param options - Progress callback, abort signal and file name.
+ * @returns Resolves when storage accepted the file (`204` on S3).
+ * @throws TempestApiError On a refused upload, with the normalized `code`.
+ */
+export declare function uploadPresignedPost(post: PresignedPost, file: Blob, options?: UploadPresignedPostOptions): Promise<void>;
+
+export declare interface UploadPresignedPostOptions {
+    /** Called on every `progress` event of the upload. */
+    onProgress?: (event: UploadProgressEvent) => void;
+    /** Abort the upload; rejects with an `AbortError` `DOMException`. */
+    signal?: AbortSignal;
+    /** File name sent with the `file` part. Defaults to `file.name` for a `File`. */
+    fileName?: string;
+}
+
 export declare interface UploadProgressEvent {
     /** Bytes already uploaded. */
     loaded: number;
@@ -18144,6 +18902,11 @@ export declare function useEventListener<K extends keyof HTMLElementEventMap>(ev
  * tied to the component (and the `url`/`enabled` dependencies); the stream
  * closes on unmount.
  *
+ * A string `url` reopens the stream when it changes. A function `url` does not:
+ * an inline arrow is a new function every render, and keying on its identity
+ * would reconnect on every render. The latest function is the one called on the
+ * next connection, so call `reconnect()` when what it resolves to must change now.
+ *
  * Pass `schema` to have every frame validated before it reaches `onMessage`,
  * instead of trusting the type argument: without it `data` is announced as `T`
  * on the strength of the generic alone, which is a promise about the server
@@ -18167,7 +18930,7 @@ export declare function useEventListener<K extends keyof HTMLElementEventMap>(ev
  *     onMessage: ({ data }) => addNotification(data),
  * });
  */
-export declare function useEventStream<T = unknown>(url: string, options?: UseEventStreamOptions<T>): UseEventStreamResult<T>;
+export declare function useEventStream<T = unknown>(url: EventStreamUrl, options?: UseEventStreamOptions<T>): UseEventStreamResult<T>;
 
 export declare interface UseEventStreamOptions<T> extends Omit<CreateEventStreamOptions<T>, "onStatusChange"> {
     /** When false, the stream is not opened. Useful for "wait for auth". Default: true. */
@@ -20186,6 +20949,30 @@ export declare function useTheme(): ThemeContextValue;
  */
 export declare function useThrottle<T>(value: T, delay: number): T;
 
+/**
+ * React form of {@link createTicketEventStream}: same ticket per connection,
+ * lifecycle tied to the component like {@link useEventStream}.
+ *
+ * Changing `client`, `prefix` or `ticketParam` does not drop an open stream:
+ * the next connection uses the new values, and `reconnect()` applies them now.
+ * Reopening on identity would reconnect on every render for a client built
+ * inline.
+ *
+ * @example
+ * const { status } = useTicketEventStream<Notification>({
+ *     client: api,
+ *     enabled: isAuthenticated,
+ *     schema: notificationSchema,
+ *     onMessage: ({ data }) => addNotification(data),
+ * });
+ *
+ * @param options - Ticket source plus every {@link useEventStream} option.
+ * @returns Status, last message and `reconnect`.
+ */
+export declare function useTicketEventStream<T = unknown>(options: UseTicketEventStreamOptions<T>): UseEventStreamResult<T>;
+
+export declare type UseTicketEventStreamOptions<T> = TicketEventStreamSource & UseEventStreamOptions<T>;
+
 /**
  * Run a callback after `delay` ms. Pass `null` to disable. Resets when
  * `delay` changes; the callback ref always points at the latest closure.