tempest-react-sdk 0.8.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.
@@ -1259,6 +1304,17 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * Build a `206 Partial Content` response from a full one for an HTTP `Range`
+ * request. Supports `bytes=start-end`, open-ended `bytes=start-` and suffix
+ * `bytes=-suffixLength`. Returns the original response when there is no usable
+ * `Range` header, or a `416` when the range is unsatisfiable.
+ *
+ * @param request The incoming request (its `Range` header drives the slice).
+ * @param response The full (200) response to slice.
+ */
+export declare function createPartialResponse(request: Request, response: Response): Promise<Response>;
+
 /**
  * Build a [[TelemetryAdapter]] backed by [`posthog-js`](https://posthog.com/docs/libraries/js).
  * The PostHog client is supplied by the caller (not bundled).
@@ -1433,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.
@@ -1468,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.
  *
@@ -1767,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;
 
@@ -2455,6 +2598,42 @@ export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputEl
 
 export declare type InputSize = "sm" | "md" | "lg";
 
+/**
+ * Install the background-sync queue: on a failed mutating request, the request
+ * is serialized to IndexedDB and a sync is registered; the original fetch still
+ * rejects (so your app can show an offline state), and the request is replayed
+ * later when the network returns.
+ */
+export declare function installBackgroundSync(options?: InstallBackgroundSyncOptions): void;
+
+/**
+ * Background-sync helper: queue failed mutating requests (POST/PUT/PATCH/DELETE)
+ * while offline and replay them when connectivity returns. A dependency-free
+ * take on Workbox's `BackgroundSyncPlugin`, backed by a tiny IndexedDB queue.
+ *
+ * Import inside your `sw.ts`. Uses the Background Sync API (`registration.sync`)
+ * when available, and also replays opportunistically on the next request as a
+ * fallback for browsers without it (e.g. Safari).
+ *
+ * @example
+ *   import { installBackgroundSync } from "tempest-react-sdk/sw";
+ *
+ *   installBackgroundSync({ match: (url) => url.pathname.startsWith("/api/") });
+ */
+/** Options for {@link installBackgroundSync}. */
+export declare interface InstallBackgroundSyncOptions {
+    /**
+     * Which requests to queue on failure. A `RegExp` against the URL or a
+     * predicate. Only non-`GET` requests are ever considered. Default: all
+     * non-`GET` requests.
+     */
+    match?: RegExp | ((url: URL, request: Request) => boolean);
+    /** IndexedDB database name, also used as the sync tag. Default `tempest-bg-sync`. */
+    queueName?: string;
+    /** Drop queued requests older than this (minutes) on replay. Default `1440` (24h). */
+    maxRetentionMinutes?: number;
+}
+
 /**
  * Install a `notificationclick` handler that focuses an existing client when
  * possible and falls back to opening a new window.
@@ -2466,6 +2645,32 @@ export declare interface InstallNotificationClickHandlerOptions {
     resolveUrl?: (data: unknown) => string;
 }
 
+/**
+ * Precache the app shell at `install` and serve it offline:
+ *  - reads `precache-manifest.json` (emitted by `tempestPwaManifest()`),
+ *  - caches every listed URL under a versioned cache,
+ *  - on `activate`, deletes stale precache versions and claims open clients,
+ *  - on `fetch`, serves precached assets cache-first and falls back to the
+ *    `navigateFallback` document for offline navigations (SPA routing).
+ *
+ * Same-origin only. Register this LAST, after any {@link installRuntimeCache}.
+ */
+export declare function installPrecache(options?: InstallPrecacheOptions): void;
+
+/** Options for {@link installPrecache}. */
+export declare interface InstallPrecacheOptions {
+    /** URL of the manifest emitted by `tempestPwaManifest()`. Default `/precache-manifest.json`. */
+    manifestUrl?: string;
+    /** Cache name prefix; the manifest `version` is appended. Default `tempest-precache`. */
+    cacheName?: string;
+    /** App-shell document served for navigation requests offline. Default `/index.html`. */
+    navigateFallback?: string;
+    /** Navigation paths that should NOT use the fallback (e.g. `[/^\/api\//]`). */
+    navigateFallbackDenylist?: RegExp[];
+    /** Activate the new worker immediately after precaching. Default `true`. */
+    skipWaiting?: boolean;
+}
+
 /**
  * Install a `push` event listener that parses the payload as JSON (with a
  * plain-text fallback) and shows a notification.
@@ -2486,6 +2691,18 @@ export declare interface InstallPushHandlerOptions {
     transform?: (payload: PushPayload) => PushPayload | null;
 }
 
+/**
+ * Install a `fetch` handler that resolves matching `GET` requests with the
+ * given runtime strategies. Non-matching requests are left untouched (no
+ * `respondWith`), so a later {@link installPrecache} can handle them.
+ *
+ * Register this BEFORE `installPrecache` so specific routes win over the
+ * precache catch-all.
+ *
+ * @param routes Ordered rules; the first whose `match` passes handles the request.
+ */
+export declare function installRuntimeCache(routes: RuntimeRoute[]): void;
+
 /**
  * Install a `message` listener that activates a waiting worker when the host
  * app sends `{ type: "SKIP_WAITING" }`.
@@ -2494,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`.
  *
@@ -2543,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.
  *
@@ -2989,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`.
  *
@@ -3587,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.
@@ -3635,6 +3911,51 @@ export declare type RouterKind = "browser" | "hash" | "memory";
 
 export { Routes }
 
+/** A single runtime-caching rule, matched against each `GET` request. */
+export declare interface RuntimeRoute {
+    /** A `RegExp` tested against the full URL, or a predicate over the parsed URL. */
+    match: RegExp | ((url: URL, request: Request) => boolean);
+    /** How to resolve a match. */
+    strategy: RuntimeStrategy;
+    /** Cache bucket name for this route. */
+    cacheName: string;
+    /** Trim the cache to at most this many entries (FIFO) after each write. */
+    maxEntries?: number;
+    /** Treat a cached response older than this (seconds) as a miss. */
+    maxAgeSeconds?: number;
+    /** For `network-first`: fall back to cache after this timeout (seconds). */
+    networkTimeoutSeconds?: number;
+    /**
+     * Serve HTTP `Range` requests (206 Partial Content) by slicing the cached
+     * full response. Enable for audio/video so seeking works offline. The full
+     * resource is cached once (the `Range` header is stripped before caching).
+     */
+    rangeRequests?: boolean;
+}
+
+/**
+ * Service-worker caching helpers — a small, dependency-free subset of what
+ * Workbox provides: precaching of the build's app shell (so the app launches
+ * offline) plus runtime caching strategies for fonts, APIs and images.
+ *
+ * Import these inside your own `sw.ts`. They run in the service-worker global
+ * scope, not the main thread. Pair `installPrecache` with the
+ * `tempestPwaManifest()` Vite plugin (from `tempest-react-sdk/vite`), which
+ * emits the `precache-manifest.json` this reads at install time.
+ *
+ * @example
+ *   /// <reference lib="webworker" />
+ *   import { installRuntimeCache, installPrecache } from "tempest-react-sdk/sw";
+ *
+ *   // Register specific routes FIRST so they win over the precache catch-all.
+ *   installRuntimeCache([
+ *     { match: /\/api\//, strategy: "network-first", cacheName: "api", maxAgeSeconds: 300 },
+ *   ]);
+ *   installPrecache();
+ */
+/** Caching strategy for a runtime route. Mirrors the common Workbox trio. */
+export declare type RuntimeStrategy = "cache-first" | "network-first" | "stale-while-revalidate";
+
 /**
  * Apply `env(safe-area-inset-*)` padding so content avoids iOS notch /
  * Android navbar / device chrome. Wrap the outermost container of pages
@@ -4192,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`
@@ -4224,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.
  */
@@ -4545,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.
  */
@@ -4566,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;
 }
 
 /**
@@ -4680,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.
@@ -4965,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.