@bpmnkit/core 0.1.1 → 0.2.0

package/dist/bpmn/bpmn-builder.d.ts

@@ -4,11 +4,15 @@ import type { RestConnectorConfig } from "./rest-connector.js";
 export interface ElementOptions {
     name?: string;
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
+    documentation?: string;
 }
 /** Options for send/receive task elements. */
 export interface MessageTaskOptions extends ElementOptions {
     /** Message name — generates or reuses a root <bpmn:message> and sets messageRef. */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). */
+    correlationKey?: string;
 }
 /** Options for creating a start event. */
 export interface StartEventOptions extends ElementOptions {
@@ -58,6 +62,11 @@ export interface ServiceTaskOptions {
     };
     /** Task header key-value pairs. */
     taskHeaders?: Record<string, string>;
+    /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
+    zeebeProperties?: Array<{
+        name: string;
+        value: string;
+    }>;
     /** Zeebe modeler template ID. */
     modelerTemplate?: string;
     /** Zeebe modeler template version. */
@@ -66,6 +75,8 @@ export interface ServiceTaskOptions {
     modelerTemplateIcon?: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
+    documentation?: string;
 }
 /** Options for creating a script task. */
 export interface ScriptTaskOptions {
@@ -77,6 +88,8 @@ export interface ScriptTaskOptions {
     resultVariable: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for creating a user task. */
 export interface UserTaskOptions {
@@ -88,6 +101,20 @@ export interface UserTaskOptions {
     zeebeUserTask?: boolean;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
+    /** Static assignee (`zeebe:assignmentDefinition assignee`). FEEL expressions must start with "=". */
+    assignee?: string;
+    /** Candidate groups, comma-separated or a FEEL expression (`zeebe:assignmentDefinition candidateGroups`). */
+    candidateGroups?: string;
+    /** Candidate users, comma-separated or a FEEL expression (`zeebe:assignmentDefinition candidateUsers`). */
+    candidateUsers?: string;
+    /** Due date — ISO 8601 or FEEL expression (`zeebe:taskSchedule dueDate`). */
+    dueDate?: string;
+    /** Follow-up date — ISO 8601 or FEEL expression (`zeebe:taskSchedule followUpDate`). */
+    followUpDate?: string;
+    /** Task priority 0-100, default 50 (`zeebe:priorityDefinition`). */
+    priority?: number;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -99,6 +126,8 @@ export interface CallActivityOptions {
     propagateAllChildVariables?: boolean;
     /** Mark this activity as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for creating a business rule task. */
 export interface BusinessRuleTaskOptions {
@@ -112,12 +141,60 @@ export interface BusinessRuleTaskOptions {
     resultVariable?: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for gateway elements. */
 export interface GatewayOptions extends ElementOptions {
     /** ID of the default sequence flow (set manually; prefer branch().defaultFlow()). */
     defaultFlow?: string;
 }
+/** Options for {@link ProcessBuilder.build}. */
+export interface BuildOptions {
+    /**
+     * Refuse to infer join gateways, so converging branches must be declared.
+     *
+     * Generated code should set this: the builder's inference is a help to someone
+     * reading the chain they just wrote, and a silent topology change to a model
+     * that cannot see what it did not emit.
+     */
+    explicitJoins?: boolean;
+    /**
+     * The former name for {@link BuildOptions.explicitJoins}, still honoured.
+     *
+     * Renamed because "strict" says nothing about what it is strict *about*, and
+     * because `applyBpmnOperations` takes a `strict` that means something else
+     * entirely — whether to throw or report problems.
+     *
+     * @deprecated Use `explicitJoins`.
+     */
+    strict?: boolean;
+}
+/** Options for a collaboration participant (a pool). */
+export interface ParticipantOptions {
+    /** Pool label. */
+    name?: string;
+    /** Id of the process this pool executes. Omit for a black box. */
+    processId?: string;
+}
+/** Options for a root-level message declared on a diagram. */
+export interface DiagramMessageOptions {
+    /** Message name, which is what Camunda 8 publishes against. */
+    name?: string;
+    /** FEEL expression Camunda 8 correlates published messages on (`zeebe:subscription`). */
+    correlationKey?: string;
+}
+/** Options for a message flow between two pools. */
+export interface MessageFlowOptions {
+    /** Id of the participant, or of a flow node inside one, the message leaves. */
+    source: string;
+    /** Id of the participant, or of a flow node inside one, the message reaches. */
+    target: string;
+    /** Flow label. */
+    name?: string;
+    /** Id of a message declared with `.message()`. */
+    messageRef?: string;
+}
 /** Options for an intermediate catch event. */
 export interface IntermediateCatchEventOptions extends ElementOptions {
     /** Timer duration (ISO 8601) — creates a timer catch event. */
@@ -128,6 +205,8 @@ export interface IntermediateCatchEventOptions extends ElementOptions {
     timerCycle?: string;
     /** Message name — creates a message catch event (aspirational). */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). Required for a deployable message catch when `messageName` is set. */
+    correlationKey?: string;
     /** Signal name — creates a signal catch event (aspirational). */
     signalName?: string;
 }
@@ -175,6 +254,8 @@ export interface BoundaryEventOptions extends ElementOptions {
     timerCycle?: string;
     /** Message name — creates a message boundary event (aspirational). */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). Required for a deployable message boundary event when `messageName` is set. */
+    correlationKey?: string;
     /** Signal name — creates a signal boundary event (aspirational). */
     signalName?: string;
     /** Creates a compensation boundary event. */
@@ -217,6 +298,11 @@ export interface AdHocSubProcessOptions extends ElementOptions {
     };
     /** Task header key-value pairs. */
     taskHeaders?: Record<string, string>;
+    /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
+    zeebeProperties?: Array<{
+        name: string;
+        value: string;
+    }>;
     /** Multi-instance loop configuration. */
     loopCharacteristics?: {
         inputCollection: string;
@@ -231,6 +317,13 @@ export interface AdHocSubProcessOptions extends ElementOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /**
+     * FEEL expression evaluated after each tool activity completes; ends the
+     * ad-hoc scope when true (`bpmn:completionCondition`).
+     */
+    completionCondition?: string;
+    /** Whether still-running inner activity instances are cancelled once the completion condition is met (default true). */
+    cancelRemainingInstances?: boolean;
 }
 /**
  * Builder for a single named branch path from a gateway.
@@ -241,6 +334,8 @@ export interface AdHocSubProcessOptions extends ElementOptions {
 export declare class BranchBuilder {
     /** @internal */
     readonly _elements: BpmnFlowElement[];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    private readonly _ids;
     /** @internal */
     readonly _flows: BpmnSequenceFlow[];
     /** @internal */
@@ -340,6 +435,8 @@ export declare class BranchBuilder {
 export declare class SubProcessContentBuilder {
     /** @internal */
     readonly _elements: BpmnFlowElement[];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    private readonly _ids;
     /** @internal */
     readonly _flows: BpmnSequenceFlow[];
     /** @internal */
@@ -354,6 +451,15 @@ export declare class SubProcessContentBuilder {
     /** @internal */
     constructor(rootMessages?: BpmnMessage[]);
     private addElement;
+    /**
+     * Add an element with no sequence-flow wiring and no cursor movement.
+     *
+     * Used for ad-hoc sub-process tool activities, which the AI Agent connector
+     * requires to be root nodes (no incoming sequence flow, not a boundary event).
+     * Unlike `serviceTask()`/`userTask()`/etc., this does not auto-connect from
+     * the current cursor and does not move it.
+     */
+    addDisconnected(element: BpmnFlowElement): this;
     startEvent(id?: string, options?: StartEventOptions): this;
     endEvent(id?: string, options?: EndEventOptions): this;
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
@@ -408,8 +514,12 @@ export declare class ProcessBuilder {
     private readonly processId;
     private processName?;
     private _isExecutable;
+    /** Whether `executable()` was called, so continue-mode leaves it alone if not. */
+    private _executableSet;
     private _versionTag?;
     private readonly flowElements;
+    /** Ids in `flowElements`, for O(1) duplicate and existence checks. */
+    private readonly elementIds;
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
@@ -425,7 +535,69 @@ export declare class ProcessBuilder {
     private _executionPlatformVersion;
     private _serviceTaskDefaults;
     private _savedMainFlowId;
+    /** Set by {@link ProcessBuilder.from}; makes `build()` update rather than generate. */
+    private _source?;
+    /** Pre-existing flow endpoints, so `build()` can prove it did not rewire them. */
+    private _sourceFlowTargets;
+    /** An `insertAfter` flow waiting to be reattached to what gets built next. */
+    private _pendingSpliceFlowId;
+    /** Flows the caller deliberately spliced, exempt from the rewiring guard. */
+    private readonly _splicedFlowIds;
     constructor(processId: string);
+    /**
+     * Continues an existing model rather than generating a new one.
+     *
+     * `build()` then returns *that document* with this process's contents
+     * replaced, so everything the builder has no opinion about — other processes,
+     * the collaboration, lanes, diagram interchange, root elements, imports,
+     * unmodelled content — is still there afterwards. Generating a replacement
+     * from scratch is what loses those.
+     *
+     * The input is not mutated; the builder works on a copy.
+     *
+     * @param definitions - The parsed model to continue.
+     * @param processId - Which process to continue. Named explicitly, because
+     *   "the first process" is a guess that goes wrong on a collaboration.
+     * @example
+     * ```typescript
+     * const updated = ProcessBuilder.from(Bpmn.parse(xml), "order")
+     *   .at("validate")
+     *   .serviceTask("notify", { name: "Notify", taskType: "notify" })
+     *   .build()
+     * ```
+     */
+    static from(definitions: BpmnDefinitions, processId: string): ProcessBuilder;
+    /**
+     * Moves the cursor to an existing flow node, so the next call chains from it.
+     *
+     * @param nodeId - A flow node directly contained by this process. Nodes inside
+     *   a sub-process are not reachable: continuing into one means building that
+     *   sub-process, not this one.
+     */
+    at(nodeId: string): this;
+    /**
+     * Splices what you build next into the path leaving an existing node.
+     *
+     * `insertAfter("validate")` followed by `.serviceTask("notify", …)` turns
+     * `validate → end` into `validate → notify → end`. The existing flow keeps its
+     * id and its target and only changes where it starts, so an edge nobody asked
+     * to move keeps its identity in the diagram and in a diff.
+     *
+     * This is the counterpart to {@link at}, which continues from a node whose
+     * path is open. Which one you mean is not guessable, so it is not guessed.
+     *
+     * @param nodeId - A flow node with exactly one outgoing sequence flow.
+     */
+    insertAfter(nodeId: string): this;
+    /** Points the cursor at an existing node and forgets any branch state. */
+    private moveCursor;
+    /**
+     * Reattaches the flow a pending `insertAfter` detached, to whatever the cursor
+     * has reached. With nothing built in between the cursor has not moved and this
+     * is a no-op, which is the right answer for `insertAfter(x)` followed by
+     * nothing.
+     */
+    private resolvePendingSplice;
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout(): this;
     /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
@@ -548,10 +720,50 @@ export declare class ProcessBuilder {
      *
      * Resolves all forward-referenced `incoming` / `outgoing` arrays and wraps
      * the process in a {@link BpmnDefinitions} ready for XML serialization.
+     *
+     * **The join contract.** Branches built with `.branch()` converge implicitly:
+     * where several paths from one gateway reach the same element, a matching join
+     * gateway is inserted for you. That is convenient by hand and a trap for
+     * generated code, which cannot see the element it did not write. Pass
+     * `{ explicitJoins: true }` to be told instead of helped — the build throws,
+     * naming the gateways it would have inserted, and you declare them yourself
+     * with `.connectTo(joinId)`.
+     *
+     * A join you declare only counts if it *matches the split*: an exclusive split
+     * converging on a parallel gateway is not the gateway inference would have
+     * added, so it is still inferred — and with `explicitJoins` that refusal is the
+     * only thing that tells you.
+     *
+     * {@link ProcessBuilder.from} never infers joins at all, whatever this option
+     * says: inference reads the whole topology, and on a document you were handed
+     * that means rewriting edges you never touched.
+     *
+     * @param options - `explicitJoins` refuses inferred join gateways. `strict` is
+     *   the former name for it and still works.
+     */
+    build(options?: BuildOptions): BpmnDefinitions;
+    /**
+     * Writes this process's contents back into the document it came from.
+     *
+     * Everything not listed here is kept by identity — other processes, the
+     * collaboration, diagram interchange, root elements, the process's own lanes,
+     * documentation, extensions and unmodelled content. That is the whole point of
+     * continuing rather than regenerating.
+     *
+     * Diagram interchange is *not* regenerated: existing shapes keep their
+     * positions, and elements added here have none until `withAutoLayout()` or a
+     * later `applyAutoLayout()` gives them one.
+     */
+    private buildOntoSource;
+    /**
+     * Refuses to rewire a flow that was already in the document.
+     *
+     * `insertJoinGateways` retargets converging flows, which is right for a
+     * topology this builder just created and wrong for one it was handed: a
+     * document would come back with edges the caller never touched pointing
+     * somewhere else. Continuing a model has to leave the model alone.
      */
-    build(options?: {
-        strict?: boolean;
-    }): BpmnDefinitions;
+    private assertSourceTopologyIntact;
     private validate;
     private addFlowElement;
 }
@@ -564,11 +776,61 @@ export declare class DiagramBuilder {
     private readonly _processes;
     private readonly _errors;
     private readonly _messages;
+    private readonly _participants;
+    private readonly _messageFlows;
+    private _collaborationId;
     private _executionPlatformVersion;
     constructor(id: string);
     /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
     executionPlatformVersion(version: string): this;
     process(id: string, callback: (b: ProcessBuilder) => void): this;
+    /** Renames the collaboration element. Defaults to `"Collaboration_1"`. */
+    collaborationId(id: string): this;
+    /**
+     * Adds a pool.
+     *
+     * Omit `processId` for a black box — a participant whose internals are not
+     * modelled. That is a real BPMN construct, not an incomplete one: it is how
+     * you draw the counterparty you exchange messages with but do not execute.
+     *
+     * @param id - The participant's element id, used verbatim.
+     */
+    participant(id: string, options?: ParticipantOptions): this;
+    /**
+     * Declares a root-level message, which a message flow may name and a Camunda 8
+     * message subscription correlates on.
+     *
+     * `ProcessBuilder` already creates messages by name for message events, so
+     * only call this for a message no event declared — typically one carried by a
+     * message flow between pools.
+     *
+     * @param id - The message's element id, used verbatim.
+     */
+    message(id: string, options?: DiagramMessageOptions): this;
+    /**
+     * Connects two pools.
+     *
+     * `source` and `target` name either participants or flow nodes inside them.
+     * Both forms are valid BPMN and the layout engine reads either, but they must
+     * be in *different* pools — a message flow is what crosses a pool boundary,
+     * and one that does not is the error this catches.
+     *
+     * @param id - The message flow's element id, used verbatim.
+     */
+    messageFlow(id: string, options: MessageFlowOptions): this;
+    /**
+     * Reports every way the declared collaboration would not survive contact with
+     * a modeler, so `build()` can refuse rather than emit a file that opens broken.
+     */
+    private collaborationProblems;
+    /** Maps every participant id and every flow node id to its owning participant. */
+    private participantIndex;
     build(): BpmnDefinitions;
+    /**
+     * A document with no participants has no collaboration — an empty
+     * `<bpmn:collaboration/>` is not a neutral addition, it makes every process a
+     * pool-less participant in a modeler.
+     */
+    private buildCollaborations;
 }
 //# sourceMappingURL=bpmn-builder.d.ts.map