@better-auth-ui/react 1.6.7 → 1.6.9

package/src/components/mutation-invalidator.tsx

@@ -0,0 +1,67 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import {
+  matchMutation,
+  matchQuery,
+  type QueryKey,
+  useQueryClient
+} from "@tanstack/react-query"
+import { useEffect } from "react"
+
+type AuthMutationMeta = {
+  invalidates?: Array<QueryKey>
+  awaits?: Array<QueryKey>
+}
+
+export function MutationInvalidator() {
+  const queryClient = useQueryClient()
+
+  useEffect(() => {
+    const mutationCache = queryClient.getMutationCache()
+    const previousOnSuccess = mutationCache.config.onSuccess
+
+    mutationCache.config.onSuccess = async (
+      data,
+      variables,
+      onMutateResult,
+      mutation,
+      context
+    ) => {
+      await previousOnSuccess?.(
+        data,
+        variables,
+        onMutateResult,
+        mutation,
+        context
+      )
+
+      if (!matchMutation({ mutationKey: authMutationKeys.all }, mutation)) {
+        return
+      }
+
+      const { invalidates, awaits } = (mutation.meta ?? {}) as AuthMutationMeta
+
+      if (invalidates?.length) {
+        queryClient.invalidateQueries({
+          predicate: (query) =>
+            invalidates.some((queryKey) => matchQuery({ queryKey }, query))
+        })
+      }
+
+      if (awaits?.length) {
+        return queryClient.invalidateQueries(
+          {
+            predicate: (query) =>
+              awaits.some((queryKey) => matchQuery({ queryKey }, query))
+          },
+          { cancelRefetch: false }
+        )
+      }
+    }
+
+    return () => {
+      mutationCache.config.onSuccess = previousOnSuccess
+    }
+  }, [queryClient])
+
+  return null
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./hooks/use-auth-query"
 export type * from "./lib/auth-client"
 export * from "./lib/auth-plugin"
 export * from "./lib/provider-icons"
+export * from "./lib/settings-tab"
 export * from "./mutations/api-key/create-api-key-mutation"
 export * from "./mutations/api-key/delete-api-key-mutation"
 export * from "./mutations/auth/request-password-reset-mutation"
@@ -25,6 +26,7 @@ export * from "./mutations/auth-mutation-options"
 export * from "./mutations/magic-link/sign-in-magic-link-mutation"
 export * from "./mutations/multi-session/revoke-multi-session-mutation"
 export * from "./mutations/multi-session/set-active-session-mutation"
+export * from "./mutations/organization"
 export * from "./mutations/passkey/add-passkey-mutation"
 export * from "./mutations/passkey/delete-passkey-mutation"
 export * from "./mutations/passkey/sign-in-passkey-mutation"
@@ -41,6 +43,7 @@ export * from "./queries/api-key/list-api-keys-query"
 export * from "./queries/auth/session-query"
 export * from "./queries/auth-query-options"
 export * from "./queries/multi-session/list-device-sessions-query"
+export * from "./queries/organization"
 export * from "./queries/passkey/list-passkeys-query"
 export * from "./queries/settings/account-info-query"
 export * from "./queries/settings/list-accounts-query"

package/src/lib/auth-client.ts

@@ -3,6 +3,7 @@ import type { passkeyClient } from "@better-auth/passkey/client"
 import type {
   magicLinkClient,
   multiSessionClient,
+  organizationClient,
   usernameClient
 } from "better-auth/client/plugins"
 import type { createAuthClient } from "better-auth/react"
@@ -35,6 +36,12 @@ export type UsernameAuthClient = ReturnType<
   typeof createAuthClient<{ plugins: [ReturnType<typeof usernameClient>] }>
 >
 
+export type OrganizationAuthClient = ReturnType<
+  typeof createAuthClient<{
+    plugins: [ReturnType<typeof organizationClient<object>>]
+  }>
+>
+
 /**
  * Unwraps a Better Auth client method's `data` payload.
  *

package/src/lib/auth-plugin.ts

@@ -1,5 +1,6 @@
 import type { AuthPluginBase, AuthView } from "@better-auth-ui/core"
 import type { ComponentType, ReactNode } from "react"
+import type { SettingsTab } from "./settings-tab"
 
 export type { AuthPluginViewPaths } from "@better-auth-ui/core"
 
@@ -23,9 +24,17 @@ export type AccountCardProps = {
   children?: ReactNode
 }
 
+/** Props for plugin-contributed cards under `/organization/...` settings. */
+export type OrganizationCardProps = {
+  className?: string
+  children?: ReactNode
+}
+
 /** Props for plugin-contributed items in the `UserButton` dropdown. */
 export type UserMenuItemProps = {
   className?: string
+  /** When true, the subtitle line (email when name/username is shown) is hidden. */
+  hideSubtitle?: boolean
 }
 
 /** Framework-agnostic slot component shapes. UI packages narrow these via `TComponents`. */
@@ -38,6 +47,8 @@ export type AuthPluginComponents = {
   securityCards?: ComponentType<SecurityCardProps>[]
   /** Rendered as cards inside account settings. */
   accountCards?: ComponentType<AccountCardProps>[]
+  /** Rendered as cards inside the active organization's settings. */
+  organizationCards?: ComponentType<OrganizationCardProps>[]
   /** Rendered as items inside the `UserButton` dropdown. */
   userMenuItems?: ComponentType<UserMenuItemProps>[]
 }
@@ -74,4 +85,10 @@ export type AuthPlugin<
   TComponents & {
     views?: AuthPluginViews<TAuthViewProps, TSettingsViewProps>
     fallbackViews?: AuthPluginFallbackViews<TAuthViewProps>
+    /**
+     * Tabs the plugin contributes to the settings page. Each entry is a
+     * {@link SettingsTab} (`view`, `label`, `component`). Read at runtime via
+     * `useAuthPlugin(plugin).settingsTabs`.
+     */
+    settingsTabs?: SettingsTab[]
   }

package/src/lib/auth-server.ts

@@ -1,6 +1,12 @@
+import type { apiKey } from "@better-auth/api-key"
 import type { passkey } from "@better-auth/passkey"
 import type { Auth } from "better-auth"
-import type { magicLink, multiSession, username } from "better-auth/plugins"
+import type {
+  magicLink,
+  multiSession,
+  organization,
+  username
+} from "better-auth/plugins"
 
 export type AuthServer = Pick<Auth, "api">
 
@@ -24,7 +30,17 @@ export type PasskeyAuthServer = Pick<
   "api"
 >
 
+export type ApiKeyAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof apiKey>] }>,
+  "api"
+>
+
 export type UsernameAuthServer = Pick<
   Auth<{ plugins: [ReturnType<typeof username>] }>,
   "api"
 >
