@uipath/maestro-builder-sdk 6.6.1 → 6.8.0

package/dist/bpmn/typed-node.js

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module';
+import { resolveFromRegistry } from './registry-fallback.js';
 const require = createRequire(import.meta.url);
 const REGISTRY = require('./registry-types.json');
 /** Every extension type in the snapshot, sorted. */
@@ -8,19 +9,35 @@ export function registryTypeNames() {
 /**
  * The spec for one extension type.
  *
+ * Snapshot first — that is the offline, reviewable, common path, and a hit costs
+ * a property read. On a MISS the registry is asked directly through `uip`
+ * ({@link resolveFromRegistry}), because a snapshot is always behind the platform
+ * by however long it has been since the last refresh, and a type outside it used
+ * to be unauthorable rather than merely unsupported: the typed methods,
+ * `dist/api-members.md` and {@link registryTypeNames} are all generated from this
+ * same file, so an author had no way even to learn the name. Set
+ * `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep resolution snapshot-only.
+ *
  * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
  * @returns Its emission spec.
- * @throws If the type is not in the committed snapshot — which means either a
- * typo or a registry refresh the snapshot has not caught up with.
+ * @throws If the type is in neither the snapshot nor the registry — which means a
+ * typo, or no `uip` to ask.
  */
 export function registryType(type) {
-    const spec = REGISTRY.types[type];
+    const spec = REGISTRY.types[type] ?? resolveFromRegistry(type);
     if (!spec) {
-        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types; ` +
-            'refresh it with `node scripts/materialize-bpmn-registry.mjs` if the platform added one.');
+        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
+            + `(uip ${REGISTRY.provenance.uipVersion}) and the registry could not be asked for this one either — `
+            + 'no `uip` on PATH, not logged in, or the type does not exist. '
+            + 'Check the spelling with `uip maestro bpmn registry search <term>`, then refresh the snapshot with '
+            + '`node scripts/materialize-bpmn-registry.mjs`.');
     }
     return spec;
 }
+/** True when the snapshot itself carries the type — no tenant needed to emit it. */
+export function isSnapshotType(type) {
+    return Object.hasOwn(REGISTRY.types, type);
+}
 /**
  * Facts the platform enforces but the registry does not state.
  *

package/dist/check.js

@@ -116,7 +116,17 @@ function checkFlow(built, ancestors, opts = {}) {
     // decision waits until the expressions are collected (see
     // HITL_OUTCOMES_UNREACHABLE below).
     const hitlChoiceNoPorts = new Map();
-    const dataFabricUpdates = [];
+    // Data Fabric writes that target a record `{ fromRead: '<step>' }` — update and
+    // delete share the selector, so they share the check.
+    const dataFabricRefs = [];
+    // Delete step names. `core.datafabric.delete` is the one verb of the family
+    // whose definition declares NO outputDefinition, so `$vars.<delete>.output` is
+    // undefined at run time (see DATAFABRIC_DELETE_HAS_NO_OUTPUT below).
+    const dataFabricDeletes = new Set();
+    // Reads that return a LIST. A multi-record read is refused as a write target
+    // (see DATAFABRIC_FROMREAD_MULTIPLE below) — the serializer emits a plain
+    // no-op task for the write, and nothing at any rung reports it.
+    const dataFabricMultiReads = new Set();
     // Placeholder (`mock()`) step names. The platform's `core.logic.mock` declares
     // one output whose `source` is the literal `"null"` — it publishes nothing —
     // so `$vars.<mock>.output` is null at run time, always (see
@@ -435,24 +445,52 @@ function checkFlow(built, ancestors, opts = {}) {
                         });
                     }
                 }
-                if (s.spec.kind === 'dataFabricRead' || s.spec.kind === 'dataFabricUpdate') {
+                if (s.spec.kind === 'dataFabricRead' || s.spec.kind === 'dataFabricCreate'
+                    || s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
                     if (!String(s.spec.inputs.entity ?? '').trim()) {
                         diags.push({
                             level: 'error', code: 'DATAFABRIC_NO_ENTITY', step: s.name,
                             message: `"${s.name}" names no Data Fabric entity. Set { entity: '<entity name>' }.`,
                         });
                     }
+                    if (s.spec.kind === 'dataFabricRead') {
+                        dataFabricReads.add(s.name);
+                        if (s.spec.inputs.resultMode === 'multiple')
+                            dataFabricMultiReads.add(s.name);
+                        checkDataFabricQuery(s.name, s.spec.inputs, diags);
+                    }
+                    if (s.spec.kind === 'dataFabricCreate') {
+                        // Not the same failure as an empty update: a BLANK value is omitted
+                        // from the insert so the column default applies, so an all-blank
+                        // `fieldValues` serializes to an empty body and runs green having
+                        // inserted nothing. The node's schema rejects that — and the fix is
+                        // a real value, never a placeholder to satisfy the rule.
+                        const written = Object.values(s.spec.inputs.values ?? {})
+                            .filter((v) => (v instanceof Expr ? true : String(v ?? '').trim() !== ''));
+                        if (written.length === 0) {
+                            diags.push({
+                                level: 'error', code: 'DATAFABRIC_EMPTY_VALUES', step: s.name,
+                                message: `"${s.name}" sets no column to a non-blank value, so it would insert nothing and run green. `
+                                    + 'The node\'s schema rejects that — give a real column a real value rather than a placeholder.',
+                            });
+                        }
+                        checkDataFabricColumns(s.name, Object.keys(s.spec.inputs.values ?? {}), 'values', diags);
+                    }
                     if (s.spec.kind === 'dataFabricUpdate') {
-                        dataFabricUpdates.push({ step: s.name, inputs: s.spec.inputs });
                         if (Object.keys(s.spec.inputs.set ?? {}).length === 0) {
                             diags.push({
                                 level: 'error', code: 'DATAFABRIC_EMPTY_SET', step: s.name,
                                 message: `"${s.name}" writes no columns — { set } is empty, so the update would no-op green.`,
                             });
                         }
+                        checkDataFabricColumns(s.name, Object.keys(s.spec.inputs.set ?? {}), 'set', diags);
                     }
-                    else {
-                        dataFabricReads.add(s.name);
+                    checkDataFabricScope(s.name, s.spec.inputs, diags);
+                    if (s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
+                        const factory = s.spec.kind === 'dataFabricUpdate' ? 'dataFabricUpdate' : 'dataFabricDelete';
+                        dataFabricRefs.push({ step: s.name, factory, record: s.spec.inputs.record });
+                        if (s.spec.kind === 'dataFabricDelete')
+                            dataFabricDeletes.add(s.name);
                     }
                 }
                 if (s.spec.kind === 'ixpExtract')
@@ -729,12 +767,27 @@ function checkFlow(built, ancestors, opts = {}) {
         }
     }
     reportUnreachableHitlOutcomes(hitlChoiceNoPorts, exprs, diags);
-    for (const { step, inputs } of dataFabricUpdates) {
-        const fromRead = inputs.record?.fromRead;
-        if (typeof fromRead === 'string' && !dataFabricReads.has(fromRead)) {
+    for (const { step, factory, record } of dataFabricRefs) {
+        const fromRead = record?.fromRead;
+        if (typeof fromRead !== 'string')
+            continue;
+        if (!dataFabricReads.has(fromRead)) {
             diags.push({
                 level: 'error', code: 'DATAFABRIC_FROMREAD_UNKNOWN', step,
                 message: `"${step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but no dataFabricRead step has that name.`,
+                suggestion: `${factory}({ …, record: { byId: '<record id>' } })`,
+            });
+            continue;
+        }
+        // A LIST is not a write target: the serializer refuses it and emits a plain
+        // no-op task, so the flow validates, runs green, and writes nothing.
+        if (dataFabricMultiReads.has(fromRead)) {
+            diags.push({
+                level: 'error', code: 'DATAFABRIC_FROMREAD_MULTIPLE', step,
+                message: `"${step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but "${fromRead}" is a `
+                    + "resultMode: 'multiple' query. A multi-record read is refused as a write target — the step compiles to "
+                    + 'a no-op and the run goes green having written nothing.',
+                suggestion: `loop the results and target each record with ${factory}({ …, record: { byId: … } })`,
             });
         }
     }
