@uipath/maestro-builder-sdk 5.2.0

package/dist/core/library.d.ts

@@ -0,0 +1,440 @@
+import { type LookupResolutions, type LookupSpec } from './lookups.js';
+export interface ResolvedConnector {
+    nodeType: string;
+    version: string;
+    /** connector key, e.g. "uipath-salesforce-slack" */
+    connectorKey: string;
+    connectorName: string;
+    httpMethod: string;
+    endpoint: string;
+    /** stable per-(connector, action) id required by uip >= 1.2 */
+    activityTypeId?: string;
+    /** the Flow definitions[] entry */
+    v1def: any;
+    /** the raw library entry (connector + operation metadata) */
+    entry: any;
+    /**
+     * The connector's activity input vocabulary: [{ name, type, required, location }].
+     *
+     * The union of TWO declarations, because the platform splits a connector
+     * operation's inputs across two files (see `readFields`):
+     *   * the v1def's `inputDefinition.fields` — the request BODY;
+     *   * the entry's `operation.parameters` — the QUERY and PATH parameters,
+     *     each tagged with its `type`.
+     * `location` says which, and is what `serialize` routes on.
+     */
+    fields: ConnectorField[];
+    /**
+     * The operation's multipart TRANSPORT parts, in declaration order — what
+     * `detail.multipartParameters` lists, whether or not the author supplies a value.
+     *
+     * A `file` part is also an author input (it appears in `fields` with
+     * `location: 'multipart'` and carries the author's value). A part of any other
+     * dataType (`string` for all 105 in the shipped library — Teams `body`, Gmail
+     * `body`, GenAI `RagRequest`) is a CONTAINER the runtime composes from
+     * `bodyParameters`: it is listed here, never in `fields`, and is emitted
+     * without a value. See `readFields`.
+     */
+    multipartParts: MultipartPart[];
+    /**
+     * Which OBJECT this resolved operation addresses — `''` for an operation that
+     * has none (the `*.http-request` passthroughs; 38 of 7,029 entries).
+     */
+    objectName: string;
+    /**
+     * True when the object came from the AUTHOR and no library entry names it — a
+     * connection-scoped object (`acr_user`). The schema is a sibling entry's, so
+     * `compile` cannot check this operation's inputs against the real thing, and
+     * the tenant is what resolves the name. Recorded rather than dropped, so a
+     * downstream reader can tell an author-supplied object from a resolved one.
+     */
+    objectNameUnverified?: boolean;
+    /**
+     * The measured LIST envelope for this operation, or `undefined` when it is
+     * UNDECLARED (see `core/list-envelope.ts` for what the two mean and why the
+     * difference is load-bearing). `{envelope: null}` is a measured BARE array;
+     * `{envelope: 'records'}` is a measured `{records: […]}` wrapper.
+     *
+     * An OVERLAY entry may carry `envelope` on the entry JSON itself and it wins
+     * over the ledger — that is how a connection-scoped `prepare-connector` result
+     * declares one for an operation the shipped ledger has never measured.
+     */
+    listEnvelope?: {
+        envelope: string | null;
+        source: string;
+        tier: string;
+    };
+}
+/**
+ * Where a connector input rides on the wire.
+ *
+ * No operation in the shipped library declares a `header` parameter (measured
+ * over all 7,029 entries — 10,705 `query`, 4,161 `path`, 105 `multipart`, zero
+ * `header`). The platform knows a `headers` slot because a *configuration*
+ * `fieldsContainer` can carry `fieldLocation: 'header'`; that is a different
+ * vocabulary, and inventing the surface here would be an unevidenced field.
+ */
+export type FieldLocation = 'body' | 'query' | 'path' | 'multipart';
+/** One multipart transport part: `{ name, dataType }` as the platform lists it. */
+export interface MultipartPart {
+    name: string;
+    dataType: string;
+}
+export interface ConnectorField {
+    name: string;
+    type?: string;
+    required?: boolean;
+    displayName?: string;
+    /**
+     * The wire slot this input goes to — `inputs.detail.{body,query,path}Parameters`
+     * / `detail.headers`. Defaults to `body`, which is where an `inputDefinition`
+     * field goes and where an untagged input has always gone.
+     */
+    location?: FieldLocation;
+    /** A one-line description, when the declaration carries one (parameters do). */
+    description?: string;
+    /**
+     * The resolvable-value contract, when the declaration carries one.
+     *
+     * Preserved rather than dropped so `check` can say "this is a lookup field"
+     * about a pasted literal. It is the raw registry block, not the generated
+     * `LookupSpec` — the classification that decides whether a helper exists at
+     * all lives in the generator (`_lookups.py`) and is mirrored by
+     * {@link lookupSpecOf} here.
+     */
+    reference?: {
+        objectName?: string;
+        path?: string;
+        lookupNames?: string[];
+        lookupValue?: string;
+        filterPattern?: string;
+        childPath?: string;
+        dependsOn?: string[];
+    };
+}
+/** The authored connector identity recovered from an already-resolved wire payload. */
+export interface ConnectorActionIdentity {
+    key: string;
+    action: string;
+    version: string;
+    object?: string;
+}
+/** The authored connector event identity recovered from a resolved payload. */
+export interface ConnectorEventIdentity {
+    key: string;
+    event: string;
+    version: string;
+    /** The author-chosen object of a GENERIC event (`record-created` on one entity); absent for a curated one. */
+    object?: string;
+}
+/**
+ * What a library says about a connector event's subscription contract — the
+ * `where` half (its event parameters) and the object half.
+ *
+ * `known: false` means the library declares nothing either way; `names: []` with
+ * `known: true` means "this operation takes NO event parameters". `generic` marks
+ * a GENERIC event (`activityType: GenericTrigger`): its node type covers every
+ * object of the connection, so the author must name one — `object` is then the
+ * entry's own object, `''` for a generic entry and the built-in object of a
+ * curated one (`Message` for Outlook `email-received`).
+ */
+export interface EventParameterFields {
+    known: boolean;
+    names: string[];
+    generic: boolean;
+    object: string;
+    /**
+     * Required parameters that SELECT the event's schema rather than scope its
+     * subscription — Jira's `project` and `issuetype`, both required and
+     * query-bucket, are what its filter and output fields are derived from.
+     * `uip is triggers describe` accepts no parameter values, so wherever this
+     * is non-empty the discovered filter vocabulary is a BASELINE that the real
+     * one extends, and `check` softens its unknown-field rule accordingly.
+     */
+    selectors: string[];
+    /**
+     * The subscription named an object this library has no variant for, on a
+     * connector whose objects come from the CONNECTION. The generic template
+     * answers in its place — which is why nothing used to notice — but it
+     * carries no object's vocabulary, so the author owes a `prepare --object`.
+     */
+    objectUnprepared: boolean;
+    /**
+     * The connector discovers CUSTOM FIELDS per connection
+     * (`hasCustomFieldDiscovery`) and no overlay has prepared this event, so the
+     * baked vocabulary is a strict subset of the tenant's by design. A field
+     * outside it may be perfectly real, which is the difference between an
+     * error and a warning.
+     */
+    customFieldsUnprepared: boolean;
+    /**
+     * The filter vocabulary is a subset NO `prepare` can complete, because this
+     * connector's schema comes from the connection and the trigger metadata call
+     * accepts no parent values. The activity path has `-f` / `--action` and so
+     * has no equivalent — this is the event-only half of the same story.
+     */
+    filtersPartial: boolean;
+}
+/**
+ * What `check` can know, OFFLINE, about whether a connector step's schema is
+ * in hand — the fact behind the OBJECT_UNPREPARED / CUSTOM_FIELDS_UNPREPARED
+ * warnings. Three kinds, matching the three connector discovery shapes:
+ *
+ *  - `object` — a Generic operation addressed by `{ object }` (SFDC
+ *    insert-record on `Company__c`): the schema exists per object, only after
+ *    `registry prepare --object` materializes it into the overlay;
+ *  - `customFields` — a curated operation whose REAL field set is
+ *    connection-resolved (Zoho Desk create-ticket: `hasCustomFieldDiscovery`):
+ *    the baked fields are a subset, the tenant's custom fields arrive only
+ *    from a prepare;
+ *  - `static` — nothing owed (Slack send-message: the schema is baked).
+ */
+export interface SchemaReadiness {
+    kind: 'object' | 'customFields' | 'static';
+    /** True when the local layers already carry what the step needs. */
+    prepared: boolean;
+    /** A materialized variant whose objectName differs only by case — the fix is
+     *  usually to use this spelling, so it travels as the suggestion. */
+    canonical?: string;
+    /** For `customFields`: the field names the tenant-agnostic snapshot carries,
+     *  so the caller can warn ONLY about inputs outside it. */
+    bakedFields?: readonly string[];
+}
+export interface LibraryOpts {
+    /**
+     * An ephemeral, connection-scoped overlay dir (`./connectors-local/`) produced
+     * by `prepare-connector`/`prepare-trigger`. Searched BEFORE the baked library,
+     * so a locally-prepared entry (with the full connection-resolved field schema)
+     * takes precedence. Auto-detected by the compile CLIs next to the
+     * `.flow.ts`/`.case.ts`/`.bpmn.ts`, mirroring `bindings.json`.
+     *
+     * When the same op exists in BOTH layers the field sets are UNIONED, not
+     * replaced: the overlay's definition wins per field name (it is
+     * connection-resolved), but a field the baked library already had is never
+     * dropped. This keeps `prepare-connector` strictly additive — fetching a live
+     * schema can only ADD accepted fields, never silently remove ones the baked
+     * library exposed (a thin `describe` response must not shrink what compiles).
+     */
+    overlayDir?: string;
+}
+export declare class Library {
+    private layers;
+    /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
+    private envelopeRows;
+    /**
+     * Everything `prepare --resolve` has recorded, from the overlay only.
+     *
+     * Never from the baked library: a resolution is a fact about ONE tenant's
+     * data, so shipping one in the published archive would hand every consumer an
+     * id from someone else's connection.
+     */
+    readonly lookupResolutions: LookupResolutions;
+    /** Collections the ledger declares connector-invariant; overlay unions over baked. */
+    private readonly invariantCollections;
+    constructor(dir: string, opts?: LibraryOpts);
+    /**
+     * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
+     *
+     * `objectName` picks WHICH object a **generic** operation addresses; see
+     * {@link Library.resolveType} for what happens when it is omitted on a
+     * nodeType that needs it, and when it names an object the library has never
+     * heard of.
+     *
+     * The event family lives under two sibling namespaces and is resolved by
+     * `resolveEvent` below — same files, same sidecar convention, different
+     * position in the flow.
+     */
+    /**
+     * One operation's resolvable lookup fields, keyed by the WIRE field name.
+     *
+     * The same set the descriptor generator emits helpers for, decided by the same
+     * rules ({@link lookupSpecOf}) over the same field vocabulary — so a `check`
+     * diagnostic can never name a `.by*` the generator did not write.
+     *
+     * @param key - Connector library key.
+     * @param action - Operation id.
+     * @param version - Pin an operation version; newest otherwise.
+     * @param objectName - The object a generic operation addresses.
+     * @returns `{ field: spec }`, empty when the operation has no resolvable lookups.
+     */
+    lookupSpecs(key: string, action: string, version?: string, objectName?: string): Record<string, LookupSpec>;
+    resolve(key: string, action: string, version?: string, objectName?: string): ResolvedConnector;
+    /**
+     * Whether a connector step's schema is materialized locally — see
+     * {@link SchemaReadiness}. Index rows are enough for the `object` question
+     * (activityType + objectName travel on every row); the `customFields`
+     * question reads one canonical entry, because the discovery flags and
+     * `requiresConnectionForSchema` live there and nowhere thinner.
+     *
+     * `undefined` means "this library has never heard of the operation", which
+     * is a different answer from "unprepared": the caller fails open on it, the
+     * same rule every other check callback follows.
+     */
+    schemaReadiness(key: string, action: string, version?: string, object?: string): SchemaReadiness | undefined;
+    /**
+     * Reverse a resolved connector activity back to the symbolic authoring key.
+     * Case decompile uses the same library that compile will use, so it never has
+     * to guess an action name from a display label.
+     */
+    identifyAction(wire: {
+        connectorKey: string;
+        httpMethod?: string;
+        endpoint?: string;
+        objectName?: string;
+        version?: string;
+    }): ConnectorActionIdentity;
+    /**
+     * Resolve a connector EVENT: the START trigger
+     * (`uipath.connector.trigger.<key>.<event>`, a bpmn:StartEvent — the flow
+     * begins when the event fires) or the mid-flow wait
+     * (`uipath.connector.event.<key>.<event>`, a bpmn:ReceiveTask — the flow pauses
+     * until it fires). The platform ships both for one connector operation, with
+     * the same `uiPathActivityTypeId`; the namespace is the only difference.
+     */
+    /**
+     * The connector's discovery classification, from whichever layer carries it.
+     *
+     * `resolveType` takes METADATA from the highest-priority layer, and a
+     * `prepare-connector` overlay writes `connector: { key }` with no
+     * `discovery` block — and a `runtime.requiresConnectionForSchema: false`
+     * that CONTRADICTS the baked library (jira is `hasFieldDiscovery: true`
+     * there). So reading discovery off the resolved entry silently reclassifies
+     * every prepared connector as static, which is exactly backwards: preparing
+     * is what an author does on the connectors whose schema comes from the
+     * connection. Fields legitimately come from the overlay; this connector-level
+     * fact does not, so it is read across layers and the first real block wins.
+     */
+    private connectorDiscovery;
+    resolveEvent(kind: 'trigger' | 'event', key: string, event: string, version?: string, objectName?: string): ResolvedConnector;
+    /**
+     * Reverse a resolved connector event payload back to its symbolic event name.
+     * Case decompile uses the same library that compile will use, mirroring
+     * {@link identifyAction} for connector activities.
+     */
+    identifyEvent(kind: 'trigger' | 'event', wire: {
+        connectorKey: string;
+        objectName?: string;
+        eventOperation?: string;
+        eventMode?: string;
+        version?: string;
+    }): ConnectorEventIdentity;
+    /**
+     * The EVENT PARAMETERS a connector event operation declares — the `where` half
+     * of a subscription — or `undefined` if the library has never heard of the
+     * operation.
+     *
+     * `{ known: true, names: [] }` and `undefined` are DIFFERENT answers, and the
+     * difference is the whole reason this method exists: "this operation takes no
+     * event parameters" is a fact (HTTP Webhook scopes by the connection, so its
+     * only correct `where` is `{}`), while "I could not look it up" is not. Reading
+     * an empty list as "none declared, so scope it anyway" is what made
+     * `EVENT_NO_SCOPE` reject correct authoring for four of the FIVE event
+     * OPERATIONS the deployed corpus contains.
+     *
+     * Two declaration sites, in order of authority:
+     *
+     *  1. the v1def's `eventParameters.fields` — the registry's OWN enrichment,
+     *     returned verbatim by `uip maestro flow registry get <trigger nodeType>
+     *     --connection-id <id>`. Present only on the `.trigger.` form (IS enriches
+     *     per node type, not per operation), so the pair is tried together;
+     *  2. the entry's `inputSchema.fields`, where a curated def declares them as
+     *     `eventParameters.<name>` alongside `filter.<name>` — PR 10's convention.
+     *
+     * Note this is the one family where `inputSchema.fields` IS authoritative. For
+     * connector ACTIONS it is a lossy third summary (`readFields`' doc comment: 5,243
+     * of 7,029 entries disagree with the union) — but both event node types ship
+     * `inputDefinition: {}` in every version, so there is no other declaration to
+     * disagree with, and the whole population is the curated overlay's four defs (the
+     * raw library snapshot carries ZERO trigger/event entries).
+     */
+    eventParameterFields(key: string, event: string, objectName?: string): EventParameterFields | undefined;
+    /**
+     * The filterable-field names a connector event declares — the vocabulary a
+     * `filters` leaf may name.
+     *
+     * TWO SOURCES, because the platform builds the two kinds of event's filter
+     * list differently, and reading one array for both under-advertises the
+     * generic form by an order of magnitude:
+     *
+     *  - a CURATED event filters on the fields its definition MARKS
+     *    (`order: 1` / `isCuratedEventField`), which is what `triggers describe`
+     *    returns as `FilterFields` and what lands in `v1def.filterFields.fields`.
+     *    Outlook `email-received`: 15 of the Message resource's 73 fields.
+     *  - a GENERIC event filters on EVERY field the object supports GET on,
+     *    which is exactly `triggers describe`'s `OutputFields` and lands in the
+     *    entry's `outputSchema.fields`. Verified against the connector
+     *    definitions: jira `issue` 323 fields → 258 GET → 258 output; outlook
+     *    `Message` 73 → 73 → 73; gmail `Message` 33 → 33 → 33.
+     *
+     * Reading `filterFields` for both is what made jira `record-created`
+     * advertise 2 filterable fields where the designer offers 258, and gmail
+     * `new-record-created` advertise none where it offers 33. The union is taken
+     * on the generic side rather than a swap, so a connector that populates both
+     * (outlook's generic form carries its curated sibling's 15) loses nothing.
+     *
+     * Only a connection-scoped prepare or an enriched generation writes either
+     * array: the thin baked manifests carry none, and for them this answers
+     * `undefined` (unknown), never `[]` (known-empty). A GENERIC event's
+     * vocabulary is per object, so pass the subscription's `object` to select
+     * the prepared variant.
+     */
+    eventFilterFields(key: string, event: string, objectName?: string): string[] | undefined;
+    /**
+     * Resolve one library entry for `nodeType`. Two orthogonal concerns compose:
+     *  - **object selection** within a layer — a GENERIC operation encodes only the
+     *    verb in its node type and the library expands it into one entry per object,
+     *    so `objectName` picks which. See `resolveInLayer` for the four cases (#143).
+     *  - **field union** across layers — a connection-scoped overlay
+     *    (`prepare-connector`) is searched before the baked library, and the fields
+     *    of the entries each layer resolves are UNIONED: the overlay can ADD fields
+     *    but never drop ones the baked library already exposed (C4).
+     */
+    private resolveType;
+    /**
+     * Turn a lookup miss into something actionable: which operations this connector
+     * DOES carry, the nearest spelling to what was asked for, and where the library
+     * being searched actually is.
+     *
+     * Without this the message was a dead end. In the 2026-09-09 case eval an agent
+     * read the tenant's `objectName` (`send-mail-v2`) off `uip maestro case spec`
+     * and passed it as the OPERATION slug; the real slug is `send-email`, and
+     * `connector not in library: …send-mail-v2.` said nothing that would reveal
+     * that. It resorted to grepping the library's JSON out of `node_modules`.
+     */
+    private describeMiss;
+    /**
+     * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
+     * GENERIC operation. Returns undefined when the layer does not carry the op;
+     * throws on an author error (a missing/ambiguous object). The four cases (#143):
+     * (1) one entry — resolved (a disagreeing `objectName` is an error, unless the
+   * entry is an un-expanded GENERIC — then accepted connection-scoped like case 4);
+     * (2) many + matching `objectName` — that entry; (3) many + no `objectName` — a
+     * named error listing the objects; (4) many + an unlisted object — accepted with
+     * a warning, synthesized from a sibling entry with the object stamped in. A
+     * connector's object set belongs to the CONNECTION, not to the registry snapshot,
+     * and the platform's designer resolves such objects live.
+     */
+    private resolveInLayer;
+    /**
+     * Pick the sibling entry a connection-scoped object borrows its schema from:
+     * the first whose path template is exactly `/<its own objectName>`, else the
+     * first whose template merely CONTAINS its object name, else the first entry.
+     * Index order breaks every tie, so the choice is stable across builds.
+     */
+    private pickDerivationSibling;
+    private build;
+    /**
+     * The measured LIST envelope for one resolved operation, if any.
+     *
+     * Two sources, entry-first: an OVERLAY entry may declare `envelope` on the
+     * entry JSON (a `prepare-connector` result that measured it live), and that
+     * wins; otherwise the shipped ledger beside `index.json`. Nothing is inferred
+     * — an operation the ledger has never measured comes back undeclared, and
+     * every consumer treats that as "behave exactly as before" (#156).
+     *
+     * Fenced to the LIST verb: the envelope question is only about a collection,
+     * and a row against a non-List operation would be a ledger mistake, so it is
+     * ignored rather than honoured.
+     */
+    private resolveListEnvelope;
+}