@uipath/maestro-builder-sdk 5.2.0

package/dist/core/list-envelope.d.ts

@@ -0,0 +1,45 @@
+/** One measured operation. `envelope: null` is the BARE array. */
+export interface ListEnvelopeRow {
+    nodeType: string;
+    /** When present, the row applies only to that object of a GENERIC operation. */
+    objectName?: string;
+    /** `null` = the array itself; a string = the single field that holds it. */
+    envelope: string | null;
+    /** A1 debug-record read · A2 product-runtime record · A3 executing archived run. */
+    tier: string;
+    source: string;
+    measuredAt?: string;
+    /**
+     * What `uip is resources run` hands back, when it differs from the runtime
+     * shape. Recorded on eight rows; no current reader consumes it — it exists for
+     * a dispatcher that needs to normalise between the CLI and the platform.
+     */
+    cliShape?: string;
+}
+/**
+ * Every declared row, from `<libraryDir>/list-envelopes.json`. An absent file is
+ * an empty ledger — every operation undeclared — which is what a library built
+ * before this card, or a bare fixture library, looks like.
+ */
+export declare function loadListEnvelopes(libraryDir: string | undefined): ListEnvelopeRow[];
+/**
+ * The row for one operation, or `undefined` when it is undeclared.
+ *
+ * A row naming an `objectName` applies to that object ALONE — the evidence was a
+ * reading of that object, and a generic operation covers up to 197 of them. A row
+ * without one applies to every object of the node type. Exact match wins.
+ */
+export declare function lookupListEnvelope(rows: ListEnvelopeRow[], nodeType: string, objectName?: string): ListEnvelopeRow | undefined;
+/**
+ * Convenience for the readers that hold a library dir rather than the rows.
+ * `{ declared: false }` and `{ declared: true, envelope: null }` are DIFFERENT
+ * answers and every caller must keep them apart: the first means "behave as
+ * before", the second means "this operation is measured, and it is bare".
+ */
+export declare function envelopeOf(libraryDir: string | undefined, nodeType: string, objectName?: string): {
+    declared: false;
+} | {
+    declared: true;
+    envelope: string | null;
+    row: ListEnvelopeRow;
+};

package/dist/core/list-envelope.js

