New Integration: Payload CMS

Description

Add Payload CMS integration to sync collections, documents, media, and content changes into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - REST API + OAuth pattern
• integrations/intercom/ - Schedule-based sync with cursor pagination
• integrations/linear/ - Content/project data sync reference

Required Files Structure

integrations/payload-cms/
├── src/
│   ├── index.ts          # Main entry, auth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Payload API utilities
│   ├── account-create.ts # Auth setup (API key or OAuth)
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Payload CMS API Integration

Auth Setup

• Payload supports both API Key and email/password (JWT) authentication
• Prefer API Key auth for integrations (simpler, no expiry management)
• Auth header: Authorization: <api-key> or Bearer <jwt>
• Base URL: user-configurable (self-hosted), e.g. https://your-payload-instance.com

Key Endpoints

• GET /api/{collection-slug} - List documents in a collection
• GET /api/{collection-slug}/{id} - Get a specific document
• POST /api/{collection-slug} - Create a document
• GET /api/globals/{global-slug} - Get global data
• GET /api/{collection-slug}/versions - List document versions
• GET /api/media - List media files

Data to Sync

1. Collections - All configured collections and their documents
2. Globals - Global singleton data (site config, settings)
3. Media - Uploaded files and media metadata
4. Versions - Document version history and draft states
5. Changes - Create, update, delete events across collections

Implementation Tasks

• Set up basic integration structure following existing integration patterns
• Implement API Key auth flow in account-create.ts with configurable base URL
• Create API utilities in utils.ts with Payload REST client
• Implement sync logic in schedule.ts to poll collections for changes
• Convert Payload document events to CORE activity format
• Handle dynamic collection schemas (fetch schema at runtime)
• Add error handling and pagination (Payload uses limit/page params)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Use IntegrationDefinitionV2 registration pattern — no v1 auth fields
• Base URL is user-defined (self-hosted); must be stored in account config
• Payload REST API is auto-generated from collection configs — schema is dynamic
• Pagination: ?limit=100&page=1 with totalDocs, totalPages in response
• Versions endpoint available only if versions: true in collection config
• Webhooks available in Payload for real-time events (optional enhancement)
• Depth parameter ?depth=2 controls relationship population

Resources

• Payload REST API Docs
• Payload Authentication
• Payload Versions
• Payload Webhooks
• Payload GitHub

Labels

enhancement, integration, new-feature, new-integration