@open-mercato/core 0.6.3-develop.3876.1.d40fe4ec2d → 0.6.3-develop.3894.1.352abf4240

package/src/modules/workflows/lib/duration.ts

@@ -0,0 +1,51 @@
+/**
+ * Parse ISO 8601 duration to milliseconds
+ *
+ * Supports:
+ * - ISO 8601: PT5M (5 minutes), PT1H (1 hour), P1D (1 day), P3D (3 days)
+ * - Simple formats: 5m, 1h, 3d, 30s
+ *
+ * @param duration - Duration string
+ * @returns Duration in milliseconds
+ */
+export function parseDuration(duration: string): number {
+  // Try ISO 8601 format first: P[n]DT[n]H[n]M[n]S
+  const iso8601Regex = /P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?/
+  const iso8601Match = duration.match(iso8601Regex)
+
+  if (iso8601Match && iso8601Match[0] === duration) {
+    const days = parseInt(iso8601Match[1] || '0')
+    const hours = parseInt(iso8601Match[2] || '0')
+    const minutes = parseInt(iso8601Match[3] || '0')
+    const seconds = parseInt(iso8601Match[4] || '0')
+
+    return (
+      days * 24 * 60 * 60 * 1000 +
+      hours * 60 * 60 * 1000 +
+      minutes * 60 * 1000 +
+      seconds * 1000
+    )
+  }
+
+  // Try simple format: 1d, 5h, 30m, 45s
+  const simpleRegex = /^(\d+)(d|h|m|s)$/
+  const simpleMatch = duration.match(simpleRegex)
+
+  if (simpleMatch) {
+    const value = parseInt(simpleMatch[1])
+    const unit = simpleMatch[2]
+
+    switch (unit) {
+      case 'd':
+        return value * 24 * 60 * 60 * 1000
+      case 'h':
+        return value * 60 * 60 * 1000
+      case 'm':
+        return value * 60 * 1000
+      case 's':
+        return value * 1000
+    }
+  }
+
+  throw new Error(`Invalid duration format: ${duration}`)
+}

package/src/modules/workflows/lib/event-logger.ts

@@ -73,6 +73,7 @@ export const WorkflowEventTypes = {
   SIGNAL_TIMEOUT: 'SIGNAL_TIMEOUT',
 
   // Timer events (Phase 9)
+  TIMER_AWAITING: 'TIMER_AWAITING',
   TIMER_FIRED: 'TIMER_FIRED',
   TIMER_CANCELLED: 'TIMER_CANCELLED',
 } as const

package/src/modules/workflows/lib/format-validation-error.ts

@@ -0,0 +1,30 @@
+type ZodIssueLite = {
+  path?: Array<string | number>
+  message?: string
+}
+
+type ApiErrorBody = {
+  error?: string
+  details?: ZodIssueLite[]
+}
+
+/**
+ * Format an API validation error body into a user-readable message.
+ *
+ * The workflow definitions API returns `{ error: 'Validation failed', details: ZodIssue[] }`
+ * for schema failures. The generic `error` string is useless to the user — the actionable
+ * information lives in `details[0].path` and `details[0].message`. This helper mirrors the
+ * visual editor's `Schema error: <path> - <message>` format so both editors surface the
+ * same diagnostic.
+ */
+export function formatWorkflowValidationError(
+  body: ApiErrorBody | null | undefined,
+  fallback: string,
+): string {
+  const issue = body?.details?.[0]
+  if (issue?.message) {
+    const path = (issue.path ?? []).join('.')
+    return path ? `${path} - ${issue.message}` : issue.message
+  }
+  return body?.error || fallback
+}

package/src/modules/workflows/lib/graph-utils.ts

@@ -452,6 +452,7 @@ function mapNodeTypeToStepType(nodeType: string): string {
     automated: 'AUTOMATED',
     decision: 'DECISION',
     waitForSignal: 'WAIT_FOR_SIGNAL',
+    waitForTimer: 'WAIT_FOR_TIMER',
   }
   return mapping[nodeType] || 'AUTOMATED'
 }
@@ -467,6 +468,7 @@ function mapStepTypeToNodeType(stepType: string): string {
     AUTOMATED: 'automated',
     DECISION: 'decision',
     WAIT_FOR_SIGNAL: 'waitForSignal',
+    WAIT_FOR_TIMER: 'waitForTimer',
   }
   return mapping[stepType] || 'automated'
 }
