@octaviaflow/flow-rules 0.9.0 → 0.10.0

package/dist/catalog/triggers/connector-trigger/events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a Connector Trigger can subscribe to, per connector.
+ *
+ * ONE vocabulary for the editor's panel and for an agent authoring over MCP.
+ * The trigger's `events` — `[{ entity, operations }]` — is what registers the
+ * flow's connector subscription, the record every inbound provider event is
+ * matched against: an entity name outside this list (or in the wrong case —
+ * HubSpot is lowercase, Salesforce is capitalised) registers a subscription
+ * that never fires, with no error anywhere. An agent wrote `lead` for a
+ * HubSpot contact trigger on 2026-09-26 and spent an hour on it.
+ *
+ * Copied as-is from octaviaflow-ui's ConnectorTriggerPanel (the panel's tables
+ * were the only copy); the panel is to import from here in its next flow-rules
+ * upgrade.
+ */
+export interface ConnectorEventEntity {
+    entity: string;
+    supportedOperations: string[];
+}
+/** One subscribed pair, as stored in a trigger step's `events`. */
+export interface ConnectorTriggerEvent {
+    entity: string;
+    operations: string[];
+}
+/**
+ * Connector ids that emit events a flow trigger can subscribe to. Database /
+ * http / openapi / ftp / etc. connectors are intentionally excluded: they
+ * cannot push events.
+ */
+export declare const EVENT_CAPABLE_CONNECTOR_IDS: ReadonlySet<string>;
+/** Every subscribable entity, by connector id. */
+export declare const CONNECTOR_EVENT_ENTITIES: Readonly<Record<string, ConnectorEventEntity[]>>;
+export declare function getEntitiesForConnector(connectorId: string): ConnectorEventEntity[];
+/** True when this connector type can drive an event trigger. */
+export declare function isEventCapableConnector(connectorId: string): boolean;
+/**
+ * The one-line summary the canvas shows under a Connector Trigger
+ * (`Hubspot · 4 events`) — the same string the panel writes.
+ */
+export declare function summarizeConnectorTriggerEvents(connectorName: string, events: ConnectorTriggerEvent[]): string;
+/**
+ * Why `events` cannot register a trigger on this connector — or `null` when
+ * it can. Names are matched EXACTLY, because the inbound matcher matches them
+ * exactly; a case-only miss says what was meant.
+ */
+export declare function validateConnectorTriggerEvents(connectorId: string, events: unknown): string | null;

package/dist/index.cjs

