@octaviaflow/flow-rules 0.15.0 → 0.17.0

package/dist/catalog/general/transform/config.d.ts

@@ -26,6 +26,19 @@ export interface FieldMapping {
     depth?: number;
     /** With `groupBy`: this field goes into each line of the record's list, not the record (DEV-478). Root level only. */
     lineField?: boolean;
+    /**
+     * "Find by" (DEV-480): the mapped value names a record in the target app —
+     * the write uses the id of the `object` record whose `matchField` equals it.
+     * Root level only; on a line field it applies to each line. Odoo and QuickBooks (DEV-487).
+     */
+    lookup?: TransformLookup;
+}
+/** A record in the target app, found by one of its fields (DEV-480). */
+export interface TransformLookup {
+    /** The target app's object (Odoo model): res.partner, product.product. */
+    object: string;
+    /** The field the mapped value is matched against: email, default_code. Must be unique. */
+    matchField: string;
 }
 /**
  * One record per key (DEV-478): rows whose `key` resolves to the same value
@@ -33,10 +46,26 @@ export interface FieldMapping {
  * `lineField` become a list of line objects under `into`, in row order.
  */
 export interface TransformGroupBy {
-    /** Source expression of the key, written like a sourceField: `{{orders[].number}}`. */
-    key: string;
+    /** Source expression of the key, written like a sourceField: `{{orders[].number}}`. Optional with `linesFrom`. */
+    key?: string;
     /** Target field holding the list of lines: `line_items` (Shopify), `Line` (QuickBooks), `order_line` (Odoo). */
     into: string;
+    /**
+     * A list on each row that supplies its lines (DEV-484): `{{orders[].line_items}}`.
+     * Each element makes one line; a line field under the list
+     * (`{{orders[].line_items[].quantity}}`) reads the element, any other reads the row.
+     */
+    linesFrom?: string;
+}
+/**
+ * One row per element of a list on each row (DEV-484): an order becomes one
+ * row per line item, each carrying the order's fields.
+ */
+export interface TransformUnwind {
+    /** The list: `{{orders[].line_items}}`. */
+    path: string;
+    /** Keep a row whose list is empty, as one row with no element. Default false. */
+    keepEmpty?: boolean;
 }
 export type TransformMode = 'visual' | 'expression';
 /**
@@ -78,8 +107,10 @@ export interface TransformConfigType {
     /** Explicit upsert/update match field (legacy externalid/pkey). Empty =
      *  per-connector auto-detection (Mongo _id, SF Id, SQL primary key). */
     upsertMatchKey?: string;
-    /** One record per key, with the `lineField` mappings collected into a list (DEV-478). */
+    /** One record per key, or per row with lines from a list on it — the `lineField` mappings collected into a list (DEV-478, DEV-484). */
     groupBy?: TransformGroupBy;
+    /** One row per element of a list on each row, before mapping (DEV-484). */
+    unwind?: TransformUnwind;
     /** Ordered column header names — the exact columns + header text written. */
     sheetHeaders?: string[];
     /** Create the target tab on first write if it doesn't exist (default true). */
@@ -139,6 +170,11 @@ export declare const TransformConfig: {
             required: boolean;
             description: string;
         };
