@uipath/maestro-builder-sdk 6.51.3 → 6.52.0

package/dist/check.d.ts

@@ -52,3 +52,11 @@ export declare const SCHEDULE_PATTERN: string;
  * and day names, and the Quartz specials `L W LW ? * #`.
  */
 export declare const SCHEDULE_CRON_PATTERN: string;
+/**
+ * The one thing `check` says about runtimes: a flow with a node from a node-type
+ * package does not run on the UiPath platform, which runs exactly its registry.
+ * Reported once per flow, naming the steps and their packages, as a WARNING: the
+ * flow is still a correct workflow for a runtime that loads the package (the
+ * local engine), it just cannot be validated or published through `uip`.
+ */
+export declare const PACKAGE_NODES_NOT_PLATFORM = "PACKAGE_NODES_NOT_PLATFORM";

package/dist/check.js

@@ -892,6 +892,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
     }
     reportUnreachableHitlOutcomes(hitlChoiceNoPorts, exprs, diags);
     checkRegisteredFamilies(registeredSteps, unresolvedSteps, stepNames, diags);
+    checkPackageNodes(registeredSteps, diags);
     // The ids this scope's other nodes get, for the file-wide nodeId check in `check`.
     for (const n of stepNames)
         if (!ledger.taken.has(n))
@@ -2819,6 +2820,36 @@ function catalogued(entry, step, code, message, suggestion) {
     // Key order as the per-family rules always wrote it — `check --json` prints it.
     return { level: known.severity, code, step, message, ...(suggestion !== undefined ? { suggestion } : {}) };
 }
