@uipath/maestro-builder-sdk 5.2.0

package/dist/core/script-return.d.ts

@@ -0,0 +1,68 @@
+/**
+ * core/script-return — what a `core.action.script` node PUBLISHES.
+ *
+ * A script node's runtime output IS its return value, but the platform's own
+ * definition can only say `output: {type: 'object', description: 'The return
+ * value of the script'}` — the node type has no way to know what any particular
+ * body returns. The designer believes that declaration and types the read as
+ * `Record<string, any>`, so mapping a string-returning script into a `string`
+ * flow output is reported as
+ *
+ *     Type 'Record<string, any>' is not assignable to type 'string'
+ *
+ * on a flow that is correct and runs. The declaration is the thing that is
+ * wrong, and it is knowable at author time: the body is right there.
+ *
+ * So the type rides on the INSTANCE, the same split `httpOutputs` uses — the
+ * bundled definition stays byte-faithful to the platform's, and what the author
+ * wrote (or what their code plainly says) is the only source of shape.
+ *
+ * Two ways in, in precedence order:
+ *
+ *   1. `script({ code, returns })` — the author says so. Always wins.
+ *   2. inference from the body, below — used when `returns` is absent.
+ *
+ * Inference is deliberately TIMID. It answers only when every `return` in the
+ * body agrees, and says nothing at all otherwise: an unknown shape must stay the
+ * definition's open object, because narrowing it wrongly turns a working read
+ * into a designer error — the exact defect this file exists to remove, pointed
+ * the other way.
+ */
+/** The vocabulary a script's output can be declared as. */
+export type ScriptReturnType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+/**
+ * What an author may write for `script({ returns })`: the type outright, or —
+ * for an object return — the FIELDS, which is the spelling every other action's
+ * `returns` uses (`http`, `rpaWorkflow`, `agent`).
+ */
+export type ScriptReturns = ScriptReturnType | Record<string, ScriptReturnType>;
+/** A resolved output declaration: a type, and for objects the fields we know. */
+export interface ScriptOutputShape {
+    type: ScriptReturnType;
+    properties?: Record<string, {
+        type: ScriptReturnType;
+    }>;
+}
+/** Normalize whatever the author wrote into the emitted shape. */
+export declare function declaredScriptShape(returns: ScriptReturns): ScriptOutputShape;
+/**
+ * The TYPE a script body plainly returns, or `undefined` when it does not
+ * plainly return one.
+ *
+ * "Plainly" is the whole contract. Every `return` in the body must resolve to
+ * the same type; one that resolves to nothing (a call, a parameter, anything
+ * whose type is not written down) makes the ANSWER nothing, not a guess from the
+ * returns that did resolve. A body with no `return` at all also answers nothing.
+ *
+ * **It types, it does not enumerate.** An object return comes back as plain
+ * `object`, never as a field list, even though the literal's fields are right
+ * there. A field list is a COMPLETENESS claim — "these are the fields" — and a
+ * body that returns `{a}` on one path and `{a, b}` on another, or assembles
+ * fields in a loop, makes that claim false while the top-level type stays true.
+ * Nothing is lost by declining: the designer types an undescribed object as
+ * `Record<string, any>`, which already admits every field read, so an inferred
+ * field list buys no diagnostic and would rewrite `properties` into every
+ * object-returning script node in every existing flow. An author who wants the
+ * fields written down says so with `returns: {…}`.
+ */
+export declare function inferScriptShape(code: string): ScriptOutputShape | undefined;

package/dist/core/script-return.js

