@better-auth-ui/react 1.6.3 → 1.6.5

package/src/mutations/settings/change-email-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 { useSession } from "../../queries/auth/session-query"
+
+export type ChangeEmailParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["changeEmail"]
+>[0]
+
+export type ChangeEmailOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof changeEmailOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for changing the current user's email address.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function changeEmailOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.changeEmail
+
+  const mutationFn = (params: ChangeEmailParams<TAuthClient>) =>
+    authClient.changeEmail({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for changing the current user's email address.
+ *
+ * Wraps `authClient.changeEmail`, refetches the session on success to
+ * surface the new email, 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 useChangeEmail<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: ChangeEmailOptions<TAuthClient>
+) {
+  const { refetch } = useSession(authClient, { refetchOnMount: false })
+
+  return useMutation({
+    ...changeEmailOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

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

@@ -0,0 +1,59 @@
+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"
+
+export type ChangePasswordParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["changePassword"]
+>[0]
+
+export type ChangePasswordOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof changePasswordOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for changing the authenticated user's password.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function changePasswordOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.changePassword
+
+  const mutationFn = (params: ChangePasswordParams<TAuthClient>) =>
+    authClient.changePassword({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for changing the authenticated user's password.
+ *
+ * Wraps `authClient.changePassword` 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 useChangePassword<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: ChangePasswordOptions<TAuthClient>
+) {
+  return useMutation({
+    ...changePasswordOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,59 @@
+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"
+
+export type DeleteUserParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["deleteUser"]
+>[0]
+
+export type DeleteUserOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof deleteUserOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for deleting the authenticated user's account.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function deleteUserOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.deleteUser
+
+  const mutationFn = (params: DeleteUserParams<TAuthClient>) =>
+    authClient.deleteUser({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for deleting the authenticated user's account.
+ *
+ * Wraps `authClient.deleteUser` 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 useDeleteUser<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: DeleteUserOptions<TAuthClient>
+) {
+  return useMutation({
+    ...deleteUserOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,59 @@
+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"
+
+export type LinkSocialParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["linkSocial"]
+>[0]
+
+export type LinkSocialOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof linkSocialOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for linking a social provider to the current user.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function linkSocialOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.linkSocial
+
+  const mutationFn = (params: LinkSocialParams<TAuthClient>) =>
+    authClient.linkSocial({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for linking a social provider to the current user.
+ *
+ * Wraps `authClient.linkSocial` to initiate a provider redirect 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 useLinkSocial<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: LinkSocialOptions<TAuthClient>
+) {
+  return useMutation({
+    ...linkSocialOptions(authClient),
+    ...options
+  })
+}

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/plugins/captcha-plugin.tsx

@@ -0,0 +1,75 @@
+"use client"
+
+import { createAuthPlugin } from "@better-auth-ui/core"
+import {
+  type ComponentType,
+  type ReactNode,
+  useCallback,
+  useEffect
+} from "react"
+import { useFetchOptions } from "../components/auth/fetch-options-provider"
+import { useAuthPlugin } from "../hooks/use-auth-plugin"
+
+/** Props passed to the consumer's `render` component. */
+export type CaptchaRenderProps = {
+  /** Call once the user solves the captcha. */
+  setToken: (token: string) => void
+  /** Call on error/expire to clear the token. */
+  clearToken: () => void
+  /**
+   * Register your widget's `reset()`. Forms call it after a failed
+   * submission since captcha tokens are single-use. Pass `null` on unmount.
+   */
+  setReset: (reset: (() => void) | null) => void
+}
+
+export type CaptchaPluginOptions = {
+  /** Renders the captcha widget. Wire `setToken`, `clearToken`, `setReset`. */
+  render: ComponentType<CaptchaRenderProps>
+}
+
+function CaptchaWidget(): ReactNode {
+  const { render: Render } = useAuthPlugin(captchaPlugin)
+  const { setFetchOptions, registerReset } = useFetchOptions()
+
+  const setToken = useCallback(
+    (token: string) => {
+      setFetchOptions({ headers: { "x-captcha-response": token } })
+    },
+    [setFetchOptions]
+  )
+
+  const clearToken = useCallback(() => {
+    setFetchOptions(undefined)
+  }, [setFetchOptions])
+
+  const setReset = useCallback(
+    (reset: (() => void) | null) => {
+      registerReset(reset)
+    },
+    [registerReset]
+  )
+
+  useEffect(() => {
+    return () => {
+      setFetchOptions(undefined)
+      registerReset(null)
+    }
+  }, [setFetchOptions, registerReset])
+
+  return (
+    <Render setToken={setToken} clearToken={clearToken} setReset={setReset} />
+  )
+}
+
+/**
+ * Provider-agnostic captcha plugin. Forwards the resolved token via the
+ * `x-captcha-response` header on Better Auth requests.
+ */
+export const captchaPlugin = createAuthPlugin(
+  "captcha",
+  ({ render }: CaptchaPluginOptions) => ({
+    render,
+    captchaComponent: <CaptchaWidget />
+  })
+)

package/src/plugins.ts

@@ -0,0 +1,3 @@
+"use client"
+
+export * from "./plugins/captcha-plugin"