+/**
+ * The one thing `check` says about runtimes: a flow with a node from a node-type
+ * package does not run on the UiPath platform, which runs exactly its registry.
+ * Reported once per flow, naming the steps and their packages, as a WARNING: the
+ * flow is still a correct workflow for a runtime that loads the package (the
+ * local engine), it just cannot be validated or published through `uip`.
+ */
+export const PACKAGE_NODES_NOT_PLATFORM = 'PACKAGE_NODES_NOT_PLATFORM';
+function checkPackageNodes(steps, diags) {
+    const byPackage = new Map();
+    let first;
+    for (const [name, placed] of steps) {
+        const origin = placed.entry.family.package;
+        if (origin === undefined)
+            continue;
+        first ??= name;
+        const list = byPackage.get(origin.name) ?? [];
+        list.push(`"${name}" (${placed.impl.typeName})`);
+        byPackage.set(origin.name, list);
+    }
+    if (first === undefined)
+        return;
+    const packages = [...byPackage].map(([pkg, names]) => `${pkg}: ${names.join(', ')}`).join('; ');
+    diags.push({
+        level: 'warning', code: PACKAGE_NODES_NOT_PLATFORM, step: first,
+        message: `This flow uses node types from a node-type package (${packages}). The UiPath platform runs only its own registry, `
+            + 'so `uip maestro flow validate` refuses the file and it cannot be published; it runs on a runtime that loads the package, '
+            + 'such as the local engine (`flow-debug`).',
+    });
+}
 /** Run each registered family's own rules over all of its placements in this flow. */
 function checkRegisteredFamilies(steps, unresolved, stepNames, diags) {
     const byFamily = new Map();
@@ -2969,7 +3000,7 @@ placed, opts, carried) {
         if (!placed)
             return;
         const { impl } = placed;
-        if (impl.definition === 'per-tenant' && placed.carried !== undefined) {
+        if (impl.definition !== 'bundled' && placed.carried !== undefined) {
             // At a carried version the carried definition answers, as serialize asks
             // it: the type's declaration covers only the versions it registers.
             if (!definitionHasErrorPort(placed.carried)) {
@@ -2977,7 +3008,7 @@ placed, opts, carried) {
                 return;
             }
         }
-        else if (impl.definition === 'per-tenant') {
+        else if (impl.definition !== 'bundled') {
             // The definition serialize will be supplied, when check's options can name
             // it (a connector's, from the library); the type answers without it otherwise.
             const def = impl.checkDefinition?.(placed.spec, opts);

package/dist/cli/commands/flow.js

@@ -92,6 +92,7 @@ export function registerFlowCommands(program) {
         .option('--import <specifier>', 'SDK import specifier in generated source')
         .option('--strict', 'fail on unsupported constructs')
         .option('--no-pipeline', 'do not emit a brownfield pipeline helper')
+        .option('--package <name...>', 'trust and load this node-type package (repeatable); otherwise package.json "maestroBuilderSdk".nodePackages decides')
         .action(async (input, options) => {
         const argv = [input];
         addValue(argv, '-o', options.output);
@@ -100,6 +101,8 @@ export function registerFlowCommands(program) {
             argv.push('--strict');
         if (options.pipeline === false)
             argv.push('--no-pipeline');
+        for (const name of options.package ?? [])
+            argv.push('--package', name);
         await invoke('flow decompile', () => import('../../decompile-cli.js'), argv);
     });
     flow.command('merge')
@@ -112,6 +115,7 @@ export function registerFlowCommands(program) {
         .option('--library <dir>', 'connector library, for compiling with --baseline-from or a .flow.ts edited source')
         .option('--bindings <file>', 'bindings.json, for the same compiles')
         .option('--strict', 'refuse when the no-edit round trip (the baseline) differs from the original')
+        .option('--package <name...>', 'trust and load this node-type package for --baseline-from (repeatable)')
         .allowExcessArguments()
         .action(async (_edited, options, command) => {
         const pair = namedOrLegacySecond(command, {
@@ -129,6 +133,8 @@ export function registerFlowCommands(program) {
         addValue(argv, '--bindings', options.bindings);
         if (options.strict)
             argv.push('--strict');
+        for (const name of options.package ?? [])
+            argv.push('--package', name);
         await invoke('flow merge', () => import('../../merge-cli.js'), argv);
     });
 }

package/dist/cli-run.d.ts

@@ -1,4 +1,6 @@
 export type CliExitCode = 0 | 1 | 2;
 export declare function runWhenInvokedDirectly(moduleUrl: string, label: string, run: (argv: string[]) => Promise<CliExitCode> | CliExitCode): void;
 /** The value after `name` in `argv`, or `undefined`. */
+/** Every value of a repeatable flag, in order: `--package a --package b` → `['a', 'b']`. */
+export declare function flagValues(argv: readonly string[], flag: string): string[];
 export declare function flagValue(argv: readonly string[], name: string): string | undefined;

package/dist/cli-run.js

@@ -51,6 +51,14 @@ export function runWhenInvokedDirectly(moduleUrl, label, run) {
     });
 }
 /** The value after `name` in `argv`, or `undefined`. */
+/** Every value of a repeatable flag, in order: `--package a --package b` → `['a', 'b']`. */
+export function flagValues(argv, flag) {
+    const out = [];
+    for (let i = 0; i < argv.length - 1; i++)
+        if (argv[i] === flag)
+            out.push(argv[i + 1]);
+    return out;
+}
 export function flagValue(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;

package/dist/core/nodes/extensions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The hand-off between a node-type package and the artifact's registry.
+ *
+ * `@uipath/maestro-builder-sdk/extend` is a builder entry and stays light at
+ * import (FB009): it must not load the Flow registry, which pulls the bundled
+ * definitions in. So a package's family is CONTRIBUTED here, and the registry
+ * ADOPTS whatever was contributed when it loads — at compile time, before any
+ * flow is built — and installs itself as the sink for every later contribution,
+ * which it then registers at once. A refusal (a kind a built-in family owns, a
+ * type that is not `definition: 'package'`) surfaces at adoption, still before
+ * the first node is serialized.
+ */
+import type { ArtifactContexts } from './node-type.js';
+import type { NodeFamily } from './family.js';
+type Sink = (family: NodeFamily<ArtifactContexts>) => void;
+/** Hand a package's family to the artifact's registry, now or when it loads. */
+export declare function contributeFamily(family: NodeFamily<ArtifactContexts>): void;
+/**
+ * The registry calls this once at load: it receives every family contributed so
+ * far and every one contributed after. Families are adopted in contribution order.
+ */
+export declare function adoptContributedFamilies(adopt: Sink): void;
+export {};

package/dist/core/nodes/extensions.js

@@ -0,0 +1,18 @@
+const pending = [];
+let sink;
+/** Hand a package's family to the artifact's registry, now or when it loads. */
+export function contributeFamily(family) {
+    if (sink !== undefined)
+        sink(family);
+    else
+        pending.push(family);
+}
+/**
+ * The registry calls this once at load: it receives every family contributed so
+ * far and every one contributed after. Families are adopted in contribution order.
+ */
+export function adoptContributedFamilies(adopt) {
+    sink = adopt;
+    for (const family of pending.splice(0))
+        adopt(family);
+}

package/dist/core/nodes/family.d.ts

@@ -25,12 +25,25 @@ export interface Placement<Spec = unknown> {
     /** The version the node will be emitted at. */
     readonly version: string;
 }
+/** The npm package a node family comes from, when it is not built into the SDK. */
+export interface PackageOrigin {
+    /** The package name an author imports, e.g. `'@uipath/flow-local-nodes'`. */
+    readonly name: string;
+    /** The package's version, when it knows it; written into each definition's provenance. */
+    readonly version?: string;
+}
 export interface NodeFamily<Ctx extends ArtifactContexts> {
     /** Stable id, e.g. `'data-fabric'`. Unique within the artifact's registry. */
     readonly id: string;
     readonly title: string;
     readonly types: readonly AnyNodeType<Ctx>[];
     readonly diagnostics: DiagnosticCatalog;
+    /**
+     * Set on a family registered from a node-type package. Every type of such a
+     * family declares `definition: 'package'`, and only such a family may; a
+     * built-in family never sets this.
+     */
+    readonly package?: PackageOrigin;
     /** Rules over every placement of this family's types, after the per-node checks. */
     check?(placements: readonly Placement[], ctx: Ctx['familyCheck']): void;
 }

package/dist/core/nodes/node-type.d.ts

@@ -25,7 +25,19 @@ import type { TypeDesc } from '../expr.js';
  * its declared inputs) is read from. `per-tenant`: built per tenant or per call —
  * there is no bundled entry to ask, so the node type declares those answers itself.
  */
-export type DefinitionSource = 'bundled' | 'per-tenant';
+/**
+ * Where a node type's definition comes from.
+ *
+ * - `bundled`: the SDK's bundled registry snapshot has it, so the node carries no
+ *   definition and the bundle answers `errorPort`.
+ * - `per-tenant`: a connector-shaped type the tenant defines; the type supplies its
+ *   definition at serialize time and declares `errorPort`.
+ * - `package`: a type from a node-type package (`@uipath/maestro-builder-sdk/extend`);
+ *   the package ships the definition, the type writes it into the file with its
+ *   provenance, and the UiPath platform does not run it. A built-in family may not
+ *   declare one — the registry refuses it (see `NodeTypeRegistry`).
+ */
+export type DefinitionSource = 'bundled' | 'per-tenant' | 'package';
 /**
  * One place a spec carries a value the artifact evaluates against its scope.
  * `value` is walked deeply for expressions; `code` is a script body whose
@@ -104,6 +116,12 @@ export type OutputContract = {
  */
 export interface FactoryCall {
     readonly factory: string;
+    /**
+     * The module the factory is imported from, when it is not the SDK: a node-type
+     * package's own name. Decompile defaults it to the type's family `package.name`,
+     * so a `print` implementation sets it only to import from somewhere else.
+     */
+    readonly module?: string;
     readonly positional?: readonly string[];
     readonly options?: ReadonlyArray<readonly [name: string, source: string | undefined]>;
     /** A note for the reader, written as a block comment after the call (the artifact escapes it). */

package/dist/core/nodes/package-definition.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The node definition a node-type package writes into a compiled `.flow`.
+ *
+ * A package type has no platform definition — neither the SDK's bundled snapshot
+ * nor the tenant has one — so the file has to carry everything a reader needs:
+ * the designer's display and handles, the input and output schemas, and the
+ * `model.expansion` template the `.flow` → BPMN converter expands.
+ *
+ * ## Why one-node expansion
+ *
+ * The product's converter (vendored in `local-engine`) resolves a node's
+ * definition as `manifestDef ?? fileDef` and reads a node's per-instance input
+ * VALUES only through a definition's `model.expansion`: a `context` entry's
+ * `source: 'node.data.inputs.<name>'` is read off each placed node while the
+ * template is expanded. So every package definition expands to exactly one
+ * `bpmn:ServiceTask` that REPLACES the node under its own id, carries
+ * `<uipath:type value="<serviceType>">`, its inputs as context, and its
+ * `=response` / `=Error` output rows — the element shape a runtime's dispatch
+ * lane reads for a connector. Expansion drops the node's original edges, so the
+ * template re-creates the `success` edge and, when the author wired `.onError`,
+ * an error boundary with the `error` edge.
+ *
+ * The input NAMES are the contract with the runtime half of the package: a
+ * handler reads them off `TaskContext.inputs`. A `string` context entry is
+ * emitted as `value` and a `json` one as a JSON `body`; the converter turns a
+ * falsy `string` into `""` and a falsy `json` into `{}`, so a package encodes
+ * booleans and numbers as `=js:` expressions rather than relying on either.
+ */
+/** One authored input of a package node. */
+export interface PackageInputField {
+    readonly type: 'string' | 'boolean' | 'number' | 'array' | 'object';
+    readonly description: string;
+    readonly required?: boolean;
+    readonly enum?: readonly string[];
+    readonly default?: unknown;
+}
+/** One field of a package node's `output`. */
+export interface PackageOutputField {
+    readonly type: 'string' | 'boolean' | 'number' | 'array' | 'object';
+    readonly description: string;
+}
+/** What a package declares about one node; `defineNodeDefinition` does the rest. */
+export interface PackageNodeShape {
+    /** The `.flow` node type, e.g. `acme.ledger.post`. */
+    readonly nodeType: string;
+    /** The BPMN service type a runtime dispatches on, e.g. `Acme.Ledger.Post`. */
+    readonly serviceType: string;
+    /** The definition version; the node's `typeVersion`. Default `1.0`. */
+    readonly version?: string;
+    readonly label: string;
+    readonly description: string;
+    /** A Lucide icon name the designer draws, e.g. `file-text`. */
+    readonly icon: string;
+    /** The designer's category for the add-node panel. Default `package`. */
+    readonly category?: string;
+    readonly tags?: readonly string[];
+    readonly inputs: Readonly<Record<string, PackageInputField>>;
+    readonly outputs: Readonly<Record<string, PackageOutputField>>;
+}
+export declare const DEFAULT_PACKAGE_DEFINITION_VERSION = "1.0";
+/**
+ * The definition `defineNodeDefinition` returns: the complete manifest, with the
+ * fields a package's node type reads back typed — `version` is the type's
+ * `version` and the snapshot reference's, `model.serviceType` is what the runtime
+ * half claims.
+ */
+export interface PackageNodeDefinition extends Record<string, unknown> {
+    readonly nodeType: string;
+    readonly version: string;
+    readonly model: Record<string, unknown> & {
+        readonly type: 'bpmn:ServiceTask';
+        readonly serviceType: string;
+    };
+}
+/**
+ * Build a package node's definition from its shape: the complete manifest a
+ * compiled flow carries as a `snapshot` reference, with the one-node expansion
+ * described above. Provenance (`source.package`) is stamped at serialize time
+ * from the family's `package`, not here, so a shape stays free of the package's
+ * own name.
+ */
+export declare function defineNodeDefinition(shape: PackageNodeShape): PackageNodeDefinition;

package/dist/core/nodes/package-definition.js

@@ -0,0 +1,162 @@
+/**
+ * The node definition a node-type package writes into a compiled `.flow`.
+ *
+ * A package type has no platform definition — neither the SDK's bundled snapshot
+ * nor the tenant has one — so the file has to carry everything a reader needs:
+ * the designer's display and handles, the input and output schemas, and the
+ * `model.expansion` template the `.flow` → BPMN converter expands.
+ *
+ * ## Why one-node expansion
+ *
+ * The product's converter (vendored in `local-engine`) resolves a node's
+ * definition as `manifestDef ?? fileDef` and reads a node's per-instance input
+ * VALUES only through a definition's `model.expansion`: a `context` entry's
+ * `source: 'node.data.inputs.<name>'` is read off each placed node while the
+ * template is expanded. So every package definition expands to exactly one
+ * `bpmn:ServiceTask` that REPLACES the node under its own id, carries
+ * `<uipath:type value="<serviceType>">`, its inputs as context, and its
+ * `=response` / `=Error` output rows — the element shape a runtime's dispatch
+ * lane reads for a connector. Expansion drops the node's original edges, so the
+ * template re-creates the `success` edge and, when the author wired `.onError`,
+ * an error boundary with the `error` edge.
+ *
+ * The input NAMES are the contract with the runtime half of the package: a
+ * handler reads them off `TaskContext.inputs`. A `string` context entry is
+ * emitted as `value` and a `json` one as a JSON `body`; the converter turns a
+ * falsy `string` into `""` and a falsy `json` into `{}`, so a package encodes
+ * booleans and numbers as `=js:` expressions rather than relying on either.
+ */
+export const DEFAULT_PACKAGE_DEFINITION_VERSION = '1.0';
+const ERROR_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: ['code', 'message', 'detail', 'category', 'status'],
+    properties: {
+        code: { type: 'string', description: 'Error code as a string' },
+        message: { type: 'string', description: 'High-level error message' },
+        detail: { type: 'string', description: 'Detailed error description' },
+        category: { type: 'string', description: 'Error category' },
+        status: { type: 'integer', description: 'HTTP status code' },
+    },
+    additionalProperties: false,
+};
+/** The context entry type the converter emits for a field: structured values ride as a JSON body. */
+function contextType(field) {
+    return field.type === 'array' || field.type === 'object' ? 'json' : 'string';
+}
+/**
+ * Build a package node's definition from its shape: the complete manifest a
+ * compiled flow carries as a `snapshot` reference, with the one-node expansion
+ * described above. Provenance (`source.package`) is stamped at serialize time
+ * from the family's `package`, not here, so a shape stays free of the package's
+ * own name.
+ */
+export function defineNodeDefinition(shape) {
+    const version = shape.version ?? DEFAULT_PACKAGE_DEFINITION_VERSION;
+    const context = Object.entries(shape.inputs).map(([name, field]) => ({
+        name,
+        type: contextType(field),
+        source: `node.data.inputs.${name}`,
+    }));
+    const properties = Object.fromEntries(Object.entries(shape.inputs).map(([name, field]) => [name, {
+            type: field.type,
+            description: field.description,
+            ...(field.enum ? { enum: [...field.enum] } : {}),
+        }]));
+    const required = Object.entries(shape.inputs).filter(([, f]) => f.required).map(([name]) => name);
+    const inputDefaults = Object.fromEntries(Object.entries(shape.inputs).filter(([, f]) => f.default !== undefined).map(([name, f]) => [name, f.default]));
+    return {
+        nodeType: shape.nodeType,
+        version,
+        category: shape.category ?? 'package',
+        description: shape.description,
+        tags: shape.tags ? [...shape.tags] : ['package', ...shape.nodeType.split('.').slice(1)],
+        sortOrder: 90,
+        supportsErrorHandling: true,
+        display: { label: shape.label, icon: shape.icon },
+        handleConfiguration: [
+            { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
+            {
+                position: 'right',
+                handles: [
+                    { id: 'success', type: 'source', handleType: 'output' },
+                    {
+                        id: 'error', label: 'Error', type: 'source', handleType: 'output',
+                        visible: '{inputs.errorHandlingEnabled}', constraints: { maxConnections: 1 },
+                    },
+                ],
+            },
+        ],
+        debug: { runtime: 'bpmnEngine' },
+        model: {
+            type: 'bpmn:ServiceTask',
+            serviceType: shape.serviceType,
+            version: 'v1',
+            expansion: {
+                nodes: [
+                    {
+                        id: '{nodeId}',
+                        type: 'bpmn:ServiceTask',
+                        replaceOriginal: true,
+                        position: { x: 0, y: 0 },
+                        data: {
+                            label: '{node.data.label}',
+                            model: {
+                                serviceType: shape.serviceType,
+                                version: 'v1',
+                                context,
+                                outputs: [
+                                    { name: 'output', type: 'object', source: '=response', var: 'output' },
+                                    { name: 'error', type: 'object', source: '=Error', var: 'error' },
+                                ],
+                            },
+                        },
+                    },
+                    {
+                        condition: "hasEdgeFromHandle('error')",
+                        id: '_Implicit_BoundaryError_{nodeId}',
+                        type: 'bpmn:BoundaryEvent',
+                        parentId: null,
+                        position: { x: 0, y: 0 },
+                        data: {
+                            label: 'Error',
+                            attachedToId: '{nodeId}',
+                            eventDefinition: { type: 'bpmn:ErrorEventDefinition', id: '_Implicit_BoundaryError_{nodeId}_Error' },
+                            // The `=Error` envelope is written by the BOUNDARY's output row when it
+                            // fires, not by the failed task's own row — without this, `.onError`
+                            // handlers read `<step>.error` as undefined. `custom: true` keeps the var
+                            // as written: the converter would otherwise prefix it with the boundary's id.
+                            model: { outputs: [{ name: 'error', type: 'object', source: '=Error', var: '{nodeId}.error', custom: true }] },
+                        },
+                    },
+                ],
+                edges: [
+                    { matchOriginalEdgeByHandle: 'success', preserveEdgeId: true, source: '{nodeId}', type: 'bpmn:SequenceFlow' },
+                    {
+                        condition: "hasEdgeFromHandle('error')",
+                        matchOriginalEdgeByHandle: 'error',
+                        preserveEdgeId: true,
+                        source: '_Implicit_BoundaryError_{nodeId}',
+                        type: 'bpmn:SequenceFlow',
+                    },
+                ],
+            },
+        },
+        inputDefinition: { type: 'object', properties, required },
+        inputDefaults,
+        outputDefinition: {
+            output: {
+                type: 'object',
+                description: `What ${shape.label} produced`,
+                source: '=response',
+                var: 'output',
+                schema: {
+                    $schema: 'http://json-schema.org/draft-07/schema#',
+                    type: 'object',
+                    properties: Object.fromEntries(Object.entries(shape.outputs).map(([k, v]) => [k, { type: v.type, description: v.description }])),
+                },
+            },
+            error: { type: 'object', description: 'Error information if the step fails', source: '=Error', var: 'error', schema: ERROR_SCHEMA },
+        },
+    };
+}

package/dist/core/nodes/registry.d.ts

@@ -35,13 +35,25 @@ export interface NodeTypeRegistryOptions {
 export declare class NodeTypeRegistry<Ctx extends ArtifactContexts> {
     #private;
     readonly artifact: string;
-    readonly families: readonly NodeFamily<Ctx>[];
     /**
      * @param artifact - The artifact's name, for messages (`'flow'`).
-     * @param families - Every family this artifact supports, in no significant order.
+     * @param families - Every built-in family this artifact supports, in no significant order.
      * @param options - What the artifact knows that the contract does not.
      */
     constructor(artifact: string, families: readonly NodeFamily<Ctx>[], options: NodeTypeRegistryOptions);
+    /** Every family the registry knows: the built-in ones, then the registered packages' in registration order. */
+    get families(): readonly NodeFamily<Ctx>[];
+    /**
+     * Register a node-type package's family (`@uipath/maestro-builder-sdk/extend`).
+     *
+     * The whole registry is re-indexed with the new family last, under the same
+     * rules construction applies, so a package cannot take a kind, a type name, a
+     * prefix or a diagnostic code a built-in family owns, nor one another package
+     * registered first. A refusal names the package and leaves the live index as
+     * it was. Registering the same family object twice is a no-op: an ESM module
+     * runs once per process, but a test may import a package through two paths.
+     */
+    register(family: NodeFamily<Ctx>): void;
     /**
      * The node type for a spec, by its kind, or undefined when the kind is not
      * registered. When several types share the kind, the one whose `matches(spec)`