@uipath/maestro-builder-sdk 6.68.1 → 6.68.2

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

@@ -383,15 +383,23 @@ export interface BuiltCaseExitCondition {
 export type TaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'flow-process' | 'function' | 'business-rule' | 'external-agent' | 'external-workflow' | 'action' | 'connector' | 'wait-for-timer' | 'wait-for-connector';
 /**
  * Task kinds that the Case schema permits as unresolved skeletons: the
- * published-resource kinds, and `action` (a human task whose Action App or form
- * is not known yet). Each compiles to a task whose `data` is `{}`, which
- * `uip maestro case validate` reports as a `TASK_NOT_CONFIGURED` warning.
+ * published-resource kinds, `action` (a human task whose Action App or form is
+ * not known yet), and the two connector kinds, `connector` (an
+ * `execute-connector-activity` task) and `wait-for-connector`, for a connector
+ * or event the spec leaves unresolved. Each compiles to a task whose `data` is
+ * `{}`, which `uip maestro case validate` reports as a `TASK_NOT_CONFIGURED`
+ * warning.
  */
-export type UnresolvedReferenceTaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'function' | 'action';
+export type UnresolvedReferenceTaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'function' | 'action' | 'connector' | 'wait-for-connector';
 /**
  * A `wait-for-connector` subscription: suspend on an Integration Service event.
- * Omit `connectorKey`/`operation` for a bare **placeholder** (for a connector not
- * yet registered — `data.uipath` carries only `serviceType`).
+ * Omit `connectorKey`/`operation` for a bare **placeholder**, the same task as
+ * `.unresolved('wait-for-connector')`: its `data` is `{}`.
+ *
+ * Setting them is the legacy named form, which `uip maestro case validate`
+ * refuses on a task (`CASE_MGMT_CONNECTOR_ACTIVITY_UNRESOLVED`, #1560): for an
+ * unresolved event use `.unresolved('wait-for-connector')`, and for a known one
+ * a trigger descriptor or `{ connector, event }`.
  */
 export interface WaitConnectorPlaceholderSpec {
     /** Connector key, e.g. `uipath-microsoft-outlook365`. */
@@ -875,8 +883,20 @@ declare class TaskBuilder {
      * `unresolved('action')` is the human-task skeleton: no Action App, title,
      * recipient or form fields, for an app that is not published yet. Use
      * `.action({ ... })` instead once the form is known.
+     * `unresolved('connector')` and `unresolved('wait-for-connector')` are the
+     * connector placeholders, for a connector key, activity or event the spec
+     * leaves unresolved: do not pick a real connector to stand in for it. Use
+     * `.connector(...)` or `.waitForConnector(...)` once it is known.
+     *
+     * @example
+     * **Leave both connector tasks of an SDD with an `<UNRESOLVED>` connector as placeholders**
+     * ```ts
+     * casePlan('notice').stage('Notice', (s) => s
+     *   .task('Notify regulator', (t) => t.unresolved('connector'))
+     *   .task('Await notice', (t) => t.unresolved('wait-for-connector')))
+     * ```
      *
-     * @param kind - The task kind to preserve: a published-resource family, or `'action'` for a human task.
+     * @param kind - The task kind to preserve: a published-resource family, `'action'` for a human task, or `'connector'` / `'wait-for-connector'` for a connector task.
      * @returns This builder, so calls chain.
      */
     unresolved(kind: UnresolvedReferenceTaskKind): this;
@@ -1061,7 +1081,7 @@ declare class TaskBuilder {
     /**
      * A wait-for-connector task in placeholder or stringly-resolved form.
      *
-     * @param spec - Omit for a placeholder, pass `connectorKey`/`operation` for the legacy named placeholder,
+     * @param spec - Omit for a placeholder (`data: {}`, the same task as `.unresolved('wait-for-connector')`), pass `connectorKey`/`operation` for the legacy named form, which `uip maestro case validate` refuses on a task (#1560; for an unresolved event use `.unresolved('wait-for-connector')`),
      * or pass a symbolic `{ connector, event, ... }` subscription for library resolution.
      * @returns This builder, so calls chain.
      */

package/dist/case/case-sdk.js

@@ -4,6 +4,7 @@ import { checkCaseExpressions, CaseBuildError } from './case-expr-check.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS, recordAuthoredCaseVersion } from './format-profile.js';
 import { schemaVersionRefusal } from '../schema-version.js';
 import { CompileRefusal } from '../core/compile-refusal.js';
+import { isConnectorPlaceholder } from './connector-placeholder.js';
 export { preserveCaseJson } from './preserve.js';
 export { CaseBuildError } from './case-expr-check.js';
 /**
@@ -208,8 +209,20 @@ class TaskBuilder {
      * `unresolved('action')` is the human-task skeleton: no Action App, title,
      * recipient or form fields, for an app that is not published yet. Use
      * `.action({ ... })` instead once the form is known.
+     * `unresolved('connector')` and `unresolved('wait-for-connector')` are the
+     * connector placeholders, for a connector key, activity or event the spec
+     * leaves unresolved: do not pick a real connector to stand in for it. Use
+     * `.connector(...)` or `.waitForConnector(...)` once it is known.
      *
-     * @param kind - The task kind to preserve: a published-resource family, or `'action'` for a human task.
+     * @example
+     * **Leave both connector tasks of an SDD with an `<UNRESOLVED>` connector as placeholders**
+     * ```ts
+     * casePlan('notice').stage('Notice', (s) => s
+     *   .task('Notify regulator', (t) => t.unresolved('connector'))
+     *   .task('Await notice', (t) => t.unresolved('wait-for-connector')))
+     * ```
+     *
+     * @param kind - The task kind to preserve: a published-resource family, `'action'` for a human task, or `'connector'` / `'wait-for-connector'` for a connector task.
      * @returns This builder, so calls chain.
      */
     unresolved(kind) {
@@ -585,6 +598,14 @@ class TaskBuilder {
             throw new CompileRefusal('TASK_IO_UNRESOLVED_REFERENCE', `task "${this._name}": an unresolved reference task cannot declare inputs or outputs.`);
         if (!this._action && !this._ref && this._kind === 'action' && this._outputs)
             throw new CompileRefusal('TASK_IO_UNRESOLVED_REFERENCE', `task "${this._name}": an unresolved action task cannot declare outputs.`);
+        // A connector placeholder's `data` must stay `{}` (connector-placeholder.ts):
+        // any output row, an `{ assign }` one included, would make it a configured
+        // task the CLI refuses for naming no activity.
+        if (this._kind === 'connector' && this._outputs?.length && isConnectorPlaceholder({ kind: this._kind, connector: this._connector, waitConnector: this._waitConnector }))
+            throw new CompileRefusal('TASK_IO_UNRESOLVED_REFERENCE', `task "${this._name}": an unresolved connector task cannot declare outputs. Remove the outputs, or resolve the connector with .connector(...) first.`);
+        if (this._kind === 'wait-for-connector' && this._outputs?.length && !extract
+            && isConnectorPlaceholder({ kind: this._kind, connector: this._connector, waitConnector: this._waitConnector }))
+            throw new CompileRefusal('TASK_IO_UNRESOLVED_REFERENCE', `task "${this._name}": an unresolved wait-for-connector task cannot declare outputs. Remove the outputs, or name the event with .waitForConnector(<trigger descriptor>) first.`);
         if (this._kind === 'wait-for-connector' && extract
             && !(this._waitConnector && 'connector' in this._waitConnector && 'event' in this._waitConnector))
             throw new CompileRefusal('TASK_OUTPUTS_PLACEHOLDER_EVENT', `task "${this._name}": a placeholder wait-for-connector task has no event response to extract outputs from — name the event (.waitForConnector(<trigger descriptor>) or { connector, event }).`);

package/dist/case/check.js

@@ -9,6 +9,7 @@ import { checkEventResolution } from '../core/event-checks.js';
 import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalHybridRefusal, isExternalExecutionMode } from './external.js';
 import { isResourceLabelRefusal, resolveResourceRef } from './resource-identity.js';
 import { taskShapeProblems } from './task-shape.js';
+import { isConnectorPlaceholder } from './connector-placeholder.js';
 const TYPE_NAMES = new Set(Object.values(types));
 // audit-case-coverage: rule-slot table start
 // This runtime table must equal the committed matrix's rejected cells. The audit
@@ -362,7 +363,8 @@ function checkLibraryConnectors(built, opts, diags) {
         rules(stage.exit, `stage "${stage.label}" exit`);
         for (const t of stage.lanes.flat()) {
             rules(t.entry, `task "${t.name}" entry`);
-            if (t.kind === 'connector' && t.connector) {
+            // A placeholder (`.unresolved('connector')`) names no operation to resolve.
+            if (t.kind === 'connector' && t.connector && !isConnectorPlaceholder(t)) {
                 const where = `Connector task "${t.name}"`;
                 const spec = t.connector;
                 checkConnectorLookups(where, spec, opts, EQUALS_EXPR_DIALECT, reporter(where, t.name));

package/dist/case/connector-placeholder.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one definition of a Case **connector placeholder**: a connector task
+ * (`execute-connector-activity`) or a wait-for-connector task whose connector
+ * is not known yet (#1354).
+ *
+ * The contract is the CLI's. `uip maestro case validate` treats an empty task
+ * `data` as the unresolved placeholder and reports it with the
+ * `TASK_NOT_CONFIGURED` warning. Any other connector task `data`, however
+ * small, is judged as a configured task, and one without `metadata` and
+ * `objectName` context entries is refused with
+ * `CASE_MGMT_CONNECTOR_ACTIVITY_UNRESOLVED` (cli
+ * `packages/case-tool/src/services/case-validators/connector-activity-validator.ts`,
+ * `appliesTo` = connector task type and non-empty `data`).
+ *
+ * So, for example:
+ *
+ *   t.unresolved('wait-for-connector')  ->  { type: 'wait-for-connector', data: {} }
+ *   t.unresolved('connector')           ->  { type: 'execute-connector-activity', data: {} }
+ *   t.waitForConnector()                ->  { type: 'wait-for-connector', data: {} }
+ *
+ * The SDK once wrote `{ serviceType: 'Intsvc.WaitForEvent' }` for the bare
+ * wait-for-connector task, after an older caseplan. The CLI refuses that, so
+ * it is only read here (decompile lifts it back to the placeholder) and never
+ * written.
+ *
+ * `serialize` writes the placeholder, `check` skips the library checks for it,
+ * the builder refuses outputs on it, and `decompile` reads it back, all through
+ * this module. A wait-for-connector *rule* is not a task and keeps its own
+ * subscription bag. A task that names its connector without resolving it
+ * (`.waitForConnector({ connectorKey, operation })`) is not a placeholder and
+ * still writes its `context`; the CLI refuses that too (#1560).
+ */
+import type { BuiltTask, TaskKind } from './case-sdk.js';
+/** The SDK task kinds that have a connector placeholder. */
+export type ConnectorPlaceholderKind = Extract<TaskKind, 'connector' | 'wait-for-connector'>;
+/**
+ * Whether a built task is a connector placeholder: a connector task with no
+ * connector call, or a wait-for-connector task that names no event (no
+ * resolved subscription and no `connectorKey` / `operation`).
+ *
+ * @param task - The task as the builder recorded it.
+ * @returns True when the task compiles to the placeholder `data: {}`.
+ */
+export declare function isConnectorPlaceholder(task: Pick<BuiltTask, 'kind' | 'connector' | 'waitConnector'>): boolean;
+/** The placeholder's `data`: empty, the shape the CLI reads as unresolved. */
+export declare function connectorPlaceholderData(): Record<string, unknown>;
+/**
+ * The SDK kind of a caseplan task that is a connector placeholder, or
+ * undefined when it is not one.
+ *
+ * Reads the CLI's placeholder (`data` empty or absent) on both connector task
+ * types, and, on a wait-for-connector task, the two shapes older SDKs wrote
+ * for it: `{ serviceType: 'Intsvc.WaitForEvent' }`, optionally with empty
+ * `inputs` / `outputs` / `bindings`, and that plus a `connectorKey` /
+ * `operation` context whose values are both `"placeholder"`.
+ *
+ * @param type - The task's wire `type`.
+ * @param data - The task's `data`.
+ * @returns The kind to lift it to with `.unresolved(kind)`, or undefined.
+ */
+export declare function connectorPlaceholderKindOf(type: unknown, data: unknown): ConnectorPlaceholderKind | undefined;

package/dist/case/connector-placeholder.js

@@ -0,0 +1,70 @@
+import { CASE_FORMAT_PROFILE } from './format-profile.js';
+/** The keys an older SDK's wait-for-connector placeholder bag carried. */
+const LEGACY_WAIT_KEYS = new Set(['serviceType', 'context', 'inputs', 'outputs', 'bindings']);
+/**
+ * Whether a built task is a connector placeholder: a connector task with no
+ * connector call, or a wait-for-connector task that names no event (no
+ * resolved subscription and no `connectorKey` / `operation`).
+ *
+ * @param task - The task as the builder recorded it.
+ * @returns True when the task compiles to the placeholder `data: {}`.
+ */
+export function isConnectorPlaceholder(task) {
+    if (task.kind === 'connector')
+        return task.connector === undefined;
+    if (task.kind !== 'wait-for-connector')
+        return false;
+    const spec = task.waitConnector;
+    if (spec === undefined)
+        return true;
+    if ('connector' in spec && 'event' in spec)
+        return false;
+    return spec.connectorKey === undefined && spec.operation === undefined;
+}
+/** The placeholder's `data`: empty, the shape the CLI reads as unresolved. */
+export function connectorPlaceholderData() {
+    return {};
+}
+/**
+ * The SDK kind of a caseplan task that is a connector placeholder, or
+ * undefined when it is not one.
+ *
+ * Reads the CLI's placeholder (`data` empty or absent) on both connector task
+ * types, and, on a wait-for-connector task, the two shapes older SDKs wrote
+ * for it: `{ serviceType: 'Intsvc.WaitForEvent' }`, optionally with empty
+ * `inputs` / `outputs` / `bindings`, and that plus a `connectorKey` /
+ * `operation` context whose values are both `"placeholder"`.
+ *
+ * @param type - The task's wire `type`.
+ * @param data - The task's `data`.
+ * @returns The kind to lift it to with `.unresolved(kind)`, or undefined.
+ */
+export function connectorPlaceholderKindOf(type, data) {
+    const kind = type === CASE_FORMAT_PROFILE.connectorActivityNodeType ? 'connector'
+        : type === 'wait-for-connector' ? 'wait-for-connector'
+            : undefined;
+    if (!kind)
+        return undefined;
+    if (data === undefined || data === null)
+        return kind;
+    if (typeof data !== 'object' || Array.isArray(data))
+        return undefined;
+    const bag = data;
+    const keys = Object.keys(bag);
+    if (keys.length === 0)
+        return kind;
+    if (kind !== 'wait-for-connector' || bag.serviceType !== CASE_FORMAT_PROFILE.waitConnectorServiceType)
+        return undefined;
+    const emptyList = (value) => value === undefined || (Array.isArray(value) && value.length === 0);
+    if (!keys.every((key) => LEGACY_WAIT_KEYS.has(key)))
+        return undefined;
+    if (!['inputs', 'outputs', 'bindings'].every((key) => emptyList(bag[key])))
+        return undefined;
+    const context = bag.context;
+    if (context === undefined)
+        return kind;
+    const placeholderContext = Array.isArray(context) && context.length === 2
+        && ['connectorKey', 'operation'].every((name) => context
+            .some((row) => row?.name === name && row.value === 'placeholder'));
+    return placeholderContext ? kind : undefined;
+}

package/dist/case/decompile.js

@@ -7,6 +7,7 @@ import { ownEntry } from '../core/own-entry.js';
 import { isUnrestorableSlotId, taskFingerprint } from './preserve.js';
 import { isInSolutionKey, SOLUTION_FOLDER } from './resource-identity.js';
 import { offlineBindingLabel } from './ids.js';
+import { connectorPlaceholderKindOf } from './connector-placeholder.js';
 const TASK_KIND_METHOD = {
     process: 'process',
     agent: 'agent',
@@ -698,6 +699,12 @@ function externalCall(task, refs, library) {
 function emitTaskKind(task, refs, library) {
     const kind = task.type;
     const data = task.data ?? {};
+    // A connector placeholder (connector-placeholder.ts): `data: {}`, or an older
+    // SDK's serviceType-only wait bag. It names no connector, so it needs no
+    // library and lifts to the call that compiles to `{}` again.
+    const placeholder = connectorPlaceholderKindOf(kind, task.data);
+    if (placeholder)
+        return `.unresolved(${tsLiteral(placeholder)})`;
     const method = ownEntry(TASK_KIND_METHOD, kind);
     if (method) {
         if (kind !== 'flow-process' && data.name === undefined && data.folderPath === undefined) {
@@ -756,7 +763,10 @@ function emitTaskKind(task, refs, library) {
     }
     if (kind === 'wait-for-connector') {
         const spec = waitConnectorSpec(data, `wait-for-connector task "${task.displayName ?? task.id ?? '?'}"`, refs);
-        return spec === undefined ? '.waitForConnector()' : `.waitForConnector(${spec})`;
+        // A bag with no context and no resolved rows is the placeholder, lifted above.
+        if (spec === undefined)
+            throw new Error(`internal SDK error: wait-for-connector task "${task.displayName ?? task.id ?? '?'}" is a placeholder the lift above missed.`);
+        return `.waitForConnector(${spec})`;
     }
     const message = kind === 'business-rule'
         // The converter reads a missing version as v2, whose result shape differs

package/dist/case/serialize.js

@@ -32,6 +32,7 @@ import { responseJsonSchema } from '../core/connector-response-schema.js';
 import { ruleShapeProblems } from './rule-options.js';
 import { CompileRefusal } from '../core/compile-refusal.js';
 import { taskShapeProblems } from './task-shape.js';
+import { connectorPlaceholderData, isConnectorPlaceholder } from './connector-placeholder.js';
 /** The ids a serialize pass hashed from element ids, by the document it returned. */
 const ELEMENT_SEEDED_IDS = new WeakMap();
 function elementSeededId(resolver, elementId, suffix) {
@@ -1195,6 +1196,11 @@ function taskData(task, resolver, taskId, stageId, ids) {
     const [shape] = taskShapeProblems(task);
     if (shape)
         throw new CompileRefusal(shape.code, shape.message);
+    // `.unresolved('connector' | 'wait-for-connector')` and a bare
+    // `.waitForConnector()`: `data: {}`, the CLI's placeholder (validate warns
+    // TASK_NOT_CONFIGURED). The builder lets no output reach one.
+    if (isConnectorPlaceholder(task))
+        return connectorPlaceholderData();
     switch (task.kind) {
         case 'process':
         case 'agent':
@@ -1280,8 +1286,8 @@ function taskData(task, resolver, taskId, stageId, ids) {
             return withCustomOutputs(data, task, resolver);
         }
         case 'wait-for-connector':
-            // Floor placeholder (no connector named) = `serviceType` only; naming the
-            // connector/operation emits the `context` subscription.
+            // A placeholder returned `{}` above; naming the connector/operation emits
+            // the `context` subscription, and a resolved one the full bag.
             return withOutputExtracts(waitConnectorBag(task.waitConnector, { alwaysContext: false }, resolver, `${stageId}-${taskId}`, `Wait-for-connector task "${task.name}"`), task, ids, resolver);
     }
 }
@@ -1327,12 +1333,14 @@ function withCustomOutputs(data, task, resolver) {
     return data;
 }
 /**
- * The `wait-for-connector` subscription bag (`data` on the task, `uipath` on the
- * rule). Verified against a real `uip maestro case` caseplan: a placeholder
- * carries `serviceType: "Intsvc.WaitForEvent"`; naming the connector adds a
- * two-entry `context` (connectorKey + operation, defaulting to `"placeholder"`)
- * and empty `inputs`/`outputs`/`bindings`. A *rule* always carries the context —
- * `validate` rejects a bare `uipath` ("connector activity missing").
+ * The `wait-for-connector` subscription bag (`data` on a task that names its
+ * connector, `uipath` on the rule). The bag carries
+ * `serviceType: "Intsvc.WaitForEvent"`; naming the connector adds a two-entry
+ * `context` (connectorKey + operation, defaulting to `"placeholder"`) and empty
+ * `inputs`/`outputs`/`bindings`. A *rule* always carries the context —
+ * `validate` rejects a bare `uipath` ("connector activity missing"). A task
+ * that names no connector never gets here: its `data` is the placeholder `{}`
+ * (connector-placeholder.ts).
  */
 function waitConnectorBag(spec, opts, resolver, elementId, where) {
     if (isResolvedSubscription(spec))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.68.1",
+  "version": "6.68.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "cc5d3156131d305c073258591e362deb7f4fbbde"
+  "gitref": "169cc7e0b99153458305df193dd0336b44955b84"
 }