/**
 * Job execution operations for B2C Commerce.
 *
 * Provides functions for executing and monitoring jobs on B2C Commerce instances.
 */
import { B2CInstance } from '../../instance/index.js';
import type { components } from '../../clients/ocapi.generated.js';
/**
 * Job execution from OCAPI.
 * Type alias to the generated schema.
 */
export type JobExecution = components['schemas']['job_execution'];
/**
 * Job step execution from OCAPI.
 * Type alias to the generated schema.
 */
export type JobStepExecution = components['schemas']['job_step_execution'];
/**
 * Job execution status from OCAPI.
 * Type alias to the generated schema's execution_status field.
 */
export type JobExecutionStatus = NonNullable<JobExecution['execution_status']>;
/**
 * Job execution parameter for starting jobs.
 * Type alias to the generated schema.
 */
export type JobExecutionParameter = components['schemas']['job_execution_parameter'];
/**
 * Options for executing a job.
 */
export interface ExecuteJobOptions {
    /** Job parameters to pass (standard jobs) */
    parameters?: JobExecutionParameter[];
    /** Raw request body (for system jobs with non-standard schemas like sfcc-search-index-*) */
    body?: Record<string, unknown>;
    /** Wait for running jobs to finish before starting (default: true) */
    waitForRunning?: boolean;
}
/**
 * Poll info passed to the onPoll callback during job waiting.
 */
export interface WaitForJobPollInfo {
    /** Job ID being waited on. */
    jobId: string;
    /** Execution ID being waited on. */
    executionId: string;
    /** Seconds elapsed since waiting started. */
    elapsedSeconds: number;
    /** Current execution status (e.g., 'running', 'pending', 'finished'). */
    status: string;
}
/**
 * Options for waiting on a job.
 */
export interface WaitForJobOptions {
    /** Polling interval in seconds (default: 3). */
    pollIntervalSeconds?: number;
    /** Maximum time to wait in seconds (default: no limit, 0 = no timeout). */
    timeoutSeconds?: number;
    /** Callback invoked on each poll with current status. */
    onPoll?: (info: WaitForJobPollInfo) => void;
    /** Custom sleep function for testing. */
    sleep?: (ms: number) => Promise<void>;
}
/**
 * Executes a job on a B2C Commerce instance.
 *
 * Starts a job execution and returns immediately with the execution details.
 * Use {@link waitForJob} to wait for completion.
 *
 * @param instance - B2C instance to execute on
 * @param jobId - Job ID to execute
 * @param options - Execution options
 * @returns Job execution details
 * @throws Error if job is already running (when waitForRunning is false)
 * @throws Error if job not found or cannot be executed
 *
 * @example
 * ```typescript
 * // Execute a simple job
 * const execution = await executeJob(instance, 'my-job-id');
 *
 * // Execute with parameters
 * const execution = await executeJob(instance, 'CustomerImportJob', {
 *   parameters: [
 *     { name: 'SiteScope', value: '{"all_storefront_sites":true}' }
 *   ]
 * });
 * ```
 */
export declare function executeJob(instance: B2CInstance, jobId: string, options?: ExecuteJobOptions): Promise<JobExecution>;
/**
 * Gets the current status of a job execution.
 *
 * @param instance - B2C instance
 * @param jobId - Job ID
 * @param executionId - Execution ID
 * @returns Current execution status
 * @throws Error if execution not found
 *
 * @example
 * ```typescript
 * const status = await getJobExecution(instance, 'my-job', 'exec-123');
 * console.log(`Status: ${status.execution_status}`);
 * ```
 */
