flow.zod.ts

import { z } from 'zod';

/**
 * Flow Node Types
 */
export const FlowNodeAction = z.enum([
  'start',            // Trigger
  'end',              // Return/Stop
  'decision',         // If/Else logic
  'assignment',       // Set Variable
  'loop',             // For Each
  'create_record',    // CRUD: Create
  'update_record',    // CRUD: Update
  'delete_record',    // CRUD: Delete
  'get_record',       // CRUD: Get/Query
  'http_request',     // Webhook/API Call
  'script',           // Custom Script (JS/TS)
  'screen',           // Screen / User-Input Element
  'wait',             // Delay/Sleep
  'subflow',          // Call another flow
  'connector_action', // Zapier-style integration action
]);

/**
 * Flow Variable Schema
 * Variables available within the flow execution context.
 */
export const FlowVariableSchema = z.object({
  name: z.string().describe('Variable name'),
  type: z.string().describe('Data type (text, number, boolean, object, list)'),
  isInput: z.boolean().default(false).describe('Is input parameter'),
  isOutput: z.boolean().default(false).describe('Is output parameter'),
});

/**
 * Flow Node Schema
 * A single step in the visual logic graph.
 * 
 * @example Decision Node
 * {
 *   id: "dec_1",
 *   type: "decision",
 *   label: "Is High Value?",
 *   config: {
 *     conditions: [
 *       { label: "Yes", expression: "{amount} > 10000" },
 *       { label: "No", expression: "true" } // default
 *     ]
 *   },
 *   position: { x: 300, y: 200 }
 * }
 */
export const FlowNodeSchema = z.object({
  id: z.string().describe('Node unique ID'),
  type: FlowNodeAction.describe('Action type'),
  label: z.string().describe('Node label'),
  
  /** Node Configuration Options (Specific to type) */
  config: z.record(z.string(), z.unknown()).optional().describe('Node configuration'),
  
  /** 
   * Connector Action Configuration
   * Used when type is 'connector_action'
   */
  connectorConfig: z.object({
    connectorId: z.string(),
    actionId: z.string(),
    input: z.record(z.string(), z.unknown()).describe('Mapped inputs for the action'),
  }).optional(),

  /** UI Position (for the canvas) */
  position: z.object({ x: z.number(), y: z.number() }).optional(),
});

/**
 * Flow Edge Schema
 * Connections between nodes.
 */
export const FlowEdgeSchema = z.object({
  id: z.string().describe('Edge unique ID'),
  source: z.string().describe('Source Node ID'),
  target: z.string().describe('Target Node ID'),
  
  /** Condition for this path (only for decision/branch nodes) */
  condition: z.string().optional().describe('Expression returning boolean used for branching'),
  
  type: z.enum(['default', 'fault']).default('default').describe('Connection type: Standard (Success) or Fault (Error) path'),
  label: z.string().optional().describe('Label on the connector'),
});

/**
 * Flow Schema
 * Visual Business Logic Orchestration.
 * 
 * @example Simple Approval Logic
 * {
 *   name: "approve_order_flow",
 *   label: "Approve Large Orders",
 *   type: "record_change",
 *   status: "active",
 *   nodes: [
 *     { id: "start", type: "start", label: "Start", position: {x: 0, y: 0} },
 *     { id: "check_amount", type: "decision", label: "Check Amount", position: {x: 0, y: 100} },
 *     { id: "auto_approve", type: "update_record", label: "Auto Approve", position: {x: -100, y: 200} },
 *     { id: "submit_for_approval", type: "connector_action", label: "Submit", position: {x: 100, y: 200} }
 *   ],
 *   edges: [
 *     { id: "e1", source: "start", target: "check_amount" },
 *     { id: "e2", source: "check_amount", target: "auto_approve", condition: "{amount} < 500" },
 *     { id: "e3", source: "check_amount", target: "submit_for_approval", condition: "{amount} >= 500" }
 *   ]
 * }
 */
export const FlowSchema = z.object({
  /** Identity */
  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name'),
  label: z.string().describe('Flow label'),
  description: z.string().optional(),
  
  /** Metadata & Versioning */
  version: z.number().int().default(1).describe('Version number'),
  status: z.enum(['draft', 'active', 'obsolete', 'invalid']).default('draft').describe('Deployment status'),
  template: z.boolean().default(false).describe('Is logic template (Subflow)'),

  /** Trigger Type */
  type: z.enum(['autolaunched', 'record_change', 'schedule', 'screen', 'api']).describe('Flow type'),
  
  /** Configuration Variables */
  variables: z.array(FlowVariableSchema).optional().describe('Flow variables'),
  
  /** Graph Definition */
  nodes: z.array(FlowNodeSchema).describe('Flow nodes'),
  edges: z.array(FlowEdgeSchema).describe('Flow connections'),
  
  /** Execution Config */
  active: z.boolean().default(false).describe('Is active (Deprecated: use status)'),
  runAs: z.enum(['system', 'user']).default('user').describe('Execution context'),
});

export type Flow = z.input<typeof FlowSchema>;
export type FlowParsed = z.infer<typeof FlowSchema>;
export type FlowNode = z.input<typeof FlowNodeSchema>;
export type FlowNodeParsed = z.infer<typeof FlowNodeSchema>;
export type FlowEdge = z.input<typeof FlowEdgeSchema>;
export type FlowEdgeParsed = z.infer<typeof FlowEdgeSchema>;