+
+export type OrganizationAuthServer = Pick<
+  Auth<{ plugins: [ReturnType<typeof organization>] }>,
+  "api"
+>

package/src/lib/settings-tab.ts

@@ -0,0 +1,21 @@
+import type { SettingsView } from "@better-auth-ui/core"
+import type { ComponentType, ReactNode } from "react"
+
+/**
+ * Tab contributions for the settings page.
+ *
+ * Plugins declare `settingsTabs` on their object to add extra tabs.
+ * Read at runtime via `useAuthPlugin(plugin).settingsTabs`.
+ */
+export interface SettingsTab {
+  /**
+   * Settings view id — must match a key on `plugin.viewPaths.settings` and
+   * {@link SettingsView} (including keys added via `declare module` augmentation).
+   */
+  view: SettingsView
+  /** Display label */
+  label: ReactNode
+  /** Component rendered in the tab panel */
+  // biome-ignore lint/suspicious/noExplicitAny: any
+  component: ComponentType<any>
+}

package/src/mutations/api-key/create-api-key-mutation.ts

@@ -1,16 +1,26 @@
-import { apiKeyMutationKeys } from "@better-auth-ui/core/plugins"
-import { mutationOptions, useMutation } from "@tanstack/react-query"
+import {
+  apiKeyMutationKeys,
+  apiKeyQueryKeys
+} from "@better-auth-ui/core/plugins"
+import {
+  mutationOptions,
+  type QueryClient,
+  useMutation
+} from "@tanstack/react-query"
 import type { BetterFetchError } from "better-auth/react"
 
 import type { ApiKeyAuthClient } from "../../lib/auth-client"
-import { useListApiKeys } from "../../queries/api-key/list-api-keys-query"
+import { useSession } from "../../queries/auth/session-query"
 
