/**
 * @youranalytics/web-sdk Type Definitions
 * Comprehensive types for the analytics SDK
 */
/**
 * Unique visitor identifier that persists across sessions.
 * Branded type prevents mixing with other string IDs.
 */
export type VisitorId = string & {
    readonly __brand: 'VisitorId';
};
/**
 * Session identifier that resets on new browser session.
 * Branded type prevents mixing with other string IDs.
 */
export type SessionId = string & {
    readonly __brand: 'SessionId';
};
/**
 * Analytics SDK configuration options.
 * Only `apiKey` is required; all other options have sensible defaults.
 */
export type AnalyticsConfig = {
    /** API key from analytics dashboard (required) */
    readonly apiKey: string;
    /** Analytics server endpoint — override if self-hosting (defaults to the hosted service) */
    readonly endpoint?: string;
    /** Enable debug logging to console */
    readonly debug?: boolean;
    /** Max events before auto-flush */
    readonly maxQueueSize?: number;
    /** Flush interval in milliseconds */
    readonly flushInterval?: number;
    /** Auto-track page views on initialization and navigation */
    readonly autoTrack?: boolean;
    /** Enable adaptive network behavior (adjusts batching based on connection quality) */
    readonly adaptiveNetwork?: boolean;
    /** Rewrite the page URL before it is stored on an event (e.g. strip ids, tokens, query) */
    readonly sanitizeUrl?: (url: string) => string;
    /** Use this visitor ID instead of the generated one (not written to storage) */
    readonly visitorId?: string;
};
/**
 * Resolved configuration with all defaults applied.
 * Used internally after merging user config with defaults.
 */
export type ResolvedConfig = {
    readonly apiKey: string;
    readonly endpoint: string;
    readonly debug: boolean;
    readonly maxQueueSize: number;
    readonly flushInterval: number;
    readonly autoTrack: boolean;
    readonly adaptiveNetwork: boolean;
    readonly sanitizeUrl?: (url: string) => string;
};
/**
 * UTM parameters for campaign tracking.
 * Extracted from URL query parameters.
 */
export type UtmParams = {
    /** Traffic source (e.g., 'google', 'newsletter') */
    readonly source?: string;
    /** Marketing medium (e.g., 'cpc', 'email') */
    readonly medium?: string;
    /** Campaign name */
    readonly campaign?: string;
    /** Paid search keyword */
    readonly term?: string;
    /** Ad content identifier */
    readonly content?: string;
};
/**
 * Raw event as sent to the analytics server.
 * Contains all tracking data including context.
 */
export type RawEvent = {
    /** Event name (e.g., 'pageview', 'click', 'signup') */
    readonly event: string;
    /** Custom event properties */
    readonly properties: Record<string, unknown>;
    /** Client timestamp (milliseconds since epoch) */
    readonly timestamp: number;
    /** Unique visitor identifier (persists across sessions) */
    readonly visitor_id: string;
    /** Session identifier (resets on new browser session) */
    readonly session_id: string;
    /** Current page URL */
    readonly page_url: string;
    /** Page title */
    readonly page_title?: string;
    /** Referrer URL */
    readonly referrer?: string;
    /** User agent string */
    readonly user_agent: string;
    /** Screen width in pixels */
    readonly screen_width: number;
    /** Screen height in pixels */
    readonly screen_height: number;
    /** UTM parameters if present */
    readonly utm?: UtmParams;
};
/**
 * Queued event waiting to be flushed.
 * Page URL and title are captured at track time; other context is added at flush time.
 */
export type QueuedEvent = {
    /** Event name */
    readonly event: string;
    /** Custom event properties */
    readonly properties: Record<string, unknown>;
    /** Timestamp when event was queued */
    readonly timestamp: number;
    /** Page URL when the event was tracked (already sanitized) */
    readonly page_url?: string;
    /** Page title when the event was tracked */
    readonly page_title?: string;
};
/**
 * Network connection type as reported by the Network Information API.
 * Used for adaptive batching strategies.
 */
export type ConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'unknown';
/**
 * Network information for adaptive behavior.
 * Based on the Network Information API.
 */
export type NetworkInfo = {
    /** Effective connection type */
    readonly effectiveType: ConnectionType;
    /** Downlink speed in Mbps */
    readonly downlink?: number;
    /** Round-trip time in milliseconds */
    readonly rtt?: number;
    /** Whether the user has enabled data saver mode */
    readonly saveData?: boolean;
};
/**
 * Batch of events sent to the server.
 * Includes API key for authentication.
 */
export type EventBatch = {
    /** API key for authentication */
    readonly api_key: string;
    /** Array of events in this batch */
    readonly events: readonly RawEvent[];
};
/**
 * Adaptive settings computed based on network conditions.
 * Adjusts SDK behavior for optimal performance.
 */
export type AdaptiveSettings = {
    /** Maximum events to queue before forcing a flush */
    readonly maxQueueSize: number;
    /** Interval between automatic flushes in milliseconds */
    readonly flushInterval: number;
    /** Whether to compress event payloads */
    readonly compressionEnabled: boolean;
};
/**
 * SDK internal state.
 */
export type SdkState = {
    /** Whether the SDK has been initialized */
    initialized: boolean;
    /** Current event queue */
    queue: QueuedEvent[];
    /** Flush timer ID */
    flushTimerId: ReturnType<typeof setTimeout> | null;
    /** Current visitor ID */
    visitorId: VisitorId | null;
    /** Current session ID */
    sessionId: SessionId | null;
};
/**
 * Check if a value is a valid UTM params object.
 */
export declare function isValidUtmParams(value: unknown): value is UtmParams;
/**
 * Check if a value is a valid RawEvent.
 * Performs runtime validation of event structure.
 */
export declare function isValidEvent(value: unknown): value is RawEvent;
/**
 * Check if a value is a valid AnalyticsConfig.
 */
export declare function isValidConfig(value: unknown): value is AnalyticsConfig;
/**
 * Check if a value is a valid QueuedEvent.
 */
export declare function isValidQueuedEvent(value: unknown): value is QueuedEvent;
/**
 * Create a branded VisitorId from a string.
 * Use this when generating or parsing visitor IDs.
 */
export declare function createVisitorId(id: string): VisitorId;
/**
 * Create a branded SessionId from a string.
 * Use this when generating or parsing session IDs.
 */
export declare function createSessionId(id: string): SessionId;
/**
 * Default configuration values.
 */
export declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'apiKey' | 'endpoint'>;
//# sourceMappingURL=types.d.ts.map