@uipath/maestro-builder-sdk 6.68.3 → 6.68.5

package/dist/bindings-v2.d.ts

@@ -1,13 +1,6 @@
 import type { ConnectionUse } from './core/compile-refusal.js';
-/** One declared solution resource. */
-export interface BindingsV2Resource {
-    resource: string;
-    key: string;
-    id?: string;
-    value: Record<string, unknown>;
-    metadata: Record<string, unknown>;
-    [k: string]: unknown;
-}
+import { type BindingsV2Resource } from './core/bindings-v2-resource.js';
+export type { BindingsV2Resource };
 /** The `bindings_v2.json` document. */
 export interface BindingsV2Document {
     version: string;

package/dist/bindings-v2.js

@@ -55,10 +55,11 @@
  */
 import { BindingRefusal, connectionConnectorConflictMessage } from './core/binding-messages.js';
 import { isRecord } from './core/node-envelope.js';
+import { BINDINGS_V2_DOCUMENT_VERSION, connectionResource, RESOURCE_BINDINGS_VERSION, } from './core/bindings-v2-resource.js';
 /** The document version pack emits. */
-const DOCUMENT_VERSION = '2.0';
+const DOCUMENT_VERSION = BINDINGS_V2_DOCUMENT_VERSION;
 /** The per-resource metadata version pack stamps. */
-const BINDINGS_VERSION = '2.2';
+const BINDINGS_VERSION = RESOURCE_BINDINGS_VERSION;
 function nonEmptyString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
@@ -235,26 +236,15 @@ export function connectionResources(flow) {
         const binding = candidates[0];
         const displayLabel = nonEmptyString(binding.name) ?? key;
         const label = isRecord(node.display) ? nonEmptyString(node.display.label) : undefined;
-        resources.push({
+        // The same row Case writes (core/bindings-v2-resource.ts); pack writes no folderKey slot.
+        resources.push(connectionResource({
             resource: 'connection',
             key,
-            // Pack concatenates resource and key with no separator for a connection.
-            id: `connection${key}`,
-            value: {
-                ConnectionId: {
-                    defaultValue: nonEmptyString(binding.default) ?? key,
-                    isExpression: false,
-                    displayName: displayLabel,
-                },
-            },
-            metadata: {
-                ActivityName: label ?? nonEmptyString(node.id) ?? key,
-                BindingsVersion: BINDINGS_VERSION,
-                DisplayLabel: displayLabel,
-                UseConnectionService: 'true',
-                Connector: connector,
-            },
-        });
+            connectionId: nonEmptyString(binding.default) ?? key,
+            displayLabel,
+            activityName: label ?? nonEmptyString(node.id) ?? key,
+            connector,
+        }));
     }
     return resources;
 }

package/dist/case/bindings-v2.d.ts

@@ -0,0 +1,3 @@
+import { type BindingsV2Resource } from '../core/bindings-v2-resource.js';
+/** Every resource the caseplan's root bindings declare, in the order their rows first appear. */
+export declare function deriveCaseBindingsV2(caseplan: Record<string, unknown>): BindingsV2Resource[];

package/dist/case/bindings-v2.js

