@blinkdotnew/sdk 0.8.0 → 0.10.0

package/README.md

@@ -580,16 +580,23 @@ blink.analytics.log('button_clicked', {
 })
 
 // All events automatically include:
-// - timestamp, project_id, user_id, session_id
+// - timestamp, project_id, user_id, user_email, session_id
 // - pathname (current page), referrer, screen_width
 // - device/browser/OS info (parsed server-side)
+// - channel detection (Organic Search, Social, Direct, etc.)
+// - UTM parameters (source, medium, campaign, content, term)
+// - UTM persistence for attribution tracking across sessions
 
 // Control analytics
 blink.analytics.disable()
 blink.analytics.enable()
 const isEnabled = blink.analytics.isEnabled()
 
+// Clear attribution data (e.g., when user logs out)
+blink.analytics.clearAttribution()
+
 // Features: Privacy-first, offline support, event batching, session management
+// Attribution: UTM params persist across sessions for conversion tracking
 ```
 
 ### Realtime Operations

package/dist/index.d.mts

@@ -257,10 +257,17 @@ interface AnalyticsEvent {
     type: string;
     timestamp?: string;
     user_id?: string | null;
+    user_email?: string | null;
     session_id?: string | null;
     pathname?: string | null;
     referrer?: string | null;
     screen_width?: number | null;
+    channel?: string | null;
+    utm_source?: string | null;
+    utm_medium?: string | null;
+    utm_campaign?: string | null;
+    utm_content?: string | null;
+    utm_term?: string | null;
     [key: string]: any;
 }
 interface BlinkAnalytics {
@@ -269,6 +276,8 @@ interface BlinkAnalytics {
     enable(): void;
     isEnabled(): boolean;
     setUserId(userId: string | null): void;
+    setUserEmail(email: string | null): void;
+    clearAttribution(): void;
 }
 declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private httpClient;
@@ -277,7 +286,10 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private timer;
     private enabled;
     private userId;
+    private userEmail;
     private hasTrackedPageview;
+    private utmParams;
+    private persistedAttribution;
     constructor(httpClient: HttpClient, projectId: string);
     /**
      * Log a custom analytics event
@@ -299,6 +311,14 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
      * Set the user ID for analytics events
      */
     setUserId(userId: string | null): void;
+    /**
+     * Set the user email for analytics events
+     */
+    setUserEmail(email: string | null): void;
+    /**
+     * Clear persisted attribution data
+     */
+    clearAttribution(): void;
     private buildEvent;
     private sanitizeData;
     private enqueue;
@@ -311,6 +331,10 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private trackPageview;
     private setupRouteChangeListener;
     private setupUnloadListener;
+    private captureUTMParams;
+    private loadPersistedAttribution;
+    private persistAttribution;
+    private detectChannel;
 }
 
 /**

package/dist/index.d.ts

@@ -257,10 +257,17 @@ interface AnalyticsEvent {
     type: string;
     timestamp?: string;
     user_id?: string | null;
+    user_email?: string | null;
     session_id?: string | null;
     pathname?: string | null;
     referrer?: string | null;
     screen_width?: number | null;
+    channel?: string | null;
+    utm_source?: string | null;
+    utm_medium?: string | null;
+    utm_campaign?: string | null;
+    utm_content?: string | null;
+    utm_term?: string | null;
     [key: string]: any;
 }
 interface BlinkAnalytics {
@@ -269,6 +276,8 @@ interface BlinkAnalytics {
     enable(): void;
     isEnabled(): boolean;
     setUserId(userId: string | null): void;
+    setUserEmail(email: string | null): void;
+    clearAttribution(): void;
 }
 declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private httpClient;
@@ -277,7 +286,10 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private timer;
     private enabled;
     private userId;
+    private userEmail;
     private hasTrackedPageview;
+    private utmParams;
+    private persistedAttribution;
     constructor(httpClient: HttpClient, projectId: string);
     /**
      * Log a custom analytics event
@@ -299,6 +311,14 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
      * Set the user ID for analytics events
      */
     setUserId(userId: string | null): void;
+    /**
+     * Set the user email for analytics events
+     */
+    setUserEmail(email: string | null): void;
+    /**
+     * Clear persisted attribution data
+     */
+    clearAttribution(): void;
     private buildEvent;
     private sanitizeData;
     private enqueue;
@@ -311,6 +331,10 @@ declare class BlinkAnalyticsImpl implements BlinkAnalytics {
     private trackPageview;
     private setupRouteChangeListener;
     private setupUnloadListener;
+    private captureUTMParams;
+    private loadPersistedAttribution;
+    private persistAttribution;
+    private detectChannel;
 }
 
 /**

package/dist/index.js

@@ -2887,6 +2887,7 @@ var BATCH_TIMEOUT = 3e3;
 var MAX_STRING_LENGTH = 256;
 var STORAGE_KEY_QUEUE = "blinkAnalyticsQueue";
 var STORAGE_KEY_SESSION = "blinkAnalyticsSession";
+var STORAGE_KEY_ATTRIBUTION = "blinkAnalyticsAttribution";
 var BlinkAnalyticsImpl = class {
   httpClient;
   projectId;
@@ -2894,7 +2895,10 @@ var BlinkAnalyticsImpl = class {
   timer = null;
   enabled = true;
   userId = null;
+  userEmail = null;
   hasTrackedPageview = false;
+  utmParams = {};
+  persistedAttribution = {};
   constructor(httpClient, projectId) {
     this.httpClient = httpClient;
     this.projectId = projectId;
@@ -2905,6 +2909,8 @@ var BlinkAnalyticsImpl = class {
       this.enabled = false;
       return;
     }
+    this.loadPersistedAttribution();
+    this.captureUTMParams();
     this.loadQueue();
     this.trackPageview();
     this.setupRouteChangeListener();
@@ -2945,18 +2951,42 @@ var BlinkAnalyticsImpl = class {
   setUserId(userId) {
     this.userId = userId;
   }
+  /**
+   * Set the user email for analytics events
+   */
+  setUserEmail(email) {
+    this.userEmail = email;
+  }
+  /**
+   * Clear persisted attribution data
+   */
+  clearAttribution() {
+    this.persistedAttribution = {};
+    try {
+      localStorage.removeItem(STORAGE_KEY_ATTRIBUTION);
+    } catch {
+    }
+  }
   // Private methods
   buildEvent(type, data = {}) {
     const sessionId = this.getOrCreateSessionId();
+    const channel = this.detectChannel();
     return {
       type,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       project_id: this.projectId,
       user_id: this.userId,
+      user_email: this.userEmail,
       session_id: sessionId,
       pathname: window.location.pathname,
       referrer: document.referrer || null,
       screen_width: window.innerWidth,
+      channel,
+      utm_source: this.utmParams.utm_source || this.persistedAttribution.utm_source || null,
+      utm_medium: this.utmParams.utm_medium || this.persistedAttribution.utm_medium || null,
+      utm_campaign: this.utmParams.utm_campaign || this.persistedAttribution.utm_campaign || null,
+      utm_content: this.utmParams.utm_content || this.persistedAttribution.utm_content || null,
+      utm_term: this.utmParams.utm_term || this.persistedAttribution.utm_term || null,
       ...this.sanitizeData(data)
     };
   }
@@ -3091,6 +3121,73 @@ var BlinkAnalyticsImpl = class {
       this.flush();
     });
   }
+  captureUTMParams() {
+    const urlParams = new URLSearchParams(window.location.search);
+    this.utmParams = {
+      utm_source: urlParams.get("utm_source"),
+      utm_medium: urlParams.get("utm_medium"),
+      utm_campaign: urlParams.get("utm_campaign"),
+      utm_content: urlParams.get("utm_content"),
+      utm_term: urlParams.get("utm_term")
+    };
+    const hasNewParams = Object.values(this.utmParams).some((v) => v !== null);
+    if (hasNewParams) {
+      this.persistAttribution();
+    }
+  }
+  loadPersistedAttribution() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_ATTRIBUTION);
+      if (stored) {
+        this.persistedAttribution = JSON.parse(stored);
+      }
+    } catch {
+      this.persistedAttribution = {};
+    }
+  }
+  persistAttribution() {
+    try {
+      const attribution = {
+        ...this.persistedAttribution,
+        ...Object.fromEntries(
+          Object.entries(this.utmParams).filter(([_, v]) => v !== null)
+        )
+      };
+      localStorage.setItem(STORAGE_KEY_ATTRIBUTION, JSON.stringify(attribution));
+      this.persistedAttribution = attribution;
+    } catch {
+    }
+  }
+  detectChannel() {
+    const referrer = document.referrer;
+    const utmMedium = this.utmParams.utm_medium;
+    this.utmParams.utm_source;
+    if (utmMedium) {
+      if (utmMedium === "cpc" || utmMedium === "ppc") return "Paid Search";
+      if (utmMedium === "email") return "Email";
+      if (utmMedium === "social") return "Social";
+      if (utmMedium === "referral") return "Referral";
+      if (utmMedium === "display") return "Display";
+      if (utmMedium === "affiliate") return "Affiliate";
+    }
+    if (!referrer) return "Direct";
+    try {
+      const referrerUrl = new URL(referrer);
+      const referrerDomain = referrerUrl.hostname.toLowerCase();
+      if (/google\.|bing\.|yahoo\.|duckduckgo\.|baidu\.|yandex\./.test(referrerDomain)) {
+        return "Organic Search";
+      }
+      if (/facebook\.|twitter\.|linkedin\.|instagram\.|youtube\.|tiktok\.|reddit\./.test(referrerDomain)) {
+        return "Social";
+      }
+      if (/mail\.|outlook\.|gmail\./.test(referrerDomain)) {
+        return "Email";
+      }
+      return "Referral";
+    } catch {
+      return "Direct";
+    }
+  }
 };
 
 // src/client.ts
@@ -3121,8 +3218,10 @@ var BlinkClientImpl = class {
     this.auth.onAuthStateChanged((state) => {
       if (state.isAuthenticated && state.user) {
         this.analytics.setUserId(state.user.id);
+        this.analytics.setUserEmail(state.user.email);
       } else {
         this.analytics.setUserId(null);
+        this.analytics.setUserEmail(null);
       }
     });
   }

package/dist/index.mjs

@@ -2885,6 +2885,7 @@ var BATCH_TIMEOUT = 3e3;
 var MAX_STRING_LENGTH = 256;
 var STORAGE_KEY_QUEUE = "blinkAnalyticsQueue";
 var STORAGE_KEY_SESSION = "blinkAnalyticsSession";
+var STORAGE_KEY_ATTRIBUTION = "blinkAnalyticsAttribution";
 var BlinkAnalyticsImpl = class {
   httpClient;
   projectId;
@@ -2892,7 +2893,10 @@ var BlinkAnalyticsImpl = class {
   timer = null;
   enabled = true;
   userId = null;
+  userEmail = null;
   hasTrackedPageview = false;
+  utmParams = {};
+  persistedAttribution = {};
   constructor(httpClient, projectId) {
     this.httpClient = httpClient;
     this.projectId = projectId;
@@ -2903,6 +2907,8 @@ var BlinkAnalyticsImpl = class {
       this.enabled = false;
       return;
     }
+    this.loadPersistedAttribution();
+    this.captureUTMParams();
     this.loadQueue();
     this.trackPageview();
     this.setupRouteChangeListener();
@@ -2943,18 +2949,42 @@ var BlinkAnalyticsImpl = class {
   setUserId(userId) {
     this.userId = userId;
   }
+  /**
+   * Set the user email for analytics events
+   */
+  setUserEmail(email) {
+    this.userEmail = email;
+  }
+  /**
+   * Clear persisted attribution data
+   */
+  clearAttribution() {
+    this.persistedAttribution = {};
+    try {
+      localStorage.removeItem(STORAGE_KEY_ATTRIBUTION);
+    } catch {
+    }
+  }
   // Private methods
   buildEvent(type, data = {}) {
     const sessionId = this.getOrCreateSessionId();
+    const channel = this.detectChannel();
     return {
       type,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       project_id: this.projectId,
       user_id: this.userId,
+      user_email: this.userEmail,
       session_id: sessionId,
       pathname: window.location.pathname,
       referrer: document.referrer || null,
       screen_width: window.innerWidth,
+      channel,
+      utm_source: this.utmParams.utm_source || this.persistedAttribution.utm_source || null,
+      utm_medium: this.utmParams.utm_medium || this.persistedAttribution.utm_medium || null,
+      utm_campaign: this.utmParams.utm_campaign || this.persistedAttribution.utm_campaign || null,
+      utm_content: this.utmParams.utm_content || this.persistedAttribution.utm_content || null,
+      utm_term: this.utmParams.utm_term || this.persistedAttribution.utm_term || null,
       ...this.sanitizeData(data)
     };
   }
@@ -3089,6 +3119,73 @@ var BlinkAnalyticsImpl = class {
       this.flush();
     });
   }
+  captureUTMParams() {
+    const urlParams = new URLSearchParams(window.location.search);
+    this.utmParams = {
+      utm_source: urlParams.get("utm_source"),
+      utm_medium: urlParams.get("utm_medium"),
+      utm_campaign: urlParams.get("utm_campaign"),
+      utm_content: urlParams.get("utm_content"),
+      utm_term: urlParams.get("utm_term")
+    };
+    const hasNewParams = Object.values(this.utmParams).some((v) => v !== null);
+    if (hasNewParams) {
+      this.persistAttribution();
+    }
+  }
+  loadPersistedAttribution() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_ATTRIBUTION);
+      if (stored) {
+        this.persistedAttribution = JSON.parse(stored);
+      }
+    } catch {
+      this.persistedAttribution = {};
+    }
+  }
+  persistAttribution() {
+    try {
+      const attribution = {
+        ...this.persistedAttribution,
+        ...Object.fromEntries(
+          Object.entries(this.utmParams).filter(([_, v]) => v !== null)
+        )
+      };
+      localStorage.setItem(STORAGE_KEY_ATTRIBUTION, JSON.stringify(attribution));
+      this.persistedAttribution = attribution;
+    } catch {
+    }
+  }
+  detectChannel() {
+    const referrer = document.referrer;
+    const utmMedium = this.utmParams.utm_medium;
+    this.utmParams.utm_source;
+    if (utmMedium) {
+      if (utmMedium === "cpc" || utmMedium === "ppc") return "Paid Search";
+      if (utmMedium === "email") return "Email";
+      if (utmMedium === "social") return "Social";
+      if (utmMedium === "referral") return "Referral";
+      if (utmMedium === "display") return "Display";
+      if (utmMedium === "affiliate") return "Affiliate";
+    }
+    if (!referrer) return "Direct";
+    try {
+      const referrerUrl = new URL(referrer);
+      const referrerDomain = referrerUrl.hostname.toLowerCase();
+      if (/google\.|bing\.|yahoo\.|duckduckgo\.|baidu\.|yandex\./.test(referrerDomain)) {
+        return "Organic Search";
+      }
+      if (/facebook\.|twitter\.|linkedin\.|instagram\.|youtube\.|tiktok\.|reddit\./.test(referrerDomain)) {
+        return "Social";
+      }
+      if (/mail\.|outlook\.|gmail\./.test(referrerDomain)) {
+        return "Email";
+      }
+      return "Referral";
+    } catch {
+      return "Direct";
+    }
+  }
 };
 
 // src/client.ts
@@ -3119,8 +3216,10 @@ var BlinkClientImpl = class {
     this.auth.onAuthStateChanged((state) => {
       if (state.isAuthenticated && state.user) {
         this.analytics.setUserId(state.user.id);
+        this.analytics.setUserEmail(state.user.email);
       } else {
         this.analytics.setUserId(null);
+        this.analytics.setUserEmail(null);
       }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",