@@ -0,0 +1,197 @@
+/**
+ * core/script-return — what a `core.action.script` node PUBLISHES.
+ *
+ * A script node's runtime output IS its return value, but the platform's own
+ * definition can only say `output: {type: 'object', description: 'The return
+ * value of the script'}` — the node type has no way to know what any particular
+ * body returns. The designer believes that declaration and types the read as
+ * `Record<string, any>`, so mapping a string-returning script into a `string`
+ * flow output is reported as
+ *
+ *     Type 'Record<string, any>' is not assignable to type 'string'
+ *
+ * on a flow that is correct and runs. The declaration is the thing that is
+ * wrong, and it is knowable at author time: the body is right there.
+ *
+ * So the type rides on the INSTANCE, the same split `httpOutputs` uses — the
+ * bundled definition stays byte-faithful to the platform's, and what the author
+ * wrote (or what their code plainly says) is the only source of shape.
+ *
+ * Two ways in, in precedence order:
+ *
+ *   1. `script({ code, returns })` — the author says so. Always wins.
+ *   2. inference from the body, below — used when `returns` is absent.
+ *
+ * Inference is deliberately TIMID. It answers only when every `return` in the
+ * body agrees, and says nothing at all otherwise: an unknown shape must stay the
+ * definition's open object, because narrowing it wrongly turns a working read
+ * into a designer error — the exact defect this file exists to remove, pointed
+ * the other way.
+ */
+import * as ts from 'typescript';
+/** Normalize whatever the author wrote into the emitted shape. */
+export function declaredScriptShape(returns) {
+    if (typeof returns === 'string')
+        return { type: returns };
+    return {
+        type: 'object',
+        properties: Object.fromEntries(Object.entries(returns).map(([k, t]) => [k, { type: t }])),
+    };
+}
+/**
+ * The TYPE a script body plainly returns, or `undefined` when it does not
+ * plainly return one.
+ *
+ * "Plainly" is the whole contract. Every `return` in the body must resolve to
+ * the same type; one that resolves to nothing (a call, a parameter, anything
+ * whose type is not written down) makes the ANSWER nothing, not a guess from the
+ * returns that did resolve. A body with no `return` at all also answers nothing.
+ *
+ * **It types, it does not enumerate.** An object return comes back as plain
+ * `object`, never as a field list, even though the literal's fields are right
+ * there. A field list is a COMPLETENESS claim — "these are the fields" — and a
+ * body that returns `{a}` on one path and `{a, b}` on another, or assembles
+ * fields in a loop, makes that claim false while the top-level type stays true.
+ * Nothing is lost by declining: the designer types an undescribed object as
+ * `Record<string, any>`, which already admits every field read, so an inferred
+ * field list buys no diagnostic and would rewrite `properties` into every
+ * object-returning script node in every existing flow. An author who wants the
+ * fields written down says so with `returns: {…}`.
+ */
+export function inferScriptShape(code) {
+    // Wrap so a top-level `return` parses — this is how the runtime executes it.
+    const sf = ts.createSourceFile('script.ts', `function __block() {\n${code}\n}`, ts.ScriptTarget.ES2020, true);
+    // `var d = Math.floor(...); return { days: d }` is how these bodies are
+    // written, so simple local initializers are resolved before typing a return.
+    // Last write wins: a name reassigned to a different type is a name we cannot
+    // type, and the disagreement below is what discards it.
+    const locals = new Map();
+    const collectLocals = (n) => {
+        if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.initializer) {
+            locals.set(n.name.text, n.initializer);
+        }
+        ts.forEachChild(n, collectLocals);
+    };
+    collectLocals(sf);
+    const shapes = [];
+    const visit = (n) => {
+        // A nested function's `return` belongs to that function, not to the script.
+        if (n !== sf && (ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n))) {
+            if (n.parent !== sf)
+                return;
+        }
+        if (ts.isReturnStatement(n))
+            shapes.push(n.expression ? typeOf(n.expression, locals, 0) : undefined);
+        ts.forEachChild(n, visit);
+    };
+    // Skip the synthetic wrapper so its own body is walked, not treated as nested.
+    ts.forEachChild(sf, (n) => (ts.isFunctionDeclaration(n) && n.body ? ts.forEachChild(n.body, visit) : visit(n)));
+    if (shapes.length === 0)
+        return undefined;
+    // One unresolved return poisons the answer — see the doc comment.
+    if (shapes.some((s) => s === undefined))
+        return undefined;
+    const first = shapes[0];
+    if (shapes.some((s) => s.type !== first.type))
+        return undefined;
+    // Type only — never the fields, see the doc comment.
+    return { type: first.type };
+}
+/** The type of one expression, or undefined when it is not written down. */
+function typeOf(expr, locals, depth) {
+    // Bounded: a local initialized from another local is followed, a cycle is not.
+    if (depth > 8)
+        return undefined;
+    const e = ts.isParenthesizedExpression(expr) ? expr.expression : expr;
+    if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e) || ts.isTemplateExpression(e)) {
+        return { type: 'string' };
+    }
+    if (ts.isNumericLiteral(e))
+        return { type: 'number' };
+    if (e.kind === ts.SyntaxKind.TrueKeyword || e.kind === ts.SyntaxKind.FalseKeyword) {
+        return { type: 'boolean' };
+    }
+    if (ts.isArrayLiteralExpression(e))
+        return { type: 'array' };
+    if (ts.isObjectLiteralExpression(e))
+        return { type: 'object' };
+    // `-1` / `+n` / `!ok` — the operator decides, not the operand.
+    if (ts.isPrefixUnaryExpression(e)) {
+        if (e.operator === ts.SyntaxKind.ExclamationToken)
+            return { type: 'boolean' };
+        if (e.operator === ts.SyntaxKind.MinusToken || e.operator === ts.SyntaxKind.PlusToken) {
+            return typeOf(e.operand, locals, depth + 1)?.type === 'number' ? { type: 'number' } : undefined;
+        }
+        return undefined;
+    }
+    if (ts.isBinaryExpression(e))
+        return binaryShape(e, locals, depth);
+    // `cond ? a : b` — only when both arms agree.
+    if (ts.isConditionalExpression(e)) {
+        const a = typeOf(e.whenTrue, locals, depth + 1);
+        const b = typeOf(e.whenFalse, locals, depth + 1);
+        return a && b && a.type === b.type ? { type: a.type } : undefined;
+    }
+    // A local whose initializer we can type. `$vars.…` is an identifier chain the
+    // script reads from the runtime bag, never a local, so it lands here and
+    // correctly answers nothing.
+    if (ts.isIdentifier(e)) {
+        const init = locals.get(e.text);
+        return init ? typeOf(init, locals, depth + 1) : undefined;
+    }
+    // `String(x)` / `Number(x)` / `Boolean(x)` — the platform's own bodies use
+    // these to coerce before publishing, and the conversion names the type.
+    if (ts.isCallExpression(e) && ts.isIdentifier(e.expression)) {
+        const fn = e.expression.text;
+        if (fn === 'String')
+            return { type: 'string' };
+        if (fn === 'Number' || fn === 'parseInt' || fn === 'parseFloat')
+            return { type: 'number' };
+        if (fn === 'Boolean')
+            return { type: 'boolean' };
+    }
+    // `[...].join(…)` / `x.toFixed(…)` and friends: the METHOD names the type.
+    if (ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression)) {
+        const m = e.expression.name.text;
+        if (m === 'join' || m === 'toFixed' || m === 'toString' || m === 'trim'
+            || m === 'toUpperCase' || m === 'toLowerCase')
+            return { type: 'string' };
+        if (m === 'map' || m === 'filter' || m === 'slice' || m === 'concat' || m === 'sort')
+            return undefined;
+    }
+    return undefined;
+}
+/** `a + b`, comparisons, and the short-circuit operators. */
+function binaryShape(e, locals, depth) {
+    const op = e.operatorToken.kind;
+    // A comparison is a boolean whatever its operands are.
+    if (op === ts.SyntaxKind.EqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsEqualsToken
+        || op === ts.SyntaxKind.ExclamationEqualsToken || op === ts.SyntaxKind.ExclamationEqualsEqualsToken
+        || op === ts.SyntaxKind.LessThanToken || op === ts.SyntaxKind.LessThanEqualsToken
+        || op === ts.SyntaxKind.GreaterThanToken || op === ts.SyntaxKind.GreaterThanEqualsToken) {
+        return { type: 'boolean' };
+    }
+    const left = typeOf(e.left, locals, depth + 1);
+    const right = typeOf(e.right, locals, depth + 1);
+    if (op === ts.SyntaxKind.PlusToken) {
+        // JS `+` is concatenation the moment EITHER side is a string — which is how
+        // these bodies build a message out of a runtime value: `"claim " + $vars.…`.
+        // That is a string no matter what the unknown side turns out to be.
+        if (left?.type === 'string' || right?.type === 'string')
+            return { type: 'string' };
+        if (left?.type === 'number' && right?.type === 'number')
+            return { type: 'number' };
+        return undefined;
+    }
+    if (op === ts.SyntaxKind.MinusToken || op === ts.SyntaxKind.AsteriskToken
+        || op === ts.SyntaxKind.SlashToken || op === ts.SyntaxKind.PercentToken) {
+        // Arithmetic is numeric regardless of what the operands turn out to be —
+        // `$vars.a.output * 2` is a number even though the left side is unknown.
+        return { type: 'number' };
+    }
+    // `a || b` / `a ?? b` — only when both sides agree; the fallback is the point.
+    if (op === ts.SyntaxKind.BarBarToken || op === ts.SyntaxKind.QuestionQuestionToken) {
+        return left && right && left.type === right.type ? { type: left.type } : undefined;
+    }
+    return undefined;
+}

