@nanobpm/urban 0.82.1 → 0.84.0

package/src/runtime/engine/nanosdk.ts

@@ -13,8 +13,17 @@
 
 import type {
   EngineClient,
+  ElementInstanceState,
+  ElementInstanceSummary,
+  ElementInstanceFilter,
+  ElementInstanceWaitState,
+  ElementInstanceWaitStateFilter,
+  WaitStateType,
   EngineJob,
   FormSchema,
+  IncidentFilter,
+  IncidentState,
+  IncidentSummary,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
@@ -63,6 +72,294 @@ export function normalizeProcessInstanceState(
   }
 }
 
+/** 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 function normalizeElementInstanceState(
+  raw: unknown,
+): ElementInstanceState | undefined {
+  if (typeof raw !== "string") return undefined;
+  switch (raw.toUpperCase()) {
+    case "ACTIVE":
+      return "ACTIVE";
+    case "COMPLETED":
+      return "COMPLETED";
+    case "TERMINATED":
+      return "TERMINATED";
+    default:
+      return 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 function normalizeWaitStateType(raw: unknown): WaitStateType | undefined {
+  if (typeof raw !== "string") return undefined;
+  switch (raw.toUpperCase()) {
+    case "JOB":
+      return "JOB";
+    case "MESSAGE":
+      return "MESSAGE";
+    case "USER_TASK":
+      return "USER_TASK";
+    case "TIMER":
+      return "TIMER";
+    case "SIGNAL":
+      return "SIGNAL";
+    case "CONDITION":
+      return "CONDITION";
+    default:
+      return 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 function normalizeIncidentState(raw: unknown): IncidentState {
+  if (typeof raw !== "string") return "UNKNOWN";
+  switch (raw.toUpperCase()) {
+    case "ACTIVE":
+      return "ACTIVE";
+    case "MIGRATED":
+      return "MIGRATED";
+    case "PENDING":
+      return "PENDING";
+    case "RESOLVED":
+      return "RESOLVED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a numeric key to a string (the engine may serialize a key
+ *  either way) but never `String(...)`-coerces an arbitrary object into a garbage
+ *  `"[object Object]"` id. The blank check trims, matching `getElementInstance`'s blank-key
+ *  guard and the form-key presence helpers, so a `"   "` key can never leak into a result. */
+function presentEngineKey(value: unknown): string | undefined {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : undefined;
+  }
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
+ *  absent/blank (including a whitespace-only string). A mutating seam operation addresses a
+ *  single entity by key, so a blank key is a caller bug that must fail fast with an actionable
+ *  message rather than reach the engine as an empty path segment / invalid changeset and surface
+ *  an opaque transport error. Reuses {@link presentEngineKey}'s trim-and-coerce rule so a padded
+ *  key like `" 5 "` is normalized identically to how read paths resolve it. */
+function requireEngineKey(value: unknown, name: string): string {
+  const key = presentEngineKey(value);
+  if (key === undefined) {
+    throw new Error(`${name} must be a non-empty key`);
+  }
+  return key;
+}
+
+/** A required text field (a wait-state discriminator's `jobType`/`messageName`/`signalName`),
+ *  or `undefined` when absent or blank — the caller skips the row rather than emitting a typed
+ *  wait state carrying an empty required string. Returns the trimmed value, matching the
+ *  presence rule used for keys, so surrounding whitespace can never leak into a result. */
+function presentText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** The element type carried on an element-instance/wait-state row. The Camunda SDK DTO calls
+ *  it `type`; a plain REST/Rust-engine body may call it `elementType`. Accept either. */
+function pickElementType(row: Record<string, unknown>): string | undefined {
+  return presentText(row.elementType) ?? presentText(row.type);
+}
+
+/** 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 function mapElementInstanceRow(
+  row: Record<string, unknown>,
+  log: Log,
+): ElementInstanceSummary | undefined {
+  const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+  if (elementInstanceKey === undefined) {
+    log("warn", "skipping element instance with no key in engine response");
+    return undefined;
+  }
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  if (processInstanceKey === undefined) {
+    log("warn", "skipping element instance with no processInstanceKey in engine response", {
+      elementInstanceKey,
+    });
+    return undefined;
+  }
+  const elementId = typeof row.elementId === "string" && row.elementId.trim() !== ""
+    ? row.elementId.trim()
+    : undefined;
+  if (elementId === undefined) {
+    log("warn", "skipping element instance with no elementId in engine response", {
+      elementInstanceKey,
+    });
+    return undefined;
+  }
+  const state = normalizeElementInstanceState(row.state);
+  if (state === undefined) {
+    log("warn", "skipping element instance with unrecognized state", {
+      elementInstanceKey,
+      state: String(row.state),
+    });
+    return undefined;
+  }
+  const elementType = pickElementType(row);
+  return {
+    elementInstanceKey,
+    processInstanceKey,
+    elementId,
+    ...(elementType ? { elementType } : {}),
+    state,
+  };
+}
+
+/** 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 function mapElementInstanceWaitStateRow(
+  row: Record<string, unknown>,
+  log: Log,
+): ElementInstanceWaitState | undefined {
+  const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  const elementId = typeof row.elementId === "string" && row.elementId.trim() !== ""
+    ? row.elementId.trim()
+    : undefined;
+  if (elementInstanceKey === undefined || processInstanceKey === undefined || elementId === undefined) {
+    log("warn", "skipping element-instance wait state with incomplete identity in engine response");
+    return undefined;
+  }
+  const details = isRecord(row.details) ? row.details : row;
+  const waitStateType = normalizeWaitStateType(details.waitStateType ?? row.waitStateType);
+  if (waitStateType === undefined) {
+    log("warn", "skipping element-instance wait state with unrecognized waitStateType", {
+      elementInstanceKey,
+      waitStateType: String(details.waitStateType ?? row.waitStateType),
+    });
+    return undefined;
+  }
+  const elementType = pickElementType(row);
+  const base = {
+    elementInstanceKey,
+    processInstanceKey,
+    elementId,
+    ...(elementType ? { elementType } : {}),
+  };
+  switch (waitStateType) {
+    case "JOB": {
+      // `jobType` is the required discriminator of a JOB park; without it the row is malformed.
+      const jobType = presentText(details.jobType);
+      if (jobType === undefined) {
+        log("warn", "skipping JOB wait state with no jobType in engine response", {
+          elementInstanceKey,
+        });
+        return undefined;
+      }
+      const jobKey = presentEngineKey(details.jobKey);
+      return { ...base, waitStateType, jobType, ...(jobKey ? { jobKey } : {}) };
+    }
+    case "MESSAGE": {
+      // `messageName` is the required discriminator of a MESSAGE park.
+      const messageName = presentText(details.messageName);
+      if (messageName === undefined) {
+        log("warn", "skipping MESSAGE wait state with no messageName in engine response", {
+          elementInstanceKey,
+        });
+        return undefined;
+      }
+      const correlationKey = presentText(details.correlationKey);
+      return {
+        ...base,
+        waitStateType,
+        messageName,
+        ...(correlationKey ? { correlationKey } : {}),
+      };
+    }
+    case "USER_TASK": {
+      // `userTaskKey` is the required identity of a USER_TASK park; without it the row is
+      // malformed. Skip it (like the missing-identity guards above) rather than emit a typed
+      // wait state carrying an empty key that would break a downstream join.
+      const userTaskKey = presentEngineKey(details.taskKey ?? details.userTaskKey);
+      if (userTaskKey === undefined) {
+        log("warn", "skipping USER_TASK wait state with no userTaskKey in engine response", {
+          elementInstanceKey,
+        });
+        return undefined;
+      }
+      return { ...base, waitStateType, userTaskKey };
+    }
+    case "SIGNAL": {
+      // `signalName` is the required discriminator of a SIGNAL park.
+      const signalName = presentText(details.signalName);
+      if (signalName === undefined) {
+        log("warn", "skipping SIGNAL wait state with no signalName in engine response", {
+          elementInstanceKey,
+        });
+        return undefined;
+      }
+      return { ...base, waitStateType, signalName };
+    }
+    case "TIMER":
+      return { ...base, waitStateType };
+    case "CONDITION":
+      return { ...base, waitStateType };
+  }
+}
+
+/** 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 function mapIncidentRow(
+  row: Record<string, unknown>,
+  log: Log,
+): IncidentSummary | undefined {
+  const incidentKey = presentEngineKey(row.incidentKey);
+  if (incidentKey === undefined) {
+    log("warn", "skipping incident with no incidentKey in engine response");
+    return undefined;
+  }
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  if (processInstanceKey === undefined) {
+    log("warn", "skipping incident with no processInstanceKey in engine response", {
+      incidentKey,
+    });
+    return undefined;
+  }
+  const elementId = presentText(row.elementId);
+  const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+  const jobKey = presentEngineKey(row.jobKey);
+  const errorType = presentText(row.errorType);
+  const errorMessage = presentText(row.errorMessage);
+  return {
+    incidentKey,
+    processInstanceKey,
+    ...(elementId ? { elementId } : {}),
+    ...(elementInstanceKey ? { elementInstanceKey } : {}),
+    ...(jobKey ? { jobKey } : {}),
+    ...(errorType ? { errorType } : {}),
+    ...(errorMessage ? { errorMessage } : {}),
+    state: normalizeIncidentState(row.state),
+  };
+}
+
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -146,6 +443,38 @@ export interface NanoSdkClient {
     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
@@ -355,6 +684,140 @@ export class SdkEngineClient implements EngineClient {
     });
   }
 
+  async searchElementInstances(
+    filter?: ElementInstanceFilter,
+  ): Promise<ElementInstanceSummary[]> {
+    // Mirror `searchProcessInstances`: build the engine filter from the transport-agnostic
+    // selectors, read at zero-wait consistency (an element-instance search is eventually
+    // consistent), and map each row through the single `mapElementInstanceRow` gate — which
+    // also `searchElementInstances`/`getElementInstance` share — dropping malformed rows.
+    const f: Record<string, unknown> = {};
+    if (filter?.processInstanceKey) f.processInstanceKey = filter.processInstanceKey;
+    if (filter?.elementId) f.elementId = filter.elementId;
+    if (filter?.state) f.state = filter.state;
+    const body = await this.client.searchElementInstances(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapElementInstanceRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async searchElementInstanceWaitStates(
+    filter?: ElementInstanceWaitStateFilter,
+  ): Promise<ElementInstanceWaitState[]> {
+    // The wait-states search surfaces *every* park (job/message/timer/signal/condition/user
+    // task), not just user tasks. Same zero-wait read + per-row mapping-gate shape as
+    // `searchElementInstances`; the SDK nests park-specific fields under `details`, which
+    // `mapElementInstanceWaitStateRow` unwraps.
+    const f: Record<string, unknown> = {};
+    if (filter?.processInstanceKey) f.processInstanceKey = filter.processInstanceKey;
+    if (filter?.elementId) f.elementId = filter.elementId;
+    if (filter?.waitStateType) f.waitStateType = filter.waitStateType;
+    const body = await this.client.searchElementInstanceWaitStates(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapElementInstanceWaitStateRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async getElementInstance(
+    elementInstanceKey: string,
+  ): Promise<ElementInstanceSummary | null> {
+    // A blank key can never address an element instance — short-circuit to null rather than
+    // issue a `GET /element-instances/` with an empty segment. Normalize the key up front (as
+    // `getForm` resolves a normalized identifier before fetching) so a padded-but-valid key
+    // like `" 5 "` addresses the same element instance rather than 404ing on the raw segment.
+    if (typeof elementInstanceKey !== "string" || elementInstanceKey.trim() === "") {
+      return null;
+    }
+    const key = elementInstanceKey.trim();
+    let body: Record<string, unknown>;
+    try {
+      body = await this.client.getElementInstance(
+        { elementInstanceKey: key },
+        { consistency: { waitUpToMs: 0 } },
+      );
+    } catch (err) {
+      // A 404 (no such element instance) is an expected "not found", not a fault — mirror
+      // `getForm`, which treats a failed fetch as absence (null) rather than propagating.
+      this.log("warn", "getElementInstance: engine fetch failed", {
+        elementInstanceKey: key,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+    if (!isRecord(body)) return null;
+    return mapElementInstanceRow(body, this.log) ?? null;
+  }
+
+  async searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]> {
+    // Same shape as `searchElementInstances`: build the engine filter from the transport-agnostic
+    // selectors, read at zero-wait consistency (an incident search is eventually consistent), and
+    // map each row through the single `mapIncidentRow` gate, dropping malformed rows.
+    const f: Record<string, unknown> = {};
+    // Normalize the request selectors the same way the response mapper normalizes keys: a
+    // whitespace-only/padded `processInstanceKey` must not reach the engine as a garbage filter
+    // segment (which would silently return surprising empty results).
+    const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+    if (processInstanceKey) f.processInstanceKey = processInstanceKey;
+    if (filter?.state) f.state = filter.state;
+    const body = await this.client.searchIncidents(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapIncidentRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async resolveIncident(input: { incidentKey: string }): Promise<void> {
+    await this.client.resolveIncident({
+      incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),
+    });
+  }
+
+  async updateJobRetries(input: { jobKey: string; retries: number }): Promise<void> {
+    // The "retry a failed job" operation: a job's remaining retries are the `retries` field of
+    // the `updateJob` changeset. Bumping them back above zero makes a failed job activatable so a
+    // paired `resolveIncident` can return it to the pool.
+    const jobKey = requireEngineKey(input.jobKey, "jobKey");
+    // `retries` serializes straight into the engine changeset, and `number` admits `NaN`,
+    // fractional, and negative values — none of which is a valid retry count. Reject them up
+    // front so a tool-driven call fails with a clear message instead of an opaque engine error.
+    if (!Number.isInteger(input.retries) || input.retries < 0) {
+      throw new Error("retries must be a non-negative integer");
+    }
+    await this.client.updateJob({
+      jobKey,
+      changeset: { retries: input.retries },
+    });
+  }
+
+  async setVariables(input: {
+    scopeKey: string;
+    variables: Record<string, unknown>;
+    local?: boolean;
+  }): Promise<void> {
+    // A scope is addressed by its element-instance key (the process instance's root scope is an
+    // element instance too), so `scopeKey` maps straight onto `elementInstanceKey`. `local`
+    // defaults to engine behaviour (propagate to the outermost scope) when unset.
+    await this.client.createElementInstanceVariables({
+      elementInstanceKey: requireEngineKey(input.scopeKey, "scopeKey"),
+      variables: input.variables,
+      ...(input.local === undefined ? {} : { local: input.local }),
+    });
+  }
+
   async registerWorker(
     jobType: string,
     handler: JobHandler,

package/src/runtime/index.ts

@@ -83,6 +83,12 @@ export type { ValidationIssue } from "./core/validate.ts";
 // Host + engine contracts (for custom hosts / tests)
 export type {
   EngineClient,
+  ElementInstanceState,
+  ElementInstanceSummary,
+  ElementInstanceFilter,
+  ElementInstanceWaitState,
+  ElementInstanceWaitStateFilter,
+  WaitStateType,
   EngineJob,
   FormSchema,
   HostContext,
@@ -90,6 +96,10 @@ export type {
   HttpRequest,
   HttpResponse,
   HttpServer,
+  IncidentState,
+  EngineIncidentState,
+  IncidentFilter,
+  IncidentSummary,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,