@stacksee/analytics 0.3.3 → 0.4.2

package/dist/server-BKqARaUf.js

@@ -0,0 +1,174 @@
+var p = Object.defineProperty;
+var g = (a, s, e) => s in a ? p(a, s, { enumerable: !0, configurable: !0, writable: !0, value: e }) : a[s] = e;
+var t = (a, s, e) => g(a, typeof s != "symbol" ? s + "" : s, e);
+import { i as h } from "./environment-Bnc8FqHv.js";
+import { PostHog as o } from "posthog-node";
+class l {
+  constructor(s) {
+    t(this, "debug", !1);
+    t(this, "enabled", !0);
+    (s == null ? void 0 : s.debug) !== void 0 && (this.debug = s.debug), (s == null ? void 0 : s.enabled) !== void 0 && (this.enabled = s.enabled);
+  }
+  log(s, e) {
+    this.debug && console.log(`[${this.name}] ${s}`, e);
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+}
+class b extends l {
+  constructor(e) {
+    super({ debug: e.debug, enabled: e.enabled });
+    t(this, "name", "PostHog-Client");
+    t(this, "posthog");
+    t(this, "initialized", !1);
+    t(this, "config");
+    this.config = e;
+  }
+  async initialize() {
+    if (this.isEnabled() && !this.initialized) {
+      if (!h()) {
+        this.log("Skipping initialization - not in browser environment");
+        return;
+      }
+      if (!this.config.token || typeof this.config.token != "string")
+        throw new Error("PostHog requires a token");
+      try {
+        const { default: e } = await import("posthog-js"), { token: i, debug: r, ...d } = this.config;
+        e.init(i, {
+          ...d,
+          debug: r ?? this.debug
+        }), this.posthog = e, this.initialized = !0, this.log("Initialized successfully", this.config);
+      } catch (e) {
+        throw console.error("[PostHog-Client] Failed to initialize:", e), e;
+      }
+    }
+  }
+  identify(e, i) {
+    !this.isEnabled() || !this.initialized || !this.posthog || (this.posthog.identify(e, i), this.log("Identified user", { userId: e, traits: i }));
+  }
+  track(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.posthog) return;
+    const r = {
+      ...e.properties,
+      category: e.category,
+      timestamp: e.timestamp || Date.now(),
+      ...e.userId && { userId: e.userId },
+      ...e.sessionId && { sessionId: e.sessionId },
+      ...(i == null ? void 0 : i.page) && { $current_url: i.page.path },
+      ...(i == null ? void 0 : i.device) && { device: i.device },
+      ...(i == null ? void 0 : i.utm) && { utm: i.utm }
+    };
+    this.posthog.capture(e.action, r), this.log("Tracked event", { event: e, context: i });
+  }
+  pageView(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.posthog || !h())
+      return;
+    const r = {
+      ...e,
+      ...(i == null ? void 0 : i.page) && {
+        path: i.page.path,
+        title: i.page.title,
+        referrer: i.page.referrer
+      }
+    };
+    this.posthog.capture("$pageview", r), this.log("Tracked page view", { properties: e, context: i });
+  }
+  pageLeave(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.posthog || !h())
+      return;
+    const r = {
+      ...e,
+      ...(i == null ? void 0 : i.page) && {
+        path: i.page.path,
+        title: i.page.title,
+        referrer: i.page.referrer
+      }
+    };
+    this.posthog.capture("$pageleave", r), this.log("Tracked page leave", { properties: e, context: i });
+  }
+  reset() {
+    !this.isEnabled() || !this.initialized || !this.posthog || !h() || (this.posthog.reset(), this.log("Reset user session"));
+  }
+}
+class m extends l {
+  constructor(e) {
+    super({ debug: e.debug, enabled: e.enabled });
+    t(this, "name", "PostHog-Server");
+    t(this, "client");
+    t(this, "initialized", !1);
+    t(this, "config");
+    this.config = e;
+  }
+  initialize() {
+    if (this.isEnabled() && !this.initialized) {
+      if (!this.config.apiKey || typeof this.config.apiKey != "string")
+        throw new Error("PostHog requires an apiKey");
+      try {
+        const { apiKey: e, ...i } = this.config;
+        this.client = new o(e, {
+          host: "https://app.posthog.com",
+          flushAt: 20,
+          flushInterval: 1e4,
+          ...i
+        }), this.initialized = !0, this.log("Initialized successfully", this.config);
+      } catch (e) {
+        throw console.error("[PostHog-Server] Failed to initialize:", e), e;
+      }
+    }
+  }
+  identify(e, i) {
+    !this.isEnabled() || !this.initialized || !this.client || (this.client.identify({
+      distinctId: e,
+      properties: i
+    }), this.log("Identified user", { userId: e, traits: i }));
+  }
+  track(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const r = {
+      ...e.properties,
+      category: e.category,
+      timestamp: e.timestamp ? new Date(e.timestamp) : /* @__PURE__ */ new Date(),
+      ...e.sessionId && { sessionId: e.sessionId },
+      ...(i == null ? void 0 : i.page) && {
+        $current_url: i.page.path,
+        $page_title: i.page.title,
+        $referrer: i.page.referrer
+      },
+      ...(i == null ? void 0 : i.device) && { device: i.device },
+      ...(i == null ? void 0 : i.utm) && { utm: i.utm }
+    };
+    this.client.capture({
+      distinctId: e.userId || "anonymous",
+      event: e.action,
+      properties: r
+    }), this.log("Tracked event", { event: e, context: i });
+  }
+  pageView(e, i) {
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const r = {
+      ...e,
+      ...(i == null ? void 0 : i.page) && {
+        path: i.page.path,
+        title: i.page.title,
+        referrer: i.page.referrer
+      }
+    };
+    this.client.capture({
+      distinctId: "anonymous",
+      event: "$pageview",
+      properties: r
+    }), this.log("Tracked page view", { properties: e, context: i });
+  }
+  async reset() {
+    !this.isEnabled() || !this.initialized || !this.client || (await this.client.flush(), this.log("Flushed pending events"));
+  }
+  async shutdown() {
+    this.client && (await this.client.shutdown(), this.log("Shutdown complete"));
+  }
+}
+export {
+  l as B,
+  b as P,
+  m as a
+};