@@ -0,0 +1,97 @@
+/**
+ * list-envelope — read the LIST-ENVELOPE LEDGER that sits beside the connector
+ * library's `index.json`.
+ *
+ * ## What the ledger answers
+ *
+ * A connector LIST operation's node output is either the array itself (**bare**,
+ * `envelope: null`) or that array inside a one-field wrapper object
+ * (`envelope: "records"` ⇒ `{records: […]}`). **Nothing in the library declares
+ * which**: `outputSchema.fields` describes ONE record either way, and the two
+ * operations that declare no fields at all sit on opposite sides of what the
+ * corpus guessed ([#156](https://github.com/UiPath/flow-builder-sdk/issues/156)).
+ * It cannot be derived, so it is measured and written down — one row per
+ * operation, each carrying the evidence that put it there.
+ *
+ * ## The rule this file exists to enforce
+ *
+ * **An operation with no row is UNDECLARED, and undeclared means every reader
+ * behaves exactly as it did before the ledger existed.** The emitter declares no
+ * container, and a reader must go on treating an unknown name on a list output as
+ * a possible wrapper. 2,149 of the shipped library's 7,029 entries are List
+ * operations and the ledger holds eight — that ratio is the design, not a gap.
+ * It grows on demand, one measurement at a time.
+ *
+ * Measured 2026-08-02 (card G13, eight `flow debug` / product-runtime readings):
+ * every operation measured so far is **bare**, including both the corpus called
+ * wrappers. The ledger's own `$comment` carries the mechanism and the evidence
+ * tiers; this module only reads it.
+ *
+ * If a second reader is ever needed outside this package, copy this one rather
+ * than sharing it through a new package boundary: a 40-line JSON reader is the
+ * cheaper half. The LEDGER is the single source of truth — the readers are
+ * interchangeable.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const CACHE = new Map();
+/**
+ * Every declared row, from `<libraryDir>/list-envelopes.json`. An absent file is
+ * an empty ledger — every operation undeclared — which is what a library built
+ * before this card, or a bare fixture library, looks like.
+ */
+export function loadListEnvelopes(libraryDir) {
+    if (!libraryDir)
+        return [];
+    const cached = CACHE.get(libraryDir);
+    if (cached)
+        return cached;
+    let rows = [];
+    const file = join(libraryDir, 'list-envelopes.json');
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (Array.isArray(parsed.operations))
+                rows = parsed.operations;
+        }
+        catch {
+            // A malformed ledger reads as an EMPTY one rather than throwing: the
+            // permissive path is the pre-ledger behaviour, so the worst case of a bad
+            // edit is losing the exactness, never breaking a compile.
+            rows = [];
+        }
+    }
+    CACHE.set(libraryDir, rows);
+    return rows;
+}
+/**
+ * The row for one operation, or `undefined` when it is undeclared.
+ *
+ * A row naming an `objectName` applies to that object ALONE — the evidence was a
+ * reading of that object, and a generic operation covers up to 197 of them. A row
+ * without one applies to every object of the node type. Exact match wins.
+ */
+export function lookupListEnvelope(rows, nodeType, objectName) {
+    let loose;
+    for (const r of rows) {
+        if (r.nodeType !== nodeType)
+            continue;
+        if (r.objectName === undefined) {
+            loose ??= r;
+            continue;
+        }
+        if (objectName !== undefined && r.objectName === objectName)
+            return r;
+    }
+    return loose;
+}
+/**
+ * Convenience for the readers that hold a library dir rather than the rows.
+ * `{ declared: false }` and `{ declared: true, envelope: null }` are DIFFERENT
+ * answers and every caller must keep them apart: the first means "behave as
+ * before", the second means "this operation is measured, and it is bare".
+ */
+export function envelopeOf(libraryDir, nodeType, objectName) {
+    const row = lookupListEnvelope(loadListEnvelopes(libraryDir), nodeType, objectName);
+    return row ? { declared: true, envelope: row.envelope ?? null, row } : { declared: false };
+}

package/dist/core/lookup-store.d.ts

@@ -0,0 +1,22 @@
+import type { LookupResolutions } from './lookups.js';
+/**
+ * Load `<overlayDir>/resolutions.json`, or an empty map.
+ *
+ * An absent or malformed file reads as EMPTY rather than throwing, matching
+ * `loadListEnvelopes`. The consequence of an empty map is not a wrong artifact
+ * — it is a compile error naming the `prepare` command to run, which is the
+ * behaviour an author wants from a missing resolution anyway.
+ */
+export declare function loadLookupResolutions(overlayDir: string | undefined): LookupResolutions;
+/**
+ * The invariant-collection ledger's `objectName` set, from a library dir.
+ *
+ * Absent or malformed reads as EMPTY, which is the permissive direction: an
+ * unlisted collection is treated as a real lookup, which is never wrong — only
+ * occasionally ceremonial. The opposite default would drop the helper from a
+ * genuinely connection-scoped field.
+ *
+ * @param libraryDir - A `library-json` directory, or the local overlay.
+ * @returns Every `objectName` declared connector-invariant.
+ */
+export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;

