@loopkit/react/dist/index.d.ts

React TypeScript wrapper for @loopkit/javascript with built-in auto-tracking and comprehensive TypeScript support

import React, { ReactNode, Component, ErrorInfo, DependencyList } from 'react';
import { LoopKitConfig, TrackOptions, BatchEventInput } from '@loopkit/javascript';
import * as javascript from '@loopkit/javascript';
export { javascript as LoopKit };
export { BatchEventInput, ClickEventProperties, Config, Event, GroupEvent, ILoopKit, INetworkManager, IQueueManager, ISessionManager, IStorageManager, IdentifyEvent, LogLevel, LoopKitConfig, Options, RetryBackoff, TrackEvent, TrackOptions } from '@loopkit/javascript';

/**
 * LoopKit React SDK Types
 *
 * This file extends the core @loopkit/javascript types with React-specific functionality.
 */

interface UserProperties {
    email?: string;
    name?: string;
    firstName?: string;
    lastName?: string;
    plan?: string;
    signup_date?: string;
    [key: string]: any;
}
interface GroupProperties {
    name?: string;
    plan?: string;
    employee_count?: number;
    [key: string]: any;
}
interface LoopKitContextValue {
    isInitialized: boolean;
    isLoading: boolean;
    error: Error | null;
    config: LoopKitConfig | null;
    track: (eventName: string, properties?: Record<string, any>, options?: TrackOptions) => Promise<void>;
    trackBatch: (events: BatchEventInput[]) => Promise<void>;
    identify: (userId: string, properties?: UserProperties) => Promise<void>;
    group: (groupId: string, properties?: GroupProperties, groupType?: string) => Promise<void>;
    flush: () => Promise<void>;
    getQueueSize: () => number;
    configure: (options: Partial<LoopKitConfig>) => void;
}
interface LoopKitProviderProps {
    apiKey: string;
    config?: Partial<LoopKitConfig>;
    children: ReactNode;
    onError?: (error: Error) => void;
    onInitialized?: () => void;
}
interface UseLoopKitOptions {
    userId?: string;
    userProperties?: UserProperties;
    autoIdentify?: boolean;
}
interface UseLoopKitReturn extends Omit<LoopKitContextValue, 'configure'> {
    trackPageView: (pageName?: string, properties?: Record<string, any>) => Promise<void>;
    trackClick: (elementName: string, properties?: Record<string, any>) => Promise<void>;
    trackFormSubmit: (formName: string, properties?: Record<string, any>) => Promise<void>;
    setUserId: (userId: string, properties?: UserProperties) => Promise<void>;
    setUserProperties: (properties: UserProperties) => Promise<void>;
    setGroup: (groupId: string, properties?: GroupProperties, groupType?: string) => Promise<void>;
}
declare class LoopKitError extends Error {
    code?: string | undefined;
    originalError?: Error | undefined;
    constructor(message: string, code?: string | undefined, originalError?: Error | undefined);
}
declare class LoopKitInitializationError extends LoopKitError {
    constructor(message: string, originalError?: Error);
}
declare class LoopKitTrackingError extends LoopKitError {
    constructor(message: string, originalError?: Error);
}

/**
 * LoopKit Provider Component
 *
 * Wraps your app and provides LoopKit analytics functionality to all child components.
 * The underlying @loopkit/javascript SDK automatically handles page views, clicks, and errors.
 *
 * This component uses a proper SSR-compatible pattern where both server and client
 * render the same structure, but client-side functionality is only available after hydration.
 */
declare const LoopKitProvider: React.FC<LoopKitProviderProps>;
/**
 * Hook to access LoopKit context
 *
 * @throws {Error} If used outside of LoopKitProvider
 */
declare const useLoopKitContext: () => LoopKitContextValue;

