@bpmnkit/core 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +31 -0
  2. package/dist/bpmn/bpmn-builder.d.ts +8 -0
  3. package/dist/bpmn/bpmn-builder.js +6 -2
  4. package/dist/bpmn/compact.d.ts +37 -5
  5. package/dist/bpmn/compact.js +218 -30
  6. package/dist/bpmn/connector-line.d.ts +46 -0
  7. package/dist/bpmn/connector-line.js +135 -0
  8. package/dist/bpmn/optimize/patterns.js +4 -3
  9. package/dist/bpmn/process-delta.d.ts +91 -0
  10. package/dist/bpmn/process-delta.js +259 -0
  11. package/dist/bpmn/process-text-writer.d.ts +63 -0
  12. package/dist/bpmn/process-text-writer.js +202 -0
  13. package/dist/bpmn/process-text.d.ts +200 -0
  14. package/dist/bpmn/process-text.js +1568 -0
  15. package/dist/bpmn/rest-connector.d.ts +6 -0
  16. package/dist/bpmn/rest-connector.js +6 -0
  17. package/dist/bpmn/secrets.d.ts +15 -0
  18. package/dist/bpmn/secrets.js +59 -0
  19. package/dist/bpmn/utils.js +4 -0
  20. package/dist/bpmn/zeebe-extensions.d.ts +10 -0
  21. package/dist/bpmn/zeebe-extensions.js +7 -0
  22. package/dist/connectors/aliases.d.ts +21 -0
  23. package/dist/connectors/aliases.js +272 -0
  24. package/dist/connectors/api.d.ts +118 -0
  25. package/dist/connectors/api.js +280 -0
  26. package/dist/connectors/apply-element.d.ts +59 -0
  27. package/dist/connectors/apply-element.js +385 -0
  28. package/dist/connectors/apply.d.ts +136 -0
  29. package/dist/connectors/apply.js +352 -0
  30. package/dist/connectors/cards.d.ts +96 -0
  31. package/dist/connectors/cards.js +306 -0
  32. package/dist/connectors/catalog.d.ts +79 -0
  33. package/dist/connectors/catalog.js +209 -0
  34. package/dist/connectors/index.d.ts +33 -0
  35. package/dist/connectors/index.js +24 -0
  36. package/dist/connectors/lines.d.ts +108 -0
  37. package/dist/connectors/lines.js +568 -0
  38. package/dist/connectors/select.d.ts +85 -0
  39. package/dist/connectors/select.js +419 -0
  40. package/dist/connectors/template-types.d.ts +188 -0
  41. package/dist/connectors/template-types.js +6 -0
  42. package/dist/connectors/templates/bpmnkit.d.ts +12 -0
  43. package/dist/connectors/templates/bpmnkit.js +186 -0
  44. package/dist/connectors/templates/generated.d.ts +3 -0
  45. package/dist/connectors/templates/generated.js +95885 -0
  46. package/dist/connectors/validate.d.ts +66 -0
  47. package/dist/connectors/validate.js +271 -0
  48. package/dist/index.d.ts +11 -1
  49. package/dist/index.js +5 -0
  50. package/package.json +5 -1
package/README.md CHANGED
@@ -33,6 +33,7 @@ Parse → Modify → Validate → Export
33
33
  - **Camunda Form Definitions** — type-safe form schema builder
34
34
  - **Optimizer** — built-in rule engine to detect and auto-fix anti-patterns
35
35
  - **Compact Format** — 70% smaller token-efficient JSON representation for AI/LLM workflows
36
+ - **Connector catalog** — all Camunda 8 out-of-the-box connector templates, applied deterministically (`@bpmnkit/core/connectors`)
36
37
  - **Zero Dependencies** — runs in browsers, Node.js, Deno, Bun, and edge runtimes
37
38
 
38
39
  ## Installation
@@ -308,6 +309,31 @@ import { writeBpmn } from "@bpmnkit/core/node"
308
309
  const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