package/dist/core/lookup-store.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * core/lookup-store — the two on-disk side-tables the lookup surface reads.
+ *
+ * SEPARATE FROM `core/lookups.ts` ON PURPOSE. That module is re-exported from
+ * `flow-sdk.ts`, which is the authoring entry point: a `.flow.ts` imports it,
+ * and so does anything type-checking one. The moment it imported `node:fs`,
+ * every consumer needed `@types/node` on hand to compile a flow — which broke a
+ * generated-trigger gate that had deliberately been checking the authoring
+ * surface with a bare tsconfig.
+ *
+ * Authoring needs the TYPES and the `lookup()` factory; only the compilers and
+ * the CLIs need to read files. Keeping the split makes that structural rather
+ * than a thing to remember.
+ */
+const RESOLUTION_CACHE = new Map();
+/**
+ * Load `<overlayDir>/resolutions.json`, or an empty map.
+ *
+ * An absent or malformed file reads as EMPTY rather than throwing, matching
+ * `loadListEnvelopes`. The consequence of an empty map is not a wrong artifact
+ * — it is a compile error naming the `prepare` command to run, which is the
+ * behaviour an author wants from a missing resolution anyway.
+ */
+export function loadLookupResolutions(overlayDir) {
+    if (!overlayDir)
+        return {};
+    const cached = RESOLUTION_CACHE.get(overlayDir);
+    if (cached)
+        return cached;
+    let rows = {};
+    const file = join(overlayDir, 'resolutions.json');
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (parsed.resolutions && typeof parsed.resolutions === 'object') {
+                rows = parsed.resolutions;
+            }
+        }
+        catch {
+            rows = {};
+        }
+    }
+    RESOLUTION_CACHE.set(overlayDir, rows);
+    return rows;
+}
+/**
+ * The invariant-collection ledger's `objectName` set, from a library dir.
+ *
+ * Absent or malformed reads as EMPTY, which is the permissive direction: an
+ * unlisted collection is treated as a real lookup, which is never wrong — only
+ * occasionally ceremonial. The opposite default would drop the helper from a
+ * genuinely connection-scoped field.
+ *
+ * @param libraryDir - A `library-json` directory, or the local overlay.
+ * @returns Every `objectName` declared connector-invariant.
+ */
+export function loadInvariantCollections(libraryDir) {
+    if (!libraryDir)
+        return new Set();
+    const cached = INVARIANT_CACHE.get(libraryDir);
+    if (cached)
+        return cached;
+    const out = new Set();
+    const file = join(libraryDir, 'invariant-collections.json');
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (Array.isArray(parsed.collections)) {
+                for (const row of parsed.collections) {
+                    const name = row?.objectName;
+                    if (typeof name === 'string')
+                        out.add(name);
+                }
+            }
+        }
+        catch {
+            /* an empty ledger — see above */
+        }
+    }
+    INVARIANT_CACHE.set(libraryDir, out);
+    return out;
+}
+const INVARIANT_CACHE = new Map();

package/dist/core/lookups.d.ts

