@uipath/maestro-builder-sdk 6.47.3 → 6.48.0

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

@@ -1,7 +1,7 @@
 /**
- * The document factories, `documentClassify()` and `dynamicExtract()`. Moved
- * from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the
- * package entry re-exports them.
+ * The document factories, `documentClassify()`, `dynamicExtract()` and
+ * `ixpExtract()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
 /**
@@ -28,3 +28,60 @@ export function documentClassify(inputs) {
 export function dynamicExtract(inputs) {
     return builtinActionSpec({ kind: 'dynamicExtract', inputs });
 }
+/**
+ * Extract fields from a document with a published IxP project — the platform's
+ * **Extract** node (`uipath.ixp.*`, service contract `IXP.Extraction`).
+ *
+ * @remarks
+ * **The result's shape is three levels deep and PascalCase.** A field lands at
+ * `out('<step>', 'ExtractionResult.ResultsDocument.Fields')` — an array of
+ * `{ FieldId, FieldName, FieldType, IsMissing, Values[], Confidence }`, looked
+ * up by `FieldName`. `Fields[]` is under `ResultsDocument`, not directly under
+ * `ExtractionResult`, and there is no `result` wrapper: the platform's
+ * serializer strips it before the value reaches the variable.
+ *
+ * **A local run cannot extract anything** — extraction needs a real document on
+ * the IxP service. An offline run returns the baked
+ * fixture shape, and only a platform run reaches the model. So a green local
+ * rung proves the wiring and the definition, never that a document was read.
+ *
+ * **`fileRef` is emitted as a PLAIN `=js:` string, not the expression envelope
+ * the rest of the file uses** — the one place this family diverges from the
+ * format's general spelling, and the contract this node owes the platform. The
+ * product's own `ixp-node` validator tests `typeof fileRef !== 'string'` and
+ * refuses the object form (*"inputs.fileRef must be a `=js:$vars.…`
+ * expression"*), the node's registry manifest declares
+ * `{type:'string', minLength:1}`, and so do all 150 v1-authored instances in the
+ * deployed corpus that carry the field — at file versions 1.6, 1.8 and 1.9 alike,
+ * with zero envelopes among them. The RUNTIME
+ * accepts both, so only `uip maestro flow validate` sees a wrong one; the
+ * emitter's exemption lives in `migrate.ts` (`UNWRAPPED_INPUTS`).
+ * See the IxP node reference (`website/reference/ixp.md`) §3.
+ *
+ * @example
+ * **Extract an invoice total and read it out of the nested result**
+ * ```ts
+ * flow('InvoiceIntake')
+ *   .input({ invoiceFile: types.file })
+ *   .output({ total: types.string })
+ *   .step('extract', ixpExtract({
+ *     project: 'uipath.ixp.invoiceixp-cef0d447-ixp.ff973488-5d89-8035-86ac-f980b4be6deb-c4359cde-55f0-4f0e-9322-c6cdce74ab4c',
+ *     modelName: 'invoiceixp-cef0d447-ixp',
+ *     name: 'InvoiceIXP',
+ *     folderName: 'Shared',
+ *     fileRef: out('start', 'invoiceFile'),
+ *   }))
+ *   .step('readTotal', script({ code: `
+ *     const fields = $vars.extract.output.ExtractionResult.ResultsDocument.Fields || [];
+ *     return { total: fields.find(f => f.FieldName === 'invoiceTotal')?.Values?.[0] };
+ *   ` }))
+ *   .return({ total: out('readTotal', 'total') })
+ * ```
+ *
+ * @param inputs - The published IxP `project` and `modelName`, and the document
+ * to read (`fileRef`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function ixpExtract(inputs) {
+    return builtinActionSpec({ kind: 'ixpExtract', inputs });
+}

package/dist/nodes/document/flow/family.d.ts

@@ -1,3 +1,3 @@
-/** The document node family, as flow-node-registry.ts lists it: Document Classify and Dynamic Extract. */
+/** The document node family, as flow-node-registry.ts lists it: Document Classify, Dynamic Extract and an IxP project's extractor. */
 import type { FlowNodeFamily } from '../../../flow-node-type.js';
 export declare const documentFlowFamily: FlowNodeFamily;

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

