@blinkdotnew/sdk 0.7.1 → 0.8.0

package/README.md

@@ -81,6 +81,22 @@ await blink.realtime.publish('chat-room', 'message', { text: 'Hello world!' })
 const users = await blink.realtime.presence('chat-room')
 console.log('Online users:', users.length)
 
+// Analytics operations (automatic pageview tracking + custom events)
+// Pageviews are tracked automatically on initialization and route changes
+blink.analytics.log('button_clicked', {
+  button_id: 'signup',
+  page: '/pricing'
+})
+
+// Check if analytics is enabled
+if (blink.analytics.isEnabled()) {
+  console.log('Analytics is active')
+}
+
+// Disable/enable analytics
+blink.analytics.disable()
+blink.analytics.enable()
+
 // Storage operations (instant - returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
@@ -109,6 +125,7 @@ This SDK powers every Blink-generated app with:
 - **📁 Storage**: File upload, download, and management
 - **📧 Notifications**: Email sending with attachments, custom branding, and delivery tracking
 - **⚡ Realtime**: WebSocket-based pub/sub messaging, presence tracking, and live updates
+- **📊 Analytics**: Automatic pageview tracking, custom event logging, session management, and privacy-first design
 - **🌐 Universal**: Works on client-side and server-side
 - **📱 Framework Agnostic**: React, Vue, Svelte, vanilla JS, Node.js, Deno
 - **🔄 Real-time**: Built-in auth state management and token refresh
@@ -550,6 +567,31 @@ try {
 }
 ```
 
+### Analytics Operations
+
+```typescript
+// 🔥 Analytics (NEW!) - Automatic pageview tracking + custom events
+// Pageviews are tracked automatically on initialization and route changes
+
+// Log custom events - context data is added automatically
+blink.analytics.log('button_clicked', {
+  button_id: 'signup',
+  campaign: 'summer_sale'
+})
+
+// All events automatically include:
+// - timestamp, project_id, user_id, session_id
+// - pathname (current page), referrer, screen_width
+// - device/browser/OS info (parsed server-side)
+
+// Control analytics
+blink.analytics.disable()
+blink.analytics.enable()
+const isEnabled = blink.analytics.isEnabled()
+
+// Features: Privacy-first, offline support, event batching, session management
+```
+
 ### Realtime Operations
 
 ```typescript

package/dist/index.d.mts

@@ -248,6 +248,71 @@ declare class BlinkDataImpl implements BlinkData {
     }): Promise<SearchResponse>;
 }
 
