@uipath/maestro-builder-sdk 5.2.0

package/dist/core/expr.js

@@ -0,0 +1,400 @@
+/**
+ * core/expr — Flow-style expressions and type descriptors, shared by every
+ * builder SDK (flow, case, bpmn).
+ *
+ * An expression is either a literal value baked into a node, or a dynamic JS
+ * expression the runtime evaluates (a reference to a variable or an upstream
+ * node's output). A builder never reads live values — you construct references
+ * with these helpers, and nothing runs at author time except graph
+ * construction.
+ */
+/**
+ * A Flow expression. Either a literal value (a constant baked into the node)
+ * or a dynamic JS expression that the runtime evaluates (e.g. a reference to a
+ * variable or an upstream node's output).
+ */
+export class Expr {
+    js;
+    literal;
+    value;
+    constructor(js, literal = false, value) {
+        this.js = js;
+        this.literal = literal;
+        this.value = value;
+    }
+}
+/**
+ * A constant value baked directly into a node input.
+ *
+ * @param value - The constant, JSON-encoded into the emitted expression.
+ * @returns An {@link Expr} carrying the literal.
+ */
+export function lit(value) {
+    return new Expr(JSON.stringify(value), true, value);
+}
+/**
+ * Reference a flow-level variable or input by name → `$vars.<name>`.
+ *
+ * @param name - The variable or input as declared with `.var(...)` / `.input(...)`.
+ * @returns An {@link Expr} reading that variable at run time.
+ */
+export function v(name) {
+    return new Expr(`$vars.${name}`);
+}
+/** The manual trigger node's default id. */
+export const DEFAULT_TRIGGER_ID = 'start';
+/**
+ * Reference a flow input by name → `$vars.<triggerId>.output.<name>`.
+ *
+ * @remarks
+ * NOT an alias of {@link v}: an input is published as the TRIGGER NODE's output,
+ * so it is read through the trigger's id rather than as a bare global. Renaming the
+ * trigger with `.triggerId(...)` rewrites these references with it.
+ *
+ * @param name - The input as declared with `.input({ … })`.
+ * @returns An {@link Expr} reading that input off the trigger node.
+ * @see v
+ * @example
+ * ```ts
+ * .input({ amount: types.number })
+ * .step('check', script({ code: `return ${input('amount')} > 100;` }))
+ * ```
+ */
+export function input(name) {
+    // A flow input is published as the TRIGGER NODE's output, not as a bare global:
+    // v1 keys an `in` global by `<triggerNodeId>.output.<name>`, and the designer
+    // types the expression scope as `{ start: { output: { …inputs } } }`. Emitting
+    // `$vars.<name>` produced a reference the designer reports as
+    // "Property '<name>' does not exist".
+    //
+    // `start` is the trigger's id. When a flow renames it, `renameRefs` rewrites
+    // these references along with every other node-id reference.
+    return new Expr(`$vars.${DEFAULT_TRIGGER_ID}.output.${name}`);
+}
+/**
+ * Reference an ENTRY POINT's scoped input: `entryInput('nightly', 'batchDate')`
+ * reads `$vars.nightly.output.batchDate` — an input declared on
+ * `.entryPoint('nightly', …, { inputs: { batchDate: … } })`. `input(name)`
+ * remains the spelling for the DEFAULT root's inputs.
+ *
+ * @param entryPointId - The `.entryPoint()` id that declared the input.
+ * @param name - The input's declared name on that entry point.
+ * @returns An expression usable anywhere an `Expr` is accepted.
+ */
+export function entryInput(entryPointId, name) {
+    return new Expr(`$vars.${entryPointId}.output.${name}`);
+}
+/**
+ * Reference an upstream step's output → `$vars.<step>.output[.<path>]`.
+ * e.g. `out('fetchRate', 'body.rate')`.
+ *
+ * @remarks
+ * Write the reference this way, or dotted by hand — never through a bracket
+ * (`$vars.fetchRate["output"]`, `$vars["fetchRate"].output`). Both of those
+ * resolve at run time, so the mistake is invisible, but only the DOTTED form is
+ * rewritten on the way out: a subflow copy renames node ids, the queue family
+ * publishes its result as `<step>.response`, and a failure envelope resolves per
+ * node family. A bracketed read opts out of all three and goes stale the moment
+ * one applies. `path` may still bracket INTO the value — `out('rows', 'items')`
+ * then `["odd key"]` — because nothing rewrites past the runtime variable.
+ *
+ * @param step - The step whose result to read, named as it was in `.step(...)`.
+ * @param path - A dotted path INTO that result. Omit it for the whole output.
+ * @returns An {@link Expr} reading that value at run time.
+ * @see ran
+ * @see err
+ * @enforcedBy VARS_BRACKET_READ Reach a step by a dot, not a bracket — the
+ * bracketed spelling is the one the compiler cannot rewrite.
+ */
+export function out(step, path) {
+    return new Expr(`$vars.${step}.output${path ? '.' + path : ''}`);
+}
+/**
+ * Did this step run? → `!!$vars.<step>.output`.
+ *
+ * @remarks
+ * For the shape a `switch` creates: a value is computed in exactly ONE arm, and
+ * the step after the join has to read *whichever arm ran*.
+ *
+ * ```ts
+ * .switch('route', [
+ *   { when: js`${input('direction')} === 'f2i'`, body: (b) => b.step('toInches', script(…)) },
+ *   { when: js`${input('direction')} === 'i2f'`, body: (b) => b.step('toFeet',   script(…)) },
+ * ])
+ * .return({ result: js`${ran('toInches')} ? ${out('toInches', 'result')} : ${out('toFeet', 'result')}` })
+ * ```
+ *
+ * ### What it means, and what it does NOT
+ *
+ * It tests **what the step published**, because that is the only thing the
+ * platform will answer. The runtime's variable bag is flat and keyed by dotted
+ * names: it holds `"toInches.output"`, pre-declared `null` before the step runs
+ * and left `null` if the step never runs. So `!!$vars.toInches.output` is false
+ * until the arm runs and true after.
+ *
+ * Two consequences worth knowing before you rely on it:
+ *
+ * - **A step that RAN but published nothing reads as not-ran.** Ran-ness is
+ *   output-presence, not execution. A `mock()` placeholder publishes nothing by
+ *   design, so `ran()` of one is always false — locally and deployed alike.
+ * - **Do not test the step itself.** `$vars.toInches ? … : …` is the spelling
+ *   deployed flows reach for, and it is DEAD: there is no bare `toInches` key in
+ *   the bag, so it is `undefined` whether or not the step ran, and every guard
+ *   built on it silently takes the wrong branch. Measured on the product
+ *   runtime — a flow whose taken arm computed `23` returned `null`, reported
+ *   `Completed`, and was scored 1.0 by v1's graders
+ *   (`runs/flow-sdk-g21-2026-08-02/probe-truthiness/RECORD.md`). A green run is
+ *   not evidence the expression worked.
+ *
+ * A switch's own `matchedCase` / `matchedCaseId` cannot help either: the format
+ * declares them and the server runtime never populates them (measured, same
+ * probe family), which is why ran-ness is computed from the output instead.
+ *
+ * @param step - The step to test, named as it was in `.step(...)`.
+ * @returns An {@link Expr} that is true only if the step produced output.
+ * @enforcedBy STEP_READ_WITHOUT_OUTPUT Test ran-ness with `ran()`, never a bare
+ * `$vars.<step>` — the runtime has no such key, so the guard is always false.
+ */
+export function ran(step) {
+    return new Expr(`!!$vars.${step}.output`);
+}
+/**
+ * Reference a FAILED step's error → `$vars.<step>.error[.<field>]`.
+ *
+ * @remarks
+ * Only meaningful inside that step's `.onError(...)` handler — the platform
+ * writes the failure when the node's error boundary fires, and nowhere else.
+ * The envelope carries the same fields on every family that publishes one:
+ *
+ * | field | type | example |
+ * |---|---|---|
+ * | `code` | string | `'404'` — a STRING even for an HTTP status |
+ * | `message` | string | `'Integration Services resource not found'` |
+ * | `detail` | string | the whole upstream response |
+ * | `category` | string | `'User'` |
+ * | `status` | number | `404` |
+ * | `response` | unknown | undeclared; `null` in every probe |
+ * | `element` | string | undeclared; the id of the step that failed |
+ *
+ * The last two resolve at run time — measured, a container handler reading
+ * `element` came back with the failing body step's id — but they are absent from
+ * the declared schema, so `uip maestro flow validate` reports
+ * `EXPRESSION_DIAGNOSTIC: Property 'element' does not exist on type
+ * '<Step>_Error'` for them. Valid, and noisy: prefer the declared five unless you
+ * specifically need one of these.
+ *
+ * **Which VARIABLE holds it is per node family, and this helper owns that.**
+ * Measured on the product (2026-09-10), one debug run per family:
+ *
+ * | family | envelope in | `<step>.error` is |
+ * |---|---|---|
+ * | connector (all 3806 of them) | `<step>.error` | the envelope |
+ * | `core.action.script` | `<step>.error` | the envelope |
+ * | `uipath.pattern.deep-rag` | `<step>.error` | the envelope |
+ * | `core.subflow` | `<step>.error` | the envelope |
+ * | `core.action.queue.create` | `<step>.error` | the envelope |
+ * | `core.action.http.v2` (managed) | `<step>.output` | the boolean `true` |
+ * | `core.action.http` (plain, any version) | nowhere — no envelope at all | the boolean `true` |
+ *
+ * So the author writes one shape, `.error.<field>`, and `serialize` rewrites it
+ * to `.output.<field>` for the one family that publishes it there
+ * (`errorEnvelopeVar` in `serialize.ts`). Do not hand-write either prefix: which
+ * one is right is not a property of the expression, it is a property of the node
+ * the step happens to be, and only the builder knows that.
+ *
+ * The history matters, because this has now been wrong in both directions. It
+ * read `.error.<field>` originally; a managed-http debug run showed `.error` was
+ * the boolean `true` there and the envelope sat in `.output`, so it was changed
+ * to `.output.<field>` for every family — which silently broke the other six,
+ * where `.output` is `null` after a failure. Both measurements were right about
+ * the family they measured. The fix is not a constant either way.
+ *
+ * Plain `http({ managed: false })` publishes NO envelope in any version — 1.0.0
+ * and the 1.3 that `uip maestro flow migrate` upgrades it to both set
+ * `<step>.error = true` and leave `<step>.output` null — so there is nothing for
+ * this helper to read. `check` refuses a handler there (HTTP_ONERROR_V1) rather
+ * than emitting a read that resolves to nothing.
+ *
+ * `out('<step>','error')` is still wrong and `check` still refuses it
+ * (ERROR_READ_VIA_OUT): the success-path output has no `error` field of its own.
+ * Use the boolean `$vars.<step>.error` — `err('<step>')` with no field — to ask
+ * *whether* it failed; that reads truthy on every family, the envelope object
+ * included.
+ *
+ * @example
+ * **Read the failure inside the step's error handler**
+ * ```ts
+ * .step('load', script({ code: 'return JSON.parse($vars.start.output.raw);' }))
+ * .onError((h) => h.return({ note: tmpl`bad payload: ${err('load', 'message')}` }))
+ * ```
+ *
+ * @example
+ * **The same read, without naming the step** — inside a handler the failed step
+ * is known, so the handler's own `err` needs only the field, and a step rename
+ * cannot leave the read pointing at the wrong node.
+ * ```ts
+ * .onError((h) => h.return({ note: tmpl`bad payload: ${h.err('message')}` }))
+ * ```
+ *
+ * @param step - The step that FAILED, named as it was in `.step(...)`.
+ * @param field - One of the envelope's fields. Omit it to test WHETHER the step
+ * failed.
+ * @returns An {@link Expr} reading the failure inside an `.onError(...)` handler.
+ * @enforcedBy ERROR_READ_VIA_OUT Read an error with `err()`, never
+ * `out('<step>', 'error')` — the success output has no `error` field of its own.
+ * @enforcedBy ERROR_ENVELOPE_VIA_OUTPUT Inside a handler, the failed step's
+ * `.output` is empty; an envelope field read from it resolves to nothing.
+ */
+export function err(step, field) {
+    // ONE shape for every family. `serialize` rewrites the prefix for the families
+    // that publish the envelope elsewhere — see `errorEnvelopeVar`.
+    return new Expr(`$vars.${step}.error${field ? '.' + field : ''}`);
+}
+/**
+ * Build a raw JS *expression* (a condition or computation).
+ * Interpolated `Expr`s contribute their reference; other values are JSON-encoded.
+ * e.g. js`${input('from')} !== ${input('to')}` → `$vars.from !== $vars.to`
+ *
+ * @param strings - The template's literal parts, supplied by the tag call.
+ * @param vals - Interpolated values. An {@link Expr} contributes its reference;
+ * anything else is JSON-encoded.
+ * @returns An {@link Expr} carrying the composed JavaScript expression.
+ * @see tmpl
+ */
+export function js(strings, ...vals) {
+    let out = '';
+    strings.forEach((s, i) => {
+        out += s;
+        if (i < vals.length)
+            out += exprText(vals[i]);
+    });
+    return new Expr(out.trim());
+}
+/**
+ * Build a JS *string template* (for URLs, messages, etc.).
+ * e.g. tmpl`https://api.rates.io/${input('from')}` →
+ *      a JS template literal referencing `$vars.from`.
+ *
+ * @param strings - The template's literal parts, supplied by the tag call.
+ * @param vals - Interpolated values, each rendered into the string at run time.
+ * @returns An {@link Expr} carrying a JavaScript template literal.
+ * @see js
+ */
+export function tmpl(strings, ...vals) {
+    let body = '';
+    strings.forEach((s, i) => {
+        body += s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+        if (i < vals.length)
+            body += '${' + exprText(vals[i]) + '}';
+    });
+    return new Expr('`' + body + '`');
+}
+function exprText(val) {
+    return val instanceof Expr ? val.js : JSON.stringify(val);
+}
+/**
+ * Coerce a raw value or Expr into an Expr.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function toExpr(val) {
+    return val instanceof Expr ? val : lit(val);
+}
+// ─── FLAT NAMES — what the platform calls a reference ───────────────────────
+//
+// An inline agent's arguments are named by the platform, not by us: flow-v1's
+// `preDeriveAgentInputDefinitions` scans the agent NODE's prompts for `$vars.*` /
+// `$metadata.*` references and names each derived argument with the reference's
+// FLAT NAME — the path with its dots replaced by `__`. So an `agent.json` that
+// templates `{{input.<something-else>}}` templates against a key that does not
+// exist, and the placeholder reaches the model as literal text (board G-20).
+//
+// The encoding lives here, next to the helpers that BUILD those references, so
+// `check` and `serialize` cannot drift apart about what a reference is called.
+/**
+ * flow-v1 flow-schema `utils.ts:70` — the flat-name segment separator.
+ *
+ * @internal Encoding detail shared by `check` and `serialize`, not an authoring value.
+ */
+export const FLAT_SEP = '__';
+/**
+ * A JS expression that is EXACTLY one `$vars.*` / `$metadata.*` reference and
+ * nothing else — the only shape with a single platform argument to name.
+ *
+ * The path grammar is flow-v1's `VARIABLE_PATH_PATTERN` verbatim
+ * (`services/src/variables/constants.ts:38-44`): an identifier, then any number
+ * of `.identifier` / `[0]` selectors. Note what that admits — `.length` is an
+ * identifier segment, so both `out('a', 'items[0].id')` and a `….lines.length`
+ * read are single references rather than computed expressions.
+ */
+const SINGLE_SOURCE_REF = /^\$(vars|metadata)\.([a-zA-Z_]\w*(?:\[\d+\]|\.[a-zA-Z_]\w*)*)$/;
+/** Segment splitter — flow-v1 `encodeFlatName` (`agent-cluster-rewrite.ts:114-117`). */
+const PATH_SEGMENT = /[a-zA-Z_]\w*|\[(\d+)\]/g;
+/**
+ * The name the PLATFORM will call this reference by, or `undefined` when the
+ * expression is not a single reference (a literal, or a computed expression
+ * spanning zero or several references — neither has one argument to name).
+ *
+ * flow-v1's `encodeFlatName` (`agent-cluster-rewrite.ts:113-121`): split into
+ * identifier segments plus bare index numbers and join with `__`; the `$vars.`
+ * prefix is dropped, `$metadata` keeps `metadata` as its first segment.
+ *
+ * ```
+ * flatNameOf('$vars.notes')                              // 'notes'
+ * flatNameOf('$vars.normalizeData.output.invoiceNumber') // 'normalizeData__output__invoiceNumber'
+ * flatNameOf('$vars.a.output.items[0].id')               // 'a__output__items__0__id'
+ * flatNameOf('$metadata.jobId')                          // 'metadata__jobId'
+ * flatNameOf('$vars.a.output.x + $vars.b')               // undefined — composite
+ * ```
+ *
+ * Accepts the expression with or without the `=js:` prefix a rendered binding
+ * carries, so both the authored `Expr.js` and an emitted binding can be asked.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function flatNameOf(expression) {
+    return flatNameSegmentsOf(expression)?.join(FLAT_SEP);
+}
+/**
+ * {@link flatNameOf}'s segments, before they are joined.
+ *
+ * Exposed because the JOIN is lossy: `__` is both the separator and a legal
+ * character inside an identifier, so a step named `erp__lookup` produces
+ * `erp__lookup__output__value`, which decodes back to the wrong path
+ * (`erp.lookup.output.value`). v1's own inverse says as much — `decodeFlatName`
+ * round-trips "provided variable and node IDs disallow `__`". `check` reads the
+ * segments to warn about exactly that.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function flatNameSegmentsOf(expression) {
+    const bare = (expression.startsWith('=js:') ? expression.slice(4) : expression).trim();
+    const m = SINGLE_SOURCE_REF.exec(bare);
+    if (!m)
+        return undefined;
+    const segments = Array.from(m[2].matchAll(PATH_SEGMENT), (s) => s[1] ?? s[0]);
+    return m[1] === 'vars' ? segments : ['metadata', ...segments];
+}
+// ─── Types ──────────────────────────────────────────────────────────────────
+/** Variable type descriptors (map to Flow variable `type` values). */
+export const types = {
+    string: 'string',
+    number: 'number',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    file: 'file',
+    any: 'any',
+    // Case-management type vocabulary (M87): the platform distinguishes numeric
+    // widths and date kinds. These map straight to the caseplan variable `type`
+    // and drive the entry-points.json type→format projection.
+    integer: 'integer',
+    float: 'float',
+    double: 'double',
+    date: 'date',
+    datetime: 'datetime',
+    // Structured (object/array) case variables persist as `type: 'jsonSchema'` with
+    // the shape carried in a JSON-schema `body` (object vs array lives in body.type).
+    // Case-only — declare via the `jsonSchema(body)` helper.
+    jsonSchema: 'jsonSchema',
+};

package/dist/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * core — the domain-agnostic layer shared by every builder SDK (flow, case,
+ * bpmn): expressions, action specs, connector-library resolution, and symbolic
+ * binding resolution. Domain builders (flow/, case/, bpmn/) compose these.
+ */
+export * from './expr.js';
+export * from './actions.js';
+export * from './connectors.js';
+export * from './library.js';
+export * from './bindings.js';

package/dist/core/index.js

@@ -0,0 +1,10 @@
+/**
+ * core — the domain-agnostic layer shared by every builder SDK (flow, case,
+ * bpmn): expressions, action specs, connector-library resolution, and symbolic
+ * binding resolution. Domain builders (flow/, case/, bpmn/) compose these.
+ */
+export * from './expr.js';
+export * from './actions.js';
+export * from './connectors.js';
+export * from './library.js';
+export * from './bindings.js';