@better-auth-ui/react 1.6.1 → 1.6.3

package/src/hooks/settings/use-set-active-session.ts

@@ -1,46 +1,58 @@
-import {
-  type AuthClient,
-  useAuth,
-  useAuthMutation,
-  useListDeviceSessions,
-  useSession
-} from "@better-auth-ui/react"
-import { useQueryClient } from "@tanstack/react-query"
-import type { UseAuthMutationOptions } from "../auth/use-auth-mutation"
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+
+import { useAuth } from "../../components/auth/auth-provider"
+import type { AuthClient } from "../../lib/auth-client"
+import { setActiveSessionOptions } from "../../mutations/settings/set-active-session-options"
+import { sessionOptions } from "../../queries/auth/session-options"
+import { useSession } from "../auth/use-session"
+import { useListDeviceSessions } from "./use-list-device-sessions"
+
+export type UseSetActiveSessionParams = NonNullable<
+  Parameters<AuthClient["multiSession"]["setActive"]>[0]
+>
+
+export type UseSetActiveSessionOptions = Omit<
+  ReturnType<typeof setActiveSessionOptions>,
+  "mutationKey" | "mutationFn"
+>
 
 /**
  * Hook that sets an active device session in multi-session mode.
  *
+ * Optimistically switches the cached session to the matching device session,
+ * scrolls to top, and refetches both the session and device-session queries.
+ *
+ * @param options - React Query options forwarded to `useMutation`.
  * @returns The `useMutation` result.
  */
