@uipath/maestro-builder-sdk 6.24.0 → 6.25.0

package/dist/nodes/hitl/flow/spec.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The HITL family's authoring types (`uipath.human-in-the-loop` and its
+ * `.quick-form`, `.coded-action-app` and `.document-validation` variants), and
+ * the kind's entry in `FlowActionSpecs`. Moved from core/actions.ts in Phase 4
+ * of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. The form fields stay in
+ * `core/actions.ts`: an agent's quick-form escalation shares them.
+ */
+import type { Expr } from '../../../core/expr.js';
+import type { FormField } from '../../../core/actions.js';
+/**
+ * Where the task is delivered. The four ids are the platform's own — including
+ * the lowercase `'teams'`, which is how every deployed recipient spells
+ * Microsoft Teams (the canvas's channel list, `hitl-types.ts`).
+ */
+export type HitlChannel = 'Slack' | 'teams' | 'Email' | 'ActionCenter';
+/**
+ * How the task is assigned, the platform's own vocabulary (canvas
+ * `HITL_ASSIGNEE_TYPE`): `'user'` a single user, `'group'` all users of a
+ * group, `'staticEmail'`/`'staticGroupName'` literal values instead of
+ * directory picks, `'workload'`/`'roundRobin'` distribution over a group, and
+ * `'custom'` an expression the engine evaluates (`value` holds it).
+ */
+export type HitlAssigneeType = 'user' | 'group' | 'staticEmail' | 'staticGroupName' | 'workload' | 'roundRobin' | 'custom';
+/** A per-channel Integration Service connection (Slack / Teams delivery). */
+export interface HitlConnection {
+    /** The connection's display name. */
+    name?: string | null;
+    /** The connection key the engine resolves, e.g. `'Slack'` for the default. */
+    key: string;
+    /** Folder the connection lives in; `null` for tenant-level defaults. */
+    folderPath?: string | null;
+}
+/**
+ * Who gets the task and over which channels. Omit the whole object for the
+ * definition's default (Email + Action Center, assigned to a group) — which is
+ * what 203 of 233 deployed v1 human tasks carry, and what this SDK has always
+ * emitted.
+ *
+ * ```ts
+ * hitl({
+ *   recipient: {
+ *     channels: ['Email', 'ActionCenter'],
+ *     assignee: { type: 'user', value: 'reviewer@acme.test' },
+ *   },
+ *   …
+ * })
+ * ```
+ */
+export interface HitlRecipient {
+    /** Delivery channels. Defaults to the emitted definition's own default set. */
+    channels?: HitlChannel[];
+    /** Who the task is assigned to. */
+    assignee: {
+        type: HitlAssigneeType;
+        /**
+         * The user email / group name / expression, per `type`. The engine lowers
+         * this to its `{ Value, Type }` recipient contract; without one the task
+         * falls back to the tenant's assignment default.
+         */
+        value?: string;
+        /** Display name the designer shows next to the pick. Cosmetic. */
+        displayName?: string;
+    };
+    /**
+     * Per-channel connections, keyed by channel id (`Slack` / `teams`). Only the
+     * connector-backed channels take one; Email and Action Center do not.
+     */
+    connections?: Partial<Record<'Slack' | 'teams', HitlConnection>>;
+}
+/**
+ * The Document Validation task's subject — `variant: 'document-validation'`
+ * only. The reviewer gets the platform's validation station (or a custom app
+ * with a Validation Control) over a document and its extraction result.
+ */
+export interface DocValidationInputs {
+    /**
+     * The extraction result to validate — bind the `ExtractionResult` output of
+     * an upstream Extract step, e.g. `out('extract', 'ExtractionResult')`.
+     * Required: the station has nothing to validate without it.
+     */
+    extractionResult: Expr | string;
+    /** Storage bucket id holding the document. */
+    storageBucket?: string;
+    /** The document's id within the bucket. */
+    documentId?: string;
+    /**
+     * `'standard'` (default) for the native validation station, `'custom'` for a
+     * custom app with a Validation Control — which then requires `taxonomy`.
+     */
+    render?: 'standard' | 'custom';
+    /** The taxonomy the custom app validates against. Required when `render: 'custom'`. */
+    taxonomy?: Expr | string;
+}
+/**
+ * One completion button. `action: 'End'` marks an outcome that ENDS the process
+ * rather than continuing (the platform's own two-value vocabulary — anything
+ * that is not exactly `'End'` reads as continue).
+ *
+ * `id` is the outcome's wire id — `schema.outcomes[].id`, and the `outcome-<id>`
+ * port its edge leaves from. Leave it out and the id is a slug of `name`
+ * (`'Needs info'` → `needs-info`). Set it only to keep an id a flow already
+ * has, as decompile does for a task the designer drew
+ * (`{ name: 'Reject', id: 'outcome-1778015958049' }`): merge keeps the
+ * original node, so its edges must use that node's ids.
+ *
+ * @remarks
+ * A bare string is shorthand for `{ name }`.
+ */
+export type Outcome = string | {
+    name: string;
+    action?: 'Continue' | 'End';
+    id?: string;
+};
+/**
+ * WHICH human-task node type to emit. The platform ships three spellings of the
+ * same node; two of them resolve on this tenant and are what this option picks.
+ *
+ * @remarks
+ * - **omitted** — `uipath.human-in-the-loop`, the original node, which chooses
+ *   the form kind with `inputs.type: 'quick'`. This is the default and it does
+ *   not change: it is where the platform's own versioning continues, and 319 of
+ *   the corpus's human tasks are on it.
+ * - **`'quick-form'`** — `uipath.human-in-the-loop.quick-form`. Same inline form,
+ *   but the node TYPE is the "quick" choice, so no `inputs.type` is written
+ *   (165 of its 175 deployed instances omit it). Everything you author is
+ *   identical; pick it when something downstream keys on the literal type
+ *   string, which flow-v1's own task checkers do.
+ * - **`'action-app'`** — `uipath.human-in-the-loop.coded-action-app`. The form is
+ *   NOT in the flow: it belongs to a deployed Action App, named by `app`. You
+ *   still declare `outcomes` (the flow routes on them); you must NOT declare
+ *   `fields` (the app owns them) — `check` says so.
+ *
+ * - **`'document-validation'`** — `uipath.human-in-the-loop.document-validation`.
+ *   A validation station over a document + extraction result, named by
+ *   `document`. No `fields` (the station is the form); `outcomes` still route.
+ *   The definition is BUNDLED from the workbench manifest — the tenant registry
+ *   does not serve the family (same availability note as do-while).
+ */
+export type HitlVariant = 'quick-form' | 'action-app' | 'document-validation';
+/**
+ * A deployed Action App that supplies a human task's form — the `'action-app'`
+ * variant's subject.
+ *
+ * @remarks
+ * The names are the platform's own, from flow-v1's app picker: an app is closed
+ * by `key` (its GUID) plus the `folderPath` it is deployed in, with `name` the
+ * human-readable title. This SDK is offline and never calls the Apps API, so
+ * what you write here is what you already know about the app.
+ *
+ * ```ts
+ * hitl({
+ *   variant: 'action-app',
+ *   app: {
+ *     name: 'Expense Review',
+ *     key: 'c0ba97df-8a30-4fe0-b4b4-4611a631d77b',
+ *     folderPath: 'Shared',
+ *     inputs: { 'Expense Amount': out('fetchExpense', 'total') },
+ *   },
+ *   outcomes: ['Approve', 'Reject'],
+ * })
+ * ```
+ */
+export interface AppRef {
+    /** The app's display title, e.g. `'Expense Review'`. */
+    name: string;
+    /** The app's key (a GUID) — how the platform resolves which app this is. */
+    key: string;
+    /** Fully-qualified folder the app is deployed in, e.g. `'Shared'`. */
+    folderPath: string;
+    /**
+     * The app's stable system name. `null` until the app's first deployment
+     * assigns one, which is why it is optional and why `null` is a legal value
+     * rather than something to omit.
+     */
+    appSystemName?: string | null;
+    /**
+     * What to send the app, keyed by the app's OWN input parameter names — so the
+     * keys are the app author's, spaces and all (`'Invoice Amount'`), not
+     * identifiers of ours. Values are references, e.g. `out('step', 'field')`.
+     *
+     * Emitted as `inputs.appInputBindings`, the map flow-v1's serializer turns
+     * into the task's `HitlTaskArguments`.
+     */
+    inputs?: Record<string, Expr | string>;
+}
+export interface HitlInputs {
+    /**
+     * Which human-task node type to emit. Omit it for today's default — see
+     * {@link HitlVariant}. Omitting it emits exactly what it always has.
+     */
+    variant?: HitlVariant;
+    /**
+     * The deployed Action App that owns this task's form. Required by — and only
+     * legal with — `variant: 'action-app'`.
+     */
+    app?: AppRef;
+    /** Task title the reviewer sees. Defaults to the step's label. */
+    title?: string;
+    /** Action Center priority. Defaults to `'Low'`. */
+    priority?: 'Low' | 'Medium' | 'High';
+    /**
+     * The form, as an array of field descriptors — `direction: 'input'` for a value
+     * the reviewer reads, `'output'` for one they fill in. An array (not a map)
+     * because the ids are yours and order is the order on the form.
+     *
+     * Required for the inline-form variants (the default and `'quick-form'`).
+     * FORBIDDEN with `variant: 'action-app'`, where the form belongs to the
+     * deployed app rather than to the flow — `check` says so both ways.
+     */
+    fields?: FormField[];
+    /**
+     * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
+     * reviewer has no way to complete the task and the flow waits forever. The
+     * first is the primary (default) one. Each outcome is its own exit,
+     * `outcome-<slug>`: the default node and `'quick-form'` never leave on
+     * `completed` once they have outcomes. On the default node MORE THAN ONE
+     * outcome routes per outcome: the first continues the main path and the rest
+     * are routed with `.stepToList('outcome-<slug>', …)`. With `'quick-form'`,
+     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`, an explicit
+     * `{ version }` or one outcome, `.step()` continues EVERY outcome instead.
+     *
+     * Which one they pressed is also `out('<step>', 'Action')` — that is what the
+     * platform's own routing conditions compare against.
+     */
+    outcomes: Outcome[];
+    /** Who gets the task and how. Omit for the definition's default delivery. */
+    recipient?: HitlRecipient;
+    /** Action Center labels, comma-separated (the platform stores one string). */
+    labels?: string;
+    /**
+     * Whether the task ROUTES per outcome. Each outcome has its own exit either
+     * way (`outcome-<id>`, the name slugified: `'Approve'` → `outcome-approve`).
+     *
+     * `true`: the FIRST outcome continues the main path and the others are routed
+     * with `.stepToList('outcome-<id>', …)`, or the run stalls when the reviewer
+     * picks one. The default node with more than one outcome already does this,
+     * on its **1.1** definition unless a `{ version }` pins another; `'quick-form'`
+     * supports it on its one definition. `false`: EVERY outcome continues to the
+     * next step on its own edge — a task that routes the decision as DATA by
+     * reading `out('<step>', 'Action')`; `'quick-form'` does this by default.
+     * `'action-app'` and `'document-validation'` read their outcomes from the app
+     * and leave on their one `completed` exit, so `true` is refused there.
+     */
+    outcomePorts?: boolean;
+    /**
+     * Expose the task's runtime error as a bindable `out('<step>', 'error')`
+     * object (`{ code, message, detail, category, status }`). Selects the node's
+     * **1.2** definition — which also routes per outcome, so this implies
+     * {@link HitlInputs.outcomePorts | outcomePorts}. Default node only.
+     */
+    exposeError?: boolean;
+    /**
+     * The document to validate. Required by — and only legal with —
+     * `variant: 'document-validation'`.
+     */
+    document?: DocValidationInputs;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link hitl} builds. */
+        hitl: {
+            inputs: HitlInputs;
+        };
+    }
+}

package/dist/nodes/hitl/flow/spec.js

@@ -0,0 +1 @@
+export {};

package/dist/serialize.d.ts

@@ -126,10 +126,8 @@ export declare function perCallDefinition(spec: {
  * The definition version serialize emits for a typed action step that is not
  * yet on the node-type registry: the author's `{ version }` when given,
  * otherwise the version the step's inputs select, otherwise `undefined` (the
- * pinned default). Two such families pick a version themselves:
- *
- *  - `hitl`: `exposeError` selects `@1.2`, per-outcome routing selects `@1.1`;
- *  - `inlineAgent`: the newest bundled version, not the first bundled entry.
+ * pinned default). One such family picks a version itself: `inlineAgent`
+ * takes the newest bundled version, not the first bundled entry.
  *
  * The emit paths read their version here, and `check` resolves the definition
  * it asks about with this same version (#1041), so the two cannot pick