309
310
  ```
310
311
 
312
+ ### Connectors (`@bpmnkit/core/connectors`)
313
+
314
+ The Camunda 8 out-of-the-box connector catalog, behind its own subpath so its data is only
315
+ bundled by code that imports it. The templates leave out icons, groups, tooltips and
316
+ placeholders; [`@bpmnkit/connectors`](https://www.npmjs.com/package/@bpmnkit/connectors)
317
+ adds those back for a property panel.
318
+
319
+ | Export | Description |
320
+ |--------|-------------|
321
+ | `listConnectors()` / `searchConnectors(query)` | Summaries: task type, direction, required and optional inputs |
322
+ | `applyConnectorTemplate(id, values)` | Builder options for a bundled template, plus problems |
323
+ | `applyTemplateToElement(defs, id, template, values)` | Apply a template to an existing element |
324
+ | `validateElementTemplate(value)` | Structural check of an element template |
325
+ | `findConnectorCards(query)` / `formatConnectorCard(card)` | One card per operation, with only its inputs — for a model's prompt |
326
+ | `applyConnectorLines(defs, lines)` | Apply the `with` lines a model wrote in the line format |
327
+ | `selectConnectors({ text, tasks })` | Pick the cards a model sees for each task of a diagram |
328
+
329
+ ```typescript
330
+ import { applyConnectorTemplate } from "@bpmnkit/core/connectors"
331
+
332
+ const { serviceTask, problems } = applyConnectorTemplate("io.camunda.connectors.HttpJson.v2", {
333
+ url: "https://api.example.com/orders",
334
+ })
335
+ ```
336
+
311
337
  ### DMN
312
338
 
313
339
  | Export | Description |
@@ -335,6 +361,10 @@ const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
335
361
  | `compactify(defs)` | Convert to compact `CompactDiagram` |
336
362
  | `expand(compact)` | Restore full `BpmnDefinitions` |
337
363
  | `createCompactStream(opts?)` | Read a diagram out of a model's token stream, frame by frame |
364
+ | `parseProcessText(text)` | Read a process a model wrote in the line format (`PROCESS_TEXT_GUIDE`); never throws |
365
+ | `createProcessTextStream()` | Read the line format while it streams, one finished line at a time |
366
+ | `writeProcessText(defs)` | Write an existing diagram in the line format, for a model to read; returns the text and an alias → element id map |
367
+ | `parseProcessDelta(text)` | Read a change script (`PROCESS_DELTA_GUIDE`): only what changes, by id; never throws |
338
368
  | `generateId(prefix)` | Generate a unique short ID |
339
369
 
340
370
  ### Process documentation
@@ -374,6 +404,7 @@ const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
374
404
  | [`@bpmnkit/patterns`](https://www.npmjs.com/package/@bpmnkit/patterns) | Domain process patterns for BPMNKit AIKit |
375
405
  | [`@bpmnkit/reebe-wasm`](https://www.npmjs.com/package/@bpmnkit/reebe-wasm) | WebAssembly BPMN engine for browser simulation |
376
406
  | [`@bpmnkit/worker-client`](https://www.npmjs.com/package/@bpmnkit/worker-client) | Thin Zeebe REST client for standalone workers |
407
+ | [`@bpmnkit/flow`](https://www.npmjs.com/package/@bpmnkit/flow) | Code-first durable flows that derive BPMN, job types and workers |
377
408
  | [`@bpmnkit/user-tasks`](https://www.npmjs.com/package/@bpmnkit/user-tasks) | Embeddable user task widget for Camunda 8 |
378
409
  | [`@bpmnkit/cli-sdk`](https://www.npmjs.com/package/@bpmnkit/cli-sdk) | Plugin authoring SDK for the casen CLI |
379
410
  | [`@bpmnkit/create-casen-plugin`](https://www.npmjs.com/package/@bpmnkit/create-casen-plugin) | Scaffold a new casen CLI plugin in seconds |
@@ -67,6 +67,10 @@ export interface ServiceTaskOptions {
67
67
  name: string;
68
68
  value: string;
69
69
  }>;
70
+ /** Marks the task as an AI agent the engine runs (`zeebe:agentDefinition`, Camunda 8.10+). */
71
+ agentDefinition?: {
72
+ agentType: string;
73
+ };
70
74
  /** Zeebe modeler template ID. */
71
75
  modelerTemplate?: string;
72
76
  /** Zeebe modeler template version. */
@@ -293,6 +297,10 @@ export interface AdHocSubProcessOptions extends ElementOptions {
293
297
  name: string;
294
298
  value: string;
295
299
  }>;
300
+ /** Marks the sub-process as an AI agent the engine runs (`zeebe:agentDefinition`, Camunda 8.10+). */
301
+ agentDefinition?: {
302
+ agentType: string;
303
+ };
296
304
  /** Multi-instance loop configuration. */
297
305
  loopCharacteristics?: {
298
306
  inputCollection: string;
@@ -2,7 +2,7 @@ import { ValidationError } from "../errors.js";
2
2
  import { generateId } from "../types/id-generator.js";
3
3
  import { applyAutoLayout } from "./auto-layout.js";
4
4
  import { createFlowElement } from "./element-shape.js";
5
- import { restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
5
+ import { REST_CONNECTOR_TEMPLATE_VERSION, restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
6
6
  import { assignStableFlowIds, rootDefinitionId } from "./stable-ids.js";
7
7
  import { ensureZeebeExtension, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
8
8
  // Keep in sync with packages/core/package.json version
@@ -266,6 +266,8 @@ function buildServiceTaskExtensions(options) {
266
266
  if (options.zeebeProperties) {
267
267
  extensions.properties = { properties: options.zeebeProperties };
268
268
  }
269
+ if (options.agentDefinition)
270
+ extensions.agentDefinition = options.agentDefinition;
269
271
  return zeebeExtensionsToXmlElements(extensions);
270
272
  }
271
273
  function makeConditionExpression(expression) {
@@ -294,6 +296,8 @@ function buildAdHocSubProcessExtensions(options) {
294
296
  if (options?.zeebeProperties) {
295
297
  zeebeExt.properties = { properties: options.zeebeProperties };
296
298
  }
299
+ if (options?.agentDefinition)
300
+ zeebeExt.agentDefinition = options.agentDefinition;
297
301
  const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
298
302
  const adHocAttrs = {};
299
303
  if (options?.activeElementsCollection) {
@@ -1914,7 +1918,7 @@ export class ProcessBuilder {
1914
1918
  // Stamp the template identifier so editors recognise this as a REST connector
1915
1919
  el.unknownAttributes = {
1916
1920
  "zeebe:modelerTemplate": "io.camunda.connectors.HttpJson.v2",
1917
- "zeebe:modelerTemplateVersion": "12",
1921
+ "zeebe:modelerTemplateVersion": REST_CONNECTOR_TEMPLATE_VERSION,
1918
1922
  };
1919
1923
  this.addFlowElement(el);
1920
1924
  return this;
@@ -19,12 +19,20 @@ export interface CompactElement {
19
19
  dataStoreRef?: string;
20
20
  /** dataObject / dataObjectReference: marks a collection. */
21
21
  isCollection?: boolean;
22
+ /** Zeebe task headers (key→value). */
23
+ taskHeaders?: Record<string, string>;
22
24
  /**
23
- * Zeebe task headers (key→value).
24
- * For the Camunda HTTP connector use jobType "io.camunda:http-json:1" and set:
25
- * url, method, and optionally headers/body/connectionTimeoutInSeconds.
25
+ * Zeebe input mappings (target→source); a source starting with `=` is FEEL.
26
+ * A connector reads its configuration from these: for the Camunda HTTP
27
+ * connector (jobType "io.camunda:http-json:1") set `url`, `method`, and
28
+ * optionally `headers`, `queryParameters`, `body`, `authentication.type`.
26
29
  */
27
- taskHeaders?: Record<string, string>;
30
+ inputs?: Record<string, string>;
31
+ /** The element template applied to this element (`zeebe:modelerTemplate`). */
32
+ modelerTemplate?: {
33
+ id: string;
34
+ version?: number;
35
+ };
28
36
  /** Called process ID (callActivity: zeebe:calledElement.processId) */
29
37
  calledProcess?: string;
30
38
  /** Linked form ID (userTask: zeebe:formDefinition.formId) */
@@ -34,7 +42,9 @@ export interface CompactElement {
34
42
  /**
35
43
  * Primary output variable.
36
44
  * - For businessRuleTask: stored in zeebe:calledDecision.resultVariable.
37
- * - For serviceTask with jobType: stored as a zeebe:ioMapping output (source "= response").
45
+ * - For a Camunda connector job type (`io.camunda:…`): stored as the `resultVariable`
46
+ * task header, which is where the connector runtime reads it.
47
+ * - For any other serviceTask with jobType: stored as a zeebe:ioMapping output (source "= response").
38
48
  */
39
49
  resultVariable?: string;
40
50
  /** Event definition type (timer, error, message, signal, …) */
@@ -48,6 +58,18 @@ export interface CompactElement {
48
58
  elements: CompactElement[];
49
59
  flows: CompactFlow[];
50
60
  };
61
+ /**
62
+ * Runs the activity once per item of a list (`zeebe:loopCharacteristics`):
63
+ * `collection` is the FEEL expression of the list, `element` the variable each
64
+ * instance gets its item in. In parallel unless `sequential`.
65
+ */
66
+ multiInstance?: {
67
+ collection: string;
68
+ element?: string;
69
+ sequential?: boolean;
70
+ };
71
+ /** A timer event's ISO 8601 duration (`PT5M`): how long it waits once reached. */
72
+ timerDuration?: string;
51
73
  }
52
74
  /** A sequence flow in compact form. */
53
75
  export interface CompactFlow {
@@ -126,6 +148,12 @@ export declare function defaultFlows(elements: readonly CompactElement[], flows:
126
148
  */
127
149
  export declare function compactify(defs: BpmnDefinitions): CompactDiagram;
128
150
  export declare function makeEventDef(eventType: string): BpmnEventDefinition | undefined;
151
+ /**
152
+ * Job types run by the Camunda connector runtime (`io.camunda:http-json:1`,
153
+ * `io.camunda.agenticai:aiagent:1`, …). The runtime reads `resultVariable` from
154
+ * a task header, not from an output mapping.
155
+ */
156
+ export declare function isConnectorJobType(jobType: string): boolean;
129
157
  export declare function makeExtensions(el: CompactElement): XmlElement[];
130
158
  export declare function buildFlowElement(el: CompactElement, incoming: string[], outgoing: string[],
131
159
  /** Id of the outgoing flow marked `isDefault`, for a gateway that has one. */
@@ -134,6 +162,10 @@ defaultFlow?: string): BpmnFlowElement;
134
162
  * Restores a {@link CompactDiagram} (produced by {@link compactify} or an AI
135
163
  * model) back to a full {@link BpmnDefinitions} with auto-generated layout.
136
164
  *
165
+ * @throws {Error} When the diagram cannot be valid BPMN — a flow or boundary
166
+ * event naming an element that is not in its scope, a duplicate or missing id,
167
+ * or an unknown `eventType`. The message lists every problem at once.
168
+ *
137
169
  * @example
138
170
  * ```typescript