@@ -482,6 +484,7 @@ function getBadgeForNodeType(nodeType: string): string {
     automated: 'Automated',
     decision: 'Decision',
     waitForSignal: 'Wait for Signal',
+    waitForTimer: 'Wait for Timer',
   }
   return badges[nodeType] || 'Task'
 }

package/src/modules/workflows/lib/node-type-icons.ts

@@ -1,6 +1,6 @@
-import { CircleDot, CircleStop, User, Zap, Workflow, Clock, LucideIcon } from 'lucide-react'
+import { CircleDot, CircleStop, User, Zap, Workflow, Clock, Timer, LucideIcon } from 'lucide-react'
 
-export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal'
+export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal' | 'waitForTimer'
 
 export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   start: CircleDot,
@@ -9,6 +9,7 @@ export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   automated: Zap,
   subWorkflow: Workflow,
   waitForSignal: Clock,
+  waitForTimer: Timer,
 }
 
 export const NODE_TYPE_COLORS: Record<NodeType, string> = {
@@ -18,6 +19,7 @@ export const NODE_TYPE_COLORS: Record<NodeType, string> = {
   automated: 'text-amber-500',
   subWorkflow: 'text-purple-500',
   waitForSignal: 'text-purple-500',
+  waitForTimer: 'text-cyan-500',
 }
 
 export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: string }> = {
@@ -27,6 +29,7 @@ export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: st
   automated: { title: 'AUTOMATED', description: 'System task' },
   subWorkflow: { title: 'SUB-WORKFLOW', description: 'Invoke workflow' },
   waitForSignal: { title: 'WAIT FOR SIGNAL', description: 'Pause for external event' },
+  waitForTimer: { title: 'WAIT FOR TIMER', description: 'Pause for a duration' },
 }
 
 const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
@@ -36,6 +39,7 @@ const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
   AUTOMATED: 'automated',
   SUB_WORKFLOW: 'subWorkflow',
   WAIT_FOR_SIGNAL: 'waitForSignal',
