@wooksjs/event-wf 0.7.7 → 0.7.9

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import * as _wooksjs_event_core from '@wooksjs/event-core';
 import { EventContextOptions, EventKindSeeds, EventContext } from '@wooksjs/event-core';
 export { EventContext, EventContextOptions, useLogger, useRouteParams } from '@wooksjs/event-core';
+import * as _prostojs_wf_outlets from '@prostojs/wf/outlets';
+import { WfStateStrategy, WfOutlet, WfOutletRequest } from '@prostojs/wf/outlets';
+export { EncapsulatedStateStrategy, HandleStateStrategy, WfOutlet, WfOutletRequest, WfOutletResult, WfState, WfStateStore, WfStateStoreMemory, WfStateStrategy, outlet, outletEmail, outletHttp } from '@prostojs/wf/outlets';
+import { TFlowOutput, Workflow, Step, TWorkflowSpy, TStepHandler, TWorkflowSchema } from '@prostojs/wf';
+export { StepRetriableError, TStepHandler, TWorkflowSchema } from '@prostojs/wf';
 import * as wooks from 'wooks';
 import { Wooks, TWooksHandler, TWooksOptions, WooksAdapterBase } from 'wooks';
 import { TConsoleBase } from '@prostojs/logger';
-import { Workflow, Step, TWorkflowSpy, TStepHandler, TWorkflowSchema, TFlowOutput } from '@prostojs/wf';
-export { StepRetriableError, TStepHandler, TWorkflowSchema } from '@prostojs/wf';
 
 /**
  * Composable that provides access to the current workflow execution state.
@@ -16,14 +19,14 @@ export { StepRetriableError, TStepHandler, TWorkflowSchema } from '@prostojs/wf'
  * const stepInput = input<MyInput>()
  * ```
  */
