import type { TelemetryContext } from './types.mts';
/**
 * Finalize telemetry and clean up resources (async version).
 * This should be called before process.exit to ensure telemetry is sent and resources are cleaned up.
 * Use this in async contexts like beforeExit handlers.
 *
 * @returns Promise that resolves when finalization completes.
 */
export declare function finalizeTelemetry(): Promise<void>;
/**
 * Finalize telemetry synchronously (best-effort).
 * This triggers a flush without awaiting it.
 * Use this in synchronous contexts like signal handlers where async operations are not possible.
 *
 * Note: This is best-effort only. Events may be lost if the process exits before flush completes.
 * Prefer finalizeTelemetry() (async version) when possible.
 */
export declare function finalizeTelemetrySync(): void;
/**
 * Set up exit handlers for telemetry finalization.
 * This registers handlers for both normal exits (beforeExit) and common fatal signals.
 *
 * Flushing strategy:
 * - Batch-based: Auto-flush when queue reaches 10 events.
 * - beforeExit: Async handler for clean shutdowns (when event loop empties).
 * - Fatal signals (SIGINT, SIGTERM, SIGHUP): Best-effort sync flush.
 * - Accepts that forced exits (SIGKILL, process.exit()) may lose final events.
 *
 * Call this once during CLI initialization to ensure telemetry is flushed on exit.
 * Safe to call multiple times - only registers handlers once.
 *
 * @example
 * ```typescript
 * // In src/cli.mts
 * setupTelemetryExitHandlers()
 * ```
 */
export declare function setupTelemetryExitHandlers(): void;
/**
 * Track subprocess exit and finalize telemetry.
 * This is a convenience function that tracks completion/error based on exit code
 * and ensures telemetry is flushed before returning.
 *
 * Note: Only tracks subprocess-level events. CLI-level events (cli_complete, cli_error)
 * are tracked by the main CLI entry point in src/cli.mts.
 *
 * @param command - Command name (e.g., 'npm', 'pip').
 * @param startTime - Start timestamp from trackSubprocessStart.
 * @param exitCode - Process exit code (null treated as error).
 * @returns Promise that resolves when tracking and flush complete.
 *
 * @example
 * ```typescript
 * await trackSubprocessExit(NPM, subprocessStartTime, code)
 * ```
 */
export declare function trackSubprocessExit(command: string, startTime: number, exitCode: number | null): Promise<void>;
/**
 * Generic event tracking function.
 * Tracks any telemetry event with optional error details and explicit flush.
 *
 * Events are automatically flushed via batch size or exit handlers.
 * Use the flush option only when immediate submission is required.
 *
 * @param eventType Type of event to track.
 * @param context Event context.
 * @param metadata Event metadata.
 * @param options Optional configuration.
 * @returns Promise that resolves when tracking completes.
 */
export declare function trackEvent(eventType: string, context: TelemetryContext, metadata?: Record<string, unknown>, options?: {
    error?: Error | undefined;
    flush?: boolean | undefined;
}): Promise<void>;
/**
 * Track CLI initialization event.
 * Should be called at the start of CLI execution.
 *
 * @param argv Command line arguments (process.argv).
 * @returns Start timestamp for duration calculation.
 */
export declare function trackCliStart(argv: string[]): Promise<number>;
/**
 * Track a generic CLI event with optional metadata.
 * Use this for tracking custom events during CLI execution.
 *
 * @param eventType Type of event to track.
 * @param argv Command line arguments (process.argv).
 * @param metadata Optional additional metadata to include with the event.
 */
export declare function trackCliEvent(eventType: string, argv: string[], metadata?: Record<string, unknown> | undefined): Promise<void>;
/**
 * Track CLI completion event.
 * Should be called on successful CLI exit.
 * Flushes immediately since this is typically the last event before process exit.
 *
 * @param argv
 * @param startTime Start timestamp from trackCliStart.
 * @param exitCode Process exit code (default: 0).
 */
export declare function trackCliComplete(argv: string[], startTime: number, exitCode?: string | number | undefined | null): Promise<void>;
/**
 * Track CLI error event.
 * Should be called when CLI exits with an error.
 * Flushes immediately since this is typically the last event before process exit.
 *
 * @param argv
 * @param startTime Start timestamp from trackCliStart.
 * @param error Error that occurred.
 * @param exitCode Process exit code (default: 1).
 */
export declare function trackCliError(argv: string[], startTime: number, error: unknown, exitCode?: number | string | undefined | null): Promise<void>;
/**
 * Track subprocess/command start event.
 *
 * Use this when spawning external commands like npm, npx, coana, cdxgen, etc.
 *
 * @param command Command being executed (e.g., 'npm', 'npx', 'coana').
 * @param metadata Optional additional metadata (e.g., cwd, purpose).
 * @returns Start timestamp for duration calculation.
 */
export declare function trackSubprocessStart(command: string, metadata?: Record<string, unknown> | undefined): Promise<number>;
/**
 * Track subprocess/command completion event.
 *
 * Should be called when spawned command completes successfully.
 *
 * @param command Command that was executed.
 * @param startTime Start timestamp from trackSubprocessStart.
 * @param exitCode Process exit code.
 * @param metadata Optional additional metadata (e.g., stdout length, stderr length).
 */
export declare function trackSubprocessComplete(command: string, startTime: number, exitCode: number | null, metadata?: Record<string, unknown> | undefined): Promise<void>;
/**
 * Track subprocess/command error event.
 *
 * Should be called when spawned command fails or throws error.
 *
 * @param command Command that was executed.
 * @param startTime Start timestamp from trackSubprocessStart.
 * @param error Error that occurred.
 * @param exitCode Process exit code.
 * @param metadata Optional additional metadata.
 */
export declare function trackSubprocessError(command: string, startTime: number, error: unknown, exitCode?: number | null | undefined, metadata?: Record<string, unknown> | undefined): Promise<void>;
//# sourceMappingURL=integration.d.mts.map