payload-automation/MIGRATION-v0.0.24.md

Migration Guide: v0.0.23 → v0.0.24

What's New

Version 0.0.24 introduces trigger builder helpers that dramatically reduce boilerplate when creating custom triggers, plus fixes field name clashing between built-in and external trigger parameters.

Breaking Changes

None - This is a fully backward-compatible release. All existing triggers continue to work exactly as before.

New Features

1. Trigger Builder Helpers

New helper functions eliminate 90% of boilerplate when creating custom triggers:

npm update @xtr-dev/payload-automation

// Import the new helpers
import { 
  createTrigger, 
  webhookTrigger, 
  cronTrigger 
} from '@xtr-dev/payload-automation/helpers'

2. Fixed Field Name Clashing

Built-in trigger parameters now use a JSON backing store to prevent conflicts with custom trigger fields.

Migration Steps

Step 1: Update Package

npm install @xtr-dev/payload-automation@latest
# or
pnpm update @xtr-dev/payload-automation

Step 2: (Optional) Modernize Custom Triggers

Your existing triggers will continue to work, but you can optionally migrate to the cleaner syntax:

Before (Still Works)

const customTrigger = {
  slug: 'order-webhook',
  inputs: [
    {
      name: 'webhookSecret',
      type: 'text',
      required: true,
      virtual: true,
      admin: {
        condition: (_, siblingData) => siblingData?.type === 'order-webhook',
        description: 'Secret for webhook validation'
      },
      hooks: {
        afterRead: [({ siblingData }) => siblingData?.parameters?.webhookSecret],
        beforeChange: [({ value, siblingData }) => {
          if (!siblingData.parameters) siblingData.parameters = {}
          siblingData.parameters.webhookSecret = value
          return undefined
        }]
      }
    }
    // ... more boilerplate
  ]
}

After (Recommended)

import { createTrigger } from '@xtr-dev/payload-automation/helpers'

const orderWebhook = createTrigger('order-webhook').parameters({
  webhookSecret: {
    type: 'text',
    required: true,
    admin: {
      description: 'Secret for webhook validation'
    }
  }
  // Add more parameters easily
})

Step 3: (Optional) Use Preset Builders

For common trigger patterns:

import { webhookTrigger, cronTrigger } from '@xtr-dev/payload-automation/helpers'

// Webhook trigger with built-in path, secret, headers parameters
const paymentWebhook = webhookTrigger('payment-webhook')
  .parameter('currency', {
    type: 'select',
    options: ['USD', 'EUR', 'GBP']
  })
  .build()

// Cron trigger with built-in expression, timezone parameters  
const dailyReport = cronTrigger('daily-report')
  .parameter('format', {
    type: 'select',
    options: ['pdf', 'csv']
  })
  .build()

Quick Migration Examples

Simple Trigger Migration

// OLD WAY (still works)
{
  slug: 'user-signup',
  inputs: [/* 20+ lines of boilerplate per field */]
}

// NEW WAY (recommended)
import { createTrigger } from '@xtr-dev/payload-automation/helpers'

const userSignup = createTrigger('user-signup').parameters({
  source: {
    type: 'select',
    options: ['web', 'mobile', 'api'],
    required: true
  },
  userType: {
    type: 'select', 
    options: ['regular', 'premium'],
    defaultValue: 'regular'
  }
})

Webhook Trigger Migration

// OLD WAY
{
  slug: 'payment-webhook',
  inputs: [/* Manual webhookPath field + lots of boilerplate */]
}

// NEW WAY  
import { webhookTrigger } from '@xtr-dev/payload-automation/helpers'

const paymentWebhook = webhookTrigger('payment-webhook')
  .parameter('minimumAmount', { 
    type: 'number', 
    min: 0 
  })
  .build()

Benefits of Migration

• 90% less code - Eliminate virtual field boilerplate
• No field name conflicts - Built-in parameters isolated
• Better TypeScript support - Full type inference
• Preset patterns - Common trigger types ready-to-use
• Composable API - Easy to extend and customize

Compatibility

• ✅ Existing triggers continue to work unchanged
• ✅ Mix old and new trigger styles in same config
• ✅ No database changes required
• ✅ PayloadCMS field compatibility maintained

Need Help?

• View examples
• Read documentation
• Report issues

---

TL;DR: Update the package, optionally migrate custom triggers to use the new helpers for cleaner code. All existing triggers continue to work without changes.