@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

package/dist/registry/generators/fields.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which fields an operation exposes to an author.
+ *
+ * Body fields live in the sidecar's `inputDefinition.fields`; query, path and
+ * FILE multipart parameters live in the entry's `operation.parameters`. The
+ * descriptor generator, the Markdown generator and `prepare` all need the same
+ * answer, so the rules live here once. Ported from the top of
+ * `generate_connectors_ts.py`.
+ */
+import { type LibraryEntry, type LibraryField, type V1Definition } from "../model/library.js";
+import { type LookupSpecData } from "../lookup-specs.js";
+/**
+ * A multipart parameter that is not a file. The runtime composes it from the
+ * body parameters; the author never fills it. Same rule as `core/library.ts`.
+ */
+export declare function isContainerPart(parameter: {
+    type?: unknown;
+    dataType?: unknown;
+}): boolean;
+/**
+ * The complete input vocabulary the SDK runtime consumes: sidecar body fields,
+ * then query/path/file-multipart parameters, a parameter replacing a same-named
+ * body field in place because its wire location is authoritative.
+ */
+export declare function authoritativeInputFields(entry: LibraryEntry, v1def: V1Definition | undefined): LibraryField[];
+/**
+ * {@link authoritativeInputFields}, falling back to the catalog's
+ * `inputSchema.fields` when the union is empty and the catalog declares a
+ * required field, then appending the catalog's file-typed fields.
+ */
+export declare function inputFields(entry: LibraryEntry, v1def: V1Definition | undefined): LibraryField[];
+/**
+ * The one field list a descriptor's inputs — or an event's `where` — come from.
+ * An event's authored inputs are its subscription parameters, held only in the
+ * sidecar's `eventParameters.fields`.
+ */
+export declare function descriptorInputFields(entry: LibraryEntry, v1def: V1Definition | undefined): LibraryField[];
+/** `{ fieldName → spec }` for every input field that earns a `.by*` helper. */
+export declare function lookupSpecs(entry: LibraryEntry, v1def: V1Definition | undefined, invariant: ReadonlySet<string>): Map<string, LookupSpecData>;
+/**
+ * The fields whose TypeScript type must also accept a `LookupToken`: exactly the
+ * set {@link lookupSpecs} generates helpers for, decided by the same call.
+ */
+export declare function markLookupFields(entry: LibraryEntry, fields: readonly LibraryField[], invariant: ReadonlySet<string>): Array<LibraryField & {
+    __lookup?: true;
+}>;

package/dist/registry/generators/fields.js