+/**
+ * Blink Analytics Module
+ * Provides automatic pageview tracking and custom event logging
+ */
+
+interface AnalyticsEvent {
+    type: string;
+    timestamp?: string;
+    user_id?: string | null;
+    session_id?: string | null;
+    pathname?: string | null;
+    referrer?: string | null;
+    screen_width?: number | null;
+    [key: string]: any;
+}
+interface BlinkAnalytics {
+    log(eventName: string, data?: Record<string, any>): void;
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+    setUserId(userId: string | null): void;
+}
+declare class BlinkAnalyticsImpl implements BlinkAnalytics {
+    private httpClient;
+    private projectId;
+    private queue;
+    private timer;
+    private enabled;
+    private userId;
+    private hasTrackedPageview;
+    constructor(httpClient: HttpClient, projectId: string);
+    /**
+     * Log a custom analytics event
+     */
+    log(eventName: string, data?: Record<string, any>): void;
+    /**
+     * Disable analytics tracking
+     */
+    disable(): void;
+    /**
+     * Enable analytics tracking
+     */
+    enable(): void;
+    /**
+     * Check if analytics is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set the user ID for analytics events
+     */
+    setUserId(userId: string | null): void;
+    private buildEvent;
+    private sanitizeData;
+    private enqueue;
+    private flush;
+    private clearTimer;
+    private getOrCreateSessionId;
+    private createNewSession;
+    private loadQueue;
+    private persistQueue;
+    private trackPageview;
+    private setupRouteChangeListener;
+    private setupUnloadListener;
+}
+
 /**
  * Blink Client - Main SDK entry point
  * Factory function and client class for the Blink SDK
@@ -261,6 +326,7 @@ interface BlinkClient {
     data: BlinkData;
     realtime: BlinkRealtime;
     notifications: BlinkNotifications;
+    analytics: BlinkAnalytics;
 }
 /**
  * Create a new Blink client instance
@@ -720,4 +786,4 @@ declare class BlinkRealtimeImpl implements BlinkRealtime {
     onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };
+export { type AnalyticsEvent, type AuthStateChangeCallback, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };

package/dist/index.d.ts

@@ -248,6 +248,71 @@ declare class BlinkDataImpl implements BlinkData {
     }): Promise<SearchResponse>;
 }
 
+/**
+ * Blink Analytics Module
+ * Provides automatic pageview tracking and custom event logging
+ */
+
+interface AnalyticsEvent {
+    type: string;
+    timestamp?: string;
+    user_id?: string | null;
+    session_id?: string | null;
+    pathname?: string | null;
+    referrer?: string | null;
+    screen_width?: number | null;
+    [key: string]: any;
+}
+interface BlinkAnalytics {
+    log(eventName: string, data?: Record<string, any>): void;
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+    setUserId(userId: string | null): void;
+}
+declare class BlinkAnalyticsImpl implements BlinkAnalytics {
+    private httpClient;
+    private projectId;
+    private queue;
+    private timer;
+    private enabled;
+    private userId;
+    private hasTrackedPageview;
+    constructor(httpClient: HttpClient, projectId: string);
+    /**
+     * Log a custom analytics event
+     */
+    log(eventName: string, data?: Record<string, any>): void;
+    /**
+     * Disable analytics tracking
+     */
+    disable(): void;
+    /**
+     * Enable analytics tracking
+     */
+    enable(): void;
+    /**
+     * Check if analytics is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set the user ID for analytics events
+     */
+    setUserId(userId: string | null): void;
+    private buildEvent;
+    private sanitizeData;
+    private enqueue;
+    private flush;
+    private clearTimer;
+    private getOrCreateSessionId;
+    private createNewSession;
+    private loadQueue;
+    private persistQueue;
+    private trackPageview;
+    private setupRouteChangeListener;
+    private setupUnloadListener;
+}
+
 /**
  * Blink Client - Main SDK entry point
  * Factory function and client class for the Blink SDK
@@ -261,6 +326,7 @@ interface BlinkClient {
     data: BlinkData;
     realtime: BlinkRealtime;
     notifications: BlinkNotifications;
+    analytics: BlinkAnalytics;
 }
 /**
  * Create a new Blink client instance
@@ -720,4 +786,4 @@ declare class BlinkRealtimeImpl implements BlinkRealtime {
     onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
 }
 
-export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };
+export { type AnalyticsEvent, type AuthStateChangeCallback, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkData, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };

package/dist/index.js

@@ -2880,6 +2880,219 @@ var BlinkNotificationsImpl = class {
   }
 };
 
+// src/analytics.ts
+var SESSION_DURATION = 30 * 60 * 1e3;
+var MAX_BATCH_SIZE = 10;
+var BATCH_TIMEOUT = 3e3;
+var MAX_STRING_LENGTH = 256;
+var STORAGE_KEY_QUEUE = "blinkAnalyticsQueue";
+var STORAGE_KEY_SESSION = "blinkAnalyticsSession";
+var BlinkAnalyticsImpl = class {
+  httpClient;
+  projectId;
+  queue = [];
+  timer = null;
+  enabled = true;
+  userId = null;
+  hasTrackedPageview = false;
+  constructor(httpClient, projectId) {
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+    if (typeof window === "undefined") {
+      return;
+    }
+    if (navigator.doNotTrack === "1") {
+      this.enabled = false;
+      return;
+    }
+    this.loadQueue();
+    this.trackPageview();
+    this.setupRouteChangeListener();
+    this.setupUnloadListener();
+  }
+  /**
+   * Log a custom analytics event
+   */
+  log(eventName, data = {}) {
+    if (!this.enabled || typeof window === "undefined") {
+      return;
+    }
+    const event = this.buildEvent(eventName, data);
+    this.enqueue(event);
+  }
+  /**
+   * Disable analytics tracking
+   */
+  disable() {
+    this.enabled = false;
+    this.clearTimer();
+  }
+  /**
+   * Enable analytics tracking
+   */
+  enable() {
+    this.enabled = true;
+  }
+  /**
+   * Check if analytics is enabled
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Set the user ID for analytics events
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  // Private methods
+  buildEvent(type, data = {}) {
+    const sessionId = this.getOrCreateSessionId();
+    return {
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      project_id: this.projectId,
+      user_id: this.userId,
+      session_id: sessionId,
+      pathname: window.location.pathname,
+      referrer: document.referrer || null,
+      screen_width: window.innerWidth,
+      ...this.sanitizeData(data)
+    };
+  }
+  sanitizeData(data) {
+    if (typeof data === "string") {
+      return data.length > MAX_STRING_LENGTH ? data.slice(0, MAX_STRING_LENGTH - 3) + "..." : data;
+    }
+    if (typeof data === "object" && data !== null) {
+      const result = {};
+      for (const key in data) {
+        result[key] = this.sanitizeData(data[key]);
+      }
+      return result;
+    }
+    return data;
+  }
+  enqueue(event) {
+    this.queue.push(event);
+    this.persistQueue();
+    if (this.queue.length >= MAX_BATCH_SIZE) {
+      this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+    }
+  }
+  async flush() {
+    this.clearTimer();
+    if (this.queue.length === 0) {
+      return;
+    }
+    const events = this.queue.slice(0, MAX_BATCH_SIZE);
+    this.queue = this.queue.slice(MAX_BATCH_SIZE);
+    this.persistQueue();
+    try {
+      await this.httpClient.post(`/api/analytics/${this.projectId}/log`, { events });
+    } catch (error) {
+      this.queue = [...events, ...this.queue];
+      this.persistQueue();
+      console.error("Failed to send analytics events:", error);
+    }
+    if (this.queue.length > 0) {
+      this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+    }
+  }
+  clearTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  getOrCreateSessionId() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_SESSION);
+      if (stored) {
+        const session = JSON.parse(stored);
+        const now = Date.now();
+        if (now - session.lastActivityAt > SESSION_DURATION) {
+          return this.createNewSession();
+        }
+        session.lastActivityAt = now;
+        localStorage.setItem(STORAGE_KEY_SESSION, JSON.stringify(session));
+        return session.id;
+      }
+      return this.createNewSession();
+    } catch {
+      return null;
+    }
+  }
+  createNewSession() {
+    const now = Date.now();
+    const randomId = Math.random().toString(36).substring(2, 10);
+    const session = {
+      id: `sess_${now}_${randomId}`,
+      startedAt: now,
+      lastActivityAt: now
+    };
+    try {
+      localStorage.setItem(STORAGE_KEY_SESSION, JSON.stringify(session));
+    } catch {
+    }
+    return session.id;
+  }
+  loadQueue() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_QUEUE);
+      if (stored) {
+        this.queue = JSON.parse(stored);
+        if (this.queue.length > 0) {
+          this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+        }
+      }
+    } catch {
+      this.queue = [];
+    }
+  }
+  persistQueue() {
+    try {
+      if (this.queue.length === 0) {
+        localStorage.removeItem(STORAGE_KEY_QUEUE);
+      } else {
+        localStorage.setItem(STORAGE_KEY_QUEUE, JSON.stringify(this.queue));
+      }
+    } catch {
+    }
+  }
+  trackPageview() {
+    if (!this.hasTrackedPageview) {
+      this.log("pageview");
+      this.hasTrackedPageview = true;
+    }
+  }
+  setupRouteChangeListener() {
+    const originalPushState = history.pushState;
+    const originalReplaceState = history.replaceState;
+    history.pushState = (...args) => {
+      originalPushState.apply(history, args);
+      this.log("pageview");
+    };
+    history.replaceState = (...args) => {
+      originalReplaceState.apply(history, args);
+      this.log("pageview");
+    };
+    window.addEventListener("popstate", () => {
+      this.log("pageview");
+    });
+  }
+  setupUnloadListener() {
+    window.addEventListener("pagehide", () => {
+      this.flush();
+    });
+    window.addEventListener("unload", () => {
+      this.flush();
+    });
+  }
+};
+
 // src/client.ts
 var BlinkClientImpl = class {
   auth;
@@ -2889,6 +3102,7 @@ var BlinkClientImpl = class {
   data;
   realtime;
   notifications;
+  analytics;
   httpClient;
   constructor(config) {
     this.auth = new BlinkAuth(config);
@@ -2903,6 +3117,14 @@ var BlinkClientImpl = class {
     this.data = new BlinkDataImpl(this.httpClient, config.projectId);
     this.realtime = new BlinkRealtimeImpl(this.httpClient, config.projectId);
     this.notifications = new BlinkNotificationsImpl(this.httpClient);
+    this.analytics = new BlinkAnalyticsImpl(this.httpClient, config.projectId);
+    this.auth.onAuthStateChanged((state) => {
+      if (state.isAuthenticated && state.user) {
+        this.analytics.setUserId(state.user.id);
+      } else {
+        this.analytics.setUserId(null);
+      }
+    });
   }
 };
 function createClient(config) {
@@ -2917,6 +3139,7 @@ function createClient(config) {
 }
 
 exports.BlinkAIImpl = BlinkAIImpl;
+exports.BlinkAnalyticsImpl = BlinkAnalyticsImpl;
 exports.BlinkDataImpl = BlinkDataImpl;
 exports.BlinkDatabase = BlinkDatabase;
 exports.BlinkRealtimeChannel = BlinkRealtimeChannel;

package/dist/index.mjs

@@ -2878,6 +2878,219 @@ var BlinkNotificationsImpl = class {
   }
 };
 
+// src/analytics.ts
+var SESSION_DURATION = 30 * 60 * 1e3;
+var MAX_BATCH_SIZE = 10;
+var BATCH_TIMEOUT = 3e3;
+var MAX_STRING_LENGTH = 256;
+var STORAGE_KEY_QUEUE = "blinkAnalyticsQueue";
+var STORAGE_KEY_SESSION = "blinkAnalyticsSession";
+var BlinkAnalyticsImpl = class {
+  httpClient;
+  projectId;
+  queue = [];
+  timer = null;
+  enabled = true;
+  userId = null;
+  hasTrackedPageview = false;
+  constructor(httpClient, projectId) {
+    this.httpClient = httpClient;
+    this.projectId = projectId;
+    if (typeof window === "undefined") {
+      return;
+    }
+    if (navigator.doNotTrack === "1") {
+      this.enabled = false;
+      return;
+    }
+    this.loadQueue();
+    this.trackPageview();
+    this.setupRouteChangeListener();
+    this.setupUnloadListener();
+  }
+  /**
+   * Log a custom analytics event
+   */
+  log(eventName, data = {}) {
+    if (!this.enabled || typeof window === "undefined") {
+      return;
+    }
+    const event = this.buildEvent(eventName, data);
+    this.enqueue(event);
+  }
+  /**
+   * Disable analytics tracking
+   */
+  disable() {
+    this.enabled = false;
+    this.clearTimer();
+  }
+  /**
+   * Enable analytics tracking
+   */
+  enable() {
+    this.enabled = true;
+  }
+  /**
+   * Check if analytics is enabled
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Set the user ID for analytics events
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  // Private methods
+  buildEvent(type, data = {}) {
+    const sessionId = this.getOrCreateSessionId();
+    return {
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      project_id: this.projectId,
+      user_id: this.userId,
+      session_id: sessionId,
+      pathname: window.location.pathname,
+      referrer: document.referrer || null,
+      screen_width: window.innerWidth,
+      ...this.sanitizeData(data)
+    };
+  }
+  sanitizeData(data) {
+    if (typeof data === "string") {
+      return data.length > MAX_STRING_LENGTH ? data.slice(0, MAX_STRING_LENGTH - 3) + "..." : data;
+    }
+    if (typeof data === "object" && data !== null) {
+      const result = {};
+      for (const key in data) {
+        result[key] = this.sanitizeData(data[key]);
+      }
+      return result;
+    }
+    return data;
+  }
+  enqueue(event) {
+    this.queue.push(event);
+    this.persistQueue();
+    if (this.queue.length >= MAX_BATCH_SIZE) {
+      this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+    }
+  }
+  async flush() {
+    this.clearTimer();
+    if (this.queue.length === 0) {
+      return;
+    }
+    const events = this.queue.slice(0, MAX_BATCH_SIZE);
+    this.queue = this.queue.slice(MAX_BATCH_SIZE);
+    this.persistQueue();
+    try {
+      await this.httpClient.post(`/api/analytics/${this.projectId}/log`, { events });
+    } catch (error) {
+      this.queue = [...events, ...this.queue];
+      this.persistQueue();
+      console.error("Failed to send analytics events:", error);
+    }
+    if (this.queue.length > 0) {
+      this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+    }
+  }
+  clearTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  getOrCreateSessionId() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_SESSION);
+      if (stored) {
+        const session = JSON.parse(stored);
+        const now = Date.now();
+        if (now - session.lastActivityAt > SESSION_DURATION) {
+          return this.createNewSession();
+        }
+        session.lastActivityAt = now;
+        localStorage.setItem(STORAGE_KEY_SESSION, JSON.stringify(session));
+        return session.id;
+      }
+      return this.createNewSession();
+    } catch {
+      return null;
+    }
+  }
+  createNewSession() {
+    const now = Date.now();
+    const randomId = Math.random().toString(36).substring(2, 10);
+    const session = {
+      id: `sess_${now}_${randomId}`,
+      startedAt: now,
+      lastActivityAt: now
+    };
+    try {
+      localStorage.setItem(STORAGE_KEY_SESSION, JSON.stringify(session));
+    } catch {
+    }
+    return session.id;
+  }
+  loadQueue() {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY_QUEUE);
+      if (stored) {
+        this.queue = JSON.parse(stored);
+        if (this.queue.length > 0) {
+          this.timer = setTimeout(() => this.flush(), BATCH_TIMEOUT);
+        }
+      }
+    } catch {
+      this.queue = [];
+    }
+  }
+  persistQueue() {
+    try {
+      if (this.queue.length === 0) {
+        localStorage.removeItem(STORAGE_KEY_QUEUE);
+      } else {
+        localStorage.setItem(STORAGE_KEY_QUEUE, JSON.stringify(this.queue));
+      }
+    } catch {
+    }
+  }
+  trackPageview() {
+    if (!this.hasTrackedPageview) {
+      this.log("pageview");
+      this.hasTrackedPageview = true;
+    }
+  }
+  setupRouteChangeListener() {
+    const originalPushState = history.pushState;
+    const originalReplaceState = history.replaceState;
+    history.pushState = (...args) => {
+      originalPushState.apply(history, args);
+      this.log("pageview");
+    };
+    history.replaceState = (...args) => {
+      originalReplaceState.apply(history, args);
+      this.log("pageview");
+    };
+    window.addEventListener("popstate", () => {
+      this.log("pageview");
+    });
+  }
+  setupUnloadListener() {
+    window.addEventListener("pagehide", () => {
+      this.flush();
+    });
+    window.addEventListener("unload", () => {
+      this.flush();
+    });
+  }
+};
+
 // src/client.ts
 var BlinkClientImpl = class {
   auth;
@@ -2887,6 +3100,7 @@ var BlinkClientImpl = class {
   data;
   realtime;
   notifications;
+  analytics;
   httpClient;
   constructor(config) {
     this.auth = new BlinkAuth(config);
@@ -2901,6 +3115,14 @@ var BlinkClientImpl = class {
     this.data = new BlinkDataImpl(this.httpClient, config.projectId);
     this.realtime = new BlinkRealtimeImpl(this.httpClient, config.projectId);
     this.notifications = new BlinkNotificationsImpl(this.httpClient);
+    this.analytics = new BlinkAnalyticsImpl(this.httpClient, config.projectId);
+    this.auth.onAuthStateChanged((state) => {
+      if (state.isAuthenticated && state.user) {
+        this.analytics.setUserId(state.user.id);
+      } else {
+        this.analytics.setUserId(null);
+      }
+    });
   }
 };
 function createClient(config) {
@@ -2914,6 +3136,6 @@ function createClient(config) {
   return new BlinkClientImpl(clientConfig);
 }
 
-export { BlinkAIImpl, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };
+export { BlinkAIImpl, BlinkAnalyticsImpl, BlinkDataImpl, BlinkDatabase, BlinkRealtimeChannel, BlinkRealtimeImpl, BlinkStorageImpl, BlinkTable, createClient };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/package.json

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