Type Definitions

/**
 * A single property value
 * Can be string, number, boolean, null, or undefined
 */
type Property = string | number | boolean | null | undefined;

/**
 * Object containing event or user properties
 * Keys are property names, values can be single properties or arrays
 */
type Properties = Record<string, Property | Property[]>;

/**
 * JSON-serializable value
 * Includes objects, arrays, strings, numbers, booleans, and null
 */
type JsonType = any;

/**
 * Event name - any string value
 * Can be custom event names or known PostHog event names
 */
type EventName = string;

/**
 * Result of capturing an event
 */
interface CaptureResult {
    /**
     * Event name that was captured
     */
    event: string;

    /**
     * Properties that were sent with the event
     * Includes both provided properties and auto-added properties
     */
    properties: Record<string, any>;
}

/**
 * Options for capturing events
 */
interface CaptureOptions {
    /**
     * Send this event immediately without batching
     * @default false
     */
    send_instantly?: boolean;

    /**
     * Custom timestamp for the event
     * @default Current time
     */
    timestamp?: Date;

    /**
     * User properties to set with this event
     * These properties are set on the person profile
     */
    $set?: Properties;

    /**
     * User properties to set once with this event
     * Only set if not already present on the person profile
     */
    $set_once?: Properties;

    /**
     * Internal batch key for grouping events
     * @internal
     */
    _batchKey?: string;
}

/**
 * Callback to modify events before sending
 * Return null to block the event from being sent
 * Return modified CaptureResult to change event data
 */
type BeforeSendFn = (data: CaptureResult) => CaptureResult | null;

/**
 * Callback invoked when feature flags are loaded
 * @param flags - Object mapping flag keys to boolean or string values
 * @param variants - Object mapping flag keys to variant names
 * @param context - Additional context including error information
 */
type FeatureFlagsCallback = (
    flags: Record<string, boolean | string>,
    variants: Record<string, string | undefined>,
    context?: { errorsLoading?: string }
) => void;

/**
 * Detailed information about a feature flag
 */
interface FeatureFlagDetail {
    /**
     * Flag key
     */
    key: string;

    /**
     * Whether the flag is enabled
     */
    enabled: boolean;

    /**
     * Variant value for multivariate flags
     */
    variant?: string;

    /**
     * Reason for the flag evaluation result
     */
    reason?: EvaluationReason;

    /**
     * Additional metadata about the flag
     */
    metadata?: {
        /**
         * Flag ID in PostHog
         */
        id?: number;

        /**
         * Flag version number
         */
        version?: number;

        /**
         * Human-readable description
         */
        description?: string;

        /**
         * JSON payload attached to flag
         */
        payload?: JsonType;
    };
}

/**
 * Reason for feature flag evaluation result
 */
type EvaluationReason =
    | 'local_evaluation'      // Evaluated locally in browser
    | 'remote_evaluation'     // Evaluated by PostHog server
    | 'override'              // Manually overridden via updateFlags()
    | 'bootstrap'             // Loaded from bootstrap config
    | 'fallback'              // Fallback value used
    | 'disabled'              // Flags are disabled
    | 'error';                // Error occurred during evaluation

/**
 * Early access feature information
 */
interface EarlyAccessFeature {
    /**
     * Unique identifier
     */
    id: string;

    /**
     * Feature key
     */
    key: string;

    /**
     * Feature name
     */
    name: string;

    /**
     * Feature description
     */
    description?: string;

    /**
     * Current development stage
     */
    stage: EarlyAccessFeatureStage;
}

/**
 * Early access feature development stage
 */
enum EarlyAccessFeatureStage {
    /**
     * In development, not ready for users
     */
    Development = 'development',

    /**
     * Alpha testing phase
     */
    Alpha = 'alpha',

    /**
     * Beta testing phase
     */
    Beta = 'beta',

    /**
     * Generally available to all
     */
    GeneralAvailability = 'general-availability',
}

/**
 * Callback for early access feature loading
 * @param features - Array of available early access features
 * @param context - Loading context with status and error information
 */
type EarlyAccessFeatureCallback = (
    features: EarlyAccessFeature[],
    context?: { isLoaded: boolean; error?: string }
) => void;

/**
 * Callback invoked when a remote config payload is fetched
 * @param payload - The decrypted remote config payload (JSON value)
 */
