@dotbep/core 0.2.12 → 0.2.14

package/dist/index.d.ts

@@ -77,6 +77,9 @@ export declare const AssetTypeSchema: z.ZodObject<{
     extensionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 
+/** Fires when an automation handler throws. */
+export declare type AutomationFailedListener = (instance: WorkflowInstance, automationId: string, error: string) => Promise<void>;
+
 /**
  * Handler for an automation node. Receives the instance and the payload filtered
  * from instance.context according to FlowAutomation.payload. Must return an object
@@ -340,6 +343,7 @@ export declare const BEPSchema: z.ZodObject<{
                 pattern: z.ZodString;
                 flags: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
+            validationMessage: z.ZodOptional<z.ZodString>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -361,6 +365,7 @@ export declare const BEPSchema: z.ZodObject<{
                 pattern: z.ZodString;
                 flags: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
+            validationMessage: z.ZodOptional<z.ZodString>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -382,6 +387,7 @@ export declare const BEPSchema: z.ZodObject<{
                 pattern: z.ZodString;
                 flags: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
+            validationMessage: z.ZodOptional<z.ZodString>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
         output: z.ZodArray<z.ZodObject<{
@@ -398,6 +404,7 @@ export declare const BEPSchema: z.ZodObject<{
                 pattern: z.ZodString;
                 flags: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
+            validationMessage: z.ZodOptional<z.ZodString>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
@@ -852,10 +859,8 @@ export declare type EffectHandler = (instance: WorkflowInstance, payload: Record
 export declare interface EffectOutcome {
     effectId: string;
     fromEdgeId: string;
-    /** executed = handler ran ok | skipped = no handler or missing required fields | failed = handler threw */
+    /** executed = handler ran ok | skipped = no handler registered | failed = handler threw */
     status: 'executed' | 'skipped' | 'failed';
-    /** Required context fields that were missing. Present when status = 'skipped'. */
-    missingFields?: string[];
     /** Error message thrown by the handler. Present when status = 'failed'. */
     error?: string;
 }
