@octaviaflow/flow-rules 0.21.0 → 0.22.0

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

@@ -67,6 +67,18 @@ export interface TransformUnwind {
     /** Keep a row whose list is empty, as one row with no element. Default false. */
     keepEmpty?: boolean;
 }
+/** How rows are written — the Transform panel's "Advanced options" (DEV-267/268). */
+export interface TransformWriteSettings {
+    /** Rows per write call. Empty = the connector's own default. */
+    batchSize?: number;
+    /** `continue` (default): failed rows are reported and the rest are written. `fail`: the step stops at the first failed row. */
+    onError?: 'continue' | 'fail';
+    /** Map and validate, write nothing. */
+    dryRun?: boolean;
+    /** Put the failed rows on the step's output. */
+    exposeFailedRows?: boolean;
+}
+export declare const TRANSFORM_ON_ERROR: readonly NonNullable<TransformWriteSettings['onError']>[];
 export type TransformMode = 'visual' | 'expression';
 /**
  * The authoring modes. `visual` is the Field Mapper and the only mode the panel
@@ -111,6 +123,8 @@ export interface TransformConfigType {
     groupBy?: TransformGroupBy;
     /** One row per element of a list on each row, before mapping (DEV-484). */
     unwind?: TransformUnwind;
+    /** How rows are written (the panel's "Advanced options", DEV-267/268). */
+    writeSettings?: TransformWriteSettings;
     /** 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 +153,16 @@ export declare const TransformConfig: {
             options: readonly TransformOperation[];
             description: string;
         };
+        upsertMatchKey: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        writeSettings: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
         connectorId: {
             type: string;
             required: boolean;

package/dist/index.cjs

@@ -107,6 +107,7 @@ __export(exports_src, {
   SortDirection: () => SortDirection,
   StorageActionConfig: () => StorageActionConfig,
   TRANSFORM_MODES: () => TRANSFORM_MODES,
+  TRANSFORM_ON_ERROR: () => TRANSFORM_ON_ERROR,
   TRANSFORM_OPERATIONS: () => TRANSFORM_OPERATIONS,
   TransformConfig: () => TransformConfig,
   USER_FUNCTION_PREFIX: () => USER_FUNCTION_PREFIX,
@@ -3387,6 +3388,7 @@ var WhatsappSendConfig = {
 };
 
 // src/catalog/general/transform/config.ts
+var TRANSFORM_ON_ERROR = ["continue", "fail"];
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [
   { id: "upsert", label: "Upsert" },
@@ -3411,6 +3413,21 @@ function groupByErrors(config) {
   }
   return errors;
 }
+function writeSettingsErrors(config) {
+  const ws = config.writeSettings;
+  if (ws === undefined || ws === null)
+    return [];
+  if (typeof ws !== "object" || Array.isArray(ws))
+    return ["Write settings must be an object (writeSettings)"];
+  const errors = [];
+  if (ws.onError !== undefined && !isOneOf(TRANSFORM_ON_ERROR, ws.onError)) {
+    errors.push(`Write settings: onError must be one of: ${TRANSFORM_ON_ERROR.join(", ")} (got "${String(ws.onError)}")`);
+  }
+  if (ws.batchSize !== undefined && !(Number.isInteger(ws.batchSize) && ws.batchSize > 0)) {
+    errors.push(`Write settings: batchSize must be a whole number above 0 (got "${String(ws.batchSize)}")`);
+  }
+  return errors;
+}
 function unwindErrors(config) {
   const unwind = config.unwind;
   if (!unwind)
@@ -3452,6 +3469,16 @@ var TransformConfig = {
       options: TRANSFORM_OPERATION_IDS,
       description: "What to do with each mapped record at the target: upsert, insert, update or delete"
     },
+    upsertMatchKey: {
+      type: "text",
+      required: false,
+      description: "For upsert and update: the TARGET field that says which existing record a row is (DEV-646). A row whose value matches a record updates it; " + "no match creates one (upsert). Empty = the connector decides: Salesforce Id, MongoDB _id, the SQL primary key. " + "A sync that may run more than once must upsert on a key that is stable and unique for the SOURCE record, or every run creates the records again. " + "Salesforce: the key must be an External ID field on the object (describe_connector_object) — mapping a source id into a normal field is not enough, and " + 'without one the upsert fails with "External ID is not found in record". If the object has no External ID field for this source, say so and ask the person: ' + "they create one in Salesforce (for example a HubSpot Contact Id text field marked External ID and Unique), or choose insert knowing re-runs duplicate."
+    },
+    writeSettings: {
+      type: "json",
+      required: false,
+      description: 'How rows are written: { "batchSize"?: number, "onError"?: "continue" | "fail", "dryRun"?: boolean, "exposeFailedRows"?: boolean }. ' + 'onError "continue" (the default) writes every row it can and reports the failures (the run ends as partial success); "fail" stops the step at the first failed row. ' + "dryRun maps and validates without writing."
+    },
     connectorId: { type: "connection", required: true },
     database: {
       type: "text",
@@ -3473,7 +3500,7 @@ 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. " + '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."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "targetField is the target app's own field name, normally one describe_connector_object lists; a name it does not list is written as given, so the field must exist in the target app (a custom field the person created). " + "A field the target requires (Salesforce Account Name) must be mapped, and a source value that can be empty needs a fallback or the row fails. " + "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",
@@ -3529,7 +3556,7 @@ var TransformConfig = {
         });
       }
     }
-    errors.push(...groupByErrors(config), ...unwindErrors(config));
+    errors.push(...groupByErrors(config), ...unwindErrors(config), ...writeSettingsErrors(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, queryFieldsSatisfied, queryTablesSatisfied, validateBuildQueryConfig, validateVisualConfig, QUERY_AUTHORED_SQL_MESSAGE, QUERY_VISUAL_ONLY_MESSAGE, } from "./catalog/general/query/config";
 export { type BuildQueryConfig, type ColumnSchema, type CompiledQuery, type Condition, type ConditionGroup, type ConditionRow, type ConnectorSchema, isConditionGroup, MAX_CONDITION_DEPTH, QUERY_AGGREGATE_FUNCTIONS, QUERY_COMPARISON_OPERATORS, QUERY_CONDITION_OPERATORS, QUERY_MODES, QUERY_RELATIVE_DATE_OPERATORS, QUERY_TYPES, type QueryAggregate, type QueryAggregateFn, type QueryComparisonOperator, type QueryConditionOperator, type QueryExecutionResult, type QueryJoin, type QueryJoinOperator, type QuerySort, RELATIVE_DATE_DIRECTIONS, RELATIVE_DATE_MAX_AMOUNT, RELATIVE_DATE_UNITS, type RelativeDate, type RelativeDateDirection, type RelativeDateUnit, SortDirection, type VisualConfigV2, type VisualQueryConfig, } from "./catalog/general/query/types";
-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 { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_ON_ERROR, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformLookup, type TransformUnwind, type TransformOperation, type TransformWriteSettings, } 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

@@ -3210,6 +3210,7 @@ var WhatsappSendConfig = {
 };
 
 // src/catalog/general/transform/config.ts
+var TRANSFORM_ON_ERROR = ["continue", "fail"];
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [
   { id: "upsert", label: "Upsert" },
@@ -3234,6 +3235,21 @@ function groupByErrors(config) {
   }
   return errors;
 }
+function writeSettingsErrors(config) {
+  const ws = config.writeSettings;
+  if (ws === undefined || ws === null)
+    return [];
+  if (typeof ws !== "object" || Array.isArray(ws))
+    return ["Write settings must be an object (writeSettings)"];
+  const errors = [];
+  if (ws.onError !== undefined && !isOneOf(TRANSFORM_ON_ERROR, ws.onError)) {
+    errors.push(`Write settings: onError must be one of: ${TRANSFORM_ON_ERROR.join(", ")} (got "${String(ws.onError)}")`);
+  }
+  if (ws.batchSize !== undefined && !(Number.isInteger(ws.batchSize) && ws.batchSize > 0)) {
+    errors.push(`Write settings: batchSize must be a whole number above 0 (got "${String(ws.batchSize)}")`);
+  }
+  return errors;
+}
 function unwindErrors(config) {
   const unwind = config.unwind;
   if (!unwind)
@@ -3275,6 +3291,16 @@ var TransformConfig = {
       options: TRANSFORM_OPERATION_IDS,
       description: "What to do with each mapped record at the target: upsert, insert, update or delete"
     },
+    upsertMatchKey: {
+      type: "text",
+      required: false,
+      description: "For upsert and update: the TARGET field that says which existing record a row is (DEV-646). A row whose value matches a record updates it; " + "no match creates one (upsert). Empty = the connector decides: Salesforce Id, MongoDB _id, the SQL primary key. " + "A sync that may run more than once must upsert on a key that is stable and unique for the SOURCE record, or every run creates the records again. " + "Salesforce: the key must be an External ID field on the object (describe_connector_object) — mapping a source id into a normal field is not enough, and " + 'without one the upsert fails with "External ID is not found in record". If the object has no External ID field for this source, say so and ask the person: ' + "they create one in Salesforce (for example a HubSpot Contact Id text field marked External ID and Unique), or choose insert knowing re-runs duplicate."
+    },
+    writeSettings: {
+      type: "json",
+      required: false,
+      description: 'How rows are written: { "batchSize"?: number, "onError"?: "continue" | "fail", "dryRun"?: boolean, "exposeFailedRows"?: boolean }. ' + 'onError "continue" (the default) writes every row it can and reports the failures (the run ends as partial success); "fail" stops the step at the first failed row. ' + "dryRun maps and validates without writing."
+    },
     connectorId: { type: "connection", required: true },
     database: {
       type: "text",
@@ -3296,7 +3322,7 @@ 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. " + '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."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "targetField is the target app's own field name, normally one describe_connector_object lists; a name it does not list is written as given, so the field must exist in the target app (a custom field the person created). " + "A field the target requires (Salesforce Account Name) must be mapped, and a source value that can be empty needs a fallback or the row fails. " + "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",
@@ -3352,7 +3378,7 @@ var TransformConfig = {
         });
       }
     }
-    errors.push(...groupByErrors(config), ...unwindErrors(config));
+    errors.push(...groupByErrors(config), ...unwindErrors(config), ...writeSettingsErrors(config));
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {
@@ -6243,6 +6269,7 @@ export {
   SortDirection,
   StorageActionConfig,
   TRANSFORM_MODES,
+  TRANSFORM_ON_ERROR,
   TRANSFORM_OPERATIONS,
   TransformConfig,
   USER_FUNCTION_PREFIX,

package/package.json

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