interface Props {
    children: ReactNode;
    fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode);
    onError?: (error: Error, errorInfo: ErrorInfo) => void;
    enableTracking?: boolean;
}
interface State {
    hasError: boolean;
    error: Error | null;
    errorInfo: ErrorInfo | null;
}
/**
 * React Error Boundary with automatic error tracking
 *
 * This component catches React component errors and automatically tracks them
 * with LoopKit, complementing the JavaScript SDK's global error tracking.
 */
declare class LoopKitErrorBoundary extends Component<Props, State> {
    constructor(props: Props);
    static getDerivedStateFromError(error: Error): State;
    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
    render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
}
/**
 * Higher-order component to wrap components with error boundary
 */
declare function withErrorBoundary<P extends object>(WrappedComponent: React.ComponentType<P>, errorBoundaryProps?: Omit<Props, 'children'>): {
    (props: P): React.JSX.Element;
    displayName: string;
};

/**
 * Main hook for using LoopKit analytics
 *
 * Provides enhanced functionality with convenience methods for common React tracking scenarios.
 * The underlying @loopkit/javascript SDK automatically handles clicks, page views, and errors.
 *
 * @param options Configuration options for the hook
 * @returns Enhanced LoopKit functionality with convenience methods
 */
declare const useLoopKit: (options?: UseLoopKitOptions) => UseLoopKitReturn;
/**
 * Hook for tracking page views manually
 *
 * Note: @loopkit/javascript automatically tracks page views by default.
 * Use this hook when you need additional React-specific context or manual control.
 *
 * @param pageName Optional page name override
 * @param properties Additional properties to send with page view
 * @param dependencies Array of dependencies that should trigger a new page view
 */
declare const usePageView: (pageName?: string, properties?: Record<string, any>, dependencies?: DependencyList) => void;
/**
 * Hook for auto-identifying users
 *
 * Automatically identifies the user when the hook is used with a userId.
 *
 * @param userId User ID to identify
 * @param properties User properties to set
 */
declare const useIdentify: (userId: string | null, properties?: UserProperties) => void;
/**
 * Hook for tracking events with a simple function
 *
 * Returns a memoized tracking function that can be used in event handlers.
 *
 * @param eventName The name of the event to track
 * @param defaultProperties Default properties to include with every event
 * @returns Function to call when the event should be tracked
 */
declare const useTrackEvent: (eventName: string, defaultProperties?: Record<string, any>) => (additionalProperties?: Record<string, any>) => void;
/**
 * Hook for tracking component performance
 *
 * Tracks render times and component lifecycle events.
 *
 * @param componentName Name of the component being tracked
 * @param options Tracking options
 */
declare const usePerformanceTracking: (componentName: string, options?: {
    trackRenderTime?: boolean;
    trackMounts?: boolean;
    trackUnmounts?: boolean;
    enabled?: boolean;
}) => void;
/**
 * Hook for tracking React Router navigation
 *
 * Specifically designed to work with React Router and track route changes.
 * Note: @loopkit/javascript automatically tracks page views, but this provides
 * additional React Router specific context.
 *
 * @param routeName Optional route name override
 * @param routeParams Route parameters to include
 */
declare const useRouteTracking: (routeName?: string, routeParams?: Record<string, any>) => void;
/**
 * Hook for tracking feature flag usage
 *
 * Tracks when feature flags are evaluated or used.
 *
 * @param flagName Name of the feature flag
 * @param flagValue Current value of the flag
 * @param metadata Additional metadata about the flag
 */
declare const useFeatureFlagTracking: (flagName: string, flagValue: boolean | string | number, metadata?: Record<string, any>) => void;

export { GroupProperties, LoopKitContextValue, LoopKitError, LoopKitErrorBoundary, LoopKitInitializationError, LoopKitProvider, LoopKitProviderProps, LoopKitTrackingError, UseLoopKitOptions, UseLoopKitReturn, UserProperties, useFeatureFlagTracking, useIdentify, useLoopKit, useLoopKitContext, usePageView, usePerformanceTracking, useRouteTracking, useTrackEvent, withErrorBoundary };