@@ -1002,6 +1055,20 @@ function checkFlow(built, ancestors, opts = {}) {
                 });
                 continue;
             }
+            // A Data Fabric delete is the one verb of that family whose definition
+            // declares no outputDefinition at all — the record is gone, so there is
+            // nothing to publish. Read the record on the step that FOUND it instead,
+            // which on the `{ fromRead }` form is already in the flow.
+            if (dataFabricDeletes.has(name)) {
+                diags.push({
+                    level: 'error',
+                    code: 'DATAFABRIC_DELETE_HAS_NO_OUTPUT',
+                    message: `Delete "${name}" produces no output, but "$vars.${name}${field ? '.' + field : ''}" reads one in "${step}". `
+                        + 'A Data Fabric delete declares no outputs — take the value off the dataFabricRead step that found the record, before the delete.',
+                    step,
+                });
+                continue;
+            }
             if (delayNames.has(name)) {
                 diags.push({
                     level: 'error',
@@ -4635,6 +4702,102 @@ function checkCaseValueTypes(s, typeOf, diags, triggerId) {
  * `output` is the aggregate (after the loop) and `error` the failure detail.
  */
 const LOOP_FIELDS = new Set(['currentItem', 'currentIndex', 'collection', 'output', 'error']);
+/**
+ * Columns Data Fabric assigns and never accepts a write for.
+ *
+ * The canvas hides them from both write editors, but the serializer has no
+ * guard: a hand-authored `Id` row satisfies the node's own "at least one field"
+ * rule, ships in the body, and is rejected — and the rejection is only logged,
+ * so the row comes back unchanged and the run goes green.
+ */
+const DATAFABRIC_SYSTEM_COLUMNS = new Set(['Id', 'CreateTime', 'CreatedBy', 'UpdateTime', 'UpdatedBy']);
+function checkDataFabricColumns(step, columns, option, diags) {
+    const system = columns.filter((c) => DATAFABRIC_SYSTEM_COLUMNS.has(c));
+    if (system.length) {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_SYSTEM_COLUMN', step,
+            message: `"${step}" writes ${system.map((c) => JSON.stringify(c)).join(', ')} in { ${option} }. `
+                + 'Data Fabric assigns its system columns (Id, CreateTime, CreatedBy, UpdateTime, UpdatedBy) and rejects a '
+                + 'write to them — and it only LOGS the rejection, so the row comes back unchanged and the run goes green.',
+        });
+    }
+}
+/**
+ * A folder-scoped entity is portable only with its `Entity` bindings.
+ *
+ * `_folderKey` on its own still serializes — it falls back to a source-org
+ * literal and logs a warning — so the flow looks fine until it is deployed to
+ * another org. Refusing the half-authored pair here is the whole point: the
+ * alternative is a defect that only appears at deploy time, in a different org,
+ * to somebody else.
+ */
+function checkDataFabricScope(step, inputs, diags) {
+    if (inputs.folderKey !== undefined && inputs.resourceKey === undefined) {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_FOLDER_NO_RESOURCE_KEY', step,
+            message: `"${step}" sets { folderKey } without { resourceKey }. A folder-scoped entity needs both — with only `
+                + 'the folder key the entity serializes as a source-org literal, which validates, runs in this org, and '
+                + 'breaks on deploy to another one.',
+            suggestion: 'resolve the key with `uip solution resources list --kind Entity`, or drop { folderKey } and keep '
+                + 'the entity tenant-scoped',
+        });
+    }
+    if (inputs.resourceKey !== undefined && inputs.folderKey === undefined) {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_RESOURCE_KEY_NO_FOLDER', step,
+            message: `"${step}" sets { resourceKey } without { folderKey }. The pair exists to scope a FOLDER entity; a `
+                + 'tenant-scoped entity needs neither and serializes as a dotted literal.',
+        });
+    }
+}
+/**
+ * The query options, none of which the node's `inputDefinition` declares — they
+ * are `_`-prefixed extras, so `uip maestro flow validate` checks none of them
+ * and every mistake here is silent at run time.
+ */
+function checkDataFabricQuery(step, inputs, diags) {
+    const listOnly = ['limit', 'skip', 'sort', 'fields'].filter((k) => inputs[k] !== undefined);
+    if (listOnly.length && inputs.resultMode !== 'multiple') {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_QUERY_OPTS_WITHOUT_MULTIPLE', step,
+            message: `"${step}" sets { ${listOnly.join(', ')} }, which only a list query uses, but its resultMode is `
+                + `${inputs.resultMode ? JSON.stringify(inputs.resultMode) : 'unset (a single-record read)'}.`,
+            suggestion: "resultMode: 'multiple'",
+        });
+    }
+    // The emitted query ALWAYS carries a limit — omitted it resolves to 100 — and
+    // 1000 is a hard ceiling that TRUNCATES rather than erroring above it.
+    if (inputs.limit !== undefined && (!Number.isInteger(inputs.limit) || inputs.limit < 1 || inputs.limit > 1000)) {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_LIMIT_RANGE', step,
+            message: `"${step}": limit must be a whole number between 1 and 1000 (got ${inputs.limit}). 1000 is a hard `
+                + 'ceiling — a larger value truncates silently, so page with { skip } instead.',
+        });
+    }
+    // `in` is honoured only on a list query; on a single read the row compiles
+    // away, and a read whose filters compiled away returns EVERY record.
+    if (inputs.resultMode !== 'multiple' && (inputs.filters ?? []).some((f) => f.operator === 'in')) {
+        diags.push({
+            level: 'error', code: 'DATAFABRIC_IN_REQUIRES_MULTIPLE', step,
+            message: `"${step}" filters with the 'in' operator, which is honoured only when resultMode is 'multiple'. `
+                + 'On a single-record read that row compiles away — and a read whose filters compiled away matches every record.',
+        });
+    }
+    // A filter expression switched on and left blank is refused by the serializer,
+    // and it refuses the WHOLE query rather than dropping the row, which strands
+    // every downstream reference to this step.
+    for (const f of inputs.filters ?? []) {
+        const blank = f.value instanceof Expr ? f.value.js.trim() === '' : String(f.value ?? '').trim() === '';
+        if (blank) {
+            diags.push({
+                level: 'error', code: 'DATAFABRIC_FILTER_BLANK_VALUE', step,
+                message: `"${step}" has a filter on ${JSON.stringify(f.field)} with a blank value. The serializer refuses the `
+                    + 'ENTIRE query rather than dropping the row, so the step emits nothing and every downstream $vars read of '
+                    + 'it breaks.',
+            });
+        }
+    }
+}
 function collectActionExprs(s, out, errorSource) {
     const push = (val) => {
         if (val instanceof Expr && !val.literal)
@@ -4691,6 +4854,30 @@ function collectActionExprs(s, out, errorSource) {
             push(val);
         return;
     }
+    if (s.spec.kind === 'dataFabricRead' || s.spec.kind === 'dataFabricCreate'
+        || s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
+        // Every value a Data Fabric step carries is authored against flow scope: a
+        // filter's comparison value, the record id, the columns written. The family
+        // was missing here entirely, so a `$vars.` typo in any of them travelled to
+        // the platform unchecked — and the delete verb's no-output rule below has
+        // nothing to fire on until these are collected.
+        if (s.spec.kind === 'dataFabricRead') {
+            for (const f of s.spec.inputs.filters ?? [])
+                push(f.value);
+            return;
+        }
+        if (s.spec.kind === 'dataFabricCreate') {
+            for (const val of Object.values(s.spec.inputs.values ?? {}))
+                push(val);
+            return;
+        }
+        push(s.spec.inputs.record?.byId);
+        if (s.spec.kind === 'dataFabricUpdate') {
+            for (const val of Object.values(s.spec.inputs.set ?? {}))
+                push(val);
+        }
+        return;
+    }
     if (s.spec.kind === 'connector') {
         // Same gap on the connector surface: `messageToSend: tmpl`…${v('typo')}``
         // reached the runtime unchecked.