type RemoteConfigFeatureFlagCallback = (payload: JsonType) => void;

/**
 * Options for overriding feature flags
 * Can be:
 * - false: Clear all overrides
 * - string[]: Enable list of flags
 * - Record<string, string | boolean>: Set specific flag variants
 * - Object with flags and/or payloads: Full override configuration
 */
type OverrideFeatureFlagsOptions =
    | false                                    // Clear all overrides
    | string[]                                 // Enable list of flags
    | Record<string, string | boolean>         // Set flag variants
    | {
        /**
         * Flag overrides (false to clear, array to enable, object to set variants)
         */
        flags?: false | string[] | Record<string, string | boolean>;

        /**
         * Payload overrides for flags
         */
        payloads?: Record<string, JsonType>;

        /**
         * Suppress override warnings in console
         * @default false
         */
        suppressWarning?: boolean;
    };

/**
 * Callback invoked when surveys are loaded
 * @param surveys - Array of available surveys
 * @param context - Loading context with status and error information
 */
type SurveyCallback = (
    surveys: Survey[],
    context?: { isLoaded: boolean; error?: string }
) => void;

/**
 * Survey object containing all survey data
 */
interface Survey {
    /**
     * Unique survey identifier
     */
    id: string;

    /**
     * Survey name
     */
    name: string;

    /**
     * Survey description
     */
    description: string;

    /**
     * Survey type
     */
    type: SurveyType;

    /**
     * Survey questions
     */
    questions: SurveyQuestion[];

    /**
     * Visual appearance settings
     */
    appearance: SurveyAppearance | null;

    /**
     * Conditions for displaying the survey
     */
    conditions: {
        /**
         * URL pattern to match
         */
        url?: string;

        /**
         * CSS selector to match
         */
        selector?: string;

        /**
         * Events that trigger the survey
         */
        events?: { values: SurveyEventWithFilters[] } | null;

        /**
         * Wait time before showing (days)
         */
        wait_period_days?: number;

        /**
         * Response rate limit
         */
        response_rate_limit?: number;
    } | null;

    /**
     * When survey starts being active
     */
    start_date?: string;

    /**
     * When survey stops being active
     */
    end_date?: string;

    /**
     * Survey targeting configuration
     */
    targeting?: {
        /**
         * Feature flag key for targeting
         */
        flag_key?: string;

        /**
         * Required flag variant
         */
        variant?: string;
    };
}

/**
 * Type of survey display
 */
enum SurveyType {
    /**
     * Popover overlay survey
     */
    Popover = 'popover',

    /**
     * API-only survey (no UI, handle display yourself)
     */
    API = 'api',

    /**
     * Widget survey (e.g., feedback button)
     */
    Widget = 'widget',

    /**
     * External survey (link to external survey tool)
     */
    ExternalSurvey = 'external_survey',
}

/**
 * Union type for all survey question types
 */
type SurveyQuestion =
    | BasicSurveyQuestion
    | LinkSurveyQuestion
    | RatingSurveyQuestion
    | MultipleSurveyQuestion;

/**
 * Open-ended text question
 */
interface BasicSurveyQuestion {
    /**
     * Question type
     */
    type: SurveyQuestionType.Open;

    /**
     * Question text
     */
    question: string;

    /**
     * Additional description or context
     */
    description?: string;

    /**
     * Whether response is required
     */
    required?: boolean;

    /**
     * Placeholder text for input
     */
    placeholder?: string;
}

/**
 * Link or button question
 */
interface LinkSurveyQuestion {
    /**
     * Question type
     */
    type: SurveyQuestionType.Link;

    /**
     * Question text
     */
    question: string;

    /**
     * URL to link to
     */
    link: string;

    /**
     * Button text
     */
    buttonText?: string;
}

/**
 * Rating scale question
 */
interface RatingSurveyQuestion {
    /**
     * Question type
     */
    type: SurveyQuestionType.Rating;

    /**
     * Question text
     */
    question: string;

    /**
     * Additional description or context
     */
    description?: string;

    /**
     * Whether response is required
     */
    required?: boolean;

    /**
     * Maximum rating value
     */
    scale: number;

    /**
     * Label for lowest rating
     */
    lowerBoundLabel?: string;

