@zaplier/sdk 1.8.1 → 1.8.3

package/dist/v2/core.d.ts

@@ -1,7 +1,278 @@
+/**
+ * Visitor-related types for SDK responses
+ */
+/**
+ * Visitor information returned by getVisitorInfo()
+ */
+interface VisitorInfo {
+    visitorId: string;
+    workspaceId: string;
+    location: {
+        country?: string;
+        countryCode?: string;
+        city?: string;
+    };
+    device: {
+        browser?: string;
+        os?: string;
+        deviceType?: string;
+        userAgent?: string;
+    };
+    stats: {
+        visitCount: number;
+        firstSeenAt: string;
+        lastSeenAt: string;
+        identificationScore?: number;
+    };
+    signals?: {
+        smartSignals?: any;
+        tlsFingerprint?: string | null;
+        cookieFingerprint?: string | null;
+    };
+}
+/**
+ * Visit history entry
+ */
+interface VisitHistoryEntry {
+    id: string;
+    timestamp: string;
+    location: string | null;
+    country?: string | null;
+    countryCode?: string | null;
+    city?: string | null;
+    ip: string | null;
+    browser: string | null;
+    os: string | null;
+    deviceType: string | null;
+    isIncognito: boolean;
+    vpnDetected: boolean;
+    suspectScore: number;
+}
+/**
+ * Visitor history response
+ */
+interface VisitorHistory {
+    visitorId: string;
+    visits: VisitHistoryEntry[];
+    summary: {
+        totalVisits: number;
+        uniqueIPs: number;
+        uniqueLocations: number;
+        incognitoSessions: number;
+    };
+}
+/**
+ * User data returned by getUserData()
+ */
+interface UserData {
+    sessionId: string;
+    visitorId?: string;
+    userId?: string;
+    location: {
+        city?: string;
+        country?: string;
+        coordinates?: {
+            lat: number;
+            lng: number;
+        };
+    };
+    device: {
+        userAgent: string;
+        language: string;
+        screen: {
+            width: number;
+            height: number;
+        };
+    };
+    journey: any[];
+    fingerprint?: string;
+}
+
+/**
+ * SDK Configuration Types
+ *
+ * 100% Cookieless tracking using fingerprinting only.
+ * No storage dependencies - fully GDPR/LGPD compliant.
+ */
+interface SDKConfig {
+    /** Workspace token (required) */
+    token: string;
+    /** Enable session replay recording (default: false) */
+    replay?: boolean;
+    /** Enable heatmap tracking (default: false) */
+    heatmap?: boolean;
+    /** Enable debug mode for development (default: false) */
+    debug?: boolean;
+    /** Allow tracking on localhost (default: false) */
+    allow_localhost?: boolean;
+    /** GDPR mode - limits invasive fingerprinting (default: false) */
+    gdprMode?: boolean;
+}
+/**
+ * Internal configuration with optimized defaults
+ * These settings are not exposed to the user but can be referenced internally
+ */
+interface InternalConfig extends SDKConfig {
+    apiEndpoint: string;
+    retryEnabled: boolean;
+    maxRetries: number;
+    retryDelays: number[];
+    autoTrack: boolean;
+    dedupeEnabled: boolean;
+    fingerprintEnabled: boolean;
+    presenceTracking: boolean;
+    heartbeatInterval: number;
+    scrollTracking: boolean;
+    scrollDepthTracking: boolean;
+    gdprCompliant: boolean;
+    enhancedTracking: 'ask' | 'true' | 'false';
+    replaySampling: number;
+    replayMaskInputs: boolean;
+}
+
+/**
+ * Event and Tracking Types
+ */
+interface BaseEventData {
+    eventType: string;
+    eventName?: string;
+    customData?: Record<string, any>;
+}
+interface PageViewEvent extends BaseEventData {
+    eventType: 'page_view';
+    url?: string;
+    pageTitle?: string;
+    referrer?: string;
+    spaNavigation?: boolean;
+    navigationType?: 'manual' | 'spa' | 'direct';
+}
+
+/**
+ * Method parameter types for SDK calls
+ */
+/**
+ * Parameters for trackPurchase()
+ */
+interface TrackPurchaseParams {
+    value?: number;
+    revenue?: number;
+    currency?: string;
+    quantity?: number;
+    productId?: string;
+    productName?: string;
+    orderId?: string;
+    customData?: Record<string, any>;
+}
+/**
+ * Parameters for trackAddToCart()
+ */
+interface TrackAddToCartParams {
+    productId?: string;
+    productName?: string;
+    price?: number;
+    quantity?: number;
+    customData?: Record<string, any>;
+}
+/**
+ * Parameters for trackViewContent()
+ */
+interface TrackViewContentParams {
+    productId?: string;
+    productName?: string;
+    category?: string;
+    customData?: Record<string, any>;
+}
+/**
+ * Parameters for trackInitiateCheckout()
+ */
+interface TrackInitiateCheckoutParams {
+    value?: number;
+    currency?: string;
+    numItems?: number;
+    customData?: Record<string, any>;
+}
+/**
+ * Parameters for identify()
+ */
+interface IdentifyParams {
+    email?: string;
+    phone?: string;
+    [key: string]: any;
+}
+/**
+ * Response from trackConversion()
+ */
+interface ConversionLikelihoodResponse {
+    score: number;
+    factors: string[];
+}
+/**
+ * Response from getUserSegment()
+ */
+interface UserSegmentResponse {
+    type: "high_intent" | "medium_intent" | "exploring";
+    confidence: number;
+}
+
+/**
+ * Main SDK interface
+ */
+interface ZaplierSDK {
+    track(eventType: string, eventData?: Record<string, any>): void;
+    trackCustomEvent(eventName: string, metadata?: Record<string, any>): boolean;
+    trackConversion(eventName: string, value?: number, currency?: string, metadata?: Record<string, any>): boolean;
+    trackPageView(data?: Partial<PageViewEvent>): void;
+    trackPurchase(data: TrackPurchaseParams): void;
+    trackAddToCart(data?: TrackAddToCartParams): void;
+    trackViewContent(data?: TrackViewContentParams): void;
+    trackInitiateCheckout(data?: TrackInitiateCheckoutParams): void;
+    trackLead(data?: Record<string, any>): void;
+    identify(userData: IdentifyParams): void;
+    trackSPANavigation(url?: string, title?: string): void;
+    resetScrollTracking(): void;
+    startPresenceTracking(): void;
+    stopPresenceTracking(): void;
+    heatmap: {
+        enable(): void;
+        disable(): void;
+    };
+    replay: {
+        enable(): void;
+        disable(): void;
+        addFunnelStep(stepData: Record<string, any>): void;
+        markConversion(data: Record<string, any>): void;
+    };
+    enableEnhancedTracking(): boolean;
+    disableEnhancedTracking(): void;
+    isEnhancedMode(): boolean;
+    getVisitorId(): string | null;
+    getVisitorInfo(): Promise<VisitorInfo | null>;
+    getVisitorHistory(): Promise<VisitorHistory | null>;
+    getUserData(): UserData;
+    getConversionLikelihood(): ConversionLikelihoodResponse;
+    getUserSegment(): UserSegmentResponse;
+    config: InternalConfig;
+    version: string;
+}
+/**
+ * Global window interface extension
+ */
+declare global {
+    interface Window {
+        Zaplier?: ZaplierSDK;
+        zaplier?: ZaplierSDK;
+        stalker?: {
+            config?: Partial<SDKConfig>;
+            q?: any[][];
+        } & ZaplierSDK;
+    }
+}
+
 /**
  * Zaplier SDK Core v2.0.0 - Performance Optimized
  * Minimal core for instant initialization with lazy loading
  */