@@ -0,0 +1,111 @@
+/**
+ * Which fields an operation exposes to an author.
+ *
+ * Body fields live in the sidecar's `inputDefinition.fields`; query, path and
+ * FILE multipart parameters live in the entry's `operation.parameters`. The
+ * descriptor generator, the Markdown generator and `prepare` all need the same
+ * answer, so the rules live here once. Ported from the top of
+ * `generate_connectors_ts.py`.
+ */
+import { isEventNodeType } from "../model/library.js";
+import { catalogReferences, classify, specsFromFields } from "../lookup-specs.js";
+/**
+ * A multipart parameter that is not a file. The runtime composes it from the
+ * body parameters; the author never fills it. Same rule as `core/library.ts`.
+ */
+export function isContainerPart(parameter) {
+    return parameter.type === "multipart" && String(parameter.dataType || "string").toLowerCase() !== "file";
+}
+/**
+ * The complete input vocabulary the SDK runtime consumes: sidecar body fields,
+ * then query/path/file-multipart parameters, a parameter replacing a same-named
+ * body field in place because its wire location is authoritative.
+ */
+export function authoritativeInputFields(entry, v1def) {
+    const fields = (v1def?.inputDefinition?.fields ?? []).map((f) => ({ ...f }));
+    const positions = new Map();
+    fields.forEach((field, index) => positions.set(field.name, index));
+    for (const parameter of entry.operation?.parameters ?? []) {
+        const name = parameter.name;
+        const location = parameter.type;
+        if (!name || (location !== "query" && location !== "path" && location !== "multipart"))
+            continue;
+        if (isContainerPart(parameter))
+            continue;
+        const field = {
+            name,
+            type: parameter.dataType,
+            required: parameter.required === true,
+        };
+        if (parameter.displayName)
+            field.displayName = parameter.displayName;
+        if (parameter.description)
+            field.description = parameter.description;
+        // A QUERY parameter can carry a `reference` too — Slack's `send_as` does.
+        if (parameter.reference && typeof parameter.reference === "object")
+            field.reference = parameter.reference;
+        const at = positions.get(name);
+        if (at !== undefined) {
+            fields[at] = field;
+        }
+        else {
+            positions.set(name, fields.length);
+            fields.push(field);
+        }
+    }
+    return fields;
+}
+/**
+ * {@link authoritativeInputFields}, falling back to the catalog's
+ * `inputSchema.fields` when the union is empty and the catalog declares a
+ * required field, then appending the catalog's file-typed fields.
+ */
+export function inputFields(entry, v1def) {
+    let fields = authoritativeInputFields(entry, v1def);
+    const catalogFields = entry.inputSchema?.fields ?? [];
+    if (fields.length === 0 && catalogFields.some((f) => f.required === true)) {
+        fields = catalogFields.map((f) => ({ ...f }));
+    }
+    const positions = new Set(fields.map((f) => f.name));
+    for (const catalogField of catalogFields) {
+        const name = catalogField.name;
+        if (!name || String(catalogField.type || "").toLowerCase() !== "file" || positions.has(name))
+            continue;
+        positions.add(name);
+        fields.push({ ...catalogField });
+    }
+    return fields;
+}
+/**
+ * The one field list a descriptor's inputs — or an event's `where` — come from.
+ * An event's authored inputs are its subscription parameters, held only in the
+ * sidecar's `eventParameters.fields`.
+ */
+export function descriptorInputFields(entry, v1def) {
+    if (isEventNodeType(entry.nodeType || ""))
+        return v1def?.eventParameters?.fields ?? [];
+    return inputFields(entry, v1def);
+}
+/** `{ fieldName → spec }` for every input field that earns a `.by*` helper. */
+export function lookupSpecs(entry, v1def, invariant) {
+    return specsFromFields(inputFields(entry, v1def), invariant, catalogReferences(entry));
+}
+/**
+ * The fields whose TypeScript type must also accept a `LookupToken`: exactly the
+ * set {@link lookupSpecs} generates helpers for, decided by the same call.
+ */
+export function markLookupFields(entry, fields, invariant) {
+    // The catalog's `reference` is merged INTO the returned field, not only
+    // consulted: the descriptor's lookup note reads target and value from it.
+    const references = catalogReferences(entry);
+    return fields.map((field) => {
+        const merged = { ...field };
+        const name = merged.name;
+        if (!(merged.reference && typeof merged.reference === "object") && name !== undefined && references.has(name)) {
+            merged.reference = references.get(name);
+        }
+        if (classify(merged, invariant) === "lookup")
+            merged.__lookup = true;
+        return merged;
+    });
+}

package/dist/registry/generators/markdown/common.d.ts

@@ -0,0 +1,21 @@
+import { type Dict } from "./pyvalue.js";
+/**
+ * One enum choice, as the literal an author would write. `inputSchema` uses
+ * plain strings; `inputDefinition` uses `{ name, value }` objects, and `value`
+ * is what the flow has to send.
+ */
+export declare function enumValue(v: unknown): string;
+/**
+ * The collection to call to resolve a field's value, or `""`. `path` is
+ * preferred over `objectName` because the schema documents `path` as the one
+ * used for the call; either may carry a `?query`, which is split off.
+ */
+export declare function referenceCollection(f: Dict): string;
+/** The `?query` half of whichever side {@link referenceCollection} used, or `""`. */
+export declare function referenceQuery(f: Dict): string;
+/**
+ * `[name, type, wireName]`: the source-facing name and type, plus the distinct
+ * wire name when there is one. A top-level `users[*]` is flattened wire
+ * notation the descriptor exposes as `users: string[]`.
+ */
+export declare function authoringField(f: Dict): [name: string, type: string, wireName: string];

package/dist/registry/generators/markdown/common.js

