@better-auth-ui/react 1.6.3 → 1.6.4

package/src/mutations/settings/revoke-session-mutation.ts

@@ -0,0 +1,69 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { AuthClient } from "../../lib/auth-client"
+import { useListSessions } from "../../queries/settings/list-sessions-query"
+
+export type RevokeSessionParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["revokeSession"]
+>[0]
+
+export type RevokeSessionOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof revokeSessionOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for revoking a user session.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function revokeSessionOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.revokeSession
+
+  const mutationFn = (params: RevokeSessionParams<TAuthClient>) =>
+    authClient.revokeSession({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for revoking a user session.
+ *
+ * Wraps `authClient.revokeSession`, refetches the sessions list on success,
+ * and forwards React Query mutation options such as `onSuccess`, `onError`,
+ * and `retry`.
+ *
+ * @param authClient - The Better Auth client.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useRevokeSession<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: RevokeSessionOptions<TAuthClient>
+) {
+  const { refetch: refetchSessions } = useListSessions(authClient, {
+    refetchOnMount: false
+  })
+
+  return useMutation({
+    ...revokeSessionOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetchSessions()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/settings/unlink-account-mutation.ts

@@ -0,0 +1,67 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { AuthClient } from "../../lib/auth-client"
+import { useListAccounts } from "../../queries/settings/list-accounts-query"
+
+export type UnlinkAccountParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["unlinkAccount"]
+>[0]
+
+export type UnlinkAccountOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof unlinkAccountOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for unlinking a social provider from the current user.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function unlinkAccountOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.unlinkAccount
+
+  const mutationFn = (params: UnlinkAccountParams<TAuthClient>) =>
+    authClient.unlinkAccount({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for unlinking a social provider from the current user.
+ *
+ * Wraps `authClient.unlinkAccount`, refetches the linked accounts list on
+ * success, and forwards React Query mutation options such as `onSuccess`,
+ * `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useUnlinkAccount<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: UnlinkAccountOptions<TAuthClient>
+) {
+  const { refetch } = useListAccounts(authClient, { refetchOnMount: false })
+
+  return useMutation({
+    ...unlinkAccountOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/settings/update-user-mutation.ts

@@ -0,0 +1,82 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import {
+  mutationOptions,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+import type { AuthClient } from "../../lib/auth-client"
+import { sessionOptions, useSession } from "../../queries/auth/session-query"
+
+export type UpdateUserParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["updateUser"]
+>[0]
+
+export type UpdateUserOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof updateUserOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for updating the authenticated user's profile.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function updateUserOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.updateUser
+
+  const mutationFn = (params: UpdateUserParams<TAuthClient>) =>
+    authClient.updateUser({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for updating the authenticated user's profile.
+ *
+ * Wraps `authClient.updateUser`, optimistically patches the cached session
+ * with the new fields, refetches the session, and forwards React Query
+ * mutation options such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useUpdateUser<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: UpdateUserOptions<TAuthClient>
+) {
+  const { data: session, refetch: refetchSession } = useSession(authClient, {
+    refetchOnMount: false
+  })
+
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...updateUserOptions(authClient),
+    ...options,
+    onSuccess: async (data, variables, ...rest) => {
+      if (session) {
+        queryClient.setQueryData(sessionOptions(authClient).queryKey, {
+          ...session,
+          user: { ...session.user, ...variables }
+        })
+      }
+
+      refetchSession()
+
+      await options?.onSuccess?.(data, variables, ...rest)
+    }
+  })
+}

package/src/mutations/username/is-username-available-mutation.ts

@@ -0,0 +1,62 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { UsernameAuthClient } from "../../lib/auth-client"
+
+export type IsUsernameAvailableParams<TAuthClient extends UsernameAuthClient> =
+  Parameters<TAuthClient["isUsernameAvailable"]>[0]
+
+export type IsUsernameAvailableOptions<TAuthClient extends UsernameAuthClient> =
+  Omit<
+    ReturnType<typeof isUsernameAvailableOptions<TAuthClient>>,
+    "mutationKey" | "mutationFn"
+  >
+
+/**
+ * Mutation options factory for checking username availability.
+ *
+ * Modeled as a mutation because callers typically trigger the check on
+ * user action (debounced input, form submit) rather than on mount.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function isUsernameAvailableOptions<
+  TAuthClient extends UsernameAuthClient
+>(authClient: TAuthClient) {
+  const mutationKey = authMutationKeys.isUsernameAvailable
+
+  const mutationFn = (params: IsUsernameAvailableParams<TAuthClient>) =>
+    authClient.isUsernameAvailable({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for checking whether a username is available.
+ *
+ * Wraps `authClient.isUsernameAvailable` and forwards React Query mutation
+ * options such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the username plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useIsUsernameAvailable<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient,
+  options?: IsUsernameAvailableOptions<TAuthClient>
+) {
+  return useMutation({
+    ...isUsernameAvailableOptions(authClient),
+    ...options
+  })
+}

package/src/mutations/username/sign-in-username-mutation.ts

@@ -0,0 +1,74 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import {
+  mutationOptions,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { UsernameAuthClient } from "../../lib/auth-client"
+import { sessionOptions } from "../../queries/auth/session-query"
+
+export type SignInUsernameParams<TAuthClient extends UsernameAuthClient> =
+  Parameters<TAuthClient["signIn"]["username"]>[0]
+
+export type SignInUsernameOptions<TAuthClient extends UsernameAuthClient> =
+  Omit<
+    ReturnType<typeof signInUsernameOptions<TAuthClient>>,
+    "mutationKey" | "mutationFn"
+  >
+
+/**
+ * Mutation options factory for username/password sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInUsernameOptions<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signIn.username
+
+  const mutationFn = (params: SignInUsernameParams<TAuthClient>) =>
+    authClient.signIn.username({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for username/password sign-in.
+ *
+ * Wraps `authClient.signIn.username`, resets the session query on success so
+ * the new session is refetched, and forwards React Query mutation options
+ * such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the username plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignInUsername<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient,
+  options?: SignInUsernameOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signInUsernameOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.resetQueries({
+        queryKey: sessionOptions(authClient).queryKey
+      })
+
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

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>
 }