package/dist/server.js

@@ -1,11 +1,11 @@
 var o = Object.defineProperty;
 var f = (r, e, t) => e in r ? o(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
-var a = (r, e, t) => f(r, typeof e != "symbol" ? e + "" : e, t);
+var n = (r, e, t) => f(r, typeof e != "symbol" ? e + "" : e, t);
 class u {
   constructor(e) {
-    a(this, "providers", []);
-    a(this, "config");
-    a(this, "initialized", !1);
+    n(this, "providers", []);
+    n(this, "config");
+    n(this, "initialized", !1);
     this.config = e, this.providers = e.providers;
   }
   initialize() {
@@ -24,7 +24,7 @@ class u {
       console.warn("[Analytics] Not initialized. Call initialize() first.");
       return;
     }
-    const n = {
+    const a = {
       action: e,
       category: this.getCategoryFromEventName(e),
       properties: t,
@@ -36,7 +36,7 @@ class u {
       ...i == null ? void 0 : i.context
     }, d = this.providers.map(async (s) => {
       try {
-        await s.track(n, c);
+        await s.track(a, c);
       } catch (l) {
         console.error(
           `[Analytics] Provider ${s.name} failed to track event:`,
@@ -46,14 +46,23 @@ class u {
     });
     await Promise.all(d);
   }
-  page(e, t) {
+  pageView(e, t) {
     if (!this.initialized) return;
     const i = {
       ...this.config.defaultContext,
       ...t == null ? void 0 : t.context
     };
-    for (const n of this.providers)
-      n.page(e, i);
+    for (const a of this.providers)
+      a.pageView(e, i);
+  }
+  pageLeave(e, t) {
+    if (!this.initialized) return;
+    const i = {
+      ...this.config.defaultContext,
+      ...t == null ? void 0 : t.context
+    };
+    for (const a of this.providers)
+      a.pageLeave && a.pageLeave(e, i);
   }
   async shutdown() {
     const e = this.providers.map((t) => "shutdown" in t && typeof t.shutdown == "function" ? t.shutdown() : Promise.resolve());

package/dist/src/adapters/client/browser-analytics.d.ts

@@ -13,7 +13,8 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
     private ensureInitialized;
     identify(userId: string, traits?: Record<string, unknown>): void;
     track<TEventName extends keyof TEventMap & string>(eventName: TEventName, properties: TEventMap[TEventName]): Promise<void>;
-    page(properties?: Record<string, unknown>): void;
+    pageView(properties?: Record<string, unknown>): void;
+    pageLeave(properties?: Record<string, unknown>): void;
     reset(): void;
     updateContext(context: Partial<EventContext>): void;
     private getCategoryFromEventName;

package/dist/src/adapters/server/server-analytics.d.ts

@@ -12,7 +12,10 @@ export declare class ServerAnalytics<TEventMap extends DefaultEventMap = Default
         sessionId?: string;
         context?: EventContext;
     }): Promise<void>;
-    page(properties?: Record<string, unknown>, options?: {
+    pageView(properties?: Record<string, unknown>, options?: {
+        context?: EventContext;
+    }): void;
+    pageLeave(properties?: Record<string, unknown>, options?: {
         context?: EventContext;
     }): void;
     shutdown(): Promise<void>;

package/dist/src/client/index.d.ts

@@ -1,7 +1,7 @@
-export { createClientAnalytics, createAnalytics, getAnalytics, track, identify, page, reset, type ClientAnalyticsConfig, } from '../client.js';
+export { createClientAnalytics, createAnalytics, getAnalytics, track, identify, pageView, pageLeave, reset, type ClientAnalyticsConfig, } from '../client.js';
 export { BrowserAnalytics } from '../adapters/client/browser-analytics.js';
 export { PostHogClientProvider } from '../providers/posthog/client.js';
-export type { PostHogConfig } from '../providers/posthog/types.js';
+export type { PostHogConfig } from 'posthog-js';
 export { BaseAnalyticsProvider } from '../providers/base.provider.js';
 export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from '../core/events/types.js';
 export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, } from '../core/events/index.js';

package/dist/src/client.d.ts

@@ -52,7 +52,11 @@ export declare function identify(userId: string, traits?: Record<string, unknown
 /**
  * Convenience function to track page views
  */
-export declare function page(properties?: Record<string, unknown>): void;
+export declare function pageView(properties?: Record<string, unknown>): void;
+/**
+ * Convenience function to track page leave events
+ */
+export declare function pageLeave(properties?: Record<string, unknown>): void;
 /**
  * Convenience function to reset user session
  */

package/dist/src/core/events/types.d.ts

@@ -30,7 +30,8 @@ export interface AnalyticsProvider {
     initialize(): Promise<void> | void;
     identify(userId: string, traits?: Record<string, unknown>): Promise<void> | void;
     track(event: BaseEvent, context?: EventContext): Promise<void> | void;
-    page(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    pageLeave?(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
     reset(): Promise<void> | void;
 }
 export interface AnalyticsConfig {

package/dist/src/index.d.ts

@@ -1,6 +1,6 @@
 export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from './core/events/types.js';
 export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, EventMapFromCollection, } from './core/events/index.js';
-export { createAnalytics as createClientAnalytics, getAnalytics, track as trackClient, identify as identifyClient, page as pageClient, reset as resetClient, type ClientAnalyticsConfig, } from './client.js';
+export { createAnalytics as createClientAnalytics, getAnalytics, track as trackClient, identify as identifyClient, pageView as pageViewClient, pageLeave as pageLeaveClient, reset as resetClient, type ClientAnalyticsConfig, } from './client.js';
 export { createServerAnalytics, ServerAnalytics, type ServerAnalyticsConfig, } from './server.js';
-export { BaseAnalyticsProvider, PostHogClientProvider, PostHogServerProvider, type PostHogConfig, } from './providers/index.js';
+export { BaseAnalyticsProvider, PostHogClientProvider, PostHogServerProvider, type PostHogConfig, type PostHogOptions, } from './providers/index.js';
 export { BrowserAnalytics } from './adapters/client/browser-analytics.js';

package/dist/src/providers/base.provider.d.ts

@@ -10,7 +10,8 @@ export declare abstract class BaseAnalyticsProvider implements AnalyticsProvider
     abstract initialize(): Promise<void> | void;
     abstract identify(userId: string, traits?: Record<string, unknown>): Promise<void> | void;
     abstract track(event: BaseEvent, context?: EventContext): Promise<void> | void;
-    abstract page(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    abstract pageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    pageLeave?(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
     abstract reset(): Promise<void> | void;
     protected log(message: string, data?: unknown): void;
     protected isEnabled(): boolean;

package/dist/src/providers/index.d.ts

@@ -1,4 +1,5 @@
 export { BaseAnalyticsProvider } from './base.provider.js';
 export { PostHogClientProvider } from './posthog/client.js';
 export { PostHogServerProvider } from './posthog/server.js';
-export type { PostHogConfig } from './posthog/types.js';
+export type { PostHogConfig } from 'posthog-js';
+export type { PostHogOptions } from 'posthog-node';

package/dist/src/providers/posthog/client.d.ts

@@ -1,24 +1,20 @@
 import { BaseEvent, EventContext } from '../../core/events/types.js';
 import { BaseAnalyticsProvider } from '../base.provider.js';
-import { PostHogConfig } from './types.js';
-import { PostHog } from 'posthog-js';
-declare global {
-    interface Window {
-        posthog?: PostHog;
-    }
-}
+import { PostHogConfig } from 'posthog-js';
 export declare class PostHogClientProvider extends BaseAnalyticsProvider {
     name: string;
     private posthog?;
     private initialized;
     private config;
-    constructor(config: PostHogConfig & {
+    constructor(config: Partial<PostHogConfig> & {
+        token: string;
         debug?: boolean;
         enabled?: boolean;
     });
     initialize(): Promise<void>;
     identify(userId: string, traits?: Record<string, unknown>): void;
     track(event: BaseEvent, context?: EventContext): void;
-    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageLeave(properties?: Record<string, unknown>, context?: EventContext): void;
     reset(): void;
 }

package/dist/src/providers/posthog/server.d.ts

@@ -1,19 +1,21 @@
 import { BaseEvent, EventContext } from '../../core/events/types.js';
 import { BaseAnalyticsProvider } from '../base.provider.js';
-import { PostHogConfig } from './types.js';
+import { PostHogOptions } from 'posthog-node';
 export declare class PostHogServerProvider extends BaseAnalyticsProvider {
     name: string;
     private client?;
     private initialized;
     private config;
-    constructor(config: PostHogConfig & {
+    constructor(config: {
+        apiKey: string;
+    } & PostHogOptions & {
         debug?: boolean;
         enabled?: boolean;
     });
     initialize(): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
     track(event: BaseEvent, context?: EventContext): void;
-    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
     reset(): Promise<void>;
     shutdown(): Promise<void>;
 }

package/dist/src/server/index.d.ts

@@ -1,6 +1,6 @@
 export { createServerAnalytics, ServerAnalytics, type ServerAnalyticsConfig, } from '../server.js';
 export { PostHogServerProvider } from '../providers/posthog/server.js';
-export type { PostHogConfig } from '../providers/posthog/types.js';
+export type { PostHogOptions } from 'posthog-node';
 export { BaseAnalyticsProvider } from '../providers/base.provider.js';
 export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from '../core/events/types.js';
 export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, } from '../core/events/index.js';

package/dist/src/utils/environment.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Environment detection utilities
+ */
+/**
+ * Check if we're running in a browser environment
+ * @returns true if running in browser, false if in Node.js or other environments
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if we're running in a Node.js environment
+ * @returns true if running in Node.js, false otherwise
+ */
+export declare function isNode(): boolean;
+/**
+ * Check if we're running in a server-side rendering context
+ * @returns true if likely in SSR context, false otherwise
+ */
+export declare function isSSR(): boolean;

package/dist/test/mock-provider.d.ts

@@ -13,7 +13,11 @@ export declare class MockAnalyticsProvider extends BaseAnalyticsProvider {
             event: BaseEvent;
             context?: EventContext;
         }>;
-        page: Array<{
+        pageView: Array<{
+            properties?: Record<string, unknown>;
+            context?: EventContext;
+        }>;
+        pageLeave: Array<{
             properties?: Record<string, unknown>;
             context?: EventContext;
         }>;
@@ -22,7 +26,8 @@ export declare class MockAnalyticsProvider extends BaseAnalyticsProvider {
     initialize(): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
     track(event: BaseEvent, context?: EventContext): void;
-    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageLeave(properties?: Record<string, unknown>, context?: EventContext): void;
     reset(): void;
     clearCalls(): void;
     isInitialized(): boolean;

package/dist/test/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {
@@ -57,8 +57,8 @@
     "vitest": "^2.0.3"
   },
   "optionalDependencies": {
-    "posthog-js": "^1.96.0",
-    "posthog-node": "^3.2.0"
+    "posthog-js": "^1.268.2",
+    "posthog-node": "^5.9.0"
   },
   "engines": {
     "pnpm": ">=9.0.0",

package/readme.md

@@ -445,6 +445,42 @@ export const POST: RequestHandler = async ({ request }) => {
 };
 ```
 
+#### Note for SvelteKit Users: Navigation Tracking
+
+If you're using SvelteKit and want to track page views and page leaves automatically with PostHog (as recommended in their documentation), add this to your root layout:
+
+```typescript
+// src/app.html or src/routes/+layout.svelte
+<script>
+  import { pageView, pageLeave } from '@stacksee/analytics/client';
+  import { beforeNavigate, afterNavigate } from '$app/navigation';
+  import { browser } from '$app/environment';
+
+  let { children } = $props():
+
+  // Only set up navigation tracking in the browser
+  if (browser) {
+    beforeNavigate(() => {
+      pageLeave();
+    });
+
+    afterNavigate(() => {
+      pageView();
+    });
+  }
+</script>
+
+<main>
+  {@render children()}
+</main>
+```
+
+This automatically tracks:
+- **Page leaves** before navigation (`$pageleave` events in PostHog)
+- **Page views** after navigation (`$pageview` events in PostHog)
+
+The tracking is framework-agnostic, so you can use similar patterns with Next.js router events, Vue Router hooks, or any other navigation system.
+
 ### Event Categories
 
 Event categories help organize your analytics data. The SDK provides predefined categories with TypeScript autocomplete:
@@ -759,7 +795,8 @@ const analytics = createClientAnalytics<typeof AppEvents>({
 #### `BrowserAnalytics<TEventMap>`
 - `track(eventName, properties): Promise<void>` - Track an event with type-safe event names and properties
 - `identify(userId, traits)` - Identify a user
-- `page(properties)` - Track a page view
+- `pageView(properties)` - Track a page view
+- `pageLeave(properties)` - Track a page leave event
 - `reset()` - Reset user session
 - `updateContext(context)` - Update event context
 
@@ -784,7 +821,8 @@ const analytics = createServerAnalytics<AppEvents>({
 #### `ServerAnalytics<TEventMap>`
 - `track(eventName, properties, options): Promise<void>` - Track an event with type-safe event names and properties
 - `identify(userId, traits)` - Identify a user
-- `page(properties, options)` - Track a page view
+- `pageView(properties, options)` - Track a page view
+- `pageLeave(properties, options)` - Track a page leave event
 - `shutdown()` - Flush pending events and cleanup
 
 ### Type Helpers