@bpmnkit/core 1.2.0 → 1.4.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 (51) hide show
  1. package/README.md +26 -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 +39 -5
  5. package/dist/bpmn/compact.js +151 -29
  6. package/dist/bpmn/connector-line.d.ts +46 -0
  7. package/dist/bpmn/connector-line.js +135 -0
  8. package/dist/bpmn/full-operations.js +8 -1
  9. package/dist/bpmn/optimize/patterns.js +1 -3
  10. package/dist/bpmn/process-delta.d.ts +7 -0
  11. package/dist/bpmn/process-delta.js +34 -2
  12. package/dist/bpmn/process-text-writer.d.ts +12 -2
  13. package/dist/bpmn/process-text-writer.js +16 -1
  14. package/dist/bpmn/process-text.d.ts +36 -1
  15. package/dist/bpmn/process-text.js +412 -17
  16. package/dist/bpmn/rest-connector.d.ts +6 -0
  17. package/dist/bpmn/rest-connector.js +6 -0
  18. package/dist/bpmn/secrets.d.ts +15 -0
  19. package/dist/bpmn/secrets.js +59 -0
  20. package/dist/bpmn/utils.js +4 -0
  21. package/dist/bpmn/zeebe-extensions.d.ts +10 -0
  22. package/dist/bpmn/zeebe-extensions.js +7 -0
  23. package/dist/connectors/aliases.d.ts +21 -0
  24. package/dist/connectors/aliases.js +272 -0
  25. package/dist/connectors/api.d.ts +118 -0
  26. package/dist/connectors/api.js +280 -0
  27. package/dist/connectors/apply-element.d.ts +59 -0
  28. package/dist/connectors/apply-element.js +385 -0
  29. package/dist/connectors/apply.d.ts +136 -0
  30. package/dist/connectors/apply.js +352 -0
  31. package/dist/connectors/cards.d.ts +96 -0
  32. package/dist/connectors/cards.js +306 -0
  33. package/dist/connectors/catalog.d.ts +79 -0
  34. package/dist/connectors/catalog.js +209 -0
  35. package/dist/connectors/index.d.ts +33 -0
  36. package/dist/connectors/index.js +24 -0
  37. package/dist/connectors/lines.d.ts +108 -0
  38. package/dist/connectors/lines.js +568 -0
  39. package/dist/connectors/select.d.ts +85 -0
  40. package/dist/connectors/select.js +419 -0
  41. package/dist/connectors/template-types.d.ts +188 -0
  42. package/dist/connectors/template-types.js +6 -0
  43. package/dist/connectors/templates/bpmnkit.d.ts +12 -0
  44. package/dist/connectors/templates/bpmnkit.js +186 -0
  45. package/dist/connectors/templates/generated.d.ts +3 -0
  46. package/dist/connectors/templates/generated.js +95885 -0
  47. package/dist/connectors/validate.d.ts +66 -0
  48. package/dist/connectors/validate.js +271 -0
  49. package/dist/index.d.ts +7 -3
  50. package/dist/index.js +2 -0
  51. package/package.json +5 -1
