@nanobpm/bojtos-kit 0.1.0 → 0.2.0

package/dist/session.d.ts

@@ -1,5 +1,5 @@
 import { type InitInput } from "@nanobpm/engine-wasm";
-import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+import type { ActivatedJob, ActivateInstruction, Snapshot, WasmEvent } from "./types.js";
 /**
  * The source of the engine wasm binary. Under a bundler that understands
  * `new URL(..., import.meta.url)` (e.g. Vite) the default loader needs no
@@ -48,6 +48,63 @@ export interface BojtosSession {
     completeJob(jobKey: string, variablesJson: string): Snapshot;
     /** Fail a waiting job; with no retries left this raises an incident. */
     failJob(jobKey: string, retries: number, message: string): Snapshot;
+    /**
+     * Throw a BPMN business error from a waiting job: interrupts the activity via a
+     * matching error boundary/event-subprocess catch, or raises an incident if
+     * uncaught. The job is consumed either way.
+     */
+    throwError(jobKey: string, errorCode: string, errorMessage: string): Snapshot;
+    /**
+     * Set a job's remaining retries. Used to recover a job parked on a no-retries
+     * incident before resolving that incident; does not itself unblock the job.
+     */
+    updateRetries(jobKey: string, retries: number): Snapshot;
+    /**
+     * Resolve an open incident by key, retrying the work that failed (returns a
+     * parked job to the activatable pool / re-evaluates a gateway / re-creates a
+     * service-task job).
+     */
+    resolveIncident(incidentKey: string): Snapshot;
+    /**
+     * Merge variables into a scope (a process-instance or element-instance key).
+     * When `local` is true they are written strictly into the target scope,
+     * otherwise they propagate up to the nearest ancestor scope defining each name.
+     */
+    setVariables(scopeKey: string, variablesJson: string, local: boolean): Snapshot;
+    /**
+     * Broadcast a signal by name to every open subscription that matches, across
+     * all instances, merging `variablesJson` into each correlated instance.
+     */
+    broadcastSignal(signalName: string, variablesJson: string): Snapshot;
+    /** Cancel (terminate) a running process instance: every token is discarded. */
+    cancelInstance(instanceKey: string): Snapshot;
+    /**
+     * Modify a running process instance (Zeebe "modify process instance"): move
+     * tokens by terminating existing element instances and/or activating new
+     * ones. Each activate instruction places a token at `elementId` (in the
+     * process root scope), first merging its optional `variables` into the root
+     * scope; `terminateElementInstanceKeys` are the keys of active element
+     * instances (from `instances[].activeElements[].key`) to terminate. If the
+     * terminations drain the last token and nothing is activated, the instance is
+     * terminated.
+     */
+    modify(instanceKey: string, activateInstructions: ActivateInstruction[], terminateElementInstanceKeys: string[]): Snapshot;
+    /** Complete a waiting user task, merging `variablesJson` into the instance. */
+    completeUserTask(userTaskKey: string, variablesJson: string): Snapshot;
+    /**
+     * Assign a user task to `assignee`. With `allowOverride` false the command is
+     * rejected if the task already has an assignee (unassign it first).
+     */
+    assignUserTask(userTaskKey: string, assignee: string, allowOverride: boolean): Snapshot;
+    /** Clear a user task's assignee. */
+    unassignUserTask(userTaskKey: string): Snapshot;
+    /**
+     * Update a user task's attributes from a JSON changeset. Recognised keys (all
+     * optional): `candidateGroups` / `candidateUsers` (string arrays),
+     * `dueDate` / `followUpDate` (ISO-8601 string, or `null`/`""` to clear),
+     * `priority` (0..=100). Only present keys are changed.
+     */
+    updateUserTask(userTaskKey: string, changesetJson: string): Snapshot;
     /**
      * Correlate a message to any instance waiting on it: publishes `messageName`
      * with `correlationKey` (the value the waiting subscription's `correlationKey`

package/dist/session.js

@@ -48,6 +48,39 @@ class WasmBojtosSession {
     failJob(jobKey, retries, message) {
         return parseSnapshot(this.engine.failJob(jobKey, retries, message));
     }
+    throwError(jobKey, errorCode, errorMessage) {
+        return parseSnapshot(this.engine.throwError(jobKey, errorCode, errorMessage));
+    }
+    updateRetries(jobKey, retries) {
+        return parseSnapshot(this.engine.updateRetries(jobKey, retries));
+    }
+    resolveIncident(incidentKey) {
+        return parseSnapshot(this.engine.resolveIncident(incidentKey));
+    }
+    setVariables(scopeKey, variablesJson, local) {
+        return parseSnapshot(this.engine.setVariables(scopeKey, variablesJson || "{}", local));
+    }
+    broadcastSignal(signalName, variablesJson) {
+        return parseSnapshot(this.engine.broadcastSignal(signalName, variablesJson || "{}"));
+    }
+    cancelInstance(instanceKey) {
+        return parseSnapshot(this.engine.cancelInstance(instanceKey));
+    }
+    modify(instanceKey, activateInstructions, terminateElementInstanceKeys) {
+        return parseSnapshot(this.engine.modify(instanceKey, JSON.stringify(activateInstructions ?? []), JSON.stringify(terminateElementInstanceKeys ?? [])));
+    }
+    completeUserTask(userTaskKey, variablesJson) {
+        return parseSnapshot(this.engine.completeUserTask(userTaskKey, variablesJson || "{}"));
+    }
+    assignUserTask(userTaskKey, assignee, allowOverride) {
+        return parseSnapshot(this.engine.assignUserTask(userTaskKey, assignee, allowOverride));
+    }
+    unassignUserTask(userTaskKey) {
+        return parseSnapshot(this.engine.unassignUserTask(userTaskKey));
+    }
+    updateUserTask(userTaskKey, changesetJson) {
+        return parseSnapshot(this.engine.updateUserTask(userTaskKey, changesetJson || "{}"));
+    }
     correlateMessage(messageName, correlationKey, variablesJson) {
         return parseSnapshot(this.engine.correlateMessage(messageName, correlationKey, variablesJson || "{}"));
     }

package/dist/types.d.ts

@@ -51,10 +51,80 @@ export interface TimerDto {
     dueAt: number;
     dueInMs: number;
 }
+/** A user task parked on a `userTask` element, awaiting a human. */
+export interface UserTaskDto {
+    key: string;
+    instanceKey: string;
+    elementInstanceKey: string;
+    elementId: string;
+    /** `Created` (waiting), `Completed`, or `Canceled`. */
+    state: string;
+    assignee?: string;
+    candidateGroups: string[];
+    candidateUsers: string[];
+    dueDate?: string;
+    followUpDate?: string;
+    priority: number;
+}
+/** An open message subscription (a waiting message catch/boundary event). */
+export interface MessageSubscriptionDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    messageName: string;
+    correlationKey: string;
+    /** What the subscription guards (intermediate/boundary, interrupting or not). */
+    kind: string;
+}
+/** An open signal subscription (a waiting signal catch/boundary event). */
+export interface SignalSubscriptionDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    signalName: string;
+    kind: string;
+}
+/**
+ * Per-element token statistics for diagram overlays: `active` live tokens,
+ * cumulative `completed` element instances, and current `incidents`.
+ */
+export interface ElementStatDto {
+    elementId: string;
+    active: number;
+    completed: number;
+    incidents: number;
+}
+/** A traversed connection, as source/target element ids. */
+export interface SequenceFlowDto {
+    from: string;
+    to: string;
+}
+/** An evaluated decision instance (from a `businessRuleTask` / DMN). */
+export interface DecisionInstanceDto {
+    instanceKey: string;
+    elementId: string;
+    decisionKey: string;
+    decisionId: string;
+    output: unknown;
+    evaluatedAt: number;
+}
+/**
+ * One activation instruction for {@link BojtosSession.modify}: place a new token
+ * at `elementId`, first merging `variables` into the instance's root scope.
+ * Mirrors Zeebe's process-instance-modification activate instruction (the token
+ * is activated in the process root scope).
+ */
+export interface ActivateInstruction {
+    elementId: string;
+    variables?: Record<string, unknown>;
+}
 /**
  * The full simulation state returned by every engine command. `activeElementIds`
  * / `incidentElementIds` drive the token/incident highlight (the visual
  * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ * `userTasks`, `messageSubscriptions`, `signalSubscriptions`, `elementStats`,
+ * `takenSequenceFlows` and `decisionInstances` back a Web-Modeler-Play-style UI
+ * (task panels, correlation/broadcast, overlays, DMN results).
  */
 export interface Snapshot {
     now: number;
@@ -67,6 +137,12 @@ export interface Snapshot {
     jobs: JobDto[];
     incidents: IncidentDto[];
     timers: TimerDto[];
+    userTasks: UserTaskDto[];
+    messageSubscriptions: MessageSubscriptionDto[];
+    signalSubscriptions: SignalSubscriptionDto[];
+    elementStats: ElementStatDto[];
+    takenSequenceFlows: SequenceFlowDto[];
+    decisionInstances: DecisionInstanceDto[];
     activeElementIds: string[];
     incidentElementIds: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic core of the Bojtos in-browser BPMN demo framework (ADR 0043): a single scenario runner over the @nanobpm/engine-wasm engine (deploy, start instances, complete/fail jobs, advance the clock, read snapshots and the event log), plus the engine's snapshot/event contract types. Consumed by @nanobpm/bojtos-react and the console test-run panel.",
   "type": "module",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nanobpm/engine-wasm": "^0.1.0"
+    "@nanobpm/engine-wasm": "^0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3"

package/src/session.ts

@@ -1,5 +1,5 @@
 import init, { type InitInput, TestEngine } from "@nanobpm/engine-wasm";
-import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+import type { ActivatedJob, ActivateInstruction, Snapshot, WasmEvent } from "./types.js";
 
 // Lazily initialise the wasm module exactly once per page, no matter how many
 // sessions are created. Mirrors the console's original `ensureWasm`.
@@ -70,6 +70,75 @@ export interface BojtosSession {
   completeJob(jobKey: string, variablesJson: string): Snapshot;
   /** Fail a waiting job; with no retries left this raises an incident. */
   failJob(jobKey: string, retries: number, message: string): Snapshot;
+  /**
+   * Throw a BPMN business error from a waiting job: interrupts the activity via a
+   * matching error boundary/event-subprocess catch, or raises an incident if
+   * uncaught. The job is consumed either way.
+   */
+  throwError(jobKey: string, errorCode: string, errorMessage: string): Snapshot;
+  /**
+   * Set a job's remaining retries. Used to recover a job parked on a no-retries
+   * incident before resolving that incident; does not itself unblock the job.
+   */
+  updateRetries(jobKey: string, retries: number): Snapshot;
+  /**
+   * Resolve an open incident by key, retrying the work that failed (returns a
+   * parked job to the activatable pool / re-evaluates a gateway / re-creates a
+   * service-task job).
+   */
+  resolveIncident(incidentKey: string): Snapshot;
+  /**
+   * Merge variables into a scope (a process-instance or element-instance key).
+   * When `local` is true they are written strictly into the target scope,
+   * otherwise they propagate up to the nearest ancestor scope defining each name.
+   */
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot;
+  /**
+   * Broadcast a signal by name to every open subscription that matches, across
+   * all instances, merging `variablesJson` into each correlated instance.
+   */
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot;
+  /** Cancel (terminate) a running process instance: every token is discarded. */
+  cancelInstance(instanceKey: string): Snapshot;
+  /**
+   * Modify a running process instance (Zeebe "modify process instance"): move
+   * tokens by terminating existing element instances and/or activating new
+   * ones. Each activate instruction places a token at `elementId` (in the
+   * process root scope), first merging its optional `variables` into the root
+   * scope; `terminateElementInstanceKeys` are the keys of active element
+   * instances (from `instances[].activeElements[].key`) to terminate. If the
+   * terminations drain the last token and nothing is activated, the instance is
+   * terminated.
+   */
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot;
+  /** Complete a waiting user task, merging `variablesJson` into the instance. */
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot;
+  /**
+   * Assign a user task to `assignee`. With `allowOverride` false the command is
+   * rejected if the task already has an assignee (unassign it first).
+   */
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot;
+  /** Clear a user task's assignee. */
+  unassignUserTask(userTaskKey: string): Snapshot;
+  /**
+   * Update a user task's attributes from a JSON changeset. Recognised keys (all
+   * optional): `candidateGroups` / `candidateUsers` (string arrays),
+   * `dueDate` / `followUpDate` (ISO-8601 string, or `null`/`""` to clear),
+   * `priority` (0..=100). Only present keys are changed.
+   */
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot;
   /**
    * Correlate a message to any instance waiting on it: publishes `messageName`
    * with `correlationKey` (the value the waiting subscription's `correlationKey`
@@ -141,6 +210,84 @@ class WasmBojtosSession implements BojtosSession {
     return parseSnapshot(this.engine.failJob(jobKey, retries, message));
   }
 
+  throwError(
+    jobKey: string,
+    errorCode: string,
+    errorMessage: string,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.throwError(jobKey, errorCode, errorMessage),
+    );
+  }
+
+  updateRetries(jobKey: string, retries: number): Snapshot {
+    return parseSnapshot(this.engine.updateRetries(jobKey, retries));
+  }
+
+  resolveIncident(incidentKey: string): Snapshot {
+    return parseSnapshot(this.engine.resolveIncident(incidentKey));
+  }
+
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.setVariables(scopeKey, variablesJson || "{}", local),
+    );
+  }
+
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.broadcastSignal(signalName, variablesJson || "{}"),
+    );
+  }
+
+  cancelInstance(instanceKey: string): Snapshot {
+    return parseSnapshot(this.engine.cancelInstance(instanceKey));
+  }
+
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.modify(
+        instanceKey,
+        JSON.stringify(activateInstructions ?? []),
+        JSON.stringify(terminateElementInstanceKeys ?? []),
+      ),
+    );
+  }
+
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.completeUserTask(userTaskKey, variablesJson || "{}"),
+    );
+  }
+
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.assignUserTask(userTaskKey, assignee, allowOverride),
+    );
+  }
+
+  unassignUserTask(userTaskKey: string): Snapshot {
+    return parseSnapshot(this.engine.unassignUserTask(userTaskKey));
+  }
+
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.updateUserTask(userTaskKey, changesetJson || "{}"),
+    );
+  }
+
   correlateMessage(
     messageName: string,
     correlationKey: string,

package/src/types.ts

@@ -63,10 +63,87 @@ export interface TimerDto {
   dueInMs: number;
 }
 
+/** A user task parked on a `userTask` element, awaiting a human. */
+export interface UserTaskDto {
+  key: string;
+  instanceKey: string;
+  elementInstanceKey: string;
+  elementId: string;
+  /** `Created` (waiting), `Completed`, or `Canceled`. */
+  state: string;
+  assignee?: string;
+  candidateGroups: string[];
+  candidateUsers: string[];
+  dueDate?: string;
+  followUpDate?: string;
+  priority: number;
+}
+
+/** An open message subscription (a waiting message catch/boundary event). */
+export interface MessageSubscriptionDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  messageName: string;
+  correlationKey: string;
+  /** What the subscription guards (intermediate/boundary, interrupting or not). */
+  kind: string;
+}
+
+/** An open signal subscription (a waiting signal catch/boundary event). */
+export interface SignalSubscriptionDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  signalName: string;
+  kind: string;
+}
+
+/**
+ * Per-element token statistics for diagram overlays: `active` live tokens,
+ * cumulative `completed` element instances, and current `incidents`.
+ */
+export interface ElementStatDto {
+  elementId: string;
+  active: number;
+  completed: number;
+  incidents: number;
+}
+
+/** A traversed connection, as source/target element ids. */
+export interface SequenceFlowDto {
+  from: string;
+  to: string;
+}
+
+/** An evaluated decision instance (from a `businessRuleTask` / DMN). */
+export interface DecisionInstanceDto {
+  instanceKey: string;
+  elementId: string;
+  decisionKey: string;
+  decisionId: string;
+  output: unknown;
+  evaluatedAt: number;
+}
+
+/**
+ * One activation instruction for {@link BojtosSession.modify}: place a new token
+ * at `elementId`, first merging `variables` into the instance's root scope.
+ * Mirrors Zeebe's process-instance-modification activate instruction (the token
+ * is activated in the process root scope).
+ */
+export interface ActivateInstruction {
+  elementId: string;
+  variables?: Record<string, unknown>;
+}
+
 /**
  * The full simulation state returned by every engine command. `activeElementIds`
  * / `incidentElementIds` drive the token/incident highlight (the visual
  * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ * `userTasks`, `messageSubscriptions`, `signalSubscriptions`, `elementStats`,
+ * `takenSequenceFlows` and `decisionInstances` back a Web-Modeler-Play-style UI
+ * (task panels, correlation/broadcast, overlays, DMN results).
  */
 export interface Snapshot {
   now: number;
@@ -79,6 +156,12 @@ export interface Snapshot {
   jobs: JobDto[];
   incidents: IncidentDto[];
   timers: TimerDto[];
+  userTasks: UserTaskDto[];
+  messageSubscriptions: MessageSubscriptionDto[];
+  signalSubscriptions: SignalSubscriptionDto[];
+  elementStats: ElementStatDto[];
+  takenSequenceFlows: SequenceFlowDto[];
+  decisionInstances: DecisionInstanceDto[];
   activeElementIds: string[];
   incidentElementIds: string[];
 }