@better-auth-ui/react 1.6.3 → 1.6.4

package/src/lib/auth-server.ts

@@ -0,0 +1,30 @@
+import type { passkey } from "@better-auth/passkey"
+import type { Auth } from "better-auth"
+import type { magicLink, multiSession, username } from "better-auth/plugins"
+
+export type AuthServer = Pick<Auth, "api">
+
+// Per-plugin variants mirror the client-side types in `auth-client.ts` so
+// server-side query factories can depend on a narrow `auth` shape that
+// includes the plugin's API surface without requiring the full `betterAuth`
+// return type to be threaded through as a generic.
+
+export type MagicLinkAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof magicLink>] }>,
+  "api"
+>
+
+export type MultiSessionAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof multiSession>] }>,
+  "api"
+>
+
+export type PasskeyAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof passkey>] }>,
+  "api"
+>
+
+export type UsernameAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof username>] }>,
+  "api"
+>

package/src/mutations/auth/request-password-reset-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 RequestPasswordResetParams<TAuthClient extends AuthClient> =
+  Parameters<TAuthClient["requestPasswordReset"]>[0]
+
+export type RequestPasswordResetOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof requestPasswordResetOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for requesting a password reset email.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function requestPasswordResetOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.requestPasswordReset
+
+  const mutationFn = (params: RequestPasswordResetParams<TAuthClient>) =>
+    authClient.requestPasswordReset({
+      ...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 password reset email.
+ *
+ * Wraps `authClient.requestPasswordReset` 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 useRequestPasswordReset<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: RequestPasswordResetOptions<TAuthClient>
+) {
+  return useMutation({
+    ...requestPasswordResetOptions(authClient),
+    ...options
+  })
+}

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

@@ -0,0 +1,60 @@
+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 ResetPasswordParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["resetPassword"]
+>[0]
+
+export type ResetPasswordOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof resetPasswordOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for completing a password reset.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function resetPasswordOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.resetPassword
+
+  const mutationFn = (params: ResetPasswordParams<TAuthClient>) =>
+    authClient.resetPassword({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for completing a password reset.
+ *
+ * Wraps `authClient.resetPassword` (using the token from the reset 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 useResetPassword<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: ResetPasswordOptions<TAuthClient>
+) {
+  return useMutation({
+    ...resetPasswordOptions(authClient),
+    ...options
+  })
+}

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

@@ -1,49 +1,94 @@
-import { type MutationKey, mutationOptions } from "@tanstack/react-query"
+import {
+  type MutationKey,
+  mutationOptions,
+  type UseMutationOptions
+} 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
+/**
+ * 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>
 
-// 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]
+/**
+ * Resolved data type returned by an {@link AuthMutationFn}.
+ */
+export type AuthMutationFnData<TFn extends AuthMutationFn> = Awaited<
+  ReturnType<TFn>
+>
 
 /**
- * Build `mutationOptions` for a Better Auth endpoint.
+ * Variables type accepted by `mutate` / `mutateAsync` for a given
+ * {@link AuthMutationFn}.
  *
- * Wires `throw: true` into `fetchOptions` so the mutation rejects with a
- * `BetterFetchError` on failure instead of resolving with `{ error }`.
+ * 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.
  *
- * 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 }>`).
+ * 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.signIn.email`).
- * @param mutationKey - Scope for the mutation cache key.
+ * @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<
-  // 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>
-      }
-    }
-  )
+  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>
 }