payload 4.0.0-internal.bc5cf8c → 4.0.0-internal.bf4bcce

package/skills/payload/reference/ADAPTERS.md

@@ -0,0 +1,312 @@
+# Payload Adapters Reference
+
+Complete reference for database, storage, and email adapters.
+
+## Database Adapters
+
+### MongoDB
+
+```ts
+import { mongooseAdapter } from '@payloadcms/db-mongodb'
+
+export default buildConfig({
+  db: mongooseAdapter({
+    url: process.env.DATABASE_URL,
+  }),
+})
+```
+
+### Postgres
+
+```ts
+import { postgresAdapter } from '@payloadcms/db-postgres'
+
+export default buildConfig({
+  db: postgresAdapter({
+    pool: {
+      connectionString: process.env.DATABASE_URL,
+    },
+    push: false, // Don't auto-push schema changes
+    migrationDir: './migrations',
+  }),
+})
+```
+
+### SQLite
+
+```ts
+import { sqliteAdapter } from '@payloadcms/db-sqlite'
+
+export default buildConfig({
+  db: sqliteAdapter({
+    client: {
+      url: 'file:./payload.db',
+    },
+    transactionOptions: {}, // Enable transactions (disabled by default)
+  }),
+})
+```
+
+## Transactions
+
+Payload automatically uses transactions for all-or-nothing database operations. Pass `req` to include operations in the same transaction.
+
+```ts
+import type { CollectionAfterChangeHook } from 'payload'
+
+const afterChange: CollectionAfterChangeHook = async ({ req, doc }) => {
+  // This will be part of the same transaction
+  await req.payload.create({
+    req, // Pass req to use same transaction
+    collection: 'audit-log',
+    overrideAccess: true,
+    data: { action: 'created', docId: doc.id },
+  })
+}
+
+// Manual transaction control
+const transactionID = await payload.db.beginTransaction()
+try {
+  await payload.create({
+    collection: 'orders',
+    overrideAccess: true,
+    data: orderData,
+    req: { transactionID },
+  })
+  await payload.update({
+    collection: 'inventory',
+    overrideAccess: true,
+    id: itemId,
+    data: { stock: newStock },
+    req: { transactionID },
+  })
+  await payload.db.commitTransaction(transactionID)
+} catch (error) {
+  await payload.db.rollbackTransaction(transactionID)
+  throw error
+}
+```
+
+**Note**: MongoDB requires replicaset for transactions. SQLite requires `transactionOptions: {}` to enable.
+
+### Threading req Through Operations
+
+**Critical**: When performing nested operations in hooks, always pass `req` to maintain transaction context. Failing to do so breaks atomicity and can cause partial updates.
+
+```ts
+import type { CollectionAfterChangeHook } from 'payload'
+
+// ✅ CORRECT: Thread req through nested operations
+const resaveChildren: CollectionAfterChangeHook = async ({ collection, doc, req }) => {
+  // Find children - pass req
+  const children = await req.payload.find({
+    collection: 'children',
+    overrideAccess: true,
+    where: { parent: { equals: doc.id } },
+    req, // Maintains transaction context
+  })
+
+  // Update each child - pass req
+  for (const child of children.docs) {
+    await req.payload.update({
+      id: child.id,
+      collection: 'children',
+      overrideAccess: true,
+      data: { updatedField: 'value' },
+      req, // Same transaction as parent operation
+    })
+  }
+}
+
+// ❌ WRONG: Missing req breaks transaction
+const brokenHook: CollectionAfterChangeHook = async ({ collection, doc, req }) => {
+  const children = await req.payload.find({
+    collection: 'children',
+    overrideAccess: true,
+    where: { parent: { equals: doc.id } },
+    // Missing req - separate transaction or no transaction
+  })
+
+  for (const child of children.docs) {
+    await req.payload.update({
+      id: child.id,
+      collection: 'children',
+      overrideAccess: true,
+      data: { updatedField: 'value' },
+      // Missing req - if parent operation fails, these updates persist
+    })
+  }
+}
+```
+
+**Why This Matters:**
+
+- **MongoDB (with replica sets)**: Creates atomic session across operations
+- **PostgreSQL**: All operations use same Drizzle transaction
+- **SQLite (with transactions enabled)**: Ensures rollback on errors
+- **Without req**: Each operation runs independently, breaking atomicity
+
+**When req is Required:**
+
+- All mutating operations in hooks (create, update, delete)
+- Operations that must succeed/fail together
+- When using MongoDB replica sets or Postgres
+- Any operation that relies on `req.context` or `req.user`
+
+**When req is Optional:**
+
+- Read-only lookups independent of current transaction
+- Operations with `disableTransaction: true`
+- Administrative operations with `overrideAccess: true`
+
+## Storage Adapters
+
+Available storage adapters:
+
+- **@payloadcms/storage-s3** - AWS S3
+- **@payloadcms/storage-azure** - Azure Blob Storage
+- **@payloadcms/storage-gcs** - Google Cloud Storage
+- **@payloadcms/storage-r2** - Cloudflare R2
+- **@payloadcms/storage-vercel-blob** - Vercel Blob
+
+### AWS S3
+
+```ts
+import { s3Storage } from '@payloadcms/storage-s3'
+
+export default buildConfig({
+  plugins: [
+    s3Storage({
+      collections: {
+        media: true,
+      },
+      bucket: process.env.S3_BUCKET,
+      config: {
+        credentials: {
+          accessKeyId: process.env.S3_ACCESS_KEY_ID,
+          secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+        },
+        region: process.env.S3_REGION,
+      },
+    }),
+  ],
+})
+```
+
+### Azure Blob Storage
+
+```ts
+import { azureStorage } from '@payloadcms/storage-azure'
+
+export default buildConfig({
+  plugins: [
+    azureStorage({
+      collections: {
+        media: true,
+      },
+      connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
+      containerName: process.env.AZURE_STORAGE_CONTAINER_NAME,
+    }),
+  ],
+})
+```
+
+### Google Cloud Storage
+
+```ts
+import { gcsStorage } from '@payloadcms/storage-gcs'
+
+export default buildConfig({
+  plugins: [
+    gcsStorage({
+      collections: {
+        media: true,
+      },
+      bucket: process.env.GCS_BUCKET,
+      options: {
+        projectId: process.env.GCS_PROJECT_ID,
+        credentials: JSON.parse(process.env.GCS_CREDENTIALS),
+      },
+    }),
+  ],
+})
+```
+
+### Cloudflare R2
+
+```ts
+import { r2Storage } from '@payloadcms/storage-r2'
+
+export default buildConfig({
+  plugins: [
+    r2Storage({
+      collections: {
+        media: true,
+      },
+      bucket: process.env.R2_BUCKET,
+      config: {
+        credentials: {
+          accessKeyId: process.env.R2_ACCESS_KEY_ID,
+          secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+        },
+        region: 'auto',
+        endpoint: process.env.R2_ENDPOINT,
+      },
+    }),
+  ],
+})
+```
+
+### Vercel Blob
+
+```ts
+import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
+
+export default buildConfig({
+  plugins: [
+    vercelBlobStorage({
+      collections: {
+        media: true,
+      },
+      token: process.env.BLOB_READ_WRITE_TOKEN,
+    }),
+  ],
+})
+```
+
+## Email Adapters
+
+### Nodemailer (SMTP)
+
+```ts
+import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
+
+export default buildConfig({
+  email: nodemailerAdapter({
+    defaultFromAddress: 'noreply@example.com',
+    defaultFromName: 'My App',
+    transportOptions: {
+      host: process.env.SMTP_HOST,
+      port: 587,
+      auth: {
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS,
+      },
+    },
+  }),
+})
+```
+
+### Resend
+
+```ts
+import { resendAdapter } from '@payloadcms/email-resend'
+
+export default buildConfig({
+  email: resendAdapter({
+    defaultFromAddress: 'noreply@example.com',
+    defaultFromName: 'My App',
+    apiKey: process.env.RESEND_API_KEY,
+  }),
+})
+```

