krisspy-sdk 0.8.2 → 0.9.1

package/dist/index.d.mts

@@ -760,10 +760,20 @@ declare class KrisspyRealtime {
  * to the analytics ingest endpoint. Works with SPAs (intercepts pushState).
  * Browser-only module - safely no-ops in React Native / Node.js.
  *
+ * Supports two backends:
+ * - Krisspy internal analytics (default, via /api/v1/analytics/events)
+ * - OpenPanel (when openpanelClientId is provided, uses @openpanel/web SDK)
+ *
  * @example
  * const krisspy = createClient({ backendId: '...', apiKey: '...' })
  * krisspy.analytics.init({ autoTrackPageViews: true })
  * krisspy.analytics.track('button_click', { label: 'signup' })
+ *
+ * // With OpenPanel:
+ * krisspy.analytics.init({
+ *   openpanelClientId: '049c50ff-...',
+ *   openpanelApiUrl: 'https://api-openpanel.krisspy.ai',
+ * })
  */
 
 interface AnalyticsInitOptions {
@@ -775,6 +785,23 @@ interface AnalyticsInitOptions {
     flushInterval?: number;
     /** Enable debug logging (default: false) */
     debug?: boolean;
+    /** OpenPanel client ID (UUID). When set, events are sent to OpenPanel instead of Krisspy. */
+    openpanelClientId?: string;
+    /** OpenPanel API URL for self-hosted instances (default: https://api-openpanel.krisspy.ai) */
+    openpanelApiUrl?: string;
+    /** Track outgoing links (OpenPanel, default: true) */
+    trackOutgoingLinks?: boolean;
+    /** Track elements with data-track attributes (OpenPanel, default: true) */
+    trackAttributes?: boolean;
+    /** Track hash changes in URL (OpenPanel, default: false) */
+    trackHashChanges?: boolean;
+    /** Disable tracking entirely (OpenPanel, default: false) */
+    disabled?: boolean;
+    /** Filter function — return false to drop an event before sending */
+    filter?: (event: {
+        name: string;
+        properties?: Record<string, any>;
+    }) => boolean;
 }
 interface AnalyticsEvent {
     eventName: string;
@@ -796,6 +823,9 @@ declare class KrisspyAnalytics {
     private originalPushState;
     private popstateHandler;
     private unloadHandler;
+    /** OpenPanel SDK instance (loaded dynamically when openpanelClientId is set) */
+    private openpanel;
+    private useOpenPanel;
     constructor(http: HttpClient, backendId: string);
     /**
      * Initialize analytics tracking
@@ -810,6 +840,51 @@ declare class KrisspyAnalytics {
      * Identify a user (attach userId + traits to all future events)
      */
     identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Set properties that will be sent with every event
+     */
+    setGlobalProperties(props: Record<string, any>): void;
+    /**
+     * Increment a numeric property on a user profile
+     */
+    increment(profileId: string, property: string, value?: number): void;
+    /**
+     * Decrement a numeric property on a user profile
+     */
+    decrement(profileId: string, property: string, value?: number): void;
+    /**
+     * Create or update a group entity (company, team, etc.)
+     */
+    upsertGroup(group: {
+        id: string;
+        type: string;
+        name: string;
+        properties?: Record<string, any>;
+    }): void;
+    /**
+     * Link the current user to a group — tags all future events
+     */
+    setGroup(groupId: string): void;
+    /**
+     * Track a revenue event
+     */
+    revenue(amount: number, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Queue a pending revenue event (call flushRevenue() to send)
+     */
+    pendingRevenue(amount: number, properties?: Record<string, any>): void;
+    /**
+     * Flush all pending revenue events
+     */
+    flushRevenue(): Promise<void>;
+    /**
+     * Clear pending revenue
+     */
+    clearRevenue(): void;
+    /**
+     * Clear current user data (including groups)
+     */
+    clear(): void;
     /**
      * Flush event queue to the server (async)
      */
@@ -825,6 +900,12 @@ declare class KrisspyAnalytics {
     private getOrCreateSessionId;
     private getIngestUrl;
     private setupNavigationTracking;
+    /**
+     * Initialize OpenPanel SDK dynamically.
+     * Loads @openpanel/web at runtime (must be installed by the user).
+     * Falls back gracefully if not available.
+     */
+    private initOpenPanel;
 }
 
 /**

package/dist/index.d.ts

@@ -760,10 +760,20 @@ declare class KrisspyRealtime {
  * to the analytics ingest endpoint. Works with SPAs (intercepts pushState).
  * Browser-only module - safely no-ops in React Native / Node.js.
  *
+ * Supports two backends:
+ * - Krisspy internal analytics (default, via /api/v1/analytics/events)
+ * - OpenPanel (when openpanelClientId is provided, uses @openpanel/web SDK)
+ *
  * @example
  * const krisspy = createClient({ backendId: '...', apiKey: '...' })
  * krisspy.analytics.init({ autoTrackPageViews: true })
  * krisspy.analytics.track('button_click', { label: 'signup' })
+ *
+ * // With OpenPanel:
+ * krisspy.analytics.init({
+ *   openpanelClientId: '049c50ff-...',
+ *   openpanelApiUrl: 'https://api-openpanel.krisspy.ai',
+ * })
  */
 
 interface AnalyticsInitOptions {
@@ -775,6 +785,23 @@ interface AnalyticsInitOptions {
     flushInterval?: number;
     /** Enable debug logging (default: false) */
     debug?: boolean;
+    /** OpenPanel client ID (UUID). When set, events are sent to OpenPanel instead of Krisspy. */
+    openpanelClientId?: string;
+    /** OpenPanel API URL for self-hosted instances (default: https://api-openpanel.krisspy.ai) */
+    openpanelApiUrl?: string;
+    /** Track outgoing links (OpenPanel, default: true) */
+    trackOutgoingLinks?: boolean;
+    /** Track elements with data-track attributes (OpenPanel, default: true) */
+    trackAttributes?: boolean;
+    /** Track hash changes in URL (OpenPanel, default: false) */
+    trackHashChanges?: boolean;
+    /** Disable tracking entirely (OpenPanel, default: false) */
+    disabled?: boolean;
+    /** Filter function — return false to drop an event before sending */
+    filter?: (event: {
+        name: string;
+        properties?: Record<string, any>;
+    }) => boolean;
 }
 interface AnalyticsEvent {
     eventName: string;
@@ -796,6 +823,9 @@ declare class KrisspyAnalytics {
     private originalPushState;
     private popstateHandler;
     private unloadHandler;
+    /** OpenPanel SDK instance (loaded dynamically when openpanelClientId is set) */
+    private openpanel;
+    private useOpenPanel;
     constructor(http: HttpClient, backendId: string);
     /**
      * Initialize analytics tracking
@@ -810,6 +840,51 @@ declare class KrisspyAnalytics {
      * Identify a user (attach userId + traits to all future events)
      */
     identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Set properties that will be sent with every event
+     */
+    setGlobalProperties(props: Record<string, any>): void;
+    /**
+     * Increment a numeric property on a user profile
+     */
+    increment(profileId: string, property: string, value?: number): void;
+    /**
+     * Decrement a numeric property on a user profile
+     */
+    decrement(profileId: string, property: string, value?: number): void;
+    /**
+     * Create or update a group entity (company, team, etc.)
+     */
+    upsertGroup(group: {
+        id: string;
+        type: string;
+        name: string;
+        properties?: Record<string, any>;
+    }): void;
+    /**
+     * Link the current user to a group — tags all future events
+     */
+    setGroup(groupId: string): void;
+    /**
+     * Track a revenue event
+     */
+    revenue(amount: number, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Queue a pending revenue event (call flushRevenue() to send)
+     */
+    pendingRevenue(amount: number, properties?: Record<string, any>): void;
+    /**
+     * Flush all pending revenue events
+     */
+    flushRevenue(): Promise<void>;
+    /**
+     * Clear pending revenue
+     */
+    clearRevenue(): void;
+    /**
+     * Clear current user data (including groups)
+     */
+    clear(): void;
     /**
      * Flush event queue to the server (async)
      */
@@ -825,6 +900,12 @@ declare class KrisspyAnalytics {
     private getOrCreateSessionId;
     private getIngestUrl;
     private setupNavigationTracking;
+    /**
+     * Initialize OpenPanel SDK dynamically.
+     * Loads @openpanel/web at runtime (must be installed by the user).
+     * Falls back gracefully if not available.
+     */
+    private initOpenPanel;
 }
 
 /**

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -32,6 +34,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -1307,6 +1317,9 @@ var KrisspyAnalytics = class {
     this.originalPushState = null;
     this.popstateHandler = null;
     this.unloadHandler = null;
+    /** OpenPanel SDK instance (loaded dynamically when openpanelClientId is set) */
+    this.openpanel = null;
+    this.useOpenPanel = false;
     this.http = http;
     this.backendId = backendId;
   }
@@ -1323,6 +1336,12 @@ var KrisspyAnalytics = class {
       flushInterval: 5e3,
       debug: false
     }, options);
+    if (this.options.openpanelClientId) {
+      this.useOpenPanel = true;
+      this.initialized = true;
+      this.initOpenPanel();
+      return;
+    }
     this.sessionId = this.getOrCreateSessionId();
     this.initialized = true;
     if (this.options.autoTrackPageViews) {
@@ -1339,7 +1358,7 @@ var KrisspyAnalytics = class {
     window.addEventListener("beforeunload", this.unloadHandler);
     this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
     if (this.options.debug) {
-      console.log("[Krisspy Analytics] Initialized", { backendId: this.backendId, sessionId: this.sessionId });
+      console.log("[Krisspy Analytics] Initialized (internal)", { backendId: this.backendId, sessionId: this.sessionId });
     }
   }
   /**
@@ -1347,6 +1366,13 @@ var KrisspyAnalytics = class {
    */
   track(eventName, properties) {
     if (!this.initialized) return;
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.track(eventName, properties);
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Tracked:", eventName, properties);
+      }
+      return;
+    }
     const event = {
       eventName,
       sessionId: this.sessionId,
@@ -1365,10 +1391,100 @@ var KrisspyAnalytics = class {
   identify(userId, traits) {
     this.userId = userId;
     this.userTraits = traits || {};
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.identify(__spreadValues({ profileId: userId }, traits));
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Identified:", userId, traits);
+      }
+      return;
+    }
     if (this.initialized) {
       this.track("identify", __spreadValues({ userId }, traits));
     }
   }
+  // ── OpenPanel-specific methods (no-op when using internal analytics) ──
+  /**
+   * Set properties that will be sent with every event
+   */
+  setGlobalProperties(props) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.setGlobalProperties(props);
+    }
+  }
+  /**
+   * Increment a numeric property on a user profile
+   */
+  increment(profileId, property, value) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.increment({ profileId, property, value });
+    }
+  }
+  /**
+   * Decrement a numeric property on a user profile
+   */
+  decrement(profileId, property, value) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.decrement({ profileId, property, value });
+    }
+  }
+  /**
+   * Create or update a group entity (company, team, etc.)
+   */
+  upsertGroup(group) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.upsertGroup(group);
+    }
+  }
+  /**
+   * Link the current user to a group — tags all future events
+   */
+  setGroup(groupId) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.setGroup(groupId);
+    }
+  }
+  /**
+   * Track a revenue event
+   */
+  async revenue(amount, properties) {
+    if (this.useOpenPanel && this.openpanel) {
+      await this.openpanel.revenue(amount, properties);
+    }
+  }
+  /**
+   * Queue a pending revenue event (call flushRevenue() to send)
+   */
+  pendingRevenue(amount, properties) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.pendingRevenue(amount, properties);
+    }
+  }
+  /**
+   * Flush all pending revenue events
+   */
+  async flushRevenue() {
+    if (this.useOpenPanel && this.openpanel) {
+      await this.openpanel.flushRevenue();
+    }
+  }
+  /**
+   * Clear pending revenue
+   */
+  clearRevenue() {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.clearRevenue();
+    }
+  }
+  /**
+   * Clear current user data (including groups)
+   */
+  clear() {
+    this.userId = null;
+    this.userTraits = {};
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.clear();
+    }
+  }
   /**
    * Flush event queue to the server (async)
    */
