@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/uip/commands.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `uip` invocations the registry makes, as argv.
+ *
+ * Argument ORDER is part of each command's identity: recordings and the
+ * response cache are keyed by it, so a reordered flag is a cache miss and a
+ * fresh tenant call. The harness that compared this order against what the
+ * Python generators issued went with the Python; these builders still
+ * reproduce that order exactly, including the one odd case — `connections
+ * list` inserts its flags at a fixed position rather than appending them —
+ * because the committed fixtures under `tests/fixtures/library-build/cache`
+ * are keyed by the names the Python's order produced.
+ */
+export declare const UIP = "uip";
+/** `--connection-id <id>` when a connection is in scope, else nothing. */
+export declare function connectionArgs(connectionId?: string): string[];
+/** `-f name=value` per parent field, in the order given. */
+export declare function fieldArgs(parentFields: ReadonlyMap<string, string> | Readonly<Record<string, string>> | undefined): string[];
+export declare function registrySearchConnectors(): string[];
+export declare function registrySearch(query: string): string[];
+export declare function registryGet(nodeType: string, connectionId?: string): string[];
+export declare function isConnectorsMetadata(connectorKey: string): string[];
+export declare function isResourcesDescribeOperation(connectorKey: string, objectName: string, operation: string, connectionId?: string, parentFields?: ReadonlyMap<string, string> | Readonly<Record<string, string>>): string[];
+export declare function isResourcesDescribeObject(connectorKey: string, objectName: string, connectionId?: string): string[];
+export declare function isResourcesList(connectorKey: string, options?: {
+    operation?: string;
+    refresh?: boolean;
+    connectionId?: string;
+}): string[];
+export declare function isResourcesRunList(connectorKey: string, collection: string, connectionId: string, query?: string): string[];
+export declare function isTriggersObjects(connectorKey: string, operation: string, connectionId?: string): string[];
+export declare function isTriggersDescribe(connectorKey: string, operation: string, objectName: string, connectionId?: string): string[];
+/**
+ * `uip is connections list --output json`, with `--all-folders` and `--byoa`
+ * inserted at position 4 — `--byoa` last, so it lands first — exactly as the
+ * Python did.
+ */
+export declare function isConnectionsList(options?: {
+    allFolders?: boolean;
+    byoa?: boolean;
+}): string[];

package/dist/registry/uip/commands.js

@@ -0,0 +1,80 @@
+/**
+ * The `uip` invocations the registry makes, as argv.
+ *
+ * Argument ORDER is part of each command's identity: recordings and the
+ * response cache are keyed by it, so a reordered flag is a cache miss and a
+ * fresh tenant call. The harness that compared this order against what the
+ * Python generators issued went with the Python; these builders still
+ * reproduce that order exactly, including the one odd case — `connections
+ * list` inserts its flags at a fixed position rather than appending them —
+ * because the committed fixtures under `tests/fixtures/library-build/cache`
+ * are keyed by the names the Python's order produced.
+ */
+export const UIP = "uip";
+/** `--connection-id <id>` when a connection is in scope, else nothing. */
+export function connectionArgs(connectionId) {
+    return connectionId ? ["--connection-id", connectionId] : [];
+}
+/** `-f name=value` per parent field, in the order given. */
+export function fieldArgs(parentFields) {
+    if (!parentFields)
+        return [];
+    const entries = parentFields instanceof Map ? [...parentFields.entries()] : Object.entries(parentFields);
+    return entries.flatMap(([name, value]) => ["-f", `${name}=${value}`]);
+}
+export function registrySearchConnectors() {
+    return [UIP, "maestro", "flow", "registry", "search", "--filter", "tags:in=connector", "--output", "json"];
+}
+export function registrySearch(query) {
+    return [UIP, "maestro", "flow", "registry", "search", query, "--output", "json"];
+}
+export function registryGet(nodeType, connectionId) {
+    return [UIP, "maestro", "flow", "registry", "get", nodeType, "--output", "json", ...connectionArgs(connectionId)];
+}
+export function isConnectorsMetadata(connectorKey) {
+    return [UIP, "is", "connectors", "metadata", connectorKey, "--output", "json"];
+}
+export function isResourcesDescribeOperation(connectorKey, objectName, operation, connectionId, parentFields) {
+    return [
+        UIP, "is", "resources", "describe", connectorKey, objectName, "--operation", operation, "--output", "json",
+        ...connectionArgs(connectionId),
+        ...fieldArgs(parentFields),
+    ];
+}
+export function isResourcesDescribeObject(connectorKey, objectName, connectionId) {
+    return [UIP, "is", "resources", "describe", connectorKey, objectName, "--output", "json", ...connectionArgs(connectionId)];
+}
+export function isResourcesList(connectorKey, options = {}) {
+    return [
+        UIP, "is", "resources", "list", connectorKey,
+        ...(options.operation ? ["--operation", options.operation] : []),
+        ...(options.refresh ? ["--refresh"] : []),
+        "--output", "json",
+        ...connectionArgs(options.connectionId),
+    ];
+}
+export function isResourcesRunList(connectorKey, collection, connectionId, query) {
+    return [
+        UIP, "is", "resources", "run", "list", connectorKey, collection, "--connection-id", connectionId, "--output", "json",
+        ...(query ? ["--query", query] : []),
+    ];
+}
+export function isTriggersObjects(connectorKey, operation, connectionId) {
+    return [UIP, "is", "triggers", "objects", connectorKey, operation, ...connectionArgs(connectionId), "--output", "json"];
+}
+export function isTriggersDescribe(connectorKey, operation, objectName, connectionId) {
+    return [UIP, "is", "triggers", "describe", connectorKey, operation, objectName, ...connectionArgs(connectionId), "--output", "json"];
+}
+/**
+ * `uip is connections list --output json`, with `--all-folders` and `--byoa`
+ * inserted at position 4 — `--byoa` last, so it lands first — exactly as the
+ * Python did.
+ */
+export function isConnectionsList(options = {}) {
+    const argv = [UIP, "is", "connections", "list", "--output", "json"];
+    if (options.allFolders)
+        argv.splice(4, 0, "--all-folders");
+    if (options.byoa)
+        argv.splice(4, 0, "--byoa");
+    return argv;
+}