@@ -0,0 +1,352 @@
1
+ import { parseExpression } from "@bpmnkit/feel";
2
+ import { getTemplate, propertyKey } from "./catalog.js";
3
+ export function evalCondition(cond, values) {
4
+ if ("allMatch" in cond) {
5
+ return cond.allMatch.every((c) => evalCondition(c, values));
6
+ }
7
+ // `String()` because a Boolean property's condition compares against `true`/`false`,
8
+ // while every resolved value is the string the XML will carry.
9
+ if ("equals" in cond)
10
+ return values[cond.property] === String(cond.equals);
11
+ if ("oneOf" in cond)
12
+ return cond.oneOf.includes(values[cond.property] ?? "");
13
+ if ("isActive" in cond)
14
+ return Boolean(values[cond.property]) === cond.isActive;
15
+ if ("isEmpty" in cond)
16
+ return !values[cond.property] === cond.isEmpty;
17
+ return true;
18
+ }
19
+ function defaultValueOf(prop) {
20
+ if (prop.value === undefined)
21
+ return undefined;
22
+ return String(prop.value);
23
+ }
24
+ /**
25
+ * The effective value of every active property: user override, else template
26
+ * default.
27
+ *
28
+ * Only an active property has a value, as in the Modeler. A dropdown hidden by
29
+ * its own condition does not keep its default, so it cannot switch on the
30
+ * properties that depend on it: GitHub's `labelOperationType` defaults to a
31
+ * label operation, but while `operationGroup` is "issue" it is hidden, and the
32
+ * label inputs stay off. Conditions can chain, so this repeats until nothing
33
+ * changes.
34
+ */
35
+ export function resolveValues(template, values) {
36
+ let resolved = {};
37
+ // Each pass can only switch on properties whose conditions read the previous pass's
38
+ // values, so the chain is never longer than the property list
39
+ for (let pass = 0; pass <= template.properties.length; pass++) {
40
+ const next = {};
41
+ for (const prop of template.properties) {
42
+ const key = propertyKey(prop);
43
+ if (!key || key in next)
44
+ continue;
45
+ if (prop.condition && !evalCondition(prop.condition, resolved))
46
+ continue;
47
+ const value = values[key] ?? defaultValueOf(prop);
48
+ if (value !== undefined)
49
+ next[key] = value;
50
+ }
51
+ if (sameValues(next, resolved))
52
+ return next;
53
+ resolved = next;
54
+ }
55
+ return resolved;
56
+ }
57
+ function sameValues(a, b) {
58
+ const keys = Object.keys(a);
59
+ return keys.length === Object.keys(b).length && keys.every((k) => b[k] === a[k]);
60
+ }
61
+ /**
62
+ * The binding types `applyBinding` below writes.
63
+ *
64
+ * Declared beside the switch so the two are edited together: anything the
65
+ * switch gains belongs here, and `validateElementTemplate` warns about every
66
+ * binding that is valid but absent from this set — otherwise a template using
67
+ * one would apply silently and do nothing.
68
+ */
69
+ export const APPLIED_BINDING_TYPES = new Set([
70
+ "zeebe:input",
71
+ "zeebe:output",
72
+ "zeebe:taskHeader",
73
+ "zeebe:taskDefinition",
74
+ "zeebe:taskDefinition:type",
75
+ "zeebe:property",
76
+ "zeebe:adHoc",
77
+ "zeebe:agentDefinition",
78
+ "property",
79
+ "bpmn:Message#property",
80
+ "bpmn:Message#zeebe:subscription#property",
81
+ "zeebe:linkedResource",
82
+ ]);
83
+ function applyBinding(binding, value, accum) {
84
+ switch (binding.type) {
85
+ case "zeebe:input":
86
+ accum.inputs.push({ source: value, target: binding.name });
87
+ return;
88
+ case "zeebe:output":
89
+ // `binding.source` is the template's fixed FEEL read expression (e.g. "=response");
90
+ // `value` is the user-chosen process-variable name to write it to.
91
+ accum.outputs.push({ source: binding.source, target: value });
92
+ return;
93
+ case "zeebe:taskHeader":
94
+ accum.taskHeaders[binding.key] = value;
95
+ return;
96
+ case "zeebe:taskDefinition":
97
+ if (binding.property === "type")
98
+ accum.taskType = value;
99
+ else
100
+ accum.retries = value;
101
+ return;
102
+ case "zeebe:taskDefinition:type":
103
+ accum.taskType = value;
104
+ return;
105
+ case "zeebe:property":
106
+ accum.zeebeProperties.push({ name: binding.name, value });
107
+ return;
108
+ case "zeebe:adHoc":
109
+ accum.adHoc[binding.property] = value;
110
+ return;
111
+ case "zeebe:agentDefinition":
112
+ accum.agentDefinition[binding.property] = value;
113
+ return;
114
+ case "property":
115
+ // "name" binds to the element's display name — handled by the caller, not here.
116
+ return;
117
+ case "bpmn:Message#property":
118
+ accum.message[binding.name] = value;
119
+ return;
120
+ case "bpmn:Message#zeebe:subscription#property":
121
+ accum.subscription[binding.name] = value;
122
+ return;
123
+ case "zeebe:linkedResource": {
124
+ const link = accum.linkedResources.get(binding.linkName) ?? {};
125
+ link[binding.property] = value;
126
+ accum.linkedResources.set(binding.linkName, link);
127
+ return;
128
+ }
129
+ default:
130
+ return;
131
+ }
132
+ }
133
+ /** A binding the template resolved but the builder options have no field for. */
134
+ function notExpressible(what) {
135
+ return {
136
+ message: `${what} cannot be carried by builder options — use applyTemplateToElement() to write the template onto a model instead.`,
137
+ };
138
+ }
139
+ function directionOf(template) {
140
+ return template.elementType?.value ?? template.appliesTo[0] ?? "";
141
+ }
142
+ /**
143
+ * Resolves a template and a set of values into the bindings its active
144
+ * properties write — the half of applying a template that does not depend on
145
+ * where the result goes, shared by {@link applyElementTemplate} and
146
+ * `applyTemplateToElement`.
147
+ *
148
+ * @param generate - Supplies a value for an active property that declares a
149
+ * `generatedValue` and was given none. Returning `undefined` leaves the
150
+ * binding unwritten; the callback reports that however suits its caller.
151
+ */
152
+ export function resolveBindings(template, values, generate) {
153
+ const resolved = resolveValues(template, values);
154
+ const problems = [];
155
+ const knownKeys = new Set(template.properties.map(propertyKey).filter(Boolean));
156
+ for (const key of Object.keys(values)) {
157
+ if (key !== "name" && !knownKeys.has(key)) {
158
+ problems.push({
159
+ key,
160
+ kind: "unknown-key",
161
+ message: `Unknown value key "${key}" for template "${template.id}"`,
162
+ });
163
+ }
164
+ }
165
+ const accum = {
166
+ inputs: [],
167
+ outputs: [],
168
+ taskHeaders: {},
169
+ zeebeProperties: [],
170
+ adHoc: {},
171
+ agentDefinition: {},
172
+ message: {},
173
+ subscription: {},
174
+ linkedResources: new Map(),
175
+ };
176
+ for (const prop of template.properties) {
177
+ const key = propertyKey(prop);
178
+ if (prop.condition && !evalCondition(prop.condition, resolved))
179
+ continue;
180
+ let value = resolved[key];
181
+ if ((value === undefined || value === "") && prop.generatedValue) {
182
+ value = generate(key, prop);
183
+ }
184
+ if (value === undefined || value === "") {
185
+ if (prop.type !== "Hidden" && prop.constraints?.notEmpty) {
186
+ problems.push({
187
+ key,
188
+ kind: "missing-required",
189
+ message: `Missing required value for "${prop.label ?? key}" (${key})`,
190
+ });
191
+ }
192
+ continue;
193
+ }
194
+ if ((prop.feel === "required" || prop.feel === "optional") && value.startsWith("=")) {
195
+ const { errors } = parseExpression(value.slice(1));
196
+ for (const err of errors) {
197
+ problems.push({
198
+ key,
199
+ kind: "invalid-feel",
200
+ message: `Invalid FEEL expression for "${key}": ${err.message}`,
201
+ });
202
+ }
203
+ }
204
+ applyBinding(prop.binding, value, accum);
205
+ }
206
+ return { accum, problems };
207
+ }
208
+ /**
209
+ * Applies a Camunda 8 out-of-the-box connector element template deterministically.
210
+ *
211
+ * Unlike a naive apply that only handles `zeebe:input`, this resolves every
212
+ * binding kind (`zeebe:input`, `zeebe:output`, `zeebe:taskHeader`,
213
+ * `zeebe:taskDefinition(:type)`, `zeebe:property`, `zeebe:adHoc`,
214
+ * `zeebe:agentDefinition`), respects
215
+ * dropdown-gated `condition`s, validates required fields, and parse-validates
216
+ * any value that looks like a FEEL expression (leading "=").
217
+ *
218
+ * The result is builder options, which have no field for some bindings: a
219
+ * message start event's correlation key and `zeebe:linkedResource` come back
220
+ * as problems rather than being dropped, and a message name the template
221
+ * generates per element (`generatedValue`) must be passed in `values`. Inbound
222
+ * intermediate and boundary templates' `zeebe:property` bindings are returned
223
+ * but not written by `@bpmnkit/core`'s builder. {@link applyTemplateToElement}
224
+ * writes every binding onto an existing element of a parsed model instead.
225
+ *
226
+ * `values` keys match `ConnectorSummary.requiredInputs[].key` /
227
+ * `optionalInputs[].key` from `listConnectors()`/`searchConnectors()`.
228
+ *
229
+ * Operates on any {@link ElementTemplate} object — not just the bundled OOTB
230
+ * catalog — so custom/generated templates (e.g. from `@bpmnkit/connector-gen`)
231
+ * work the same way. Use {@link applyConnectorTemplate} to apply by bundled
232
+ * template id instead.
233
+ */
234
+ export function applyElementTemplate(template, values = {}) {
235
+ const ungenerated = [];
236
+ const { accum, problems } = resolveBindings(template, values, (key) => {
237
+ ungenerated.push(key);
238
+ return undefined;
239
+ });
240
+ // Builder options name no element, so there is nothing to derive a per-element value from.
241
+ for (const key of ungenerated) {
242
+ problems.push({
243
+ key,
244
+ message: `"${key}" is generated per element (generatedValue) and no value was given. ` +
245
+ `Pass values["${key}"], or apply with applyTemplateToElement(), which derives one from the element id.`,
246
+ });
247
+ }
248
+ if (accum.linkedResources.size > 0) {
249
+ problems.push(notExpressible("zeebe:linkedResource bindings"));
250
+ }
251
+ const modelerTemplate = template.id;
252
+ const modelerTemplateVersion = template.version !== undefined ? String(template.version) : undefined;
253
+ const modelerTemplateIcon = template.icon?.contents;
254
+ const name = values.name ?? template.name;
255
+ const direction = directionOf(template);
256
+ const { agentType } = accum.agentDefinition;
257
+ const agentDefinition = agentType === undefined ? undefined : { agentType };
258
+ if (direction === "bpmn:AdHocSubProcess") {
259
+ return {
260
+ adHocSubProcess: {
261
+ name,
262
+ taskDefinition: accum.taskType
263
+ ? { type: accum.taskType, retries: accum.retries }
264
+ : undefined,
265
+ ioMapping: accum.inputs.length || accum.outputs.length
266
+ ? { inputs: accum.inputs, outputs: accum.outputs }
267
+ : undefined,
268
+ taskHeaders: Object.keys(accum.taskHeaders).length > 0 ? accum.taskHeaders : undefined,
269
+ zeebeProperties: accum.zeebeProperties.length > 0 ? accum.zeebeProperties : undefined,
270
+ agentDefinition,
271
+ outputCollection: accum.adHoc.outputCollection,
272
+ outputElement: accum.adHoc.outputElement,
273
+ activeElementsCollection: accum.adHoc.activeElementsCollection,
274
+ modelerTemplate,
275
+ modelerTemplateVersion,
276
+ modelerTemplateIcon,
277
+ },
278
+ problems,
279
+ };
280
+ }
281
+ if (direction === "bpmn:StartEvent" ||
282
+ direction === "bpmn:BoundaryEvent" ||
283
+ direction === "bpmn:IntermediateCatchEvent" ||
284
+ direction === "bpmn:ReceiveTask") {
285
+ if (accum.inputs.length > 0 ||
286
+ accum.outputs.length > 0 ||
287
+ Object.keys(accum.taskHeaders).length > 0) {
288
+ problems.push({
289
+ message: "Template uses zeebe:input/output/taskHeader bindings on an event-attached element; " +
290
+ "applyConnectorTemplate() only maps zeebe:property for start/boundary/intermediate events. " +
291
+ "Apply the remaining bindings manually.",
292
+ });
293
+ }
294
+ const partial = {
295
+ name,
296
+ zeebeProperties: accum.zeebeProperties.length > 0 ? accum.zeebeProperties : undefined,
297
+ modelerTemplate,
298
+ modelerTemplateVersion,
299
+ modelerTemplateIcon,
300
+ messageName: accum.message.name,
301
+ };
302
+ const correlationKey = accum.subscription.correlationKey;
303
+ if (direction === "bpmn:StartEvent") {
304
+ if (correlationKey !== undefined) {
305
+ problems.push(notExpressible("A message start event's correlation key"));
306
+ }
307
+ return { startEvent: partial, problems };
308
+ }
309
+ if (direction === "bpmn:BoundaryEvent") {
310
+ return { boundaryEvent: { ...partial, correlationKey }, problems };
311
+ }
312
+ return { intermediateEvent: { ...partial, correlationKey }, problems };
313
+ }
314
+ // Default: outbound service task (bpmn:ServiceTask, bpmn:SendTask, bpmn:EndEvent, bpmn:Task, ...)
315
+ if (!accum.taskType) {
316
+ problems.push({
317
+ kind: "no-task-type",
318
+ message: `Template "${template.id}" produced no zeebe:taskDefinition type`,
319
+ });
320
+ }
321
+ return {
322
+ serviceTask: {
323
+ name,
324
+ taskType: accum.taskType ?? "",
325
+ retries: accum.retries,
326
+ ioMapping: accum.inputs.length || accum.outputs.length
327
+ ? { inputs: accum.inputs, outputs: accum.outputs }
328
+ : undefined,
329
+ taskHeaders: Object.keys(accum.taskHeaders).length > 0 ? accum.taskHeaders : undefined,
330
+ zeebeProperties: accum.zeebeProperties.length > 0 ? accum.zeebeProperties : undefined,
331
+ agentDefinition,
332
+ modelerTemplate,
333
+ modelerTemplateVersion,
334
+ modelerTemplateIcon,
335
+ },
336
+ problems,
337
+ };
338
+ }
339
+ /**
340
+ * Applies a bundled Camunda 8 out-of-the-box connector element template by
341
+ * id — see {@link applyElementTemplate} for the full binding-resolution
342
+ * behavior. Returns a single `problems` entry if `templateId` isn't in the
343
+ * bundled catalog (use `applyElementTemplate` directly for custom templates).
344
+ */
345
+ export function applyConnectorTemplate(templateId, values = {}) {
346
+ const template = getTemplate(templateId);
347
+ if (!template) {
348
+ return { problems: [{ message: `Unknown connector template "${templateId}"` }] };
349
+ }
350
+ return applyElementTemplate(template, values);
351
+ }
352
+ //# sourceMappingURL=apply.js.map
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Connector cards: the smallest text that lets a model configure one connector
3
+ * operation.
4
+ *
5
+ * A template mixes many operations in one property list, gated by dropdowns:
6
+ * GitHub's `owner` is required by five operations and listed five times. A
7
+ * model handed the template, or a summary of it, cannot tell which inputs
8
+ * belong to the operation it wants. A card is one operation with only the
9
+ * inputs active for it. Modes of an operation (authentication type, AI
10
+ * provider) stay on the card as choices, each with the inputs it adds.
11
+ *
12
+ * Cards are worked out from the templates and {@link CONNECTOR_ALIASES}, never
13
+ * written by hand; tests apply every card's required inputs and expect no
14
+ * missing-required problem.
15
+ */
16
+ import { type ConnectorDirection } from "./catalog.js";
17
+ /** One input a card asks for. */
18
+ export interface CardInput {
19
+ /** The key to pass in `applyConnectorTemplate`'s `values`. */
20
+ key: string;
21
+ label: string;
22
+ /** A credential: write `{{secrets.NAME}}`, never a value. */
23
+ secret?: true;
24
+ /** The value must be a FEEL expression (starting with `=`). */
25
+ feel?: true;
26
+ /** The allowed values of a dropdown. */
27
+ choices?: string[];
28
+ /** The template's default, when it has one. */
29
+ default?: string;
30
+ /**
31
+ * Plumbing most flows leave alone — retries, timeouts, error expressions,
32
+ * TLS, saved credentials, inbound deduplication. {@link formatConnectorCard}
33
+ * leaves these out unless asked.
34
+ */
35
+ advanced?: true;
36
+ }
37
+ /** A dropdown that changes which inputs the operation needs, such as an authentication type. */
38
+ export interface CardMode {
39
+ key: string;
40
+ label: string;
41
+ /** The flow must choose: the template requires a value and has no default. */
42
+ required?: true;
43
+ default?: string;
44
+ /** Each choice, with the required inputs it adds to the card's. */
45
+ choices: Array<{
46
+ value: string;
47
+ requires: string[];
48
+ }>;
49
+ }
50
+ /** One connector operation, with only the inputs it uses. */
51
+ export interface ConnectorCard {
52
+ templateId: string;
53
+ /** The short name a model writes, e.g. `slack`. */
54
+ alias: string;
55
+ /** The operation within the template, e.g. `chat.postMessage`; absent when it has one. */
56
+ operation?: string;
57
+ /** The template name, and the operation's label when it has several. */
58
+ title: string;
59
+ description?: string;
60
+ taskType?: string;
61
+ direction: ConnectorDirection;
62
+ /** The values that select this operation; pass them with the inputs. */
63
+ values: Record<string, string>;
64
+ required: CardInput[];
65
+ optional: CardInput[];
66
+ modes: CardMode[];
67
+ }
68
+ /** The alias of a template: its entry in {@link CONNECTOR_ALIASES}, else its id. */
69
+ export declare function connectorAlias(templateId: string): string;
70
+ /** The template an alias names, among bundled and registered templates. */
71
+ export declare function templateIdForAlias(alias: string): string | undefined;
72
+ /** The cards of one template, registered or bundled; empty for an unknown id. */
73
+ export declare function connectorCards(templateId: string): ConnectorCard[];
74
+ /** Every card of every bundled and registered template. */
75
+ export declare function listConnectorCards(): ConnectorCard[];
76
+ /** How well a card matches search terms: alias, then template name, then operation, then anywhere. */
77
+ export declare function cardScore(card: ConnectorCard, terms: readonly string[]): number;
78
+ /** The words of a request that can say which connector it means. */
79
+ export declare function searchTerms(text: string): string[];
80
+ /**
81
+ * Cards that match a query, best first: an alias named outright scores highest,
82
+ * then words of the template name, then of the operation, then anywhere.
83
+ * Outbound connectors win ties.
84
+ */
85
+ export declare function findConnectorCards(query: string, options?: {
86
+ limit?: number;
87
+ }): ConnectorCard[];
88
+ /**
89
+ * A card as one line for a prompt: `alias operation — title | required* … |
90
+ * optional: … | mode=default: choice(adds*) …`. A `*` marks a required input.
91
+ * Advanced inputs are left out unless `options.advanced` is set.
92
+ */
93
+ export declare function formatConnectorCard(card: ConnectorCard, options?: {
94
+ advanced?: boolean;
95
+ }): string;
96
+ //# sourceMappingURL=cards.d.ts.map