@delmaredigital/payload-better-auth 0.6.9 → 0.7.0

package/README.md

@@ -12,7 +12,13 @@ Better Auth adapter and plugins for Payload CMS. Enables seamless integration be
   <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32"></a>
 </p>
 
-> **Upgrading to 0.5?** This release requires Better Auth 1.5 and includes breaking changes to client plugins, API key imports, and auth instance types. See the [CHANGELOG](./CHANGELOG.md#054---2026-03-02) for migration instructions.
+> ⚠️ **Upgrading to 0.7?** This release requires **Better Auth 1.6** and includes several breaking changes:
+>
+> - **Schema migration required** for projects using the `twoFactor` plugin — Better Auth 1.6.2 added a `verified` column to the `twoFactor` table.
+> - **`oidcProvider` → `@better-auth/oauth-provider`** — generated OAuth types now reflect the `oauth-provider` schema. Consumers using `oidcProvider()` at runtime will keep working, but `OauthApplication` / `PluginId` / `ModelKey` type exports have changed shape. Migrating to `@better-auth/oauth-provider` is recommended.
+> - **Client helper type widening** — `createPayloadAuthClient()` and `payloadAuthPlugins` are typed more conservatively to keep `.d.ts` portable. For typed plugin methods (e.g. `client.twoFactor.verifyTotp`), list plugins explicitly in `createAuthClient({ plugins: [...] })` (see [Client-Side Auth](#4-client-side-auth) below).
+>
+> See the [CHANGELOG](./CHANGELOG.md#070---2026-04-21) for full migration instructions.
 
 ---
 
@@ -30,7 +36,7 @@ For AI-assisted exploration: [DeepWiki](https://deepwiki.com/delmaredigital/payl
 pnpm add @delmaredigital/payload-better-auth better-auth
 ```
 
-**Requirements:** `payload` >= 3.69.0 · `better-auth` >= 1.5.0 · `next` >= 15.4.8 · `react` >= 19.2.1
+**Requirements:** `payload` >= 3.69.0 · `better-auth` >= 1.6.0 · `next` >= 15.4.8 · `react` >= 19.2.1
 
 ## Quick Start
 
@@ -138,13 +144,18 @@ export default buildConfig({
 // src/lib/auth/client.ts
 'use client'
 
-import { createPayloadAuthClient } from '@delmaredigital/payload-better-auth/client'
+import { createAuthClient, twoFactorClient } from '@delmaredigital/payload-better-auth/client'
+import { passkeyClient } from '@better-auth/passkey/client'
 
-export const authClient = createPayloadAuthClient()
+export const authClient = createAuthClient({
+  plugins: [twoFactorClient(), passkeyClient()],
+})
 
 export const { useSession, signIn, signUp, signOut, twoFactor, passkey } = authClient
 ```
 
+> Listing plugins inline (rather than using `createPayloadAuthClient()` or spreading `payloadAuthPlugins`) ensures `twoFactor` and other plugin methods are typed on the returned client.
+
 ### 5. Server-Side Session
 
 ```ts

package/dist/components/BeforeLogin.d.ts

@@ -1,10 +1,10 @@
 export type BeforeLoginProps = {
-    /** URL to redirect to for login. Default: '/admin/login' */
+    /** URL to redirect to for login. Defaults to `${routes.admin}/login`. */
     loginUrl?: string;
 };
 /**
  * BeforeLogin component that redirects to the custom login page.
  * Injected into Payload's beforeLogin slot to intercept default login.
  */
-export declare function BeforeLogin({ loginUrl }: BeforeLoginProps): import("react").JSX.Element;
+export declare function BeforeLogin({ loginUrl }?: BeforeLoginProps): import("react").JSX.Element;
 export default BeforeLogin;

package/dist/components/BeforeLogin.js

@@ -2,16 +2,19 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from 'react';
 import { useRouter } from 'next/navigation.js';
+import { useConfig } from '@payloadcms/ui';
 /**
  * BeforeLogin component that redirects to the custom login page.
  * Injected into Payload's beforeLogin slot to intercept default login.
- */ export function BeforeLogin({ loginUrl = '/admin/login' }) {
+ */ export function BeforeLogin({ loginUrl } = {}) {
     const router = useRouter();
+    const { config: { routes: { admin: adminRoute } } } = useConfig();
+    const target = loginUrl ?? `${adminRoute}/login`;
     useEffect(()=>{
-        router.replace(loginUrl);
+        router.replace(target);
     }, [
         router,
-        loginUrl
+        target
     ]);
     // Show loading state while redirecting
     return /*#__PURE__*/ _jsx("div", {

package/dist/components/LoginView.js

@@ -5,6 +5,7 @@ import { useRouter } from 'next/navigation.js';
 import { createAuthClient } from 'better-auth/react';
 import { twoFactorClient } from 'better-auth/client/plugins';
 import { hasAnyRole, hasAllRoles } from '../utils/access.js';
+import { useConfig } from '@payloadcms/ui';
 /**
  * Check if user has the required role(s)
  */ function checkUserRoles(user, requiredRole, requireAllRoles) {
@@ -22,6 +23,8 @@ import { hasAnyRole, hasAllRoles } from '../utils/access.js';
 }
 export function LoginView({ authClient: providedClient, logo, title = 'Login', afterLoginPath = '/admin', requiredRole = 'admin', requireAllRoles = false, enablePasskey = 'auto', enableSignUp = 'auto', defaultSignUpRole = 'user', enableForgotPassword = 'auto', resetPasswordUrl }) {
     const router = useRouter();
+    // Payload Config
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
     // View state
     const [viewMode, setViewMode] = useState('login');
     // Form fields
@@ -91,7 +94,7 @@ export function LoginView({ authClient: providedClient, logo, title = 'Login', a
         if (enablePasskey === 'auto') {
             // Check if passkey endpoint exists (GET request)
             // Better Auth passkey routes are at /passkey/* (singular)
-            fetch('/api/auth/passkey/generate-authenticate-options', {
+            fetch(`${apiRoute}/auth/passkey/generate-authenticate-options`, {
                 method: 'GET',
                 credentials: 'include'
             }).then((res)=>{
@@ -111,7 +114,7 @@ export function LoginView({ authClient: providedClient, logo, title = 'Login', a
     useEffect(()=>{
         if (enableSignUp === 'auto') {
             // Check if sign-up endpoint exists
-            fetch('/api/auth/sign-up/email', {
+            fetch(`${apiRoute}/auth/sign-up/email`, {
                 method: 'OPTIONS',
                 credentials: 'include'
             }).then((res)=>{
@@ -131,7 +134,7 @@ export function LoginView({ authClient: providedClient, logo, title = 'Login', a
     useEffect(()=>{
         if (enableForgotPassword === 'auto') {
             // Check if request-password-reset endpoint exists
-            fetch('/api/auth/request-password-reset', {
+            fetch(`${apiRoute}/auth/request-password-reset`, {
                 method: 'OPTIONS',
                 credentials: 'include'
             }).then((res)=>{
@@ -254,7 +257,7 @@ export function LoginView({ authClient: providedClient, logo, title = 'Login', a
             const client = await getClient();
             const result = await client.requestPasswordReset({
                 email,
-                redirectTo: resetPasswordUrl ?? `${window.location.origin}/admin/reset-password`
+                redirectTo: resetPasswordUrl ?? `${window.location.origin}${adminRoute}/reset-password`
             });
             if (result.error) {
                 setError(result.error.message ?? 'Failed to send reset email');

package/dist/components/LogoutButton.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState } from 'react';
 import { useRouter } from 'next/navigation.js';
+import { useConfig } from '@payloadcms/ui';
 /**
  * Logout button component styled to match Payload's admin nav.
  * Uses Payload's CSS classes and variables for native theme integration.
@@ -10,6 +11,8 @@ import { useRouter } from 'next/navigation.js';
  * clean state when switching between users.
  */ export function LogoutButton() {
     const router = useRouter();
+    // Payload Config
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
     const [isLoading, setIsLoading] = useState(false);
     async function handleLogout() {
         if (isLoading) return;
@@ -19,7 +22,7 @@ import { useRouter } from 'next/navigation.js';
             // - Better Auth: clears BA session cookie
             // - Payload: clears JWT cookie (payload-token) so useAuth() resets
             await Promise.allSettled([
-                fetch('/api/auth/sign-out', {
+                fetch(`${apiRoute}/auth/sign-out`, {
                     method: 'POST',
                     credentials: 'include',
                     headers: {
@@ -27,12 +30,12 @@ import { useRouter } from 'next/navigation.js';
                     },
                     body: JSON.stringify({})
                 }),
-                fetch('/api/users/logout', {
+                fetch(`${apiRoute}/users/logout`, {
                     method: 'POST',
                     credentials: 'include'
                 })
             ]);
-            router.push('/admin/login');
+            router.push(`${adminRoute}/login`);
         } catch (error) {
             console.error('[better-auth] Logout error:', error);
             setIsLoading(false);

package/dist/components/auth/ForgotPasswordView.js

@@ -1,10 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useConfig } from '@payloadcms/ui';
 import { useState } from 'react';
 /**
  * Forgot password page component for requesting a password reset email.
  * Uses Better Auth's forgetPassword endpoint.
  */ export function ForgotPasswordView({ logo, title = 'Forgot Password', loginPath = '/admin/login', successMessage = 'If an account exists with this email, you will receive a password reset link.' }) {
+    // Payload Config
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
     const [email, setEmail] = useState('');
     const [error, setError] = useState(null);
     const [success, setSuccess] = useState(false);
@@ -14,7 +17,7 @@ import { useState } from 'react';
         setLoading(true);
         setError(null);
         try {
-            const response = await fetch('/api/auth/forget-password', {
+            const response = await fetch(`${apiRoute}/auth/forget-password`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json'
@@ -22,7 +25,7 @@ import { useState } from 'react';
                 credentials: 'include',
                 body: JSON.stringify({
                     email,
-                    redirectTo: `${window.location.origin}/admin/reset-password`
+                    redirectTo: `${window.location.origin}${adminRoute}/reset-password`
                 })
             });
             if (response.ok) {

package/dist/components/auth/ResetPasswordView.d.ts

@@ -3,7 +3,7 @@ export type ResetPasswordViewProps = {
     logo?: React.ReactNode;
     /** Page title. Default: 'Reset Password' */
     title?: string;
-    /** Path to redirect after successful reset. Default: '/admin/login' */
+    /** Path to redirect after successful reset. Defaults to `${routes.admin}/login`. */
     afterResetPath?: string;
     /** Minimum password length. Default: 8 */
     minPasswordLength?: number;

package/dist/components/auth/ResetPasswordView.js

@@ -2,13 +2,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useEffect } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation.js';
+import { useConfig } from '@payloadcms/ui';
 /**
  * Reset password page component for setting a new password.
  * Expects a token in the URL query parameter.
  * Uses Better Auth's resetPassword endpoint.
- */ export function ResetPasswordView({ logo, title = 'Reset Password', afterResetPath = '/admin/login', minPasswordLength = 8 }) {
+ */ export function ResetPasswordView({ logo, title = 'Reset Password', afterResetPath, minPasswordLength = 8 }) {
     const router = useRouter();
     const searchParams = useSearchParams();
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
+    const resolvedAfterResetPath = afterResetPath ?? `${adminRoute}/login`;
     const [password, setPassword] = useState('');
     const [confirmPassword, setConfirmPassword] = useState('');
     const [error, setError] = useState(null);
@@ -42,7 +45,7 @@ import { useRouter, useSearchParams } from 'next/navigation.js';
         }
         setLoading(true);
         try {
-            const response = await fetch('/api/auth/reset-password', {
+            const response = await fetch(`${apiRoute}/auth/reset-password`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json'
@@ -111,7 +114,7 @@ import { useRouter, useSearchParams } from 'next/navigation.js';
                         children: "Your password has been successfully reset. You can now log in with your new password."
                     }),
                     /*#__PURE__*/ _jsx("button", {
-                        onClick: ()=>router.push(afterResetPath),
+                        onClick: ()=>router.push(resolvedAfterResetPath),
                         style: {
                             padding: 'calc(var(--base) * 0.75) calc(var(--base) * 1.5)',
                             background: 'var(--theme-elevation-800)',

package/dist/components/management/SecurityNavLinks.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { NavGroup } from '@payloadcms/ui';
+import { NavGroup, useConfig } from '@payloadcms/ui';
 /**
  * Navigation links for security management features.
  * Rendered in admin sidebar via afterNavLinks injection.
@@ -8,14 +8,16 @@ import { NavGroup } from '@payloadcms/ui';
  *
  * Currently only renders API Keys link — 2FA and Passkeys
  * are now embedded as ui fields on the user document.
- */ export function SecurityNavLinks({ basePath = '/admin/security', showApiKeys = true } = {}) {
+ */ export function SecurityNavLinks({ basePath, showApiKeys = true } = {}) {
+    const { config: { routes: { admin: adminRoute } } } = useConfig();
     if (!showApiKeys) {
         return null;
     }
+    const resolvedBasePath = basePath ?? `${adminRoute}/security`;
     return /*#__PURE__*/ _jsx(NavGroup, {
         label: "Security",
         children: /*#__PURE__*/ _jsx("a", {
-            href: `${basePath}/api-keys`,
+            href: `${resolvedBasePath}/api-keys`,
             className: "nav__link",
             children: /*#__PURE__*/ _jsx("span", {
                 className: "nav__link-label",

package/dist/components/twoFactor/TwoFactorSetupView.d.ts

@@ -3,7 +3,7 @@ export type TwoFactorSetupViewProps = {
     logo?: React.ReactNode;
     /** Page title. Default: 'Set Up Two-Factor Authentication' */
     title?: string;
-    /** Path to redirect after successful setup. Default: '/admin' */
+    /** Path to redirect after successful setup. Defaults to `routes.admin`. */
     afterSetupPath?: string;
     /** Callback after successful setup */
     onSetupComplete?: () => void;

package/dist/components/twoFactor/TwoFactorSetupView.js

@@ -1,11 +1,14 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useEffect } from 'react';
+import { useConfig } from '@payloadcms/ui';
 /**
  * Two-factor authentication setup component.
  * Displays QR code for TOTP apps and allows verification.
  * Uses Better Auth's twoFactor plugin endpoints.
- */ export function TwoFactorSetupView({ logo, title = 'Set Up Two-Factor Authentication', afterSetupPath = '/admin', onSetupComplete }) {
+ */ export function TwoFactorSetupView({ logo, title = 'Set Up Two-Factor Authentication', afterSetupPath, onSetupComplete }) {
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
+    const resolvedAfterSetupPath = afterSetupPath ?? adminRoute;
     const [step, setStep] = useState('loading');
     const [totpUri, setTotpUri] = useState(null);
     const [secret, setSecret] = useState(null);
@@ -16,7 +19,7 @@ import { useState, useEffect } from 'react';
     useEffect(()=>{
         async function enableTwoFactor() {
             try {
-                const response = await fetch('/api/auth/two-factor/enable', {
+                const response = await fetch(`${apiRoute}/auth/two-factor/enable`, {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json'
@@ -41,13 +44,15 @@ import { useState, useEffect } from 'react';
             }
         }
         enableTwoFactor();
-    }, []);
+    }, [
+        apiRoute
+    ]);
     async function handleVerify(e) {
         e.preventDefault();
         setLoading(true);
         setError(null);
         try {
-            const response = await fetch('/api/auth/two-factor/verify-totp', {
+            const response = await fetch(`${apiRoute}/auth/two-factor/verify-totp`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json'
@@ -144,7 +149,7 @@ import { useState, useEffect } from 'react';
                         children: "Your account is now protected with two-factor authentication."
                     }),
                     /*#__PURE__*/ _jsx("a", {
-                        href: afterSetupPath,
+                        href: resolvedAfterSetupPath,
                         style: {
                             display: 'inline-block',
                             padding: 'calc(var(--base) * 0.75) calc(var(--base) * 1.5)',

package/dist/components/twoFactor/TwoFactorVerifyView.d.ts

@@ -3,7 +3,7 @@ export type TwoFactorVerifyViewProps = {
     logo?: React.ReactNode;
     /** Page title. Default: 'Two-Factor Authentication' */
     title?: string;
-    /** Path to redirect after successful verification. Default: '/admin' */
+    /** Path to redirect after successful verification. Defaults to `routes.admin`. */
     afterVerifyPath?: string;
     /** Callback after successful verification */
     onVerifyComplete?: () => void;

package/dist/components/twoFactor/TwoFactorVerifyView.js

@@ -2,12 +2,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { useRouter } from 'next/navigation.js';
+import { useConfig } from '@payloadcms/ui';
 /**
  * Two-factor authentication verification component.
  * Used during login flow when 2FA is enabled on the account.
  * Uses Better Auth's twoFactor plugin endpoints.
- */ export function TwoFactorVerifyView({ logo, title = 'Two-Factor Authentication', afterVerifyPath = '/admin', onVerifyComplete }) {
+ */ export function TwoFactorVerifyView({ logo, title = 'Two-Factor Authentication', afterVerifyPath, onVerifyComplete }) {
     const router = useRouter();
+    const { config: { routes: { admin: adminRoute, api: apiRoute } } } = useConfig();
+    const resolvedAfterVerifyPath = afterVerifyPath ?? adminRoute;
     const [code, setCode] = useState('');
     const [error, setError] = useState(null);
     const [loading, setLoading] = useState(false);
@@ -17,7 +20,7 @@ import { useRouter } from 'next/navigation.js';
         setLoading(true);
         setError(null);
         try {
-            const endpoint = useBackupCode ? '/api/auth/two-factor/verify-backup-code' : '/api/auth/two-factor/verify-totp';
+            const endpoint = useBackupCode ? `${apiRoute}/auth/two-factor/verify-backup-code` : `${apiRoute}/auth/two-factor/verify-totp`;
             const response = await fetch(endpoint, {
                 method: 'POST',
                 headers: {
@@ -30,7 +33,7 @@ import { useRouter } from 'next/navigation.js';
             });
             if (response.ok) {
                 onVerifyComplete?.();
-                router.push(afterVerifyPath);
+                router.push(resolvedAfterVerifyPath);
                 router.refresh();
             } else {
                 const data = await response.json().catch(()=>({}));