@trakoo/posthog 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 trakoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @trakoo/posthog
+
+PostHog providers for [trakoo](https://www.npmjs.com/package/trakoo), the typed, provider-agnostic analytics library.
+
+## Installation
+
+Install the package with only the PostHog SDK for the side you use:
+
+```bash
+# Browser
+pnpm add trakoo @trakoo/posthog posthog-js
+
+# Server
+pnpm add trakoo @trakoo/posthog posthog-node
+```
+
+## Usage
+
+`appEvents` is your event registry, created with `defineEvents()` from `trakoo`.
+
+```typescript title="lib/analytics.ts"
+import { createClientAnalytics } from 'trakoo/client';
+import { PostHogClientProvider } from '@trakoo/posthog/client';
+import { appEvents } from './events';
+
+export const analytics = createClientAnalytics({
+  events: appEvents,
+  providers: [
+    new PostHogClientProvider({
+      token: import.meta.env.VITE_POSTHOG_KEY,
+      api_host: import.meta.env.VITE_POSTHOG_HOST
+    })
+  ]
+});
+```
+
+```typescript title="lib/server-analytics.ts"
+import { createServerAnalytics } from 'trakoo/server';
+import { PostHogServerProvider } from '@trakoo/posthog/server';
+import { appEvents } from './events';
+
+export function createRequestAnalytics() {
+  return createServerAnalytics({
+    events: appEvents,
+    providers: [
+      new PostHogServerProvider({
+        apiKey: process.env.POSTHOG_API_KEY!,
+        host: 'https://us.i.posthog.com'
+      })
+    ]
+  });
+}
+```
+
+PostHog's Node client queues events. Call `shutdown()` on a request-owned instance before the request ends.
+
+Server events take their distinct ID from each call. An event without a user is sent anonymously, without a person profile. Pass the visitor's IP and user agent as `context.server` so PostHog can locate the visitor and see their browser. The provider sends them as `$ip` and `$raw_user_agent`, and turns GeoIP on for events that carry an IP unless you set `disableGeoip`.
+
+In the browser, PostHog captures page views on its own by default. If you call trakoo's `pageView()`, set `capture_pageview: false` so views aren't counted twice.
+
+## Documentation
+
+https://trakoo.co/docs/providers/posthog

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+import type { PostHogConfig } from "posthog-js";
+export type PostHogClientConfig = Partial<PostHogConfig> & {
+    token: string;
+    instanceName?: string;
+    debug?: boolean;
+    enabled?: boolean;
+};
+export declare class PostHogClientProvider extends BaseAnalyticsProvider {
+    name: string;
+    private posthog?;
+    private initialized;
+    private initializePromise?;
+    private readonly config;
+    private readonly instanceName;
+    constructor(config: PostHogClientConfig);
+    initialize(): Promise<void>;
+    private initializePostHog;
+    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;
+}
+export type { PostHogConfig } from "posthog-js";

package/dist/client.js

@@ -0,0 +1,113 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+import { isBrowser } from "./environment.js";
+let posthogProviderSequence = 0;
+const nextInstanceName = () => `trakoo_${++posthogProviderSequence}`;
+export class PostHogClientProvider extends BaseAnalyticsProvider {
+    name = "PostHog-Client";
+    posthog;
+    initialized = false;
+    initializePromise;
+    config;
+    instanceName;
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+        this.instanceName = config.instanceName ?? nextInstanceName();
+    }
+    initialize() {
+        if (!this.isEnabled() || this.initialized)
+            return Promise.resolve();
+        if (this.initializePromise)
+            return this.initializePromise;
+        // Check if we're in a browser environment
+        if (!isBrowser()) {
+            this.log("Skipping initialization - not in browser environment");
+            return Promise.resolve();
+        }
+        this.initializePromise = this.initializePostHog().catch((error) => {
+            this.initializePromise = undefined;
+            console.error(`[PostHog-Client] Failed to initialize (${this.getErrorClass(error)})`);
+            throw error;
+        });
+        return this.initializePromise;
+    }
+    async initializePostHog() {
+        // Validate config has required fields
+        if (!this.config.token || typeof this.config.token !== "string") {
+            throw new Error("PostHog requires a token");
+        }
+        // Dynamically import PostHog to avoid SSR issues
+        const { default: posthog } = await import("posthog-js");
+        const { token, instanceName: _instanceName, enabled: _enabled, debug: configDebug, ...posthogConfig } = this.config;
+        this.posthog = posthog.init(token, {
+            ...posthogConfig,
+            debug: configDebug ?? this.debug,
+        }, this.instanceName);
+        this.initialized = true;
+        this.log("Initialized successfully");
+    }
+    identify(userId, traits) {
+        if (!this.isEnabled() || !this.initialized || !this.posthog)
+            return;
+        this.posthog.identify(userId, traits);
+        this.log("Identified user");
+    }
+    track(event, context) {
+        if (!this.isEnabled() || !this.initialized || !this.posthog)
+            return;
+        // `$current_url` is left to posthog-js, which reads the live location on
+        // every capture. The page context is only refreshed by pageView, and a
+        // caller's property would override the SDK's full URL.
+        //
+        // The time stays a property: posthog-js sends any capture that has an
+        // options argument, such as `timestamp`, outside its batch queue.
+        const properties = {
+            ...event.properties,
+            category: event.category,
+            timestamp: event.timestamp || Date.now(),
+            ...(event.userId && { userId: event.userId }),
+            ...(event.sessionId && { sessionId: event.sessionId }),
+            ...(context?.device && { device: context.device }),
+            ...(context?.utm && { utm: context.utm }),
+            // Include user email and traits as regular event properties
+            ...(context?.user?.email && { user_email: context.user.email }),
+            ...(context?.user?.traits && { user_traits: context.user.traits }),
+        };
+        this.posthog.capture(event.action, properties);
+        this.log("Tracked event");
+    }
+    pageView(properties, context) {
+        if (!this.isEnabled() || !this.initialized || !this.posthog || !isBrowser())
+            return;
+        const pageProperties = {
+            ...properties,
+            ...(context?.page && {
+                path: context.page.path,
+                title: context.page.title,
+                referrer: context.page.referrer,
+            }),
+        };
+        this.posthog.capture("$pageview", pageProperties);
+        this.log("Tracked page view");
+    }
+    pageLeave(properties, context) {
+        if (!this.isEnabled() || !this.initialized || !this.posthog || !isBrowser())
+            return;
+        const pageLeaveProperties = {
+            ...properties,
+            ...(context?.page && {
+                path: context.page.path,
+                title: context.page.title,
+                referrer: context.page.referrer,
+            }),
+        };
+        this.posthog.capture("$pageleave", pageLeaveProperties);
+        this.log("Tracked page leave");
+    }
+    reset() {
+        if (!this.isEnabled() || !this.initialized || !this.posthog || !isBrowser())
+            return;
+        this.posthog.reset();
+        this.log("Reset user session");
+    }
+}

