@uipath/maestro-builder-sdk 6.46.7 → 6.47.1

package/dist/case/business-event-shape.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The problems with a case's declared business events that `check` reports and
+ * `serialize` refuses: an empty name, a name declared twice (an `api-event`
+ * rule matches by name, so it could not tell the two apart), an option
+ * `.businessEvent()` does not read (it would be dropped from the caseplan), or a
+ * payload of a type the Designer does not write.
+ *
+ * A payload is an object or array schema (`type` absent, `'object'` or
+ * `'array'`): the two shapes the Case Designer and `uip maestro case sdd
+ * convert` write. Any other type, such as `{ type: 'string' }`, is refused.
+ * Nobody has confirmed that Studio Web's Business events panel loads one; once
+ * someone does, this can be loosened.
+ */
+import type { BuiltBusinessEvent } from './case-sdk.js';
+/** One problem with a declared business event. */
+export interface BusinessEventProblem {
+    code: 'BUSINESS_EVENT_NAME' | 'DUP_BUSINESS_EVENT' | 'BUSINESS_EVENT_UNKNOWN_OPTION' | 'BUSINESS_EVENT_PAYLOAD_TYPE';
+    message: string;
+}
+/**
+ * Report every problem with the case's business events, in declaration order.
+ * Options set to `undefined` count as absent.
+ *
+ * @param events - The events as `.businessEvent()` recorded them.
+ * @returns The problems, empty when every event is well formed.
+ */
+export declare function businessEventProblems(events: readonly BuiltBusinessEvent[]): BusinessEventProblem[];

package/dist/case/business-event-shape.js

@@ -0,0 +1,45 @@
+/** The keys a declared business event carries; any other is refused. */
+const BUSINESS_EVENT_KEYS = ['name', 'description', 'payload'];
+/**
+ * Report every problem with the case's business events, in declaration order.
+ * Options set to `undefined` count as absent.
+ *
+ * @param events - The events as `.businessEvent()` recorded them.
+ * @returns The problems, empty when every event is well formed.
+ */
+export function businessEventProblems(events) {
+    const problems = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (typeof event.name !== 'string' || !event.name.trim())
+            problems.push({ code: 'BUSINESS_EVENT_NAME', message: 'A business event has an empty name — rules match events by name.' });
+        else if (seen.has(event.name))
+            problems.push({
+                code: 'DUP_BUSINESS_EVENT',
+                message: `Business event "${event.name}" is declared twice — rules match events by name, so each name must be unique.`,
+            });
+        else
+            seen.add(event.name);
+        for (const key of Object.keys(event))
+            if (!BUSINESS_EVENT_KEYS.includes(key) && event[key] !== undefined)
+                problems.push({
+                    code: 'BUSINESS_EVENT_UNKNOWN_OPTION',
+                    message: `Business event "${String(event.name)}" does not take option "${key}", so it would be dropped from the caseplan — ` +
+                        `.businessEvent() takes "description" and "payload" (the payload's JSON Schema object; the caseplan's "schema" string is written from it).`,
+                });
+        const payload = event.payload;
+        if (payload !== undefined) {
+            const isRecord = typeof payload === 'object' && payload !== null && !Array.isArray(payload);
+            const type = isRecord ? payload.type : undefined;
+            if (!isRecord || (type !== undefined && type !== 'object' && type !== 'array'))
+                problems.push({
+                    code: 'BUSINESS_EVENT_PAYLOAD_TYPE',
+                    message: `Business event "${String(event.name)}" payload must be an object or array schema (no "type", type "object" or type "array"), ` +
+                        `e.g. { type: 'object', properties: { amount: { type: 'number' } } }` +
+                        (isRecord ? `; got type ${JSON.stringify(type)}.` : '; got a value that is not a JSON Schema object.') +
+                        ` Other types are refused until Studio Web's Business events panel is confirmed to load them.`,
+                });
+        }
+    }
+    return problems;
+}

package/dist/case/case-sdk.d.ts

