@veloxts/router 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/router
 
+## 0.8.1
+
+### Patch Changes
+
+- feat: add business logic primitives for B2B SaaS apps
+- Updated dependencies
+  - @veloxts/core@0.8.1
+  - @veloxts/validation@0.8.1
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -39,14 +39,16 @@
  */
 /** Router package version */
 export declare const ROUTER_VERSION: string;
-export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
+export type { AfterHandler, CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureErrors, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, PolicyActionLike, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, TransactionalOptions, } from './types.js';
 export { PROCEDURE_METHOD_MAP, } from './types.js';
 export type { GuardErrorResponse, RouterErrorCode } from './errors.js';
 export { GuardError, isGuardError } from './errors.js';
 export type { DefineProceduresOptions, } from './procedure/builder.js';
 export { defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, } from './procedure/builder.js';
+export type { PipelineStep, RevertAction, StepOptions } from './procedure/pipeline.js';
+export { defineRevert, defineStep } from './procedure/pipeline.js';
 export { createProcedure, typedProcedure } from './procedure/factory.js';
-export type { BuilderRuntimeState, InferOutputSchema, InferProcedures, InferSchemaOutput, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidOutputSchema, ValidSchema, } from './procedure/types.js';
+export type { BuilderRuntimeState, InferOutputSchema, InferProcedures, InferSchemaOutput, PostHandlerBuilder, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidOutputSchema, ValidSchema, } from './procedure/types.js';
 export type { RouterResult } from './router-utils.js';
 export { createRouter, toRouter } from './router-utils.js';
 export type { NamingWarning, NamingWarningType, WarningConfig, WarningOption } from './warnings.js';

package/dist/index.js

@@ -51,6 +51,7 @@ export {
 // Builder functions
 defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, // Short alias for defineProcedures
  } from './procedure/builder.js';
+export { defineRevert, defineStep } from './procedure/pipeline.js';
 // ============================================================================
 // Router Utilities
 // ============================================================================

package/dist/procedure/builder.d.ts

