@open-mercato/core 0.4.2-canary-968c919ed2 → 0.4.2-canary-f821f89ef6

package/src/modules/workflows/data/entities.ts

@@ -46,6 +46,63 @@ export type UserTaskStatus =
   | 'CANCELLED'
   | 'ESCALATED'
 
+// ============================================================================
+// Event Trigger Types
+// ============================================================================
+
+export type TriggerFilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'startsWith'
+  | 'endsWith'
+  | 'in'
+  | 'notIn'
+  | 'exists'
+  | 'notExists'
+  | 'regex'
+
+export interface TriggerFilterCondition {
+  field: string // JSON path (e.g., "status", "metadata.type")
+  operator: TriggerFilterOperator
+  value: unknown
+}
+
+export interface TriggerContextMapping {
+  targetKey: string // Key in workflow initial context
+  sourceExpression: string // Path from event payload (supports dot notation)
+  defaultValue?: unknown
+}
+
+export interface WorkflowEventTriggerConfig {
+  filterConditions?: TriggerFilterCondition[]
+  contextMapping?: TriggerContextMapping[]
+  debounceMs?: number // Debounce rapid events
+  maxConcurrentInstances?: number // Limit concurrent instances
+  entityType?: string // Entity type for workflow instance metadata (e.g., "SalesOrder")
+}
+
+/**
+ * WorkflowDefinitionTrigger - Embedded trigger configuration
+ *
+ * Triggers are now embedded directly in the workflow definition,
+ * allowing users to configure event-based workflow starts during
+ * workflow creation in the visual editor.
+ */
+export interface WorkflowDefinitionTrigger {
+  triggerId: string
+  name: string
+  description?: string | null
+  eventPattern: string // e.g., "sales.orders.created", "customers.*"
+  config?: WorkflowEventTriggerConfig | null
+  enabled: boolean
+  priority: number
+}
+
 // ============================================================================
 // JSONB Structure Interfaces
 // ============================================================================