@@ -24,7 +24,7 @@ export { preserveCaseJson } from './preserve.js';
 export type { CaseJsonPreservation, PreservedCaseNode, PreservedTaskFields, PreservedVariableLane } from './preserve.js';
 export { CaseBuildError } from './case-expr-check.js';
 export type { CaseLocatedDiagnostic } from './case-expr-check.js';
-export type CaseRuleType = 'case-entered' | 'required-tasks-completed' | 'required-stages-completed' | 'selected-stage-completed' | 'selected-stage-exited' | 'selected-tasks-completed' | 'current-stage-entered' | 'adhoc' | 'runs-sequentially' | 'user-selected-stage' | 'wait-for-connector' | 'sla-status-change';
+export type CaseRuleType = 'case-entered' | 'required-tasks-completed' | 'required-stages-completed' | 'selected-stage-completed' | 'selected-stage-exited' | 'selected-tasks-completed' | 'current-stage-entered' | 'adhoc' | 'runs-sequentially' | 'user-selected-stage' | 'wait-for-connector' | 'sla-status-change' | 'api-event';
 export interface RuleOpts {
     /**
      * Symbolic stage label (for `selected-stage-completed` / `selected-stage-exited`).
@@ -72,6 +72,14 @@ export interface RuleOpts {
      * a **breach** rule (`slaId` alone). Resolved to `escalationId`.
      */
     escalation?: string;
+    /**
+     * For an `api-event` rule — the **name of the business event** it listens for,
+     * e.g. `rule('api-event', { businessEvent: 'Invoice Approved' })`. Declare the
+     * event on the case with {@link CaseBuilder.businessEvent}. Emitted as the
+     * rule's `businessEventType`; the match is on the exact name, so an
+     * undeclared or misspelled name never fires.
+     */
+    businessEvent?: string;
     /** A `=js:` gate on case state (for `adhoc`, or as an extra guard on any rule). */
     expression?: string;
 }
@@ -372,9 +380,9 @@ export interface BuiltCaseExitCondition {
     marksCaseComplete?: boolean;
     rules: CaseRule[][];
 }
-export type TaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'flow-process' | 'business-rule' | 'external-agent' | 'external-workflow' | 'action' | 'connector' | 'wait-for-timer' | 'wait-for-connector';
+export type TaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'flow-process' | 'function' | 'business-rule' | 'external-agent' | 'external-workflow' | 'action' | 'connector' | 'wait-for-timer' | 'wait-for-connector';
 /** Published-resource task kinds that the Case schema permits as unresolved skeletons. */
-export type UnresolvedReferenceTaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management';
+export type UnresolvedReferenceTaskKind = 'process' | 'agent' | 'rpa' | 'api-workflow' | 'case-management' | 'function';
 /**
  * A `wait-for-connector` subscription: suspend on an Integration Service event.
  * Omit `connectorKey`/`operation` for a bare **placeholder** (for a connector not
@@ -680,6 +688,29 @@ export interface CaseLayout {
     /** Trigger node layout keyed by its display name (`Trigger 1` for the default). */
     triggers?: Record<string, CaseNodeLayout>;
 }
