@uipath/maestro-builder-sdk 6.49.3 → 6.50.1

package/dist/serialize.js

@@ -18,8 +18,6 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
 import { resolveVersionCarried } from './core/nodes/versioned.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
-import { ConnectorResolveError } from './core/connector-resolve-error.js';
-import { synthesizedDefinitionRefusal } from './core/synthesized-definition.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
@@ -30,11 +28,10 @@ import { placeholderPosition } from './node-placement.js';
 import { hasExits } from './core/step-ports.js';
 import { stopsAtEnd } from './flow-step-tree.js';
 import { assertNodeEnvelope } from './core/node-envelope.js';
-import { buildConfiguration } from './core/connector-configuration.js';
 import { fnv1aX4Uuid, stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf, jmesString, jmesStringProblem } from './core/event-filters.js';
 import { FLOW_EXPR_DIALECT } from './core/connector-checks.js';
-import { buildConnectorInputs, connectorInputErrors as coreConnectorInputErrors, transportHttpMethod } from './core/connector-inputs.js';
+import { connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — Flow's binding of the shared validator.
@@ -118,48 +115,6 @@ const SUBFLOW_OUTPUT = {
     source: '=result.response',
     var: 'output',
 };
-/** The inline (autonomous) agent's node type — fixed, not per-instance. */
-/**
- * Declare a LIST operation's output as the ARRAY it is, when the ledger has
- * MEASURED that it is one ([#203](https://github.com/UiPath/flow-builder-sdk/issues/203)).
- *
- * Every connector definition declares `outputs.output.type: 'object'` — list
- * operations included, and **0 of 544 deployed connector nodes declare `array`
- * anywhere** (card CLEANUP's corpus scan). For most of the library that is the
- * honest thing to emit, because the SDK does not know better. For an operation in
- * the list-envelope ledger it does:
- *
- *   · `envelope: null` (a measured BARE array) ⇒ **`type: 'array'`**;
- *   · a measured WRAPPER ⇒ `object`, unchanged — the value IS an object then;
- *   · UNDECLARED ⇒ untouched, which is #202's status quo.
- *
- * Why this matters beyond tidiness: `typeAgentInputSchemas` builds an agent's
- * pydantic input model from these declarations, and card ga7's scored run r2 died
- * at `AGENT_STARTUP.INPUT_VALIDATION_ERROR` because a Data Service list node said
- * `object` and the runtime sent 8 rows. #202 made that property TYPELESS, which
- * unblocked the agent without asserting anything; this says the true thing.
- *
- * ## And deliberately NO item schema
- *
- * #203 suggested emitting the item fields alongside. They are not emitted, and the
- * reason is a measurement rather than caution: a list operation's declared fields
- * are **neither a superset nor a subset** of the real response (card LT, three live
- * responses — ServiceNow `incident` declares 0 of the 103 fields it returns; Entra
- * declares 20, returns 15, misses 2; Jira declares 253, returns 116, misses 42).
- * Asserting them into an agent's pydantic model would reject real rows — the exact
- * fault class above, moved rather than fixed. The library lift stays a READ-checking
- * aid, where it fails open by design (lesson 26). The emitted bytes claim only what
- * is certain: this is an array.
- */
-function declareListOutputType(node, rc) {
-    const declared = rc.listEnvelope;
-    if (!declared || declared.envelope !== null)
-        return;
-    const out = node.outputs?.output;
-    if (!out || typeof out !== 'object' || out.type !== 'object')
-        return;
-    out.type = 'array';
-}
 /**
  * Read a connector definition's connection requirements without collapsing
  * three distinct states:
@@ -315,8 +270,7 @@ function scheduleInputs(inputs, nodeId) {
         ...(isPreset ? {} : { timerValue: every }),
     };
 }
-/** A required connector input left empty — the one draft code with no error class of its own. */
-export const CONNECTOR_INPUT_MISSING = 'CONNECTOR_INPUT_MISSING';
+export { CONNECTOR_INPUT_MISSING } from './core/connector-inputs.js';
 /**
  * `serialize`, plus the extra files the flow needs on disk beside it.
  *
@@ -2346,6 +2300,14 @@ export function serialize(built, opts = {}) {
         if (impl.errorEnvelope)
             scope.rename.errorEnvelopes.set(step.name, impl.errorEnvelope);
         const rendered = new WeakSet();
+        // A rendered value's JSON copy, marked as the file's: placement writes it as
+        // is instead of rendering it again. Both renderers below go through it.
+        const fileCopy = (out) => {
+            const copy = jsonClone(out);
+            if (copy !== null && typeof copy === 'object')
+                rendered.add(copy);
+            return copy;
+        };
         const ctx = {
             step: step.name,
             nodeId: id,
@@ -2357,13 +2319,7 @@ export function serialize(built, opts = {}) {
                 // Only a `lit` unwraps to a new value. Its JSON copy is the file's: a
                 // copy, so an object the author also passes outside the `lit` is not
                 // mistaken for this one and still has its expressions rendered.
-                if (out !== value && out !== null && typeof out === 'object') {
-                    const copy = JSON.parse(JSON.stringify(out));
-                    if (copy !== null && typeof copy === 'object')
-                        rendered.add(copy);
-                    return copy;
-                }
-                return out;
+                return out !== value && out !== null && typeof out === 'object' ? fileCopy(out) : out;
             },
             renameRefs: (js) => renameRefs(js, scope.rename),
             stepNodeId: (name) => scope.stepNodeId.get(name) ?? name,
@@ -2397,9 +2353,34 @@ export function serialize(built, opts = {}) {
             resourceNodeId: (explicit, seed, at) => resourceNodeId(scope, explicit, seed, at),
             emitted: (typeName, v) => emittedDefs.get(`${typeName}@${v}`),
             library: opts.library,
+            // Rendered once: placement renders the contribution's inputs again, so the
+            // result is marked as the file's, as `render` marks a `lit`'s copy. A copy,
+            // so an author object the walk returned as is (a `lit`'s own) stays unmarked
+            // where it is also used outside the `lit`.
+            renderDeep: (value) => {
+                const out = renderDeep(value, scope.rename, rendered);
+                return out !== null && typeof out === 'object' ? fileCopy(out) : out;
+            },
+            drafting: opts.draft !== undefined,
+            draft: (code, message) => opts.draft?.({ nodeId: id, code: code, message }),
         };
         const bound = [];
         const contribution = impl.serialize(spec, ctx);
+        if (contribution.standIn !== undefined) {
+            // A draft stand-in: the node as the draft has it, with no definition to
+            // place it against (see FlowNodeContribution.standIn).
+            if (!ctx.drafting)
+                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName} returned a draft stand-in outside a draft compile.`);
+            const { type, typeVersion, inputs } = contribution.standIn;
+            scope.nodes.push({
+                id, type, typeVersion,
+                ...(parentId ? { parentId } : {}), display: { label: step.name },
+                inputs: { ...inputs },
+            });
+            for (const t of tails)
+                addEdge(scope, t, id);
+            return [{ node: id, port: contribution.port ?? 'output' }];
+        }
         // The definition contract, both halves: a per-tenant type supplies its
         // definition, and a bundled type does not (its definition is the bundle's, and
         // makeNode records it, so the error-edge refusal and check ask the same one).
@@ -2414,7 +2395,9 @@ export function serialize(built, opts = {}) {
         // instance's edits (a queue step's own resourceKey, for instance). Only a type
         // that supplies none at a carried version takes the carried definition as is.
         if (contribution.definition !== undefined) {
-            def = resolveContributionDefinition(contribution.definition, version, where);
+            // A type whose definition names its version is held to the author's pin by
+            // makeNode, with the message every definition's mismatch gets.
+            def = resolveContributionDefinition(contribution.definition, entry.type.versionedByDefinition ? undefined : version, where);
         }
         else if (impl.definition === 'per-tenant' && resolved.carried === undefined) {
             throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${version} returned no definition.`);
@@ -2436,14 +2419,14 @@ export function serialize(built, opts = {}) {
             // tenant definition (an inline agent at 1.1) may have no error handle.
             const port = resolved.carried !== undefined
                 ? definitionHasErrorPort(def ?? resolved.carried)
-                : typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
+                : typeof impl.errorPort === 'function' ? impl.errorPort(spec, def) : impl.errorPort === true;
             // The declaration answers for check, which has no definition; here the
             // definition is in hand, and the two must agree (#1011).
             if (port && def !== undefined && !definitionHasErrorPort(def)) {
                 throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} declares an error port, `
                     + 'but the definition it supplied has no error handle and no supportsErrorHandling.');
             }
-            declaredErrorPorts.set(id, { port, typeName: nodeType, version });
+            declaredErrorPorts.set(id, { port, typeName: nodeType, version: def?.version ?? version });
         }
         // A forward port is a handle the definition declares, one of the type's
         // author-named exits, or one the product derives (`derivesPort`: a human
@@ -2462,7 +2445,11 @@ export function serialize(built, opts = {}) {
         if (resolved.carried !== undefined)
             bundledNodeDefs.set(id, def ?? resolved.carried);
         return placeStepNode({
-            where, stepName: step.name, id, typeName: nodeType, requestedVersion: version, def, contribution, bound, tails, scope, parentId,
+            where, stepName: step.name, id, typeName: nodeType,
+            // A type whose definition names its version is placed at that version,
+            // held to the author's pin, as makeNode holds any definition to one.
+            requestedVersion: entry.type.versionedByDefinition ? step.options?.version : version,
+            def, contribution, bound, tails, scope, parentId,
             trackOutcomes: true,
             rendered,
         });
@@ -2501,129 +2488,6 @@ export function serialize(built, opts = {}) {
             subflows[id] = emitSubflowBody(spec.child, id);
             return [{ node: id, port: successPort(NODE_TYPE.subflow) }];
         }
-        if (spec.kind === 'connector') {
-            if (!opts.library)
-                throw new Error(`connector "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
-            let rc;
-            try {
-                rc = opts.library.resolve(spec.key, spec.action, spec.version, spec.object);
-            }
-            catch (error) {
-                if (!opts.draft || !(error instanceof ConnectorResolveError) || error.code !== 'CONNECTOR_OBJECT_REQUIRED')
-                    throw error;
-                // A generic operation saved before its object was picked has no
-                // definition to emit against. Draft tolerance emits a stable stand-in
-                // under the node's id; merge restores the original when it is untouched
-                // and refuses it otherwise.
-                const id = stepUid(scope, step.name);
-                opts.draft({ nodeId: id, code: error.code, message: error.message });
-                // It leaves on the port every connector action leaves on, so the
-                // no-edit round trip rewires nothing. Its inputs carry what the author
-                // wrote, so an edit to the node (an input, a connection) shows up as a
-                // change and merge refuses it instead of restoring the original.
-                const type = `uipath.connector.${spec.key}.${spec.action}`;
-                scope.nodes.push({
-                    id, type, typeVersion: spec.version ?? '1.0.0',
-                    ...(parentId ? { parentId } : {}), display: { label: step.name },
-                    inputs: {
-                        draft: true,
-                        spec: renderDeep(spec.inputs ?? {}, scope.rename),
-                        ...(spec.connection !== undefined ? { connection: spec.connection } : {}),
-                        ...(spec.folder !== undefined ? { folder: spec.folder } : {}),
-                    },
-                });
-                for (const t of tails)
-                    addEdge(scope, t, id);
-                return [{ node: id, port: successPort(type) }];
-            }
-            // An entry `prepare` synthesized from Integration Service compiles in BPMN only.
-            const noDefinition = synthesizedDefinitionRefusal(rc);
-            if (noDefinition)
-                throw noDefinition;
-            const id = stepUid(scope, step.name);
-            const node = makeNode(rc.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def: rc.v1def });
-            declareListOutputType(node, rc);
-            // A draft that names no connection gets no binding rows either: there
-            // is nothing to bind, and rows with an empty resourceKey would leak into
-            // the merged file through merge's bindings union.
-            let unbound = false;
-            try {
-                requireBindingPair(`connector "${step.name}"`, spec, { key: spec.key, action: spec.action });
-            }
-            catch (error) {
-                if (!opts.draft || !(error instanceof BindingRefusal))
-                    throw error;
-                opts.draft({ nodeId: id, code: error.code, message: error.message });
-                unbound = true;
-            }
-            const conn = resolveBinding(opts, spec.connection, 'connection', `connector "${step.name}"`, { key: spec.key, action: spec.action });
-            const folder = resolveBinding(opts, spec.folder, 'folder', `connector "${step.name}"`, { key: spec.key, action: spec.action });
-            // The platform reaches the connection through the flow's `bindings[]`,
-            // never through `inputs.detail` — without this pair the run faults with
-            // `[102010]` (board G-19; see connectionResourceBindings).
-            const { entries: connBindings } = connectionResourceBindings({ def: rc.v1def, connectorKey: rc.connectorKey, connectionId: conn, folderKey: folder }, resourceBindings);
-            if (!unbound)
-                for (const b of connBindings)
-                    resourceBindings.set(b.id, b);
-            const connectorInputs = buildConnectorInputs(rc, spec.inputs, {
-                ...(opts.draft
-                    ? { onMissingRequired: (m) => opts.draft({ nodeId: id, code: CONNECTOR_INPUT_MISSING, message: `connector ${rc.nodeType}: ${m}` }) }
-                    : {}),
-                dialect: FLOW_EXPR_DIALECT,
-                render: (value) => renderDeep(value, scope.rename),
-                resolutions: opts.library.lookupResolutions ?? {},
-                // Only for the missing-required hint; a test double that is not a full
-                // Library simply gets the plain message.
-                lookups: typeof opts.library.lookupSpecs === 'function'
-                    ? opts.library.lookupSpecs(spec.key, spec.action, spec.version, spec.object)
-                    : {},
-            });
-            const replayInputs = {
-                ...(connectorInputs.bodyParameters ?? {}),
-                ...(connectorInputs.pathParameters ?? {}),
-                ...(connectorInputs.queryParameters ?? {}),
-            };
-            const detail = {
-                connector: rc.connectorKey,
-                method: transportHttpMethod(rc.httpMethod),
-                endpoint: rc.endpoint,
-                // The op's object identity, as a SIBLING of the copy inside
-                // `configuration` — the designer emits both, and every connector node in
-                // a product-exported flow carries it (`curated_create_issue`,
-                // `Company__c`, `send_message_to_channel_v2` on the reference export).
-                // The event path already did; this action path had dropped it.
-                // Conditional because the library defaults a missing
-                // `operation.objectName` to '' — an op that names no object gets no key,
-                // not an empty one.
-                ...(rc.objectName ? { objectName: rc.objectName } : {}),
-                inputMetadata: {},
-                errorState: { hasError: false },
-                telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
-                configuration: buildConfiguration(rc.entry, rc.version, replayInputs, id),
-                ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
-                ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
-                ...(folder ? { connectionFolderKey: folder } : {}),
-            };
-            // Validate activity inputs against the connector's field list and place
-            // each one in the slot its LOCATION names — body → detail.bodyParameters,
-            // query → detail.queryParameters, path → detail.pathParameters, multipart
-            // → detail.multipartParameters (where the runtime looks) — so
-            // a schema-valid-but-contract-wrong connector node fails at compile with
-            // an actionable message instead of silently at run time.
-            //
-            // `bodyParameters` is emitted unconditionally, as it always has been (3 of
-            // 1,283 deployed connector nodes carry an empty one, so it is a legal
-            // shape); the other three appear only when the op has inputs there, which
-            // is the platform's dominant convention — of those 1,283 nodes, 899 omit
-            // `pathParameters` entirely and NONE carries an empty one. That also keeps
-            // every body-only connector's emission byte-identical to before.
-            Object.assign(detail, connectorInputs);
-            node.inputs = { detail };
-            scope.nodes.push(node);
-            for (const t of tails)
-                addEdge(scope, t, id);
-            return [{ node: id, port: successPort(rc.nodeType) }];
-        }
         if (spec.kind === 'waitEvent') {
             if (!opts.library)
                 throw new Error(`waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.49.3",
+  "version": "6.50.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "0187c4bea37cd0a8fd78aae6125b040583097f96"
+  "gitref": "3b0f8b3f6e84465828936a6242656c563947c74d"
 }