    /**
     * Label for highest rating
     */
    upperBoundLabel?: string;
}

/**
 * Multiple or single choice question
 */
interface MultipleSurveyQuestion {
    /**
     * Question type
     */
    type: SurveyQuestionType.MultipleChoice | SurveyQuestionType.SingleChoice;

    /**
     * Question text
     */
    question: string;

    /**
     * Additional description or context
     */
    description?: string;

    /**
     * Whether response is required
     */
    required?: boolean;

    /**
     * Available choices
     */
    choices: string[];

    /**
     * Allow custom "Other" option
     */
    hasOpenChoice?: boolean;
}

/**
 * Types of survey questions
 */
enum SurveyQuestionType {
    /**
     * Open text response
     */
    Open = 'open',

    /**
     * Multiple choice (allow multiple selections)
     */
    MultipleChoice = 'multiple_choice',

    /**
     * Single choice (radio buttons)
     */
    SingleChoice = 'single_choice',

    /**
     * Rating scale (e.g., 1-5, 1-10)
     */
    Rating = 'rating',

    /**
     * Link or button
     */
    Link = 'link',
}

/**
 * Position for popover surveys
 */
enum SurveyPosition {
    TopLeft = 'top_left',
    TopRight = 'top_right',
    TopCenter = 'top_center',
    MiddleLeft = 'middle_left',
    MiddleRight = 'middle_right',
    MiddleCenter = 'middle_center',
    BottomLeft = 'bottom_left',
    BottomRight = 'bottom_right',
    BottomCenter = 'bottom_center',
    Left = 'left',
    Center = 'center',
    Right = 'right',

    /**
     * Position next to the trigger element
     */
    NextToTrigger = 'next_to_trigger',
}

/**
 * Visual appearance settings for surveys
 */
interface SurveyAppearance {
    /**
     * Background color (hex or CSS color)
     */
    backgroundColor?: string;

    /**
     * Text color (hex or CSS color)
     */
    textColor?: string;

    /**
     * Submit button text
     */
    submitButtonText?: string;

    /**
     * Submit button color
     */
    submitButtonColor?: string;

    /**
     * Rating button color
     */
    ratingButtonColor?: string;

    /**
     * Border color
     */
    borderColor?: string;

    /**
     * Position on screen
     */
    position?: SurveyPosition;

    /**
     * Placeholder text color
     */
    placeholderTextColor?: string;

    /**
     * Thank you message after submission
     */
    thankYouMessage?: string;

    /**
     * Display thank you message inline or as redirect
     */
    thankYouMessageDisplay?: 'inline' | 'redirect';

    /**
     * URL to redirect to after submission (if redirect)
     */
    thankYouMessageRedirect?: string;

    /**
     * Auto-dismiss after submission (milliseconds)
     */
    autoDismiss?: number;

    /**
     * Width of survey (pixels or percentage)
     */
    width?: string | number;

    /**
     * Max width of survey
     */
    maxWidth?: string | number;

    /**
     * Padding (CSS padding value)
     */
    padding?: string | number;

    /**
     * Border radius (CSS border-radius value)
     */
    borderRadius?: string | number;

    /**
     * Show PostHog branding
     */
    showBranding?: boolean;
}

/**
 * Options for displaying a survey
 */
type DisplaySurveyOptions = DisplaySurveyPopoverOptions | DisplaySurveyInlineOptions;

/**
 * Options for popover display
 */
interface DisplaySurveyPopoverOptions {
    /**
     * Display type
     */
    type: DisplaySurveyType.Popover;

    /**
     * Position on screen
     */
    position?: SurveyPosition;

    /**
     * Background color
     */
    backgroundColor?: string;

    /**
     * Text color
     */
    textColor?: string;

    /**
     * Submit button text
     */
    submitButtonText?: string;

    /**
     * Submit button color
     */
    submitButtonColor?: string;

    /**
     * Rating button color
     */
    ratingButtonColor?: string;

    /**
     * Border color
     */
    borderColor?: string;

    /**
     * Placeholder text
     */
    placeholder?: string;
}

/**
 * Options for inline display
 */
interface DisplaySurveyInlineOptions {
    /**
     * Display type
     */
    type: DisplaySurveyType.Inline;

    /**
     * CSS selector for container element
     */
    selector: string;
}

