@better-auth-ui/core 1.6.3 → 1.6.4

package/src/lib/auth-plugin.ts

@@ -0,0 +1,79 @@
+import type { AdditionalFields } from "../config/additional-fields-config"
+
+/**
+ * View-path contributions kept on the plugin object.
+ *
+ * Plugins that add routable sub-pages (e.g. `magicLinkPlugin` adds
+ * `/auth/magic-link`) declare the URL segment under the matching section.
+ * Read at runtime via `useAuthPlugin(plugin).viewPaths.*`.
+ */
+export type AuthPluginViewPaths = {
+  auth?: Record<string, string>
+  settings?: Record<string, string>
+}
+
+/**
+ * Core authentication plugin interface.
+ *
+ * Defines the identity, localization, and routing contributions every plugin
+ * may ship. UI packages extend this with framework-specific slot components
+ * (see `AuthPlugin` in `@better-auth-ui/react`).
+ */
+export interface AuthPluginBase {
+  /** Unique identifier. Used as a React key and localization namespace. */
+  id: string
+  /** Localization defaults contributed by the plugin. */
+  localization?: Record<string, unknown>
+  /**
+   * View-path segments the plugin contributes. Read by host components
+   * (e.g. `<Auth>`, `MagicLinkButton`) via `useAuthPlugin(plugin).viewPaths`.
+   */
+  viewPaths?: AuthPluginViewPaths
+  /**
+   * Additional user fields contributed by the plugin. These are merged with
+   * user-defined additionalFields in the auth config.
+   */
+  additionalFields?: AdditionalFields
+  /**
+   * Additional properties contributed by the plugin.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Composable module-augmentation slot for narrowing the plugin type returned
+ * by `useAuth()`. Each augmentation registers under its own key so multiple
+ * augmentations (e.g. a UI package and a user-land template) can coexist
+ * without colliding on a single shared property.
+ *
+ * The resolved {@link AuthPlugin} type is the union of every registered
+ * value, so `useAuth().plugins` is typed as the broadest plugin shape
+ * across all augmentations a consumer has imported.
+ *
+ * Pick any unique string as the key — the key is only used to keep slots
+ * disjoint during declaration merging and is never read at runtime.
+ *
+ * @example
+ * declare module "@better-auth-ui/core" {
+ *   interface AuthPluginRegister {
+ *     // Use a key unique to your package or app, e.g. the package name.
+ *     myUiPackage: MyAuthPlugin
+ *   }
+ * }
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging slot
+export interface AuthPluginRegister {}
+
+/**
+ * Resolved auth plugin type. Consumers widen this via keyed augmentations on
+ * {@link AuthPluginRegister}; the resolved type is the union of every
+ * registered value. With no augmentations it falls back to the
+ * framework-agnostic {@link AuthPluginBase}.
+ */
+export type AuthPlugin = [keyof AuthPluginRegister] extends [never]
+  ? AuthPluginBase
+  : AuthPluginRegister[keyof AuthPluginRegister] extends infer P
+    ? P extends AuthPluginBase
+      ? P
+      : AuthPluginBase
+    : AuthPluginBase

package/src/lib/auth-query-keys.ts

@@ -0,0 +1,68 @@
+/**
+ * Hierarchical query key factory for every Better Auth query managed by
+ * this library.
+ *
+ * Keys are nested — higher-level keys are valid prefixes of their
+ * descendants — so a single call can invalidate a whole subtree:
+ *
+ * ```ts
+ * queryClient.invalidateQueries({ queryKey: authQueryKeys.all })
+ * queryClient.invalidateQueries({ queryKey: authQueryKeys.user(userId) })
+ * queryClient.invalidateQueries({ queryKey: authQueryKeys.session })
+ * ```
+ *
+ * This factory lives in `@better-auth-ui/core` so it can be shared across
+ * framework packages (`@better-auth-ui/react`, a future `/solid` package,
+ * etc.) and across client- and server-side query variants — the cache
+ * entries line up regardless of which query options factory produced them.
+ *
+ * For mutation keys, see `authMutationKeys` in `./auth-mutation-keys`.
+ */
+export const authQueryKeys = {
+  /** Root key for every Better Auth query. */
+  all: ["auth"] as const,
+
+  /** Key for the current `getSession` query. */
+  session: ["auth", "getSession"] as const,
+
+  /** Prefix for every per-user query. */
+  users: () => [...authQueryKeys.all, "user"] as const,
+  /** Prefix for every query scoped to a specific user. */
+  user: (userId: string | undefined) =>
+    [...authQueryKeys.users(), userId] as const,
+
+  /** Key for `multiSession.listDeviceSessions` for the given user. */
+  listDeviceSessions: <TQuery = undefined>(
+    userId: string | undefined,
+    query?: TQuery
+  ) =>
+    [
+      ...authQueryKeys.user(userId),
+      "listDeviceSessions",
+      query ?? null
+    ] as const,
+
+  /** Key for the user's passkey list. */
+  listPasskeys: <TQuery = undefined>(
+    userId: string | undefined,
+    query?: TQuery
+  ) => [...authQueryKeys.user(userId), "listPasskeys", query ?? null] as const,
+
+  /** Key for `accountInfo` for the given user. */
+  accountInfo: <TQuery = undefined>(
+    userId: string | undefined,
+    query?: TQuery
+  ) => [...authQueryKeys.user(userId), "accountInfo", query ?? null] as const,
+
+  /** Key for `listAccounts` for the given user. */
+  listAccounts: <TQuery = undefined>(
+    userId: string | undefined,
+    query?: TQuery
+  ) => [...authQueryKeys.user(userId), "listAccounts", query ?? null] as const,
+
+  /** Key for `listSessions` for the given user. */
+  listSessions: <TQuery = undefined>(
+    userId: string | undefined,
+    query?: TQuery
+  ) => [...authQueryKeys.user(userId), "listSessions", query ?? null] as const
+} as const

package/src/lib/create-auth-plugin.ts

@@ -0,0 +1,47 @@
+/**
+ * Creates a plugin factory and attaches its `id` as a static property.
+ *
+ * Lifts the plugin's `id` out of the factory's runtime output so consumers
+ * (e.g. `useAuthPlugin`) can read it without invoking the factory. This lets
+ * plugins keep required options (like `themePlugin`'s `setTheme`) without
+ * forcing every factory to be callable with zero arguments.
+ *
+ * The returned factory:
+ * - is callable with the original arguments and returns the factory's result
+ *   merged with `{ id }`
+ * - exposes `id` as a static property so it can be read at registration or
+ *   lookup time without allocating a plugin instance
+ *
+ * Type safety for the plugin's shape is enforced at the registration site
+ * (`<AuthProvider plugins={[…]} />`) where `plugins` is typed as `AuthPlugin[]`.
+ *
+ * @example
+ * ```ts
+ * export const themePlugin = createAuthPlugin(
+ *   "theme",
+ *   (options: ThemePluginOptions) => ({
+ *     localization: { ...themeLocalization, ...options.localization },
+ *     theme: options.theme ?? "system",
+ *     setTheme: options.setTheme,
+ *     themes: options.themes ?? ["system", "light", "dark"]
+ *   })
+ * )
+ *
+ * themePlugin.id // "theme"
+ * themePlugin({ setTheme }) // { id: "theme", localization, theme, setTheme, themes }
+ * ```
+ */
+export function createAuthPlugin<
+  const TId extends string,
+  TArgs extends unknown[],
+  TResult extends object
+>(
+  id: TId,
+  factory: (...args: TArgs) => TResult
+): ((...args: TArgs) => Omit<TResult, "id"> & { id: TId }) & { id: TId } {
+  const wrapped = (...args: TArgs): Omit<TResult, "id"> & { id: TId } => ({
+    ...factory(...args),
+    id
+  })
+  return Object.assign(wrapped, { id })
+}

package/src/lib/deep-partial.ts

@@ -0,0 +1,12 @@
+/**
+ * Recursive partial. Leaves functions and arrays intact so callable props
+ * stay callable and array element types are preserved.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: canonical "any function" top type
+export type DeepPartial<T> = T extends (...args: any[]) => any
+  ? T
+  : T extends readonly unknown[]
+    ? T
+    : T extends object
+      ? { [P in keyof T]?: DeepPartial<T[P]> }
+      : T

package/src/lib/localization.ts

@@ -3,9 +3,6 @@ export const localization = {
     /** @remarks `"Account"` */
     account: "Account",
 
-    /** @remarks `"Add Account"` */
-    addAccount: "Add Account",
-
     /** @remarks `"Already have an account?"` */
     alreadyHaveAnAccount: "Already have an account?",
 
@@ -36,12 +33,6 @@ export const localization = {
     /** @remarks `"Invalid reset password token"` */
     invalidResetPasswordToken: "Invalid reset password token",
 
-    /** @remarks `"Magic Link"` */
-    magicLink: "Magic Link",
-
-    /** @remarks `"Magic link sent to your email"` */
-    magicLinkSent: "Magic link sent to your email",
-
     /** @remarks `"Name"` */
     name: "Name",
 
@@ -60,9 +51,6 @@ export const localization = {
     /** @remarks `"OR"` */
     or: "OR",
 
-    /** @remarks `"Passkey"` */
-    passkey: "Passkey",
-
     /** @remarks `"Password"` */
     password: "Password",
 
@@ -90,9 +78,6 @@ export const localization = {
     /** @remarks `"Reset Password"` */
     resetPassword: "Reset Password",
 
-    /** @remarks `"Send Magic Link"` */
-    sendMagicLink: "Send Magic Link",
-
     /** @remarks `"Send reset link"` */
     sendResetLink: "Send reset link",
 
@@ -108,24 +93,6 @@ export const localization = {
     /** @remarks `"Sign Up"` */
     signUp: "Sign Up",
 
-    /** @remarks `"Switch Account"` */
-    switchAccount: "Switch Account",
-
-    /** @remarks `"Username"` */
-    username: "Username",
-
-    /** @remarks `"Username is available"` */
-    usernameAvailable: "Username is available",
-
-    /** @remarks `"Enter your username or email"` */
-    usernameOrEmailPlaceholder: "Enter your username or email",
-
-    /** @remarks `"Enter your username"` */
-    usernamePlaceholder: "Enter your username",
-
-    /** @remarks `"Username is already taken. Please try another."` */
-    usernameTaken: "Username is already taken. Please try another.",
-
     /** @remarks `"Verification email sent!"` */
     verificationEmailSent: "Verification email sent!",
 
@@ -172,12 +139,12 @@ export const localization = {
     /** @remarks `"Link your {{provider}} account"` */
     linkProvider: "Link your {{provider}} account",
 
-    /** @remarks `"Appearance"` */
-    appearance: "Appearance",
-
     /** @remarks `"Cancel"` */
     cancel: "Cancel",
 
+    /** @remarks `"Copy to clipboard"` */
+    copyToClipboard: "Copy to clipboard",
+
     /** @remarks `"Change email"` */
     changeEmail: "Change email",
 
@@ -196,45 +163,14 @@ export const localization = {
     /** @remarks `"Enter your current password"` */
     currentPasswordPlaceholder: "Enter your current password",
 
-    /** @remarks `"Dark"` */
-    dark: "Dark",
-
     /** @remarks `"Danger zone"` */
     dangerZone: "Danger zone",
 
-    /** @remarks `"Delete user"` */
-    deleteUser: "Delete user",
-
-    /** @remarks `"Permanently remove your account and all associated data. This cannot be undone."` */
-    deleteUserDescription:
-      "Permanently remove your account and all associated data. This cannot be undone.",
-
-    /** @remarks `"Check your email to confirm account deletion."` */
-    deleteUserVerificationSent: "Check your email to confirm account deletion.",
-
-    /** @remarks `"Your account has been deleted."` */
-    deleteUserSuccess: "Your account has been deleted.",
-
-    /** @remarks `"Light"` */
-    light: "Light",
-
-    /** @remarks `"Manage accounts"` */
-    manageAccounts: "Manage accounts",
-
-    /** @remarks `"Add passkey"` */
-    addPasskey: "Add passkey",
-
     /** @remarks `"Delete"` */
     delete: "Delete",
 
-    /** @remarks `"Passkeys"` */
-    passkeys: "Passkeys",
-
-    /** @remarks `"Manage your passkeys for secure access."` */
-    passkeysDescription: "Manage your passkeys for secure access.",
-
-    /** @remarks `"Securely access your account without a password."` */
-    passkeysInstructions: "Securely access your account without a password.",
+    /** @remarks `"Optional"` */
+    optional: "Optional",
 
     /** @remarks `"Profile"` */
     profile: "Profile",
@@ -267,11 +203,8 @@ export const localization = {
     /** @remarks `"Settings"` */
     settings: "Settings",
 
-    /** @remarks `"System"` */
-    system: "System",
-
-    /** @remarks `"Theme"` */
-    theme: "Theme",
+    /** @remarks `"Time"` */
+    time: "Time",
 
     /** @remarks `"Unlink {{provider}}"` */
     unlinkProvider: "Unlink {{provider}}",

package/src/lib/utils.ts

@@ -1,3 +1,5 @@
+import type { DeepPartial } from "./deep-partial"
+
 /**
  * Type guard that checks whether a value is a non-null, non-array object.
  */
@@ -127,7 +129,7 @@ export function fileToBase64(file: File): Promise<string> {
  * @param source - Partial overrides to apply on top of `target`.
  * @returns A new merged object of type `T`.
  */
-export function deepmerge<T>(target: T, source: Partial<T>): T {
+export function deepmerge<T>(target: T, source: DeepPartial<T>): T {
   if (isPlainObject(target) && isPlainObject(source)) {
     const result: Record<string, unknown> = { ...target }
 
@@ -137,7 +139,7 @@ export function deepmerge<T>(target: T, source: Partial<T>): T {
       if (key in target) {
         result[key] = deepmerge(
           (target as Record<string, unknown>)[key],
-          value as unknown as Partial<T>
+          value as never
         )
       } else {
         result[key] = value

package/src/lib/view-paths.ts

@@ -1,7 +1,11 @@
 /**
  * View path segments for authentication routes.
+ *
+ * Contains the fixed built-ins every install ships with. Plugin-contributed
+ * paths (e.g. `magicLinkPlugin`'s `magicLink`) live on the plugin object and
+ * are read via `useAuthPlugin(plugin).viewPaths.auth.*`.
  */
-export type AuthViewPaths = {
+export interface AuthViewPaths {
   /**
    * Path segment for the sign-in view
    * @default "sign-in"
@@ -12,11 +16,6 @@ export type AuthViewPaths = {
    * @default "sign-up"
    */
   signUp: string
-  /**
-   * Path segment for the magic link authentication view
-   * @default "magic-link"
-   */
-  magicLink: string
   /**
    * Path segment for the forgot password view
    * @default "forgot-password"
@@ -37,7 +36,7 @@ export type AuthViewPaths = {
 /**
  * View path segments for settings routes.
  */
-export type SettingsViewPaths = {
+export interface SettingsViewPaths {
   /**
    * Path segment for the account settings view
    * @default "account"
@@ -64,7 +63,6 @@ export const viewPaths: ViewPaths = {
   auth: {
     signIn: "sign-in",
     signUp: "sign-up",
-    magicLink: "magic-link",
     forgotPassword: "forgot-password",
     resetPassword: "reset-password",
     signOut: "sign-out"

package/src/plugins/delete-user/delete-user-localization.ts

@@ -0,0 +1,16 @@
+export const deleteUserLocalization = {
+  /** @remarks `"Delete user"` */
+  deleteUser: "Delete user",
+
+  /** @remarks `"Permanently remove your account and all associated data. This cannot be undone."` */
+  deleteUserDescription:
+    "Permanently remove your account and all associated data. This cannot be undone.",
+
+  /** @remarks `"Check your email to confirm account deletion."` */
+  deleteUserVerificationSent: "Check your email to confirm account deletion.",
+
+  /** @remarks `"Your account has been deleted."` */
+  deleteUserSuccess: "Your account has been deleted."
+}
+
+export type DeleteUserLocalization = typeof deleteUserLocalization

package/src/plugins/delete-user/delete-user-plugin.ts

@@ -0,0 +1,27 @@
+import { createAuthPlugin } from "../../lib/create-auth-plugin"
+import {
+  type DeleteUserLocalization,
+  deleteUserLocalization
+} from "./delete-user-localization"
+
+export type DeleteUserPluginOptions = {
+  /**
+   * When `true`, matches server `sendDeleteAccountVerification`: deletion starts by sending a
+   * verification email instead of deleting immediately in this request.
+   */
+  sendDeleteAccountVerification?: boolean
+  /**
+   * Override the plugin's default localization strings.
+   * @remarks `DeleteUserLocalization`
+   */
+  localization?: Partial<DeleteUserLocalization>
+}
+
+export const deleteUserPlugin = createAuthPlugin(
+  "deleteUser",
+  (options: DeleteUserPluginOptions = {}) => ({
+    localization: { ...deleteUserLocalization, ...options.localization },
+    sendDeleteAccountVerification:
+      options.sendDeleteAccountVerification ?? false
+  })
+)

package/src/plugins/index.ts

@@ -0,0 +1,14 @@
+export * from "./delete-user/delete-user-localization"
+export * from "./delete-user/delete-user-plugin"
+export * from "./magic-link/magic-link-localization"
+export * from "./magic-link/magic-link-mutation-keys"
+export * from "./magic-link/magic-link-plugin"
+export * from "./multi-session/multi-session-localization"
+export * from "./multi-session/multi-session-plugin"
+export * from "./passkey/passkey-localization"
+export * from "./passkey/passkey-mutation-keys"
+export * from "./passkey/passkey-plugin"
+export * from "./theme/theme-localization"
+export * from "./theme/theme-plugin"
+export * from "./username/username-localization"
+export * from "./username/username-plugin"

package/src/plugins/magic-link/magic-link-localization.ts

@@ -0,0 +1,10 @@
+export const magicLinkLocalization = {
+  /** @remarks `"Magic Link"` */
+  magicLink: "Magic Link",
+  /** @remarks `"Send Magic Link"` */
+  sendMagicLink: "Send Magic Link",
+  /** @remarks `"Check your email for the magic link"` */
+  magicLinkSent: "Check your email for the magic link"
+}
+
+export type MagicLinkLocalization = typeof magicLinkLocalization

package/src/plugins/magic-link/magic-link-mutation-keys.ts

@@ -0,0 +1,17 @@
+/**
+ * Mutation keys contributed by the magic-link plugin.
+ *
+ * Kept under the shared `["auth", "signIn", ...]` namespace as the built-in
+ * sign-in mutation keys so consumers can match the whole sign-in surface
+ * with `useIsMutating({ mutationKey: ["auth", "signIn"] })` regardless of
+ * which strategy is in flight.
+ *
+ * @example
+ * ```ts
+ * useIsMutating({ mutationKey: magicLinkMutationKeys.signIn })
+ * ```
+ */
+export const magicLinkMutationKeys = {
+  /** Key for `signIn.magicLink`. */
+  signIn: ["auth", "signIn", "magicLink"] as const
+} as const

package/src/plugins/magic-link/magic-link-plugin.ts

@@ -0,0 +1,40 @@
+import { createAuthPlugin } from "../../lib/create-auth-plugin"
+// Side-effect import so this file participates in declaration merging on the
+// same module instance that external consumers reach via `@better-auth-ui/core`.
+import type {} from "../../lib/view-paths"
+import {
+  type MagicLinkLocalization,
+  magicLinkLocalization
+} from "./magic-link-localization"
+
+declare module "../../lib/view-paths" {
+  /** Widens `AuthViewPaths` by adding the `"magicLink"` path when this plugin is imported. */
+  interface AuthViewPaths {
+    /** @default "magic-link" */
+    magicLink?: string
+  }
+}
+
+export type MagicLinkPluginOptions = {
+  /**
+   * Override the plugin's default localization strings.
+   * @remarks `MagicLinkLocalization`
+   */
+  localization?: Partial<MagicLinkLocalization>
+  /**
+   * URL segment for the magic-link view.
+   * @remarks `string`
+   * @default "magic-link"
+   */
+  path?: string
+}
+
+export const magicLinkPlugin = createAuthPlugin(
+  "magicLink",
+  (options: MagicLinkPluginOptions = {}) => ({
+    localization: { ...magicLinkLocalization, ...options.localization },
+    viewPaths: {
+      auth: { magicLink: options.path ?? "magic-link" }
+    }
+  })
+)

package/src/plugins/multi-session/multi-session-localization.ts

@@ -0,0 +1,12 @@
+export const multiSessionLocalization = {
+  /** @remarks `"Switch Account"` */
+  switchAccount: "Switch Account",
+  /** @remarks `"Add Account"` */
+  addAccount: "Add Account",
+  /** @remarks `"Manage accounts"` */
+  manageAccounts: "Manage accounts",
+  /** @remarks `"Manage your accounts for secure access."` */
+  manageAccountsDescription: "Manage your accounts for secure access."
+}
+
+export type MultiSessionLocalization = typeof multiSessionLocalization

package/src/plugins/multi-session/multi-session-plugin.ts

@@ -0,0 +1,20 @@
+import { createAuthPlugin } from "../../lib/create-auth-plugin"
+import {
+  type MultiSessionLocalization,
+  multiSessionLocalization
+} from "./multi-session-localization"
+
+export type MultiSessionPluginOptions = {
+  /**
+   * Override the plugin's default localization strings.
+   * @remarks `MultiSessionLocalization`
+   */
+  localization?: Partial<MultiSessionLocalization>
+}
+
+export const multiSessionPlugin = createAuthPlugin(
+  "multiSession",
+  (options: MultiSessionPluginOptions = {}) => ({
+    localization: { ...multiSessionLocalization, ...options.localization }
+  })
+)

package/src/plugins/passkey/passkey-localization.ts

@@ -0,0 +1,16 @@
+export const passkeyLocalization = {
+  /** @remarks `"Passkey"` */
+  passkey: "Passkey",
+  /** @remarks `"Add passkey"` */
+  addPasskey: "Add passkey",
+  /** @remarks `"Delete passkey {{name}}"` */
+  deletePasskey: "Delete passkey {{name}}",
+  /** @remarks `"Passkeys"` */
+  passkeys: "Passkeys",
+  /** @remarks `"Manage your passkeys for secure access."` */
+  passkeysDescription: "Manage your passkeys for secure access.",
+  /** @remarks `"Securely access your account without a password."` */
+  passkeysInstructions: "Securely access your account without a password."
+}
+
+export type PasskeyLocalization = typeof passkeyLocalization

package/src/plugins/passkey/passkey-mutation-keys.ts

@@ -0,0 +1,15 @@
+/**
+ * Mutation keys contributed by the passkey plugin.
+ *
+ * `signIn` is kept under the shared `["auth", "signIn", ...]` namespace so
+ * consumers can match the whole sign-in surface with
+ * `useIsMutating({ mutationKey: ["auth", "signIn"] })`.
+ */
+export const passkeyMutationKeys = {
+  /** Key for `signIn.passkey`. */
+  signIn: ["auth", "signIn", "passkey"] as const,
+  /** Key for `passkey.addPasskey`. */
+  addPasskey: ["auth", "passkey", "addPasskey"] as const,
+  /** Key for `passkey.deletePasskey`. */
+  deletePasskey: ["auth", "passkey", "deletePasskey"] as const
+} as const

package/src/plugins/passkey/passkey-plugin.ts

@@ -0,0 +1,20 @@
+import { createAuthPlugin } from "../../lib/create-auth-plugin"
+import {
+  type PasskeyLocalization,
+  passkeyLocalization
+} from "./passkey-localization"
+
+export type PasskeyPluginOptions = {
+  /**
+   * Override the plugin's default localization strings.
+   * @remarks `PasskeyLocalization`
+   */
+  localization?: Partial<PasskeyLocalization>
+}
+
+export const passkeyPlugin = createAuthPlugin(
+  "passkey",
+  (options: PasskeyPluginOptions = {}) => ({
+    localization: { ...passkeyLocalization, ...options.localization }
+  })
+)

package/src/plugins/theme/theme-localization.ts

@@ -0,0 +1,14 @@
+export const themeLocalization = {
+  /** @remarks `"Appearance"` */
+  appearance: "Appearance",
+  /** @remarks `"Theme"` */
+  theme: "Theme",
+  /** @remarks `"System"` */
+  system: "System",
+  /** @remarks `"Light"` */
+  light: "Light",
+  /** @remarks `"Dark"` */
+  dark: "Dark"
+}
+
+export type ThemeLocalization = typeof themeLocalization