@delmaredigital/payload-better-auth 0.4.1 → 0.4.3

package/README.md

@@ -20,6 +20,7 @@ For additional documentation and references, visit: [https://deepwiki.com/delmar
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [MongoDB Setup](#mongodb-setup)
 - [API Reference](#api-reference)
 - [Customization](#customization)
 - [Access Control Helpers](#access-control-helpers)
@@ -166,7 +167,9 @@ export const Users: CollectionConfig = {
 > [better-auth] Auto-adding fields to 'users': ['twoFactorEnabled']
 > ```
 
-### Step 3: Configure Payload
+### Step 3: Configure Payload (Postgres)
+
+> For MongoDB, see [MongoDB Setup](#mongodb-setup).
 
 ```ts
 // src/payload.config.ts
@@ -292,6 +295,111 @@ export default async function Dashboard() {
 
 ---
 
+## MongoDB Setup
+
+The adapter auto-detects MongoDB and configures itself accordingly. No special adapter configuration is needed.
+
+### Key Differences from Postgres
+
+| | Postgres (default) | MongoDB |
+|---|---|---|
+| **ID type** | `'number'` (SERIAL) | `'text'` (ObjectId strings) |
+| **`generateId`** | Set to `'serial'` | Do not set (MongoDB generates ObjectIds) |
+| **`idType`** | `'number'` (default) | Auto-detected as `'text'` |
+| **`betterAuthStrategy`** | `idType: 'number'` (default) | `idType: 'text'` |
+| **`createSessionHelpers`** | `idType: 'number'` | `idType: 'text'` (or omit) |
+
+### Quick Start (MongoDB)
+
+```ts
+// src/payload.config.ts
+import { buildConfig } from 'payload'
+import { mongooseAdapter } from '@payloadcms/db-mongodb'
+import { betterAuth } from 'better-auth'
+import {
+  betterAuthCollections,
+  createBetterAuthPlugin,
+  payloadAdapter,
+} from '@delmaredigital/payload-better-auth'
+import { betterAuthOptions } from './lib/auth/config'
+import { Users } from './collections/Users'
+
+export default buildConfig({
+  collections: [Users],
+  plugins: [
+    betterAuthCollections({
+      betterAuthOptions,
+      skipCollections: ['user'],
+    }),
+    createBetterAuthPlugin({
+      createAuth: (payload) =>
+        betterAuth({
+          ...betterAuthOptions,
+          database: payloadAdapter({ payloadClient: payload }),
+          // Do NOT set advanced.database.generateId — MongoDB generates ObjectIds
+          secret: process.env.BETTER_AUTH_SECRET,
+          trustedOrigins: ['http://localhost:3000'],
+        }),
+    }),
+  ],
+  db: mongooseAdapter({
+    url: process.env.DATABASE_URI!,
+  }),
+})
+```
+
+**Users collection:**
+
+```ts
+import { betterAuthStrategy } from '@delmaredigital/payload-better-auth'
+
+export const Users: CollectionConfig = {
+  slug: 'users',
+  auth: {
+    disableLocalStrategy: true,
+    strategies: [betterAuthStrategy({ idType: 'text' })],
+  },
+  // ... fields and access control same as Postgres setup
+}
+```
+
+**Session helpers:**
+
+```ts
+import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+export const { getServerSession, getServerUser } = createSessionHelpers<User>({
+  idType: 'text',
+})
+```
+
+### Migrating from Postgres to MongoDB
+
+1. **Remove `generateId: 'serial'`** from your Better Auth config (the `advanced.database` block)
+2. **Change `betterAuthStrategy()`** to use `idType: 'text'`:
+   ```ts
+   strategies: [betterAuthStrategy({ idType: 'text' })]
+   ```
+3. **Update `createSessionHelpers`** (if using) to `idType: 'text'`:
+   ```ts
+   createSessionHelpers<User>({ idType: 'text' })
+   ```
+4. **Remove `idType: 'number'`** from `adapterConfig` if you had it set explicitly — the adapter auto-detects `'text'` for MongoDB
+5. **Switch the Payload database adapter**:
+   ```ts
+   // Before
+   import { postgresAdapter } from '@payloadcms/db-postgres'
+   db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URL } })
+
+   // After
+   import { mongooseAdapter } from '@payloadcms/db-mongodb'
+   db: mongooseAdapter({ url: process.env.DATABASE_URI! })
+   ```
+6. **Remove `idFieldsAllowlist`/`idFieldsBlocklist`** from `adapterConfig` if set — these are only relevant for serial ID conversion
+
+---
+
 ## API Reference
 
 ### `payloadAdapter(config)`
@@ -312,13 +420,16 @@ payloadAdapter({
 |--------|------|-------------|
 | `payloadClient` | `BasePayload \| () => Promise<BasePayload>` | Payload instance or factory function |
 | `adapterConfig.enableDebugLogs` | `boolean` | Enable debug logging (default: `false`) |
-| `adapterConfig.idType` | `'number' \| 'text'` | ID type (default: `'number'` for Payload's SERIAL IDs) |
+| `adapterConfig.dbType` | `'postgres' \| 'mongodb' \| 'sqlite'` | Database type (auto-detected from Payload's adapter) |
+| `adapterConfig.idType` | `'number' \| 'text'` | ID type (auto-detected: `'number'` for Postgres/SQLite, `'text'` for MongoDB) |
 | `adapterConfig.idFieldsAllowlist` | `string[]` | Additional fields to convert to numeric IDs (default: `[]`) |
 | `adapterConfig.idFieldsBlocklist` | `string[]` | Fields to exclude from numeric ID conversion (default: `[]`) |
 
-**ID Type:**
-- Defaults to `'number'` (SERIAL) - Payload's default
-- Set `idType: 'text'` if using UUIDs
+**Database & ID Type:**
+- **Auto-detected**: The adapter reads `payload.db.name` to determine the database type, then sets `idType` accordingly
+- **Postgres/SQLite**: `idType` defaults to `'number'` (SERIAL IDs)
+- **MongoDB**: `idType` is always `'text'` (ObjectId strings)
+- Set `dbType` explicitly only if auto-detection doesn't work for your adapter
 
 **Note:** When using number IDs (default), you can optionally set `generateId: 'serial'` in Better Auth to be explicit:
 ```typescript

package/dist/adapter/collections.js

@@ -303,11 +303,19 @@ function generateCollection(modelKey, table, usePlural, adminGroup, customAccess
             });
         } else {
             const saveToJWT = configureSaveToJWT ? getSaveToJWT(modelKey, payloadFieldName) : undefined;
+            // Fields managed exclusively by Better Auth should be read-only in the admin UI
+            const readOnlyFields = [
+                'twoFactorEnabled'
+            ];
+            const isReadOnly = readOnlyFields.includes(payloadFieldName);
             const field = {
                 name: payloadFieldName,
                 type: fieldType,
                 admin: {
-                    description: `Auto-added by Better Auth (${fieldKey})`
+                    description: `Auto-added by Better Auth (${fieldKey})`,
+                    ...isReadOnly && {
+                        readOnly: true
+                    }
                 },
                 ...saveToJWT !== undefined && {
                     saveToJWT

package/dist/adapter/index.d.ts

@@ -8,6 +8,20 @@
  */
 import type { Adapter, BetterAuthOptions } from 'better-auth';
 import type { BasePayload } from 'payload';
+/**
+ * Database types supported by Payload CMS.
+ */
+export type DbType = 'postgres' | 'mongodb' | 'sqlite';
+/**
+ * Detect the database type from the Payload instance.
+ */
+export declare function detectDbType(payload: BasePayload): DbType;
+/**
+ * Determine ID type based on database type and Better Auth config.
+ * MongoDB always uses text IDs (ObjectId strings).
+ * Postgres defaults to 'number' (SERIAL) unless generateId indicates otherwise.
+ */
+export declare function resolveIdType(dbType: DbType, options: BetterAuthOptions, explicitIdType?: 'number' | 'text'): 'number' | 'text';
 export type PayloadAdapterConfig = {
     /**
      * The Payload instance or a function that returns it.
@@ -22,6 +36,11 @@ export type PayloadAdapterConfig = {
          * Enable debug logging for troubleshooting
          */
         enableDebugLogs?: boolean;
+        /**
+         * Database type. Auto-detected from Payload's database adapter if not set.
+         * Set explicitly if auto-detection doesn't work for your adapter.
+         */
+        dbType?: DbType;
         /**
          * ID type used by Payload.
          * If not specified, auto-detects from Better Auth's generateId setting.

package/dist/adapter/index.js

@@ -7,15 +7,26 @@
  * @packageDocumentation
  */ import { createAdapterFactory } from 'better-auth/adapters';
 /**
- * Detect ID type from Better Auth options.
- * Defaults to 'number' (SERIAL) since Payload uses SERIAL IDs by default.
- */ function detectIdType(options) {
+ * Detect the database type from the Payload instance.
+ */ export function detectDbType(payload) {
+    const dbName = payload.db?.name;
+    if (typeof dbName === 'string') {
+        if (dbName.includes('mongo') || dbName.includes('mongoose')) return 'mongodb';
+        if (dbName.includes('sqlite')) return 'sqlite';
+    }
+    return 'postgres';
+}
+/**
+ * Determine ID type based on database type and Better Auth config.
+ * MongoDB always uses text IDs (ObjectId strings).
+ * Postgres defaults to 'number' (SERIAL) unless generateId indicates otherwise.
+ */ export function resolveIdType(dbType, options, explicitIdType) {
+    if (dbType === 'mongodb') return 'text';
+    if (explicitIdType) return explicitIdType;
     const generateId = options.advanced?.database?.generateId;
-    // If explicitly set to something other than 'serial', use text (UUID)
     if (generateId !== undefined && generateId !== 'serial') {
         return 'text';
     }
-    // Default to number (SERIAL) - Payload's default
     return 'number';
 }
 /**
@@ -59,7 +70,7 @@
     async function resolvePayloadClient() {
         return typeof payloadClient === 'function' ? await payloadClient() : payloadClient;
     }
-    function convertOperator(operator, value) {
+    function convertOperator(operator, value, dbType) {
         switch(operator){
             case 'eq':
                 return {
@@ -89,15 +100,25 @@
                 return {
                     in: value
                 };
+            case 'not_in':
+                return {
+                    not_in: value
+                };
             case 'contains':
                 return {
                     contains: value
                 };
             case 'starts_with':
+                if (dbType === 'mongodb') return {
+                    contains: value
+                };
                 return {
                     like: `${value}%`
                 };
             case 'ends_with':
+                if (dbType === 'mongodb') return {
+                    contains: value
+                };
                 return {
                     like: `%${value}`
                 };
@@ -122,9 +143,11 @@
     }
     // Return the adapter factory function
     return (options)=>{
-        // Determine ID type: explicit config > auto-detect
-        // Defaults to 'number' (SERIAL) since Payload uses SERIAL IDs by default
-        const idType = adapterConfig.idType ?? detectIdType(options);
+        // Determine ID type based on database type
+        // If payloadClient is already resolved, detect dbType immediately
+        // Otherwise default to 'postgres' (will be updated on first operation)
+        const effectiveDbType = adapterConfig.dbType ?? (typeof payloadClient !== 'function' ? detectDbType(payloadClient) : 'postgres');
+        const idType = resolveIdType(effectiveDbType, options, adapterConfig.idType);
         const generateId = options.advanced?.database?.generateId;
         // Warn if using number IDs but Better Auth is explicitly configured to generate its own IDs
         // This would cause Better Auth to generate UUIDs which won't work with SERIAL columns
@@ -153,10 +176,10 @@
             // Payload collections are plural by default (users, sessions, etc.)
             // Users can customize via BetterAuthOptions: user: { modelName: 'custom_users' }
             usePlural: true,
-            // Let Payload generate IDs when using serial/auto-increment
-            disableIdGeneration: idType === 'number',
-            // Payload supports these features
-            supportsNumericIds: true,
+            // Payload always generates IDs (SERIAL for postgres/sqlite, ObjectId for mongodb)
+            disableIdGeneration: true,
+            // MongoDB uses ObjectId strings, not numeric IDs
+            supportsNumericIds: effectiveDbType !== 'mongodb',
             supportsDates: true,
             supportsBooleans: true,
             supportsJSON: true,
@@ -171,11 +194,18 @@
         // so we'll resolve it lazily on first operation
         let resolvedPayload = null;
         let resolvePromise = null;
+        let resolvedDbType = adapterConfig.dbType ?? null;
         const getPayload = async ()=>{
             if (resolvedPayload) return resolvedPayload;
             if (!resolvePromise) {
                 resolvePromise = resolvePayloadClient().then((p)=>{
                     resolvedPayload = p;
+                    if (!resolvedDbType) {
+                        resolvedDbType = detectDbType(p);
+                        if (enableDebugLogs) {
+                            console.log('[payload-adapter] Detected database type:', resolvedDbType);
+                        }
+                    }
                     return p;
                 });
             }
@@ -295,19 +325,6 @@
                             }
                         }
                     }
-                    // Convert date strings to Date objects
-                    // Better Auth expects Date objects for date field comparisons
-                    for (const [key, value] of Object.entries(transformed)){
-                        if (typeof value !== 'string') continue;
-                        // Check if schema defines this field as a date type
-                        const fieldDef = modelSchema.fields[key];
-                        if (fieldDef?.type === 'date') {
-                            const dateValue = new Date(value);
-                            if (!isNaN(dateValue.getTime())) {
-                                transformed[key] = dateValue;
-                            }
-                        }
-                    }
                     // Convert semantic ID fields to numbers when using serial IDs
                     // Heuristic: fields ending in 'Id' or '_id' containing numeric strings
                     // Modified by allowlist (add) and blocklist (exclude)
@@ -337,7 +354,7 @@
                     if (where.length === 1) {
                         const w = where[0];
                         return {
-                            [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value)
+                            [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value, resolvedDbType ?? 'postgres')
                         };
                     }
                     const andConditions = where.filter((w)=>w.connector !== 'OR');
@@ -345,12 +362,12 @@
                     const result = {};
                     if (andConditions.length > 0) {
                         result.and = andConditions.map((w)=>({
-                                [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value)
+                                [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value, resolvedDbType ?? 'postgres')
                             }));
                     }
                     if (orConditions.length > 0) {
                         result.or = orConditions.map((w)=>({
-                                [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value)
+                                [getPayloadFieldName(model, w.field)]: convertOperator(w.operator, w.value, resolvedDbType ?? 'postgres')
                             }));
                     }
                     return result;
@@ -389,10 +406,19 @@
                             // Transform back and merge with input data for Better Auth
                             // Database result takes precedence (handles hooks that modify data like firstUserAdmin)
                             const transformed = transformDataFromPayload(model, result);
-                            return {
+                            const merged = {
                                 ...data,
                                 ...transformed
                             };
+                            if (enableDebugLogs) {
+                                debugLog('create result', {
+                                    collection,
+                                    resultId: result.id,
+                                    transformedKeys: Object.keys(transformed),
+                                    mergedKeys: Object.keys(merged)
+                                });
+                            }
+                            return merged;
                         } catch (error) {
                             console.error('[payload-adapter] create failed:', {
                                 collection,
@@ -424,15 +450,39 @@
                                         depth: join ? 1 : 0,
                                         overrideAccess: true
                                     });
-                                    return transformDataFromPayload(model, result);
+                                    const transformed = transformDataFromPayload(model, result);
+                                    if (enableDebugLogs) {
+                                        debugLog('findOne result (byID)', {
+                                            collection,
+                                            id: convertId(id),
+                                            found: true,
+                                            transformedKeys: Object.keys(transformed)
+                                        });
+                                    }
+                                    return transformed;
                                 } catch (error) {
                                     if (error instanceof Error && 'status' in error && error.status === 404) {
+                                        if (enableDebugLogs) {
+                                            debugLog('findOne result (byID)', {
+                                                collection,
+                                                id: convertId(id),
+                                                found: false
+                                            });
+                                        }
                                         return null;
                                     }
                                     throw error;
                                 }
                             }
                             const payloadWhere = convertWhereToPayload(model, where);
+                            if (enableDebugLogs) {
+                                debugLog('findOne query', {
+                                    collection,
+                                    payloadWhere: JSON.stringify(payloadWhere),
+                                    resolvedDbType,
+                                    idType
+                                });
+                            }
                             const result = await payload.find({
                                 collection,
                                 where: payloadWhere,
@@ -440,8 +490,22 @@
                                 depth: join ? 1 : 0,
                                 overrideAccess: true
                             });
+                            if (enableDebugLogs) {
+                                debugLog('findOne result', {
+                                    collection,
+                                    totalDocs: result.totalDocs,
+                                    found: result.docs.length > 0
+                                });
+                            }
                             if (!result.docs[0]) return null;
-                            return transformDataFromPayload(model, result.docs[0]);
+                            const transformed = transformDataFromPayload(model, result.docs[0]);
+                            if (enableDebugLogs) {
+                                debugLog('findOne transformed', {
+                                    collection,
+                                    transformedKeys: Object.keys(transformed)
+                                });
+                            }
+                            return transformed;
                         } catch (error) {
                             console.error('[payload-adapter] findOne failed:', {
                                 model,

package/dist/components/LogoutButton.d.ts

@@ -1,6 +1,9 @@
 /**
  * Logout button component styled to match Payload's admin nav.
  * Uses Payload's CSS classes and variables for native theme integration.
+ *
+ * Clears both Better Auth session and Payload's JWT cookie to ensure
+ * clean state when switching between users.
  */
 export declare function LogoutButton(): import("react").JSX.Element;
 export default LogoutButton;

package/dist/components/LogoutButton.js

@@ -5,6 +5,9 @@ import { useRouter } from 'next/navigation.js';
 /**
  * Logout button component styled to match Payload's admin nav.
  * Uses Payload's CSS classes and variables for native theme integration.
+ *
+ * Clears both Better Auth session and Payload's JWT cookie to ensure
+ * clean state when switching between users.
  */ export function LogoutButton() {
     const router = useRouter();
     const [isLoading, setIsLoading] = useState(false);
@@ -12,14 +15,23 @@ import { useRouter } from 'next/navigation.js';
         if (isLoading) return;
         setIsLoading(true);
         try {
-            await fetch('/api/auth/sign-out', {
-                method: 'POST',
-                credentials: 'include',
-                headers: {
-                    'Content-Type': 'application/json'
-                },
-                body: JSON.stringify({})
-            });
+            // Clear both sessions simultaneously while cookies are still valid.
+            // - Better Auth: clears BA session cookie
+            // - Payload: clears JWT cookie (payload-token) so useAuth() resets
+            await Promise.allSettled([
+                fetch('/api/auth/sign-out', {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({})
+                }),
+                fetch('/api/users/logout', {
+                    method: 'POST',
+                    credentials: 'include'
+                })
+            ]);
             router.push('/admin/login');
         } catch (error) {
             console.error('[better-auth] Logout error:', error);