@xtr-dev/payload-automation 0.0.52 → 0.0.53

package/README.md

@@ -8,15 +8,13 @@ A workflow automation plugin for PayloadCMS 3.x. Build visual workflows triggere
 
 ## Features
 
-- **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
+- 🔄 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
+- ⚙️ Step dependencies with parallel and sequential execution
 
 ## Installation
 
@@ -30,20 +28,20 @@ npm install @xtr-dev/payload-automation
 
 ```typescript
 import { buildConfig } from 'payload'
-import { workflowsPlugin } from '@xtr-dev/payload-automation'
+import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
 
 export default buildConfig({
+  // ... your config
   plugins: [
     workflowsPlugin({
-      enabled: true,
       collectionTriggers: {
-        orders: true,  // Enable all hooks for orders
-        users: {
-          afterChange: true,  // Only specific hooks
+        posts: true,    // Enable all CRUD triggers for posts
+        users: { 
+          create: true, // Only enable create trigger for users
+          update: true
         }
       },
-      // Register custom steps
-      steps: [myCustomStep],
+      enabled: true,
     }),
   ],
 })
@@ -52,10 +50,10 @@ export default buildConfig({
 ## Imports
 
 ```typescript
-// Main plugin
-import { workflowsPlugin } from '@xtr-dev/payload-automation'
+// Server plugin
+import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
 
-// Client components
+// Client components  
 import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client'
 
 // Types
@@ -89,13 +87,80 @@ const exampleWorkflows: SeedWorkflow[] = [
         name: 'Send Email',
         type: 'send-email',
         input: {
-          to: '$.trigger.doc.email',
+          to: '{{trigger.doc.email}}',
           subject: 'Welcome!',
           text: 'Thanks for joining us!',
         },
       },
     ],
   },
