@octaviaflow/flow-rules 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -53,6 +53,9 @@ __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,
   QueryMode: () => QueryMode,
@@ -61,11 +64,13 @@ __export(exports_src, {
   SortDirection: () => SortDirection,
   TRANSFORM_OPERATIONS: () => TRANSFORM_OPERATIONS,
   TransformConfig: () => TransformConfig,
+  USER_FUNCTION_PREFIX: () => USER_FUNCTION_PREFIX,
   VariablesConfig: () => VariablesConfig,
   actionsRegistry: () => actionsRegistry,
   buildPathOptions: () => buildPathOptions,
   collectArrayPaths: () => collectArrayPaths,
   collectArrayPathsFromSample: () => collectArrayPathsFromSample,
+  configErrors: () => configErrors,
   emailDefinition: () => emailDefinition,
   flattenNestedWorkflow: () => flattenNestedWorkflow,
   generateConnectionsFromSteps: () => generateConnectionsFromSteps,
@@ -81,7 +86,9 @@ __export(exports_src, {
   getNodeValidationStatus: () => getNodeValidationStatus,
   getStorageProvider: () => getStorageProvider,
   inferSchemaFromSample: () => inferSchemaFromSample,
+  isMappingFunction: () => isMappingFunction,
   isQueryableConnector: () => isQueryableConnector,
+  mappingTransformFunctionName: () => mappingTransformFunctionName,
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
   storageConfigKeys: () => storageConfigKeys,
@@ -91,6 +98,8 @@ __export(exports_src, {
   validateEdge: () => validateEdge,
   validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
+  validateStepConfig: () => validateStepConfig,
+  validateStepConfigs: () => validateStepConfigs,
   validateWorkflow: () => validateWorkflow
 });
 module.exports = __toCommonJS(exports_src);
@@ -4093,3 +4102,240 @@ function validateFlowData(flow) {
   const f = flow;
   return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
 }
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+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

@@ -43,3 +43,5 @@ export { type ManualTriggerConfigType } from "./catalog/triggers/manual-trigger/
 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

@@ -3996,6 +3996,243 @@ function validateFlowData(flow) {
   const f = flow;
   return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
 }
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+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,
@@ -4011,6 +4248,9 @@ export {
   ForEachConfig,
   JoinType,
   LogicalOperator,
+  MAPPING_FUNCTIONS,
+  MAPPING_FUNCTION_SPECS,
+  MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig,
   NodeStatus,
   QueryMode,
@@ -4019,11 +4259,13 @@ export {
   SortDirection,
   TRANSFORM_OPERATIONS,
   TransformConfig,
+  USER_FUNCTION_PREFIX,
   VariablesConfig,
   actionsRegistry,
   buildPathOptions,
   collectArrayPaths,
   collectArrayPathsFromSample,
+  configErrors,
   emailDefinition,
   flattenNestedWorkflow,
   generateConnectionsFromSteps,
@@ -4039,7 +4281,9 @@ export {
   getNodeValidationStatus,
   getStorageProvider,
   inferSchemaFromSample,
+  isMappingFunction,
   isQueryableConnector,
+  mappingTransformFunctionName,
   migrateDelayConfig,
   queryDefinition,
   storageConfigKeys,
@@ -4049,5 +4293,7 @@ export {
   validateEdge,
   validateFlowData,
   validateNode,
+  validateStepConfig,
+  validateStepConfigs,
   validateWorkflow
 };

package/dist/rules/configSafety.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a step's config may contain, enforced where a caller cannot skip it.
+ *
+ * The editor's rules run in a browser, so they are advice, not a fence. A
+ * request posted straight at the API — or modified on its way — reaches
+ * `PUT /flows/:id/workflow`, which validated STRUCTURE (ids, connections,
+ * cycles) and typed config as `z.record(z.string(), z.unknown())`. Any key,
+ * any value, stored verbatim.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: treat `inputSchema.fields` as an
+ * allow-list. Measured against the real estate, 71 of 131 distinct config
+ * keys in use are not declared there — `slack_message.text`,
+ * `query.visualConfig`, `transform.operation`, `flowId` on nearly every
+ * action. `inputSchema` describes the fields the config PANEL renders, and
+ * every action with a custom panel stores more than that. Rejecting undeclared
+ * keys would refuse most flows on the platform. So an unknown key is a
+ * WARNING, never an error.
+ *
+ * What it does enforce is the part a legitimate client never violates:
+ *
+ *   1. a declared field's declared TYPE;
+ *   2. keys that can poison an object prototype;
+ *   3. a size and depth bound, because a config is a form's worth of settings
+ *      and an unbounded one is a document every reader of that flow pays for
+ *      (the DEV-366 problem, in a different field).
+ *
+ * Every one of those was dry-run against all 295 steps of the 77 flows on
+ * beta before it was allowed to block anything: 0 oversized (largest 28 KB
+ * against a 256 KB cap), 0 deeper than 6 (limit 12), 0 forbidden keys, 0 type
+ * mismatches. A rule that refuses data the platform already holds is not a
+ * fence, it is an outage.
+ *
+ * An enumerated field's options are checked but only WARN, for the same
+ * reason — see the note at that check.
+ */
+/** Largest config a single step may carry, serialised. */
+export declare const MAX_STEP_CONFIG_BYTES: number;
+export type ConfigIssueCode = "FORBIDDEN_KEY" | "CONFIG_TOO_LARGE" | "CONFIG_TOO_DEEP" | "FIELD_WRONG_TYPE" | "FIELD_BAD_OPTION" | "UNDECLARED_FIELD";
+export interface ConfigIssue {
+    severity: "error" | "warning";
+    code: ConfigIssueCode;
+    stepId: string;
+    /** The config key, when the issue is about one. */
+    field?: string;
+    message: string;
+}
+export interface StepLike {
+    id?: unknown;
+    actionDefinitionId?: unknown;
+    config?: unknown;
+}
+/**
+ * Check one step's config.
+ *
+ * Errors block a save. Warnings never do — see the file header on why an
+ * undeclared key cannot be an error.
+ */
+export declare function validateStepConfig(step: StepLike): ConfigIssue[];
+/** Every step of a workflow. `steps` may be nested; flatten before calling. */
+export declare function validateStepConfigs(steps: readonly StepLike[]): ConfigIssue[];
+/** Just the blocking ones — what a save path refuses on. */
+export declare function configErrors(steps: readonly StepLike[]): ConfigIssue[];

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.5.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",