@@ -45,9 +45,11 @@ __export(exports_src, {
   AggregateFunction: () => AggregateFunction,
   CONDITION_OPERATORS: () => CONDITION_OPERATORS,
   CONFIG_CONTRACTS: () => CONFIG_CONTRACTS,
+  CONNECTOR_EVENT_ENTITIES: () => CONNECTOR_EVENT_ENTITIES,
   ConditionConfig: () => ConditionConfig,
   DATABASE_CONNECTOR_IDS: () => DATABASE_CONNECTOR_IDS,
   DebugConfig: () => DebugConfig,
+  EVENT_CAPABLE_CONNECTOR_IDS: () => EVENT_CAPABLE_CONNECTOR_IDS,
   EdgeType: () => EdgeType,
   EmailConfig: () => EmailConfig,
   FieldType: () => FieldType,
@@ -89,20 +91,24 @@ __export(exports_src, {
   getActionsByCategory: () => getActionsByCategory,
   getAllActions: () => getAllActions,
   getEdgeValidationStatus: () => getEdgeValidationStatus,
+  getEntitiesForConnector: () => getEntitiesForConnector,
   getNodeConfigStatus: () => getNodeConfigStatus,
   getNodeValidationStatus: () => getNodeValidationStatus,
   getStorageProvider: () => getStorageProvider,
   inferSchemaFromSample: () => inferSchemaFromSample,
   isEditorPrivateKey: () => isEditorPrivateKey,
+  isEventCapableConnector: () => isEventCapableConnector,
   isMappingFunction: () => isMappingFunction,
   isQueryableConnector: () => isQueryableConnector,
   mappingTransformFunctionName: () => mappingTransformFunctionName,
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
   storageConfigKeys: () => storageConfigKeys,
+  summarizeConnectorTriggerEvents: () => summarizeConnectorTriggerEvents,
   transformConnectionToEdge: () => transformConnectionToEdge,
   transformFlowToWorkflow: () => transformFlowToWorkflow,
   transformStepToNode: () => transformStepToNode,
+  validateConnectorTriggerEvents: () => validateConnectorTriggerEvents,
   validateEdge: () => validateEdge,
   validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
@@ -555,7 +561,7 @@ var connectorTriggerDefinition = {
         key: "events",
         label: "Events",
         type: "json" /* JSON */,
-        description: "Entity/operation pairs to subscribe to",
+        description: 'Entity/operation pairs to subscribe to, as [{ "entity": "contact", "operations": ["Create", "Update"] }]. ' + "This is what registers the trigger — the platform derives the flow's connector subscription from it. " + "Entity and operation names are per connector (describe_action_type lists them); a name outside that list never fires.",
         validation: { required: true }
       }
     ]
@@ -3974,6 +3980,124 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/triggers/connector-trigger/events.ts
+var EVENT_CAPABLE_CONNECTOR_IDS = new Set([
+  "quickbooks_online",
+  "shopify",
+  "hubspot",
+  "salesforce",
+  "google_sheets",
+  "whatsapp"
+]);
+var QBO_ENTITIES = [
+  { entity: "Invoice", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "Customer", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "Payment", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "Bill", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "Estimate", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "SalesReceipt", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "CreditMemo", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "Vendor", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "Item", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "Account", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "JournalEntry", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "PurchaseOrder", supportedOperations: ["Create", "Update", "Delete"] }
+];
+var SALESFORCE_ENTITIES = [
+  { entity: "Lead", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Account", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Contact", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Opportunity", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Case", supportedOperations: ["Create", "Update", "Delete", "Undelete"] }
+];
+var HUBSPOT_ENTITIES = [
+  { entity: "contact", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "company", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "deal", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "ticket", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "product", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "line_item", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "lead", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "quote", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "call", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "email", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "meeting_event", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "task", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "note", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "order", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "cart", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "invoice", supportedOperations: ["Create", "Update", "Delete"] }
+];
+var SHOPIFY_ENTITIES = [
+  { entity: "Order", supportedOperations: ["Create", "Update", "Paid", "Fulfilled", "Cancelled"] },
+  { entity: "Product", supportedOperations: ["Create", "Update"] },
+  { entity: "Customer", supportedOperations: ["Create", "Update"] }
+];
+var GOOGLE_SHEETS_ENTITIES = [
+  { entity: "Row", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "Sheet", supportedOperations: ["Create", "Update"] }
+];
+var WHATSAPP_ENTITIES = [
+  { entity: "Message", supportedOperations: ["Received"] }
+];
+var CONNECTOR_EVENT_ENTITIES = {
+  quickbooks_online: QBO_ENTITIES,
+  salesforce: SALESFORCE_ENTITIES,
+  hubspot: HUBSPOT_ENTITIES,
+  shopify: SHOPIFY_ENTITIES,
+  google_sheets: GOOGLE_SHEETS_ENTITIES,
+  whatsapp: WHATSAPP_ENTITIES
+};
+function getEntitiesForConnector(connectorId) {
+  return CONNECTOR_EVENT_ENTITIES[connectorId] ?? [];
+}
+function isEventCapableConnector(connectorId) {
+  return EVENT_CAPABLE_CONNECTOR_IDS.has(connectorId) && getEntitiesForConnector(connectorId).length > 0;
+}
+function summarizeConnectorTriggerEvents(connectorName, events) {
+  const eventCount = events.reduce((acc, ev) => acc + ev.operations.length, 0);
+  if (eventCount === 0)
+    return connectorName;
+  const noun = eventCount === 1 ? "event" : "events";
+  return `${connectorName} · ${eventCount} ${noun}`;
+}
+function validateConnectorTriggerEvents(connectorId, events) {
+  const entities = getEntitiesForConnector(connectorId);
+  if (!isEventCapableConnector(connectorId)) {
+    return `"${connectorId}" does not emit events a trigger can subscribe to. ` + `Event-capable connectors: ${[...EVENT_CAPABLE_CONNECTOR_IDS].join(", ")}.`;
+  }
+  if (!Array.isArray(events) || events.length === 0) {
+    return 'events must be a non-empty array of { "entity": string, "operations": string[] }.';
+  }
+  const seen = new Set;
+  for (const ev of events) {
+    const entity = ev?.entity;
+    const operations = ev?.operations;
+    if (typeof entity !== "string" || !entity) {
+      return 'Each event needs an "entity" (string).';
+    }
+    const known = entities.find((e) => e.entity === entity);
+    if (!known) {
+      const caseHit = entities.find((e) => e.entity.toLowerCase() === entity.toLowerCase());
+      const hint = caseHit ? ` Did you mean "${caseHit.entity}"? Names are case-sensitive.` : "";
+      return `Unknown entity "${entity}" for ${connectorId}.${hint} Entities: ${entities.map((e) => e.entity).join(", ")}.`;
+    }
+    if (seen.has(entity))
+      return `Entity "${entity}" is listed twice — give it one entry with all its operations.`;
+    seen.add(entity);
+    if (!Array.isArray(operations) || operations.length === 0) {
+      return `Event "${entity}" needs a non-empty "operations" array. Operations: ${known.supportedOperations.join(", ")}.`;
+    }
+    for (const op of operations) {
+      if (typeof op !== "string" || !known.supportedOperations.includes(op)) {
+        const caseHit = typeof op === "string" ? known.supportedOperations.find((o) => o.toLowerCase() === op.toLowerCase()) : undefined;
+        const hint = caseHit ? ` Did you mean "${caseHit}"?` : "";
+        return `Unknown operation "${String(op)}" for ${connectorId} ${entity}.${hint} Operations: ${known.supportedOperations.join(", ")}.`;
+      }
+    }
+  }
+  return null;
+}
 // src/catalog/workflow.ts
 var NodeStatus;
 ((NodeStatus) => {

package/dist/index.d.ts

@@ -40,6 +40,7 @@ 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 { CONNECTOR_EVENT_ENTITIES, EVENT_CAPABLE_CONNECTOR_IDS, getEntitiesForConnector, isEventCapableConnector, summarizeConnectorTriggerEvents, validateConnectorTriggerEvents, type ConnectorEventEntity, type ConnectorTriggerEvent, } from "./catalog/triggers/connector-trigger/events";
 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

@@ -441,7 +441,7 @@ var connectorTriggerDefinition = {
         key: "events",
         label: "Events",
         type: "json" /* JSON */,
-        description: "Entity/operation pairs to subscribe to",
+        description: 'Entity/operation pairs to subscribe to, as [{ "entity": "contact", "operations": ["Create", "Update"] }]. ' + "This is what registers the trigger — the platform derives the flow's connector subscription from it. " + "Entity and operation names are per connector (describe_action_type lists them); a name outside that list never fires.",
         validation: { required: true }
       }
     ]
@@ -3860,6 +3860,124 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/triggers/connector-trigger/events.ts
+var EVENT_CAPABLE_CONNECTOR_IDS = new Set([
+  "quickbooks_online",
+  "shopify",
+  "hubspot",
+  "salesforce",
+  "google_sheets",
+  "whatsapp"
+]);
+var QBO_ENTITIES = [
+  { entity: "Invoice", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "Customer", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "Payment", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "Bill", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "Estimate", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "SalesReceipt", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "CreditMemo", supportedOperations: ["Create", "Update", "Delete", "Void", "Emailed"] },
+  { entity: "Vendor", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "Item", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "Account", supportedOperations: ["Create", "Update", "Delete", "Merge"] },
+  { entity: "JournalEntry", supportedOperations: ["Create", "Update", "Delete", "Void"] },
+  { entity: "PurchaseOrder", supportedOperations: ["Create", "Update", "Delete"] }
+];
+var SALESFORCE_ENTITIES = [
+  { entity: "Lead", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Account", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Contact", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Opportunity", supportedOperations: ["Create", "Update", "Delete", "Undelete"] },
+  { entity: "Case", supportedOperations: ["Create", "Update", "Delete", "Undelete"] }
+];
+var HUBSPOT_ENTITIES = [
+  { entity: "contact", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "company", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "deal", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "ticket", supportedOperations: ["Create", "Update", "Delete", "Merge", "Restore", "AssociationChange"] },
+  { entity: "product", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "line_item", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "lead", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "quote", supportedOperations: ["Create", "Update", "Delete", "Restore"] },
+  { entity: "call", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "email", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "meeting_event", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "task", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "note", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "order", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "cart", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "invoice", supportedOperations: ["Create", "Update", "Delete"] }
+];
+var SHOPIFY_ENTITIES = [
+  { entity: "Order", supportedOperations: ["Create", "Update", "Paid", "Fulfilled", "Cancelled"] },
+  { entity: "Product", supportedOperations: ["Create", "Update"] },
+  { entity: "Customer", supportedOperations: ["Create", "Update"] }
+];
+var GOOGLE_SHEETS_ENTITIES = [
+  { entity: "Row", supportedOperations: ["Create", "Update", "Delete"] },
+  { entity: "Sheet", supportedOperations: ["Create", "Update"] }
+];
+var WHATSAPP_ENTITIES = [
+  { entity: "Message", supportedOperations: ["Received"] }
+];
+var CONNECTOR_EVENT_ENTITIES = {
+  quickbooks_online: QBO_ENTITIES,
+  salesforce: SALESFORCE_ENTITIES,
+  hubspot: HUBSPOT_ENTITIES,
+  shopify: SHOPIFY_ENTITIES,
+  google_sheets: GOOGLE_SHEETS_ENTITIES,
+  whatsapp: WHATSAPP_ENTITIES
+};
+function getEntitiesForConnector(connectorId) {
+  return CONNECTOR_EVENT_ENTITIES[connectorId] ?? [];
+}
+function isEventCapableConnector(connectorId) {
+  return EVENT_CAPABLE_CONNECTOR_IDS.has(connectorId) && getEntitiesForConnector(connectorId).length > 0;
+}
+function summarizeConnectorTriggerEvents(connectorName, events) {
+  const eventCount = events.reduce((acc, ev) => acc + ev.operations.length, 0);
+  if (eventCount === 0)
+    return connectorName;
+  const noun = eventCount === 1 ? "event" : "events";
+  return `${connectorName} · ${eventCount} ${noun}`;
+}
+function validateConnectorTriggerEvents(connectorId, events) {
+  const entities = getEntitiesForConnector(connectorId);
+  if (!isEventCapableConnector(connectorId)) {
+    return `"${connectorId}" does not emit events a trigger can subscribe to. ` + `Event-capable connectors: ${[...EVENT_CAPABLE_CONNECTOR_IDS].join(", ")}.`;
+  }
+  if (!Array.isArray(events) || events.length === 0) {
+    return 'events must be a non-empty array of { "entity": string, "operations": string[] }.';
+  }
+  const seen = new Set;
+  for (const ev of events) {
+    const entity = ev?.entity;
+    const operations = ev?.operations;
+    if (typeof entity !== "string" || !entity) {
+      return 'Each event needs an "entity" (string).';
+    }
+    const known = entities.find((e) => e.entity === entity);
+    if (!known) {
+      const caseHit = entities.find((e) => e.entity.toLowerCase() === entity.toLowerCase());
+      const hint = caseHit ? ` Did you mean "${caseHit.entity}"? Names are case-sensitive.` : "";
+      return `Unknown entity "${entity}" for ${connectorId}.${hint} Entities: ${entities.map((e) => e.entity).join(", ")}.`;
+    }
+    if (seen.has(entity))
+      return `Entity "${entity}" is listed twice — give it one entry with all its operations.`;
+    seen.add(entity);
+    if (!Array.isArray(operations) || operations.length === 0) {
+      return `Event "${entity}" needs a non-empty "operations" array. Operations: ${known.supportedOperations.join(", ")}.`;
+    }
+    for (const op of operations) {
+      if (typeof op !== "string" || !known.supportedOperations.includes(op)) {
+        const caseHit = typeof op === "string" ? known.supportedOperations.find((o) => o.toLowerCase() === op.toLowerCase()) : undefined;
+        const hint = caseHit ? ` Did you mean "${caseHit}"?` : "";
+        return `Unknown operation "${String(op)}" for ${connectorId} ${entity}.${hint} Operations: ${known.supportedOperations.join(", ")}.`;
+      }
+    }
+  }
+  return null;
+}
 // src/catalog/workflow.ts
 var NodeStatus;
 ((NodeStatus) => {
@@ -5067,9 +5185,11 @@ export {
   AggregateFunction,
   CONDITION_OPERATORS,
   CONFIG_CONTRACTS,
+  CONNECTOR_EVENT_ENTITIES,
   ConditionConfig,
   DATABASE_CONNECTOR_IDS,
   DebugConfig,
+  EVENT_CAPABLE_CONNECTOR_IDS,
   EdgeType,
   EmailConfig,
   FieldType,
@@ -5111,20 +5231,24 @@ export {
   getActionsByCategory,
   getAllActions,
   getEdgeValidationStatus,
+  getEntitiesForConnector,
   getNodeConfigStatus,
   getNodeValidationStatus,
   getStorageProvider,
   inferSchemaFromSample,
   isEditorPrivateKey,
+  isEventCapableConnector,
   isMappingFunction,
   isQueryableConnector,
   mappingTransformFunctionName,
   migrateDelayConfig,
   queryDefinition,
   storageConfigKeys,
+  summarizeConnectorTriggerEvents,
   transformConnectionToEdge,
   transformFlowToWorkflow,
   transformStepToNode,
+  validateConnectorTriggerEvents,
   validateEdge,
   validateFlowData,
   validateNode,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.9.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",
+  "version": "0.10.0",
+  "description": "The flow action catalog and the rules engine behind Flow Doctor — 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",
   "module": "./dist/index.js",