@uipath/maestro-builder-sdk 6.11.6 → 6.12.0

package/dist/bpmn/typed-node.js

@@ -19,12 +19,16 @@ export function registryTypeNames() {
  * `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep resolution snapshot-only.
  *
  * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @param inline - A spec supplied by the author, which is used as is.
  * @returns Its emission spec.
  * @throws If the type is in neither the snapshot nor the registry — which means a
  * typo, or no `uip` to ask.
  */
-export function registryType(type) {
-    const spec = REGISTRY.types[type] ?? resolveFromRegistry(type);
+export function registryType(type, inline) {
+    // An inline spec wins over both the snapshot and the tenant — it is the author
+    // saying "emit THIS", for a type the snapshot lacks and no `uip` can describe, or
+    // for one the snapshot describes wrongly. See `ActivityNodeOpts.spec`.
+    const spec = inline ?? REGISTRY.types[type] ?? resolveFromRegistry(type);
     if (!spec) {
         throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
             + `(uip ${REGISTRY.provenance.uipVersion}) and the registry could not be asked for this one either — `
@@ -82,7 +86,22 @@ export const REGISTRY_GAPS = {
     // which `uip maestro bpmn validate` has always accepted. So the guard was right
     // that they are undeclared and wrong that they are invalid — recorded here rather
     // than by loosening the guard, which is what catches an author's typo.
-    'Intsvc.ActivityExecution': { extraContext: ['activity', 'resourceKey'] },
+    // `requiredContext` — context fields the PLATFORM requires and the registry
+    // snapshot does not mark required (or, here, does not declare at all).
+    //
+    // `Intsvc.ActivityExecution` must carry `activity`; without it `uip maestro bpmn
+    // validate` reports
+    //
+    //     [canvas] [ERROR] EMPTY_REQUIRED_FIELD: The field 'activity' in node 'op' is
+    //                      required but has no value.
+    //
+    // and `check` could not know, because it derives required fields from the snapshot.
+    // The connector emitter has always written `activity`, so this only bites a
+    // hand-rolled `.activity()` — but it bit it at the LAST rung. The divergence is
+    // measured rather than assumed: `bpmn-registry-required-drift.test.ts` diffs the
+    // required-field set the canvas validator carries against the snapshot's, over every
+    // type both know, and asserts the only difference is what this table records.
+    'Intsvc.ActivityExecution': { extraContext: ['activity', 'resourceKey'], requiredContext: ['activity'] },
     // `outputRowsFixed` — the type permits EXACTLY the output row its spec declares.
     // A mapped second row is refused:
     //
@@ -115,8 +134,8 @@ function identifierize(name) {
         .join('');
 }
 /** The variable a typed node's output row writes, or `undefined` when it has none. */
-export function typedNodeOutputVar(id, type, outputVar) {
-    const spec = registryType(type);
+export function typedNodeOutputVar(id, type, outputVar, inline) {
+    const spec = registryType(type, inline);
     if (!spec.output)
         return undefined;
     return outputVar ?? `${id}_${identifierize(spec.output.name)}`;
@@ -182,7 +201,13 @@ function contextRows(m, type, spec, supplied, verbatim = false) {
     // it and the author never learns why their setting did nothing — so it is
     // refused. The exception is a type with a recorded `extraContext` gap, where the
     // platform is known to accept fields the registry omits.
-    const known = new Set([...spec.context.map((f) => f.name), ...(REGISTRY_GAPS[type]?.extraContext ?? [])]);
+    const known = new Set([
+        ...spec.context.map((f) => f.name),
+        ...(REGISTRY_GAPS[type]?.extraContext ?? []),
+        // A field the platform REQUIRES is necessarily one it permits, so recording it as
+        // required is enough — an `extraContext` twin is not also needed.
+        ...(REGISTRY_GAPS[type]?.requiredContext ?? []),
+    ]);
     const unknown = Object.keys(supplied).filter((k) => !known.has(k));
     if (unknown.length) {
         throw new Error(`context field(s) ${unknown.map((u) => `"${u}"`).join(', ')} are not declared by this extension type. ` +
@@ -234,10 +259,16 @@ function inputRows(m, spec, inputs) {
         // platform does not read, and one no validator complains about.
         //
         // So: the declared field decides when there is one, the key when there is not.
+        //
+        // The same split decides the TYPE of an undeclared field. Every undeclared value
+        // used to be written as a `json` body, so a scalar came out JSON-quoted —
+        // `recordId` as `"1111-…"`, quotes included, where every real export writes
+        // `type="string" value="1111-…"`. A structured value is still a json body; a
+        // scalar is written as the `value` attribute, the way a declared scalar is.
         const declared = new Map(spec.inputs.map((f) => [f.name, f]));
         return keys.map((k) => {
             const field = declared.get(k);
-            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? 'json');
+            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? inferredInputType(inputs[k]));
         });
     }
     if (!spec.inputName)
@@ -277,6 +308,23 @@ function payloadInput(m, name, target, value, type) {
         props.target = target;
     return m.create('uipath:Input', props);
 }
+/** `json` for an object or array, `string` for anything else — see `inputRows`. */
+function inferredInputType(value) {
+    return value !== null && typeof value === 'object' ? 'json' : 'string';
+}
+/** `uipath:input` payload rows exactly as the caller spelled them, deriving nothing. */
+export function verbatimInputRows(m, rows) {
+    return rows.map((row) => {
+        const props = { name: row.name, type: row.type ?? 'string' };
+        if (row.target !== undefined)
+            props.target = row.target;
+        if (row.value !== undefined)
+            props.value = row.value;
+        if (row.body !== undefined)
+            props.body = jsonBody(row.body);
+        return m.create('uipath:Input', props);
+    });
+}
 /** The `uipath:output` row, when the type declares one. */
 function outputRow(m, spec, varName) {
     if (!spec.output)
@@ -308,7 +356,7 @@ export function createTypedNode(m, id, type, input,
  * Optional so a caller with no variable context still gets today's behaviour.
  */
 varType) {
-    const spec = registryType(type);
+    const spec = registryType(type, input.spec);
     if (!spec.element || !spec.tag) {
         throw new Error(`extension type "${type}" has no element/tag in the registry snapshot; it cannot be authored.`);
     }
@@ -352,7 +400,10 @@ varType) {
         }
         payload.context = m.create('uipath:Context', context);
     }
-    const ins = inputRows(m, spec, input.inputs ?? {});
+    // Spelled out by the caller: emit exactly these rows, deriving nothing — see
+    // TypedNodeInput.inputRows. This is what lets a connector's per-parameter rows
+    // (`name="start" type="string" value="0" target="query"`) survive a round trip.
+    const ins = input.inputRows ? verbatimInputRows(m, input.inputRows) : inputRows(m, spec, input.inputs ?? {});
     if (ins.length)
         payload.input = ins;
     const rows = [];
@@ -365,7 +416,7 @@ varType) {
             payload.output = rows;
         return finish(m, spec, id, input.name, payload);
     }
-    const outVar = typedNodeOutputVar(id, type, input.outputVar);
+    const outVar = typedNodeOutputVar(id, type, input.outputVar, spec);
     const out = outVar ? outputRow(m, spec, outVar) : undefined;
     if (out)
         rows.push(out);
@@ -476,8 +527,8 @@ function moddleElementOf(element) {
  * @param type - The extension type.
  * @returns Its fields that must be bound, with the target each binding needs.
  */
-export function bindingRequiredFields(type) {
-    return registryType(type).context.filter((f) => f.bindingInfo !== null && f.required);
+export function bindingRequiredFields(type, inline) {
+    return registryType(type, inline).context.filter((f) => f.bindingInfo !== null && f.required);
 }
 /**
  * Required context fields the author left unset and the registry cannot default.
@@ -490,10 +541,21 @@ export function bindingRequiredFields(type) {
  * @param context - The context values the author supplied.
  * @returns The names of required fields with no value and no default.
  */
-export function missingRequiredContext(type, context = {}) {
-    return registryType(type)
-        .context.filter((f) => f.required && context[f.name] === undefined && (f.default ?? '') === '')
+export function missingRequiredContext(type, context = {}, inline) {
+    // The platform's test is `isNilOrEmpty(field.value)`, so a field present and BLANK is
+    // as missing as one absent — and blank is the likelier authoring slip of the two, a
+    // value that came from an expression or a variable that had nothing in it. Checking
+    // only for `undefined` let every one of those through to the last rung.
+    const unset = (name) => {
+        const v = context[name];
+        return v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    };
+    const declared = registryType(type, inline)
+        .context.filter((f) => f.required && unset(f.name) && (f.default ?? '') === '')
         .map((f) => f.name);
+    // Fields the platform requires that the snapshot does not — see `REGISTRY_GAPS`.
+    const gaps = (REGISTRY_GAPS[type]?.requiredContext ?? []).filter((name) => !declared.includes(name) && unset(name));
+    return [...declared, ...gaps];
 }
 /**
  * Required PAYLOAD fields the author left unset.
@@ -519,9 +581,9 @@ export function missingRequiredInputs(type, inputs = {},
  * genuinely does not spell (it writes `connection`). Reading both makes this
  * agree with the CLI instead of guessing on either side of it.
  */
-context = {}) {
+context = {}, inline) {
     const notEnforced = new Set(REGISTRY_GAPS[type]?.notEnforcedInputs ?? []);
-    return registryType(type)
+    return registryType(type, inline)
         .inputs.filter((f) => f.required &&
         !notEnforced.has(f.name) &&
         inputs[f.name] === undefined &&
@@ -560,8 +622,8 @@ context = {}) {
  * @param type - The extension type.
  * @returns The required payload field names that cannot be expressed, or `[]`.
  */
-export function unsatisfiableRequiredInputs(type) {
-    const spec = registryType(type);
+export function unsatisfiableRequiredInputs(type, inline) {
+    const spec = registryType(type, inline);
     if (spec.inputPattern !== 'mergedBody' && spec.inputPattern !== 'splitInputsItemData')
         return [];
     return spec.inputs.filter((f) => f.required).map((f) => f.name);

package/dist/cli/commands/bpmn.js

@@ -18,6 +18,7 @@ export function registerBpmnCommands(program) {
         .description('Check authored TypeScript. Check a .bpmn with `uip maestro bpmn validate`.')
         .argument('<input>', 'a .bpmn.ts path or bare name')
         .option('--source', 'check authored TypeScript')
+        .option('--graph', 'also print the resolved wiring: every element with the flows leaving it, implied edges marked ~>')
         .addOption(retiredCompiledOption())
         .action(async (input, options) => {
         let mode;
@@ -32,7 +33,10 @@ export function registerBpmnCommands(program) {
             refuse('flow-sdk bpmn check --compiled: use `uip maestro bpmn validate <file.bpmn>`');
             return;
         }
-        await invoke('bpmn check', () => loadTool(import.meta.url, '../../bpmn/check-cli.js'), [input]);
+        const argv = [input];
+        if (options.graph)
+            argv.push('--graph');
+        await invoke('bpmn check', () => loadTool(import.meta.url, '../../bpmn/check-cli.js'), argv);
     });
     family.command('tidy')
         .description('Add diagram layout to a compiled .bpmn artifact.')
@@ -49,10 +53,12 @@ export function registerBpmnCommands(program) {
         .argument('<input>', 'input .bpmn path')
         .option('-o, --output <file>', 'output .bpmn.ts path')
         .option('--import <specifier>', 'SDK import specifier in generated source')
+        .option('--style <style>', 'explicit (default) writes one call per element and flow; nested lifts boundary events, gateways and event sub-processes into the nesting constructs where the graph is provably the same')
         .action(async (input, options) => {
         const argv = [input];
         addValue(argv, '-o', options.output);
         addValue(argv, '--import', options.import);
+        addValue(argv, '--style', options.style);
         await invoke('bpmn decompile', () => loadTool(import.meta.url, '../../bpmn/decompile-cli.js'), argv);
     });
     family

package/dist/index.d.ts

@@ -24,9 +24,12 @@ export type { CaseRule, CaseRuleInput, CaseRuleGrid, WhenExpression, CaseJsonPre
 export { serialize as serializeCase } from './case/serialize.js';
 export { decompile as decompileCase, decompileWithDiagnostics as decompileCaseWithDiagnostics } from './case/decompile.js';
 export { bpmn } from './bpmn/bpmn-sdk.js';
-export type { BuiltBpmn, BpmnNode, BpmnFlow, BpmnVarDecl, EventDef, GatewayKind, EventKind, LoopSpec, RetrySpec, ActivityOpts, HttpOpts, } from './bpmn/bpmn-sdk.js';
+export type { BuiltBpmn, BpmnNode, BpmnFlow, BpmnVarDecl, EventDef, GatewayKind, EventKind, LoopSpec, RetrySpec, ActivityOpts, HttpOpts, ActivityBodyFn, ArmBodyFn, HandlerOpts, ErrorHandlerOpts, TimerHandlerOpts, MessageHandlerOpts, ChooseArm, ChooseOpts, SplitOpts, JoinOpts, EventSubProcessOpts, FlowMode, } from './bpmn/bpmn-sdk.js';
+export { PathBuilder, ActivityBuilder } from './bpmn/bpmn-sdk.js';
+export { renderGraph as renderBpmnGraph, graphModel as bpmnGraphModel } from './bpmn/graph.js';
+export type { GraphScope as BpmnGraphScope, GraphNode as BpmnGraphNode, GraphEdge as BpmnGraphEdge } from './bpmn/graph.js';
 export { registryTypeNames, registryType, isSnapshotType } from './bpmn/typed-node.js';
-export type { RegistryTypeSpec, RegistryContextField, RegistryOutput } from './bpmn/typed-node.js';
+export type { RegistryTypeSpec, RegistryContextField, RegistryInputField, RegistryOutput, TypedContextRow, TypedInputRow, TypedOutputRow } from './bpmn/typed-node.js';
 export { serialize as serializeBpmn } from './bpmn/serialize.js';
 export { check as checkBpmn } from './bpmn/check.js';
 export type { Diagnostic as BpmnDiagnostic } from './bpmn/check.js';

package/dist/index.js

@@ -27,6 +27,9 @@ export { serialize as serializeCase } from './case/serialize.js';
 export { decompile as decompileCase, decompileWithDiagnostics as decompileCaseWithDiagnostics } from './case/decompile.js';
 // BPMN authoring API. `bpmn()` exposes only BPMN methods.
 export { bpmn } from './bpmn/bpmn-sdk.js';
+export { PathBuilder, ActivityBuilder } from './bpmn/bpmn-sdk.js';
+// The resolved wiring `bpmn check --graph` prints, for a tool that wants it as data.
+export { renderGraph as renderBpmnGraph, graphModel as bpmnGraphModel } from './bpmn/graph.js';
 // The registry snapshot the typed nodes emit from — exposed so the coverage
 // ledger and its audit read the same source the emitter does. `isSnapshotType`
 // separates the two answers `registryType` now gives: a type the snapshot carries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.11.6",
+  "version": "6.12.0",
   "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": "db117054e312c3c2aa7b7b208d3a92fc68de7fb9"
+  "gitref": "82b2ac95dd3b9af08b6a40f3421af49a5c95d7c8"
 }