alphana-sdk 1.0.0 → 1.5.0

package/dist/react/index.d.mts

@@ -49,19 +49,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;
@@ -72,12 +87,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;
@@ -124,6 +159,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;
@@ -139,6 +265,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;
@@ -150,6 +294,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;
 }
@@ -221,12 +372,14 @@ declare class LogCapture {
 
 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;
@@ -238,7 +391,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
@@ -283,6 +440,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
@@ -315,6 +482,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. */
@@ -380,6 +575,9 @@ declare function useHeatmapData(path?: string, refreshMs?: number): HeatmapPoint
  * Returns a live array of all page views recorded in the current session.
  */
 declare function usePageViews(): PageView[];
+declare function useTrackRevenue(): (payload: RevenueEventPayload) => void;
+declare function useTrackGoal(): (payload: GoalEventPayload) => void;
+declare function useTrackJourneyStep(): (payload: JourneyStepEventPayload) => void;
 /**
  * Returns a live record of cumulative milliseconds spent per path.
  */
@@ -398,5 +596,29 @@ declare function useFeatureFlags(): Record<string, boolean>;
  * ```
  */
 declare function useFeatureFlagEnabled(flagKey: string): boolean;
+/**
+ * Returns all assigned A/B variants as `{ [experimentKey]: variantKey | null }`.
+ * Re-renders when assignments are fetched (on `init()` or `fetchAbTests()`).
+ */
+declare function useAbTests(): Record<string, string | null>;
+/**
+ * Returns the assigned variant key for one running experiment, or `null`
+ * while loading / when the experiment is inactive.
+ *
+ * ```tsx
+ * const variant = useAbVariant('checkout-cta-test');
+ * if (variant === 'variant-b') return <BlueCta />;
+ * return <GreenCta />;
+ * ```
+ */
+declare function useAbVariant(experimentKey: string): string | null;
+/**
+ * Returns `true` when the visitor is assigned to the given variant key.
+ *
+ * ```tsx
+ * const isVariantB = useIsAbVariant('checkout-cta-test', 'variant-b');
+ * ```
+ */
+declare function useIsAbVariant(experimentKey: string, variantKey: string): boolean;
 
-export { UserTrackerProvider, type UserTrackerProviderProps, useFeatureFlagEnabled, useFeatureFlags, useHeatmapData, usePageView, usePageViews, useTimeSpent, useTracker };
+export { UserTrackerProvider, type UserTrackerProviderProps, useAbTests, useAbVariant, useFeatureFlagEnabled, useFeatureFlags, useHeatmapData, useIsAbVariant, usePageView, usePageViews, useTimeSpent, useTrackGoal, useTrackJourneyStep, useTrackRevenue, useTracker };

package/dist/react/index.d.ts

@@ -49,19 +49,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;
@@ -72,12 +87,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;
@@ -124,6 +159,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;
@@ -139,6 +265,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;
@@ -150,6 +294,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;
 }
@@ -221,12 +372,14 @@ declare class LogCapture {
 
 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;
@@ -238,7 +391,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
@@ -283,6 +440,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
@@ -315,6 +482,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. */
@@ -380,6 +575,9 @@ declare function useHeatmapData(path?: string, refreshMs?: number): HeatmapPoint
  * Returns a live array of all page views recorded in the current session.
  */
 declare function usePageViews(): PageView[];
+declare function useTrackRevenue(): (payload: RevenueEventPayload) => void;
+declare function useTrackGoal(): (payload: GoalEventPayload) => void;
+declare function useTrackJourneyStep(): (payload: JourneyStepEventPayload) => void;
 /**
  * Returns a live record of cumulative milliseconds spent per path.
  */
@@ -398,5 +596,29 @@ declare function useFeatureFlags(): Record<string, boolean>;
  * ```
  */
 declare function useFeatureFlagEnabled(flagKey: string): boolean;
+/**
+ * Returns all assigned A/B variants as `{ [experimentKey]: variantKey | null }`.
+ * Re-renders when assignments are fetched (on `init()` or `fetchAbTests()`).
+ */
+declare function useAbTests(): Record<string, string | null>;
+/**
+ * Returns the assigned variant key for one running experiment, or `null`
+ * while loading / when the experiment is inactive.
+ *
+ * ```tsx
+ * const variant = useAbVariant('checkout-cta-test');
+ * if (variant === 'variant-b') return <BlueCta />;
+ * return <GreenCta />;
+ * ```
+ */
+declare function useAbVariant(experimentKey: string): string | null;
+/**
+ * Returns `true` when the visitor is assigned to the given variant key.
+ *
+ * ```tsx
+ * const isVariantB = useIsAbVariant('checkout-cta-test', 'variant-b');
+ * ```
+ */
+declare function useIsAbVariant(experimentKey: string, variantKey: string): boolean;
 
-export { UserTrackerProvider, type UserTrackerProviderProps, useFeatureFlagEnabled, useFeatureFlags, useHeatmapData, usePageView, usePageViews, useTimeSpent, useTracker };
+export { UserTrackerProvider, type UserTrackerProviderProps, useAbTests, useAbVariant, useFeatureFlagEnabled, useFeatureFlags, useHeatmapData, useIsAbVariant, usePageView, usePageViews, useTimeSpent, useTrackGoal, useTrackJourneyStep, useTrackRevenue, useTracker };