@nanobpm/urban 0.82.1 → 0.84.0

package/dist/runtime/core/host.d.ts

@@ -227,6 +227,142 @@ export interface UserTaskFilter {
     assignee?: string;
     candidateGroup?: string;
 }
+/**
+ * An element instance's lifecycle state, as the engine reports it on a
+ * `/v2/element-instances/search` result. Mirrors the engine's `ElementInstanceStateEnum`:
+ * `ACTIVE` (a token is currently *at* this element), `COMPLETED` (the token has left it), or
+ * `TERMINATED` (the element was interrupted). Structurally the same state set as
+ * {@link ProcessInstanceState} (one active state plus the `COMPLETED`/`TERMINATED` terminals),
+ * but a distinct concept — element instances are the tokens *within* a process instance — so it
+ * is kept as its own type rather than aliased.
+ */
+export type ElementInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+/**
+ * A single element instance ("token") as {@link EngineClient.searchElementInstances} and
+ * {@link EngineClient.getElementInstance} report it — the finest-grained "how far has this
+ * process instance progressed" signal, below the process-instance lifecycle
+ * ({@link ProcessInstanceSnapshot}) and independent of whether the element is a user task
+ * ({@link UserTaskSummary}). It surfaces active *non-user-task* elements (a service task, a
+ * gateway, a catch event) a user-task search cannot see — "the furthest element reached".
+ * Carries the element instance's own key, its identity (`elementId`, its BPMN `elementType`
+ * when the engine reports it), the owning process instance, and its lifecycle `state`.
+ */
+export interface ElementInstanceSummary {
+    readonly elementInstanceKey: string;
+    readonly processInstanceKey: string;
+    readonly elementId: string;
+    /** The BPMN element type (e.g. `"SERVICE_TASK"`, `"USER_TASK"`,
+     *  `"INTERMEDIATE_CATCH_EVENT"`), when the engine reports it. Kept transport-agnostic (a
+     *  bare string) so a new BPMN element type on the engine flows through without having to be
+     *  enumerated here. Absent when the adapter's read model does not carry it. */
+    readonly elementType?: string;
+    readonly state: ElementInstanceState;
+}
+/**
+ * The kind of wait an element instance is parked in, as a
+ * `/v2/element-instances/wait-states/search` result reports it. Unlike a user-task search,
+ * this surfaces *every* park — a `JOB` (a service task awaiting a worker), a `MESSAGE`
+ * (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well as a
+ * `USER_TASK` — so a consumer can read "what is this instance blocked on" beyond user tasks.
+ */
+export type WaitStateType = "JOB" | "MESSAGE" | "USER_TASK" | "TIMER" | "SIGNAL" | "CONDITION";
+/**
+ * A single parked (waiting) element instance as
+ * {@link EngineClient.searchElementInstanceWaitStates} reports it. Every variant carries the
+ * element instance's identity; the `waitStateType` discriminates the park-specific fields — a
+ * `JOB` carries the `jobType`/`jobKey` it is parked on, a `MESSAGE` the awaited
+ * `messageName`/`correlationKey`, a `USER_TASK` the `userTaskKey`, a `SIGNAL` the
+ * `signalName` — so a caller narrows on `waitStateType` to reach them type-safely rather than
+ * probing a flat optional-field bag.
+ */
+export type ElementInstanceWaitState = {
+    readonly elementInstanceKey: string;
+    readonly processInstanceKey: string;
+    readonly elementId: string;
+    readonly elementType?: string;
+} & ({
+    readonly waitStateType: "JOB";
+    readonly jobType: string;
+    readonly jobKey?: string;
+} | {
+    readonly waitStateType: "MESSAGE";
+    readonly messageName: string;
+    readonly correlationKey?: string;
+} | {
+    readonly waitStateType: "USER_TASK";
+    readonly userTaskKey: string;
+} | {
+    readonly waitStateType: "TIMER";
+} | {
+    readonly waitStateType: "SIGNAL";
+    readonly signalName: string;
+} | {
+    readonly waitStateType: "CONDITION";
+});
+/**
+ * Selectors for an element-instance search: which process instance, element, and/or lifecycle
+ * state to match. Used by {@link EngineClient.searchElementInstances}.
+ */
+export interface ElementInstanceFilter {
+    processInstanceKey?: string;
+    elementId?: string;
+    state?: ElementInstanceState;
+}
+/**
+ * Selectors for an element-instance *wait-state* search: which process instance, element,
+ * and/or kind of wait to match. Used by {@link EngineClient.searchElementInstanceWaitStates}.
+ * There is deliberately no lifecycle-`state` selector — a wait state is always an active park.
+ */
+export interface ElementInstanceWaitStateFilter {
+    processInstanceKey?: string;
+    elementId?: string;
+    waitStateType?: WaitStateType;
+}
+/**
+ * The engine's own incident-state enum — the lifecycle states an engine actually reports and
+ * that are valid as a search selector. An `ACTIVE` incident is an open fault a human/agent can
+ * act on (resolve/retry); the other values are terminal or transitional. This is the single
+ * source of truth for real engine states; {@link IncidentState} derives from it.
+ */
+export type EngineIncidentState = "ACTIVE" | "MIGRATED" | "PENDING" | "RESOLVED";
+/**
+ * The lifecycle state of an incident, as {@link EngineClient.searchIncidents} reports it.
+ * Extends {@link EngineIncidentState} with the client-side `"UNKNOWN"` sentinel — a fallback
+ * used when the engine returns an unrecognized/absent value, so an incident is surfaced rather
+ * than dropped for an odd state. Because `"UNKNOWN"` is not a real engine state, it is not a
+ * valid {@link IncidentFilter} selector. A caller narrows on this union rather than probing a
+ * raw string.
+ */
+export type IncidentState = EngineIncidentState | "UNKNOWN";
+/**
+ * Selectors for an incident search: which process instance and/or lifecycle state to match.
+ * Used by {@link EngineClient.searchIncidents}. An eventually consistent (zero-wait) read; an
+ * unset selector matches every incident.
+ */
+export interface IncidentFilter {
+    processInstanceKey?: string;
+    state?: EngineIncidentState;
+}
+/**
+ * A single incident (a stuck token — a job out of retries, an unhandled error, a failed
+ * gateway evaluation) as {@link EngineClient.searchIncidents} reports it. Carries the
+ * `incidentKey` a caller passes to {@link EngineClient.resolveIncident}, the owning
+ * `processInstanceKey`, and — when the incident is job-backed — the `jobKey` a caller passes
+ * to {@link EngineClient.updateJobRetries} to make the job retriable before resolving.
+ * `errorType`/`errorMessage` are the engine's fault description; they are free-form across
+ * engines (the live SDK reports a Camunda error-type enum, the in-process engine a coarser
+ * `kind`), so treat them as diagnostic text, not a stable taxonomy.
+ */
+export interface IncidentSummary {
+    readonly incidentKey: string;
+    readonly processInstanceKey: string;
+    readonly elementId?: string;
+    readonly elementInstanceKey?: string;
+    readonly jobKey?: string;
+    readonly errorType?: string;
+    readonly errorMessage?: string;
+    readonly state: IncidentState;
+}
 /**
  * A deployed form's form-js schema plus its identifying metadata, as
  * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
@@ -327,6 +463,76 @@ export interface EngineClient {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
     }): Promise<ProcessInstanceSnapshot[]>;
+    /**
+     * Search element instances ("tokens") by process instance, element, and/or lifecycle state
+     * (`POST /v2/element-instances/search`). Where {@link searchProcessInstances} answers "is
+     * this instance still running" and {@link searchUserTasks} answers "what user tasks are
+     * open", this answers "what element has a token reached" — including the active
+     * *non-user-task* elements (a service task, a gateway, a catch event) that a user-task
+     * search cannot see, i.e. "the furthest element reached". An eventually consistent
+     * (zero-wait) read; each {@link ElementInstanceSummary} carries the element instance's key,
+     * its `elementId`/`elementType`, the owning process instance, and its `state`.
+     */
+    searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
+    /**
+     * Search the *wait states* of element instances
+     * (`POST /v2/element-instances/wait-states/search`) — every park, not only user tasks. A
+     * `JOB` park (a service task awaiting a worker), a `MESSAGE` park (an event awaiting
+     * correlation), a `TIMER`/`SIGNAL`/`CONDITION`, plus `USER_TASK`. A zero-wait read; each
+     * result is discriminated by `waitStateType` (see {@link ElementInstanceWaitState}), so a
+     * consumer can read the job/message parks a {@link searchUserTasks} cannot surface.
+     */
+    searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
+    /**
+     * Fetch a single element instance by its key (`GET /v2/element-instances/{elementInstanceKey}`),
+     * or `null` when it cannot be resolved — the key is blank, no such element instance exists
+     * (a 404), or the fetch otherwise fails. A read is treated as absence rather than propagating
+     * (mirroring {@link getForm}), so a caller distinguishes "have it" from "don't" without a
+     * try/catch. A zero-wait read returning the same {@link ElementInstanceSummary} shape as
+     * {@link searchElementInstances}.
+     */
+    getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
+    /**
+     * Search incidents by owning process instance and/or lifecycle state
+     * (`POST /v2/incidents/search`) — the open faults blocking one or more instances (a job out
+     * of retries, an unhandled error, a failed gateway evaluation). An eventually consistent
+     * (zero-wait) read; each {@link IncidentSummary} carries the `incidentKey` to pass to
+     * {@link resolveIncident} and, for a job-backed incident, the `jobKey` to pass to
+     * {@link updateJobRetries}. The debugging counterpart to the read accessors above: where
+     * they answer "how far has this instance progressed", this answers "why is it stuck".
+     */
+    searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    /**
+     * Resolve an open incident by key (`POST /v2/incidents/{incidentKey}/resolution`), unblocking
+     * the parked token: a job incident returns the job to the activatable pool (so it must have
+     * retries left first — see {@link updateJobRetries}), a gateway incident re-evaluates, an
+     * uncaught-error incident re-creates the service-task job. A mutating operation.
+     */
+    resolveIncident(input: {
+        incidentKey: string;
+    }): Promise<void>;
+    /**
+     * Update the remaining retries of a job (`PATCH /v2/jobs/{jobKey}`) — the "retry a failed
+     * job" operation. Setting a failed job's retries back above zero makes it activatable again;
+     * paired with {@link resolveIncident}, this is how a stuck `jobNoRetries` incident is cleared
+     * (bump retries, then resolve). A mutating operation.
+     */
+    updateJobRetries(input: {
+        jobKey: string;
+        retries: number;
+    }): Promise<void>;
+    /**
+     * Set (merge) variables into a scope (`PUT /v2/element-instances/{scopeKey}/variables`).
+     * `scopeKey` is a process-instance key or an element-instance key; when `local` is `true` the
+     * variables are merged strictly into that local scope, otherwise (the default) they propagate
+     * to the outermost scope. A mutating operation used to repair state before resolving an
+     * incident or to steer an instance during debugging.
+     */
+    setVariables(input: {
+        scopeKey: string;
+        variables: Record<string, unknown>;
+        local?: boolean;
+    }): Promise<void>;
     /** Register a push worker for a job type. Draining is handled by the adapter. */
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
@@ -350,4 +556,4 @@ export interface EngineClient {
  * and `getForm` before it) that a purely structural `implements EngineClient` check no
  * longer catches once the fake is published/compiled against an older `@nanobpm/urban`.
  */