-export function useSetActiveSession(
-  options?: UseAuthMutationOptions<AuthClient["multiSession"]["setActive"]>
-) {
+export function useSetActiveSession(options?: UseSetActiveSessionOptions) {
   const queryClient = useQueryClient()
   const { authClient } = useAuth()
-
   const { refetch: refetchSession } = useSession({ refetchOnMount: false })
   const { data: deviceSessions, refetch: refetchDeviceSessions } =
     useListDeviceSessions({ refetchOnMount: false })
 
-  return useAuthMutation({
-    authFn: authClient.multiSession.setActive,
-    options: {
-      ...options,
-      onSuccess: async (data, { sessionToken }, ...args) => {
-        const deviceSession = deviceSessions?.find(
-          (session) => session.session.token === sessionToken
-        )
+  return useMutation({
+    ...setActiveSessionOptions(authClient),
+    ...options,
+    onSuccess: async (data, variables, ...rest) => {
+      const sessionToken = variables?.sessionToken
+      const deviceSession = deviceSessions?.find(
+        (session) => session.session.token === sessionToken
+      )
 
-        if (deviceSession)
-          queryClient.setQueryData(["auth", "getSession"], deviceSession)
+      if (deviceSession) {
+        queryClient.setQueryData(
+          sessionOptions(authClient).queryKey,
+          deviceSession
+        )
+      }
 
-        window.scrollTo({ top: 0 })
+      window.scrollTo({ top: 0 })
 
-        await refetchSession()
-        await refetchDeviceSessions()
-        await options?.onSuccess?.(data, { sessionToken }, ...args)
-      }
+      await refetchSession()
+      await refetchDeviceSessions()
+      await options?.onSuccess?.(data, variables, ...rest)
     }
   })
 }

package/src/hooks/settings/use-unlink-account.ts

@@ -1,31 +1,37 @@
-import {
-  type AuthClient,
-  useAuth,
-  useAuthMutation
-} from "@better-auth-ui/react"
-import type { UseAuthMutationOptions } from "../auth/use-auth-mutation"
+import { useMutation } from "@tanstack/react-query"
 
+import { useAuth } from "../../components/auth/auth-provider"
+import type { AuthClient } from "../../lib/auth-client"
+import { unlinkAccountOptions } from "../../mutations/settings/unlink-account-options"
 import { useListAccounts } from "./use-list-accounts"
 
+export type UseUnlinkAccountParams = NonNullable<
+  Parameters<AuthClient["unlinkAccount"]>[0]
+>
+
+export type UseUnlinkAccountOptions = Omit<
+  ReturnType<typeof unlinkAccountOptions>,
+  "mutationKey" | "mutationFn"
+>
+
 /**
  * Hook that creates a mutation for unlinking a social provider from the current user.
  *
+ * Refetches the linked accounts list on success.
+ *
+ * @param options - React Query options forwarded to `useMutation`.
  * @returns The `useMutation` result.
  */
-export function useUnlinkAccount(
-  options?: UseAuthMutationOptions<AuthClient["unlinkAccount"]>
-) {
+export function useUnlinkAccount(options?: UseUnlinkAccountOptions) {
   const { authClient } = useAuth()
   const { refetch } = useListAccounts({ refetchOnMount: false })
 
-  return useAuthMutation({
-    authFn: authClient.unlinkAccount,
-    options: {
-      ...options,
-      onSuccess: async (...args) => {
-        await refetch()
-        await options?.onSuccess?.(...args)
-      }
+  return useMutation({
+    ...unlinkAccountOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
     }
   })
 }

package/src/hooks/settings/use-update-user.ts

@@ -1,44 +1,50 @@
-import {
-  type AuthClient,
-  useAuth,
-  useAuthMutation,
-  useSession
-} from "@better-auth-ui/react"
-import { useQueryClient } from "@tanstack/react-query"
-import type {
-  UseAuthMutationOptions,
-  UseAuthMutationResult
-} from "../auth/use-auth-mutation"
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+
+import { useAuth } from "../../components/auth/auth-provider"
+import type { AuthClient } from "../../lib/auth-client"
+import { updateUserOptions } from "../../mutations/settings/update-user-options"
+import { sessionOptions } from "../../queries/auth/session-options"
+import { useSession } from "../auth/use-session"
+
+export type UseUpdateUserParams = NonNullable<
+  Parameters<AuthClient["updateUser"]>[0]
+>
+
+export type UseUpdateUserOptions = Omit<
+  ReturnType<typeof updateUserOptions>,
+  "mutationKey" | "mutationFn"
+>
 
 /**
  * Hook that creates a mutation for updating the authenticated user's profile.
  *
- * The mutation submits the name update, refetches the session on success,
- * and displays success or error toasts.
+ * Optimistically merges the update into the cached session, then refetches
+ * the session to reconcile with the server.
  *
+ * @param options - React Query options forwarded to `useMutation`.
  * @returns The `useMutation` result.
  */
-export function useUpdateUser(
-  options?: UseAuthMutationOptions<AuthClient["updateUser"]>
-): UseAuthMutationResult<AuthClient["updateUser"]> {
+export function useUpdateUser(options?: UseUpdateUserOptions) {
   const { authClient } = useAuth()
-  const { data: session, refetch } = useSession({ refetchOnMount: false })
+  const { data: session, refetch: refetchSession } = useSession({
+    refetchOnMount: false
+  })
   const queryClient = useQueryClient()
 
-  return useAuthMutation({
-    authFn: authClient.updateUser,
-    options: {
-      ...options,
-      onSuccess: async (data, variables, ...rest) => {
-        queryClient.setQueryData(["auth", "getSession"], {
+  return useMutation({
+    ...updateUserOptions(authClient),
+    ...options,
+    onSuccess: async (data, variables, ...rest) => {
+      if (session) {
+        queryClient.setQueryData(sessionOptions(authClient).queryKey, {
           ...session,
-          user: { ...session?.user, ...variables }
+          user: { ...session.user, ...variables }
         })
+      }
 
-        refetch()
+      refetchSession()
 
-        await options?.onSuccess?.(data, variables, ...rest)
-      }
+      await options?.onSuccess?.(data, variables, ...rest)
     }
   })
 }

package/src/hooks/use-auth-mutation.ts

@@ -0,0 +1,29 @@
+import { type MutationKey, useMutation } from "@tanstack/react-query"
+import { authMutationOptions } from "../mutations/auth-mutation-options"
+
+/**
+ * Escape-hatch hook for Better Auth endpoints that don't have a purpose-built
+ * mutation hook in this library yet. Thin wrapper over `useMutation` and
+ * `authMutationOptions`.
+ *
+ * @param authFn - Better Auth client method (e.g. `authClient.emailOtp.sendVerificationOtp`).
+ * @param mutationKey - Scope for the mutation cache key.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useAuthMutation<
+  // biome-ignore lint/suspicious/noExplicitAny: matches authMutationOptions' widened constraint
+  TFn extends (...args: any) => any,
+  const TMutationKey extends MutationKey
+>(
+  authFn: TFn,
+  mutationKey: TMutationKey,
+  options?: Omit<
+    ReturnType<typeof authMutationOptions<TFn, TMutationKey>>,
+    "mutationKey" | "mutationFn"
+  >
+) {
+  return useMutation({
+    ...authMutationOptions(authFn, mutationKey),
+    ...options
+  })
+}

package/src/hooks/use-auth-query.ts

@@ -0,0 +1,36 @@
+import { type QueryKey, useQuery } from "@tanstack/react-query"
+import { type AuthFn, authQueryOptions } from "../queries/auth-query-options"
+
+type UseAuthQueryOptions<TFn extends AuthFn, TQueryKey extends QueryKey> = Omit<
+  ReturnType<typeof authQueryOptions<TFn, TQueryKey>>,
+  "queryKey" | "queryFn"
+> &
+  NonNullable<Parameters<TFn>[0]>
+
+/**
+ * Escape-hatch hook for Better Auth endpoints that don't have a purpose-built
+ * hook in this library yet. Thin wrapper over `useQuery` and `authQueryOptions`.
+ *
+ * @param authFn - Better Auth client method (e.g. `authClient.magicLink.list`).
+ * @param queryKey - Scope prefix for the key. `options.query` is appended automatically.
+ * @param options - Better Auth params (`query`, `fetchOptions`) and React
+ *   Query options forwarded to `useQuery`.
+ */
+export function useAuthQuery<
+  TFn extends AuthFn,
+  const TQueryKey extends QueryKey
+>(
+  authFn: TFn,
+  queryKey: TQueryKey,
+  options?: UseAuthQueryOptions<TFn, TQueryKey>
+) {
+  const { query, fetchOptions, ...queryOptions } = options ?? {}
+
+  return useQuery({
+    ...authQueryOptions(authFn, queryKey, {
+      query,
+      fetchOptions
+    } as Parameters<TFn>[0]),
+    ...queryOptions
+  })
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./components/email"
 export * from "./components/icons"
 export * from "./components/settings/account/theme-preview"
 export * from "./hooks/auth/use-authenticate"
+export * from "./hooks/auth/use-is-username-available"
 export * from "./hooks/auth/use-request-password-reset"
 export * from "./hooks/auth/use-reset-password"
 export * from "./hooks/auth/use-send-verification-email"
@@ -13,6 +14,7 @@ export * from "./hooks/auth/use-sign-in-email"
 export * from "./hooks/auth/use-sign-in-magic-link"
 export * from "./hooks/auth/use-sign-in-passkey"
 export * from "./hooks/auth/use-sign-in-social"
+export * from "./hooks/auth/use-sign-in-username"
 export * from "./hooks/auth/use-sign-out"
 export * from "./hooks/auth/use-sign-up-email"
 export * from "./hooks/auth/use-user"
@@ -32,6 +34,8 @@ export * from "./hooks/settings/use-revoke-session"
 export * from "./hooks/settings/use-set-active-session"
 export * from "./hooks/settings/use-unlink-account"
 export * from "./hooks/settings/use-update-user"
+export * from "./hooks/use-auth-mutation"
+export * from "./hooks/use-auth-query"
 export * from "./lib/auth-client"
 export * from "./lib/auth-config"
 export * from "./lib/auth-context"

package/src/lib/auth-config.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig as BaseAuthConfig } from "@better-auth-ui/react/core"
+import type { AuthConfig as BaseAuthConfig } from "@better-auth-ui/core"
 import type { ComponentType, PropsWithChildren } from "react"
 import type { AnyAuthClient, AuthClient } from "./auth-client"
 

package/src/mutations/auth/is-username-available-options.ts

@@ -0,0 +1,18 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * 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(authClient: AuthClient) {
+  return authMutationOptions<
+    typeof authClient.isUsernameAvailable,
+    ["auth", "isUsernameAvailable"],
+    { available: boolean; message: string | null }
+  >(authClient.isUsernameAvailable, ["auth", "isUsernameAvailable"])
+}

package/src/mutations/auth/request-password-reset-options.ts

@@ -0,0 +1,14 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for requesting a password reset email.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function requestPasswordResetOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.requestPasswordReset, [
+    "auth",
+    "requestPasswordReset"
+  ])
+}

package/src/mutations/auth/reset-password-options.ts

@@ -0,0 +1,14 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for completing a password reset.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function resetPasswordOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.resetPassword, [
+    "auth",
+    "resetPassword"
+  ])
+}

package/src/mutations/auth/send-verification-email-options.ts

@@ -0,0 +1,14 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for sending a verification email.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function sendVerificationEmailOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.sendVerificationEmail, [
+    "auth",
+    "sendVerificationEmail"
+  ])
+}

package/src/mutations/auth/sign-in-email-options.ts

@@ -0,0 +1,19 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for email/password sign-in.
+ *
+ * The returned `mutationKey` (`["auth", "signIn", "email"]`) is stable and
+ * can be passed to `useIsMutating` or matched inside a global
+ * `MutationCache` observer for toast handling.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInEmailOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signIn.email, [
+    "auth",
+    "signIn",
+    "email"
+  ])
+}

package/src/mutations/auth/sign-in-magic-link-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for magic-link sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInMagicLinkOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signIn.magicLink, [
+    "auth",
+    "signIn",
+    "magicLink"
+  ])
+}

package/src/mutations/auth/sign-in-passkey-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for passkey sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInPasskeyOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signIn.passkey, [
+    "auth",
+    "signIn",
+    "passkey"
+  ])
+}

package/src/mutations/auth/sign-in-social-options.ts

@@ -0,0 +1,19 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for social sign-in.
+ *
+ * The returned `mutationKey` (`["auth", "signIn", "social"]`) is stable and
+ * can be passed to `useIsMutating` or matched inside a global
+ * `MutationCache` observer for toast handling.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInSocialOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signIn.social, [
+    "auth",
+    "signIn",
+    "social"
+  ])
+}

