@codaco/analytics 8.0.0 → 9.0.0

package/src/__tests__/index.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from "vitest";
+import { defaultConfig, isDisabledByEnv, mergeConfig } from "../config";
+import { ErrorPropertiesSchema, EventPropertiesSchema, type EventType, eventTypes, legacyEventTypeMap } from "../types";
+
+describe("Event Types", () => {
+	it("should export all event types", () => {
+		expect(eventTypes).toEqual([
+			"app_setup",
+			"protocol_installed",
+			"interview_started",
+			"interview_completed",
+			"data_exported",
+			"error",
+		]);
+	});
+
+	it("should map legacy event types to new snake_case types", () => {
+		expect(legacyEventTypeMap.AppSetup).toBe("app_setup");
+		expect(legacyEventTypeMap.ProtocolInstalled).toBe("protocol_installed");
+		expect(legacyEventTypeMap.InterviewStarted).toBe("interview_started");
+		expect(legacyEventTypeMap.InterviewCompleted).toBe("interview_completed");
+		expect(legacyEventTypeMap.DataExported).toBe("data_exported");
+		expect(legacyEventTypeMap.Error).toBe("error");
+	});
+});
+
+describe("Event Schemas", () => {
+	describe("EventPropertiesSchema", () => {
+		it("should validate event properties with metadata", () => {
+			const properties = {
+				metadata: {
+					version: "1.0.0",
+					userId: "123",
+				},
+			};
+
+			const result = EventPropertiesSchema.safeParse(properties);
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate event properties without metadata", () => {
+			const properties = {};
+			const result = EventPropertiesSchema.safeParse(properties);
+			expect(result.success).toBe(true);
+		});
+
+		it("should allow arbitrary metadata keys and values", () => {
+			const properties = {
+				metadata: {
+					string: "value",
+					number: 42,
+					boolean: true,
+					nested: { key: "value" },
+					array: [1, 2, 3],
+				},
+			};
+
+			const result = EventPropertiesSchema.safeParse(properties);
+			expect(result.success).toBe(true);
+		});
+	});
+
+	describe("ErrorPropertiesSchema", () => {
+		it("should validate error properties with all fields", () => {
+			const errorProps = {
+				message: "Something went wrong",
+				name: "TestError",
+				stack: "Error: Something went wrong\n    at test.ts:10",
+				cause: "Root cause",
+				metadata: {
+					context: "test",
+				},
+			};
+
+			const result = ErrorPropertiesSchema.safeParse(errorProps);
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate error properties with required fields only", () => {
+			const errorProps = {
+				message: "Error message",
+				name: "Error",
+			};
+
+			const result = ErrorPropertiesSchema.safeParse(errorProps);
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject error properties missing message", () => {
+			const errorProps = {
+				name: "Error",
+			};
+
+			const result = ErrorPropertiesSchema.safeParse(errorProps);
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject error properties missing name", () => {
+			const errorProps = {
+				message: "Error message",
+			};
+
+			const result = ErrorPropertiesSchema.safeParse(errorProps);
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+describe("Configuration", () => {
+	describe("defaultConfig", () => {
+		it("should have correct default values", () => {
+			expect(defaultConfig.apiHost).toBe("https://ph-relay.networkcanvas.com");
+			expect(defaultConfig.posthogOptions?.disable_session_recording).toBe(true);
+			expect(defaultConfig.posthogOptions?.autocapture).toBe(false);
+			expect(defaultConfig.posthogOptions?.capture_pageview).toBe(false);
+			expect(defaultConfig.posthogOptions?.advanced_disable_feature_flags).toBe(false);
+		});
+	});
+
+	describe("mergeConfig", () => {
+		it("should merge user config with defaults", () => {
+			const userConfig = {
+				installationId: "test-123",
+				apiKey: "phc_test",
+			};
+
+			const merged = mergeConfig(userConfig);
+
+			expect(merged.installationId).toBe("test-123");
+			expect(merged.apiKey).toBe("phc_test");
+			expect(merged.apiHost).toBe("https://ph-relay.networkcanvas.com");
+			expect(merged.disabled).toBe(false);
+		});
+
+		it("should allow overriding default values", () => {
+			const userConfig = {
+				installationId: "test-123",
+				apiKey: "phc_test",
+				apiHost: "https://custom.posthog.com",
+				disabled: true,
+				debug: true,
+			};
+
+			const merged = mergeConfig(userConfig);
+
+			expect(merged.apiHost).toBe("https://custom.posthog.com");
+			expect(merged.disabled).toBe(true);
+			expect(merged.debug).toBe(true);
+		});
+
+		it("should use placeholder API key when none provided (proxy mode)", () => {
+			const userConfig = {
+				installationId: "test-123",
+			};
+
+			const merged = mergeConfig(userConfig);
+
+			// When using proxy mode, a placeholder key is automatically provided
+			expect(merged.apiKey).toBe("phc_proxy_mode_placeholder");
+			expect(merged.installationId).toBe("test-123");
+		});
+
+		it("should merge PostHog options", () => {
+			const userConfig = {
+				installationId: "test-123",
+				apiKey: "phc_test",
+				posthogOptions: {
+					autocapture: true,
+					capture_pageview: true,
+				},
+			};
+
+			const merged = mergeConfig(userConfig);
+
+			expect(merged.posthogOptions.autocapture).toBe(true);
+			expect(merged.posthogOptions.capture_pageview).toBe(true);
+			// Should still have default values for other options
+			expect(merged.posthogOptions.disable_session_recording).toBe(true);
+		});
+	});
+});
+
+describe("Environment Variables", () => {
+	describe("isDisabledByEnv", () => {
+		it("should return a boolean value", () => {
+			// This test depends on the actual env vars
+			// In a real test, you would mock process.env
+			const result = isDisabledByEnv();
+			expect(typeof result).toBe("boolean");
+		});
+	});
+});
+
+describe("Type Exports", () => {
+	it("should export EventType correctly", () => {
+		const validTypes: EventType[] = [
+			"app_setup",
+			"protocol_installed",
+			"interview_started",
+			"interview_completed",
+			"data_exported",
+			"error",
+		];
+
+		expect(validTypes).toEqual(eventTypes);
+	});
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import { ensureError } from "../utils";
+
+describe("ensureError", () => {
+	it("should return the error if value is already an Error instance", () => {
+		const error = new Error("Test error");
+		const result = ensureError(error);
+		expect(result).toBe(error);
+		expect(result.message).toBe("Test error");
+	});
+
+	it("should return a default error when no value is thrown", () => {
+		const result = ensureError(null);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toBe("No value was thrown");
+	});
+
+	it("should return a default error when undefined is thrown", () => {
+		const result = ensureError(undefined);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toBe("No value was thrown");
+	});
+
+	it("should wrap a string in an Error", () => {
+		const result = ensureError("Something went wrong");
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toContain("This value was thrown as is, not through an Error");
+		expect(result.message).toContain('"Something went wrong"');
+	});
+
+	it("should wrap a number in an Error", () => {
+		const result = ensureError(42);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toContain("This value was thrown as is, not through an Error");
+		expect(result.message).toContain("42");
+	});
+
+	it("should wrap an object in an Error with stringified value", () => {
+		const obj = { code: "ERR_001", details: "Something failed" };
+		const result = ensureError(obj);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toContain("This value was thrown as is, not through an Error");
+		expect(result.message).toContain(JSON.stringify(obj));
+	});
+
+	it("should wrap an array in an Error with stringified value", () => {
+		const arr = ["error1", "error2"];
+		const result = ensureError(arr);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toContain("This value was thrown as is, not through an Error");
+		expect(result.message).toContain(JSON.stringify(arr));
+	});
+
+	it("should handle circular references gracefully", () => {
+		const circular: { prop?: unknown } = {};
+		circular.prop = circular;
+
+		// Mock console.error to avoid test output pollution
+		const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+		const result = ensureError(circular);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toBe(
+			"This value was thrown as is, not through an Error: [Unable to stringify the thrown value]",
+		);
+		expect(consoleErrorSpy).toHaveBeenCalled();
+
+		consoleErrorSpy.mockRestore();
+	});
+
+	it("should handle custom error classes that inherit from Error", () => {
+		class CustomError extends Error {
+			code: string;
+			constructor(message: string, code: string) {
+				super(message);
+				this.code = code;
+				this.name = "CustomError";
+			}
+		}
+
+		const customError = new CustomError("Custom error message", "CUSTOM_001");
+		const result = ensureError(customError);
+		expect(result).toBe(customError);
+		expect(result.message).toBe("Custom error message");
+	});
+
+	it("should handle boolean values", () => {
+		const result = ensureError(true);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toContain("This value was thrown as is, not through an Error");
+		expect(result.message).toContain("true");
+	});
+
+	it("should handle empty string", () => {
+		const result = ensureError("");
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toBe("No value was thrown");
+	});
+
+	it("should handle zero as a value", () => {
+		const result = ensureError(0);
+		expect(result).toBeInstanceOf(Error);
+		expect(result.message).toBe("No value was thrown");
+	});
+});

package/src/client.ts

@@ -0,0 +1,151 @@
+import posthog from "posthog-js";
+import type { Analytics, AnalyticsConfig, ErrorProperties, EventProperties, EventType } from "./types";
+import { ensureError } from "./utils";
+
+/**
+ * Create a client-side analytics instance
+ * This wraps PostHog with Network Canvas-specific functionality
+ */
+export function createAnalytics(config: Required<AnalyticsConfig>): Analytics {
+	const { apiHost, apiKey, installationId, disabled, debug, posthogOptions } = config;
+
+	// If analytics is disabled, return a no-op implementation
+	if (disabled) {
+		return createNoOpAnalytics(installationId);
+	}
+
+	// Initialize PostHog
+	posthog.init(apiKey, {
+		api_host: apiHost,
+		loaded: (posthogInstance) => {
+			// Set installation ID as a super property (included with every event)
+			posthogInstance.register({
+				installation_id: installationId,
+			});
+
+			if (debug) {
+				posthogInstance.debug();
+			}
+		},
+		...posthogOptions,
+	});
+
+	return {
+		trackEvent: (eventType: EventType | string, properties?: EventProperties) => {
+			if (disabled) return;
+
+			try {
+				posthog.capture(eventType, {
+					...properties,
+					// Flatten metadata into properties for better PostHog integration
+					...(properties?.metadata ?? {}),
+				});
+			} catch (_e) {
+				if (debug) {
+				}
+			}
+		},
+
+		trackError: (error: Error, additionalProperties?: EventProperties) => {
+			if (disabled) return;
+
+			try {
+				const errorObj = ensureError(error);
+				const errorProperties: ErrorProperties = {
+					message: errorObj.message,
+					name: errorObj.name,
+					stack: errorObj.stack,
+					cause: errorObj.cause ? String(errorObj.cause) : undefined,
+					...additionalProperties,
+				};
+
+				posthog.capture("error", {
+					...errorProperties,
+					// Flatten metadata
+					...(additionalProperties?.metadata ?? {}),
+				});
+			} catch (_e) {
+				if (debug) {
+				}
+			}
+		},
+
+		isFeatureEnabled: (flagKey: string) => {
+			if (disabled) return false;
+
+			try {
+				return posthog.isFeatureEnabled(flagKey);
+			} catch (_e) {
+				if (debug) {
+				}
+				return undefined;
+			}
+		},
+
+		getFeatureFlag: (flagKey: string) => {
+			if (disabled) return undefined;
+
+			try {
+				return posthog.getFeatureFlag(flagKey);
+			} catch (_e) {
+				if (debug) {
+				}
+				return undefined;
+			}
+		},
+
+		reloadFeatureFlags: () => {
+			if (disabled) return;
+
+			try {
+				posthog.reloadFeatureFlags();
+			} catch (_e) {
+				if (debug) {
+				}
+			}
+		},
+
+		identify: (distinctId: string, properties?: Record<string, unknown>) => {
+			if (disabled) return;
+
+			try {
+				posthog.identify(distinctId, properties);
+			} catch (_e) {
+				if (debug) {
+				}
+			}
+		},
+
+		reset: () => {
+			if (disabled) return;
+
+			try {
+				posthog.reset();
+			} catch (_e) {
+				if (debug) {
+				}
+			}
+		},
+
+		isEnabled: () => !disabled,
+
+		getInstallationId: () => installationId,
+	};
+}
+
+/**
+ * Create a no-op analytics instance when analytics is disabled
+ */
+function createNoOpAnalytics(installationId: string): Analytics {
+	return {
+		trackEvent: () => {},
+		trackError: () => {},
+		isFeatureEnabled: () => false,
+		getFeatureFlag: () => undefined,
+		reloadFeatureFlags: () => {},
+		identify: () => {},
+		reset: () => {},
+		isEnabled: () => false,
+		getInstallationId: () => installationId,
+	};
+}

package/src/config.ts

@@ -0,0 +1,92 @@
+import type { AnalyticsConfig } from "./types";
+
+/**
+ * Hardcoded PostHog API host - always uses the Cloudflare Worker reverse proxy
+ * Authentication is handled by the worker at this endpoint
+ */
+const POSTHOG_PROXY_HOST = "https://ph-relay.networkcanvas.com";
+
+/**
+ * Dummy API key used for proxy mode
+ * PostHog JS library requires an API key for initialization, but when using
+ * the reverse proxy, authentication is handled by the Cloudflare Worker.
+ * This placeholder key is used for client-side initialization only.
+ */
+const PROXY_MODE_DUMMY_KEY = "phc_proxy_mode_placeholder";
+
+/**
+ * Check if analytics is disabled via environment variables
+ */
+export function isDisabledByEnv(): boolean {
+	if (typeof process === "undefined") {
+		return false;
+	}
+
+	return process.env.DISABLE_ANALYTICS === "true" || process.env.NEXT_PUBLIC_DISABLE_ANALYTICS === "true";
+}
+
+/**
+ * Default configuration for analytics
+ * API host and key are hardcoded, but disabled flag can be set via environment variables
+ */
+export const defaultConfig: Partial<AnalyticsConfig> = {
+	// Always use the Cloudflare Worker reverse proxy
+	apiHost: POSTHOG_PROXY_HOST,
+
+	// Analytics enabled by default (can be disabled via env var or config option)
+	disabled: false,
+
+	// Debug mode disabled by default
+	debug: false,
+
+	// Default PostHog options
+	posthogOptions: {
+		// Disable session recording by default (can be enabled per-app)
+		disable_session_recording: true,
+
+		// Disable autocapture to keep events clean and intentional
+		autocapture: false,
+
+		// Disable automatic pageview capture (apps can enable if needed)
+		capture_pageview: false,
+
+		// Disable pageleave events
+		capture_pageleave: false,
+
+		// Don't use cross-subdomain cookies
+		cross_subdomain_cookie: false,
+
+		// Enable feature flags by default
+		advanced_disable_feature_flags: false,
+
+		// Send feature flag events
+		advanced_disable_feature_flags_on_first_load: false,
+
+		// Enable persistence for feature flags
+		persistence: "localStorage+cookie",
+	},
+};
+
+/**
+ * Merge user config with defaults
+ *
+ * Note: This package is designed to work exclusively with the Cloudflare Worker
+ * reverse proxy (ph-relay.networkcanvas.com). Authentication is handled by the
+ * worker, so the API key is optional and defaults to a placeholder value.
+ *
+ * The only environment variable checked is DISABLE_ANALYTICS / NEXT_PUBLIC_DISABLE_ANALYTICS
+ * for disabling tracking. All other configuration is hardcoded or passed explicitly.
+ */
+export function mergeConfig(userConfig: AnalyticsConfig): Required<AnalyticsConfig> {
+	return {
+		apiHost: userConfig.apiHost ?? defaultConfig.apiHost ?? POSTHOG_PROXY_HOST,
+		apiKey: userConfig.apiKey ?? PROXY_MODE_DUMMY_KEY,
+		installationId: userConfig.installationId,
+		disabled: userConfig.disabled ?? isDisabledByEnv() ?? defaultConfig.disabled ?? false,
+		debug: userConfig.debug ?? defaultConfig.debug ?? false,
+		posthogOptions: {
+			...defaultConfig.posthogOptions,
+			...userConfig.posthogOptions,
+		},
+	};
+}

package/src/hooks.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import { useContext } from "react";
+import { AnalyticsContext } from "./provider";
+import type { Analytics } from "./types";
+
+/**
+ * Hook to access analytics functionality in React components
+ *
+ * @example
+ * ```tsx
+ * import { useAnalytics } from '@codaco/analytics';
+ *
+ * function MyComponent() {
+ *   const { trackEvent, trackError } = useAnalytics();
+ *
+ *   const handleAction = () => {
+ *     trackEvent('protocol_installed', {
+ *       metadata: { protocolName: 'My Protocol' }
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleAction}>Install Protocol</button>;
+ * }
+ * ```
+ */
+export function useAnalytics(): Analytics {
+	const analytics = useContext(AnalyticsContext);
+
+	if (!analytics) {
+		throw new Error("useAnalytics must be used within an AnalyticsProvider");
+	}
+
+	return analytics;
+}
+
+/**
+ * Hook to access feature flags
+ *
+ * @example
+ * ```tsx
+ * import { useFeatureFlag } from '@codaco/analytics';
+ *
+ * function MyComponent() {
+ *   const isNewFeatureEnabled = useFeatureFlag('new-feature');
+ *
+ *   if (isNewFeatureEnabled) {
+ *     return <NewFeature />;
+ *   }
+ *
+ *   return <OldFeature />;
+ * }
+ * ```
+ */
+export function useFeatureFlag(flagKey: string): boolean {
+	const analytics = useAnalytics();
+	return analytics.isFeatureEnabled(flagKey) ?? false;
+}
+
+/**
+ * Hook to access feature flag values (for multivariate flags)
+ *
+ * @example
+ * ```tsx
+ * import { useFeatureFlagValue } from '@codaco/analytics';
+ *
+ * function MyComponent() {
+ *   const theme = useFeatureFlagValue('theme-variant');
+ *
+ *   return <div className={theme === 'dark' ? 'dark-theme' : 'light-theme'}>
+ *     Content
+ *   </div>;
+ * }
+ * ```
+ */
+export function useFeatureFlagValue(flagKey: string): string | boolean | undefined {
+	const analytics = useAnalytics();
+	return analytics.getFeatureFlag(flagKey);
+}