@@ -41,7 +41,7 @@ import type { InferProcedures, ProcedureBuilder, ProcedureDefinitions } from './
  *   });
  * ```
  */
-export declare function procedure<TContext extends BaseContext = BaseContext>(): ProcedureBuilder<unknown, unknown, TContext>;
+export declare function procedure<TContext extends BaseContext = BaseContext>(): ProcedureBuilder<unknown, unknown, TContext, never>;
 /**
  * Options for defining a procedure collection
  */

package/dist/procedure/builder.js

@@ -7,12 +7,14 @@
  *
  * @module procedure/builder
  */
-import { ConfigurationError, logWarning } from '@veloxts/core';
+import { ConfigurationError, createLogger, ForbiddenError, logWarning, } from '@veloxts/core';
 import { GuardError } from '../errors.js';
 import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
 import { isResourceSchema, isTaggedResourceSchema, Resource, } from '../resource/index.js';
 import { deriveParentParamName } from '../utils/pluralization.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
+import { executeExternalSteps, executePipeline, splitPipelineSteps } from './pipeline-executor.js';
+const log = createLogger('router');
 // ============================================================================
 // Builder Factory
 // ============================================================================
@@ -158,6 +160,24 @@ function createBuilder(state) {
                 guards: [...state.guards, ...guardDefs],
             });
         },
+        /**
+         * Adds a policy action check to the procedure
+         */
+        policy(action) {
+            return createBuilder({
+                ...state,
+                policyAction: action,
+            });
+        },
+        /**
+         * Declares domain error classes this procedure may throw
+         */
+        throws(...errorClasses) {
+            return createBuilder({
+                ...state,
+                errorClasses: [...(state.errorClasses ?? []), ...errorClasses],
+            });
+        },
         /**
          * Sets REST route override
          */
@@ -213,6 +233,37 @@ function createBuilder(state) {
                 parentResources: parentConfigs,
             });
         },
+        /**
+         * Declares a domain event to emit after successful handler execution
+         */
+        emits(eventClass, mapper) {
+            // Cast is safe: the typed TEventData and TOutput are erased at runtime.
+            // BuilderRuntimeState stores the widened types for uniform handling.
+            const entry = { eventClass, mapper };
+            return createBuilder({
+                ...state,
+                emittedEvents: [...(state.emittedEvents ?? []), entry],
+            });
+        },
+        /**
+         * Wraps the handler in a database transaction
+         */
+        transactional(options) {
+            return createBuilder({
+                ...state,
+                transactional: true,
+                transactionalOptions: options,
+            });
+        },
+        /**
+         * Adds pipeline steps that execute before the handler
+         */
+        through(...steps) {
+            return createBuilder({
+                ...state,
+                pipelineSteps: [...(state.pipelineSteps ?? []), ...steps],
+            });
+        },
         /**
          * Finalizes as a query procedure
          *
@@ -278,8 +329,8 @@ function compileProcedure(type, handler, state) {
     // Pre-compile the middleware chain executor if middlewares exist
     // This avoids rebuilding the chain on every request
     const precompiledExecutor = typedMiddlewares.length > 0 ? createMiddlewareExecutor(typedMiddlewares, handler) : undefined;
-    // Create the final procedure object
-    return {
+    // Create the final procedure object with .useAfter() support
+    return createPostHandlerBuilder({
         type,
         handler,
         inputSchema: state.inputSchema,
@@ -298,7 +349,18 @@ function compileProcedure(type, handler, state) {
         _resourceSchema: state.resourceSchema,
         // Store explicit resource level from tagged schema (e.g., UserSchema.authenticated)
         _resourceLevel: state.resourceLevel,
-    };
+        // Store error classes declared via .throws()
+        errorClasses: state.errorClasses,
+        // Store transactional configuration
+        transactional: state.transactional,
+        transactionalOptions: state.transactionalOptions,
+        // Store emitted events declared via .emits()
+        emittedEvents: state.emittedEvents,
+        // Store pipeline steps declared via .through()
+        pipelineSteps: state.pipelineSteps,
+        // Store policy action declared via .policy()
+        policyAction: state.policyAction,
+    });
 }
 /**
  * Compiles a Level 3 branched procedure with a handler map
@@ -310,7 +372,7 @@ function compileProcedure(type, handler, state) {
  */
 function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state) {
     const typedMiddlewares = state.middlewares;
-    return {
+    return createPostHandlerBuilder({
         type,
         handler: dispatchHandler,
         inputSchema: state.inputSchema,
@@ -327,6 +389,45 @@ function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state
         _resourceSchema: state.resourceSchema,
         _resourceLevel: undefined, // No fixed level — determined at runtime by branch selection
         _handlerMap: handlerMap,
+        // Store error classes declared via .throws()
+        errorClasses: state.errorClasses,
+        // Store transactional configuration
+        transactional: state.transactional,
+        transactionalOptions: state.transactionalOptions,
+        // Store pipeline steps declared via .through()
+        pipelineSteps: state.pipelineSteps,
+        // Store policy action declared via .policy()
+        policyAction: state.policyAction,
+    });
+}
+// ============================================================================
+// PostHandlerBuilder Factory
+// ============================================================================
+/**
+ * Creates a PostHandlerBuilder from a CompiledProcedure's fields
+ *
+ * Wraps a compiled procedure object with a `.useAfter()` method that
+ * appends after-handler hooks. Each call returns a new PostHandlerBuilder
+ * with the hook added, preserving immutability.
+ *
+ * The resulting object passes `isCompiledProcedure` because it retains
+ * all required fields (type, handler, middlewares, guards).
+ *
+ * @internal
+ */
+function createPostHandlerBuilder(compiled) {
+    return {
+        ...compiled,
+        useAfter(handler) {
+            const afterHandlers = [
+                ...(compiled.afterHandlers ?? []),
+                handler,
+            ];
+            return createPostHandlerBuilder({
+                ...compiled,
+                afterHandlers,
+            });
+        },
     };
 }
 /**
@@ -510,25 +611,101 @@ export async function executeProcedure(procedure, rawInput, ctx) {
     const input = procedure.inputSchema
         ? procedure.inputSchema.parse(rawInput)
         : rawInput;
+    // Step 2.3: Policy check — if .policy() was used
+    if (procedure.policyAction) {
+        const ctxRecord = ctxWithLevel;
+        const user = ctxRecord.user;
+        if (user == null) {
+            throw new ForbiddenError('Policy check failed: no authenticated user');
+        }
+        const resourceNameRaw = procedure.policyAction.resourceName;
+        const resourceName = resourceNameRaw.charAt(0).toLowerCase() + resourceNameRaw.slice(1);
+        const policyResource = ctxRecord[resourceName];
+        const allowed = await procedure.policyAction.check(user, policyResource);
+        if (!allowed) {
+            throw new ForbiddenError(`Policy check failed: cannot ${procedure.policyAction.actionName} ${procedure.policyAction.resourceName}`);
+        }
+    }
     // Step 2.5: Level 3 branch selection — if handler map is present
     if (procedure._handlerMap) {
         return executeBranchedProcedure(procedure, input, ctxWithLevel);
     }
+    // Step 2.7: Execute pipeline steps if .through() was used
+    // Pipeline transforms input before the handler. Runs inside transaction when applicable.
+    const pipelineSteps = procedure.pipelineSteps;
+    const hasPipeline = pipelineSteps !== undefined && pipelineSteps.length > 0;
     // Step 3: Execute handler (with or without middleware)
+    // Helper that runs a given set of pipeline steps + middleware chain + handler
+    const executeWithSteps = async (steps, execCtx) => {
+        const hasSteps = steps !== undefined && steps.length > 0;
+        // Run pipeline to transform input before handler
+        const handlerInput = hasSteps
+            ? (await executePipeline(steps, input, execCtx))
+            : input;
+        enrichedInput = handlerInput;
+        if (procedure._precompiledExecutor) {
+            // PERFORMANCE: Use pre-compiled middleware chain executor
+            return procedure._precompiledExecutor(handlerInput, execCtx);
+        }
+        if (procedure.middlewares.length === 0) {
+            // No middleware - execute handler directly
+            return procedure.handler({ input: handlerInput, ctx: execCtx });
+        }
+        // Fallback: Build middleware chain dynamically (should not normally happen)
+        return executeMiddlewareChain(procedure.middlewares, handlerInput, execCtx, async () => procedure.handler({ input: handlerInput, ctx: execCtx }));
+    };
     let result;
-    if (procedure._precompiledExecutor) {
-        // PERFORMANCE: Use pre-compiled middleware chain executor
-        result = await procedure._precompiledExecutor(input, ctxWithLevel);
-    }
-    else if (procedure.middlewares.length === 0) {
-        // No middleware - execute handler directly
-        result = await procedure.handler({ input, ctx: ctxWithLevel });
+    let enrichedInput = input;
+    // Wrap in transaction if .transactional() was called and ctx.db.$transaction exists
+    const ctxRecord = ctxWithLevel;
+    const db = ctxRecord.db;
+    const isTransactional = procedure.transactional && db && typeof db.$transaction === 'function';
+    if (isTransactional) {
+        const $transaction = db.$transaction;
+        if (hasPipeline) {
+            // Two-phase model: split steps into DB (inside tx) and external (after commit)
+            const { dbSteps, externalSteps } = splitPipelineSteps(pipelineSteps);
+            // Phase A: Run DB steps + handler inside transaction
+            result = await $transaction(async (tx) => {
+                const txCtx = { ...ctxWithLevel, db: tx };
+                return executeWithSteps(dbSteps.length > 0 ? dbSteps : undefined, txCtx);
+            }, procedure.transactionalOptions);
+            // Phase B: Run external steps after commit (outside transaction)
+            if (externalSteps.length > 0) {
+                await executeExternalSteps(externalSteps, input, ctxWithLevel);
+            }
+        }
+        else {
+            // Transactional, no pipeline — wrap handler in $transaction (current behavior)
+            result = await $transaction(async (tx) => {
+                const txCtx = { ...ctxWithLevel, db: tx };
+                return executeWithSteps(undefined, txCtx);
+            }, procedure.transactionalOptions);
+        }
     }
     else {
-        // Fallback: Build middleware chain dynamically (should not normally happen)
-        result = await executeMiddlewareChain(procedure.middlewares, input, ctxWithLevel, async () => procedure.handler({ input, ctx: ctxWithLevel }));
+        // Not transactional — run all steps in declaration order (regardless of external flag)
+        result = await executeWithSteps(hasPipeline ? pipelineSteps : undefined, ctxWithLevel);
     }
-    // Step 4: Auto-project if resource schema is set
+    // Step 4: Emit domain events if .emits() was used
+    if (procedure.emittedEvents) {
+        const ctxEvents = ctxRecord
+            .events;
+        if (ctxEvents?.emit) {
+            for (const { eventClass, mapper } of procedure.emittedEvents) {
+                try {
+                    const eventData = mapper
+                        ? mapper(result)
+                        : result;
+                    await ctxEvents.emit(new eventClass(eventData));
+                }
+                catch (error) {
+                    log.error('Event emission error:', error);
+                }
+            }
+        }
+    }
+    // Step 5: Auto-project if resource schema is set
     if (procedure._resourceSchema) {
         const schema = procedure._resourceSchema;
         // Prefer explicit level from tagged schema over guard-derived level
@@ -543,10 +720,22 @@ export async function executeProcedure(procedure, rawInput, ctx) {
             result = projectOne(result);
         }
     }
-    // Step 5: Validate output if schema provided
+    // Step 6: Validate output if schema provided
     if (procedure.outputSchema) {
-        return procedure.outputSchema.parse(result);
+        result = procedure.outputSchema.parse(result);
+    }
+    // Step 7: Execute after-handler hooks if .useAfter() was used
+    if (procedure.afterHandlers?.length) {
+        for (const afterHandler of procedure.afterHandlers) {
+            try {
+                await afterHandler({ input: enrichedInput, result, ctx: ctxWithLevel });
+            }
+            catch (error) {
+                log.error('useAfter hook error:', error);
+            }
+        }
     }
+    // Return the ORIGINAL result (hooks cannot modify it)
     return result;
 }
 // ============================================================================

package/dist/procedure/pipeline-executor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pipeline executor for .through() steps
+ *
+ * Executes pipeline steps in declaration order. Each step's output becomes
+ * the next step's input. On failure, runs revert actions for completed
+ * steps in reverse order (compensation pattern).
+ *
+ * When `.transactional()` is combined with `.through()`, the executor
+ * implements a two-phase model:
+ * - Phase A: DB steps (non-external) run inside the transaction
+ * - Phase B: External steps run after the transaction commits
+ *
+ * @module procedure/pipeline-executor
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { PipelineStep } from './pipeline.js';
+/**
+ * Result of splitting pipeline steps into DB and external phases
+ */
+export interface SplitPipelineSteps {
+    /** Steps that run inside the DB transaction (external === false) */
+    readonly dbSteps: ReadonlyArray<PipelineStep>;
+    /** Steps that run after transaction commit (external === true) */
+    readonly externalSteps: ReadonlyArray<PipelineStep>;
+}
+/**
+ * Splits pipeline steps into DB (non-external) and external phases
+ *
+ * Validates the ordering constraint: when transactional, all external steps
+ * must come AFTER all DB steps. If an external step appears before a DB step,
+ * a ConfigurationError is thrown.
+ *
+ * @param steps - Pipeline steps to split
+ * @returns Object with `dbSteps` and `externalSteps` arrays
+ * @throws ConfigurationError if an external step precedes a DB step
+ */
+export declare function splitPipelineSteps(steps: ReadonlyArray<PipelineStep>): SplitPipelineSteps;
+/**
+ * Executes a sequence of pipeline steps
+ *
+ * Steps run in declaration order. Each step receives the previous step's
+ * output as its input (the first step receives the original validated input).
+ *
+ * If a step fails:
+ * 1. Collects all completed steps that have a revertAction
+ * 2. Runs their revert handlers in REVERSE order
+ * 3. Each revert receives the output of the step being reverted
+ * 4. Revert errors are logged but do not suppress the original error
+ * 5. Rethrows the original error
+ *
+ * @param steps - Pipeline steps to execute in order
+ * @param input - Initial input (typically the validated procedure input)
+ * @param ctx - Request context
+ * @returns The output of the last step
+ */
+export declare function executePipeline(steps: ReadonlyArray<PipelineStep>, input: unknown, ctx: BaseContext): Promise<unknown>;
+/**
+ * Executes external pipeline steps after a transaction has committed
+ *
+ * External steps run in declaration order. If a step fails, revert actions
+ * are run for all previously completed EXTERNAL steps in reverse order.
+ * The DB transaction is already committed — DB changes persist.
+ *
+ * @param steps - External pipeline steps to execute in order
+ * @param input - Input for the first external step (output of last DB step, or original input)
+ * @param ctx - Request context (with the ORIGINAL db, not the transactional client)
+ * @returns The output of the last external step (ignored by the caller, since handler already ran)
+ */
+export declare function executeExternalSteps(steps: ReadonlyArray<PipelineStep>, input: unknown, ctx: BaseContext): Promise<void>;

package/dist/procedure/pipeline-executor.js

@@ -0,0 +1,134 @@
+/**
+ * Pipeline executor for .through() steps
+ *
+ * Executes pipeline steps in declaration order. Each step's output becomes
+ * the next step's input. On failure, runs revert actions for completed
+ * steps in reverse order (compensation pattern).
+ *
+ * When `.transactional()` is combined with `.through()`, the executor
+ * implements a two-phase model:
+ * - Phase A: DB steps (non-external) run inside the transaction
+ * - Phase B: External steps run after the transaction commits
+ *
+ * @module procedure/pipeline-executor
+ */
+import { ConfigurationError, createLogger } from '@veloxts/core';
+const log = createLogger('router');
+/**
+ * Splits pipeline steps into DB (non-external) and external phases
+ *
+ * Validates the ordering constraint: when transactional, all external steps
+ * must come AFTER all DB steps. If an external step appears before a DB step,
+ * a ConfigurationError is thrown.
+ *
+ * @param steps - Pipeline steps to split
+ * @returns Object with `dbSteps` and `externalSteps` arrays
+ * @throws ConfigurationError if an external step precedes a DB step
+ */
+export function splitPipelineSteps(steps) {
+    const dbSteps = [];
+    const externalSteps = [];
+    let seenExternal = false;
+    for (const step of steps) {
+        if (step.external) {
+            seenExternal = true;
+            externalSteps.push(step);
+        }
+        else {
+            if (seenExternal) {
+                throw new ConfigurationError(`Pipeline step "${step.name}" (DB) is declared after external step "${externalSteps[externalSteps.length - 1].name}". ` +
+                    'When using .transactional(), all external steps must come after all DB steps in the .through() declaration.');
+            }
+            dbSteps.push(step);
+        }
+    }
+    return { dbSteps, externalSteps };
+}
+/**
+ * Executes a sequence of pipeline steps
+ *
+ * Steps run in declaration order. Each step receives the previous step's
+ * output as its input (the first step receives the original validated input).
+ *
+ * If a step fails:
+ * 1. Collects all completed steps that have a revertAction
+ * 2. Runs their revert handlers in REVERSE order
+ * 3. Each revert receives the output of the step being reverted
+ * 4. Revert errors are logged but do not suppress the original error
+ * 5. Rethrows the original error
+ *
+ * @param steps - Pipeline steps to execute in order
+ * @param input - Initial input (typically the validated procedure input)
+ * @param ctx - Request context
+ * @returns The output of the last step
+ */
+export async function executePipeline(steps, input, ctx) {
+    const completedSteps = [];
+    let currentInput = input;
+    for (const step of steps) {
+        try {
+            const output = await step.handler({ input: currentInput, ctx });
+            completedSteps.push({ step, output });
+            currentInput = output;
+        }
+        catch (error) {
+            // Step failed — run reverts for completed steps in reverse order
+            await runReverts(completedSteps, ctx);
+            throw error;
+        }
+    }
+    return currentInput;
+}
+/**
+ * Executes external pipeline steps after a transaction has committed
+ *
+ * External steps run in declaration order. If a step fails, revert actions
+ * are run for all previously completed EXTERNAL steps in reverse order.
+ * The DB transaction is already committed — DB changes persist.
+ *
+ * @param steps - External pipeline steps to execute in order
+ * @param input - Input for the first external step (output of last DB step, or original input)
+ * @param ctx - Request context (with the ORIGINAL db, not the transactional client)
+ * @returns The output of the last external step (ignored by the caller, since handler already ran)
+ */
+export async function executeExternalSteps(steps, input, ctx) {
+    const completedSteps = [];
+    let currentInput = input;
+    for (const step of steps) {
+        try {
+            const output = await step.handler({ input: currentInput, ctx });
+            completedSteps.push({ step, output });
+            currentInput = output;
+        }
+        catch (error) {
+            // External step failed — revert only completed external steps
+            await runReverts(completedSteps, ctx);
+            throw error;
+        }
+    }
+}
+/**
+ * Runs revert actions for completed steps in reverse order
+ *
+ * Each revert receives the output of the step it is reverting.
+ * Revert errors are logged but never suppress the original error.
+ *
+ * @param completedSteps - Steps that completed successfully before the failure
+ * @param ctx - Request context (forwarded to revert handlers)
+ * @internal
+ */
+async function runReverts(completedSteps, ctx) {
+    // Process in reverse order
+    for (let i = completedSteps.length - 1; i >= 0; i--) {
+        const { step, output } = completedSteps[i];
+        if (!step.revertAction) {
+            continue;
+        }
+        try {
+            await step.revertAction.handler({ input: output, ctx });
+        }
+        catch (revertError) {
+            log.error(`Revert "${step.revertAction.name}" for step "${step.name}" failed:`, revertError);
+        }
+    }
+}

package/dist/procedure/pipeline.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pipeline step and revert action factories
+ *
+ * Provides `defineStep` and `defineRevert` for building pipeline steps
+ * that execute in sequence via `.through()` on the procedure builder.
+ * Each step's output becomes the next step's input. External steps run
+ * outside DB transactions and can have revert actions for compensation.
+ *
+ * @module procedure/pipeline
+ */
+import type { BaseContext } from '@veloxts/core';
+/**
+ * Options for configuring a pipeline step
+ */
+export interface StepOptions {
+    /** Step name used for logging and error reporting */
+    readonly name: string;
+    /** Whether this step runs outside the DB transaction (default: false) */
+    readonly external?: boolean;
+}
+/**
+ * A revert action that undoes the effect of an external step
+ *
+ * Revert actions are invoked when a later step in the pipeline fails,
+ * allowing compensation for steps that ran outside the DB transaction.
+ */
+export interface RevertAction<TInput = unknown> {
+    readonly name: string;
+    readonly handler: (params: {
+        input: TInput;
+        ctx: BaseContext;
+    }) => void | Promise<void>;
+}
+/**
+ * A single step in a procedure pipeline
+ *
+ * Steps execute in order, each one's output becoming the next one's input.
+ * External steps run outside DB transactions and may have revert actions
+ * for compensation when a later step fails.
+ */
+export interface PipelineStep<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly external: boolean;
+    readonly handler: (params: {
+        input: TInput;
+        ctx: BaseContext;
+    }) => TOutput | Promise<TOutput>;
+    readonly revertAction?: RevertAction;
+    /** Attach a revert action to this step, returning a new step (immutable) */
+    onRevert(revert: RevertAction): PipelineStep<TInput, TOutput>;
+}
+/** Handler function signature for pipeline steps */
+type StepHandler<TInput, TOutput> = (params: {
+    input: TInput;
+    ctx: BaseContext;
+}) => TOutput | Promise<TOutput>;
+/**
+ * Define a pipeline step with a string name (external defaults to false)
+ *
+ * @example
+ * ```typescript
+ * const validate = defineStep('validateInventory', async ({ input, ctx }) => {
+ *   return { ...input, validated: true };
+ * });
+ * ```
+ */
+export declare function defineStep<TInput = unknown, TOutput = unknown>(name: string, handler: StepHandler<TInput, TOutput>): PipelineStep<TInput, TOutput>;
+/**
+ * Define a pipeline step with options (name + external flag)
+ *
+ * @example
+ * ```typescript
+ * const charge = defineStep(
+ *   { name: 'chargePayment', external: true },
+ *   async ({ input, ctx }) => {
+ *     return { ...input, chargeId: 'ch_123' };
+ *   },
+ * );
+ * ```
+ */
+export declare function defineStep<TInput = unknown, TOutput = unknown>(options: StepOptions, handler: StepHandler<TInput, TOutput>): PipelineStep<TInput, TOutput>;
+/**
+ * Define a revert action for compensating an external pipeline step
+ *
+ * Revert handlers receive the same `{ input, ctx }` shape but return void.
+ *
+ * @example
+ * ```typescript
+ * const refund = defineRevert('refundPayment', async ({ input, ctx }) => {
+ *   await gateway.refund(input.chargeId);
+ * });
+ * ```
+ */
+export declare function defineRevert<TInput = unknown>(name: string, handler: (params: {
+    input: TInput;
+    ctx: BaseContext;
+}) => void | Promise<void>): RevertAction<TInput>;
+export {};