@uipath/maestro-builder-sdk 6.36.1 → 6.38.0

package/dist/core/cli-library.d.ts

@@ -1,4 +1,4 @@
-import { Library, type ResolvedConnector } from './library.js';
+import { ConnectorResolveError, Library, type ResolvedConnector } from './library.js';
 import type { BindingsView } from './binding-messages.js';
 import { type ConnectorCheckOpts } from './connector-checks.js';
 import type { LookupResolutions, LookupSpec } from './lookups.js';
@@ -32,9 +32,15 @@ export declare function openCliLibrary(argv: readonly string[]): Library | undef
  * recorded by `registry prepare --resolve` would be reported as still owed,
  * telling the author to re-run a prepare they already ran.
  */
-export declare function connectorCheckOpts(library: Library | undefined, bindings?: BindingsView, inputErrors?: ConnectorInputValidator): ConnectorCheckOpts & EventCheckOpts;
+export declare function connectorCheckOpts(library: Library | undefined, bindings?: BindingsView, inputErrors?: ConnectorInputValidator, refuse?: ConnectorRefusal): ConnectorCheckOpts & EventCheckOpts;
 /** A family's field-contract validator: `compile`'s refusal for these inputs, or `undefined`. */
 export type ConnectorInputValidator = (rc: ResolvedConnector, inputs: Record<string, unknown>, resolutions: LookupResolutions, lookups: Readonly<Record<string, LookupSpec>>) => string | undefined;
+/**
+ * A family's own refusal of an operation the library DID resolve — Flow's
+ * `synthesizedDefinitionRefusal` — applied after `library.resolve`, so check
+ * and compile refuse the same entry with the same code and text.
+ */
+export type ConnectorRefusal = (rc: ResolvedConnector) => ConnectorResolveError | undefined;
 /**
  * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
  * for a subscription, or `undefined` when it resolves.

package/dist/core/cli-library.js

@@ -57,12 +57,12 @@ export function openCliLibrary(argv) {
  * recorded by `registry prepare --resolve` would be reported as still owed,
  * telling the author to re-run a prepare they already ran.
  */
