@delmaredigital/payload-better-auth 0.3.12 → 0.3.14

package/README.md

@@ -552,24 +552,62 @@ betterAuthStrategy({
 |--------|------|-------------|
 | `usersCollection` | `string` | The collection slug for users (default: `'users'`) |
 
-### `getServerSession(payload, headers)`
+### `getServerSession<TUser>(payload, headers)`
 
-Get the current session on the server.
+Get the current session on the server. Pass your Payload `User` type for full type safety:
 
 ```ts
-const session = await getServerSession(payload, headersList)
-// Returns: { user: { id, email, name, ... }, session: { id, expiresAt, ... } } | null
+import { getServerSession } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+const session = await getServerSession<User>(payload, headersList)
+// session.user.role, session.user.firstName, etc. are fully typed
+```
+
+### `getServerUser<TUser>(payload, headers)`
+
+Get the current user on the server (shorthand for `session.user`):
+
+```ts
+import { getServerUser } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+const user = await getServerUser<User>(payload, headersList)
+// user.role, user.firstName, etc. are fully typed
 ```
 
-### `getServerUser(payload, headers)`
+### `createSessionHelpers<TUser>(options?)`
 
-Get the current user on the server (shorthand for `session.user`).
+Create typed session helpers bound to your User type. Define once, import everywhere — no generics needed at call sites:
 
 ```ts
-const user = await getServerUser(payload, headersList)
-// Returns: { id, email, name, ... } | null
+// lib/auth.ts
+import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+export const { getServerSession, getServerUser } = createSessionHelpers<User>()
 ```
 
+```ts
+// app/page.tsx
+import { getServerSession } from '@/lib/auth'
+
+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

@@ -22,8 +22,8 @@ export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAn
 export type { ApiKeyInfo, ApiKeyAccessConfig, } from './utils/apiKeyAccess.js';
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 export type { AuthDetectionResult } from './utils/detectAuthConfig.js';
-export { getServerSession, getServerUser } from './utils/session.js';
-export type { Session } from './utils/session.js';
+export { getServerSession, getServerUser, createSessionHelpers } 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/index.js

@@ -20,7 +20,7 @@ export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAn
 // Auth config detection utility
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 // Session utilities
-export { getServerSession, getServerUser } from './utils/session.js';
+export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';
 // First user admin hook utility
 export { firstUserAdminHooks } from './utils/firstUserAdmin.js';
 // Better Auth defaults utility

package/dist/utils/session.d.ts

@@ -4,14 +4,15 @@
  * @packageDocumentation
  */
 import type { BasePayload } from 'payload';
-export type Session = {
-    user: {
-        id: string;
-        email: string;
-        name?: string;
-        image?: string;
-        [key: string]: unknown;
-    };
+type DefaultUser = {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    [key: string]: unknown;
+};
+export type Session<TUser = DefaultUser> = {
+    user: TUser;
     session: {
         id: string;
         expiresAt: Date;
@@ -21,35 +22,43 @@ export type Session = {
 /**
  * Get the current session from headers.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ * Pass your Payload-generated `User` type for full type safety.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerSession } from '@delmare/payload-better-auth'
+ * import { getServerSession } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const session = await getServerSession(payload, headersList)
+ *   const session = await getServerSession<User>(payload, headersList)
  *
  *   if (!session) {
  *     redirect('/login')
  *   }
  *
+ *   // session.user.role is fully typed
  *   return <div>Hello {session.user.name}</div>
  * }
  * ```
  */
-export declare function getServerSession(payload: BasePayload, headers: Headers): Promise<Session | null>;
+export declare function getServerSession<TUser = DefaultUser>(payload: BasePayload, headers: Headers): Promise<Session<TUser> | null>;
 /**
  * Get the current user from the session.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerUser } from '@delmare/payload-better-auth'
+ * import { getServerUser } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const user = await getServerUser(payload, headersList)
+ *   const user = await getServerUser<User>(payload, headersList)
  *
  *   if (!user) {
  *     redirect('/login')
@@ -59,4 +68,54 @@ export declare function getServerSession(payload: BasePayload, headers: Headers)
  * }
  * ```
  */
-export declare function getServerUser(payload: BasePayload, headers: Headers): Promise<Session['user'] | null>;
+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.
+ *
+ * Define once in a shared file, then import the typed helpers
+ * everywhere — no generics needed at call sites.
+ *
+ * @example
+ * ```ts
+ * // lib/auth.ts
+ * import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
+ *
+ * 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>(options?: SessionHelperOptions): {
+    getServerSession: (payload: BasePayload, headers: Headers) => Promise<Session<TUser> | null>;
+    getServerUser: (payload: BasePayload, headers: Headers) => Promise<TUser | null>;
+};
+export {};

package/dist/utils/session.js

@@ -5,19 +5,24 @@
  */ /**
  * Get the current session from headers.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ * Pass your Payload-generated `User` type for full type safety.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerSession } from '@delmare/payload-better-auth'
+ * import { getServerSession } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const session = await getServerSession(payload, headersList)
+ *   const session = await getServerSession<User>(payload, headersList)
  *
  *   if (!session) {
  *     redirect('/login')
  *   }
  *
+ *   // session.user.role is fully typed
  *   return <div>Hello {session.user.name}</div>
  * }
  * ```
@@ -40,14 +45,17 @@
 /**
  * Get the current user from the session.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerUser } from '@delmare/payload-better-auth'
+ * import { getServerUser } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const user = await getServerUser(payload, headersList)
+ *   const user = await getServerUser<User>(payload, headersList)
  *
  *   if (!user) {
  *     redirect('/login')
@@ -60,3 +68,70 @@
     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.
+ *
+ * Define once in a shared file, then import the typed helpers
+ * everywhere — no generics needed at call sites.
+ *
+ * @example
+ * ```ts
+ * // lib/auth.ts
+ * import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
+ *
+ * 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(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: 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.12",
+  "version": "0.3.14",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",