@@ -869,71 +874,50 @@ export declare class Engine {
     private readonly getHistoricalBep?;
     private _runtime;
     private storage;
-    get runtime(): Runtime<any>;
     private skipRaci;
-    private readonly transitionListeners;
-    private readonly createdListeners;
-    private readonly completedListeners;
-    private readonly effectFailedListeners;
-    /**
-     * Called internally by Bep — injects the BEP data getter and history resolver.
-     * Use bep.engine.init() to configure the runtime and storage before operating.
-     */
+    private readonly _transitionListeners;
+    private readonly _createdListeners;
+    private readonly _completedListeners;
+    private readonly _cancelledListeners;
+    private readonly _effectFailedListeners;
+    private readonly _automationFailedListeners;
+    get runtime(): Runtime<any>;
+    /** Namespaced workflow instance operations. */
+    readonly workflows: {
+        create(workflowId: string, trackedAsset: WorkflowInstance['trackedAsset'], initiatedBy: string): Promise<WorkflowInstance | null>;
+        emit(instanceId: string, event: IncomingEvent): Promise<EventResult>;
+        get(instanceId: string): Promise<WorkflowInstance | null>;
+        list(filter?: InstanceFilter): Promise<WorkflowInstance[]>;
+        delete(instanceId: string): Promise<void>;
+        cancel(instanceId: string): Promise<void>;
+        getStatus(instanceId: string): Promise<WorkflowStatus | null>;
+        resolveContext(instanceId: string): Promise<Record<string, unknown>>;
+        onTransition(listener: TransitionListener): Engine;
+        onCreated(listener: LifecycleListener): Engine;
+        onCompleted(listener: LifecycleListener): Engine;
+        onCancelled(listener: LifecycleListener): Engine;
+        onEffectFailed(listener: EffectFailedListener): Engine;
+        onAutomationFailed(listener: AutomationFailedListener): Engine;
+    };
     constructor(getBep: () => BEP, getHistoricalBep?: (version: string) => Promise<BEP>);
     /**
      * Configures the engine with a runtime and storage backend.
-     * Must be called before any operations (createInstance, emit, etc.).
+     * Must be called before any operations (workflows.create, workflows.emit, etc.).
      * Returns `this` for chaining.
      */
     init(config: EngineInitConfig): this;
-    /** Fires after every successful emit() — all listeners run concurrently. */
-    onTransition(listener: TransitionListener): this;
-    /** Fires after createInstance() persists the new instance. */
-    onInstanceCreated(listener: LifecycleListener): this;
-    /** Fires when instance.status becomes 'completed'. */
-    onInstanceCompleted(listener: LifecycleListener): this;
-    /** Fires when an effect handler throws or returns status 'failed'. */
-    onEffectFailed(listener: EffectFailedListener): this;
-    /**
-     * Creates a new workflow instance positioned at the first node after start and persists it.
-     * Records the current BEP version on the instance for historical resolution.
-     * Returns null if the workflowId does not exist or has no start node.
-     */
-    createInstance(workflowId: string, trackedAsset: WorkflowInstance['trackedAsset'], initiatedBy: string): Promise<WorkflowInstance | null>;
-    /**
-     * Emits an event against a workflow instance.
-     *
-     * 1. Loads the instance from storage.
-     * 2. Resolves the BEP version the instance was created against.
-     * 3. Processes the event (pure transition logic — transitions + decision auto-traversal).
-     * 4. Persists the updated instance.
-     * 5. Executes effect handlers declared in the runtime.
-     * 6. Fires lifecycle listeners concurrently.
-     * 7. Returns the result with the updated instance and effect outcomes.
-     */
-    emit(instanceId: string, event: IncomingEvent): Promise<EventResult>;
-    getInstance(instanceId: string): Promise<WorkflowInstance | null>;
-    /**
-     * Returns instances matching the filter.
-     * `pendingActionFor` (Member.email) is resolved at the Engine level using
-     * the BEP RACI data — the storage layer does not need to understand it.
-     */
-    getInstances(filter?: InstanceFilter): Promise<WorkflowInstance[]>;
-    /**
-     * Returns what a specific actor can do from the current node of an instance.
-     * Returns null if the instance does not exist.
-     */
-    getNodeConfig(instanceId: string, actorEmail: string): Promise<NodeConfig | null>;
-    deleteInstance(instanceId: string): Promise<void>;
-    /**
-     * Runs the resolver declared for a remote data source and returns the raw payload.
-     * Throws if the remoteDataId does not exist in the BEP or has no resolver assigned.
-     */
     getRemoteData(remoteDataId: string): Promise<unknown>;
+    private _create;
+    private _emit;
+    private _get;
+    private _list;
+    private _delete;
+    private _cancel;
+    private _getStatus;
+    private _resolveContext;
     private _assertInit;
     private _resolveBep;
     private _fire;
-    private _resolveFromHistory;
     private _executeAutomationNode;
     private _executeEffect;
 }
@@ -950,6 +934,13 @@ export declare interface EngineInitConfig {
     };
 }
 