-export type CreateApiKeyParams<TAuthClient extends ApiKeyAuthClient> =
-  Parameters<TAuthClient["apiKey"]["create"]>[0]
+export type CreateApiKeyParams<
+  TAuthClient extends ApiKeyAuthClient = ApiKeyAuthClient
+> = Parameters<TAuthClient["apiKey"]["create"]>[0]
 
-export type CreateApiKeyOptions<TAuthClient extends ApiKeyAuthClient> = Omit<
+export type CreateApiKeyOptions<
+  TAuthClient extends ApiKeyAuthClient = ApiKeyAuthClient
+> = Omit<
   ReturnType<typeof createApiKeyOptions<TAuthClient>>,
-  "mutationKey" | "mutationFn"
+  "mutationKey" | "mutationFn" | "meta"
 >
 
 /**
@@ -21,7 +31,7 @@ export type CreateApiKeyOptions<TAuthClient extends ApiKeyAuthClient> = Omit<
 export function createApiKeyOptions<TAuthClient extends ApiKeyAuthClient>(
   authClient: TAuthClient
 ) {
-  const mutationKey = apiKeyMutationKeys.createApiKey
+  const mutationKey = apiKeyMutationKeys.create
 
   const mutationFn = (params: CreateApiKeyParams<TAuthClient>) =>
     authClient.apiKey.create({
@@ -42,23 +52,28 @@ export function createApiKeyOptions<TAuthClient extends ApiKeyAuthClient>(
 /**
  * Create a mutation for creating an API key.
  *
- * Refetches the user's API key list on success unless disabled via options.
+ * On success, `MutationInvalidator` awaits invalidation of the user's API key
+ * list queries (see `meta.awaits`).
  *
  * @param authClient - The Better Auth client with the API key plugin.
  * @param options - React Query options forwarded to `useMutation`.
  */
 export function useCreateApiKey<TAuthClient extends ApiKeyAuthClient>(
   authClient: TAuthClient,
-  options?: CreateApiKeyOptions<TAuthClient>
+  options?: CreateApiKeyOptions<TAuthClient>,
+  queryClient?: QueryClient
 ) {
-  const { refetch } = useListApiKeys(authClient, { refetchOnMount: false })
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
 
-  return useMutation({
-    ...createApiKeyOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      await refetch()
-      await options?.onSuccess?.(...args)
-    }
-  })
+  return useMutation(
+    {
+      ...createApiKeyOptions(authClient),
+      ...options,
+      meta: {
+        awaits: [apiKeyQueryKeys.lists(userId)]
+      }
+    },
+    queryClient
+  )
 }

package/src/mutations/api-key/delete-api-key-mutation.ts

@@ -1,16 +1,26 @@
-import { apiKeyMutationKeys } from "@better-auth-ui/core/plugins"
-import { mutationOptions, useMutation } from "@tanstack/react-query"
+import {
+  apiKeyMutationKeys,
+  apiKeyQueryKeys
+} from "@better-auth-ui/core/plugins"
+import {
+  mutationOptions,
+  type QueryClient,
+  useMutation
+} from "@tanstack/react-query"
 import type { BetterFetchError } from "better-auth/react"
 
 import type { ApiKeyAuthClient } from "../../lib/auth-client"
-import { useListApiKeys } from "../../queries/api-key/list-api-keys-query"
+import { useSession } from "../../queries/auth/session-query"
 
-export type DeleteApiKeyParams<TAuthClient extends ApiKeyAuthClient> =
-  Parameters<TAuthClient["apiKey"]["delete"]>[0]
+export type DeleteApiKeyParams<
+  TAuthClient extends ApiKeyAuthClient = ApiKeyAuthClient
+> = Parameters<TAuthClient["apiKey"]["delete"]>[0]
 
-export type DeleteApiKeyOptions<TAuthClient extends ApiKeyAuthClient> = Omit<
+export type DeleteApiKeyOptions<
+  TAuthClient extends ApiKeyAuthClient = ApiKeyAuthClient
+> = Omit<
   ReturnType<typeof deleteApiKeyOptions<TAuthClient>>,