@@ -0,0 +1,55 @@
+/**
+ * Field-level helpers several sections share: how an enum choice prints, which
+ * collection a `reference` points at, and the authoring name of a field.
+ * Ported from the top of `convert_library_to_md.py`.
+ */
+import { pyStr, pyStripChars, splitOnce } from "../../compat/pystr.js";
+import { getStr, isDict, pyOr } from "./pyvalue.js";
+/**
+ * One enum choice, as the literal an author would write. `inputSchema` uses
+ * plain strings; `inputDefinition` uses `{ name, value }` objects, and `value`
+ * is what the flow has to send.
+ */
+export function enumValue(v) {
+    if (isDict(v))
+        return pyStr("value" in v ? v.value : "name" in v ? v.name : "");
+    return pyStr(v);
+}
+/** `reference.path or reference.objectName or ""`, when it is a string. */
+function referenceSource(f) {
+    const reference = f.reference;
+    if (!isDict(reference))
+        return undefined;
+    const source = pyOr(reference.path, reference.objectName, "");
+    return typeof source === "string" ? source : undefined;
+}
+/**
+ * The collection to call to resolve a field's value, or `""`. `path` is
+ * preferred over `objectName` because the schema documents `path` as the one
+ * used for the call; either may carry a `?query`, which is split off.
+ */
+export function referenceCollection(f) {
+    const source = referenceSource(f);
+    if (!source)
+        return "";
+    return pyStripChars(splitOnce(source, "?")[0], "/");
+}
+/** The `?query` half of whichever side {@link referenceCollection} used, or `""`. */
+export function referenceQuery(f) {
+    const source = referenceSource(f);
+    if (source === undefined)
+        return "";
+    return splitOnce(source, "?")[1] ?? "";
+}
+/**
+ * `[name, type, wireName]`: the source-facing name and type, plus the distinct
+ * wire name when there is one. A top-level `users[*]` is flattened wire
+ * notation the descriptor exposes as `users: string[]`.
+ */
+export function authoringField(f) {
+    const wireName = getStr(f, "name", "?");
+    const type = getStr(f, "type", "?");
+    if (wireName.endsWith("[*]") && !wireName.includes("."))
+        return [wireName.slice(0, -3), `${type}[]`, wireName];
+    return [wireName, type, ""];
+}

package/dist/registry/generators/markdown/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Markdown library: one page per operation plus a rewritten `index.json`.
+ *
+ * Reads an extracted `library-json/` tree and renders the parallel tree of
+ * `.md` pages agents read for connector discovery, with an index whose `path`s
+ * point at the pages. Symbol names the pages cite (`connector(SendMessageToUser,
+ * …)`) are derived by `naming.symbolIndex`, the same map the descriptor
+ * generator uses, so a page cannot cite a symbol that module did not emit.
+ *
+ * Ported from `integrations/scripts/convert_library_to_md.py`; the output is
+ * byte-for-byte that script's. A caller writes each page as-is and the index
+ * with `pyJsonDocument(index)`.
+ */
+import type { LoadedLibrary } from "../../library-reader.js";
+import type { LibraryEntry, LibraryIndex, V1Definition } from "../../model/library.js";
+export interface MarkdownContext {
+    /** `naming.symbolIndex` over the index: `nodeType → exported descriptor name`. */
+    symbols: ReadonlyMap<string, string>;
+    /** `objectName`s the curated ledger declares connector-invariant. */
+    invariant: ReadonlySet<string>;
+}
+/** One operation's page. `v1def` is the sidecar already unwrapped from a one-element list. */
+export declare function renderMarkdownPage(entry: LibraryEntry, v1def: V1Definition | undefined, ctx: MarkdownContext): string;
+export interface MarkdownOutput {
+    /** `<index path with .json → .md>` → page text, in index order. */
+    pages: Map<string, string>;
+    /** The source index with each converted row's `path` rewritten; other keys untouched. */
+    index: LibraryIndex;
+    /** One `  WARN: missing source entry <path>` line per row whose entry file is absent. */
+    warnings: string[];
+}
+/** Every operation the index names, rendered. Rows whose path is not a `.json` or whose file is missing are left as they are. */
+export declare function renderMarkdownLibrary(library: LoadedLibrary): MarkdownOutput;