@@ -1470,6 +1586,46 @@ var KrisspyAnalytics = class {
     };
     window.addEventListener("popstate", this.popstateHandler);
   }
+  /**
+   * Initialize OpenPanel SDK dynamically.
+   * Loads @openpanel/web at runtime (must be installed by the user).
+   * Falls back gracefully if not available.
+   */
+  async initOpenPanel() {
+    const clientId = this.options.openpanelClientId;
+    const apiUrl = this.options.openpanelApiUrl || "https://api-openpanel.krisspy.ai";
+    try {
+      const { OpenPanel } = await import("@openpanel/web");
+      this.openpanel = new OpenPanel({
+        clientId,
+        apiUrl,
+        trackScreenViews: this.options.autoTrackPageViews !== false,
+        trackOutgoingLinks: this.options.trackOutgoingLinks !== false,
+        trackAttributes: this.options.trackAttributes !== false,
+        trackHashChanges: this.options.trackHashChanges,
+        disabled: this.options.disabled,
+        filter: this.options.filter
+      });
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Initialized", { clientId, apiUrl });
+      }
+    } catch (err) {
+      console.warn(
+        "[Krisspy Analytics] @openpanel/web not found. Install it with: npm install @openpanel/web\nFalling back to internal analytics."
+      );
+      this.useOpenPanel = false;
+      this.openpanel = null;
+      this.sessionId = this.getOrCreateSessionId();
+      if (this.options.autoTrackPageViews) {
+        this.track("session_start", {});
+        this.track("page_view", { url: window.location.href, referrer: document.referrer });
+      }
+      if (this.options.autoTrackNavigation) {
+        this.setupNavigationTracking();
+      }
+      this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
+    }
+  }
 };
 
 // src/notifications.ts