/**
 * Survey display mode
 */
enum DisplaySurveyType {
    /**
     * Show as popover overlay
     */
    Popover = 'popover',

    /**
     * Show inline in page
     */
    Inline = 'inline',
}

/**
 * Result of checking if survey can be rendered
 */
interface SurveyRenderReason {
    /**
     * Whether the survey can be rendered
     */
    canRender: boolean;

    /**
     * Reason why it can or cannot be rendered
     * Examples: "already_completed", "rate_limited", "conditions_not_met"
     */
    reason: string;
}

/**
 * Built-in survey event names
 */
enum SurveyEventName {
    /**
     * Survey was shown to user
     */
    SHOWN = 'survey shown',

    /**
     * Survey was dismissed without completion
     */
    DISMISSED = 'survey dismissed',

    /**
     * Survey response was submitted
     */
    SENT = 'survey sent',

    /**
     * Survey was abandoned (partially completed)
     */
    ABANDONED = 'survey abandoned',
}

/**
 * Callback invoked when session ID changes
 * @param sessionId - New session ID
 * @param windowId - Window/tab identifier
 */
type SessionIdChangedCallback = (sessionId: string, windowId: string) => void;

/**
 * Configuration for session recording
 */
interface SessionRecordingOptions {
    /**
     * Enable or disable session recording
     * @default undefined (uses server-side config)
     */
    enabled?: boolean;

    /**
     * Mask all input fields
     * @default false
     */
    maskAllInputs?: boolean;

    /**
     * CSS selector for text elements to mask
     */
    maskTextSelector?: string;

    /**
     * CSS selector for elements to completely block from recording
     */
    blockSelector?: string;

    /**
     * Record cross-origin iframes
     * @default false
     */
    recordCrossOriginIframes?: boolean;

    /**
     * Sample rate for session recording (0-1)
     * 0.1 = 10% of sessions recorded
     */
    sampleRate?: number;

    /**
     * Minimum session duration to record (milliseconds)
     */
    minimumDurationMilliseconds?: number;

    /**
     * Feature flag controlling recording
     */
    linkedFlag?: string | FlagVariant;

    /**
     * Enable canvas recording
     * @default false
     */
    recordCanvas?: boolean;

    /**
     * Capture console logs in recordings
     * @default true
     */
    consoleLogRecordingEnabled?: boolean;

    /**
     * Capture network activity
     */
    networkPayloadCapture?: NetworkPayloadCaptureOptions;

    /**
     * Capture performance data
     * @default true
     */
    capturePerformance?: boolean;

    /**
     * URL triggers for recording
     */
    urlTriggers?: string[];

    /**
     * Event triggers for recording
     */
    eventTriggers?: string[];

    /**
     * Mask text content
     * @default false
     */
    maskTextContent?: boolean;

    /**
     * Function to mask captured network requests
     */
    maskCapturedNetworkRequestFn?: (data: NetworkRequest) => NetworkRequest | null;
}

/**
 * Options for capturing network activity
 */
interface NetworkPayloadCaptureOptions {
    /**
     * Record request/response headers
     */
    recordHeaders?: boolean | {
        request: boolean;
        response: boolean;
    };

    /**
     * Record request/response bodies
     * Can specify content types to capture
     */
    recordBody?: boolean | string[] | {
        request: boolean | string[];
        response: boolean | string[];
    };
}

/**
 * Network request data captured during recording
 */
interface NetworkRequest {
    /**
     * Request URL
     */
    url: string;

    /**
     * HTTP method
     */
    method: string;

    /**
     * Request headers
     */
    headers?: Record<string, string>;

    /**
     * Request body
     */
    body?: string;

    /**
     * Response status code
     */
    status?: number;

    /**
     * Response headers
     */
    responseHeaders?: Record<string, string>;

    /**
     * Response body
     */
    responseBody?: string;
}

/**
 * Feature flag variant configuration
 */
interface FlagVariant {
    /**
     * Feature flag key
     */
    flag: string;

    /**
     * Required variant value
     */
    variant: string;
}

/**
 * Web experiment for A/B testing with DOM transformations
 */
interface WebExperiment {
    /**
     * Unique experiment ID
     */
    id: number;

    /**
     * Human-readable experiment name
     */
    name: string;