package/dist/core/stable-id.d.ts

@@ -0,0 +1,28 @@
+/**
+ * core/stable-id — a uuid-shaped id derived from a seed, with no randomness.
+ *
+ * The designer mints random uuids for the ids inside a connector's filter tree
+ * and event subscription. We cannot: recompiling an unchanged flow has to be
+ * byte-identical, and a random id would churn every build and show up as a diff
+ * in every artifact review.
+ *
+ * Shared by the event-subscription serializer and the CEQL filter-tree parser so
+ * there is one implementation rather than two that drift.
+ *
+ * ## The `>>> 0` on the last segment is a fix, not a flourish
+ *
+ * `^` in JavaScript yields a SIGNED 32-bit integer, so `(h1 ^ h2)` is negative
+ * about half the time. `(-2023473408).toString(16)` is `'-78a62ef0'`, which is
+ * already 8 characters, so the `padStart(8, '0')` never fires and the `-` lands
+ * in the middle of the id:
+ *
+ *     86592478-0100-4008-8000--78a62ef0100
+ *                             ↑ not a uuid
+ *
+ * Measured over 5,000 seeds before the fix: **2,483 malformed — 49.7%.** Every
+ * other connector event-subscription filter therefore shipped an id the canvas
+ * cannot read as a uuid. Coercing to unsigned first is the whole repair; the
+ * hash itself is unchanged, so a seed that produced a WELL-FORMED id still
+ * produces exactly that id.
+ */
+export declare function stableId(seed: string): string;

