@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

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[];

package/dist/registry/generators/markdown/sections/example.js

@@ -0,0 +1,295 @@
+/**
+ * `## Example`: a compilable `connector(...)` call — or, for an event, an
+ * `onEvent(...)` / `waitForEvent(...)` call — for the operation.
+ *
+ * Required inputs only, nested the way the descriptor's `Inputs` type is
+ * nested, with the import path DERIVED: a schema-dynamic operation's
+ * descriptor lives in `./connectors-local/` after a `prepare`. When a
+ * descriptor exists the example is type-checked against its `Inputs`, so the
+ * required set is the descriptor generator's, not this module's; the two
+ * vocabularies disagree about required-ness on most operations, and that
+ * disagreement is pre-existing. Ported from `example_lines`,
+ * `event_example_lines`, `nest_inputs`, `example_value`, `leaf_name` and
+ * `pascal_step`.
+ */
+import { PACKAGE_NAME } from "../../../../package-name.js";
+import { pyJsonString } from "../../../codecs/pyjson.js";
+import { sortedStrings } from "../../../compat/compare.js";
+import { afterLast, pyStr, upperFirst } from "../../../compat/pystr.js";
+import { classify, referenceOf } from "../../../lookup-specs.js";
+import { isEventNodeType, TRIGGER_PREFIX } from "../../../model/library.js";
+import { byAliases } from "../../../naming.js";
+import { descriptorInputFields, markLookupFields } from "../../fields.js";
+import { authoringField, enumValue } from "../common.js";
+import { dictOf, firstValue, getStr, IDENT, listOf, pyFloatAccepts, pyOr, pyTruthy, strList, } from "../pyvalue.js";
+/** `fields.project.key` → `projectKey`: a readable input name, not a path. */
+export function leafName(fieldName) {
+    const parts = fieldName.replaceAll("[*]", "").split(".").filter((p) => p);
+    if (!parts.length)
+        return "value";
+    if (parts.length === 1)
+        return parts[0];
+    const [head, ...rest] = parts.slice(-2);
+    return head + rest.map(upperFirst).join("");
+}
+/** `send-message-to-user` → `sendMessageToUser`, a usable step name. */
+export function pascalStep(action) {
+    const words = action.replaceAll("_", "-").split("-").filter((w) => w);
+    if (!words.length)
+        return "step";
+    const [head, ...rest] = words;
+    return head + rest.map(upperFirst).join("");
+}
+/**
+ * One level of the example's input literal. A segment can be BOTH an array
+ * and an object (`contacts[*].name` is a list of objects), so array-ness is a
+ * flag on the node. `children` is insertion-ordered, like the Python dict.
+ */
+class Node {
+    children = new Map();
+    isArray = false;
+    leaf;
+}
+/** Render `[name, value]` pairs as the nested object literal an author writes. */
+export function nestInputs(pairs) {
+    const root = new Node();
+    for (const [name, value] of pairs) {
+        let node = root;
+        for (const segment of pyStr(name).split(".").filter((p) => p)) {
+            const isArray = segment.endsWith("[*]");
+            const key = isArray ? segment.slice(0, -3) : segment;
+            let child = node.children.get(key);
+            if (child === undefined) {
+                child = new Node();
+                node.children.set(key, child);
+            }
+            child.isArray = child.isArray || isArray;
+            node = child;
+        }
+        node.leaf = value;
+    }
+    const render = (node, indent) => {
+        const pad = "  ".repeat(indent);
+        const lines = [];
+        for (const [key, child] of node.children) {
+            const safe = IDENT.test(key) ? key : pyJsonString(key);
+            if (child.children.size) {
+                const [openBrace, closeBrace] = child.isArray ? ["[{", "}],"] : ["{", "},"];
+                lines.push(`${pad}${safe}: ${openBrace}`);
+                lines.push(...render(child, indent + 1));
+                lines.push(`${pad}${closeBrace}`);
+            }
+            else {
+                const value = child.leaf !== undefined ? child.leaf : "undefined";
+                lines.push(child.isArray ? `${pad}${safe}: [${value}],` : `${pad}${safe}: ${value},`);
+            }
+        }
+        return lines;
+    };
+    return render(root, 1);
+}
+/**
+ * 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 function exampleValue(f, symbol, invariant, connectorKey = "", action = "") {
+    const [name] = authoringField(f);
+    // The lookup table is keyed by the WIRE name (`addLabelIds[*]`), which is
+    // what `--resolve` and `buildConnectorInputs` both match on.
+    const wire = pyStr(pyOr(f.name, name));
+    const kind = classify(f, invariant);
+    if (kind === "lookup") {
+        const reference = referenceOf(f);
+        const names = strList(reference.lookupNames);
+        const aliases = byAliases(names);
+        const first = names.length ? names[0] : "id";
+        if (symbol) {
+            if (aliases.size)
+                return `lookup(${symbol}, '${wire}').${firstValue(aliases)}('…')`;
+            return `lookup(${symbol}, '${wire}').by('${first}', '…')`;
+        }
+        // NO DESCRIPTOR — a Generic CRUD expansion: the string form, generic `.by` only.
+        return `lookup('${connectorKey}', '${action}', '${wire}').by('${first}', '…')`;
+    }
+    const type = getStr(f, "type", "").toLowerCase();
+    const enumeration = f.enum;
+    if (pyTruthy(enumeration)) {
+        // The choice list is strings even when the field is not; fall back rather
+        // than emit something that does not compile.
+        const choice = enumValue(listOf(enumeration)[0]);
+        if (type === "boolean" || type === "bool") {
+            const lowered = choice.toLowerCase();
+            if (lowered === "true" || lowered === "false")
+                return lowered;
+        }
+        else if (type === "number" || type === "integer" || type === "float" || type === "double" || type === "long") {
+            if (pyFloatAccepts(choice))
+                return choice;
+        }
+        else {
+            return pyJsonString(choice);
+        }
+    }
+    return `input('${leafName(name)}')`;
+}
+/** A compilable `connector(...)` call for this operation; events go to {@link eventExampleLines}. */
+export function exampleLines(j, fields, symbol, invariant, v1def) {
+    const connectorKey = pyStr(pyOr(dictOf(j.connector).key, "<connector>"));
+    const operation = dictOf(j.operation);
+    const runtime = dictOf(j.runtime);
+    const nodeType = pyStr(pyOr(j.nodeType, ""));
+    const action = afterLast(nodeType, ".");
+    const step = pascalStep(action);
+    if (isEventNodeType(nodeType))
+        return eventExampleLines(j, symbol, connectorKey, action, step, v1def);
+    // WHICH REQUIRED SET: the descriptor's `Inputs` when a descriptor exists,
+    // marked with the SAME call the descriptor generator uses; else this
+    // module's own vocabulary, which the string form cannot fail on.
+    let exampleFields;
+    if (symbol) {
+        const entry = j;
+        const raw = (v1def ?? {});
+        // Marked with the SAME call the descriptor generator uses — it also merges
+        // the catalog's `reference` into a field whose authoring vocabulary lacks
+        // one — so the example puts a helper on exactly the fields that have one.
+        exampleFields = markLookupFields(entry, descriptorInputFields(entry, raw), invariant);
+    }
+    else {
+        exampleFields = fields;
+    }
+    const required = exampleFields.filter((f) => pyTruthy(f.required));
+    const schemaDynamic = pyTruthy(operation.objectFromDiscovery) ||
+        pyTruthy(dictOf(operation.schemaAction).parents) ||
+        pyTruthy(runtime.requiresConnectionForSchema);
+    const out = ["## Example", ""];
+    const pairs = required.map((f) => {
+        const [name, , wireName] = authoringField(f);
+        return [wireName ? f.name : name, exampleValue(f, symbol, invariant, connectorKey, action)];
+    });
+    // Import exactly what the rendered body uses.
+    const bodyUses = new Set(["connector"]);
+    if (pairs.some(([, v]) => v.includes("lookup(")))
+        bodyUses.add("lookup");
+    if (pairs.some(([, v]) => v.includes("input(")))
+        bodyUses.add("input");
+    const imported = sortedStrings(bodyUses).join(", ");
+    out.push("```ts");
+    // THE PACKAGE, not a relative path.
+    out.push(`import { ${imported} } from '${PACKAGE_NAME}';`);
+    let head;
+    if (symbol) {
+        const directory = schemaDynamic ? "connectors-local" : "connectors";
+        out.push(`import { ${symbol} } from './${directory}/${connectorKey}.ts';`);
+        out.push("");
+        head = `.step('${step}', connector(${symbol}, {`;
+    }
+    else {
+        out.push("");
+        head = `.step('${step}', connector('${connectorKey}', '${action}', {`;
+    }
+    out.push(head);
+    if (pairs.length)
+        out.push(...nestInputs(pairs));
+    const opts = [];
+    if (pyTruthy(runtime.requiresConnection))
+        opts.push(`connection: '${afterLast(connectorKey, "-")}'`);
+    if (pyTruthy(runtime.requiresFolderKey))
+        opts.push("folder: 'shared'");
+    if (!symbol && (operation.activityType === "Generic" || operation.activityType === "GenericExpanded")) {
+        opts.push(`object: '${pyStr(pyOr(operation.objectName, "<object>"))}'`);
+    }
+    const tail = "}" + (opts.length ? `, { ${opts.join(", ")} }` : "") + "))";
+    out.push(tail);
+    out.push("```");
+    out.push("");
+    if (schemaDynamic && symbol) {
+        // ONE ordering per page: the import fact stays; authoring comes first.
+        if (pyTruthy(operation.objectFromDiscovery)) {
+            out.push("The descriptor comes from `./connectors-local/` and this " +
+                "import resolves only after " +
+                `\`npx flow-sdk registry prepare ${connectorKey} ${action} ` +
+                "--object <name>` runs. That never blocks authoring: write " +
+                "the step first with the string form and " +
+                "`{ object: '<name-as-the-task-said-it>' }` — `check` " +
+                "names this exact prepare — then switch to this import.");
+        }
+        else {
+            out.push("The descriptor comes from `./connectors-local/` and this " +
+                "import resolves only after " +
+                `\`npx flow-sdk registry prepare ${connectorKey} ${action}\` ` +
+                "runs. That never blocks authoring: the fields in this " +
+                "catalog are authorable immediately, and `check` flags any " +
+                "input outside them with this same command.");
+        }
+        out.push("");
+    }
+    return out;
+}
+/**
+ * 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 function eventExampleLines(j, symbol, connectorKey, action, step, v1def) {
+    const operation = dictOf(j.operation);
+    const generic = operation.activityType === "GenericTrigger";
+    const start = getStr(j, "nodeType", "").startsWith(TRIGGER_PREFIX);
+    // The SIDECAR's event parameters: the raw input definition's names are not
+    // even legal object keys. No parameters, no `where`.
+    const params = listOf(pyOr(dictOf(pyOr(dictOf(v1def).eventParameters, {})).fields, []))
+        .map(dictOf)
+        .filter((f) => typeof f.name === "string" && !pyTruthy(f.hidden))
+        .map((f) => f.name);
+    const factory = start ? "onEvent" : "waitForEvent";
+    const out = ["## Example", "", "```ts"];
+    out.push(`import { ${factory} } from '${PACKAGE_NAME}';`);
+    if (symbol)
+        out.push(`import { ${symbol} } from './connectors/${connectorKey}.ts';`);
+    out.push("");
+    const opts = [];
+    let whereLines = [];
+    if (generic)
+        opts.push("object: '<Object>'");
+    else if (params.length) {
+        // NESTED, exactly as inputs are: the generated `…Where` interface splits a
+        // dotted parameter into an object (`channelData.channel.id` becomes
+        // `channelData: ConnectorValue<ChannelDataInput>`), so a flat key — quoted
+        // or not — is not a member of the type. Unnested, Teams'
+        // `channelData.channel.id` made the only two event examples in the library
+        // the only `## Example` fences in ~8,000 that did not parse.
+        whereLines = nestInputs(params.map((p) => [p, `'<${p}>'`])).map((line) => `  ${line}`);
+    }
+    opts.push(`connection: '${afterLast(connectorKey, "-")}'`);
+    opts.push("folder: 'shared'");
+    const lead = symbol
+        ? `${factory}(${symbol}, {`
+        : `${factory}({ connector: '${connectorKey}', event: '${action}',`;
+    if (whereLines.length > 0) {
+        // Multi-line, like the action example, because the nested `where` is.
+        out.push(start ? `.trigger(${lead}` : `.step('${step}', ${lead}`);
+        out.push("  where: {");
+        out.push(...whereLines);
+        out.push("  },");
+        for (const option of opts)
+            out.push(`  ${option},`);
+        out.push("}))");
+    }
+    else {
+        const call = symbol
+            ? `${factory}(${symbol}, { ${opts.join(", ")} })`
+            : `${factory}({ connector: '${connectorKey}', event: '${action}', ${opts.join(", ")} })`;
+        out.push(start ? `.trigger(${call})` : `.step('${step}', ${call})`);
+    }
+    out.push("```");
+    out.push("");
+    if (generic) {
+        out.push("A GENERIC event: it fires for ONE object of the connection, so `object` " +
+            `names it. \`uip is triggers objects ${connectorKey} ` +
+            `${pyStr(pyOr(operation.eventOperation, operation.name, "<EVENT>"))} ` +
+            "--connection-id <id>` lists the objects the bound connection exposes.");
+        out.push("");
+    }
+    return out;
+}

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

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