package/dist/environment.d.ts

@@ -0,0 +1 @@
+export declare function isBrowser(): boolean;

package/dist/environment.js

@@ -0,0 +1,3 @@
+export function isBrowser() {
+    return (typeof window !== "undefined" && typeof window.document !== "undefined");
+}

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+import type { PostHogOptions } from "posthog-node";
+export declare class PostHogServerProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private initialized;
+    private initializePromise?;
+    private config;
+    constructor(config: {
+        apiKey: string;
+    } & PostHogOptions & {
+        debug?: boolean;
+        enabled?: boolean;
+    });
+    initialize(): Promise<void>;
+    private initializePostHog;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): void;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
+    /**
+     * Adds what PostHog reads from its own fields and properties: the event
+     * time, the visitor's IP and user agent, and the page and campaign. Identity
+     * comes from this call alone, because one server provider serves many users.
+     */
+    private buildEventMessage;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export type { PostHogOptions } from "posthog-node";

package/dist/server.js

@@ -0,0 +1,196 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+const firstString = (...values) => {
+    for (const value of values) {
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return undefined;
+};
+/**
+ * The `device` context without its IP. The address travels as `$ip`, where
+ * PostHog's project setting to discard client IP data applies; a copy nested
+ * in `device` would escape that setting.
+ */
+const deviceWithoutIp = (device) => {
+    if (!device)
+        return undefined;
+    const { ip: _ip, ...rest } = device;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+};
+/**
+ * The context PostHog reads from its own standard properties: the page URL,
+ * and the campaign fields PostHog attributes traffic by.
+ */
+const standardProperties = (context) => {
+    const currentUrl = firstString(context?.page?.url, context?.page?.path);
+    const utm = context?.utm;
+    return {
+        ...(currentUrl && { $current_url: currentUrl }),
+        ...(utm?.source && { utm_source: utm.source }),
+        ...(utm?.medium && { utm_medium: utm.medium }),
+        ...(utm?.name && { utm_campaign: utm.name }),
+    };
+};
+const isMissingPackageError = (error, packageName) => {
+    try {
+        if (!error || typeof error !== "object")
+            return false;
+        const code = Reflect.get(error, "code");
+        const message = Reflect.get(error, "message");
+        if ((code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") ||
+            typeof message !== "string") {
+            return false;
+        }
+        return (message.includes(`Cannot find package '${packageName}'`) ||
+            message.includes(`Cannot find module '${packageName}'`));
+    }
+    catch {
+        return false;
+    }
+};
+export class PostHogServerProvider extends BaseAnalyticsProvider {
+    name = "PostHog-Server";
+    client;
+    initialized = false;
+    initializePromise;
+    config;
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+    }
+    initialize() {
+        if (!this.isEnabled() || this.initialized)
+            return Promise.resolve();
+        if (this.initializePromise)
+            return this.initializePromise;
+        this.initializePromise = this.initializePostHog().catch((error) => {
+            this.initializePromise = undefined;
+            console.error(`[PostHog-Server] Failed to initialize (${this.getErrorClass(error)})`);
+            throw error;
+        });
+        return this.initializePromise;
+    }
+    async initializePostHog() {
+        // Validate config has required fields
+        if (!this.config.apiKey || typeof this.config.apiKey !== "string") {
+            throw new Error("PostHog requires an apiKey");
+        }
+        let PostHogClient;
+        try {
+            ({ PostHog: PostHogClient } = await import("posthog-node"));
+        }
+        catch (error) {
+            if (isMissingPackageError(error, "posthog-node")) {
+                throw new Error("PostHog server provider requires the optional peer package posthog-node");
+            }
+            throw error;
+        }
+        // The host is left to the SDK, whose default is PostHog's US ingestion
+        // host rather than the legacy app.posthog.com.
+        const { apiKey, ...posthogOptions } = this.config;
+        this.client = new PostHogClient(apiKey, {
+            flushAt: 20,
+            flushInterval: 10000,
+            ...posthogOptions,
+        });
+        this.initialized = true;
+        this.log("Initialized successfully");
+    }
+    identify(userId, traits) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        this.client.identify({
+            distinctId: userId,
+            properties: traits,
+        });
+        this.log("Identified user");
+    }
+    track(event, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        const device = deviceWithoutIp(context?.device);
+        const properties = {
+            ...event.properties,
+            category: event.category,
+            ...(event.sessionId && { sessionId: event.sessionId }),
+            ...(context?.page && {
+                $page_title: context.page.title,
+                $referrer: context.page.referrer,
+            }),
+            ...(device && { device }),
+            ...(context?.utm && { utm: context.utm }),
+            // Include user email and traits as regular event properties
+            ...(context?.user?.email && { user_email: context.user.email }),
+            ...(context?.user?.traits && { user_traits: context.user.traits }),
+        };
+        this.client.capture(this.buildEventMessage({
+            event: event.action,
+            distinctId: event.userId || context?.user?.userId,
+            properties,
+            context,
+            timestamp: event.timestamp,
+        }));
+        this.log("Tracked event");
+    }
+    pageView(properties, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        const pageProperties = {
+            ...properties,
+            ...(context?.page && {
+                path: context.page.path,
+                title: context.page.title,
+                referrer: context.page.referrer,
+            }),
+        };
+        this.client.capture(this.buildEventMessage({
+            event: "$pageview",
+            distinctId: context?.user?.userId || context?.user?.email,
+            properties: pageProperties,
+            context,
+        }));
+        this.log("Tracked page view");
+    }
+    /**
+     * Adds what PostHog reads from its own fields and properties: the event
+     * time, the visitor's IP and user agent, and the page and campaign. Identity
+     * comes from this call alone, because one server provider serves many users.
+     */
+    buildEventMessage({ event, distinctId, properties, context, timestamp, }) {
+        const ip = firstString(context?.server?.ip, context?.device?.ip);
+        const userAgent = firstString(context?.server?.userAgent, context?.device?.userAgent);
+        return {
+            // An event without a user gets a distinct ID of its own and no person
+            // profile, as PostHog recommends. A shared placeholder ID would merge
+            // every anonymous visitor into one person.
+            distinctId: distinctId || crypto.randomUUID(),
+            event,
+            properties: {
+                ...properties,
+                ...standardProperties(context),
+                ...(ip && { $ip: ip }),
+                ...(userAgent && { $raw_user_agent: userAgent }),
+                ...(!distinctId && { $process_person_profile: false }),
+            },
+            ...(timestamp !== undefined && { timestamp: new Date(timestamp) }),
+            // posthog-node disables GeoIP by default because it would locate the
+            // server. A forwarded visitor IP is the one to locate, unless the app
+            // configured `disableGeoip` itself.
+            ...(ip &&
+                this.config.disableGeoip === undefined && { disableGeoip: false }),
+        };
+    }
+    async reset() {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Flush any pending events
+        await this.client.flush();
+        this.log("Flushed pending events");
+    }
+    async shutdown() {
+        if (this.client) {
+            await this.client.shutdown();
+            this.log("Shutdown complete");
+        }
+    }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@trakoo/posthog",
+  "version": "0.0.0",
+  "description": "PostHog provider for trakoo",
+  "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "analytics",
+    "trakoo",
+    "posthog",
+    "typescript"
+  ],
+  "author": "Chris Jayden <https://github.com/multiplehats>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multiplehats/trakoo.git",
+    "directory": "packages/posthog"
+  },
+  "bugs": {
+    "url": "https://github.com/multiplehats/trakoo/issues"
+  },
+  "homepage": "https://trakoo.co/docs/providers/posthog",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "posthog-js": "^1.268.2",
+    "posthog-node": "^5.9.0",
+    "trakoo": "^1.2.1"
+  },
+  "peerDependenciesMeta": {
+    "posthog-js": {
+      "optional": true
+    },
+    "posthog-node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "posthog-js": "^1.434.12",
+    "posthog-node": "^5.53.0",
+    "trakoo": "1.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}