package/dist/registry/generators/markdown/index.js

@@ -0,0 +1,37 @@
+import { pyStr } from "../../compat/pystr.js";
+import { symbolIndex } from "../../naming.js";
+import { renderOp } from "./page.js";
+import { pyOr } from "./pyvalue.js";
+/** One operation's page. `v1def` is the sidecar already unwrapped from a one-element list. */
+export function renderMarkdownPage(entry, v1def, ctx) {
+    return renderOp(entry, v1def, ctx.symbols.get(entry.nodeType), ctx.invariant);
+}
+/** Every operation the index names, rendered. Rows whose path is not a `.json` or whose file is missing are left as they are. */
+export function renderMarkdownLibrary(library) {
+    const index = library.index;
+    const pages = new Map();
+    const warnings = [];
+    const entries = index.entries;
+    if (!Array.isArray(entries))
+        return { pages, index, warnings };
+    // The SAME map the descriptor generator uses.
+    const symbols = symbolIndex(entries);
+    const rows = entries.map((row) => {
+        const relJson = pyStr(pyOr(row.path, ""));
+        if (!relJson || !relJson.endsWith(".json"))
+            return row;
+        const entry = library.readEntry(row);
+        if (entry === undefined) {
+            warnings.push(`  WARN: missing source entry ${library.entryPath(row)}`);
+            return row;
+        }
+        // The Flow node shape lives beside the entry as `<op>.v1def.json`; its
+        // inputDefinition is what the compiler validates, so inputs render from it.
+        const v1def = library.readV1Def(row);
+        const md = renderOp(entry, v1def, symbols.get(row.nodeType), library.invariant);
+        const relMd = `${relJson.slice(0, -".json".length)}.md`;
+        pages.set(relMd, md);
+        return { ...row, path: relMd };
+    });
+    return { pages, index: { ...index, entries: rows }, warnings };
+}

package/dist/registry/generators/markdown/page.d.ts

@@ -0,0 +1,8 @@
+import { type Dict } from "./pyvalue.js";
+/**
+ * @param j the canonical entry
+ * @param v1def the sidecar, or `undefined` when the operation ships none
+ * @param symbol the generated descriptor's exported name, or `undefined` when there is no descriptor
+ * @param invariant `objectName`s the curated ledger declares connector-invariant
+ */
+export declare function renderOp(j: Dict, v1def: Dict | undefined, symbol: string | undefined, invariant: ReadonlySet<string>): string;

package/dist/registry/generators/markdown/page.js

@@ -0,0 +1,52 @@
+/**
+ * One library entry rendered to Markdown: header → schema-dynamic notice →
+ * choosing the object → resolving the field set → required inputs → optional
+ * inputs → resolving lookups → example → filtering → outputs. Ported from
+ * `render_op`; the page is `"\n".join(lines)` with no trailing newline.
+ */
+import { afterLast, pyStr } from "../../compat/pystr.js";
+import { dictOf, getStr, pyOr, pyTruthy } from "./pyvalue.js";
+import { choosingObjectLines } from "./sections/choosing-object.js";
+import { exampleLines } from "./sections/example.js";
+import { eventFilterLines } from "./sections/filtering.js";
+import { headerLines } from "./sections/header.js";
+import { assembleFields, optionalInputsLines, requiredInputsLines } from "./sections/inputs.js";
+import { lookupLines } from "./sections/lookups.js";
+import { outputsLines } from "./sections/outputs.js";
+import { schemaActionLines } from "./sections/resolving-fields.js";
+import { schemaDynamicLines } from "./sections/schema-dynamic.js";
+/**
+ * @param j the canonical entry
+ * @param v1def the sidecar, or `undefined` when the operation ships none
+ * @param symbol the generated descriptor's exported name, or `undefined` when there is no descriptor
+ * @param invariant `objectName`s the curated ledger declares connector-invariant
+ */
+export function renderOp(j, v1def, symbol, invariant) {
+    const nodeType = getStr(j, "nodeType", "?");
+    const conn = dictOf(j.connector);
+    const op = dictOf(j.operation);
+    const out = [];
+    out.push(...headerLines(j, nodeType));
+    out.push(...schemaDynamicLines(j, nodeType));
+    const fields = assembleFields(j, v1def);
+    const required = fields.filter((f) => pyTruthy(f.required));
+    const optional = fields.filter((f) => !pyTruthy(f.required));
+    out.push(...choosingObjectLines(j, nodeType));
+    const action = op.schemaAction;
+    if (pyTruthy(action)) {
+        out.push(...schemaActionLines(pyStr(pyOr(conn.key, "<connector>")), pyStr(pyOr(op.objectName, "")), pyStr(pyOr(op.name, "<operation>")), dictOf(action), fields));
+    }
+    out.push(...requiredInputsLines(required));
+    out.push(...optionalInputsLines(optional));
+    const lookups = lookupLines(pyStr(pyOr(conn.key, "<connector>")), afterLast(nodeType, "."), fields, symbol, invariant);
+    if (lookups.length) {
+        out.push("## Resolving lookups", "");
+        out.push(...lookups);
+        out.push("");
+    }
+    // The example goes AFTER the lookups section: it uses the helpers that section introduces.
+    out.push(...exampleLines(j, fields, symbol, invariant, v1def));
+    out.push(...eventFilterLines(j, v1def));
+    out.push(...outputsLines(j));
+    return out.join("\n");
+}

