@uipath/maestro-builder-sdk 6.49.3 → 6.50.1

package/dist/decompile.js

@@ -774,7 +774,8 @@ function emitRegisteredSpec(node, imp, inputNames, graph) {
     };
     const options = opts((call.options ?? []).map(([k, v]) => [k, v]));
     const args = [...(call.positional ?? []), ...(options ? [options] : [])];
-    return `${imp.use(call.factory)}(${args.join(', ')})`;
+    return `${imp.use(call.factory)}(${args.join(', ')})`
+        + (call.comment !== undefined ? ` /* ${commentText(call.comment)} */` : '');
 }
 /**
  * Emit the action-spec argument for a `.step(id, <spec>)` call — e.g.
@@ -789,11 +790,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         return lifted;
     switch (node.type) {
         default:
-            // A connector action node: `uipath.connector.<key>.<action>` (but NOT the
-            // event nodes `uipath.connector.event.*` / `.trigger.*`, which are triggers).
-            if (node.type.startsWith('uipath.connector.') && !node.type.startsWith('uipath.connector.event.') && !node.type.startsWith('uipath.connector.trigger.')) {
-                return emitConnector(node, imp, inputNames, o);
-            }
             // A mid-flow connector EVENT wait (`uipath.connector.event.<key>.<event>`
             // placed as a step rather than as the start node).
             if (node.type.startsWith('uipath.connector.event.')) {
@@ -809,30 +805,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
             return unsupportedSpec(node, imp, o);
     }
 }
-/**
- * Split a connector `nodeType` (`uipath.connector.<key>.<action>`) into key +
- * action. Mirrors `core/connectors.ts`'s `splitConnectorNodeType`.
- */
-function splitConnector(nodeType) {
-    const rest = nodeType.replace(/^uipath\.connector\./, '');
-    const dot = rest.lastIndexOf('.');
-    if (dot <= 0)
-        return undefined;
-    return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
-}
-/** Pull `objectName` out of a connector's `=jsonString:` configuration blob, if present. */
-function connectorObjectName(configuration) {
-    if (typeof configuration !== 'string' || !configuration.startsWith('=jsonString:'))
-        return undefined;
-    try {
-        const cfg = JSON.parse(configuration.slice('=jsonString:'.length));
-        const name = cfg?.instanceParameters?.objectName ?? cfg?.objectName;
-        return typeof name === 'string' ? name : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Invert a connector action node into a `connector(key, action, inputs, opts)`
  * call. serialize routes author inputs into `detail.bodyParameters` /
@@ -948,41 +920,6 @@ function emitEventSubscription(node, imp, inputNames) {
         ['folder', folder !== undefined ? tsLiteral(folder) : undefined],
     ]) + unboundMarker(node, { connection: conn, folder }, connector, event);
 }