@@ -1,7 +1,8 @@
+import { IXP_DIAGNOSTICS, ixpExtractNodeType } from './ixp.js';
 import { documentClassifyNodeType, DOCUMENT_DIAGNOSTICS, dynamicExtractNodeType } from './node-type.js';
 export const documentFlowFamily = {
     id: 'document',
     title: 'Document understanding',
-    types: [documentClassifyNodeType, dynamicExtractNodeType],
-    diagnostics: DOCUMENT_DIAGNOSTICS,
+    types: [documentClassifyNodeType, dynamicExtractNodeType, ixpExtractNodeType],
+    diagnostics: { ...DOCUMENT_DIAGNOSTICS, ...IXP_DIAGNOSTICS },
 };

package/dist/nodes/document/flow/ixp.d.ts

@@ -0,0 +1,34 @@
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import { type IxpExtractInputs } from './spec.js';
+export type IxpExtractSpec = {
+    kind: 'ixpExtract';
+    inputs: IxpExtractInputs;
+};
+export declare const IXP_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * 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.
+ */
+export declare function ixpExtractDef(spec: {
+    project: string;
+    modelName: string;
+    name: string;
+    folderName: string;
+    folderPath?: string;
+    versionTag?: string;
+    description?: string;
+}): any;
+export declare const ixpExtractNodeType: FlowVersionedNodeType<IxpExtractSpec>;

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