-export function connectorCheckOpts(library, bindings, inputErrors = (rc, inputs, resolutions, lookups) => connectorInputErrors(rc, inputs, resolutions, lookups, { dialect: EQUALS_EXPR_DIALECT })) {
+export function connectorCheckOpts(library, bindings, inputErrors = (rc, inputs, resolutions, lookups) => connectorInputErrors(rc, inputs, resolutions, lookups, { dialect: EQUALS_EXPR_DIALECT }), refuse) {
     if (!library)
         return bindings ? { bindings } : {};
     // One memoized resolve per connector step, shared by `connectorResolveError`
     // and `connectorInputs`, so the second hook does not resolve again.
-    const resolve = connectorResolver(library);
+    const resolve = connectorResolver(library, refuse);
     return {
         eventResolveError: eventResolveErrorFor(library),
         ...byoaCheckOpts(library),
@@ -129,14 +129,16 @@ const CONNECTOR_RESOLVE_FAILED = 'CONNECTOR_RESOLVE_FAILED';
  * "unknown" used to let `check` pass a step `compile` then died on (#1015); the
  * event twin, `eventResolveErrorFor`, already reported every throw.
  */
-function connectorResolver(library) {
+function connectorResolver(library, refuse) {
     const memo = new Map();
     return (spec) => {
         const id = JSON.stringify([spec.key, spec.action, spec.version ?? null, spec.object ?? null]);
         let r = memo.get(id);
         if (!r) {
             try {
-                r = { rc: library.resolve(spec.key, spec.action, spec.version, spec.object) };
+                const rc = library.resolve(spec.key, spec.action, spec.version, spec.object);
+                const refused = refuse?.(rc);
+                r = refused ? { error: { code: refused.code, message: refused.message } } : { rc };
             }
             catch (error) {
                 r = error instanceof ConnectorResolveError

package/dist/core/connector-resolve-error.d.ts

@@ -15,7 +15,13 @@ export type ConnectorResolveCode =
  * The index lists the operation, but its entry file or `.v1def.json` sidecar is
  * missing or not valid JSON: the library on disk is incomplete (#1015).
  */
- | 'CONNECTOR_LIBRARY_ENTRY_UNREADABLE';
+ | 'CONNECTOR_LIBRARY_ENTRY_UNREADABLE'
+/**
+ * Flow only: the sidecar was synthesized from Integration Service by `registry
+ * prepare` (no registry node exists), and a Flow node needs the registry's
+ * definition. BPMN compiles the same entry (`core/synthesized-definition.ts`).
+ */
+ | 'CONNECTOR_NO_FLOW_DEFINITION';
 /**
  * The refusal `Library.resolve` throws, with a `code` for each reason.
  *

package/dist/core/event-checks.js

@@ -18,7 +18,7 @@
  * `skill-bpmn-outlook-waitfor-email` in `flow-v2-run-8` failed on exactly that last
  * question, and in run 12 on having nowhere to put a payload condition.
  */
-import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './lookups.js';
+import { isLookupToken, resolvedEventValue, unresolvedLookupMessage, } from './lookups.js';
 import { prepareCommand } from './cli-spelling.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem, jmesStringProblem } from './event-filters.js';
 import { EVENT_BYOA_UNVERIFIED, byoaUnverified } from './byoa.js';
@@ -129,7 +129,7 @@ export function checkEventResolution(subscription, where, kind, opts, error, war
     for (const [key, value] of scope) {
         if (!isLookupToken(value))
             continue;
-        if (resolvedValue(value, resolutions) !== undefined)
+        if (resolvedEventValue(value, resolutions) !== undefined)
             continue;
         warn('LOOKUP_UNRESOLVED', `${where}: \`where.${key}\` ` + unresolvedLookupMessage(value)
             + `\nCompile will fail until this is recorded.`);

package/dist/core/lookups.d.ts

@@ -114,6 +114,11 @@ export declare function lookup<D extends LookupBearing, F extends keyof NonNulla
  * and there are no typed aliases, so only the generic `.by(name, value)` is
  * available. A consistent trade rather than a new one.
  *
+ * On a connector EVENT's `where` (`.waitForEvent()` / `.eventTrigger()` /
+ * `onEvent()`), `action` is the event id and the token is matched against the
+ * resolution `prepare` recorded for the event as well, so this form and
+ * `lookup({ connector, event }, field)` resolve alike.
+ *
  * @param key - The connector library key, e.g. `'uipath-salesforce-slack'`.
  * @param action - The operation id, e.g. `'send-message-to-user'`.
  * @param field - The lookup field, e.g. `'channel'`.
@@ -177,6 +182,23 @@ export type LookupResolutions = Readonly<Record<string, LookupResolution>>;
  * @returns The connector-facing id, when this exact `(nodeType, field, by, value)` was resolved.
  */
 export declare function resolvedValue(token: LookupToken, resolutions: LookupResolutions): string | undefined;
+/**
+ * {@link resolvedValue} for a token on an event's `where`.
+ *
+ * `prepare` records an event's resolutions under the EVENT form of the node type,
+ * which the descriptor form `lookup({ connector, event }, field)` keys a token
+ * under too. The string form `lookup(key, action, field)` cannot know it is being
+ * used on an event and keys the token under the activity form, so a recorded
+ * resolution was never found for it: on the 2026-10-16 run an author whose
+ * `prepare --resolve parentFolderId:displayName=Inbox` had succeeded still saw
+ * `LOOKUP_UNRESOLVED` from `check` and a refusal from `compile`, and pasted the
+ * id in by hand. The token's own key is tried first; the event form second.
+ *
+ * @param token - The unresolved lookup, from either `lookup()` form.
+ * @param resolutions - Everything `prepare --resolve` has recorded.
+ * @returns The connector-facing id, when either key was resolved.
+ */
+export declare function resolvedEventValue(token: LookupToken, resolutions: LookupResolutions): string | undefined;
 /**
  * The message for a lookup nothing has resolved — the command that fixes it.
  *

package/dist/core/lookups.js

@@ -166,6 +166,39 @@ export function resolvedValue(token, resolutions) {
     const { nodeType, field, by, value } = token.__lookup;
     return resolutions[lookupKey(nodeType, field, by, value)]?.value;
 }
+/**
+ * The event form of a node type — `uipath.connector.event.<key>.<op>` — for one
+ * written without a role segment, else `undefined`. A role-less type is what the
+ * string form `lookup(key, action, field)` keys a token under.
+ */
+function eventFormOf(nodeType) {
+    const m = /^uipath\.connector\.(?!event\.|trigger\.)(.+)$/.exec(nodeType);
+    return m ? `uipath.connector.event.${m[1]}` : undefined;
+}
+/**
+ * {@link resolvedValue} for a token on an event's `where`.
+ *
+ * `prepare` records an event's resolutions under the EVENT form of the node type,
+ * which the descriptor form `lookup({ connector, event }, field)` keys a token
+ * under too. The string form `lookup(key, action, field)` cannot know it is being
+ * used on an event and keys the token under the activity form, so a recorded
+ * resolution was never found for it: on the 2026-10-16 run an author whose
+ * `prepare --resolve parentFolderId:displayName=Inbox` had succeeded still saw
+ * `LOOKUP_UNRESOLVED` from `check` and a refusal from `compile`, and pasted the
+ * id in by hand. The token's own key is tried first; the event form second.
+ *
+ * @param token - The unresolved lookup, from either `lookup()` form.
+ * @param resolutions - Everything `prepare --resolve` has recorded.
+ * @returns The connector-facing id, when either key was resolved.
+ */
+export function resolvedEventValue(token, resolutions) {
+    const own = resolvedValue(token, resolutions);
+    if (own !== undefined)
+        return own;
+    const { nodeType, field, by, value } = token.__lookup;
+    const eventForm = eventFormOf(nodeType);
+    return eventForm === undefined ? undefined : resolutions[lookupKey(eventForm, field, by, value)]?.value;
+}
 /**
  * The message for a lookup nothing has resolved — the command that fixes it.
  *
@@ -282,7 +315,7 @@ export function resolveEventWhere(where, resolutions, site) {
             out[key] = value;
             continue;
         }
-        const resolved = resolvedValue(value, resolutions);
+        const resolved = resolvedEventValue(value, resolutions);
         if (resolved === undefined)
             throw new Error(`${site}: \`where.${key}\` ` + unresolvedLookupMessage(value));
         out[key] = resolved;

package/dist/core/synthesized-definition.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The one refusal Flow adds on top of `Library.resolve`: an operation whose
+ * sidecar `registry prepare` synthesized from Integration Service
+ * (`prepare/integration-service.ts`) has no registry node behind it. A BPMN
+ * `sendTask` carries its own identity and rows, so BPMN compiles it; a Flow
+ * node embeds the registry's whole definition — form, handles, model — which
+ * no describe supplies, so Flow refuses it here, in `check` and `compile`
+ * alike, instead of emitting a node the designer cannot open.
+ */
+import { ConnectorResolveError } from './connector-resolve-error.js';
+import type { ResolvedConnector } from './library.js';
+/** The marker `prepare` writes on a sidecar it built from Integration Service. */
+export declare const SYNTHESIZED_FROM_INTEGRATION_SERVICE = "integration-service";
+/** Flow's refusal for a resolved operation with no registry definition, or `undefined` when it has one. */
+export declare function synthesizedDefinitionRefusal(rc: Pick<ResolvedConnector, 'v1def' | 'connectorKey' | 'nodeType'>): ConnectorResolveError | undefined;

package/dist/core/synthesized-definition.js

@@ -0,0 +1,22 @@
+/**
+ * The one refusal Flow adds on top of `Library.resolve`: an operation whose
+ * sidecar `registry prepare` synthesized from Integration Service
+ * (`prepare/integration-service.ts`) has no registry node behind it. A BPMN
+ * `sendTask` carries its own identity and rows, so BPMN compiles it; a Flow
+ * node embeds the registry's whole definition — form, handles, model — which
+ * no describe supplies, so Flow refuses it here, in `check` and `compile`
+ * alike, instead of emitting a node the designer cannot open.
+ */
+import { ConnectorResolveError } from './connector-resolve-error.js';
+/** The marker `prepare` writes on a sidecar it built from Integration Service. */
+export const SYNTHESIZED_FROM_INTEGRATION_SERVICE = 'integration-service';
+/** Flow's refusal for a resolved operation with no registry definition, or `undefined` when it has one. */
+export function synthesizedDefinitionRefusal(rc) {
+    const origin = rc.v1def?.synthesizedFrom;
+    if (origin !== SYNTHESIZED_FROM_INTEGRATION_SERVICE)
+        return undefined;
+    const action = String(rc.nodeType).replace(/^uipath\.connector\.[^.]+\./, '');
+    return new ConnectorResolveError('CONNECTOR_NO_FLOW_DEFINITION', `connector ${rc.connectorKey} ${action} was prepared from Integration Service because the Flow node catalog serves no node for ${rc.connectorKey}; `
+        + 'a Flow step or inline agent tool needs that node (its form, handles and model), so this operation compiles in BPMN only. '
+        + `Author it as a BPMN .connector(), or check \`uip maestro flow registry search ${rc.connectorKey}\` after \`registry pull --force\` in case the catalog has since gained it.`);
+}

package/dist/registry/library-build/context.d.ts

@@ -130,4 +130,20 @@ export declare function isResourcesList(ctx: BuildContext, connectorKey: string,
  * files are deliberately not reused: that output omitted the discovery
  * capabilities and would silently mark every connector static.
  */
+/** `uip is activities list`'s answer: its rows, or why it could not be read. */
+export type IsActivitiesCatalog = {
+    rows: unknown[];
+} | {
+    failure: string;
+};
+/**
+ * Cached `uip is activities list <key>`: the connector's activity catalog
+ * (every row, curated or not — the caller filters on `IsCurated`), or the
+ * failure in the CLI's own words ({@link failureReason}): a refusal, output
+ * that is not JSON, or a `Result: Failure` envelope (an expired token, a 5xx,
+ * a connector the tenant has not enabled). Cached beside the `is resources`
+ * payloads — it is the same catalog service, read without a connection — and
+ * a cached failure keeps its reason.
+ */
+export declare function isActivitiesCatalog(ctx: BuildContext, connectorKey: string): Promise<IsActivitiesCatalog>;
 export declare function isConnectorGet(ctx: BuildContext, connectorKey: string): Promise<unknown>;

package/dist/registry/library-build/context.js

@@ -16,7 +16,7 @@
 import { createHash } from "node:crypto";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByKeys } from "../compat/compare.js";
-import { isConnectorsMetadata, isResourcesDescribeObject, isResourcesDescribeOperation, isResourcesList as isResourcesListArgv, registryGet as registryGetArgv, } from "../uip/commands.js";
+import { isActivitiesList as isActivitiesListArgv, isConnectorsMetadata, isResourcesDescribeObject, isResourcesDescribeOperation, isResourcesList as isResourcesListArgv, registryGet as registryGetArgv, } from "../uip/commands.js";
 import { CACHED_FAILURE, isCachedFailure, safeCacheName } from "../uip/response-cache.js";
 import { failureReason, isNodeNotFound } from "../uip/envelope.js";
 import { get, isPyDict, pyOr, pyTruthy } from "./py.js";
@@ -251,11 +251,38 @@ export async function isResourcesList(ctx, connectorKey, options = {}) {
     return Array.isArray(payload.Data) ? payload.Data : undefined;
 }
 /**
- * `is_connector_get`: cached `uip is connectors metadata <key>`, answering the
- * first element of `Data` or `undefined`. The legacy `connectors get` cache
- * files are deliberately not reused: that output omitted the discovery
- * capabilities and would silently mark every connector static.
+ * Cached `uip is activities list <key>`: the connector's activity catalog
+ * (every row, curated or not — the caller filters on `IsCurated`), or the
+ * failure in the CLI's own words ({@link failureReason}): a refusal, output
+ * that is not JSON, or a `Result: Failure` envelope (an expired token, a 5xx,
+ * a connector the tenant has not enabled). Cached beside the `is resources`
+ * payloads — it is the same catalog service, read without a connection — and
+ * a cached failure keeps its reason.
  */
+export async function isActivitiesCatalog(ctx, connectorKey) {
+    const name = `${safeCacheName(connectorKey, "_activities_list")}.json`;
+    if (ctx.caches.is.has(name)) {
+        const cached = ctx.caches.is.read(name);
+        const data = get(cached, "Data");
+        if (Array.isArray(data))
+            return { rows: data };
+        return { failure: String(pyOr(get(cached, "Message"), "the cached answer carries no rows")) };
+    }
+    const result = await runUip(ctx, isActivitiesListArgv(connectorKey));
+    if (refused(result))
+        return { failure: failureReason(result) };
+    const parsed = parseStdout(result.stdout);
+    if (parsed === undefined)
+        return { failure: failureReason(result) };
+    const payload = envelope(parsed);
+    if (get(payload, "Result") !== "Success") {
+        const failure = failureReason(result);
+        writeCache(ctx.caches.is, name, { Result: "Failure", Message: failure, [CACHED_FAILURE]: true });
+        return { failure };
+    }
+    writeCache(ctx.caches.is, name, payload);
+    return Array.isArray(payload.Data) ? { rows: payload.Data } : { failure: "the answer carries no Data rows" };
+}
 export async function isConnectorGet(ctx, connectorKey) {
     const name = `${safeCacheName(connectorKey, "_connector_metadata")}.json`;
     const firstRow = (payload) => {

package/dist/registry/prepare/actions.d.ts

@@ -56,6 +56,21 @@ export interface RegistryCatalog {
      */
     failure?: string;
 }
+/** Whether `registry pull --force` refreshed the local catalog copy, or why not. */
+export type RegistryRefresh = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `uip maestro flow registry pull --force`: refresh the local catalog copy the
+ * probes and the search answer from. It never refreshes itself, so before
+ * `prepare` concludes that the catalog serves nothing for a connector it pulls
+ * once and looks again; a stale copy would otherwise send a connector the
+ * catalog does serve down the BPMN-only path, and state it as fact.
+ */
+export declare function refreshRegistryCatalog(client: UipClient, timeoutMs?: number): Promise<RegistryRefresh>;
 /**
  * `registry search <key>`, read for both catalogs. This runs only on the
  * failure path, to tell the author what the catalog does serve.

package/dist/registry/prepare/actions.js

@@ -18,7 +18,7 @@
  */
 import { compareCodePoints, sortedStrings } from "../compat/compare.js";
 import { editDistance } from "../../core/edit-distance.js";
-import { registrySearch } from "../uip/commands.js";
+import { registryPull, registrySearch } from "../uip/commands.js";
 import { failureReason, findJsonDocument, tail } from "../uip/envelope.js";
 import { isPlainObject, pyOr } from "./support.js";
 /**
@@ -141,6 +141,17 @@ export function registryEventIds(payload, connectorKey) {
         forms: ["trigger", "event"].filter((form) => forms.get(id).has(form)),
     }));
 }
+/**
+ * `uip maestro flow registry pull --force`: refresh the local catalog copy the
+ * probes and the search answer from. It never refreshes itself, so before
+ * `prepare` concludes that the catalog serves nothing for a connector it pulls
+ * once and looks again; a stale copy would otherwise send a connector the
+ * catalog does serve down the BPMN-only path, and state it as fact.
+ */
+export async function refreshRegistryCatalog(client, timeoutMs) {
+    const result = await client.run(registryPull(), timeoutMs === undefined ? undefined : { timeoutMs });
+    return result.code === 0 ? { ok: true } : { ok: false, reason: failureReason(result) };
+}
 /**
  * `registry search <key>`, read for both catalogs. This runs only on the
  * failure path, to tell the author what the catalog does serve.

package/dist/registry/prepare/integration-service.d.ts

@@ -0,0 +1,105 @@
+import { SYNTHESIZED_FROM_INTEGRATION_SERVICE } from "../../core/synthesized-definition.js";
+import { type BuildContext } from "../library-build/context.js";
+import type { LibraryEntry } from "../model/library.js";
+/** The marker a synthesized sidecar carries; Flow refuses a definition that has it. One owner, `core/`, so the writer and the refuser cannot drift. */
+export { SYNTHESIZED_FROM_INTEGRATION_SERVICE };
+/** One row of `uip is activities list`, the fields this module reads. */
+export interface IsActivity {
+    /** The activity's own name, PascalCase: `CreateTestSet`. */
+    name: string;
+    displayName: string;
+    description: string;
+    /** The IS object the activity addresses: `TestSet`. */
+    objectName: string;
+    /** The HTTP verb as the catalog spells it: `POST`, `GETBYID`, `PATCH`, … */
+    method: string;
+}
+/** Why the Integration Service path could not prepare the action. */
+export type IntegrationServiceMiss = 
+/** The catalog could not be listed (`reason`: the CLI's own words), or lists no curated activity (no `reason`). */
+{
+    kind: "no-catalog";
+    reason?: string;
+}
+/** The catalog lists curated activities, none of which is the action; their ids, for the refusal. */
+ | {
+    kind: "no-such-activity";
+    activities: string[];
+}
+/** The activity's HTTP method maps to no `is resources` verb, so there is no describe to read. */
+ | {
+    kind: "no-operation";
+    activity: IsActivity;
+}
+/** The activity exists but `is resources describe` returned no schema for it. */
+ | {
+    kind: "no-schema";
+    activity: IsActivity;
+    operation: string;
+};
+export interface IntegrationServicePrepared {
+    entry: LibraryEntry;
+    /**
+     * The action id the entry goes by: the activity's own name in kebab case,
+     * whatever spelling the author gave (`--action "Create Test Set"` prepares
+     * `create-test-set`). The overlay path and the handoff use it.
+     */
+    action: string;
+    /** The registry-shaped node `planLibrary` builds the sidecar from. */
+    node: Record<string, unknown>;
+    activity: IsActivity;
+    /** The `is resources` verb the describe was read under (`Create`, `Retrieve`, …). */
+    operation: string;
+}
+/**
+ * The action id an activity goes by: its PascalCase name in kebab case —
+ * `CreateTestSet` → `create-test-set`, `AssignTestCasesToReq` →
+ * `assign-test-cases-to-req`, `CreateV2Attachment` → `create-v2-attachment`.
+ * A run of capitals stays one word (`GetPDFReport` → `get-pdf-report`).
+ */
+export declare function activityActionId(name: string): string;
+/** The curated rows of an activities listing, in the catalog's order. */
+export declare function curatedActivities(rows: readonly unknown[]): IsActivity[];
+/**
+ * The curated activity an author's action names: by action id first
+ * (`create-test-set`), then by the activity's own name or display name,
+ * case-insensitively — `CreateTestSet`, `"Create Test Set"` and `create test set`
+ * all reach it. The spellings are compared both as given and in kebab case, so a
+ * display name with spaces matches whether or not the author kebab-cased it.
+ */
+export declare function matchActivity(activities: readonly IsActivity[], action: string): IsActivity | undefined;
+/** The `is resources` verb an activity's HTTP method reads under; `undefined` for a verb the catalog has no describe for. */
+export declare function describeOperationFor(method: string): string | undefined;
+/**
+ * Prepare one action from Integration Service: the entry and the node the
+ * sidecar is built from, or why not.
+ */
+export declare function integrationServiceEntry(ctx: BuildContext, input: {
+    connectorKey: string;
+    action: string;
+}): Promise<IntegrationServicePrepared | {
+    miss: IntegrationServiceMiss;
+}>;
+/**
+ * The library entry for one described activity — the shape `extractCanonical`
+ * writes from a registry node, filled from the describe instead: the IS
+ * object and verb, the path and its parameters, the request fields as the
+ * input schema. `httpMethod` keeps the catalog's spelling (`GETBYID` for a
+ * get-by-id, as registry entries do); the wire maps it. The entry goes by the
+ * activity's own action id, never the author's spelling: a display name would
+ * put spaces (or a `/`) in the overlay path and a second entry next to the id.
+ */
+export declare function synthesizeEntry(input: {
+    connectorKey: string;
+    activity: IsActivity;
+    operation: string;
+    described: Record<string, unknown>;
+    connector: unknown;
+}): LibraryEntry;
+/**
+ * The node `planLibrary` turns into the `.v1def.json` sidecar — the little a
+ * BPMN compile reads of one (`inputDefinition.fields` for the body, the model's
+ * type and service type) and the marker Flow refuses on. `buildV1Definition`
+ * keeps every key here.
+ */
+export declare function synthesizeNode(entry: LibraryEntry, described: Record<string, unknown>): Record<string, unknown>;