@shellapps/experience 1.0.1 → 1.2.0

package/dist/index.d.mts

@@ -11,95 +11,583 @@ interface ExperienceConfig {
     maxBatchSize?: number;
     debug?: boolean;
 }
+interface TrackEvent {
+    eventType: string;
+    sessionId: string;
+    timestamp: number;
+    metadata?: Record<string, string>;
+    pageContext?: PageContext;
+    elementContext?: ElementContext;
+}
 interface PageContext {
-    path: string;
+    url: string;
     title: string;
     referrer: string;
-    viewportWidth: number;
-    viewportHeight: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    loadTime?: number;
 }
 interface ElementContext {
+    selector: string;
+    dataT?: string;
     tag: string;
-    text: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+interface HeatmapEvent {
+    sessionId: string;
+    timestamp: number;
+    type: 'click' | 'move' | 'hover';
     x: number;
     y: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    url: string;
 }
-interface ExperienceEvent {
-    eventId: string;
-    appId: string;
-    profileId: string;
-    sessionId: string;
-    timestampMs: number;
-    eventType: string;
-    pageUrl: string;
-    elementTid: string;
-    metadata: Record<string, unknown>;
-    pageContext: PageContext;
-    elementContext: ElementContext | null;
-}
-interface ErrorReport {
-    eventId: string;
-    appId: string;
-    profileId: string;
+interface EventBatch {
+    events: TrackEvent[];
+    heatmapEvents: HeatmapEvent[];
+}
+interface IngestResponse {
+    success: boolean;
+    message?: string;
+}
+interface ErrorEvent {
     sessionId: string;
-    timestampMs: number;
+    timestamp: number;
     message: string;
-    stack: string;
-    severity: string;
-    extra: Record<string, unknown>;
-    pageContext: PageContext;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    severity: Severity;
     breadcrumbs: Breadcrumb[];
+    browserContext: BrowserContext;
+    tags?: Record<string, string>;
+    extra?: Record<string, any>;
+}
+declare enum Severity {
+    INFO = 0,
+    WARNING = 1,
+    ERROR = 2,
+    FATAL = 3
 }
 interface Breadcrumb {
-    type: string;
-    category: string;
+    timestamp: number;
+    category: 'navigation' | 'click' | 'console' | 'fetch' | 'xhr' | 'ui';
     message: string;
-    timestampMs: number;
-    data?: Record<string, unknown>;
+    data?: Record<string, any>;
+    level?: 'info' | 'warning' | 'error';
 }
-interface HeatmapEntry {
-    x: number;
-    y: number;
-    type: 'move' | 'click';
-    timestampMs: number;
-    viewportWidth: number;
-    viewportHeight: number;
-    pageUrl: string;
+interface BrowserContext {
+    userAgent: string;
+    url: string;
+    timestamp: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+interface ErrorBatch {
+    errors: ErrorEvent[];
+}
+interface Session {
+    id: string;
+    startTime: number;
+    getDuration(): number;
+}
+interface FeatureFlag {
+    key: string;
+    value: any;
+    type: 'boolean' | 'string' | 'number' | 'json';
+}
+interface FlagResponse {
+    flags: Record<string, any>;
+}
+interface TransportConfig {
+    endpoint: string;
+    apiKey: string;
+    debug: boolean;
+}
+type EventHandler = (event: Event) => void;
+type UnsubscribeFn = () => void;
+interface ResolvedExperienceConfig {
+    appId: string;
+    apiKey: string;
+    endpoint: string;
+    enableTracking: boolean;
+    enableErrorCapture: boolean;
+    enableHeatmaps: boolean;
+    enableBreadcrumbs: boolean;
+    sampleRate: number;
+    batchIntervalMs: number;
+    maxBatchSize: number;
+    debug: boolean;
 }
 
 declare class Experience {
+    private static instance;
     private config;
-    private sessionId;
-    private profileId;
-    private eventQueue;
-    private errorQueue;
-    private batchTimer;
-    private breadcrumbs;
-    private flags;
-    private flagsFetched;
-    private teardownFns;
-    private destroyed;
+    private sessionManager;
+    private transport;
+    private batcher;
+    private breadcrumbManager;
+    private heatmapTracker;
+    private errorCapture;
+    private autoTracker;
+    private dataTTracker;
+    private flagClient;
+    private offlineQueue;
+    private isShutdown;
+    private isInSample;
     private constructor();
-    static init(config: ExperienceConfig): Experience;
-    private log;
-    private setup;
-    track(eventName: string, metadata?: Record<string, unknown>): void;
+    private resolveConfig;
+    private setupFailureHandling;
+    private enableFeatures;
+    track(eventType: string, metadata?: Record<string, string>): void;
     trackPageView(): void;
-    captureError(error: Error, extra?: Record<string, unknown>): void;
-    captureMessage(msg: string, severity?: string): void;
-    getFlag<T>(name: string, defaultValue: T): T;
+    captureError(error: Error, options?: {
+        tags?: Record<string, string>;
+        extra?: Record<string, any>;
+        severity?: Severity;
+    }): void;
+    captureMessage(message: string, severity?: string): void;
+    getFlag<T>(key: string, defaultValue: T): T;
     identify(profileId: string): void;
     shutdown(): Promise<void>;
-    private enqueueEvent;
-    private enqueueError;
-    private flush;
-    private flushSync;
-    private sendOrQueue;
-    private sendRequest;
-    private fetchFlags;
-    private setupErrorCapture;
-    private setupAutoPageViews;
-    private setupHeatmaps;
+    private getCurrentPageContext;
+    getSessionInfo(): {
+        sessionId: string;
+        duration: number;
+        isInSample: boolean;
+    };
+    getQueueStatus(): Promise<{
+        pendingEvents: number;
+        pendingErrors: number;
+        offlineQueue: {
+            events: number;
+            errors: number;
+            isOnline: boolean;
+            isInitialized: boolean;
+        };
+    }>;
+    getBreadcrumbs(): Breadcrumb[];
+    getFlagCacheInfo(): {
+        size: number;
+        keys: string[];
+        oldestEntry?: {
+            key: string;
+            age: number;
+        };
+        newestEntry?: {
+            key: string;
+            age: number;
+        };
+    };
+    flush(): Promise<void>;
+    static init(config: ExperienceConfig): Experience;
+    static getInstance(): Experience | null;
+    trackElement(element: Element, eventType: string): void;
+    private getElementSelector;
+}
+
+declare class SessionManager {
+    private session;
+    constructor();
+    private generateUUID;
+    private initializeSession;
+    private createNewSession;
+    getCurrentSession(): Session;
+    getSessionId(): string;
+    getSessionDuration(): number;
+    renewSession(): void;
+}
+
+declare class Transport {
+    private config;
+    private encoder;
+    constructor(config: TransportConfig);
+    private sendProtobuf;
+    private sendJSON;
+    sendEventBatch(batch: EventBatch): Promise<IngestResponse>;
+    sendErrorBatch(batch: ErrorBatch): Promise<IngestResponse>;
+    sendEventBatchBeacon(batch: EventBatch): Promise<void>;
+    sendErrorBatchBeacon(batch: ErrorBatch): Promise<void>;
+    fetchFlags(appId: string, profileId?: string): Promise<Record<string, any>>;
+}
+
+declare class EventBatcher {
+    private trackEvents;
+    private heatmapEvents;
+    private errorEvents;
+    private transport;
+    private batchIntervalMs;
+    private maxBatchSize;
+    private debug;
+    private flushTimer;
+    private unsubscribeFns;
+    constructor(transport: Transport, batchIntervalMs?: number, maxBatchSize?: number, debug?: boolean);
+    private setupAutoFlush;
+    private scheduleNextFlush;
+    private setupUnloadHandler;
+    addTrackEvent(event: TrackEvent): void;
+    addHeatmapEvent(event: HeatmapEvent): void;
+    addErrorEvent(error: ErrorEvent): void;
+    flush(): Promise<void>;
+    flushErrors(): Promise<void>;
+    flushBeacon(): void;
+    getPendingEventCount(): number;
+    getPendingErrorCount(): number;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+
+declare class BreadcrumbManager {
+    private breadcrumbs;
+    private unsubscribeFns;
+    private originalConsole;
+    private originalFetch;
+    private isEnabled;
+    constructor();
+    enable(): void;
+    disable(): void;
+    private addBreadcrumb;
+    private setupConsoleWrapping;
+    private restoreConsole;
+    private setupFetchWrapping;
+    private restoreFetch;
+    private setupXHRWrapping;
+    private setupNavigationListeners;
+    private setupClickListener;
+    private getElementSelector;
+    getBreadcrumbs(): Breadcrumb[];
+    clear(): void;
+    addCustomBreadcrumb(category: Breadcrumb['category'], message: string, data?: Record<string, any>): void;
+}
+
+declare class HeatmapTracker {
+    private batcher;
+    private sessionId;
+    private isEnabled;
+    private unsubscribeFns;
+    private lastMouseMoveTime;
+    private hoverTimer;
+    private lastHoverPosition;
+    constructor(batcher: EventBatcher, sessionId: string);
+    enable(): void;
+    disable(): void;
+    private setupMouseMoveTracking;
+    private setupClickTracking;
+    private setupHoverTracking;
+    private getViewportSize;
+    updateSessionId(sessionId: string): void;
+    trackClick(x: number, y: number): void;
+    trackHover(x: number, y: number): void;
+}
+
+declare class ErrorCapture {
+    private batcher;
+    private breadcrumbManager;
+    private sessionId;
+    private isEnabled;
+    private unsubscribeFns;
+    private originalWindowError;
+    private originalUnhandledRejection;
+    constructor(batcher: EventBatcher, breadcrumbManager: BreadcrumbManager, sessionId: string);
+    enable(): void;
+    disable(): void;
+    private setupGlobalErrorHandler;
+    private setupUnhandledRejectionHandler;
+    private restoreOriginalHandlers;
+    private getBrowserContext;
+    private captureError;
+    captureException(error: Error, options?: {
+        tags?: Record<string, string>;
+        extra?: Record<string, any>;
+        severity?: Severity;
+    }): void;
+    captureMessage(message: string, severity?: Severity, options?: {
+        tags?: Record<string, string>;
+        extra?: Record<string, any>;
+    }): void;
+    captureBreadcrumb(message: string, category?: 'navigation' | 'click' | 'console' | 'fetch' | 'xhr' | 'ui', data?: Record<string, any>): void;
+    updateSessionId(sessionId: string): void;
+    private extractErrorInfo;
+    static getSeverityFromString(severity: string): Severity;
+    triggerTestError(): void;
+}
+
+declare class AutoTracker {
+    private batcher;
+    private sessionId;
+    private isEnabled;
+    private unsubscribeFns;
+    private lastUrl;
+    private pageLoadTime;
+    constructor(batcher: EventBatcher, sessionId: string);
+    enable(): void;
+    disable(): void;
+    private trackInitialPageView;
+    private calculateLoadTime;
+    private setupSPATracking;
+    private getPageContext;
+    private trackPageView;
+    trackCurrentPage(): void;
+    trackNavigation(eventType: string, metadata?: Record<string, string>): void;
+    updateSessionId(sessionId: string): void;
+    getCurrentPageInfo(): PageContext;
+}
+
+declare class DataTTracker {
+    private batcher;
+    private sessionId;
+    private isEnabled;
+    private unsubscribeFns;
+    private mutationObserver;
+    private intersectionObserver;
+    private visibleElements;
+    private hoverTimers;
+    constructor(batcher: EventBatcher, sessionId: string);
+    enable(): void;
+    disable(): void;
+    private setupMutationObserver;
+    private setupEventDelegation;
+    private setupVisibilityTracking;
+    private setupHoverTracking;
+    private scanExistingElements;
+    private processNewElement;
+    private findDataTParent;
+    private getElementSelector;
+    private getElementContext;
+    private getPageContext;
+    private trackDataTEvent;
+    updateSessionId(sessionId: string): void;
+}
+
+declare class FeatureFlagClient {
+    private transport;
+    private appId;
+    private profileId;
+    private flagCache;
+    private cacheTimeoutMs;
+    private eventSource;
+    private debug;
+    constructor(transport: Transport, appId: string, debug?: boolean);
+    setProfileId(profileId: string): void;
+    fetchFlags(): Promise<void>;
+    getFlag<T>(key: string, defaultValue: T): T;
+    getFlagSync<T>(key: string, defaultValue: T): T;
+    private convertValue;
+    private fetchFlagsInBackground;
+    private _backgroundFetchInProgress;
+    initialize(): Promise<void>;
+    setupRealtimeUpdates(endpoint?: string): void;
+    closeRealtimeUpdates(): void;
+    clearCache(): void;
+    getCacheInfo(): {
+        size: number;
+        keys: string[];
+        oldestEntry?: {
+            key: string;
+            age: number;
+        };
+        newestEntry?: {
+            key: string;
+            age: number;
+        };
+    };
+    hasCachedFlag(key: string): boolean;
+    getAllCachedFlags(): Record<string, any>;
+    preloadFlags(keys: string[]): Promise<void>;
+    shutdown(): void;
+}
+
+declare class OfflineQueue {
+    private transport;
+    private db;
+    private debug;
+    private isInitialized;
+    private unsubscribeFns;
+    private isProcessing;
+    constructor(transport: Transport, debug?: boolean);
+    private initialize;
+    private openDatabase;
+    private setupOnlineListener;
+    private generateId;
+    storeEventBatch(batch: EventBatch): Promise<void>;
+    storeErrorBatch(batch: ErrorBatch): Promise<void>;
+    private storeItem;
+    private cleanupOldItems;
+    private getAllItems;
+    private removeItem;
+    processStoredItems(): Promise<void>;
+    private processStoreItems;
+    getQueueStatus(): Promise<{
+        events: number;
+        errors: number;
+        isOnline: boolean;
+        isInitialized: boolean;
+    }>;
+    clear(): Promise<void>;
+    shutdown(): void;
+}
+
+declare class ProtobufEncoder {
+    private buffer;
+    private encodeVarint;
+    private encodeTag;
+    private encodeString;
+    private encodeUint64;
+    private encodeUint32;
+    private encodeBool;
+    private encodeMessage;
+    private encodeMapEntry;
+    private encodeViewport;
+    private encodePosition;
+    private encodePageContext;
+    private encodeElementContext;
+    private encodeTrackEvent;
+    private encodeHeatmapEvent;
+    private encodeBreadcrumb;
+    private encodeBrowserContext;
+    private encodeErrorEvent;
+    encodeEventBatch(batch: EventBatch): Uint8Array;
+    encodeErrorBatch(batch: ErrorBatch): Uint8Array;
+}
+
+declare const TrackEventSchema: {
+    eventType: number;
+    sessionId: number;
+    timestamp: number;
+    metadata: number;
+    pageContext: number;
+    elementContext: number;
+};
+declare const PageContextSchema: {
+    url: number;
+    title: number;
+    referrer: number;
+    viewport: number;
+    loadTime: number;
+};
+declare const ViewportSchema: {
+    width: number;
+    height: number;
+};
+declare const ElementContextSchema: {
+    selector: number;
+    dataT: number;
+    tag: number;
+    position: number;
+};
+declare const PositionSchema: {
+    x: number;
+    y: number;
+};
+declare const HeatmapEventSchema: {
+    sessionId: number;
+    timestamp: number;
+    type: number;
+    x: number;
+    y: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    url: number;
+};
+declare const EventBatchSchema: {
+    events: number;
+    heatmapEvents: number;
+};
+declare const IngestResponseSchema: {
+    success: number;
+    message: number;
+};
+declare const ErrorEventSchema: {
+    sessionId: number;
+    timestamp: number;
+    message: number;
+    filename: number;
+    lineno: number;
+    colno: number;
+    stack: number;
+    severity: number;
+    breadcrumbs: number;
+    browserContext: number;
+    tags: number;
+    extra: number;
+};
+declare const BreadcrumbSchema: {
+    timestamp: number;
+    category: number;
+    message: number;
+    data: number;
+    level: number;
+};
+declare const BrowserContextSchema: {
+    userAgent: number;
+    url: number;
+    timestamp: number;
+    viewport: number;
+};
+declare const ErrorBatchSchema: {
+    errors: number;
+};
+declare const WireType: {
+    VARINT: number;
+    FIXED64: number;
+    LENGTH_DELIMITED: number;
+    START_GROUP: number;
+    END_GROUP: number;
+    FIXED32: number;
+};
+declare const SeverityEnum: {
+    INFO: number;
+    WARNING: number;
+    ERROR: number;
+    FATAL: number;
+};
+declare const HeatmapTypeEnum: {
+    click: number;
+    move: number;
+    hover: number;
+};
+declare const BreadcrumbCategoryEnum: {
+    navigation: number;
+    click: number;
+    console: number;
+    fetch: number;
+    xhr: number;
+    ui: number;
+};
+declare const BreadcrumbLevelEnum: {
+    info: number;
+    warning: number;
+    error: number;
+};
+
+declare const schemas_BreadcrumbCategoryEnum: typeof BreadcrumbCategoryEnum;
+declare const schemas_BreadcrumbLevelEnum: typeof BreadcrumbLevelEnum;
+declare const schemas_BreadcrumbSchema: typeof BreadcrumbSchema;
+declare const schemas_BrowserContextSchema: typeof BrowserContextSchema;
+declare const schemas_ElementContextSchema: typeof ElementContextSchema;
+declare const schemas_ErrorBatchSchema: typeof ErrorBatchSchema;
+declare const schemas_ErrorEventSchema: typeof ErrorEventSchema;
+declare const schemas_EventBatchSchema: typeof EventBatchSchema;
+declare const schemas_HeatmapEventSchema: typeof HeatmapEventSchema;
+declare const schemas_HeatmapTypeEnum: typeof HeatmapTypeEnum;
+declare const schemas_IngestResponseSchema: typeof IngestResponseSchema;
+declare const schemas_PageContextSchema: typeof PageContextSchema;
+declare const schemas_PositionSchema: typeof PositionSchema;
+declare const schemas_SeverityEnum: typeof SeverityEnum;
+declare const schemas_TrackEventSchema: typeof TrackEventSchema;
+declare const schemas_ViewportSchema: typeof ViewportSchema;
+declare const schemas_WireType: typeof WireType;
+declare namespace schemas {
+  export { schemas_BreadcrumbCategoryEnum as BreadcrumbCategoryEnum, schemas_BreadcrumbLevelEnum as BreadcrumbLevelEnum, schemas_BreadcrumbSchema as BreadcrumbSchema, schemas_BrowserContextSchema as BrowserContextSchema, schemas_ElementContextSchema as ElementContextSchema, schemas_ErrorBatchSchema as ErrorBatchSchema, schemas_ErrorEventSchema as ErrorEventSchema, schemas_EventBatchSchema as EventBatchSchema, schemas_HeatmapEventSchema as HeatmapEventSchema, schemas_HeatmapTypeEnum as HeatmapTypeEnum, schemas_IngestResponseSchema as IngestResponseSchema, schemas_PageContextSchema as PageContextSchema, schemas_PositionSchema as PositionSchema, schemas_SeverityEnum as SeverityEnum, schemas_TrackEventSchema as TrackEventSchema, schemas_ViewportSchema as ViewportSchema, schemas_WireType as WireType };
 }
 
-export { type Breadcrumb, type ElementContext, type ErrorReport, Experience, type ExperienceConfig, type ExperienceEvent, type HeatmapEntry, type PageContext };
+export { AutoTracker, type Breadcrumb, BreadcrumbManager, type BrowserContext, DataTTracker, type ElementContext, type ErrorBatch, ErrorCapture, type ErrorEvent, type EventBatch, EventBatcher, type EventHandler, Experience, type ExperienceConfig, type FeatureFlag, FeatureFlagClient, type FlagResponse, type HeatmapEvent, HeatmapTracker, type IngestResponse, OfflineQueue, type PageContext, schemas as ProtoSchemas, ProtobufEncoder, type ResolvedExperienceConfig, type Session, SessionManager, Severity, type TrackEvent, Transport, type TransportConfig, type UnsubscribeFn };