package/src/mutations/auth/sign-in-username-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for username/password sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInUsernameOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signIn.username, [
+    "auth",
+    "signIn",
+    "username"
+  ])
+}

package/src/mutations/auth/sign-out-options.ts

@@ -0,0 +1,11 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for signing out.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signOutOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signOut, ["auth", "signOut"])
+}

package/src/mutations/auth/sign-up-email-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for email/password sign-up.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signUpEmailOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.signUp.email, [
+    "auth",
+    "signUp",
+    "email"
+  ])
+}

package/src/mutations/auth-mutation-options.ts

@@ -0,0 +1,49 @@
+import { type MutationKey, mutationOptions } from "@tanstack/react-query"
+import type { BetterFetchError, BetterFetchOption } from "better-auth/client"
+
+export type AuthMutationFn<TData = unknown, TVariables = unknown> = (
+  params: TVariables & { fetchOptions?: BetterFetchOption }
+) => Promise<{ data: TData }>
+
+type AuthMutationFnData<TFn> =
+  TFn extends AuthMutationFn<infer TData> ? TData : never
+
+// biome-ignore lint/suspicious/noExplicitAny: loose constraint for overloaded/generic signatures
+type AuthMutationFnVariables<TFn extends (...args: any) => any> =
+  undefined extends Parameters<TFn>[0]
+    ? // biome-ignore lint/suspicious/noConfusingVoidType: void lets `mutate()` be called with no arg
+      void | NonNullable<Parameters<TFn>[0]>
+    : Parameters<TFn>[0]
+
+/**
+ * Build `mutationOptions` for a Better Auth endpoint.
+ *
+ * Wires `throw: true` into `fetchOptions` so the mutation rejects with a
+ * `BetterFetchError` on failure instead of resolving with `{ error }`.
+ *
+ * TData is inferred from the endpoint's non-throw response shape. For
+ * required-body endpoints where inference falls back to `never`, pass
+ * `TData` explicitly (e.g. `authMutationOptions<_, _, { available: boolean }>`).
+ *
+ * @param authFn - Better Auth client method (e.g. `authClient.signIn.email`).
+ * @param mutationKey - Scope for the mutation cache key.
+ */
+export function authMutationOptions<
+  // biome-ignore lint/suspicious/noExplicitAny: constraint widened so required-body endpoints pass
+  TFn extends (...args: any) => any,
+  const TMutationKey extends MutationKey,
+  TData = AuthMutationFnData<TFn>
+>(authFn: TFn, mutationKey: TMutationKey) {
+  return mutationOptions<TData, BetterFetchError, AuthMutationFnVariables<TFn>>(
+    {
+      mutationKey,
+      mutationFn: (variables) => {
+        const v = variables as { fetchOptions?: BetterFetchOption } | undefined
+        return authFn({
+          ...v,
+          fetchOptions: { ...v?.fetchOptions, throw: true }
+        } as Parameters<TFn>[0]) as Promise<TData>
+      }
+    }
+  )
+}