package/dist/index.mjs

@@ -1272,6 +1272,9 @@ var KrisspyAnalytics = class {
     this.originalPushState = null;
     this.popstateHandler = null;
     this.unloadHandler = null;
+    /** OpenPanel SDK instance (loaded dynamically when openpanelClientId is set) */
+    this.openpanel = null;
+    this.useOpenPanel = false;
     this.http = http;
     this.backendId = backendId;
   }
@@ -1288,6 +1291,12 @@ var KrisspyAnalytics = class {
       flushInterval: 5e3,
       debug: false
     }, options);
+    if (this.options.openpanelClientId) {
+      this.useOpenPanel = true;
+      this.initialized = true;
+      this.initOpenPanel();
+      return;
+    }
     this.sessionId = this.getOrCreateSessionId();
     this.initialized = true;
     if (this.options.autoTrackPageViews) {
@@ -1304,7 +1313,7 @@ var KrisspyAnalytics = class {
     window.addEventListener("beforeunload", this.unloadHandler);
     this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
     if (this.options.debug) {
-      console.log("[Krisspy Analytics] Initialized", { backendId: this.backendId, sessionId: this.sessionId });
+      console.log("[Krisspy Analytics] Initialized (internal)", { backendId: this.backendId, sessionId: this.sessionId });
     }
   }
   /**
@@ -1312,6 +1321,13 @@ var KrisspyAnalytics = class {
    */
   track(eventName, properties) {
     if (!this.initialized) return;
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.track(eventName, properties);
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Tracked:", eventName, properties);
+      }
+      return;
+    }
     const event = {
       eventName,
       sessionId: this.sessionId,
@@ -1330,10 +1346,100 @@ var KrisspyAnalytics = class {
   identify(userId, traits) {
     this.userId = userId;
     this.userTraits = traits || {};
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.identify(__spreadValues({ profileId: userId }, traits));
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Identified:", userId, traits);
+      }
+      return;
+    }
     if (this.initialized) {
       this.track("identify", __spreadValues({ userId }, traits));
     }
   }
