tempest-react-sdk 0.9.0 → 0.10.0

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

@@ -28,6 +28,7 @@ import { ForwardRefExoticComponent } from 'react';
 import { HashRouter } from 'react-router-dom';
 import { HTMLAttributes } from 'react';
 import { ImgHTMLAttributes } from 'react';
+import { InfiniteData } from '@tanstack/react-query';
 import { InputEventHandler } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react/jsx-runtime';
@@ -47,6 +48,7 @@ import { Path } from 'react-hook-form';
 import { PersistOptions } from 'zustand/middleware';
 import { PointerEventHandler } from 'react';
 import { QueryClient } from '@tanstack/react-query';
+import { QueryKey } from '@tanstack/react-query';
 import { ReactElement } from 'react';
 import { ReactEventHandler } from 'react';
 import { ReactNode } from 'react';
@@ -77,10 +79,12 @@ import { UseFormProps } from 'react-hook-form';
 import { UseFormRegister } from 'react-hook-form';
 import { UseFormReturn } from 'react-hook-form';
 import { useFormState } from 'react-hook-form';
+import { UseInfiniteQueryOptions } from '@tanstack/react-query';
 import { useLocation } from 'react-router-dom';
 import { useMatch } from 'react-router-dom';
 import { useNavigate } from 'react-router-dom';
 import { useParams } from 'react-router-dom';
+import { UseQueryOptions } from '@tanstack/react-query';
 import { useRouteError } from 'react-router-dom';
 import { useSearchParams } from 'react-router-dom';
 import { useWatch } from 'react-hook-form';
@@ -157,6 +161,12 @@ export declare interface ApiClientConfig {
     baseURL: string;
     /** Returns the current bearer token (or null/undefined). Called per request. */
     getToken?: () => string | null | undefined;
+    /**
+     * Per-request correlation id sent as the `X-Request-ID` header, matching the
+     * Tempest FastAPI SDK `RequestIDMiddleware`. Defaults to a generated id.
+     * Return an empty string to disable the header.
+     */
+    requestId?: () => string;
     /** Called on 401 responses. Use it to logout the user or trigger a refresh. */
     onUnauthorized?: (response: Response) => void | Promise<void>;
     /**
@@ -173,8 +183,26 @@ export declare interface ApiClientConfig {
 }
 
 export declare interface ApiError {
+    /** HTTP status code (0 for network failures). */
     status: number;
+    /** Human-readable message — the backend envelope's `detail` (or `message`). */
     detail: string;
+    /**
+     * Programmatic error code from the Tempest FastAPI SDK envelope (`code`),
+     * e.g. `"EMAIL_TAKEN"`. Lets callers branch without parsing `detail`.
+     */
+    code?: string;
+    /**
+     * Correlation id echoed from the backend envelope's `details.request_id`
+     * (or the `X-Request-ID` response header). Pair it with `createLogger`.
+     */
+    requestId?: string;
+    /**
+     * Seconds to wait before retrying, parsed from the `Retry-After` response
+     * header (commonly on `429`/`503`). Honored by {@link retry}.
+     */
+    retryAfter?: number;
+    /** The raw parsed error body, when available. */
     body?: unknown;
 }
 
