tempest-react-sdk 0.79.0 → 0.80.0

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

@@ -768,6 +768,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 {
@@ -2417,7 +2431,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 +4237,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 +4300,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;
@@ -5478,6 +5514,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()`.
  *
@@ -7326,6 +7391,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.
  *
@@ -9478,6 +9556,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. */
@@ -12926,6 +13019,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"`. */
@@ -15829,6 +15938,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;
 
@@ -16581,6 +16698,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 +17494,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 +18317,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 +18345,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 +20364,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.