import type { Workflow } from '@botpress/client';
import type { BaseWorkflow } from './workflow';
import type { ZuiType } from '../types';
import { z, type ZodType } from '@botpress/sdk';
type WorkflowStepOptions = {
    maxAttempts?: number;
};
type MapOptions = {
    maxAttempts?: number;
    concurrency?: number;
};
/**
 * Workflow step execution API. Steps are the building blocks of workflows with automatic retry logic and state persistence.
 */
export interface WorkflowStep {
    /**
     * Execute a workflow step with automatic retry logic and state persistence.
     * Steps are idempotent and resumable - if a step has already been executed, its cached result is returned immediately.
     * @param name - Unique identifier for this step within the workflow
     * @param run - Function to execute, receives the current attempt number
     * @param options - Configuration options
     * @param options.maxAttempts - Maximum number of retry attempts (default: 5)
     * @returns The result of the step execution
     * @example
     * const data = await step("fetch-user", async () => {
     *   return await fetchUser(userId);
     * });
     */
    <T>(name: string, run: ({ attempt }: {
        attempt: number;
    }) => T | Promise<T>, options?: WorkflowStepOptions): Promise<T>;
    /**
     * Put the workflow into listening mode, waiting for external events to resume.
     * The workflow will pause at this step and can be resumed by triggering it with an event.
     * @param name - The name of the step
     * @example
     * await step.listen("wait-for-approval");
     * // Workflow pauses here until an event triggers it to continue
     */
    listen(name: string): Promise<void>;
    /**
     * Mark the workflow as failed with a specific reason and stop execution.
     * This immediately terminates the workflow and sets its status to "failed".
     * @param reason - Description of why the workflow failed
     * @example
     * if (!user.isVerified) {
     *   await step.fail("User verification required");
     * }
     */
    fail(reason: string): Promise<void>;
    /**
     * Record a progress checkpoint in the workflow without performing any action.
     * Useful for tracking workflow execution stages and creating audit trails.
     * @param name - The name of the progress checkpoint
     * @example
     * await step.progress("Started processing");
     * // ... do work ...
     * await step.progress("Finished processing");
     */
    progress(name: string): Promise<void>;
    /**
     * Immediately abort the workflow execution without marking it as failed.
     * The workflow status remains unchanged and can potentially be resumed later.
     * This is different from step.fail() which marks the workflow as failed.
     * @example
     * if (shouldPause) {
     *   step.abort(); // Stop execution but keep workflow in current state
     * }
     */
    abort(): void;
    /**
     * Pause workflow execution for the specified duration in milliseconds.
     * For delays >= 10 seconds, the workflow enters listening mode to save resources.
     * For shorter delays, uses an in-memory timeout.
     * @param name - The name of the step
     * @param ms - Duration to sleep in milliseconds
     * @example
     * await step.sleep("wait-5-min", 5 * 60 * 1000);
     * await step.sleep("short-delay", 1000);
     */
    sleep(name: string, ms: number): Promise<void>;
    /**
     * Sleep until the specified date, minus a buffer to ensure the step can complete before the workflow times out.
     * If the date is in the past, the step will return immediately.
     * @param name - The name of the step
     * @param date - The date to sleep until
     * @example
     * await step.sleepUntil("wait-until-noon", new Date("2025-01-15T12:00:00Z"));
     */
    sleepUntil(name: string, date: Date | string): Promise<void>;
    /**
     * Wait for another workflow to complete before continuing.
     * The current workflow will pause and poll until the target workflow finishes.
     * @param name - The name of the step
     * @param workflowId - ID of the workflow to wait for
     * @returns The completed workflow object
     * @throws Error if attempting to wait for the same workflow (would cause deadlock)
     * @example
     * const childWorkflow = await childWorkflowInstance.start({});
     * const result = await step.waitForWorkflow("wait-for-child", childWorkflow.id);
     */
    waitForWorkflow(name: string, workflowId: string): Promise<Workflow>;
    /**
     * Start another workflow and wait for it to complete, returning its output.
     * This is a convenience method that combines workflow.start() and step.waitForWorkflow().
     * @param name - The name of the step
     * @param workflow - The workflow instance to execute
     * @returns The output of the completed workflow
     * @example
     * const processedData = await step.executeWorkflow(
     *   "process-data",
     *   dataProcessingWorkflow
     * );
     */
    executeWorkflow<TName extends string, TInput extends ZuiType, TOutput extends ZodType>(name: string, workflow: BaseWorkflow<TName, TInput, TOutput>, input?: z.infer<TInput>): Promise<z.infer<TOutput>>;
    /**
     * Process an array of items in parallel with controlled concurrency, collecting results.
     * Each item is processed in its own step with automatic retry logic.
     * @param name - The name of the map operation
     * @param items - Array of items to process
     * @param run - Function to process each item, receives the item and its index
     * @param opts - Configuration options
     * @param opts.maxAttempts - Maximum retry attempts per item (default: 5)
     * @param opts.concurrency - Maximum number of concurrent operations (default: 1)
     * @returns Array of results in the same order as input items
     * @example
     * const results = await step.map(
     *   "process-users",
     *   users,
     *   async (user, { i }) => processUser(user),
     *   { concurrency: 5 }
     * );
     */
    map<T, U>(name: string, items: T[], run: (input: T, opts: {
        i: number;
    }) => Promise<U>, opts?: MapOptions): Promise<U[]>;
    /**
     * Process an array of items in parallel without collecting results.
     * Similar to step.map but doesn't return an array of results (for side effects only).
     * @param name - The name of the forEach operation
     * @param items - Array of items to process
     * @param run - Function to process each item, receives the item and its index
     * @param opts - Configuration options
     * @param opts.maxAttempts - Maximum retry attempts per item (default: 5)
     * @param opts.concurrency - Maximum number of concurrent operations (default: 1)
     * @example
     * await step.forEach(
     *   "notify-users",
     *   users,
     *   async (user) => sendNotification(user),
     *   { concurrency: 10 }
     * );
     */
    forEach<T>(name: string, items: T[], run: (input: T, opts: {
        i: number;
    }) => Promise<void>, opts?: MapOptions): Promise<void>;
    /**
     * Process an array of items in sequential batches.
     * Items are grouped into batches and each batch is processed as a single step.
     * Useful for bulk operations with external APIs that accept multiple items.
     * @param name - The name of the batch operation
     * @param items - Array of items to process
     * @param run - Function to process each batch, receives the batch array and starting index
     * @param opts - Configuration options
     * @param opts.batchSize - Number of items per batch (default: 20)
     * @param opts.maxAttempts - Maximum retry attempts per batch (default: 5)
     * @example
     * await step.batch(
     *   "bulk-insert",
     *   records,
     *   async (batch) => database.bulkInsert(batch),
     *   { batchSize: 100 }
     * );
     */
    batch<T>(name: string, items: T[], run: (input: T[], opts: {
        i: number;
    }) => Promise<void>, opts?: {
        batchSize?: number;
        maxAttempts?: number;
    }): Promise<void>;
}
export declare const step: WorkflowStep;
export {};
//# sourceMappingURL=workflow-step.d.ts.map