-function emitConnector(node, imp, inputNames, o) {
-    const split = splitConnector(node.type);
-    const detail = (node.inputs?.detail ?? {});
-    if (!split)
-        return unsupportedSpec(node, imp, o);
-    const slots = ['bodyParameters', 'queryParameters', 'pathParameters'];
-    const flat = [];
-    for (const s of slots) {
-        const m = detail[s];
-        if (m && typeof m === 'object' && !Array.isArray(m)) {
-            for (const [k, v] of Object.entries(m))
-                flat.push([k, emitVal(v, imp, inputNames)]);
-        }
-    }
-    const multipart = detail.multipartParameters;
-    if (Array.isArray(multipart)) {
-        for (const part of multipart) {
-            if (typeof part?.name === 'string' && Object.prototype.hasOwnProperty.call(part, 'value')) {
-                flat.push([part.name, emitVal(part.value, imp, inputNames)]);
-            }
-        }
-    }
-    const connection = typeof detail.connectionId === 'string' ? detail.connectionId : undefined;
-    const folder = typeof detail.connectionFolderKey === 'string' ? detail.connectionFolderKey : undefined;
-    const object = connectorObjectName(detail.configuration);
-    const optsSrc = opts([
-        ['connection', connection !== undefined ? tsLiteral(connection) : undefined],
-        ['folder', folder !== undefined ? tsLiteral(folder) : undefined],
-        ['object', object !== undefined ? tsLiteral(object) : undefined],
-    ]);
-    const inputsSrc = objLit(flat) || '{}';
-    const args = [tsLiteral(split.key), tsLiteral(split.action), inputsSrc, ...(optsSrc ? [optsSrc] : [])];
-    return `${imp.use('connector')}(${args.join(', ')})`
-        + unboundMarker(node, { connection, folder }, split.key, split.action);
-}
 /** Best-effort placeholder for a node type the reverse-map does not yet cover. */
 function unsupportedSpec(node, imp, o) {
     // The file's own definition for this node — the manifest the platform served.

package/dist/flow-node-registry.js

@@ -10,6 +10,7 @@ import { NodeTypeRegistry } from './core/nodes/registry.js';
 import { hasBundledDefinition } from './flow-definitions.js';
 import { agentFlowFamily } from './nodes/agent/flow/family.js';
 import { aiPatternsFlowFamily } from './nodes/ai-patterns/flow/family.js';
+import { connectorFlowFamily } from './nodes/connector/flow/family.js';
 import { conversationFlowFamily } from './nodes/conversation/flow/family.js';
 import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
 import { delayFlowFamily } from './nodes/delay/flow/family.js';
@@ -22,5 +23,5 @@ import { queueFlowFamily } from './nodes/queue/flow/family.js';
 import { scriptFlowFamily } from './nodes/script/flow/family.js';
 import { transformFlowFamily } from './nodes/transform/flow/family.js';
 /** The families, in no significant order. Adding one is the whole of registering it. */
-export const FLOW_NODE_FAMILIES = [agentFlowFamily, aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [agentFlowFamily, aiPatternsFlowFamily, connectorFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-node-type.d.ts

@@ -87,6 +87,19 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
         /** Display fields set over the definition's, after `shape: 'circle'` (a tool's `description`). */
         readonly display?: Readonly<Record<string, unknown>>;
     }>;
+    /**
+     * In a draft compile ({@link FlowSerializeContext.drafting}), the node the type
+     * cannot build — a generic connector operation saved before its object was
+     * picked has no definition — written as this stand-in: the given type,
+     * `typeVersion` and inputs (written as given), the step's label, no definition,
+     * `ui` or `model`. Merge restores the original when it is untouched. Everything
+     * else in the contribution is ignored but `port`.
+     */
+    standIn?: {
+        readonly type: string;
+        readonly typeVersion: string;
+        readonly inputs: Readonly<Record<string, unknown>>;
+    };
 }
 /** What `serialize` may ask of the serializer, for one placement. */
 export interface FlowSerializeContext {
@@ -213,6 +226,21 @@ export interface FlowSerializeContext {
     emitted(typeName: string, version: string): unknown;
     /** The connector library serialize was given, for a type that resolves a connector operation. */
     readonly library: SerializeOpts['library'];
+    /**
+     * Render a value and every `Expr` nested in its objects and arrays, as a
+     * connector's inputs are. A `lookup()` token is refused: it belongs only where a
+     * connector input resolves it (the whole value of a field, or an array element).
+     * An object result is a JSON copy that placement writes as is, so a `lit()`'s
+     * contents are not rendered a second time.
+     */
+    renderDeep(value: unknown): unknown;
+    /**
+     * Whether this is a draft compile (merge's): a refusal the author can still fix
+     * is reported through {@link draft} and the step emitted as far as it can be.
+     */
+    readonly drafting: boolean;
+    /** Report a draft finding on this node: what a non-draft compile would have refused. Only when {@link drafting}. */
+    draft(code: string, message: string): void;
 }
 /** What `deserialize` may ask of the decompiler, for one serialized node. */
 export interface FlowDeserializeContext {
@@ -349,6 +377,22 @@ export interface FlowCheckContext {
      * An explicit id equal to one another node gets is reported once the whole
      * file is checked (`INLINE_AGENT_RESOURCE_NODE_ID`).
      */
+    /**
+     * Run the rules every Integration Service operation shares — its lookups, its
+     * schema readiness, its contract against the library facts check was given
+     * (`options`), and BINDING_MISSING — on this step. Their codes are the
+     * pipeline's, shared with an event subscription's, so they belong to no
+     * family catalog; each is reported at its own severity.
+     */
+    connector(spec: {
+        key: string;
+        action: string;
+        version?: string;
+        object?: string;
+        connection?: unknown;
+        folder?: unknown;
+        inputs?: unknown;
+    }): void;
     readonly resources: {
         /** An id compile derives for one of this step's resources, and what it is, for that report. */
         derivedNodeId(id: string, what: string): void;
@@ -461,6 +505,21 @@ export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution,
      * the definition, an exit of the type, nor derived.
      */
     derivesPort?(spec: Spec, port: string): boolean;
+    /**
+     * The measured runtime shape of this step's LIST output, when it has one: a
+     * bare array (`envelope: null`) or an object holding it under `envelope`. A
+     * loop over the output checks its read against it (LIST_OUTPUT_WRAPPER).
+     * `options` are check's (a connector's measured list envelopes among them).
+     */
+    listShape?(spec: Spec, options: CheckOpts): {
+        envelope: string | null;
+    } | undefined;
+    /**
+     * The definition serialize will be supplied for a per-tenant type, when check's
+     * `options` can name it (a connector's, from the library). Check passes it to
+     * `errorPort`, so the two rungs give one answer; undefined when it cannot.
+     */
+    checkDefinition?(spec: Spec, options: CheckOpts): unknown;
 }
 /** A Flow node type with several versions. */
 export type FlowVersionedNodeType<Spec> = VersionedNodeType<Spec, FlowNodeContribution, FlowContexts, FlowNodeType<Spec>>;

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

@@ -0,0 +1,3 @@
+/** The connector node family, as flow-node-registry.ts lists it: an Integration Service connector operation. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const connectorFlowFamily: FlowNodeFamily;

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

@@ -0,0 +1,8 @@
+import { connectorNodeType } from './node-type.js';
+export const connectorFlowFamily = {
+    id: 'connector',
+    title: 'Integration Service connector',
+    types: [connectorNodeType],
+    // Its rules' codes are the pipeline's, shared with an event subscription (ctx.connector).
+    diagnostics: {},
+};

package/dist/nodes/connector/flow/node-type.d.ts

@@ -0,0 +1,25 @@
+/**
+ * An Integration Service connector operation — `connector(key, action, inputs,
+ * opts)`, a node type per operation: `uipath.connector.<connectorKey>.<action>`.
+ * The type owns every name under `uipath.connector.` that is an operation
+ * (`typeNameMatches`): not an event subscription's `uipath.connector.event.*` or a
+ * trigger's `uipath.connector.trigger.*`, which belong to `waitForEvent()` and
+ * `onEvent()`. Per-tenant: the definition is the library entry's, and so is its
+ * version (`versionedByDefinition`; most operations are at 1.0.0, some at 4.0.0).
+ *
+ * The spec and `connector()` stay in core/actions.ts: Case imports the spec, and
+ * Case may not import a node family. The rules the connector shares with an event
+ * subscription — lookups, schema readiness, the library contract, the binding
+ * labels — stay in core and run through `ctx.connector`, with their codes.
+ *
+ * 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 except for the three deliberate changes its 4o
+ * entry lists.
+ */
+import type { ActionSpec } from '../../../core/actions.js';
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+export type ConnectorSpec = Extract<ActionSpec, {
+    kind: 'connector';
+}>;
+export declare const connectorNodeType: FlowVersionedNodeType<ConnectorSpec>;

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

@@ -0,0 +1,294 @@
+import { BindingRefusal, bindingMissingMessage, missingBindingLabels } from '../../../core/binding-messages.js';
+import { prepareCommand } from '../../../core/cli-spelling.js';
+import { buildConfiguration } from '../../../core/connector-configuration.js';
+import { CONNECTOR_INPUT_MISSING, FLOW_EXPR_DIALECT, buildConnectorInputs, transportHttpMethod } from '../../../core/connector-inputs.js';
+import { ConnectorResolveError } from '../../../core/connector-resolve-error.js';
+import { definitionHasErrorPort } from '../../../core/error-port.js';
+import { Expr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-clone.js';
+import { subNodeId } from '../../../core/node-id-placeholder.js';
+import { synthesizedDefinitionRefusal } from '../../../core/synthesized-definition.js';
+import { tsLiteral, tsObject } from '../../../core/ts-literal.js';
+const CONNECTOR_PREFIX = 'uipath.connector.';
+/** `<key>.<action>` after the prefix, split on the last dot; undefined for an event, a trigger, or a name with no action. */
+function splitOperation(typeName) {
+    if (!typeName.startsWith(CONNECTOR_PREFIX))
+        return undefined;
+    const rest = typeName.slice(CONNECTOR_PREFIX.length);
+    if (rest.startsWith('event.') || rest.startsWith('trigger.'))
+        return undefined;
+    const dot = rest.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
+}
+/**
+ * The node's `output` slot for a LIST operation, declared as the ARRAY it is when
+ * the ledger has MEASURED that it is one ([#203](https://github.com/UiPath/flow-builder-sdk/issues/203)).
+ *
+ * Every connector definition declares `outputs.output.type: 'object'` — list
+ * operations included, and **0 of 544 deployed connector nodes declare `array`
+ * anywhere** (card CLEANUP's corpus scan). For most of the library that is the
+ * honest thing to emit, because the SDK does not know better. For an operation in
+ * the list-envelope ledger it does:
+ *
+ *   · `envelope: null` (a measured BARE array) ⇒ **`type: 'array'`**;
+ *   · a measured WRAPPER ⇒ `object`, unchanged — the value IS an object then;
+ *   · UNDECLARED ⇒ untouched, which is #202's status quo.
+ *
+ * Why this matters beyond tidiness: `typeAgentInputSchemas` builds an agent's
+ * pydantic input model from these declarations, and card ga7's scored run r2 died
+ * at `AGENT_STARTUP.INPUT_VALIDATION_ERROR` because a Data Service list node said
+ * `object` and the runtime sent 8 rows. #202 made that property TYPELESS, which
+ * unblocked the agent without asserting anything; this says the true thing.
+ *
+ * ## And deliberately NO item schema
+ *
+ * #203 suggested emitting the item fields alongside. They are not emitted, and the
+ * reason is a measurement rather than caution: a list operation's declared fields
+ * are **neither a superset nor a subset** of the real response (card LT, three live
+ * responses — ServiceNow `incident` declares 0 of the 103 fields it returns; Entra
+ * declares 20, returns 15, misses 2; Jira declares 253, returns 116, misses 42).
+ * Asserting them into an agent's pydantic model would reject real rows — the exact
+ * fault class above, moved rather than fixed. The library lift stays a READ-checking
+ * aid, where it fails open by design (lesson 26). The emitted bytes claim only what
+ * is certain: this is an array.
+ */
+function listOutputs(rc, nodeId) {
+    if (!rc.listEnvelope || rc.listEnvelope.envelope !== null)
+        return undefined;
+    const out = rc.v1def?.outputDefinition?.output;
+    if (!out || typeof out !== 'object' || out.type !== 'object')
+        return undefined;
+    return { output: { ...subNodeId(jsonClone(out), nodeId), type: 'array' } };
+}
+function serializeConnector(spec, ctx) {
+    const step = ctx.step;
+    if (!ctx.library)
+        throw new Error(`connector "${step}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+    let rc;
+    try {
+        rc = ctx.library.resolve(spec.key, spec.action, spec.version, spec.object);
+    }
+    catch (error) {
+        if (!ctx.drafting || !(error instanceof ConnectorResolveError) || error.code !== 'CONNECTOR_OBJECT_REQUIRED')
+            throw error;
+        // A generic operation saved before its object was picked has no definition
+        // to emit against. Draft tolerance emits a stable stand-in under the node's
+        // id; merge restores the original when it is untouched and refuses it
+        // otherwise. It leaves on the port every connector action leaves on, so the
+        // no-edit round trip rewires nothing. Its inputs carry what the author wrote,
+        // so an edit to the node (an input, a connection) shows up as a change and
+        // merge refuses it instead of restoring the original.
+        ctx.draft(error.code, error.message);
+        return {
+            inputs: {},
+            port: 'output',
+            standIn: {
+                type: `${CONNECTOR_PREFIX}${spec.key}.${spec.action}`,
+                typeVersion: spec.version ?? '1.0.0',
+                inputs: {
+                    draft: true,
+                    spec: ctx.renderDeep(spec.inputs ?? {}),
+                    ...(spec.connection !== undefined ? { connection: spec.connection } : {}),
+                    ...(spec.folder !== undefined ? { folder: spec.folder } : {}),
+                },
+            },
+        };
+    }
+    // An entry `prepare` synthesized from Integration Service compiles in BPMN only.
+    const noDefinition = synthesizedDefinitionRefusal(rc);
+    if (noDefinition)
+        throw noDefinition;
+    const where = `connector "${step}"`;
+    const target = { key: spec.key, action: spec.action };
+    // A connector-bound node needs both labels (#890); check says so first
+    // (BINDING_MISSING). A draft that names no connection gets no binding rows
+    // either: there is nothing to bind, and rows with an empty resourceKey would
+    // leak into the merged file through merge's bindings union.
+    let unbound = false;
+    const missing = missingBindingLabels(spec);
+    if (missing.length > 0) {
+        const refusal = new BindingRefusal('BINDING_MISSING', bindingMissingMessage(where, missing, target));
+        if (!ctx.drafting)
+            throw refusal;
+        ctx.draft(refusal.code, refusal.message);
+        unbound = true;
+    }
+    const conn = ctx.resolveBinding(spec.connection, 'connection', where, target);
+    const folder = ctx.resolveBinding(spec.folder, 'folder', where, target);
+    // The platform reaches the connection through the flow's `bindings[]`, never
+    // through `inputs.detail` — without this pair the run faults with `[102010]`
+    // (board G-19).
+    if (!unbound) {
+        ctx.bindConnection({
+            model: rc.v1def?.model,
+            connectorKey: rc.connectorKey, connectionId: conn,
+            ...(folder !== undefined ? { folderKey: folder } : {}),
+        });
+    }
+    const library = ctx.library;
+    const connectorInputs = buildConnectorInputs(rc, spec.inputs, {
+        ...(ctx.drafting
+            ? { onMissingRequired: (m) => ctx.draft(CONNECTOR_INPUT_MISSING, `connector ${rc.nodeType}: ${m}`) }
+            : {}),
+        dialect: FLOW_EXPR_DIALECT,
+        render: (value) => ctx.renderDeep(value),
+        resolutions: library.lookupResolutions ?? {},
+        // Only for the missing-required hint; a test double that is not a full
+        // Library simply gets the plain message.
+        lookups: typeof library.lookupSpecs === 'function'
+            ? library.lookupSpecs(spec.key, spec.action, spec.version, spec.object)
+            : {},
+    });
+    const replayInputs = {
+        ...(connectorInputs.bodyParameters ?? {}),
+        ...(connectorInputs.pathParameters ?? {}),
+        ...(connectorInputs.queryParameters ?? {}),
+    };
+    const detail = {
+        connector: rc.connectorKey,
+        method: transportHttpMethod(rc.httpMethod),
+        endpoint: rc.endpoint,
+        // The op's object identity, as a SIBLING of the copy inside `configuration`
+        // — the designer emits both, and every connector node in a product-exported
+        // flow carries it. Conditional because the library defaults a missing
+        // `operation.objectName` to '' — an op that names no object gets no key.
+        ...(rc.objectName ? { objectName: rc.objectName } : {}),
+        inputMetadata: {},
+        errorState: { hasError: false },
+        telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
+        configuration: buildConfiguration(rc.entry, rc.version, replayInputs, ctx.nodeId),
+        ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
+        ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
+        ...(folder ? { connectionFolderKey: folder } : {}),
+    };
+    // Each input in the slot its LOCATION names — body → detail.bodyParameters,
+    // query → queryParameters, path → pathParameters, multipart →
+    // multipartParameters — checked against the operation's field list.
+    // `bodyParameters` is emitted unconditionally (3 of 1,283 deployed connector
+    // nodes carry an empty one); the others only when the op has inputs there.
+    Object.assign(detail, connectorInputs);
+    // The node is the operation the author named (`rc.nodeType`); a definition
+    // naming another — a library entry that borrowed one, as a synthetic test
+    // library does — is written under that name, so the node and its
+    // definitions[] entry agree.
+    const v1def = rc.v1def;
+    const def = v1def.nodeType === rc.nodeType ? v1def : { ...v1def, nodeType: rc.nodeType };
+    const outputs = listOutputs(rc, ctx.nodeId);
+    return {
+        definition: { source: 'snapshot', nodeType: def.nodeType, version: def.version, manifest: def },
+        inputs: { detail },
+        // Every connector operation leaves on `output`, named: a definition with no
+        // handles has no default to fall back on.
+        port: 'output',
+        ...(outputs !== undefined ? { outputs } : {}),
+    };
+}
+/** A connector input's value as decompile reads it: an expression back to an `Expr`, wire text as text, any other JSON as is. */
+function liftValue(v, ctx) {
+    const raw = Array.isArray(v) ? undefined : ctx.sourceText(v);
+    if (raw === undefined)
+        return v;
+    return raw.startsWith('=js:') ? new Expr(raw.slice(4)) : raw;
+}
+/** Pull `objectName` out of a connector's `=jsonString:` configuration blob, if present. */
+function configurationObjectName(configuration) {
+    if (typeof configuration !== 'string' || !configuration.startsWith('=jsonString:'))
+        return undefined;
+    try {
+        const cfg = JSON.parse(configuration.slice('=jsonString:'.length));
+        const name = cfg?.instanceParameters?.objectName ?? cfg?.objectName;
+        return typeof name === 'string' ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function liftConnector(node, ctx) {
+    const n = node;
+    const split = splitOperation(n.type);
+    if (!split)
+        return undefined;
+    const detail = (n.inputs?.detail ?? {});
+    const inputs = [];
+    for (const slot of ['bodyParameters', 'queryParameters', 'pathParameters']) {
+        const m = detail[slot];
+        if (m && typeof m === 'object' && !Array.isArray(m)) {
+            for (const [k, v] of Object.entries(m))
+                inputs.push([k, liftValue(v, ctx)]);
+        }
+    }
+    const multipart = detail.multipartParameters;
+    if (Array.isArray(multipart)) {
+        for (const part of multipart) {
+            if (typeof part?.name === 'string' && Object.prototype.hasOwnProperty.call(part, 'value')) {
+                inputs.push([part.name, liftValue(part.value, ctx)]);
+            }
+        }
+    }
+    const connection = typeof detail.connectionId === 'string' ? detail.connectionId : undefined;
+    const folder = typeof detail.connectionFolderKey === 'string' ? detail.connectionFolderKey : undefined;
+    // A connection the file never picked (`connectionId: null`): the source cannot
+    // invent labels for it, and compile refuses a node without both
+    // (BINDING_MISSING, flow-builder-sdk#890), so the source says so at the node
+    // and the run warns once.
+    const missing = missingBindingLabels({ connection, folder });
+    if (missing.length > 0) {
+        ctx.warn(`node ${tsLiteral(n.id)} (${n.type}) has no ${missing.join(' or ')} in the .flow (an unbound draft). `
+            + `The source leaves ${missing.length > 1 ? 'them' : 'it'} out, and compile refuses the node (BINDING_MISSING) `
+            + `until it names both labels: run \`${prepareCommand(split.key, split.action)}\`, then pass `
+            + `\`connection\` and \`folder\`.`);
+    }
+    return {
+        kind: 'connector', ...split, inputs, connection, folder,
+        object: configurationObjectName(detail.configuration),
+        missing,
+    };
+}
+function printConnector(l, ctx) {
+    // A present input whose value is `undefined` (the inputs check accepts one, and
+    // serialize keeps it in memory) prints as `undefined`, as it did before the port.
+    const value = (v) => (v === undefined ? 'undefined' : v instanceof Expr ? ctx.value(v) : ctx.json(v));
+    const optional = (v) => (v === undefined ? undefined : ctx.string(v));
+    return {
+        factory: 'connector',
+        positional: [ctx.string(l.key), ctx.string(l.action), tsObject(l.inputs.map(([k, v]) => [k, value(v)])) || '{}'],
+        options: [
+            ['connection', optional(l.connection)],
+            ['folder', optional(l.folder)],
+            ['object', optional(l.object)],
+        ],
+        ...(l.missing.length > 0
+            ? { comment: `TODO: bind ${l.missing.join(' and ')}; compile refuses this node until it has both labels (BINDING_MISSING)` }
+            : {}),
+    };
+}
+const connector10 = {
+    kind: 'connector', typeName: `${CONNECTOR_PREFIX}*`, version: '1.0.0', factory: 'connector',
+    definition: 'per-tenant',
+    // The library's definition answers, in serialize and, given a library, in check
+    // (checkDefinition). Without one check assumes the port every operation the
+    // library serves declares.
+    errorPort: (_spec, definition) => definition === undefined || definitionHasErrorPort(definition),
+    checkDefinition: (spec, options) => {
+        const def = options.connectorDefinition?.(spec.key, spec.action, spec.version, spec.object);
+        // Named as serialize places it: under the operation the author named.
+        return def !== null && typeof def === 'object' ? { ...def, nodeType: `${CONNECTOR_PREFIX}${spec.key}.${spec.action}` } : undefined;
+    },
+    serialize: (spec, ctx) => serializeConnector(spec, ctx),
+    deserialize: (node, ctx) => liftConnector(node, ctx),
+    print: (spec, ctx) => printConnector(spec, ctx),
+    check: (spec, ctx) => ctx.connector(spec),
+    // Every Expr in the inputs, nested ones included, resolves against the flow's names.
+    expressions: (spec) => [{ value: spec.inputs }],
+    output: () => ({ kind: 'opaque' }),
+    listShape: (spec, options) => options.listEnvelope?.(spec.key, spec.action, spec.version, spec.object),
+};
+export const connectorNodeType = {
+    kind: 'connector', typeName: `${CONNECTOR_PREFIX}*`, typeNamePrefix: CONNECTOR_PREFIX, factory: 'connector',
+    typeNameMatches: (typeName) => splitOperation(typeName) !== undefined,
+    versionedByDefinition: true,
+    defaultVersion: connector10.version,
+    versions: { [connector10.version]: connector10 },
+};

package/dist/serialize.d.ts

@@ -3,7 +3,7 @@ import type { BuiltFlow } from './flow-sdk.js';
 import type { Library } from './library.js';
 import { type BindingRefusalCode } from './core/binding-messages.js';
 import type { Bindings } from './bindings.js';
-import { connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
+import { CONNECTOR_INPUT_MISSING, connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — Flow's binding of the shared validator.
@@ -23,8 +23,7 @@ export interface SerializeWarning {
     code: string;
     message: string;
 }
-/** A required connector input left empty — the one draft code with no error class of its own. */
-export declare const CONNECTOR_INPUT_MISSING = "CONNECTOR_INPUT_MISSING";
+export { CONNECTOR_INPUT_MISSING } from './core/connector-inputs.js';
 /** The refusals a draft-tolerant compile reports instead of throwing. */
 export type DraftCode = BindingRefusalCode | typeof CONNECTOR_INPUT_MISSING | 'CONNECTOR_OBJECT_REQUIRED';
 /** A refusal a draft-tolerant compile reported instead of throwing (see {@link SerializeOpts.draft}). */