-  "mutationKey" | "mutationFn"
+  "mutationKey" | "mutationFn" | "meta"
 >
 
 /**
@@ -21,7 +31,7 @@ export type DeleteApiKeyOptions<TAuthClient extends ApiKeyAuthClient> = Omit<
 export function deleteApiKeyOptions<TAuthClient extends ApiKeyAuthClient>(
   authClient: TAuthClient
 ) {
-  const mutationKey = apiKeyMutationKeys.deleteApiKey
+  const mutationKey = apiKeyMutationKeys.delete
 
   const mutationFn = (params: DeleteApiKeyParams<TAuthClient>) =>
     authClient.apiKey.delete({
@@ -42,21 +52,28 @@ export function deleteApiKeyOptions<TAuthClient extends ApiKeyAuthClient>(
 /**
  * Create a mutation for deleting an API key.
  *
+ * On success, `MutationInvalidator` awaits invalidation of the user's API key
+ * list queries (see `meta.awaits`).
+ *
  * @param authClient - The Better Auth client with the API key plugin.
  * @param options - React Query options forwarded to `useMutation`.
  */
 export function useDeleteApiKey<TAuthClient extends ApiKeyAuthClient>(
   authClient: TAuthClient,
-  options?: DeleteApiKeyOptions<TAuthClient>
+  options?: DeleteApiKeyOptions<TAuthClient>,
+  queryClient?: QueryClient
 ) {
-  const { refetch } = useListApiKeys(authClient, { refetchOnMount: false })
-
-  return useMutation({
-    ...deleteApiKeyOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      await refetch()
-      await options?.onSuccess?.(...args)
-    }
-  })
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
+
+  return useMutation(
+    {
+      ...deleteApiKeyOptions(authClient),
+      ...options,
+      meta: {
+        awaits: [apiKeyQueryKeys.lists(userId)]
+      }
+    },
+    queryClient
+  )
 }

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

@@ -1,13 +1,12 @@
-import { authMutationKeys } from "@better-auth-ui/core"
+import { authMutationKeys, authQueryKeys } from "@better-auth-ui/core"
 import {
   mutationOptions,
-  useMutation,
-  useQueryClient
+  type QueryClient,
+  useMutation
 } 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"]
@@ -15,7 +14,7 @@ export type SignInEmailParams<TAuthClient extends AuthClient> = Parameters<
 
 export type SignInEmailOptions<TAuthClient extends AuthClient> = Omit<
   ReturnType<typeof signInEmailOptions<TAuthClient>>,
