@octaviaflow/flow-rules 0.22.0 → 0.23.0

package/README.md

@@ -50,8 +50,17 @@ const required = action?.inputSchema.fields.filter((f) => f.validation?.required
 
 // Does this flow work?
 const { isValid, errors, warnings } = validateWorkflow(nodes, edges);
+
+// With what the caller knows beyond the canvas (optional, 0.23.0+):
+validateWorkflow(nodes, edges, { connectorTypes: { [connectionId]: "salesforce" } });
 ```
 
+`connectorTypes` maps each connection id the flow uses to its connector type.
+With it, a Transform that upserts or updates into a target whose fallback key is
+its own record id (Salesforce, MongoDB, Shopify, Odoo, HubSpot objects other
+than contacts and companies), with no match field and no mapping that writes
+that id, gets a warning (DEV-646). Without it, that rule says nothing.
+
 ### The severity contract
 
 Unchanged from rules-v2 (DEV-220, ADR-flow-pause-and-rules-v2):

package/dist/index.cjs

@@ -85,6 +85,7 @@ __export(exports_src, {
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
   ONEDRIVE_OPERATIONS: () => ONEDRIVE_OPERATIONS,
+  OWN_ID_MATCH_TARGETS: () => OWN_ID_MATCH_TARGETS,
   OneDriveActionConfig: () => OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS: () => PLATFORM_CONFIG_KEYS,
   QUERY_AGGREGATE_FUNCTIONS: () => QUERY_AGGREGATE_FUNCTIONS,
@@ -161,6 +162,7 @@ __export(exports_src, {
   storageConfigKeys: () => storageConfigKeys,
   storageOperations: () => storageOperations,
   summarizeConnectorTriggerEvents: () => summarizeConnectorTriggerEvents,
+  syncMatchKeyWarning: () => syncMatchKeyWarning,
   transformConnectionToEdge: () => transformConnectionToEdge,
   transformFlowToWorkflow: () => transformFlowToWorkflow,
   transformStepToNode: () => transformStepToNode,
@@ -5293,9 +5295,52 @@ function contractValidationErrors(node) {
   }
 }
 
+// src/rules/syncMatchKey.ts
+var OWN_ID_MATCH_TARGETS = {
+  salesforce: {
+    app: "Salesforce",
+    idFields: ["Id"],
+    hint: "an External ID field on the object that holds the source record's id"
+  },
+  mongodb: { app: "MongoDB", idFields: ["_id"], hint: "a field that is unique for each source record" },
+  shopify: { app: "Shopify", idFields: ["id"], hint: "a field Shopify can look up, such as email, sku or handle" },
+  odoo: { app: "Odoo", idFields: ["id"], hint: "a field that is unique for each source record" },
+  hubspot: {
+    app: "HubSpot",
+    idFields: ["id", "hs_object_id"],
+    naturalKeyObjects: new Set(["contacts", "companies"]),
+    hint: "a property that is unique for each source record"
+  }
+};
+var MATCHING_OPERATIONS = new Set(["upsert", "update"]);
+var text = (v) => typeof v === "string" ? v.trim() : "";
+function syncMatchKeyWarning(node, connectorTypes) {
+  if (node.actionDefinitionId !== "transform" || !connectorTypes)
+    return null;
+  const config = node.config ?? {};
+  const operation = text(config.operation);
+  if (!MATCHING_OPERATIONS.has(operation))
+    return null;
+  if (text(config.upsertMatchKey))
+    return null;
+  if (text(config.mode) === "expression")
+    return null;
+  const connectionId = text(config.connectorId);
+  const target = connectionId ? OWN_ID_MATCH_TARGETS[connectorTypes[connectionId] ?? ""] : undefined;
+  if (!target)
+    return null;
+  if (target.naturalKeyObjects?.has(text(config.objectName).toLowerCase()))
+    return null;
+  const mappings = Array.isArray(config.mappings) ? config.mappings : [];
+  if (mappings.some((m) => target.idFields.includes(text(m?.targetField))))
+    return null;
+  const consequence = operation === "upsert" ? "the rows from another app don't carry it, so every run fails or, run as insert, creates the records again" : "the rows from another app don't carry it, so nothing is updated";
+  return `No match field: this ${operation} into ${target.app} matches on ${target.app}'s own record id, and ${consequence}. ` + `Set a match field (${target.hint}).`;
+}
+
 // src/rules/workflowValidator.ts
 var nodeName = (n) => n.label || n.id;