+  {
+    slug: 'example-order-processing',
+    name: 'Example: Order Processing Pipeline',
+    description: 'Process order with validation, inventory check, and notifications',
+    triggers: [
+      {
+        type: 'collection-hook',
+        parameters: {
+          collectionSlug: 'orders',
+          hook: 'afterChange',
+        },
+        condition: 'trigger.operation = "create"',
+      },
+    ],
+    steps: [
+      {
+        name: 'Validate Order',
+        type: 'http-request-step',
+        input: {
+          url: 'https://api.example.com/validate',
+          method: 'POST',
+          body: {
+            orderId: '{{trigger.doc.id}}',
+            items: '{{trigger.doc.items}}',
+          },
+        },
+      },
+      {
+        name: 'Check Inventory',
+        type: 'http-request-step',
+        input: {
+          url: 'https://api.example.com/inventory/check',
+          method: 'POST',
+          body: {
+            items: '{{trigger.doc.items}}',
+          },
+        },
+        // This step runs only after Validate Order succeeds
+        dependencies: ['Validate Order'],
+      },
+      {
+        name: 'Create Shipment',
+        type: 'create-document',
+        input: {
+          collection: 'shipments',
+          data: {
+            orderId: '{{trigger.doc.id}}',
+            status: 'pending',
+            items: '{{trigger.doc.items}}',
+          },
+        },
+        // This step waits for both validation and inventory check
+        dependencies: ['Validate Order', 'Check Inventory'],
+      },
+      {
+        name: 'Send Confirmation Email',
+        type: 'send-email',
+        input: {
+          to: '{{trigger.doc.customer.email}}',
+          subject: 'Order Confirmed',
+          text: 'Your order {{trigger.doc.id}} has been confirmed!',
+        },
+        // Only send email after shipment is created
+        dependencies: ['Create Shipment'],
+      },
+    ],
+  },
 ]
 
 workflowsPlugin({
@@ -114,8 +179,73 @@ Seeded workflows:
 
 See [docs/SEEDING_WORKFLOWS.md](./docs/SEEDING_WORKFLOWS.md) for detailed documentation.
 
+## Step Dependencies
+
+Steps can declare dependencies on other steps to control execution order. The workflow executor uses topological sorting to determine the optimal execution order.
+
+### How Dependencies Work
+
+- **Parallel Execution**: Steps without dependencies run in parallel
+- **Sequential Execution**: Steps with dependencies wait for their dependencies to complete successfully
+- **Multiple Dependencies**: A step can depend on multiple other steps (all must succeed)
+- **Failure Handling**: If a dependency fails, the dependent step is skipped
+
+### Example: Parallel and Sequential Steps
+
+```typescript
+steps: [
+  {
+    name: 'Fetch User Data',
+    type: 'http-request-step',
+    // No dependencies - runs immediately
+  },
+  {
+    name: 'Fetch Order Data',
+    type: 'http-request-step',
+    // No dependencies - runs in parallel with Fetch User Data
+  },
+  {
+    name: 'Generate Report',
+    type: 'http-request-step',
+    dependencies: ['Fetch User Data', 'Fetch Order Data'],
+    // Waits for both API calls to complete
+    input: {
+      url: 'https://api.example.com/reports',
+      body: {
+        user: '{{steps.FetchUserData.output.user}}',
+        orders: '{{steps.FetchOrderData.output.orders}}',
+      },
+    },
+  },
+]
+```
+
+### Accessing Step Output
+
+Use `{{steps.<stepName>.output.<field>}}` to reference data from completed steps:
+
+```typescript
+{
+  name: 'Process Result',
+  type: 'create-document',
+  dependencies: ['API Call'],
+  input: {
+    collection: 'results',
+    data: {
+      // Access output from the "API Call" step
+      apiResponse: '{{steps.APICall.output.data}}',
+      status: '{{steps.APICall.output.status}}',
+    },
+  },
+}
+```
+
 ## Step Types
 
+> **Note:** Steps are just regular [PayloadCMS tasks](https://payloadcms.com/docs/jobs/overview). This plugin uses Payload's built-in job queue system, so you can leverage all of Payload's task features including retries, scheduling, and monitoring. Any `TaskConfig` you create is a valid step.
+
+The plugin comes with a few built-in step types found below.
+
 ### HTTP Request
 Call external APIs with full configuration:
 
@@ -156,12 +286,13 @@ Send notifications via PayloadCMS email adapter:
 
 ## Custom Steps
 
-Create reusable step types with the `createStep` factory:
+Steps are standard PayloadCMS tasks, so creating custom steps is just defining a `TaskConfig`. No proprietary APIs to learn:
 
 ```typescript
-import { createStep } from '@xtr-dev/payload-automation/steps'
+import type { TaskConfig } from 'payload'
 
-export const SlackNotificationStep = createStep({
+// Define the step configuration
+export const SlackNotificationStep: TaskConfig<'slack-notification'> = {
   slug: 'slack-notification',
   label: 'Send Slack Message',
 
@@ -175,42 +306,40 @@ export const SlackNotificationStep = createStep({
     { 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(),
+  handler: async ({ input, req }) => {
+    try {
+      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 {
+        output: {
+          messageId: data.message.ts,
+          timestamp: new Date().toISOString(),
+        },
+        state: 'succeeded'
+      }
+    } catch (error) {
+      return {
+        output: {},
+        state: 'failed',
+        errorMessage: error instanceof Error ? error.message : 'Unknown error'
+      }
     }
   },
-})
-```
-
-Register custom steps in the plugin config:
+}
 
-```typescript
+// Register in plugin config
 workflowsPlugin({
   steps: [SlackNotificationStep],
 })

package/dist/steps/index.d.ts

@@ -1,5 +1,3 @@
-export { createStep } from './create-step.js';
-export type { StepDefinition, StepTask } from './create-step.js';
 export { CreateDocumentStepTask } from './create-document.js';
 export { createDocumentHandler } from './create-document-handler.js';
 export { DeleteDocumentStepTask } from './delete-document.js';

package/dist/steps/index.js

@@ -1,5 +1,3 @@
-// Step factory for creating new steps
-export { createStep } from './create-step.js';
 // Built-in steps
 export { CreateDocumentStepTask } from './create-document.js';
 export { createDocumentHandler } from './create-document-handler.js';

package/dist/steps/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/steps/index.ts"],"sourcesContent":["// Step factory for creating new steps\nexport { createStep } from './create-step.js'\nexport type { StepDefinition, StepTask } from './create-step.js'\n\n// Built-in steps\nexport { CreateDocumentStepTask } from './create-document.js'\nexport { createDocumentHandler } from './create-document-handler.js'\nexport { DeleteDocumentStepTask } from './delete-document.js'\nexport { deleteDocumentHandler } from './delete-document-handler.js'\nexport { HttpRequestStepTask } from './http-request.js'\nexport { httpStepHandler } from './http-request-handler.js'\n\nexport { ReadDocumentStepTask } from './read-document.js'\nexport { readDocumentHandler } from './read-document-handler.js'\nexport { SendEmailStepTask } from './send-email.js'\nexport { sendEmailHandler } from './send-email-handler.js'\nexport { UpdateDocumentStepTask } from './update-document.js'\nexport { updateDocumentHandler } from './update-document-handler.js'\n"],"names":["createStep","CreateDocumentStepTask","createDocumentHandler","DeleteDocumentStepTask","deleteDocumentHandler","HttpRequestStepTask","httpStepHandler","ReadDocumentStepTask","readDocumentHandler","SendEmailStepTask","sendEmailHandler","UpdateDocumentStepTask","updateDocumentHandler"],"mappings":"AAAA,sCAAsC;AACtC,SAASA,UAAU,QAAQ,mBAAkB;AAG7C,iBAAiB;AACjB,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B;AACpE,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B;AACpE,SAASC,mBAAmB,QAAQ,oBAAmB;AACvD,SAASC,eAAe,QAAQ,4BAA2B;AAE3D,SAASC,oBAAoB,QAAQ,qBAAoB;AACzD,SAASC,mBAAmB,QAAQ,6BAA4B;AAChE,SAASC,iBAAiB,QAAQ,kBAAiB;AACnD,SAASC,gBAAgB,QAAQ,0BAAyB;AAC1D,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B"}
+{"version":3,"sources":["../../src/steps/index.ts"],"sourcesContent":["// Built-in steps\nexport { CreateDocumentStepTask } from './create-document.js'\nexport { createDocumentHandler } from './create-document-handler.js'\nexport { DeleteDocumentStepTask } from './delete-document.js'\nexport { deleteDocumentHandler } from './delete-document-handler.js'\nexport { HttpRequestStepTask } from './http-request.js'\nexport { httpStepHandler } from './http-request-handler.js'\n\nexport { ReadDocumentStepTask } from './read-document.js'\nexport { readDocumentHandler } from './read-document-handler.js'\nexport { SendEmailStepTask } from './send-email.js'\nexport { sendEmailHandler } from './send-email-handler.js'\nexport { UpdateDocumentStepTask } from './update-document.js'\nexport { updateDocumentHandler } from './update-document-handler.js'\n"],"names":["CreateDocumentStepTask","createDocumentHandler","DeleteDocumentStepTask","deleteDocumentHandler","HttpRequestStepTask","httpStepHandler","ReadDocumentStepTask","readDocumentHandler","SendEmailStepTask","sendEmailHandler","UpdateDocumentStepTask","updateDocumentHandler"],"mappings":"AAAA,iBAAiB;AACjB,SAASA,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B;AACpE,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B;AACpE,SAASC,mBAAmB,QAAQ,oBAAmB;AACvD,SAASC,eAAe,QAAQ,4BAA2B;AAE3D,SAASC,oBAAoB,QAAQ,qBAAoB;AACzD,SAASC,mBAAmB,QAAQ,6BAA4B;AAChE,SAASC,iBAAiB,QAAQ,kBAAiB;AACnD,SAASC,gBAAgB,QAAQ,0BAAyB;AAC1D,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,qBAAqB,QAAQ,+BAA8B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/payload-automation",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "description": "PayloadCMS Automation Plugin - Comprehensive workflow automation system with visual workflow building, execution tracking, and step types",
   "license": "MIT",
   "type": "module",

package/dist/steps/create-step.d.ts

@@ -1,66 +0,0 @@
-import type { Field, JsonObject, PayloadRequest, TaskConfig } from 'payload';
-/**
- * Configuration for creating a step with the factory.
- */
-export interface StepDefinition<TSlug extends string> {
-    /** Unique identifier for the step */
-    slug: TSlug;
-    /** Human-readable label for the step (optional, defaults to slug) */
-    label?: string;
-    /** Input fields schema */
-    inputSchema: Field[];
-    /** Output fields schema */
-    outputSchema: Field[];
-    /**
-     * Optional validation function. Throw an error if validation fails.
-     * Runs before the execute function.
-     */
-    validate?: (input: JsonObject) => void;
-    /**
-     * The main execution function for the step.
-     * Should return the output data on success, or throw an error on failure.
-     */
-    execute: (input: JsonObject, req: PayloadRequest) => Promise<JsonObject>;
-}
-/**
- * The result type returned by createStep.
- * Combines TaskConfig with the handler for convenience.
- */
-export type StepTask<TSlug extends string> = TaskConfig<TSlug>;
-/**
- * Creates a step definition that combines TaskConfig and handler in one place.
- *
- * This factory eliminates the need for separate `{step}.ts` and `{step}-handler.ts` files
- * by providing a single unified definition.
- *
- * @example
- * ```typescript
- * export const myStep = createStep({
- *   slug: 'my-step',
- *   inputSchema: [
- *     { name: 'url', type: 'text', required: true }
- *   ],
- *   outputSchema: [
- *     { name: 'result', type: 'json' }
- *   ],
- *   validate: (input) => {
- *     if (!input.url) throw new Error('URL is required')
- *   },
- *   execute: async (input, req) => {
- *     const response = await fetch(input.url)
- *     return { result: await response.json() }
- *   }
- * })
- * ```
- */
-export declare function createStep<TSlug extends string>(definition: StepDefinition<TSlug>): StepTask<TSlug>;
-/**
- * Helper type to extract input type from a step's inputSchema.
- * Note: This provides a basic type based on field names, not full type inference.
- */
-export type StepInput<T extends StepTask<string>> = T extends StepTask<infer _> ? Record<string, unknown> : never;
-/**
- * Helper type to extract output type from a step's outputSchema.
- * Note: This provides a basic type based on field names, not full type inference.
- */
-export type StepOutput<T extends StepTask<string>> = T extends StepTask<infer _> ? Record<string, unknown> : never;

package/dist/steps/create-step.js

@@ -1,59 +0,0 @@
-/**
- * Creates a step definition that combines TaskConfig and handler in one place.
- *
- * This factory eliminates the need for separate `{step}.ts` and `{step}-handler.ts` files
- * by providing a single unified definition.
- *
- * @example
- * ```typescript
- * export const myStep = createStep({
- *   slug: 'my-step',
- *   inputSchema: [
- *     { name: 'url', type: 'text', required: true }
- *   ],
- *   outputSchema: [
- *     { name: 'result', type: 'json' }
- *   ],
- *   validate: (input) => {
- *     if (!input.url) throw new Error('URL is required')
- *   },
- *   execute: async (input, req) => {
- *     const response = await fetch(input.url)
- *     return { result: await response.json() }
- *   }
- * })
- * ```
- */ export function createStep(definition) {
-    const { slug, label, inputSchema, outputSchema, validate, execute } = definition;
-    // Create the handler that wraps validation and execution
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const handler = async ({ input, req })=>{
-        try {
-            const jsonInput = input ?? {};
-            // Run validation if provided
-            if (validate) {
-                validate(jsonInput);
-            }
-            // Execute the step
-            const output = await execute(jsonInput, req);
-            return {
-                output,
-                state: 'succeeded'
-            };
-        } catch (error) {
-            return {
-                errorMessage: error instanceof Error ? error.message : 'Unknown error',
-                state: 'failed'
-            };
-        }
-    };
-    return {
-        slug,
-        label,
-        handler,
-        inputSchema,
-        outputSchema
-    };
-}
-
-//# sourceMappingURL=create-step.js.map

package/dist/steps/create-step.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/steps/create-step.ts"],"sourcesContent":["import type { Field, JsonObject, PayloadRequest, TaskConfig, TaskHandler } from 'payload'\n\n/**\n * Configuration for creating a step with the factory.\n */\nexport interface StepDefinition<TSlug extends string> {\n  /** Unique identifier for the step */\n  slug: TSlug\n  /** Human-readable label for the step (optional, defaults to slug) */\n  label?: string\n  /** Input fields schema */\n  inputSchema: Field[]\n  /** Output fields schema */\n  outputSchema: Field[]\n  /**\n   * Optional validation function. Throw an error if validation fails.\n   * Runs before the execute function.\n   */\n  validate?: (input: JsonObject) => void\n  /**\n   * The main execution function for the step.\n   * Should return the output data on success, or throw an error on failure.\n   */\n  execute: (input: JsonObject, req: PayloadRequest) => Promise<JsonObject>\n}\n\n/**\n * The result type returned by createStep.\n * Combines TaskConfig with the handler for convenience.\n */\nexport type StepTask<TSlug extends string> = TaskConfig<TSlug>\n\n/**\n * Creates a step definition that combines TaskConfig and handler in one place.\n *\n * This factory eliminates the need for separate `{step}.ts` and `{step}-handler.ts` files\n * by providing a single unified definition.\n *\n * @example\n * ```typescript\n * export const myStep = createStep({\n *   slug: 'my-step',\n *   inputSchema: [\n *     { name: 'url', type: 'text', required: true }\n *   ],\n *   outputSchema: [\n *     { name: 'result', type: 'json' }\n *   ],\n *   validate: (input) => {\n *     if (!input.url) throw new Error('URL is required')\n *   },\n *   execute: async (input, req) => {\n *     const response = await fetch(input.url)\n *     return { result: await response.json() }\n *   }\n * })\n * ```\n */\nexport function createStep<TSlug extends string>(\n  definition: StepDefinition<TSlug>\n): StepTask<TSlug> {\n  const { slug, label, inputSchema, outputSchema, validate, execute } = definition\n\n  // Create the handler that wraps validation and execution\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const handler = async ({ input, req }: any) => {\n    try {\n      const jsonInput = (input ?? {}) as JsonObject\n\n      // Run validation if provided\n      if (validate) {\n        validate(jsonInput)\n      }\n\n      // Execute the step\n      const output = await execute(jsonInput, req)\n      return {\n        output,\n        state: 'succeeded'\n      }\n    } catch (error) {\n      return {\n        errorMessage: error instanceof Error ? error.message : 'Unknown error',\n        state: 'failed'\n      }\n    }\n  }\n\n  return {\n    slug,\n    label,\n    handler,\n    inputSchema,\n    outputSchema\n  } as StepTask<TSlug>\n}\n\n/**\n * Helper type to extract input type from a step's inputSchema.\n * Note: This provides a basic type based on field names, not full type inference.\n */\nexport type StepInput<T extends StepTask<string>> = T extends StepTask<infer _>\n  ? Record<string, unknown>\n  : never\n\n/**\n * Helper type to extract output type from a step's outputSchema.\n * Note: This provides a basic type based on field names, not full type inference.\n */\nexport type StepOutput<T extends StepTask<string>> = T extends StepTask<infer _>\n  ? Record<string, unknown>\n  : never\n"],"names":["createStep","definition","slug","label","inputSchema","outputSchema","validate","execute","handler","input","req","jsonInput","output","state","error","errorMessage","Error","message"],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,SAASA,WACdC,UAAiC;IAEjC,MAAM,EAAEC,IAAI,EAAEC,KAAK,EAAEC,WAAW,EAAEC,YAAY,EAAEC,QAAQ,EAAEC,OAAO,EAAE,GAAGN;IAEtE,yDAAyD;IACzD,8DAA8D;IAC9D,MAAMO,UAAU,OAAO,EAAEC,KAAK,EAAEC,GAAG,EAAO;QACxC,IAAI;YACF,MAAMC,YAAaF,SAAS,CAAC;YAE7B,6BAA6B;YAC7B,IAAIH,UAAU;gBACZA,SAASK;YACX;YAEA,mBAAmB;YACnB,MAAMC,SAAS,MAAML,QAAQI,WAAWD;YACxC,OAAO;gBACLE;gBACAC,OAAO;YACT;QACF,EAAE,OAAOC,OAAO;YACd,OAAO;gBACLC,cAAcD,iBAAiBE,QAAQF,MAAMG,OAAO,GAAG;gBACvDJ,OAAO;YACT;QACF;IACF;IAEA,OAAO;QACLX;QACAC;QACAK;QACAJ;QACAC;IACF;AACF"}