package/dist/registry/generators/markdown/pyvalue.d.ts

@@ -0,0 +1,34 @@
+export type Dict = Record<string, unknown>;
+/** Python truthiness for JSON-shaped values: empty strings and containers are false, `NaN` is true. */
+export declare function pyTruthy(v: unknown): boolean;
+/** `a or b or …`: the first Python-truthy operand, else the last one. */
+export declare function pyOr<T>(...values: T[]): T;
+/** `isinstance(v, dict)`. */
+export declare function isDict(v: unknown): v is Dict;
+/** `(v or {})` where the Python goes on to call `.get` — a non-dict reads as empty. */
+export declare function dictOf(v: unknown): Dict;
+/**
+ * The items Python's `for x in (v or [])` would visit: a list's items, a
+ * string's code points, a dict's keys; nothing for anything else.
+ */
+export declare function listOf(v: unknown): unknown[];
+/** `str(d.get(key, default))`: a missing key yields `default`, a present `None` yields `"None"`. */
+export declare function getStr(d: Dict, key: string, fallback: string): string;
+/** `[str(x) for x in (v or [])]`. */
+export declare function strList(v: unknown): string[];
+/** The first value of an insertion-ordered map: `next(iter(d.values()))`. Callers check emptiness first. */
+export declare function firstValue<V>(map: ReadonlyMap<unknown, V>): V;
+/** `re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*").fullmatch`: a bare object key. */
+export declare const IDENT: RegExp;
+/**
+ * Whether Python's `float(s)` accepts the string.
+ *
+ * `float()` strips whitespace (see {@link FLOAT_SPACE}), maps every `Nd`
+ * digit to ASCII, allows a single `_` between digits (PEP 515), and takes
+ * `inf`/`infinity`/`nan` in any ASCII case with an optional sign. It rejects
+ * the empty string, hex, a dangling exponent, an embedded NUL and underscores
+ * anywhere but between digits. The generator uses the verdict, not the value:
+ * an enum choice a number-typed field can carry prints bare, anything else
+ * falls through.
+ */
+export declare function pyFloatAccepts(s: string): boolean;

package/dist/registry/generators/markdown/pyvalue.js

