@uipath/maestro-builder-sdk 6.31.7 → 6.31.9

package/dist/check.js

@@ -10,7 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { actionVersion, bundledActionNodeType, bundledContainerDefinition, bundledDefinition, perCallDefinition, resolveContributionDefinition } from './serialize.js';
-import { FORM_FIELD_TYPES, formFieldTypeHint, formFieldTypeWhy } from './core/form-field-type.js';
+import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText } from './core/form-field-type.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
 import { checkCookedEscapes } from './flow-expr-check.js';
@@ -3416,7 +3416,17 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
                 if (!FORM_FIELD_TYPES.includes(String(f?.type))) {
                     at('INLINE_AGENT_ESCALATION_FIELD_TYPE_UNKNOWN', `Inline agent step "${step}"'s quick-form escalation gives the field "${String(f?.id ?? '?')}" the type `
                         + `${JSON.stringify(f?.type)}, ${formFieldTypeWhy(f?.type, `which the form does not recognize — it would `
-                            + `be published as a plain string`)}. Valid: ${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
+                            + `be published as a plain string`)}. Valid: ${validFormFieldTypesText()}.`, formFieldTypeHint(f?.type));
+                }
+                const optionsProblem = formFieldOptionsProblem(f?.type, f?.options);
+                if (optionsProblem !== undefined) {
+                    const message = `Inline agent step "${step}"'s quick-form escalation field "${String(f?.id ?? '?')}" `
+                        + `${formFieldOptionsWhy(optionsProblem, f?.type)}.`;
+                    if (optionsProblem === 'ignored')
+                        warn('INLINE_AGENT_ESCALATION_FIELD_OPTIONS_IGNORED', message);
+                    else {
+                        at('INLINE_AGENT_ESCALATION_FIELD_OPTIONS', message, `options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }]`);
+                    }
                 }
             }
             continue;

package/dist/core/actions.d.ts

@@ -55,11 +55,53 @@ export interface ConnectorOpts {
     object?: string;
 }
 /**
- * A form field's type. The platform does not recognize a type outside this set:
- * older runtimes read it as text (so a number field becomes a text box), newer
- * ones reject the form. That is why `check` rejects anything outside this set.
+ * The platform's 11 canonical quick-form field types (`@uipath/hitl-schema-types`
+ * `fieldType`), which the designer saves. Each has its own value shape:
+ * `integer` → a JSON integer, `date` → `'2026-10-15'`, `datetime` → an ISO
+ * date-time, `file` → a binary-format string, `object` / `array` → JSON.
  */