@@ -0,0 +1,281 @@
+/**
+ * The `bindings_v2.json` resources a caseplan's root `bindings[]` rows declare:
+ * the root-row pass of `uip maestro case bindings sync` (`deriveCaseBindingsV2`
+ * in cli `packages/case-tool/src/services/case-bindings-service.ts`). It is
+ * NOT the whole CLI function; see "Not ported" below.
+ *
+ * `uip maestro case validate --strict` re-derives the sidecar with that
+ * function and compares it to the file on disk entry by entry, as serialized
+ * JSON (`STRICT_BINDINGS_SIDECAR_STALE`), so field order matters as well as
+ * field values. The CLI is a restricted package the SDK cannot depend on, so
+ * this is a copy; `tests/case-bindings-v2-parity.test.ts` holds it to the
+ * CLI's own output, one resource kind at a time, from a fixture the real CLI
+ * function derived. Re-record that fixture with
+ * `bun typescript/tests/fixtures/case-bindings-v2/record.ts <uipath-cli checkout>`.
+ *
+ * Every entry comes from the root `bindings[]` rows, grouped by
+ * `(resource, resourceKey)`:
+ *
+ *   - `Connection` → the connection row Flow writes too
+ *     ({@link connectionResource}); its connector and activity label come from
+ *     the connector context that references the row's binding id.
+ *   - `app` / `process` / `ixpDeployment` → the Case Designer shape.
+ *   - any other resource → the plain shape.
+ *
+ * Not ported — the CLI function's other passes:
+ *
+ *   - `EventTrigger` / `Property` entries for a connector start trigger
+ *     (`deriveEventTriggerResources`). The SDK writes these triggers, so this
+ *     is a live gap: builder-sdk#1557, a known-gap row in the parity test.
+ *   - The stored-binding overlay: entries a connector task keeps in its
+ *     `metadata` context's `body.bindings`, merged into the derived entry's
+ *     metadata or appended. The serializer's connector `metadata` body has no
+ *     `bindings` key, so there is nothing to overlay today.
+ *   - `Role` entries from `metadata.caseRoles`. The SDK neither authors nor
+ *     preserves `caseRoles` (it is not in preserve.ts's metadata keys).
+ *
+ * If the serializer starts writing either of the last two, port the pass and
+ * add a task for it to the parity fixture (`fixtures/case-bindings-v2/plan.ts`).
+ */
+import { isRecord } from '../core/node-envelope.js';
+import { connectionResource, RESOURCE_BINDINGS_VERSION, } from '../core/bindings-v2-resource.js';
+import { isInSolutionKey, SOLUTION_FOLDER } from './resource-identity.js';
+const CONNECTION_RESOURCE = 'Connection';
+/** The placeholder a manual-mode http-request task binds; nothing declares it. */
+const IMPLICIT_CONNECTION = 'ImplicitConnection';
+const CONNECTION_ID_ATTRIBUTE = 'ConnectionId';
+const FOLDER_KEY_ATTRIBUTE = 'folderKey';
+const BINDING_REFERENCE_PREFIX = '=bindings.';
+function asBindingRow(value) {
+    if (!isRecord(value))
+        return undefined;
+    return typeof value.id === 'string'
+        && typeof value.resource === 'string'
+        && typeof value.resourceKey === 'string'
+        && value.resourceKey !== ''
+        && typeof value.propertyAttribute === 'string'
+        && (value.default === undefined || typeof value.default === 'string')
+        ? value
+        : undefined;
+}
+/** Every resource the caseplan's root bindings declare, in the order their rows first appear. */
+export function deriveCaseBindingsV2(caseplan) {
+    const groups = new Map();
+    for (const entry of Array.isArray(caseplan.bindings) ? caseplan.bindings : []) {
+        const binding = asBindingRow(entry);
+        if (!binding)
+            continue;
+        if (binding.resource === CONNECTION_RESOURCE && binding.resourceKey === IMPLICIT_CONNECTION)
+            continue;
+        const groupKey = `${binding.resource}:${binding.resourceKey}`;
+        const group = groups.get(groupKey);
+        if (group)
+            group.push(binding);
+        else
+            groups.set(groupKey, [binding]);
+    }
+    const connectorUses = collectConnectorUses(caseplan);
+    const labels = bindingLabels(caseplan.nodes);
+    return [...groups.values()].map((group) => group[0].resource === CONNECTION_RESOURCE
+        ? connectionEntry(group, connectorUses)
+        : resourceEntry(group, labels));
+}
+function attributeDefault(group, attribute) {
+    return group.find((binding) => binding.propertyAttribute === attribute)?.default;
+}
+/**
+ * A connection: its `ConnectionId` row labels it, its `folderKey` row (keyed
+ * by the connection, not the folder) gives the folder slot.
+ */
+function connectionEntry(group, uses) {
+    const key = group[0].resourceKey;
+    const use = group.map((binding) => uses.get(binding.id)).find((found) => found !== undefined);
+    const label = (group.find((binding) => binding.propertyAttribute === CONNECTION_ID_ATTRIBUTE) ?? group[0]).name;
+    return connectionResource({
+        resource: CONNECTION_RESOURCE,
+        key,
+        connectionId: attributeDefault(group, CONNECTION_ID_ATTRIBUTE) ?? key,
+        ...(typeof label === 'string' && label !== '' && { displayLabel: label }),
+        folderKey: attributeDefault(group, FOLDER_KEY_ATTRIBUTE),
+        activityName: use?.activityName,
+        connector: use?.connectorKey,
+    });
+}
+/**
+ * The Case Designer's label for each value slot of an app or process entry.
+ * These resources get the Designer shape (cli#5003, MST-16424): an `id`, each
+ * slot flagged and labelled, and the `BindingsVersion` / `SolutionsSupport`
+ * metadata without which deploy cannot override the entry.
+ */
+const DESIGNER_SLOT_NAMES = new Map([
+    ['app', { name: 'App name', folderPath: 'Folder path', solutionsSupport: true }],
+    ['process', { name: 'Process name', folderPath: 'Folder path', solutionsSupport: true }],
+    ['ixpDeployment', { name: 'name', folderPath: 'Folder path', solutionsSupport: false }],
+]);
+/**
+ * One sidecar entry for a group of root binding rows that share a resource and
+ * a resource key. The subtype comes from the rows only: a Flow's rows carry
+ * none, so its entry has none either, as the Designer saves it.
+ *
+ * `metadata.ActivityName` labels a Designer-shaped entry with the first task
+ * that references one of its rows ({@link bindingLabels}).
+ */
+function resourceEntry(group, labels) {
+    const resource = group[0].resource;
+    const key = group[0].resourceKey;
+    // An in-solution resource binds an empty folderPath in the caseplan, while
+    // the sidecar names its folder by the sentinel the key carries.
+    const folderPath = isInSolutionKey(key) ? SOLUTION_FOLDER : attributeDefault(group, 'folderPath');
+    const name = attributeDefault(group, 'name');
+    const subType = group.map((binding) => binding.resourceSubType).find((found) => found !== undefined);
+    const designer = DESIGNER_SLOT_NAMES.get(resource);
+    if (designer) {
+        const value = {};
+        if (folderPath !== undefined) {
+            value.folderPath = { defaultValue: folderPath, isExpression: false, displayName: designer.folderPath };
+        }
+        if (name !== undefined) {
+            value.name = { defaultValue: name, isExpression: false, displayName: designer.name };
+        }
+        const activityName = group.map((binding) => labels.get(binding.id)).find((found) => found !== undefined);
+        return {
+            resource,
+            key,
+            id: `${resource}${key}`,
+            value,
+            metadata: {
+                ...(activityName !== undefined && { ActivityName: activityName }),
+                BindingsVersion: RESOURCE_BINDINGS_VERSION,
+                DisplayLabel: 'name',
+                ...(designer.solutionsSupport && { SolutionsSupport: 'true' }),
+                ...(subType !== undefined && { subType }),
+            },
+        };
+    }
+    const value = {};
+    if (name !== undefined)
+        value.name = { defaultValue: name };
+    if (folderPath !== undefined)
+        value.folderPath = { defaultValue: folderPath };
+    // A solution-resource picker (such as a Data Fabric entity) carries its folder key as a slot of its own.
+    const folderKey = attributeDefault(group, FOLDER_KEY_ATTRIBUTE);
+    if (folderKey !== undefined)
+        value.folderKey = { defaultValue: folderKey };
+    return {
+        resource,
+        key,
+        value,
+        metadata: {
+            BindingsVersion: RESOURCE_BINDINGS_VERSION,
+            ...(subType !== undefined && { subType }),
+        },
+    };
+}
+/** A task's or condition's `displayName`, a trigger's `display.label`, or a legacy node's `label`. */
+function ownLabel(node) {
+    const display = isRecord(node.display) ? node.display.label : undefined;
+    return [node.displayName, display, node.label].find((label) => typeof label === 'string' && label !== '');
+}
+/**
+ * Every value under `root`, each with the label of the nearest object above it
+ * that names itself ({@link ownLabel}) — the CLI's `walkLabelled`.
+ */
+function walkLabelled(root, visit) {
+    const walk = (node, label) => {
+        visit(node, label);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item, label);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        const scoped = ownLabel(node) ?? label;
+        for (const value of Object.values(node))
+            walk(value, scoped);
+    };
+    walk(root, undefined);
+}
+/** A `{ name, value }` context array that names a connector, by entry name; else undefined. */
+function connectorContext(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const byName = new Map();
+    for (const entry of value) {
+        if (!isRecord(entry) || typeof entry.name !== 'string')
+            return undefined;
+        if (typeof entry.value === 'string')
+            byName.set(entry.name, entry.value);
+    }
+    return byName.has('connectorKey') ? byName : undefined;
+}
+function referencedBindingId(context) {
+    const connection = context?.get('connection');
+    return connection?.startsWith(BINDING_REFERENCE_PREFIX)
+        ? connection.slice(BINDING_REFERENCE_PREFIX.length)
+        : undefined;
+}
+/**
+ * The connector whose authentication an http-request task reuses: its `body`
+ * input's `targetConnector`. Its context names the generic HTTP connector
+ * whatever the request calls, while the connection belongs to the target.
+ */
+function httpTargetConnector(node) {
+    if (!isRecord(node) || node.type !== 'http-request' || !isRecord(node.data) || !Array.isArray(node.data.inputs)) {
+        return undefined;
+    }
+    for (const input of node.data.inputs) {
+        if (!isRecord(input) || input.name !== 'body' || !isRecord(input.body))
+            continue;
+        const target = input.body.targetConnector;
+        if (typeof target === 'string' && target !== '')
+            return target;
+    }
+    return undefined;
+}
+/**
+ * The connector of each connection binding, keyed by binding id, from the
+ * connector contexts that reference it (`connection: "=bindings.<id>"`). The
+ * first use wins, as the CLI's `collectConnectorKeys` decides it.
+ */
+function collectConnectorUses(caseplan) {
+    const byBindingId = new Map();
+    walkLabelled(caseplan, (node, label) => {
+        // Before the context array beneath it, which would otherwise claim the
+        // binding for the generic HTTP connector.
+        const target = httpTargetConnector(node);
+        if (target !== undefined && isRecord(node)) {
+            const data = node.data;
+            const bindingId = referencedBindingId(connectorContext(data.context));
+            if (bindingId !== undefined && !byBindingId.has(bindingId)) {
+                byBindingId.set(bindingId, { connectorKey: target, activityName: ownLabel(node) ?? label });
+            }
+        }
+        if (!Array.isArray(node))
+            return;
+        const context = connectorContext(node);
+        const connectorKey = context?.get('connectorKey');
+        const bindingId = referencedBindingId(context);
+        if (connectorKey !== undefined && bindingId !== undefined && !byBindingId.has(bindingId)) {
+            byBindingId.set(bindingId, { connectorKey, activityName: label });
+        }
+    });
+    return byBindingId;
+}
+/**
+ * The label of the first object that references each binding id
+ * (`=bindings.<id>`), in document order: the nearest enclosing `displayName`,
+ * `display.label` or `label`. The same walk as the CLI's
+ * `collectBindingLabels`, so both name an entry after the same task.
+ */
+function bindingLabels(nodes) {
+    const found = new Map();
+    walkLabelled(nodes ?? [], (node, label) => {
+        if (typeof node !== 'string' || label === undefined || !node.startsWith(BINDING_REFERENCE_PREFIX))
+            return;
+        const id = node.slice(BINDING_REFERENCE_PREFIX.length);
+        if (!found.has(id))
+            found.set(id, label);
+    });
+    return found;
+}

