@better-auth-ui/react 1.6.3 → 1.6.5

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>
 }

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)
+    }
+  })
+}

package/src/mutations/passkey/add-passkey-mutation.ts

@@ -0,0 +1,66 @@
+import { passkeyMutationKeys } from "@better-auth-ui/core/plugins"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+import type { PasskeyAuthClient } from "../../lib/auth-client"
+import { useListPasskeys } from "../../queries/passkey/list-passkeys-query"
+
+export type AddPasskeyParams<TAuthClient extends PasskeyAuthClient> =
+  Parameters<TAuthClient["passkey"]["addPasskey"]>[0]
+
+export type AddPasskeyOptions<TAuthClient extends PasskeyAuthClient> = Omit<
+  ReturnType<typeof addPasskeyOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for registering a new passkey.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ */
+export function addPasskeyOptions<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = passkeyMutationKeys.addPasskey
+
+  // biome-ignore lint/suspicious/noConfusingVoidType: void allows no-arg mutate
+  const mutationFn = (params?: AddPasskeyParams<TAuthClient> | void) =>
+    authClient.passkey.addPasskey({
+      ...(params ?? {}),
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for registering a new passkey.
+ *
+ * Wraps `authClient.passkey.addPasskey`, refetches the user's passkey list
+ * on success, and forwards React Query mutation options such as
+ * `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useAddPasskey<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  options?: AddPasskeyOptions<TAuthClient>
+) {
+  const { refetch } = useListPasskeys(authClient, { refetchOnMount: false })
+
+  return useMutation({
+    ...addPasskeyOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/passkey/delete-passkey-mutation.ts

@@ -0,0 +1,66 @@
+import { passkeyMutationKeys } from "@better-auth-ui/core/plugins"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { PasskeyAuthClient } from "../../lib/auth-client"
+import { useListPasskeys } from "../../queries/passkey/list-passkeys-query"
+
+export type DeletePasskeyParams<TAuthClient extends PasskeyAuthClient> =
+  Parameters<TAuthClient["passkey"]["deletePasskey"]>[0]
+
+export type DeletePasskeyOptions<TAuthClient extends PasskeyAuthClient> = Omit<
+  ReturnType<typeof deletePasskeyOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for deleting a passkey.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function deletePasskeyOptions<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = passkeyMutationKeys.deletePasskey
+
+  const mutationFn = (params: DeletePasskeyParams<TAuthClient>) =>
+    authClient.passkey.deletePasskey({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for deleting a passkey.
+ *
+ * Wraps `authClient.passkey.deletePasskey`, refetches the user's passkey
+ * list on success, and forwards React Query mutation options such as
+ * `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useDeletePasskey<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  options?: DeletePasskeyOptions<TAuthClient>
+) {
+  const { refetch } = useListPasskeys(authClient, { refetchOnMount: false })
+
+  return useMutation({
+    ...deletePasskeyOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      await refetch()
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/mutations/passkey/sign-in-passkey-mutation.ts

@@ -0,0 +1,74 @@
+import { passkeyMutationKeys } from "@better-auth-ui/core/plugins"
+import {
+  mutationOptions,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { PasskeyAuthClient } from "../../lib/auth-client"
+import { sessionOptions } from "../../queries/auth/session-query"
+
+export type SignInPasskeyParams<TAuthClient extends PasskeyAuthClient> =
+  Parameters<TAuthClient["signIn"]["passkey"]>[0]
+
+export type SignInPasskeyOptions<TAuthClient extends PasskeyAuthClient> = Omit<
+  ReturnType<typeof signInPasskeyOptions<TAuthClient>>,
+  "mutationKey" | "mutationFn"
+>
+
+/**
+ * Mutation options factory for passkey sign-in.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ */
+export function signInPasskeyOptions<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = passkeyMutationKeys.signIn
+
+  // biome-ignore lint/suspicious/noConfusingVoidType: void allows no-arg mutate
+  const mutationFn = (params?: SignInPasskeyParams<TAuthClient> | void) =>
+    authClient.signIn.passkey({
+      ...(params ?? {}),
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for passkey sign-in.
+ *
+ * Wraps `authClient.signIn.passkey`, 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 passkey plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignInPasskey<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  options?: SignInPasskeyOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signInPasskeyOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.resetQueries({
+        queryKey: sessionOptions(authClient).queryKey
+      })
+
+      await options?.onSuccess?.(...args)
+    }
+  })
+}