@@ -0,0 +1,227 @@
+/** How `prepare` should retrieve the collection, chosen from the metadata. */
+export type LookupStrategy = 
+/** `filterPattern` present — substitute `{filter}` and issue one request. */
+'filter'
+/** No server-side filter — page the collection and match client-side. */
+ | 'scan'
+/** `childPath` present — the collection is a tree to walk. */
+ | 'tree'
+/** `dependsOn` present — another field must resolve first. */
+ | 'dependent';
+/**
+ * One lookup field's retrieval contract, generated from `reference`.
+ *
+ * This is DATA on the descriptor, not a type surface. The generator's existing
+ * scale guards (`TS_MAX_TYPE_DEPTH`, `TS_MAX_FIELD_COUNT_PER_ENTRY`) exist
+ * because NetSuite already pushes `tsc`, and a thousand more *type* surfaces
+ * would make that worse for no gain. The one place types are derived from it —
+ * {@link LookupBuilder}'s alias methods — is a mapped type over an object
+ * literal that is only instantiated at a call site, so it costs nothing on the
+ * modules nobody imports.
+ */
+export interface LookupSpec {
+    /** The collection holding the records, e.g. `curated_users`. */
+    objectName?: string;
+    /** The path to call, filter included, e.g. `/curated_users?fields=id`. */
+    path: string;
+    /** Every field the collection can be searched by. */
+    by: readonly string[];
+    /** The field whose value is sent to the connector, e.g. `id`. */
+    value: string;
+    /** `{ byEmail: 'profile.email' }` — only for names with an unambiguous alias. */
+    aliases: Readonly<Record<string, string>>;
+    strategy: LookupStrategy;
+    /** For `strategy: 'dependent'`, the fields that must resolve first. */
+    dependsOn?: readonly string[];
+}
+/**
+ * An unresolved lookup: what `.byEmail(…)` returns.
+ *
+ * Deliberately a plain branded object rather than an `Expr`. An `Expr` renders
+ * to a runtime expression string and would silently reach the wire; this must
+ * not render at all until something has resolved it, so it carries no `render`
+ * and `renderDeep` refuses it.
+ */
+export interface LookupToken {
+    readonly __lookup: {
+        readonly nodeType: string;
+        readonly field: string;
+        readonly by: string;
+        readonly value: unknown;
+    };
+}
+/** True when `v` is an unresolved {@link LookupToken}. */
+export declare function isLookupToken(v: unknown): v is LookupToken;
+/**
+ * The identity of one resolution, as `prepare` records it and `compile` reads it.
+ *
+ * JSON-encoded rather than delimiter-joined because every component is
+ * author-supplied text: a real name containing the delimiter would collide two
+ * distinct resolutions onto one key, and the symptom would be a flow compiled
+ * with the wrong person's id.
+ */
+export declare function lookupKey(nodeType: string, field: string, by: string, value: unknown): string;
+/** What `lookup(...)` returns: the generic form plus any generated aliases. */
+export type LookupBuilder<S extends LookupSpec | undefined = undefined> = S extends LookupSpec ? {
+    by(name: S['by'][number], value: unknown): LookupToken;
+} & {
+    [K in keyof S['aliases']]: (value: unknown) => LookupToken;
+} : {
+    by(name: string, value: unknown): LookupToken;
+};
+/**
+ * The descriptor shape `lookup()` needs — a nodeType plus its lookup table.
+ *
+ * @internal Structural constraint for the overload; not an authoring surface.
+ */
+interface LookupBearing {
+    nodeType: string;
+    lookups?: Readonly<Record<string, LookupSpec>>;
+}
+/**
+ * A trigger descriptor that DOES carry a lookup table.
+ *
+ * `lookups` is required here so a descriptor without one still falls through to
+ * the loose event overload rather than being typed against an empty table.
+ *
+ * @internal Structural constraint for the overload; not an authoring surface.
+ */
+interface EventLookupBearing {
+    connector: string;
+    event: string;
+    nodeType?: undefined;
+    lookups: Readonly<Record<string, LookupSpec>>;
+}
+/**
+ * Begin resolving a lookup field on a generated descriptor.
+ *
+ * @param descriptor - A generated operation carrying a `lookups` table.
+ * @param field - The lookup field, e.g. `'channel'`.
+ * @returns A builder exposing `.by(name, value)` and one method per generated alias.
+ */
+export declare function lookup<D extends LookupBearing, F extends keyof NonNullable<D['lookups']> & string>(descriptor: D, field: F): LookupBuilder<NonNullable<D['lookups']>[F] extends LookupSpec ? NonNullable<D['lookups']>[F] : never>;
+/**
+ * Begin resolving a lookup field addressed by connector key and action.
+ *
+ * @remarks
+ * The string form exists because Generic CRUD operations are authored from the
+ * library by object rather than through a descriptor — and the generic half of
+ * the library carries 710 of the 1,365 lookup fields, so a descriptor-only
+ * helper would miss the majority of its own surface.
+ *
+ * It gives up exactly what `connector(key, action, …)` already gives up beside
+ * `connector(descriptor, …)`: the field name is unchecked until `check` runs,
+ * and there are no typed aliases, so only the generic `.by(name, value)` is
+ * available. A consistent trade rather than a new one.
+ *
+ * @param key - The connector library key, e.g. `'uipath-salesforce-slack'`.
+ * @param action - The operation id, e.g. `'send-message-to-user'`.
+ * @param field - The lookup field, e.g. `'channel'`.
+ * @returns A builder exposing `.by(name, value)`.
+ */
+export declare function lookup(key: string, action: string, field: string): LookupBuilder;
+/**
+ * Begin resolving a `where` parameter on a trigger descriptor that carries a
+ * lookup table.
+ *
+ * @remarks
+ * An event parameter holding an id is resolved exactly as a connector input is,
+ * against the same `reference` block, so a generated trigger descriptor carries
+ * the same `lookups` table and earns the same aliases —
+ * `lookup(EmailReceived, 'parentFolderId').byDisplayName('Inbox')`.
+ *
+ * @param descriptor - A trigger descriptor carrying a `lookups` table.
+ * @param field - The event parameter, e.g. `'parentFolderId'`.
+ * @returns A builder exposing `.by(name, value)` and one method per generated alias.
+ */
+export declare function lookup<D extends EventLookupBearing, F extends keyof D['lookups'] & string>(descriptor: D, field: F): LookupBuilder<D['lookups'][F] extends LookupSpec ? D['lookups'][F] : never>;
+/**
+ * Begin resolving a `where` parameter on a connector-EVENT descriptor.
+ *
+ * @remarks
+ * A trigger descriptor carries `connector` + `event`, never a `nodeType`. The
+ * token is keyed under the EVENT-form node type
+ * (`uipath.connector.event.<connector>.<event>`), which is the form `prepare`
+ * records resolutions under and the form both node roles resolve to. A
+ * descriptor that ships no `lookups` table — an event nothing has described, or
+ * one whose parameters hold no ids — offers only the generic
+ * `.by(name, value)`, same trade as the string form: the `by` is checked by
+ * `prepare`, not here.
+ *
+ * @param descriptor - A trigger descriptor (or `{ connector, event }` literal).
+ * @param field - The event parameter, e.g. `'parentFolderId'`.
+ * @returns A builder exposing `.by(name, value)`.
+ */
+export declare function lookup(descriptor: {
+    connector: string;
+    event: string;
+    nodeType?: undefined;
+}, field: string): LookupBuilder;
+/** One recorded resolution, as `connectors-local/resolutions.json` stores it. */
+export interface LookupResolution {
+    nodeType: string;
+    field: string;
+    by: string;
+    /** The human-meaningful value the author wrote. */
+    match: string;
+    /** The opaque id the connector wants. */
+    value: string;
+}
+/** Every recorded resolution, keyed by {@link lookupKey}. */
+export type LookupResolutions = Readonly<Record<string, LookupResolution>>;
+/**
+ * The recorded id for a token, or `undefined`.
+ *
+ * @param token - The unresolved lookup.
+ * @param resolutions - Everything `prepare --resolve` has recorded.
+ * @returns The connector-facing id, when this exact `(nodeType, field, by, value)` was resolved.
+ */
+export declare function resolvedValue(token: LookupToken, resolutions: LookupResolutions): string | undefined;
+/**
+ * The message for a lookup nothing has resolved — the command that fixes it.
+ *
+ * A missing resolution is the same class of error as a missing schema, and it
+ * reads the same way on purpose: name the thing, then print the one command.
+ *
+ * @param token - The unresolved lookup.
+ * @returns A diagnostic whose last line can be pasted into a shell.
+ */
+export declare function unresolvedLookupMessage(token: LookupToken): string;
+type RawReference = {
+    objectName?: string;
+    path?: string;
+    lookupNames?: string[];
+    lookupValue?: string;
+    filterPattern?: string;
+    childPath?: string;
+    dependsOn?: string[];
+} | undefined;
+/**
+ * The {@link LookupSpec} for one field, or `undefined` when it earns no helper.
+ *
+ * @param reference - The field's raw registry `reference` block.
+ * @param invariant - `objectName`s the ledger declares connector-invariant.
+ * @returns The spec a `.by*` helper would be generated from, or `undefined`.
+ */
+export declare function lookupSpecOf(reference: RawReference, invariant?: ReadonlySet<string>): LookupSpec | undefined;
+/**
+ * Refuse a lookup token where the family cannot resolve one.
+ *
+ * `lookup()` is a FLOW surface today: only `serialize.ts` substitutes a
+ * recorded resolution, and only `check.ts` reports an unresolved one. Case and
+ * BPMN pass connector input values straight into their emitted payload, so a
+ * token reaching either one is embedded verbatim — a `.case` carrying
+ * `{"__lookup": {…}}` where the connector expects an id.
+ *
+ * That is silent wrongness, which is the failure this whole surface exists to
+ * remove; emitting it from the tool that removes it would be the worst possible
+ * outcome. Until Case and BPMN read `resolutions.json` too, they refuse the
+ * token and say so.
+ *
+ * @param value - A connector input value.
+ * @param family - The authoring family, for the message.
+ * @param field - The input name, for the message.
+ * @throws If `value` is an unresolved {@link LookupToken}.
+ */
+export declare function refuseLookupToken(value: unknown, family: string, field: string): void;
+export {};