@weave-kit/engine 0.4.0 → 0.6.0

package/dist/runtime/data-access/workflow.d.ts

@@ -0,0 +1,146 @@
+import type { Pool, PoolClient } from 'pg';
+import type { IdentitySubject, Locale, WorkflowDefinition } from '../../core/index.js';
+/** the workflow action set (single source of truth) */
+export declare const WORKFLOW_ACTIONS: {
+    readonly SUBMIT: "submit";
+    readonly APPROVE: "approve";
+    readonly REJECT: "reject";
+    readonly WITHDRAW: "withdraw";
+    readonly CANCEL: "cancel";
+    readonly FORWARD: "forward";
+    readonly REACTIVATE: "reactivate";
+};
+export type WorkflowAction = (typeof WORKFLOW_ACTIONS)[keyof typeof WORKFLOW_ACTIONS];
+/** role name that may run admin-only actions (reactivate / future override) */
+export declare const WORKFLOW_ADMIN_ROLE = "admin";
+/** true when the subject holds an admin role */
+export declare function isWorkflowAdmin(subject: IdentitySubject | undefined): boolean;
+/** what the caller needs to audit / emit / re-arm timers after a transition */
+export interface WorkflowTransitionOutcome {
+    /** resulting instance state */
+    state: 'running' | 'finished' | 'canceled';
+    /** current active node id (running) — for the timeout scheduler */
+    nodeId?: string;
+    /** node the record left (for audit / the transitioned event) */
+    fromNodeId?: string;
+    /** node the record entered (for audit / the transitioned event) */
+    toNodeId?: string;
+}
+export interface WorkflowRuntimeOptions {
+    name: string;
+    workflow?: WorkflowDefinition;
+    workflowHash?: string;
+}
+/**
+ * Run one workflow action within the caller's transaction. The instance row is
+ * locked; steps/workitems are opened/closed accordingly. The side-table status
+ * mirror is updated in the same transaction.
+ */
+export declare function runWorkflowTransition(client: PoolClient, def: WorkflowRuntimeOptions, recordKey: string, action: string, subject: IdentitySubject | undefined, payload: Record<string, unknown> | undefined, locale: Locale | undefined): Promise<WorkflowTransitionOutcome>;
+/** presence-lock TTL (seconds) — matches the frontend heartbeat convention */
+export declare const WORKFLOW_LOCK_TTL_SECONDS = 60;
+/** one open workitem of the current step, as seen by a caller */
+export interface WorkflowWorkitemView {
+    id: string;
+    nodeId: string;
+    kind: string;
+    state: string;
+    participant: string;
+}
+/** read-only workflow status for a record (GET …/workflow) */
+export interface WorkflowStatus {
+    state: 'draft' | 'running' | 'finished' | 'canceled';
+    /** current node id (running only) */
+    node?: string;
+    approval?: string | null;
+    /** actions available to the caller */
+    actions: string[];
+    /** the caller's open workitems on the current step */
+    workitems: WorkflowWorkitemView[];
+}
+/**
+ * Read a record's workflow status (no locking): instance state, current node
+ * and the actions available to `subject`. Used by the REST/MCP read surface.
+ */
+export declare function getWorkflowStatus(client: Pool | PoolClient, def: WorkflowRuntimeOptions, recordKey: string, subject: IdentitySubject | undefined): Promise<WorkflowStatus>;
+/** acquire/renew the caller's presence lock on the current step (TTL lease) */
+export declare function acquireWorkflowLock(client: Pool | PoolClient, def: WorkflowRuntimeOptions, recordKey: string, subject: IdentitySubject | undefined, locale: Locale | undefined): Promise<{
+    expiresAt: Date;
+}>;
+/** release the caller's presence lock (and drop any expired locks for the record) */
+export declare function releaseWorkflowLock(client: Pool | PoolClient, def: WorkflowRuntimeOptions, recordKey: string, subject: IdentitySubject | undefined): Promise<void>;
+/** one step in a record's workflow history */
+export interface WorkflowStepView {
+    id: string;
+    nodeId: string;
+    kind: string;
+    ordinal: number;
+    state: string;
+    approval: string | null;
+    enteredAt: Date;
+    finishedAt: Date | null;
+}
+/** one workitem in a record's workflow history */
+export interface WorkflowWorkitemHistory {
+    id: string;
+    stepId: string;
+    nodeId: string;
+    kind: string;
+    participant: string;
+    state: string;
+    approval: string | null;
+    action: string | null;
+    finisher: string | null;
+    delegant: string | null;
+    receiptor: string | null;
+    comment: string | null;
+    receivedAt: Date;
+    finishedAt: Date | null;
+    allowedAt: Date | null;
+}
+/** a record's full workflow history (steps + workitems) */
+export interface WorkflowHistory {
+    state: string;
+    approval: string | null;
+    steps: WorkflowStepView[];
+    workitems: WorkflowWorkitemHistory[];
+}
+/** read a record's workflow history (steps + workitems), oldest first */
+export declare function getWorkflowHistory(client: Pool | PoolClient, def: WorkflowRuntimeOptions, recordKey: string): Promise<WorkflowHistory>;
+/** one pending workitem in a subject's cross-object inbox */
+export interface WorkflowTodo {
+    object: string;
+    recordKey: string;
+    workitemId: string;
+    nodeId: string;
+    kind: string;
+    state: string;
+}
+/** the subject's pending workitems across all objects (`approve` items awaiting action) */
+export declare function getWorkflowTodos(client: Pool | PoolClient, subject: IdentitySubject | undefined): Promise<WorkflowTodo[]>;
+/**
+ * Fire a node's `onTimeout` action (system actor): approve advances, reject
+ * rolls back. Stale timers (the record already left the node) are ignored.
+ * Returns the node the record is now at so the caller can re-arm the timer.
+ */
+export declare function advanceOnTimeout(client: PoolClient, def: WorkflowRuntimeOptions, recordKey: string, nodeId: string, action: 'approve' | 'reject', locale: Locale | undefined): Promise<{
+    state: 'running' | 'finished';
+    nodeId?: string;
+}>;
+/** an admin override patch (`PATCH …/workflow`) */
+export interface WorkflowOverride {
+    /** jump the record to this node (must exist in the pinned definition) */
+    node?: string;
+    /** or terminate it (`canceled` / `finished`) */
+    state?: string;
+}
+/**
+ * Admin override: jump a record to a node, or terminate it. Admin-only
+ * (`WORKFLOW_ADMIN_ROLE`); unlike `reactivate` it also applies to a running
+ * instance.
+ */
+export declare function overrideWorkflow(client: PoolClient, def: WorkflowRuntimeOptions, recordKey: string, patch: WorkflowOverride, subject: IdentitySubject | undefined, locale: Locale | undefined): Promise<{
+    state: string;
+    nodeId?: string;
+}>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/runtime/data-access/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/runtime/data-access/workflow.ts"],"names":[],"mappings":"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"}