/**
 * Provider Helper Utilities
 *
 * Centralized helper functions for provider lookup, validation, and error handling.
 * Eliminates code duplication across service functions.
 */
import type { LLMProvider, ServiceType, ProviderName } from '../providers/types.js';
import type { Logger, LLMResponse, LLMErrorCode, LLMRequestContext, LLMResponseContext, LLMErrorContext } from './types.js';
/**
 * Result of provider validation - either success with provider or failure with error response
 */
export type ProviderValidationResult = {
    success: true;
    provider: LLMProvider;
} | {
    success: false;
    error_response: LLMResponse;
};
/**
 * Options for provider validation
 */
export interface ProviderValidationOptions {
    /** LLM provider name (uses primary if not specified) */
    llm?: ProviderName;
    /** Service type to validate capability for */
    service_type: ServiceType;
    /** Logger instance */
    logger: Logger;
}
/**
 * Get and validate a provider for a specific service type
 *
 * This function consolidates the provider lookup and capability validation
 * logic that was previously duplicated across all service functions.
 *
 * @param options - Validation options
 * @returns Provider if valid, or error response if not
 *
 * @example
 * ```typescript
 * const result = get_validated_provider({
 *   llm: 'gemini',
 *   service_type: SERVICE_TYPES.TEXT_TEXT,
 *   logger,
 * });
 *
 * if (!result.success) {
 *   return result.error_response;
 * }
 *
 * const response = await result.provider.text_text(params, logger);
 * ```
 */
export declare function get_validated_provider(options: ProviderValidationOptions): ProviderValidationResult;
/**
 * Build a structured error response with both legacy and new error formats
 *
 * @param code - Error code from LLM_ERROR_CODES
 * @param message - Human-readable error message
 * @param retryable - Whether this error is potentially retryable (default: false)
 * @param details - Additional error details (optional)
 * @returns LLMResponse with structured error
 *
 * @example
 * ```typescript
 * return build_error_response(
 *   LLM_ERROR_CODES.RATE_LIMITED,
 *   'Rate limit exceeded. Please try again later.',
 *   true,
 *   { retry_after: 60 }
 * );
 * ```
 */
export declare function build_error_response(code: LLMErrorCode, message: string, retryable?: boolean, details?: Record<string, unknown>): LLMResponse;
/**
 * Build a helpful error message when provider is not found
 *
 * @param llm - The requested LLM name (or undefined for primary)
 * @returns LLMResponse with helpful error message
 */
export declare function build_provider_not_found_error(llm?: ProviderName): LLMResponse;
/**
 * Build an error response for unsupported capability
 *
 * @param provider_name - Name of the provider
 * @param service_type - The unsupported service type
 * @returns LLMResponse with capability error
 */
export declare function build_capability_error(provider_name: string, service_type: ServiceType): LLMResponse;
/**
 * Sanitize data for logging by replacing base64 strings with placeholders
 *
 * Recursively traverses objects and arrays, detecting and replacing:
 * - Data URLs (data:image/..., data:application/...)
 * - Long base64 strings (>500 chars)
 * - Known base64 fields: image_b64, data, inlineData.data
 *
 * @param data - Data to sanitize
 * @param max_string_length - Maximum length for regular strings (optional, default: no limit)
 * @returns Sanitized copy of the data
 *
 * @example
 * ```typescript
 * const sanitized = sanitize_for_logging({
 *   prompt: 'Describe this image',
 *   image_b64: 'iVBORw0KGgoAAAANSUhE...(50000 chars)',
 * });
 * // Result: { prompt: 'Describe this image', image_b64: '[BASE64_DATA: 50000 chars]' }
 * ```
 */
export declare function sanitize_for_logging(data: unknown, max_string_length?: number): unknown;
/**
 * Options for logging an LLM API call
 */
export interface LogLLMCallOptions {
    /** Service type name (e.g., 'text_text', 'image_text') */
    service_type: string;
    /** Prompt area (if using dynamic prompt from DB) */
    prompt_area?: string;
    /** Prompt key (if using dynamic prompt from DB) */
    prompt_key?: string;
    /** Variables being injected */
    variables?: Record<string, string>;
    /** Prompt text before variable substitution */
    prompt_before?: string;
    /** Prompt text after variable substitution */
    prompt_after?: string;
    /** Logger instance */
    logger: Logger;
}
/**
 * Log the start of an LLM API call with clean, focused output
 * Shows: service type, prompt_area/key, variables, prompt before/after
 */
export declare function log_llm_call_start(options: LogLLMCallOptions): void;
/**
 * Log the result of an LLM API call
 */
export declare function log_llm_call_result(service_type: string, response: LLMResponse, logger: Logger): void;
export declare function log_api_start(_api_name: string, _file_name: string, _logger: Logger): void;
export declare function log_api_complete(_api_name: string, _file_name: string, _success: boolean, _logger: Logger): void;
export declare function log_api_details(_provider: LLMProvider, _service_type: ServiceType, _file_name: string, _logger: Logger, _additional_data?: Record<string, unknown>): void;
export declare function log_api_response(_response: LLMResponse, _file_name: string, _logger: Logger): void;
/**
 * Log and build error response for caught exceptions
 *
 * @param error - The caught error
 * @param function_name - Name of the function where error occurred
 * @param file_name - Source file name
 * @param logger - Logger instance
 * @param error_code - Optional specific error code (defaults to UNKNOWN)
 * @returns LLMResponse with error details
 */
export declare function handle_caught_error(error: unknown, function_name: string, file_name: string, logger: Logger, error_code?: LLMErrorCode): LLMResponse;
/**
 * Auto-detect error code from error message
 *
 * @param error - The error to analyze
 * @returns Detected error code
 */
export declare function detect_error_code(error: unknown): LLMErrorCode;
/**
 * Call the beforeRequest hook if configured
 *
 * @param context - Request context
 */
export declare function call_before_request_hook(context: LLMRequestContext): Promise<void>;
/**
 * Call the afterResponse hook if configured
 *
 * @param context - Response context
 */
export declare function call_after_response_hook(context: LLMResponseContext): Promise<void>;
/**
 * Call the onError hook if configured
 *
 * @param context - Error context
 */
export declare function call_on_error_hook(context: LLMErrorContext): Promise<void>;
/**
 * Create a request context for hooks
 *
 * @param service_type - Service type being called
 * @param provider - Provider name
 * @param params - Request parameters
 * @returns Request context
 */
export declare function create_request_context(service_type: ServiceType, provider: string, params: Record<string, unknown>): LLMRequestContext;
//# sourceMappingURL=provider_helper.d.ts.map