@uipath/maestro-builder-sdk 6.70.0 → 6.70.2

package/dist/core/carried-connector-fields.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Connector input fields a decompiled task CARRIES — the plan's own field
+ * declarations for the ones the connector library does not list (#1362).
+ *
+ * The published library is a snapshot, and a connector keeps shipping after it
+ * is taken. Studio Web saves a connector activity against the LIVE connector,
+ * and writes that connector's field list into the activity's configuration
+ * (`optionalConfiguration.fieldsContainer.inputFields`). So a Designer plan can
+ * use a field the library has never heard of: Outlook `get-email-list` saved at
+ * connector 1.47.0 carries `bodyFormat: "html"`, and the library's entry has no
+ * `bodyFormat`. With the library as the only field authority, `check` and
+ * `compile` refused that untouched field as `unknown input`, and the easy way
+ * past the refusal was to delete it: a silent change to the task.
+ *
+ * Decompile now copies the saved declaration of each field the library lacks
+ * into the task's source (`carriedFields`), and `check` and `compile` read the
+ * operation's fields as the library's plus the carried ones. This is the same
+ * idea as Flow's carried node definitions (`core/carried-definitions.ts`): the
+ * file's own definition is the third source, after the SDK and the library.
+ *
+ * It only ever ADDS a name. A field the library declares keeps the library's
+ * type, location and `required`, whatever the carried copy says, so a carried
+ * list cannot relax a check the library makes. And a carried field is accepted,
+ * never demanded: the library's own fields are the required contract.
+ *
+ * For instance, with `carriedFields: [{ name: 'bodyFormat', type: 'string',
+ * location: 'query' }]`, the input `{ bodyFormat: 'html' }` compiles to
+ * `queryParameters.bodyFormat = "html"`; without it, compile refuses it.
+ */
+import type { FieldLocation, ResolvedConnector } from './library.js';
+/** Where a carried field rides on the wire: the request body, the query string or the path. */
+export type CarriedFieldLocation = Extract<FieldLocation, 'body' | 'query' | 'path'>;
+/**
+ * One input field a connector task carries from the plan it was decompiled from.
+ *
+ * Written by decompile, copied from the activity's saved field list. It is not an
+ * authoring surface: an input the connector library already declares is checked
+ * against the library, whatever is carried.
+ */
+export interface CarriedConnectorField {
+    /** The field's name, as the saved field list names it, e.g. `bodyFormat`. */
+    name: string;
+    /** The wire slot the saved field list names (`fieldLocation`). */
+    location: CarriedFieldLocation;
+    /** `string`, `number`, `boolean`, `array` or `object`, when the saved field declares one. */
+    type?: string;
+}
+/**
+ * Why `fields` cannot be carried, or `undefined` when it can.
+ *
+ * For instance `[{ name: 'bodyFormat', location: 'header' }]` is refused: a
+ * header is no slot the connector wire has.
+ */
+export declare function carriedConnectorFieldsRefusal(fields: unknown, where: string): string | undefined;
+/**
+ * `rc` with each carried field the library does not declare appended to its
+ * fields, as an optional input. A name the library declares keeps the library's
+ * declaration. `fields` must have passed {@link carriedConnectorFieldsRefusal}.
+ */
+export declare function withCarriedFields(rc: ResolvedConnector, fields: readonly CarriedConnectorField[] | undefined): ResolvedConnector;
+/**
+ * The fields a saved activity configuration declares that `rc` does not, as
+ * decompile carries them: from `optionalConfiguration.fieldsContainer.inputFields`,
+ * request fields only, in the saved order. Empty when the configuration has no
+ * field list (an SDK-compiled plan writes the essential half only), or every
+ * saved field is in the library. A saved field on a slot the connector wire has
+ * no place for (a `header`) is not carried.
+ *
+ * @param configuration - The parsed `=jsonString:` configuration blob.
+ */
+export declare function savedFieldsMissingFromLibrary(configuration: unknown, rc: ResolvedConnector): CarriedConnectorField[];

package/dist/core/carried-connector-fields.js

@@ -0,0 +1,80 @@
+import { ownEntry } from './own-entry.js';
+const LOCATIONS = { body: 'body', query: 'query', path: 'path' };
+const TYPES = {
+    string: 'string', boolean: 'boolean', number: 'number', integer: 'number', array: 'array', object: 'object',
+};
+/**
+ * Why `fields` cannot be carried, or `undefined` when it can.
+ *
+ * For instance `[{ name: 'bodyFormat', location: 'header' }]` is refused: a
+ * header is no slot the connector wire has.
+ */
+export function carriedConnectorFieldsRefusal(fields, where) {
+    if (fields === undefined)
+        return undefined;
+    if (!Array.isArray(fields))
+        return `${where}: carriedFields must be an array of { name, location, type? } fields.`;
+    const seen = new Set();
+    for (const field of fields) {
+        const f = field;
+        if (!f || typeof f !== 'object' || typeof f.name !== 'string' || !f.name)
+            return `${where}: a carried field must name itself with a non-empty string.`;
+        if (typeof f.location !== 'string' || ownEntry(LOCATIONS, f.location) === undefined)
+            return `${where}: carried field "${f.name}" has location ${JSON.stringify(f.location)}; expected "body", "query" or "path".`;
+        if (f.type !== undefined && (typeof f.type !== 'string' || !Object.values(TYPES).includes(f.type)))
+            return `${where}: carried field "${f.name}" has type ${JSON.stringify(f.type)}; expected "string", "number", "boolean", "array" or "object".`;
+        const extra = Object.keys(f).find((key) => key !== 'name' && key !== 'location' && key !== 'type');
+        if (extra !== undefined)
+            return `${where}: carried field "${f.name}" has unsupported key "${extra}".`;
+        if (seen.has(f.name))
+            return `${where}: carried field "${f.name}" is listed twice.`;
+        seen.add(f.name);
+    }
+    return undefined;
+}
+/**
+ * `rc` with each carried field the library does not declare appended to its
+ * fields, as an optional input. A name the library declares keeps the library's
+ * declaration. `fields` must have passed {@link carriedConnectorFieldsRefusal}.
+ */
+export function withCarriedFields(rc, fields) {
+    if (!fields?.length)
+        return rc;
+    const known = new Set(rc.fields.map((f) => f.name));
+    const added = fields
+        .filter((f) => !known.has(f.name))
+        .map((f) => ({ name: f.name, location: f.location, required: false, ...(f.type !== undefined ? { type: f.type } : {}) }));
+    return added.length ? { ...rc, fields: [...rc.fields, ...added] } : rc;
+}
+/**
+ * The fields a saved activity configuration declares that `rc` does not, as
+ * decompile carries them: from `optionalConfiguration.fieldsContainer.inputFields`,
+ * request fields only, in the saved order. Empty when the configuration has no
+ * field list (an SDK-compiled plan writes the essential half only), or every
+ * saved field is in the library. A saved field on a slot the connector wire has
+ * no place for (a `header`) is not carried.
+ *
+ * @param configuration - The parsed `=jsonString:` configuration blob.
+ */
+export function savedFieldsMissingFromLibrary(configuration, rc) {
+    const inputFields = configuration
+        ?.optionalConfiguration?.fieldsContainer?.inputFields;
+    if (!Array.isArray(inputFields))
+        return [];
+    const known = new Set(rc.fields.map((f) => f.name));
+    const out = [];
+    for (const raw of inputFields) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const f = raw;
+        if (typeof f.name !== 'string' || !f.name || known.has(f.name) || f.request === false)
+            continue;
+        const location = typeof f.fieldLocation === 'string' ? ownEntry(LOCATIONS, f.fieldLocation) : undefined;
+        if (!location)
+            continue;
+        known.add(f.name);
+        const type = typeof f.type === 'string' ? ownEntry(TYPES, f.type) : undefined;
+        out.push({ name: f.name, location, ...(type !== undefined ? { type } : {}) });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.70.0",
+  "version": "6.70.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "990446f9254b96a4cb0cbfc1a3ec7f99deaabe5e"
+  "gitref": "f3203eee21b892b6b70e41a5bf791aa30fdc0fc2"
 }