@wooksjs/event-wf 0.7.7 → 0.7.9

package/dist/index.cjs

@@ -6,11 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key$1; i < n; i++) {
-		key$1 = keys[i];
-		if (!__hasOwnProp.call(to, key$1) && key$1 !== except) __defProp(to, key$1, {
-			get: ((k) => from[k]).bind(null, key$1),
-			enumerable: !(desc = __getOwnPropDesc(from, key$1)) || desc.enumerable
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key$2; i < n; i++) {
+		key$2 = keys[i];
+		if (!__hasOwnProp.call(to, key$2) && key$2 !== except) __defProp(to, key$2, {
+			get: ((k) => from[k]).bind(null, key$2),
+			enumerable: !(desc = __getOwnPropDesc(from, key$2)) || desc.enumerable
 		});
 	}
 	return to;
@@ -22,6 +22,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __wooksjs_event_core = __toESM(require("@wooksjs/event-core"));
+const __wooksjs_event_http = __toESM(require("@wooksjs/event-http"));
+const __wooksjs_http_body = __toESM(require("@wooksjs/http-body"));
+const node_crypto = __toESM(require("node:crypto"));
 const __prostojs_wf = __toESM(require("@prostojs/wf"));
 const wooks = __toESM(require("wooks"));
 
@@ -46,17 +49,14 @@ const resumeKey = (0, __wooksjs_event_core.key)("wf.resume");
 * const stepInput = input<MyInput>()
 * ```
 */
-function useWfState() {
-	const c = (0, __wooksjs_event_core.current)();
-	return {
-		ctx: () => c.get(wfKind.keys.inputContext),
-		input: () => c.get(wfKind.keys.input),
-		schemaId: c.get(wfKind.keys.schemaId),
-		stepId: () => c.get(wfKind.keys.stepId),
-		indexes: () => c.get(wfKind.keys.indexes),
-		resume: c.get(resumeKey)
-	};
-}
+const useWfState = (0, __wooksjs_event_core.defineWook)((c) => ({
+	ctx: () => c.get(wfKind.keys.inputContext),
+	input: () => c.get(wfKind.keys.input),
+	schemaId: c.get(wfKind.keys.schemaId),
+	stepId: () => c.get(wfKind.keys.stepId),
+	indexes: () => c.get(wfKind.keys.indexes),
+	resume: c.get(resumeKey)
+}));
 
 //#endregion
 //#region packages/event-wf/src/event-wf.ts
@@ -75,6 +75,446 @@ function resumeWfContext(options, seeds, fn) {
 	});
 }
 
+//#endregion
+//#region packages/event-wf/src/outlets/outlet-context.ts
+/** Registered outlet handlers, keyed by name */
+const outletsRegistryKey = (0, __wooksjs_event_core.key)("wf.outlets.registry");
+/** Active state strategy for current request */
+const stateStrategyKey = (0, __wooksjs_event_core.key)("wf.outlets.stateStrategy");
+/** Finished response set by workflow steps */
+const wfFinishedKey = (0, __wooksjs_event_core.key)("wf.outlets.finished");
+
+//#endregion
+//#region packages/event-wf/src/outlets/use-wf-outlet.ts
+/**
+* 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.
+*/
+const useWfOutlet = (0, __wooksjs_event_core.defineWook)((ctx) => ({
+	getStateStrategy: () => ctx.get(stateStrategyKey),
+	getOutlets: () => ctx.get(outletsRegistryKey),
+	getOutlet: (name) => ctx.get(outletsRegistryKey)?.get(name) ?? null
+}));
+
+//#endregion
+//#region packages/event-wf/src/outlets/use-wf-finished.ts
+/**
+* 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 } })
+* ```
+*/
+const useWfFinished = (0, __wooksjs_event_core.defineWook)((ctx) => ({
+	set: (response) => ctx.set(wfFinishedKey, response),
+	get: () => ctx.has(wfFinishedKey) ? ctx.get(wfFinishedKey) : void 0
+}));
+
+//#endregion
+//#region packages/event-wf/src/outlets/trigger.ts
+const DEFAULT_CONSUME_TOKEN = { email: true };
+/**
+* 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))
+* ```
+*/
+async function handleWfOutletRequest(config, deps) {
+	const tok = config.token ?? {};
+	const tokenName = tok.name ?? "wfs";
+	const tokenRead = tok.read ?? [
+		"body",
+		"query",
+		"cookie"
+	];
+	const tokenWrite = tok.write ?? "body";
+	const wfidName = config.wfidName ?? "wfid";
+	const ctx = (0, __wooksjs_event_core.current)();
+	const registry = new Map(config.outlets.map((o) => [o.name, o]));
+	ctx.set(outletsRegistryKey, registry);
+	ctx.set(wfFinishedKey, void 0);
+	const { parseBody } = (0, __wooksjs_http_body.useBody)();
+	const { params } = (0, __wooksjs_event_http.useUrlParams)();
+	const { getCookie } = (0, __wooksjs_event_http.useCookies)();
+	const response = (0, __wooksjs_event_http.useResponse)();
+	const body = await parseBody().catch(() => void 0);
+	const queryParams = params();
+	let token;
+	for (const source of tokenRead) {
+		if (source === "body") token = body?.[tokenName];
+		else if (source === "query") token = queryParams.get(tokenName) ?? void 0;
+		else if (source === "cookie") token = getCookie(tokenName) ?? void 0;
+		if (token) break;
+	}
+	const wfid = body?.[wfidName] ?? queryParams.get(wfidName) ?? void 0;
+	const input = body?.input;
+	const resolveStrategy = (id) => typeof config.state === "function" ? config.state(id) : config.state;
+	const shouldConsume = (outletName) => {
+		if (typeof tok.consume === "boolean") return tok.consume;
+		return (tok.consume ?? DEFAULT_CONSUME_TOKEN)[outletName] ?? false;
+	};
+	let output;
+	if (token) {
+		const strategy = resolveStrategy(wfid ?? "");
+		ctx.set(stateStrategyKey, strategy);
+		const state = await strategy.retrieve(token);
+		if (!state) return {
+			error: "Invalid or expired workflow state",
+			status: 400
+		};
+		if (state.schemaId !== (wfid ?? "")) {
+			const realStrategy = resolveStrategy(state.schemaId);
+			ctx.set(stateStrategyKey, realStrategy);
+		}
+		const outletName = state.meta?.outlet;
+		if (outletName && shouldConsume(outletName)) await strategy.consume(token);
+		output = await deps.resume(state, {
+			input,
+			eventContext: ctx
+		});
+	} else if (wfid) {
+		if (config.allow?.length && !config.allow.includes(wfid)) return {
+			error: `Workflow '${wfid}' is not allowed`,
+			status: 403
+		};
+		if (config.block?.includes(wfid)) return {
+			error: `Workflow '${wfid}' is blocked`,
+			status: 403
+		};
+		const strategy = resolveStrategy(wfid);
+		ctx.set(stateStrategyKey, strategy);
+		const initialContext = config.initialContext ? config.initialContext(body, wfid) : {};
+		output = await deps.start(wfid, initialContext, {
+			input,
+			eventContext: ctx
+		});
+	} else return {
+		error: "Missing wfs (state token) or wfid (workflow ID)",
+		status: 400
+	};
+	if (output.finished) {
+		if (config.onFinished) return config.onFinished({
+			context: output.state.context,
+			schemaId: output.state.schemaId
+		});
+		const finished = ctx.get(wfFinishedKey);
+		if (finished?.cookies) for (const [name, cookie] of Object.entries(finished.cookies)) response.setCookie(name, cookie.value, cookie.options);
+		if (finished?.type === "redirect") {
+			response.setHeader("location", finished.value);
+			return { status: finished.status ?? 302 };
+		}
+		if (finished) return finished.value;
+		return { finished: true };
+	}
+	if (output.inputRequired) {
+		const outletReq = output.inputRequired;
+		const outletHandler = registry.get(outletReq.outlet);
+		if (!outletHandler) return {
+			error: `Unknown outlet: '${outletReq.outlet}'`,
+			status: 500
+		};
+		const strategy = ctx.get(stateStrategyKey);
+		const stateWithMeta = {
+			...output.state,
+			meta: { outlet: outletReq.outlet }
+		};
+		const newToken = await strategy.persist(stateWithMeta, output.expires ? { ttl: output.expires - Date.now() } : void 0);
+		if (tokenWrite === "cookie") response.setCookie(tokenName, newToken, {
+			httpOnly: true,
+			sameSite: "Strict",
+			path: "/"
+		});
+		const result = await outletHandler.deliver(outletReq, newToken);
+		if (tokenWrite === "body" && result?.response && typeof result.response === "object") return {
+			...result.response,
+			[tokenName]: newToken
+		};
+		return result?.response ?? { waiting: true };
+	}
+	if (output.error) return {
+		error: output.error.message,
+		errorList: output.errorList
+	};
+	return { error: "Unexpected workflow state" };
+}
+
+//#endregion
+//#region packages/event-wf/src/outlets/create-outlet.ts
+/**
+* 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'] }
+* ```
+*/
+function createHttpOutlet(opts) {
+	return {
+		name: "http",
+		async deliver(request, _token) {
+			const body = opts?.transform ? opts.transform(request.payload, request.context) : typeof request.payload === "object" && request.payload !== null ? {
+				...request.payload,
+				...request.context
+			} : request.payload;
+			return { response: body };
+		}
+	};
+}
+/**
+* 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}` },
+*   })
+* })
+* ```
+*/
+function createEmailOutlet(send) {
+	return {
+		name: "email",
+		async deliver(request, token) {
+			await send({
+				target: request.target ?? "",
+				template: request.template ?? "",
+				context: request.context ?? {},
+				token
+			});
+			return { response: {
+				sent: true,
+				outlet: "email"
+			} };
+		}
+	};
+}
+
+//#endregion
+//#region packages/event-wf/src/outlets/create-handler.ts
+/**
+* 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))
+* ```
+*/
+function createOutletHandler(wfApp) {
+	return (config) => handleWfOutletRequest(config, {
+		start: (schemaId, context, opts) => wfApp.start(schemaId, context, opts),
+		resume: (state, opts) => wfApp.resume(state, opts)
+	});
+}
+
+//#endregion
+//#region node_modules/.pnpm/@prostojs+wf@0.1.1/node_modules/@prostojs/wf/dist/outlets/index.mjs
+/**
+* Generic outlet request. Use for custom outlets.
+*
+* @example
+* return outlet('pending-task', {
+*   payload: ApprovalForm,
+*   target: managerId,
+*   context: { orderId, amount },
+* })
+*/
+function outlet(name, data) {
+	return { inputRequired: {
+		outlet: name,
+		...data
+	} };
+}
+/**
+* Pause for HTTP form input. The outlet returns the payload (form definition)
+* and state token in the HTTP response.
+*
+* @example
+* return outletHttp(LoginForm)
+* return outletHttp(LoginForm, { error: 'Invalid credentials' })
+*/
+function outletHttp(payload, context) {
+	return outlet("http", {
+		payload,
+		context
+	});
+}
+/**
+* Pause and send email with a magic link containing the state token.
+*
+* @example
+* return outletEmail('user@test.com', 'invite', { name: 'Alice' })
+*/
+function outletEmail(target, template, context) {
+	return outlet("email", {
+		target,
+		template,
+		context
+	});
+}
+/**
+* Self-contained AES-256-GCM encrypted state strategy.
+*
+* Workflow state is encrypted into a base64url token that travels with the
+* transport (cookie, URL param, hidden field). No server-side storage needed.
+*
+* Token format: `base64url(iv[12] + authTag[16] + ciphertext)`
+*
+* @example
+* const strategy = new EncapsulatedStateStrategy({
+*     secret: crypto.randomBytes(32),
+*     defaultTtl: 3600_000, // 1 hour
+* });
+* const token = await strategy.persist(state);
+* const recovered = await strategy.retrieve(token);
+*/
+var EncapsulatedStateStrategy = class {
+	/** @throws if secret is not exactly 32 bytes */
+	constructor(config) {
+		this.config = config;
+		this.key = typeof config.secret === "string" ? Buffer.from(config.secret, "hex") : config.secret;
+		if (this.key.length !== 32) throw new Error("EncapsulatedStateStrategy: secret must be exactly 32 bytes");
+	}
+	/**
+	* Encrypt workflow state into a self-contained token.
+	* @param state — workflow state to persist
+	* @param options.ttl — time-to-live in ms (overrides defaultTtl)
+	* @returns base64url-encoded encrypted token
+	*/
+	async persist(state, options) {
+		const ttl = options?.ttl ?? this.config.defaultTtl ?? 0;
+		const exp = ttl > 0 ? Date.now() + ttl : 0;
+		const payload = JSON.stringify({
+			s: state,
+			e: exp
+		});
+		const iv = (0, node_crypto.randomBytes)(12);
+		const cipher = (0, node_crypto.createCipheriv)("aes-256-gcm", this.key, iv);
+		const encrypted = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+		const tag = cipher.getAuthTag();
+		return Buffer.concat([
+			iv,
+			tag,
+			encrypted
+		]).toString("base64url");
+	}
+	/** Decrypt and return workflow state. Returns null if token is invalid, expired, or tampered. */
+	async retrieve(token) {
+		return this.decrypt(token);
+	}
+	/** Same as retrieve (stateless — cannot truly invalidate a token). */
+	async consume(token) {
+		return this.decrypt(token);
+	}
+	decrypt(token) {
+		try {
+			const buf = Buffer.from(token, "base64url");
+			if (buf.length < 28) return null;
+			const iv = buf.subarray(0, 12);
+			const tag = buf.subarray(12, 28);
+			const ciphertext = buf.subarray(28);
+			const decipher = (0, node_crypto.createDecipheriv)("aes-256-gcm", this.key, iv);
+			decipher.setAuthTag(tag);
+			const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+			const { s: state, e: exp } = JSON.parse(decrypted.toString("utf8"));
+			if (exp > 0 && Date.now() > exp) return null;
+			return state;
+		} catch {
+			return null;
+		}
+	}
+};
+var HandleStateStrategy = class {
+	constructor(config) {
+		this.config = config;
+	}
+	async persist(state, options) {
+		const handle = (this.config.generateHandle ?? node_crypto.randomUUID)();
+		const ttl = options?.ttl ?? this.config.defaultTtl ?? 0;
+		const expiresAt = ttl > 0 ? Date.now() + ttl : void 0;
+		await this.config.store.set(handle, state, expiresAt);
+		return handle;
+	}
+	async retrieve(token) {
+		return (await this.config.store.get(token))?.state ?? null;
+	}
+	async consume(token) {
+		return (await this.config.store.getAndDelete(token))?.state ?? null;
+	}
+};
+/**
+* In-memory state store for development and testing.
+* State is lost on process restart.
+*/
+var WfStateStoreMemory = class {
+	constructor() {
+		this.store = /* @__PURE__ */ new Map();
+	}
+	async set(handle, state, expiresAt) {
+		this.store.set(handle, {
+			state,
+			expiresAt
+		});
+	}
+	async get(handle) {
+		const entry = this.store.get(handle);
+		if (!entry) return null;
+		if (entry.expiresAt && Date.now() > entry.expiresAt) {
+			this.store.delete(handle);
+			return null;
+		}
+		return entry;
+	}
+	async delete(handle) {
+		this.store.delete(handle);
+	}
+	async getAndDelete(handle) {
+		const entry = await this.get(handle);
+		if (entry) this.store.delete(handle);
+		return entry;
+	}
+	async cleanup() {
+		const now = Date.now();
+		let count = 0;
+		for (const [handle, entry] of this.store) if (entry.expiresAt && now > entry.expiresAt) {
+			this.store.delete(handle);
+			count++;
+		}
+		return count;
+	}
+};
+
 //#endregion
 //#region packages/event-wf/src/workflow.ts
 /** Workflow engine that resolves steps via Wooks router lookup. */
@@ -267,15 +707,25 @@ function createWfApp(opts, wooks$1) {
 }
 
 //#endregion
+exports.EncapsulatedStateStrategy = EncapsulatedStateStrategy;
+exports.HandleStateStrategy = HandleStateStrategy;
 Object.defineProperty(exports, 'StepRetriableError', {
   enumerable: true,
   get: function () {
     return __prostojs_wf.StepRetriableError;
   }
 });
+exports.WfStateStoreMemory = WfStateStoreMemory;
 exports.WooksWf = WooksWf;
+exports.createEmailOutlet = createEmailOutlet;
+exports.createHttpOutlet = createHttpOutlet;
+exports.createOutletHandler = createOutletHandler;
 exports.createWfApp = createWfApp;
 exports.createWfContext = createWfContext;
+exports.handleWfOutletRequest = handleWfOutletRequest;
+exports.outlet = outlet;
+exports.outletEmail = outletEmail;
+exports.outletHttp = outletHttp;
 exports.resumeKey = resumeKey;
 exports.resumeWfContext = resumeWfContext;
 Object.defineProperty(exports, 'useLogger', {
@@ -290,6 +740,8 @@ Object.defineProperty(exports, 'useRouteParams', {
     return __wooksjs_event_core.useRouteParams;
   }
 });
+exports.useWfFinished = useWfFinished;
+exports.useWfOutlet = useWfOutlet;
 exports.useWfState = useWfState;
 exports.wfKind = wfKind;
 exports.wfShortcuts = wfShortcuts;