@octaviaflow/flow-rules 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -53,6 +53,8 @@ __export(exports_src, {
   ForEachConfig: () => ForEachConfig,
   JoinType: () => JoinType,
   LogicalOperator: () => LogicalOperator,
+  MAPPING_FUNCTIONS: () => MAPPING_FUNCTIONS,
+  MAPPING_FUNCTION_SPECS: () => MAPPING_FUNCTION_SPECS,
   MAX_STEP_CONFIG_BYTES: () => MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
@@ -62,6 +64,7 @@ __export(exports_src, {
   SortDirection: () => SortDirection,
   TRANSFORM_OPERATIONS: () => TRANSFORM_OPERATIONS,
   TransformConfig: () => TransformConfig,
+  USER_FUNCTION_PREFIX: () => USER_FUNCTION_PREFIX,
   VariablesConfig: () => VariablesConfig,
   actionsRegistry: () => actionsRegistry,
   buildPathOptions: () => buildPathOptions,
@@ -83,7 +86,9 @@ __export(exports_src, {
   getNodeValidationStatus: () => getNodeValidationStatus,
   getStorageProvider: () => getStorageProvider,
   inferSchemaFromSample: () => inferSchemaFromSample,
+  isMappingFunction: () => isMappingFunction,
   isQueryableConnector: () => isQueryableConnector,
+  mappingTransformFunctionName: () => mappingTransformFunctionName,
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
   storageConfigKeys: () => storageConfigKeys,
@@ -4252,3 +4257,85 @@ function validateStepConfigs(steps) {
 function configErrors(steps) {
   return validateStepConfigs(steps).filter((i) => i.severity === "error");
 }
+// src/rules/mappingFunctions.ts
+var str = (v) => String(v ?? "");
+var HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+var MAPPING_FUNCTIONS = {
+  concat: (...args) => args.map((a) => a == null ? "" : String(a)).join(""),
+  uppercase: (val) => str(val).toUpperCase(),
+  lowercase: (val) => str(val).toLowerCase(),
+  trim: (val) => str(val).trim(),
+  parseDate: (val) => {
+    const d = new Date(String(val));
+    return isNaN(d.getTime()) ? null : d.toISOString();
+  },
+  parseNumber: (val) => {
+    const n = Number(val);
+    return isNaN(n) ? null : n;
+  },
+  toString: (val) => str(val),
+  substring: (val, start, end) => {
+    const s = str(val);
+    return s.substring(Number(start) || 0, end !== undefined ? Number(end) : undefined);
+  },
+  replace: (val, search, replacement) => str(val).replace(String(search), String(replacement)),
+  default: (val, fallback) => val == null || val === "" ? fallback : val,
+  normalizeUrl: (val, scheme = "https") => {
+    const s = str(val).trim();
+    if (!s)
+      return "";
+    if (HAS_SCHEME.test(s))
+      return s;
+    return `${String(scheme || "https")}://${s}`;
+  },
+  normalizeEmail: (val) => str(val).trim().toLowerCase(),
+  normalizePhone: (val, countryCode) => {
+    const raw = str(val).trim();
+    if (!raw)
+      return "";
+    const plus = raw.startsWith("+");
+    const digits = raw.replace(/\D/g, "");
+    if (!digits)
+      return "";
+    if (plus)
+      return `+${digits}`;
+    const cc = str(countryCode).replace(/\D/g, "");
+    return cc ? `+${cc}${digits}` : digits;
+  },
+  toDateOnly: (val) => {
+    const d = new Date(String(val));
+    return isNaN(d.getTime()) ? null : d.toISOString().slice(0, 10);
+  }
+};
+var MAPPING_FUNCTION_SPECS = [
+  { name: "concat", signature: 'concat(value, "text", …)', description: "Joins the value and any literals into one string.", example: 'concat(value, " Ltd")' },
+  { name: "uppercase", signature: "uppercase(value)", description: "Upper-cases the value.", example: "uppercase(value)" },
+  { name: "lowercase", signature: "lowercase(value)", description: "Lower-cases the value.", example: "lowercase(value)" },
+  { name: "trim", signature: "trim(value)", description: "Removes leading and trailing whitespace.", example: "trim(value)" },
+  { name: "parseDate", signature: "parseDate(value)", description: "Parses to a full ISO timestamp, or null if unparseable.", example: "parseDate(value)" },
+  { name: "parseNumber", signature: "parseNumber(value)", description: "Parses to a number, or null if not numeric.", example: "parseNumber(value)" },
+  { name: "toString", signature: "toString(value)", description: 'Renders the value as a string ("" when empty).', example: "toString(value)" },
+  { name: "substring", signature: "substring(value, start, end?)", description: "Takes part of the value by index.", example: "substring(value, 0, 10)" },
+  { name: "replace", signature: 'replace(value, "find", "with")', description: "Replaces the first match.", example: 'replace(value, "Inc", "Inc.")' },
+  { name: "default", signature: 'default(value, "fallback")', description: "Uses the fallback when the value is empty or missing.", example: 'default(value, "Unknown")' },
+  { name: "normalizeUrl", signature: "normalizeUrl(value, scheme?)", description: "Adds https:// when the value names no scheme. Leaves http://, mailto: and others alone.", example: "normalizeUrl(value)" },
+  { name: "normalizeEmail", signature: "normalizeEmail(value)", description: "Trims and lower-cases an address.", example: "normalizeEmail(value)" },
+  { name: "normalizePhone", signature: "normalizePhone(value, countryCode?)", description: "Strips punctuation to digits, keeping a leading +. With a country code, prefixes numbers that lack one.", example: 'normalizePhone(value, "+1")' },
+  { name: "toDateOnly", signature: "toDateOnly(value)", description: "Reduces a timestamp to YYYY-MM-DD in UTC.", example: "toDateOnly(value)" }
+];
+var USER_FUNCTION_PREFIX = "user.";
+function isMappingFunction(name) {
+  if (!name)
+    return false;
+  if (name.startsWith(USER_FUNCTION_PREFIX))
+    return name.length > USER_FUNCTION_PREFIX.length;
+  return Object.hasOwn(MAPPING_FUNCTIONS, name);
+}
+function mappingTransformFunctionName(transform) {
+  const trimmed = (transform ?? "").trim();
+  if (!trimmed)
+    return null;
+  const normalised = /^[A-Za-z_][\w.]*$/.test(trimmed) ? `${trimmed}(value)` : trimmed;
+  const match = normalised.match(/^([A-Za-z_][\w.]*)\((.*)\)$/s);
+  return match ? match[1] : null;
+}

package/dist/index.d.ts

@@ -44,3 +44,4 @@ export * from "./catalog/workflow";
 export { type FlowConnection, type FlowData, type FlowStep, generateConnectionsFromSteps, transformConnectionToEdge, transformFlowToWorkflow, transformStepToNode, validateFlowData, } from "./rules/flowShape";
 export { flattenNestedWorkflow } from "./rules/flattenNestedWorkflow";
 export { configErrors, MAX_STEP_CONFIG_BYTES, validateStepConfig, validateStepConfigs, type ConfigIssue, type ConfigIssueCode, } from "./rules/configSafety";
+export { isMappingFunction, MAPPING_FUNCTION_SPECS, MAPPING_FUNCTIONS, mappingTransformFunctionName, USER_FUNCTION_PREFIX, type MappingFunction, type MappingFunctionSpec, } from "./rules/mappingFunctions";

package/dist/index.js

@@ -4151,6 +4151,88 @@ function validateStepConfigs(steps) {
 function configErrors(steps) {
   return validateStepConfigs(steps).filter((i) => i.severity === "error");
 }
+// src/rules/mappingFunctions.ts
+var str = (v) => String(v ?? "");
+var HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+var MAPPING_FUNCTIONS = {
+  concat: (...args) => args.map((a) => a == null ? "" : String(a)).join(""),
+  uppercase: (val) => str(val).toUpperCase(),
+  lowercase: (val) => str(val).toLowerCase(),
+  trim: (val) => str(val).trim(),
+  parseDate: (val) => {
+    const d = new Date(String(val));
+    return isNaN(d.getTime()) ? null : d.toISOString();
+  },
+  parseNumber: (val) => {
+    const n = Number(val);
+    return isNaN(n) ? null : n;
+  },
+  toString: (val) => str(val),
+  substring: (val, start, end) => {
+    const s = str(val);
+    return s.substring(Number(start) || 0, end !== undefined ? Number(end) : undefined);
+  },
+  replace: (val, search, replacement) => str(val).replace(String(search), String(replacement)),
+  default: (val, fallback) => val == null || val === "" ? fallback : val,
+  normalizeUrl: (val, scheme = "https") => {
+    const s = str(val).trim();
+    if (!s)
+      return "";
+    if (HAS_SCHEME.test(s))
+      return s;
+    return `${String(scheme || "https")}://${s}`;
+  },
+  normalizeEmail: (val) => str(val).trim().toLowerCase(),
+  normalizePhone: (val, countryCode) => {
+    const raw = str(val).trim();
+    if (!raw)
+      return "";
+    const plus = raw.startsWith("+");
+    const digits = raw.replace(/\D/g, "");
+    if (!digits)
+      return "";
+    if (plus)
+      return `+${digits}`;
+    const cc = str(countryCode).replace(/\D/g, "");
+    return cc ? `+${cc}${digits}` : digits;
+  },
+  toDateOnly: (val) => {
+    const d = new Date(String(val));
+    return isNaN(d.getTime()) ? null : d.toISOString().slice(0, 10);
+  }
+};
+var MAPPING_FUNCTION_SPECS = [
+  { name: "concat", signature: 'concat(value, "text", …)', description: "Joins the value and any literals into one string.", example: 'concat(value, " Ltd")' },
+  { name: "uppercase", signature: "uppercase(value)", description: "Upper-cases the value.", example: "uppercase(value)" },
+  { name: "lowercase", signature: "lowercase(value)", description: "Lower-cases the value.", example: "lowercase(value)" },
+  { name: "trim", signature: "trim(value)", description: "Removes leading and trailing whitespace.", example: "trim(value)" },
+  { name: "parseDate", signature: "parseDate(value)", description: "Parses to a full ISO timestamp, or null if unparseable.", example: "parseDate(value)" },
+  { name: "parseNumber", signature: "parseNumber(value)", description: "Parses to a number, or null if not numeric.", example: "parseNumber(value)" },
+  { name: "toString", signature: "toString(value)", description: 'Renders the value as a string ("" when empty).', example: "toString(value)" },
+  { name: "substring", signature: "substring(value, start, end?)", description: "Takes part of the value by index.", example: "substring(value, 0, 10)" },
+  { name: "replace", signature: 'replace(value, "find", "with")', description: "Replaces the first match.", example: 'replace(value, "Inc", "Inc.")' },
+  { name: "default", signature: 'default(value, "fallback")', description: "Uses the fallback when the value is empty or missing.", example: 'default(value, "Unknown")' },
+  { name: "normalizeUrl", signature: "normalizeUrl(value, scheme?)", description: "Adds https:// when the value names no scheme. Leaves http://, mailto: and others alone.", example: "normalizeUrl(value)" },
+  { name: "normalizeEmail", signature: "normalizeEmail(value)", description: "Trims and lower-cases an address.", example: "normalizeEmail(value)" },
+  { name: "normalizePhone", signature: "normalizePhone(value, countryCode?)", description: "Strips punctuation to digits, keeping a leading +. With a country code, prefixes numbers that lack one.", example: 'normalizePhone(value, "+1")' },
+  { name: "toDateOnly", signature: "toDateOnly(value)", description: "Reduces a timestamp to YYYY-MM-DD in UTC.", example: "toDateOnly(value)" }
+];
+var USER_FUNCTION_PREFIX = "user.";
+function isMappingFunction(name) {
+  if (!name)
+    return false;
+  if (name.startsWith(USER_FUNCTION_PREFIX))
+    return name.length > USER_FUNCTION_PREFIX.length;
+  return Object.hasOwn(MAPPING_FUNCTIONS, name);
+}
+function mappingTransformFunctionName(transform) {
+  const trimmed = (transform ?? "").trim();
+  if (!trimmed)
+    return null;
+  const normalised = /^[A-Za-z_][\w.]*$/.test(trimmed) ? `${trimmed}(value)` : trimmed;
+  const match = normalised.match(/^([A-Za-z_][\w.]*)\((.*)\)$/s);
+  return match ? match[1] : null;
+}
 export {
   ActionCategory,
   ActionStatus,
@@ -4166,6 +4248,8 @@ export {
   ForEachConfig,
   JoinType,
   LogicalOperator,
+  MAPPING_FUNCTIONS,
+  MAPPING_FUNCTION_SPECS,
   MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig,
   NodeStatus,
@@ -4175,6 +4259,7 @@ export {
   SortDirection,
   TRANSFORM_OPERATIONS,
   TransformConfig,
+  USER_FUNCTION_PREFIX,
   VariablesConfig,
   actionsRegistry,
   buildPathOptions,
@@ -4196,7 +4281,9 @@ export {
   getNodeValidationStatus,
   getStorageProvider,
   inferSchemaFromSample,
+  isMappingFunction,
   isQueryableConnector,
+  mappingTransformFunctionName,
   migrateDelayConfig,
   queryDefinition,
   storageConfigKeys,

package/dist/rules/mappingFunctions.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The functions a Field Mapper `transform` may call — implementations AND the
+ * list, in one place.
+ *
+ * WHY THIS EXISTS. A Transform step's mapping has two slots, and they are not
+ * interchangeable:
+ *
+ *   sourceField  names a FIELD          `{{Website}}`
+ *   transform    transforms the VALUE   `uppercase(value)`
+ *
+ * Neither one evaluates an expression. `sourceField` is a literal path lookup,
+ * and `transform` is a single function call — so anything clever written in
+ * either resolves to nothing. Both failure modes were silent: a bad
+ * `sourceField` wrote an EMPTY value on every record, and an unknown
+ * `transform` function returned the source value unchanged, with a comment in
+ * the engine that said so out loud ("an unknown built-in falls through
+ * silently"). An agent hit the first one and blanked a field on every customer
+ * a live flow synced.
+ *
+ * Shipping the list without the implementations would just move the drift: the
+ * UI's FX sidebar already advertises 99 functions while the engine's mapping
+ * executor accepted 10, and four of those ten were not in the sidebar at all.
+ * So this module owns BOTH. One import, nothing to keep in step.
+ *
+ * ADDING ONE: put it in `MAPPING_FUNCTIONS` with a `MAPPING_FUNCTION_SPECS`
+ * entry. The spec is what the editor lists and what an agent is shown, so a
+ * function without one is invisible and effectively does not exist.
+ */
+/** A value-transform. `value` is the resolved source; the rest are literals. */
+export type MappingFunction = (...args: unknown[]) => unknown;
+export interface MappingFunctionSpec {
+    name: string;
+    /** How it is written, for the picker and for an agent's tool description. */
+    signature: string;
+    description: string;
+    example: string;
+}
+export declare const MAPPING_FUNCTIONS: Record<string, MappingFunction>;
+export declare const MAPPING_FUNCTION_SPECS: readonly MappingFunctionSpec[];
+/** Custom functions are written by the workspace and resolved at run time. */
+export declare const USER_FUNCTION_PREFIX = "user.";
+/**
+ * Is this a function a mapping may call?
+ *
+ * `user.*` is accepted on name alone — the workspace's own functions are
+ * resolved from a registry at run time, and this module cannot know them.
+ */
+export declare function isMappingFunction(name: string): boolean;
+/**
+ * The function a `transform` calls, or `null` when it is not a call at all.
+ *
+ * Mirrors the engine's parsing exactly, including the back-compat shim: a BARE
+ * name (`uppercase`) means `uppercase(value)`, because older saved mappings
+ * persisted just the name.
+ */
+export declare function mappingTransformFunctionName(transform: string): string | null;

package/package.json

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