@kitbase/analytics 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,1242 @@
+/**
+ * Configuration options for offline event queueing
+ */
+interface OfflineConfig {
+    /**
+     * Enable offline queueing
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of events to store in the queue
+     * Oldest events are dropped when limit is reached
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * Interval in milliseconds to flush queued events when online
+     * @default 30000 (30 seconds)
+     */
+    flushInterval?: number;
+    /**
+     * Number of events to send per batch when flushing
+     * @default 50
+     */
+    flushBatchSize?: number;
+    /**
+     * Maximum number of retry attempts for failed events
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff
+     * @default 1000 (1 second)
+     */
+    retryBaseDelay?: number;
+}
+/**
+ * A queued event stored in the database
+ */
+interface QueuedEvent {
+    /**
+     * Auto-incremented unique identifier
+     */
+    id?: number;
+    /**
+     * The event payload to send
+     */
+    payload: LogPayload;
+    /**
+     * Timestamp when the event was queued (ms since epoch)
+     */
+    timestamp: number;
+    /**
+     * Number of retry attempts made
+     */
+    retries: number;
+    /**
+     * Timestamp of the last retry attempt (ms since epoch)
+     */
+    lastAttempt?: number;
+}
+/**
+ * Statistics about the event queue
+ */
+interface QueueStats {
+    /**
+     * Number of events currently in the queue
+     */
+    size: number;
+    /**
+     * Oldest event timestamp in the queue
+     */
+    oldestEvent?: number;
+    /**
+     * Whether the queue is currently flushing
+     */
+    isFlushing: boolean;
+}
+
+/**
+ * Bot detection module for filtering automated traffic
+ *
+ * Detects common automation tools, headless browsers, and bot user agents.
+ * Inspired by DataFast's bot detection approach.
+ */
+/**
+ * Bot detection result
+ * @internal This is an internal API and may change without notice.
+ */
+interface BotDetectionResult {
+    isBot: boolean;
+    reason?: string;
+    checks: {
+        webdriver: boolean;
+        phantomjs: boolean;
+        nightmare: boolean;
+        automationGlobals: boolean;
+        documentAttributes: boolean;
+        userAgentHeadless: boolean;
+        userAgentHttpClient: boolean;
+        missingUserAgent: boolean;
+        invalidEnvironment: boolean;
+    };
+}
+/**
+ * Configuration for bot detection
+ * @internal This is an internal API and may change without notice.
+ */
+interface BotDetectionConfig {
+    /**
+     * Enable bot detection.
+     * When enabled and a bot is detected, all tracking events are blocked.
+     * Set to false to disable bot detection.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Check for webdriver flag (Chrome, Firefox)
+     * @default true
+     */
+    checkWebdriver?: boolean;
+    /**
+     * Check for PhantomJS
+     * @default true
+     */
+    checkPhantomJS?: boolean;
+    /**
+     * Check for Nightmare.js
+     * @default true
+     */
+    checkNightmare?: boolean;
+    /**
+     * Check for automation tool globals
+     * @default true
+     */
+    checkAutomationGlobals?: boolean;
+    /**
+     * Check document element attributes
+     * @default true
+     */
+    checkDocumentAttributes?: boolean;
+    /**
+     * Check user agent for headless browsers
+     * @default true
+     */
+    checkUserAgentHeadless?: boolean;
+    /**
+     * Check user agent for HTTP clients/bots
+     * @default true
+     */
+    checkUserAgentHttpClient?: boolean;
+    /**
+     * Additional user agent patterns to detect as bots
+     */
+    additionalBotPatterns?: string[];
+    /**
+     * Callback when a bot is detected
+     */
+    onBotDetected?: (result: BotDetectionResult) => void;
+}
+/**
+ * Detect if the current visitor is a bot
+ *
+ * @internal This is an internal API and may change without notice.
+ * @param config - Bot detection configuration
+ * @returns Bot detection result
+ *
+ * @example
+ * ```typescript
+ * const result = detectBot();
+ * if (result.isBot) {
+ *   console.log('Bot detected:', result.reason);
+ * }
+ * ```
+ */
+declare function detectBot(config?: BotDetectionConfig): BotDetectionResult;
+/**
+ * Quick check if current visitor is a bot
+ *
+ * @internal This is an internal API and may change without notice.
+ * @param config - Bot detection configuration
+ * @returns true if bot detected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isBot()) {
+ *   console.log('Bot detected, skipping tracking');
+ *   return;
+ * }
+ * ```
+ */
+declare function isBot(config?: BotDetectionConfig): boolean;
+/**
+ * Check a custom user agent string for bot patterns
+ * Useful for server-side bot detection
+ *
+ * @internal This is an internal API and may change without notice.
+ * @param userAgent - The user agent string to check
+ * @param additionalPatterns - Additional patterns to check
+ * @returns true if bot user agent detected
+ *
+ * @example
+ * ```typescript
+ * // Server-side usage
+ * const ua = request.headers['user-agent'];
+ * if (isUserAgentBot(ua)) {
+ *   console.log('Bot request detected');
+ * }
+ * ```
+ */
+declare function isUserAgentBot(userAgent: string, additionalPatterns?: string[]): boolean;
+/**
+ * Get the current user agent (browser only)
+ *
+ * @internal This is an internal API and may change without notice.
+ * @returns User agent string or null if not in browser
+ */
+declare function getUserAgent(): string | null;
+
+/**
+ * Configuration options for the Kitbase client
+ */
+interface KitbaseConfig {
+    /**
+     * Your Kitbase SDK key (sent as the `x-sdk-key` HTTP header)
+     */
+    sdkKey: string;
+    /**
+     * Override the default API endpoint.
+     * @default 'https://api.kitbase.dev'
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug mode for console logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Offline queueing configuration.
+     * Events are queued locally when offline or when the API fails,
+     * and automatically sent when back online.
+     */
+    offline?: OfflineConfig;
+    /**
+     * Analytics tracking configuration.
+     * Enables pageview tracking and revenue tracking.
+     */
+    analytics?: AnalyticsConfig$1;
+    /**
+     * Bot detection configuration.
+     * When enabled, detects automated traffic and can block tracking for bots.
+     * @internal This is an internal API and may change without notice.
+     */
+    botDetection?: BotDetectionConfig;
+}
+/**
+ * Tag values can be strings, numbers, or booleans
+ */
+type TagValue$1 = string | number | boolean;
+/**
+ * Event tags for additional metadata
+ */
+type Tags$1 = Record<string, TagValue$1>;
+/**
+ * Options for tracking an event
+ */
+interface TrackOptions$1 {
+    /**
+     * The channel/category for the event
+     * @example 'payments', 'auth', 'users'
+     */
+    channel: string;
+    /**
+     * The name of the event
+     * @example 'New Subscription', 'User Signed Up'
+     */
+    event: string;
+    /**
+     * Optional user identifier (set when user is identified/logged in)
+     */
+    user_id?: string;
+    /**
+     * Icon for the event (emoji or icon name)
+     * @example '💰', 'money_bag'
+     */
+    icon?: string;
+    /**
+     * Whether to send a notification for this event
+     * @default false
+     */
+    notify?: boolean;
+    /**
+     * Optional description for the event
+     */
+    description?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags$1;
+}
+/**
+ * Response from the track API
+ */
+interface TrackResponse$1 {
+    /**
+     * Unique identifier for the logged event
+     */
+    id: string;
+    /**
+     * The event name
+     */
+    event: string;
+    /**
+     * Server timestamp when the event was recorded
+     */
+    timestamp: string;
+}
+/**
+ * Internal request payload sent to the API
+ */
+interface LogPayload {
+    channel: string;
+    event: string;
+    user_id?: string;
+    icon?: string;
+    notify?: boolean;
+    description?: string;
+    tags?: Tags$1;
+    /**
+     * Client-side timestamp (ms since epoch) when the event occurred.
+     * Always set by the SDK for both online and offline events.
+     */
+    client_timestamp: number;
+    /**
+     * Client-generated session UUID, rotated after 30min of inactivity.
+     * Used by the server for offline session reconstruction.
+     */
+    client_session_id: string;
+}
+/**
+ * Configuration for analytics tracking
+ */
+interface AnalyticsConfig$1 {
+    /**
+     * Enable automatic pageview tracking on route changes
+     * @default true
+     */
+    autoTrackPageViews?: boolean;
+    /**
+     * Enable automatic outbound link click tracking
+     * Tracks when users click links to external domains
+     * @default true
+     */
+    autoTrackOutboundLinks?: boolean;
+    /**
+     * Track clicks on interactive elements (buttons, links, inputs)
+     * @default true
+     */
+    autoTrackClicks?: boolean;
+    /**
+     * Track max scroll depth per page (sent on navigation)
+     * @default true
+     */
+    autoTrackScrollDepth?: boolean;
+    /**
+     * Track visibility duration of elements with `data-kb-track-visibility` attribute.
+     * Uses IntersectionObserver to measure how long elements are visible in the viewport.
+     * @default true
+     */
+    autoTrackVisibility?: boolean;
+    /**
+     * Track Core Web Vitals (LCP, CLS, INP, FCP, TTFB).
+     * Collects all metrics and sends them as a single `web_vitals` event.
+     * Requires the `web-vitals` library (included as a dependency).
+     * @default false
+     */
+    autoTrackWebVitals?: boolean;
+    /**
+     * Detect frustration signals (rage clicks and dead clicks).
+     * Rage clicks: 3+ rapid clicks in the same area within 1 second.
+     * Dead clicks: clicks on interactive elements that produce no DOM change.
+     * @default true
+     */
+    autoDetectFrustration?: boolean;
+}
+/**
+ * Options for tracking a pageview
+ */
+interface PageViewOptions$1 {
+    /**
+     * The page path (defaults to window.location.pathname)
+     */
+    path?: string;
+    /**
+     * The page title (defaults to document.title)
+     */
+    title?: string;
+    /**
+     * The referrer URL
+     */
+    referrer?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags$1;
+}
+/**
+ * Options for tracking revenue
+ */
+interface RevenueOptions {
+    /**
+     * Revenue amount in cents (e.g., 1999 for $19.99)
+     */
+    amount: number;
+    /**
+     * Currency code (e.g., 'USD', 'EUR')
+     * @default 'USD'
+     */
+    currency?: string;
+    /**
+     * Optional user identifier
+     */
+    user_id?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags$1;
+}
+/**
+ * Options for identifying a user
+ */
+interface IdentifyOptions {
+    /**
+     * The unique user identifier
+     */
+    userId: string;
+    /**
+     * User traits/properties
+     */
+    traits?: Tags$1;
+}
+
+/**
+ * Configuration options for the Kitbase lite client (without offline queue)
+ */
+interface KitbaseLiteConfig {
+    /**
+     * Your Kitbase SDK key (sent as the `x-sdk-key` HTTP header)
+     */
+    sdkKey: string;
+    /**
+     * Override the default API endpoint.
+     * @default 'https://api.kitbase.dev'
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug mode for console logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Analytics tracking configuration.
+     * Enables pageview tracking and revenue tracking.
+     */
+    analytics?: AnalyticsConfig;
+    /**
+     * Bot detection configuration.
+     * When enabled, detects automated traffic and can block tracking for bots.
+     * @internal This is an internal API and may change without notice.
+     */
+    botDetection?: BotDetectionConfig;
+}
+/**
+ * Tag values can be strings, numbers, or booleans
+ */
+type TagValue = string | number | boolean;
+/**
+ * Event tags for additional metadata
+ */
+type Tags = Record<string, TagValue>;
+/**
+ * Options for tracking an event
+ */
+interface TrackOptions {
+    /**
+     * The channel/category for the event
+     * @example 'payments', 'auth', 'users'
+     */
+    channel: string;
+    /**
+     * The name of the event
+     * @example 'New Subscription', 'User Signed Up'
+     */
+    event: string;
+    /**
+     * Optional user identifier (set when user is identified/logged in)
+     */
+    user_id?: string;
+    /**
+     * Icon for the event (emoji or icon name)
+     * @example '💰', 'money_bag'
+     */
+    icon?: string;
+    /**
+     * Whether to send a notification for this event
+     * @default false
+     */
+    notify?: boolean;
+    /**
+     * Optional description for the event
+     */
+    description?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags;
+}
+/**
+ * Response from the track API
+ */
+interface TrackResponse {
+    /**
+     * Unique identifier for the logged event
+     */
+    id: string;
+    /**
+     * The event name
+     */
+    event: string;
+    /**
+     * Server timestamp when the event was recorded
+     */
+    timestamp: string;
+}
+/**
+ * Configuration for analytics tracking
+ */
+interface AnalyticsConfig {
+    /**
+     * Enable automatic pageview tracking on route changes
+     * @default true
+     */
+    autoTrackPageViews?: boolean;
+    /**
+     * Enable automatic outbound link click tracking
+     * Tracks when users click links to external domains
+     * @default true
+     */
+    autoTrackOutboundLinks?: boolean;
+    /**
+     * Track clicks on interactive elements (buttons, links, inputs)
+     * @default true
+     */
+    autoTrackClicks?: boolean;
+    /**
+     * Track max scroll depth per page (sent on navigation)
+     * @default true
+     */
+    autoTrackScrollDepth?: boolean;
+    /**
+     * Track visibility duration of elements with `data-kb-track-visibility` attribute.
+     * Uses IntersectionObserver to measure how long elements are visible in the viewport.
+     * @default true
+     */
+    autoTrackVisibility?: boolean;
+    /**
+     * Track Core Web Vitals (LCP, CLS, INP, FCP, TTFB).
+     * Collects all metrics and sends them as a single `web_vitals` event.
+     * Requires the `web-vitals` library (included as a dependency).
+     * @default false
+     */
+    autoTrackWebVitals?: boolean;
+    /**
+     * Detect frustration signals (rage clicks and dead clicks).
+     * Rage clicks: 3+ rapid clicks in the same area within 1 second.
+     * Dead clicks: clicks on interactive elements that produce no DOM change.
+     * @default true
+     */
+    autoDetectFrustration?: boolean;
+}
+/**
+ * Options for tracking a pageview
+ */
+interface PageViewOptions {
+    /**
+     * The page path (defaults to window.location.pathname)
+     */
+    path?: string;
+    /**
+     * The page title (defaults to document.title)
+     */
+    title?: string;
+    /**
+     * The referrer URL
+     */
+    referrer?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags;
+}
+
+interface KitbasePlugin {
+    readonly name: string;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    methods?: Record<string, (...args: any[]) => any>;
+}
+interface PluginContext {
+    track(options: TrackOptions): Promise<TrackResponse | void>;
+    readonly config: Readonly<AnalyticsConfig>;
+    readonly debug: boolean;
+    log(message: string, data?: unknown): void;
+    isBotBlockingActive(): boolean;
+    findClickableElement(event: MouseEvent): Element | null;
+    readonly CLICKABLE_SELECTOR: string;
+    getRootDomain(hostname: string): string;
+    isSameRootDomain(host1: string, host2: string): boolean;
+    getUtmParams(): Tags;
+}
+
+/**
+ * Kitbase base client for tracking events (lite version without offline queue)
+ *
+ * This is a lightweight version of the Kitbase client that sends events
+ * directly to the API without offline queueing support.
+ *
+ * @example
+ * ```typescript
+ * import { Kitbase } from '@kitbase/analytics/lite';
+ *
+ * const kitbase = new Kitbase({
+ *   sdkKey: '<YOUR_API_KEY>',
+ *   debug: true,
+ * });
+ *
+ * // Register super properties (included in all events)
+ * kitbase.register({ app_version: '2.1.0', platform: 'web' });
+ *
+ * // Track events
+ * await kitbase.track({
+ *   channel: 'payments',
+ *   event: 'Page Viewed',
+ *   icon: '👀',
+ * });
+ * ```
+ */
+declare class KitbaseAnalytics$1 {
+    protected readonly sdkKey: string;
+    protected readonly baseUrl: string;
+    protected superProperties: Tags$1;
+    protected timedEvents: Map<string, number>;
+    protected debugMode: boolean;
+    protected analyticsConfig: KitbaseLiteConfig['analytics'];
+    protected userId: string | null;
+    protected botDetectionConfig: BotDetectionConfig;
+    protected botDetectionResult: BotDetectionResult | null;
+    private clientSessionId;
+    private lastActivityAt;
+    private static readonly SESSION_TIMEOUT_MS;
+    private _plugins;
+    private _pluginContext;
+    constructor(config: KitbaseLiteConfig, defaultPlugins?: KitbasePlugin[]);
+    /**
+     * Register a plugin
+     *
+     * @param plugin - The plugin instance to register
+     *
+     * @example
+     * ```typescript
+     * kitbase.use(new WebVitalsPlugin());
+     * ```
+     */
+    use(plugin: KitbasePlugin): void;
+    /**
+     * Get the names of all registered plugins
+     */
+    getPlugins(): string[];
+    private getPluginContext;
+    /**
+     * Enable or disable debug mode
+     * When enabled, all SDK operations are logged to the console
+     *
+     * @param enabled - Whether to enable debug mode
+     *
+     * @example
+     * ```typescript
+     * kitbase.setDebugMode(true);
+     * // All events and operations will now be logged
+     * ```
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Check if debug mode is enabled
+     */
+    isDebugMode(): boolean;
+    /**
+     * Internal logging function
+     */
+    protected log(message: string, data?: unknown): void;
+    /**
+     * Register super properties that will be included with every event
+     * These properties are stored in memory only and reset on page reload
+     *
+     * @param properties - Properties to register
+     *
+     * @example
+     * ```typescript
+     * kitbase.register({
+     *   app_version: '2.1.0',
+     *   platform: 'web',
+     *   environment: 'production',
+     * });
+     * ```
+     */
+    register(properties: Tags$1): void;
+    /**
+     * Register super properties only if they haven't been set yet
+     * Useful for setting default values that shouldn't override existing ones
+     *
+     * @param properties - Properties to register if not already set
+     *
+     * @example
+     * ```typescript
+     * kitbase.registerOnce({ first_visit: new Date().toISOString() });
+     * ```
+     */
+    registerOnce(properties: Tags$1): void;
+    /**
+     * Remove a super property
+     *
+     * @param key - The property key to remove
+     *
+     * @example
+     * ```typescript
+     * kitbase.unregister('platform');
+     * ```
+     */
+    unregister(key: string): void;
+    /**
+     * Get all registered super properties
+     *
+     * @returns A copy of the current super properties
+     *
+     * @example
+     * ```typescript
+     * const props = kitbase.getSuperProperties();
+     * console.log(props); // { app_version: '2.1.0', platform: 'web' }
+     * ```
+     */
+    getSuperProperties(): Tags$1;
+    /**
+     * Clear all super properties
+     *
+     * @example
+     * ```typescript
+     * kitbase.clearSuperProperties();
+     * ```
+     */
+    clearSuperProperties(): void;
+    /**
+     * Start timing an event
+     * When the same event is tracked later, a $duration property (in seconds)
+     * will automatically be included
+     *
+     * @param eventName - The name of the event to time
+     *
+     * @example
+     * ```typescript
+     * kitbase.timeEvent('Video Watched');
+     * // ... user watches video ...
+     * await kitbase.track({
+     *   channel: 'engagement',
+     *   event: 'Video Watched',
+     *   tags: { video_id: '123' }
+     * });
+     * // Event will include $duration: 45.2 (seconds)
+     * ```
+     */
+    timeEvent(eventName: string): void;
+    /**
+     * Cancel a timed event without tracking it
+     *
+     * @param eventName - The name of the event to cancel timing for
+     *
+     * @example
+     * ```typescript
+     * kitbase.timeEvent('Checkout Flow');
+     * // User abandons checkout
+     * kitbase.cancelTimeEvent('Checkout Flow');
+     * ```
+     */
+    cancelTimeEvent(eventName: string): void;
+    /**
+     * Get all currently timed events
+     *
+     * @returns Array of event names that are currently being timed
+     *
+     * @example
+     * ```typescript
+     * const timedEvents = kitbase.getTimedEvents();
+     * console.log(timedEvents); // ['Video Watched', 'Checkout Flow']
+     * ```
+     */
+    getTimedEvents(): string[];
+    /**
+     * Get the duration of a timed event (without stopping it)
+     * @internal
+     *
+     * @param eventName - The name of the event
+     * @returns Duration in seconds, or null if not being timed
+     */
+    getEventDuration(eventName: string): number | null;
+    /**
+     * Check if the current visitor is detected as a bot
+     *
+     * @internal This is an internal API and may change without notice.
+     * @returns true if bot detected, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (kitbase.isBot()) {
+     *   console.log('Bot detected, tracking disabled');
+     * }
+     * ```
+     */
+    isBot(): boolean;
+    /**
+     * Get detailed bot detection result
+     *
+     * @internal This is an internal API and may change without notice.
+     * @returns Bot detection result with detailed checks, or null if detection not enabled
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.getBotDetectionResult();
+     * if (result?.isBot) {
+     *   console.log('Bot detected:', result.reason);
+     *   console.log('Checks:', result.checks);
+     * }
+     * ```
+     */
+    getBotDetectionResult(): BotDetectionResult | null;
+    /**
+     * Force re-run bot detection
+     * Useful if you want to check again after page state changes
+     *
+     * @internal This is an internal API and may change without notice.
+     * @returns Updated bot detection result
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.redetectBot();
+     * console.log('Is bot:', result.isBot);
+     * ```
+     */
+    redetectBot(): BotDetectionResult;
+    /**
+     * Check if bot blocking is currently active
+     * When bot detection is enabled and a bot is detected, all events are blocked.
+     *
+     * @internal This is an internal API and may change without notice.
+     * @returns true if bots are being blocked from tracking
+     */
+    isBotBlockingActive(): boolean;
+    /**
+     * Get or create a client-side session ID.
+     * Rotates the session after 30 minutes of inactivity.
+     * @internal
+     */
+    protected getClientSessionId(): string;
+    /**
+     * Generate a UUID v4, with fallback for environments where
+     * crypto.randomUUID() is not available (older WebViews, Ionic).
+     */
+    private static generateUUID;
+    /**
+     * Track an event
+     *
+     * Events are sent directly to the API. For offline queueing support,
+     * use the full Kitbase client instead.
+     *
+     * @param options - Event tracking options
+     * @returns Promise resolving to the track response, or void if tracking is blocked
+     * @throws {ValidationError} When required fields are missing
+     * @throws {AuthenticationError} When the API key is invalid
+     * @throws {ApiError} When the API returns an error
+     * @throws {TimeoutError} When the request times out
+     */
+    track(options: TrackOptions$1): Promise<TrackResponse$1 | void>;
+    protected validateTrackOptions(options: TrackOptions$1): void;
+    /**
+     * Send a request to the API
+     */
+    protected sendRequest<T>(endpoint: string, body: unknown): Promise<T>;
+    protected parseResponseBody(response: Response): Promise<unknown>;
+    protected getErrorMessage(body: unknown, fallback: string): string;
+    /**
+     * Track a page view
+     *
+     * @param options - Page view options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * // Track current page
+     * await kitbase.trackPageView();
+     *
+     * // Track with custom path
+     * await kitbase.trackPageView({ path: '/products/123', title: 'Product Details' });
+     * ```
+     */
+    trackPageView(options?: PageViewOptions$1): Promise<TrackResponse$1 | void>;
+    /**
+     * Track a click on an interactive element
+     */
+    trackClick(tags: Tags$1): Promise<TrackResponse$1 | void>;
+    /**
+     * Track an outbound link click
+     *
+     * @param options - Outbound link options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * await kitbase.trackOutboundLink({
+     *   url: 'https://example.com',
+     *   text: 'Visit Example',
+     * });
+     * ```
+     */
+    trackOutboundLink(options: {
+        url: string;
+        text?: string;
+    }): Promise<TrackResponse$1 | void>;
+    /**
+     * Track a revenue event
+     *
+     * @param options - Revenue options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * // Track a $19.99 purchase
+     * await kitbase.trackRevenue({
+     *   amount: 1999,
+     *   currency: 'USD',
+     *   tags: { product_id: 'prod_123', plan: 'premium' },
+     * });
+     * ```
+     */
+    trackRevenue(options: RevenueOptions): Promise<TrackResponse$1 | void>;
+    /**
+     * Identify a user
+     * Sets the user identity on the server.
+     * Call this when a user signs up or logs in.
+     *
+     * @param options - Identify options
+     * @returns Promise that resolves when the identity is set
+     *
+     * @example
+     * ```typescript
+     * await kitbase.identify({
+     *   userId: 'user_123',
+     *   traits: { email: 'user@example.com', plan: 'premium' },
+     * });
+     * ```
+     */
+    identify(options: IdentifyOptions): Promise<void>;
+    /**
+     * Get the current user ID (set via identify)
+     */
+    getUserId(): string | null;
+    /**
+     * Reset the user identity
+     * Call this when a user logs out
+     *
+     * @example
+     * ```typescript
+     * kitbase.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Shutdown the client and cleanup resources
+     * Call this when you're done using the client to stop timers and close connections
+     *
+     * @example
+     * ```typescript
+     * kitbase.shutdown();
+     * ```
+     */
+    shutdown(): void;
+}
+
+/**
+ * Initialize the Kitbase Analytics SDK
+ *
+ * Creates a singleton instance that is used for all tracking.
+ * Call this once at the top of your application entry point.
+ *
+ * @param config - SDK configuration
+ * @returns The KitbaseAnalytics instance
+ *
+ * @example
+ * ```typescript
+ * import { init } from '@kitbase/analytics';
+ *
+ * init({
+ *   sdkKey: '<YOUR_API_KEY>',
+ *   debug: true,
+ *   offline: { enabled: true },
+ * });
+ * ```
+ */
+declare function init(config: KitbaseConfig): KitbaseAnalytics;
+/**
+ * Get the current KitbaseAnalytics singleton instance
+ *
+ * @returns The instance, or null if `init()` has not been called
+ */
+declare function getInstance(): KitbaseAnalytics | null;
+declare class KitbaseAnalytics extends KitbaseAnalytics$1 {
+    private queue;
+    private offlineEnabled;
+    constructor(config: KitbaseConfig);
+    /**
+     * Enable or disable debug mode
+     * When enabled, all SDK operations are logged to the console
+     *
+     * @param enabled - Whether to enable debug mode
+     *
+     * @example
+     * ```typescript
+     * kitbase.setDebugMode(true);
+     * // All events and operations will now be logged
+     * ```
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Get offline queue statistics
+     *
+     * @returns Queue statistics including size and flush status
+     *
+     * @example
+     * ```typescript
+     * const stats = await kitbase.getQueueStats();
+     * console.log(stats); // { size: 5, isFlushing: false }
+     * ```
+     */
+    getQueueStats(): Promise<QueueStats | null>;
+    /**
+     * Manually flush the offline queue
+     * Events are automatically flushed on interval and when coming back online,
+     * but this method can be used to trigger an immediate flush
+     *
+     * @example
+     * ```typescript
+     * await kitbase.flushQueue();
+     * ```
+     */
+    flushQueue(): Promise<void>;
+    /**
+     * Clear all events from the offline queue
+     *
+     * @example
+     * ```typescript
+     * await kitbase.clearQueue();
+     * ```
+     */
+    clearQueue(): Promise<void>;
+    /**
+     * Callback for the queue to send batched events via the batch endpoint.
+     * Sends all events in a single HTTP request instead of individual POSTs.
+     */
+    private sendQueuedEvents;
+    /**
+     * Track an event
+     *
+     * When offline queueing is enabled, events are always written to the local
+     * database first (write-ahead), then sent to the server. This ensures no
+     * events are lost if the browser crashes or the network fails.
+     *
+     * @param options - Event tracking options
+     * @returns Promise resolving to the track response, or void if tracking is blocked
+     * @throws {ValidationError} When required fields are missing
+     * @throws {AuthenticationError} When the API key is invalid (only when offline disabled)
+     * @throws {ApiError} When the API returns an error (only when offline disabled)
+     * @throws {TimeoutError} When the request times out (only when offline disabled)
+     */
+    track(options: TrackOptions$1): Promise<TrackResponse$1 | void>;
+    protected validateTrackOptions(options: TrackOptions$1): void;
+    /**
+     * Shutdown the client and cleanup resources
+     * Call this when you're done using the client to stop timers and close connections
+     *
+     * @example
+     * ```typescript
+     * await kitbase.shutdown();
+     * ```
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Base error class for Kitbase SDK errors
+ */
+declare class KitbaseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when API authentication fails
+ */
+declare class AuthenticationError extends KitbaseError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the API request fails
+ */
+declare class ApiError extends KitbaseError {
+    readonly statusCode: number;
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when request validation fails
+ */
+declare class ValidationError extends KitbaseError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when a request times out
+ */
+declare class TimeoutError extends KitbaseError {
+    constructor(message?: string);
+}
+
+/**
+ * Create the default set of plugins based on analytics configuration.
+ * Reads config flags and instantiates only the enabled plugins.
+ */
+declare function createDefaultPlugins(config?: AnalyticsConfig): KitbasePlugin[];
+
+declare class PageViewPlugin implements KitbasePlugin {
+    readonly name = "page-view";
+    private ctx;
+    private active;
+    private popstateListener;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    get methods(): {
+        trackPageView: (options?: PageViewOptions) => Promise<TrackResponse | void>;
+    };
+    private trackPageView;
+}
+
+declare class OutboundLinksPlugin implements KitbasePlugin {
+    readonly name = "outbound-links";
+    private ctx;
+    private clickListener;
+    private keydownListener;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    get methods(): {
+        trackOutboundLink: (options: {
+            url: string;
+            text?: string;
+        }) => Promise<TrackResponse | void>;
+    };
+    private handleLinkClick;
+    private trackOutboundLink;
+}
+
+declare class ClickTrackingPlugin implements KitbasePlugin {
+    readonly name = "click-tracking";
+    private ctx;
+    private clickListener;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    get methods(): {
+        trackClick: (tags: Tags) => Promise<TrackResponse | void>;
+    };
+    private trackClick;
+}
+
+declare class ScrollDepthPlugin implements KitbasePlugin {
+    readonly name = "scroll-depth";
+    private ctx;
+    private active;
+    private maxScrollDepth;
+    private scrollListener;
+    private beforeUnloadListener;
+    private popstateListener;
+    private scrollRafScheduled;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    private flushScrollDepth;
+}
+
+declare class VisibilityPlugin implements KitbasePlugin {
+    readonly name = "visibility";
+    private ctx;
+    private active;
+    private visibilityObservers;
+    private visibilityMutationObserver;
+    private visibilityData;
+    private beforeUnloadListener;
+    private popstateListener;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    private scanForVisibilityElements;
+    private observeVisibilityElement;
+    private getOrCreateObserver;
+    private flushVisibilityForElement;
+    private flushAllVisibilityEvents;
+}
+
+declare class WebVitalsPlugin implements KitbasePlugin {
+    readonly name = "web-vitals";
+    private ctx;
+    private sent;
+    private timeout;
+    private beforeUnloadListener;
+    private data;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+    private sendWebVitals;
+}
+
+declare class FrustrationPlugin implements KitbasePlugin {
+    readonly name = "frustration";
+    private ctx;
+    private rageClickBuffer;
+    private deadClickObserver;
+    private deadClickTimeout;
+    private clickListener;
+    setup(ctx: PluginContext): void | false;
+    teardown(): void;
+}
+
+export { type AnalyticsConfig$1 as AnalyticsConfig, ApiError, AuthenticationError, type BotDetectionConfig, type BotDetectionResult, ClickTrackingPlugin, FrustrationPlugin, type IdentifyOptions, KitbaseAnalytics, type KitbaseConfig, KitbaseError, type KitbasePlugin, type OfflineConfig, OutboundLinksPlugin, type PageViewOptions$1 as PageViewOptions, PageViewPlugin, type PluginContext, type QueueStats, type QueuedEvent, type RevenueOptions, ScrollDepthPlugin, type TagValue$1 as TagValue, type Tags$1 as Tags, TimeoutError, type TrackOptions$1 as TrackOptions, type TrackResponse$1 as TrackResponse, ValidationError, VisibilityPlugin, WebVitalsPlugin, createDefaultPlugins, detectBot, getInstance, getUserAgent, init, isBot, isUserAgentBot };