@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/library-build/generic-expand.js

@@ -0,0 +1,363 @@
+/**
+ * Generic-action expansion: one library entry per `(connector, object,
+ * operation)` the IS resources catalog advertises, using the matching Generic
+ * registry action as a template.
+ *
+ * A Generic registry action (`uipath.connector.<key>.insert-record`) is an
+ * untyped runtime dispatcher: the object is picked at design time. The
+ * expanded entries keep the SOURCE Generic nodeType so an emitter can produce
+ * a valid Flow node by re-stamping `operation.objectName` onto it, and land
+ * under `<connector>/generic/<object>/<op>@<ver>.json`.
+ *
+ * Connectors whose objects live on the tenant (`hasObjectDiscovery` /
+ * `hasCustomObjectDiscovery`) are NOT expanded: they ship one entry per verb,
+ * marked `objectFromDiscovery`, and the author lists objects against their own
+ * connection.
+ */
+import { sortedByKeys } from "../compat/compare.js";
+import { afterLast, pyStr, pyStrip, pyTitle } from "../compat/pystr.js";
+import { mapConcurrent } from "../concurrency.js";
+import { messageOf } from "../errors.js";
+import { isHttpPassthrough, normalizeFieldKeys, pick } from "./canonical.js";
+import { isDescribeObject, isDescribeOperation, isResourcesList } from "./context.js";
+import { deepCopy, get, item, pyIter, pyOr, truthy } from "./py.js";
+/**
+ * `_generic_templates_by_op`: bucket Generic CRUD entries by IS operation
+ * name per connector. Generic CRUD actions carry an `operation` verb
+ * (`Create`/`Delete`/`Retrieve`/`List`/`Update`/`Replace`) but no
+ * `httpMethod`; the IS catalog returns the same verbs under
+ * `AvailableOperations[].Name`.
+ */
+export function genericTemplatesByOp(genericEntries) {
+    const out = new Map();
+    for (const e of genericEntries) {
+        if (isHttpPassthrough(e))
+            continue;
+        const opName = pyStrip(pyStr(pyOr(get(item(e, "operation"), "name"), "")));
+        if (!opName)
+            continue;
+        const key = item(item(e, "connector"), "key");
+        if (!truthy(key))
+            continue;
+        let byOp = out.get(key);
+        if (!byOp) {
+            byOp = new Map();
+            out.set(key, byOp);
+        }
+        byOp.set(opName, e);
+    }
+    return out;
+}
+/**
+ * `_make_expanded_entry`: one expanded entry from a Generic template + an
+ * (object, op) pair. `obj` is a `resources list` row, `op` an element of
+ * `AvailableOperations`, `opData` the per-operation describe `Data` (may be
+ * absent — the entry is still built, with an empty schema). The template's
+ * discovery flag is copied, never inferred from field counts.
+ */
+export function makeExpandedEntry(template, obj, op, opData) {
+    const entry = deepCopy(template);
+    const templateOperation = item(template, "operation");
+    const objectName = pyOr(get(obj, "Name"), "");
+    const objectDisplay = pyOr(get(obj, "DisplayName"), objectName);
+    const opName = pyOr(pick(op, "Name", "name"), "");
+    const opMethod = pyOr(pick(op, "Method", "method"), get(templateOperation, "httpMethod", ""));
+    const opPath = pyOr(pick(op, "Path", "path"), "");
+    const opDescription = pyOr(pick(op, "Description", "description"), "");
+    const operation = item(entry, "operation");
+    operation.objectName = objectName;
+    operation.objectDisplayName = objectDisplay;
+    operation.name = opName;
+    operation.httpMethod = opMethod;
+    operation.path = opPath;
+    operation.subType = pyOr(get(obj, "SubType"), get(templateOperation, "subType", ""));
+    operation.activityType = "GenericExpanded";
+    operation.sourceNodeType = item(template, "nodeType");
+    const display = item(entry, "display");
+    display.label = pyStrip(`${pyStr(opName)} ${pyStr(objectDisplay)}`);
+    if (truthy(opDescription))
+        display.description = opDescription;
+    // Pull schema + path template from the per-operation describe payload.
+    if (truthy(opData)) {
+        const opInner = pyOr(pick(opData, "Operation", "operation"), {});
+        const opInnerPath = pick(opInner, "Path", "path");
+        if (truthy(opInnerPath))
+            operation.pathTemplate = opInnerPath;
+        const params = pyOr(pick(opData, "Parameters", "parameters"), []);
+        if (truthy(params))
+            operation.parameters = normalizeFieldKeys(params);
+        const requestFields = pyOr(pick(opData, "RequestFields", "requestFields"), []);
+        const responseFields = pyOr(pick(opData, "ResponseFields", "responseFields"), []);
+        entry.inputSchema = { fields: normalizeFieldKeys(requestFields) };
+        entry.outputSchema = { fields: normalizeFieldKeys(responseFields) };
+    }
+    else {
+        entry.inputSchema = { fields: [] };
+        entry.outputSchema = { fields: [] };
+    }
+    return entry;
+}
+/** `_unique_by_name`: first occurrence of each `Name`, in order. */
+export function uniqueByName(objects) {
+    const unique = new Map();
+    for (const obj of pyIter(pyOr(objects, []))) {
+        const objectName = get(obj, "Name");
+        if (truthy(objectName) && !unique.has(objectName))
+            unique.set(objectName, obj);
+    }
+    return unique;
+}
+/**
+ * `_list_generic_objects`: list and deduplicate the objects available to one
+ * connector. When the caller named specific objects and the catalog does not
+ * contain them, retry once with a refresh before believing it — a stale
+ * `uip is resources list` cache reports a real object as missing.
+ */
+export async function listGenericObjects(ctx, connectorKey, templatesByOp, objectNames) {
+    const operationFilter = templatesByOp.size === 1 ? [...templatesByOp.keys()][0] : null;
+    const objects = await isResourcesList(ctx, connectorKey, { operation: operationFilter });
+    let unique = uniqueByName(objects);
+    if (truthy(objectNames) && !objectNames.every((name) => unique.has(name))) {
+        const refreshed = uniqueByName(await isResourcesList(ctx, connectorKey, { operation: operationFilter, refresh: true }));
+        // Keep the cached answer when the refresh failed outright, so a network
+        // blip does not turn a working lookup into "not found".
+        if (refreshed.size > 0)
+            unique = refreshed;
+    }
+    return [...unique.values()];
+}
+/**
+ * `expand_generic_for_connector`: materialize per-(object, op) entries for one
+ * connector, sequentially — the shape `prepare` uses. `objectNames`, when
+ * given, restricts the objects described; an empty list describes none.
+ */
+export async function expandGenericForConnector(ctx, connectorKey, templatesByOp, objectNames) {
+    const objects = await listGenericObjects(ctx, connectorKey, templatesByOp, objectNames);
+    if (objects.length === 0)
+        return [];
+    // Dedupe by (object_name, op_name): some IS catalogs list the same object
+    // twice (uipath-servicenow-servicenow exposes `curated_incident_task` twice).
+    const seenPairs = new Set();
+    const out = [];
+    for (const obj of objects) {
+        const objectName = get(obj, "Name");
+        if (!truthy(objectName))
+            continue;
+        if (objectNames !== undefined && !objectNames.includes(objectName))
+            continue;
+        const objData = await isDescribeObject(ctx, connectorKey, objectName);
+        if (!truthy(objData))
+            continue;
+        const available = pyOr(pick(objData, "AvailableOperations", "availableOperations"), []);
+        for (const op of pyIter(available)) {
+            const opName = pick(op, "Name", "name");
+            if (!truthy(opName))
+                continue;
+            const pair = JSON.stringify([objectName, opName]);
+            if (seenPairs.has(pair))
+                continue;
+            seenPairs.add(pair);
+            const template = templatesByOp.get(opName);
+            if (!truthy(template))
+                continue;
+            const opData = await isDescribeOperation(ctx, connectorKey, objectName, opName);
+            out.push(makeExpandedEntry(template, obj, op, opData));
+        }
+    }
+    return out;
+}
+/**
+ * `objects_come_from_the_connection`: true when this connector's object set is
+ * only knowable per connection. Field discovery alone does NOT qualify.
+ */
+export function objectsComeFromTheConnection(entry) {
+    const discovery = pyOr(get(pyOr(get(entry, "connector"), {}), "discovery"), {});
+    return truthy(pyOr(get(discovery, "hasObjectDiscovery"), get(discovery, "hasCustomObjectDiscovery")));
+}
+/**
+ * `as_discovery_entry`: recast a Generic CRUD template as the discovery entry
+ * shipped for it — flagged, object cleared, labelled by verb ("Update Record",
+ * "List Records").
+ */
+export function asDiscoveryEntry(entry) {
+    const operation = item(entry, "operation");
+    operation.objectFromDiscovery = true;
+    operation.objectName = "";
+    const name = pyOr(get(operation, "name"), "");
+    if (truthy(name)) {
+        item(entry, "display").label = name === "List" ? "List Records" : `${pyStr(name)} Record`;
+    }
+    return entry;
+}
+/**
+ * `disambiguate_discovery_labels`: keep two discovery entries on one connector
+ * from sharing a label. Only the colliding ones are renamed, from their own
+ * node type (`search-records` → "Search Records", via `str.title()`).
+ */
+export function disambiguateDiscoveryLabels(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        if (!truthy(get(pyOr(get(entry, "operation"), {}), "objectFromDiscovery")))
+            continue;
+        const key = JSON.stringify([
+            get(pyOr(get(entry, "connector"), {}), "key"),
+            get(pyOr(get(entry, "display"), {}), "label"),
+        ]);
+        const group = groups.get(key);
+        if (group)
+            group.push(entry);
+        else
+            groups.set(key, [entry]);
+    }
+    for (const items of groups.values()) {
+        if (items.length < 2)
+            continue;
+        for (const entry of items) {
+            const slug = afterLast(pyStr(pyOr(get(entry, "nodeType"), "")), ".");
+            if (slug)
+                item(entry, "display").label = pyTitle(slug.replaceAll("-", " ").replaceAll("_", " "));
+        }
+    }
+    return entries;
+}
+/**
+ * A deterministic order for expanded entries: connector key, object name,
+ * operation name, node type — stable, so ties keep their input order.
+ *
+ * DELIBERATE FIX. The Python appended expansions as thread-pool futures
+ * completed, so the order two entries reached `write_library` in — and, when
+ * both claimed one path with equal input counts, which one survived — varied
+ * from run to run. Sorting here makes the library a function of its inputs.
+ * The index is sorted separately, so this changes no bytes when no such tie
+ * exists.
+ */
+export function sortExpandedEntries(entries) {
+    return sortedByKeys(entries, (e) => pyStr(pyOr(get(pyOr(get(e, "connector"), {}), "key"), "")), (e) => pyStr(pyOr(get(pyOr(get(e, "operation"), {}), "objectName"), "")), (e) => pyStr(pyOr(get(pyOr(get(e, "operation"), {}), "name"), "")), (e) => pyStr(pyOr(get(e, "nodeType"), "")));
+}
+/**
+ * `expand_all_generics`: expand every Generic entry into per-(object, op)
+ * entries. Returns `[curatedAndPassthrough, expanded]`: Curated entries pass
+ * through untouched; HTTP-passthrough Generic entries pass through as
+ * one-per-connector entries; CRUD Generic entries are dropped in favour of
+ * their expansions; object-dynamic ones become discovery entries.
+ *
+ * The three remote phases (list objects, describe objects, describe
+ * operations) each run under `mapConcurrent`, so `expanded` comes back in
+ * connector × object × operation order rather than completion order.
+ */
+export async function expandAllGenerics(ctx, entries) {
+    const curatedAndPassthrough = [];
+    const genericCrud = [];
+    let discoveryEntries = 0;
+    for (const e of entries) {
+        const at = get(item(e, "operation"), "activityType", "");
+        if (at === "Generic") {
+            if (isHttpPassthrough(e)) {
+                curatedAndPassthrough.push(e);
+            }
+            else if (objectsComeFromTheConnection(e)) {
+                curatedAndPassthrough.push(asDiscoveryEntry(e));
+                discoveryEntries += 1;
+            }
+            else {
+                genericCrud.push(e);
+            }
+        }
+        else {
+            // A generic connector EVENT is answered by `resolveConnectorEvents`;
+            // Curated or anything else passes through.
+            curatedAndPassthrough.push(e);
+        }
+    }
+    disambiguateDiscoveryLabels(curatedAndPassthrough);
+    const templates = genericTemplatesByOp(genericCrud);
+    ctx.reporter.info(`  ${genericCrud.length} Generic CRUD entries across ${templates.size} connectors`);
+    ctx.reporter.info(`  ${discoveryEntries} kept unexpanded: objects come from the connection`);
+    ctx.reporter.info(`  ${entries.filter((e) => isHttpPassthrough(e)).length} HTTP-passthrough entries (kept as-is)`);
+    const expanded = [];
+    if (templates.size === 0)
+        return [curatedAndPassthrough, expanded];
+    // Phase 1: the object catalog of every templated connector.
+    const templateKeys = [...templates.keys()];
+    let listed = 0;
+    let objectsSoFar = 0;
+    const listings = await mapConcurrent(templateKeys, ctx.concurrency, async (k) => {
+        let objects = [];
+        try {
+            objects = await listGenericObjects(ctx, k, templates.get(k));
+        }
+        catch (exc) {
+            ctx.reporter.warn(`  WARN: object listing failed for ${k}: ${messageOf(exc)}`);
+        }
+        listed += 1;
+        objectsSoFar += objects.length;
+        if (listed % 25 === 0 || listed === templateKeys.length) {
+            ctx.reporter.info(`  Listed objects for ${listed}/${templateKeys.length} connectors (${objectsSoFar} objects so far)`);
+        }
+        return objects;
+    });
+    const connectorObjects = [];
+    templateKeys.forEach((k, i) => {
+        for (const obj of listings[i])
+            connectorObjects.push([k, obj]);
+    });
+    // Phase 2: which operations each object offers, matched to a template.
+    let described = 0;
+    let candidatesSoFar = 0;
+    const perObject = await mapConcurrent(connectorObjects, ctx.concurrency, async ([k, obj]) => {
+        const found = [];
+        let objData;
+        try {
+            objData = await isDescribeObject(ctx, k, item(obj, "Name"));
+        }
+        catch (exc) {
+            objData = undefined;
+            ctx.reporter.warn(`  WARN: object describe failed for ${k}/${pyStr(item(obj, "Name"))}: ${messageOf(exc)}`);
+        }
+        if (truthy(objData)) {
+            const available = pyOr(pick(objData, "AvailableOperations", "availableOperations"), []);
+            const seenOpNames = new Set();
+            for (const op of pyIter(available)) {
+                const opName = pick(op, "Name", "name");
+                if (!truthy(opName) || seenOpNames.has(opName))
+                    continue;
+                seenOpNames.add(opName);
+                const template = templates.get(k).get(opName);
+                if (truthy(template))
+                    found.push([k, obj, op, template]);
+            }
+        }
+        described += 1;
+        candidatesSoFar += found.length;
+        if (described % 100 === 0 || described === connectorObjects.length) {
+            ctx.reporter.info(`  Described ${described}/${connectorObjects.length} objects (${candidatesSoFar} operations so far)`);
+        }
+        return found;
+    });
+    const operationCandidates = perObject.flat();
+    // Phase 3: the per-operation schema, and the entry.
+    let expandedCount = 0;
+    const results = await mapConcurrent(operationCandidates, ctx.concurrency, async ([k, obj, op, template]) => {
+        const objectName = item(obj, "Name");
+        const opName = pick(op, "Name", "name");
+        let opData;
+        try {
+            opData = await isDescribeOperation(ctx, k, objectName, opName);
+        }
+        catch (exc) {
+            opData = undefined;
+            ctx.reporter.warn(`  WARN: operation describe failed for ${k}/${objectName}/${opName}: ${messageOf(exc)}`);
+        }
+        const entry = makeExpandedEntry(template, obj, op, opData);
+        expandedCount += 1;
+        if (expandedCount % 100 === 0 || expandedCount === operationCandidates.length) {
+            ctx.reporter.info(`  Expanded ${expandedCount}/${operationCandidates.length} object operations`);
+        }
+        return entry;
+    });
+    expanded.push(...results);
+    const schemaDynamic = expanded.filter((e) => truthy(get(item(e, "runtime"), "requiresConnectionForSchema"))).length;
+    ctx.reporter.info(`  expanded ${expanded.length} entries from ${genericCrud.length} Generic CRUD actions`);
+    ctx.reporter.info(`  schema-dynamic among expanded: ${schemaDynamic}/${expanded.length}`);
+    return [curatedAndPassthrough, expanded];
+}

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