@@ -0,0 +1,106 @@
+/**
+ * Python value semantics the Markdown generator leans on.
+ *
+ * `convert_library_to_md.py` is written against dicts — `.get()`, `or`
+ * fallbacks, truthiness tests — and its output is byte-locked. These helpers
+ * spell those semantics once so each section module can be read beside the
+ * Python line for line. JSON has no `undefined`, so after `JSON.parse` an
+ * absent key is `undefined` and an explicit `null` is `null`: the same
+ * distinction Python's `d.get(k, default)` draws between a missing key (the
+ * default) and a `None` value (printed as `None`).
+ */
+import { pyStr, pyStripChars } from "../../compat/pystr.js";
+/** Python truthiness for JSON-shaped values: empty strings and containers are false, `NaN` is true. */
+export function pyTruthy(v) {
+    if (v === null || v === undefined)
+        return false;
+    switch (typeof v) {
+        case "boolean":
+            return v;
+        case "number":
+            return v !== 0;
+        case "bigint":
+            return v !== 0n;
+        case "string":
+            return v.length > 0;
+        case "object":
+            if (Array.isArray(v))
+                return v.length > 0;
+            if (v instanceof Map || v instanceof Set)
+                return v.size > 0;
+            return Object.keys(v).length > 0;
+        default:
+            return true;
+    }
+}
+/** `a or b or …`: the first Python-truthy operand, else the last one. */
+export function pyOr(...values) {
+    for (const v of values)
+        if (pyTruthy(v))
+            return v;
+    return values[values.length - 1];
+}
+/** `isinstance(v, dict)`. */
+export function isDict(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** `(v or {})` where the Python goes on to call `.get` — a non-dict reads as empty. */
+export function dictOf(v) {
+    return isDict(v) ? v : {};
+}
+/**
+ * The items Python's `for x in (v or [])` would visit: a list's items, a
+ * string's code points, a dict's keys; nothing for anything else.
+ */
+export function listOf(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string")
+        return Array.from(v);
+    if (isDict(v))
+        return Object.keys(v);
+    return [];
+}
+/** `str(d.get(key, default))`: a missing key yields `default`, a present `None` yields `"None"`. */
+export function getStr(d, key, fallback) {
+    const v = d[key];
+    return v === undefined ? fallback : pyStr(v);
+}
+/** `[str(x) for x in (v or [])]`. */
+export function strList(v) {
+    return listOf(pyOr(v, [])).map((x) => pyStr(x));
+}
+/** The first value of an insertion-ordered map: `next(iter(d.values()))`. Callers check emptiness first. */
+export function firstValue(map) {
+    return map.values().next().value;
+}
+/** `re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*").fullmatch`: a bare object key. */
+export const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** `digitpart ::= digit (["_"] digit)*` over every Unicode decimal digit, as `float()` accepts. */
+const DIGITS = "\\p{Nd}(?:_?\\p{Nd})*";
+const FLOAT_LITERAL = new RegExp(`^[+-]?(?:${DIGITS}(?:\\.(?:${DIGITS})?)?|\\.${DIGITS})(?:[eE][+-]?${DIGITS})?$`, "u");
+const SPECIAL_FLOAT = /^[+-]?(?:inf|infinity|nan)$/i;
+/**
+ * What `float()` strips: the C `isspace` set for ASCII (the transform copies
+ * ASCII verbatim, so `\x1c`–`\x1f` are NOT whitespace here although
+ * `str.strip()` removes them) plus every non-ASCII character `str.isspace()`
+ * is true for, which the transform maps to a space first.
+ */
+const FLOAT_SPACE = " \t\n\u000b\u000c\r\u0085\u00a0\u1680" +
+    "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a" +
+    "\u2028\u2029\u202f\u205f\u3000";
+/**
+ * Whether Python's `float(s)` accepts the string.
+ *
+ * `float()` strips whitespace (see {@link FLOAT_SPACE}), maps every `Nd`
+ * digit to ASCII, allows a single `_` between digits (PEP 515), and takes
+ * `inf`/`infinity`/`nan` in any ASCII case with an optional sign. It rejects
+ * the empty string, hex, a dangling exponent, an embedded NUL and underscores
+ * anywhere but between digits. The generator uses the verdict, not the value:
+ * an enum choice a number-typed field can carry prints bare, anything else
+ * falls through.
+ */
+export function pyFloatAccepts(s) {
+    const text = pyStripChars(s, FLOAT_SPACE);
+    return FLOAT_LITERAL.test(text) || SPECIAL_FLOAT.test(text);
+}

package/dist/registry/generators/markdown/sections/choosing-object.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function choosingObjectLines(j: Dict, nodeType: string): string[];

package/dist/registry/generators/markdown/sections/choosing-object.js

@@ -0,0 +1,52 @@
+/**
+ * `## Choosing the object`, on an operation that works on any object of the
+ * connection (`objectFromDiscovery`). Object selection precedes field
+ * selection, so this sits above the inputs.
+ */
+import { afterLast, pyStr } from "../../../compat/pystr.js";
+import { dictOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function choosingObjectLines(j, nodeType) {
+    const op = dictOf(j.operation);
+    if (!pyTruthy(op.objectFromDiscovery))
+        return [];
+    const conn = dictOf(j.connector);
+    const connectorKey = pyStr(pyOr(conn.key, "<connector>"));
+    const verb = pyStr(pyOr(op.name, "<operation>"));
+    const prefix = `uipath.connector.${connectorKey}.`;
+    const mdAction = nodeType.startsWith(prefix) ? nodeType.slice(prefix.length) : afterLast(nodeType, ".");
+    return [
+        "## Choosing the object",
+        "",
+        "This operation works on any object in the connection, including " +
+            "custom ones, so the object list is not in this catalog. Do not " +
+            "run discovery commands and do not hand-filter the catalog — " +
+            "author the step with the object name as the task said it (any " +
+            "casing), then one command matches it deterministically:",
+        "",
+        "```bash",
+        `npx flow-sdk registry prepare ${connectorKey} ${mdAction} --object <name-as-the-task-said-it>`,
+        "```",
+        "",
+        "The name is matched, never equality-tested: exact, then " +
+            "case-insensitive on API name and display name (`matched " +
+            "\"Company__C\" -> Company__c` is printed), narrowed to objects " +
+            `that support ${verb}. It then fetches the object's ` +
+            "connection-resolved fields, generates the typed descriptor, and " +
+            "prints the import line to use.",
+        "",
+        "**If the name matches several objects, the command refuses and " +
+            "prints the candidates** (API name, display name, custom, " +
+            "operations). `Custom: yes` marks an object that exists only on " +
+            "this tenant, so it could never have been in this catalog — a " +
+            "task that says \"custom\" means one of those rows. Pick by the " +
+            "task's wording, or present the candidates and let the user " +
+            "choose; never pick for them, and do not assume the user's " +
+            "wording is the API name. Then re-run with the chosen name.",
+        "",
+        "**If nothing matches**, the command has already retried against " +
+            "a refreshed catalog before saying so — the object genuinely is " +
+            "not on this connection. Check the value against the task's " +
+            "words, or surface it to the user rather than inventing one.",
+        "",
+    ];
+}

package/dist/registry/generators/markdown/sections/example.d.ts

@@ -0,0 +1,22 @@
+import { type Dict } from "../pyvalue.js";
+/** `fields.project.key` → `projectKey`: a readable input name, not a path. */
+export declare function leafName(fieldName: string): string;
+/** `send-message-to-user` → `sendMessageToUser`, a usable step name. */
+export declare function pascalStep(action: string): string;
+/** Render `[name, value]` pairs as the nested object literal an author writes. */
+export declare function nestInputs(pairs: ReadonlyArray<readonly [unknown, string]>): string[];
+/**
+ * The value to show for one required input: a resolvable lookup shows its
+ * helper; an enum shows its FIRST DECLARED CHOICE, typed to the declaration
+ * where it can be; anything else shows `input('<name>')`.
+ */
+export declare function exampleValue(f: Dict, symbol: string | undefined, invariant: ReadonlySet<string>, connectorKey?: string, action?: string): string;
+/** A compilable `connector(...)` call for this operation; events go to {@link eventExampleLines}. */
+export declare function exampleLines(j: Dict, fields: readonly Dict[], symbol: string | undefined, invariant: ReadonlySet<string>, v1def: Dict | undefined): string[];
+/**
+ * A compilable `onEvent(...)` / `waitForEvent(...)` call for a connector
+ * EVENT. A GENERIC event (`GenericTrigger`) watches ONE object the entry does
+ * not name, so the example shows the `object` option; a curated event shows
+ * `where` with the sidecar's event parameters.
+ */
+export declare function eventExampleLines(j: Dict, symbol: string | undefined, connectorKey: string, action: string, step: string, v1def: Dict | undefined): string[];