    /**
     * Optional feature flag key controlling this experiment
     */
    feature_flag_key?: string;

    /**
     * Map of variant names to variant configurations
     */
    variants: Record<string, WebExperimentVariant>;
}

/**
 * A variant configuration within a web experiment
 */
interface WebExperimentVariant {
    /**
     * Display conditions for this variant
     */
    conditions?: WebExperimentConditions;

    /**
     * Variant name (matches feature flag variant value)
     */
    variant_name: string;

    /**
     * List of transformations to apply
     */
    transforms: WebExperimentTransform[];
}

/**
 * Conditions for applying a web experiment variant
 */
interface WebExperimentConditions {
    /**
     * URL matching configuration
     */
    url?: string;

    /**
     * How to match the URL
     */
    urlMatchType?: WebExperimentUrlMatchType;

    /**
     * UTM parameter matching
     */
    utm?: {
        utm_source?: string;
        utm_medium?: string;
        utm_campaign?: string;
        utm_term?: string;
    };
}

/**
 * URL matching types for web experiment conditions
 */
type WebExperimentUrlMatchType =
    | 'regex'         // Regular expression match
    | 'not_regex'     // Inverse regex match
    | 'exact'         // Exact URL match
    | 'is_not'        // URL is not this value
    | 'icontains'     // URL contains substring (case-insensitive)
    | 'not_icontains' // URL does not contain substring
    ;

/**
 * DOM transformation to apply in web experiment
 */
interface WebExperimentTransform {
    /**
     * CSS selector to target elements
     */
    selector?: string;

    /**
     * HTML attributes to set/modify
     */
    attributes?: Array<{ name: string; value: string }>;

    /**
     * Text content to replace
     */
    text?: string;

    /**
     * HTML content to replace
     */
    html?: string;

    /**
     * Image URL to replace
     */
    imgUrl?: string;

    /**
     * CSS styles to apply
     */
    css?: string;
}

/**
 * Callback for web experiments loaded
 */
type WebExperimentsCallback = (webExperiments: WebExperiment[]) => void;

/**
 * Response from a PostHog request
 */
interface RequestResponse {
    /**
     * HTTP status code
     */
    statusCode: number;

    /**
     * HTTP status text
     */
    statusText?: string;

    /**
     * Response body
     */
    body?: string;
}

/**
 * Callback for request completion
 * @param response - HTTP response details
 */
type RequestCallback = (response: RequestResponse) => void;

/**
 * HTTP headers
 */
type Headers = Record<string, string>;

interface PostHogConfig {
    // Core configuration
    api_host?: string;
    token?: string;
    loaded?: (posthog: PostHog) => void;
    name?: string;

    // Event capture
    capture_pageview?: boolean | 'history_change';
    capture_pageleave?: boolean | 'if_capture_pageview';
    autocapture?: boolean | AutocaptureConfig;
    capture_exceptions?: boolean | ExceptionAutoCaptureConfig;

    // Storage & persistence
    persistence?: 'cookie' | 'localStorage' | 'sessionStorage' | 'memory' | 'localStorage+cookie';
    disable_persistence?: boolean;
    cookie_expiration?: number;
    secure_cookie?: boolean;

    // Privacy & consent
    opt_out_capturing_by_default?: boolean;
    opt_out_persistence_by_default?: boolean;
    respect_dnt?: boolean;
    cookieless_mode?: 'never' | 'always' | 'on_reject';
    property_denylist?: string[];

    // Feature flags
    advanced_disable_flags?: boolean;
    advanced_disable_feature_flags_on_first_load?: boolean;
    feature_flag_request_timeout_ms?: number;

    // Session recording
    disable_session_recording?: boolean;
    session_recording?: SessionRecordingOptions;

    // Request configuration
    request_batching?: boolean;
    batch_size?: number;
    batch_max_wait_ms?: number;
    request_headers?: Headers;

    // Advanced
    person_profiles?: 'always' | 'identified_only' | 'never';
    debug?: boolean;
    before_send?: BeforeSendFn;
    mask_all_text?: boolean;
    mask_all_element_attributes?: boolean;

    // ... many more options
}

/**
 * Configuration for automatic event capture
 */
interface AutocaptureConfig {
    /**
     * Capture click events
     * @default true
     */
    capture_clicks?: boolean;