139
171
  * const compact = await askAI(prompt) // AI returns CompactDiagram JSON
@@ -1,5 +1,6 @@
1
1
  import { layoutProcess } from "../layout/index.js";
2
2
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
3
+ import { restConnectorTaskType } from "./rest-connector.js";
3
4
  // ── Default flows ────────────────────────────────────────────────────────────
4
5
  /**
5
6
  * The gateway types that carry a `bpmn:default`. No other element in this model
@@ -49,14 +50,21 @@ function compactifyElement(el) {
49
50
  const jobType = findAttr(ext, "zeebe:taskDefinition", "type");
50
51
  if (jobType)
51
52
  result.jobType = jobType;
52
- // Extract task headers (key→value map from zeebe:taskHeaders children)
53
+ // Extract task headers (key→value map from zeebe:taskHeaders children). A connector's
54
+ // result variable is a header; it is kept apart to round-trip as `resultVariable`.
55
+ const connector = jobType !== undefined && isConnectorJobType(jobType);
56
+ let headerResult;
53
57
  const taskHeadersEl = ext.find((e) => e.name === "zeebe:taskHeaders");
54
58
  if (taskHeadersEl && taskHeadersEl.children.length > 0) {
55
59
  const headers = {};
56
60
  for (const child of taskHeadersEl.children) {
57
61
  const key = child.attributes.key;
58
62
  const value = child.attributes.value;
59
- if (key !== undefined && value !== undefined)
63
+ if (key === undefined || value === undefined)
64
+ continue;
65
+ if (connector && key === "resultVariable")
66
+ headerResult = value;
67
+ else
60
68
  headers[key] = value;
61
69
  }
62
70
  if (Object.keys(headers).length > 0)
@@ -75,8 +83,12 @@ function compactifyElement(el) {
75
83
  if (rv)
76
84
  result.resultVariable = rv;
77
85
  }
86
+ else if (connector) {
87
+ if (headerResult !== undefined)
88
+ result.resultVariable = headerResult;
89
+ }
78
90
  else {
79
- // For service tasks: extract the primary output variable from ioMapping
91
+ // For job workers: extract the primary output variable from ioMapping
80
92
  const ioMappingEl = ext.find((e) => e.name === "zeebe:ioMapping");
81
93
  if (ioMappingEl) {
82
94
  const outputs = ioMappingEl.children.filter((c) => c.name === "zeebe:output");
@@ -87,8 +99,35 @@ function compactifyElement(el) {
87
99
  }
88
100
  }
89
101
  }
102
+ const inputs = {};
103
+ for (const input of ext.find((e) => e.name === "zeebe:ioMapping")?.children ?? []) {
104
+ const { source, target } = input.attributes;
105
+ if (input.name === "zeebe:input" && source !== undefined && target !== undefined) {
106
+ inputs[target] = source;
107
+ }
108
+ }
109
+ if (Object.keys(inputs).length > 0)
110
+ result.inputs = inputs;
111
+ const template = el.unknownAttributes["zeebe:modelerTemplate"];
112
+ if (template) {
113
+ const version = Number.parseInt(el.unknownAttributes["zeebe:modelerTemplateVersion"] ?? "", 10);
114
+ result.modelerTemplate = Number.isNaN(version) ? { id: template } : { id: template, version };
115
+ }
90
116
  if ("eventDefinitions" in el && el.eventDefinitions.length > 0) {
91
- result.eventType = el.eventDefinitions[0]?.type;
117
+ const def = el.eventDefinitions[0];
118
+ result.eventType = def?.type;
119
+ if (def?.type === "timer" && def.timeDuration)
120
+ result.timerDuration = def.timeDuration;
121
+ }
122
+ const loop = "loopCharacteristics" in el ? el.loopCharacteristics : undefined;
123
+ const zeebeLoop = loop?.extensionElements.find((x) => x.name === "zeebe:loopCharacteristics");
124
+ const collection = zeebeLoop?.attributes.inputCollection;
125
+ if (loop && collection) {
126
+ result.multiInstance = { collection };
127
+ if (zeebeLoop.attributes.inputElement)
128
+ result.multiInstance.element = zeebeLoop.attributes.inputElement;
129
+ if (loop.isSequential)
130
+ result.multiInstance.sequential = true;
92
131
  }
93
132
  if (el.type === "boundaryEvent") {
94
133
  result.attachedTo = el.attachedToRef;
@@ -165,6 +204,78 @@ export function compactify(defs) {
165
204
  };
166
205
  }
167
206
  // ── Expand ───────────────────────────────────────────────────────────────────
207
+ const EVENT_TYPES = new Set([
208
+ "timer",
209
+ "error",
210
+ "message",
211
+ "signal",
212
+ "escalation",
213
+ "cancel",
214
+ "terminate",
215
+ "conditional",
216
+ "link",
217
+ "compensate",
218
+ ]);
219
+ /**
220
+ * Every reason `compact` cannot become valid BPMN, as sentences naming the ids
221
+ * involved.
222
+ *
223
+ * `expand` used to build whatever it was given: an edge to an element that was
224
+ * never written came out as a `targetRef` pointing at nothing, a repeated id
225
+ * came out twice, a flow without an id came out without one, and an unknown
226
+ * `eventType` was dropped. Each is XML a modeler or an engine rejects later,
227
+ * with no trace back to here. A model writing the diagram makes all four
228
+ * mistakes, so the check is total and reports them together — one error that
229
+ * lists every problem is what a caller can hand back for a repair.
230
+ */
231
+ function compactProblems(compact) {
232
+ const problems = [];
233
+ const seen = new Set();
234
+ const claim = (id, what) => {
235
+ if (seen.has(id))
236
+ problems.push(`duplicate id "${id}" (${what})`);
237
+ seen.add(id);
238
+ };
239
+ const checkScope = (elements, flows, scope) => {
240
+ const ids = new Set();
241
+ for (const el of elements) {
242
+ if (typeof el.id !== "string" || el.id === "") {
243
+ problems.push(`a ${el.type} in ${scope} has no id`);
244
+ continue;
245
+ }
246
+ claim(el.id, el.type);
247
+ ids.add(el.id);
248
+ if (el.eventType !== undefined && !EVENT_TYPES.has(el.eventType)) {
249
+ problems.push(`element "${el.id}" has unknown eventType "${el.eventType}" (expected one of ${[...EVENT_TYPES].join(", ")})`);
250
+ }
251
+ }
252
+ for (const el of elements) {
253
+ if (el.type === "boundaryEvent" && (el.attachedTo === undefined || !ids.has(el.attachedTo))) {
254
+ problems.push(el.attachedTo === undefined
255
+ ? `boundary event "${el.id}" has no attachedTo`
256
+ : `boundary event "${el.id}" is attached to "${el.attachedTo}", which is not an element in ${scope}`);
257
+ }
258
+ if (el.children)
259
+ checkScope(el.children.elements, el.children.flows, `"${el.id}"`);
260
+ }
261
+ for (const flow of flows) {
262
+ const label = `flow ${flow.id ? `"${flow.id}"` : `from "${flow.from}" to "${flow.to}"`}`;
263
+ if (typeof flow.id !== "string" || flow.id === "")
264
+ problems.push(`${label} has no id`);
265
+ else
266
+ claim(flow.id, "sequence flow");
267
+ for (const end of [flow.from, flow.to]) {
268
+ if (!ids.has(end))
269
+ problems.push(`${label} references "${end}", which is not an element in ${scope}`);
270
+ }
271
+ }
272
+ };
273
+ for (const process of compact.processes) {
274
+ claim(process.id, "process");
275
+ checkScope(process.elements, process.flows, `process "${process.id}"`);
276
+ }
277
+ return problems;
278
+ }
168
279
  export function makeEventDef(eventType) {
169
280
  switch (eventType) {
170
281
  case "timer":
@@ -191,16 +302,59 @@ export function makeEventDef(eventType) {
191
302
  return undefined;
192
303
  }
193
304
  }
305
+ /**
306
+ * Job types run by the Camunda connector runtime (`io.camunda:http-json:1`,
307
+ * `io.camunda.agenticai:aiagent:1`, …). The runtime reads `resultVariable` from
308
+ * a task header, not from an output mapping.
309
+ */
310
+ export function isConnectorJobType(jobType) {
311
+ return /^io\.camunda[.:]/.test(jobType);
312
+ }
313
+ /** Inputs of the HTTP connector that older compact answers wrote as task headers. */
314
+ function isRestInputKey(key) {
315
+ return (key === "url" ||
316
+ key === "method" ||
317
+ key === "headers" ||
318
+ key === "queryParameters" ||
319
+ key === "body" ||
320
+ key === "connectionTimeoutInSeconds" ||
321
+ key === "readTimeoutInSeconds" ||
322
+ key.startsWith("authentication."));
323
+ }
324
+ /**
325
+ * Split an element's configuration into input mappings and task headers the
326
+ * way the engine reads them. The HTTP connector reads `url`, `method` and the
327
+ * rest from its inputs, so those keys move out of `taskHeaders`, where earlier
328
+ * prompts told models to put them and where the connector never looks.
329
+ */
330
+ function zeebeConfig(el) {
331
+ const rest = el.jobType === restConnectorTaskType();
332
+ const inputs = { ...el.inputs };
333
+ const headers = {};
334
+ for (const [key, value] of Object.entries(el.taskHeaders ?? {})) {
335
+ if (rest && isRestInputKey(key))
336
+ inputs[key] ??= value;
337
+ else
338
+ headers[key] = value;
339
+ }
340
+ if (rest && inputs.url !== undefined)
341
+ inputs["authentication.type"] ??= "noAuth";
342
+ if (el.jobType && isConnectorJobType(el.jobType) && el.resultVariable && !el.decisionId) {
343
+ headers.resultVariable ??= el.resultVariable;
344
+ }
345
+ return { inputs, headers };
346
+ }
194
347
  export function makeExtensions(el) {
195
348
  const ext = [];
349
+ const { inputs, headers } = zeebeConfig(el);
196
350
  if (el.jobType) {
197
351
  ext.push({ name: "zeebe:taskDefinition", attributes: { type: el.jobType }, children: [] });
198
352
  }
199
- if (el.taskHeaders && Object.keys(el.taskHeaders).length > 0) {
353
+ if (Object.keys(headers).length > 0) {
200
354
  ext.push({
201
355
  name: "zeebe:taskHeaders",
202
356
  attributes: {},
203
- children: Object.entries(el.taskHeaders).map(([key, value]) => ({
357
+ children: Object.entries(headers).map(([key, value]) => ({
204
358
  name: "zeebe:header",
205
359
  attributes: { key, value },
206
360
  children: [],
@@ -227,20 +381,22 @@ export function makeExtensions(el) {
227
381
  children: [],
228
382
  });
229
383
  }
230
- else if (el.resultVariable && el.jobType) {
231
- // Service task with a result variable: map the connector response to the variable
232
- ext.push({
233
- name: "zeebe:ioMapping",
234
- attributes: {},
235
- children: [
236
- {
237
- name: "zeebe:output",
238
- attributes: { source: "= response", target: el.resultVariable },
239
- children: [],
240
- },
241
- ],
384
+ const ioMapping = Object.entries(inputs).map(([target, source]) => ({
385
+ name: "zeebe:input",
386
+ attributes: { source, target },
387
+ children: [],
388
+ }));
389
+ if (el.resultVariable && el.jobType && !el.decisionId && !isConnectorJobType(el.jobType)) {
390
+ // A job worker's result: map its `response` variable to the result variable
391
+ ioMapping.push({
392
+ name: "zeebe:output",
393
+ attributes: { source: "= response", target: el.resultVariable },
394
+ children: [],
242
395
  });
243
396
  }
397
+ if (ioMapping.length > 0) {
398
+ ext.push({ name: "zeebe:ioMapping", attributes: {}, children: ioMapping });
399
+ }
244
400
  return ext;
245
401
  }
246
402
  function buildSubContent(children) {
@@ -280,6 +436,14 @@ function buildSubContent(children) {
280
436
  groups: [],
281
437
  };
282
438
  }
439
+ function templateAttributes(el) {
440
+ if (!el.modelerTemplate)
441
+ return {};
442
+ const { id, version } = el.modelerTemplate;
443
+ return version === undefined
444
+ ? { "zeebe:modelerTemplate": id }
445
+ : { "zeebe:modelerTemplate": id, "zeebe:modelerTemplateVersion": String(version) };
446
+ }
283
447
  export function buildFlowElement(el, incoming, outgoing,
284
448
  /** Id of the outgoing flow marked `isDefault`, for a gateway that has one. */
285
449
  defaultFlow) {
@@ -290,11 +454,27 @@ defaultFlow) {
290
454
  incoming,
291
455
  outgoing,
292
456
  extensionElements: makeExtensions(el),
293
- unknownAttributes: {},
457
+ unknownAttributes: templateAttributes(el),
294
458
  };
295
- const eventDef = el.eventType ? makeEventDef(el.eventType) : undefined;
459
+ const made = el.eventType ? makeEventDef(el.eventType) : undefined;
460
+ const eventDef = made?.type === "timer" && el.timerDuration ? { ...made, timeDuration: el.timerDuration } : made;
296
461
  const eventDefs = eventDef ? [eventDef] : [];
297
462
  const subContent = buildSubContent(el.children);
463
+ const loop = el.multiInstance && {
464
+ loopCharacteristics: {
465
+ isSequential: el.multiInstance.sequential || undefined,
466
+ extensionElements: [
467
+ {
468
+ name: "zeebe:loopCharacteristics",
469
+ attributes: {
470
+ inputCollection: el.multiInstance.collection,
471
+ ...(el.multiInstance.element ? { inputElement: el.multiInstance.element } : {}),
472
+ },
473
+ children: [],
474
+ },
475
+ ],
476
+ },
477
+ };
298
478
  switch (el.type) {
299
479
  case "startEvent":
300
480
  return { ...base, type: "startEvent", eventDefinitions: eventDefs };
@@ -313,25 +493,25 @@ defaultFlow) {
313
493
  eventDefinitions: eventDefs,
314
494
  };
315
495
  case "serviceTask":
316
- return { ...base, type: "serviceTask" };
496
+ return { ...base, type: "serviceTask", ...loop };
317
497
  case "scriptTask":
318
- return { ...base, type: "scriptTask" };
498
+ return { ...base, type: "scriptTask", ...loop };
319
499
  case "userTask":
320
- return { ...base, type: "userTask" };
500
+ return { ...base, type: "userTask", ...loop };
321
501
  case "businessRuleTask":
322
- return { ...base, type: "businessRuleTask" };
502
+ return { ...base, type: "businessRuleTask", ...loop };
323
503
  case "callActivity":
324
- return { ...base, type: "callActivity" };
504
+ return { ...base, type: "callActivity", ...loop };
325
505
  case "sendTask":
326
- return { ...base, type: "sendTask" };
506
+ return { ...base, type: "sendTask", ...loop };
327
507
  case "receiveTask":
328
- return { ...base, type: "receiveTask" };
508
+ return { ...base, type: "receiveTask", ...loop };
329
509
  case "manualTask":
330
- return { ...base, type: "manualTask" };
510
+ return { ...base, type: "manualTask", ...loop };
331
511
  case "task":
332
- return { ...base, type: "task" };
512
+ return { ...base, type: "task", ...loop };
333
513
  case "subProcess":
334
- return { ...base, type: "subProcess", ...subContent };
514
+ return { ...base, type: "subProcess", ...subContent, ...loop };
335
515
  case "adHocSubProcess":
336
516
  return { ...base, type: "adHocSubProcess", ...subContent };
337
517
  case "eventSubProcess":
@@ -445,6 +625,10 @@ function expandProcess(compact) {
445
625
  * Restores a {@link CompactDiagram} (produced by {@link compactify} or an AI
446
626
  * model) back to a full {@link BpmnDefinitions} with auto-generated layout.
447
627
  *
628
+ * @throws {Error} When the diagram cannot be valid BPMN — a flow or boundary
629
+ * event naming an element that is not in its scope, a duplicate or missing id,
630
+ * or an unknown `eventType`. The message lists every problem at once.
631
+ *
448
632
  * @example
449
633
  * ```typescript
450
634
  * const compact = await askAI(prompt) // AI returns CompactDiagram JSON
@@ -455,6 +639,10 @@ function expandProcess(compact) {
455
639
  */
456
640
  export function expand(compact) {
457
641
  assertCompactDiagram(compact, "expand");
642
+ const problems = compactProblems(compact);
643
+ if (problems.length > 0) {
644
+ throw new Error(`expand: invalid CompactDiagram — ${problems.join("; ")}`);
645
+ }
458
646
  const processes = [];
459
647
  const diagrams = [];
460
648
  for (const cp of compact.processes) {
@@ -0,0 +1,46 @@
1
+ /**
2
+ * `with` lines: how a model configures a connector in the line format.
3
+ *
4
+ * ```
5
+ * with post: slack chat.postMessage | data.channel=#ops | data.text== "Order " + orderId
6
+ * with fetch: http GET https://api.example.com/orders | result=order
7
+ * ```
8
+ *
9
+ * A line names a node already written by its id, the connector by its alias,
10
+ * the operation when the connector has several, and the inputs as
11
+ * `key=value` (`key==expr` for FEEL). Path lines are unchanged, so a `with`
12
+ * line can follow anywhere and a diagram streams as before.
13
+ *
14
+ * This module only reads the line. Which connector an alias names, which keys
15
+ * it has and what it writes is `@bpmnkit/core/connectors`' part, so the parser
16
+ * stays free of the catalog's data.
17
+ *
18
+ * @packageDocumentation
19
+ */
20
+ import type { ProcessTextProblem } from "./process-text.js";
21
+ /** One `with` line, as written. Nothing is resolved against the catalog yet. */
22
+ export interface ConnectorLine {
23
+ /** The node's id as written. */
24
+ id: string;
25
+ /** The connector alias, e.g. `slack`. */
26
+ alias: string;
27
+ /**
28
+ * The words after the alias, before the first `|`: the operation, and for
29
+ * some connectors values written without a key (`http GET <url>`). A word
30
+ * starting with `=` or a quote runs to the end of the head.
31
+ */
32
+ args: string[];
33
+ /** `key=value` parts, in the order written; a later key wins. */
34
+ values: Record<string, string>;
35
+ line: number;
36
+ }
37
+ /** `with <id>:` at the start of a line. */
38
+ export declare const CONNECTOR_LINE: RegExp;
39
+ /**
40
+ * Reads a `with` line, or answers `undefined` when the line is not one.
41
+ *
42
+ * Never throws: a line that starts like one but cannot be read becomes a
43
+ * problem, and the parts it could read are kept.
44
+ */
45
+ export declare function parseConnectorLine(text: string, line: number, problems: ProcessTextProblem[]): ConnectorLine | undefined;
46
+ //# sourceMappingURL=connector-line.d.ts.map