alphana-sdk 1.0.0 → 1.5.0

package/dist/index.d.mts

@@ -46,19 +46,34 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured.
-     * Only paths registered here will be tracked. If empty or undefined, the SDK
-     * will send data for all pages (the backend enforces limits at ingest time).
+     * 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).
      *
-     * Obtain the list of registered paths from the alphana dashboard under
-     * "Heatmap Pages" for your app, then pass them here.
+     * 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"]`
      */
     heatmapPages?: string[];
+    /**
+     * When true, records DOM mutations with rrweb and sends `session_replay` events
+     * for pixel-accurate session replay in the dashboard (requires plan + platform).
+     * @default false
+     */
+    sessionReplay?: boolean;
+    /** rrweb full snapshot interval in ms. @default 600000 (10 min) */
+    sessionReplayCheckoutEveryNms?: number;
+    /** Max rrweb events per batch before an immediate flush. @default 48 */
+    sessionReplayMaxEventsPerBatch?: number;
+    /** Periodic flush of buffered rrweb events (ms). @default 4000 */
+    sessionReplayFlushIntervalMs?: number;
     /** Called synchronously for every emitted event. */
     onEvent?: (event: TrackerEvent) => void;
 }
+/** Assigned variant key per running A/B experiment (`null` = not in experiment). */
+type AbVariantsMap = Record<string, string | null>;
 interface GeoLocation {
     /** ISO 3166-1 alpha-2 country code, e.g. "US" */
     country: string;
@@ -69,12 +84,32 @@ interface GeoLocation {
     latitude?: number;
     longitude?: number;
 }
+interface UtmParams {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+interface AttributionContext {
+    landingPage: string;
+    referrer?: string;
+    referrerHost?: string;
+    utm?: UtmParams;
+    clickIds?: Record<string, string>;
+    capturedAt: number;
+}
 interface PageView {
     path: string;
     title: string;
     timestamp: number;
     sessionId: string;
     referrer?: string;
+    utm?: UtmParams;
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
 }
 interface TimeSpent {
     path: string;
@@ -121,6 +156,97 @@ interface UTurn {
     timestamp: number;
     sessionId: string;
 }
+type UserProperties = Record<string, string>;
+interface IdentifyEvent {
+    properties: UserProperties;
+    visitorId: string;
+    timestamp: number;
+}
+type RevenueEventStatus = "pending" | "paid" | "refunded" | "cancelled" | "failed";
+interface RevenueLineItem {
+    id?: string;
+    name?: string;
+    category?: string;
+    quantity?: number;
+    price?: number;
+}
+interface RevenueEventPayload {
+    eventName?: "purchase" | "subscription" | "renewal" | "upgrade" | "refund" | string;
+    amount: number;
+    currency: string;
+    transactionId?: string;
+    orderId?: string;
+    productId?: string;
+    planId?: string;
+    coupon?: string;
+    status?: RevenueEventStatus;
+    items?: RevenueLineItem[];
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface RevenueEvent extends RevenueEventPayload {
+    sessionId: string;
+    visitorId: string;
+    timestamp: number;
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
+}
+interface GoalEventPayload {
+    key: string;
+    name?: string;
+    value?: number;
+    currency?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface GoalEvent extends GoalEventPayload {
+    sessionId: string;
+    visitorId: string;
+    path: string;
+    timestamp: number;
+}
+interface JourneyStepEventPayload {
+    key: string;
+    label?: string;
+    path?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface JourneyStepEvent extends JourneyStepEventPayload {
+    sessionId: string;
+    visitorId: string;
+    path: string;
+    timestamp: number;
+}
+/**
+ * One-time (or rare) snapshot of the client environment for a session.
+ * Lets the backend align device / OS / browser with what the browser reports
+ * (useful vs. reduced User-Agent strings) and store locale / viewport context
+ * for session replay catalog rows.
+ */
+interface ClientContext {
+    sessionId: string;
+    timestamp: number;
+    device: "desktop" | "mobile" | "tablet";
+    os: string;
+    browser: string;
+    language: string;
+    languages: string[];
+    /** `prefers-color-scheme` when available */
+    colorScheme: "" | "light" | "dark";
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    /** IANA time zone from `Intl`, e.g. `Asia/Tehran` */
+    timeZone: string;
+    sdkVersion: string;
+}
+/** One batch of rrweb `eventWithTime` payloads for the backend. */
+interface SessionReplayBatch {
+    seq: number;
+    events: unknown[];
+}
 type TrackerEvent = {
     type: "pageview";
     data: PageView;
@@ -136,6 +262,24 @@ type TrackerEvent = {
 } | {
     type: "uturn";
     data: UTurn;
+} | {
+    type: "identify";
+    data: IdentifyEvent;
+} | {
+    type: "revenue";
+    data: RevenueEvent;
+} | {
+    type: "goal";
+    data: GoalEvent;
+} | {
+    type: "journey_step";
+    data: JourneyStepEvent;
+} | {
+    type: "client_context";
+    data: ClientContext;
+} | {
+    type: "session_replay";
+    data: SessionReplayBatch;
 };
 interface SessionData {
     id: string;
@@ -147,6 +291,13 @@ interface SessionData {
     timeSpent: Record<string, number>;
     /** Collected points per path */
     heatmap: Record<string, HeatmapPoint[]>;
+    /** Latest properties supplied through identify(). */
+    userProperties: UserProperties;
+    /** First and latest marketing touchpoints captured for this visitor. */
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
     /** Approximate visitor location resolved from IP (filled asynchronously) */
     location?: GeoLocation;
 }
@@ -215,12 +366,14 @@ declare class LogCapture {
 declare const DEFAULT_ENDPOINT = "https://api.alphana.ir/api/events";
 type SubscriberFn = (event: TrackerEvent) => void;
 type FlagSubscriberFn = (flags: Record<string, boolean>) => void;
+type AbTestSubscriberFn = (variants: AbVariantsMap) => void;
 declare class UserTracker {
     private readonly cfg;
     private session;
     private navigation?;
     private time?;
     private heatmap?;
+    private sessionReplay?;
     /** Public so consumers can call logCapture.capture() for manual log entries. */
     logCapture?: LogCapture;
     private initialized;
@@ -232,7 +385,11 @@ declare class UserTracker {
     private userProperties;
     private flags;
     private readonly flagSubscribers;
+    private abVariants;
+    private readonly abTestSubscribers;
     constructor(config?: TrackerConfig);
+    private updateAttributionForPageView;
+    private currentAttribution;
     /**
      * Attach event listeners and start tracking.
      * Safe to call during SSR — returns `this` immediately if `window` is
@@ -277,6 +434,16 @@ declare class UserTracker {
      * ```
      */
     trackPageView(path?: string): void;
+    /**
+     * Track a monetary conversion such as a purchase, subscription, renewal,
+     * upgrade, or refund. Revenue events include the current attribution context
+     * so the backend can credit campaigns without recomputing browser state.
+     */
+    trackRevenue(payload: RevenueEventPayload): void;
+    /** Track a business goal such as signup, trial_start, lead, or checkout_start. */
+    trackGoal(payload: GoalEventPayload): void;
+    /** Track a named product journey milestone beyond automatic pageviews. */
+    trackJourneyStep(payload: JourneyStepEventPayload): void;
     /**
      * Identify the current user with a set of properties.
      * Properties are merged with any previously set ones and used for feature
@@ -309,6 +476,34 @@ declare class UserTracker {
     onFlagsChange(fn: FlagSubscriberFn): () => void;
     /** Fetch (or re-fetch) flags from the backend evaluate endpoint. */
     fetchFlags(): Promise<void>;
+    /**
+     * Returns variant keys assigned to this visitor for each running experiment.
+     * Fetched on `init()` and after `fetchAbTests()`.
+     *
+     * ```ts
+     * const variants = tracker.getAbVariants();
+     * // { 'checkout-cta-test': 'variant-b' }
+     * ```
+     */
+    getAbVariants(): AbVariantsMap;
+    /**
+     * Returns the assigned variant key for one experiment, or `null` if the
+     * experiment is not running or not found.
+     */
+    getAbVariant(experimentKey: string): string | null;
+    /**
+     * Returns `true` when the visitor is assigned to the given variant key.
+     */
+    isAbVariant(experimentKey: string, variantKey: string): boolean;
+    /**
+     * Subscribe to A/B assignment updates. Returns an unsubscribe function.
+     */
+    onAbTestsChange(fn: AbTestSubscriberFn): () => void;
+    /**
+     * Fetch (or re-fetch) variant assignments from `/ab-tests/evaluate`.
+     * @param keys When set, only these experiment keys are evaluated and merged.
+     */
+    fetchAbTests(keys?: string[]): Promise<void>;
     /** A read-only snapshot of the current session. */
     getSession(): Readonly<SessionData>;
     /** All page views recorded so far. */
@@ -336,4 +531,15 @@ declare class UserTracker {
     private sendBatch;
 }
 
-export { DEFAULT_ENDPOINT, type GeoLocation, type HeatmapPoint, type HeatmapRenderOptions, LogCapture, type LogEntry, type LogLevel, type PageView, type RageClick, type SessionData, type TimeSpent, type TrackerConfig, type TrackerEvent, type UTurn, UserTracker };
+declare const ALPHANA_SDK_VERSION = "1.0.2";
+
+/**
+ * Canonical URL path (+ optional query) for analytics / heatmap matching.
+ *
+ * Next.js `usePathname()` often returns percent-encoded segments while
+ * `window.location.pathname` is decoded — without normalization the backend
+ * cannot match registered heatmap pages or aggregate the same route.
+ */
+declare function normalizeTrackerPath(path: string): string;
+
+export { ALPHANA_SDK_VERSION, type AbVariantsMap, type AttributionContext, type ClientContext, DEFAULT_ENDPOINT, type GeoLocation, type GoalEvent, type GoalEventPayload, type HeatmapPoint, type HeatmapRenderOptions, type JourneyStepEvent, type JourneyStepEventPayload, LogCapture, type LogEntry, type LogLevel, type PageView, type RageClick, type RevenueEvent, type RevenueEventPayload, type RevenueEventStatus, type RevenueLineItem, type SessionData, type TimeSpent, type TrackerConfig, type TrackerEvent, type UTurn, UserTracker, type UtmParams, normalizeTrackerPath };

package/dist/index.d.ts

@@ -46,19 +46,34 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured.
-     * Only paths registered here will be tracked. If empty or undefined, the SDK
-     * will send data for all pages (the backend enforces limits at ingest time).
+     * 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).
      *
-     * Obtain the list of registered paths from the alphana dashboard under
-     * "Heatmap Pages" for your app, then pass them here.
+     * 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"]`
      */
     heatmapPages?: string[];
+    /**
+     * When true, records DOM mutations with rrweb and sends `session_replay` events
+     * for pixel-accurate session replay in the dashboard (requires plan + platform).
+     * @default false
+     */
+    sessionReplay?: boolean;
+    /** rrweb full snapshot interval in ms. @default 600000 (10 min) */
+    sessionReplayCheckoutEveryNms?: number;
+    /** Max rrweb events per batch before an immediate flush. @default 48 */
+    sessionReplayMaxEventsPerBatch?: number;
+    /** Periodic flush of buffered rrweb events (ms). @default 4000 */
+    sessionReplayFlushIntervalMs?: number;
     /** Called synchronously for every emitted event. */
     onEvent?: (event: TrackerEvent) => void;
 }
+/** Assigned variant key per running A/B experiment (`null` = not in experiment). */
+type AbVariantsMap = Record<string, string | null>;
 interface GeoLocation {
     /** ISO 3166-1 alpha-2 country code, e.g. "US" */
     country: string;
@@ -69,12 +84,32 @@ interface GeoLocation {
     latitude?: number;
     longitude?: number;
 }
+interface UtmParams {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+interface AttributionContext {
+    landingPage: string;
+    referrer?: string;
+    referrerHost?: string;
+    utm?: UtmParams;
+    clickIds?: Record<string, string>;
+    capturedAt: number;
+}
 interface PageView {
     path: string;
     title: string;
     timestamp: number;
     sessionId: string;
     referrer?: string;
+    utm?: UtmParams;
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
 }
 interface TimeSpent {
     path: string;
@@ -121,6 +156,97 @@ interface UTurn {
     timestamp: number;
     sessionId: string;
 }
+type UserProperties = Record<string, string>;
+interface IdentifyEvent {
+    properties: UserProperties;
+    visitorId: string;
+    timestamp: number;
+}
+type RevenueEventStatus = "pending" | "paid" | "refunded" | "cancelled" | "failed";
+interface RevenueLineItem {
+    id?: string;
+    name?: string;
+    category?: string;
+    quantity?: number;
+    price?: number;
+}
+interface RevenueEventPayload {
+    eventName?: "purchase" | "subscription" | "renewal" | "upgrade" | "refund" | string;
+    amount: number;
+    currency: string;
+    transactionId?: string;
+    orderId?: string;
+    productId?: string;
+    planId?: string;
+    coupon?: string;
+    status?: RevenueEventStatus;
+    items?: RevenueLineItem[];
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface RevenueEvent extends RevenueEventPayload {
+    sessionId: string;
+    visitorId: string;
+    timestamp: number;
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
+}
+interface GoalEventPayload {
+    key: string;
+    name?: string;
+    value?: number;
+    currency?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface GoalEvent extends GoalEventPayload {
+    sessionId: string;
+    visitorId: string;
+    path: string;
+    timestamp: number;
+}
+interface JourneyStepEventPayload {
+    key: string;
+    label?: string;
+    path?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface JourneyStepEvent extends JourneyStepEventPayload {
+    sessionId: string;
+    visitorId: string;
+    path: string;
+    timestamp: number;
+}
+/**
+ * One-time (or rare) snapshot of the client environment for a session.
+ * Lets the backend align device / OS / browser with what the browser reports
+ * (useful vs. reduced User-Agent strings) and store locale / viewport context
+ * for session replay catalog rows.
+ */
+interface ClientContext {
+    sessionId: string;
+    timestamp: number;
+    device: "desktop" | "mobile" | "tablet";
+    os: string;
+    browser: string;
+    language: string;
+    languages: string[];
+    /** `prefers-color-scheme` when available */
+    colorScheme: "" | "light" | "dark";
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    /** IANA time zone from `Intl`, e.g. `Asia/Tehran` */
+    timeZone: string;
+    sdkVersion: string;
+}
+/** One batch of rrweb `eventWithTime` payloads for the backend. */
+interface SessionReplayBatch {
+    seq: number;
+    events: unknown[];
+}
 type TrackerEvent = {
     type: "pageview";
     data: PageView;
@@ -136,6 +262,24 @@ type TrackerEvent = {
 } | {
     type: "uturn";
     data: UTurn;
+} | {
+    type: "identify";
+    data: IdentifyEvent;
+} | {
+    type: "revenue";
+    data: RevenueEvent;
+} | {
+    type: "goal";
+    data: GoalEvent;
+} | {
+    type: "journey_step";
+    data: JourneyStepEvent;
+} | {
+    type: "client_context";
+    data: ClientContext;
+} | {
+    type: "session_replay";
+    data: SessionReplayBatch;
 };
 interface SessionData {
     id: string;
@@ -147,6 +291,13 @@ interface SessionData {
     timeSpent: Record<string, number>;
     /** Collected points per path */
     heatmap: Record<string, HeatmapPoint[]>;
+    /** Latest properties supplied through identify(). */
+    userProperties: UserProperties;
+    /** First and latest marketing touchpoints captured for this visitor. */
+    attribution?: {
+        firstTouch?: AttributionContext;
+        lastTouch?: AttributionContext;
+    };
     /** Approximate visitor location resolved from IP (filled asynchronously) */
     location?: GeoLocation;
 }
@@ -215,12 +366,14 @@ declare class LogCapture {
 declare const DEFAULT_ENDPOINT = "https://api.alphana.ir/api/events";
 type SubscriberFn = (event: TrackerEvent) => void;
 type FlagSubscriberFn = (flags: Record<string, boolean>) => void;
+type AbTestSubscriberFn = (variants: AbVariantsMap) => void;
 declare class UserTracker {
     private readonly cfg;
     private session;
     private navigation?;
     private time?;
     private heatmap?;
+    private sessionReplay?;
     /** Public so consumers can call logCapture.capture() for manual log entries. */
     logCapture?: LogCapture;
     private initialized;
@@ -232,7 +385,11 @@ declare class UserTracker {
     private userProperties;
     private flags;
     private readonly flagSubscribers;
+    private abVariants;
+    private readonly abTestSubscribers;
     constructor(config?: TrackerConfig);
+    private updateAttributionForPageView;
+    private currentAttribution;
     /**
      * Attach event listeners and start tracking.
      * Safe to call during SSR — returns `this` immediately if `window` is
@@ -277,6 +434,16 @@ declare class UserTracker {
      * ```
      */
     trackPageView(path?: string): void;
+    /**
+     * Track a monetary conversion such as a purchase, subscription, renewal,
+     * upgrade, or refund. Revenue events include the current attribution context
+     * so the backend can credit campaigns without recomputing browser state.
+     */
+    trackRevenue(payload: RevenueEventPayload): void;
+    /** Track a business goal such as signup, trial_start, lead, or checkout_start. */
+    trackGoal(payload: GoalEventPayload): void;
+    /** Track a named product journey milestone beyond automatic pageviews. */
+    trackJourneyStep(payload: JourneyStepEventPayload): void;
     /**
      * Identify the current user with a set of properties.
      * Properties are merged with any previously set ones and used for feature
@@ -309,6 +476,34 @@ declare class UserTracker {
     onFlagsChange(fn: FlagSubscriberFn): () => void;
     /** Fetch (or re-fetch) flags from the backend evaluate endpoint. */
     fetchFlags(): Promise<void>;
+    /**
+     * Returns variant keys assigned to this visitor for each running experiment.
+     * Fetched on `init()` and after `fetchAbTests()`.
+     *
+     * ```ts
+     * const variants = tracker.getAbVariants();
+     * // { 'checkout-cta-test': 'variant-b' }
+     * ```
+     */
+    getAbVariants(): AbVariantsMap;
+    /**
+     * Returns the assigned variant key for one experiment, or `null` if the
+     * experiment is not running or not found.
+     */
+    getAbVariant(experimentKey: string): string | null;
+    /**
+     * Returns `true` when the visitor is assigned to the given variant key.
+     */
+    isAbVariant(experimentKey: string, variantKey: string): boolean;
+    /**
+     * Subscribe to A/B assignment updates. Returns an unsubscribe function.
+     */
+    onAbTestsChange(fn: AbTestSubscriberFn): () => void;
+    /**
+     * Fetch (or re-fetch) variant assignments from `/ab-tests/evaluate`.
+     * @param keys When set, only these experiment keys are evaluated and merged.
+     */
+    fetchAbTests(keys?: string[]): Promise<void>;
     /** A read-only snapshot of the current session. */
     getSession(): Readonly<SessionData>;
     /** All page views recorded so far. */
@@ -336,4 +531,15 @@ declare class UserTracker {
     private sendBatch;
 }
 
-export { DEFAULT_ENDPOINT, type GeoLocation, type HeatmapPoint, type HeatmapRenderOptions, LogCapture, type LogEntry, type LogLevel, type PageView, type RageClick, type SessionData, type TimeSpent, type TrackerConfig, type TrackerEvent, type UTurn, UserTracker };
+declare const ALPHANA_SDK_VERSION = "1.0.2";
+
+/**
+ * Canonical URL path (+ optional query) for analytics / heatmap matching.
+ *
+ * Next.js `usePathname()` often returns percent-encoded segments while
+ * `window.location.pathname` is decoded — without normalization the backend
+ * cannot match registered heatmap pages or aggregate the same route.
+ */
+declare function normalizeTrackerPath(path: string): string;
+
+export { ALPHANA_SDK_VERSION, type AbVariantsMap, type AttributionContext, type ClientContext, DEFAULT_ENDPOINT, type GeoLocation, type GoalEvent, type GoalEventPayload, type HeatmapPoint, type HeatmapRenderOptions, type JourneyStepEvent, type JourneyStepEventPayload, LogCapture, type LogEntry, type LogLevel, type PageView, type RageClick, type RevenueEvent, type RevenueEventPayload, type RevenueEventStatus, type RevenueLineItem, type SessionData, type TimeSpent, type TrackerConfig, type TrackerEvent, type UTurn, UserTracker, type UtmParams, normalizeTrackerPath };