@visitor-analytics-sdk/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visitor Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,418 @@
+interface AnalyticsRecord {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly sessionId: string;
+    readonly pageUrl: string;
+    readonly pagePath: string;
+    readonly referrer: string;
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly devicePixelRatio: number;
+    readonly browser: BrowserData;
+    readonly device: DeviceData;
+    readonly performance: PerformanceData;
+    readonly environment: EnvironmentData;
+    readonly features: FeatureData;
+    readonly interaction: InteractionData;
+    readonly metadata: MetadataData;
+}
+interface BrowserData {
+    readonly name: string;
+    readonly version: string;
+    readonly engine: string;
+    readonly engineVersion: string;
+    readonly userAgent: string;
+    readonly language: string;
+    readonly cookiesEnabled: boolean;
+    readonly javaScriptEnabled: boolean;
+    readonly doNotTrack: boolean | null;
+}
+interface DeviceData {
+    readonly os: string;
+    readonly osVersion: string;
+    readonly platform: string;
+    readonly architecture: string;
+    readonly formFactor: DeviceFormFactor;
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly devicePixelRatio: number;
+    readonly colorDepth: number;
+    readonly orientation: OrientationType;
+    readonly touchSupport: TouchSupport;
+    readonly hardwareConcurrency: number;
+    readonly maxTouchPoints: number;
+}
+type DeviceFormFactor = "desktop" | "mobile" | "tablet" | "smarttv" | "wearable" | "console" | "unknown";
+type TouchSupport = "none" | "coarse" | "fine";
+interface PerformanceData {
+    readonly navigationTiming: NavigationTiming | null;
+    readonly paintTiming: PaintTiming | null;
+    readonly largestContentfulPaint: number | null;
+    readonly firstContentfulPaint: number | null;
+    readonly cumulativeLayoutShift: number | null;
+    readonly interactionToNextPaint: number | null;
+    readonly deviceMemory: number | null;
+    readonly networkType: string;
+    readonly effectiveType: string;
+    readonly downlink: number | null;
+    readonly rtt: number | null;
+    readonly saveData: boolean;
+}
+interface NavigationTiming {
+    readonly redirectTime: number;
+    readonly dnsLookupTime: number;
+    readonly tcpConnectTime: number;
+    readonly requestTime: number;
+    readonly responseTime: number;
+    readonly domInteractiveTime: number;
+    readonly domContentLoadedTime: number;
+    readonly domCompleteTime: number;
+    readonly loadTime: number;
+    readonly duration: number;
+}
+interface PaintTiming {
+    readonly firstPaint: number;
+    readonly firstContentfulPaint: number;
+}
+interface EnvironmentData {
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly languages: readonly string[];
+    readonly language: string;
+    readonly locale: string;
+    readonly prefersColorScheme: "light" | "dark" | "no-preference";
+    readonly prefersReducedMotion: boolean;
+    readonly prefersContrast: "no-preference" | "more" | "less" | "custom";
+    readonly colorGamut: "srgb" | "p3" | "rec2020" | "unknown";
+    readonly hdr: boolean;
+    readonly localStorageSupport: boolean;
+    readonly sessionStorageSupport: boolean;
+    readonly indexedDBSupport: boolean;
+    readonly cookieSupport: boolean;
+    readonly cacheAPISupport: boolean;
+}
+interface FeatureData {
+    readonly webgl: boolean;
+    readonly webgl2: boolean;
+    readonly webgpu: boolean;
+    readonly wasm: boolean;
+    readonly webrtc: boolean;
+    readonly websockets: boolean;
+    readonly broadcastChannel: boolean;
+    readonly sharedWorker: boolean;
+    readonly serviceWorker: boolean;
+    readonly notifications: boolean;
+    readonly clipboard: boolean;
+    readonly fileSystemAccess: boolean;
+    readonly webShare: boolean;
+    readonly webAuthn: boolean;
+    readonly pushManager: boolean;
+    readonly geolocation: boolean;
+    readonly bluetooth: boolean;
+    readonly usb: boolean;
+    readonly serial: boolean;
+    readonly gamepad: boolean;
+    readonly pictureInPicture: boolean;
+    readonly fullscreen: boolean;
+}
+interface InteractionData {
+    readonly sessionDuration: number;
+    readonly timeOnPage: number;
+    readonly routeChanges: number;
+    readonly scrollDepth: number;
+    readonly clickCount: number;
+    readonly resizeCount: number;
+    readonly visibilityChanges: number;
+    readonly focusChanges: number;
+    readonly landingPage: string;
+    readonly exitPage: string | null;
+    readonly utmSource: string | null;
+    readonly utmMedium: string | null;
+    readonly utmCampaign: string | null;
+    readonly utmTerm: string | null;
+    readonly utmContent: string | null;
+}
+interface MetadataData {
+    readonly sdkVersion: string;
+    readonly buildTarget: string;
+    readonly collectorVersion: string;
+    readonly customData: Record<string, string | number | boolean>;
+}
+type CollectorCategory = "browser" | "device" | "performance" | "environment" | "features" | "interaction" | "custom";
+interface Collector {
+    readonly name: string;
+    readonly category: CollectorCategory;
+    readonly version: string;
+    enabled: boolean;
+    collect(context: CollectorContext): Promise<Partial<AnalyticsRecord>>;
+    init?(context: CollectorContext): Promise<void>;
+    destroy?(): Promise<void>;
+}
+interface CollectorContext {
+    readonly document: DocumentLike;
+    readonly navigator: NavigatorLike;
+    readonly window: WindowLike;
+    readonly performance: PerformanceLike;
+    readonly location: LocationLike;
+    readonly history: HistoryLike;
+    readonly screen: ScreenLike;
+}
+interface DocumentLike {
+    readonly cookie: string;
+    readonly referrer: string;
+    readonly title: string;
+    readonly visibilityState: "visible" | "hidden" | "prerender";
+    readonly documentElement: {
+        scrollHeight: number;
+    };
+    createElement(tagName: string): HTMLElement;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+interface NavigatorLike {
+    readonly userAgent: string;
+    readonly language: string;
+    readonly languages: readonly string[];
+    readonly platform: string;
+    readonly hardwareConcurrency: number;
+    readonly maxTouchPoints: number;
+    readonly cookieEnabled: boolean;
+    readonly doNotTrack: boolean | null;
+    readonly deviceMemory: number | undefined;
+    readonly connection: NetworkInformationLike | undefined;
+    readonly storage: StorageManagerLike | undefined;
+    readonly share?: (data: ShareData) => Promise<void>;
+    readonly clipboard: ClipboardLike | undefined;
+    readonly permissions: PermissionsLike | undefined;
+}
+interface WindowLike {
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+    readonly screen: ScreenLike;
+    readonly devicePixelRatio: number;
+    readonly localStorage: Storage | undefined;
+    readonly sessionStorage: Storage | undefined;
+    readonly indexedDB: IDBFactory | undefined;
+    matchMedia(query: string): MediaQueryList | null;
+    requestIdleCallback?(callback: IdleRequestCallback, options?: IdleRequestOptions): number;
+    cancelIdleCallback?(handle: number): void;
+    requestAnimationFrame?(callback: FrameRequestCallback): number;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+interface PerformanceLike {
+    readonly timing: PerformanceTiming | undefined;
+    readonly navigation: PerformanceNavigation | undefined;
+    getEntries(): PerformanceEntryList;
+    getEntriesByType(name: string): readonly PerformanceEntry[];
+    getEntriesByName(name: string): readonly PerformanceEntry[];
+    mark?(name: string): void;
+    measure?(name: string, startMark?: string, endMark?: string): void;
+    clearMarks?(name?: string): void;
+    clearMeasures?(name?: string): void;
+    now(): number;
+}
+interface LocationLike {
+    readonly href: string;
+    readonly origin: string;
+    readonly pathname: string;
+    readonly search: string;
+    readonly hash: string;
+    readonly host: string;
+    readonly hostname: string;
+    readonly protocol: string;
+    readonly port: string;
+}
+interface HistoryLike {
+    readonly length: number;
+    pushState(state: unknown, title: string, url?: string | URL | null): void;
+    replaceState(state: unknown, title: string, url?: string | URL | null): void;
+}
+interface ScreenLike {
+    readonly width: number;
+    readonly height: number;
+    readonly availWidth: number;
+    readonly availHeight: number;
+    readonly colorDepth: number;
+    readonly pixelDepth: number;
+    readonly orientation: ScreenOrientationLike | undefined;
+}
+interface ScreenOrientationLike {
+    readonly type: OrientationType;
+    readonly angle: number;
+}
+interface NetworkInformationLike {
+    readonly type: string;
+    readonly effectiveType: string;
+    readonly downlink: number;
+    readonly rtt: number;
+    readonly saveData: boolean;
+}
+interface StorageManagerLike {
+    estimate(): Promise<StorageEstimate>;
+    persist(): Promise<boolean>;
+    persisted(): Promise<boolean>;
+}
+interface ClipboardLike {
+    readText(): Promise<string>;
+    writeText(text: string): Promise<void>;
+}
+interface PermissionsLike {
+    query(desc: PermissionDesc): Promise<PermissionStatus>;
+}
+interface PermissionDesc {
+    name: string;
+}
+type StorageType = "memory" | "localstorage" | "indexeddb" | "custom";
+interface StorageAdapter {
+    save(record: AnalyticsRecord): Promise<void>;
+    saveBatch(records: readonly AnalyticsRecord[]): Promise<void>;
+    load(): Promise<readonly AnalyticsRecord[]>;
+    loadBatch(limit: number): Promise<readonly AnalyticsRecord[]>;
+    remove(ids: readonly string[]): Promise<void>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+    export(): Promise<string>;
+}
+interface UploaderConfig {
+    readonly endpoint: string;
+    readonly batchSize: number;
+    readonly flushInterval: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelay: number;
+    readonly retryMaxDelay: number;
+    readonly compressionEnabled: boolean;
+    readonly deduplicationEnabled: boolean;
+    readonly headers: Record<string, string>;
+    readonly timeout: number;
+}
+interface UploadPayload {
+    readonly records: readonly AnalyticsRecord[];
+    readonly batchId: string;
+    readonly timestamp: number;
+    readonly sdkVersion: string;
+}
+interface UploadResult {
+    readonly success: boolean;
+    readonly batchId: string;
+    readonly statusCode?: number;
+    readonly error?: string;
+    readonly retryable: boolean;
+}
+type UploadEventHandler = (event: UploadEvent) => void;
+interface UploadEvent {
+    readonly type: "batch-sent" | "batch-success" | "batch-failed" | "retry-scheduled" | "queue-full";
+    readonly batchId: string;
+    readonly recordCount: number;
+    readonly timestamp: number;
+    readonly error?: string;
+    readonly retryCount?: number;
+    readonly nextRetryAt?: number;
+}
+interface Plugin {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    install(analytics: PluginContext): void;
+    uninstall?(analytics: PluginContext): void;
+}
+interface PluginContext {
+    addCollector(collector: Collector): void;
+    removeCollector(name: string): void;
+    on(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    getConfig(): AnalyticsConfig;
+}
+type AnalyticsEvent = "start" | "stop" | "flush" | "sync" | "record-collected" | "batch-uploaded" | "batch-failed" | "error" | "collector-registered" | "collector-removed" | "plugin-installed" | "plugin-uninstalled" | "storage-saved" | "storage-loaded" | "config-changed";
+interface AnalyticsConfig {
+    readonly endpoint: string;
+    readonly storage: StorageType | StorageAdapter;
+    readonly autoStart: boolean;
+    readonly batchSize: number;
+    readonly flushInterval: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelay: number;
+    readonly retryMaxDelay: number;
+    readonly compressionEnabled: boolean;
+    readonly deduplicationEnabled: boolean;
+    readonly headers: Record<string, string>;
+    readonly timeout: number;
+    readonly collectBrowser: boolean;
+    readonly collectDevice: boolean;
+    readonly collectPerformance: boolean;
+    readonly collectEnvironment: boolean;
+    readonly collectFeatures: boolean;
+    readonly collectInteraction: boolean;
+    readonly includeUserAgent: boolean;
+    readonly includeReferrer: boolean;
+    readonly sessionTimeout: number;
+    readonly customData: Record<string, string | number | boolean>;
+}
+type AnalyticsConfigPartial = Partial<AnalyticsConfig>;
+interface VisitorAnalyticsFactory {
+    create(config: AnalyticsConfigPartial): VisitorAnalyticsInstance;
+}
+interface VisitorAnalyticsInstance {
+    start(): void;
+    stop(): void;
+    flush(): Promise<void>;
+    sync(): Promise<void>;
+    retryFailed(): Promise<void>;
+    use(plugin: Plugin): void;
+    addCollector(collector: Collector): void;
+    removeCollector(name: string): void;
+    getCollectedData(): Promise<readonly AnalyticsRecord[]>;
+    export(): Promise<string>;
+    on(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    destroy(): Promise<void>;
+}
+
+declare class VisitorAnalytics implements VisitorAnalyticsInstance {
+    private config;
+    private eventBus;
+    private pluginManager;
+    private storage;
+    private uploader;
+    private collectors;
+    private collectorContext;
+    private isRunning;
+    private sessionId;
+    private collectTimer;
+    constructor(config?: AnalyticsConfigPartial);
+    private registerBuiltInCollectors;
+    private buildCollectorContext;
+    start(): void;
+    stop(): void;
+    flush(): Promise<void>;
+    sync(): Promise<void>;
+    retryFailed(): Promise<void>;
+    use(plugin: Plugin): void;
+    addCollector(collector: Collector): void;
+    removeCollector(name: string): void;
+    getCollectedData(): Promise<readonly AnalyticsRecord[]>;
+    export(): Promise<string>;
+    on(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    destroy(): Promise<void>;
+    private collectAndStore;
+    private collectRecord;
+    private createPluginContext;
+}
+declare function createAnalytics(config?: AnalyticsConfigPartial): VisitorAnalyticsInstance;
+
+type Handler = (...args: readonly unknown[]) => void;
+declare class EventBus {
+    private readonly listeners;
+    on(event: AnalyticsEvent, handler: Handler): void;
+    off(event: AnalyticsEvent, handler: Handler): void;
+    emit(event: AnalyticsEvent, ...args: readonly unknown[]): void;
+    removeAllListeners(event?: AnalyticsEvent): void;
+    listenerCount(event: AnalyticsEvent): number;
+}
+
+export { type AnalyticsConfig, type AnalyticsConfigPartial, type AnalyticsEvent, type AnalyticsRecord, type BrowserData, type ClipboardLike, type Collector, type CollectorCategory, type CollectorContext, type DeviceData, type DeviceFormFactor, type DocumentLike, type EnvironmentData, EventBus, type FeatureData, type HistoryLike, type InteractionData, type LocationLike, type MetadataData, type NavigationTiming, type NavigatorLike, type NetworkInformationLike, type PaintTiming, type PerformanceData, type PerformanceLike, type PermissionDesc, type PermissionsLike, type Plugin, type PluginContext, type ScreenLike, type ScreenOrientationLike, type StorageAdapter, type StorageManagerLike, type StorageType, type TouchSupport, type UploadEvent, type UploadEventHandler, type UploadPayload, type UploadResult, type UploaderConfig, VisitorAnalytics, type VisitorAnalyticsFactory, type VisitorAnalyticsInstance, type WindowLike, createAnalytics };