@uipath/maestro-builder-sdk 6.20.5 → 6.21.0

package/dist/flow-sdk.d.ts

@@ -22,6 +22,7 @@ export * from './nodes/data-fabric/flow/index.js';
 export * from './nodes/delay/flow/index.js';
 export * from './nodes/document/flow/index.js';
 export * from './nodes/mock/flow/index.js';
+export * from './nodes/queue/flow/index.js';
 export * from './nodes/script/flow/index.js';
 export * from './nodes/transform/flow/index.js';
 export { resolveFlowRefs, resolveRefPath, hasFileRefs } from './ref-resolve.js';
@@ -379,6 +380,11 @@ export interface NodeOptions {
      * Flow JSON stores it. Keys name declared `.var()` variables (or flow
      * outputs); values are `Expr`s or raw literals.
      *
+     * A key that names a flow output writes the output's backing Variable,
+     * `<output>Value` (`direction: 'inout'`), because Studio Web's Update
+     * Variable cannot target an Output; every End then maps the output from that
+     * Variable.
+     *
      * @remarks
      * Not accepted on `.branch()`, `.switch()`, `.parallel()`, or `.trigger()` —
      * the platform strips updates from decision/switch/merge nodes on save, and a
@@ -1439,6 +1445,16 @@ declare class FlowBuilder extends StepList {
      * second variable (its default becomes the output's); a different type is a
      * `check` error, `OUTPUT_VAR_MISMATCH`.
      *
+     * In the `.flow`, Studio Web sets an Output only on an End node, and neither
+     * Update Variable nor an expression can touch one. So an output that the flow
+     * sets or reads from inside (`{ updates }`, a `{ shared }` input, a
+     * `default`, or a `v('<name>')` read) is emitted with a backing Variable,
+     * `<name>Value` (`direction: 'inout'`): updates and reads go to the Variable,
+     * and every End maps the output from it. That id must be free; a step,
+     * input or `.var()` already called `<name>Value` is a `check` error,
+     * `OUTPUT_BACKING_COLLISION`. An output only `.return({ … })` sets needs no
+     * Variable: an End that does not name it maps `null`.
+     *
      * @example
      * **A loop accumulator**
      * ```ts

package/dist/flow-sdk.js

@@ -26,6 +26,7 @@ export * from './nodes/data-fabric/flow/index.js';
 export * from './nodes/delay/flow/index.js';
 export * from './nodes/document/flow/index.js';
 export * from './nodes/mock/flow/index.js';
+export * from './nodes/queue/flow/index.js';
 export * from './nodes/script/flow/index.js';
 export * from './nodes/transform/flow/index.js';
 // `$ref`-split ingestion (design §5): decompile resolves local-file refs into
@@ -1176,6 +1177,16 @@ class FlowBuilder extends StepList {
      * second variable (its default becomes the output's); a different type is a
      * `check` error, `OUTPUT_VAR_MISMATCH`.
      *
+     * In the `.flow`, Studio Web sets an Output only on an End node, and neither
+     * Update Variable nor an expression can touch one. So an output that the flow
+     * sets or reads from inside (`{ updates }`, a `{ shared }` input, a
+     * `default`, or a `v('<name>')` read) is emitted with a backing Variable,
+     * `<name>Value` (`direction: 'inout'`): updates and reads go to the Variable,
+     * and every End maps the output from it. That id must be free; a step,
+     * input or `.var()` already called `<name>Value` is a `check` error,
+     * `OUTPUT_BACKING_COLLISION`. An output only `.return({ … })` sets needs no
+     * Variable: an End that does not name it maps `null`.
+     *
      * @example
      * **A loop accumulator**
      * ```ts

package/dist/flow-variables.d.ts

@@ -54,10 +54,12 @@ export interface FlowGlobalsPlan<D extends DeclaredVariable = DeclaredVariable>
  * `@uipath/maestro-sdk` (the code that turns a `.flow` into what runs):
  * - only an `out` global is a flow OUTPUT at the root — `buildNodeOutputMappings`
  *   drops an End node's mapping for any id that is not `direction: 'out'`;
- * - `inout` is published as an INPUT too — solution discovery puts it on the
- *   entry point's input schema — so `inout` would widen the caller's contract;
- * - `{ updates }` on an `out` global is the same output mapping (`var: <id>`) as
- *   on an `inout` one, so a loop body can read and rewrite it mid-run;
+ * - `inout` is not part of the caller's contract either way: `@uipath/flow-schema`
+ *   packaging builds the entry-point input schema from `in` globals bound to the
+ *   trigger, and the output schema from `out` globals only;
+ * - a loop body that reads and rewrites the value mid-run does so through the
+ *   output's backing `inout` Variable (`flow-output-backing.ts`, #1092), because
+ *   Studio Web neither updates nor reads an Output;
  * - the `default` on `<uipath:output>` is serialized (`collectVariablesFromNodes`)
  *   and a subflow seeds its `out` globals from `defaultValue ?? null`
  *   (`buildSeedTask`). The v1 CLI's `variable add --direction out

package/dist/flow-variables.js

@@ -58,10 +58,12 @@ const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
  * `@uipath/maestro-sdk` (the code that turns a `.flow` into what runs):
  * - only an `out` global is a flow OUTPUT at the root — `buildNodeOutputMappings`
  *   drops an End node's mapping for any id that is not `direction: 'out'`;
- * - `inout` is published as an INPUT too — solution discovery puts it on the
- *   entry point's input schema — so `inout` would widen the caller's contract;
- * - `{ updates }` on an `out` global is the same output mapping (`var: <id>`) as
- *   on an `inout` one, so a loop body can read and rewrite it mid-run;
+ * - `inout` is not part of the caller's contract either way: `@uipath/flow-schema`
+ *   packaging builds the entry-point input schema from `in` globals bound to the
+ *   trigger, and the output schema from `out` globals only;
+ * - a loop body that reads and rewrites the value mid-run does so through the
+ *   output's backing `inout` Variable (`flow-output-backing.ts`, #1092), because
+ *   Studio Web neither updates nor reads an Output;
  * - the `default` on `<uipath:output>` is serialized (`collectVariablesFromNodes`)
  *   and a subflow seeds its `out` globals from `defaultValue ?? null`
  *   (`buildSeedTask`). The v1 CLI's `variable add --direction out

package/dist/nodes/queue/flow/check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The Queue family's rules and their catalog. Moved from check.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages are unchanged.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { QueueItemInputs } from './spec.js';
+/** Every code the family reports, with the severity it reports it at. */
+export declare const QUEUE_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * Check a `queueItem(...)` call.
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the queue exists, whether anything
+ * drains it, and what a consumer writes into a processed item's result all live on
+ * the tenant. So these cover the mistakes decidable from the call — plus the one
+ * mistake the PLATFORM decides and rejects at run time, which is worth catching
+ * here because its error arrives from Orchestrator as an HTTP 400 three layers
+ * away:
+ *
+ *  - a missing/blank `queue`, `folderPath` or `key`. Without the first two
+ *    nothing can resolve the node's `resourceBindings.name`, and without `key`
+ *    nothing joins the node to its bindings — both read as engine errors rather
+ *    than authoring ones.
+ *  - a `key` that is not a GUID. The commonest form is passing the queue's NAME
+ *    where its Orchestrator key belongs.
+ *  - a NESTED `item`. Orchestrator answers "Property values must be simple (like
+ *    numbers or text) and not complex or composite data types (like objects or
+ *    arrays)" — a run-time 400 for something visible in the source.
+ *  - a `priority` outside the three the node type offers. The platform normalizes
+ *    an unknown one silently, so it is a wrong RESULT, not an error.
+ *  - `returns` on a step that does not wait (there is nothing per-tenant to
+ *    declare), and a `wait: true` step whose result nothing can read.
+ *  - a non-ISO `dueDate` / `deferDate`.
+ */
+export declare function checkQueueItem(inputs: QueueItemInputs | undefined, ctx: FlowCheckContext): void;

package/dist/nodes/queue/flow/check.js

@@ -0,0 +1,126 @@
+import { commentText } from '../../../core/comment-text.js';
+import { nearestName } from '../../../core/edit-distance.js';
+import { Expr } from '../../../core/expr.js';
+import { GUID_RE } from '../../../core/binding-messages.js';
+/** Every code the family reports, with the severity it reports it at. */
+export const QUEUE_DIAGNOSTICS = {
+    QUEUE_NO_NAME: { severity: 'error', summary: 'no queue name' },
+    QUEUE_NO_FOLDER: { severity: 'error', summary: 'no folderPath' },
+    QUEUE_NO_KEY: { severity: 'error', summary: 'no queue key' },
+    QUEUE_KEY_NOT_GUID: { severity: 'error', summary: 'the key is not an Orchestrator GUID' },
+    QUEUE_NO_ITEM: { severity: 'warning', summary: 'the item carries no data' },
+    QUEUE_ITEM_NOT_OBJECT: { severity: 'error', summary: 'the item is not an object' },
+    QUEUE_ITEM_FIELD_NOT_PRIMITIVE: { severity: 'error', summary: 'an item field is not a primitive' },
+    QUEUE_BAD_PRIORITY: { severity: 'error', summary: 'a priority the node type does not offer' },
+    QUEUE_BAD_DATE: { severity: 'error', summary: 'a date Orchestrator cannot read' },
+    QUEUE_RETURNS_WITHOUT_WAIT: { severity: 'warning', summary: 'returns without wait: true' },
+    QUEUE_READ_NOT_OUTPUT: { severity: 'error', summary: 'a read outside the step\'s output' },
+    QUEUE_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'a field read off a wait result with no returns' },
+    QUEUE_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'a read of a field the step does not publish' },
+};
+/**
+ * Check a `queueItem(...)` call.
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the queue exists, whether anything
+ * drains it, and what a consumer writes into a processed item's result all live on
+ * the tenant. So these cover the mistakes decidable from the call — plus the one
+ * mistake the PLATFORM decides and rejects at run time, which is worth catching
+ * here because its error arrives from Orchestrator as an HTTP 400 three layers
+ * away:
+ *
+ *  - a missing/blank `queue`, `folderPath` or `key`. Without the first two
+ *    nothing can resolve the node's `resourceBindings.name`, and without `key`
+ *    nothing joins the node to its bindings — both read as engine errors rather
+ *    than authoring ones.
+ *  - a `key` that is not a GUID. The commonest form is passing the queue's NAME
+ *    where its Orchestrator key belongs.
+ *  - a NESTED `item`. Orchestrator answers "Property values must be simple (like
+ *    numbers or text) and not complex or composite data types (like objects or
+ *    arrays)" — a run-time 400 for something visible in the source.
+ *  - a `priority` outside the three the node type offers. The platform normalizes
+ *    an unknown one silently, so it is a wrong RESULT, not an error.
+ *  - `returns` on a step that does not wait (there is nothing per-tenant to
+ *    declare), and a `wait: true` step whose result nothing can read.
+ *  - a non-ISO `dueDate` / `deferDate`.
+ */
+export function checkQueueItem(inputs, ctx) {
+    const step = ctx.step;
+    // Severity is the catalog's (QUEUE_DIAGNOSTICS): `at` and `warn` name the intent.
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const warn = at;
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.queue)) {
+        at('QUEUE_NO_NAME', `Queue step "${step}" has no \`queue\`. That is the queue's name in Orchestrator, and the `
+            + `runtime resolves the queue by name + folder — without it the run fails before dispatch.`, `queue: 'SupplierInvoices'`);
+    }
+    if (blank(inputs?.folderPath)) {
+        at('QUEUE_NO_FOLDER', `Queue step "${step}" has no \`folderPath\`. Queues are folder-scoped, and the runtime `
+            + `resolves this one by name + folder.`, `folderPath: 'Shared'`);
+    }
+    if (blank(inputs?.key)) {
+        at('QUEUE_NO_KEY', `Queue step "${step}" has no \`key\`. That is the queue's own Orchestrator key, and it is `
+            + `what joins this node to the flow's queue bindings — without it nothing says which `
+            + `bindings belong to the node, so it cannot be dispatched. Find it with `
+            + `\`uip or queues list --all-folders\`.`, `key: 'fa1a7328-cd17-4525-b5ab-29d86e399312'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('QUEUE_KEY_NOT_GUID', `Queue step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not an `
+            + `Orchestrator key. \`key\` is the GUID the tenant gives the queue; the queue's NAME goes `
+            + `in \`queue\` and its folder in \`folderPath\`.`, `key: '<guid>', queue: ${JSON.stringify(inputs.key)}`);
+    }
+    // The item's data must be FLAT. This is the platform's rule, not ours, and it is
+    // enforced at the far end: a nested value earns an HTTP 400 from Orchestrator
+    // mid-run, which is a long way from the line that caused it.
+    const item = inputs?.item;
+    if (item === undefined || item === null) {
+        warn('QUEUE_NO_ITEM', `Queue step "${step}" has no \`item\`, so it enqueues an item with no data. That is legal `
+            + `— a bare item with a reference is a real pattern — but if the work needs a payload, this `
+            + `is where it goes.`, `item: { InvoiceId: input('invoiceRef') }`);
+    }
+    else if (typeof item !== 'object' || Array.isArray(item)) {
+        at('QUEUE_ITEM_NOT_OBJECT', `Queue step "${step}"'s \`item\` is ${Array.isArray(item) ? 'an array' : typeof item}. It `
+            + `must be an object of field names to primitive values — that object becomes the queue `
+            + `item's \`SpecificContent\`.`, `item: { InvoiceId: 'INV-1', Amount: 120 }`);
+    }
+    else {
+        for (const [k, v] of Object.entries(item)) {
+            // An Expr is a reference the runtime resolves — its VALUE may be anything,
+            // and nothing local can know, so it is not flagged here.
+            if (v instanceof Expr)
+                continue;
+            if (v !== null && typeof v === 'object') {
+                at('QUEUE_ITEM_FIELD_NOT_PRIMITIVE', `Queue step "${step}"'s \`item.${k}\` is ${Array.isArray(v) ? 'an array' : 'an object'}. `
+                    + `Orchestrator rejects a queue item whose property values are not simple: `
+                    + `"Property values must be simple (like numbers or text) and not complex or composite `
+                    + `data types (like objects or arrays)". Flatten it, or JSON-encode it into one string `
+                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${commentText(k)}Id, ${commentText(k)}Name, …`);
+            }
+        }
+    }
+    if (inputs?.priority !== undefined && !QUEUE_PRIORITIES.includes(String(inputs.priority))) {
+        at('QUEUE_BAD_PRIORITY', `Queue step "${step}"'s \`priority\` is ${JSON.stringify(inputs.priority)}. The node type `
+            + `offers exactly ${QUEUE_PRIORITIES.map((p) => `"${p}"`).join(', ')} — anything else is `
+            + `normalized silently by the platform, so the item is enqueued at the wrong priority `
+            + `rather than rejected.`, `priority: '${nearestName(String(inputs.priority), QUEUE_PRIORITIES) ?? 'Normal'}'`);
+    }
+    for (const field of ['deferDate', 'dueDate']) {
+        const v = inputs?.[field];
+        if (typeof v === 'string' && v.trim() !== '' && Number.isNaN(Date.parse(v))) {
+            at('QUEUE_BAD_DATE', `Queue step "${step}"'s \`${field}\` is ${JSON.stringify(v)}, which is not a date `
+                + `Orchestrator can read. It takes ISO-8601 — a full timestamp with a zone.`, `${field}: '2026-08-05T17:00:00Z'`);
+        }
+    }
+    // `returns` describes what a CONSUMER produced, which only exists if the step
+    // waited for one. On a fire-and-forget enqueue it is a misunderstanding worth
+    // naming: the output is the queue item's own record, and the serializer already
+    // declares its fields.
+    if (!inputs?.wait && inputs?.returns && Object.keys(inputs.returns).length) {
+        warn('QUEUE_RETURNS_WITHOUT_WAIT', `Queue step "${step}" declares \`returns\` but does not \`wait\`, so nothing produces those `
+            + `fields: a fire-and-forget enqueue publishes the queue ITEM's own Orchestrator record `
+            + `(\`Key\`, \`Status\`, \`Reference\`, \`SpecificContent\`, …), whose fields are already `
+            + `declared for you. \`returns\` describes what a CONSUMER wrote into a processed item's `
+            + `result, which needs \`wait: true\`.`, `wait: true`);
+    }
+}
+/** The three priorities `core.action.queue.create[-and-wait]`'s form offers. */
+const QUEUE_PRIORITIES = ['Low', 'Normal', 'High'];

package/dist/nodes/queue/flow/factories.d.ts

@@ -0,0 +1,49 @@
+/** The Queue family's factory. Moved from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { QueueItemInputs } from './spec.js';
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function queueItem(inputs: QueueItemInputs): ActionSpec;

package/dist/nodes/queue/flow/factories.js

@@ -0,0 +1,50 @@
+/** The Queue family's factory. Moved from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function queueItem(inputs) {
+    return builtinActionSpec({ kind: 'queueItem', inputs });
+}

package/dist/nodes/queue/flow/family.d.ts

@@ -0,0 +1,3 @@
+/** The Queue node family, as flow-node-registry.ts lists it: `core.action.queue.create[-and-wait]`. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const queueFlowFamily: FlowNodeFamily;

package/dist/nodes/queue/flow/family.js

@@ -0,0 +1,8 @@
+import { QUEUE_DIAGNOSTICS } from './check.js';
+import { queueNodeTypes } from './node-type.js';
+export const queueFlowFamily = {
+    id: 'queue',
+    title: 'Queue',
+    types: queueNodeTypes,
+    diagnostics: QUEUE_DIAGNOSTICS,
+};

package/dist/nodes/queue/flow/index.d.ts

@@ -0,0 +1,3 @@
+/** The Queue family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/queue/flow/index.js

@@ -0,0 +1,3 @@
+/** The Queue family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/queue/flow/node-type.d.ts

@@ -0,0 +1,8 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { QueueItemInputs } from './spec.js';
+/** The spec both queue node types read. */
+export type QueueItemSpec = {
+    kind: 'queueItem';
+    inputs: QueueItemInputs;
+};
+export declare const queueNodeTypes: FlowVersionedNodeType<QueueItemSpec>[];