package/dist/core/stable-id.js

@@ -0,0 +1,37 @@
+/**
+ * core/stable-id — a uuid-shaped id derived from a seed, with no randomness.
+ *
+ * The designer mints random uuids for the ids inside a connector's filter tree
+ * and event subscription. We cannot: recompiling an unchanged flow has to be
+ * byte-identical, and a random id would churn every build and show up as a diff
+ * in every artifact review.
+ *
+ * Shared by the event-subscription serializer and the CEQL filter-tree parser so
+ * there is one implementation rather than two that drift.
+ *
+ * ## The `>>> 0` on the last segment is a fix, not a flourish
+ *
+ * `^` in JavaScript yields a SIGNED 32-bit integer, so `(h1 ^ h2)` is negative
+ * about half the time. `(-2023473408).toString(16)` is `'-78a62ef0'`, which is
+ * already 8 characters, so the `padStart(8, '0')` never fires and the `-` lands
+ * in the middle of the id:
+ *
+ *     86592478-0100-4008-8000--78a62ef0100
+ *                             ↑ not a uuid
+ *
+ * Measured over 5,000 seeds before the fix: **2,483 malformed — 49.7%.** Every
+ * other connector event-subscription filter therefore shipped an id the canvas
+ * cannot read as a uuid. Coercing to unsigned first is the whole repair; the
+ * hash itself is unchanged, so a seed that produced a WELL-FORMED id still
+ * produces exactly that id.
+ */
+export function stableId(seed) {
+    let h1 = 0x811c9dc5;
+    let h2 = 0x01000193;
+    for (let i = 0; i < seed.length; i++) {
+        h1 = (h1 ^ seed.charCodeAt(i)) * 0x01000193 >>> 0;
+        h2 = (h2 + seed.charCodeAt(i) * (i + 7)) >>> 0;
+    }
+    const hex = (n, len) => (n >>> 0).toString(16).padStart(8, '0').slice(0, len);
+    return `${hex(h1, 8)}-${hex(h2, 4)}-4${hex(h1 >>> 8, 3)}-8${hex(h2 >>> 8, 3)}-${hex(h1 ^ h2, 8)}${hex(h2, 4)}`;
+}