-  "mutationKey" | "mutationFn"
+  "mutationKey" | "mutationFn" | "meta"
 >
 
 /**
@@ -51,28 +50,25 @@ export function signInEmailOptions<TAuthClient extends AuthClient>(
 /**
  * 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`.
+ * On success, `MutationInvalidator` awaits invalidation of the session
+ * query so the new session is refetched (see `meta.awaits`).
  *
  * @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>
+  options?: SignInEmailOptions<TAuthClient>,
+  queryClient?: QueryClient
 ) {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    ...signInEmailOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      queryClient.resetQueries({
-        queryKey: sessionOptions(authClient).queryKey
-      })
-
-      await options?.onSuccess?.(...args)
-    }
-  })
+  return useMutation(
+    {
+      ...signInEmailOptions(authClient),
+      ...options,
+      meta: {
+        awaits: [authQueryKeys.session]
+      }
+    },
+    queryClient
+  )
 }

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

@@ -1,6 +1,7 @@
 import { authMutationKeys, authQueryKeys } from "@better-auth-ui/core"
 import {
   mutationOptions,
+  type QueryClient,
   useMutation,
   useQueryClient
 } from "@tanstack/react-query"
@@ -47,25 +48,30 @@ export function signOutOptions<TAuthClient extends AuthClient>(
 /**
  * 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`.
+ * On success, removes every cached auth query so no stale data leaks across
+ * accounts. Sign-out uses a direct `removeQueries` call (rather than the
+ * `meta.awaits` / `meta.invalidates` pattern) because the goal is to drop
+ * cache entries entirely, not to refetch them.
  *
  * @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>
+  options?: SignOutOptions<TAuthClient>,
+  queryClient?: QueryClient
 ) {
-  const queryClient = useQueryClient()
+  const defaultQueryClient = useQueryClient(queryClient)
 
-  return useMutation({
-    ...signOutOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      queryClient.removeQueries({ queryKey: authQueryKeys.all })
-      await options?.onSuccess?.(...args)
-    }
-  })
+  return useMutation(
+    {
+      ...signOutOptions(authClient),
+      ...options,
+      onSuccess: async (...args) => {
+        defaultQueryClient.removeQueries({ queryKey: authQueryKeys.all })
+        await options?.onSuccess?.(...args)
+      }
+    },
+    queryClient
+  )
 }

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

@@ -1,13 +1,12 @@
-import { authMutationKeys } from "@better-auth-ui/core"
+import { authMutationKeys, authQueryKeys } from "@better-auth-ui/core"
 import {
   mutationOptions,
-  useMutation,
-  useQueryClient
+  type QueryClient,
+  useMutation
 } 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"]
@@ -15,7 +14,7 @@ export type SignUpEmailParams<TAuthClient extends AuthClient> = Parameters<
 
 export type SignUpEmailOptions<TAuthClient extends AuthClient> = Omit<
   ReturnType<typeof signUpEmailOptions<TAuthClient>>,
-  "mutationKey" | "mutationFn"
+  "mutationKey" | "mutationFn" | "meta"
 >
 
 /**
@@ -47,28 +46,25 @@ export function signUpEmailOptions<TAuthClient extends AuthClient>(
 /**
  * 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`.
+ * On success, `MutationInvalidator` awaits invalidation of the session
+ * query so the new session is refetched (see `meta.awaits`).
  *
  * @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>
+  options?: SignUpEmailOptions<TAuthClient>,
+  queryClient?: QueryClient
 ) {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    ...signUpEmailOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      queryClient.resetQueries({
-        queryKey: sessionOptions(authClient).queryKey
-      })
-
-      await options?.onSuccess?.(...args)
-    }
-  })
+  return useMutation(
+    {
+      ...signUpEmailOptions(authClient),
+      ...options,
+      meta: {
+        awaits: [authQueryKeys.session]
+      }
+    },
+    queryClient
+  )
 }

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

@@ -1,9 +1,16 @@
-import { authMutationKeys } from "@better-auth-ui/core"
-import { mutationOptions, useMutation } from "@tanstack/react-query"
+import {
+  multiSessionMutationKeys,
+  multiSessionQueryKeys
+} from "@better-auth-ui/core/plugins"
+import {
+  mutationOptions,
+  type QueryClient,
+  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"
+import { useSession } from "../../queries/auth/session-query"
 
 export type RevokeMultiSessionParams<
   TAuthClient extends MultiSessionAuthClient
@@ -13,7 +20,7 @@ export type RevokeMultiSessionOptions<
   TAuthClient extends MultiSessionAuthClient
 > = Omit<
   ReturnType<typeof revokeMultiSessionOptions<TAuthClient>>,
-  "mutationKey" | "mutationFn"
+  "mutationKey" | "mutationFn" | "meta"
 >
 
 /**
@@ -24,7 +31,7 @@ export type RevokeMultiSessionOptions<
 export function revokeMultiSessionOptions<
   TAuthClient extends MultiSessionAuthClient
 >(authClient: TAuthClient) {
-  const mutationKey = authMutationKeys.multiSession.revoke
+  const mutationKey = multiSessionMutationKeys.revoke
 
   const mutationFn = (params: RevokeMultiSessionParams<TAuthClient>) =>
     authClient.multiSession.revoke({
@@ -45,26 +52,30 @@ export function revokeMultiSessionOptions<
 /**
  * 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`.
+ * On success, `MutationInvalidator` awaits invalidation of the device
+ * sessions list (see `meta.awaits`).
  *
  * @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
-  })
+>(
+  authClient: TAuthClient,
+  options?: RevokeMultiSessionOptions<TAuthClient>,
+  queryClient?: QueryClient
+) {
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
 
-  return useMutation({
-    ...revokeMultiSessionOptions(authClient),
-    ...options,
-    onSuccess: async (...args) => {
-      await refetch()
-      await options?.onSuccess?.(...args)
-    }
-  })
+  return useMutation(
+    {
+      ...revokeMultiSessionOptions(authClient),
+      ...options,
+      meta: {
+        awaits: [multiSessionQueryKeys.lists(userId)]
+      }
+    },
+    queryClient
+  )
 }