thrivestack-node-sdk/dist/ThriveStack.d.ts

Official ThriveStack Analytics SDK for Node.js and Next.js server-side applications

/**
 * ThriveStack Analytics Platform
 * Comprehensive analytics tracking with privacy-first approach for Node.js
 * @version 2.0.1
 */
export interface ThriveStackOptions {
    apiKey: string;
    apiEndpoint?: string;
    respectDoNotTrack?: boolean;
    enableConsent?: boolean;
    batchSize?: number;
    batchInterval?: number;
    source?: string;
    sessionTimeout?: number;
    debounceDelay?: number;
    defaultConsent?: boolean;
}
export interface LocationInfo {
    city?: string | null;
    region?: string | null;
    country?: string | null;
    postal?: string | null;
    loc?: string | null;
    timezone?: string | null;
}
export interface EventData {
    event_name: string;
    properties: Record<string, any>;
    user_id?: string;
    context: {
        group_id?: string;
        device_id?: string | null;
        session_id?: string;
        source?: string;
    };
    timestamp: string;
}
export interface UserData {
    user_id: string;
    traits: Record<string, any>;
    timestamp: string;
}
export interface GroupData {
    group_id: string;
    user_id?: string;
    traits: Record<string, any>;
    timestamp: string;
}
export interface SessionData {
    sessionId: string;
    startTime: string;
    lastActivity: string;
}
export interface ConsentCategories {
    functional: boolean;
    analytics: boolean;
    marketing: boolean;
}
export declare class ThriveStack {
    private apiKey;
    private apiEndpoint;
    private respectDoNotTrack;
    private enableConsent;
    private source;
    private geoIpServiceUrl;
    private ipAddress;
    private locationInfo;
    private eventQueue;
    private queueTimer;
    private batchSize;
    private batchInterval;
    private interactionHistory;
    private maxHistoryLength;
    private consentCategories;
    private userId;
    private groupId;
    private deviceId;
    private sessionTimeout;
    private debounceDelay;
    private sessionUpdateTimer;
    private sessionStorage;
    constructor(options: ThriveStackOptions | string);
    /**
     * Initialize device ID
     */
    private initializeDeviceId;
    /**
     * Fetch IP address and location information
     */
    private fetchIpAndLocationInfo;
    /**
     * Get local IP address
     */
    private getLocalIpAddress;
    /**
     * Initialize ThriveStack and start tracking
     */
    init(userId?: string, source?: string): Promise<void>;
    /**
     * Check if tracking is allowed
     */
    shouldTrack(): boolean;
    /**
     * Check if specific tracking category is allowed
     */
    isTrackingAllowed(category: keyof ConsentCategories): boolean;
    /**
     * Update consent settings for a tracking category
     */
    setConsent(category: keyof ConsentCategories, hasConsent: boolean): void;
    /**
     * Set user ID for tracking
     */
    setUserId(userId: string): void;
    /**
     * Set group ID for tracking
     */
    setGroupId(groupId: string): void;
    /**
     * Set source for tracking
     */
    setSource(source: string): void;
    /**
     * Queue an event for batched sending
     */
    queueEvent(events: EventData | EventData[]): void;
    /**
     * Process and send queued events
     */
    private processQueue;
    /**
     * Track events by sending to ThriveStack API
     */
    track(events: EventData[]): Promise<any>;
    /**
     * Send user identification data
     */
    identify(data: UserData | UserData[]): Promise<any>;
    /**
     * Send group data
     */
    group(data: GroupData | GroupData[]): Promise<any>;
    /**
     * Get device ID
     */
    getDeviceId(): string | null;
    /**
     * Get session ID
     */
    getSessionId(): string;
    /**
     * Create a new session
     */
    private createNewSession;
    /**
     * Update session activity with debouncing
     */
    updateSessionActivity(): void;
    /**
     * Immediate session activity update
     */
    private updateSessionActivityImmediate;
    /**
     * Capture page visit event (adapted for Node.js)
     */
    capturePageVisit(pageInfo?: {
        title?: string;
        url?: string;
        path?: string;
        referrer?: string;
    }): Promise<void>;
    /**
     * Capture custom event
     */
    captureEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
    /**
     * Add event to interaction history
     */
    private addToInteractionHistory;
    /**
     * Automatically detect and clean PII from event data
     */
    private cleanPIIFromEventData;
    /**
     * Set user information and optionally make identify API call
     */
    setUser(userId: string, emailId?: string, properties?: Record<string, any>): Promise<any | null>;
    /**
     * Set group information and optionally make group API call
     */
    setGroup(groupId: string, groupDomain?: string, groupName?: string, properties?: Record<string, any>): Promise<any | null>;
    /**
     * Enable debug mode for troubleshooting
     */
    enableDebugMode(): void;
    /**
     * Get interaction history
     */
    getInteractionHistory(): Array<{
        type: string;
        details: Record<string, any>;
        timestamp: string;
        sequence: number;
    }>;
    /**
     * Clear interaction history
     */
    clearInteractionHistory(): void;
    /**
     * Get current configuration
     */
    getConfig(): {
        apiEndpoint: string;
        batchSize: number;
        batchInterval: number;
        sessionTimeout: number;
        source: string;
        userId: string;
        groupId: string;
        deviceId: string | null;
    };
}