/**
 * Lifecycle event types emitted by adapters.
 *
 * These events follow the Salesforce CLI pattern for telemetry and debugging.
 * Events are organized by adapter category and phase:
 *
 * **Query Events** (`adapter:query:*`):
 * - `start`: Emitted when a SOQL query begins. Payload includes operation name and query context.
 * - `complete`: Emitted when query succeeds. Payload includes duration and record count context.
 * - `error`: Emitted when query fails. Payload includes duration and error message.
 *
 * **Describe Events** (`adapter:describe:*`):
 * - `start`: Emitted when describing an object/global. Payload includes object name context.
 * - `complete`: Emitted when describe succeeds. Payload includes duration and field count context.
 * - `error`: Emitted when describe fails. Payload includes duration and error message.
 *
 * **Tooling Events** (`adapter:tooling:*`):
 * - `start`: Emitted when a Tooling API operation begins.
 * - `complete`: Emitted when Tooling operation succeeds.
 * - `error`: Emitted when Tooling operation fails.
 *
 * **Apex Events** (`adapter:apex:*`):
 * - `start`: Emitted when Apex execution begins. Payload includes code length context.
 * - `complete`: Emitted when Apex succeeds. Payload includes hasDebugLog context.
 * - `error`: Emitted when Apex fails. Payload includes compiled status and error message.
 *
 * @example
 * ```typescript
 * // Subscribing to lifecycle events
 * Lifecycle.getInstance().on('adapter:query:complete', (payload) => {
 *   console.log(`Query completed in ${payload.duration}ms`);
 * });
 * ```
 */
export type AdapterLifecycleEvent = 'adapter:query:start' | 'adapter:query:complete' | 'adapter:query:error' | 'adapter:describe:start' | 'adapter:describe:complete' | 'adapter:describe:error' | 'adapter:tooling:start' | 'adapter:tooling:complete' | 'adapter:tooling:error' | 'adapter:apex:start' | 'adapter:apex:complete' | 'adapter:apex:error';
/**
 * Payload for lifecycle events.
 *
 * Properties vary by event type:
 *
 * | Property | start | complete | error |
 * |----------|-------|----------|-------|
 * | operation | Always | Always | Always |
 * | duration | Never | Always | Always |
 * | success | Never | Always (true) | Always (false) |
 * | errorMessage | Never | Never | Always |
 * | context | Optional | Optional | Optional |
 */
export type LifecycleEventPayload = {
    /** The adapter operation being performed (always present) */
    operation: string;
    /** Duration in milliseconds (present on complete/error events only) */
    duration?: number;
    /** Whether the operation succeeded (present on complete/error events only) */
    success?: boolean;
    /** Error message (present on error events only) */
    errorMessage?: string;
    /** Additional context data specific to the operation */
    context?: Record<string, unknown>;
};
/**
 * Configuration for lifecycle event emission.
 */
export type LifecycleConfig = {
    /** Whether to emit lifecycle events. Default: false */
    emitLifecycleEvents?: boolean;
};
/**
 * Emits a lifecycle event if enabled.
 *
 * This function is a no-op if lifecycle events are disabled,
 * making it safe to call without checking configuration first.
 *
 * @param event - The event name to emit
 * @param payload - The event payload
 * @param enabled - Whether lifecycle events are enabled
 * @throws {Error} When Lifecycle.emit() fails - errors are caught and silently ignored to prevent adapter operation disruption
 *
 * @example
 * ```typescript
 * await emitLifecycleEvent('adapter:query:start', {
 *   operation: 'query',
 *   context: { soql: 'SELECT Id FROM Account' }
 * }, true);
 * ```
 */
export declare function emitLifecycleEvent(event: AdapterLifecycleEvent, payload: LifecycleEventPayload, enabled: boolean): Promise<void>;
/**
 * Creates lifecycle event helpers for an adapter.
 *
 * This factory creates start/complete/error helper functions
 * that handle the common pattern of emitting events.
 *
 * The returned object contains three methods:
 * - `start(operation, context?)`: Emits start event. Call at operation beginning.
 * - `complete(operation, startTime, context?)`: Emits complete event with duration. Call on success.
 * - `error(operation, startTime, errorMessage, context?)`: Emits error event. Call on failure.
 *
 * The `startTime` parameter should be `Date.now()` captured at operation start,
 * used to calculate duration in milliseconds.
 *
 * @param category - The adapter category (query, describe, tooling, apex)
 * @param enabled - Whether lifecycle events are enabled
 * @returns Helper functions for emitting events
 *
 * @example
 * ```typescript
 * const lifecycle = createLifecycleEmitter('query', config?.emitLifecycleEvents ?? false);
 *
 * lifecycle.start('query', { soql: 'SELECT Id FROM Account' });
 * // ... perform operation ...
 * lifecycle.complete('query', startTime, { recordCount: 100 });
 * ```
 */
export declare function createLifecycleEmitter(category: 'query' | 'describe' | 'tooling' | 'apex', enabled: boolean): {
    start: (operation: string, context?: Record<string, unknown>) => Promise<void>;
    complete: (operation: string, startTime: number, context?: Record<string, unknown>) => Promise<void>;
    error: (operation: string, startTime: number, errorMessage: string, context?: Record<string, unknown>) => Promise<void>;
};