+  // ── OpenPanel-specific methods (no-op when using internal analytics) ──
+  /**
+   * Set properties that will be sent with every event
+   */
+  setGlobalProperties(props) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.setGlobalProperties(props);
+    }
+  }
+  /**
+   * Increment a numeric property on a user profile
+   */
+  increment(profileId, property, value) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.increment({ profileId, property, value });
+    }
+  }
+  /**
+   * Decrement a numeric property on a user profile
+   */
+  decrement(profileId, property, value) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.decrement({ profileId, property, value });
+    }
+  }
+  /**
+   * Create or update a group entity (company, team, etc.)
+   */
+  upsertGroup(group) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.upsertGroup(group);
+    }
+  }
+  /**
+   * Link the current user to a group — tags all future events
+   */
+  setGroup(groupId) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.setGroup(groupId);
+    }
+  }
+  /**
+   * Track a revenue event
+   */
+  async revenue(amount, properties) {
+    if (this.useOpenPanel && this.openpanel) {
+      await this.openpanel.revenue(amount, properties);
+    }
+  }
+  /**
+   * Queue a pending revenue event (call flushRevenue() to send)
+   */
+  pendingRevenue(amount, properties) {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.pendingRevenue(amount, properties);
+    }
+  }
+  /**
+   * Flush all pending revenue events
+   */
+  async flushRevenue() {
+    if (this.useOpenPanel && this.openpanel) {
+      await this.openpanel.flushRevenue();
+    }
+  }
+  /**
+   * Clear pending revenue
+   */
+  clearRevenue() {
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.clearRevenue();
+    }
+  }
+  /**
+   * Clear current user data (including groups)
+   */
+  clear() {
+    this.userId = null;
+    this.userTraits = {};
+    if (this.useOpenPanel && this.openpanel) {
+      this.openpanel.clear();
+    }
+  }
   /**
    * Flush event queue to the server (async)
    */
