@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/generators/descriptors.js

@@ -0,0 +1,405 @@
+/**
+ * Statically-typed connector descriptor modules from the canonical JSON library.
+ *
+ * For every Curated and HTTP-request operation, one `descriptor<Inputs,
+ * Outputs>()` const plus its `Inputs`/`Outputs` interfaces; for every connector
+ * EVENT, a `triggerDescriptor<Where, Outputs>()` const. Grouped one module per
+ * connector, `connectors/<connector-key>.ts`. Authored flows import the exported
+ * consts by name, so the module text is an API contract: it is byte-for-byte
+ * what `generate_connectors_ts.py` wrote. The differential that proved that
+ * ran while the Python was in the tree and was deleted with it, so
+ * `tests/registry-descriptors.test.ts` is now the description of the text.
+ *
+ * Inputs are the union of the sidecar's body fields and the entry's query/path/
+ * file-multipart parameters (see `fields.ts`); dotted and wildcard names are
+ * rebuilt as nested objects and arrays (`type-tree.ts`) and named once per
+ * connector (`type-registry.ts`). Outputs come from `outputSchema.fields`.
+ * `GenericExpanded` operations are skipped unless asked for, and a generic
+ * event's per-object variants are skipped because they share their template's
+ * node type and so would emit the same const twice.
+ */
+import { PACKAGE_NAME } from "../../package-name.js";
+import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
+import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
+import { afterLast, pyRstrip, pyStr, pyStrip, splitOnce } from "../compat/pystr.js";
+import { referenceOf, specsFromFields } from "../lookup-specs.js";
+import { isEventNodeType, } from "../model/library.js";
+import { symbolIndex } from "../naming.js";
+import { descriptorInputFields, lookupSpecs, markLookupFields } from "./fields.js";
+import { NamedTypeRegistry } from "./type-registry.js";
+import { buildTypeTree, pyTruthy, subtreeRequired } from "./type-tree.js";
+/** `str(value or "")`. */
+function strOrEmpty(value) {
+    return pyTruthy(value) ? pyStr(value) : "";
+}
+/** A field name is a valid identifier only if it has no dots, brackets, etc.; otherwise it is quoted. */
+export function keyLiteral(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : pyJsonString(name);
+}
+/** One sentence for a lookup field's own doc comment: what it sends, how to get one. */
+export function lookupFieldNote(declared) {
+    const reference = referenceOf(declared) ?? {};
+    const target = pyStr(pyTruthy(reference.objectName) ? reference.objectName : splitOnce(strOrEmpty(reference.path), "?")[0]);
+    const value = pyStr(pyTruthy(reference.lookupValue) ? reference.lookupValue : "id");
+    const field = strOrEmpty(declared.name);
+    return (`LOOKUP — sends a \`${target}.${value}\`, never a name or e-mail: ` +
+        `lookup(<Descriptor>, '${field}') (helpers in the LOOKUP lines above the descriptor).`);
+}
+/**
+ * One property line.
+ *
+ * An INPUT property is wrapped so it also accepts an expression, and a
+ * resolvable lookup additionally accepts an unresolved token. The wrapper goes
+ * here rather than on the leaf type so that `tags: input('tags')` — the whole
+ * collection as one expression — is legal alongside `tags: ['a', out(…)]`.
+ * An OUTPUT property is never wrapped: it came back from the connector.
+ */
+export function emitNestedProperty(name, node, indent, namedTypes, allOptional, isInput = false) {
+    const lines = [];
+    const declared = node.declared ?? {};
+    let desc = pyStrip(strOrEmpty(declared.description)).replaceAll("\n", " ");
+    if (isInput && pyTruthy(declared.__lookup)) {
+        // The identity goes ON the field, not only in the LOOKUP block above the
+        // descriptor: "The reporter of the issue" beside `ConnectorLookupValue<string>`
+        // read as "any string", and an e-mail went into `fields.reporter.id`.
+        desc = pyStrip(`${desc} ${lookupFieldNote(declared)}`);
+    }
+    if (desc)
+        lines.push(`${indent}/** ${desc} */`);
+    const optional = allOptional || !subtreeRequired(node) ? "?" : "";
+    let rendered = namedTypes.typeFor(name, node);
+    if (isInput) {
+        const wrapper = pyTruthy(declared.__lookup) ? "ConnectorLookupValue" : "ConnectorValue";
+        rendered = `${wrapper}<${rendered}>`;
+    }
+    lines.push(`${indent}${keyLiteral(name)}${optional}: ${rendered};`);
+    return lines;
+}
+/** `export interface <name> { … }` over the roots of one tree. */
+export function emitInterface(name, allOptional, namedTypes, fieldTree, isInput = false) {
+    const out = [`export interface ${name} {`];
+    for (const [fieldName, node] of fieldTree) {
+        out.push(...emitNestedProperty(fieldName, node, "  ", namedTypes, allOptional, isInput));
+    }
+    out.push("}");
+    return out;
+}
+export const STRATEGY_PROSE = {
+    filter: "one request (the operation declares a server-side filter)",
+    scan: "paged scan (this operation declares no filterPattern)",
+    tree: "hierarchical walk (the collection is a tree)",
+    dependent: "dependent — another field must resolve first",
+};
+/**
+ * The grep-able header: the lookups stated in prose beside the data, for agents
+ * that read source with Grep and have no language server. Bare ` * ` body
+ * lines, to be spliced inside a `/** … *\/` block.
+ */
+export function emitLookupComment(specs, symbol = "<Descriptor>") {
+    const lines = [];
+    for (const [field, spec] of specs) {
+        const target = splitOnce(pyStr(pyTruthy(spec.objectName) ? spec.objectName : spec.path), "?")[0];
+        lines.push(` * LOOKUP: \`${field}\` -> ${target}.${spec.value}`);
+        const aliases = spec.aliases;
+        const offered = aliases.size > 0 ? [...aliases.values()].map((a) => `${a}()`) : [];
+        const byList = spec.by.map((n) => `\`${n}\``).join(", ");
+        lines.push(` *   by: ${byList}`);
+        // THE WHOLE CALL, not just the method names: naming `.byEmail` without the
+        // `lookup(Descriptor, 'field')` wrapper says helpers exist but not how to
+        // reach one.
+        const first = aliases.size > 0 ? [...aliases.values()][0] : undefined;
+        const call = first
+            ? `lookup(${symbol}, '${field}').${first}(value)`
+            : spec.by.length > 0
+                ? `lookup(${symbol}, '${field}').by('${spec.by[0]}', value)`
+                : `lookup(${symbol}, '${field}')`;
+        lines.push(` *   use: ${call}`);
+        if (offered.length > 0) {
+            lines.push(` *   also: ${[...aliases.values()].map((a) => `.${a}`).join(", ")}  ·  .by(name, value)`);
+        }
+        else {
+            lines.push(" *   also: .by(name, value) only — aliases collided");
+        }
+        lines.push(` *   strategy: ${STRATEGY_PROSE[spec.strategy]}`);
+        if (spec.dependsOn && spec.dependsOn.length > 0) {
+            lines.push(` *   resolve first: ${spec.dependsOn.map((d) => `\`${d}\``).join(", ")}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The descriptor's `lookups:` literal — a RUNTIME value, not a type. `lookup()`
+ * reads `aliases` from it to build the `.byName()` family.
+ */
+export function emitLookupsBlock(specs) {
+    if (specs.size === 0)
+        return [];
+    const lines = ["  lookups: {"];
+    for (const [field, spec] of specs) {
+        lines.push(`    ${keyLiteral(field)}: {`);
+        if (pyTruthy(spec.objectName))
+            lines.push(`      objectName: ${pyJsonString(spec.objectName)},`);
+        lines.push(`      path: ${pyJsonStringify(spec.path)},`);
+        lines.push(`      by: ${pyJsonStringify(spec.by)},`);
+        lines.push(`      value: ${pyJsonString(spec.value)},`);
+        const aliases = [...spec.aliases].map(([name, alias]) => `${alias}: ${pyJsonString(name)}`).join(", ");
+        lines.push(`      aliases: {${aliases ? ` ${aliases} ` : ""}},`);
+        lines.push(`      strategy: ${pyJsonString(spec.strategy)},`);
+        if (spec.dependsOn && spec.dependsOn.length > 0)
+            lines.push(`      dependsOn: ${pyJsonStringify(spec.dependsOn)},`);
+        lines.push("    },");
+    }
+    lines.push("  },");
+    return lines;
+}
+/** `entry.get("version", "1.0.0")`: the key's value when present, even `null`. */
+function versionOf(entry) {
+    return "version" in entry ? entry.version : "1.0.0";
+}
+/**
+ * A connector EVENT as a `triggerDescriptor()`, the shape `onEvent()` takes.
+ *
+ * The payload type comes from `outputSchema`, and `where` from the entry's
+ * event parameters. An entry that declares none keeps a loose
+ * `Record<string, string>`: that is either an event which genuinely takes no
+ * parameters (HTTP Webhook) or one nothing has described yet, and an empty
+ * interface would refuse every key in both cases.
+ */
+export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+    const nodeType = entry.nodeType;
+    const eventId = afterLast(nodeType, ".");
+    const connectorKey = pyTruthy(entry.connector?.key) ? entry.connector.key : "";
+    const label = pyTruthy(entry.display?.label) ? entry.display.label : eventId;
+    const version = versionOf(entry);
+    const generic = entry.operation?.activityType === "GenericTrigger";
+    const lines = [];
+    let whereType = "Record<string, string>";
+    if (inFields.length > 0) {
+        whereType = `${name}Where`;
+        lines.push(...emitInterface(whereType, false, inputTypes, inputTree, true));
+        lines.push("");
+    }
+    lines.push(...emitInterface(`${name}Outputs`, true, outputTypes, outputTree));
+    lines.push("");
+    // A subscription's `where` values are resolved by `lookup()` exactly as a
+    // connector input's are, so the descriptor carries the same specs.
+    const specs = specsFromFields(inFields, invariant);
+    lines.push("/**");
+    lines.push(` * ${pyStr(label)} — ${nodeType}`);
+    lines.push(" *");
+    if (generic) {
+        lines.push(" * A GENERIC event: it fires for ONE object of the connection (an entity, a");
+        lines.push(` * table, a custom object), so name it — \`onEvent(${name}, { object: '<Object>' })\`.`);
+        lines.push(` * \`uip is triggers objects ${pyStr(connectorKey)} <EVENT> --connection-id <id>\` lists them.`);
+    }
+    else {
+        lines.push(` * Start a flow on it with \`onEvent(${name}, { where: { … } })\`, or pause for it`);
+        lines.push(` * with \`waitForEvent(${name}, { … })\`; \`where\` carries its event parameters.`);
+    }
+    // INSIDE the block: `emitLookupComment` returns bare ` * ` body lines.
+    if (specs.size > 0) {
+        lines.push(" *");
+        lines.push(...emitLookupComment(specs, name));
+    }
+    lines.push(" */");
+    lines.push(`export const ${name} = triggerDescriptor<${whereType}, ${name}Outputs>()({`);
+    lines.push(`  connector: ${pyJsonStringify(connectorKey)},`);
+    lines.push(`  event: ${pyJsonString(eventId)},`);
+    lines.push(`  version: ${pyJsonStringify(version)},`);
+    lines.push(`  displayName: ${pyJsonStringify(label)},`);
+    lines.push(...emitLookupsBlock(specs));
+    lines.push("} as const);");
+    return lines;
+}
+/** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
+export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+    const nodeType = entry.nodeType;
+    const actionId = afterLast(nodeType, ".");
+    const operation = entry.operation ?? {};
+    const isGenericExpanded = operation.activityType === "GenericExpanded";
+    const label = pyTruthy(entry.display?.label) ? entry.display.label : actionId;
+    const version = versionOf(entry);
+    const runtime = entry.runtime ?? {};
+    const inFields = descriptorInputFields(entry, v1def);
+    if (isEventNodeType(nodeType)) {
+        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant);
+    }
+    const lines = [];
+    lines.push(...emitInterface(`${name}Inputs`, false, inputTypes, inputTree, true));
+    lines.push("");
+    lines.push(...emitInterface(`${name}Outputs`, true, outputTypes, outputTree));
+    lines.push("");
+    // An operation whose real field set arrives at design time has an `Inputs`
+    // type that is either empty (no object chosen yet) or just the parents. The
+    // doc comment is the only place the typed surface can say so.
+    const schemaAction = operation.schemaAction ?? {};
+    const specs = lookupSpecs(entry, v1def, invariant);
+    const lookupComment = specs.size > 0 ? emitLookupComment(specs, name) : [];
+    const header = ` * ${pyStr(label)} — ${nodeType}`;
+    if (pyTruthy(operation.objectFromDiscovery)) {
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(" * The object is chosen against the connection, so `Inputs` is empty");
+        lines.push(" * here. List the objects and read the chosen one's fields with");
+        lines.push(" * `uip is resources list` / `describe` before binding this node.");
+        if (lookupComment.length > 0) {
+            lines.push(" *");
+            lines.push(...lookupComment);
+        }
+        lines.push(" */");
+    }
+    else if (pyTruthy(schemaAction.parents)) {
+        const parents = schemaAction.parents.map((x) => `\`${pyStr(x)}\``).join(", ");
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(` * \`Inputs\` carries only the fields that SELECT the schema (${parents}).`);
+        lines.push(` * The real set comes from the \`${pyStr(schemaAction.name)}\` design-time`);
+        lines.push(" * action — describe with those values supplied to see it.");
+        if (lookupComment.length > 0) {
+            lines.push(" *");
+            lines.push(...lookupComment);
+        }
+        lines.push(" */");
+    }
+    else if (lookupComment.length > 0) {
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(...lookupComment);
+        lines.push(" */");
+    }
+    else {
+        lines.push(`/** ${pyStr(label)} — ${nodeType} */`);
+    }
+    lines.push(`export const ${name} = descriptor<${name}Inputs, ${name}Outputs>()({`);
+    lines.push(`  nodeType: ${pyJsonString(nodeType)},`);
+    lines.push(`  version: ${pyJsonStringify(version)},`);
+    if (isGenericExpanded && pyTruthy(operation.objectName)) {
+        lines.push(`  objectName: ${pyJsonStringify(operation.objectName)},`);
+    }
+    if (pyTruthy(runtime.requiresConnection))
+        lines.push("  requiresConnection: true,");
+    if (pyTruthy(runtime.requiresFolderKey))
+        lines.push("  requiresFolderKey: true,");
+    lines.push(...emitLookupsBlock(specs));
+    lines.push("} as const);");
+    return lines;
+}
+/**
+ * The catalog names required inputs but the generated `Inputs` interface is
+ * empty: the descriptor would type-check a call the platform rejects. One line
+ * naming the operation and the fields, or `undefined` when there is no gap.
+ */
+export function requiredInputGap(entry, inputTree) {
+    const required = (entry.inputSchema?.fields || [])
+        .filter((field) => field.required === true)
+        .map((field) => pyStr(pyTruthy(field.name) ? field.name : "<unnamed>"));
+    if (required.length === 0 || inputTree.size > 0)
+        return undefined;
+    const nodeType = "nodeType" in entry ? pyStr(entry.nodeType) : "<unknown node>";
+    return `${nodeType}: catalog requires ${required.join(", ")}, but the generated inputs interface is empty`;
+}
+/**
+ * `mark_lookup_fields`: flag the fields whose TypeScript type must also accept
+ * a `LookupToken` — exactly the set `lookupSpecs` generates helpers for. The
+ * work is `fields.ts`'s `markLookupFields`, which also merges the catalog's
+ * `reference` INTO a field whose own declaration lacks one, as the Python did;
+ * `lookupFieldNote` reads the lookup's target and value from that merged
+ * reference, so the doc comment on the field depends on the merge. This
+ * wrapper only narrows the result to the tree's field type.
+ */
+function markedInputFields(entry, fields, invariant) {
+    return markLookupFields(entry, fields, invariant);
+}
+/**
+ * Render every connector module of the library.
+ *
+ * The Python `main()` wrote every module and only then exited 1 on
+ * {@link DescriptorOutput.requiredInputGaps}; this returns both and the caller
+ * decides. A missing entry or sidecar throws, as the Python did.
+ */
+export function renderDescriptorModules(library, options = {}) {
+    const importSpecifier = options.importSpecifier ?? PACKAGE_NAME;
+    const includeGenericExpanded = options.includeGenericExpanded ?? false;
+    const subset = new Set((options.connectors ?? []).filter((c) => c.length > 0));
+    const invariant = library.invariant;
+    const rows = library.index.entries;
+    // Group Curated + http-request entries by connector key.
+    const byConnector = new Map();
+    for (const row of rows) {
+        if (row.activityType === "GenericExpanded" && !includeGenericExpanded)
+            continue;
+        // A generic EVENT's per-object variants share their template's nodeType and
+        // so would emit the same const twice. Only the template gets a descriptor:
+        // `onEvent(RecordCreated, { object: 'Message' })` names the object as an
+        // option, so one descriptor serves every object.
+        if (row.activityType === "GenericTrigger" && pyTruthy(row.objectName) && !includeGenericExpanded)
+            continue;
+        const key = row.connectorKey;
+        if (subset.size > 0 && !subset.has(key))
+            continue;
+        const group = byConnector.get(key);
+        if (group)
+            group.push(row);
+        else
+            byConnector.set(key, [row]);
+    }
+    // ONE symbol map for the whole run, shared with the Markdown generator.
+    const symbols = symbolIndex(rows, includeGenericExpanded);
+    const modules = new Map();
+    const requiredInputGaps = [];
+    for (const key of sortedStrings(byConnector.keys())) {
+        const inputTypes = new NamedTypeRegistry({ suffix: "Input", allOptional: false, mergeReused: false, isInput: true });
+        const outputTypes = new NamedTypeRegistry();
+        const loaded = [];
+        for (const row of sortedByCodePoint(byConnector.get(key), (r) => r.nodeType)) {
+            const entry = library.readEntry(row);
+            if (entry === undefined)
+                throw new Error(`library entry missing: ${library.entryPath(row)}`);
+            const v1def = library.readV1Def(row);
+            if (v1def === undefined)
+                throw new Error(`library sidecar missing: ${library.v1defPath(row)}`);
+            const isEvent = isEventNodeType(row.nodeType);
+            const operationInputFields = markedInputFields(entry, descriptorInputFields(entry, v1def), invariant);
+            const outputFields = entry.outputSchema?.fields || [];
+            const inputTree = buildTypeTree(operationInputFields);
+            // The required-input gap is a statement about a connector ACTION's
+            // inputs; an event's parameters are optional by construction.
+            const gap = isEvent ? undefined : requiredInputGap(entry, inputTree);
+            if (gap)
+                requiredInputGaps.push(gap);
+            const outputTree = buildTypeTree(outputFields);
+            inputTypes.discover(inputTree);
+            outputTypes.discover(outputTree);
+            loaded.push({ entry, v1def, inputTree, outputTree });
+        }
+        const operations = [];
+        for (const { entry, v1def, inputTree, outputTree } of loaded) {
+            const name = symbols.get(entry.nodeType);
+            if (name === undefined)
+                throw new Error(`no symbol for ${entry.nodeType}: the entry's nodeType is not in index.json`);
+            operations.push(...emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, outputTypes, invariant), "");
+        }
+        const emittedTypes = inputTypes.emit(emitNestedProperty);
+        const rendered = [...emittedTypes, ...operations].join("\n");
+        let specifiers = ["descriptor", "triggerDescriptor"].filter((s) => rendered.includes(`= ${s}<`));
+        if (specifiers.length === 0)
+            specifiers = ["descriptor"];
+        for (const alias of ["ConnectorLookupValue", "ConnectorValue"]) {
+            if (rendered.includes(alias))
+                specifiers.push(`type ${alias}`);
+        }
+        const body = [`import { ${specifiers.join(", ")} } from ${pyJsonString(importSpecifier)};`, ""];
+        body.push(...emittedTypes);
+        body.push(...outputTypes.emit(emitNestedProperty));
+        body.push(...operations);
+        modules.set(`${key}.ts`, `${pyRstrip(body.join("\n"))}\n`);
+    }
+    return { modules, symbols, requiredInputGaps };
+}
+/** The text the Python printed before exiting 1 on gaps; call only with a non-empty list. */
+export function formatRequiredInputGaps(gaps) {
+    return `connector wrapper generation stopped:\n- ${gaps.join("\n- ")}`;
+}

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, ""];
+}