@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

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

@@ -0,0 +1,512 @@
+/**
+ * Canonical extraction: one raw `flow registry get` node into one library entry.
+ *
+ * Everything here is a pure function of its arguments. The key ORDER of the
+ * entry it builds is the Python's dict order and is load-bearing: the entry is
+ * written with `json.dump(indent=2)` and the library's sha256 is published, so
+ * a key that moves is a different library.
+ *
+ * Also here: the connector-record stamping (`merge_connector_record`), the
+ * tier readers, the three node-type → connector-key parsers, the published-
+ * catalog filter, and the curated override tables the generator carries.
+ */
+import { pyStr, pyStrip, lowerFirst, startsWithUpper } from "../compat/pystr.js";
+import { sortedStrings } from "../compat/compare.js";
+import { get, isRecord, pyIter, pyOr, partition, truthy } from "./py.js";
+import { schemaAction } from "./schema-action.js";
+export const SCHEMA_VERSION = "1";
+/** `(connectorKey, objectName)` as a Map key; `null`s stay distinct from `""`. */
+function curatedKey(connectorKey, objectName) {
+    return JSON.stringify([connectorKey ?? null, objectName ?? null]);
+}
+/**
+ * Ops the IS CLI exposes as a POST whose inputs are query-string params with a
+ * required (often empty) body. A dispatcher reads
+ * `operation.dispatchStyle == "query-post"` and dispatches
+ * `run create <obj> --query <inputs> --body '{}'` instead of the default
+ * create→--body. The registry does not expose per-parameter location, so this
+ * is a small explicit list rather than derived.
+ */
+export const CURATED_DISPATCH_STYLE = new Map([
+    [curatedKey("uipath-uipath-dataservice", "QueryEntityRecords_V3"), "query-post"],
+    // The V2 curated sibling, and the one the REGISTRY node
+    // `uipath.connector.uipath-uipath-dataservice.query-entity-records` maps to:
+    // POST /v2/{entityName}/qer, every input a path or query parameter, body `{}`.
+    [curatedKey("uipath-uipath-dataservice", "QueryEntityRecordsCurated"), "query-post"],
+]);
+/**
+ * Per-parameter value-grammar tags. A dispatcher validates the COMPUTED input
+ * against `operation.paramGrammars` at every dispatch boundary. "sql-where":
+ * Data Service query expressions (RHS string literals must be single-quoted).
+ */
+export const CURATED_PARAM_GRAMMARS = new Map([
+    [curatedKey("uipath-uipath-dataservice", "QueryEntityRecords_V3"), { queryExpression: "sql-where" }],
+    [curatedKey("uipath-uipath-dataservice", "QueryEntityRecords"), { queryExpression: "sql-where" }],
+    [curatedKey("uipath-uipath-dataservice", "QueryEntityRecordsCurated"), { queryExpression: "sql-where" }],
+]);
+/**
+ * A few connector ops the registry enumerates only in a form `uip is resources
+ * run` can't dispatch. The Outlook reply op is enumerated as the MULTIPART
+ * `ReplyToEmailV2`; the connector also exposes the non-multipart sibling
+ * `ReplyToEmail` that Flow v1 uses. Keyed by (connectorKey, registry
+ * objectName); deep-merged into `operation` AFTER enrichment so it wins over
+ * the `is resources describe` params.
+ */
+export const CURATED_OP_OVERRIDE = new Map([
+    [
+        curatedKey("uipath-microsoft-outlook365", "ReplyToEmailV2"),
+        {
+            operation: {
+                objectName: "ReplyToEmail",
+                path: "/ReplyToEmail",
+                parameters: [
+                    {
+                        name: "id",
+                        type: "query",
+                        dataType: "string",
+                        required: true,
+                        displayName: "Message ID",
+                        description: "The id of the email to reply to",
+                    },
+                ],
+            },
+        },
+    ],
+]);
+/**
+ * `apply_curated_overrides`: deep-merge CURATED_OP_OVERRIDE into matching
+ * entries, AFTER enrichment, so the curated shape wins over the registry-
+ * described one. Matches on (connectorKey, objectName) using the entry's
+ * current (registry) objectName. Returns how many entries were touched.
+ */
+export function applyCuratedOverrides(entries, overrides = CURATED_OP_OVERRIDE) {
+    let n = 0;
+    for (const e of entries) {
+        const key = curatedKey(get(pyOr(get(e, "connector", {}), {}), "key", ""), get(pyOr(get(e, "operation", {}), {}), "objectName", ""));
+        const override = overrides.get(key);
+        if (!truthy(override))
+            continue;
+        const target = e;
+        for (const [section, fields] of Object.entries(override)) {
+            if (!(section in target) || target[section] === undefined)
+                target[section] = {};
+            const sectionValue = target[section];
+            for (const [k, v] of Object.entries(fields))
+                sectionValue[k] = v;
+        }
+        n += 1;
+    }
+    return n;
+}
+/** The `value` of the context entry named `name`, or `null`. */
+export function contextValue(context, name) {
+    for (const c of pyIter(context)) {
+        if (get(c, "name") === name)
+            return get(c, "value");
+    }
+    return null;
+}
+export function hasContext(context, name) {
+    return pyIter(context).some((c) => get(c, "name") === name);
+}
+/**
+ * `_parameter_metadata`: field-shaped metadata carried by each method
+ * parameter, keyed by name.
+ *
+ * A method parameter and a node field describe the same input in two
+ * different schemas. `displayName`, `reference` and the choice list exist on
+ * both sides, so they are the only ones worth moving across. A parameter's
+ * `enum` is deprecated in favour of `enhancedEnum`, whose `{name, value}`
+ * pairs flatten to the literals a field's `enum` holds.
+ */
+export function parameterMetadata(connectorMethodInfo) {
+    const out = new Map();
+    for (const p of pyIter(pyOr(get(pyOr(connectorMethodInfo, {}), "parameters"), []))) {
+        const name = get(p, "name");
+        if (typeof name !== "string" || !name)
+            continue;
+        const meta = {};
+        if (get(p, "displayName") !== null)
+            meta.displayName = get(p, "displayName");
+        if (get(p, "reference") !== null)
+            meta.reference = get(p, "reference");
+        if (isRecord(p) && "enum" in p) {
+            meta.enum = p.enum ?? null;
+        }
+        else if (truthy(get(p, "enhancedEnum"))) {
+            const values = pyIter(get(p, "enhancedEnum"))
+                .filter((e) => isRecord(e) && get(e, "value") !== null)
+                .map((e) => get(e, "value"));
+            if (values.length > 0)
+                meta.enum = values;
+        }
+        if (truthy(meta))
+            out.set(name, meta);
+    }
+    return out;
+}
+/** `Data.Node` from a parsed `flow registry get` response, or `null`. */
+export function nodeOf(payload) {
+    return get(get(payload, "Data", {}), "Node");
+}
+/**
+ * `extract_canonical`: the library entry for one registry `Data.Node`, or
+ * `undefined` when the node is filtered out (not enabled, not cross-platform,
+ * experimental, or without a `connectorDetail` block).
+ */
+export function extractCanonical(nodeData, ctx = {}) {
+    const node = nodeData;
+    if (!truthy(node))
+        return undefined;
+    const nodeType = get(node, "nodeType", "");
+    const model = pyOr(get(node, "model", {}), {});
+    const context = pyOr(get(model, "context", []), []);
+    // Activity-level metadata lives in the editor form: search
+    // `node.form.sections[*].fields[*].componentProps` for the `connectorDetail`
+    // block — isEnabled / targetPlatform / isExperimental / configuration.
+    let connectorDetail;
+    for (const section of pyIter(pyOr(get(pyOr(get(node, "form", {}), {}), "sections", []), []))) {
+        for (const f of pyIter(pyOr(get(section, "fields", []), []))) {
+            const cp = get(pyOr(get(f, "componentProps"), {}), "connectorDetail");
+            if (isRecord(cp) && "configuration" in cp) {
+                connectorDetail = cp;
+                break;
+            }
+        }
+        if (connectorDetail)
+            break;
+    }
+    if (!truthy(connectorDetail))
+        return undefined;
+    if (!truthy(get(connectorDetail, "isEnabled", false)))
+        return undefined;
+    if (get(connectorDetail, "targetPlatform") !== "CrossPlatform")
+        return undefined;
+    if (truthy(get(connectorDetail, "isExperimental", true)))
+        return undefined;
+    const configuration = get(connectorDetail, "configuration", "{}");
+    if (typeof configuration !== "string") {
+        throw new TypeError(`the JSON object must be str, bytes or bytearray, not ${configuration === null ? "NoneType" : typeof configuration}`);
+    }
+    let config;
+    try {
+        config = JSON.parse(configuration);
+    }
+    catch {
+        return undefined;
+    }
+    const activityType = get(config, "activityType", "");
+    // The human-readable verb lives on connectorMethodInfo when present; fall
+    // back to the model.context entry, then to the configuration blob (Generic
+    // CRUD actions carry it only there).
+    const cmi = pyOr(get(node, "connectorMethodInfo", {}), {});
+    const operationName = pyOr(get(cmi, "operation"), contextValue(context, "operation"), get(config, "operation"), "");
+    const path = pyOr(get(cmi, "path"), "");
+    const curated = pyOr(get(cmi, "curated"), {});
+    const objectDisplayName = pyOr(get(curated, "displayName"), "");
+    // Input fields: take `inputDefinition.fields` when they exist and fill their
+    // gaps from `connectorMethodInfo.parameters`; build them from the parameters
+    // when they do not. Gaps only — a value the node already states wins.
+    const paramMeta = parameterMetadata(cmi);
+    const declaredFields = pyOr(get(get(node, "inputDefinition", {}), "fields"), []);
+    const inputFields = [];
+    if (truthy(declaredFields)) {
+        for (const declared of pyIter(declaredFields)) {
+            if (!isRecord(declared))
+                throw new TypeError("cannot convert dictionary update sequence element to a dict");
+            const merged = { ...declared };
+            const meta = paramMeta.get(get(merged, "name")) ?? {};
+            for (const [key, value] of Object.entries(meta)) {
+                if (!(key in merged) || merged[key] === undefined)
+                    merged[key] = value;
+            }
+            inputFields.push(merged);
+        }
+    }
+    else {
+        for (const p of pyIter(pyOr(get(cmi, "parameters", []), []))) {
+            const f = {
+                name: get(p, "name", ""),
+                type: get(p, "dataType", "string"),
+                required: get(p, "required", false),
+                description: get(p, "description", ""),
+            };
+            Object.assign(f, paramMeta.get(f.name) ?? {});
+            inputFields.push(f);
+        }
+    }
+    let outputFields = get(get(node, "outputDefinition", {}), "fields");
+    if (!truthy(outputFields))
+        outputFields = get(get(node, "outputResponseDefinition", {}), "fields");
+    if (!truthy(outputFields))
+        outputFields = [];
+    const display = pyOr(get(node, "display", {}), {});
+    const isTrigger = pyStr(activityType).endsWith("Trigger");
+    const operation = {
+        name: operationName,
+        objectName: get(config, "objectName", ""),
+        objectDisplayName,
+        httpMethod: get(config, "httpMethod", ""),
+        path,
+        subType: get(config, "subType", ""),
+        supportsStreaming: get(config, "supportsStreaming", false),
+        activityType,
+    };
+    // A connector EVENT's operation is not `operation.name` — that is the
+    // object's CRUD verb. The event's own operation is the `model.context` entry
+    // the platform stamps (`EMAIL_RECEIVED`), the key every trigger API takes.
+    if (isTrigger)
+        operation.eventOperation = pyOr(contextValue(context, "operation"), "");
+    if (isTrigger && truthy(get(node, "eventMode")))
+        operation.eventMode = pyOr(get(node, "eventMode"), "");
+    const entry = {
+        schemaVersion: ctx.schemaVersion ?? SCHEMA_VERSION,
+        nodeType,
+        version: pyOr(get(config, "version", ""), get(node, "version", "")),
+        category: get(node, "category", ""),
+        tags: get(node, "tags", []),
+        connector: {
+            key: get(config, "connectorKey", ""),
+        },
+        operation,
+        display: {
+            label: pyOr(get(display, "label", ""), get(node, "displayName", "")),
+            description: pyOr(get(display, "description", ""), get(node, "description", "")),
+            icon: get(display, "icon", ""),
+            iconBackground: get(display, "iconBackground", ""),
+            iconBackgroundDark: get(display, "iconBackgroundDark", ""),
+        },
+        runtime: {
+            bpmnType: get(model, "type", ""),
+            serviceType: get(model, "serviceType", ""),
+            activityConfigurationVersion: pyOr(contextValue(context, "activityConfigurationVersion"), ""),
+            requiresConnection: hasContext(context, "connection"),
+            requiresFolderKey: hasContext(context, "folderKey"),
+            // Connector discovery metadata replaces the old empty-schema heuristic
+            // later in mergeConnectorRecord().
+            requiresConnectionForSchema: false,
+        },
+        inputSchema: { fields: inputFields },
+        outputSchema: { fields: outputFields },
+    };
+    // Some operations resolve their real field set from the VALUES of a few
+    // parent fields; record what a caller has to do about it.
+    const action = schemaAction(cmi, inputFields);
+    if (truthy(action))
+        operation.schemaAction = action;
+    const tableKey = curatedKey(get(config, "connectorKey", ""), get(config, "objectName", ""));
+    const dispatchStyle = (ctx.dispatchStyles ?? CURATED_DISPATCH_STYLE).get(tableKey);
+    if (truthy(dispatchStyle))
+        operation.dispatchStyle = dispatchStyle;
+    const paramGrammars = (ctx.paramGrammars ?? CURATED_PARAM_GRAMMARS).get(tableKey);
+    if (truthy(paramGrammars))
+        operation.paramGrammars = paramGrammars;
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// Connector records (`is connectors metadata`)
+// ---------------------------------------------------------------------------
+/** Accept the boolean JSON contract and older Yes/No cache rows. */
+export function asBool(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return ["true", "yes", "1"].includes(pyStrip(value).toLowerCase());
+    return false;
+}
+/** Read the connector tier across CLI response casing variants. */
+export function connectorTier(record) {
+    if (!isRecord(record))
+        return null;
+    let value = get(record, "Tier");
+    if (value === null)
+        value = get(record, "tier");
+    return value !== null ? pyStrip(pyStr(value)) : null;
+}
+/** Normalize current and legacy connector tier spellings to `tier1`/`tier2`. */
+export function normalizedConnectorTier(record) {
+    const value = connectorTier(record);
+    if (value === null)
+        return null;
+    const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+    if (["1", "t1", "tier1"].includes(normalized))
+        return "tier1";
+    if (["2", "t2", "tier2"].includes(normalized))
+        return "tier2";
+    return null;
+}
+/**
+ * Keep the node types whose connector metadata declares `tier` — actions and
+ * connector events both, per `scopedConnectorKey`. Returns the kept node types
+ * and the connector keys that matched.
+ */
+export function filterNodeTypesByTier(nodeTypes, connectorRecords, tier) {
+    if (tier !== "tier1" && tier !== "tier2")
+        throw new Error(`unsupported connector tier: ${tier}`);
+    const matching = new Set();
+    for (const [key, record] of connectorRecords)
+        if (normalizedConnectorTier(record) === tier)
+            matching.add(key);
+    const kept = nodeTypes.filter((nt) => {
+        const key = scopedConnectorKey(nt);
+        return key !== null && matching.has(key);
+    });
+    return [kept, matching];
+}
+/** `merge_connector_record`: stamp connector discovery metadata and its derived flag. */
+export function mergeConnectorRecord(entry, record) {
+    if (!truthy(record))
+        return entry;
+    const connector = entry.connector;
+    const name = get(record, "Name");
+    if (truthy(name))
+        connector.name = name;
+    const tier = connectorTier(record);
+    if (tier !== null)
+        connector.tier = tier;
+    const discovery = {
+        type: pyOr(get(record, "DiscoveryType"), ""),
+        hasObjectDiscovery: asBool(get(record, "HasObjectDiscovery")),
+        hasFieldDiscovery: asBool(get(record, "HasFieldDiscovery")),
+        hasCustomObjectDiscovery: asBool(get(record, "HasCustomObjectDiscovery")),
+        hasCustomFieldDiscovery: asBool(get(record, "HasCustomFieldDiscovery")),
+    };
+    connector.discovery = discovery;
+    entry.runtime.requiresConnectionForSchema = Object.entries(discovery).some(([key, value]) => key !== "type" && truthy(value));
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// Node types
+// ---------------------------------------------------------------------------
+const CONNECTOR_PREFIX = "uipath.connector.";
+const EVENT_PREFIX = "uipath.connector.event.";
+const TRIGGER_PREFIX = "uipath.connector.trigger.";
+/**
+ * The connector key for an ACTION node type, `uipath.connector.<key>.<op>`, or
+ * `null`. The event forms carry an extra segment and are answered by
+ * `eventConnectorKey` instead.
+ */
+export function actionConnectorKey(nodeType) {
+    if (!nodeType.startsWith(CONNECTOR_PREFIX))
+        return null;
+    const remainder = nodeType.slice(CONNECTOR_PREFIX.length);
+    if (remainder.startsWith("trigger.") || remainder.startsWith("event."))
+        return null;
+    const [connectorKey, separator] = partition(remainder, ".");
+    return separator && connectorKey ? connectorKey : null;
+}
+/**
+ * The connector key for a WAIT-form event node type,
+ * `uipath.connector.event.<key>.<event>`, or `null`. Only the wait form is
+ * generated: `registry get` refuses the start form without a connection, and
+ * the SDK derives the start form from its wait sibling.
+ */
+export function eventConnectorKey(nodeType) {
+    if (!nodeType.startsWith(EVENT_PREFIX))
+        return null;
+    const [connectorKey, separator] = partition(nodeType.slice(EVENT_PREFIX.length), ".");
+    return separator && connectorKey ? connectorKey : null;
+}
+/** The connector a node type belongs to, for SCOPE filtering: action or wait event. */
+export function scopedConnectorKey(nodeType) {
+    return actionConnectorKey(nodeType) ?? eventConnectorKey(nodeType);
+}
+/** The connector a node type belongs to, in ANY of its three forms — trigger included. */
+export function catalogConnectorKey(nodeType) {
+    const text = pyStr(pyOr(nodeType, ""));
+    const key = scopedConnectorKey(text);
+    if (key)
+        return key;
+    if (!text.startsWith(TRIGGER_PREFIX))
+        return null;
+    const [candidate, , event] = partition(text.slice(TRIGGER_PREFIX.length), ".");
+    return candidate && event ? candidate : null;
+}
+export const FIRST_PARTY_PREFIX = "uipath-";
+export const MOCK_MARKER = "mock";
+/**
+ * Does this connector key belong in the PUBLISHED catalog? `custom-<org>-*` are
+ * one tenant's own connectors and `uipath-mock-*` are eval fixtures; neither
+ * resolves for another user.
+ */
+export function isFirstPartyConnector(key) {
+    const lowered = pyStr(pyOr(key, "")).toLowerCase();
+    return lowered.startsWith(FIRST_PARTY_PREFIX) && !lowered.includes(MOCK_MARKER);
+}
+/**
+ * `(kept node types, dropped connector keys)` for a FULL build. A node type
+ * with no connector key at all is not a connector node and is kept.
+ */
+export function selectPublishedConnectors(nodeTypes) {
+    const droppedSet = new Set();
+    for (const nt of nodeTypes) {
+        const key = catalogConnectorKey(nt);
+        if (key && !isFirstPartyConnector(key))
+            droppedSet.add(key);
+    }
+    const dropped = sortedStrings(droppedSet);
+    if (dropped.length === 0)
+        return [[...nodeTypes], []];
+    const kept = nodeTypes.filter((nt) => {
+        const key = catalogConnectorKey(nt);
+        return isFirstPartyConnector(key) || !key;
+    });
+    return [kept, dropped];
+}
+/** The action segment of a `uipath.connector.<key>.<action>` node type. */
+export function actionIdFromNodeType(nodeType) {
+    const parts = nodeType.split(".");
+    return parts.length >= 4 ? parts[parts.length - 1] : nodeType.replaceAll(".", "-");
+}
+// ---------------------------------------------------------------------------
+// Generic templates and HTTP passthroughs
+// ---------------------------------------------------------------------------
+/**
+ * HTTP escape hatches (`*-http-request`, objectName usually `httpRequest` but
+ * sometimes null) are kept as-is, not expanded — there is no object catalog to
+ * iterate.
+ */
+const HTTP_PASSTHROUGH_OBJECT_NAMES = new Set(["httpRequest", "HttpRequest", "http_request"]);
+export function isHttpPassthrough(entry) {
+    if (HTTP_PASSTHROUGH_OBJECT_NAMES.has(get(entry.operation, "objectName")))
+        return true;
+    // Some connectors leave objectName null on the http-request action; fall
+    // back to recognising the nodeType suffix.
+    return actionIdFromNodeType(entry.nodeType).endsWith("http-request");
+}
+// ---------------------------------------------------------------------------
+// IS payload key normalization
+// ---------------------------------------------------------------------------
+/** Map a PascalCase key to camelCase (first character lowered). */
+export function toLowerCamel(s) {
+    if (typeof s !== "string" || !s)
+        return s;
+    return (startsWithUpper(s) ? lowerFirst(s) : s);
+}
+/**
+ * Recursively lower-camel-case every dict key in `value`. The IS CLI started
+ * returning PascalCase keys for parameters, fields and references; the library
+ * uses camelCase, so the on-disk schema stays stable across CLI versions.
+ */
+export function normalizeFieldKeys(value) {
+    if (isRecord(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[toLowerCamel(k)] = normalizeFieldKeys(v);
+        return out;
+    }
+    if (Array.isArray(value))
+        return value.map(normalizeFieldKeys);
+    return value;
+}
+/** `_pick`: the first non-None value among `d[k]` for the given keys, else `null`. */
+export function pick(d, ...keys) {
+    if (!isRecord(d))
+        return null;
+    for (const k of keys) {
+        const v = d[k];
+        if (v !== null && v !== undefined)
+            return v;
+    }
+    return null;
+}

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

@@ -0,0 +1,45 @@
+import { type Reporter } from "../reporter.js";
+import { type UipClient } from "../uip/client.js";
+import { type BuildOptions, type CatalogScope } from "./build.js";
+export interface BuildLibraryCliOptions extends BuildOptions {
+    /** `--cache-dir`: raw `flow registry get` responses and the search result. */
+    cacheDir: string;
+    /** `--is-cache-dir`: `is resources describe/list` and `is triggers` payloads. */
+    isCacheDir: string;
+    /** `--connectors-cache-dir`: `is connectors metadata` payloads. */
+    connectorsCacheDir: string;
+    /** `--keep-temp`: leave the three cache directories behind. */
+    keepTemp: boolean;
+    /** `--concurrency`: parallel remote CLI calls. */
+    concurrency: number;
+    /**
+     * `--offline`: never run `uip`; treat an uncached call as a failed one.
+     *
+     * For replaying a build from the caches a previous run left behind, which is
+     * what the pipeline publishes when something looks wrong. See
+     * {@link OfflineUipClient} for why failing is the faithful answer.
+     */
+    offline: boolean;
+}
+/** argparse's defaults, verbatim. */
+export declare const DEFAULTS: {
+    readonly outputDir: "./library";
+    readonly cacheDir: "./.registry-cache";
+    readonly isCacheDir: "./.is-cache";
+    readonly connectorsCacheDir: "./.is-connectors-cache";
+    readonly catalogScope: CatalogScope;
+    readonly concurrency: 10;
+};
+/**
+ * The options for this argv, or a {@link UsageError} carrying argparse's
+ * wording. Both `--flag value` and `--flag=value` are accepted, as argparse
+ * accepts them; anything that is neither a known flag nor a flag's value is an
+ * unrecognized argument, because the generator takes no positionals.
+ */
+export declare function parseArgs(argv: readonly string[]): BuildLibraryCliOptions;
+/** What a test swaps in for the tenant and the terminal. */
+export interface RunDeps {
+    client?: UipClient;
+    reporter?: Reporter;
+}
+export declare function run(argv: string[], deps?: RunDeps): Promise<number>;