wisetrack 2.0.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2025 WiseTrack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,128 @@
+# WiseTrack Web SDK
+
+A lightweight JavaScript SDK for tracking user behavior and events in your web applications.
+
+---
+
+## 🚀 Features
+
+- Lightweight and easy to integrate
+- Supports custom and revenue events
+- Environment-based configuration (Sandbox & Production)
+- Automatic or manual tracking control
+- Customizable logging level
+
+---
+
+## 📦 Installation
+
+```bash
+# via npm
+npm install @your-scope/wisetrack-web
+
+# via yarn
+yarn add @your-scope/wisetrack-web
+````
+
+---
+
+## ✅ Basic Usage
+
+### 1️⃣ Initialize the SDK
+
+```ts
+import { WiseTrack, WTUserEnvironment, WTLogLevel } from "@your-scope/wisetrack-web";
+
+await WiseTrack.instance.init({
+  appToken: "YOUR_APP_TOKEN",
+  appVersion: "1.0.0",
+  appFrameWork: "Next.js",
+  userEnvironment: WTUserEnvironment.SANDBOX,
+  logLevel: WTLogLevel.DEBUG,
+});
+```
+
+### 2️⃣ Start Tracking (Optional)
+
+```ts
+// Starts automatically if `startTrackerAutomatically` is true.
+// Otherwise, you can start manually:
+await WiseTrack.instance.startTracking();
+```
+
+### 3️⃣ Track a Custom Event
+
+```ts
+import { WTEvent } from "@your-scope/wisetrack-web";
+
+const signupEvent = new WTEvent.Default("signup");
+signupEvent.addParam("method", "Google");
+
+await WiseTrack.instance.trackEvent(signupEvent);
+```
+
+### 4️⃣ Track a Revenue Event
+
+```ts
+import { WTEvent, RevenueCurrency } from "@your-scope/wisetrack-web";
+
+const purchase = new WTEvent.Revenue("order_completed", 99.99, RevenueCurrency.USD);
+purchase.addParam("item_id", "SKU-123");
+
+await WiseTrack.instance.trackEvent(purchase);
+```
+
+---
+
+## ⚙️ Configuration Options
+
+| Key                         | Required | Description                                                    |
+| --------------------------- | -------- | -------------------------------------------------------------- |
+| `appToken`                  | ✅        | Your unique WiseTrack app token                                |
+| `appVersion`                | ✅        | Your app version                                               |
+| `appFrameWork`              | ✅        | The framework/platform name                                    |
+| `userEnvironment`           | ❌        | `WTUserEnvironment.SANDBOX` or `WTUserEnvironment.PRODUCTION`  |
+| `trackingWaitingTime`       | ❌        | Time in seconds to wait before tracking starts automatically   |
+| `startTrackerAutomatically` | ❌        | Whether to start tracking automatically (default: `true`)      |
+| `customDeviceId`            | ❌        | Provide your own device ID                                     |
+| `defaultTracker`            | ❌        | Optional tracker name                                          |
+| `logLevel`                  | ❌        | Logging level (`WTLogLevel.DEBUG` / `INFO` / `WARN` / `ERROR`) |
+
+---
+
+## 🧹 Flush / Stop Tracking
+
+```ts
+// Stop tracking and clear stored data
+WiseTrack.instance.flush();
+```
+
+---
+
+## 🔍 Log Level
+
+Set the SDK log level for debugging:
+
+```ts
+WiseTrack.instance.setLogLevel(WTLogLevel.DEBUG);
+```
+
+---
+
+## 📚 API Reference
+
+For detailed TypeDocs, see [📖 Full API Reference](./docs).
+
+---
+
+## 🛟 Support
+
+* [Documentation](./docs)
+* [Issues](https://github.com/wisetrack-io/web-sdk/issues)
+* Contact: [your-email@example.com](mailto:support@wisetrack.io)
+
+---
+
+## 📝 License
+
+MIT © [WiseTrack](https://wisetrack.io)

package/dist/cdn/constants/constants.d.ts

@@ -0,0 +1,20 @@
+import { WTLogLevel } from "../utils/logger";
+import { WTSDKEnvironment } from "./environments";
+/** @internal */
+export declare const WTConstants: {
+    readonly SDK: {
+        readonly HASH: "997bfbb583c1245a426a53dc1899ec779ff354f9";
+        readonly PLATFORM: "web";
+        readonly VERSION: "2.0.0";
+    };
+    readonly CONFIG: {
+        readonly BASE_URL: "https://config.wisetrack.io";
+        readonly DEFAULT_ENVIRONMENT: WTSDKEnvironment;
+    };
+    readonly DEFAULTS: {
+        readonly LOG_LEVEL: WTLogLevel;
+        readonly SESSION_INTERVAL: "1800000";
+        readonly SUBSESSION_INTERVAL: "300000";
+        readonly PARAMETERS_VALUE: string | undefined;
+    };
+};

package/dist/cdn/constants/endpoints.d.ts

@@ -0,0 +1,11 @@
+/** @internal */
+export declare const WTEndpoints: {
+    readonly EVENTS: "/api/v1/events";
+    readonly SESSIONS: "/api/v1/sessions";
+    readonly SDK_CLICKS: "/api/v1/sdk_clicks";
+    readonly SDK_INFOS: "/api/v1/sdk_infos";
+    readonly ATTRIBUTIONS: "/api/v1/attributions";
+    readonly APP_SETTINGS: "/api/v1/app_settings";
+};
+/** @internal */
+export type WTEndpoints = (typeof WTEndpoints)[keyof typeof WTEndpoints];

package/dist/cdn/constants/environments.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Defines the user environment in which the SDK is running.
+ *
+ * - `SANDBOX`: Use this for testing and development.
+ * - `PRODUCTION`: Use this for production deployment.
+ */
+export declare const WTUserEnvironment: {
+    readonly SANDBOX: "sandbox";
+    readonly PRODUCTION: "production";
+};
+export type WTUserEnvironment = (typeof WTUserEnvironment)[keyof typeof WTUserEnvironment];
+/** @internal */
+export declare const WTSDKEnvironment: {
+    readonly DEBUG: "debug";
+    readonly STAGE: "stage";
+    readonly PRODUCTION: "production";
+};
+/** @internal */
+export type WTSDKEnvironment = (typeof WTSDKEnvironment)[keyof typeof WTSDKEnvironment];
+/** @internal */
+export declare const EnvironmentUtils: {
+    sdkEnvironment: WTSDKEnvironment;
+    needAppSettings(): boolean;
+    baseUrl(): string;
+};

package/dist/cdn/core/caching/queue-data.d.ts

@@ -0,0 +1,25 @@
+import { WTEndpoints } from "../../constants/endpoints";
+import { FieldsBuilder } from "../fields/fields-builder";
+/** @internal */
+export interface RequestRecordCreator {
+    endpoint: WTEndpoints;
+    fBuilder?: FieldsBuilder;
+    queueType?: "main" | "pending";
+}
+/** @internal */
+export declare class RequestRecord {
+    readonly id: string;
+    readonly endpoint: WTEndpoints;
+    readonly parameters: Record<string, any>;
+    readonly createdAt: number;
+    retryCount: number;
+    maxRetries: number;
+    constructor(endpoint: WTEndpoints, parameters: Record<string, any>);
+}
+/** @internal */
+export declare class Mutex {
+    private locked;
+    private waitingQueue;
+    acquire(): Promise<void>;
+    release(): void;
+}

package/dist/cdn/core/caching/request-queue-manager.d.ts

@@ -0,0 +1,54 @@
+import { RequestRecord } from "./queue-data";
+/** @internal */
+export declare class RequestsQueueManager {
+    private isInitialized;
+    private isProcessing;
+    private isCurrentlyProcessing;
+    private mutex;
+    private processingInterval;
+    private readonly PROCESSING_INTERVAL_MS;
+    private failedRequestDelay;
+    private readonly MAX_DELAY_MS;
+    private readonly BACKOFF_MULTIPLIER;
+    private readonly BASE_DELAY_MS;
+    constructor();
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    private startProcessing;
+    private stopProcessing;
+    addRequest(request: RequestRecord): Promise<void>;
+    addPendingRequest(request: RequestRecord): Promise<void>;
+    private processQueues;
+    private processMainQueue;
+    private calculateBackoffDelay;
+    private processPendingQueue;
+    private sendRequest;
+    private getMainQueue;
+    private saveMainQueue;
+    private getPendingQueue;
+    private savePendingQueue;
+    private getMainRequestsSentFlag;
+    private postRequestCheck;
+    getQueueStatus(): {
+        mainQueueLength: number;
+        pendingQueueLength: number;
+        isProcessing: boolean;
+        mainRequestsSent: boolean;
+        isInBackoffDelay: boolean;
+        backoffEndsAt: number | null;
+    };
+    /**
+     * Manually reset backoff delay (useful for testing or manual recovery)
+     */
+    resetBackoffDelay(): void;
+    /**
+     * Get current backoff delay configuration
+     */
+    getBackoffConfig(): {
+        baseDelayMs: number;
+        multiplier: number;
+        maxDelayMs: number;
+    };
+}
+/** @internal */
+export declare const queueManager: RequestsQueueManager;

package/dist/cdn/core/fields/event-fields-builder.d.ts

@@ -0,0 +1,8 @@
+import { WTEvent } from "../../types/event/wt-event";
+import { FieldsBuilder } from "./fields-builder";
+/** @internal */
+export declare class EventFieldsBuilder extends FieldsBuilder {
+    event: WTEvent.Default | WTEvent.Revenue;
+    constructor(event: WTEvent.Default | WTEvent.Revenue);
+    build(): Promise<Record<string, any>>;
+}

package/dist/cdn/core/fields/fields-builder.d.ts

@@ -0,0 +1,9 @@
+/** @internal */
+export declare class FieldsBuilder {
+    build(): Promise<Record<string, any>>;
+    private getApplicationFields;
+    private getLocalFields;
+    private getDeviceFields;
+}
+/** @internal */
+export declare const fieldsBuilder: FieldsBuilder;

package/dist/cdn/core/network/api-client.d.ts

@@ -0,0 +1,9 @@
+import { WTEndpoints } from "../../constants/endpoints";
+import { WTAppSettings } from "../../types/config/wt-app-settings";
+import { WTConfig } from "../../types/config/wt-config";
+/** @internal */
+export declare const apiClient: {
+    doGetConfig(): Promise<WTConfig>;
+    doGetAppSettings(): Promise<WTAppSettings>;
+    doCallRequest(endpoint: WTEndpoints, params: Record<string, any>): Promise<boolean>;
+};

package/dist/cdn/core/network/network-error.d.ts

@@ -0,0 +1,17 @@
+/** @internal */
+export declare namespace ApiError {
+    class InvalidUrl extends Error {
+        constructor(url: string);
+    }
+    class ServerError extends Error {
+        statusCode: number;
+        message: string;
+        constructor(statusCode: number, message: string);
+    }
+    class NetworkError extends Error {
+        constructor(message: string);
+    }
+    class DecodingError extends Error {
+        constructor(message: string);
+    }
+}

package/dist/cdn/core/network/network-manager.d.ts

@@ -0,0 +1,22 @@
+import { RetryPolicy } from "./retry-policy";
+type HttpMethod = "GET" | "POST" | "PUT";
+/** @internal */
+export interface RequestOptions {
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    params?: Record<string, any>;
+    formData?: Record<string, any>;
+    retryAttempt?: number;
+}
+/** @internal */
+export interface ApiResponseWrapper {
+    success: boolean;
+    message?: string;
+    result?: any;
+}
+/** @internal */
+export declare const networkManager: {
+    readonly retryPolicy: () => RetryPolicy;
+    readonly sendRequest: (endpoint: string, options?: RequestOptions) => Promise<ApiResponseWrapper>;
+};
+export {};

package/dist/cdn/core/network/retry-policy.d.ts

@@ -0,0 +1,8 @@
+/** @internal */
+export declare class RetryPolicy {
+    private maxRetries;
+    private retryInterval;
+    constructor(maxRetries?: number, retryInterval?: number);
+    canRetry(attempt: number): boolean;
+    waitBeforeRetry(): Promise<void>;
+}

package/dist/cdn/core/storage/storage-manager.d.ts

@@ -0,0 +1,52 @@
+import { WTInitialConfig } from "../../types/config/initial-config";
+import { WTAppSettings } from "../../types/config/wt-app-settings";
+import { WTConfig } from "../../types/config/wt-config";
+import { RequestRecord } from "../caching/queue-data";
+declare class StorageManager {
+    clear(): void;
+    private setJson;
+    private getJson;
+    private optionalNumber;
+    private optionalBool;
+    get deviceId(): string | null;
+    set deviceId(value: string | null);
+    get initialDate(): string | null;
+    set initialDate(value: string | null);
+    get initialConfig(): WTInitialConfig | null;
+    set initialConfig(value: WTInitialConfig | null);
+    get config(): WTConfig | null;
+    set config(value: WTConfig | null);
+    get appSettings(): WTAppSettings | null;
+    set appSettings(value: WTAppSettings | null);
+    get sdkEnabled(): boolean;
+    set sdkEnabled(value: boolean);
+    get sdkClickSubmit(): boolean;
+    set sdkClickSubmit(value: boolean);
+    get firstSessionSubmit(): boolean;
+    set firstSessionSubmit(value: boolean);
+    get fcmToken(): string | null;
+    set fcmToken(value: string | null);
+    get pushToken(): string | null;
+    set pushToken(value: string | null);
+    get sessionCount(): number;
+    set sessionCount(value: number);
+    get subSessionCount(): number;
+    set subSessionCount(value: number);
+    get activeDuration(): number;
+    set activeDuration(value: number);
+    get inactiveDuration(): number;
+    set inactiveDuration(value: number);
+    get inactiveTime(): number | null;
+    set inactiveTime(value: number | null);
+    get activeTime(): number | null;
+    set activeTime(value: number | null);
+    get requestRecords(): RequestRecord[];
+    set requestRecords(value: RequestRecord[]);
+    get pendingRequestRecords(): RequestRecord[];
+    set pendingRequestRecords(value: RequestRecord[]);
+    get eventCount(): number;
+    set eventCount(value: number);
+}
+/** @internal */
+export declare const storageManager: StorageManager;
+export {};

package/dist/cdn/core/wisetrack.d.ts

@@ -0,0 +1,125 @@
+import { WTInitialConfig } from "../types/config/initial-config";
+import { WTEvent } from "../types/event/wt-event";
+import { WTLogLevel } from "../utils/logger";
+/**
+ * The main entry point for the WiseTrack Web SDK.
+ *
+ * Use this singleton to initialize the SDK, configure its behavior, and track events.
+ *
+ * @example
+ * ```ts
+ * const initialConfig: WTInitialConfig = {
+ *  appToken: appToken ?? "rMN5ZCwpOzY7",
+ *  appFrameWork: "native",
+ *  appVersion: "1.0.0",
+ * };
+ * await WiseTrack.instance.init(initialConfig);
+ * ```
+ */
+export declare class WiseTrack {
+    private static _instance?;
+    /**
+     * Returns the singleton instance of the WiseTrack SDK.
+     */
+    static get instance(): WiseTrack;
+    private constructor();
+    private sdkInitialized;
+    /**
+     * Initializes the WiseTrack SDK with the given configuration.
+     *
+     * This method must be called before using any tracking features.
+     *
+     * @param initConfig - The initial configuration object.
+     *
+     * @example
+     * ```ts
+     * const initialConfig: WTInitialConfig = {
+     *  appToken: appToken ?? "rMN5ZCwpOzY7",
+     *  appFrameWork: "native", // your current web app framework (native, reactjs, nextjs, ...)
+     *  appVersion: "1.0.0", // your current web app version
+     * };
+     *
+     * ```
+     */
+    init(initConfig: WTInitialConfig): Promise<void>;
+    /**
+     * Sets the log level for internal SDK logging.
+     *
+     * @param level - The desired log level.
+     *
+     * @example
+     * ```ts
+     * WiseTrack.instance.setLogLevel(WTLogLevel.WARN)
+     * // or
+     * WiseTrack.instance.setLogLevel("warn")
+     *
+     * ```
+     */
+    setLogLevel(level: WTLogLevel): void;
+    /**
+     * Clears all stored data and stops the tracker.
+     */
+    flush(): void;
+    /**
+     * Returns whether the SDK is currently enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Enables or disables the SDK.
+     *
+     * Throws an error if the SDK is disabled by the server or needs an update.
+     *
+     * @param enabled - Whether to enable the SDK.
+     * @throws If the server has disabled the SDK or a forced update is required.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Starts the tracking process.
+     *
+     * @remarks
+     * The SDK must be initialized and enabled before calling this method.
+     *
+     * NOTE: call this method just if you set startTrackerAutomatically=false in WTInitialConfig
+     */
+    startTracking(): Promise<void>;
+    /**
+     * Stops the tracking process.
+     */
+    stopTracking(): Promise<void>;
+    /**
+     * Sets the Firebase Cloud Messaging (FCM) push token for server.
+     *
+     * @param token - The FCM token.
+     */
+    setFCMToken(token: string): Promise<void>;
+    /**
+     * Tracks a custom event or revenue event.
+     *
+     * @param event - The event object to be tracked.
+     *
+     * @example
+     * ```ts
+     * // Create a Default Event
+     * const defaultEvent = new WTEvent.Default("default-event");
+     * defaultEvent.addParam("key1", "value1");
+     * defaultEvent.addParam("key2", 123);
+     * defaultEvent.addParam("key3", true);
+     * await WiseTrack.instance.trackEvent(defaultEvent);
+     *
+     * // Create a Revenue Event
+     * const revenueEvent = new WTEvent.Revenue("revenue-event", 100, "USD");
+     * revenueEvent.addParam("item_id", "item123");
+     * revenueEvent.addParam("quantity", 2);
+     * await WiseTrack.instance.trackEvent(revenueEvent);
+     * ```
+     */
+    trackEvent(event: WTEvent.Default | WTEvent.Revenue): Promise<void>;
+    /** @internal */
+    private getConfig;
+    /** @internal */
+    private updateAppSettings;
+    /** @internal */
+    private checkSdkEnabled;
+    /** @internal */
+    private checkSdkUpdate;
+}

package/dist/cdn/core/wt-tracker.d.ts

@@ -0,0 +1,25 @@
+import { WTEvent } from "../types/event/wt-event";
+/** @internal */
+declare class WTTracker {
+    private isRunning;
+    private initialized;
+    private get isEnabled();
+    initialize(): Promise<void>;
+    startTracking(): Promise<void>;
+    stopTracking(): Promise<void>;
+    checkPushToken(token: string): Promise<void>;
+    trackEvent(event: WTEvent.Default | WTEvent.Revenue): Promise<void>;
+    private getCountryCode;
+    private createAttribution;
+    private checkFirstSession;
+    private checkSdkClicks;
+    private createRequest;
+    private createDeviceID;
+    private setActivityTimes;
+    private checkSessionIntervals;
+    private isVisibleFocused;
+    private addObservers;
+}
+/** @internal */
+export declare const tracker: WTTracker;
+export {};

package/dist/cdn/index.d.ts

@@ -0,0 +1,4 @@
+export { WiseTrack } from "./core/wisetrack";
+export { WTInitialConfig } from "./types/config/initial-config";
+export { WTEvent } from "./types/event/wt-event";
+export { WTLogEngine, WTLogger, WTLogLevel } from "./utils/logger";