@stacksee/analytics 0.13.2 → 0.14.1

package/dist/providers/client.d.ts

@@ -5,6 +5,8 @@ export { BentoClientProvider } from './bento/client.js';
 export type { BentoClientConfig } from './bento/client.js';
 export { PirschClientProvider } from './pirsch/client.js';
 export type { PirschClientConfig } from './pirsch/client.js';
+export { VisitorsClientProvider } from './visitors/client.js';
+export type { VisitorsClientConfig } from './visitors/client.js';
 export { ProxyProvider } from './proxy/client.js';
 export type { ProxyProviderConfig } from './proxy/client.js';
 export type { ProxyBatchConfig, ProxyRetryConfig, ProxyEvent, ProxyPayload, ProxyTrackEvent, ProxyIdentifyEvent, ProxyPageViewEvent, ProxyResetEvent, } from './proxy/types.js';

package/dist/providers/client.js

@@ -1,10 +1,10 @@
-var f = Object.defineProperty;
-var p = (o, h, e) => h in o ? f(o, h, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[h] = e;
-var r = (o, h, e) => p(o, typeof h != "symbol" ? h + "" : h, e);
-import { B as u } from "../base.provider-AfFL5W_P.js";
-import { i as a } from "../client-DTHZYkxx.js";
-import { P as z } from "../client-DTHZYkxx.js";
-class w extends u {
+var g = Object.defineProperty;
+var p = (o, l, e) => l in o ? g(o, l, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[l] = e;
+var r = (o, l, e) => p(o, typeof l != "symbol" ? l + "" : l, e);
+import { B as f } from "../base.provider-AfFL5W_P.js";
+import { i as n } from "../client-DTHZYkxx.js";
+import { P as C } from "../client-DTHZYkxx.js";
+class w extends f {
   constructor(e) {
     super({ debug: e.debug, enabled: e.enabled });
     r(this, "name", "Bento-Client");
@@ -16,7 +16,7 @@ class w extends u {
   }
   async initialize() {
     if (this.isEnabled() && !this.initialized) {
-      if (!a()) {
+      if (!n()) {
         this.log("Skipping initialization - not in browser environment");
         return;
       }
@@ -63,7 +63,7 @@ class w extends u {
     this.log("Identified user", { userId: e, email: s, traits: i });
   }
   track(e, i) {
-    var t, n, l;
+    var t, a, h;
     if (!this.isEnabled() || !this.initialized || !this.bento) return;
     const s = {
       ...e.properties,
@@ -86,14 +86,14 @@ class w extends u {
       ...(i == null ? void 0 : i.utm) && { utm: i.utm },
       // Include user email and traits as regular event properties
       ...((t = i == null ? void 0 : i.user) == null ? void 0 : t.email) && { user_email: i.user.email },
-      ...((n = i == null ? void 0 : i.user) == null ? void 0 : n.traits) && { user_traits: i.user.traits },
-      ...((l = i == null ? void 0 : i.user) == null ? void 0 : l.userId) && { visitor: i.user.userId }
+      ...((a = i == null ? void 0 : i.user) == null ? void 0 : a.traits) && { user_traits: i.user.traits },
+      ...((h = i == null ? void 0 : i.user) == null ? void 0 : h.userId) && { visitor: i.user.userId }
     };
     this.bento.track(e.action, s), this.log("Tracked event", { event: e, context: i });
   }
   pageView(e, i) {
     var s;
-    if (!(!this.isEnabled() || !this.initialized || !this.bento || !a())) {
+    if (!(!this.isEnabled() || !this.initialized || !this.bento || !n())) {
       if (this.bento.view(), e || i != null && i.page) {
         const t = {
           ...e,
@@ -118,7 +118,7 @@ class w extends u {
   }
   pageLeave(e, i) {
     var t;
-    if (!this.isEnabled() || !this.initialized || !this.bento || !a())
+    if (!this.isEnabled() || !this.initialized || !this.bento || !n())
       return;
     const s = {
       ...e,
@@ -139,7 +139,7 @@ class w extends u {
     this.bento.track("$pageleave", s), this.log("Tracked page leave", { properties: e, context: i });
   }
   reset() {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || this.log(
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || this.log(
       "Reset user session - Note: Bento doesn't have a native reset method"
     );
   }
@@ -156,7 +156,7 @@ class w extends u {
    * ```
    */
   tag(e) {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || (this.bento.tag(e), this.log("Added tag to user", { tag: e }));
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || (this.bento.tag(e), this.log("Added tag to user", { tag: e }));
   }
   /**
    * Get the current user's email address
@@ -172,7 +172,7 @@ class w extends u {
    * ```
    */
   getEmail() {
-    return !this.isEnabled() || !this.initialized || !this.bento || !a() ? null : this.bento.getEmail();
+    return !this.isEnabled() || !this.initialized || !this.bento || !n() ? null : this.bento.getEmail();
   }
   /**
    * Get the current user's name
@@ -188,7 +188,7 @@ class w extends u {
    * ```
    */
   getName() {
-    return !this.isEnabled() || !this.initialized || !this.bento || !a() ? null : this.bento.getName();
+    return !this.isEnabled() || !this.initialized || !this.bento || !n() ? null : this.bento.getName();
   }
   // ============================================================================
   // Survey Methods
@@ -209,7 +209,7 @@ class w extends u {
    * ```
    */
   showSurveyForm(e, i, s = "popup") {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || (this.bento.showSurveyForm(e, i, s), this.log("Showed survey form", { surveyId: i, type: s }));
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || (this.bento.showSurveyForm(e, i, s), this.log("Showed survey form", { surveyId: i, type: s }));
   }
   /**
    * Validate an email address using Bento's spam check
@@ -226,7 +226,7 @@ class w extends u {
    * ```
    */
   async spamCheck(e) {
-    if (!this.isEnabled() || !this.initialized || !this.bento || !a())
+    if (!this.isEnabled() || !this.initialized || !this.bento || !n())
       return !1;
     try {
       const i = await this.bento.spamCheck(e);
@@ -247,7 +247,7 @@ class w extends u {
    * ```
    */
   showChat() {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || (this.bento.showChat ? (this.bento.showChat(), this.log("Showed chat widget")) : console.warn(
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || (this.bento.showChat ? (this.bento.showChat(), this.log("Showed chat widget")) : console.warn(
       "[Bento-Client] Chat not available. Make sure chat is enabled in your Bento settings."
     ));
   }
@@ -260,7 +260,7 @@ class w extends u {
    * ```
    */
   hideChat() {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || (this.bento.hideChat ? (this.bento.hideChat(), this.log("Hid chat widget")) : console.warn(
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || (this.bento.hideChat ? (this.bento.hideChat(), this.log("Hid chat widget")) : console.warn(
       "[Bento-Client] Chat not available. Make sure chat is enabled in your Bento settings."
     ));
   }
@@ -273,12 +273,12 @@ class w extends u {
    * ```
    */
   openChat() {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || (this.bento.openChat ? (this.bento.openChat(), this.log("Opened chat widget")) : console.warn(
+    !this.isEnabled() || !this.initialized || !this.bento || !n() || (this.bento.openChat ? (this.bento.openChat(), this.log("Opened chat widget")) : console.warn(
       "[Bento-Client] Chat not available. Make sure chat is enabled in your Bento settings."
     ));
   }
 }
-class m extends u {
+class m extends f {
   constructor(e) {
     super({ debug: e.debug, enabled: e.enabled });
     r(this, "name", "Pirsch-Client");
@@ -289,7 +289,7 @@ class m extends u {
   }
   async initialize() {
     if (this.isEnabled() && !this.initialized) {
-      if (!a()) {
+      if (!n()) {
         this.log("Skipping initialization - not in browser environment");
         return;
       }
@@ -319,7 +319,7 @@ class m extends u {
     }), this.log("Identified user via event", { userId: e, traits: i }));
   }
   async track(e, i) {
-    var t, n;
+    var t, a;
     if (!this.isEnabled() || !this.initialized || !this.client) return;
     const s = {
       ...e.properties,
@@ -334,33 +334,33 @@ class m extends u {
       ...(i == null ? void 0 : i.device) && { device: i.device },
       ...(i == null ? void 0 : i.utm) && { utm: i.utm },
       ...((t = i == null ? void 0 : i.user) == null ? void 0 : t.email) && { user_email: i.user.email },
-      ...((n = i == null ? void 0 : i.user) == null ? void 0 : n.traits) && { user_traits: i.user.traits }
+      ...((a = i == null ? void 0 : i.user) == null ? void 0 : a.traits) && { user_traits: i.user.traits }
     };
     try {
       await this.client.event(e.action, 0, s), this.log("Tracked event", { event: e, context: i });
-    } catch (l) {
-      console.error("[Pirsch-Client] Failed to track event:", l);
+    } catch (h) {
+      console.error("[Pirsch-Client] Failed to track event:", h);
     }
   }
   pageView(e, i) {
-    var l, g;
-    if (!this.isEnabled() || !this.initialized || !this.client || !a())
+    var h, d;
+    if (!this.isEnabled() || !this.initialized || !this.client || !n())
       return;
     const s = e && Object.keys(e).length > 0 ? Object.fromEntries(
       Object.entries(e).filter(
-        ([, d]) => typeof d == "string" || typeof d == "number" || typeof d == "boolean"
+        ([, u]) => typeof u == "string" || typeof u == "number" || typeof u == "boolean"
       )
     ) : void 0, t = {
-      ...((l = i == null ? void 0 : i.page) == null ? void 0 : l.url) && { url: i.page.url },
-      ...((g = i == null ? void 0 : i.page) == null ? void 0 : g.title) && { title: i.page.title },
+      ...((h = i == null ? void 0 : i.page) == null ? void 0 : h.url) && { url: i.page.url },
+      ...((d = i == null ? void 0 : i.page) == null ? void 0 : d.title) && { title: i.page.title },
       ...s && { tags: s }
-    }, n = Object.keys(t).length > 0 ? t : void 0;
-    this.client.hit(n).catch((d) => {
-      console.error("[Pirsch-Client] Failed to track page view:", d);
+    }, a = Object.keys(t).length > 0 ? t : void 0;
+    this.client.hit(a).catch((u) => {
+      console.error("[Pirsch-Client] Failed to track page view:", u);
     }), this.log("Tracked page view", { properties: e, context: i });
   }
   pageLeave(e, i) {
-    if (!this.isEnabled() || !this.initialized || !this.client || !a())
+    if (!this.isEnabled() || !this.initialized || !this.client || !n())
       return;
     const s = {
       ...e,
@@ -374,14 +374,127 @@ class m extends u {
     }), this.log("Tracked page leave", { properties: e, context: i });
   }
   reset() {
-    !this.isEnabled() || !this.initialized || !this.client || !a() || (this.client.event("session_reset", 0, {}).catch((e) => {
+    !this.isEnabled() || !this.initialized || !this.client || !n() || (this.client.event("session_reset", 0, {}).catch((e) => {
       console.error("[Pirsch-Client] Failed to track session reset:", e);
     }), this.log("Reset user session"));
   }
 }
-class v extends u {
+class v extends f {
   constructor(e) {
-    var i, s, t, n, l;
+    super({ debug: e.debug, enabled: e.enabled });
+    r(this, "name", "Visitors-Client");
+    r(this, "visitors");
+    r(this, "initialized", !1);
+    r(this, "config");
+    r(this, "scriptLoaded", !1);
+    this.config = e;
+  }
+  async initialize() {
+    if (this.isEnabled() && !this.initialized) {
+      if (!n()) {
+        this.log("Skipping initialization - not in browser environment");
+        return;
+      }
+      if (!this.config.token || typeof this.config.token != "string")
+        throw new Error("Visitors requires a token");
+      try {
+        this.scriptLoaded || await this.loadScript(), await this.waitForVisitors(), this.visitors = window.visitors, this.initialized = !0, this.log("Initialized successfully", this.config);
+      } catch (e) {
+        throw console.error("[Visitors-Client] Failed to initialize:", e), e;
+      }
+    }
+  }
+  async loadScript() {
+    return new Promise((e, i) => {
+      if (document.querySelector(
+        'script[src*="cdn.visitors.now"]'
+      )) {
+        this.scriptLoaded = !0, e();
+        return;
+      }
+      const t = document.createElement("script");
+      t.src = "https://cdn.visitors.now/v.js", t.setAttribute("data-token", this.config.token), this.config.persist && t.setAttribute("data-persist", ""), t.async = !0, t.defer = !0, t.onload = () => {
+        this.scriptLoaded = !0, e();
+      }, t.onerror = () => {
+        i(new Error("Failed to load Visitors script"));
+      }, document.head.appendChild(t);
+    });
+  }
+  async waitForVisitors(e = 50, i = 100) {
+    for (let s = 0; s < e; s++) {
+      if (window.visitors)
+        return;
+      await new Promise((t) => setTimeout(t, i));
+    }
+    throw new Error("Visitors SDK not available after loading script");
+  }
+  identify(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.visitors) return;
+    const s = { id: e };
+    if (i)
+      for (const [t, a] of Object.entries(i))
+        (typeof a == "string" || typeof a == "number") && (s[t] = a);
+    this.visitors.identify(s), this.log("Identified user", { userId: e, traits: i });
+  }
+  track(e, i) {
+    var t, a;
+    if (!this.isEnabled() || !this.initialized || !this.visitors) return;
+    const s = {};
+    if (e.properties)
+      for (const [h, d] of Object.entries(e.properties))
+        (typeof d == "string" || typeof d == "number") && (s[h] = d);
+    e.category && (s.category = e.category), (t = i == null ? void 0 : i.page) != null && t.path && (s.page_path = i.page.path), (a = i == null ? void 0 : i.page) != null && a.title && (s.page_title = i.page.title), this.visitors.track(e.action, s), this.log("Tracked event", { event: e, context: i });
+  }
+  pageView(e, i) {
+    this.log("Page view - handled automatically by Visitors script", {
+      properties: e,
+      context: i
+    });
+  }
+  pageLeave(e, i) {
+    var t;
+    if (!this.isEnabled() || !this.initialized || !this.visitors || !n())
+      return;
+    const s = {};
+    if ((t = i == null ? void 0 : i.page) != null && t.path && (s.page_path = i.page.path), e)
+      for (const [a, h] of Object.entries(e))
+        (typeof h == "string" || typeof h == "number") && (s[a] = h);
+    this.visitors.track("page_leave", s), this.log("Tracked page leave", { properties: e, context: i });
+  }
+  reset() {
+    !this.isEnabled() || !this.initialized || !this.visitors || !n() || this.log("Reset user session - Note: Visitors does not have a native reset method");
+  }
+  // ============================================================================
+  // Stripe Revenue Attribution
+  // ============================================================================
+  /**
+   * Returns the current visitor ID from the `visitor` cookie set by the
+   * visitors.now script. Pass this value in your Stripe checkout session
+   * metadata so revenue is attributed to the correct visitor.
+   *
+   * Requires persist mode to be enabled in your visitors.now project settings.
+   *
+   * @example Server-side Stripe checkout creation:
+   * ```typescript
+   * // Client-side: get visitor ID and send to your server
+   * const visitorId = visitorsProvider.getVisitorId();
+   *
+   * // Server-side: include in Stripe checkout session
+   * const session = await stripe.checkout.sessions.create({
+   *   // ...
+   *   metadata: { visitor: visitorId },
+   * });
+   * ```
+   */
+  getVisitorId() {
+    if (!n()) return null;
+    const e = document.cookie.split("; ").find((i) => i.startsWith("visitor="));
+    return e ? decodeURIComponent(e.split("=")[1]) : null;
+  }
+}
+class k extends f {
+  constructor(e) {
+    var i, s, t, a, h;
     super({ debug: e.debug, enabled: e.enabled });
     r(this, "name", "Proxy");
     r(this, "config");
@@ -392,7 +505,7 @@ class v extends u {
     r(this, "retryAttempts");
     r(this, "retryBackoff");
     r(this, "retryInitialDelay");
-    this.config = e, this.batchSize = ((i = e.batch) == null ? void 0 : i.size) ?? 10, this.batchInterval = ((s = e.batch) == null ? void 0 : s.interval) ?? 2e3, this.retryAttempts = ((t = e.retry) == null ? void 0 : t.attempts) ?? 3, this.retryBackoff = ((n = e.retry) == null ? void 0 : n.backoff) ?? "exponential", this.retryInitialDelay = ((l = e.retry) == null ? void 0 : l.initialDelay) ?? 1e3, typeof window < "u" && (window.addEventListener("beforeunload", () => {
+    this.config = e, this.batchSize = ((i = e.batch) == null ? void 0 : i.size) ?? 10, this.batchInterval = ((s = e.batch) == null ? void 0 : s.interval) ?? 2e3, this.retryAttempts = ((t = e.retry) == null ? void 0 : t.attempts) ?? 3, this.retryBackoff = ((a = e.retry) == null ? void 0 : a.backoff) ?? "exponential", this.retryInitialDelay = ((h = e.retry) == null ? void 0 : h.initialDelay) ?? 1e3, typeof window < "u" && (window.addEventListener("beforeunload", () => {
       this.flush(!0);
     }), document.addEventListener("visibilitychange", () => {
       document.visibilityState === "hidden" && this.flush(!0);
@@ -480,7 +593,7 @@ class v extends u {
     } catch (s) {
       if (i < this.retryAttempts) {
         const t = this.calculateRetryDelay(i);
-        return this.log(`Retry attempt ${i + 1} after ${t}ms`, { error: s }), await new Promise((n) => setTimeout(n, t)), this.sendWithRetry(e, i + 1);
+        return this.log(`Retry attempt ${i + 1} after ${t}ms`, { error: s }), await new Promise((a) => setTimeout(a, t)), this.sendWithRetry(e, i + 1);
       }
       throw console.error("[Proxy] Failed to send events after retries:", s), s;
     }
@@ -519,9 +632,10 @@ class v extends u {
   }
 }
 export {
-  u as BaseAnalyticsProvider,
+  f as BaseAnalyticsProvider,
   w as BentoClientProvider,
   m as PirschClientProvider,
-  z as PostHogClientProvider,
-  v as ProxyProvider
+  C as PostHogClientProvider,
+  k as ProxyProvider,
+  v as VisitorsClientProvider
 };

package/dist/providers/visitors/client.d.ts

@@ -0,0 +1,73 @@
+import { BaseEvent, EventContext } from '../../core/events/types.js';
+import { BaseAnalyticsProvider } from '../base.provider.js';
+interface VisitorsClient {
+    track(event: string, properties?: Record<string, string | number>): void;
+    identify(traits: {
+        id: string;
+        email?: string;
+        name?: string;
+        [key: string]: string | number | undefined;
+    }): void;
+}
+export interface VisitorsClientConfig {
+    /**
+     * Your Visitors project token from the dashboard
+     */
+    token: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Enable/disable the provider
+     */
+    enabled?: boolean;
+    /**
+     * Enable persist mode. Sets the `data-persist` attribute on the Visitors
+     * script tag so the visitor cookie is written, enabling cross-session
+     * tracking and Stripe revenue attribution via `getVisitorId()`.
+     */
+    persist?: boolean;
+}
+declare global {
+    interface Window {
+        visitors?: VisitorsClient;
+    }
+}
+export declare class VisitorsClientProvider extends BaseAnalyticsProvider {
+    name: string;
+    private visitors?;
+    private initialized;
+    private config;
+    private scriptLoaded;
+    constructor(config: VisitorsClientConfig);
+    initialize(): Promise<void>;
+    private loadScript;
+    private waitForVisitors;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageLeave(properties?: Record<string, unknown>, context?: EventContext): void;
+    reset(): void;
+    /**
+     * Returns the current visitor ID from the `visitor` cookie set by the
+     * visitors.now script. Pass this value in your Stripe checkout session
+     * metadata so revenue is attributed to the correct visitor.
+     *
+     * Requires persist mode to be enabled in your visitors.now project settings.
+     *
+     * @example Server-side Stripe checkout creation:
+     * ```typescript
+     * // Client-side: get visitor ID and send to your server
+     * const visitorId = visitorsProvider.getVisitorId();
+     *
+     * // Server-side: include in Stripe checkout session
+     * const session = await stripe.checkout.sessions.create({
+     *   // ...
+     *   metadata: { visitor: visitorId },
+     * });
+     * ```
+     */
+    getVisitorId(): string | null;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {
@@ -79,6 +79,8 @@
     "test:watch": "vitest",
     "test:e2e": "node e2e/pirsch.test.js",
     "test:e2e:server": "node e2e/test-app/server.js",
+    "test:e2e:visitors": "node e2e/visitors.test.js",
+    "test:e2e:visitors:server": "node e2e/visitors-test-app/server.js",
     "build": "vite build",
     "dev": "pnpm --filter @stacksee/docs dev",
     "build:docs": "pnpm --filter @stacksee/docs build",