@octaviaflow/flow-rules 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -47,12 +47,14 @@ __export(exports_src, {
   ConditionConfig: () => ConditionConfig,
   DATABASE_CONNECTOR_IDS: () => DATABASE_CONNECTOR_IDS,
   DebugConfig: () => DebugConfig,
+  EdgeType: () => EdgeType,
   EmailConfig: () => EmailConfig,
   FieldType: () => FieldType,
   ForEachConfig: () => ForEachConfig,
   JoinType: () => JoinType,
   LogicalOperator: () => LogicalOperator,
   ManualTriggerConfig: () => ManualTriggerConfig,
+  NodeStatus: () => NodeStatus,
   QueryMode: () => QueryMode,
   QueryType: () => QueryType,
   STORAGE_CONNECTOR_IDS: () => STORAGE_CONNECTOR_IDS,
@@ -65,6 +67,8 @@ __export(exports_src, {
   collectArrayPaths: () => collectArrayPaths,
   collectArrayPathsFromSample: () => collectArrayPathsFromSample,
   emailDefinition: () => emailDefinition,
+  flattenNestedWorkflow: () => flattenNestedWorkflow,
+  generateConnectionsFromSteps: () => generateConnectionsFromSteps,
   generateEdgeId: () => generateEdgeId,
   generateStepId: () => generateStepId,
   generateUUIDv4: () => generateUUIDv4,
@@ -81,7 +85,11 @@ __export(exports_src, {
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
   storageConfigKeys: () => storageConfigKeys,
+  transformConnectionToEdge: () => transformConnectionToEdge,
+  transformFlowToWorkflow: () => transformFlowToWorkflow,
+  transformStepToNode: () => transformStepToNode,
   validateEdge: () => validateEdge,
+  validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
   validateWorkflow: () => validateWorkflow
 });
@@ -3781,3 +3789,307 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/workflow.ts
+var NodeStatus;
+((NodeStatus) => {
+  NodeStatus["Idle"] = "idle";
+  NodeStatus["Running"] = "running";
+  NodeStatus["Success"] = "success";
+  NodeStatus["Error"] = "error";
+  NodeStatus["Warning"] = "warning";
+  NodeStatus["Disabled"] = "disabled";
+})(NodeStatus ||= {});
+var EdgeType;
+((EdgeType) => {
+  EdgeType["Default"] = "default";
+  EdgeType["Conditional"] = "conditional";
+  EdgeType["Loop"] = "loop";
+  EdgeType["Error"] = "error";
+})(EdgeType ||= {});
+// src/rules/flattenNestedWorkflow.ts
+function workflowIsNested(workflow) {
+  const stack = [...workflow.steps];
+  while (stack.length > 0) {
+    const s = stack.pop();
+    if (s.branches && Object.keys(s.branches).length > 0)
+      return true;
+  }
+  return false;
+}
+function flattenNestedWorkflow(workflow) {
+  if (!workflowIsNested(workflow))
+    return workflow;
+  const flatSteps = [];
+  const flatConns = [...workflow.connections];
+  const groups = [];
+  const walk = (steps, parentIdForSubflow) => {
+    for (const step of steps) {
+      const { branches, ...rest } = step;
+      const flatStep = {
+        ...rest,
+        ...parentIdForSubflow ? { parentId: parentIdForSubflow } : {}
+      };
+      flatSteps.push(flatStep);
+      if (!branches)
+        continue;
+      if (branches.body && step.type === "group") {
+        const body = branches.body;
+        groups.push({
+          group: flatStep,
+          bodyStepIds: body.steps.map((s) => s.id),
+          bodyConnections: body.connections
+        });
+        for (const c of body.connections)
+          flatConns.push(c);
+        walk(body.steps, step.id);
+      }
+      for (const branchKey of Object.keys(branches)) {
+        if (branchKey === "body" && step.type === "group")
+          continue;
+        const sub = branches[branchKey];
+        if (!sub)
+          continue;
+        for (const c of sub.connections)
+          flatConns.push(c);
+        walk(sub.steps, parentIdForSubflow);
+      }
+    }
+  };
+  walk(workflow.steps, undefined);
+  for (const g of groups) {
+    if (g.bodyStepIds.length === 0)
+      continue;
+    const bodyIdSet = new Set(g.bodyStepIds);
+    const inDeg = new Map;
+    const outDeg = new Map;
+    for (const id of g.bodyStepIds) {
+      inDeg.set(id, 0);
+      outDeg.set(id, 0);
+    }
+    for (const c of g.bodyConnections) {
+      if (bodyIdSet.has(c.sourceStepId)) {
+        outDeg.set(c.sourceStepId, (outDeg.get(c.sourceStepId) ?? 0) + 1);
+      }
+      if (bodyIdSet.has(c.targetStepId)) {
+        inDeg.set(c.targetStepId, (inDeg.get(c.targetStepId) ?? 0) + 1);
+      }
+    }
+    const roots = g.bodyStepIds.filter((id) => (inDeg.get(id) ?? 0) === 0);
+    const leaves = g.bodyStepIds.filter((id) => (outDeg.get(id) ?? 0) === 0);
+    for (const rootId of roots) {
+      flatConns.push({
+        id: `synth-inner-in-${g.group.id}-${rootId}`,
+        sourceStepId: g.group.id,
+        targetStepId: rootId,
+        sourcePort: "_inner_in"
+      });
+    }
+    for (const leafId of leaves) {
+      flatConns.push({
+        id: `synth-inner-out-${leafId}-${g.group.id}`,
+        sourceStepId: leafId,
+        targetStepId: g.group.id,
+        targetPort: "_inner_out"
+      });
+    }
+  }
+  return { ...workflow, steps: flatSteps, connections: flatConns };
+}
+
+// src/rules/flowShape.ts
+function transformStepToNode(step) {
+  const stepType = step.type;
+  const stepActionDefId = step.actionDefinitionId ?? "";
+  const nodeType = stepType === "trigger" ? "trigger" : stepType === "group" || stepActionDefId === "group" ? "group" : "action";
+  let nodeStatus = "idle" /* Idle */;
+  switch (step.status?.toLowerCase()) {
+    case "running":
+    case "executing":
+      nodeStatus = "running" /* Running */;
+      break;
+    case "completed":
+    case "success":
+      nodeStatus = "success" /* Success */;
+      break;
+    case "failed":
+    case "error":
+      nodeStatus = "error" /* Error */;
+      break;
+    case "pending":
+    case "waiting":
+      nodeStatus = "idle" /* Idle */;
+      break;
+    default:
+      nodeStatus = "idle" /* Idle */;
+  }
+  const position = step.position || { x: step.position_x || 0, y: step.position_y || 0 };
+  const posX = typeof position === "object" && position !== null && "x" in position ? position.x : step.position_x || 0;
+  const posY = typeof position === "object" && position !== null && "y" in position ? position.y : step.position_y || 0;
+  const config = step.config || {};
+  const configData = config.data || config || {};
+  const derivedFromName = step.name ? step.name.toLowerCase().replace(/\s+/g, "_") : undefined;
+  const resolvedActionDefinitionId = step.actionDefinitionId || config.connector_id || step.connector_id || derivedFromName || step.type;
+  const actionDef = getActionById(resolvedActionDefinitionId);
+  const node = {
+    id: step.id,
+    type: nodeType,
+    actionDefinitionId: resolvedActionDefinitionId,
+    actionDefinition: actionDef,
+    label: step.label || step.name,
+    description: step.description || config.description || actionDef?.description || "",
+    icon: actionDef?.icon ?? getIconForStepType(step.type),
+    position: {
+      x: posX,
+      y: posY
+    },
+    ...step.parentId ? { parentId: step.parentId } : {},
+    ...step.extent ? { extent: step.extent } : {},
+    ...step.disabled ? { disabled: true } : {},
+    ...step.dimensions && nodeType === "group" ? { dimensions: step.dimensions } : nodeType === "group" ? { dimensions: { width: 480, height: 240 } } : {},
+    config: {
+      ...configData,
+      timeout: step.timeout_seconds,
+      retryPolicy: step.retry_policy,
+      notes: step.notes,
+      tags: step.tags,
+      stepCount: step.step_count
+    },
+    ports: {
+      input: nodeType === "action" || nodeType === "group" ? [
+        {
+          id: `${step.id}-input`,
+          type: "input",
+          position: "top",
+          connected: false
+        }
+      ] : [],
+      output: (() => {
+        if (resolvedActionDefinitionId === "condition") {
+          return [
+            { id: `${step.id}_output_true`, type: "output", position: "bottom", label: "True", connected: false },
+            { id: `${step.id}_output_false`, type: "output", position: "bottom", label: "False", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "for_each" || resolvedActionDefinitionId === "for-each") {
+          return [
+            { id: `${step.id}_output_each`, type: "output", position: "bottom", label: "Each", connected: false },
+            { id: `${step.id}_output_done`, type: "output", position: "bottom", label: "Done", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "group") {
+          return [
+            { id: `${step.id}_output_0`, type: "output", position: "bottom", connected: false }
+          ];
+        }
+        return [
+          { id: `${step.id}-output`, type: "output", position: "bottom", connected: false }
+        ];
+      })()
+    },
+    configStatus: step.configStatus || undefined,
+    ...step.outputSchema ? { outputSchema: step.outputSchema } : {},
+    status: nodeStatus,
+    selected: false,
+    dragging: false,
+    isValid: step.configStatus ? step.configStatus === "valid" : true,
+    expanded: step.expanded,
+    minimized: false,
+    locked: false,
+    createdAt: step.created_at || new Date().toISOString(),
+    updatedAt: step.updated_at || new Date().toISOString()
+  };
+  return node;
+}
+function transformConnectionToEdge(connection) {
+  const sourceStepId = connection.sourceStepId || connection.source_step_id;
+  const targetStepId = connection.targetStepId || connection.target_step_id;
+  const sourcePort = connection.sourcePort || connection.source_port || `${sourceStepId}-output`;
+  const targetPort = connection.targetPort || connection.target_port || `${targetStepId}-input`;
+  let edgeType = "default" /* Default */;
+  if (connection.type === "success" || connection.type === "failure") {
+    edgeType = "conditional" /* Conditional */;
+  }
+  return {
+    id: connection.id,
+    source: sourceStepId,
+    target: targetStepId,
+    sourcePort,
+    targetPort,
+    type: edgeType,
+    label: connection.label,
+    selected: false,
+    animated: false,
+    createdAt: new Date().toISOString()
+  };
+}
+function generateConnectionsFromSteps(steps) {
+  const connections = [];
+  const sortedSteps = [...steps].sort((a, b) => a.step_count - b.step_count);
+  for (let i = 0;i < sortedSteps.length - 1; i++) {
+    const sourceStep = sortedSteps[i];
+    const targetStep = sortedSteps[i + 1];
+    connections.push({
+      id: `${sourceStep.id}-${targetStep.id}`,
+      source_step_id: sourceStep.id,
+      target_step_id: targetStep.id,
+      source_port: `${sourceStep.id}-output`,
+      target_port: `${targetStep.id}-input`,
+      type: "default"
+    });
+  }
+  return connections;
+}
+function getIconForStepType(type) {
+  const iconMap = {
+    trigger: "PlayOutline",
+    transform: "Transform",
+    action: "Application",
+    condition: "DecisionTree",
+    loop: "Repeat"
+  };
+  return iconMap[type] || "Application";
+}
+function transformFlowToWorkflow(flow) {
+  const flatWorkflow = flattenNestedWorkflow(flow.workflow);
+  const nodes = flatWorkflow.steps.map((step) => transformStepToNode(step));
+  let connections = flatWorkflow.connections;
+  if (connections === undefined || connections === null) {
+    connections = generateConnectionsFromSteps(flatWorkflow.steps);
+  } else {
+    connections = connections || [];
+  }
+  const edges = connections.map((conn, index) => {
+    if (!conn.id) {
+      conn.id = `edge-${conn.source_step_id}-${conn.target_step_id}-${index}`;
+    }
+    return transformConnectionToEdge(conn);
+  });
+  edges.forEach((edge) => {
+    const sourceNode = nodes.find((n) => n.id === edge.source);
+    const targetNode = nodes.find((n) => n.id === edge.target);
+    if (sourceNode) {
+      const port = sourceNode.ports.output.find((p) => p.id === edge.sourcePort);
+      if (port)
+        port.connected = true;
+    }
+    if (targetNode) {
+      const port = targetNode.ports.input.find((p) => p.id === edge.targetPort);
+      if (port)
+        port.connected = true;
+    }
+  });
+  return {
+    id: flow.workflow.id,
+    name: flow.workflow.name,
+    description: flow.workflow.description,
+    nodes,
+    edges,
+    workflowHistory: flow.workflowHistory || []
+  };
+}
+function validateFlowData(flow) {
+  if (!flow || typeof flow !== "object")
+    return false;
+  const f = flow;
+  return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
+}

package/dist/index.d.ts

@@ -40,3 +40,6 @@ export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_OPERATIONS, Transf
 export { STORAGE_CONNECTOR_IDS, type StorageExtraField, type StoragePathField, getStorageProvider, storageConfigKeys, } from "./catalog/storage/storageCapabilities";
 export { ManualTriggerConfig } from "./catalog/triggers/manual-trigger/index";
 export { type ManualTriggerConfigType } from "./catalog/triggers/manual-trigger/config";
+export * from "./catalog/workflow";
+export { type FlowConnection, type FlowData, type FlowStep, generateConnectionsFromSteps, transformConnectionToEdge, transformFlowToWorkflow, transformStepToNode, validateFlowData, } from "./rules/flowShape";
+export { flattenNestedWorkflow } from "./rules/flattenNestedWorkflow";

package/dist/index.js

@@ -3692,6 +3692,310 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/workflow.ts
+var NodeStatus;
+((NodeStatus) => {
+  NodeStatus["Idle"] = "idle";
+  NodeStatus["Running"] = "running";
+  NodeStatus["Success"] = "success";
+  NodeStatus["Error"] = "error";
+  NodeStatus["Warning"] = "warning";
+  NodeStatus["Disabled"] = "disabled";
+})(NodeStatus ||= {});
+var EdgeType;
+((EdgeType) => {
+  EdgeType["Default"] = "default";
+  EdgeType["Conditional"] = "conditional";
+  EdgeType["Loop"] = "loop";
+  EdgeType["Error"] = "error";
+})(EdgeType ||= {});
+// src/rules/flattenNestedWorkflow.ts
+function workflowIsNested(workflow) {
+  const stack = [...workflow.steps];
+  while (stack.length > 0) {
+    const s = stack.pop();
+    if (s.branches && Object.keys(s.branches).length > 0)
+      return true;
+  }
+  return false;
+}
+function flattenNestedWorkflow(workflow) {
+  if (!workflowIsNested(workflow))
+    return workflow;
+  const flatSteps = [];
+  const flatConns = [...workflow.connections];
+  const groups = [];
+  const walk = (steps, parentIdForSubflow) => {
+    for (const step of steps) {
+      const { branches, ...rest } = step;
+      const flatStep = {
+        ...rest,
+        ...parentIdForSubflow ? { parentId: parentIdForSubflow } : {}
+      };
+      flatSteps.push(flatStep);
+      if (!branches)
+        continue;
+      if (branches.body && step.type === "group") {
+        const body = branches.body;
+        groups.push({
+          group: flatStep,
+          bodyStepIds: body.steps.map((s) => s.id),
+          bodyConnections: body.connections
+        });
+        for (const c of body.connections)
+          flatConns.push(c);
+        walk(body.steps, step.id);
+      }
+      for (const branchKey of Object.keys(branches)) {
+        if (branchKey === "body" && step.type === "group")
+          continue;
+        const sub = branches[branchKey];
+        if (!sub)
+          continue;
+        for (const c of sub.connections)
+          flatConns.push(c);
+        walk(sub.steps, parentIdForSubflow);
+      }
+    }
+  };
+  walk(workflow.steps, undefined);
+  for (const g of groups) {
+    if (g.bodyStepIds.length === 0)
+      continue;
+    const bodyIdSet = new Set(g.bodyStepIds);
+    const inDeg = new Map;
+    const outDeg = new Map;
+    for (const id of g.bodyStepIds) {
+      inDeg.set(id, 0);
+      outDeg.set(id, 0);
+    }
+    for (const c of g.bodyConnections) {
+      if (bodyIdSet.has(c.sourceStepId)) {
+        outDeg.set(c.sourceStepId, (outDeg.get(c.sourceStepId) ?? 0) + 1);
+      }
+      if (bodyIdSet.has(c.targetStepId)) {
+        inDeg.set(c.targetStepId, (inDeg.get(c.targetStepId) ?? 0) + 1);
+      }
+    }
+    const roots = g.bodyStepIds.filter((id) => (inDeg.get(id) ?? 0) === 0);
+    const leaves = g.bodyStepIds.filter((id) => (outDeg.get(id) ?? 0) === 0);
+    for (const rootId of roots) {
+      flatConns.push({
+        id: `synth-inner-in-${g.group.id}-${rootId}`,
+        sourceStepId: g.group.id,
+        targetStepId: rootId,
+        sourcePort: "_inner_in"
+      });
+    }
+    for (const leafId of leaves) {
+      flatConns.push({
+        id: `synth-inner-out-${leafId}-${g.group.id}`,
+        sourceStepId: leafId,
+        targetStepId: g.group.id,
+        targetPort: "_inner_out"
+      });
+    }
+  }
+  return { ...workflow, steps: flatSteps, connections: flatConns };
+}
+
+// src/rules/flowShape.ts
+function transformStepToNode(step) {
+  const stepType = step.type;
+  const stepActionDefId = step.actionDefinitionId ?? "";
+  const nodeType = stepType === "trigger" ? "trigger" : stepType === "group" || stepActionDefId === "group" ? "group" : "action";
+  let nodeStatus = "idle" /* Idle */;
+  switch (step.status?.toLowerCase()) {
+    case "running":
+    case "executing":
+      nodeStatus = "running" /* Running */;
+      break;
+    case "completed":
+    case "success":
+      nodeStatus = "success" /* Success */;
+      break;
+    case "failed":
+    case "error":
+      nodeStatus = "error" /* Error */;
+      break;
+    case "pending":
+    case "waiting":
+      nodeStatus = "idle" /* Idle */;
+      break;
+    default:
+      nodeStatus = "idle" /* Idle */;
+  }
+  const position = step.position || { x: step.position_x || 0, y: step.position_y || 0 };
+  const posX = typeof position === "object" && position !== null && "x" in position ? position.x : step.position_x || 0;
+  const posY = typeof position === "object" && position !== null && "y" in position ? position.y : step.position_y || 0;
+  const config = step.config || {};
+  const configData = config.data || config || {};
+  const derivedFromName = step.name ? step.name.toLowerCase().replace(/\s+/g, "_") : undefined;
+  const resolvedActionDefinitionId = step.actionDefinitionId || config.connector_id || step.connector_id || derivedFromName || step.type;
+  const actionDef = getActionById(resolvedActionDefinitionId);
+  const node = {
+    id: step.id,
+    type: nodeType,
+    actionDefinitionId: resolvedActionDefinitionId,
+    actionDefinition: actionDef,
+    label: step.label || step.name,
+    description: step.description || config.description || actionDef?.description || "",
+    icon: actionDef?.icon ?? getIconForStepType(step.type),
+    position: {
+      x: posX,
+      y: posY
+    },
+    ...step.parentId ? { parentId: step.parentId } : {},
+    ...step.extent ? { extent: step.extent } : {},
+    ...step.disabled ? { disabled: true } : {},
+    ...step.dimensions && nodeType === "group" ? { dimensions: step.dimensions } : nodeType === "group" ? { dimensions: { width: 480, height: 240 } } : {},
+    config: {
+      ...configData,
+      timeout: step.timeout_seconds,
+      retryPolicy: step.retry_policy,
+      notes: step.notes,
+      tags: step.tags,
+      stepCount: step.step_count
+    },
+    ports: {
+      input: nodeType === "action" || nodeType === "group" ? [
+        {
+          id: `${step.id}-input`,
+          type: "input",
+          position: "top",
+          connected: false
+        }
+      ] : [],
+      output: (() => {
+        if (resolvedActionDefinitionId === "condition") {
+          return [
+            { id: `${step.id}_output_true`, type: "output", position: "bottom", label: "True", connected: false },
+            { id: `${step.id}_output_false`, type: "output", position: "bottom", label: "False", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "for_each" || resolvedActionDefinitionId === "for-each") {
+          return [
+            { id: `${step.id}_output_each`, type: "output", position: "bottom", label: "Each", connected: false },
+            { id: `${step.id}_output_done`, type: "output", position: "bottom", label: "Done", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "group") {
+          return [
+            { id: `${step.id}_output_0`, type: "output", position: "bottom", connected: false }
+          ];
+        }
+        return [
+          { id: `${step.id}-output`, type: "output", position: "bottom", connected: false }
+        ];
+      })()
+    },
+    configStatus: step.configStatus || undefined,
+    ...step.outputSchema ? { outputSchema: step.outputSchema } : {},
+    status: nodeStatus,
+    selected: false,
+    dragging: false,
+    isValid: step.configStatus ? step.configStatus === "valid" : true,
+    expanded: step.expanded,
+    minimized: false,
+    locked: false,
+    createdAt: step.created_at || new Date().toISOString(),
+    updatedAt: step.updated_at || new Date().toISOString()
+  };
+  return node;
+}
+function transformConnectionToEdge(connection) {
+  const sourceStepId = connection.sourceStepId || connection.source_step_id;
+  const targetStepId = connection.targetStepId || connection.target_step_id;
+  const sourcePort = connection.sourcePort || connection.source_port || `${sourceStepId}-output`;
+  const targetPort = connection.targetPort || connection.target_port || `${targetStepId}-input`;
+  let edgeType = "default" /* Default */;
+  if (connection.type === "success" || connection.type === "failure") {
+    edgeType = "conditional" /* Conditional */;
+  }
+  return {
+    id: connection.id,
+    source: sourceStepId,
+    target: targetStepId,
+    sourcePort,
+    targetPort,
+    type: edgeType,
+    label: connection.label,
+    selected: false,
+    animated: false,
+    createdAt: new Date().toISOString()
+  };
+}
+function generateConnectionsFromSteps(steps) {
+  const connections = [];
+  const sortedSteps = [...steps].sort((a, b) => a.step_count - b.step_count);
+  for (let i = 0;i < sortedSteps.length - 1; i++) {
+    const sourceStep = sortedSteps[i];
+    const targetStep = sortedSteps[i + 1];
+    connections.push({
+      id: `${sourceStep.id}-${targetStep.id}`,
+      source_step_id: sourceStep.id,
+      target_step_id: targetStep.id,
+      source_port: `${sourceStep.id}-output`,
+      target_port: `${targetStep.id}-input`,
+      type: "default"
+    });
+  }
+  return connections;
+}
+function getIconForStepType(type) {
+  const iconMap = {
+    trigger: "PlayOutline",
+    transform: "Transform",
+    action: "Application",
+    condition: "DecisionTree",
+    loop: "Repeat"
+  };
+  return iconMap[type] || "Application";
+}
+function transformFlowToWorkflow(flow) {
+  const flatWorkflow = flattenNestedWorkflow(flow.workflow);
+  const nodes = flatWorkflow.steps.map((step) => transformStepToNode(step));
+  let connections = flatWorkflow.connections;
+  if (connections === undefined || connections === null) {
+    connections = generateConnectionsFromSteps(flatWorkflow.steps);
+  } else {
+    connections = connections || [];
+  }
+  const edges = connections.map((conn, index) => {
+    if (!conn.id) {
+      conn.id = `edge-${conn.source_step_id}-${conn.target_step_id}-${index}`;
+    }
+    return transformConnectionToEdge(conn);
+  });
+  edges.forEach((edge) => {
+    const sourceNode = nodes.find((n) => n.id === edge.source);
+    const targetNode = nodes.find((n) => n.id === edge.target);
+    if (sourceNode) {
+      const port = sourceNode.ports.output.find((p) => p.id === edge.sourcePort);
+      if (port)
+        port.connected = true;
+    }
+    if (targetNode) {
+      const port = targetNode.ports.input.find((p) => p.id === edge.targetPort);
+      if (port)
+        port.connected = true;
+    }
+  });
+  return {
+    id: flow.workflow.id,
+    name: flow.workflow.name,
+    description: flow.workflow.description,
+    nodes,
+    edges,
+    workflowHistory: flow.workflowHistory || []
+  };
+}
+function validateFlowData(flow) {
+  if (!flow || typeof flow !== "object")
+    return false;
+  const f = flow;
+  return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
+}
 export {
   ActionCategory,
   ActionStatus,
@@ -3701,12 +4005,14 @@ export {
   ConditionConfig,
   DATABASE_CONNECTOR_IDS,
   DebugConfig,
+  EdgeType,
   EmailConfig,
   FieldType,
   ForEachConfig,
   JoinType,
   LogicalOperator,
   ManualTriggerConfig,
+  NodeStatus,
   QueryMode,
   QueryType,
   STORAGE_CONNECTOR_IDS,
@@ -3719,6 +4025,8 @@ export {
   collectArrayPaths,
   collectArrayPathsFromSample,
   emailDefinition,
+  flattenNestedWorkflow,
+  generateConnectionsFromSteps,
   generateEdgeId,
   generateStepId,
   generateUUIDv4,
@@ -3735,7 +4043,11 @@ export {
   migrateDelayConfig,
   queryDefinition,
   storageConfigKeys,
+  transformConnectionToEdge,
+  transformFlowToWorkflow,
+  transformStepToNode,
   validateEdge,
+  validateFlowData,
   validateNode,
   validateWorkflow
 };

package/dist/rules/flattenNestedWorkflow.d.ts

@@ -0,0 +1,25 @@
+type AnyConn = {
+    id?: string;
+    sourceStepId: string;
+    targetStepId: string;
+    sourcePort?: string;
+    targetPort?: string;
+    [k: string]: unknown;
+};
+type AnyStep = {
+    id: string;
+    type: string;
+    parentId?: string;
+    branches?: Record<string, {
+        steps: AnyStep[];
+        connections: AnyConn[];
+    }>;
+    [k: string]: unknown;
+};
+type AnyWorkflow = {
+    steps: AnyStep[];
+    connections: AnyConn[];
+    [k: string]: unknown;
+};
+export declare function flattenNestedWorkflow<W extends AnyWorkflow>(workflow: W): W;
+export {};

package/dist/rules/flowShape.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The PERSISTED flow shape, and how it becomes the canvas shape.
+ *
+ * A flow is stored as `steps` + `connections`; the rules engine and anything
+ * that reasons about a flow work in `nodes` + `edges`. This is the ONE
+ * conversion between them.
+ *
+ * It lived in octaviaflow-ui because only the editor ever read a flow. The
+ * server has to now: `check_flow` runs the same rules against a STORED flow
+ * and cannot do that without converting it the same way. A second converter
+ * would make an agent's verdict quietly disagree with the editor's, which is
+ * the failure this package exists to prevent.
+ *
+ * Two UI-only pieces did not come: `loadFlowFromJSON` (an HTTP fetch) and
+ * `calculateFitViewport` (canvas geometry) stay in the editor.
+ */
+/**
+ * Flow Loader Utilities
+ *
+ * Utilities for loading, transforming, and managing workflow flows
+ * from various data sources (JSON files, APIs, etc.)
+ */
+import { type WorkflowNode, type WorkflowEdge } from "../catalog/workflow";
+/**
+ * Flow data structure from database/JSON
+ */
+export interface FlowData {
+    id: string;
+    name: string;
+    description: string;
+    status: string;
+    owner: {
+        user_id: string;
+        user_name: string;
+        user_email: string;
+        permissions: string[];
+    };
+    collaborators: Array<{
+        user_id: string;
+        user_name: string;
+        user_email: string;
+        permissions: string[];
+        added_at: string;
+        added_by: string;
+    }>;
+    workflow: {
+        id: string;
+        name: string;
+        description: string;
+        status: string;
+        steps: FlowStep[];
+        connections?: FlowConnection[];
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+export interface FlowStep {
+    id: string;
+    name: string;
+    description: string;
+    type: 'trigger' | 'transform' | 'action' | 'condition' | 'loop';
+    config: {
+        connector_id?: string;
+        connection_id?: string;
+        data?: Record<string, unknown>;
+    };
+    step_count: number;
+    position_x: number;
+    position_y: number;
+    expanded: boolean;
+    timeout_seconds?: number;
+    retry_policy?: {
+        enabled: boolean;
+        max_retries: number;
+        retry_delay_seconds: number;
+        backoff_strategy: string;
+    };
+    status: string;
+    notes?: string;
+    tags?: string[];
+    created_at?: string;
+    created_by?: string;
+    updated_at?: string;
+    updated_by?: string;
+}
+export interface FlowConnection {
+    id: string;
+    source_step_id: string;
+    target_step_id: string;
+    source_port?: string;
+    target_port?: string;
+    condition?: string;
+    label?: string;
+    type?: 'default' | 'success' | 'failure';
+}
+/**
+ * Transform flow step to WorkflowNode
+ */
+export declare function transformStepToNode(step: FlowStep): WorkflowNode;
+/**
+ * Transform flow connection to WorkflowEdge
+ */
+export declare function transformConnectionToEdge(connection: FlowConnection): WorkflowEdge;
+/**
+ * Auto-generate connections from step order if not provided
+ */
+export declare function generateConnectionsFromSteps(steps: FlowStep[]): FlowConnection[];
+/**
+ * Transform complete flow data to workflow state
+ */
+export declare function transformFlowToWorkflow(flow: FlowData): {
+    id: string;
+    name: string;
+    description: string;
+    nodes: any;
+    edges: any;
+    workflowHistory: any;
+};
+/**
+ * Validate flow data structure
+ */
+export declare function validateFlowData(flow: unknown): flow is FlowData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The flow action catalog and the rules engine behind Flow Doctor \u2014 one definition of what a step accepts and what makes a flow valid, shared by the editor and the server",
   "type": "module",
   "main": "./dist/index.cjs",