+/** Minimal engine reference available to runtime handlers via this.engine. */
+export declare interface EngineRef {
+    workflows: {
+        resolveContext(instanceId: string): Promise<Record<string, unknown>>;
+    };
+}
+
 export declare class Entity<T extends object, AutoId extends boolean = false> {
     private getItems;
     protected getBep: () => BEP;
@@ -1168,6 +1159,7 @@ export declare const FlowAutomationSchema: z.ZodObject<{
             pattern: z.ZodString;
             flags: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        validationMessage: z.ZodOptional<z.ZodString>;
         options: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
     output: z.ZodArray<z.ZodObject<{
@@ -1184,6 +1176,7 @@ export declare const FlowAutomationSchema: z.ZodObject<{
             pattern: z.ZodString;
             flags: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        validationMessage: z.ZodOptional<z.ZodString>;
         options: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -1377,6 +1370,7 @@ export declare const FlowEffectSchema: z.ZodObject<{
             pattern: z.ZodString;
             flags: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        validationMessage: z.ZodOptional<z.ZodString>;
         options: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -1406,6 +1400,7 @@ export declare const FlowEventSchema: z.ZodObject<{
             pattern: z.ZodString;
             flags: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        validationMessage: z.ZodOptional<z.ZodString>;
         options: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -1479,6 +1474,7 @@ export declare const FlowPayloadFieldSchema: z.ZodObject<{
         pattern: z.ZodString;
         flags: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    validationMessage: z.ZodOptional<z.ZodString>;
     options: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 
@@ -1665,7 +1661,7 @@ export declare interface InstanceFilter {
     trackedAssetId?: string;
 }
 
-export declare type InstanceStatus = 'active' | 'completed' | 'suspended' | 'error';
+export declare type InstanceStatus = 'active' | 'completed' | 'cancelled';
 
 /** Abstraction over where instances are persisted. */
 export declare interface InstanceStore {
@@ -2022,44 +2018,6 @@ export declare const NamingTokenSchema: z.ZodEnum<{
     lbsLocation: "lbsLocation";
 }>;
 
-/** Describes what a specific actor can do from the current node of an instance. */
-export declare interface NodeConfig {
-    currentNode: {
-        id: string;
-        type: string;
-        label: string;
-    };
-    /** Transitions this actor can trigger right now. */
-    availableTransitions: {
-        edgeId: string;
-        label: string;
-        /** eventId to emit */
-        emits: string;
-        requiredPayload: {
-            key: string;
-            type: string;
-            required: boolean;
-        }[];
-    }[];
-    /** Transitions that exist but this actor cannot trigger. */
-    blockedTransitions: {
-        edgeId: string;
-        label: string;
-        reason: 'UNAUTHORIZED' | 'GUARD_UNSATISFIABLE';
-        /** What the node requires to authorize this transition. */
-        required: RaciLevel;
-    }[];
-    /** RACI assignment for the current node — resolved to roles, teams and emails. */
-    raci: {
-        responsible: RaciLevel;
-        accountable: RaciLevel;
-        consulted: RaciLevel;
-        informed: RaciLevel;
-    };
-    /** True if the current node is type "end". */
-    isTerminal: boolean;
-}
-
 export declare type NodeTimeout = z.infer<typeof NodeTimeoutSchema>;
 
 export declare const NodeTimeoutSchema: z.ZodObject<{
@@ -2282,6 +2240,9 @@ export declare class Runtime<T extends {
     readonly effects: Record<string, EffectHandler>;
     readonly automations: Record<string, AutomationHandler>;
     readonly resolvers: Record<string, ResolverHandler>;
+    /** Set by Engine.init() — available inside handlers via this.engine */
+    _engine: EngineRef | null;
+    get engine(): EngineRef;
     constructor({ env }?: RuntimeOptions);
     protected effect<K extends keyof T['effects'] & string>(key: K, handler: (instance: WorkflowInstance, ...args: Parameters<T['effects'][K]>) => Promise<void>): this;
     protected automation<K extends keyof T['automations'] & string>(key: K, handler: (instance: WorkflowInstance, ...args: Parameters<T['automations'][K]>) => Promise<ReturnType<T['automations'][K]>>): this;
@@ -2656,4 +2617,36 @@ export declare const WorkflowSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 
+/** Current state of a workflow instance — node, transitions, and RACI. Actor-independent. */
+export declare interface WorkflowStatus {
+    currentNode: {
+        id: string;
+        type: string;
+        label: string;
+    };
+    status: InstanceStatus;
+    /** All transitions available from the current node. Authorization is enforced at emit() time. */
+    transitions: {
+        edgeId: string;
+        label: string;
+        /** eventId to emit */
+        emits: string;
+        requiredPayload: {
+            key: string;
+            type: string;
+            required: boolean;
+            label?: string;
+        }[];
+    }[];
+    /** RACI assignment for the current node — resolved to roles, teams and emails. */
+    raci: {
+        responsible: RaciLevel;
+        accountable: RaciLevel;
+        consulted: RaciLevel;
+        informed: RaciLevel;
+    };
+    /** True if the current node is type "end". */
+    isTerminal: boolean;
+}
+
 export { }