@octaviaflow/flow-rules 0.14.0 → 0.16.0

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

@@ -24,6 +24,32 @@ export interface FieldMapping {
     parentId?: string;
     /** Nesting depth (0 = root) */
     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 today.
+     */
+    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
+ * become one record (fields from the group's first row); the mappings marked
+ * `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;
+    /** Target field holding the list of lines: `line_items` (Shopify), `Line` (QuickBooks), `order_line` (Odoo). */
+    into: string;
 }
 export type TransformMode = 'visual' | 'expression';
 /**
@@ -65,6 +91,8 @@ 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). */
+    groupBy?: TransformGroupBy;
     /** 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). */
@@ -117,6 +145,12 @@ export declare const TransformConfig: {
         mappings: {
             type: string;
             required: boolean;
+            description: string;
+        };
+        groupBy: {
+            type: string;
+            required: boolean;
+            description: string;
         };
         expression: {
             type: string;

package/dist/index.cjs

@@ -3771,7 +3771,16 @@ var TransformConfig = {
       options: TRANSFORM_MODES,
       description: "How the mappings are authored: visual (the Field Mapper — the only mode the editor offers) or expression (legacy JavaScript). This is not the write mode; that is `operation`."
     },
-    mappings: { type: "array", required: false },
+    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. " + '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 only for now."
+    },
+    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)."
+    },
     expression: { type: "code", required: false }
   },
   generateName: (operation, connectorLabel, objectName) => {
@@ -3809,9 +3818,23 @@ 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)");
+      }
+    }
     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 TransformOperation, } from "./catalog/general/transform/config";
+export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformLookup, 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

@@ -3613,7 +3613,16 @@ var TransformConfig = {
       options: TRANSFORM_MODES,
       description: "How the mappings are authored: visual (the Field Mapper — the only mode the editor offers) or expression (legacy JavaScript). This is not the write mode; that is `operation`."
     },
-    mappings: { type: "array", required: false },
+    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. " + '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 only for now."
+    },
+    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)."
+    },
     expression: { type: "code", required: false }
   },
   generateName: (operation, connectorLabel, objectName) => {
@@ -3651,9 +3660,23 @@ 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)");
+      }
+    }
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {

package/package.json

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