@@ -558,6 +586,23 @@ 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`.
+ */
+export declare function buildApiError(status: number, body: unknown, headers?: Headers | {
+    get(name: string): string | null;
+}, sentRequestId?: string): ApiError;
+
 /**
  * Primary action button with variants, sizes and a loading state that
  * preserves layout via an absolutely-positioned spinner.
@@ -1444,6 +1489,65 @@ export declare interface CreateStorePersistOptions<T> {
     migrate?: PersistOptions<T, Partial<T>>["migrate"];
 }
 
+/**
+ * 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.
+ *
+ * @example
+ * const auth = createTempestAuth<User, { email: string; password: string }>({
+ *     baseURL: import.meta.env.VITE_API_URL,
+ *     mePath: "/api/auth/me",
+ * });
+ *
+ * await auth.login({ email, password });   // stores session, returns the user
+ * const orders = await auth.api.get("/api/orders");  // sends the bearer token
+ * auth.logout();
+ *
+ * @param options - The auth configuration.
+ * @returns The store hook, a wired API client, and login/logout/refresh helpers.
+ */
+export declare function createTempestAuth<TUser, TCredentials = {
+    email: string;
+    password: string;
+}>(options: CreateTempestAuthOptions<TUser>): TempestAuth<TUser, TCredentials>;
+
+export declare interface CreateTempestAuthOptions<TUser> {
+    /** Base URL of the API. Required. */
+    baseURL: string;
+    /** Login route (`POST`). Default: `"/api/auth/login"`. */
+    loginPath?: string;
+    /** Refresh route (`POST`). Default: `"/api/auth/refresh"`. */
+    refreshPath?: string;
+    /** Optional current-user route (`GET`) called after login/refresh. */
+    mePath?: string;
+    /** Persist key for the store. Default: `"tempest-auth"`. */
+    storeName?: string;
+    /** Storage backend. Default: `"local"`. */
+    storage?: "local" | "session";
+    /** Send cookies (needed when the refresh token lives in an httpOnly cookie). */
+    withCredentials?: boolean;
+    /** Custom fetch implementation (testing / SSR). Defaults to `globalThis.fetch`. */
+    fetcher?: typeof fetch;
+    /**
+     * Extract tokens from a login/refresh response. Default reads
+     * `access_token` + `refresh_token`.
+     */
+    parseTokens?: (data: unknown) => {
+        token: string;
+        refreshToken?: string;
+    };
+    /** Pull the user out of the login response, when the API embeds it. */
+    parseUser?: (data: unknown) => TUser | null;
+    /**
+     * Build the refresh request body. Default sends `{ refresh_token }` when a
+     * refresh token is stored, else `undefined` (cookie-based refresh).
+     */
+    refreshBody?: (refreshToken: string | null) => unknown;
+}
+
 /**
  * Open a WebSocket with automatic exponential-backoff reconnect, optional
  * heartbeat pings, and typed JSON parsing.
@@ -1479,6 +1583,26 @@ export declare interface CreateWebSocketOptions<T> {
     onStatusChange?: (status: WebSocketStatus) => void;
 }
 
+/** Cursor-paginated response envelope (`CursorPaginationSchema[T]`). */
+export declare interface CursorPage<T> {
+    /** The rows for this batch. */
+    items: T[];
+    /** Opaque cursor for the next batch, or null when exhausted. Pass it back verbatim. */
+    next_cursor: string | null;
+    /** Whether another batch exists. */
+    has_more: boolean;
+    /** Batch size used for this query. */
+    limit: number;
+}
+
+/** Cursor filter query params (`CursorPaginationFilterSchema`). */
+export declare interface CursorParams {
+    cursor?: string | null;
+    limit?: number;
+    order_by?: string;
+    ascending?: boolean;
+}
+
 /**
  * Generic, typed list that renders a `<ul>` with one `<li>` per item.
  *
@@ -1778,6 +1902,14 @@ export declare interface ElementSize {
     height: number;
 }
 
+/**
+ * Build an empty {@link OffsetPage} — handy as `placeholderData`/`initialData`.
+ *
+ * @param pageSize - The page size to report (default 20).
+ * @returns An empty offset page on page 1.
+ */
+export declare function emptyOffsetPage<T>(pageSize?: number): OffsetPage<T>;
+
 /** Centered "nothing here yet" placeholder with optional icon and CTA. */
 export declare function EmptyState({ icon, title, description, action, className }: EmptyStateProps): JSX.Element;
 
@@ -2579,6 +2711,23 @@ export declare function installSkipWaitingListener(): void;
 
 export declare type InterpolationValues = Record<string, string | number>;
 
+/**
+ * Type guard for the {@link ApiError} shape. Matches both {@link TempestApiError}
+ * instances and plain objects carrying `status` + `detail`.
+ *
+ * @param error - The unknown value (typically a caught error).
+ * @returns Whether `error` conforms to the `ApiError` contract.
+ */
+export declare function isApiError(error: unknown): error is ApiError;
+
+/**
+ * Type guard for a {@link CursorPage} envelope.
+ *
+ * @param value - The unknown value to test.
+ * @returns Whether it carries `items` + `has_more` + a `next_cursor` key.
+ */
+export declare function isCursorPage<T = unknown>(value: unknown): value is CursorPage<T>;
+
 /**
  * Type guard asserting a value is neither `null` nor `undefined`.
  *
@@ -2628,6 +2777,14 @@ export declare function isJWTExpired(token: string, leewaySeconds?: number): boo
  */
 export declare function isNumber(value: unknown): value is number;
 
+/**
+ * Type guard for an {@link OffsetPage} envelope.
+ *
+ * @param value - The unknown value to test.
+ * @returns Whether it carries `items` + `total` + `page` + `pages`.
+ */
+export declare function isOffsetPage<T = unknown>(value: unknown): value is OffsetPage<T>;
+
 /**
  * Type guard asserting a value is a plain object literal.
  *
@@ -3074,6 +3231,33 @@ export declare interface OfflineStoreConfig<TItem> {
     ownerField?: keyof TItem & string;
 }
 
+/** Offset-paginated response envelope (fastapi-pagination `Page[T]`). */
+export declare interface OffsetPage<T> {
+    /** The rows for the current page. */
+    items: T[];
+    /** Total number of matching rows across all pages. */
+    total: number;
+    /** Current 1-based page number. */
+    page: number;
+    /** Total number of pages. */
+    pages: number;
+    /** Page size — fastapi-pagination emits `size`. */
+    size?: number;
+    /** Page size — some backends name it `page_size` instead. */
+    page_size?: number;
+}
+
+/** Offset filter query params (fastapi-pagination / `BasePaginationFilterSchema`). */
+export declare interface OffsetParams {
+    page?: number;
+    /** Page size — fastapi-pagination convention. */
+    size?: number;
+    /** Page size — `page_size` convention. */
+    page_size?: number;
+    order_by?: string;
+    ascending?: boolean;
+}
+
 /**
  * Create a new object with the given `keys` removed from `obj`.
  *
@@ -3672,6 +3856,13 @@ export declare interface RetryOptions {
     initialDelay?: number;
     /** Maximum delay between attempts. Default: 10_000. */
     maxDelay?: number;
+    /**
+     * Honor a `Retry-After` hint on the thrown error (`error.retryAfter`, in
+     * seconds — populated by {@link createApiClient} on `429`/`503`). When
+     * present it overrides the exponential backoff for that attempt. The value
+     * is capped at `maxDelay`. Default: true.
+     */
+    respectRetryAfter?: boolean;
     /**
      * Return false to stop retrying for a specific error.
      * Default: retry on any thrown error.
@@ -4322,6 +4513,46 @@ export declare interface TelemetryUser {
     traits?: Record<string, unknown>;
 }
 
+/**
+ * Error thrown by {@link createApiClient} / {@link uploadWithProgress} on a
+ * non-2xx response. Mirrors the Tempest FastAPI SDK error envelope
+ * (`{ detail, code, details.request_id }`) so callers get a typed `code` and a
+ * `requestId` for log correlation, while still being a real `Error` (stack
+ * trace, `instanceof Error`).
+ *
+ * @example
+ * try {
+ *     await api.post("/users", { body });
+ * } catch (err) {
+ *     if (isApiError(err) && err.code === "EMAIL_TAKEN") {
+ *         showFieldError("email", err.detail);
+ *     }
+ * }
+ */
+export declare class TempestApiError extends Error implements ApiError {
+    readonly status: number;
+    readonly detail: string;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly body?: unknown;
+    constructor(init: ApiError);
+}
+
+export declare interface TempestAuth<TUser, TCredentials> {
+    /** The persisted Zustand auth store hook (compatible with `<AuthGuard>`). */
+    useAuthStore: ReturnType<typeof createAuthStore<TUser>>;
+    /** A `createApiClient` wired with bearer auth + 401 → refresh → retry. */
+    api: ApiClient;
+    /** Authenticate, store the session, and resolve the user (or null). */
+    login: (credentials: TCredentials) => Promise<TUser | null>;
+    /** Clear the session (and the stored refresh token). */
+    logout: () => void;
+    /** Refresh the access token (deduplicated across concurrent callers). */
+    refresh: () => Promise<void>;
+    /** The current access token, or null. */
+    getToken: () => string | null;
+}
+
 /**
  * A single declarative route node. Mirrors React Router's nested `<Route>`
  * model but adds first-class `lazy` (code-split with retry) and `guard`
@@ -4354,6 +4585,16 @@ export declare interface TempestRouteObject {
     caseSensitive?: boolean;
 }
 
+/** The token envelope returned by a Tempest FastAPI SDK login/refresh route. */
+export declare interface TempestTokenResponse {
+    /** The bearer access token. */
+    access_token: string;
+    /** Token type — always `"bearer"` for the SDK. */
+    token_type?: string;
+    /** Optional refresh token (when the API returns it in the body, not a cookie). */
+    refresh_token?: string;
+}
+
 /**
  * Multi-line text input. Mirrors the {@link Input} API for label/helper/error.
  */
@@ -4675,7 +4916,7 @@ export declare interface UploadProgressEvent {
  *
  * `fetch` cannot report upload progress in browsers, so this helper falls
  * back to `XMLHttpRequest`. It mirrors the error contract used by
- * {@link createApiClient}: non-2xx responses throw an {@link ApiError}.
+ * {@link createApiClient}: non-2xx responses reject with a `TempestApiError`.
  *
  * @returns The parsed JSON response, or the raw text when the response is not JSON.
  */
@@ -4696,6 +4937,11 @@ export declare interface UploadWithProgressOptions {
     signal?: AbortSignal;
     /** Override the JSON parser. Defaults to `JSON.parse`. */
     parser?: (raw: string) => unknown;
+    /**
+     * Per-request correlation id sent as `X-Request-ID` (Tempest convention).
+     * Defaults to a generated id. Return an empty string to disable.
+     */
+    requestId?: () => string;
 }
 
 /**
@@ -4810,6 +5056,52 @@ export declare interface UseClipboardResult {
     reset: () => void;
 }
 
+/**
+ * Cursor-pagination hook over TanStack Query's `useInfiniteQuery` for the
+ * Tempest `CursorPaginationSchema` envelope
+ * (`{ items, next_cursor, has_more, limit }`).
+ *
+ * The opaque `next_cursor` is fed straight back as the next page param; the
+ * loop stops when `has_more` is false (or `next_cursor` is null).
+ *
+ * @example
+ * const feed = useCursorQuery<Post>({
+ *     queryKey: ["feed"],
+ *     limit: 30,
+ *     queryFn: (params) => postsService.listPosts(params),
+ * });
+ * // feed.items, feed.fetchNextPage(), feed.hasNextPage
+ */
+export declare function useCursorQuery<T>(options: UseCursorQueryOptions<T>): UseCursorQueryResult<T>;
+
+export declare interface UseCursorQueryOptions<T> extends Omit<UseInfiniteQueryOptions<CursorPage<T>, Error, InfiniteData<CursorPage<T>, string | null>, QueryKey, string | null>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"> {
+    /** Base query key — `limit`/sort is appended for cache isolation. */
+    queryKey: QueryKey;
+    /** Fetcher receiving the cursor params; return the backend envelope. */
+    queryFn: (params: CursorParams) => Promise<CursorPage<T>> | CursorPage<T>;
+    /** Batch size sent as `limit`. Default: 20. */
+    limit?: number;
+    /** Initial `order_by`. */
+    orderBy?: string;
+    /** Initial `ascending`. Default: false. */
+    ascending?: boolean;
+}
+
+export declare interface UseCursorQueryResult<T> {
+    /** All rows fetched so far, flattened across batches. */
+    items: T[];
+    /** The raw batches, in fetch order. */
+    pages: CursorPage<T>[];
+    hasNextPage: boolean;
+    isLoading: boolean;
+    isFetchingNextPage: boolean;
+    error: Error | null;
+    /** Fetch the next batch (no-op when exhausted). */
+    fetchNextPage: () => void;
+    /** Refetch from the first batch. */
+    refetch: () => void;
+}
+
 /**
  * Debounce a fast-changing value. Returns the latest value once `delay` ms
  * have elapsed without further changes.
@@ -5095,6 +5387,71 @@ export declare interface UseOAuthCallbackResult<T> {
  */
 export declare function useOnline(): boolean;
 
+/**
+ * Offset-pagination hook over TanStack Query for the fastapi-pagination /
+ * Tempest envelope (`{ items, total, page, size, pages }`).
+ *
+ * It owns the page state, sends `page` + the size param (`size` by default,
+ * or `page_size` via `sizeParam`) plus optional `order_by`/`ascending` to your
+ * fetcher, keeps the previous page visible while the next loads, and derives
+ * `hasNext`/`hasPrev`/`pageCount`.
+ *
+ * @example
+ * const users = usePaginatedQuery<User>({
+ *     queryKey: ["users"],
+ *     pageSize: 25,
+ *     queryFn: (params) => usersService.listUsers(params),
+ * });
+ * // users.items, users.next(), users.hasNext, users.pageCount
+ */
+export declare function usePaginatedQuery<T>(options: UsePaginatedQueryOptions<T>): UsePaginatedQueryResult<T>;
+
+export declare interface UsePaginatedQueryOptions<T> extends Omit<UseQueryOptions<OffsetPage<T>, Error, OffsetPage<T>, QueryKey>, "queryKey" | "queryFn"> {
+    /** Base query key — the current page/sort is appended for cache isolation. */
+    queryKey: QueryKey;
+    /** Fetcher receiving the offset params; return the backend envelope. */
+    queryFn: (params: OffsetParams) => Promise<OffsetPage<T>> | OffsetPage<T>;
+    /** Initial 1-based page. Default: 1. */
+    initialPage?: number;
+    /** Page size. Default: 20. */
+    pageSize?: number;
+    /**
+     * Query-param name for the page size. fastapi-pagination uses `"size"`
+     * (default); SDK `BasePaginationFilterSchema` configs may use `"page_size"`.
+     */
+    sizeParam?: "size" | "page_size";
+    /** Initial `order_by` (only sent when set). */
+    orderBy?: string;
+    /** Initial `ascending` (only sent when `orderBy` is set). Default: false. */
+    ascending?: boolean;
+}
+
+export declare interface UsePaginatedQueryResult<T> {
+    /** The current page envelope, or undefined while the first load is pending. */
+    page: OffsetPage<T> | undefined;
+    /** The rows of the current page (empty array while pending). */
+    items: T[];
+    /** Current 1-based page number (controlled by the hook). */
+    pageNumber: number;
+    /** Total page count from the last successful response. */
+    pageCount: number;
+    /** Total row count from the last successful response. */
+    total: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    /** Jump to a specific 1-based page (clamped to >= 1). */
+    setPage: (page: number) => void;
+    /** Go to the next page when available. */
+    next: () => void;
+    /** Go to the previous page when available. */
+    prev: () => void;
+    /** Refetch the current page. */
+    refetch: () => void;
+}
+
 /**
  * Manage page/size state for paginated lists. Reset goes back to page 1
  * without touching the page size.