@uipath/maestro-builder-sdk 5.2.0

package/dist/case/case-sdk.js

@@ -0,0 +1,923 @@
+import { connector as makeConnector, subscriptionFrom, } from '../core/actions.js';
+import { isTriggerDescriptor } from '../core/connectors.js';
+import { checkCaseExpressions, CaseBuildError } from './case-expr-check.js';
+import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS, recordAuthoredCaseVersion } from './format-profile.js';
+import { schemaVersionRefusal } from '../schema-version.js';
+export { preserveCaseJson } from './preserve.js';
+export { CaseBuildError } from './case-expr-check.js';
+/**
+ * Declare a condition rule. Pass one rule, an array for an AND-group, or an
+ * array of arrays for the complete OR-of-AND grid to
+ * `entryWhen`/`exitWhen`/etc.
+ *
+ * @param type - Which condition, e.g. `'case-entered'` or `'selected-tasks-completed'`.
+ * @param opts - What the rule needs, e.g. the `tasks` a task-completion rule waits on.
+ * @returns A rule to pass to `entryWhen` / `exitWhen` / `completeWhen`.
+ */
+export function rule(type, opts = {}) {
+    return { rule: type, ...opts };
+}
+/**
+ * Gate a condition slot only on case data without naming its default event.
+ *
+ * @param expression - A `=js:` expression over declared `vars.*` values.
+ * @returns A slot-agnostic marker resolved by `entryWhen`, `exitWhen`, or `completeWhen`.
+ */
+export function when(expression) {
+    return { kind: 'case-when-expression', expression };
+}
+const DEFAULT_RULE_BY_SLOT = {
+    'stage-entry': 'case-entered',
+    'stage-exit': 'selected-tasks-completed',
+    'task-entry': 'current-stage-entered',
+    'case-exit': 'required-stages-completed',
+};
+function resolveRule(input, slot) {
+    if (input.kind === 'case-when-expression')
+        return rule(DEFAULT_RULE_BY_SLOT[slot], { expression: input.expression });
+    return input;
+}
+/** Coerce a rule, AND-group, or complete OR-of-AND grid into the wire DNF. */
+function ruleGroups(rules, slot) {
+    const groups = !Array.isArray(rules)
+        ? [[rules]]
+        : rules.length > 0 && Array.isArray(rules[0])
+            ? rules
+            : [rules];
+    return groups.map((group) => group.map((input) => resolveRule(input, slot)));
+}
+/**
+ * Declare an escalation. `notify` recipients come from {@link toUser}/{@link toGroup}.
+ *
+ * @param opts - When it fires (`after`) and who it notifies (`notify`).
+ * @returns An escalation to attach to an SLA.
+ */
+export function escalation(opts) {
+    return opts;
+}
+/**
+ * An escalation recipient that is a single user.
+ *
+ * @param target - How the user is addressed, e.g. `'email'`.
+ * @param value - The address itself, when `target` names a lookup rather than a value.
+ * @returns A recipient for an escalation's `notify` list.
+ */
+export function toUser(target, value) {
+    return { scope: 'User', target, value };
+}
+/**
+ * An escalation recipient that is a user group.
+ *
+ * @param target - How the group is addressed, e.g. `'name'`.
+ * @param value - The value itself, when `target` names a lookup rather than a value.
+ * @returns A recipient for an escalation's `notify` list.
+ */
+export function toGroup(target, value) {
+    return { scope: 'UserGroup', target, value };
+}
+function buildSla(opts) {
+    return {
+        count: opts.count,
+        unit: opts.unit,
+        displayName: opts.displayName,
+        // The default SLA (no `when`) carries the designer's always-true gate.
+        expression: opts.when ?? '=js:true',
+        escalations: opts.escalations ?? [],
+    };
+}
+/**
+ * A manual (user-initiated) case trigger.
+ *
+ * @param opts - Display name and other trigger metadata.
+ * @returns A trigger to pass to `.trigger(...)`.
+ */
+export function manualTrigger(opts = {}) {
+    return { kind: 'manual', name: opts.name, description: opts.description };
+}
+/**
+ * A timer (scheduled) case trigger. `every` is an ISO-8601 repeating interval.
+ *
+ * @param opts - The schedule — `every`, as an ISO-8601 repeating interval.
+ * @returns A trigger to pass to `.trigger(...)`.
+ */
+export function timerTrigger(opts) {
+    return { kind: 'timer', name: opts.name, description: opts.description, timeCycle: opts.every };
+}
+export function eventTrigger(descriptorOrOpts = {}, descriptorOpts = {}) {
+    const descriptor = isTriggerDescriptor(descriptorOrOpts) ? descriptorOrOpts : undefined;
+    const opts = descriptor ? descriptorOpts : descriptorOrOpts;
+    const eventOutputs = [];
+    for (const [name, v] of Object.entries(opts.outputs ?? {})) {
+        const source = typeof v === 'string' ? v : v.source;
+        const type = (typeof v === 'string' ? 'string' : (v.type ?? 'string'));
+        eventOutputs.push({ var: name, source, type });
+    }
+    return {
+        kind: 'event',
+        name: opts.name,
+        description: opts.description,
+        eventOutputs: eventOutputs.length ? eventOutputs : undefined,
+        eventSubscription: descriptor
+            ? subscriptionFrom(descriptor, descriptorOpts)
+            : opts.subscription,
+    };
+}
+/**
+ * Declare a structured (object/array) variable type. Pass the JSON schema — object
+ * vs array is `body.type`. Use in `.var()`/`.input()`/`.output()` where a
+ * {@link TypeDesc} is expected.
+ *
+ * @example
+ * **Declare an object variable and an array variable**
+ * ```ts
+ * .var('caseData', jsonSchema({ type: 'object', properties: { status: { type: 'string' } } }))
+ * .var('attachments', jsonSchema({ type: 'array', items: { type: 'string' } }))
+ * ```
+ *
+ * @param body - The JSON schema. Its `type` decides object vs array.
+ * @returns A type descriptor for `.var()` / `.input()` / `.output()`.
+ */
+export function jsonSchema(body) {
+    return { type: 'jsonSchema', body };
+}
+/** Normalize a variable spec (a bare {@link TypeDesc}, a {@link JsonSchemaType}, or `{ type, default?, body? }`). */
+function normVarSpec(spec) {
+    if (typeof spec === 'string')
+        return { type: spec };
+    return { type: spec.type, default: spec.default, body: spec.body };
+}
+class TaskBuilder {
+    _name;
+    _kind;
+    _ref;
+    _action;
+    _connector;
+    _external;
+    _timer;
+    _waitConnector;
+    _required;
+    _runOnce;
+    _description;
+    _skip;
+    _inputs;
+    _outputs;
+    _entry = [];
+    constructor(_name) {
+        this._name = _name;
+    }
+    setKind(kind) {
+        if (this._kind)
+            throw new Error(`task "${this._name}": kind already set to "${this._kind}", cannot also be "${kind}".`);
+        this._kind = kind;
+    }
+    reference(kind, name, opts = {}) {
+        this.setKind(kind);
+        this._ref = { name, folderPath: opts.folder ?? '' };
+        return this;
+    }
+    /**
+     * Reference a published Maestro process.
+     *
+     * @param name - The published process's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    process(name, opts) {
+        return this.reference('process', name, opts);
+    }
+    /**
+     * Preserve an explicitly unresolved published-resource task as a typed
+     * skeleton whose serialized `data` is `{}`.
+     *
+     * @remarks
+     * Use this only when the requested resource identity cannot be resolved.
+     * Do not invent a name or folder. An unresolved task cannot declare input or
+     * output bindings because there is no referenced contract to bind against.
+     *
+     * @param kind - The published-resource family to preserve.
+     * @returns This builder, so calls chain.
+     */
+    unresolved(kind) {
+        this.setKind(kind);
+        return this;
+    }
+    /**
+     * Reference a published agent.
+     *
+     * @param name - The published agent's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    agent(name, opts) {
+        return this.reference('agent', name, opts);
+    }
+    /**
+     * Reference a published RPA process.
+     *
+     * @param name - The published RPA process's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    rpa(name, opts) {
+        return this.reference('rpa', name, opts);
+    }
+    /**
+     * Reference a published API workflow.
+     *
+     * @param name - The published API workflow's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    apiWorkflow(name, opts) {
+        return this.reference('api-workflow', name, opts);
+    }
+    /**
+     * Reference another published case (a **sub-case**). Pass data into the child
+     * with `.inputs({...})` and read results back with `.outputs({...})` — the same
+     * io-binding as reference-mode tasks.
+     *
+     * @param name - The published child case's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    caseManagement(name, opts) {
+        return this.reference('case-management', name, opts);
+    }
+    /**
+     * Reference a published Maestro Flow.
+     *
+     * @param name - The published Flow's name.
+     * @param opts - `folder` — the Orchestrator folder it lives in.
+     * @returns This builder, so calls chain.
+     */
+    flowProcess(name, opts) {
+        return this.reference('flow-process', name, opts);
+    }
+    external(kind, descriptor, opts) {
+        this.setKind(kind);
+        this._external = {
+            mode: opts.mode,
+            connector: makeConnector(descriptor, opts.inputs, {
+                connection: opts.connection,
+                folder: opts.folder,
+            }),
+        };
+        return this;
+    }
+    /**
+     * Invoke an external agent through its generated Integration Service descriptor.
+     *
+     * @param descriptor - An `AgentExecution` operation from a generated connector module.
+     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @returns This builder, so calls chain.
+     */
+    externalAgent(descriptor, opts) {
+        return this.external('external-agent', descriptor, opts);
+    }
+    /**
+     * Invoke an external workflow through its generated Integration Service descriptor.
+     *
+     * @param descriptor - A `ProcessExecution` operation from a generated connector module.
+     * @param opts - Required connection/folder bindings, sync/async mode, and descriptor-typed inputs.
+     * @returns This builder, so calls chain.
+     */
+    externalWorkflow(descriptor, opts) {
+        return this.external('external-workflow', descriptor, opts);
+    }
+    /**
+     * An Action Center human task. `recipient` may be an email (→ Type 2) or
+     * `{ type, value }`. `inputs`/`outputs` declare the task's form fields — inputs
+     * are read-only context the assignee sees, outputs are what they fill in.
+     * `labels` and `actionCatalogName` tag the task and name its action app.
+     *
+     * @param spec - The human task: its `title`, `priority`, `recipient`, and the `inputs` / `outputs` its form shows and collects.
+     * @returns This builder, so calls chain.
+     */
+    action(spec = {}) {
+        this.setKind('action');
+        const recipient = typeof spec.recipient === 'string' ? { type: 2, value: spec.recipient } : spec.recipient;
+        this._action = {
+            title: spec.title,
+            priority: spec.priority,
+            recipient,
+            labels: spec.labels,
+            actionCatalogName: spec.actionCatalogName,
+            inputs: spec.inputs,
+            outputs: spec.outputs,
+        };
+        return this;
+    }
+    connector(a, b, c, d) {
+        this.setKind('connector');
+        // Reuse the shared connector() so descriptor/nodeType splitting + version
+        // handling match the Flow surface exactly; store the connector ActionSpec.
+        this._connector = makeConnector(a, b, c, d);
+        return this;
+    }
+    waitForConnector(descriptorOrSpec = {}, opts) {
+        this.setKind('wait-for-connector');
+        this._waitConnector = isTriggerDescriptor(descriptorOrSpec)
+            ? subscriptionFrom(descriptorOrSpec, opts)
+            : descriptorOrSpec;
+        return this;
+    }
+    /**
+     * A wait-for-timer task (ISO-8601 `duration`, ISO `date`, or repeating `cycle`).
+     *
+     * @param spec - How long to wait: an ISO-8601 `duration`, a `date`, or a repeating `cycle`.
+     * @returns This builder, so calls chain.
+     */
+    waitForTimer(spec) {
+        this.setKind('wait-for-timer');
+        this._timer = spec;
+        return this;
+    }
+    /**
+     * Mark this task required, so its stage cannot complete without it.
+     *
+     * @param value - Whether the task is required.
+     * @returns This builder, so calls chain.
+     */
+    required(value = true) {
+        this._required = value;
+        return this;
+    }
+    /**
+     * Run this task at most once, even if its entry condition is met again.
+     *
+     * @param value - Whether the task runs only once.
+     * @returns This builder, so calls chain.
+     */
+    runOnce(value = true) {
+        this._runOnce = value;
+        return this;
+    }
+    /**
+     * Run this task again whenever its entry condition is met after stage re-entry.
+     * This is the semantic inverse of {@link TaskBuilder.runOnce} and emits an explicit
+     * `shouldRunOnlyOnce: false`.
+     *
+     * @returns This builder, so calls chain.
+     */
+    runOnReEntry() {
+        this._runOnce = false;
+        return this;
+    }
+    /**
+     * Describe this task.
+     *
+     * @param text - Prose the designer shows on the task.
+     * @returns This builder, so calls chain.
+     */
+    description(text) {
+        this._description = text;
+        return this;
+    }
+    /**
+     * Skip this task when the `=js:` expression is truthy.
+     *
+     * @param expression - An `=js:` expression; the task is skipped when it is truthy.
+     * @returns This builder, so calls chain.
+     */
+    skipWhen(expression) {
+        this._skip = expression;
+        return this;
+    }
+    /**
+     * Bind resource **input** parameters (reference-mode tasks). Each key is a
+     * declared input parameter name; each value is a literal, a case-variable read
+     * `=vars.<name>`, or a `=js:` expression. Pass `{ value, type }` to set a
+     * non-string type (default `string`).
+     *
+     * @param shape - Input parameter names to literals, case-variable references, or `{ value, type }`.
+     * @returns This builder, so calls chain.
+     */
+    inputs(shape) {
+        this._inputs ??= [];
+        for (const [name, v] of Object.entries(shape)) {
+            const value = typeof v === 'string' ? v : v.value;
+            const type = (typeof v === 'string' ? 'string' : (v.type ?? 'string'));
+            this._inputs.push({ name, value, type });
+        }
+        return this;
+    }
+    /**
+     * Extract fields of the task's **result** into case variables (reference-mode
+     * tasks). Each key is the case-variable name a later task/condition reads as
+     * `=vars.<name>`; each value is the source field expression (e.g. `=response`,
+     * `=Error.Message`). Pass `{ source, type }` to set a non-string type. Emits a
+     * `data.outputs[]` row plus a root `inputOutputs` companion so the name resolves.
+     *
+     * @param shape - Case-variable names to the result field they take, or `{ source, type }`.
+     * @returns This builder, so calls chain.
+     */
+    outputs(shape) {
+        this._outputs ??= [];
+        for (const [name, v] of Object.entries(shape)) {
+            const source = typeof v === 'string' ? v : v.source;
+            const type = (typeof v === 'string' ? 'string' : (v.type ?? 'string'));
+            this._outputs.push({ var: name, source, type });
+        }
+        return this;
+    }
+    /**
+     * Add a task-entry condition. Pass a nested array for the complete OR-of-AND grid.
+     *
+     * @param rules - One rule, an AND-group, or the complete OR-of-AND grid.
+     * @param opts - `displayName` for the condition.
+     * @returns This builder, so calls chain.
+     */
+    entryWhen(rules, opts = {}) {
+        this._entry.push({ displayName: opts.displayName, rules: ruleGroups(rules, 'task-entry') });
+        return this;
+    }
+    /** @internal */
+    _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']);
+        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), 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 {
+            name: this._name,
+            kind: this._kind,
+            ref: this._ref,
+            action: this._action,
+            connector: this._connector,
+            external: this._external,
+            timer: this._timer,
+            waitConnector: this._waitConnector,
+            required: this._required,
+            runOnce: this._runOnce,
+            description: this._description,
+            skip: this._skip,
+            inputs: this._inputs,
+            outputs: this._outputs,
+            entry: this._entry,
+        };
+    }
+}
+class StageBuilder {
+    _label;
+    _exception;
+    _description;
+    _required;
+    _lanes = [];
+    _entry = [];
+    _exit = [];
+    _sla = [];
+    constructor(_label, _exception) {
+        this._label = _label;
+        this._exception = _exception;
+    }
+    /**
+     * Describe this stage.
+     *
+     * @param text - Prose the designer shows on the stage.
+     * @returns This builder, so calls chain.
+     */
+    description(text) {
+        this._description = text;
+        return this;
+    }
+    /**
+     * Mark this stage required, so the case cannot complete without it.
+     *
+     * @param value - Whether the stage is required.
+     * @returns This builder, so calls chain.
+     */
+    required(value = true) {
+        this._required = value;
+        return this;
+    }
+    /**
+     * Add a task. `fn` receives a task sub-builder. `lane` is the index of the
+     * task's SET in `data.tasks[][]` (default 0) and orders SEQUENTIAL sets — a
+     * task whose entry conditions are all `runs-sequentially` waits for the
+     * previous set. It does NOT make tasks parallel: every other task runs when
+     * its own entry condition fires, whatever set it sits in.
+     *
+     * Two tasks on `current-stage-entered` therefore convert to byte-identical
+     * scheduler rules whether they share a set or not, and the designer writes
+     * one task per set even for a stage its own SDD calls parallel.
+     *
+     * @param displayName - The task's display name.
+     * @param fn - Receives a sub-builder for what the task does.
+     * @param opts - `lane` is the task's set index in `data.tasks[][]` (default 0);
+     *   it orders `runs-sequentially` sets and is inert for every other task.
+     * @returns This builder, so calls chain.
+     */
+    task(displayName, fn, opts = {}) {
+        const tb = new TaskBuilder(displayName);
+        fn(tb);
+        const lane = opts.lane ?? 0;
+        while (this._lanes.length <= lane)
+            this._lanes.push([]);
+        this._lanes[lane].push(tb._build());
+        return this;
+    }
+    /**
+     * Add a stage-entry condition. Pass a nested array for the complete OR-of-AND grid.
+     *
+     * @param rules - One rule, an AND-group, or the complete OR-of-AND grid.
+     * @param opts - `displayName`, and the entry behaviour flags.
+     * @returns This builder, so calls chain.
+     */
+    entryWhen(rules, opts = {}) {
+        this._entry.push({ displayName: opts.displayName, isInterrupting: opts.isInterrupting, rules: ruleGroups(rules, 'stage-entry') });
+        return this;
+    }
+    /**
+     * Add a stage-exit condition. Pass a nested array for the complete OR-of-AND grid.
+     *
+     * @param rules - One rule, an AND-group, or the complete OR-of-AND grid.
+     * @param opts - `displayName`, and whether meeting it completes the stage.
+     * @returns This builder, so calls chain.
+     */
+    exitWhen(rules, opts = {}) {
+        this._exit.push({
+            displayName: opts.displayName,
+            marksStageComplete: opts.marksStageComplete,
+            type: opts.type,
+            exitToStage: opts.exitToStage,
+            selectNextStage: opts.selectNextStage,
+            rules: ruleGroups(rules, 'stage-exit'),
+        });
+        return this;
+    }
+    /**
+     * Set an SLA (deadline + escalations) on this stage. Call more than once for
+     * conditional SLAs (each with a `when` gate); the default SLA (no `when`) must
+     * be last.
+     *
+     * @param opts - The deadline, its escalations, and an optional `when` gate.
+     * @returns This builder, so calls chain.
+     */
+    sla(opts) {
+        this._sla.push(buildSla(opts));
+        return this;
+    }
+    /** @internal */
+    _build() {
+        return {
+            label: this._label,
+            exception: this._exception,
+            description: this._description,
+            required: this._required,
+            lanes: this._lanes.length ? this._lanes : [[]],
+            entry: this._entry,
+            exit: this._exit,
+            slaRules: this._sla,
+        };
+    }
+}
+class CaseBuilder {
+    _id;
+    _name;
+    _authoredVersion;
+    _schemaVersion;
+    _description;
+    _identifier;
+    _identifierType = 'constant';
+    _caseApp = false;
+    _caseAppConfig;
+    _allowAdhocTasks;
+    _layout;
+    _vars = [];
+    _stages = [];
+    _caseExit = [];
+    _sla = [];
+    _triggers = [];
+    constructor(_id) {
+        this._id = _id;
+        this._name = _id;
+    }
+    /**
+     * Set the case plan's display name.
+     *
+     * @param n - The name the designer shows.
+     * @returns This builder, so calls chain.
+     */
+    name(n) {
+        this._name = n;
+        return this;
+    }
+    /**
+     * Set the case plan's schema version during the compatibility window.
+     *
+     * @deprecated Use {@link CaseBuilder.schemaVersion}, which declares the same
+     * concept and accepts only versions this build can actually write. This call
+     * was never a switch: it recorded a requested version that `check()` then
+     * compared against the serializer's profile.
+     * @param v - The legacy requested schema version.
+     * @returns This builder, so calls chain.
+     */
+    version(v) {
+        this._authoredVersion = v;
+        return this;
+    }
+    /**
+     * Declare the Case JSON SCHEMA version this plan targets.
+     *
+     * @remarks
+     * The top-level `version` of a `caseplan.json` is a claim that the whole
+     * document matches that grammar — `@uipath/case-schema` ships one closed
+     * schema per version — so this accepts only what the serializer can emit,
+     * currently `30.0.0` alone. Omit it and the plan declares the same thing;
+     * declaring it explicitly is what lets `case-decompile` PRESERVE the version
+     * it read rather than re-stamping the SDK's own default, so a later write-floor
+     * bump cannot silently upgrade a document a decompile already captured.
+     *
+     * Case has no `migrate` command: documents move forward on read, through the
+     * platform's feature-flag-gated chain. An older version is therefore refused
+     * with the reason rather than written onto V30 bytes.
+     *
+     * @example
+     * ```ts
+     * casePlan('claims').schemaVersion('30.0.0')
+     * ```
+     *
+     * @param version - A writable Case JSON schema version, e.g. `'30.0.0'`.
+     * @returns This builder, so calls chain.
+     * @throws Error when this SDK build cannot write `version`.
+     * @defaultValue `'30.0.0'` — `CASE_FORMAT_PROFILE.writeVersion`.
+     */
+    schemaVersion(version) {
+        const refusal = schemaVersionRefusal(CASE_SCHEMA_VERSIONS, version);
+        if (refusal)
+            throw new Error(refusal);
+        this._schemaVersion = version;
+        return this;
+    }
+    /**
+     * Describe the case plan.
+     *
+     * @param text - Prose the designer shows alongside the plan.
+     * @returns This builder, so calls chain.
+     */
+    description(text) {
+        this._description = text;
+        return this;
+    }
+    /**
+     * Set the runtime case identifier (constant prefix, or an `=`-expression when type is `external`).
+     *
+     * @param id - The prefix, or an `=`-expression when `type` is `'external'`.
+     * @param type - `'constant'` for a fixed prefix, `'external'` to compute it.
+     * @returns This builder, so calls chain.
+     */
+    identifier(id, type = 'constant') {
+        this._identifier = id;
+        this._identifierType = type;
+        return this;
+    }
+    /**
+     * Turn the generated Case App on or off, or configure its summary and sections.
+     *
+     * Section `details` are authored as a map of at most six primitive values; the
+     * serializer JSON-encodes that map into the shipped wire string. Configuring a
+     * Case App enables it. The platform-owned Case App version markers are never
+     * inferred by this method.
+     *
+     * @example
+     * **Configure a summary and one detail section**
+     * ```ts
+     * .caseApp({
+     *   summary: '=js:vars.summary',
+     *   sections: [{ title: 'Amounts', details: { total: '=js:vars.total', urgent: true } }],
+     * })
+     * ```
+     *
+     * @param enabledOrConfig - A boolean toggle, or the typed Case App configuration.
+     * @returns This builder, so calls chain.
+     */
+    caseApp(enabledOrConfig = true) {
+        if (typeof enabledOrConfig === 'boolean') {
+            this._caseApp = enabledOrConfig;
+        }
+        else {
+            this._caseApp = true;
+            this._caseAppConfig = enabledOrConfig;
+        }
+        return this;
+    }
+    /**
+     * Enable optional tasks whose entry rule is `adhoc`, allowing them to be
+     * started through the Case ad-hoc message contract.
+     *
+     * @param enabled - Whether ad-hoc optional-stage tasks are enabled.
+     * @returns This builder, so calls chain.
+     */
+    allowAdhocTasks(enabled = true) {
+        this._allowAdhocTasks = enabled;
+        return this;
+    }
+    /**
+     * Set optional designer layout for stages and triggers by their author-level
+     * names. This metadata does not affect Case behavior. Unknown or ambiguous
+     * names fail serialization rather than being silently dropped.
+     *
+     * When editing a decompiled foreign Case, an authored field wins only for the
+     * named node and field; all other preserved layout bytes remain untouched.
+     *
+     * @example
+     * **Move a stage and a named trigger**
+     * ```ts
+     * .layout({
+     *   stages: { Intake: { position: { x: 160, y: 120 } } },
+     *   triggers: { 'Order received': { position: { x: 40, y: 120 } } },
+     * })
+     * ```
+     *
+     * @param layout - Stage and trigger layout keyed by their exact display names.
+     * @returns This builder, so calls chain.
+     */
+    layout(layout) {
+        this._layout = layout;
+        return this;
+    }
+    /**
+     * Declare case In-args. Each value is a {@link TypeDesc}, or `{ type, default }`
+     * to set a default. Pass `{ from: <trigger> }` to bind the args to a trigger —
+     * their value arrives when it fires, readable as `=vars.<name>` — and they are
+     * projected into that trigger's `entry-points.json` input schema. A declared
+     * In-arg is readable as `=vars.<name>` (its `inputOutputs` companion resolves it).
+     *
+     * @example
+     * **Bind case In-args to a trigger's payload**
+     * ```ts
+     * const t = manualTrigger();
+     * casePlan('x').trigger(t)
+     *   .input({ claimId: 'string', riskScore: { type: 'float', default: '1.5' } }, { from: t })
+     * ```
+     *
+     * @param shape - In-arg names to types, or `{ type, default }`.
+     * @param opts - `{ from: <trigger> }` binds the args to a trigger's payload.
+     * @returns This builder, so calls chain.
+     */
+    input(shape, opts = {}) {
+        for (const [name, spec] of Object.entries(shape)) {
+            const { type, default: def, body } = normVarSpec(spec);
+            this._vars.push({ name, type, direction: 'in', default: def, body, sourceTrigger: opts.from });
+        }
+        return this;
+    }
+    /**
+     * Declare case Out-args. Each value is a {@link TypeDesc}, or `{ type, default }`
+     * to set a default. Out-args are readable as `=vars.<name>` and projected into
+     * every trigger's `entry-points.json` output schema (with their default).
+     *
+     * @param shape - Out-arg names to types, or `{ type, default }`.
+     * @returns This builder, so calls chain.
+     */
+    output(shape) {
+        for (const [name, spec] of Object.entries(shape)) {
+            const { type, default: def, body } = normVarSpec(spec);
+            this._vars.push({ name, type, direction: 'out', default: def, body });
+        }
+        return this;
+    }
+    /**
+     * Declare a read/write case variable.
+     *
+     * @remarks
+     * Readable from a `=js:vars.<name>` expression, like a trigger-bound In-arg.
+     *
+     * This comment used to say the opposite — that only `.input(shape, { from })`
+     * could be read, and that a bare `.var()` failed `uip maestro case validate`
+     * with "Variable 'vars.<name>' does not exist". That was true when written and
+     * stopped being true at #257, which made the serializer emit the `inputOutputs`
+     * companion (`id: <name>`, `elementId: "root"`) the platform resolves
+     * `vars.<name>` against. `check` carried a matching `VAR_NOT_REFERENCEABLE`
+     * error and dropped it for the same reason.
+     *
+     * Binding is about WHEN a value arrives, not whether it can be read. An
+     * UNDECLARED `vars.<x>` is still a hard error, thrown by `.build()`.
+     *
+     * @param name - The variable's name; read it as `=vars.<name>`.
+     * @param type - A `types.*` descriptor, or {@link jsonSchema} for a structured one.
+     * @param defaultValue - Its initial value. Non-string values are JSON-encoded
+     * before emission because the Case artifact contract stores every default as
+     * a string. Omit it to start unset.
+     * @returns This builder, so calls chain.
+     */
+    var(name, type, defaultValue) {
+        const { type: t, body } = normVarSpec(type);
+        this._vars.push({ name, type: t, direction: 'inout', default: defaultValue, body });
+        return this;
+    }
+    /**
+     * Add a case trigger (what starts the case). Call more than once for
+     * multiple triggers; the first is the primary. Omit entirely for the default
+     * single manual trigger. Build specs with {@link manualTrigger}/{@link timerTrigger}.
+     *
+     * @param t - A trigger from `manualTrigger` / `timerTrigger` / `eventTrigger`.
+     * @returns This builder, so calls chain.
+     */
+    trigger(t) {
+        this._triggers.push(t);
+        return this;
+    }
+    /**
+     * Add a primary stage. `fn` receives a stage sub-builder.
+     *
+     * @param label - The stage's display name.
+     * @param fn - Receives a sub-builder for the stage's tasks and conditions.
+     * @returns This builder, so calls chain.
+     */
+    stage(label, fn) {
+        const sb = new StageBuilder(label, false);
+        fn(sb);
+        this._stages.push(sb._build());
+        return this;
+    }
+    /**
+     * Add a secondary/exception stage (`case-management:Stage` with `data.stageType: "secondary"`).
+     *
+     * @param label - The stage's display name.
+     * @param fn - Receives a sub-builder for the stage's tasks and conditions.
+     * @returns This builder, so calls chain.
+     */
+    exceptionStage(label, fn) {
+        const sb = new StageBuilder(label, true);
+        fn(sb);
+        this._stages.push(sb._build());
+        return this;
+    }
+    /**
+     * Add a case-completion rule (`metadata.caseExitRules`, `marksCaseComplete: true` by default).
+     *
+     * @param rules - One rule, an AND-group, or the complete OR-of-AND grid.
+     * @param opts - `displayName`, and whether meeting it completes the case.
+     * @returns This builder, so calls chain.
+     */
+    completeWhen(rules, opts = {}) {
+        this._caseExit.push({
+            displayName: opts.displayName,
+            marksCaseComplete: opts.marksCaseComplete ?? true,
+            rules: ruleGroups(rules, 'case-exit'),
+        });
+        return this;
+    }
+    /**
+     * Set a case-level SLA (deadline + escalations for the whole case), emitted to
+     * `metadata.slaRules`. Call more than once for conditional SLAs; the default
+     * (no `when`) must be last.
+     *
+     * @param opts - The deadline, its escalations, and an optional `when` gate.
+     * @returns This builder, so calls chain.
+     */
+    sla(opts) {
+        this._sla.push(buildSla(opts));
+        return this;
+    }
+    /**
+     * Finish the plan and return the description the serializer writes.
+     *
+     * @returns The built case — its stages, tasks, triggers and variables.
+     */
+    build() {
+        const built = {
+            id: this._id,
+            name: this._name,
+            version: this._schemaVersion ?? CASE_FORMAT_PROFILE.writeVersion,
+            description: this._description,
+            identifier: this._identifier ?? this._name,
+            identifierType: this._identifierType,
+            caseAppEnabled: this._caseApp,
+            ...(this._caseAppConfig ? { caseAppConfig: this._caseAppConfig } : {}),
+            ...(this._allowAdhocTasks !== undefined
+                ? { allowAdhocOptionalStageTasks: this._allowAdhocTasks }
+                : {}),
+            vars: this._vars,
+            stages: this._stages,
+            caseExit: this._caseExit,
+            slaRules: this._sla,
+            triggers: this._triggers,
+            ...(this._layout ? { layout: this._layout } : {}),
+        };
+        if (this._authoredVersion !== undefined)
+            recordAuthoredCaseVersion(built, this._authoredVersion);
+        // First-level validation, intrinsic to running the SDK: catch a reference to
+        // an undeclared `vars.<name>` HERE, before the caseplan is serialized, rather
+        // than three steps later at `uip maestro case validate`. See case-expr-check.
+        const errors = checkCaseExpressions(built).filter((d) => d.level === 'error');
+        if (errors.length)
+            throw new CaseBuildError(built, errors);
+        return built;
+    }
+}
+/**
+ * Start building a case plan with the given id. (`casePlan`, not `case` — reserved word.)
+ *
+ * @param id - The plan's stable identifier.
+ * @returns A {@link CaseBuilder} to declare stages and tasks on.
+ */
+export function casePlan(id) {
+    return new CaseBuilder(id);
+}