@uipath/maestro-builder-sdk 6.18.10 → 6.19.0

package/dist/raw-node.js

@@ -0,0 +1,116 @@
+/**
+ * `rawNode` — place a node this SDK has no factory for, carrying its definition
+ * verbatim. Moved from core/node-classes.ts in Phase 3 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md so its diagnostics can ask the node-type
+ * registry what a registered type says about a raw node of it; the package entry
+ * re-exports it, so authors import it exactly as before.
+ */
+import { FlowAction, } from './core/node-classes.js';
+import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
+/**
+ * Place a node this SDK has no factory for, carrying its definition verbatim
+ * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
+ *
+ * @remarks
+ * This is the escape hatch the coverage plan requires: an unknown registry
+ * definition is expressible without bypassing serializer invariants. The
+ * serializer still owns the node's id, label, `typeVersion` and edge wiring; you
+ * supply which definition and which inputs, exactly as a hand-written
+ * {@link FlowAction} subclass would.
+ *
+ * It is also what `decompile` emits for a node type it cannot name, so a
+ * round trip preserves the node's TYPE and VERSION instead of degrading it to a
+ * placeholder:
+ *
+ * ```ts
+ * .step('exotic', rawNode({
+ *   nodeType: 'uipath.exotic.thing',
+ *   version: '2.1',
+ *   manifest: exoticManifest,      // exactly what `registry get` returned
+ *   inputs: { where: input('scope') },
+ * }))
+ * ```
+ *
+ * `manifest` must be a real definition — an exact copy of what the registry or
+ * Workbench serves for that `nodeType@version`. It is not permission to invent
+ * one: the platform resolves the node against its own catalog at run time, so a
+ * hand-written manifest validates locally and fails on the tenant.
+ *
+ * Prefer a typed factory when one exists — it carries the family's checks, its
+ * defaults, and its output contract, none of which a raw node can know.
+ *
+ * **Never for a connector.** A `uipath.connector.*` node type is refused by
+ * `check` and `compile`: a raw node carries the author's inputs verbatim, so the
+ * emitted node has no `inputs.detail` and no connection binding — `validate`
+ * only warns ("Connector is not configured") and the run can never reach
+ * Integration Service. Use {@link connector}, and `registry prepare` when
+ * compile reports an input the static library does not carry; use
+ * {@link onEvent} for a connector event trigger.
+ *
+ * **Prefer the typed factory** for a node type that has one: `check` warns
+ * (`RAW_NODE_TYPED_FAMILY`), because `validate` cannot see an input the
+ * registry definition does not declare. For a `core.datafabric.*` type, a key
+ * the product never reads (an invented `_sortOptions` in place of `_sort`) is
+ * an error at a version the SDK bundles (`RAW_NODE_UNKNOWN_INPUT`); the
+ * canvas's snapshots, such as the `_entityFields` a related-path filter
+ * needs, stay legal.
+ *
+ * @param spec - The definition to compile against, plus the node's inputs.
+ * @returns A node to pass to `.step(...)`.
+ */
+export function rawNode(spec) {
+    return new RawNode(spec);
+}
+/** The {@link rawNode} implementation — a snapshot-backed contribution. */
+class RawNode extends FlowAction {
+    spec;
+    constructor(spec) {
+        super();
+        this.spec = spec;
+    }
+    /**
+     * `check` surfaces the connector refusal as an error, a typed family as a
+     * warning, and an input a registered node type never reads as an error at a
+     * bundled version (a warning at any other); `compile` throws the errors
+     * (see {@link contribute}).
+     */
+    diagnostics() {
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        if (refusal)
+            return [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }];
+        const out = [];
+        const unknown = rawNodeInputProblem(this.spec.nodeType, this.spec.version, this.spec.inputs);
+        if (unknown)
+            out.push({ code: 'RAW_NODE_UNKNOWN_INPUT', ...unknown });
+        const typed = rawNodeTypedFamilyWarning(this.spec.nodeType);
+        if (typed)
+            out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
+        return out;
+    }
+    contribute(context) {
+        // compile does not run diagnostics(); refuse here too so the escape hatch
+        // cannot emit an unconfigured connector node. (An input a registered node
+        // type never reads is refused by the serializer, for every contribution.)
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        if (refusal)
+            throw new Error(refusal);
+        const version = context.requestedVersion ?? this.spec.version;
+        if (context.requestedVersion !== undefined && context.requestedVersion !== this.spec.version) {
+            // Versions are exact everywhere in this SDK: a contributor may not
+            // substitute its own for an explicit request (design §2.6).
+            throw new Error(`rawNode("${this.spec.nodeType}") carries version ${this.spec.version}, but the step requests `
+                + `${context.requestedVersion}. Pass the manifest for the requested version, or drop { version }.`);
+        }
+        return {
+            definition: {
+                source: 'snapshot',
+                nodeType: this.spec.nodeType,
+                version,
+                manifest: this.spec.manifest,
+            },
+            ...(this.spec.inputs !== undefined ? { inputs: this.spec.inputs } : {}),
+            ...(this.spec.outputs !== undefined ? { outputs: this.spec.outputs } : {}),
+        };
+    }
+}