Google Calendar Plugin for PayloadCMS

A comprehensive PayloadCMS plugin that provides two-way synchronization with Google Calendar, allowing users to manage calendar events directly within PayloadCMS with automatic sync to their Google Calendar accounts.

Features

• 🔄 Two-way synchronization between PayloadCMS and Google Calendar
• 🔐 OAuth2 authentication with Google Calendar API
• 📅 Multiple calendar support - sync with multiple Google Calendars
• ⚡ Real-time sync via webhooks (optional)
• 🕒 Scheduled sync with configurable intervals
• 🎯 Conflict resolution strategies (PayloadCMS wins, Google wins, newest wins)
• 📊 Sync logging and error tracking
• 🎨 Admin UI for managing calendar connections and settings
• 🔧 Flexible configuration options

Installation

npm install google-calendar-plugin
# or
yarn add google-calendar-plugin
# or
pnpm add google-calendar-plugin

Prerequisites

1. Google Cloud Project: Create a project in the Google Cloud Console
2. Enable Google Calendar API: Enable the Google Calendar API for your project
3. OAuth2 Credentials: Create OAuth2 credentials (Web application type)
4. Authorized Redirect URIs: Add your PayloadCMS domain + /api/google-calendar/callback

Configuration

1. Environment Variables

Add these environment variables to your .env file:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/google-calendar/callback

2. PayloadCMS Configuration

Add the plugin to your PayloadCMS config:

import { googleCalendarPlugin } from 'google-calendar-plugin'

export default buildConfig({
  // ... your existing config
  plugins: [
    googleCalendarPlugin({
      googleOAuth: {
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        redirectUri: process.env.GOOGLE_REDIRECT_URI!,
      },
      // Optional: Add calendar event relationship to existing collections
      collections: ['posts', 'events'], // Add googleCalendarEvent field to these collections
      // Optional: Configure sync interval (default: 15 minutes)
      syncInterval: 15,
      // Optional: Enable webhooks for real-time sync
      enableWebhooks: true,
      webhookDomain: 'https://yourdomain.com', // Required if enableWebhooks is true
    }),
  ],
})

Usage

1. Connect Google Calendar

1. Navigate to your PayloadCMS admin dashboard
2. You'll see a "Google Calendar Integration" section
3. Click "Connect Google Calendar"
4. Authorize the application in the popup window
5. Your calendars will be automatically synced

2. Manage Calendar Settings

• Enable/Disable Sync: Toggle synchronization for individual calendars
• Sync Direction: Choose between bidirectional, to Google only, or from Google only
• Conflict Resolution: Set how conflicts are resolved when the same event is modified in both systems
• Sync Interval: Configure how often automatic sync occurs

3. Create and Edit Events

• Create events in the "Calendar Events" collection
• Events are automatically synced to Google Calendar based on your settings
• Edit events in PayloadCMS and changes sync to Google Calendar
• Events created in Google Calendar sync back to PayloadCMS

4. Link Events to Other Collections

If you configured the collections option, you can link calendar events to other content:

// Example: Link a blog post to a calendar event
{
  title: "My Blog Post",
  content: "...",
  googleCalendarEvent: "event_id_here" // Relationship field added by plugin
}

API Endpoints

The plugin adds several API endpoints:

• GET /api/google-calendar/auth - Get OAuth authorization URL
• GET /api/google-calendar/callback - OAuth callback handler
• GET /api/google-calendar/status - Check connection status
• POST /api/google-calendar/sync/calendars - Manually sync calendars
• POST /api/google-calendar/sync/events?calendarId=xxx - Sync events for specific calendar
• POST /api/google-calendar/sync/all - Sync all calendars and events
• POST /api/google-calendar/webhook - Webhook endpoint for real-time sync

Collections Added

The plugin adds these collections to your PayloadCMS:

Calendar Events

• Slug: calendar-events
• Purpose: Store calendar events with Google Calendar sync
• Fields: Title, description, location, start/end times, attendees, recurrence, etc.

Google Calendars

• Slug: google-calendars
• Purpose: Store Google Calendar configurations and sync settings
• Fields: Calendar name, colors, sync settings, last sync time, etc.

Google Auth Tokens

• Slug: google-auth-tokens
• Purpose: Store encrypted OAuth tokens for users
• Fields: Access token, refresh token, expiration, scopes

Sync Logs

• Slug: sync-logs
• Purpose: Track synchronization operations and errors
• Fields: Action type, status, error messages, timestamps

Calendar Sync Settings

• Slug: calendar-sync-settings
• Purpose: User-specific sync preferences
• Fields: Sync direction, conflict resolution, intervals, notifications

Webhook Notifications

• Slug: webhook-notifications
• Purpose: Track Google Calendar webhook notifications
• Fields: Notification data, processing status, timestamps

Configuration Options

interface GoogleCalendarPluginConfig {
  // Google OAuth2 configuration (required)
  googleOAuth?: {
    clientId: string
    clientSecret: string
    redirectUri: string
  }

  // Collections to add calendar event relationships to
  collections?: string[]

  // Sync interval in minutes (default: 15)
  syncInterval?: number

  // Enable webhook support for real-time sync
  enableWebhooks?: boolean

  // Webhook domain for Google Calendar notifications
  webhookDomain?: string

  // Disable the plugin
  disabled?: boolean
}

Webhook Setup (Optional)

For real-time synchronization, you can enable webhooks:

1. Set enableWebhooks: true in plugin config
2. Provide your public domain in webhookDomain
3. Ensure your server is accessible from the internet
4. Google will send notifications to /api/google-calendar/webhook

Security Considerations

• OAuth tokens are stored encrypted in the database
• All API endpoints require user authentication
• Users can only access their own calendar data
• Webhook endpoints validate Google's signatures
• Sensitive token data is hidden in the admin UI

Troubleshooting

Common Issues

1. "OAuth configuration not provided"

   • Ensure all Google OAuth environment variables are set
   • Check that the plugin configuration includes googleOAuth settings

2. "Failed to connect Google Calendar"

   • Verify your Google Cloud project has Calendar API enabled
   • Check that OAuth credentials are correctly configured
   • Ensure redirect URI matches exactly (including protocol and port)

3. "Sync not working"

   • Check sync logs in the admin panel
   • Verify calendar sync is enabled for specific calendars
   • Check user sync settings and permissions

4. "Webhook notifications not received"

   • Ensure your server is publicly accessible
   • Check that webhookDomain is correctly configured
   • Verify Google Calendar API quotas

Debug Mode

Enable debug logging by setting:

DEBUG=google-calendar-plugin:*

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

MIT License - see LICENSE file for details.

Support

For support, please:

1. Check the troubleshooting section above
2. Search existing GitHub issues
3. Create a new issue with detailed information about your problem

Changelog

v1.0.0

• Initial release
• Two-way Google Calendar synchronization
• OAuth2 authentication
• Real-time webhook support
• Configurable sync settings
• Admin UI for calendar management