export declare function getJobExecution(instance: B2CInstance, jobId: string, executionId: string): Promise<JobExecution>;
/**
 * Waits for a job execution to complete.
 *
 * Polls the job status until it reaches a terminal state (finished or aborted).
 *
 * @param instance - B2C instance
 * @param jobId - Job ID
 * @param executionId - Execution ID to wait for
 * @param options - Wait options
 * @returns Final execution status
 * @throws Error if job fails (status ERROR or aborted)
 * @throws Error if timeout is exceeded
 *
 * @example
 * ```typescript
 * // Simple wait
 * const result = await waitForJob(instance, 'my-job', 'exec-123');
 *
 * // With poll callback
 * const result = await waitForJob(instance, 'my-job', 'exec-123', {
 *   onPoll: (info) => {
 *     console.log(`Status: ${info.status} (${info.elapsedSeconds}s elapsed)`);
 *   }
 * });
 * ```
 */
export declare function waitForJob(instance: B2CInstance, jobId: string, executionId: string, options?: WaitForJobOptions): Promise<JobExecution>;
/**
 * Error thrown when a job execution fails.
 */
export declare class JobExecutionError extends Error {
    readonly execution: JobExecution;
    constructor(message: string, execution: JobExecution);
}
/**
 * Extracts the error message from a failed job execution.
 *
 * Looks for the last step execution with exit_status code 'ERROR' and returns its message.
 *
 * @param execution - The job execution to extract the error message from
 * @returns The error message if found, undefined otherwise
 *
 * @example
 * ```typescript
 * const errorMsg = getJobErrorMessage(execution);
 * if (errorMsg) {
 *   console.error(`Job failed: ${errorMsg}`);
 * }
 * ```
 */
export declare function getJobErrorMessage(execution: JobExecution): string | undefined;
/**
 * Search options for job executions.
 */
export interface SearchJobExecutionsOptions {
    /** Filter by job ID */
    jobId?: string;
    /** Filter by status (RUNNING, PENDING, OK, ERROR, etc.) */
    status?: string | string[];
    /** Maximum results to return (default: 25) */
    count?: number;
    /** Starting index for pagination */
    start?: number;
    /** Sort by field (default: start_time desc) */
    sortBy?: string;
    /** Sort order */
    sortOrder?: 'asc' | 'desc';
}
/**
 * Search results for job executions.
 */
export interface JobExecutionSearchResult {
    /** Total matching executions */
    total: number;
    /** Number of results returned */
    count: number;
    /** Starting index */
    start: number;
    /** Job executions */
    hits: JobExecution[];
}
/**
 * Searches for job executions.
 *
 * @param instance - B2C instance
 * @param options - Search options
 * @returns Search results
 *
 * @example
 * ```typescript
 * // Search for all running jobs
 * const results = await searchJobExecutions(instance, {
 *   status: ['RUNNING', 'PENDING']
 * });
 *
 * // Search for a specific job's recent executions
 * const results = await searchJobExecutions(instance, {
 *   jobId: 'my-job',
 *   count: 10
 * });
 * ```
 */
export declare function searchJobExecutions(instance: B2CInstance, options?: SearchJobExecutionsOptions): Promise<JobExecutionSearchResult>;
/**
 * Finds a currently running job execution.
 *
 * @param instance - B2C instance
 * @param jobId - Job ID to search for
 * @returns Running execution or undefined if none found
 */
export declare function findRunningJobExecution(instance: B2CInstance, jobId: string): Promise<JobExecution | undefined>;
/**
 * Gets the log file content for a job execution.
 *
 * @param instance - B2C instance
 * @param execution - Job execution with log file path
 * @returns Log file content as string
 * @throws Error if log file doesn't exist or cannot be retrieved
 *
 * @example
 * ```typescript
 * try {
 *   const result = await waitForJob(instance, 'my-job', 'exec-123');
 * } catch (error) {
 *   if (error instanceof JobExecutionError && error.execution.is_log_file_existing) {
 *     const log = await getJobLog(instance, error.execution);
 *     console.error('Job log:', log);
 *   }
 * }
 * ```
 */
export declare function getJobLog(instance: B2CInstance, execution: JobExecution): Promise<string>;