@@ -1435,6 +1541,46 @@ var KrisspyAnalytics = class {
     };
     window.addEventListener("popstate", this.popstateHandler);
   }
+  /**
+   * Initialize OpenPanel SDK dynamically.
+   * Loads @openpanel/web at runtime (must be installed by the user).
+   * Falls back gracefully if not available.
+   */
+  async initOpenPanel() {
+    const clientId = this.options.openpanelClientId;
+    const apiUrl = this.options.openpanelApiUrl || "https://api-openpanel.krisspy.ai";
+    try {
+      const { OpenPanel } = await import("@openpanel/web");
+      this.openpanel = new OpenPanel({
+        clientId,
+        apiUrl,
+        trackScreenViews: this.options.autoTrackPageViews !== false,
+        trackOutgoingLinks: this.options.trackOutgoingLinks !== false,
+        trackAttributes: this.options.trackAttributes !== false,
+        trackHashChanges: this.options.trackHashChanges,
+        disabled: this.options.disabled,
+        filter: this.options.filter
+      });
+      if (this.options.debug) {
+        console.log("[Krisspy Analytics \u2192 OpenPanel] Initialized", { clientId, apiUrl });
+      }
+    } catch (err) {
+      console.warn(
+        "[Krisspy Analytics] @openpanel/web not found. Install it with: npm install @openpanel/web\nFalling back to internal analytics."
+      );
+      this.useOpenPanel = false;
+      this.openpanel = null;
+      this.sessionId = this.getOrCreateSessionId();
+      if (this.options.autoTrackPageViews) {
+        this.track("session_start", {});
+        this.track("page_view", { url: window.location.href, referrer: document.referrer });
+      }
+      if (this.options.autoTrackNavigation) {
+        this.setupNavigationTracking();
+      }
+      this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
+    }
+  }
 };
 
 // src/notifications.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "krisspy-sdk",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Krisspy Cloud SDK - Database, Auth, Storage, and Functions for your apps",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -41,6 +41,9 @@
     "type": "git",
     "url": "https://github.com/krisspy/krisspy-sdk"
   },
+  "dependencies": {
+    "@openpanel/web": "^1.0.0"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",