+
 interface CoreConfig {
     token: string;
     debug?: boolean;
@@ -23,8 +294,16 @@ declare class ZaplierCore {
     private sessionId?;
     private visitorId?;
     private modules;
+    private backendVisitorId?;
     private readonly version;
+    /** Cached dev environment flag, computed once at init time */
+    private _isDev;
     constructor(config: CoreConfig);
+    /**
+     * Detect dev environment for isDev event flagging.
+     * Matches ZaplierSDK.isDevEnvironment() for parity.
+     */
+    private isDevEnvironment;
     /**
      * Instant core initialization - only essential setup
      */
@@ -70,14 +349,17 @@ declare class ZaplierCore {
      */
     private generateTempVisitorId;
     /**
-     * Get visitor info (for compatibility)
+     * Get the visitor ID (backend UUID if available, otherwise temp ID)
      */
-    getVisitorInfo(): {
-        visitorId: string | undefined;
-        sessionId: string | undefined;
-        isReady: boolean;
-        hasFingerprint: boolean;
-    };
+    getVisitorId(): string | null;
+    /**
+     * Get client-side user data synchronously (SSR-safe)
+     */
+    getUserData(): UserData;
+    /**
+     * Get full visitor info from backend (async, only fetches when backend UUID is available)
+     */
+    getVisitorInfo(): Promise<VisitorInfo | null>;
 }
 /**
  * Factory function for easy initialization