-declare function useWfState(): {
+declare const useWfState: _wooksjs_event_core.WookComposable<{
     ctx: <T>() => T;
     input: <I>() => I | undefined;
     schemaId: string;
     stepId: () => string | null;
     indexes: () => number[] | undefined;
     resume: boolean;
-};
+}>;
 
 declare const wfKind: _wooksjs_event_core.EventKind<{
     schemaId: _wooksjs_event_core.SlotMarker<string>;
@@ -39,6 +42,189 @@ declare function createWfContext<R>(options: EventContextOptions, seeds: EventKi
 /** Creates a WF event context for resuming a paused workflow and runs `fn` inside it. */
 declare function resumeWfContext<R>(options: EventContextOptions, seeds: EventKindSeeds<typeof wfKind>, fn: () => R): R;
 
+/**
+ * Composable for accessing outlet infrastructure from within workflow steps.
+ *
+ * Most steps don't need this — they just return `outletHttp(form)` or
+ * `outletEmail(to, template)`. This composable is for advanced cases
+ * where steps need to inspect or modify outlet state directly.
+ */
+declare const useWfOutlet: _wooksjs_event_core.WookComposable<{
+    getStateStrategy: () => _prostojs_wf_outlets.WfStateStrategy;
+    getOutlets: () => Map<string, _prostojs_wf_outlets.WfOutlet>;
+    getOutlet: (name: string) => _prostojs_wf_outlets.WfOutlet | null;
+}>;
+
+interface WfFinishedResponse {
+    type: 'redirect' | 'data';
+    /** Redirect URL or response body */
+    value: unknown;
+    /** HTTP status code (default 200 for data, 302 for redirect) */
+    status?: number;
+    /** Cookies to set */
+    cookies?: Record<string, {
+        value: string;
+        options?: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * Composable to set the completion response for a finished workflow.
+ *
+ * @example
+ * ```ts
+ * // Redirect after login
+ * useWfFinished().set({ type: 'redirect', value: '/dashboard' })
+ *
+ * // Return data
+ * useWfFinished().set({ type: 'data', value: { success: true } })
+ * ```
+ */
+declare const useWfFinished: _wooksjs_event_core.WookComposable<{
+    set: (response: WfFinishedResponse) => void;
+    get: () => WfFinishedResponse | undefined;
+}>;
+
+interface WfOutletTokenConfig {
+    /** Where to read state token from incoming request (default: `['body', 'query', 'cookie']`) */
+    read?: Array<'body' | 'query' | 'cookie'>;
+    /** Where to write state token in response (default: `'body'`) */
+    write?: 'body' | 'cookie';
+    /** Parameter name for state token (default: `'wfs'`) */
+    name?: string;
+    /**
+     * Token consumption mode per outlet. When `true`, the trigger calls
+     * `strategy.consume()` (single-use token) instead of `strategy.retrieve()`
+     * on resume. Defaults to `{ email: true }` — email magic links are consumed
+     * on first use, HTTP tokens are reusable.
+     *
+     * Can be a boolean (applies to all outlets) or a per-outlet-name map.
+     */
+    consume?: boolean | Record<string, boolean>;
+}
+interface WfOutletTriggerConfig {
+    /** Whitelist of allowed workflow IDs. If empty, all are allowed. */
+    allow?: string[];
+    /** Blacklist of workflow IDs. Checked after allow. */
+    block?: string[];
+    /** State persistence strategy */
+    state: WfStateStrategy | ((wfid: string) => WfStateStrategy);
+    /** Registered outlets */
+    outlets: WfOutlet[];
+    /** Token configuration (reading, writing, naming, consumption) */
+    token?: WfOutletTokenConfig;
+    /** Parameter name for workflow ID (default: `'wfid'`) */
+    wfidName?: string;
+    /**
+     * Initial workflow context factory. Called when starting a new workflow.
+     * Receives the parsed request body so you can seed context from the request.
+     * Default: `() => ({})` (empty context).
+     */
+    initialContext?: (body: Record<string, unknown> | undefined, wfid: string) => unknown;
+    /**
+     * Called when a workflow finishes. If provided, its return value becomes the
+     * HTTP response — overriding `useWfFinished()`. This keeps steps transport-agnostic
+     * when the completion response is always the same shape.
+     *
+     * If not provided, falls back to `useWfFinished()` or `{ finished: true }`.
+     */
+    onFinished?: (ctx: {
+        context: unknown;
+        schemaId: string;
+    }) => unknown;
+}
+interface WfOutletTriggerDeps {
+    /** Start a workflow. Provided by WooksWf or MoostWf. */
+    start: (schemaId: string, context: unknown, opts?: {
+        input?: unknown;
+        eventContext?: unknown;
+    }) => Promise<TFlowOutput<unknown, unknown, WfOutletRequest>>;
+    /** Resume a workflow. Provided by WooksWf or MoostWf. */
+    resume: (state: {
+        schemaId: string;
+        indexes: number[];
+        context: unknown;
+    }, opts?: {
+        input?: unknown;
+        eventContext?: unknown;
+    }) => Promise<TFlowOutput<unknown, unknown, WfOutletRequest>>;
+}
+
+/**
+ * Handle an HTTP request that starts or resumes a workflow.
+ *
+ * Reads wfs (state token) and wfid (workflow ID) from request body, query params,
+ * or cookies — configurable via `config.token`. On workflow pause, persists state
+ * and dispatches to the named outlet. On finish, returns the finished response.
+ *
+ * @example
+ * ```ts
+ * // In a wooks HTTP handler:
+ * app.post('/workflow', () => handleWfOutletRequest(config, deps))
+ *
+ * // Better — use createOutletHandler():
+ * const handle = createOutletHandler(wfApp)
+ * app.post('/workflow', () => handle(config))
+ * ```
+ */
+declare function handleWfOutletRequest(config: WfOutletTriggerConfig, deps: WfOutletTriggerDeps): Promise<unknown>;
+
+/**
+ * Creates an HTTP outlet that passes through the outlet payload as
+ * the HTTP response body. This is the most common outlet — it returns
+ * forms, prompts, or data to the client.
+ *
+ * @example
+ * ```ts
+ * const httpOutlet = createHttpOutlet()
+ * // Step does: return outletHttp({ fields: ['email', 'password'] })
+ * // Client receives: { fields: ['email', 'password'] }
+ * ```
+ */
+declare function createHttpOutlet(opts?: {
+    /** Transform the payload before returning to client */
+    transform?: (payload: unknown, context?: Record<string, unknown>) => unknown;
+}): WfOutlet;
+/**
+ * Creates an email outlet that delegates to a user-provided send function.
+ * The send function receives the target, template, context, and the state
+ * token (for embedding in magic links / verification URLs).
+ *
+ * @example
+ * ```ts
+ * const emailOutlet = createEmailOutlet(async (opts) => {
+ *   await mailer.send({
+ *     to: opts.target,
+ *     template: opts.template,
+ *     data: { ...opts.context, verifyUrl: `/verify?wfs=${opts.token}` },
+ *   })
+ * })
+ * ```
+ */
+declare function createEmailOutlet(send: (opts: {
+    target: string;
+    template: string;
+    context: Record<string, unknown>;
+    token: string;
+}) => Promise<void>): WfOutlet;
+
+/**
+ * Creates a pre-wired outlet handler from a workflow app instance.
+ * Eliminates the need to manually construct `WfOutletTriggerDeps`.
+ *
+ * Accepts any object with `start` and `resume` methods (WooksWf, MoostWf, etc.).
+ *
+ * @example
+ * ```ts
+ * const handle = createOutletHandler(wfApp)
+ * httpApp.post('/workflow', () => handle(config))
+ * ```
+ */
+declare function createOutletHandler(wfApp: {
+    start: WfOutletTriggerDeps['start'];
+    resume: WfOutletTriggerDeps['resume'];
+}): (config: WfOutletTriggerConfig) => Promise<unknown>;
+
 /** Input data for creating a workflow event context. */
 interface TWFEventInput {
     schemaId: string;
@@ -153,5 +339,5 @@ declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
  */
 declare function createWfApp<T>(opts?: TWooksWfOptions, wooks?: Wooks | WooksAdapterBase): WooksWf<T, any>;
 
-export { WooksWf, createWfApp, createWfContext, resumeKey, resumeWfContext, useWfState, wfKind, wfShortcuts };
-export type { TWFEventInput, TWfRunOptions, TWooksWfOptions };
+export { WooksWf, createEmailOutlet, createHttpOutlet, createOutletHandler, createWfApp, createWfContext, handleWfOutletRequest, resumeKey, resumeWfContext, useWfFinished, useWfOutlet, useWfState, wfKind, wfShortcuts };
+export type { TWFEventInput, TWfRunOptions, TWooksWfOptions, WfFinishedResponse, WfOutletTokenConfig, WfOutletTriggerConfig, WfOutletTriggerDeps };