alphana-sdk 1.1.1 → 1.5.0

package/dist/index.d.mts

@@ -84,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;
@@ -136,6 +156,67 @@ 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
@@ -181,6 +262,18 @@ 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;
@@ -198,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;
 }
@@ -288,6 +388,8 @@ declare class UserTracker {
     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
@@ -332,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
@@ -430,4 +542,4 @@ declare const ALPHANA_SDK_VERSION = "1.0.2";
  */
 declare function normalizeTrackerPath(path: string): string;
 
-export { ALPHANA_SDK_VERSION, type AbVariantsMap, type ClientContext, 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, normalizeTrackerPath };
+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

@@ -84,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;
@@ -136,6 +156,67 @@ 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
@@ -181,6 +262,18 @@ 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;
@@ -198,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;
 }
@@ -288,6 +388,8 @@ declare class UserTracker {
     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
@@ -332,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
@@ -430,4 +542,4 @@ declare const ALPHANA_SDK_VERSION = "1.0.2";
  */
 declare function normalizeTrackerPath(path: string): string;
 
-export { ALPHANA_SDK_VERSION, type AbVariantsMap, type ClientContext, 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, normalizeTrackerPath };
+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 };