    /**
     * Capture text content of clicked elements
     * @default true
     */
    capture_text_content?: boolean;

    /**
     * CSS selectors to allow for autocapture (only these will be captured)
     */
    element_allowlist?: string[] | undefined;

    /**
     * CSS selectors to exclude from autocapture
     * @default []
     */
    element_denylist?: string[];

    /**
     * Capture rage clicks (rapid repeated clicks)
     * @default true
     */
    rageclicks?: boolean | RageclickConfig;

    /**
     * Capture dead clicks (clicks that don't cause changes)
     * @default false
     */
    dead_clicks?: boolean | DeadClicksAutoCaptureConfig;
}

/**
 * Configuration for rage click detection
 */
interface RageclickConfig {
    /**
     * Number of clicks to trigger rage click
     * @default 3
     */
    threshold?: number;

    /**
     * Time window in milliseconds
     * @default 1000
     */
    window_ms?: number;
}

/**
 * Configuration for dead click detection
 */
interface DeadClicksAutoCaptureConfig {
    /**
     * Enable dead click detection
     * @default true
     */
    enabled?: boolean;

    /**
     * CSS selectors to ignore for dead clicks
     */
    ignore_selectors?: string[];
}

/**
 * Configuration for automatic exception capture
 */
interface ExceptionAutoCaptureConfig {
    /**
     * Capture uncaught errors (window.onerror)
     * @default true
     */
    capture_unhandled_errors?: boolean;

    /**
     * Capture unhandled promise rejections
     * @default true
     */
    capture_unhandled_rejections?: boolean;

    /**
     * Capture console.error calls
     * @default false
     */
    capture_console_errors?: boolean;
}

/**
 * Configuration for bootstrapping the SDK with preloaded data
 */
interface BootstrapConfig {
    /**
     * Preloaded distinct ID
     */
    distinctID?: string;

    /**
     * Preloaded feature flags
     */
    featureFlags?: Record<string, boolean | string>;

    /**
     * Preloaded feature flag payloads
     */
    featureFlagPayloads?: Record<string, JsonType>;

    /**
     * Whether flags have been fully evaluated
     */
    isIdentifiedID?: boolean;
}

/**
 * Product tour configuration
 */
interface ProductTour {
    /**
     * Unique tour identifier
     */
    id: string;

    /**
     * Tour name
     */
    name: string;

    /**
     * Tour description
     */
    description?: string;

    /**
     * Tour type
     */
    type: 'product_tour';

    /**
     * Auto-launch the tour
     */
    auto_launch?: boolean;

    /**
     * Tour steps
     */
    steps: ProductTourStep[];

    /**
     * Display conditions
     */
    conditions?: ProductTourConditions;

    /**
     * Visual appearance
     */
    appearance?: ProductTourAppearance;

    /**
     * Display frequency
     */
    display_frequency?: ProductTourDisplayFrequency;
}

/**
 * Product tour step
 */
interface ProductTourStep {
    /**
     * Step ID
     */
    id: string;

    /**
     * Step type
     */
    type: ProductTourStepType;

    /**
     * CSS selector for target element
     */
    selector?: string;

    /**
     * How user progresses to next step
     */
    progressionTrigger: 'button' | 'click';

    /**
     * Step content (markdown format)
     */
    content: JSONContent | null;

    /**
     * Step content (HTML format)
     */
    contentHtml?: string;

    /**
     * Survey question in step
     */
    survey?: ProductTourSurveyQuestion;

    /**
     * Step buttons
     */
    buttons?: ProductTourStepButtons;

    /**
     * Banner configuration
     */
    bannerConfig?: ProductTourBannerConfig;
}

/**
 * Product tour step type
 */
type ProductTourStepType =
    | 'element'  // Highlight a specific element
    | 'modal'    // Show modal dialog
    | 'survey'   // Show survey question
    | 'banner';  // Show banner

/**
 * Callback for product tour loading
 * @param tours - Array of available product tours
 * @param context - Loading context with status and error information
 */
type ProductTourCallback = (
    tours: ProductTour[],
    context?: { isLoaded: boolean; error?: string }
) => void;

/**
 * Conversations remote configuration
 */
interface ConversationsRemoteConfig {
    /**
     * Whether conversations are enabled
     */
    enabled: boolean;