@@ -53,6 +110,7 @@ export type UserTaskStatus =
 export interface WorkflowDefinitionData {
   steps: any[] // WorkflowStep[] - will define schema in validators.ts
   transitions: any[] // WorkflowTransition[] - will define schema in validators.ts
+  triggers?: WorkflowDefinitionTrigger[] // Event triggers for automatic workflow start
   activities?: any[] // ActivityDefinition[] - will define schema in validators.ts
   queries?: any[]
   signals?: any[]
@@ -429,6 +487,71 @@ export class WorkflowEvent {
   organizationId!: string
 }
 
+// ============================================================================
+// Entity: WorkflowEventTrigger
+// ============================================================================
+
+/**
+ * WorkflowEventTrigger entity
+ *
+ * Maps event patterns to workflow definitions for automatic triggering.
+ * When a matching event is emitted, the corresponding workflow is started
+ * with context mapped from the event payload.
+ */
+@Entity({ tableName: 'workflow_event_triggers' })
+@Index({ name: 'workflow_event_triggers_event_pattern_idx', properties: ['eventPattern', 'enabled'] })
+@Index({ name: 'workflow_event_triggers_definition_idx', properties: ['workflowDefinitionId'] })
+@Index({ name: 'workflow_event_triggers_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'workflow_event_triggers_enabled_priority_idx', properties: ['enabled', 'priority'] })
+export class WorkflowEventTrigger {
+  [OptionalProps]?: 'enabled' | 'priority' | 'createdAt' | 'updatedAt' | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'name', type: 'varchar', length: 255 })
+  name!: string
+
+  @Property({ name: 'description', type: 'text', nullable: true })
+  description?: string | null
+
+  @Property({ name: 'workflow_definition_id', type: 'uuid' })
+  workflowDefinitionId!: string
+
+  @Property({ name: 'event_pattern', type: 'varchar', length: 255 })
+  eventPattern!: string
+
+  @Property({ name: 'config', type: 'jsonb', nullable: true })
+  config?: WorkflowEventTriggerConfig | null
+
+  @Property({ name: 'enabled', type: 'boolean', default: true })
+  enabled: boolean = true
+
+  @Property({ name: 'priority', type: 'integer', default: 0 })
+  priority: number = 0
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'created_by', type: 'varchar', length: 255, nullable: true })
+  createdBy?: string | null
+
+  @Property({ name: 'updated_by', type: 'varchar', length: 255, nullable: true })
+  updatedBy?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
 // Export all entities as default for MikroORM discovery
 export default [
   WorkflowDefinition,
@@ -436,4 +559,5 @@ export default [
   StepInstance,
   UserTask,
   WorkflowEvent,
+  WorkflowEventTrigger,
 ]

package/src/modules/workflows/data/validators.ts

@@ -215,10 +215,43 @@ export const workflowTransitionSchema = z.object({
   priority: z.number().int().min(0).max(9999).default(0),
 })
 
+// Workflow definition trigger schema (embedded in definition)
+// Note: Uses forward reference pattern since eventPatternSchema and eventTriggerConfigSchema are defined later
+export const workflowDefinitionTriggerSchema = z.object({
+  triggerId: z.string().min(1).max(100).regex(/^[a-z0-9_-]+$/, 'Trigger ID must contain only lowercase letters, numbers, hyphens, and underscores'),
+  name: z.string().min(1).max(255),
+  description: z.string().max(2000).optional().nullable(),
+  eventPattern: z.string()
+    .min(1, 'Event pattern is required')
+    .max(255, 'Event pattern must be at most 255 characters')
+    .regex(
+      /^(\*|[a-z0-9_]+(\.[a-z0-9_*]+)*)$/i,
+      'Event pattern must be "*" or a dot-separated pattern with optional wildcards (e.g., "customers.people.created", "sales.orders.*")'
+    ),
+  config: z.object({
+    filterConditions: z.array(z.object({
+      field: z.string().min(1).max(255),
+      operator: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'exists', 'notExists', 'regex']),
+      value: z.any(),
+    })).max(20).optional(),
+    contextMapping: z.array(z.object({
+      targetKey: z.string().min(1).max(100),
+      sourceExpression: z.string().min(1).max(255),
+      defaultValue: z.any().optional(),
+    })).max(50).optional(),
+    debounceMs: z.number().int().min(0).max(3600000).optional(),
+    maxConcurrentInstances: z.number().int().min(1).max(1000).optional(),
+  }).optional().nullable(),
+  enabled: z.boolean().default(true),
+  priority: z.number().int().min(0).max(9999).default(0),
+})
+export type WorkflowDefinitionTrigger = z.infer<typeof workflowDefinitionTriggerSchema>
+
 // Workflow definition data (JSONB structure)
 export const workflowDefinitionDataSchema = z.object({
   steps: z.array(workflowStepSchema).min(2, 'Workflow must have at least START and END steps'),
   transitions: z.array(workflowTransitionSchema).min(1, 'Workflow must have at least one transition'),
+  triggers: z.array(workflowDefinitionTriggerSchema).optional(), // Event triggers for automatic workflow start
   queries: z.array(z.any()).optional(), // For Phase 7
   signals: z.array(z.any()).optional(), // For Phase 9
   timers: z.array(z.any()).optional(), // For Phase 9
@@ -488,3 +521,108 @@ export const startWorkflowInputSchema = z.object({
 })
 
 export type StartWorkflowApiInput = z.infer<typeof startWorkflowInputSchema>
+
+// ============================================================================
+// WorkflowEventTrigger Schemas
+// ============================================================================
+
+export const triggerFilterOperatorSchema = z.enum([
+  'eq',
+  'neq',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'contains',
+  'startsWith',
+  'endsWith',
+  'in',
+  'notIn',
+  'exists',
+  'notExists',
+  'regex',
+])
+export type TriggerFilterOperator = z.infer<typeof triggerFilterOperatorSchema>
+
+export const triggerFilterConditionSchema = z.object({
+  field: z.string().min(1).max(255, 'Field path must be at most 255 characters'),
+  operator: triggerFilterOperatorSchema,
+  value: z.any(),
+})
+export type TriggerFilterCondition = z.infer<typeof triggerFilterConditionSchema>
+
+export const triggerContextMappingSchema = z.object({
+  targetKey: z.string().min(1).max(100, 'Target key must be at most 100 characters'),
+  sourceExpression: z.string().min(1).max(255, 'Source expression must be at most 255 characters'),
+  defaultValue: z.any().optional(),
+})
+export type TriggerContextMapping = z.infer<typeof triggerContextMappingSchema>
+
+export const eventTriggerConfigSchema = z.object({
+  filterConditions: z.array(triggerFilterConditionSchema).max(20, 'Maximum 20 filter conditions allowed').optional(),
+  contextMapping: z.array(triggerContextMappingSchema).max(50, 'Maximum 50 context mappings allowed').optional(),
+  debounceMs: z.number().int().min(0).max(3600000, 'Debounce cannot exceed 1 hour').optional(),
+  maxConcurrentInstances: z.number().int().min(1).max(1000, 'Max concurrent instances must be between 1 and 1000').optional(),
+})
+export type EventTriggerConfig = z.infer<typeof eventTriggerConfigSchema>
+
+export const eventPatternSchema = z.string()
+  .min(1, 'Event pattern is required')
+  .max(255, 'Event pattern must be at most 255 characters')
+  .regex(
+    /^(\*|[a-z0-9_]+(\.[a-z0-9_*]+)*)$/i,
+    'Event pattern must be "*" or a dot-separated pattern with optional wildcards (e.g., "customers.people.created", "sales.orders.*")'
+  )
+
+export const createEventTriggerSchema = z.object({
+  name: z.string().min(1).max(255),
+  description: z.string().max(2000).optional().nullable(),
+  workflowDefinitionId: uuid,
+  eventPattern: eventPatternSchema,
+  config: eventTriggerConfigSchema.optional().nullable(),
+  enabled: z.boolean().default(true),
+  priority: z.number().int().min(0).max(9999).default(0),
+  tenantId: uuid,
+  organizationId: uuid,
+  createdBy: z.string().max(255).optional().nullable(),
+})
+export type CreateEventTriggerInput = z.infer<typeof createEventTriggerSchema>
+
+// API input schema (omits tenant fields - injected from auth context)
+export const createEventTriggerInputSchema = z.object({
+  name: z.string().min(1).max(255),
+  description: z.string().max(2000).optional().nullable(),
+  workflowDefinitionId: uuid,
+  eventPattern: eventPatternSchema,
+  config: eventTriggerConfigSchema.optional().nullable(),
+  enabled: z.boolean().default(true).optional(),
+  priority: z.number().int().min(0).max(9999).default(0).optional(),
+})
+export type CreateEventTriggerApiInput = z.infer<typeof createEventTriggerInputSchema>
+
+export const updateEventTriggerSchema = createEventTriggerSchema.partial().extend({
+  id: uuid,
+})
+export type UpdateEventTriggerInput = z.infer<typeof updateEventTriggerSchema>
+
+// API update schema (omits tenant fields and allows partial updates)
+export const updateEventTriggerInputSchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  description: z.string().max(2000).optional().nullable(),
+  workflowDefinitionId: uuid.optional(),
+  eventPattern: eventPatternSchema.optional(),
+  config: eventTriggerConfigSchema.optional().nullable(),
+  enabled: z.boolean().optional(),
+  priority: z.number().int().min(0).max(9999).optional(),
+}).strict()
+export type UpdateEventTriggerApiInput = z.infer<typeof updateEventTriggerInputSchema>
+
+export const eventTriggerFilterSchema = z.object({
+  name: z.string().optional(),
+  workflowDefinitionId: uuid.optional(),
+  eventPattern: z.string().optional(),
+  enabled: z.boolean().optional(),
+  tenantId: uuid.optional(),
+  organizationId: uuid.optional(),
+})
+export type EventTriggerFilter = z.infer<typeof eventTriggerFilterSchema>