package/dist/registry/uip/envelope.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading what `uip … --output json` prints.
+ *
+ * The CLI is chatty: an update banner, a tool-version warning and a
+ * `ManifestClient` diagnostic can precede the JSON document, and the document
+ * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
+ * varied between tools. Three Python callers each had their own loop for
+ * finding the document; this is the one loop, and the one accessor.
+ */
+/** The shape every `uip` JSON response shares, read case-insensitively. */
+export interface UipEnvelope {
+    Result?: unknown;
+    Data?: unknown;
+    Message?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * The first JSON document in `text`, or `undefined`.
+ *
+ * Tries the whole text first (the common case), then every line that begins
+ * with `{` or `[`, parsing from that line to the end. The banner the CLI
+ * prints ahead of its payload never starts a line with a bracket.
+ */
+export declare function findJsonDocument(text: string): unknown;
+/** `mapping[name]` for the first `name` that matches a key case-insensitively. */
+export declare function getCI(mapping: unknown, ...names: string[]): unknown;
+/** The envelope in `text`, or `undefined` when no object with a `Result` is there. */
+export declare function parseEnvelope(text: string): UipEnvelope | undefined;
+/** True when the envelope says the call worked. */
+export declare function isSuccess(envelope: UipEnvelope | undefined): boolean;
+/**
+ * `Data` as a list of records, accepting both the bare-array and the
+ * `{ items: [...] }` spellings the Integration Service tool has used.
+ */
+export declare function dataItems(envelope: UipEnvelope | undefined): unknown[];
+/** The last `limit` characters of a stream, for a message. */
+export declare function tail(text: string, limit?: number): string;

package/dist/registry/uip/envelope.js

@@ -0,0 +1,84 @@
+/**
+ * Reading what `uip … --output json` prints.
+ *
+ * The CLI is chatty: an update banner, a tool-version warning and a
+ * `ManifestClient` diagnostic can precede the JSON document, and the document
+ * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
+ * varied between tools. Three Python callers each had their own loop for
+ * finding the document; this is the one loop, and the one accessor.
+ */
+/**
+ * The first JSON document in `text`, or `undefined`.
+ *
+ * Tries the whole text first (the common case), then every line that begins
+ * with `{` or `[`, parsing from that line to the end. The banner the CLI
+ * prints ahead of its payload never starts a line with a bracket.
+ */
+export function findJsonDocument(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // fall through to the line scan
+    }
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const head = lines[i].trimStart();
+        if (!head.startsWith("{") && !head.startsWith("["))
+            continue;
+        try {
+            return JSON.parse(lines.slice(i).join("\n"));
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/** `mapping[name]` for the first `name` that matches a key case-insensitively. */
+export function getCI(mapping, ...names) {
+    if (typeof mapping !== "object" || mapping === null || Array.isArray(mapping))
+        return undefined;
+    const keys = new Map();
+    for (const key of Object.keys(mapping))
+        keys.set(key.toLowerCase(), key);
+    for (const name of names) {
+        const key = keys.get(name.toLowerCase());
+        if (key !== undefined)
+            return mapping[key];
+    }
+    return undefined;
+}
+/** The envelope in `text`, or `undefined` when no object with a `Result` is there. */
+export function parseEnvelope(text) {
+    const document = findJsonDocument(text);
+    if (typeof document !== "object" || document === null || Array.isArray(document))
+        return undefined;
+    return document;
+}
+/** True when the envelope says the call worked. */
+export function isSuccess(envelope) {
+    return getCI(envelope, "Result") === "Success";
+}
+/**
+ * `Data` as a list of records, accepting both the bare-array and the
+ * `{ items: [...] }` spellings the Integration Service tool has used.
+ */
+export function dataItems(envelope) {
+    const data = getCI(envelope, "Data");
+    if (Array.isArray(data))
+        return data;
+    if (typeof data === "object" && data !== null) {
+        const items = getCI(data, "items");
+        if (Array.isArray(items))
+            return items;
+    }
+    return [];
+}
+/** The last `limit` characters of a stream, for a message. */
+export function tail(text, limit = 300) {
+    return text.length <= limit ? text : text.slice(text.length - limit);
+}

package/dist/registry/uip/response-cache.d.ts

@@ -0,0 +1,28 @@
+export interface ResponseCache {
+    /** The parsed payload, or `undefined` when nothing is cached under `name`. */
+    read(name: string): unknown;
+    /** Store a payload; `raw` stores the text verbatim instead of re-serializing. */
+    write(name: string, payload: unknown, raw?: string): void;
+    has(name: string): boolean;
+}
+/** The marker the Python left for a call that answered `Result: Failure`. */
+export declare const CACHED_FAILURE = "_cached_failure";
+/** True for a payload the cache stored to remember a failure. */
+export declare function isCachedFailure(payload: unknown): boolean;
+/** `_safe_filename(*parts)`: `"__".join(parts)` with anything unusual squashed to `_`. */
+export declare function safeCacheName(...parts: string[]): string;
+export declare class FsResponseCache implements ResponseCache {
+    readonly directory: string;
+    constructor(directory: string);
+    private path;
+    has(name: string): boolean;
+    read(name: string): unknown;
+    write(name: string, payload: unknown, raw?: string): void;
+}
+/** An in-memory cache for tests and for callers that want no disk. */
+export declare class MemoryResponseCache implements ResponseCache {
+    private readonly entries;
+    has(name: string): boolean;
+    read(name: string): unknown;
+    write(name: string, payload: unknown, raw?: string): void;
+}

package/dist/registry/uip/response-cache.js

@@ -0,0 +1,57 @@
+/**
+ * A cache of `uip` payloads on disk, keyed by a name the caller derives from the
+ * call. The library builder used one per command family so a re-run after a
+ * failure re-issues only the calls that never answered; `prepare` uses the same
+ * shape for its one-run temp directory.
+ *
+ * File names follow the Python generator's exactly, so a `--keep-temp` cache
+ * written by the Python and read by this code compares the pure transform and
+ * nothing else.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The marker the Python left for a call that answered `Result: Failure`. */
+export const CACHED_FAILURE = "_cached_failure";
+/** True for a payload the cache stored to remember a failure. */
+export function isCachedFailure(payload) {
+    return typeof payload === "object" && payload !== null && payload[CACHED_FAILURE] === true;
+}
+/** `_safe_filename(*parts)`: `"__".join(parts)` with anything unusual squashed to `_`. */
+export function safeCacheName(...parts) {
+    return parts.join("__").replace(/[^a-zA-Z0-9_.@-]+/g, "_");
+}
+export class FsResponseCache {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+        mkdirSync(directory, { recursive: true });
+    }
+    path(name) {
+        return join(this.directory, name);
+    }
+    has(name) {
+        return existsSync(this.path(name));
+    }
+    read(name) {
+        const path = this.path(name);
+        if (!existsSync(path))
+            return undefined;
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    write(name, payload, raw) {
+        writeFileSync(this.path(name), raw ?? JSON.stringify(payload));
+    }
+}
+/** An in-memory cache for tests and for callers that want no disk. */
+export class MemoryResponseCache {
+    entries = new Map();
+    has(name) {
+        return this.entries.has(name);
+    }
+    read(name) {
+        return this.entries.get(name);
+    }
+    write(name, payload, raw) {
+        this.entries.set(name, raw !== undefined ? JSON.parse(raw) : payload);
+    }
+}

package/lib/README.md

@@ -39,8 +39,9 @@ And the two materialized trees:
   two can't drift.
 
 The markdown cites the TypeScript by name (`connector(SendMessageToUser, …)`),
-and those names exist in neither tree — both generators derive them through
-`integrations/scripts/_naming.py`. `unpack-library.sh` cross-checks every cited
+and those names exist in neither tree — both generators derive them through the
+one `symbolIndex` in `src/registry/naming.ts`. `registry materialize
+--check-symbols` (which `unpack-library.mjs` passes) cross-checks every cited
 symbol against the emitted modules and fails if one is missing, because a wrong
 symbol is an import that throws, printed by documentation.
 
@@ -63,8 +64,8 @@ lib/
 ├── library-md/            discovery docs the agent reads — GITIGNORED, derived from library-json/
 │   └── <connector>/<action>@<ver>.md     (+ a root index.json and SKILL.md)
 └── scripts/
-    ├── unpack-library.sh        integrations/artifacts/library-json.zip → library-json/, then derive library-md/
-    └── generate-library-json.sh (re)generate library-json/ from the live registry (needs a logged-in uip)
+    ├── unpack-library.mjs       integrations/artifacts/library-json.zip → library-json/, then derive library-md/ + descriptors
+    └── generate-library-json.mjs (re)generate library-json/ from the live registry (needs a logged-in uip)
 ```
 
 The generator and the shipped **`library-json.zip`** live in the top-level
@@ -74,11 +75,12 @@ The generator and the shipped **`library-json.zip`** live in the top-level
 
 ```bash
 cd typescript/sdk/lib
-scripts/unpack-library.sh    # library-json.zip → library-json/ (~214 MB), then derive library-md/ (~2 s)
+node scripts/unpack-library.mjs   # library-json.zip → library-json/ (~214 MB), then derive library-md/ + dist/connectors/ (~40 s)
 ```
 
-Unzips the canonical JSON (the source of truth), then regenerates the markdown
-from it via `integrations/scripts/convert_library_to_md.py`. Both trees are
+Extracts the canonical JSON (the source of truth), then regenerates the markdown
+and the typed descriptors from it through the SDK's own `registry pull` and
+`registry materialize`. Both trees are
 gitignored (~21k files). The e2e Docker image runs this at build; `$FLOW_SDK_LIBRARY_JSON`
 points at the materialized `library-json/`. Until you unpack, only
 `library-json.samples/` (the 3 examples) exists locally.
@@ -95,7 +97,7 @@ The zip is a snapshot. To refresh it against the live registry:
 
 ```bash
 uip login -t <tenant>                          # verify: uip is connectors list
-scripts/generate-library-json.sh all           # registry → library-json/ (~7k ops, slow)
+node scripts/generate-library-json.mjs all     # registry → library-json/ (~7k ops, slow)
 # then re-bundle, from the repo root:
 rm -rf integrations/library-json && cp -R typescript/sdk/lib/library-json integrations/library-json
 find integrations/library-json -print | LC_ALL=C sort | zip -q -X integrations/artifacts/library-json.zip -@

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -64,7 +64,7 @@
     "node": ">=22.6"
   },
   "scripts": {
-    "build": "tsc && tsc -p cli/tsconfig.json && cp skill/references/api-index.md dist/api-index.md && cp skill/references/api-members.md dist/api-members.md && cp src/core-definitions.json dist/core-definitions.json && cp src/ixp-definition.json dist/ixp-definition.json && cp src/bpmn/uipath-moddle.v1.json dist/bpmn/uipath-moddle.v1.json && cp src/bpmn/registry-types.json dist/bpmn/registry-types.json && node scripts/copy-registry-generators.mjs && node scripts/extract-api-model.mjs --check && node scripts/gen-api-index.mjs --check && node scripts/api-doc-coverage.mjs --check && node scripts/check-api-docs.mjs",
+    "build": "tsc && tsc -p cli/tsconfig.json && cp src/core-definitions.json dist/core-definitions.json && cp src/ixp-definition.json dist/ixp-definition.json && cp src/bpmn/uipath-moddle.v1.json dist/bpmn/uipath-moddle.v1.json && cp src/bpmn/registry-types.json dist/bpmn/registry-types.json && node scripts/extract-api-model.mjs --check && node scripts/gen-api-index.mjs && node scripts/api-doc-coverage.mjs --check && node scripts/check-api-docs.mjs",
     "check:package": "node scripts/check-package-contents.mjs",
     "generate:api": "node scripts/extract-api-model.mjs && node scripts/gen-api-index.mjs",
     "docs:check": "node scripts/check-api-docs.mjs",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "a836c088fd55c8f0dc3f5650a89168f0c934d685"
+  "gitref": "7fb29d6f777b5b983815fbef279ffbcff204c5e2"
 }