    /**
     * Whether the widget is enabled
     */
    widgetEnabled?: boolean;

    /**
     * API token for conversations
     */
    token: string;

    /**
     * Greeting text
     */
    greetingText?: string;

    /**
     * Widget color (hex or CSS color)
     */
    color?: string;

    /**
     * Placeholder text for input
     */
    placeholderText?: string;

    /**
     * Require email from users
     */
    requireEmail?: boolean;

    /**
     * Collect user name
     */
    collectName?: boolean;
}

/**
 * Message in conversation
 */
interface Message {
    /**
     * Message ID
     */
    id: string;

    /**
     * Message content
     */
    content: string;

    /**
     * Author type
     */
    author_type: MessageAuthorType;

    /**
     * Author name
     */
    author_name?: string;

    /**
     * Creation timestamp (ISO 8601)
     */
    created_at: string;

    /**
     * Whether message is private (internal note)
     */
    is_private: boolean;
}

/**
 * Message author type
 */
type MessageAuthorType =
    | 'customer'  // Message from customer
    | 'AI'        // Message from AI assistant
    | 'human';    // Message from support agent

/**
 * Support ticket
 */
interface Ticket {
    /**
     * Ticket ID
     */
    id: string;

    /**
     * Ticket status
     */
    status: TicketStatus;

    /**
     * Last message preview
     */
    last_message?: string;

    /**
     * Last message timestamp (ISO 8601)
     */
    last_message_at?: string;

    /**
     * Number of messages in ticket
     */
    message_count: number;

    /**
     * Creation timestamp (ISO 8601)
     */
    created_at: string;

    /**
     * All messages in ticket
     */
    messages?: Message[];

    /**
     * Unread message count
     */
    unread_count?: number;
}

/**
 * Ticket status
 */
type TicketStatus =
    | 'new'       // Newly created ticket
    | 'open'      // Ticket is being worked on
    | 'pending'   // Waiting for customer response
    | 'on_hold'   // Ticket is on hold
    | 'resolved'; // Ticket has been resolved

/**
 * Response after sending a message
 */
interface SendMessageResponse {
    /**
     * Ticket ID
     */
    ticket_id: string;

    /**
     * Message ID
     */
    message_id: string;

    /**
     * Updated ticket status
     */
    ticket_status: TicketStatus;

    /**
     * Creation timestamp (ISO 8601)
     */
    created_at: string;

    /**
     * Unread message count
     */
    unread_count: number;
}

/**
 * Toolbar parameters
 */
interface ToolbarParams {
    /**
     * PostHog API key
     */
    apiKey?: string;

    /**
     * User email for toolbar authentication
     */
    userEmail?: string;

    /**
     * Additional custom parameters
     */
    [key: string]: any;
}

/**
 * Item for the snippet queue
 * Used primarily with the snippet loader
 */
type SnippetArrayItem = [string, ...any[]];

/**
 * Compression algorithm
 */
enum Compression {
    /**
     * GZip compression using JavaScript
     */
    GZipJS = 'gzip-js',

    /**
     * Base64 encoding
     */
    Base64 = 'base64',
}

/**
 * Options for Sentry integration
 */
interface SentryIntegrationOptions {
    /**
     * PostHog instance to integrate with
     */
    posthog?: PostHog;

    /**
     * Organization name in PostHog
     */
    organization?: string;

    /**
     * Project ID in PostHog
     */
    projectId?: number;

    /**
     * Prefix for Sentry issues
     */
    prefix?: string;
}

/**
 * Known PostHog event names
 */
type KnownEventName =
    // Page events
    | '$pageview'
    | '$pageleave'
    | '$autocapture'

    // User events
    | '$identify'
    | '$create_alias'
    | '$set'
    | '$set_once'

    // Group events
    | '$groupidentify'

    // Feature flag events
    | '$feature_flag_called'

    // Survey events
    | '$survey_shown'
    | '$survey_sent'
    | '$survey_dismissed'
    | '$survey_abandoned'

    // Exception events
    | '$exception'

    // Web vitals
    | '$web_vitals'

    // LLM events
    | '$ai_feedback'
    | '$ai_metric'

    // Session events
    | '$session_start'
    | '$session_end'

    // And more...
    ;