package/src/modules/workflows/events.ts

@@ -0,0 +1,49 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+/**
+ * Workflows Module Events
+ *
+ * Declares all events that can be emitted by the workflows module.
+ */
+const events = [
+  // Workflow Definitions
+  { id: 'workflows.definitions.created', label: 'Workflow Definition Created', entity: 'definitions', category: 'crud' },
+  { id: 'workflows.definitions.updated', label: 'Workflow Definition Updated', entity: 'definitions', category: 'crud' },
+  { id: 'workflows.definitions.deleted', label: 'Workflow Definition Deleted', entity: 'definitions', category: 'crud' },
+
+  // Workflow Instances
+  { id: 'workflows.instances.created', label: 'Workflow Instance Created', entity: 'instances', category: 'crud' },
+  { id: 'workflows.instances.updated', label: 'Workflow Instance Updated', entity: 'instances', category: 'crud' },
+  { id: 'workflows.instances.deleted', label: 'Workflow Instance Deleted', entity: 'instances', category: 'crud' },
+
+  // Workflow Lifecycle Events
+  { id: 'workflows.instance.started', label: 'Workflow Started', category: 'lifecycle' },
+  { id: 'workflows.instance.completed', label: 'Workflow Completed', category: 'lifecycle' },
+  { id: 'workflows.instance.failed', label: 'Workflow Failed', category: 'lifecycle' },
+  { id: 'workflows.instance.cancelled', label: 'Workflow Cancelled', category: 'lifecycle' },
+  { id: 'workflows.instance.paused', label: 'Workflow Paused', category: 'lifecycle' },
+  { id: 'workflows.instance.resumed', label: 'Workflow Resumed', category: 'lifecycle' },
+
+  // Activity Events
+  { id: 'workflows.activity.started', label: 'Activity Started', category: 'lifecycle' },
+  { id: 'workflows.activity.completed', label: 'Activity Completed', category: 'lifecycle' },
+  { id: 'workflows.activity.failed', label: 'Activity Failed', category: 'lifecycle' },
+
+  // Event Triggers
+  { id: 'workflows.triggers.created', label: 'Trigger Created', entity: 'triggers', category: 'crud' },
+  { id: 'workflows.triggers.updated', label: 'Trigger Updated', entity: 'triggers', category: 'crud' },
+  { id: 'workflows.triggers.deleted', label: 'Trigger Deleted', entity: 'triggers', category: 'crud' },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'workflows',
+  events,
+})
+
+/** Type-safe event emitter for workflows module */
+export const emitWorkflowsEvent = eventsConfig.emit
+
+/** Event IDs that can be emitted by the workflows module */
+export type WorkflowsEventId = typeof events[number]['id']
+
+export default eventsConfig

