import type { WizardSession } from '../lib/wizard-session';
/**
 * Telemetry project API key. Empty or whitespace-only env value means “no key”
 * (use default only when the variable is unset).
 */
export declare function resolveTelemetryApiKey(): string;
/** HTTP API URL for `@amplitude/analytics-node` (same shape as manual HTTP ingest). */
export declare function getAmplitudeNodeServerUrl(): string;
/**
 * Extract a standard property bag from the current session.
 * Used by store-level analytics and available for ad-hoc captures.
 */
export declare function sessionProperties(session: WizardSession): Record<string, unknown>;
/**
 * Smaller session bag for high-volume wizard events (taxonomy: keep event
 * properties chart-useful and within a small count).
 */
export declare function sessionPropertiesCompact(session: WizardSession): Record<string, unknown>;
export declare class Analytics {
    /**
     * Session-scoped event properties — spread into every `capture()` call.
     *
     * Use for values that are genuinely session-wide and relevant to every event:
     *   mode, wizard_version, platform, node_version, integration, package-manager
     *
     * Do NOT use for step-specific state (vercel-detected, prettier-installed, etc.)
     * — pass those as event properties directly on the relevant event.
     */
    private sessionProperties;
    private distinctId?;
    private anonymousId;
    private appName;
    private activeFlags;
    private readonly client;
    private initPromise;
    private readonly startedAt;
    constructor();
    /** Expose the anonymous device ID for cross-system correlation (logs, Sentry). */
    getAnonymousId(): string;
    setDistinctId(distinctId: string): void;
    /**
     * Send an identify call to associate user properties with the current user.
     * Call after setDistinctId() has been called with a valid email.
     */
    identifyUser(properties: {
        email?: string;
        org_id?: string;
        org_name?: string;
        project_id?: string;
        project_name?: string;
        app_id?: string | number | null;
        env_name?: string | null;
        region?: string | null;
        integration?: string | null;
    }): void;
    /**
     * Set a session-scoped property that appears on every subsequent event.
     *
     * Only use for values relevant to ALL events in the session:
     *   mode, wizard_version, platform, node_version, integration, package-manager
     *
     * For step-specific data (vercel status, prettier, etc.), pass as event
     * properties directly on the relevant `wizardCapture()` call instead.
     */
    setSessionProperty(key: string, value: string | boolean | number | null | undefined): void;
    /**
     * @deprecated Use `setSessionProperty()` for session-wide data, or pass
     * step-specific data as event properties on `wizardCapture()`.
     */
    setTag(key: string, value: string | boolean | number | null | undefined): void;
    captureException(error: Error, properties?: Record<string, unknown>): void;
    capture(eventName: string, properties?: Record<string, unknown>): void;
    /**
     * Capture a wizard-specific event. Automatically prepends "wizard cli: " to the event name.
     * All new wizard analytics should use this method instead of capture() directly.
     * Use lowercase with spaces for eventName (e.g. "agent started", "api key submitted")
     * per Amplitude quickstart taxonomy guidelines.
     */
    wizardCapture(eventName: string, properties?: Record<string, unknown>): void;
    /**
     * Apply feature-flag–based opt-out to the Amplitude SDK.
     * Defaults to ON — only opts out when `wizard-agent-analytics` is explicitly 'off'/'false'.
     */
    applyOptOut(): void;
    private ensureInitStarted;
    /**
     * Initialize the Amplitude Experiment feature-flag client.
     * Call once early in startup (e.g. after obtaining a user/device ID).
     */
    initFlags(): Promise<void>;
    /**
     * Re-evaluate flags after the user identity changes (e.g. post-login).
     */
    refreshFlags(): Promise<void>;
    getFeatureFlag(flagKey: string): Promise<string | boolean | undefined>;
    /**
     * Check if a flag is enabled (variant is 'on' or 'true').
     */
    isFeatureFlagEnabled(flagKey: string): boolean;
    /**
     * Evaluate all feature flags for the current user at the start of a run.
     * Result is cached; subsequent calls in the same run return the same map.
     * Returns flag key -> string value (booleans become 'true'/'false').
     */
    getAllFlagsForWizard(): Promise<Record<string, string>>;
    /**
     * Flush pending events without ending the session.
     * Use for mid-session flushes (e.g. feedback command) where
     * the wizard continues running after the flush.
     */
    flush(): Promise<void>;
    shutdown(status: 'success' | 'error' | 'cancelled'): Promise<void>;
}
/**
 * Full Amplitude `event_type` for CLI/TUI product feedback.
 * Same string as `wizardCapture('feedback submitted', …)`.
 */
export declare const WIZARD_FEEDBACK_EVENT_TYPE = "wizard cli: feedback submitted";
export declare const analytics: Analytics;
/**
 * Unified wizard error telemetry (aligns with starter taxonomy “Error Encountered”).
 * Emits `wizard cli: error encountered` with category / message / context.
 */
export declare function captureWizardError(errorCategory: string, errorMessage: string, errorContext: string, extra?: Record<string, unknown>): void;
