@better-auth-ui/react 1.6.2 → 1.6.3

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

@@ -1,43 +1,50 @@
-import { useQueryClient } from "@tanstack/react-query"
+import { useMutation, useQueryClient } from "@tanstack/react-query"
 
 import { useAuth } from "../../components/auth/auth-provider"
 import type { AuthClient } from "../../lib/auth-client"
-import {
-  type UseAuthMutationOptions,
-  type UseAuthMutationResult,
-  useAuthMutation
-} from "../auth/use-auth-mutation"
+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

@@ -4,8 +4,6 @@ export * from "./components/auth/auth-provider"
 export * from "./components/email"
 export * from "./components/icons"
 export * from "./components/settings/account/theme-preview"
-export * from "./hooks/auth/use-auth-mutation"
-export * from "./hooks/auth/use-auth-query"
 export * from "./hooks/auth/use-authenticate"
 export * from "./hooks/auth/use-is-username-available"
 export * from "./hooks/auth/use-request-password-reset"
@@ -36,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/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"
+  ])
+}

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

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

package/src/mutations/settings/set-active-session-options.ts

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for switching the active device session.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function setActiveSessionOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.multiSession.setActive, [
+    "auth",
+    "multiSession",
+    "setActive"
+  ])
+}

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

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

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

@@ -0,0 +1,15 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authMutationOptions } from "../auth-mutation-options"
+
+/**
+ * Mutation options factory for updating the authenticated user's profile.
+ *
+ * The returned `mutationKey` (`["auth", "updateUser"]`) 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 updateUserOptions(authClient: AuthClient) {
+  return authMutationOptions(authClient.updateUser, ["auth", "updateUser"])
+}

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

@@ -0,0 +1,18 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authQueryOptions } from "../auth-query-options"
+
+/**
+ * Query options factory for the current session.
+ *
+ * Access `.queryKey` on the returned options for cache seeding or
+ * invalidation: `queryClient.setQueryData(sessionOptions(authClient).queryKey, session)`.
+ *
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export function sessionOptions(
+  authClient: AuthClient,
+  params?: Parameters<AuthClient["getSession"]>[0]
+) {
+  return authQueryOptions(authClient.getSession, ["auth", "getSession"], params)
+}

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

@@ -0,0 +1,34 @@
+import { type QueryKey, queryOptions } from "@tanstack/react-query"
+import type { BetterFetchError, BetterFetchOption } from "better-auth/client"
+
+export type AuthFn<TData = unknown> = (params: {
+  query?: Record<string, unknown>
+  fetchOptions?: BetterFetchOption
+}) => Promise<{ data: TData }>
+
+type AuthFnData<TFn> = TFn extends AuthFn<infer TData> ? TData : never
+
+/**
+ * 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`.
+ *
+ * @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>({
+    queryKey: [...queryKey, params?.query ?? null] as const,
+    queryFn: ({ signal }) =>
+      authFn({
+        ...params,
+        fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+      }) as Promise<AuthFnData<TFn>>
+  })
+}

package/src/queries/settings/account-info-options.ts

@@ -0,0 +1,25 @@
+import type { AuthClient } from "../../lib/auth-client"
+import { authQueryOptions } from "../auth-query-options"
+
+/**
+ * Query options factory for provider-specific account info.
+ *
+ * Keyed per-user. `userId` and `params` are both optional so the factory can
+ * build stable options before either is known — the consumer swaps `queryFn`
+ * for `skipToken` until ready.
+ *
+ * @param authClient - The Better Auth client.
+ * @param userId - The current signed in user's ID.
+ * @param params - Parameters forwarded to `authClient.accountInfo`.
+ */
+export function accountInfoOptions(
+  authClient: AuthClient,
+  userId?: string,
+  params?: Parameters<AuthClient["accountInfo"]>[0]
+) {
+  return authQueryOptions(
+    authClient.accountInfo,
+    ["auth", "user", userId, "accountInfo"],
+    params
+  )
+}