package/src/modules/workflows/examples/checkout-demo-definition.json

@@ -137,11 +137,7 @@
         "priority": 100,
         "preConditions": [
           {
-            "ruleId": "cart_not_empty",
-            "required": true
-          },
-          {
-            "ruleId": "inventory_available",
+            "ruleId": "workflow_checkout_cart_not_empty",
             "required": true
           }
         ],

package/src/modules/workflows/examples/order-approval-definition.json

@@ -0,0 +1,257 @@
+{
+  "workflowId": "sales_order_approval_v1",
+  "workflowName": "Sales Order Approval Workflow",
+  "description": "Approval workflow for sales orders requiring authorization before processing",
+  "version": 1,
+  "enabled": true,
+  "metadata": {
+    "category": "Sales",
+    "tags": [
+      "sales",
+      "approval",
+      "order"
+    ],
+    "icon": "check-circle",
+    "entityType": "SalesOrder"
+  },
+  "definition": {
+    "steps": [
+      {
+        "stepId": "start",
+        "stepName": "Start",
+        "stepType": "START",
+        "description": "Initialize order approval workflow"
+      },
+      {
+        "stepId": "pending_approval",
+        "stepName": "Pending Approval",
+        "stepType": "USER_TASK",
+        "description": "Order awaiting approval decision",
+        "userTaskConfig": {
+          "formSchema": {
+            "type": "object",
+            "required": [
+              "decision"
+            ],
+            "properties": {
+              "comments": {
+                "type": "string",
+                "title": "Comments",
+                "description": "Optional comments for the decision"
+              },
+              "decision": {
+                "enum": [
+                  "approve",
+                  "reject"
+                ],
+                "type": "string",
+                "title": "Decision",
+                "description": "Approve or reject the order"
+              }
+            }
+          },
+          "slaDuration": "PT24H"
+        }
+      },
+      {
+        "stepId": "approved",
+        "stepName": "Approved",
+        "stepType": "AUTOMATED",
+        "description": "Order has been approved"
+      },
+      {
+        "stepId": "rejected",
+        "stepName": "Rejected",
+        "stepType": "AUTOMATED",
+        "description": "Order has been rejected"
+      },
+      {
+        "stepId": "end",
+        "stepName": "Complete",
+        "stepType": "END",
+        "description": "Workflow complete"
+      }
+    ],
+    "triggers": [
+      {
+        "name": "Order Approval Trigger",
+        "config": {
+          "entityType": "SalesOrder"
+        },
+        "enabled": true,
+        "priority": 0,
+        "triggerId": "order_approval_trigger",
+        "description": "Triggers when a new sales order is created",
+        "eventPattern": "sales.orders.created"
+      }
+    ],
+    "transitions": [
+      {
+        "transitionId": "start_to_pending",
+        "transitionName": "Submit for Approval",
+        "fromStepId": "start",
+        "toStepId": "pending_approval",
+        "trigger": "auto",
+        "priority": 100,
+        "continueOnActivityFailure": true,
+        "activities": [
+          {
+            "activityId": "set_pending_status",
+            "activityName": "Set Order to Pending Approval",
+            "activityType": "UPDATE_ENTITY",
+            "async": false,
+            "config": {
+              "commandId": "sales.orders.update",
+              "statusDictionary": "sales.order_status",
+              "input": {
+                "id": "{{context.id}}",
+                "statusValue": "pending_approval"
+              }
+            },
+            "retryPolicy": {
+              "maxAttempts": 3,
+              "initialIntervalMs": 1000,
+              "backoffCoefficient": 2,
+              "maxIntervalMs": 10000
+            }
+          },
+          {
+            "activityId": "emit_approval_requested",
+            "activityName": "Emit Approval Requested Event",
+            "activityType": "EMIT_EVENT",
+            "async": true,
+            "config": {
+              "eventName": "sales.order.approval.requested",
+              "payload": {
+                "orderId": "{{context.id}}",
+                "workflowInstanceId": "{{workflow.instanceId}}"
+              }
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "pending_approval_to_approved",
+        "transitionName": "Approve Order",
+        "fromStepId": "pending_approval",
+        "toStepId": "approved",
+        "trigger": "auto",
+        "priority": 100,
+        "preConditions": [
+          {
+            "ruleId": "workflow_order_approval_check_approved",
+            "required": true
+          }
+        ],
+        "continueOnActivityFailure": true,
+        "activities": [
+          {
+            "activityId": "set_approved_status",
+            "activityName": "Set Order to Approved",
+            "activityType": "UPDATE_ENTITY",
+            "async": false,
+            "config": {
+              "commandId": "sales.orders.update",
+              "statusDictionary": "sales.order_status",
+              "input": {
+                "id": "{{context.id}}",
+                "statusValue": "approved"
+              }
+            },
+            "retryPolicy": {
+              "maxAttempts": 3,
+              "initialIntervalMs": 1000,
+              "backoffCoefficient": 2,
+              "maxIntervalMs": 10000
+            }
+          },
+          {
+            "activityId": "emit_order_approved",
+            "activityName": "Emit Order Approved Event",
+            "activityType": "EMIT_EVENT",
+            "async": true,
+            "config": {
+              "eventName": "sales.order.approval.approved",
+              "payload": {
+                "orderId": "{{context.id}}",
+                "workflowInstanceId": "{{workflow.instanceId}}",
+                "approvedBy": "{{context.completedBy}}",
+                "comments": "{{context.comments}}"
+              }
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "pending_approval_to_rejected",
+        "transitionName": "Reject Order",
+        "fromStepId": "pending_approval",
+        "toStepId": "rejected",
+        "trigger": "auto",
+        "priority": 90,
+        "preConditions": [
+          {
+            "ruleId": "workflow_order_approval_check_rejected",
+            "required": true
+          }
+        ],
+        "continueOnActivityFailure": true,
+        "activities": [
+          {
+            "activityId": "set_rejected_status",
+            "activityName": "Set Order to Rejected",
+            "activityType": "UPDATE_ENTITY",
+            "async": false,
+            "config": {
+              "commandId": "sales.orders.update",
+              "statusDictionary": "sales.order_status",
+              "input": {
+                "id": "{{context.id}}",
+                "statusValue": "rejected"
+              }
+            },
+            "retryPolicy": {
+              "maxAttempts": 3,
+              "initialIntervalMs": 1000,
+              "backoffCoefficient": 2,
+              "maxIntervalMs": 10000
+            }
+          },
+          {
+            "activityId": "emit_order_rejected",
+            "activityName": "Emit Order Rejected Event",
+            "activityType": "EMIT_EVENT",
+            "async": true,
+            "config": {
+              "eventName": "sales.order.approval.rejected",
+              "payload": {
+                "orderId": "{{context.id}}",
+                "workflowInstanceId": "{{workflow.instanceId}}",
+                "rejectedBy": "{{context.completedBy}}",
+                "comments": "{{context.comments}}"
+              }
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "approved_to_end",
+        "transitionName": "Complete After Approval",
+        "fromStepId": "approved",
+        "toStepId": "end",
+        "trigger": "auto",
+        "priority": 100,
+        "continueOnActivityFailure": true
+      },
+      {
+        "transitionId": "rejected_to_end",
+        "transitionName": "Complete After Rejection",
+        "fromStepId": "rejected",
+        "toStepId": "end",
+        "trigger": "auto",
+        "priority": 100,
+        "continueOnActivityFailure": true
+      }
+    ]
+  }
+}

package/src/modules/workflows/examples/order-approval-guard-rules.json

@@ -0,0 +1,32 @@
+[
+  {
+    "ruleId": "workflow_order_approval_check_approved",
+    "ruleName": "Check Decision is Approve",
+    "description": "Validates that the approval task decision is 'approve'",
+    "ruleType": "GUARD",
+    "entityType": "workflow:sales_order_approval_v1:transition",
+    "eventType": "pre_transition",
+    "conditionExpression": {
+      "field": "workflowContext.decision",
+      "operator": "=",
+      "value": "approve"
+    },
+    "enabled": true,
+    "priority": 100
+  },
+  {
+    "ruleId": "workflow_order_approval_check_rejected",
+    "ruleName": "Check Decision is Reject",
+    "description": "Validates that the approval task decision is 'reject'",
+    "ruleType": "GUARD",
+    "entityType": "workflow:sales_order_approval_v1:transition",
+    "eventType": "pre_transition",
+    "conditionExpression": {
+      "field": "workflowContext.decision",
+      "operator": "=",
+      "value": "reject"
+    },
+    "enabled": true,
+    "priority": 100
+  }
+]