@uipath/maestro-builder-sdk 6.47.3 → 6.48.0

package/dist/nodes/document/flow/spec.js

@@ -1 +1,39 @@
-export {};
+// ─── Document extraction (uipath.ixp.*) ──────────────────────────────────────
+//
+// The platform's *Extract* node (that is its `display.canvasLabel`): it hands a
+// document to a published IxP — Intelligent eXtraction Platform — project and
+// reads the trained model's fields back. Every extractor on a tenant is its own
+// node type, `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>`, so the
+// four identity fields below come from the tenant and are named exactly as the
+// node names them.
+//
+// The type is RESOLVED, never constructed: three different spellings of that
+// tail exist in the deployed corpus (the sanitized folder path, the literal
+// string `undefined`, and today's version-id + folder-key pair), so copy the
+// one `registry search` prints.
+/**
+ * Split an extractor's node type into the two GUIDs its tail packs.
+ *
+ * `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>` — the version id is
+ * the `ixpDeployment` binding's `resourceKey` and the node's `model.id`; the
+ * folder key is `inputs.folderKey`. Returns `undefined` for a tail that is not
+ * exactly two uuids joined by `-`, which is how the two older spellings (a
+ * sanitized folder path, and the literal string `undefined`) are refused rather
+ * than mis-split.
+ *
+ * @internal Public for compatibility; not an authoring factory.
+ */
+export function parseIxpProjectType(nodeType) {
+    const rest = nodeType.startsWith('uipath.ixp.') ? nodeType.slice('uipath.ixp.'.length) : undefined;
+    if (!rest)
+        return undefined;
+    const dot = rest.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    const slug = rest.slice(0, dot);
+    const tail = rest.slice(dot + 1);
+    const m = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i.exec(tail);
+    if (!m)
+        return undefined;
+    return { slug, versionId: m[1], folderKey: m[2] };
+}

package/dist/serialize.d.ts

