/**
 * Usage Telemetry Module
 *
 * Tracks scan events and usage patterns for analytics and case studies.
 * All telemetry is opt-in and respects user privacy preferences.
 *
 * @module telemetry/usage
 */
import type { Severity, CertificationLevel } from "../certification/types.js";
/**
 * Telemetry configuration
 */
export interface TelemetryConfig {
    /** Whether telemetry is enabled */
    enabled: boolean;
    /** API endpoint for telemetry events */
    endpoint?: string;
    /** Optional API key for authentication */
    apiKey?: string;
    /** Include repository URL (requires explicit opt-in) */
    includeRepoUrl?: boolean;
    /** Include organization name (requires explicit opt-in) */
    includeOrgName?: boolean;
    /** Include user email (requires explicit opt-in) */
    includeUserEmail?: boolean;
}
/**
 * Default telemetry configuration (reads from environment)
 */
export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
/**
 * Types of telemetry events
 */
export type TelemetryEventType = "certification_started" | "certification_completed" | "certification_failed" | "finding_discovered" | "finding_resolved" | "scanner_run" | "badge_generated" | "sbom_generated" | "compliance_report_generated";
/**
 * Base telemetry event
 */
export interface BaseTelemetryEvent {
    /** Event type */
    eventType: TelemetryEventType;
    /** ISO timestamp */
    timestamp: string;
    /** SHA256 hash of project path (anonymized) */
    projectHash: string;
    /** Vaspera version */
    vasperaVersion: string;
    /** Platform (darwin, linux, win32) */
    platform: string;
    /** Node.js version */
    nodeVersion: string;
}
/**
 * Event when a certification scan starts
 */
export interface CertificationStartedEvent extends BaseTelemetryEvent {
    eventType: "certification_started";
    /** Scanners being run */
    scanners: string[];
    /** Frameworks being assessed */
    frameworks: string[];
    /** Corpus size setting */
    corpusSize?: string;
}
/**
 * Event when a certification scan completes
 */
export interface CertificationCompletedEvent extends BaseTelemetryEvent {
    eventType: "certification_completed";
    /** Certification ID */
    certificationId: string;
    /** Achieved level */
    level: CertificationLevel;
    /** Overall score (0-100) */
    score: number;
    /** Duration in milliseconds */
    duration: number;
    /** Findings count by severity */
    severityCounts: Record<Severity, number>;
    /** Total findings */
    totalFindings: number;
    /** Frameworks assessed */
    frameworks: string[];
    /** Optional: repository URL if user opted in */
    repoUrl?: string;
    /** Optional: organization name if user opted in */
    orgName?: string;
    /** Optional: user email if user opted in */
    userEmail?: string;
}
/**
 * Event when a certification scan fails
 */
export interface CertificationFailedEvent extends BaseTelemetryEvent {
    eventType: "certification_failed";
    /** Error message (sanitized) */
    errorMessage: string;
    /** Error category */
    errorCategory: "scanner_error" | "config_error" | "timeout" | "unknown";
    /** Duration before failure */
    duration: number;
}
/**
 * Event when a finding is discovered
 */
export interface FindingDiscoveredEvent extends BaseTelemetryEvent {
    eventType: "finding_discovered";
    /** Finding category */
    category: string;
    /** Severity level */
    severity: Severity;
    /** Scanner that found it */
    scanner: string;
    /** Rule/check ID */
    ruleId?: string;
}
/**
 * Event when a scanner completes
 */
export interface ScannerRunEvent extends BaseTelemetryEvent {
    eventType: "scanner_run";
    /** Scanner name */
    scanner: string;
    /** Duration in milliseconds */
    duration: number;
    /** Number of findings */
    findingsCount: number;
    /** Whether it succeeded */
    success: boolean;
}
/**
 * Union of all telemetry events
 */
export type TelemetryEvent = CertificationStartedEvent | CertificationCompletedEvent | CertificationFailedEvent | FindingDiscoveredEvent | ScannerRunEvent;
/**
 * Initialize telemetry with configuration
 */
export declare function initTelemetry(config: Partial<TelemetryConfig>): void;
/**
 * Check if telemetry is enabled
 */
export declare function isTelemetryEnabled(): boolean;
/**
 * Hash a value for anonymization
 */
export declare function hashValue(value: string): string;
/**
 * Track a telemetry event
 */
export declare function trackEvent(event: Omit<TelemetryEvent, keyof BaseTelemetryEvent> & {
    eventType: TelemetryEventType;
    projectPath: string;
}): Promise<void>;
/**
 * Flush buffered events to the telemetry endpoint
 */
export declare function flushEvents(): Promise<void>;
/**
 * Shutdown telemetry (flush remaining events)
 */
export declare function shutdownTelemetry(): Promise<void>;
/**
 * Track certification start
 */
export declare function trackCertificationStarted(projectPath: string, scanners: string[], frameworks: string[], corpusSize?: string): Promise<void>;
/**
 * Track certification completion
 */
export declare function trackCertificationCompleted(projectPath: string, certificationId: string, level: CertificationLevel, score: number, duration: number, severityCounts: Record<Severity, number>, totalFindings: number, frameworks: string[], optionalInfo?: {
    repoUrl?: string;
    orgName?: string;
    userEmail?: string;
}): Promise<void>;
/**
 * Track certification failure
 */
export declare function trackCertificationFailed(projectPath: string, errorMessage: string, errorCategory: CertificationFailedEvent["errorCategory"], duration: number): Promise<void>;
/**
 * Track a finding discovery
 */
export declare function trackFindingDiscovered(projectPath: string, category: string, severity: Severity, scanner: string, ruleId?: string): Promise<void>;
/**
 * Track a scanner run
 */
export declare function trackScannerRun(projectPath: string, scanner: string, duration: number, findingsCount: number, success: boolean): Promise<void>;
export declare const telemetry: {
    init: typeof initTelemetry;
    isEnabled: typeof isTelemetryEnabled;
    track: typeof trackEvent;
    flush: typeof flushEvents;
    shutdown: typeof shutdownTelemetry;
    trackCertificationStarted: typeof trackCertificationStarted;
    trackCertificationCompleted: typeof trackCertificationCompleted;
    trackCertificationFailed: typeof trackCertificationFailed;
    trackFindingDiscovered: typeof trackFindingDiscovered;
    trackScannerRun: typeof trackScannerRun;
};
//# sourceMappingURL=usage.d.ts.map