-export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "registerWorker", "close"];
+export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];

package/dist/runtime/core/host.js

@@ -66,6 +66,13 @@ export const ENGINE_CLIENT_METHODS = [
     "getForm",
     "completeUserTask",
     "searchProcessInstances",
+    "searchElementInstances",
+    "searchElementInstanceWaitStates",
+    "getElementInstance",
+    "searchIncidents",
+    "resolveIncident",
+    "updateJobRetries",
+    "setVariables",
     "registerWorker",
     "close",
 ];

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -8,6 +8,38 @@ export declare function requireProcessInstanceKey(key: string | number | null |
  *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
  *  future casing tweak on the engine side doesn't silently drop instances. */
 export declare function normalizeProcessInstanceState(raw: unknown): ProcessInstanceState | undefined;
+/** Map the engine's element-instance `state` onto the transport-agnostic
+ *  {@link ElementInstanceState} union, or `undefined` for an unrecognized value (which the
+ *  caller skips rather than surfacing a malformed row). Case-insensitive so a future casing
+ *  tweak on the engine side doesn't silently drop element instances. Kept separate from
+ *  {@link normalizeProcessInstanceState} — the two model distinct engine enums that only
+ *  coincide today — so element and process state can diverge without a hidden coupling. */
+export declare function normalizeElementInstanceState(raw: unknown): ElementInstanceState | undefined;
+/** Map the engine's wait-state `waitStateType` onto the transport-agnostic
+ *  {@link WaitStateType} union, or `undefined` for an unrecognized value. Case-insensitive
+ *  so a casing tweak doesn't silently drop parks. */
+export declare function normalizeWaitStateType(raw: unknown): WaitStateType | undefined;
+/** Map the engine's incident `state` onto the transport-agnostic {@link IncidentState} union,
+ *  falling back to `"UNKNOWN"` for an unrecognized/absent value (an incident is never dropped
+ *  for an odd state — unlike element/process rows, whose state is a hard identity field — so a
+ *  caller still sees the fault). Case-insensitive so a casing tweak doesn't mis-map. */
+export declare function normalizeIncidentState(raw: unknown): IncidentState;
+/** Map one engine element-instance row onto an {@link ElementInstanceSummary}, or `undefined`
+ *  when the row is malformed (missing key/elementId/process instance, or an unrecognized
+ *  state). The single source of truth both `searchElementInstances` and `getElementInstance`
+ *  extract through, so the two cannot drift. */
+export declare function mapElementInstanceRow(row: Record<string, unknown>, log: Log): ElementInstanceSummary | undefined;
+/** Map one engine wait-state row onto an {@link ElementInstanceWaitState}, or `undefined`
+ *  when the row is malformed (missing identity, or an unrecognized `waitStateType`). The
+ *  Camunda SDK nests the park-specific fields under `details`; a plain REST body may inline
+ *  them — read `details` first, then fall back to the row itself, so both wire shapes map. */
+export declare function mapElementInstanceWaitStateRow(row: Record<string, unknown>, log: Log): ElementInstanceWaitState | undefined;
+/** Map one engine incident row onto an {@link IncidentSummary}, or `undefined` when the row is
+ *  malformed (missing the `incidentKey` or the owning `processInstanceKey` — the two identity
+ *  fields a caller needs to resolve/act on it). `jobKey`/`elementInstanceKey`/`errorType`/
+ *  `errorMessage` are best-effort diagnostics: present when the engine reports them, omitted
+ *  otherwise. The single source of truth `searchIncidents` extracts through. */
+export declare function mapIncidentRow(row: Record<string, unknown>, log: Log): IncidentSummary | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -88,6 +120,33 @@ export interface NanoSdkClient {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
     }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchElementInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchElementInstanceWaitStates(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    getElementInstance(input: {
+        elementInstanceKey: string;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchIncidents(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    resolveIncident(input: {
+        incidentKey: string;
+    }, options?: unknown): Promise<unknown>;
+    updateJob(input: {
+        jobKey: string;
+        changeset: Record<string, unknown>;
+    }, options?: unknown): Promise<unknown>;
+    createElementInstanceVariables(input: {
+        elementInstanceKey: string;
+        variables: Record<string, unknown>;
+        local?: boolean;
+    }, options?: unknown): Promise<unknown>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
     /** Stop every worker created on this client. Used on teardown to also drain a
      * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -152,6 +211,22 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
     }): Promise<ProcessInstanceSnapshot[]>;
+    searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
+    searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
+    getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
+    searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    resolveIncident(input: {
+        incidentKey: string;
+    }): Promise<void>;
+    updateJobRetries(input: {
+        jobKey: string;
+        retries: number;
+    }): Promise<void>;
+    setVariables(input: {
+        scopeKey: string;
+        variables: Record<string, unknown>;
+        local?: boolean;
+    }): Promise<void>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;