@@ -104,8 +104,8 @@ export declare function serializeWithSidecars(built: BuiltFlow, opts?: Serialize
 /**
  * The node type a typed action compiles to, when that type's definition is
  * bundled in `core-definitions.json`. `undefined` for a family whose definition
- * is built per tenant or per call (connector, ixpExtract) and for a spec this
- * SDK does not lower by kind.
+ * is built per tenant or per call (connector) and for a spec this SDK does not
+ * lower by kind.
  *
  * A registered kind (flow-node-registry.ts) is not listed: its type is the
  * registry's.
@@ -114,25 +114,6 @@ export declare function bundledActionNodeType(spec: {
     kind?: string;
     inputs?: any;
 } | undefined): string | undefined;
-/**
- * The definition serialize synthesizes for a kind that has no bundled one and
- * is not on the node-type registry: an `ixpExtract` step. Its node type carries
- * a tenant's key, so the SDK builds the definition per call, transcribed from
- * what `registry get` returns. `undefined` for every other kind (a bundled
- * family, a connector, a container, a registered kind — the published process
- * resources and the agent build theirs in nodes/process/flow/).
- *
- * The emit path builds its definition here, and `check` asks this same
- * definition whether the node has an error port (#1040), so the two cannot
- * disagree.
- *
- * Throws what the family's builder throws for an unusable spec (an
- * `ixpExtract` project that is not a node type).
- */
-export declare function perCallDefinition(spec: {
-    kind?: string;
-    inputs?: any;
-} | undefined): any | undefined;
 /**
  * The bundled definition of `nodeType` that `makeNode` resolves: the author's
  * exact `{ version }` when given, otherwise the pinned default (the first

package/dist/serialize.js

@@ -6,10 +6,9 @@
  * resolved from the connector library (entry + v1def sidecar), matching what
  * the platform emits, so the result passes `uip maestro flow validate`.
  */
-import ixpDefinition from './core/ixp-definition.json' with { type: 'json' };
 import { BUNDLED_DEFINITIONS, bundledVersions } from './flow-definitions.js';
 import { LOOP_DEFAULT_VERSION, bodyUsesBreak, loopDeclaredInputs, loopHasInnerHandles, loopVersion, loopVersionRefusal } from './loop-version.js';
-import { Expr, toExpr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameSegmentsOf, parallelFork } from './flow-sdk.js';
+import { Expr, toExpr, SCHEDULE_PRESETS, flatNameSegmentsOf, parallelFork } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
@@ -120,176 +119,6 @@ const SUBFLOW_OUTPUT = {
     var: 'output',
 };
 /** The inline (autonomous) agent's node type — fixed, not per-instance. */
-/**
- * The parts every `uipath.ixp.*` definition shares, bundled verbatim from
- * `uip maestro flow registry get` (2026-07-31, after `registry pull --force`).
- *
- * Unlike rpa's and api-workflow's, an extractor's definition is MOSTLY generic:
- * three projects' definitions (`invoiceixp`, `idp-benchmark---invoices`,
- * `invoices-billing`) are byte-identical in `category`, `tags`, `sortOrder`,
- * `version`, `supportsErrorHandling`, `handleConfiguration`, `form`, `debug`,
- * `inputDefinition` and the 18.7 KB `outputDefinition` — and differ in exactly
- * five per-project places (`nodeType`, `description`, `display.label`,
- * `model.bindings`, `inputDefaults`), all of which `ixpExtractDef` builds from
- * the author's call. So the family costs one bundled template, not 13.
- *
- * **The one thing to know before re-recording it:** `registry get` answers from
- * a LOCAL CACHE (`~/.uipath/nodes/index.json`). Without
- * `uip maestro flow registry pull --force` first you get whenever you last
- * synced — which is how a stale copy of this file would claim `required:
- * ["fileRef"]` (the pre-pull answer) instead of the three the platform's
- * `ixp-node` validator actually enforces.
- */
-const IXP_DEF = ixpDefinition;
-/**
- * Build the definition for one published IxP project.
- *
- * The per-project half is derived, not asked for twice: the node type's tail
- * packs the project VERSION id (the binding's `resourceKey`, and the model
- * blob's `id`) and the FOLDER key, so the author passes the type once and those
- * two come out of it.
- *
- * `inputDefaults` matters more here than in the other per-instance families,
- * because the platform's own instance IS its defaults: measured on today's 1.0
- * nightly artifact, `node.inputs` equals `inputDefaults` verbatim with exactly
- * two edits — `fileRef` authored, and `model.modelName` forced non-empty (the
- * registry returns `null` for published/OOB deployments, and both `flow
- * validate` and Studio Web's property panel refuse that). So the emitter writes
- * the defaults and the node reads them back, rather than the two drifting.
- */
-function ixpExtractDef(spec) {
-    const parts = parseIxpProjectType(spec.project);
-    if (!parts) {
-        throw new Error(`ixpExtract: "${spec.project}" is not a resolvable extractor node type. It must be `
-            + `uipath.ixp.<slug>.<projectVersionId>-<folderKey> — copy it from `
-            + `\`uip maestro flow registry pull --force && uip maestro flow registry search -f "type:startsWith=uipath.ixp"\`.`);
-    }
-    const { versionId, folderKey } = parts;
-    const model = {
-        id: versionId,
-        // Authoring rule #1 in v1's own IxP reference: non-empty or the `ixp-node`
-        // validator fails the flow and the designer's panel crashes destructuring it.
-        modelName: spec.modelName,
-        modelDisplayName: spec.name,
-        folderKey,
-        folderName: spec.folderName,
-        // The folder's ancestor-key chain for a nested folder; the folder key alone
-        // for one published straight into a root folder, which is what the platform
-        // writes there.
-        folderPath: spec.folderPath ?? folderKey,
-        description: '',
-    };
-    return {
-        nodeType: spec.project,
-        version: IXP_DEF.version,
-        category: IXP_DEF.category,
-        tags: jsonClone(IXP_DEF.tags),
-        // The platform's own definition describes an extractor by its FOLDER, and
-        // the designer prints exactly this in the node's subtitle.
-        description: `(${spec.folderName})`,
-        sortOrder: IXP_DEF.sortOrder,
-        supportsErrorHandling: IXP_DEF.supportsErrorHandling,
-        display: {
-            canvasLabel: IXP_DEF.canvasLabel,
-            label: spec.name,
-            description: `(${spec.folderName})`,
-            icon: IXP_DEF.icon,
-        },
-        handleConfiguration: jsonClone(IXP_DEF.handleConfiguration),
-        model: {
-            ...jsonClone(IXP_DEF.model),
-            bindings: {
-                ...jsonClone(IXP_DEF.bindingsFrame),
-                resourceKey: versionId,
-                name: spec.name,
-                values: [
-                    { name: 'name', propertyAttribute: 'name', default: spec.name },
-                    { name: 'folderPath', propertyAttribute: 'folderPath', default: spec.folderName },
-                ],
-            },
-        },
-        form: jsonClone(IXP_DEF.form),
-        // A `description` the author asked for is DECLARED in the same write. The
-        // registry's own copy carries `description` in `inputDefaults` and not in
-        // `inputDefinition.properties` — lesson 42's gap, live on this family — so
-        // emitting the input without this would flag our own output as setting an
-        // undeclared input, which
-        // is what v1's deployed artifacts do (measured: 1 warning on today's green
-        // nightly file). The default is to emit no `description` at all, which is
-        // why this is conditional and the definition otherwise stays byte-identical
-        // to the platform's.
-        inputDefinition: spec.description === undefined
-            ? jsonClone(IXP_DEF.inputDefinition)
-            : {
-                ...jsonClone(IXP_DEF.inputDefinition),
-                properties: { ...jsonClone(IXP_DEF.inputDefinition.properties), description: { type: 'string' } },
-            },
-        inputDefaults: {
-            model,
-            modelName: spec.modelName,
-            ...(spec.description === undefined ? {} : { description: spec.description }),
-            // `modelName` and `projectName` are ONE value in two fields: all three
-            // measured definitions agree, and the designer shows it in two disabled
-            // boxes (the IXP-model and Folder rows of the `ixp-model` form section).
-            projectName: spec.modelName,
-            versionTag: spec.versionTag ?? '',
-            folderKey,
-            folderName: spec.folderName,
-            fileRef: '',
-            pageRange: '',
-        },
-        outputDefinition: jsonClone(IXP_DEF.outputDefinition),
-        debug: jsonClone(IXP_DEF.debug),
-    };
-}
-/**
- * The `ixpDeployment` binding pair for one IxP project — the THIRD resource kind
- * this SDK emits, after `process` and `queue`.
- *
- * Same shape and same one-pair-per-resource rule as
- * {@link processResourceBindings}: keyed by `resource + resourceKey +
- * propertyAttribute`, so two steps extracting with the same project share one
- * pair rather than shadowing each other. `resourceKey` is the project VERSION
- * id, which is what the definition's `model.bindings.resourceKey` names.
- *
- * Measured on 48 of the 151 deployed IxP artifacts (and 3 of today's 4 green
- * ones): exactly these two entries, `name` defaulting to the deployment's
- * display name and `folderPath` to its folder — note `folderPath` here holds the
- * folder NAME, not the key chain that `inputs.model.folderPath` carries.
- */
-function ixpDeploymentBindings(spec, existing) {
-    const found = (attr) => [...existing.values()].find((b) => b.resource === 'ixpDeployment' && b.resourceKey === spec.versionId && b.propertyAttribute === attr)?.id;
-    const already = { name: found('name'), folderPath: found('folderPath') };
-    if (already.name && already.folderPath) {
-        return { ids: { name: already.name, folderPath: already.folderPath }, entries: [] };
-    }
-    const slug = spec.name.replace(/[^A-Za-z0-9]/g, '') || 'Ixp';
-    let base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}`;
-    for (let n = 2; existing.has(`${base}Name`) || existing.has(`${base}FolderPath`); n++) {
-        base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}${n}`;
-    }
-    const ids = { name: `${base}Name`, folderPath: `${base}FolderPath` };
-    return { ids, entries: [
-            {
-                id: ids.name,
-                name: 'name',
-                type: 'string',
-                resource: 'ixpDeployment',
-                resourceKey: spec.versionId,
-                default: spec.name,
-                propertyAttribute: 'name',
-            },
-            {
-                id: ids.folderPath,
-                name: 'folderPath',
-                type: 'string',
-                resource: 'ixpDeployment',
-                resourceKey: spec.versionId,
-                default: spec.folderName,
-                propertyAttribute: 'folderPath',
-            },
-        ] };
-}
 /**
  * Declare a LIST operation's output as the ARRAY it is, when the ledger has
  * MEASURED that it is one ([#203](https://github.com/UiPath/flow-builder-sdk/issues/203)).
@@ -843,8 +672,8 @@ function describeDeclared(bindings) {
 /**
  * The node type a typed action compiles to, when that type's definition is
  * bundled in `core-definitions.json`. `undefined` for a family whose definition
- * is built per tenant or per call (connector, ixpExtract) and for a spec this
- * SDK does not lower by kind.
+ * is built per tenant or per call (connector) and for a spec this SDK does not
+ * lower by kind.
  *
  * A registered kind (flow-node-registry.ts) is not listed: its type is the
  * registry's.
@@ -855,28 +684,6 @@ export function bundledActionNodeType(spec) {
         default: return undefined;
     }
 }
-/**
- * The definition serialize synthesizes for a kind that has no bundled one and
- * is not on the node-type registry: an `ixpExtract` step. Its node type carries
- * a tenant's key, so the SDK builds the definition per call, transcribed from
- * what `registry get` returns. `undefined` for every other kind (a bundled
- * family, a connector, a container, a registered kind — the published process
- * resources and the agent build theirs in nodes/process/flow/).
- *
- * The emit path builds its definition here, and `check` asks this same
- * definition whether the node has an error port (#1040), so the two cannot
- * disagree.
- *
- * Throws what the family's builder throws for an unusable spec (an
- * `ixpExtract` project that is not a node type).
- */
-export function perCallDefinition(spec) {
-    const s = spec?.inputs ?? {};
-    switch (spec?.kind) {
-        case 'ixpExtract': return ixpExtractDef(s);
-        default: return undefined;
-    }
-}
 /**
  * The bundled definition of `nodeType` that `makeNode` resolves: the author's
  * exact `{ version }` when given, otherwise the pinned default (the first
@@ -2421,11 +2228,6 @@ export function serialize(built, opts = {}) {
     function successPort(type) {
         if (type === NODE_TYPE.loop)
             return 'success';
-        // Every extractor's definition declares `success` (+ `error`, gated on
-        // `errorHandlingEnabled`) on the right — so the forward edge is `success`,
-        // as it is in all 151 deployed IxP instances.
-        if (type.startsWith('uipath.ixp.'))
-            return 'success';
         // connectors, the trigger, the merge join and the mock placeholder all expose
         // their forward edge on `output` (merge's definition declares exactly one
         // source handle, `output`; so does `core.logic.mock`, and all 74 archived
@@ -2623,9 +2425,10 @@ export function serialize(built, opts = {}) {
         // input (`*_NO_KEY`), and serialize alone emits what it always did.
         const prefix = entry.type.typeNamePrefix;
         const nodeType = prefix !== undefined ? def?.nodeType : impl.typeName;
-        if (prefix !== undefined && (typeof nodeType !== 'string' || !nodeType.startsWith(prefix))) {
+        if (prefix !== undefined && (typeof nodeType !== 'string' || !nodeType.startsWith(prefix)
+            || entry.type.typeNameMatches?.(nodeType) === false)) {
             throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} supplied a definition for `
-                + `${JSON.stringify(nodeType)}, which is not a name under "${prefix}".`);
+                + `${JSON.stringify(nodeType)}, which is not a name it owns under "${prefix}".`);
         }
         if (impl.definition === 'per-tenant') {
             // At a version the flow carries, the carried definition answers: the
@@ -2821,51 +2624,6 @@ export function serialize(built, opts = {}) {
                 addEdge(scope, t, id);
             return [{ node: id, port: successPort(rc.nodeType) }];
         }
-        if (spec.kind === 'ixpExtract') {
-            const s = spec.inputs;
-            const def = perCallDefinition(spec); // ixpExtractDef: throws on an unparseable project
-            const { versionId } = parseIxpProjectType(s.project); // ixpExtractDef threw if it could not parse
-            // The bindings first: two steps on the same project share ONE pair, and
-            // the definition's `model.bindings.resourceKey` names the key they hang off.
-            const { entries } = ixpDeploymentBindings({ name: s.name, folderName: s.folderName, versionId }, resourceBindings);
-            for (const b of entries)
-                resourceBindings.set(b.id, b);
-            const id = stepUid(scope, step.name);
-            const node = makeNode(def.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def });
-            // No node-level `model` — v1's authoring reference makes this rule #15 for
-            // this family ("Studio Web–authored .flow files never carry one"), and 151
-            // of 151 deployed instances agree. Same reason the rpa/pattern families
-            // delete theirs.
-            delete node.model;
-            // The instance IS the definition's defaults, with the file the author
-            // named. Every field the designer writes, in the platform's own order.
-            node.inputs = {
-                ...jsonClone(def.inputDefaults),
-                fileRef: renderValue(s.fileRef, scope.rename),
-                ...(s.pageRange === undefined ? {} : { pageRange: s.pageRange }),
-            };
-            // The instance's `outputs` is a FIXED four-field pair, not a copy of the
-            // definition's `outputDefinition` — which `makeNode` writes for every other
-            // family and which here would drag the 18.7 KB extraction schema onto the
-            // node. v1's authoring reference is explicit ("copying outputDefinition
-            // verbatim also validates, but drags in a schema blob the runtime does not
-            // need"), and today's green nightly artifact carries exactly this. Both
-            // halves are REQUIRED: `flow validate`'s `ixp-node` validator fails a node
-            // missing either one.
-            node.outputs = {
-                output: { name: 'output', type: 'object', source: '=this', var: 'output' },
-                error: {
-                    type: 'object',
-                    description: 'Error information if the node fails',
-                    source: '=Error',
-                    var: 'error',
-                },
-            };
-            scope.nodes.push(node);
-            for (const t of tails)
-                addEdge(scope, t, id);
-            return [{ node: id, port: successPort(def.nodeType) }];
-        }
         if (spec.kind === 'waitEvent') {
             if (!opts.library)
                 throw new Error(`waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.47.3",
+  "version": "6.48.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "fc36fa72238f803ed2de5a02dc8a42f6c5d3305d"
+  "gitref": "b5eb4fa503b9753a5f3aa2c851c3f00befb13bd1"
 }