@delmaredigital/payload-better-auth 0.3.10 → 0.3.11

package/README.md

@@ -2,11 +2,19 @@
 
 Better Auth adapter and plugins for Payload CMS. Enables seamless integration between Better Auth and Payload.
 
-[![Demo](https://img.shields.io/badge/Demo-Live-blue)](https://demo.delmaredigital.com)
-[![Starter Template](https://img.shields.io/badge/Starter-Template-green)](https://github.com/delmaredigital/dd-starter)
-[![Deploy with Vercel](https://vercel.com/button)](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)
+<p align="center">
+  <a href="https://demo.delmaredigital.com"><img src="https://img.shields.io/badge/Live_Demo-Try_It_Now-2ea44f?style=for-the-badge&logo=vercel&logoColor=white" alt="Live Demo - Try It Now"></a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/delmaredigital/dd-starter"><img src="https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white" alt="Starter Template - Use This"></a>
+</p>
+
+<p align="center">
+  <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>
 
 ---
+## Documentation
+For additional documentation and references, visit: [https://deepwiki.com/delmaredigital/payload-better-auth](https://deepwiki.com/delmaredigital/payload-better-auth)
 
 ## Table of Contents
 
@@ -17,6 +25,7 @@ Better Auth adapter and plugins for Payload CMS. Enables seamless integration be
 - [Access Control Helpers](#access-control-helpers)
 - [API Key Scope Enforcement](#api-key-scope-enforcement)
 - [Plugin Compatibility](#plugin-compatibility)
+- [Recipes](#recipes)
 - [Types](#types)
 - [License](#license)
 
@@ -1585,6 +1594,130 @@ createBetterAuthPlugin({
 
 ---
 
+## Recipes
+
+Common patterns and solutions for Better Auth integration.
+
+### Auto-Create Organization on User Signup
+
+A common pattern is to automatically create a personal workspace/organization when a user signs up (and verifies their email). The key is to use Better Auth's organization API (`auth.api.createOrganization()`) rather than raw adapter calls, so that `organizationHooks` fire properly.
+
+**The Challenge:** Database hooks are defined in `betterAuthOptions` before the `auth` instance exists, so you can't directly reference `auth.api` in your hooks.
+
+**The Solution:** Use a lazy auth instance singleton:
+
+**Step 1: Create an auth instance singleton**
+
+```typescript
+// src/lib/auth/instance.ts
+import type { betterAuth } from 'better-auth'
+
+type AuthInstance = ReturnType<typeof betterAuth>
+
+let authInstance: AuthInstance | null = null
+
+export function setAuthInstance(auth: AuthInstance): void {
+  authInstance = auth
+}
+
+export function getAuthInstance(): AuthInstance {
+  if (!authInstance) {
+    throw new Error('Auth not initialized')
+  }
+  return authInstance
+}
+```
+
+**Step 2: Store the instance after creation**
+
+```typescript
+// src/payload.config.ts (or wherever you configure plugins)
+import { setAuthInstance } from '@/lib/auth/instance'
+
+createBetterAuthPlugin({
+  createAuth: (payload) => {
+    const auth = betterAuth({
+      ...betterAuthOptions,
+      database: payloadAdapter({ payloadClient: payload }),
+      // ... other options
+    })
+
+    // Store for use in database hooks
+    setAuthInstance(auth)
+
+    return auth
+  },
+})
+```
+
+**Step 3: Use the organization API in database hooks**
+
+```typescript
+// src/lib/auth/config.ts
+import { getAuthInstance } from './instance'
+
+export const betterAuthOptions: Partial<BetterAuthOptions> = {
+  // ... other options
+
+  plugins: [
+    organization({
+      // organizationHooks fire when using auth.api.createOrganization()
+      organizationHooks: {
+        afterCreateOrganization: async ({ organization }) => {
+          // This runs for ALL org creations - auto-created, manual, API
+          console.log(`Organization ${organization.id} created`)
+          // Create related records, send welcome email, etc.
+        },
+      },
+    }),
+  ],
+
+  databaseHooks: {
+    user: {
+      update: {
+        after: async (user, ctx) => {
+          // Only proceed if user just verified their email
+          if (!user.emailVerified) return
+
+          // Check if user already has an organization (e.g., joined via invitation)
+          const existingMembership = await ctx?.context?.adapter?.findOne({
+            model: 'member',
+            where: [{ field: 'userId', value: user.id }],
+          })
+          if (existingMembership) return
+
+          // Create organization using the proper API
+          // This ensures organizationHooks.afterCreateOrganization fires
+          const auth = getAuthInstance()
+          await auth.api.createOrganization({
+            body: {
+              name: `${user.name}'s Workspace`,
+              slug: generateUniqueSlug(user.name),
+              userId: user.id,
+            },
+          })
+        },
+      },
+    },
+  },
+}
+```
+
+**Why This Matters:**
+
+| Approach | organizationHooks fire? | Recommended? |
+|----------|------------------------|--------------|
+| `auth.api.createOrganization()` | ✅ Yes | ✅ Yes |
+| `ctx.context.adapter.create({ model: 'organization' })` | ❌ No | ❌ No |
+
+Using the raw adapter bypasses Better Auth's organization plugin entirely. Any logic in `organizationHooks` (like creating related records, sending notifications, or syncing with external systems) won't run.
+
+**Handling Invitations:**
+
+Users who join via invitation already have a membership record (created when they accept the invitation), so the `existingMembership` check prevents creating a duplicate personal organization for them.
+
+---
+
 ## Types
 
 The package exports comprehensive TypeScript types for Better Auth integration.

package/dist/adapter/index.js

@@ -295,6 +295,19 @@
                             }
                         }
                     }
+                    // 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)

package/package.json

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