@uipath/maestro-builder-sdk 6.14.2 → 6.14.3

package/dist/core/node-envelope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The node envelope: the fields `uip maestro flow validate` requires on EVERY
+ * entry of a `.flow` file's `nodes[]` (root and every `subflows.<id>.nodes[]`),
+ * whatever its type.
+ *
+ * Mirrors the platform's file-format node schema (`@uipath/flow-schema`
+ * `fileFormatNodeSchema`, bundled into the CLI's flow tool):
+ *
+ * ```ts
+ * id:          z.string().min(1)
+ * type:        z.string().min(1)
+ * typeVersion: z.string().regex(/^\d+\.\d+(\.\d+)?$/)
+ * display:     z.object({ … })            // required, may be {}
+ * ui:          { position: { x: number, y: number }, size?: { width, height } }  // optional in the file
+ * inputs?:     Record<string, unknown>
+ * outputs?:    Record<string, unknown>
+ * parentId?:   z.string().min(1)
+ * ```
+ *
+ * `makeNode` builds this shape for every definition-backed node, but a node
+ * built any other way (sticky notes were, issue #869) had nothing holding it
+ * to the contract: `check` passed, `compile` wrote the file, and only
+ * `flow validate` refused it. `serialize` runs this over every finished scope,
+ * so a missing field is an SDK emit bug caught before a file is written — on
+ * every path, `compile --no-check` and direct `serialize()` included.
+ */
+/** Every way `node` breaks the envelope, as `<field>: <problem>` strings. Empty when it conforms. */
+export declare function nodeEnvelopeProblems(node: unknown): string[];
+/**
+ * Throw if any node in one scope breaks the envelope. `where` names the scope
+ * (`flow "x"`, `subflow "call"`) so the message points at the file section
+ * `flow validate` would have reported.
+ */
+export declare function assertNodeEnvelope(nodes: readonly unknown[], where: string): void;

package/dist/core/node-envelope.js

@@ -0,0 +1,83 @@
+/**
+ * The node envelope: the fields `uip maestro flow validate` requires on EVERY
+ * entry of a `.flow` file's `nodes[]` (root and every `subflows.<id>.nodes[]`),
+ * whatever its type.
+ *
+ * Mirrors the platform's file-format node schema (`@uipath/flow-schema`
+ * `fileFormatNodeSchema`, bundled into the CLI's flow tool):
+ *
+ * ```ts
+ * id:          z.string().min(1)
+ * type:        z.string().min(1)
+ * typeVersion: z.string().regex(/^\d+\.\d+(\.\d+)?$/)
+ * display:     z.object({ … })            // required, may be {}
+ * ui:          { position: { x: number, y: number }, size?: { width, height } }  // optional in the file
+ * inputs?:     Record<string, unknown>
+ * outputs?:    Record<string, unknown>
+ * parentId?:   z.string().min(1)
+ * ```
+ *
+ * `makeNode` builds this shape for every definition-backed node, but a node
+ * built any other way (sticky notes were, issue #869) had nothing holding it
+ * to the contract: `check` passed, `compile` wrote the file, and only
+ * `flow validate` refused it. `serialize` runs this over every finished scope,
+ * so a missing field is an SDK emit bug caught before a file is written — on
+ * every path, `compile --no-check` and direct `serialize()` included.
+ */
+const TYPE_VERSION_RE = /^\d+\.\d+(\.\d+)?$/;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+/** Every way `node` breaks the envelope, as `<field>: <problem>` strings. Empty when it conforms. */
+export function nodeEnvelopeProblems(node) {
+    if (!isRecord(node))
+        return ['node: expected an object'];
+    const problems = [];
+    if (!isNonEmptyString(node.id))
+        problems.push('id: expected a non-empty string');
+    if (!isNonEmptyString(node.type))
+        problems.push('type: expected a non-empty string');
+    if (typeof node.typeVersion !== 'string' || !TYPE_VERSION_RE.test(node.typeVersion)) {
+        problems.push(`typeVersion: expected "x.y" or "x.y.z", got ${JSON.stringify(node.typeVersion)}`);
+    }
+    if (!isRecord(node.display))
+        problems.push('display: expected an object (may be empty)');
+    if (node.ui !== undefined) {
+        const pos = isRecord(node.ui) ? node.ui.position : undefined;
+        if (!isRecord(pos) || typeof pos.x !== 'number' || typeof pos.y !== 'number') {
+            problems.push('ui.position: expected { x: number, y: number }');
+        }
+        const size = isRecord(node.ui) ? node.ui.size : undefined;
+        if (size !== undefined && (!isRecord(size) || typeof size.width !== 'number' || typeof size.height !== 'number')) {
+            problems.push('ui.size: expected { width: number, height: number }');
+        }
+    }
+    if (node.inputs !== undefined && !isRecord(node.inputs))
+        problems.push('inputs: expected an object');
+    if (node.outputs !== undefined && !isRecord(node.outputs))
+        problems.push('outputs: expected an object');
+    if (node.parentId !== undefined && !isNonEmptyString(node.parentId)) {
+        problems.push('parentId: expected a non-empty string');
+    }
+    return problems;
+}
+/**
+ * Throw if any node in one scope breaks the envelope. `where` names the scope
+ * (`flow "x"`, `subflow "call"`) so the message points at the file section
+ * `flow validate` would have reported.
+ */
+export function assertNodeEnvelope(nodes, where) {
+    const bad = [];
+    nodes.forEach((n, i) => {
+        const problems = nodeEnvelopeProblems(n);
+        if (!problems.length)
+            return;
+        const id = isRecord(n) && typeof n.id === 'string' ? n.id : `#${i}`;
+        const type = isRecord(n) && typeof n.type === 'string' ? n.type : '?';
+        bad.push(`  node "${id}" (${type}): ${problems.join('; ')}`);
+    });
+    if (!bad.length)
+        return;
+    throw new Error(`internal SDK error: ${where} would emit ${bad.length} node(s) that \`uip maestro flow validate\` `
+        + `rejects — every node needs id, type, typeVersion and display:\n${bad.join('\n')}\n`
+        + `This is a serializer bug, not an authoring mistake; please report it.`);
+}

package/dist/serialize.js

@@ -19,6 +19,7 @@ import { BindingRefusal, GUID_RE, bindingSelfNameMessage, bindingUndeclaredMessa
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
 import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
+import { assertNodeEnvelope } from './core/node-envelope.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
 import { stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf } from './event-filters.js';
@@ -3063,6 +3064,8 @@ const ERROR_ENVELOPE_VAR = {
 function errorEnvelopeVar(nodeType) {
     return ERROR_ENVELOPE_VAR[nodeType];
 }
+/** The `typeVersion` Studio Web stamps on a sticky note. The type has no manifest to take it from. */
+const STICKY_NOTE_TYPE_VERSION = '1.0.0';
 /**
  * Append the flow's `.stickyNotes()` as real `stickyNote` nodes.
  *
@@ -3100,14 +3103,20 @@ function emitStickyNotes(built, scope) {
         if ((note.width === undefined) !== (note.height === undefined)) {
             throw new Error(`.stickyNotes(): note "${id}" needs both width and height, or neither.`);
         }
+        // The envelope Studio Web writes for a note (flow-v1 canvas: the add path
+        // sets `typeVersion: '1.0.0'` and no display, and `nodeToInstance` persists
+        // `display` as `{}`). Both fields are required on every node by
+        // `flow validate`, manifest or not (#869).
         scope.nodes.push({
             id,
             type: 'stickyNote',
-            inputs: { color: note.color ?? 'yellow', content: note.content },
+            typeVersion: STICKY_NOTE_TYPE_VERSION,
             ui: {
                 position: { x: note.x, y: note.y },
                 ...(note.width !== undefined ? { size: { width: note.width, height: note.height } } : {}),
             },
+            display: {},
+            inputs: { color: note.color ?? 'yellow', content: note.content },
         });
     });
 }
@@ -4184,6 +4193,7 @@ export function serialize(built, opts = {}) {
         typeAgentInputSchemas(scope, globals);
         emitStickyNotes(child, scope);
         const layoutEdges = applyAuthorLayout(child.layout, scope, `subflow "${nodeId}"`);
+        assertNodeEnvelope(scope.nodes, `subflow "${nodeId}"`);
         return {
             nodes: scope.nodes,
             edges: scope.edges,
@@ -6241,6 +6251,7 @@ export function serialize(built, opts = {}) {
     typeAgentInputSchemas(root, globals);
     emitStickyNotes(built, root);
     const rootLayoutEdges = applyAuthorLayout(built.layout, root, `flow "${built.id}"`);
+    assertNodeEnvelope(root.nodes, `flow "${built.id}"`);
     // The FILE-FORMAT version this document declares: the author's
     // `.schemaVersion()` when they set one, else the profile's write floor. It is
     // resolved HERE rather than in `check()` alone because the serializer must not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.14.2",
+  "version": "6.14.3",
   "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": "cb7a821ea17b6f3022c7b90e2567e91a5495576a"
+  "gitref": "52d87c5c383324464fd4c672ac4e9ec40795d994"
 }