+        unwind: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
         expression: {
             type: string;
             required: boolean;

package/dist/catalog/logic/for-each/config.d.ts

@@ -50,7 +50,7 @@ export interface ForEachConfigType {
     /** dot-path on each item; items whose key was already seen are skipped. */
     idempotencyKeyPath?: string;
     /** how per-item results are collected (default 'array'). */
-    collect?: 'array' | 'none' | 'groupBy' | 'reduce';
+    collect?: 'array' | 'none' | 'groupBy' | 'reduce' | 'rows';
     /** groupBy — dot-path on each result used as the group key. */
     groupByPath?: string;
     /** reduce — built-in reduction over successful results. */
@@ -93,6 +93,12 @@ export declare const ForEachConfig: {
             type: string;
             required: boolean;
         };
+        collect: {
+            type: string;
+            required: boolean;
+            options: string[];
+            description: string;
+        };
     };
     validate: (config: Partial<ForEachConfigType>) => {
         valid: boolean;

package/dist/index.cjs

@@ -3340,7 +3340,13 @@ var ForEachConfig = {
     itemVariable: { type: "string", required: true },
     indexVariable: { type: "string", required: false },
     batchSize: { type: "number", required: false },
-    continueOnError: { type: "boolean", required: false }
+    continueOnError: { type: "boolean", required: false },
+    collect: {
+      type: "select",
+      required: false,
+      options: ["array", "none", "groupBy", "reduce", "rows"],
+      description: "What the Done port carries besides the counts: array (each iteration's result in `results`, the default), none, groupBy (by groupByPath), " + "reduce (reduceOp over reducePath), or rows — also `data`: every row the body produced (each iteration's Query/Transform rows, else its result), " + "so ONE step on the Done port maps and writes them all instead of a write per iteration."
+    }
   },
   validate: (config) => {
     const errors = [];
@@ -3725,6 +3731,34 @@ var TRANSFORM_OPERATIONS = [
 ];
 var TRANSFORM_OPERATION_IDS = TRANSFORM_OPERATIONS.map((o) => o.id);
 var DATABASE_CONNECTOR_IDS = new Set(["mongodb", "postgresql", "mysql", "google_sheets"]);
+function groupByErrors(config) {
+  const groupBy = config.groupBy;
+  if (!groupBy || !(groupBy.key || groupBy.into || groupBy.linesFrom))
+    return [];
+  const errors = [];
+  if (!groupBy.key && !groupBy.linesFrom) {
+    errors.push("One record per key: choose the key field (groupBy.key)");
+  }
+  if (!groupBy.into)
+    errors.push("One record per key: name the field that holds the lines (groupBy.into)");
+  if ((groupBy.key || groupBy.linesFrom) && groupBy.into && !(config.mappings ?? []).some((m) => m.lineField)) {
+    errors.push("One record per key: mark at least one mapping as a line field (lineField: true)");
+  }
+  return errors;
+}
+function unwindErrors(config) {
+  const unwind = config.unwind;
+  if (!unwind)
+    return [];
+  if (!unwind.path?.trim()) {
+    return unwind.keepEmpty !== undefined ? ["One row per item: choose the list (unwind.path)"] : [];
+  }
+  const linesFrom = config.groupBy?.linesFrom;
+  if (linesFrom && linesFrom.trim() === unwind.path.trim()) {
+    return ["One row per item and Lines come from name the same list — use one of them (unwind.path, groupBy.linesFrom)"];
+  }
+  return [];
+}
 var TransformConfig = {
   defaults: {
     name: "Transform",
@@ -3774,12 +3808,17 @@ var TransformConfig = {
     mappings: {
       type: "array",
       required: false,
-      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
     },
     groupBy: {
       type: "json",
       required: false,
-      description: 'One record per key, with line items: { "key": "{{orders[].number}}", "into": "line_items" }. Rows whose key is the same become ONE record ' + "(its fields from the first row); mappings with lineField: true become a list of lines under `into` (Shopify line_items, QuickBooks Line, Odoo order_line). " + "Dotted line fields nest inside each line (SalesItemLineDetail.ItemRef.value)."
+      description: "Records with line items; mappings with lineField: true become a list of lines under `into` (Shopify line_items, QuickBooks Line, Odoo order_line). " + 'Two ways, combinable: (1) the lines are flat rows — { "key": "{{orders[].number}}", "into": "order_line" }: rows with the same key become ONE record ' + '(its fields from the first row), one line per row; (2) the lines are a list INSIDE each row — { "into": "order_line", "linesFrom": "{{orders[].line_items}}" }: ' + "each row is one record and each element of the list one line; a line field under the list ({{orders[].line_items[].quantity}}) reads the element, " + "any other path reads the row. Dotted line fields nest inside each line (SalesItemLineDetail.ItemRef.value)."
+    },
+    unwind: {
+      type: "json",
+      required: false,
+      description: 'One row per element of a list on each row: { "path": "{{orders[].line_items}}", "keepEmpty": false }. Every mapping then reads the element under the ' + "list path ({{orders[].line_items[].sku}}) and the row everywhere else ({{orders[].name}}) — an order becomes one row per line, for targets that take " + "flat rows (Sheets, SQL). A row whose list is empty is dropped unless keepEmpty is true."
     },
     expression: { type: "code", required: false }
   },
@@ -3818,19 +3857,14 @@ var TransformConfig = {
           if (!mapping.targetField) {
             errors.push(`Mapping ${index + 1}: Target field is required`);
           }
+          const lookup = mapping.lookup;
+          if (lookup && (!lookup.object || !lookup.matchField)) {
+            errors.push(`Mapping ${index + 1}: Find by needs both the object and the field to match (lookup.object, lookup.matchField)`);
+          }
         });
       }
     }
-    const groupBy = config.groupBy;
-    if (groupBy && (groupBy.key || groupBy.into)) {
-      if (!groupBy.key)
-        errors.push("One record per key: choose the key field (groupBy.key)");
-      if (!groupBy.into)
-        errors.push("One record per key: name the field that holds the lines (groupBy.into)");
-      if (groupBy.key && groupBy.into && !(config.mappings ?? []).some((m) => m.lineField)) {
-        errors.push("One record per key: mark at least one mapping as a line field (lineField: true)");
-      }
-    }
+    errors.push(...groupByErrors(config), ...unwindErrors(config));
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {

package/dist/index.d.ts

@@ -36,7 +36,7 @@ export { EmailConfig, } from "./catalog/communication/email-send/config";
 export { queryDefinition, } from "./catalog/general/query/index";
 export { isQueryableConnector, } from "./catalog/general/query/config";
 export { AggregateFunction, type BuildQueryConfig, type ColumnSchema, type ConnectorSchema, JoinType, LogicalOperator, type QueryExecutionResult, type QueryField, type QueryFilter, type QueryFilterGroup, type QueryJoin, type QuerySort, SortDirection, type VisualQueryConfig, } from "./catalog/general/query/types";
-export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformOperation, } from "./catalog/general/transform/config";
+export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformLookup, type TransformUnwind, type TransformOperation, } from "./catalog/general/transform/config";
 export { AGGREGATE_FUNCTIONS, AGGREGATE_FUNCTION_DESCRIPTIONS, AggregateConfig, type AggregateConfigType, type AggregateFn, type AggregateMetric, type AggregateSchemaNode, groupKeyName, } from "./catalog/general/aggregate/config";
 export { detectRecordFields, resolveRecordSchema, type RecordSchemaLike, } from "./catalog/logic/for-each/recordSchema";
 export { STORAGE_CONNECTOR_IDS, type StorageExtraField, type StoragePathField, getStorageProvider, storageConfigKeys, } from "./catalog/storage/storageCapabilities";

package/dist/index.js

@@ -3182,7 +3182,13 @@ var ForEachConfig = {
     itemVariable: { type: "string", required: true },
     indexVariable: { type: "string", required: false },
     batchSize: { type: "number", required: false },
-    continueOnError: { type: "boolean", required: false }
+    continueOnError: { type: "boolean", required: false },
+    collect: {
+      type: "select",
+      required: false,
+      options: ["array", "none", "groupBy", "reduce", "rows"],
+      description: "What the Done port carries besides the counts: array (each iteration's result in `results`, the default), none, groupBy (by groupByPath), " + "reduce (reduceOp over reducePath), or rows — also `data`: every row the body produced (each iteration's Query/Transform rows, else its result), " + "so ONE step on the Done port maps and writes them all instead of a write per iteration."
+    }
   },
   validate: (config) => {
     const errors = [];
@@ -3567,6 +3573,34 @@ var TRANSFORM_OPERATIONS = [
 ];
 var TRANSFORM_OPERATION_IDS = TRANSFORM_OPERATIONS.map((o) => o.id);
 var DATABASE_CONNECTOR_IDS = new Set(["mongodb", "postgresql", "mysql", "google_sheets"]);
+function groupByErrors(config) {
+  const groupBy = config.groupBy;
+  if (!groupBy || !(groupBy.key || groupBy.into || groupBy.linesFrom))
+    return [];
+  const errors = [];
+  if (!groupBy.key && !groupBy.linesFrom) {
+    errors.push("One record per key: choose the key field (groupBy.key)");
+  }
+  if (!groupBy.into)
+    errors.push("One record per key: name the field that holds the lines (groupBy.into)");
+  if ((groupBy.key || groupBy.linesFrom) && groupBy.into && !(config.mappings ?? []).some((m) => m.lineField)) {
+    errors.push("One record per key: mark at least one mapping as a line field (lineField: true)");
+  }
+  return errors;
+}
+function unwindErrors(config) {
+  const unwind = config.unwind;
+  if (!unwind)
+    return [];
+  if (!unwind.path?.trim()) {
+    return unwind.keepEmpty !== undefined ? ["One row per item: choose the list (unwind.path)"] : [];
+  }
+  const linesFrom = config.groupBy?.linesFrom;
+  if (linesFrom && linesFrom.trim() === unwind.path.trim()) {
+    return ["One row per item and Lines come from name the same list — use one of them (unwind.path, groupBy.linesFrom)"];
+  }
+  return [];
+}
 var TransformConfig = {
   defaults: {
     name: "Transform",
@@ -3616,12 +3650,17 @@ var TransformConfig = {
     mappings: {
       type: "array",
       required: false,
-      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
     },
     groupBy: {
       type: "json",
       required: false,
-      description: 'One record per key, with line items: { "key": "{{orders[].number}}", "into": "line_items" }. Rows whose key is the same become ONE record ' + "(its fields from the first row); mappings with lineField: true become a list of lines under `into` (Shopify line_items, QuickBooks Line, Odoo order_line). " + "Dotted line fields nest inside each line (SalesItemLineDetail.ItemRef.value)."
+      description: "Records with line items; mappings with lineField: true become a list of lines under `into` (Shopify line_items, QuickBooks Line, Odoo order_line). " + 'Two ways, combinable: (1) the lines are flat rows — { "key": "{{orders[].number}}", "into": "order_line" }: rows with the same key become ONE record ' + '(its fields from the first row), one line per row; (2) the lines are a list INSIDE each row — { "into": "order_line", "linesFrom": "{{orders[].line_items}}" }: ' + "each row is one record and each element of the list one line; a line field under the list ({{orders[].line_items[].quantity}}) reads the element, " + "any other path reads the row. Dotted line fields nest inside each line (SalesItemLineDetail.ItemRef.value)."
+    },
+    unwind: {
+      type: "json",
+      required: false,
+      description: 'One row per element of a list on each row: { "path": "{{orders[].line_items}}", "keepEmpty": false }. Every mapping then reads the element under the ' + "list path ({{orders[].line_items[].sku}}) and the row everywhere else ({{orders[].name}}) — an order becomes one row per line, for targets that take " + "flat rows (Sheets, SQL). A row whose list is empty is dropped unless keepEmpty is true."
     },
     expression: { type: "code", required: false }
   },
@@ -3660,19 +3699,14 @@ var TransformConfig = {
           if (!mapping.targetField) {
             errors.push(`Mapping ${index + 1}: Target field is required`);
           }
+          const lookup = mapping.lookup;
+          if (lookup && (!lookup.object || !lookup.matchField)) {
+            errors.push(`Mapping ${index + 1}: Find by needs both the object and the field to match (lookup.object, lookup.matchField)`);
+          }
         });
       }
     }
-    const groupBy = config.groupBy;
-    if (groupBy && (groupBy.key || groupBy.into)) {
-      if (!groupBy.key)
-        errors.push("One record per key: choose the key field (groupBy.key)");
-      if (!groupBy.into)
-        errors.push("One record per key: name the field that holds the lines (groupBy.into)");
-      if (groupBy.key && groupBy.into && !(config.mappings ?? []).some((m) => m.lineField)) {
-        errors.push("One record per key: mark at least one mapping as a line field (lineField: true)");
-      }
-    }
+    errors.push(...groupByErrors(config), ...unwindErrors(config));
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {

package/package.json

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