+/** Options for {@link CaseBuilder.businessEvent}. */
+export interface BusinessEventOpts {
+    /** What the event means, shown in the Case Designer's Business events panel. */
+    description?: string;
+    /**
+     * The JSON Schema of the payload the sender attaches, e.g.
+     * `{ type: 'object', properties: { amount: { type: 'number' } } }`. Written to
+     * `schema` as a string, with `$schema` defaulted to draft 7, the way the Case
+     * Designer saves it. It must be an object or array schema (no `type`,
+     * `type: 'object'` or `type: 'array'`, the shapes the Designer writes): any
+     * other type is refused (BUSINESS_EVENT_PAYLOAD_TYPE) until someone confirms
+     * Studio Web's Business events panel loads it. Only the empty object schema (`{}`,
+     * `{ type: 'object' }` or `{ type: 'object', properties: {} }`) is left out;
+     * any other object payload, e.g. `{ type: 'object', required: ['a'] }`, is
+     * written.
+     */
+    payload?: Record<string, unknown>;
+}
+/** A declared business event, as the serializer reads it. */
+export interface BuiltBusinessEvent extends BusinessEventOpts {
+    /** The event name an `api-event` rule matches on, exactly. */
+    name: string;
+}
 export interface BuiltCase {
     id: string;
     name: string;
@@ -701,6 +732,8 @@ export interface BuiltCase {
     stages: BuiltStage[];
     caseExit: BuiltCaseExitCondition[];
     slaRules: BuiltSla[];
+    /** Business events an `api-event` rule can listen for (`metadata.businessEvents`). */
+    businessEvents?: BuiltBusinessEvent[];
     /** Empty = the default single manual trigger. */
     triggers: BuiltTrigger[];
     /** Optional designer layout, resolved to final node ids by the serializer. */
@@ -851,6 +884,22 @@ declare class TaskBuilder {
     flowProcess(name: string, opts?: {
         folder?: string;
     }): this;
+    /**
+     * Reference a deployed **Coded Function** (a `uipath-functions` project).
+     *
+     * @remarks
+     * Emits a `function` task bound like the other published resources, with
+     * `resourceSubType: 'Function'`. A function is its own task type: do not
+     * model one as `.apiWorkflow()` or `.agent()`. A function with several
+     * deployments of one name is told apart by its folder.
+     *
+     * @param name - The deployed function's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in, or `'solution_folder'` (the default when omitted) for one built in this solution. Compile binds the task through a name/folderPath pair of root bindings keyed `<folder>.<name>`.
+     * @returns This builder, so calls chain.
+     */
+    function(name: string, opts?: {
+        folder?: string;
+    }): this;
     /**
      * Evaluate a deployed **business rule** (a DMN decision package) and read its
      * decisions back.
@@ -1146,6 +1195,7 @@ declare class CaseBuilder {
     private readonly _stages;
     private readonly _caseExit;
     private readonly _sla;
+    private readonly _businessEvents;
     private readonly _triggers;
     constructor(_id: string);
     /**
@@ -1367,6 +1417,17 @@ declare class CaseBuilder {
      * @returns This builder, so calls chain.
      */
     sla(opts: SlaOpts): this;
+    /**
+     * Declare a business event: a named message an outside system sends to a
+     * running case. An `api-event` rule listens for it by name, e.g.
+     * `.exitWhen(rule('api-event', { businessEvent: 'Invoice Approved' }), …)`.
+     * Emitted to `metadata.businessEvents`.
+     *
+     * @param name - The event name rules match on, exactly.
+     * @param opts - Its description and payload schema.
+     * @returns This builder, so calls chain.
+     */
+    businessEvent(name: string, opts?: BusinessEventOpts): this;
     /**
      * Finish the plan and return the description the serializer writes.
      *

package/dist/case/case-sdk.js

@@ -264,6 +264,22 @@ class TaskBuilder {
     flowProcess(name, opts) {
         return this.reference('flow-process', name, opts);
     }
+    /**
+     * Reference a deployed **Coded Function** (a `uipath-functions` project).
+     *
+     * @remarks
+     * Emits a `function` task bound like the other published resources, with
+     * `resourceSubType: 'Function'`. A function is its own task type: do not
+     * model one as `.apiWorkflow()` or `.agent()`. A function with several
+     * deployments of one name is told apart by its folder.
+     *
+     * @param name - The deployed function's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in, or `'solution_folder'` (the default when omitted) for one built in this solution. Compile binds the task through a name/folderPath pair of root bindings keyed `<folder>.<name>`.
+     * @returns This builder, so calls chain.
+     */
+    function(name, opts) {
+        return this.reference('function', name, opts);
+    }
     /**
      * Evaluate a deployed **business rule** (a DMN decision package) and read its
      * decisions back.
@@ -488,12 +504,11 @@ class TaskBuilder {
     _build() {
         if (!this._kind)
             throw new Error(`task "${this._name}" has no kind — call .process()/.agent()/.rpa()/.action()/.connector()/.waitForTimer()/… once.`);
-        // Task I/O binding is reference-mode only — process/agent/rpa/api-workflow,
-        // case-management, and flow-process. Connector tasks derive their own
-        // inputs/outputs from the operation schema.
-        const REF_IO = new Set(['process', 'agent', 'rpa', 'api-workflow', 'case-management', 'flow-process', 'business-rule']);
+        // Task I/O binding is reference-mode only (REF_IO). Connector tasks derive
+        // their own inputs/outputs from the operation schema.
+        const REF_IO = new Set(['process', 'agent', 'rpa', 'api-workflow', 'case-management', 'flow-process', 'function', 'business-rule']);
         if ((this._inputs || this._outputs) && !REF_IO.has(this._kind))
-            throw new Error(`task "${this._name}": .inputs()/.outputs() are only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/business-rule), not "${this._kind}".`);
+            throw new Error(`task "${this._name}": .inputs()/.outputs() are only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/function/business-rule), not "${this._kind}".`);
         if (!this._ref && (this._inputs || this._outputs))
             throw new Error(`task "${this._name}": an unresolved reference task cannot declare inputs or outputs.`);
         return {
@@ -652,6 +667,7 @@ class CaseBuilder {
     _stages = [];
     _caseExit = [];
     _sla = [];
+    _businessEvents = [];
     _triggers = [];
     constructor(_id) {
         this._id = _id;
@@ -936,6 +952,20 @@ class CaseBuilder {
         this._sla.push(buildSla(opts));
         return this;
     }
+    /**
+     * Declare a business event: a named message an outside system sends to a
+     * running case. An `api-event` rule listens for it by name, e.g.
+     * `.exitWhen(rule('api-event', { businessEvent: 'Invoice Approved' }), …)`.
+     * Emitted to `metadata.businessEvents`.
+     *
+     * @param name - The event name rules match on, exactly.
+     * @param opts - Its description and payload schema.
+     * @returns This builder, so calls chain.
+     */
+    businessEvent(name, opts = {}) {
+        this._businessEvents.push({ name, ...opts });
+        return this;
+    }
     /**
      * Finish the plan and return the description the serializer writes.
      *
@@ -958,6 +988,7 @@ class CaseBuilder {
             stages: this._stages,
             caseExit: this._caseExit,
             slaRules: this._sla,
+            ...(this._businessEvents.length ? { businessEvents: this._businessEvents } : {}),
             triggers: this._triggers,
             ...(this._layout ? { layout: this._layout } : {}),
         };

package/dist/case/check.js

@@ -1,3 +1,5 @@
+import { businessEventProblems } from './business-event-shape.js';
+import { ruleShapeProblems } from './rule-options.js';
 import { types } from '../core/expr.js';
 import { authoredCaseVersion, CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
 import { schemaVersionRefusal } from '../schema-version.js';
@@ -212,7 +214,35 @@ export function check(built, opts = {}) {
             code: 'NO_CASE_COMPLETION',
             message: 'Case has no completion rule — add .completeWhen(rule(\'required-stages-completed\')).',
         });
+    // Business events: `metadata.businessEvents` names, matched exactly by an
+    // `api-event` rule's `businessEventType`. `uip maestro case validate` rejects a
+    // rule naming none (BUSINESS_EVENT_NOT_SELECTED) or an undeclared one
+    // (BUSINESS_EVENT_NOT_FOUND); both are reported here, at the rule.
+    const businessEvents = new Set((built.businessEvents ?? []).map((event) => event.name));
+    for (const problem of businessEventProblems(built.businessEvents ?? []))
+        diags.push({ level: 'error', code: problem.code, message: problem.message });
+    const refEvent = (r, where) => {
+        if (r.rule !== 'api-event')
+            return;
+        if (!r.businessEvent)
+            diags.push({
+                level: 'error',
+                code: 'API_EVENT_NO_BUSINESS_EVENT',
+                message: 'Rule "api-event" names no business event, so it listens for nothing — pass { businessEvent: \'<name>\' } with a name declared by .businessEvent(\'<name>\').',
+                where,
+            });
+        else if (!businessEvents.has(r.businessEvent))
+            diags.push({
+                level: 'error',
+                code: 'UNKNOWN_BUSINESS_EVENT',
+                message: `Rule "api-event" listens for business event "${r.businessEvent}", which the case does not declare — add .businessEvent(${JSON.stringify(r.businessEvent)}) to the case.`,
+                where,
+            });
+    };
     const refPlacement = (r, slot, where) => {
+        for (const problem of ruleShapeProblems(r))
+            diags.push({ level: 'error', code: problem.code, message: problem.message, where });
+        refEvent(r, where);
         const bad = ILLEGAL.find((x) => x.rule === r.rule && x.slot === slot);
         if (bad)
             diags.push({
@@ -432,7 +462,7 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
     // fails. So the signature below must include the expression and the refs, not
     // just the rule name — keying on the rule type alone would reject legal
     // value-tiered routing, which is the natural way to express "under $25k goes here".
-    const sig = (c) => JSON.stringify(c.rules.map((g) => g.map((r) => [r.rule, r.stage ?? '', (r.tasks ?? []).join(','), r.expression ?? ''])));
+    const sig = (c) => JSON.stringify(c.rules.map((g) => g.map((r) => [r.rule, r.stage ?? '', (r.tasks ?? []).join(','), r.expression ?? '', r.businessEvent ?? ''])));
     const seenExit = new Map();
     stage.exit.forEach((c, i) => {
         const k = sig(c);

package/dist/case/decompile.d.ts

@@ -40,6 +40,7 @@ interface Rule {
     uipath?: SubscriptionBag;
     slaId?: string;
     escalationId?: string;
+    businessEventType?: string;
 }
 interface Condition {
     id?: string;
@@ -137,6 +138,12 @@ interface CasePlan {
         caseAppEnabled?: boolean;
         caseExitRules?: Condition[];
         slaRules?: SlaWire[];
+        businessEvents?: Array<{
+            name?: unknown;
+            description?: unknown;
+            schema?: unknown;
+            [key: string]: unknown;
+        }>;
         caseAppConfig?: {
             caseSummary?: unknown;
             sections?: Array<{

package/dist/case/decompile.js

@@ -13,6 +13,7 @@ const TASK_KIND_METHOD = {
     'api-workflow': 'apiWorkflow',
     'case-management': 'caseManagement',
     'flow-process': 'flowProcess',
+    function: 'function',
 };
 function boolLit(value) {
     return value ? 'true' : 'false';
@@ -261,11 +262,46 @@ function emitRule(rule, refs) {
             entries.push(['escalation', tsLiteral(escalation)]);
         }
     }
+    if (rule.rule === 'api-event' && rule.businessEventType !== undefined)
+        entries.push(['businessEvent', tsLiteral(rule.businessEventType)]);
     if (rule.conditionExpression !== undefined)
         entries.push(['expression', tsLiteral(rule.conditionExpression)]);
     const options = opts(entries);
     return options ? `rule(${tsLiteral(rule.rule)}, ${options})` : `rule(${tsLiteral(rule.rule)})`;
 }
+/**
+ * `.businessEvent(name, { description, payload })` for one
+ * `metadata.businessEvents[]` entry. The Designer stores the payload schema as
+ * a JSON string; it comes back as the object the builder takes, `$schema`
+ * included, so the recompile writes the same string.
+ */
+function businessEventSource(event) {
+    if (!event || typeof event !== 'object' || typeof event.name !== 'string')
+        throw new Error('a business event has no name, which is not authorable.');
+    const unknown = Object.keys(event).filter((key) => !['name', 'description', 'schema'].includes(key));
+    if (unknown.length)
+        throw new Error(`business event "${event.name}" has unsupported field "${unknown[0]}", which is not authorable.`);
+    if (event.description !== undefined && typeof event.description !== 'string')
+        throw new Error(`business event "${event.name}" has a non-string description.`);
+    let payload;
+    if (event.schema !== undefined) {
+        if (typeof event.schema !== 'string')
+            throw new Error(`business event "${event.name}" has a non-string schema.`);
+        try {
+            payload = JSON.parse(event.schema);
+        }
+        catch {
+            throw new Error(`business event "${event.name}" has a schema that is not JSON.`);
+        }
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            throw new Error(`business event "${event.name}" has a schema that is not a JSON Schema object.`);
+    }
+    const options = opts([
+        ['description', event.description !== undefined ? tsLiteral(event.description) : undefined],
+        ['payload', payload !== undefined ? tsLiteral(payload) : undefined],
+    ]);
+    return options ? `.businessEvent(${tsLiteral(event.name)}, ${options})` : `.businessEvent(${tsLiteral(event.name)})`;
+}
 function emitRuleArg(condition, refs) {
     const groups = condition.rules ?? [];
     const rendered = groups.map((group) => group.map((rule) => emitRule(rule, refs)));
@@ -1126,7 +1162,7 @@ export function collectPreservation(plan) {
         preservation.topLevel = topLevel;
     const metadataKnown = new Set([
         'caseIdentifier', 'caseIdentifierType', 'caseAppEnabled', 'caseAppConfig', 'publishVersion', 'caseExitRules', 'slaRules',
-        'allowAdhocOptionalStageTasks', 'waitForHumanSelectNextStageDFConnector',
+        'allowAdhocOptionalStageTasks', 'waitForHumanSelectNextStageDFConnector', 'businessEvents',
     ]);
     const metadata = Object.fromEntries(Object.entries(plan.metadata ?? {}).filter(([name]) => !metadataKnown.has(name)));
     if (Object.keys(metadata).length)
@@ -1336,6 +1372,8 @@ export function decompileWithDiagnostics(plan, options = {}) {
     emitVariables(out, depth, plan, triggerNameById);
     triggers.forEach((_trigger, index) => out.line(depth, `.trigger(trigger${index + 1})`));
     (metadata.slaRules ?? []).forEach((sla, index) => out.line(depth, `.sla(${slaSource(sla, index)})`));
+    for (const event of metadata.businessEvents ?? [])
+        out.line(depth, businessEventSource(event));
     for (const node of plan.nodes ?? [])
         if (isStage(node))
             emitStage(out, depth, node, refs, options.library, selectNextStage);

package/dist/case/preserve.js

@@ -21,7 +21,7 @@ const TOP_LEVEL_KEYS = new Set([
 const METADATA_KEYS = new Set([
     'caseIdentifier', 'caseIdentifierType', 'caseAppEnabled', 'publishVersion', 'caseExitRules', 'slaRules',
     'caseAppConfig', 'adhocCaseEndData',
-    'allowAdhocOptionalStageTasks', 'waitForHumanSelectNextStageDFConnector',
+    'allowAdhocOptionalStageTasks', 'waitForHumanSelectNextStageDFConnector', 'businessEvents',
 ]);
 const VARIABLE_KEYS = new Set([
     'id', 'name', 'type', 'default', 'body', '_jsonSchema', 'elementId', 'var',

package/dist/case/rule-options.d.ts

@@ -0,0 +1,15 @@
+/** Options each rule kind reads; check and serialize refuse any other key. */
+import type { CaseRule } from './case-sdk.js';
+/** One problem with a rule's shape: an unknown kind, or an option its kind does not read. */
+export interface RuleShapeProblem {
+    code: 'UNKNOWN_RULE' | 'RULE_UNKNOWN_OPTION';
+    message: string;
+}
+/**
+ * Report an unknown rule kind, or each option the rule's kind does not read.
+ * Options set to `undefined` count as absent.
+ *
+ * @param r - The rule as built (`rule(type, opts)` or a literal).
+ * @returns The problems, empty when the rule is well formed.
+ */
+export declare function ruleShapeProblems(r: CaseRule): RuleShapeProblem[];

package/dist/case/rule-options.js

@@ -0,0 +1,46 @@
+import { ownEntry } from '../core/own-entry.js';
+/** `expression` is a gate any rule can carry. */
+const COMMON = ['expression'];
+const RULE_OPTIONS = {
+    'case-entered': [],
+    'required-tasks-completed': [],
+    'required-stages-completed': [],
+    'selected-stage-completed': ['stage'],
+    'selected-stage-exited': ['stage'],
+    'selected-tasks-completed': ['tasks'],
+    'current-stage-entered': [],
+    adhoc: [],
+    'runs-sequentially': [],
+    'user-selected-stage': [],
+    'wait-for-connector': ['connector'],
+    'sla-status-change': ['sla', 'escalation'],
+    'api-event': ['businessEvent'],
+};
+/**
+ * Report an unknown rule kind, or each option the rule's kind does not read.
+ * Options set to `undefined` count as absent.
+ *
+ * @param r - The rule as built (`rule(type, opts)` or a literal).
+ * @returns The problems, empty when the rule is well formed.
+ */
+export function ruleShapeProblems(r) {
+    const kind = r.rule;
+    const own = ownEntry(RULE_OPTIONS, kind);
+    if (!own)
+        return [
+            {
+                code: 'UNKNOWN_RULE',
+                message: `Unknown rule "${kind}" — the rule kinds are ${Object.keys(RULE_OPTIONS).map((k) => `"${k}"`).join(', ')}.`,
+            },
+        ];
+    const allowed = [...own, ...COMMON];
+    return Object.keys(r)
+        .filter((key) => key !== 'rule' && r[key] !== undefined)
+        .filter((key) => !allowed.includes(key))
+        .map((key) => ({
+        code: 'RULE_UNKNOWN_OPTION',
+        message: `Rule "${kind}" does not take option "${key}", so it would be dropped from the caseplan — ` +
+            `"${kind}" takes ${allowed.map((k) => `"${k}"`).join(', ')}.` +
+            (kind === 'api-event' ? ` Name the event with { businessEvent: '<name>' }.` : ''),
+    }));
+}

package/dist/case/serialize.js

@@ -22,7 +22,9 @@ import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './
 import { ownEntry } from '../core/own-entry.js';
 import { resolveSchemaVersion } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors, } from './preserve.js';
+import { businessEventProblems } from './business-event-shape.js';
 import { readEventFilter, eventFilterProblem, eventFilterTreeLeaf } from '../core/event-filters.js';
+import { ruleShapeProblems } from './rule-options.js';
 /**
  * Condition `displayName` allocator.
  *
@@ -90,6 +92,7 @@ export function serialize(built, opts = {}) {
         slaIdByName: new Map(),
         escalationId: new Map(),
         escalationIdByName: new Map(),
+        businessEvents: new Set((built.businessEvents ?? []).map((event) => event.name)),
         conditionName: conditionNamer(built),
     };
     // Preallocate SLA + escalation ids (before any rule is emitted) so a
@@ -221,6 +224,12 @@ export function serialize(built, opts = {}) {
     if (built.slaRules.length) {
         metadata.slaRules = built.slaRules.map((s, i, all) => emitSla(s, i, all.length, ids, resolver));
     }
+    if (built.businessEvents?.length) {
+        const [problem] = businessEventProblems(built.businessEvents);
+        if (problem)
+            throw new Error(problem.message);
+        metadata.businessEvents = built.businessEvents.map(emitBusinessEvent);
+    }
     // Variables: declared vars + the readable companions that task outputs bound
     // (collected during stage emission above). A declared var wins on a name clash.
     const variables = emitVariables(built.vars, ids, triggerNodeByRef);
@@ -905,7 +914,8 @@ function taskData(task, resolver, taskId, stageId, ids) {
         // into the child (`data.inputs[]`) and reading results back (`data.outputs[]`)
         // uses the identical io-binding wire as the other reference tasks (Gap F).
         case 'case-management':
-        case 'flow-process': {
+        case 'flow-process':
+        case 'function': {
             // Reference-mode task, plus optional io-binding: input params and output
             // extractions (`data.inputs[]` / `data.outputs[]`). Each row's `elementId`
             // is "<stageId>-<taskId>"; an output also registers a root `inputOutputs`
@@ -1249,6 +1259,7 @@ const REFERENCE_BINDING = {
     'api-workflow': { resource: 'process', subType: 'Api' },
     'case-management': { resource: 'process', subType: 'CaseManagement' },
     'flow-process': { resource: 'process' },
+    function: { resource: 'process', subType: 'Function' },
 };
 /**
  * Mint (once per resource + resourceKey + attribute) one root binding row of a
@@ -1745,6 +1756,9 @@ function emitRules(rules, seed, ownerId, ids, resolver, site) {
     return rules.map((group, gi) => group.map((r, ri) => emitRule(r, `${seed}:${gi}:${ri}`, ownerId, ids, resolver, site)));
 }
 function emitRule(r, seed, ownerId, ids, resolver, site) {
+    const [shape] = ruleShapeProblems(r);
+    if (shape)
+        throw new Error(`${shape.message.replace(/^Rule /, 'rule ')} (in ${site})`);
     const ruleId = ids.ruleId(seed);
     const out = { rule: r.rule, id: ruleId };
     if (r.rule === 'selected-stage-completed' || r.rule === 'selected-stage-exited') {
@@ -1780,10 +1794,57 @@ function emitRule(r, seed, ownerId, ids, resolver, site) {
             out.escalationId = escId;
         }
     }
+    if (r.rule === 'api-event') {
+        // The event is matched by its exact name at run time; a rule without one
+        // listens for nothing, so both a missing and an undeclared name refuse.
+        if (!r.businessEvent)
+            throw new Error(`rule "api-event" in ${site} names no business event — write rule('api-event', { businessEvent: '<name>' }) with a name declared by .businessEvent('<name>').`);
+        if (!resolver.businessEvents.has(r.businessEvent))
+            throw new Error(`rule "api-event" in ${site} listens for business event "${r.businessEvent}", which the case does not declare — add .businessEvent(${JSON.stringify(r.businessEvent)}).`);
+        out.businessEventType = r.businessEvent;
+    }
     if (r.expression)
         out.conditionExpression = r.expression;
     return out;
 }
+const JSON_SCHEMA_DRAFT_7 = 'http://json-schema.org/draft-07/schema#';
+/**
+ * True only for a payload that says nothing at all: `{}`, `{ type: 'object' }`
+ * or `{ type: 'object', properties: {} }`. Any other key (`required`,
+ * `$schema`, a non-object `type`, ...) is content the author wrote, so the
+ * schema is written and survives a decompile/recompile round trip.
+ */
+function isEmptyObjectSchema(payload) {
+    return Object.entries(payload).every(([key, value]) => {
+        if (key === 'type')
+            return value === 'object';
+        if (key === 'properties')
+            return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length === 0;
+        return false;
+    });
+}
+/**
+ * One `metadata.businessEvents[]` entry, in the shape the Case Designer saves
+ * (`{ name, description?, schema? }`). `schema` is the payload's JSON Schema
+ * serialized to a string with `$schema` defaulted to draft 7. The payload is an
+ * object or array schema (`businessEventProblems` refuses any other type before
+ * this runs), and every one except the empty object schema
+ * (`isEmptyObjectSchema`) is written. That keeps more than the Designer and `uip maestro case sdd
+ * convert`, which write a schema only for `type: 'array'` or a non-empty
+ * `properties`: `{ type: 'object', required: ['a'] }` is written here and left
+ * out there, so a decompiled payload recompiles unchanged.
+ */
+function emitBusinessEvent(event) {
+    const out = { name: event.name };
+    if (event.description !== undefined)
+        out.description = event.description;
+    const payload = event.payload;
+    if (payload !== undefined) {
+        if (!isEmptyObjectSchema(payload))
+            out.schema = JSON.stringify({ ...payload, $schema: payload.$schema ?? JSON_SCHEMA_DRAFT_7 });
+    }
+    return out;
+}
 function emitEntry(c, seed, ownerId, label, ids, resolver) {
     const out = {
         id: ids.conditionId(seed),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.46.7",
+  "version": "6.47.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "68e27a784a7d9b4fff5177074148d05e0c993a65"
+  "gitref": "05cde3ec95db903ec81d2df24fd4e60bade77a97"
 }