+  WAIT_FOR_TIMER: 'waitForTimer',
 }
 
 export function stepTypeToNodeType(stepType: string): NodeType {

package/src/modules/workflows/lib/signal-handler.ts

@@ -5,12 +5,14 @@
  */
 
 import { EntityManager } from '@mikro-orm/core'
+import type { EntityManager as PostgreSqlEntityManager } from '@mikro-orm/postgresql'
 import type { AwilixContainer } from 'awilix'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { WorkflowInstance, WorkflowDefinition, StepInstance } from '../data/entities'
-import { logWorkflowEvent } from './event-logger'
-import { executeWorkflow } from './workflow-executor'
-import * as stepHandler from './step-handler'
-import * as transitionHandler from './transition-handler'
+import type * as eventLoggerModule from './event-logger'
+import type * as stepHandlerModule from './step-handler'
+import type * as transitionHandlerModule from './transition-handler'
+import type * as workflowExecutorModule from './workflow-executor'
 
 export interface SendSignalOptions {
   /**
@@ -61,12 +63,23 @@ export async function sendSignal(
 ): Promise<void> {
   const { instanceId, signalName, payload, userId, tenantId, organizationId } = options
 
+  const eventLogger = container.resolve<typeof eventLoggerModule>('eventLogger')
+  const stepHandler = container.resolve<typeof stepHandlerModule>('stepHandler')
+  const transitionHandler = container.resolve<typeof transitionHandlerModule>('transitionHandler')
+  const workflowExecutor = container.resolve<typeof workflowExecutorModule>('workflowExecutor')
+
   // Fetch workflow instance
-  const instance = await em.findOne(WorkflowInstance, {
-    id: instanceId,
-    tenantId,
-    organizationId,
-  })
+  const instance = await findOneWithDecryption(
+    em as PostgreSqlEntityManager,
+    WorkflowInstance,
+    {
+      id: instanceId,
+      tenantId,
+      organizationId,
+    },
+    undefined,
+    { tenantId, organizationId },
+  )
 
   if (!instance) {
     throw new SignalError(
@@ -85,8 +98,19 @@ export async function sendSignal(
     )
   }
 
-  // Load workflow definition to check current step
-  const definition = await em.findOne(WorkflowDefinition, instance.definitionId)
+  // Load workflow definition with tenant/org scope to check current step
+  const definition = await findOneWithDecryption(
+    em as PostgreSqlEntityManager,
+    WorkflowDefinition,
+    {
+      id: instance.definitionId,
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: instance.tenantId, organizationId: instance.organizationId },
+  )
   if (!definition) {
     throw new SignalError(
       'Workflow definition not found',
@@ -133,7 +157,7 @@ export async function sendSignal(
   instance.updatedAt = now
 
   // Log signal received event
-  await logWorkflowEvent(em, {
+  await eventLogger.logWorkflowEvent(em, {
     workflowInstanceId: instance.id,
     eventType: 'SIGNAL_RECEIVED',
     eventData: {
@@ -146,11 +170,19 @@ export async function sendSignal(
   })
 
   // Find active step instance and exit it
-  const stepInstance = await em.findOne(StepInstance, {
-    workflowInstanceId: instance.id,
-    stepId: instance.currentStepId,
-    status: 'ACTIVE',
-  })
+  const stepInstance = await findOneWithDecryption(
+    em as PostgreSqlEntityManager,
+    StepInstance,
+    {
+      workflowInstanceId: instance.id,
+      stepId: instance.currentStepId,
+      status: 'ACTIVE',
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    },
+    undefined,
+    { tenantId: instance.tenantId, organizationId: instance.organizationId },
+  )
 
   if (stepInstance) {
     await stepHandler.exitStep(em, stepInstance, {
@@ -212,7 +244,7 @@ export async function sendSignal(
   }
 
   // Resume workflow execution
-  await executeWorkflow(em, container, instance.id, { userId })
+  await workflowExecutor.executeWorkflow(em, container, instance.id, { userId })
 }
 
 /**
@@ -226,12 +258,18 @@ export async function sendSignalByCorrelationKey(
   const { correlationKey, signalName, payload, userId, tenantId, organizationId } = options
 
   // Find all paused instances with this correlation key
-  const instances = await em.find(WorkflowInstance, {
-    correlationKey,
-    status: 'PAUSED',
-    tenantId,
-    organizationId,
-  })
+  const instances = await findWithDecryption(
+    em as PostgreSqlEntityManager,
+    WorkflowInstance,
+    {
+      correlationKey,
+      status: 'PAUSED',
+      tenantId,
+      organizationId,
+    },
+    undefined,
+    { tenantId, organizationId },
+  )
 
   let signalsProcessed = 0
 

package/src/modules/workflows/lib/step-handler.ts

@@ -19,6 +19,8 @@ import {
   type StepInstanceStatus,
   type WorkflowStepType,
 } from '../data/entities'
+import { parseDuration } from './duration'
+import { logWorkflowEvent } from './event-logger'
 
 // ============================================================================
 // Types and Interfaces
@@ -333,9 +335,11 @@ async function executeStepByType(
     case 'WAIT_FOR_SIGNAL':
       return await handleWaitForSignalStep(em, instance, stepInstance, stepDef, context)
 
+    case 'WAIT_FOR_TIMER':
+      return await handleWaitForTimerStep(em, instance, stepInstance, stepDef, context)
+
     case 'PARALLEL_FORK':
     case 'PARALLEL_JOIN':
-    case 'WAIT_FOR_TIMER':
       // These will be implemented in later phases
       throw new StepExecutionError(
         `Step type not yet implemented: ${stepType}`,
@@ -756,66 +760,119 @@ async function handleWaitForSignalStep(
   }
 }
 
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
 /**
- * Parse ISO 8601 duration to milliseconds
- *
- * Supports:
- * - ISO 8601: PT5M (5 minutes), PT1H (1 hour), P1D (1 day), P3D (3 days)
- * - Simple formats: 5m, 1h, 3d, 30s
+ * Handle WAIT_FOR_TIMER step - pause workflow until a timer fires.
  *
- * @param duration - Duration string
- * @returns Duration in milliseconds
+ * Reads `duration` (relative, e.g. "PT5M") or `until` (ISO 8601 datetime) from
+ * `stepDef.config` (preferred — matches StepsEditor) or `stepDef.timerConfig`.
+ * Enqueues a delayed timer job on the workflow-activities queue; when the job
+ * is processed by the activity worker, it calls `timerHandler.fireTimer` to
+ * resume the workflow.
  */
-function parseDuration(duration: string): number {
-  // Try ISO 8601 format first: P[n]DT[n]H[n]M[n]S
-  const iso8601Regex = /P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?/
-  const iso8601Match = duration.match(iso8601Regex)
-
-  if (iso8601Match && iso8601Match[0] === duration) {
-    const days = parseInt(iso8601Match[1] || '0')
-    const hours = parseInt(iso8601Match[2] || '0')
-    const minutes = parseInt(iso8601Match[3] || '0')
-    const seconds = parseInt(iso8601Match[4] || '0')
-
-    return (
-      days * 24 * 60 * 60 * 1000 +
-      hours * 60 * 60 * 1000 +
-      minutes * 60 * 1000 +
-      seconds * 1000
+async function handleWaitForTimerStep(
+  em: EntityManager,
+  instance: WorkflowInstance,
+  stepInstance: StepInstance,
+  stepDef: any,
+  context: StepExecutionContext
+): Promise<StepExecutionResult> {
+  const timerConfig = stepDef.config || stepDef.timerConfig || {}
+  const duration: string | undefined = timerConfig.duration
+  const until: string | undefined = timerConfig.until
+
+  if (!duration && !until) {
+    throw new StepExecutionError(
+      'WAIT_FOR_TIMER requires either "duration" (e.g., "PT5M") or "until" (ISO 8601 datetime)',
+      'TIMER_CONFIG_MISSING',
+      { stepId: stepDef.stepId }
     )
   }
 
-  // Try simple format: 1d, 5h, 30m, 45s
-  const simpleRegex = /^(\d+)(d|h|m|s)$/
-  const simpleMatch = duration.match(simpleRegex)
-
-  if (simpleMatch) {
-    const value = parseInt(simpleMatch[1])
-    const unit = simpleMatch[2]
-
-    switch (unit) {
-      case 'd':
-        return value * 24 * 60 * 60 * 1000
-      case 'h':
-        return value * 60 * 60 * 1000
-      case 'm':
-        return value * 60 * 1000
-      case 's':
-        return value * 1000
+  let fireAtMs: number
+  if (until) {
+    const targetDate = new Date(until)
+    if (isNaN(targetDate.getTime())) {
+      throw new StepExecutionError(
+        `WAIT_FOR_TIMER invalid "until" datetime: ${until}`,
+        'TIMER_CONFIG_INVALID',
+        { until }
+      )
     }
+    fireAtMs = targetDate.getTime()
+  } else {
+    fireAtMs = Date.now() + parseDuration(duration as string)
   }
 
-  throw new StepExecutionError(
-    `Invalid duration format: ${duration}`,
-    'INVALID_DURATION',
-    { duration }
-  )
+  const delayMs = fireAtMs - Date.now()
+  const fireAt = new Date(fireAtMs)
+
+  // Immediate-fire path: skip the queue round-trip if the timer is in the past
+  if (delayMs <= 0) {
+    return {
+      status: 'COMPLETED',
+      outputData: {
+        stepType: 'WAIT_FOR_TIMER',
+        timerFiredImmediately: true,
+        fireAt,
+        duration,
+        until,
+      },
+    }
+  }
+
+  const now = new Date()
+
+  // Enqueue delayed timer job via the shared activity queue.
+  // Imported here to avoid a top-level cycle between step-handler and activity-executor.
+  const { enqueueTimerJob } = await import('./activity-executor')
+  const jobId = await enqueueTimerJob({
+    workflowInstanceId: instance.id,
+    stepInstanceId: stepInstance.id,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+    userId: context.userId,
+    fireAt: fireAt.toISOString(),
+    delayMs,
+  })
+
+  await logWorkflowEvent(em, {
+    workflowInstanceId: instance.id,
+    stepInstanceId: stepInstance.id,
+    eventType: 'TIMER_AWAITING',
+    eventData: {
+      fireAt: fireAt.toISOString(),
+      duration: duration || null,
+      until: until || null,
+      jobId,
+    },
+    userId: context.userId,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  })
+
+  instance.status = 'PAUSED'
+  instance.pausedAt = now
+  instance.updatedAt = now
+  await em.flush()
+
+  return {
+    status: 'WAITING',
+    waitReason: 'TIMER',
+    outputData: {
+      fireAt,
+      duration,
+      until,
+      jobId,
+    },
+  }
 }
 
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+// parseDuration is imported from ./duration
+
 /**
  * Log step-related event to event sourcing table
  */