@delmaredigital/payload-better-auth 0.3.13 → 0.3.15

package/README.md

@@ -545,12 +545,14 @@ Payload auth strategy for Better Auth session validation.
 ```ts
 betterAuthStrategy({
   usersCollection: 'users',
+  idType: 'number', // default — coerces session field IDs for serial IDs
 })
 ```
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `usersCollection` | `string` | The collection slug for users (default: `'users'`) |
+| `idType` | `'number' \| 'text'` | Coerces string IDs in session fields (`activeOrganizationId`, etc.) to numbers. Defaults to `'number'` matching the adapter default. Set to `'text'` for UUID IDs. |
 
 ### `getServerSession<TUser>(payload, headers)`
 
@@ -576,7 +578,7 @@ const user = await getServerUser<User>(payload, headersList)
 // user.role, user.firstName, etc. are fully typed
 ```
 
-### `createSessionHelpers<TUser>()`
+### `createSessionHelpers<TUser>(options?)`
 
 Create typed session helpers bound to your User type. Define once, import everywhere — no generics needed at call sites:
 
@@ -596,6 +598,18 @@ const session = await getServerSession(payload, headersList)
 // session.user is typed as User — no generic needed
 ```
 
+**Serial IDs (Payload default):** Better Auth always returns string IDs from `api.getSession()`, which causes Payload relationship fields to reject them. Pass `idType: 'number'` to coerce ID fields to numbers automatically:
+
+```ts
+export const { getServerSession, getServerUser } = createSessionHelpers<User>({
+  idType: 'number', // coerces user.id, session.userId, etc. to numbers
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `idType` | `'number' \| 'text'` | Set to `'number'` when using serial IDs to coerce string IDs to numbers. Matches the adapter's `adapterConfig.idType` option. |
+
 ### `withBetterAuthDefaults(options)`
 
 Applies sensible defaults to Better Auth options. Useful for simplifying common configurations.

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { ApiKeyInfo, ApiKeyAccessConfig, } from './utils/apiKeyAccess.js';
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 export type { AuthDetectionResult } from './utils/detectAuthConfig.js';
 export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';
-export type { Session } from './utils/session.js';
+export type { Session, SessionHelperOptions } from './utils/session.js';
 export { firstUserAdminHooks } from './utils/firstUserAdmin.js';
 export type { FirstUserAdminOptions } from './utils/firstUserAdmin.js';
 export { withBetterAuthDefaults, apiKeyWithDefaults } from './utils/betterAuthDefaults.js';

package/dist/plugin/index.d.ts

@@ -178,6 +178,17 @@ export type BetterAuthStrategyOptions = {
      * @default 'members'
      */
     membersCollection?: string;
+    /**
+     * ID type strategy matching your adapter's `adapterConfig.idType`.
+     *
+     * When `'number'` (default), coerces string IDs in session fields
+     * (e.g., `activeOrganizationId`) to numbers before merging onto `req.user`.
+     * Better Auth always returns string IDs from `api.getSession()`, but Payload
+     * relationship fields expect numbers when using serial IDs.
+     *
+     * @default 'number'
+     */
+    idType?: 'number' | 'text';
 };
 /**
  * Payload auth strategy that uses Better Auth for authentication.

package/dist/plugin/index.js

@@ -459,7 +459,7 @@ let apiKeyScopesConfig = undefined;
  * }
  * ```
  */ export function betterAuthStrategy(options = {}) {
-    const { usersCollection = 'users', membersCollection = 'members' } = options;
+    const { usersCollection = 'users', membersCollection = 'members', idType = 'number' } = options;
     return {
         name: 'better-auth',
         authenticate: async ({ payload, headers })=>{
@@ -498,6 +498,19 @@ let apiKeyScopesConfig = undefined;
                 // Extract session fields to merge onto user (e.g., activeOrganizationId from org plugin)
                 // Exclude fields that might conflict with user fields
                 const { id: _sessionId, userId: _userId, expiresAt: _expiresAt, token: _token, ...sessionFields } = sessionData.session || {};
+                // Coerce string IDs in session fields to numbers when using serial IDs.
+                // BA's api.getSession() always returns strings, but Payload relationship
+                // fields expect numbers for serial IDs.
+                if (idType === 'number') {
+                    for (const [key, value] of Object.entries(sessionFields)){
+                        if (typeof value !== 'string') continue;
+                        if (key === 'id' || /(?:Id|_id)$/.test(key)) {
+                            if (/^\d+$/.test(value)) {
+                                sessionFields[key] = parseInt(value, 10);
+                            }
+                        }
+                    }
+                }
                 // If there's an active organization, fetch the user's role in that org
                 let organizationRole;
                 if (sessionFields.activeOrganizationId) {

package/dist/utils/session.d.ts

@@ -69,6 +69,19 @@ export declare function getServerSession<TUser = DefaultUser>(payload: BasePaylo
  * ```
  */
 export declare function getServerUser<TUser = DefaultUser>(payload: BasePayload, headers: Headers): Promise<TUser | null>;
+export type SessionHelperOptions = {
+    /**
+     * ID type strategy matching your adapter's `adapterConfig.idType`.
+     *
+     * Set to `'number'` when using Payload's default serial IDs.
+     * Better Auth always returns string IDs from `api.getSession()` —
+     * this option coerces `id` and `*Id` / `*_id` fields to numbers
+     * so they work directly in Payload relationship fields.
+     *
+     * @default undefined (no coercion)
+     */
+    idType?: 'number' | 'text';
+};
 /**
  * Create typed session helpers bound to your User type.
  *
@@ -84,15 +97,24 @@ export declare function getServerUser<TUser = DefaultUser>(payload: BasePayload,
  * export const { getServerSession, getServerUser } = createSessionHelpers<User>()
  * ```
  *
+ * @example
+ * ```ts
+ * // With serial IDs (Payload default) — coerces string IDs to numbers
+ * export const { getServerSession, getServerUser } = createSessionHelpers<User>({
+ *   idType: 'number',
+ * })
+ * ```
+ *
  * ```ts
  * // app/page.tsx
  * import { getServerSession } from '@/lib/auth'
  *
  * const session = await getServerSession(payload, headersList)
  * // session.user is typed as User — no generic needed
+ * // session.user.id is a number when idType: 'number'
  * ```
  */
-export declare function createSessionHelpers<TUser = DefaultUser>(): {
+export declare function createSessionHelpers<TUser = DefaultUser>(options?: SessionHelperOptions): {
     getServerSession: (payload: BasePayload, headers: Headers) => Promise<Session<TUser> | null>;
     getServerUser: (payload: BasePayload, headers: Headers) => Promise<TUser | null>;
 };

package/dist/utils/session.js

@@ -68,6 +68,24 @@
     const session = await getServerSession(payload, headers);
     return session?.user ?? null;
 }
+/**
+ * Coerce numeric-string ID fields to numbers on a shallow object.
+ * Matches the adapter's heuristic: `id`, fields ending in `Id` or `_id`.
+ */ function coerceIds(obj) {
+    if (!obj || typeof obj !== 'object') return obj;
+    const result = {
+        ...obj
+    };
+    for (const [key, value] of Object.entries(result)){
+        if (typeof value !== 'string') continue;
+        if (key === 'id' || /(?:Id|_id)$/.test(key)) {
+            if (/^\d+$/.test(value)) {
+                result[key] = parseInt(value, 10);
+            }
+        }
+    }
+    return result;
+}
 /**
  * Create typed session helpers bound to your User type.
  *
@@ -83,16 +101,37 @@
  * export const { getServerSession, getServerUser } = createSessionHelpers<User>()
  * ```
  *
+ * @example
+ * ```ts
+ * // With serial IDs (Payload default) — coerces string IDs to numbers
+ * export const { getServerSession, getServerUser } = createSessionHelpers<User>({
+ *   idType: 'number',
+ * })
+ * ```
+ *
  * ```ts
  * // app/page.tsx
  * import { getServerSession } from '@/lib/auth'
  *
  * const session = await getServerSession(payload, headersList)
  * // session.user is typed as User — no generic needed
+ * // session.user.id is a number when idType: 'number'
  * ```
- */ export function createSessionHelpers() {
+ */ export function createSessionHelpers(options) {
+    const shouldCoerceIds = options?.idType === 'number';
+    const typedGetServerSession = async (payload, headers)=>{
+        const session = await getServerSession(payload, headers);
+        if (!session || !shouldCoerceIds) return session;
+        return {
+            user: coerceIds(session.user),
+            session: coerceIds(session.session)
+        };
+    };
     return {
-        getServerSession: (payload, headers)=>getServerSession(payload, headers),
-        getServerUser: (payload, headers)=>getServerUser(payload, headers)
+        getServerSession: typedGetServerSession,
+        getServerUser: async (payload, headers)=>{
+            const session = await typedGetServerSession(payload, headers);
+            return session?.user ?? null;
+        }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-better-auth",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",