alphana-sdk 1.6.6 → 1.9.0

package/dist/index.d.mts

@@ -4,6 +4,11 @@ interface TrackerConfig {
      * Defaults to `https://api.alphana.ir/api/events` (Alphana Cloud).
      */
     endpoint?: string;
+    /**
+     * Override unified ingest URL. When omitted, derived from `endpoint` as
+     * `…/api/collect`.
+     */
+    collectEndpoint?: string;
     /**
      * App ID obtained from the UserTracker dashboard.
      * Sent in every request body so the backend associates events with the correct app.
@@ -39,6 +44,16 @@ interface TrackerConfig {
      * Default: 5000 (5 s)
      */
     flushInterval?: number;
+    /**
+     * Gzip-compress large ingest payloads before upload when the browser supports
+     * `CompressionStream`. Default: true
+     */
+    compressPayloads?: boolean;
+    /**
+     * Minimum UTF-8 JSON size (bytes) before gzip compression is attempted.
+     * Default: 1024
+     */
+    compressionThresholdBytes?: number;
     /**
      * Automatically capture console.info/warn/error, window.onerror, and
      * unhandledrejection events and send them to the backend log endpoint.
@@ -46,15 +61,11 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured client-side.
-     * Paths should match the dashboard "Heatmap pages" list (decoded Unicode is
-     * fine — the SDK normalizes percent-encoding vs `window.location` mismatches).
-     *
-     * If empty or undefined, the SDK may still collect moves locally, but the
-     * backend only persists points when the app has at least one registered
-     * heatmap page and the path matches.
-     *
-     * Example: `heatmapPages: ["/", "/pricing", "/dashboard"]`
+     * @deprecated Optional client-side path filter only. Heatmap pages are
+     * registered in the Alphana dashboard; the backend persists points only for
+     * those paths. Leave unset so the SDK collects on every page and the server
+     * filters — no SDK configuration is required when you add a page in the
+     * dashboard.
      */
     heatmapPages?: string[];
     /**
@@ -144,11 +155,23 @@ interface HeatmapPoint {
     pw?: number;
     /** Page scrollHeight at the time of the event (used for accurate remapping) */
     ph?: number;
+    /** Viewport (innerWidth) at capture time — disambiguates responsive layouts. */
+    vw?: number;
     type: "move" | "click" | "scroll";
     path: string;
     timestamp: number;
     /** Text/label of the clicked element — only present on click events. */
     target?: string;
+    /**
+     * Stable CSS selector of the anchored element (clicks only). Lets the
+     * dashboard place the point relative to the element in the screenshot, so it
+     * stays accurate even when the visitor's layout differed from the capture.
+     */
+    selector?: string;
+    /** Click X as a fraction (0–1) of the anchored element's width (clicks only). */
+    relX?: number;
+    /** Click Y as a fraction (0–1) of the anchored element's height (clicks only). */
+    relY?: number;
 }
 interface RageClick {
     path: string;
@@ -357,15 +380,17 @@ interface LogEntry {
 }
 /**
  * Automatically captures console.info/warn/error output and unhandled errors,
- * then ships them to the backend `/logs/ingest` endpoint.
+ * then ships them to the unified `/api/collect` ingest endpoint.
  *
  * All console methods are restored exactly in `destroy()`.
  */
 declare class LogCapture {
-    private readonly endpoint;
+    private readonly collectUrl;
     private readonly sessionId;
     private readonly appId?;
     private readonly authHeaders;
+    private readonly compressPayloads;
+    private readonly compressionThresholdBytes;
     private origInfo;
     private origWarn;
     private origError;
@@ -374,9 +399,12 @@ declare class LogCapture {
     private initialized;
     constructor(options: {
         endpoint: string;
+        collectEndpoint?: string;
         sessionId: string;
         secretKey?: string;
         appId?: string;
+        compressPayloads?: boolean;
+        compressionThresholdBytes?: number;
     });
     init(): void;
     destroy(): void;
@@ -540,6 +568,8 @@ declare class UserTracker {
     getHeatmapData(path: string): HeatmapPoint[];
     /** Heatmap points for all tracked paths. */
     getHeatmapData(): Record<string, HeatmapPoint[]>;
+    private get collectUrl();
+    private currentPath;
     /**
      * Immediately drain the event queue and POST pending events to `/batch`.
      * Fire-and-forget; errors are intentionally swallowed like other analytics calls.
@@ -553,7 +583,6 @@ declare class UserTracker {
      * cancelled by the browser before it completes.
      */
     private flushBeacon;
-    private buildBatchBody;
     private sendBatch;
 }
 

package/dist/index.d.ts

@@ -4,6 +4,11 @@ interface TrackerConfig {
      * Defaults to `https://api.alphana.ir/api/events` (Alphana Cloud).
      */
     endpoint?: string;
+    /**
+     * Override unified ingest URL. When omitted, derived from `endpoint` as
+     * `…/api/collect`.
+     */
+    collectEndpoint?: string;
     /**
      * App ID obtained from the UserTracker dashboard.
      * Sent in every request body so the backend associates events with the correct app.
@@ -39,6 +44,16 @@ interface TrackerConfig {
      * Default: 5000 (5 s)
      */
     flushInterval?: number;
+    /**
+     * Gzip-compress large ingest payloads before upload when the browser supports
+     * `CompressionStream`. Default: true
+     */
+    compressPayloads?: boolean;
+    /**
+     * Minimum UTF-8 JSON size (bytes) before gzip compression is attempted.
+     * Default: 1024
+     */
+    compressionThresholdBytes?: number;
     /**
      * Automatically capture console.info/warn/error, window.onerror, and
      * unhandledrejection events and send them to the backend log endpoint.
@@ -46,15 +61,11 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured client-side.
-     * Paths should match the dashboard "Heatmap pages" list (decoded Unicode is
-     * fine — the SDK normalizes percent-encoding vs `window.location` mismatches).
-     *
-     * If empty or undefined, the SDK may still collect moves locally, but the
-     * backend only persists points when the app has at least one registered
-     * heatmap page and the path matches.
-     *
-     * Example: `heatmapPages: ["/", "/pricing", "/dashboard"]`
+     * @deprecated Optional client-side path filter only. Heatmap pages are
+     * registered in the Alphana dashboard; the backend persists points only for
+     * those paths. Leave unset so the SDK collects on every page and the server
+     * filters — no SDK configuration is required when you add a page in the
+     * dashboard.
      */
     heatmapPages?: string[];
     /**
@@ -144,11 +155,23 @@ interface HeatmapPoint {
     pw?: number;
     /** Page scrollHeight at the time of the event (used for accurate remapping) */
     ph?: number;
+    /** Viewport (innerWidth) at capture time — disambiguates responsive layouts. */
+    vw?: number;
     type: "move" | "click" | "scroll";
     path: string;
     timestamp: number;
     /** Text/label of the clicked element — only present on click events. */
     target?: string;
+    /**
+     * Stable CSS selector of the anchored element (clicks only). Lets the
+     * dashboard place the point relative to the element in the screenshot, so it
+     * stays accurate even when the visitor's layout differed from the capture.
+     */
+    selector?: string;
+    /** Click X as a fraction (0–1) of the anchored element's width (clicks only). */
+    relX?: number;
+    /** Click Y as a fraction (0–1) of the anchored element's height (clicks only). */
+    relY?: number;
 }
 interface RageClick {
     path: string;
@@ -357,15 +380,17 @@ interface LogEntry {
 }
 /**
  * Automatically captures console.info/warn/error output and unhandled errors,
- * then ships them to the backend `/logs/ingest` endpoint.
+ * then ships them to the unified `/api/collect` ingest endpoint.
  *
  * All console methods are restored exactly in `destroy()`.
  */
 declare class LogCapture {
-    private readonly endpoint;
+    private readonly collectUrl;
     private readonly sessionId;
     private readonly appId?;
     private readonly authHeaders;
+    private readonly compressPayloads;
+    private readonly compressionThresholdBytes;
     private origInfo;
     private origWarn;
     private origError;
@@ -374,9 +399,12 @@ declare class LogCapture {
     private initialized;
     constructor(options: {
         endpoint: string;
+        collectEndpoint?: string;
         sessionId: string;
         secretKey?: string;
         appId?: string;
+        compressPayloads?: boolean;
+        compressionThresholdBytes?: number;
     });
     init(): void;
     destroy(): void;
@@ -540,6 +568,8 @@ declare class UserTracker {
     getHeatmapData(path: string): HeatmapPoint[];
     /** Heatmap points for all tracked paths. */
     getHeatmapData(): Record<string, HeatmapPoint[]>;
+    private get collectUrl();
+    private currentPath;
     /**
      * Immediately drain the event queue and POST pending events to `/batch`.
      * Fire-and-forget; errors are intentionally swallowed like other analytics calls.
@@ -553,7 +583,6 @@ declare class UserTracker {
      * cancelled by the browser before it completes.
      */
     private flushBeacon;
-    private buildBatchBody;
     private sendBatch;
 }