-function validateNode(node, allNodes, allEdges) {
+function validateNode(node, allNodes, allEdges, context = {}) {
   const errors = [];
   if (!node.id || node.id.trim().length === 0) {
     errors.push({
@@ -5350,6 +5395,16 @@ function validateNode(node, allNodes, allEdges) {
       nodeId: node.id
     });
   }
+  const syncKey = syncMatchKeyWarning(node, context.connectorTypes);
+  if (syncKey) {
+    errors.push({
+      id: `node-${node.id}-sync-key`,
+      type: "node",
+      severity: "warning",
+      message: syncKey,
+      nodeId: node.id
+    });
+  }
   const hasOutput = allEdges.some((edge) => edge.source === node.id);
   if (!hasOutput && node.type === "trigger") {
     errors.push({
@@ -5408,7 +5463,7 @@ function validateEdge(edge, allNodes, allEdges = []) {
   }
   return errors;
 }
-function validateWorkflow(nodes, edges) {
+function validateWorkflow(nodes, edges, context = {}) {
   const allErrors = [];
   const hasTrigger = nodes.some((node) => node.type === "trigger");
   if (!hasTrigger) {
@@ -5429,7 +5484,7 @@ function validateWorkflow(nodes, edges) {
     });
   }
   nodes.forEach((node) => {
-    const nodeErrors = validateNode(node, nodes, edges);
+    const nodeErrors = validateNode(node, nodes, edges, context);
     allErrors.push(...nodeErrors);
   });
   edges.forEach((edge) => {

package/dist/index.d.ts

@@ -20,7 +20,8 @@
  */
 export * from "./catalog/types";
 export { actionsRegistry, getAllActions, getActionById, getActionsByCategory, } from "./catalog/index";
-export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, type ValidationError, type ValidationResult, } from "./rules/workflowValidator";
+export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, type ValidationError, type ValidationResult, type ValidationContext, } from "./rules/workflowValidator";
+export { OWN_ID_MATCH_TARGETS, syncMatchKeyWarning } from "./rules/syncMatchKey";
 export { getNodeConfigStatus, missingContractRequired, contractValidationErrors, type NodeConfigStatus, type NodeConfigStatusResult, } from "./rules/nodeConfigStatus";
 export { generateWorkflowId, generateStepId, generateEdgeId, generateUUIDv4, } from "./ids";
 export { CONDITION_OPERATORS, ConditionConfig, type ConditionFilter, type ConditionOperator, } from "./catalog/logic/condition/config";

package/dist/index.js

@@ -5115,9 +5115,52 @@ function contractValidationErrors(node) {
   }
 }
 
+// src/rules/syncMatchKey.ts
+var OWN_ID_MATCH_TARGETS = {
+  salesforce: {
+    app: "Salesforce",
+    idFields: ["Id"],
+    hint: "an External ID field on the object that holds the source record's id"
+  },
+  mongodb: { app: "MongoDB", idFields: ["_id"], hint: "a field that is unique for each source record" },
+  shopify: { app: "Shopify", idFields: ["id"], hint: "a field Shopify can look up, such as email, sku or handle" },
+  odoo: { app: "Odoo", idFields: ["id"], hint: "a field that is unique for each source record" },
+  hubspot: {
+    app: "HubSpot",
+    idFields: ["id", "hs_object_id"],
+    naturalKeyObjects: new Set(["contacts", "companies"]),
+    hint: "a property that is unique for each source record"
+  }
+};
+var MATCHING_OPERATIONS = new Set(["upsert", "update"]);
+var text = (v) => typeof v === "string" ? v.trim() : "";
+function syncMatchKeyWarning(node, connectorTypes) {
+  if (node.actionDefinitionId !== "transform" || !connectorTypes)
+    return null;
+  const config = node.config ?? {};
+  const operation = text(config.operation);
+  if (!MATCHING_OPERATIONS.has(operation))
+    return null;
+  if (text(config.upsertMatchKey))
+    return null;
+  if (text(config.mode) === "expression")
+    return null;
+  const connectionId = text(config.connectorId);
+  const target = connectionId ? OWN_ID_MATCH_TARGETS[connectorTypes[connectionId] ?? ""] : undefined;
+  if (!target)
+    return null;
+  if (target.naturalKeyObjects?.has(text(config.objectName).toLowerCase()))
+    return null;
+  const mappings = Array.isArray(config.mappings) ? config.mappings : [];
+  if (mappings.some((m) => target.idFields.includes(text(m?.targetField))))
+    return null;
+  const consequence = operation === "upsert" ? "the rows from another app don't carry it, so every run fails or, run as insert, creates the records again" : "the rows from another app don't carry it, so nothing is updated";
+  return `No match field: this ${operation} into ${target.app} matches on ${target.app}'s own record id, and ${consequence}. ` + `Set a match field (${target.hint}).`;
+}
+
 // src/rules/workflowValidator.ts
 var nodeName = (n) => n.label || n.id;
-function validateNode(node, allNodes, allEdges) {
+function validateNode(node, allNodes, allEdges, context = {}) {
   const errors = [];
   if (!node.id || node.id.trim().length === 0) {
     errors.push({
@@ -5172,6 +5215,16 @@ function validateNode(node, allNodes, allEdges) {
       nodeId: node.id
     });
   }
+  const syncKey = syncMatchKeyWarning(node, context.connectorTypes);
+  if (syncKey) {
+    errors.push({
+      id: `node-${node.id}-sync-key`,
+      type: "node",
+      severity: "warning",
+      message: syncKey,
+      nodeId: node.id
+    });
+  }
   const hasOutput = allEdges.some((edge) => edge.source === node.id);
   if (!hasOutput && node.type === "trigger") {
     errors.push({
@@ -5230,7 +5283,7 @@ function validateEdge(edge, allNodes, allEdges = []) {
   }
   return errors;
 }
-function validateWorkflow(nodes, edges) {
+function validateWorkflow(nodes, edges, context = {}) {
   const allErrors = [];
   const hasTrigger = nodes.some((node) => node.type === "trigger");
   if (!hasTrigger) {
@@ -5251,7 +5304,7 @@ function validateWorkflow(nodes, edges) {
     });
   }
   nodes.forEach((node) => {
-    const nodeErrors = validateNode(node, nodes, edges);
+    const nodeErrors = validateNode(node, nodes, edges, context);
     allErrors.push(...nodeErrors);
   });
   edges.forEach((edge) => {
@@ -6247,6 +6300,7 @@ export {
   ManualTriggerConfig,
   NodeStatus,
   ONEDRIVE_OPERATIONS,
+  OWN_ID_MATCH_TARGETS,
   OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS,
   QUERY_AGGREGATE_FUNCTIONS,
@@ -6323,6 +6377,7 @@ export {
   storageConfigKeys,
   storageOperations,
   summarizeConnectorTriggerEvents,
+  syncMatchKeyWarning,
   transformConnectionToEdge,
   transformFlowToWorkflow,
   transformStepToNode,

package/dist/rules/syncMatchKey.d.ts

@@ -0,0 +1,48 @@
+/**
+ * An upsert or update with nothing to match on (DEV-646).
+ *
+ * Prod, 2026-11-09: a HubSpot → Salesforce "sync" built over the MCP set no
+ * match field. The upsert failed ("External ID is not found in record"); run
+ * as insert instead, every run created all 140 Accounts again.
+ *
+ * With no `upsertMatchKey`, the Engine's writer falls back to a key of its
+ * own. For some targets that key is the target record's OWN id, which rows
+ * coming from another app never carry unless a mapping writes it. Those are
+ * the targets this rule warns about, mirroring the Engine:
+ *
+ *   salesforce  `Id`          writeToSalesforce: matchKey || externalIdField || 'Id'
+ *   mongodb     `_id`         writeToMongoDB:    matchKey || '_id'
+ *   shopify     `id`          isShopifyIdKey:    no key = PUT by id
+ *   odoo        `id`          writeToOdoo:       matchKey || 'id'
+ *   hubspot     own id        writeToHubSpot:    matchKey || email (contacts) / domain (companies) || record id
+ *
+ * Silent, because the fallback is a natural key or can't be known here:
+ * QuickBooks (DocNumber / DisplayName), HubSpot contacts and companies, the
+ * SQL targets and Snowflake (the primary key), and the OData targets (SAP,
+ * Business Central, D365 F&O), whose entity key comes from live metadata.
+ *
+ * The rule needs to know which app a connection is. A Transform's
+ * `connectorId` is a connection (instance) id, so the caller passes
+ * `connectorTypes` (connection id → connector type). Without it, or for a
+ * connection it doesn't list, the rule says nothing.
+ */
+import type { WorkflowNode } from '../catalog/workflow';
+interface OwnIdTarget {
+    /** How the app is named in the message. */
+    readonly app: string;
+    /** Target field names that ARE the record's own id: a mapping to one supplies the match. */
+    readonly idFields: readonly string[];
+    /** Objects whose writer falls back to a natural key instead (lower case). */
+    readonly naturalKeyObjects?: ReadonlySet<string>;
+    /** What to use as the match field, said in the app's terms. */
+    readonly hint: string;
+}
+/** Connector types whose upsert/update, with no match field, matches on the target record's own id. */
+export declare const OWN_ID_MATCH_TARGETS: Readonly<Record<string, OwnIdTarget>>;
+/**
+ * The warning for a Transform that upserts or updates into a target whose
+ * fallback is its own record id, with no match field set and no mapping that
+ * writes that id. `null` when there is nothing to say.
+ */
+export declare function syncMatchKeyWarning(node: WorkflowNode, connectorTypes: Readonly<Record<string, string>> | undefined): string | null;
+export {};

package/dist/rules/workflowValidator.d.ts

@@ -16,6 +16,17 @@
  *             ("won't run" orphans, multi-flow canvas, duplicate edges).
  */
 import { WorkflowNode, WorkflowEdge } from '../catalog/workflow';
+/**
+ * What the caller knows beyond the canvas. Every field is optional: a rule
+ * that needs one says nothing without it.
+ */
+export interface ValidationContext {
+    /**
+     * Connection (instance) id → connector type (`salesforce`, `mongodb`, …),
+     * for the connections the flow's steps use (DEV-646).
+     */
+    connectorTypes?: Readonly<Record<string, string>>;
+}
 export interface ValidationError {
     id: string;
     type: 'node' | 'edge' | 'workflow';
@@ -32,7 +43,7 @@ export interface ValidationResult {
 /**
  * Validate a single node.
  */
-export declare function validateNode(node: WorkflowNode, allNodes: WorkflowNode[], allEdges: WorkflowEdge[]): ValidationError[];
+export declare function validateNode(node: WorkflowNode, allNodes: WorkflowNode[], allEdges: WorkflowEdge[], context?: ValidationContext): ValidationError[];
 /**
  * Validate a single edge. `allEdges` powers real duplicate detection —
  * only the SECOND-and-later instance of a duplicate is flagged, so one
@@ -42,7 +53,7 @@ export declare function validateEdge(edge: WorkflowEdge, allNodes: WorkflowNode[
 /**
  * Validate entire workflow.
  */
-export declare function validateWorkflow(nodes: WorkflowNode[], edges: WorkflowEdge[]): ValidationResult;
+export declare function validateWorkflow(nodes: WorkflowNode[], edges: WorkflowEdge[], context?: ValidationContext): ValidationResult;
 /**
  * Get validation status for a specific node
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.22.0",
+  "version": "0.23.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",