@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

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

@@ -0,0 +1,286 @@
+/**
+ * `main()` of `generate_library_json.py`, as a function of its options and
+ * ports: search → scope → trigger side-file → fetch → extract → enrich →
+ * connector records → generic expansion → events → curated overrides → plan →
+ * write.
+ *
+ * Every remote call goes through the {@link BuildContext} built from the ports,
+ * so a build against a `--keep-temp` cache the Python left behind makes no call
+ * at all — which is how the port is proven byte-for-byte. The two `sys.exit(
+ * "<message>")` gates are thrown as {@link Refusal}s carrying the same text.
+ */
+import { dirname, join, normalize } from "node:path";
+import { sortedStrings } from "../compat/compare.js";
+import { pyStr } from "../compat/pystr.js";
+import { mapConcurrent } from "../concurrency.js";
+import { Refusal, messageOf } from "../errors.js";
+import { registrySearchConnectors } from "../uip/commands.js";
+import { applyCuratedOverrides, extractCanonical, filterNodeTypesByTier, mergeConnectorRecord, nodeOf, scopedConnectorKey, selectPublishedConnectors, } from "./canonical.js";
+import { SEARCH_RESULTS_NAME, createBuildContext, isConnectorGet, registryCacheName, registryGet, } from "./context.js";
+import { enrichAll } from "./enrich.js";
+import { resolveConnectorEvents } from "./events.js";
+import { expandAllGenerics, sortExpandedEntries } from "./generic-expand.js";
+import { orphanCheck, planLibrary, triggerRows } from "./plan.js";
+import { get, item, pyIter, pyOr, pyReprStrList, truthy } from "./py.js";
+import { writePlan, writeTriggerSideFile } from "./write.js";
+/** The Python's default: beside the output directory. */
+export function defaultTriggersOutput(outputDir) {
+    return join(dirname(normalize(outputDir)) || ".", "registry-triggers.json");
+}
+/** `{c.strip() for c in text.split(",") if c.strip()}`, in first-seen order. */
+export function parseConnectorsFlag(text) {
+    const seen = new Set();
+    for (const part of text.split(",")) {
+        const key = part.trim();
+        if (key)
+            seen.add(key);
+    }
+    return [...seen];
+}
+/** `", ".join(missing[:10])` plus ` (+N more)` past ten. */
+function missingPreview(missing) {
+    const preview = missing.slice(0, 10).join(", ");
+    const remainder = missing.length > 10 ? ` (+${missing.length - 10} more)` : "";
+    return `${preview}${remainder}`;
+}
+/**
+ * `registry_search`: the connector node types the registry lists, from the
+ * cached raw stdout of `flow registry search --filter tags:in=connector` —
+ * fetched once when the cache has no `_search_results.json`.
+ */
+export async function registrySearch(ctx) {
+    if (!ctx.caches.registry.has(SEARCH_RESULTS_NAME)) {
+        ctx.reporter.info("Running registry search...");
+        const result = await ctx.client.run(registrySearchConnectors(), ctx.timeoutMs === undefined ? undefined : { timeoutMs: ctx.timeoutMs });
+        if (result.code !== 0)
+            throw new Refusal(`Registry search failed: ${result.stderr}`, "REGISTRY_SEARCH_FAILED");
+        ctx.caches.registry.write(SEARCH_RESULTS_NAME, undefined, result.stdout);
+    }
+    const data = ctx.caches.registry.read(SEARCH_RESULTS_NAME);
+    const out = [];
+    for (const entry of pyIter(get(data, "Data", []))) {
+        const nodeType = item(entry, "NodeType");
+        if (typeof nodeType === "string" && nodeType.startsWith("uipath.connector."))
+            out.push(nodeType);
+    }
+    return out;
+}
+/**
+ * `fetch_all`: the registry response of every node type, from the cache or
+ * fetched in parallel. `nodeType → cache name`; a node type whose fetch failed
+ * is absent (and was reported by `registryGet`).
+ */
+export async function fetchAll(ctx, nodeTypes) {
+    const results = new Map();
+    const toFetch = [];
+    let alreadyCached = 0;
+    for (const nt of nodeTypes) {
+        const name = registryCacheName(nt);
+        if (ctx.caches.registry.has(name)) {
+            results.set(nt, name);
+            alreadyCached += 1;
+        }
+        else {
+            toFetch.push(nt);
+        }
+    }
+    if (alreadyCached)
+        ctx.reporter.info(`  ${alreadyCached} connectors already cached, ${toFetch.length} to fetch`);
+    if (toFetch.length > 0) {
+        let done = 0;
+        const names = await mapConcurrent(toFetch, ctx.concurrency, async (nt) => {
+            const name = await registryGet(ctx, nt);
+            done += 1;
+            if (done % 50 === 0 || done === toFetch.length)
+                ctx.reporter.info(`  Fetched ${done}/${toFetch.length}`);
+            return name;
+        });
+        toFetch.forEach((nt, i) => {
+            const name = names[i];
+            if (name)
+                results.set(nt, name);
+        });
+    }
+    return results;
+}
+/**
+ * `fetch_connector_records_for_keys`: one `is connectors metadata` per key,
+ * sorted and deduplicated; `key → record`, `null` where the lookup failed.
+ */
+export async function fetchConnectorRecordsForKeys(ctx, keys) {
+    const sorted = sortedStrings(new Set([...keys].filter((key) => truthy(key))));
+    ctx.reporter.info(`  Looking up ${sorted.length} connector records...`);
+    let done = 0;
+    const records = await mapConcurrent(sorted, ctx.concurrency, async (key) => {
+        let record;
+        try {
+            record = await isConnectorGet(ctx, key);
+        }
+        catch {
+            record = undefined;
+        }
+        done += 1;
+        if (done % 50 === 0 || done === sorted.length)
+            ctx.reporter.info(`  Fetched ${done}/${sorted.length} connector records`);
+        return record ?? null;
+    });
+    return new Map(sorted.map((key, i) => [key, records[i]]));
+}
+/** `fetch_connector_records`: one record per unique connector key in `entries`. */
+export function fetchConnectorRecords(ctx, entries) {
+    const keys = entries.map((e) => item(item(e, "connector"), "key")).filter((key) => truthy(key));
+    return fetchConnectorRecordsForKeys(ctx, keys);
+}
+/** The whole generator, `main()` minus argument parsing and cache cleanup. */
+export async function buildLibrary(options, ports) {
+    const ctx = createBuildContext(ports);
+    const info = (line) => ctx.reporter.info(line);
+    const warn = (line) => ctx.reporter.warn(line);
+    const concurrency = ctx.concurrency;
+    let nodeTypes = await registrySearch(ctx);
+    info(`Found ${nodeTypes.length} connector node types`);
+    let connectorRecords;
+    if (options.connectors !== undefined) {
+        // Curated subset: the requested connectors' action AND connector-event
+        // node types. The START form stays out — `registry get` refuses it
+        // without a --connection-id.
+        const allow = new Set(options.connectors);
+        const before = nodeTypes.length;
+        nodeTypes = nodeTypes.filter((nt) => {
+            const key = scopedConnectorKey(nt);
+            return key !== null && allow.has(key);
+        });
+        const matched = new Set([...allow].filter((key) => nodeTypes.some((nt) => `${nt}.`.includes(`.${key}.`))));
+        info(`Curated subset: kept ${nodeTypes.length}/${before} node types for ${matched.size}/${allow.size} connectors ` +
+            pyReprStrList(sortedStrings(matched)));
+        const missing = [...allow].filter((key) => !matched.has(key));
+        if (missing.length > 0) {
+            warn(`  WARN: no registry nodes matched these connector keys: ${pyReprStrList(sortedStrings(missing))}`);
+        }
+    }
+    else {
+        // A full build ships the PUBLISHED catalog, not everything the build
+        // tenant happens to see.
+        const before = nodeTypes.length;
+        const [kept, dropped] = selectPublishedConnectors(nodeTypes);
+        nodeTypes = kept;
+        if (dropped.length > 0) {
+            info(`Published catalog: kept ${nodeTypes.length}/${before} node types, dropped ${dropped.length} ` +
+                `tenant-local connector(s) ${pyReprStrList(dropped)}`);
+        }
+    }
+    const catalogScope = options.catalogScope ?? "all";
+    if (catalogScope === "tier1" || catalogScope === "tier2") {
+        const tierNumber = catalogScope.slice(-1);
+        const scopeKeys = new Set(nodeTypes.map((nt) => scopedConnectorKey(nt)).filter((key) => Boolean(key)));
+        info(`Resolving Tier ${tierNumber} scope from metadata for ${scopeKeys.size} connector keys...`);
+        connectorRecords = await fetchConnectorRecordsForKeys(ctx, scopeKeys);
+        const missingMetadata = sortedStrings([...connectorRecords].filter(([, record]) => record === null).map(([key]) => key));
+        if (missingMetadata.length > 0) {
+            throw new Refusal(`Tier ${tierNumber} filtering requires connector metadata for every candidate connector, but lookup ` +
+                `failed for: ${missingPreview(missingMetadata)}`, "TIER_METADATA_MISSING");
+        }
+        const before = nodeTypes.length;
+        const [kept, matchingKeys] = filterNodeTypesByTier(nodeTypes, connectorRecords, catalogScope);
+        nodeTypes = kept;
+        if (matchingKeys.size === 0) {
+            throw new Refusal(`Tier ${tierNumber} filtering selected no connectors. Expected the Tier field from ` +
+                `\`uip is connectors metadata\` to contain '${tierNumber}'.`, "TIER_EMPTY");
+        }
+        info(`Tier ${tierNumber} scope: kept ${nodeTypes.length}/${before} action node types for ${matchingKeys.size} connectors`);
+    }
+    // Side-file: every trigger nodeType the registry search exposed.
+    const triggersOutput = options.triggersOutput || defaultTriggersOutput(options.outputDir);
+    info(`Writing trigger side-file → ${triggersOutput}`);
+    let triggerCount = 0;
+    if (!ctx.caches.registry.has(SEARCH_RESULTS_NAME)) {
+        warn(`  WARN: search cache missing at ${SEARCH_RESULTS_NAME}; can't write triggers side-file`);
+    }
+    else {
+        const rows = triggerRows(ctx.caches.registry.read(SEARCH_RESULTS_NAME));
+        triggerCount = writeTriggerSideFile(rows, triggersOutput);
+        info(`  wrote ${triggerCount} triggers to ${triggersOutput}`);
+    }
+    info(`Fetching connector details (concurrency=${concurrency})...`);
+    const cacheFiles = await fetchAll(ctx, nodeTypes);
+    info(`Successfully fetched ${cacheFiles.size} connectors`);
+    info("Extracting connector entries (Curated + Generic)...");
+    let entries = [];
+    const v1defSources = new Map();
+    const byActivity = new Map();
+    for (const nt of sortedStrings(cacheFiles.keys())) {
+        const name = cacheFiles.get(nt);
+        try {
+            const entry = extractCanonical(nodeOf(ctx.caches.registry.read(name)));
+            if (truthy(entry)) {
+                entries.push(entry);
+                v1defSources.set(item(entry, "nodeType"), name);
+                // `entry["operation"].get("activityType", "") or "(empty)"`, printed
+                // with `str()`: a `True` stays `True`, not `true`, in the count line.
+                const at = pyStr(pyOr(get(item(entry, "operation"), "activityType", ""), "(empty)"));
+                byActivity.set(at, (byActivity.get(at) ?? 0) + 1);
+            }
+        }
+        catch (e) {
+            warn(`  WARN: error processing ${nt}: ${messageOf(e)}`);
+        }
+    }
+    info(`Found ${entries.length} entries total: ` +
+        sortedStrings(byActivity.keys())
+            .map((k) => `${k}=${byActivity.get(k)}`)
+            .join(", "));
+    if (!options.skipEnrichment) {
+        info(`Enriching via \`is resources describe\` (concurrency=${concurrency})...`);
+        entries = await enrichAll(ctx, entries);
+    }
+    if (!options.skipConnectorEnrichment) {
+        info(`Enriching via \`is connectors metadata\` (concurrency=${concurrency})...`);
+        if (connectorRecords === undefined)
+            connectorRecords = await fetchConnectorRecords(ctx, entries);
+        const missingMetadata = sortedStrings([...connectorRecords].filter(([, record]) => record === null).map(([key]) => key));
+        if (missingMetadata.length > 0) {
+            throw new Refusal("Connector metadata is required to classify schema discovery, but `uip is connectors metadata` " +
+                `failed for: ${missingPreview(missingMetadata)}. Upgrade the UiPath CLI or rerun after checking authentication.`, "CONNECTOR_METADATA_MISSING");
+        }
+        let named = 0;
+        for (const e of entries) {
+            const key = item(item(e, "connector"), "key");
+            mergeConnectorRecord(e, connectorRecords.get(key) ?? null);
+            if (truthy(get(item(e, "connector"), "name")))
+                named += 1;
+        }
+        const schemaDynamic = entries.filter((e) => truthy(get(item(e, "runtime"), "requiresConnectionForSchema"))).length;
+        info(`  Named ${named}/${entries.length} entries from connector records`);
+        info(`  schema-dynamic from connector capabilities: ${schemaDynamic}/${entries.length}`);
+    }
+    if (!options.skipGenericExpansion) {
+        info(`Expanding Generic CRUD by (object, operation) (concurrency=${concurrency})...`);
+        const [kept, expanded] = await expandAllGenerics(ctx, entries);
+        // DELIBERATE FIX: the Python appended expansions in thread-completion
+        // order; sorted, a build is a function of its inputs (see
+        // `sortExpandedEntries`).
+        entries = [...kept, ...sortExpandedEntries(expanded)];
+    }
+    info(`Resolving connector events (concurrency=${concurrency})...`);
+    const [described, expandedEvents] = await resolveConnectorEvents(ctx, entries);
+    entries = [...described, ...sortExpandedEntries(expandedEvents)];
+    // Curated op remaps — applied last so they override anything enrichment or
+    // expansion produced.
+    const overridden = applyCuratedOverrides(entries);
+    if (overridden)
+        info(`  Applied ${overridden} curated op override(s)`);
+    info("Writing canonical library...");
+    const loadNode = (nodeType) => {
+        const name = v1defSources.get(nodeType);
+        return name ? nodeOf(ctx.caches.registry.read(name)) : undefined;
+    };
+    const plan = planLibrary(entries, loadNode);
+    for (const line of plan.warnings)
+        warn(line);
+    const orphans = orphanCheck(plan.files, plan.index);
+    if (orphans.length > 0)
+        warn(`  WARN: ${orphans.length} entry file(s) have no index row: ${orphans.slice(0, 5).join(", ")}`);
+    const written = writePlan(plan, options.outputDir);
+    info(`Wrote ${written} library entries + index.json`);
+    return { nodeTypes, entries, plan, written, triggersOutput, triggerCount };
+}

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