package/skills/payload/reference/ADVANCED.md

@@ -0,0 +1,393 @@
+# Payload Advanced Features
+
+Complete reference for authentication, jobs, custom endpoints, components, plugins, and localization.
+
+## Authentication
+
+### Login
+
+```ts
+// REST API
+const response = await fetch('/api/users/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    password: 'password',
+  }),
+})
+
+// Local API
+const result = await payload.login({
+  collection: 'users',
+  overrideAccess: false, // intentionally run the collection's login access control
+  data: {
+    email: 'user@example.com',
+    password: 'password',
+  },
+})
+```
+
+### Forgot Password
+
+```ts
+await payload.forgotPassword({
+  collection: 'users',
+  overrideAccess: true,
+  data: {
+    email: 'user@example.com',
+  },
+})
+```
+
+### Custom Strategy
+
+```ts
+import type { CollectionConfig, Strategy } from 'payload'
+
+const customStrategy: Strategy = {
+  name: 'custom',
+  authenticate: async ({ payload, headers }) => {
+    const token = headers.get('authorization')?.split(' ')[1]
+    if (!token) return { user: null }
+
+    const user = await verifyToken(token)
+    return { user }
+  },
+}
+
+export const Users: CollectionConfig = {
+  slug: 'users',
+  auth: {
+    strategies: [customStrategy],
+  },
+  fields: [],
+}
+```
+
+### API Keys
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const APIKeys: CollectionConfig = {
+  slug: 'api-keys',
+  auth: {
+    disableLocalStrategy: true,
+    useAPIKey: true,
+  },
+  fields: [],
+}
+```
+
+## Jobs Queue
+
+Offload long-running or scheduled tasks to background workers.
+
+### Tasks
+
+```ts
+import { buildConfig } from 'payload'
+import type { TaskConfig } from 'payload'
+
+export default buildConfig({
+  jobs: {
+    tasks: [
+      {
+        slug: 'sendWelcomeEmail',
+        inputSchema: [
+          { name: 'userEmail', type: 'text', required: true },
+          { name: 'userName', type: 'text', required: true },
+        ],
+        outputSchema: [{ name: 'emailSent', type: 'checkbox', required: true }],
+        retries: 2, // Retry up to 2 times on failure
+        handler: async ({ input, req }) => {
+          await sendEmail({
+            to: input.userEmail,
+            subject: `Welcome ${input.userName}`,
+          })
+          return { output: { emailSent: true } }
+        },
+      } as TaskConfig<'sendWelcomeEmail'>,
+    ],
+  },
+})
+```
+
+### Queueing Jobs
+
+```ts
+// In a trusted hook or other system operation
+await req.payload.jobs.queue({
+  task: 'sendWelcomeEmail',
+  input: {
+    userEmail: 'user@example.com',
+    userName: 'John',
+  },
+  overrideAccess: true,
+  waitUntil: new Date('2024-12-31'), // Optional: schedule for future
+})
+```
+
+### Workflows
+
+Multi-step jobs that run in sequence:
+
+```ts
+{
+  slug: 'onboardUser',
+  inputSchema: [{ name: 'userId', type: 'text' }],
+  handler: async ({ job, req }) => {
+    const results = await job.runInlineTask({
+      task: async ({ input }) => {
+        // Step 1: Send welcome email
+        await sendEmail(input.userId)
+        return { output: { emailSent: true } }
+      },
+    })
+
+    await job.runInlineTask({
+      task: async () => {
+        // Step 2: Create onboarding tasks
+        await createTasks()
+        return { output: { tasksCreated: true } }
+      },
+    })
+  },
+}
+```
+
+## Custom Endpoints
+
+Add custom REST API routes to collections, globals, or root config. See [ENDPOINTS.md](ENDPOINTS.md) for detailed patterns, authentication, helpers, and real-world examples.
+
+### Root Endpoints
+
+```ts
+import { buildConfig } from 'payload'
+import type { Endpoint } from 'payload'
+
+const helloEndpoint: Endpoint = {
+  path: '/hello',
+  method: 'get',
+  handler: () => {
+    return Response.json({ message: 'Hello!' })
+  },
+}
+
+const greetEndpoint: Endpoint = {
+  path: '/greet/:name',
+  method: 'get',
+  handler: (req) => {
+    return Response.json({
+      message: `Hello ${req.routeParams.name}!`,
+    })
+  },
+}
+
+export default buildConfig({
+  endpoints: [helloEndpoint, greetEndpoint],
+  collections: [],
+  secret: process.env.PAYLOAD_SECRET || '',
+})
+```
+
+### Collection Endpoints
+
+```ts
+import type { CollectionConfig, Endpoint } from 'payload'
+
+const featuredEndpoint: Endpoint = {
+  path: '/featured',
+  method: 'get',
+  handler: async (req) => {
+    const posts = await req.payload.find({
+      collection: 'posts',
+      overrideAccess: false,
+      req,
+      where: { featured: { equals: true } },
+    })
+    return Response.json(posts)
+  },
+}
+
+export const Posts: CollectionConfig = {
+  slug: 'posts',
+  endpoints: [featuredEndpoint],
+  fields: [
+    { name: 'title', type: 'text' },
+    { name: 'featured', type: 'checkbox' },
+  ],
+}
+```
+
+## Custom Components
+
+### Field Component (Client)
+
+```tsx
+'use client'
+import type React from 'react'
+import { useField } from '@payloadcms/ui'
+import type { TextFieldClientProps } from 'payload'
+
+export const CustomField: React.FC<TextFieldClientProps> = () => {
+  const { value, setValue } = useField()
+
+  return <input value={value || ''} onChange={(e) => setValue(e.target.value)} />
+}
+```
+
+### Custom View
+
+```tsx
+'use client'
+import { DefaultTemplate } from '@payloadcms/ui/rsc'
+
+export const CustomView = () => {
+  return (
+    <DefaultTemplate>
+      <h1>Custom Dashboard</h1>
+      {/* Your content */}
+    </DefaultTemplate>
+  )
+}
+```
+
+### Admin Config
+
+```ts
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  admin: {
+    components: {
+      beforeDashboard: ['/components/BeforeDashboard'],
+      beforeLogin: ['/components/BeforeLogin'],
+      views: {
+        custom: {
+          Component: '/views/Custom',
+          path: '/custom',
+        },
+      },
+    },
+  },
+  collections: [],
+  secret: process.env.PAYLOAD_SECRET || '',
+})
+```
+
+## Plugins
+
+### Available Plugins
+
+- **@payloadcms/plugin-seo** - SEO fields with meta title/description, Open Graph, preview generation
+- **@payloadcms/plugin-redirects** - Manage URL redirects (301/302) for Next.js apps
+- **@payloadcms/plugin-nested-docs** - Hierarchical document structures with breadcrumbs
+- **@payloadcms/plugin-form-builder** - Dynamic form builder with submissions and validation
+- **@payloadcms/plugin-search** - Full-text search integration (Algolia support)
+- **@payloadcms/plugin-stripe** - Stripe payments, subscriptions, webhooks
+- **@payloadcms/plugin-ecommerce** - Complete ecommerce solution (products, variants, carts, orders)
+- **@payloadcms/plugin-import-export** - Import/export data via CSV
+- **@payloadcms/plugin-multi-tenant** - Multi-tenancy with tenant isolation
+- **@payloadcms/plugin-sentry** - Sentry error tracking integration
+- **@payloadcms/plugin-mcp** - Model Context Protocol for AI integrations
+
+### Using Plugins
+
+```ts
+import { buildConfig } from 'payload'
+import { seoPlugin } from '@payloadcms/plugin-seo'
+import { redirectsPlugin } from '@payloadcms/plugin-redirects'
+
+export default buildConfig({
+  plugins: [
+    seoPlugin({
+      collections: ['posts', 'pages'],
+    }),
+    redirectsPlugin({
+      collections: ['pages'],
+    }),
+  ],
+  collections: [],
+  secret: process.env.PAYLOAD_SECRET || '',
+})
+```
+
+### Creating Plugins
+
+```ts
+import type { Config } from 'payload'
+
+interface PluginOptions {
+  enabled?: boolean
+}
+
+export const myPlugin =
+  (options: PluginOptions) =>
+  (config: Config): Config => ({
+    ...config,
+    collections: [
+      ...(config.collections || []),
+      {
+        slug: 'plugin-collection',
+        fields: [{ name: 'title', type: 'text' }],
+      },
+    ],
+    onInit: async (payload) => {
+      if (config.onInit) await config.onInit(payload)
+      // Plugin initialization
+    },
+  })
+```
+
+## Localization
+
+```ts
+import { buildConfig } from 'payload'
+import type { Field, Payload } from 'payload'
+
+export default buildConfig({
+  localization: {
+    locales: ['en', 'es', 'de'],
+    defaultLocale: 'en',
+    fallback: true,
+  },
+  collections: [],
+  secret: process.env.PAYLOAD_SECRET || '',
+})
+
+// Localized field
+const localizedField: TextField = {
+  name: 'title',
+  type: 'text',
+  localized: true,
+}
+
+// Query with locale
+const posts = await payload.find({
+  collection: 'posts',
+  overrideAccess: true,
+  locale: 'es',
+})
+```
+
+## TypeScript Type References
+
+For complete TypeScript type definitions and signatures, reference these files from the Payload source:
+
+### Core Configuration Types
+
+- **[All Commonly-Used Types](https://github.com/payloadcms/payload/blob/main/packages/payload/src/index.ts)** - Check here first for commonly used types and interfaces. All core types are exported from this file.
+
+### Database & Adapters
+
+- **[Database Adapter Types](https://github.com/payloadcms/payload/blob/main/packages/payload/src/database/types.ts)** - Base adapter interface
+- **[MongoDB Adapter](https://github.com/payloadcms/payload/blob/main/packages/db-mongodb/src/index.ts)** - MongoDB-specific options
+- **[Postgres Adapter](https://github.com/payloadcms/payload/blob/main/packages/db-postgres/src/index.ts)** - Postgres-specific options
+
+### Rich Text & Plugins
+
+- **[Lexical Types](https://github.com/payloadcms/payload/blob/main/packages/richtext-lexical/src/exports/server/index.ts)** - Lexical editor configuration
+
+When users need detailed type information, fetch these URLs to provide complete signatures and optional parameters.