@better-auth-ui/react 1.6.3 → 1.6.5

package/src/queries/auth/session-query.ts

@@ -0,0 +1,135 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { AuthClient, InferData } from "../../lib/auth-client"
+
+export type SessionData<TAuthClient extends AuthClient = AuthClient> =
+  InferData<TAuthClient["getSession"]>
+
+export type Session<TAuthClient extends AuthClient = AuthClient> = NonNullable<
+  SessionData<TAuthClient>
+>
+
+export type SessionParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["getSession"]
+>[0]
+
+export type SessionOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof sessionOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current session.
+ *
+ * Shares a query key with the server-side `sessionOptions` so that data
+ * prefetched during SSR hydrates seamlessly into the client cache.
+ *
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export function sessionOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) {
+  type TData = SessionData<TAuthClient>
+  const queryKey = authQueryKeys.session
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.getSession({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current session from the query cache, calling `fetchSession` under
+ * the hood if no cached entry exists. Resolves with the session data, making
+ * it ideal for loaders or `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const ensureSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.ensureQueryData(sessionOptions(authClient, params))
+
+/**
+ * Prefetch the current session into the query cache. Behaves like
+ * `fetchSession`, but does not throw on error and does not return the data —
+ * use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const prefetchSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.prefetchQuery(sessionOptions(authClient, params))
+
+/**
+ * Fetch and cache the current session, resolving with the data or throwing
+ * on error. If a cached entry exists and is neither invalidated nor older
+ * than `staleTime`, the cached value is returned without a network call;
+ * otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const fetchSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.fetchQuery(sessionOptions(authClient, params))
+
+export type UseSessionOptions<TAuthClient extends AuthClient> =
+  SessionOptions<TAuthClient> & SessionParams<TAuthClient>
+
+/**
+ * Subscribe to the current session via TanStack Query.
+ *
+ * Shares a query key with the server-side `sessionOptions`, so SSR-hydrated
+ * session data is reused from the cache without an immediate refetch.
+ *
+ * @param authClient - The Better Auth client.
+ * @param options - `getSession` params (`query`, `fetchOptions`) merged
+ *   with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useSession<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options: UseSessionOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { query, fetchOptions, ...queryOptions } = options
+
+  return useQuery(
+    {
+      ...sessionOptions(authClient, { query, fetchOptions }),
+      ...queryOptions
+    },
+    queryClient
+  )
+}

package/src/queries/auth-query-options.ts

@@ -1,34 +1,83 @@
-import { type QueryKey, queryOptions } from "@tanstack/react-query"
+import {
+  type DataTag,
+  type QueryKey,
+  queryOptions,
+  type UseQueryOptions
+} from "@tanstack/react-query"
 import type { BetterFetchError, BetterFetchOption } from "better-auth/client"
 
-export type AuthFn<TData = unknown> = (params: {
+/**
+ * Read-style Better Auth client method (params shape `{ query?, fetchOptions? }`).
+ * Mutation-style endpoints use `AuthMutationFn` / `useAuthMutation` instead.
+ */
+export type AuthQueryFn<TData = unknown> = (params: {
   query?: Record<string, unknown>
   fetchOptions?: BetterFetchOption
 }) => Promise<{ data: TData }>
 
-type AuthFnData<TFn> = TFn extends AuthFn<infer TData> ? TData : never
+export type AuthQueryFnData<TFn> =
+  TFn extends AuthQueryFn<infer TData> ? TData : never
+
+/**
+ * Final query key produced by {@link authQueryOptions}: the caller's prefix
+ * followed by `params.query ?? null`.
+ */
+export type AuthQueryKey<
+  TFn extends AuthQueryFn = AuthQueryFn,
+  TPrefix extends QueryKey = QueryKey
+> = readonly [...TPrefix, NonNullable<Parameters<TFn>[0]>["query"] | null]
+
+/**
+ * Return type of {@link authQueryOptions}. Named so TypeScript emits
+ * `DataTag<…>` by reference in the `.d.ts`, instead of the raw
+ * `{ [dataTagSymbol]: … }` intersection — which triggers a declaration-emit
+ * bug where `dataTagSymbol` isn't re-imported at the use site and silently
+ * breaks `setQueryData`/`getQueryData` type inference at the consumer.
+ */
+export type AuthQueryOptions<
+  TFn extends AuthQueryFn = AuthQueryFn,
+  TPrefix extends QueryKey = QueryKey
+> = Omit<
+  UseQueryOptions<
+    AuthQueryFnData<TFn>,
+    BetterFetchError,
+    AuthQueryFnData<TFn>,
+    AuthQueryKey<TFn, TPrefix>
+  >,
+  "queryKey"
+> & {
+  queryKey: DataTag<
+    AuthQueryKey<TFn, TPrefix>,
+    AuthQueryFnData<TFn>,
+    BetterFetchError
+  >
+}
 
 /**
  * Build `queryOptions` for a Better Auth endpoint.
  *
- * Appends `params.query` (or `null`) to the supplied `queryKey` so cache
- * identity tracks endpoint inputs. Wires `throw: true` and the React Query
- * `AbortSignal` into `fetchOptions`.
+ * Injects React Query's `signal` and `throw: true` into `fetchOptions` so the
+ * request is cancelled on unmount and errors surface as `BetterFetchError`
+ * instead of `{ data, error }`.
  *
  * @param authFn - Better Auth client method (e.g. `authClient.getSession`).
  * @param queryKey - Scope prefix for the key. `params.query` is appended automatically.
  * @param params - Parameters forwarded to `authFn`.
  */
 export function authQueryOptions<
-  TFn extends AuthFn,
-  const TQueryKey extends QueryKey
->(authFn: TFn, queryKey: TQueryKey, params?: Parameters<TFn>[0]) {
-  return queryOptions<AuthFnData<TFn>, BetterFetchError>({
+  TFn extends AuthQueryFn,
+  const TPrefix extends QueryKey
+>(
+  authFn: TFn,
+  queryKey: TPrefix,
+  params?: Parameters<TFn>[0]
+): AuthQueryOptions<TFn, TPrefix> {
+  return queryOptions<AuthQueryFnData<TFn>, BetterFetchError>({
     queryKey: [...queryKey, params?.query ?? null] as const,
     queryFn: ({ signal }) =>
       authFn({
         ...params,
         fetchOptions: { ...params?.fetchOptions, signal, throw: true }
-      }) as Promise<AuthFnData<TFn>>
-  })
+      }) as Promise<AuthQueryFnData<TFn>>
+  }) as AuthQueryOptions<TFn, TPrefix>
 }

package/src/queries/multi-session/list-device-sessions-query.ts

@@ -0,0 +1,177 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  skipToken,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { InferData, MultiSessionAuthClient } from "../../lib/auth-client"
+import { useSession } from "../auth/session-query"
+
+export type ListDeviceSessionsData<
+  TAuthClient extends MultiSessionAuthClient = MultiSessionAuthClient
+> = InferData<TAuthClient["multiSession"]["listDeviceSessions"]>
+
+export type ListDeviceSession<
+  TAuthClient extends MultiSessionAuthClient = MultiSessionAuthClient
+> = NonNullable<ListDeviceSessionsData<TAuthClient>>[number]
+
+export type ListDeviceSessionsParams<
+  TAuthClient extends MultiSessionAuthClient
+> = Parameters<TAuthClient["multiSession"]["listDeviceSessions"]>[0]
+
+export type ListDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = Omit<
+  ReturnType<typeof listDeviceSessionsOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current user's device sessions.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The current signed-in user's ID. Used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export function listDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+>(
+  authClient: TAuthClient,
+  userId: string | undefined,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) {
+  type TData = ListDeviceSessionsData<TAuthClient>
+  const queryKey = authQueryKeys.listDeviceSessions(userId, params?.query)
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.multiSession.listDeviceSessions({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current user's device sessions from the query cache, calling
+ * `fetchListDeviceSessions` under the hood if no cached entry exists.
+ * Resolves with the device session list, making it ideal for loaders or
+ * `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const ensureListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.ensureQueryData(
+    listDeviceSessionsOptions(authClient, userId, params)
+  )
+
+/**
+ * Prefetch the current user's device sessions into the query cache. Behaves
+ * like `fetchListDeviceSessions`, but does not throw on error and does not
+ * return the data — use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const prefetchListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.prefetchQuery(
+    listDeviceSessionsOptions(authClient, userId, params)
+  )
+
+/**
+ * Fetch and cache the current user's device sessions, resolving with the
+ * data or throwing on error. If a cached entry exists and is neither
+ * invalidated nor older than `staleTime`, the cached value is returned
+ * without a network call; otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const fetchListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.fetchQuery(listDeviceSessionsOptions(authClient, userId, params))
+
+export type UseListDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = ListDeviceSessionsOptions<TAuthClient> &
+  ListDeviceSessionsParams<TAuthClient>
+
+/**
+ * Subscribe to the current user's device sessions (multi-session account
+ * switcher) via TanStack Query.
+ *
+ * Shares a query key with the server-side `listDeviceSessionsOptions`, so
+ * SSR-hydrated data is reused from the cache without an immediate refetch.
+ * The query is gated on a signed-in user; while the session is loading or
+ * absent, the underlying `queryFn` is replaced with `skipToken`.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param options - `listDeviceSessions` params (`query`, `fetchOptions`)
+ *   merged with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useListDeviceSessions<
+  TAuthClient extends MultiSessionAuthClient
+>(
+  authClient: TAuthClient,
+  options: UseListDeviceSessionsOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
+
+  const { query, fetchOptions, ...queryOptions } = options
+
+  const baseOptions = listDeviceSessionsOptions(authClient, userId, {
+    query,
+    fetchOptions
+  })
+
+  return useQuery(
+    {
+      ...queryOptions,
+      ...baseOptions,
+      queryFn: userId ? baseOptions.queryFn : skipToken
+    },
+    queryClient
+  )
+}

package/src/queries/passkey/list-passkeys-query.ts

@@ -0,0 +1,154 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  skipToken,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { InferData, PasskeyAuthClient } from "../../lib/auth-client"
+import { useSession } from "../auth/session-query"
+
+export type ListPasskeysData<TAuthClient extends PasskeyAuthClient> = InferData<
+  TAuthClient["passkey"]["listUserPasskeys"]
+>
+
+export type ListPasskeysParams<TAuthClient extends PasskeyAuthClient> =
+  Parameters<TAuthClient["passkey"]["listUserPasskeys"]>[0]
+
+export type ListPasskey<
+  TAuthClient extends PasskeyAuthClient = PasskeyAuthClient
+> = NonNullable<ListPasskeysData<TAuthClient>>[number]
+
+export type ListPasskeysOptions<TAuthClient extends PasskeyAuthClient> = Omit<
+  ReturnType<typeof listPasskeysOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current user's passkeys.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The current signed-in user's ID. Used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export function listPasskeysOptions<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  userId: string | undefined,
+  params?: ListPasskeysParams<TAuthClient>
+) {
+  type TData = ListPasskeysData<TAuthClient>
+  const queryKey = authQueryKeys.listPasskeys(userId, params?.query)
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.passkey.listUserPasskeys({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current user's passkeys from the query cache, calling
+ * `fetchListPasskeys` under the hood if no cached entry exists. Resolves
+ * with the passkey list, making it ideal for loaders or `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const ensureListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) =>
+  queryClient.ensureQueryData(listPasskeysOptions(authClient, userId, params))
+
+/**
+ * Prefetch the current user's passkeys into the query cache. Behaves like
+ * `fetchListPasskeys`, but does not throw on error and does not return
+ * the data — use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const prefetchListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) => queryClient.prefetchQuery(listPasskeysOptions(authClient, userId, params))
+
+/**
+ * Fetch and cache the current user's passkeys, resolving with the data or
+ * throwing on error. If a cached entry exists and is neither invalidated
+ * nor older than `staleTime`, the cached value is returned without a
+ * network call; otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const fetchListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) => queryClient.fetchQuery(listPasskeysOptions(authClient, userId, params))
+
+export type UseListPasskeysOptions<TAuthClient extends PasskeyAuthClient> =
+  ListPasskeysOptions<TAuthClient> & ListPasskeysParams<TAuthClient>
+
+/**
+ * Subscribe to the current user's passkeys via TanStack Query.
+ *
+ * Shares a query key with the server-side `listPasskeysOptions`, so
+ * SSR-hydrated data is reused from the cache without an immediate refetch.
+ * The query is gated on a signed-in user; while the session is loading or
+ * absent, the underlying `queryFn` is replaced with `skipToken`.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param options - `listPasskeys` params (`query`, `fetchOptions`) merged
+ *   with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useListPasskeys<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  options: UseListPasskeysOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
+
+  const { query, fetchOptions, ...queryOptions } = options
+
+  const baseOptions = listPasskeysOptions(authClient, userId, {
+    query,
+    fetchOptions
+  })
+
+  return useQuery(
+    {
+      ...queryOptions,
+      ...baseOptions,
+      queryFn: userId ? baseOptions.queryFn : skipToken
+    },
+    queryClient
+  )
+}