@xtr-dev/payload-automation 0.0.43 → 0.0.46

package/README.md

@@ -2,47 +2,48 @@
 
 [![npm version](https://badge.fury.io/js/@xtr-dev%2Fpayload-automation.svg)](https://www.npmjs.com/package/@xtr-dev/payload-automation)
 
-A workflow automation plugin for PayloadCMS 3.x. Run steps in workflows triggered by document changes or webhooks.
+A workflow automation plugin for PayloadCMS 3.x. Build visual workflows triggered by document changes, webhooks, or manual execution.
 
-⚠️ **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
+> **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0.
 
 ## Features
 
-- 🔄 Visual workflow builder in PayloadCMS admin
-- ⚡ Run workflows when documents are created/updated/deleted
-- 🎯 Trigger workflows via webhooks
-- 📊 Track workflow execution history
-- 🔧 HTTP requests, document operations, email sending
-- 🔗 Use data from previous steps in templates
+- **Visual Workflow Builder** - Drag-and-drop workflow editor in PayloadCMS admin
+- **Workflow Visualizer** - React component for displaying workflows with real-time execution status
+- **Collection Triggers** - Run workflows when documents are created, updated, or deleted
+- **Webhook Triggers** - Trigger workflows via HTTP endpoints
+- **Step Dependencies** - Define execution order with parallel and sequential steps
+- **Execution Tracking** - Full history with step-by-step results, duration, and logs
+- **Built-in Steps** - HTTP requests, document CRUD, email sending
+- **Custom Steps** - Create your own step types with the step factory
+- **JSONata Expressions** - Powerful data transformation between steps
 
 ## Installation
 
 ```bash
-npm install @xtr-dev/payload-automation
-# or
 pnpm add @xtr-dev/payload-automation
 # or
-yarn add @xtr-dev/payload-automation
+npm install @xtr-dev/payload-automation
 ```
 
 ## Quick Start
 
 ```typescript
 import { buildConfig } from 'payload'
-import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
+import { workflowsPlugin } from '@xtr-dev/payload-automation'
 
 export default buildConfig({
-  // ... your config
   plugins: [
     workflowsPlugin({
+      enabled: true,
       collectionTriggers: {
-        posts: true,    // Enable all CRUD triggers for posts
-        users: { 
-          create: true, // Only enable create trigger for users
-          update: true
+        orders: true,  // Enable all hooks for orders
+        users: {
+          afterChange: true,  // Only specific hooks
         }
       },
-      enabled: true,
+      // Register custom steps
+      steps: [myCustomStep],
     }),
   ],
 })
@@ -51,8 +52,8 @@ export default buildConfig({
 ## Imports
 
 ```typescript
-// Server plugin
-import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
+// Main plugin
+import { workflowsPlugin } from '@xtr-dev/payload-automation'
 
 // Client components
 import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client'
@@ -75,11 +76,12 @@ const exampleWorkflows: SeedWorkflow[] = [
     description: 'Send email when user is created',
     triggers: [
       {
-        type: 'collection',
+        type: 'collection-hook',
         parameters: {
-          collection: 'users',
-          hook: 'afterCreate',
+          collectionSlug: 'users',
+          hook: 'afterChange',
         },
+        condition: 'trigger.operation = "create"',
       },
     ],
     steps: [
@@ -115,59 +117,229 @@ See [docs/SEEDING_WORKFLOWS.md](./docs/SEEDING_WORKFLOWS.md) for detailed docume
 ## Step Types
 
 ### HTTP Request
-Call external APIs. Supports GET, POST, PUT, DELETE, PATCH. Uses Bearer tokens, API keys, or basic auth.
+Call external APIs with full configuration:
+
+```typescript
+{
+  type: 'http-request-step',
+  config: {
+    url: 'https://api.example.com/webhook',
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{"orderId": "{{trigger.doc.id}}"}'
+  }
+}
+```
 
-HTTP steps succeed even with 4xx/5xx status codes. Only network errors (timeouts, DNS failures) cause step failure. Check `{{steps.stepName.output.status}}` for error handling.
+Supports GET, POST, PUT, DELETE, PATCH. Authentication via Bearer tokens, API keys, or basic auth.
 
 ### Document Operations
-- **Create Document** - Create PayloadCMS documents
+
+- **Create Document** - Create new PayloadCMS documents
 - **Read Document** - Query documents with filters
-- **Update Document** - Modify existing documents  
+- **Update Document** - Modify existing documents
 - **Delete Document** - Remove documents
 
-### Communication
-- **Send Email** - Send notifications via PayloadCMS email
+### Send Email
+Send notifications via PayloadCMS email adapter:
+
+```typescript
+{
+  type: 'send-email',
+  config: {
+    to: '{{trigger.doc.customer.email}}',
+    subject: 'Order Confirmed',
+    template: 'order-confirmation'
+  }
+}
+```
+
+## Custom Steps
+
+Create reusable step types with the `createStep` factory:
+
+```typescript
+import { createStep } from '@xtr-dev/payload-automation/steps'
+
+export const SlackNotificationStep = createStep({
+  slug: 'slack-notification',
+  label: 'Send Slack Message',
+
+  inputSchema: [
+    { name: 'channel', type: 'text', required: true },
+    { name: 'message', type: 'textarea', required: true },
+  ],
+
+  outputSchema: [
+    { name: 'messageId', type: 'text' },
+    { name: 'timestamp', type: 'text' },
+  ],
+
+  visual: {
+    icon: '💬',
+    color: '#4A154B',
+  },
+
+  validate: (input) => {
+    if (!input.channel?.startsWith('#')) {
+      throw new Error('Channel must start with #')
+    }
+  },
+
+  execute: async (input, req) => {
+    const response = await fetch('https://slack.com/api/chat.postMessage', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.SLACK_TOKEN}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        channel: input.channel,
+        text: input.message,
+      }),
+    })
+
+    const data = await response.json()
+    return {
+      messageId: data.message.ts,
+      timestamp: new Date().toISOString(),
+    }
+  },
+})
+```
+
+Register custom steps in the plugin config:
+
+```typescript
+workflowsPlugin({
+  steps: [SlackNotificationStep],
+})
+```
+
+## JSONata Expressions
+
+Use `{{expression}}` syntax for dynamic values. [JSONata](https://jsonata.org) provides powerful data transformation.
+
+### Available Context
+
+- `trigger.doc` - The document that triggered the workflow
+- `trigger.type` - Trigger type ('collection' | 'global')
+- `trigger.collection` - Collection slug for collection triggers
+- `steps.<stepName>.output` - Output from a completed step
+- `steps.<stepName>.state` - Step state ('succeeded' | 'failed' | 'pending' | 'skipped')
 
-## Templates
+### Examples
 
-Use `{{}}` to insert data:
+```javascript
+// Access trigger data
+{{trigger.doc.id}}
+{{trigger.doc.customer.email}}
 
-- `{{trigger.doc.id}}` - Data from the document that triggered the workflow  
-- `{{steps.stepName.output}}` - Data from previous steps
+// Use previous step output
+{{steps.createOrder.output.id}}
+{{steps.fetchUser.output.name}}
 
-Example:
-```json
+// Conditions (in step config)
+{{trigger.doc.status = 'published'}}
+{{trigger.doc.total > 100}}
+
+// String transformation
+{{$uppercase(trigger.doc.title)}}
+{{$join(trigger.doc.tags, ', ')}}
+
+// Object construction
 {
-  "url": "https://api.example.com/posts/{{steps.createPost.output.id}}",
-  "condition": "{{trigger.doc.status}} == 'published'"
+  "orderId": "{{trigger.doc.id}}",
+  "total": "{{$sum(trigger.doc.items.price)}}"
+}
+```
+
+### Custom Functions
+
+| Function | Description |
+|----------|-------------|
+| `$now()` | Current ISO timestamp |
+| `$uuid()` | Generate UUID v4 |
+| `$default(value, fallback)` | Return fallback if null |
+| `$coalesce(a, b, ...)` | First non-null value |
+| `$env('PUBLIC_*')` | Access PUBLIC_ env vars |
+
+## Execution Tracking
+
+All workflow executions are stored in the `workflow-runs` collection with:
+
+- Trigger data that initiated the run
+- Step-by-step results with status and duration
+- Execution logs with timestamps
+- Total duration and final status
+
+Query runs programmatically:
+
+```typescript
+const runs = await payload.find({
+  collection: 'workflow-runs',
+  where: {
+    workflow: { equals: workflowId },
+    status: { equals: 'completed' },
+  },
+  sort: '-createdAt',
+  limit: 10,
+})
+```
+
+## Plugin Configuration
+
+```typescript
+interface WorkflowsPluginConfig {
+  // Enable/disable the plugin
+  enabled?: boolean
+
+  // Collection triggers
+  collectionTriggers?: {
+    [collectionSlug: string]: boolean | {
+      afterChange?: boolean
+      afterDelete?: boolean
+      afterRead?: boolean
+      // ... other hooks
+    }
+  }
+
+  // Global triggers
+  globalTriggers?: {
+    [globalSlug: string]: boolean | { /* hooks */ }
+  }
+
+  // Custom step definitions
+  steps?: StepDefinition[]
 }
 ```
 
 ## Requirements
 
-- PayloadCMS ^3.45.0
+- PayloadCMS ^3.37.0
 - Node.js ^18.20.2 || >=20.9.0
-- pnpm ^9 || ^10
+- React 18+ (for client components)
 
 ## Logging
 
-Set `PAYLOAD_AUTOMATION_LOG_LEVEL` to control logs:
-- `silent`, `error`, `warn` (default), `info`, `debug`, `trace`
+Control log verbosity with `PAYLOAD_AUTOMATION_LOG_LEVEL`:
 
 ```bash
-PAYLOAD_AUTOMATION_LOG_LEVEL=debug npm run dev
+PAYLOAD_AUTOMATION_LOG_LEVEL=debug pnpm dev
 ```
 
-## Scheduled Workflows
+Levels: `silent` | `error` | `warn` (default) | `info` | `debug` | `trace`
 
-Use webhook triggers with external cron services:
+## Collections
 
-```bash
-# Call workflow webhook from cron
-curl -X POST https://your-app.com/api/workflows-webhook/daily-report
-```
+The plugin creates these collections:
 
-Built-in cron triggers were removed in v0.0.37+.
+| Collection | Slug | Description |
+|------------|------|-------------|
+| Triggers | `automation-triggers` | Reusable trigger definitions |
+| Steps | `automation-steps` | Step templates with configuration |
+| Workflows | `workflows` | Workflow definitions |
+| Workflow Runs | `workflow-runs` | Execution history |
 
 ## License
 

package/dist/collections/Steps.d.ts

@@ -0,0 +1,6 @@
+import type { CollectionConfig, TaskConfig } from 'payload';
+/**
+ * Creates the automation-steps collection.
+ * Steps are reusable building blocks that can be used across multiple workflows.
+ */
+export declare const createStepsCollection: (steps: TaskConfig<string>[]) => CollectionConfig;

package/dist/collections/Steps.js

@@ -0,0 +1,166 @@
+/**
+ * Creates the automation-steps collection.
+ * Steps are reusable building blocks that can be used across multiple workflows.
+ */ export const createStepsCollection = (steps)=>{
+    // Build step type options from registered steps
+    const stepTypeOptions = steps.map((step)=>({
+            label: step.label || step.slug,
+            value: step.slug
+        }));
+    return {
+        slug: 'automation-steps',
+        access: {
+            create: ()=>true,
+            delete: ()=>true,
+            read: ()=>true,
+            update: ()=>true
+        },
+        admin: {
+            defaultColumns: [
+                'name',
+                'type',
+                'updatedAt'
+            ],
+            description: 'Reusable step templates that can be used across workflows.',
+            group: 'Automation',
+            useAsTitle: 'name'
+        },
+        fields: [
+            {
+                name: 'name',
+                type: 'text',
+                admin: {
+                    description: 'Human-readable name for this step'
+                },
+                required: true
+            },
+            {
+                name: 'description',
+                type: 'textarea',
+                admin: {
+                    description: 'Optional description of what this step does'
+                }
+            },
+            {
+                name: 'type',
+                type: 'select',
+                admin: {
+                    description: 'The type of action this step performs'
+                },
+                options: stepTypeOptions,
+                required: true
+            },
+            // Step configuration
+            {
+                type: 'collapsible',
+                label: 'Configuration',
+                admin: {
+                    initCollapsed: false
+                },
+                fields: [
+                    {
+                        name: 'config',
+                        type: 'json',
+                        admin: {
+                            description: 'Step configuration in JSON format. String values can use JSONata expressions for dynamic data (e.g., "trigger.doc.id")'
+                        },
+                        defaultValue: {}
+                    }
+                ]
+            },
+            // Visual properties for workflow builder
+            {
+                type: 'collapsible',
+                label: 'Appearance',
+                admin: {
+                    initCollapsed: true
+                },
+                fields: [
+                    {
+                        name: 'color',
+                        type: 'text',
+                        admin: {
+                            description: 'Color for the step node in the visual builder (hex code)',
+                            placeholder: '#3b82f6'
+                        },
+                        defaultValue: '#3b82f6'
+                    },
+                    {
+                        name: 'icon',
+                        type: 'text',
+                        admin: {
+                            description: 'Icon name for the step (optional)'
+                        }
+                    }
+                ]
+            },
+            // Input validation schema (optional)
+            {
+                type: 'collapsible',
+                label: 'Advanced',
+                admin: {
+                    initCollapsed: true
+                },
+                fields: [
+                    {
+                        name: 'inputValidation',
+                        type: 'json',
+                        admin: {
+                            description: 'Optional JSON schema for validating step inputs'
+                        }
+                    },
+                    {
+                        name: 'retryOnFailure',
+                        type: 'checkbox',
+                        admin: {
+                            description: 'Retry this step if it fails'
+                        },
+                        defaultValue: false
+                    },
+                    {
+                        name: 'maxRetries',
+                        type: 'number',
+                        admin: {
+                            condition: (_, siblingData)=>siblingData?.retryOnFailure === true,
+                            description: 'Maximum number of retry attempts'
+                        },
+                        defaultValue: 3
+                    },
+                    {
+                        name: 'retryDelay',
+                        type: 'number',
+                        admin: {
+                            condition: (_, siblingData)=>siblingData?.retryOnFailure === true,
+                            description: 'Delay between retries in milliseconds'
+                        },
+                        defaultValue: 1000
+                    }
+                ]
+            },
+            // Usage tracking
+            {
+                name: 'usageCount',
+                type: 'number',
+                admin: {
+                    description: 'Number of workflows using this step',
+                    readOnly: true,
+                    position: 'sidebar'
+                },
+                defaultValue: 0
+            }
+        ],
+        hooks: {
+            beforeChange: [
+                // Validate that type is selected
+                async ({ data, operation })=>{
+                    if ((operation === 'create' || operation === 'update') && !data?.type) {
+                        throw new Error('Step type is required');
+                    }
+                    return data;
+                }
+            ]
+        }
+    };
+};
+
+//# sourceMappingURL=Steps.js.map

package/dist/collections/Steps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/collections/Steps.ts"],"sourcesContent":["import type { CollectionConfig, TaskConfig } from 'payload'\n\n/**\n * Creates the automation-steps collection.\n * Steps are reusable building blocks that can be used across multiple workflows.\n */\nexport const createStepsCollection = (\n  steps: TaskConfig<string>[]\n): CollectionConfig => {\n  // Build step type options from registered steps\n  const stepTypeOptions = steps.map(step => ({\n    label: step.label || step.slug,\n    value: step.slug,\n  }))\n\n  return {\n    slug: 'automation-steps',\n    access: {\n      create: () => true,\n      delete: () => true,\n      read: () => true,\n      update: () => true,\n    },\n    admin: {\n      defaultColumns: ['name', 'type', 'updatedAt'],\n      description: 'Reusable step templates that can be used across workflows.',\n      group: 'Automation',\n      useAsTitle: 'name',\n    },\n    fields: [\n      {\n        name: 'name',\n        type: 'text',\n        admin: {\n          description: 'Human-readable name for this step',\n        },\n        required: true,\n      },\n      {\n        name: 'description',\n        type: 'textarea',\n        admin: {\n          description: 'Optional description of what this step does',\n        },\n      },\n      {\n        name: 'type',\n        type: 'select',\n        admin: {\n          description: 'The type of action this step performs',\n        },\n        options: stepTypeOptions,\n        required: true,\n      },\n      // Step configuration\n      {\n        type: 'collapsible',\n        label: 'Configuration',\n        admin: {\n          initCollapsed: false,\n        },\n        fields: [\n          {\n            name: 'config',\n            type: 'json',\n            admin: {\n              description: 'Step configuration in JSON format. String values can use JSONata expressions for dynamic data (e.g., \"trigger.doc.id\")',\n            },\n            defaultValue: {},\n          },\n        ],\n      },\n      // Visual properties for workflow builder\n      {\n        type: 'collapsible',\n        label: 'Appearance',\n        admin: {\n          initCollapsed: true,\n        },\n        fields: [\n          {\n            name: 'color',\n            type: 'text',\n            admin: {\n              description: 'Color for the step node in the visual builder (hex code)',\n              placeholder: '#3b82f6',\n            },\n            defaultValue: '#3b82f6',\n          },\n          {\n            name: 'icon',\n            type: 'text',\n            admin: {\n              description: 'Icon name for the step (optional)',\n            },\n          },\n        ],\n      },\n      // Input validation schema (optional)\n      {\n        type: 'collapsible',\n        label: 'Advanced',\n        admin: {\n          initCollapsed: true,\n        },\n        fields: [\n          {\n            name: 'inputValidation',\n            type: 'json',\n            admin: {\n              description: 'Optional JSON schema for validating step inputs',\n            },\n          },\n          {\n            name: 'retryOnFailure',\n            type: 'checkbox',\n            admin: {\n              description: 'Retry this step if it fails',\n            },\n            defaultValue: false,\n          },\n          {\n            name: 'maxRetries',\n            type: 'number',\n            admin: {\n              condition: (_, siblingData) => siblingData?.retryOnFailure === true,\n              description: 'Maximum number of retry attempts',\n            },\n            defaultValue: 3,\n          },\n          {\n            name: 'retryDelay',\n            type: 'number',\n            admin: {\n              condition: (_, siblingData) => siblingData?.retryOnFailure === true,\n              description: 'Delay between retries in milliseconds',\n            },\n            defaultValue: 1000,\n          },\n        ],\n      },\n      // Usage tracking\n      {\n        name: 'usageCount',\n        type: 'number',\n        admin: {\n          description: 'Number of workflows using this step',\n          readOnly: true,\n          position: 'sidebar',\n        },\n        defaultValue: 0,\n      },\n    ],\n    hooks: {\n      beforeChange: [\n        // Validate that type is selected\n        async ({ data, operation }) => {\n          if ((operation === 'create' || operation === 'update') && !data?.type) {\n            throw new Error('Step type is required')\n          }\n          return data\n        }\n      ],\n    },\n  }\n}\n"],"names":["createStepsCollection","steps","stepTypeOptions","map","step","label","slug","value","access","create","delete","read","update","admin","defaultColumns","description","group","useAsTitle","fields","name","type","required","options","initCollapsed","defaultValue","placeholder","condition","_","siblingData","retryOnFailure","readOnly","position","hooks","beforeChange","data","operation","Error"],"mappings":"AAEA;;;CAGC,GACD,OAAO,MAAMA,wBAAwB,CACnCC;IAEA,gDAAgD;IAChD,MAAMC,kBAAkBD,MAAME,GAAG,CAACC,CAAAA,OAAS,CAAA;YACzCC,OAAOD,KAAKC,KAAK,IAAID,KAAKE,IAAI;YAC9BC,OAAOH,KAAKE,IAAI;QAClB,CAAA;IAEA,OAAO;QACLA,MAAM;QACNE,QAAQ;YACNC,QAAQ,IAAM;YACdC,QAAQ,IAAM;YACdC,MAAM,IAAM;YACZC,QAAQ,IAAM;QAChB;QACAC,OAAO;YACLC,gBAAgB;gBAAC;gBAAQ;gBAAQ;aAAY;YAC7CC,aAAa;YACbC,OAAO;YACPC,YAAY;QACd;QACAC,QAAQ;YACN;gBACEC,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;gBACf;gBACAM,UAAU;YACZ;YACA;gBACEF,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;gBACf;YACF;YACA;gBACEI,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;gBACf;gBACAO,SAASpB;gBACTmB,UAAU;YACZ;YACA,qBAAqB;YACrB;gBACED,MAAM;gBACNf,OAAO;gBACPQ,OAAO;oBACLU,eAAe;gBACjB;gBACAL,QAAQ;oBACN;wBACEC,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;wBACf;wBACAS,cAAc,CAAC;oBACjB;iBACD;YACH;YACA,yCAAyC;YACzC;gBACEJ,MAAM;gBACNf,OAAO;gBACPQ,OAAO;oBACLU,eAAe;gBACjB;gBACAL,QAAQ;oBACN;wBACEC,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;4BACbU,aAAa;wBACf;wBACAD,cAAc;oBAChB;oBACA;wBACEL,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;wBACf;oBACF;iBACD;YACH;YACA,qCAAqC;YACrC;gBACEK,MAAM;gBACNf,OAAO;gBACPQ,OAAO;oBACLU,eAAe;gBACjB;gBACAL,QAAQ;oBACN;wBACEC,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;wBACf;oBACF;oBACA;wBACEI,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;wBACf;wBACAS,cAAc;oBAChB;oBACA;wBACEL,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLa,WAAW,CAACC,GAAGC,cAAgBA,aAAaC,mBAAmB;4BAC/Dd,aAAa;wBACf;wBACAS,cAAc;oBAChB;oBACA;wBACEL,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLa,WAAW,CAACC,GAAGC,cAAgBA,aAAaC,mBAAmB;4BAC/Dd,aAAa;wBACf;wBACAS,cAAc;oBAChB;iBACD;YACH;YACA,iBAAiB;YACjB;gBACEL,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;oBACbe,UAAU;oBACVC,UAAU;gBACZ;gBACAP,cAAc;YAChB;SACD;QACDQ,OAAO;YACLC,cAAc;gBACZ,iCAAiC;gBACjC,OAAO,EAAEC,IAAI,EAAEC,SAAS,EAAE;oBACxB,IAAI,AAACA,CAAAA,cAAc,YAAYA,cAAc,QAAO,KAAM,CAACD,MAAMd,MAAM;wBACrE,MAAM,IAAIgB,MAAM;oBAClB;oBACA,OAAOF;gBACT;aACD;QACH;IACF;AACF,EAAC"}

package/dist/collections/Triggers.d.ts

@@ -0,0 +1,7 @@
+import type { CollectionConfig } from 'payload';
+import type { WorkflowsPluginConfig } from '../plugin/config-types.js';
+/**
+ * Creates the automation-triggers collection.
+ * Triggers are reusable and can be shared across multiple workflows.
+ */
+export declare const createTriggersCollection: <T extends string>(options: WorkflowsPluginConfig<T>) => CollectionConfig;