@uipath/maestro-builder-sdk 6.51.3 → 6.52.1

package/dist/case/decompile.js

@@ -506,7 +506,11 @@ function connectorVersion(context) {
     const encoded = metadata?.activityPropertyConfiguration?.configuration;
     if (typeof encoded === 'string' && encoded.startsWith('=jsonString:')) {
         try {
-            return JSON.parse(encoded.slice('=jsonString:'.length))?.essentialConfiguration?.packageVersion;
+            // The activity's version is `instanceParameters.version`. `packageVersion`
+            // is what the platform writes as "1.0.0" on every activity; an SDK plan
+            // once wrote the library version there, so it stays the fallback.
+            const essential = JSON.parse(encoded.slice('=jsonString:'.length))?.essentialConfiguration;
+            return essential?.instanceParameters?.version ?? essential?.packageVersion;
         }
         catch {
             throw new Error('connector task has malformed activity metadata configuration JSON.');

package/dist/case/serialize.js

@@ -11,7 +11,8 @@
 import { IdGen, offlineBindingSeed } from './ids.js';
 import { isUnrestorableSlotId } from './preserve.js';
 import { v31TaskSets } from './task-sets.js';
-import { buildConnectorInputs, nestConnectorBody, transportHttpMethod } from '../core/connector-inputs.js';
+import { buildConnectorInputs, nestConnectorBody, replayInputsOf, transportHttpMethod } from '../core/connector-inputs.js';
+import { buildEssentialConfiguration } from '../core/connector-configuration.js';
 import { EQUALS_EXPR_DIALECT } from '../core/connector-checks.js';
 import { bindingLabelRefusal } from '../core/binding-messages.js';
 import { resolveEventWhere } from '../core/lookups.js';
@@ -1444,7 +1445,7 @@ function connectorTaskData(spec, resolver, elementId, where, executionType) {
     // from the `body` slot. This used to drop the whole wire and push a filled
     // file part into the body, where the runtime does not look for it (#1420).
     const fileParts = (slots.multipartParameters ?? []).filter((part) => part.dataType.toLowerCase() === 'file');
-    context.push(io('metadata', 'json', { body: connectorMetadata(rc, op, slots, executionType) }));
+    context.push(io('metadata', 'json', { body: connectorMetadata(rc, op, slots, elementId, executionType) }));
     const inputs = [
         ioSlot('pathParameters', pathParameters, `${elementId}`),
         ioSlot('queryParameters', queryParameters, `${elementId}`),
@@ -1601,45 +1602,39 @@ function folderBindingRef(resolver, name, connection, site) {
     }
     return { id };
 }
-/** The connector `metadata` json blob: the FUNCTIONAL essentialConfiguration +
+/**
+ * The connector `metadata` json blob: the FUNCTIONAL essentialConfiguration +
  * activityTypeId, and the multipart wire of a multipart operation. Designer
  * cosmetics (packageId/activityColor/…) are omitted — the caseplan
- * schema-validates without them (see design §C). */
-function connectorMetadata(rc, op, slots, executionType) {
+ * schema-validates without them (see design §C).
+ *
+ * The configuration is the one Flow writes, from the shared
+ * {@link buildEssentialConfiguration}. Case used to build its own, thinner copy:
+ * no `operation` verb, `customFieldsRequestDetails`, `connectorVersion` or
+ * `unifiedTypesCompatible`, a curated-only `instanceParameters` even for a
+ * Generic activity, and the library version where the platform writes
+ * `packageVersion: "1.0.0"` (#1420).
+ */
+function connectorMetadata(rc, op, slots, seed, executionType) {
     // The part DECLARATIONS only: a file part's value rides on its `file` input.
     const multipartParameters = (slots.multipartParameters ?? []).map(({ name, dataType }) => ({ name, dataType }));
-    const instanceParameters = {
-        connectorKey: rc.connectorKey,
-        objectName: op.objectName ?? rc.nodeType.split('.').pop(),
-        httpMethod: rc.httpMethod,
-        activityType: op.activityType ?? 'Curated',
-        version: rc.version,
-        supportsStreaming: op.supportsStreaming ?? false,
-        subType: op.subType ?? 'standard',
-    };
-    const configuration = {
-        essentialConfiguration: {
-            instanceParameters,
-            objectName: instanceParameters.objectName,
-            httpMethod: transportHttpMethod(rc.httpMethod),
-            path: rc.endpoint,
-            packageVersion: rc.version,
-            // An external task's object states how it runs; the Designer saves it here
-            // and beside the configuration. A plain connector activity has none.
-            ...(executionType ? { executionType } : {}),
-        },
-    };
+    // The configuration replays the authored values (a schema action's parent
+    // fields, a CEQL filter's tree), keyed by the library's own names, as Flow's.
+    const essential = buildEssentialConfiguration(rc.entry, rc.version, replayInputsOf(slots), seed, executionType ?? null);
+    const configuration = `=jsonString:${JSON.stringify({ essentialConfiguration: essential })}`;
+    const instanceParameters = essential.instanceParameters;
+    const objectName = String(op.objectName ?? rc.nodeType.split('.').pop());
     return {
         activityPropertyConfiguration: {
             ...(multipartParameters.length ? { multipartParameters } : {}),
-            configuration: `=jsonString:${JSON.stringify(configuration)}`,
+            configuration,
             uiPathActivityTypeId: rc.activityTypeId ?? '',
             errorState: { issues: [] },
             ...(executionType ? { executionType } : {}),
         },
         activityMetadata: {
             activity: {
-                displayName: rc.entry.display?.label ?? instanceParameters.objectName,
+                displayName: rc.entry.display?.label ?? objectName,
                 description: rc.entry.display?.description ?? '',
                 category: rc.connectorName,
                 configuration: JSON.stringify(instanceParameters),
@@ -1653,7 +1648,7 @@ function connectorMetadata(rc, op, slots, executionType) {
         telemetryData: {
             connectorKey: rc.connectorKey,
             connectorName: rc.connectorName,
-            objectName: instanceParameters.objectName,
+            objectName,
             objectDisplayName: op.objectDisplayName ?? rc.entry.display?.operationLabel ?? '',
         },
     };

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/connector-configuration.d.ts

@@ -63,6 +63,33 @@
  *
  * Neither is cosmetic for a generic node: v1's own `check_generic_dynamic_node.py`
  * identifies the activity semantically, by `activityType == 'generic'` **and
- * `operation == 'list'`**, read from these very keys.
+ * `operation == 'list'`**, read from these very keys. *
+ * ## `savedJitInputFieldId` is not written, because the library cannot say when
+ *
+ * The CLI writes `savedJitInputFieldId: "in_<objectName>"` for a create /
+ * update / replace whose IS metadata declares a `body` PARAMETER (a
+ * just-in-time body). The offline library does not carry that parameter: its
+ * `operation.parameters` hold only `query` · `path` · `multipart`. Its body
+ * FIELDS do not stand in for it. Measured over the Designer- and CLI-saved
+ * create/update/replace nodes in the eval corpus: Slack `create-channel` (2
+ * body fields) carries the key, while `join-channel` (1 body field, 0/2) and
+ * `create-group-direct-message` (1 body field, 0/89) do not, and Data Service
+ * `create-entity-record` (no body fields) does (336/405). Writing it on a
+ * guess would be wrong on hundreds of nodes, so it stays out until the library
+ * records the body parameter.
+ */
+export declare function buildConfiguration(entry: any, version: string, inputValues?: Record<string, unknown>, seed?: string, executionType?: string | null): string;
+/**
+ * The `essentialConfiguration` object that {@link buildConfiguration} wraps in
+ * its `=jsonString:` envelope. For a caller that also needs a field of it (Case
+ * copies its `instanceParameters` into the activity metadata), so it does not
+ * parse the string back.
+ *
+ * @param entry - The connector library entry.
+ * @param version - The connector version.
+ * @param inputValues - The authored inputs to replay, keyed by the library's names.
+ * @param seed - Seed for the saved filter tree ids.
+ * @param executionType - An External Agent / Workflow object's run mode, or `null`.
+ * @returns The essential configuration, with only Studio Web's essential keys.
  */
-export declare function buildConfiguration(entry: any, version: string, inputValues?: Record<string, unknown>, seed?: string): string;
+export declare function buildEssentialConfiguration(entry: any, version: string, inputValues?: Record<string, unknown>, seed?: string, executionType?: string | null): Record<string, unknown>;

package/dist/core/connector-configuration.js

@@ -20,6 +20,14 @@ const ESSENTIAL_DEFAULTS = {
     executionType: null,
     operation: 'create',
     packageVersion: '1.0.0',
+    // The CLI's offline builder writes these two on every activity
+    // (`buildActivityEssentialConfiguration`, uipath-cli
+    // `integrationservice-sdk/src/dap/essential-config.ts`), and so does every
+    // Designer save in the eval corpus. `connectorVersion` is a request header
+    // the library does not carry; Studio Web fills it from its type cache on
+    // open, so offline it is `null`, as the CLI and the Case fixture write it.
+    connectorVersion: null,
+    unifiedTypesCompatible: true,
 };
 /**
  * Which of an operation's parameters carries a CEQL filter.
@@ -161,9 +169,40 @@ function envelope(flat) {
  *
  * Neither is cosmetic for a generic node: v1's own `check_generic_dynamic_node.py`
  * identifies the activity semantically, by `activityType == 'generic'` **and
- * `operation == 'list'`**, read from these very keys.
+ * `operation == 'list'`**, read from these very keys. *
+ * ## `savedJitInputFieldId` is not written, because the library cannot say when
+ *
+ * The CLI writes `savedJitInputFieldId: "in_<objectName>"` for a create /
+ * update / replace whose IS metadata declares a `body` PARAMETER (a
+ * just-in-time body). The offline library does not carry that parameter: its
+ * `operation.parameters` hold only `query` · `path` · `multipart`. Its body
+ * FIELDS do not stand in for it. Measured over the Designer- and CLI-saved
+ * create/update/replace nodes in the eval corpus: Slack `create-channel` (2
+ * body fields) carries the key, while `join-channel` (1 body field, 0/2) and
+ * `create-group-direct-message` (1 body field, 0/89) do not, and Data Service
+ * `create-entity-record` (no body fields) does (336/405). Writing it on a
+ * guess would be wrong on hundreds of nodes, so it stays out until the library
+ * records the body parameter.
+ */
+export function buildConfiguration(entry, version, inputValues, seed = 'node', executionType = null) {
+    return '=jsonString:' + JSON.stringify({
+        essentialConfiguration: buildEssentialConfiguration(entry, version, inputValues, seed, executionType),
+    });
+}
+/**
+ * The `essentialConfiguration` object that {@link buildConfiguration} wraps in
+ * its `=jsonString:` envelope. For a caller that also needs a field of it (Case
+ * copies its `instanceParameters` into the activity metadata), so it does not
+ * parse the string back.
+ *
+ * @param entry - The connector library entry.
+ * @param version - The connector version.
+ * @param inputValues - The authored inputs to replay, keyed by the library's names.
+ * @param seed - Seed for the saved filter tree ids.
+ * @param executionType - An External Agent / Workflow object's run mode, or `null`.
+ * @returns The essential configuration, with only Studio Web's essential keys.
  */
-export function buildConfiguration(entry, version, inputValues, seed = 'node') {
+export function buildEssentialConfiguration(entry, version, inputValues, seed = 'node', executionType = null) {
     const op = entry.operation ?? {};
     const conn = entry.connector ?? {};
     const at = op.activityType;
@@ -177,6 +216,9 @@ export function buildConfiguration(entry, version, inputValues, seed = 'node') {
         : ESSENTIAL_DEFAULTS.operation;
     const composed = {
         ...ESSENTIAL_DEFAULTS,
+        // An External Agent / Workflow object states how it runs; a connector
+        // activity has none (`null`, the default).
+        executionType,
         operation: verb,
         customFieldsRequestDetails: schemaReplayDetails(op, inputValues),
         savedFilterTrees: savedFilterTrees(op, inputValues, seed),
@@ -202,5 +244,5 @@ export function buildConfiguration(entry, version, inputValues, seed = 'node') {
             },
         ...(op.pathTemplate || op.path ? { path: op.pathTemplate || op.path } : {}),
     };
-    return '=jsonString:' + JSON.stringify(envelope(composed));
+    return envelope(composed).essentialConfiguration;
 }

package/dist/core/connector-inputs.d.ts

@@ -58,6 +58,16 @@ export declare const CONNECTOR_INPUT_MISSING = "CONNECTOR_INPUT_MISSING";
  */
 export declare function connectorInputErrors(rc: ResolvedConnector, inputs: Record<string, unknown>, resolutions?: LookupResolutions, lookups?: Readonly<Record<string, LookupSpec>>, wire?: Pick<ConnectorInputOpts, 'dialect' | 'render'>): string | undefined;
 export declare function buildConnectorInputs(rc: any, inputs: Record<string, unknown>, opts: ConnectorInputOpts): ConnectorSlots;
+/**
+ * The authored values a connector's `configuration` replays (a schema action's
+ * parent fields, a CEQL filter's tree), keyed by the library's own names: the
+ * body, path and query slots, merged. Flow and Case both write the
+ * configuration from this, so the two cannot drift.
+ *
+ * @param slots - The slots {@link buildConnectorInputs} returned.
+ * @returns The merged body, path and query values.
+ */
+export declare function replayInputsOf(slots: ConnectorSlots): Record<string, unknown>;
 /**
  * `inputMetadata.multipart.bodyFieldName` names the CONTAINER part — the one the
  * runtime composes from `bodyParameters`. Measured on the designer's own nodes in

package/dist/core/connector-inputs.js

@@ -253,6 +253,22 @@ function swapLookupTokens(value, resolutions, unresolved) {
         return value.map((item) => swapLookupTokens(item, resolutions, unresolved));
     return value;
 }
+/**
+ * The authored values a connector's `configuration` replays (a schema action's
+ * parent fields, a CEQL filter's tree), keyed by the library's own names: the
+ * body, path and query slots, merged. Flow and Case both write the
+ * configuration from this, so the two cannot drift.
+ *
+ * @param slots - The slots {@link buildConnectorInputs} returned.
+ * @returns The merged body, path and query values.
+ */
+export function replayInputsOf(slots) {
+    return {
+        ...(slots.bodyParameters ?? {}),
+        ...(slots.pathParameters ?? {}),
+        ...(slots.queryParameters ?? {}),
+    };
+}
 /**
  * `inputMetadata.multipart.bodyFieldName` names the CONTAINER part — the one the
  * runtime composes from `bodyParameters`. Measured on the designer's own nodes in

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;