package/src/mutations/settings/add-passkey-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for registering a new passkey.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function addPasskeyOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.passkey.addPasskey, [
+    "auth",
+    "passkey",
+    "addPasskey"
+  ])
+}

package/src/mutations/settings/change-email-options.ts

@@ -0,0 +1,11 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for changing the current user's email address.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function changeEmailOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.changeEmail, ["auth", "changeEmail"])
+}

package/src/mutations/settings/change-password-options.ts

@@ -0,0 +1,14 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for changing the authenticated user's password.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function changePasswordOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.changePassword, [
+    "auth",
+    "changePassword"
+  ])
+}

package/src/mutations/settings/delete-passkey-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for deleting a passkey.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function deletePasskeyOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.passkey.deletePasskey, [
+    "auth",
+    "passkey",
+    "deletePasskey"
+  ])
+}

package/src/mutations/settings/delete-user-options.ts

@@ -0,0 +1,11 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for deleting the authenticated user's account.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function deleteUserOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.deleteUser, ["auth", "deleteUser"])
+}

package/src/mutations/settings/link-social-options.ts

@@ -0,0 +1,11 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for linking a social provider to the current user.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function linkSocialOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.linkSocial, ["auth", "linkSocial"])
+}

package/src/mutations/settings/revoke-multi-session-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for revoking a device session in multi-session mode.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function revokeMultiSessionOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.multiSession.revoke, [
+    "auth",
+    "multiSession",
+    "revoke"
+  ])
+}