@@ -0,0 +1,119 @@
+import type { LibraryEntry } from "../model/library.js";
+import { type Dict } from "./py.js";
+export declare const SCHEMA_VERSION = "1";
+/**
+ * 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 declare const CURATED_DISPATCH_STYLE: ReadonlyMap<string, string>;
+/**
+ * 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 declare const CURATED_PARAM_GRAMMARS: ReadonlyMap<string, Dict>;
+/**
+ * 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 declare const CURATED_OP_OVERRIDE: ReadonlyMap<string, Record<string, Dict>>;
+/** The curated tables `extractCanonical` consults; tests can hand in their own. */
+export interface CanonicalContext {
+    schemaVersion?: string;
+    dispatchStyles?: ReadonlyMap<string, string>;
+    paramGrammars?: ReadonlyMap<string, Dict>;
+}
+/**
+ * `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 declare function applyCuratedOverrides(entries: LibraryEntry[], overrides?: ReadonlyMap<string, Record<string, Dict>>): number;
+/** The `value` of the context entry named `name`, or `null`. */
+export declare function contextValue(context: unknown, name: string): unknown;
+export declare function hasContext(context: unknown, name: string): boolean;
+/**
+ * `_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 declare function parameterMetadata(connectorMethodInfo: unknown): Map<string, Dict>;
+/** `Data.Node` from a parsed `flow registry get` response, or `null`. */
+export declare function nodeOf(payload: unknown): unknown;
+/**
+ * `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 declare function extractCanonical(nodeData: unknown, ctx?: CanonicalContext): LibraryEntry | undefined;
+/** Accept the boolean JSON contract and older Yes/No cache rows. */
+export declare function asBool(value: unknown): boolean;
+/** Read the connector tier across CLI response casing variants. */
+export declare function connectorTier(record: unknown): string | null;
+/** Normalize current and legacy connector tier spellings to `tier1`/`tier2`. */
+export declare function normalizedConnectorTier(record: unknown): "tier1" | "tier2" | 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 declare function filterNodeTypesByTier(nodeTypes: readonly string[], connectorRecords: ReadonlyMap<string, unknown>, tier: string): [string[], Set<string>];
+/** `merge_connector_record`: stamp connector discovery metadata and its derived flag. */
+export declare function mergeConnectorRecord(entry: LibraryEntry, record: unknown): LibraryEntry;
+/**
+ * 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 declare function actionConnectorKey(nodeType: string): string | 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 declare function eventConnectorKey(nodeType: string): string | null;
+/** The connector a node type belongs to, for SCOPE filtering: action or wait event. */
+export declare function scopedConnectorKey(nodeType: string): string | null;
+/** The connector a node type belongs to, in ANY of its three forms — trigger included. */
+export declare function catalogConnectorKey(nodeType: unknown): string | null;
+export declare const FIRST_PARTY_PREFIX = "uipath-";
+export declare 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 declare function isFirstPartyConnector(key: unknown): boolean;
+/**
+ * `(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 declare function selectPublishedConnectors(nodeTypes: readonly string[]): [string[], string[]];
+/** The action segment of a `uipath.connector.<key>.<action>` node type. */
+export declare function actionIdFromNodeType(nodeType: string): string;
+export declare function isHttpPassthrough(entry: LibraryEntry): boolean;
+/** Map a PascalCase key to camelCase (first character lowered). */
+export declare function toLowerCamel<T>(s: T): T;
+/**
+ * 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 declare function normalizeFieldKeys(value: unknown): unknown;
+/** `_pick`: the first non-None value among `d[k]` for the given keys, else `null`. */
+export declare function pick(d: unknown, ...keys: string[]): unknown;