/**
 * SMI-1246: PostHog Telemetry Integration
 *
 * Provides product analytics and event tracking via PostHog:
 * - Skill searches and views
 * - Installation events
 * - User engagement metrics
 * - Feature usage tracking
 *
 * Privacy-first: All user IDs are anonymized, no PII collected.
 */
import { PostHog } from 'posthog-node';
/**
 * PostHog configuration options
 */
export interface PostHogConfig {
    /** PostHog API key (starts with phc_) */
    apiKey: string;
    /** PostHog host URL (default: https://app.posthog.com) */
    host?: string;
    /** Flush interval in milliseconds (default: 10000) */
    flushInterval?: number;
    /** Enable debug logging (default: false) */
    debug?: boolean;
    /** Disable telemetry entirely (default: false) */
    disabled?: boolean;
}
/**
 * Event types for Skillsmith analytics
 */
export type SkillsmithEventType = 'skill_search' | 'skill_view' | 'skill_install' | 'skill_uninstall' | 'skill_compare' | 'skill_recommend' | 'api_error' | 'feature_flag_evaluated' | 'skill_invoke' | 'skill_context_load' | 'skill_invoke_unparsed';
/**
 * Event properties for skill-related events
 */
export interface SkillEventProperties {
    /** Skill ID (author/name format) */
    skill_id?: string;
    /** Search query */
    query?: string;
    /** Number of results returned */
    result_count?: number;
    /** Trust tier filter applied */
    trust_tier?: string;
    /** Category filter applied */
    category?: string;
    /** Response time in milliseconds */
    duration_ms?: number;
    /** Error code if applicable */
    error_code?: string;
    /** Source of the event (cli, mcp, api) */
    source?: 'cli' | 'mcp' | 'api';
    /** Additional custom properties */
    [key: string]: unknown;
}
/**
 * Initialize PostHog client
 * Call this at application startup
 *
 * @param config - PostHog configuration
 */
export declare function initializePostHog(config: PostHogConfig): void;
/**
 * Get the PostHog client instance
 * Returns null if not initialized or disabled
 */
export declare function getPostHog(): PostHog | null;
/**
 * Check if PostHog is enabled and initialized
 */
export declare function isPostHogEnabled(): boolean;
/**
 * Track an event with PostHog
 * Silently no-ops if PostHog is disabled or not initialized
 *
 * @param distinctId - Anonymous user identifier
 * @param event - Event name
 * @param properties - Event properties
 */
export declare function trackEvent(distinctId: string, event: SkillsmithEventType | string, properties?: SkillEventProperties): void;
/**
 * Allowed trait keys for user identification.
 * Only non-PII properties are permitted to prevent data leakage.
 */
export declare const ALLOWED_TRAITS: readonly ["tier", "version", "platform", "sdk_version"];
/**
 * Type for allowed user traits - restricted to prevent PII leakage.
 * Only safe, non-identifying properties are permitted.
 */
export type AllowedUserTraits = {
    /** User tier (e.g., 'free', 'pro', 'enterprise') */
    tier?: string;
    /** Application version */
    version?: string;
    /** Platform identifier (e.g., 'darwin', 'linux', 'win32') */
    platform?: string;
    /** SDK version used */
    sdk_version?: string;
};
/**
 * Identify a user with restricted traits.
 *
 * @warning DO NOT pass PII (email, name, IP, etc.) to this function.
 * Only the following safe traits are allowed: tier, version, platform, sdk_version.
 * Any other properties will be silently filtered out to prevent data leakage.
 *
 * @param distinctId - Anonymous user identifier (should be a hash, not an email)
 * @param traits - User properties (restricted to AllowedUserTraits)
 */
export declare function identifyUser(distinctId: string, traits: AllowedUserTraits): void;
/**
 * Check if a feature flag is enabled for a user
 *
 * @param distinctId - Anonymous user identifier
 * @param flagKey - Feature flag key
 * @returns true if enabled, false otherwise
 */
export declare function isFeatureFlagEnabled(distinctId: string, flagKey: string): Promise<boolean>;
/**
 * Flush all pending events immediately
 * Call this before application shutdown
 */
export declare function flushPostHog(): Promise<void>;
/**
 * Shutdown PostHog client
 * Call this at application shutdown
 */
export declare function shutdownPostHog(): Promise<void>;
/**
 * Convenience function to track skill search events
 */
export declare function trackSkillSearch(distinctId: string, query: string, resultCount: number, durationMs: number, filters?: {
    trustTier?: string;
    category?: string;
}): void;
/**
 * Convenience function to track skill view events
 */
export declare function trackSkillView(distinctId: string, skillId: string, source: 'cli' | 'mcp' | 'api'): void;
/**
 * Convenience function to track skill install events
 */
export declare function trackSkillInstall(distinctId: string, skillId: string, source: 'cli' | 'mcp' | 'api'): void;
/**
 * Parameters for tracking a skill invocation event (SMI-5016).
 * `distinctId` defaults to `'anonymous'` so the HOF can emit without knowing
 * the per-user ID at wrap-time; callers with a resolved ID should pass it.
 */
export interface TrackSkillInvokeParams {
    skillId: string;
    source: 'mcp-tool' | 'cli' | 'vscode-extension';
    framework: string;
    durationMs: number;
    success: boolean;
    distinctId?: string;
    /**
     * SMI-5456 agent-mediation marker fields. Per-event, non-identifying; they
     * ride the same consent-gated event as the rest of the payload.
     */
    /** True when the invocation is part of an agent-mediated session. */
    agentSession?: boolean;
    /** True when the invocation originated from a nudge. */
    nudgeOrigin?: boolean;
    /** Paywall / nudge trigger id, or null. */
    triggerId?: string | null;
    /**
     * SMI-5615: error capture fields, populated only when `success` is `false`.
     * `errorMessage` is already redacted and truncated (<=256 chars) by the
     * caller (`withTelemetry`) — no stack traces leave the machine.
     */
    /** The caught error's constructor name (e.g. `TypeError`), or `typeof` for non-Error throws. */
    errorName?: string;
    /** Redacted, truncated (<=256 char) error message. */
    errorMessage?: string;
    /**
     * Cross-signal join key shared by a disk log line, an OTel span, and this
     * PostHog event for one call — installed per-call by `withTelemetry` via
     * `runWithCorrelationId`. Present regardless of success/failure.
     */
    correlationId?: string;
}
/**
 * Convenience function to track skill invocation events (SMI-5016).
 * Mirrors `trackSkillInstall()` — positional for resolved-ID callers.
 */
export declare function trackSkillInvoke(params: TrackSkillInvokeParams): void;
/**
 * Convenience function to track API errors
 */
export declare function trackApiError(distinctId: string, errorCode: string, endpoint: string, durationMs?: number): void;
//# sourceMappingURL=posthog.d.ts.map