autotel-posthog 0.1.0

package/dist/subscriber.js

@@ -0,0 +1,519 @@
+import { EventSubscriber } from "autotel-subscribers";
+import slowRedact from "slow-redact";
+//#region src/subscriber/error-formatter.ts
+const MAX_CAUSE_DEPTH = 5;
+function formatExceptionForPostHog(exceptionList, platform = "web:javascript", redactor) {
+	return { $exception_list: exceptionList.map((ex) => ({
+		type: ex.type,
+		value: redactor ? redactor(ex.value) : ex.value,
+		mechanism: ex.mechanism,
+		stacktrace: { frames: (ex.stacktrace?.frames || []).map((frame) => ({
+			...frame,
+			abs_path: frame.abs_path && redactor ? redactor(frame.abs_path) : frame.abs_path,
+			platform
+		})) }
+	})) };
+}
+function errorToExceptionList(input, redactor) {
+	const error = input instanceof Error ? input : new Error(input === null || input === void 0 ? "Unknown error" : String(input));
+	const records = [];
+	let current = error;
+	let depth = 0;
+	while (current && depth < MAX_CAUSE_DEPTH) {
+		const value = current.message || "Unknown error";
+		const frames = current.stack ? parseStackBasic(current.stack) : void 0;
+		records.push({
+			type: current.name || "Error",
+			value: redactor ? redactor(value) : value,
+			mechanism: {
+				type: "manual",
+				handled: true
+			},
+			stacktrace: frames ? { frames: redactor ? frames.map((f) => ({
+				...f,
+				abs_path: f.abs_path ? redactor(f.abs_path) : f.abs_path
+			})) : frames } : void 0
+		});
+		current = current.cause instanceof Error ? current.cause : void 0;
+		depth++;
+	}
+	return records.toReversed();
+}
+function parseStackBasic(stack) {
+	const lines = stack.split("\n");
+	const frames = [];
+	const re = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
+	for (const line of lines) {
+		const match = line.trim().match(re);
+		if (match) {
+			const [, fn, absPath, lineStr, colStr] = match;
+			if (!absPath) continue;
+			frames.push({
+				function: fn || void 0,
+				abs_path: absPath,
+				filename: absPath.split("/").pop() || absPath,
+				lineno: Number.parseInt(lineStr ?? "0", 10),
+				colno: Number.parseInt(colStr ?? "0", 10),
+				in_app: !absPath.includes("node_modules")
+			});
+		}
+	}
+	return frames;
+}
+//#endregion
+//#region src/values.ts
+/** The value as an object, or undefined when it is anything else. */
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** The string the value carries, or undefined when it carries anything else. */
+function asString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+/** One field of a value, when the value is an object at all. */
+function readProperty(source, key) {
+	return asRecord(source)?.[key];
+}
+/**
+* The Error a caller's callback expects, wrapping whatever was actually
+* thrown - a string, a number, an object with no stack.
+*/
+function toError(cause) {
+	return cause instanceof Error ? cause : new Error(String(cause));
+}
+//#endregion
+//#region src/subscriber/index.ts
+var PostHogSubscriber = class extends EventSubscriber {
+	name = "PostHogSubscriber";
+	version = "2.0.0";
+	posthog = null;
+	config;
+	initPromise = null;
+	/** True when using browser's window.posthog (different API signature) */
+	isBrowserClient = false;
+	/**
+	* The same client seen through the browser SDK's shape.
+	*
+	* The two SDKs disagree about `capture`: Node takes one object, the browser
+	* takes a name and properties. Rather than cast at each call site, the cast
+	* happens once here and the calls are typed against `posthog-js` itself — so
+	* a change to the browser signature is a compile error rather than a runtime
+	* one in a page.
+	*/
+	get browserClient() {
+		return this.isBrowserClient && this.posthog ? this.posthog : void 0;
+	}
+	pathRedactor = null;
+	stringRedactor = null;
+	constructor(config) {
+		super();
+		if (config.serverless) config = {
+			flushAt: 1,
+			flushInterval: 0,
+			requestTimeout: 3e3,
+			...config
+		};
+		if (!config.apiKey && !config.client && !config.useGlobalClient) throw new Error("PostHogSubscriber requires either apiKey, client, or useGlobalClient to be provided");
+		this.enabled = config.enabled ?? true;
+		this.config = {
+			filterUndefinedValues: true,
+			...config
+		};
+		if (this.config.redactPaths && this.config.redactPaths.length > 0) this.pathRedactor = slowRedact({
+			paths: this.config.redactPaths,
+			serialize: false
+		});
+		if (this.config.stringRedactor) this.stringRedactor = this.config.stringRedactor;
+		if (this.enabled) this.initPromise = this.initialize();
+	}
+	async initialize() {
+		try {
+			if (this.config.useGlobalClient) {
+				const globalPostHog = readProperty(globalThis, "posthog");
+				if (globalPostHog) {
+					this.posthog = globalPostHog;
+					this.isBrowserClient = true;
+					this.setupErrorHandling();
+					return;
+				}
+				throw new Error("useGlobalClient enabled but window.posthog not found. Ensure PostHog script is loaded before initializing the subscriber.");
+			}
+			if (this.config.client) {
+				this.posthog = this.config.client;
+				this.setupErrorHandling();
+				return;
+			}
+			const { PostHog } = await import("posthog-node");
+			this.posthog = new PostHog(this.config.apiKey, {
+				host: this.config.host || "https://us.i.posthog.com",
+				flushAt: this.config.flushAt,
+				flushInterval: this.config.flushInterval,
+				requestTimeout: this.config.requestTimeout,
+				disableGeoip: this.config.disableGeoip,
+				sendFeatureFlagEvent: this.config.sendFeatureFlags
+			});
+			this.setupErrorHandling();
+		} catch (error) {
+			console.error("PostHog subscriber failed to initialize. Install posthog-node: pnpm add posthog-node", error);
+			this.enabled = false;
+			this.config.onError?.(toError(error));
+		}
+	}
+	setupErrorHandling() {
+		if (this.config.debug) this.posthog?.debug();
+		if (this.config.onError && this.posthog?.on) this.posthog.on("error", this.config.onError);
+	}
+	async ensureInitialized() {
+		if (this.initPromise) {
+			await this.initPromise;
+			this.initPromise = null;
+		}
+	}
+	/**
+	* Feature-flag options as posthog-node's own parameter type.
+	*
+	* SAFETY: FeatureFlagOptions above mirrors the fields posthog-node accepts -
+	* groups, person and group properties, and the two evaluation switches. The
+	* SDK declares them inline on each method rather than as a named type, so
+	* the correspondence is stated here once instead of at each call.
+	*/
+	flagOptions(options) {
+		return options;
+	}
+	extractDistinctId(attributes) {
+		return asString(attributes?.userId) ?? asString(attributes?.user_id) ?? "anonymous";
+	}
+	redactProperties(properties) {
+		let result = properties;
+		if (this.pathRedactor) result = this.pathRedactor(properties);
+		if (this.stringRedactor) result = this.redactStringValues(result);
+		return result;
+	}
+	redactStringValues(obj) {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) result[key] = this.redactValue(value);
+		return result;
+	}
+	redactArray(arr) {
+		return arr.map((item) => this.redactValue(item));
+	}
+	/** One value, redacted: a string masked, a container walked. */
+	redactValue(value) {
+		const text = asString(value);
+		if (text !== void 0) return this.stringRedactor(text);
+		if (Array.isArray(value)) return this.redactArray(value);
+		const nested = asRecord(value);
+		return nested ? this.redactStringValues(nested) : value;
+	}
+	/**
+	* Set the string redactor. Called by autotel init() when attributeRedactor is configured.
+	* Can also be called manually.
+	*/
+	setStringRedactor(redactor) {
+		this.stringRedactor = redactor;
+	}
+	/**
+	* Send payload to PostHog
+	*
+	* Maps autotel context to PostHog-specific field names:
+	* - autotel.trace_id → $trace_id
+	* - autotel.span_id → $span_id
+	* - autotel.correlation_id → $correlation_id
+	* - autotel.trace_url → $trace_url
+	*/
+	async sendToDestination(payload) {
+		await this.ensureInitialized();
+		const filteredAttributes = this.config.filterUndefinedValues === false ? payload.attributes : this.filterAttributes(payload.attributes);
+		const properties = { ...filteredAttributes };
+		if (payload.value !== void 0) properties.value = payload.value;
+		if (payload.stepNumber !== void 0) properties.step_number = payload.stepNumber;
+		if (payload.stepName !== void 0) properties.step_name = payload.stepName;
+		if (payload.autotel) {
+			if (payload.autotel.trace_id) properties.$trace_id = payload.autotel.trace_id;
+			if (payload.autotel.span_id) properties.$span_id = payload.autotel.span_id;
+			if (payload.autotel.correlation_id) properties.$correlation_id = payload.autotel.correlation_id;
+			if (payload.autotel.trace_flags) properties.$trace_flags = payload.autotel.trace_flags;
+			if (payload.autotel.trace_state) properties.$trace_state = payload.autotel.trace_state;
+			if (payload.autotel.trace_url) properties.$trace_url = payload.autotel.trace_url;
+			if (payload.autotel.linked_trace_id_count !== void 0) properties.$linked_trace_id_count = payload.autotel.linked_trace_id_count;
+			if (payload.autotel.linked_trace_id_hash) properties.$linked_trace_id_hash = payload.autotel.linked_trace_id_hash;
+			if (payload.autotel.linked_trace_ids) properties.$linked_trace_ids = payload.autotel.linked_trace_ids;
+		}
+		const redactedProperties = this.redactProperties(properties);
+		if (payload.attributes?.["exception.list"]) try {
+			const formatted = formatExceptionForPostHog(JSON.parse(asString(payload.attributes["exception.list"]) ?? "[]"), void 0, this.stringRedactor ?? void 0);
+			const exceptionProperties = {
+				...redactedProperties,
+				...formatted
+			};
+			if (this.isBrowserClient) this.browserClient?.capture("$exception", exceptionProperties);
+			else this.posthog?.capture({
+				distinctId: this.extractDistinctId(filteredAttributes),
+				event: "$exception",
+				properties: exceptionProperties
+			});
+		} catch {}
+		const distinctId = this.extractDistinctId(filteredAttributes);
+		if (this.isBrowserClient) this.browserClient?.capture(payload.name, redactedProperties);
+		else {
+			const capturePayload = {
+				distinctId,
+				event: payload.name,
+				properties: redactedProperties
+			};
+			if (filteredAttributes?.groups) capturePayload.groups = filteredAttributes.groups;
+			this.posthog?.capture(capturePayload);
+		}
+	}
+	/**
+	* Check if a feature flag is enabled for a user
+	*
+	* @param flagKey - Feature flag key
+	* @param distinctId - User ID or anonymous ID
+	* @param options - Feature flag evaluation options
+	* @returns true if enabled, false otherwise
+	*
+	* @example
+	* ```typescript
+	* const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+	*
+	* // With groups
+	* const isEnabled = await subscriber.isFeatureEnabled('beta-features', 'user-123', {
+	*   groups: { company: 'acme-corp' }
+	* });
+	* ```
+	*/
+	async isFeatureEnabled(flagKey, distinctId, options) {
+		if (!this.enabled) return false;
+		await this.ensureInitialized();
+		try {
+			return await this.posthog?.isFeatureEnabled(flagKey, distinctId, this.flagOptions(options)) ?? false;
+		} catch (error) {
+			this.config.onError?.(toError(error));
+			return false;
+		}
+	}
+	/**
+	* Get feature flag value for a user
+	*
+	* @param flagKey - Feature flag key
+	* @param distinctId - User ID or anonymous ID
+	* @param options - Feature flag evaluation options
+	* @returns Flag value (string, boolean, or undefined)
+	*
+	* @example
+	* ```typescript
+	* const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+	* // Returns: 'control' | 'test' | 'test-2' | undefined
+	*
+	* // With person properties
+	* const variant = await subscriber.getFeatureFlag('premium-feature', 'user-123', {
+	*   personProperties: { plan: 'premium' }
+	* });
+	* ```
+	*/
+	async getFeatureFlag(flagKey, distinctId, options) {
+		if (!this.enabled) return void 0;
+		await this.ensureInitialized();
+		try {
+			return await this.posthog?.getFeatureFlag(flagKey, distinctId, this.flagOptions(options));
+		} catch (error) {
+			this.config.onError?.(toError(error));
+			return;
+		}
+	}
+	/**
+	* Get all feature flags for a user
+	*
+	* @param distinctId - User ID or anonymous ID
+	* @param options - Feature flag evaluation options
+	* @returns Object mapping flag keys to their values
+	*
+	* @example
+	* ```typescript
+	* const flags = await subscriber.getAllFlags('user-123');
+	* // Returns: { 'new-checkout': true, 'experiment-variant': 'test', ... }
+	* ```
+	*/
+	async getAllFlags(distinctId, options) {
+		if (!this.enabled) return {};
+		await this.ensureInitialized();
+		try {
+			return await this.posthog?.getAllFlags(distinctId, this.flagOptions(options)) ?? {};
+		} catch (error) {
+			this.config.onError?.(toError(error));
+			return {};
+		}
+	}
+	/**
+	* Reload feature flags from PostHog server
+	*
+	* Call this to refresh feature flag definitions without restarting.
+	*
+	* @example
+	* ```typescript
+	* await subscriber.reloadFeatureFlags();
+	* ```
+	*/
+	async reloadFeatureFlags() {
+		if (!this.enabled) return;
+		await this.ensureInitialized();
+		try {
+			await this.posthog?.reloadFeatureFlags();
+		} catch (error) {
+			this.config.onError?.(toError(error));
+		}
+	}
+	/**
+	* Identify a user and set their properties
+	*
+	* @param distinctId - User ID
+	* @param properties - Person properties ($set, $set_once, or custom properties)
+	*
+	* @example
+	* ```typescript
+	* // Set properties (will update existing values)
+	* await subscriber.identify('user-123', {
+	*   $set: {
+	*     email: 'user@example.com',
+	*     plan: 'premium'
+	*   }
+	* });
+	*
+	* // Set properties only once (won't update if already exists)
+	* await subscriber.identify('user-123', {
+	*   $set_once: {
+	*     signup_date: '2025-01-17'
+	*   }
+	* });
+	* ```
+	*/
+	async identify(distinctId, properties) {
+		if (!this.enabled) return;
+		await this.ensureInitialized();
+		try {
+			this.posthog?.identify({
+				distinctId,
+				properties
+			});
+		} catch (error) {
+			this.config.onError?.(toError(error));
+		}
+	}
+	/**
+	* Identify a group and set its properties
+	*
+	* Groups are useful for B2B SaaS to track organizations, teams, or accounts.
+	*
+	* @param groupType - Type of group (e.g., 'company', 'organization', 'team')
+	* @param groupKey - Unique identifier for the group
+	* @param properties - Group properties
+	*
+	* @example
+	* ```typescript
+	* await subscriber.groupIdentify('company', 'acme-corp', {
+	*   $set: {
+	*     name: 'Acme Corporation',
+	*     industry: 'saas',
+	*     employees: 500,
+	*     plan: 'enterprise'
+	*   }
+	* });
+	* ```
+	*/
+	async groupIdentify(groupType, groupKey, properties) {
+		if (!this.enabled) return;
+		await this.ensureInitialized();
+		try {
+			this.posthog?.groupIdentify({
+				groupType,
+				groupKey: String(groupKey),
+				properties
+			});
+		} catch (error) {
+			this.config.onError?.(toError(error));
+		}
+	}
+	/**
+	* Track an event with group context
+	*
+	* Use this to associate events with groups (e.g., organizations).
+	*
+	* @param name - Event name
+	* @param attributes - Event attributes
+	* @param groups - Group context (e.g., { company: 'acme-corp' })
+	*
+	* @example
+	* ```typescript
+	* await subscriber.trackEventWithGroups('feature.used', {
+	*   userId: 'user-123',
+	*   feature: 'advanced-events'
+	* }, {
+	*   company: 'acme-corp'
+	* });
+	* ```
+	*/
+	async trackEventWithGroups(name, attributes, groups) {
+		if (!this.enabled) return;
+		await this.ensureInitialized();
+		const eventAttributes = { ...attributes };
+		if (groups) eventAttributes.groups = groups;
+		await this.trackEvent(name, eventAttributes);
+	}
+	/**
+	* Capture an exception and send to PostHog error tracking.
+	*
+	* If using browser client (window.posthog), delegates to its captureException.
+	* Otherwise, formats and sends via posthog-node capture API.
+	*/
+	async captureException(error, options) {
+		if (!this.enabled) return;
+		await this.ensureInitialized();
+		try {
+			if (this.isBrowserClient) {
+				const browserProps = options?.additionalProperties ? this.redactProperties(options.additionalProperties) : void 0;
+				this.browserClient?.captureException?.(error, browserProps);
+				return;
+			}
+			const properties = {
+				...formatExceptionForPostHog(errorToExceptionList(error, this.stringRedactor ?? void 0), "node:javascript", this.stringRedactor ?? void 0),
+				...options?.additionalProperties
+			};
+			this.posthog?.capture({
+				distinctId: options?.distinctId || "anonymous",
+				event: "$exception",
+				properties: this.redactProperties(properties)
+			});
+		} catch (error_) {
+			this.config.onError?.(toError(error_));
+		}
+	}
+	/**
+	* Flush pending events and clean up resources
+	*/
+	async shutdown() {
+		await super.shutdown();
+		await this.ensureInitialized();
+		if (this.posthog) try {
+			await this.posthog.shutdown();
+		} catch (error) {
+			this.config.onError?.(toError(error));
+		}
+	}
+	/**
+	* Handle errors with custom error handler
+	*/
+	handleError(error, payload) {
+		this.config.onError?.(error);
+		if (this.config.onErrorWithContext) this.config.onErrorWithContext({
+			error,
+			eventName: payload.name,
+			eventType: payload.type,
+			attributes: payload.attributes,
+			subscriberName: this.name
+		});
+		super.handleError(error, payload);
+	}
+};
+//#endregion
+export { PostHogSubscriber };

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "autotel-posthog",
+  "version": "0.1.0",
+  "description": "Everything PostHog for autotel: browser session/replay join, server-side event subscriber, and trace links in both directions",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./subscriber": {
+      "types": "./dist/subscriber.d.ts",
+      "import": "./dist/subscriber.js",
+      "require": "./dist/subscriber.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "slow-redact": "^0.3.2"
+  },
+  "peerDependencies": {
+    "@opentelemetry/sdk-trace-base": ">=2.0.0",
+    "posthog-js": ">=1.200.0",
+    "posthog-node": ">=4.0.0",
+    "autotel": "6.5.0",
+    "autotel-subscribers": "49.0.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@types/node": "^26.1.2",
+    "posthog-js": "1.417.1",
+    "posthog-node": "^4.18.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "autotel": "6.5.0",
+    "autotel-subscribers": "49.0.0"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "posthog",
+    "session-replay",
+    "product-analytics",
+    "tracing",
+    "observability",
+    "autotel"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-posthog"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "posthog-js": {
+      "optional": true
+    },
+    "autotel": {
+      "optional": true
+    },
+    "autotel-subscribers": {
+      "optional": true
+    },
+    "posthog-node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  }
+}