@uipath/maestro-builder-sdk 5.2.0

package/dist/core/expr.d.ts

@@ -0,0 +1,323 @@
+/**
+ * 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 declare class Expr {
+    readonly js: string;
+    readonly literal: boolean;
+    readonly value?: unknown | undefined;
+    constructor(js: string, literal?: boolean, value?: unknown | undefined);
+}
+/**
+ * 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 declare function lit(value: unknown): Expr;
+/**
+ * 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 declare function v(name: string): Expr;
+/** The manual trigger node's default id. */
+export declare 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 declare function input(name: string): Expr;
+/**
+ * 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 declare function entryInput(entryPointId: string, name: string): Expr;
+/**
+ * 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 declare function out(step: string, path?: string): Expr;
+/**
+ * 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 declare function ran(step: string): Expr;
+/**
+ * The fields a failure envelope carries.
+ *
+ * The first five are what every error-capable node's definition declares
+ * (`outputDefinition.error.schema`, `required`, `additionalProperties: false`).
+ * `response` and `element` are NOT declared and are present at run time anyway —
+ * measured on every family probed (2026-09-10), `element` carrying the id of the
+ * step that failed. They are typed here because a field that exists should be
+ * readable; the declared five stay first because those are the contract.
+ */
+export type ErrorEnvelopeField = 'code' | 'message' | 'detail' | 'category' | 'status' | 'response' | 'element';
+/**
+ * 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 declare function err(step: string, field?: ErrorEnvelopeField): Expr;
+/**
+ * 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 declare function js(strings: TemplateStringsArray, ...vals: unknown[]): Expr;
+/**
+ * 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 declare function tmpl(strings: TemplateStringsArray, ...vals: unknown[]): Expr;
+/**
+ * Coerce a raw value or Expr into an Expr.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export declare function toExpr(val: unknown): Expr;
+/**
+ * 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 declare const FLAT_SEP = "__";
+/**
+ * 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 declare function flatNameOf(expression: string): string | undefined;
+/**
+ * {@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 declare function flatNameSegmentsOf(expression: string): string[] | undefined;
+/** Variable type descriptors (map to Flow variable `type` values). */
+export declare const types: {
+    readonly string: "string";
+    readonly number: "number";
+    readonly boolean: "boolean";
+    readonly object: "object";
+    readonly array: "array";
+    readonly file: "file";
+    readonly any: "any";
+    readonly integer: "integer";
+    readonly float: "float";
+    readonly double: "double";
+    readonly date: "date";
+    readonly datetime: "datetime";
+    readonly jsonSchema: "jsonSchema";
+};
+export type TypeDesc = (typeof types)[keyof typeof types];