-export type FormFieldType = 'text' | 'number' | 'boolean' | 'date-time';
+export type CanonicalFormFieldType = 'string' | 'number' | 'integer' | 'float' | 'double' | 'boolean' | 'date' | 'datetime' | 'file' | 'object' | 'array';
+/**
+ * The platform's choice-control spellings of a field type. Each names the data
+ * the field holds AND how it renders (`@uipath/hitl-schema-types`
+ * `resolveFieldType` + `controlForDeclaredType`): `singleSelect` is a `string`
+ * shown as a dropdown, `multiSelect` an `array` shown as a multi-select, and
+ * `enum` (what the designer's variable picker writes for a closed set) a
+ * `string` shown as a dropdown. The choices are the field's `options`.
+ */
+export type ControlFormFieldType = 'singleSelect' | 'multiSelect' | 'enum';
+/**
+ * A form field's type: one of the platform's canonical types; `'text'` /
+ * `'date-time'`, the SDK's older spellings of `'string'` / `'datetime'` (the
+ * platform resolves both); or a choice-control spelling (`'singleSelect'`,
+ * `'multiSelect'`, `'enum'`), which the form renders as a picker over the
+ * field's `options`. A quick form with any other type fails the platform's
+ * validation, which is why `check` rejects it.
+ *
+ * @example
+ * hitl({ fields: [{ id: 'dueOn', type: 'date', direction: 'output' }], outcomes: ['Done'] })
+ * hitl({
+ *   fields: [{
+ *     id: 'priority', type: 'singleSelect', direction: 'output',
+ *     options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }],
+ *   }],
+ *   outcomes: ['Done'],
+ * })
+ */
+export type FormFieldType = CanonicalFormFieldType | 'text' | 'date-time' | ControlFormFieldType;
+/**
+ * One choice of a picker field (`@uipath/hitl-schema-types` `optionShape`):
+ * `value` is what the answer holds, `label` what the reviewer sees, and `id`
+ * the option's own stable id. All three are required by the platform.
+ */
+export interface FormFieldOption {
+    /** The option's own stable id, e.g. `'opt-1'`. */
+    id: string;
+    /** What the answer holds when the reviewer picks it, e.g. `'high'`. */
+    value: string;
+    /** What the reviewer sees, e.g. `'High'`. */
+    label: string;
+}
 /** A value the reviewer READS: shown on the form, filled in from the flow. */
 export interface ShownField {
     /** Field id — the key the answer object uses. Must be unique on the form. */
@@ -68,6 +110,11 @@ export interface ShownField {
     label?: string;
     type: FormFieldType;
     direction: 'input';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /**
      * What to show — a reference, e.g. `input('amount')` or
      * `out('fetchInvoice', 'body.total')`. Required: a shown field with nothing
@@ -84,6 +131,11 @@ export interface AskedField {
     label?: string;
     type: FormFieldType;
     direction: 'output';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /** Reviewer must fill it in before the task can be completed. */
     required?: boolean;
 }
@@ -100,6 +152,11 @@ export interface InOutField {
     label?: string;
     type: FormFieldType;
     direction: 'inOut';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /** What to pre-fill — a reference, e.g. `out('fetchInvoice', 'body.total')`. */
     value: Expr;
     /** Reviewer must confirm/fill it before the task can be completed. */

package/dist/core/form-field-type.d.ts

@@ -1,49 +1,160 @@
 /**
- * The product's spellings of the form-field types the SDK models.
+ * The quick-form field-type vocabulary: the product's own, transcribed.
  *
  * A quick form's field `type` is read by the product through
- * `@uipath/hitl-schema-types` `normalizeFieldType`. Its canonical stored values
- * are `string`, `number`, `boolean`, `datetime`, … and it accepts aliases for
- * each: `text` is an alias of `string`, `date-time` of `datetime`, and .NET
- * names such as `System.String` resolve too. The designer saves the canonical
- * value, so a canvas-built form says `"string"`; the SDK (like flow-v1's
- * serializer and `uip maestro flow hitl add`) writes `text`.
+ * `@uipath/hitl-schema-types` (`fieldType`, `resolveFieldType`,
+ * `FIELD_TYPE_TO_JSON_SCHEMA`). It has 11 canonical stored values — `string`,
+ * `number`, `integer`, `float`, `double`, `boolean`, `date`, `datetime`, `file`,
+ * `object`, `array` — and it resolves aliases onto them: `text` is a legacy
+ * alias of `string`, `date-time` of `datetime`, and .NET names such as
+ * `System.Int32` resolve too. A `quick` form whose type resolves to none of the
+ * 11 fails the product's validation.
  *
- * So `"string"` and `"text"` are the same field on the wire. This table maps
- * each product spelling of the four types {@link FormFieldType} models to the
- * SDK's spelling, so decompile hands the author source `check` accepts.
- * A type the SDK does not model (`integer`, `date`,
- * `file`, …) has no entry: it stays as written, and `check` reports it.
+ * That package is published only to GitHub Packages, so the SDK cannot depend
+ * on it at runtime. This module is a transcription, and
+ * `tests/hitl-field-type-contract.test.ts` runs the real package against it:
+ * the canonical set, each type's JSON Schema, and every alias below must agree
+ * with the pinned `@uipath/hitl-schema-types`. A canonical-set, JSON Schema or
+ * control-spelling change upstream fails there; a new data alias does not.
  *
- * Mirrors `resolveFieldType` in `@uipath/hitl-schema-types` 1.1.6, restricted
- * to the groups that resolve to `string`, `number`, `boolean` and `datetime`
- * (minus `singleSelect` / `enum` / `union` / …, which resolve to `string` but
- * are not a plain text box).
+ * Besides data types, the product accepts three CHOICE-CONTROL spellings —
+ * `singleSelect`, `multiSelect`, `enum` — which name both the data the field
+ * holds and the control it renders with (#1235). The SDK accepts them in
+ * source and writes them as written, so a canvas dropdown stays a dropdown.
+ *
+ * Every SDK path reads field types from here: `check` (human tasks and inline
+ * agent quick-form escalations), decompile, and the serializers' output
+ * schemas.
  */
-import type { FormFieldType } from './actions.js';
+import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldOption } from './actions.js';
+/** The product's 11 canonical quick-form field types, in its own order. */
+export declare const CANONICAL_FORM_FIELD_TYPES: CanonicalFormFieldType[];
+/** The SDK's legacy spellings (`text`, `date-time`), for diagnostics that list them. */
+export declare const LEGACY_FORM_FIELD_TYPES: string[];
+/** The choice-control spellings, for `check`'s messages and the contract test. */
+export declare const CONTROL_FORM_FIELD_TYPES: ControlFormFieldType[];
 /**
- * The SDK's spelling of a wire form-field type, or `undefined` when the SDK
- * does not model that type.
+ * Every form-field type the SDK accepts in source: the 11 canonical ones, the
+ * SDK's legacy aliases, and the three choice-control spellings.
+ */
+export declare const FORM_FIELD_TYPES: string[];
+/**
+ * The tail of a "Valid: …" diagnostic: the canonical types, then the legacy
+ * spellings and the choice controls in parentheses.
  *
  * @example
- * sdkFormFieldType('string')   // 'text'
- * sdkFormFieldType('datetime') // 'date-time'
- * sdkFormFieldType('integer')  // undefined
+ * validFormFieldTypesText() // 'string, …, array (or the older text, date-time; or a choice control: singleSelect, …)'
  */
-export declare function sdkFormFieldType(wire: unknown): FormFieldType | undefined;
+export declare function validFormFieldTypesText(): string;
 /**
- * Why a form-field type is refused: a product spelling of a type the SDK
- * models (`"string"` is the platform's own name for text), or a type
- * the SDK does not model at all. `unknownWhy` is the caller's reason for the
- * second case; the default is a human task's.
+ * The data type and control a choice-control spelling names, or `undefined`
+ * for any other type.
+ *
+ * @example
+ * controlFormFieldType('singleSelect') // { data: 'string', control: 'dropdown' }
+ * controlFormFieldType('multiSelect')  // { data: 'array', control: 'multiSelect' }
+ * controlFormFieldType('string')       // undefined
+ */
+export declare function controlFormFieldType(type: unknown): {
+    data: CanonicalFormFieldType;
+    control: string;
+} | undefined;
+/** The product aliases, for the contract test. */
+export declare const FORM_FIELD_TYPE_ALIASES: Readonly<Record<string, CanonicalFormFieldType>>;
+/**
+ * The canonical type a wire or source spelling names, or `undefined` when it
+ * names none the SDK models. A choice-control spelling is its own wire
+ * spelling, so it is `undefined` here too — its data type is
+ * `controlFormFieldType(t).data`; resolving it here would let a caller write
+ * `string` for a dropdown.
+ *
+ * @example
+ * canonicalFormFieldType('integer')      // 'integer'
+ * canonicalFormFieldType('text')         // 'string'
+ * canonicalFormFieldType('System.Int32') // 'integer'
+ * canonicalFormFieldType('string[]')     // 'array'
+ * canonicalFormFieldType('string | null') // 'string'
+ * canonicalFormFieldType('singleSelect') // undefined
+ */
+export declare function canonicalFormFieldType(type: unknown): CanonicalFormFieldType | undefined;
+/**
+ * The spelling decompile writes into source for a wire field type: a canonical
+ * type or an SDK alias stays as written, so a canvas form (`"integer"`,
+ * `"date"`) and a classic-CLI form (`"text"`) both compile back to the bytes
+ * they came from; a product alias the SDK does not accept in source
+ * (`"System.Int32"`, `"string[]"`) becomes its canonical type; anything else
+ * stays verbatim for `check` to report.
+ *
+ * @example
+ * sourceFormFieldType('date')          // 'date'
+ * sourceFormFieldType('text')          // 'text'
+ * sourceFormFieldType('System.String') // 'string'
+ * sourceFormFieldType('string[]')      // 'array'
+ * sourceFormFieldType('singleSelect')  // 'singleSelect'
+ */
+export declare function sourceFormFieldType(wire: unknown): string;
+/**
+ * Why a form-field type is refused: a product alias the SDK does not accept in
+ * source (`"System.Int32"` is the platform's .NET name for `integer`), or a type
+ * the product does not recognize at all. `unknownWhy` is the caller's reason for
+ * the second case; the default is a human task's.
  */
 export declare function formFieldTypeWhy(type: unknown, unknownWhy?: string): string;
-/** The form-field types the SDK models. */
-export declare const FORM_FIELD_TYPES: string[];
-/** The `suggestion` for an unknown form-field type: the nearest valid one, else `type: 'text'`. */
+/** The `suggestion` for an unknown form-field type: its canonical type, the nearest valid one, else `type: 'string'`. */
 export declare function formFieldTypeHint(type: unknown): string;
-/** JSON-Schema type per form-field type, as flow-v1's form serializer maps them (quick-form escalations and human tasks). */
-export declare const FORM_FIELD_JSON_TYPE: Record<FormFieldType, {
+/**
+ * The JSON Schema of a field's value, for the output (and escalation input)
+ * schemas the serializers write; `undefined` for a type the SDK does not model.
+ *
+ * @example
+ * formFieldJsonSchema('date') // { type: 'string', format: 'date' }
+ * formFieldJsonSchema('text') // { type: 'string' }
+ * formFieldJsonSchema('multiSelect') // { type: 'array' }
+ */
+export declare function formFieldJsonSchema(type: unknown): {
     type: string;
     format?: string;
-}>;
+} | undefined;
+/**
+ * A picker field's choices as the form row carries them (`options`, each
+ * `{ id, value, label }` — the product's `optionShape`), copied so the wire
+ * never aliases the author's array. `undefined` when the field has none.
+ * Both serializers (human task, quick-form escalation) write through this.
+ */
+export declare function formFieldOptionsWire(options: readonly FormFieldOption[] | undefined): FormFieldOption[] | undefined;
+/**
+ * A form row's `options` read back for source: the well-formed choices
+ * (string `id`, `value`, `label` — all three the product requires), or
+ * `undefined` when the row has no `options` array. A malformed entry is left
+ * out, not coerced: `{ id: 'o1', value: 1 }` is not rewritten to
+ * `value: '1', label: ''`. Decompile (human task and quick-form escalation)
+ * reads through this, so a canvas dropdown's choices survive an edit.
+ *
+ * @example
+ * liftFormFieldOptions([{ id: 'o1', value: 'a', label: 'A' }, { id: 'o2', value: 2 }])
+ * // [{ id: 'o1', value: 'a', label: 'A' }]
+ */
+export declare function liftFormFieldOptions(raw: unknown): FormFieldOption[] | undefined;
+/**
+ * What is wrong with a form field's `options`, or `undefined` when nothing is.
+ * `check` reports each (human task and quick-form escalation):
+ *
+ * - `'malformed'`: `options` is there but is not an array of `{ id, value,
+ *   label }` strings. Serialize would throw or write rows the platform refuses.
+ * - `'missing'`: a choice-control type (`singleSelect`, `multiSelect`, `enum`)
+ *   with no choices. The form publishes an empty picker.
+ * - `'ignored'`: choices on a type that is not a choice control. The form
+ *   renders a plain input and never shows them.
+ *
+ * @example
+ * formFieldOptionsProblem('singleSelect', undefined)                         // 'missing'
+ * formFieldOptionsProblem('singleSelect', {})                                // 'malformed'
+ * formFieldOptionsProblem('string', [{ id: 'o1', value: 'a', label: 'A' }]) // 'ignored'
+ * formFieldOptionsProblem('enum', [{ id: 'o1', value: 'a', label: 'A' }])   // undefined
+ */
+export declare function formFieldOptionsProblem(type: unknown, options: unknown): 'malformed' | 'missing' | 'ignored' | undefined;
+/**
+ * The reason text for a `formFieldOptionsProblem`, worded for a diagnostic
+ * that starts "… the field "<id>" …".
+ */
+export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | 'ignored', type: unknown): string;