@@ -0,0 +1,389 @@
+/**
+ * An IxP project's extractor — `ixpExtract()`, a node type per published
+ * project: `uipath.ixp.<projectSlug>.<projectVersionId>-<folderKey>`. The type
+ * owns every name under `uipath.ixp.` whose tail is that pair of uuids
+ * (`typeNameMatches`), which keeps Dynamic Extract's exact
+ * `uipath.ixp.extract-document-builder` and the two older, unresolvable tail
+ * spellings out of it. Per-tenant: the definition is one bundled template plus
+ * the project's identity. Moved from serialize.ts / check.ts / decompile.ts in
+ * Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed
+ * source, codes and messages unchanged.
+ */
+import ixpDefinition from '../../../core/ixp-definition.json' with { type: 'json' };
+import { definitionHasErrorPort } from '../../../core/error-port.js';
+import { Expr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-clone.js';
+import { parseIxpProjectType } from './spec.js';
+const IXP_PREFIX = 'uipath.ixp.';
+export const IXP_DIAGNOSTICS = {
+    IXP_FORBIDDEN_INPUT: { severity: 'error', summary: 'an IxP step setting an input the current node does not declare' },
+    IXP_NO_FILE: { severity: 'error', summary: 'an IxP step with no fileRef' },
+    IXP_NO_FOLDER: { severity: 'error', summary: 'an IxP step with no folderName' },
+    IXP_NO_MODEL_NAME: { severity: 'error', summary: 'an IxP step with no modelName' },
+    IXP_NO_NAME: { severity: 'error', summary: 'an IxP step with no name' },
+    IXP_NO_PROJECT: { severity: 'error', summary: 'an IxP step with no project' },
+    IXP_PROJECT_NOT_NODE_TYPE: { severity: 'error', summary: 'an IxP project that is not a uipath.ixp.* node type' },
+    IXP_PROJECT_TAIL_UNPARSEABLE: { severity: 'error', summary: "an IxP project whose tail is not the version id and folder key" },
+};
+/**
+ * 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.
+ */
+export 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',
+            },
+        ] };
+}
+/**
+ * The five forbidden inputs on an IxP node. They belonged to a prior schema and
+ * v1's own authoring reference calls them "the most common training-data-recall
+ * mistake" — the current node declares none of them, so each is an input the
+ * definition does not have.
+ *
+ * They are not reachable through `ixpExtract()`'s typed surface, which is the
+ * point of having one; this check exists for the JS caller and for a
+ * hand-written spec object, where TypeScript is not in the way.
+ */
+const IXP_FORBIDDEN_INPUTS = ['digitizationMode', 'documentTaxonomy', 'attachmentId', 'fileName', 'mimeType'];
+/**
+ * `ixpExtract(...)`-specific checks.
+ *
+ * All four identity fields are load-bearing on the tenant and none of them can
+ * be derived, so a missing one is an error rather than a warning: the node type
+ * is per-project, and the definition's own `inputDefinition` marks `modelName`
+ * and `folderKey` required (`minLength: 1`) beside `fileRef` — which is why
+ * `flow validate`'s `ixp-node` validator rejects a node with an empty one.
+ */
+function checkIxpExtract(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    const project = String(inputs?.project ?? '').trim();
+    if (blank(project)) {
+        at('IXP_NO_PROJECT', `IxP step "${step}" has no \`project\`. That is the extractor's whole node type, and it carries the `
+            + `project version id and folder key the platform resolves the deployment by. Copy it from the registry `
+            + `— never construct it: three different spellings of its tail exist in deployed flows.`, `project: 'uipath.ixp.<slug>.<projectVersionId>-<folderKey>'  // uip maestro flow registry pull --force && uip maestro flow registry search -f "type:startsWith=uipath.ixp"`);
+    }
+    else if (!project.startsWith('uipath.ixp.')) {
+        at('IXP_PROJECT_NOT_NODE_TYPE', `IxP step "${step}"'s \`project\` is ${JSON.stringify(inputs.project)}, which is not a \`uipath.ixp.*\` node `
+            + `type. This field takes the type verbatim from \`registry search\`, not the project's name or id — the `
+            + `name goes in \`name\` and the slug in \`modelName\`.`);
+    }
+    else if (parseIxpProjectType(project) === undefined) {
+        at('IXP_PROJECT_TAIL_UNPARSEABLE', `IxP step "${step}"'s \`project\` ends in ${JSON.stringify(project.slice(project.lastIndexOf('.') + 1))}, which is `
+            + `not the \`<projectVersionId>-<folderKey>\` pair of uuids the current registry serves. Two older spellings `
+            + `exist in the corpus — a sanitized folder path, and the literal string "undefined" — and neither resolves `
+            + `today. Re-read the type from \`registry search\` after \`registry pull --force\`.`);
+    }
+    if (blank(inputs?.modelName)) {
+        at('IXP_NO_MODEL_NAME', `IxP step "${step}" has no \`modelName\`. The definition marks it required (\`minLength: 1\`) and the `
+            + `platform's \`ixp-node\` validator refuses an empty one — it is the project's own name as the tenant `
+            + `spells it, which the node type's slug has lower-cased and de-punctuated beyond recovery.`, `modelName: 'invoiceixp-cef0d447-ixp'  // registry get → inputDefaults.modelName`);
+    }
+    if (blank(inputs?.name)) {
+        at('IXP_NO_NAME', `IxP step "${step}" has no \`name\`. It is the deployment's display name — the \`ixpDeployment\` binding's `
+            + `\`name\`, which is how the deployed flow finds the project.`, `name: 'InvoiceIXP'  // registry get → inputDefaults.model.modelDisplayName`);
+    }
+    if (blank(inputs?.folderName)) {
+        at('IXP_NO_FOLDER', `IxP step "${step}" has no \`folderName\`. IxP deployments are folder-scoped, and this is the binding's `
+            + `\`folderPath\` default — the folder the runtime looks in.`, `folderName: 'Shared'  // registry get → inputDefaults.folderName`);
+    }
+    const fileRef = inputs?.fileRef;
+    if (fileRef === undefined || fileRef === null
+        || (typeof fileRef === 'string' && fileRef.trim() === '')) {
+        at('IXP_NO_FILE', `IxP step "${step}" has no \`fileRef\`. It is the node's only required INPUT (\`inputDefinition.required\`) `
+            + `and it takes a whole Flow Attachment object — normally a \`file\`-typed flow input.`, `fileRef: out('start', 'invoiceFile')   // .input({ invoiceFile: types.file })`);
+    }
+    for (const f of IXP_FORBIDDEN_INPUTS) {
+        if (inputs?.[f] !== undefined) {
+            at('IXP_FORBIDDEN_INPUT', `IxP step "${step}" sets \`${f}\`, which the current node does not declare — it belonged to a prior `
+                + `schema. ${f === 'documentTaxonomy' ? 'The taxonomy travels in the resolved `model` blob.'
+                    : f === 'digitizationMode' ? 'The serializer defaults it to `fileUpload` internally.'
+                        : 'It is derived from `fileRef` upstream.'}`);
+        }
+    }
+}
+/**
+ * The extractor's node: the definition's `inputDefaults` with the file the
+ * author named, and the fixed output pair.
+ */
+function serializeIxpExtract(s, ctx) {
+    const def = ixpExtractDef(s); // 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 }, ctx.bindings);
+    for (const b of entries)
+        ctx.bind(b);
+    return {
+        definition: { source: 'snapshot', nodeType: def.nodeType, version: def.version, manifest: 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.
+        model: 'omit',
+        // 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.
+        port: 'success',
+        // The instance IS the definition's defaults, with the file the author named.
+        // Every field the designer writes, in the platform's own order.
+        inputs: {
+            ...jsonClone(def.inputDefaults),
+            fileRef: ctx.render(s.fileRef),
+            ...(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 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.
+        outputs: {
+            output: { name: 'output', type: 'object', source: '=this', var: 'output' },
+            error: {
+                type: 'object',
+                description: 'Error information if the node fails',
+                source: '=Error',
+                var: 'error',
+            },
+        },
+        replaceOutputs: true,
+    };
+}
+function liftIxpExtract(node, ctx) {
+    const n = node;
+    const i = (n.inputs ?? {});
+    const plain = (k) => {
+        const v = ctx.sourceText(i[k]);
+        return v === undefined || v === '' ? undefined : v;
+    };
+    const fr = ctx.sourceText(i.fileRef) ?? '';
+    // The DEPLOYMENT's display name is nested in `inputs.model`, not at the top
+    // of `inputs` — the two are different values (the model block's
+    // `modelDisplayName` is 'InvoiceIXP'; `modelName` is the slug), so reading
+    // the wrong one recovers the slug as the name.
+    const model = (i.model ?? {});
+    const nested = (k) => typeof model[k] === 'string' && model[k] !== '' ? model[k] : undefined;
+    const lifted = {
+        project: n.type,
+        // `modelName`/`projectName` are one value in two fields; either recovers it.
+        modelName: plain('modelName') ?? plain('projectName') ?? nested('modelName') ?? '',
+        name: nested('modelDisplayName') ?? plain('modelName') ?? '',
+        folderName: plain('folderName') ?? nested('folderName') ?? '',
+        fileRef: fr.startsWith('=js:') ? new Expr(fr.slice(4)) : fr,
+        pageRange: plain('pageRange'),
+        versionTag: plain('versionTag'),
+        description: plain('description') ?? nested('description'),
+    };
+    return { kind: 'ixpExtract', inputs: lifted };
+}
+function printIxpExtract(spec, ctx) {
+    const l = spec.inputs;
+    const optional = (v) => (v === undefined ? undefined : ctx.string(v));
+    return {
+        factory: 'ixpExtract',
+        options: [
+            ['project', ctx.string(l.project)],
+            ['modelName', ctx.string(l.modelName)],
+            ['name', ctx.string(l.name)],
+            ['folderName', ctx.string(l.folderName)],
+            ['fileRef', ctx.value(l.fileRef)],
+            ['pageRange', optional(l.pageRange)],
+            ['versionTag', optional(l.versionTag)],
+            ['description', optional(l.description)],
+        ],
+    };
+}
+const ixpExtract10 = {
+    kind: 'ixpExtract', typeName: `${IXP_PREFIX}*`, version: IXP_DEF.version, factory: 'ixpExtract',
+    definition: 'per-tenant',
+    // The definition this SDK builds is the one serialize emits; asking it keeps
+    // the two in step (#1040). A project the builder cannot parse has no
+    // definition to ask, and the family's own rules report it (IXP_PROJECT_*).
+    errorPort: (spec) => {
+        try {
+            return definitionHasErrorPort(ixpExtractDef(spec.inputs));
+        }
+        catch {
+            return true;
+        }
+    },
+    serialize: (spec, ctx) => serializeIxpExtract(spec.inputs, ctx),
+    deserialize: (node, ctx) => liftIxpExtract(node, ctx),
+    print: (spec, ctx) => printIxpExtract(spec, ctx),
+    check: (spec, ctx) => checkIxpExtract(spec.inputs, ctx),
+    // check collected no expressions for an IxP step before the port; unchanged by it.
+    expressions: () => [],
+    output: () => ({ kind: 'opaque' }),
+};
+export const ixpExtractNodeType = {
+    kind: 'ixpExtract', typeName: `${IXP_PREFIX}*`, typeNamePrefix: IXP_PREFIX, factory: 'ixpExtract',
+    // An extractor is a tail of two uuids; Dynamic Extract's
+    // `uipath.ixp.extract-document-builder` and the older tails are not.
+    typeNameMatches: (typeName) => parseIxpProjectType(typeName) !== undefined,
+    defaultVersion: ixpExtract10.version,
+    versions: { [ixpExtract10.version]: ixpExtract10 },
+};

package/dist/nodes/document/flow/node-type.js

@@ -5,9 +5,7 @@
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
  * codes and messages unchanged.
  *
- * Not here: `ixpExtract()` (`uipath.ixp.<project type>`), whose type name comes
- * from the model rather than being one fixed name, which the contract does not
- * express yet.
+ * `ixpExtract()` (`uipath.ixp.<slug>.<versionId>-<folderKey>`) is in `ixp.ts`.
  */
 import { toExpr } from '../../../core/expr.js';
 import { jsonClone } from '../../../core/json-clone.js';

package/dist/nodes/document/flow/spec.d.ts

@@ -1,11 +1,13 @@
 /**
  * The document family's authoring types — Document Classify
- * (`uipath.document.classify`) and Dynamic Extract
- * (`uipath.ixp.extract-document-builder`) — and their kinds' entries in
+ * (`uipath.document.classify`), Dynamic Extract
+ * (`uipath.ixp.extract-document-builder`) and an IxP project's extractor
+ * (`uipath.ixp.<slug>.<versionId>-<folderKey>`) — and their kinds' entries in
  * `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
  */
 import type { Expr } from '../../../core/expr.js';
+/** What `documentClassify()` takes: the document, and how to split and classify it. */
 export interface DocumentClassifyInputs {
     /** The document to classify — a file reference (`input('file')`, `out('fetch', 'fileRef')`, …). */
     fileRef: string | Expr;
@@ -16,6 +18,7 @@ export interface DocumentClassifyInputs {
     /** Model configuration overrides; omit for the platform defaults (gemini_2_5_flash). */
     modelConfig?: Record<string, unknown>;
 }
+/** What `dynamicExtract()` takes: the document and the fields to extract from it. */
 export interface DynamicExtractInputs {
     /** The document to extract from — a file reference. */
     fileRef: string | Expr;
@@ -51,6 +54,99 @@ export interface DynamicExtractInputs {
     /** Model configuration overrides; omit for the platform defaults. */
     modelConfig?: Record<string, unknown>;
 }
+/**
+ * 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 declare function parseIxpProjectType(nodeType: string): {
+    slug: string;
+    versionId: string;
+    folderKey: string;
+} | undefined;
+/** What `ixpExtract()` takes: the IxP project's extractor, its identity on the tenant, and the document. */
+export interface IxpExtractInputs {
+    /**
+     * The extractor's node type, verbatim from
+     * `uip maestro flow registry search -f "type:startsWith=uipath.ixp"` — e.g.
+     * `'uipath.ixp.invoiceixp-cef0d447-ixp.ff973488-5d89-8035-86ac-f980b4be6deb-c4359cde-55f0-4f0e-9322-c6cdce74ab4c'`.
+     *
+     * **Run `uip maestro flow registry pull --force` first.** `registry search`
+     * and `registry get` answer from a local cache (`~/.uipath/nodes/`), so
+     * without a pull you are reading whenever you last synced.
+     *
+     * Two GUIDs are packed in that tail — the project **version** id and the
+     * **folder** key — and both are read back out of it here, which is why
+     * nothing else has to be passed twice.
+     */
+    project: string;
+    /**
+     * The project's own name, as the tenant spells it — the slug, e.g.
+     * `'idp-benchmark---invoices-c735405a-ixp'`. It is
+     * `inputDefaults.modelName` in `registry get`, and the node carries it as
+     * both `modelName` and `projectName` (one value, two fields — the designer
+     * shows it in two disabled boxes).
+     *
+     * It cannot be recovered from {@link IxpExtractInputs.project}: the node type's slug is
+     * lower-cased and de-punctuated (`---` collapses to `-`), which does not
+     * invert.
+     */
+    modelName: string;
+    /**
+     * The deployment's display name, e.g. `'InvoiceIXP'` —
+     * `inputDefaults.model.modelDisplayName`. It becomes the node's
+     * `model.modelDisplayName` and the `ixpDeployment` binding's `name`.
+     */
+    name: string;
+    /**
+     * The folder the project is published in, e.g. `'Shared'` or
+     * `'Shared/uipath-maestro-flow/BillingDispute'` —
+     * `inputDefaults.folderName`. It becomes the binding's `folderPath` default
+     * and the definition's own `description`.
+     */
+    folderName: string;
+    /**
+     * The document to extract from — a whole **Flow Attachment** object, the same
+     * shape and the same two ways of referencing it as
+     * {@link SummarizeInputs.attachment}:
+     *
+     * ```ts
+     * flow('InvoiceIntake')
+     *   .input({ invoiceFile: types.file })
+     *   .step('extract', ixpExtract({ …, fileRef: out('start', 'invoiceFile') }))
+     * ```
+     *
+     * It is the node's only authored input, and the definition marks it
+     * `required` (with `modelName` and `folderKey`, which this factory fills in).
+     */
+    fileRef: Expr;
+    /** Pages to process, e.g. `'1-5'`. Empty (the default) means the whole document. */
+    pageRange?: string;
+    /** Pin a published version tag. Empty (the default) means the latest. */
+    versionTag?: string;
+    /**
+     * The folder's key CHAIN, when the project lives in a nested folder —
+     * `inputDefaults.model.folderPath`, a dot-joined path of ancestor folder keys
+     * (`<root>.<parent>.<folder>`). Defaults to the folder key alone, which is
+     * what the platform writes for a project published straight into `Shared`.
+     */
+    folderPath?: string;
+    /**
+     * A free-text note on the node. Off by default, deliberately: the definition
+     * does not declare it (so setting it draws a "sets an input its type does not
+     * declare" warning unless the emitted definition is widened in the same
+     * write, which this does), and it is empty in 114 of the 117 deployed nodes
+     * that carry it at all.
+     */
+    description?: string;
+}
 declare module '../../../core/actions.js' {
     interface FlowActionSpecs {
         /** The spec {@link documentClassify} builds. */
@@ -61,5 +157,9 @@ declare module '../../../core/actions.js' {
         dynamicExtract: {
             inputs: DynamicExtractInputs;
         };
+        /** The spec {@link ixpExtract} builds. */
+        ixpExtract: {
+            inputs: IxpExtractInputs;
+        };
     }
 }