@delmaredigital/payload-better-auth 0.3.13 → 0.3.14

package/README.md

@@ -576,7 +576,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 +596,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/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.14",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",