@codaco/analytics 7.0.0 → 9.0.0

package/src/__tests__/client.test.ts

@@ -0,0 +1,276 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createAnalytics } from "../client";
+import type { AnalyticsConfig } from "../types";
+
+// Mock posthog-js
+vi.mock("posthog-js", () => ({
+	default: {
+		init: vi.fn().mockReturnValue({
+			register: vi.fn(),
+			debug: vi.fn(),
+		}),
+		capture: vi.fn(),
+		isFeatureEnabled: vi.fn(),
+		getFeatureFlag: vi.fn(),
+		reloadFeatureFlags: vi.fn(),
+		identify: vi.fn(),
+		reset: vi.fn(),
+	},
+}));
+
+import posthog from "posthog-js";
+
+describe("createAnalytics", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	const mockConfig: Required<AnalyticsConfig> = {
+		apiHost: "https://ph-relay.networkcanvas.com",
+		apiKey: "phc_test",
+		installationId: "test-install-123",
+		disabled: false,
+		debug: false,
+		posthogOptions: {},
+	};
+
+	describe("initialization", () => {
+		it("should initialize PostHog with correct config", () => {
+			createAnalytics(mockConfig);
+
+			expect(posthog.init).toHaveBeenCalledWith(
+				"phc_test",
+				expect.objectContaining({
+					api_host: "https://ph-relay.networkcanvas.com",
+				}),
+			);
+		});
+
+		it("should not initialize PostHog when disabled", () => {
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const analytics = createAnalytics(disabledConfig);
+
+			expect(posthog.init).not.toHaveBeenCalled();
+			expect(analytics.isEnabled()).toBe(false);
+		});
+
+		it("should register installation ID as super property", () => {
+			const mockPosthogInstance = {
+				register: vi.fn(),
+				debug: vi.fn(),
+			};
+
+			vi.mocked(posthog.init).mockImplementation((_token, options) => {
+				options?.loaded?.(mockPosthogInstance as never);
+				return mockPosthogInstance as never;
+			});
+
+			createAnalytics(mockConfig);
+
+			expect(mockPosthogInstance.register).toHaveBeenCalledWith({
+				installation_id: "test-install-123",
+			});
+		});
+
+		it("should enable debug mode when configured", () => {
+			const mockPosthogInstance = {
+				register: vi.fn(),
+				debug: vi.fn(),
+			};
+
+			vi.mocked(posthog.init).mockImplementation((_token, options) => {
+				options?.loaded?.(mockPosthogInstance as never);
+				return mockPosthogInstance as never;
+			});
+
+			const debugConfig = { ...mockConfig, debug: true };
+			createAnalytics(debugConfig);
+
+			expect(mockPosthogInstance.debug).toHaveBeenCalled();
+		});
+	});
+
+	describe("trackEvent", () => {
+		it("should capture events with PostHog", () => {
+			const analytics = createAnalytics(mockConfig);
+
+			analytics.trackEvent("app_setup", {
+				metadata: { version: "1.0.0" },
+			});
+
+			expect(posthog.capture).toHaveBeenCalledWith("app_setup", {
+				metadata: { version: "1.0.0" },
+				version: "1.0.0",
+			});
+		});
+
+		it("should flatten metadata into properties", () => {
+			const analytics = createAnalytics(mockConfig);
+
+			analytics.trackEvent("protocol_installed", {
+				metadata: {
+					protocolId: "proto-123",
+					version: "2.0.0",
+				},
+			});
+
+			expect(posthog.capture).toHaveBeenCalledWith("protocol_installed", {
+				metadata: {
+					protocolId: "proto-123",
+					version: "2.0.0",
+				},
+				protocolId: "proto-123",
+				version: "2.0.0",
+			});
+		});
+
+		it("should not capture events when disabled", () => {
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const analytics = createAnalytics(disabledConfig);
+
+			analytics.trackEvent("app_setup");
+
+			expect(posthog.capture).not.toHaveBeenCalled();
+		});
+
+		it("should handle errors gracefully", () => {
+			const analytics = createAnalytics(mockConfig);
+			vi.mocked(posthog.capture).mockImplementation(() => {
+				throw new Error("PostHog error");
+			});
+
+			// Should not throw
+			expect(() => analytics.trackEvent("app_setup")).not.toThrow();
+		});
+	});
+
+	describe("trackError", () => {
+		it("should capture errors with full details", () => {
+			const analytics = createAnalytics(mockConfig);
+			const error = new Error("Test error");
+			error.stack = "Error: Test error\n    at test.ts:10";
+
+			analytics.trackError(error);
+
+			expect(posthog.capture).toHaveBeenCalledWith(
+				"error",
+				expect.objectContaining({
+					message: "Test error",
+					name: "Error",
+					stack: expect.stringContaining("Error: Test error"),
+				}),
+			);
+		});
+
+		it("should include additional properties", () => {
+			const analytics = createAnalytics(mockConfig);
+			const error = new Error("Test error");
+
+			analytics.trackError(error, {
+				metadata: { context: "test" },
+			});
+
+			expect(posthog.capture).toHaveBeenCalledWith(
+				"error",
+				expect.objectContaining({
+					message: "Test error",
+					metadata: { context: "test" },
+					context: "test",
+				}),
+			);
+		});
+
+		it("should not capture errors when disabled", () => {
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const analytics = createAnalytics(disabledConfig);
+			const error = new Error("Test error");
+
+			analytics.trackError(error);
+
+			expect(posthog.capture).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("feature flags", () => {
+		it("should check if feature is enabled", () => {
+			const analytics = createAnalytics(mockConfig);
+			vi.mocked(posthog.isFeatureEnabled).mockReturnValue(true);
+
+			const result = analytics.isFeatureEnabled("new-feature");
+
+			expect(result).toBe(true);
+			expect(posthog.isFeatureEnabled).toHaveBeenCalledWith("new-feature");
+		});
+
+		it("should get feature flag value", () => {
+			const analytics = createAnalytics(mockConfig);
+			vi.mocked(posthog.getFeatureFlag).mockReturnValue("variant-a");
+
+			const result = analytics.getFeatureFlag("experiment");
+
+			expect(result).toBe("variant-a");
+			expect(posthog.getFeatureFlag).toHaveBeenCalledWith("experiment");
+		});
+
+		it("should reload feature flags", () => {
+			const analytics = createAnalytics(mockConfig);
+
+			analytics.reloadFeatureFlags();
+
+			expect(posthog.reloadFeatureFlags).toHaveBeenCalled();
+		});
+
+		it("should return false for feature flags when disabled", () => {
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const analytics = createAnalytics(disabledConfig);
+
+			expect(analytics.isFeatureEnabled("test")).toBe(false);
+			expect(analytics.getFeatureFlag("test")).toBeUndefined();
+		});
+	});
+
+	describe("user identification", () => {
+		it("should identify users", () => {
+			const analytics = createAnalytics(mockConfig);
+
+			analytics.identify("user-123", { email: "test@example.com" });
+
+			expect(posthog.identify).toHaveBeenCalledWith("user-123", {
+				email: "test@example.com",
+			});
+		});
+
+		it("should reset user identity", () => {
+			const analytics = createAnalytics(mockConfig);
+
+			analytics.reset();
+
+			expect(posthog.reset).toHaveBeenCalled();
+		});
+
+		it("should not identify when disabled", () => {
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const analytics = createAnalytics(disabledConfig);
+
+			analytics.identify("user-123");
+
+			expect(posthog.identify).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("utility methods", () => {
+		it("should return enabled status", () => {
+			const analytics = createAnalytics(mockConfig);
+			expect(analytics.isEnabled()).toBe(true);
+
+			const disabledConfig = { ...mockConfig, disabled: true };
+			const disabledAnalytics = createAnalytics(disabledConfig);
+			expect(disabledAnalytics.isEnabled()).toBe(false);
+		});
+
+		it("should return installation ID", () => {
+			const analytics = createAnalytics(mockConfig);
+			expect(analytics.getInstallationId()).toBe("test-install-123");
+		});
+	});
+});

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");
+	});
+});