@@ -0,0 +1,71 @@
+import type { IndexRow, LibraryEntry, TriggerCatalogueRow } from "../model/library.js";
+import { actionIdFromNodeType } from "./canonical.js";
+import { type Dict } from "./py.js";
+export { actionIdFromNodeType };
+/** `_safe_path_segment`: sanitize a string for use as one path segment. */
+export declare function safePathSegment(s: string): string;
+/**
+ * `_input_field_count`: how much of a schema an entry carries — the tie-break
+ * when two claim one path, since whichever loses is dropped from the catalogue.
+ */
+export declare function inputFieldCount(entry: unknown): number;
+/**
+ * `_entry_relpath`: where to write `entry` relative to the library root, sans
+ * extension, `/`-separated. Expanded Generic entries land under
+ * `<connector>/generic/<object>/<op>@<ver>`; per-object EVENT variants under
+ * `<connector>/events/<object>/<action>@<ver>` (they keep the template's
+ * nodeType, so the object is what separates them).
+ */
+export declare function entryRelpath(entry: LibraryEntry): string;
+/**
+ * `_build_v1_definition`: project a registry `Data.Node` into the shape a
+ * `.flow` file expects under `definitions[]`: drop `connectorMethodInfo` and
+ * `outputResponseDefinition`, add the three fields the editor stamps on every
+ * connector definition when absent (`setdefault`: a present `null` stays).
+ */
+export declare function buildV1Definition(nodeData: unknown): Dict;
+/**
+ * The raw `Data.Node` for a node type whose registry response the build
+ * holds, or `undefined` when it holds none (Python: `v1def_source_paths.get`
+ * answered nothing). May throw; the planner reports and moves on.
+ */
+export type NodeLoader = (nodeType: string) => unknown;
+export interface LibraryPlan {
+    /** POSIX-relative path → file text, `index.json` included. */
+    files: Map<string, string>;
+    /** The index rows, sorted as written. */
+    index: IndexRow[];
+    /** `WARN:` lines, verbatim. */
+    warnings: string[];
+    /** How many entry files the plan holds — `write_library`'s return value. */
+    written: number;
+}
+export interface PlanOptions {
+    schemaVersion?: string;
+}
+/**
+ * `write_library` without the disk.
+ *
+ * Collision protocol, per relpath: an identical second entry is skipped; one
+ * with fewer-or-equal input fields is skipped with a warning; a richer one
+ * replaces the earlier (its index row is dropped, its files are overwritten).
+ * The sidecar is projected from the node the loader answers, with the entry's
+ * resolved input fields stamped in (always for an expanded Generic node,
+ * otherwise only when the entry has any) and its `eventSchema` stamped in when
+ * present. Index rows carry `objectFromDiscovery` only when set.
+ */
+export declare function planLibrary(entries: readonly LibraryEntry[], loadNode: NodeLoader, opts?: PlanOptions): LibraryPlan;
+/**
+ * Every entry file in `files` that has no index row: an empty list is the
+ * invariant `write_library` used to break (index one row longer than the
+ * directory). Sidecars and the known non-entry files are exempt.
+ */
+export declare function orphanCheck(files: ReadonlyMap<string, string>, index: readonly IndexRow[]): string[];
+/**
+ * `write_triggers_side_file`'s rows: every trigger nodeType the registry
+ * search exposed, sorted by `(connectorKey, NodeType)`.
+ */
+export declare function triggerRows(searchPayload: unknown): TriggerCatalogueRow[];
+export declare const TRIGGER_CATALOGUE_NOTE: string;
+/** The side-file's text: the envelope around the rows, `json.dump(indent=2)` + newline. */
+export declare function triggerCatalogueDocument(rows: readonly TriggerCatalogueRow[]): string;