@better-auth-ui/react 1.6.2 → 1.6.4

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

@@ -0,0 +1,58 @@
+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 SendVerificationEmailParams<TAuthClient extends AuthClient> =
+  Parameters<TAuthClient["sendVerificationEmail"]>[0]
+
+export type SendVerificationEmailOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof sendVerificationEmailOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for sending a verification email.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function sendVerificationEmailOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.sendVerificationEmail
+
+  const mutationFn = (params: SendVerificationEmailParams<TAuthClient>) =>
+    authClient.sendVerificationEmail({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for sending an email-verification link.
+ *
+ * Wraps `authClient.sendVerificationEmail` 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 useSendVerificationEmail<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: SendVerificationEmailOptions<TAuthClient>
+) {
+  return useMutation({
+    ...sendVerificationEmailOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,78 @@
+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 } from "../../queries/auth/session-query"
+
+export type SignInEmailParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["signIn"]["email"]
+>[0]
+
+export type SignInEmailOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof signInEmailOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for email/password sign-in.
+ *
+ * The returned `mutationKey` (`authMutationKeys.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<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signIn.email
+
+  const mutationFn = (params: SignInEmailParams<TAuthClient>) =>
+    authClient.signIn.email({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for email/password sign-in.
+ *
+ * Wraps `authClient.signIn.email`, 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.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignInEmail<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: SignInEmailOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signInEmailOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.resetQueries({
+        queryKey: sessionOptions(authClient).queryKey
+      })
+
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

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

@@ -0,0 +1,64 @@
+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 SignInSocialParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["signIn"]["social"]
+>[0]
+
+export type SignInSocialOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof signInSocialOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * 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<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signIn.social
+
+  const mutationFn = (params: SignInSocialParams<TAuthClient>) =>
+    authClient.signIn.social({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for social sign-in.
+ *
+ * Wraps `authClient.signIn.social` 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 useSignInSocial<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: SignInSocialOptions<TAuthClient>
+) {
+  return useMutation({
+    ...signInSocialOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,71 @@
+import { authMutationKeys, authQueryKeys } 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"
+
+export type SignOutParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["signOut"]
+>[0]
+
+export type SignOutOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof signOutOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for signing out.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signOutOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signOut
+
+  // biome-ignore lint/suspicious/noConfusingVoidType: void allows no-arg mutate
+  const mutationFn = (params?: SignOutParams<TAuthClient> | void) =>
+    authClient.signOut({
+      ...(params ?? {}),
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for signing the current user out.
+ *
+ * Wraps `authClient.signOut`, removes all cached auth queries 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 useSignOut<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: SignOutOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signOutOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.removeQueries({ queryKey: authQueryKeys.all })
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/auth/sign-up-email-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 { AuthClient } from "../../lib/auth-client"
+import { sessionOptions } from "../../queries/auth/session-query"
+
+export type SignUpEmailParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["signUp"]["email"]
+>[0]
+
+export type SignUpEmailOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof signUpEmailOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for email/password sign-up.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signUpEmailOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signUp.email
+
+  const mutationFn = (params: SignUpEmailParams<TAuthClient>) =>
+    authClient.signUp.email({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for email/password sign-up.
+ *
+ * Wraps `authClient.signUp.email`, 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.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignUpEmail<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: SignUpEmailOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signUpEmailOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.resetQueries({
+        queryKey: sessionOptions(authClient).queryKey
+      })
+
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

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

@@ -0,0 +1,94 @@
+import {
+  type MutationKey,
+  mutationOptions,
+  type UseMutationOptions
+} from "@tanstack/react-query"
+import type { BetterFetchError, BetterFetchOption } from "better-auth/client"
+
+/**
+ * Write-style Better Auth client method. Variables are a single object that
+ * may carry top-level params plus `fetchOptions` (e.g. `signIn.email` takes
+ * `{ email, password, rememberMe?, fetchOptions? }`).
+ *
+ * Read-style endpoints use `AuthQueryFn` / `useAuthQuery` instead.
+ */
+export type AuthMutationFn = (
+  // biome-ignore lint/suspicious/noExplicitAny: variance bridge for arbitrary Better Auth client methods
+  variables: any
+) => Promise<unknown>
+
+/**
+ * Resolved data type returned by an {@link AuthMutationFn}.
+ */
+export type AuthMutationFnData<TFn extends AuthMutationFn> = Awaited<
+  ReturnType<TFn>
+>
+
+/**
+ * Variables type accepted by `mutate` / `mutateAsync` for a given
+ * {@link AuthMutationFn}.
+ *
+ * If the method's params are entirely optional (e.g. `authClient.signOut`),
+ * this resolves to `Variables | void` so `mutate()` is callable without
+ * arguments. Otherwise it resolves to the exact required shape so the type
+ * checker rejects `mutate()` when the underlying call needs params.
+ */
+export type AuthMutationFnVariables<TFn extends AuthMutationFn> =
+  Parameters<TFn>[0] extends infer P
+    ? undefined extends P
+      ? // biome-ignore lint/suspicious/noConfusingVoidType: void allows no-arg mutate
+        NonNullable<P> | void
+      : P
+    : never
+
+/**
+ * Return type of {@link authMutationOptions}, matching the shape produced by
+ * TanStack Query's own `mutationOptions` helper.
+ */
+export type AuthMutationOptions<
+  TFn extends AuthMutationFn,
+  TMutationKey extends MutationKey = MutationKey
+> = Omit<
+  UseMutationOptions<
+    AuthMutationFnData<TFn>,
+    BetterFetchError,
+    AuthMutationFnVariables<TFn>
+  >,
+  "mutationKey"
+> & {
+  mutationKey: TMutationKey
+}
+
+/**
+ * Build `mutationOptions` for a write-style Better Auth endpoint.
+ *
+ * Injects `throw: true` into `fetchOptions` so the promise rejects with a
+ * `BetterFetchError` on failure instead of resolving to `{ data, error }`.
+ *
+ * @param authFn - Better Auth client method (e.g. `authClient.emailOtp.sendVerificationOtp`).
+ * @param mutationKey - Stable key for the mutation (used by `useIsMutating`, `MutationCache`, …).
+ */
+export function authMutationOptions<
+  TFn extends AuthMutationFn,
+  const TMutationKey extends MutationKey
+>(
+  authFn: TFn,
+  mutationKey: TMutationKey
+): AuthMutationOptions<TFn, TMutationKey> {
+  const mutationFn = (variables: AuthMutationFnVariables<TFn>) => {
+    const vars = (variables ?? {}) as { fetchOptions?: BetterFetchOption }
+    return authFn({
+      ...vars,
+      fetchOptions: { ...vars.fetchOptions, throw: true }
+    }) as Promise<AuthMutationFnData<TFn>>
+  }
+
+  return mutationOptions<
+    AuthMutationFnData<TFn>,
+    BetterFetchError,
+    AuthMutationFnVariables<TFn>
+  >({
+    mutationKey,
+    mutationFn
+  }) as AuthMutationOptions<TFn, TMutationKey>
+}

package/src/mutations/magic-link/sign-in-magic-link-mutation.ts

@@ -0,0 +1,59 @@
+import { magicLinkMutationKeys } from "@better-auth-ui/core/plugins"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { MagicLinkAuthClient } from "../../lib/auth-client"
+
+export type SignInMagicLinkParams<TAuthClient extends MagicLinkAuthClient> =
+  Parameters<TAuthClient["signIn"]["magicLink"]>[0]
+
+export type SignInMagicLinkOptions<TAuthClient extends MagicLinkAuthClient> =
+  Omit<
+    ReturnType<typeof signInMagicLinkOptions<TAuthClient>>,
+    "mutationKey" | "mutationFn"
+  >
+
+/**
+ * Mutation options factory for magic-link sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInMagicLinkOptions<TAuthClient extends MagicLinkAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = magicLinkMutationKeys.signIn
+
+  const mutationFn = (params: SignInMagicLinkParams<TAuthClient>) =>
+    authClient.signIn.magicLink({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for requesting a magic-link sign-in email.
+ *
+ * Wraps `authClient.signIn.magicLink` and forwards React Query mutation
+ * options such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the magic-link plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignInMagicLink<TAuthClient extends MagicLinkAuthClient>(
+  authClient: TAuthClient,
+  options?: SignInMagicLinkOptions<TAuthClient>
+) {
+  return useMutation({
+    ...signInMagicLinkOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,70 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { MultiSessionAuthClient } from "../../lib/auth-client"
+import { useListDeviceSessions } from "../../queries/multi-session/list-device-sessions-query"
+
+export type RevokeMultiSessionParams<
+  TAuthClient extends MultiSessionAuthClient
+> = Parameters<TAuthClient["multiSession"]["revoke"]>[0]
+
+export type RevokeMultiSessionOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = Omit<
+  ReturnType<typeof revokeMultiSessionOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for revoking a device session in multi-session mode.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ */
+export function revokeMultiSessionOptions<
+  TAuthClient extends MultiSessionAuthClient
+>(authClient: TAuthClient) {
+  const mutationKey = authMutationKeys.multiSession.revoke
+
+  const mutationFn = (params: RevokeMultiSessionParams<TAuthClient>) =>
+    authClient.multiSession.revoke({
+      ...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 device session in multi-session mode.
+ *
+ * Wraps `authClient.multiSession.revoke`, refetches the device sessions list
+ * on success, and forwards React Query mutation options such as `onSuccess`,
+ * `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useRevokeMultiSession<
+  TAuthClient extends MultiSessionAuthClient
+>(authClient: TAuthClient, options?: RevokeMultiSessionOptions<TAuthClient>) {
+  const { refetch } = useListDeviceSessions(authClient, {
+    refetchOnMount: false
+  })
+
+  return useMutation({
+    ...revokeMultiSessionOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/multi-session/set-active-session-mutation.ts

@@ -0,0 +1,98 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import {
+  mutationOptions,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { MultiSessionAuthClient } from "../../lib/auth-client"
+import {
+  type SessionData,
+  sessionOptions,
+  useSession
+} from "../../queries/auth/session-query"
+import { useListDeviceSessions } from "../../queries/multi-session/list-device-sessions-query"
+
+export type SetActiveSessionParams<TAuthClient extends MultiSessionAuthClient> =
+  Parameters<TAuthClient["multiSession"]["setActive"]>[0]
+
+export type SetActiveSessionOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = Omit<
+  ReturnType<typeof setActiveSessionOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for switching the active device session.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ */
+export function setActiveSessionOptions<
+  TAuthClient extends MultiSessionAuthClient
+>(authClient: TAuthClient) {
+  const mutationKey = authMutationKeys.multiSession.setActive
+
+  const mutationFn = (params: SetActiveSessionParams<TAuthClient>) =>
+    authClient.multiSession.setActive({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for switching the active device session.
+ *
+ * Wraps `authClient.multiSession.setActive`, optimistically swaps the cached
+ * session to the matching device session, refetches both the session and
+ * device-session queries, and forwards React Query mutation options such as
+ * `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSetActiveSession<TAuthClient extends MultiSessionAuthClient>(
+  authClient: TAuthClient,
+  options?: SetActiveSessionOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+  const { refetch: refetchSession } = useSession(authClient, {
+    refetchOnMount: false
+  })
+  const { data: deviceSessions, refetch: refetchDeviceSessions } =
+    useListDeviceSessions(authClient, {
+      refetchOnMount: false
+    })
+
+  return useMutation({
+    ...setActiveSessionOptions(authClient),
+    ...options,
+    onSuccess: async (data, variables, ...rest) => {
+      const sessionToken = variables?.sessionToken
+      const deviceSession = deviceSessions?.find(
+        ({ session: { token } }) => token === sessionToken
+      )
+
+      if (deviceSession) {
+        queryClient.setQueryData(
+          sessionOptions(authClient).queryKey,
+          deviceSession as SessionData<TAuthClient>
+        )
+      }
+
+      await refetchSession()
+      await refetchDeviceSessions()
+      await options?.onSuccess?.(data, variables, ...rest)
+    }
+  })
+}