package/dist/case/case-sdk.d.ts

@@ -437,9 +437,10 @@ export type ConnectorSpecData = Extract<ActionSpec, {
  * and `hybrid` as `Async…Execution`, and writes the value itself into the task's
  * `executionType` context.
  *
- * `hybrid` is refused for now (EXTERNAL_TASK_HYBRID_UNSUPPORTED): the Designer
- * also writes an event pair for it (`operation`, `eventMode`) that the connector
- * library does not carry (#1387). Add a task on a hybrid object in Studio Web.
+ * An `async` or `hybrid` object also answers through an event, which the
+ * Designer saves next to it; pass that pair as {@link ExternalTaskOptions.event}.
+ * A `hybrid` task without it is refused (EXTERNAL_TASK_EVENT), since the task
+ * would have nothing to wait on.
  *
  * It does not decide whether the stage waits for the task. A task the stage must
  * not wait on is `.required(false)`, whatever its execution type. For example, a
@@ -447,6 +448,27 @@ export type ConnectorSpecData = Extract<ActionSpec, {
  * it.
  */
 export type ExternalExecutionMode = 'sync' | 'async' | 'hybrid';
+/**
+ * The event an `async` or `hybrid` external object answers with, as Integration
+ * Service reports it for the connector object.
+ *
+ * @remarks
+ * Like the execution type, a property of the connector object, not a choice:
+ * the Case Designer reads it from the object's metadata (its first event mode
+ * and that mode's first event type) and saves it as the task's `operation` and
+ * `eventMode` context rows, and as `eventType` / `eventMode` in the metadata's
+ * `activityPropertyConfiguration`. Copy it from the same two rows of the
+ * activity's `case spec` result (`caseShape.context`). `decompile` lifts it from
+ * a saved task. For
+ * example, the Power Automate "Invoke a Flow" object (`hybrid`) answers with
+ * `{ operation: 'TRIGGER_CREATED', mode: 'polling' }`.
+ */
+export interface ExternalEventPair {
+    /** The event operation, e.g. `TRIGGER_CREATED`: the task's `operation` context row. */
+    operation: string;
+    /** How the event is received: the task's `eventMode` context row. */
+    mode: 'polling' | 'webhooks';
+}
 /** Required wiring and typed inputs for an external agent/workflow invocation. */
 export interface ExternalTaskOptions<I extends Record<string, unknown>> {
     /** Symbolic Integration Service connection name declared in `bindings.json`. */
@@ -460,6 +482,12 @@ export interface ExternalTaskOptions<I extends Record<string, unknown>> {
      * `.required(false)`. See {@link ExternalExecutionMode}.
      */
     mode: ExternalExecutionMode;
+    /**
+     * The event an `async` or `hybrid` object answers with. Required for `hybrid`;
+     * optional for `async`; refused for `sync`, which answers inline. See
+     * {@link ExternalEventPair}.
+     */
+    event?: ExternalEventPair;
     /** Inputs statically checked by the generated connector descriptor. */
     inputs: I;
 }
@@ -467,6 +495,8 @@ export interface ExternalTaskOptions<I extends Record<string, unknown>> {
 export interface ExternalTaskSpecData {
     /** The connector object's `executionType`. */
     mode: ExternalExecutionMode;
+    /** The event an `async` or `hybrid` object answers with, when given. */
+    event?: ExternalEventPair;
     /** Shared connector action identity, inputs, and symbolic bindings. */
     connector: ConnectorSpecData;
 }

package/dist/case/case-sdk.js

@@ -334,6 +334,7 @@ class TaskBuilder {
         this.setKind(kind);
         this._external = {
             mode: opts.mode,
+            ...(opts.event !== undefined ? { event: { ...opts.event } } : {}),
             connector: makeConnector(descriptor, opts.inputs, {
                 connection: opts.connection,
                 folder: opts.folder,

package/dist/case/check.js

@@ -6,7 +6,7 @@ import { schemaVersionRefusal } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors, preservedBindings } from './preserve.js';
 import { EQUALS_EXPR_DIALECT, checkBindingLabels, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, } from '../core/connector-checks.js';
 import { checkEventResolution } from '../core/event-checks.js';
-import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalHybridRefusal, isExternalExecutionMode } from './external.js';
+import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_EVENT, externalEventRefusal, isExternalExecutionMode } from './external.js';
 import { isResourceLabelRefusal, resolveResourceRef } from './resource-identity.js';
 import { taskShapeProblems } from './task-shape.js';
 import { isConnectorPlaceholder } from './connector-placeholder.js';
@@ -623,13 +623,11 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
                         message: `${family} task "${t.name}" mode must be the connector object's executionType: "sync", "async" or "hybrid".`,
                         where: t.name,
                     });
-                else if (t.external.mode === 'hybrid')
-                    diags.push({
-                        level: 'error',
-                        code: EXTERNAL_TASK_HYBRID_UNSUPPORTED,
-                        message: externalHybridRefusal(`${family} task "${t.name}"`),
-                        where: t.name,
-                    });
+                else {
+                    const refused = externalEventRefusal(`${family} task "${t.name}"`, t.external.mode, t.external.event);
+                    if (refused)
+                        diags.push({ level: 'error', code: EXTERNAL_TASK_EVENT, message: refused, where: t.name });
+                }
                 if (!t.external.connector?.key?.trim() || !t.external.connector?.action?.trim())
                     diags.push({
                         level: 'error',