@codaco/analytics 8.0.0 → 9.0.1

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+import { A as AnalyticsConfig, a as Analytics } from './types-DK5BiTnW.js';
+import 'zod';
+
+/**
+ * Initialize server-side analytics
+ * Call this once in your app (e.g., in a layout or middleware)
+ *
+ * @example
+ * ```ts
+ * // In your Next.js layout or API route
+ * import { initServerAnalytics } from '@codaco/analytics/server';
+ *
+ * initServerAnalytics({
+ *   installationId: 'your-unique-installation-id',
+ * });
+ * ```
+ */
+declare function initServerAnalytics(config: AnalyticsConfig): void;
+/**
+ * Get the server-side analytics instance
+ * Use this in server components, API routes, and server actions
+ *
+ * @example
+ * ```ts
+ * import { getServerAnalytics } from '@codaco/analytics/server';
+ *
+ * export async function POST(request: Request) {
+ *   const analytics = getServerAnalytics();
+ *   analytics.trackEvent('data_exported', {
+ *     metadata: { format: 'csv' }
+ *   });
+ *
+ *   // ... rest of your handler
+ * }
+ * ```
+ */
+declare function getServerAnalytics(): Analytics;
+/**
+ * Convenience export for direct usage
+ * Requires calling initServerAnalytics() first
+ */
+declare const serverAnalytics: Analytics;
+
+export { getServerAnalytics, initServerAnalytics, serverAnalytics };

package/dist/server.js

@@ -0,0 +1,153 @@
+import {
+  ensureError,
+  mergeConfig
+} from "./chunk-3NEQVIC4.js";
+
+// src/server.ts
+var ServerAnalytics = class {
+  config;
+  disabled;
+  constructor(config) {
+    this.config = mergeConfig(config);
+    this.disabled = this.config.disabled;
+  }
+  /**
+   * Track an event on the server-side
+   */
+  trackEvent(eventType, properties) {
+    if (this.disabled) return;
+    this.sendToPostHog(eventType, {
+      ...properties,
+      ...properties?.metadata ?? {}
+    }).catch((_error) => {
+      if (this.config.debug) {
+      }
+    });
+  }
+  /**
+   * Track an error on the server-side
+   */
+  trackError(error, additionalProperties) {
+    if (this.disabled) return;
+    const errorObj = ensureError(error);
+    const errorProperties = {
+      message: errorObj.message,
+      name: errorObj.name,
+      stack: errorObj.stack,
+      cause: errorObj.cause ? String(errorObj.cause) : void 0,
+      ...additionalProperties
+    };
+    this.sendToPostHog("error", {
+      ...errorProperties,
+      ...additionalProperties?.metadata ?? {}
+    }).catch((_error) => {
+      if (this.config.debug) {
+      }
+    });
+  }
+  /**
+   * Feature flags are not supported in server-side mode
+   * Use client-side hooks or PostHog API directly for feature flags
+   */
+  isFeatureEnabled(_flagKey) {
+    return false;
+  }
+  /**
+   * Feature flags are not supported in server-side mode
+   */
+  getFeatureFlag(_flagKey) {
+    return void 0;
+  }
+  /**
+   * Feature flags are not supported in server-side mode
+   */
+  reloadFeatureFlags() {
+  }
+  /**
+   * User identification on the server-side
+   */
+  identify(distinctId, properties) {
+    if (this.disabled) return;
+    this.sendToPostHog("$identify", {
+      $set: properties ?? {},
+      distinct_id: distinctId
+    }).catch((_error) => {
+      if (this.config.debug) {
+      }
+    });
+  }
+  /**
+   * Reset is not applicable on server-side
+   */
+  reset() {
+  }
+  isEnabled() {
+    return !this.disabled;
+  }
+  getInstallationId() {
+    return this.config.installationId;
+  }
+  /**
+   * Send event to PostHog using fetch API
+   * Note: API key authentication is handled by the Cloudflare Worker proxy,
+   * so we don't include it in the payload.
+   */
+  async sendToPostHog(event, properties) {
+    if (this.disabled) return;
+    const payload = {
+      event,
+      properties: {
+        ...properties,
+        installation_id: this.config.installationId
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    try {
+      const response = await fetch(`${this.config.apiHost}/capture`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload),
+        // Use keepalive for reliability
+        keepalive: true
+      });
+      if (!response.ok) {
+        throw new Error(`PostHog API returned ${response.status}: ${response.statusText}`);
+      }
+    } catch (_error) {
+      if (this.config.debug) {
+      }
+    }
+  }
+};
+var serverAnalyticsInstance = null;
+function initServerAnalytics(config) {
+  if (!serverAnalyticsInstance) {
+    serverAnalyticsInstance = new ServerAnalytics(config);
+  }
+}
+function getServerAnalytics() {
+  if (!serverAnalyticsInstance) {
+    throw new Error(
+      "Server analytics not initialized. Call initServerAnalytics() first (e.g., in your root layout or middleware)."
+    );
+  }
+  return serverAnalyticsInstance;
+}
+var serverAnalytics = new Proxy({}, {
+  get(_target, prop) {
+    if (!serverAnalyticsInstance) {
+      throw new Error(
+        "Server analytics not initialized. Call initServerAnalytics({ installationId: '...' }) first (e.g., in your root layout or middleware)."
+      );
+    }
+    return serverAnalyticsInstance[prop];
+  }
+});
+export {
+  getServerAnalytics,
+  initServerAnalytics,
+  serverAnalytics
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import { mergeConfig } from \"./config\";\nimport type { Analytics, AnalyticsConfig, ErrorProperties, EventProperties, EventType } from \"./types\";\nimport { ensureError } from \"./utils\";\n\n/**\n * Server-side analytics implementation\n * This uses PostHog's API directly for server-side tracking\n */\nclass ServerAnalytics implements Analytics {\n\tprivate config: Required<AnalyticsConfig>;\n\tprivate disabled: boolean;\n\n\tconstructor(config: AnalyticsConfig) {\n\t\tthis.config = mergeConfig(config);\n\t\tthis.disabled = this.config.disabled;\n\t}\n\n\t/**\n\t * Track an event on the server-side\n\t */\n\ttrackEvent(eventType: EventType | string, properties?: EventProperties): void {\n\t\tif (this.disabled) return;\n\n\t\t// Send event to PostHog using fetch\n\t\tthis.sendToPostHog(eventType, {\n\t\t\t...properties,\n\t\t\t...(properties?.metadata ?? {}),\n\t\t}).catch((_error) => {\n\t\t\tif (this.config.debug) {\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Track an error on the server-side\n\t */\n\ttrackError(error: Error, additionalProperties?: EventProperties): void {\n\t\tif (this.disabled) return;\n\n\t\tconst errorObj = ensureError(error);\n\t\tconst errorProperties: ErrorProperties = {\n\t\t\tmessage: errorObj.message,\n\t\t\tname: errorObj.name,\n\t\t\tstack: errorObj.stack,\n\t\t\tcause: errorObj.cause ? String(errorObj.cause) : undefined,\n\t\t\t...additionalProperties,\n\t\t};\n\n\t\tthis.sendToPostHog(\"error\", {\n\t\t\t...errorProperties,\n\t\t\t...(additionalProperties?.metadata ?? {}),\n\t\t}).catch((_error) => {\n\t\t\tif (this.config.debug) {\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Feature flags are not supported in server-side mode\n\t * Use client-side hooks or PostHog API directly for feature flags\n\t */\n\tisFeatureEnabled(_flagKey: string): boolean {\n\t\treturn false;\n\t}\n\n\t/**\n\t * Feature flags are not supported in server-side mode\n\t */\n\tgetFeatureFlag(_flagKey: string): string | boolean | undefined {\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Feature flags are not supported in server-side mode\n\t */\n\treloadFeatureFlags(): void {}\n\n\t/**\n\t * User identification on the server-side\n\t */\n\tidentify(distinctId: string, properties?: Record<string, unknown>): void {\n\t\tif (this.disabled) return;\n\n\t\tthis.sendToPostHog(\"$identify\", {\n\t\t\t$set: properties ?? {},\n\t\t\tdistinct_id: distinctId,\n\t\t}).catch((_error) => {\n\t\t\tif (this.config.debug) {\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Reset is not applicable on server-side\n\t */\n\treset(): void {}\n\n\tisEnabled(): boolean {\n\t\treturn !this.disabled;\n\t}\n\n\tgetInstallationId(): string {\n\t\treturn this.config.installationId;\n\t}\n\n\t/**\n\t * Send event to PostHog using fetch API\n\t * Note: API key authentication is handled by the Cloudflare Worker proxy,\n\t * so we don't include it in the payload.\n\t */\n\tprivate async sendToPostHog(event: string, properties: Record<string, unknown>): Promise<void> {\n\t\tif (this.disabled) return;\n\n\t\tconst payload = {\n\t\t\tevent,\n\t\t\tproperties: {\n\t\t\t\t...properties,\n\t\t\t\tinstallation_id: this.config.installationId,\n\t\t\t},\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t};\n\n\t\ttry {\n\t\t\tconst response = await fetch(`${this.config.apiHost}/capture`, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders: {\n\t\t\t\t\t\"Content-Type\": \"application/json\",\n\t\t\t\t},\n\t\t\t\tbody: JSON.stringify(payload),\n\t\t\t\t// Use keepalive for reliability\n\t\t\t\tkeepalive: true,\n\t\t\t});\n\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow new Error(`PostHog API returned ${response.status}: ${response.statusText}`);\n\t\t\t}\n\t\t} catch (_error) {\n\t\t\t// Silently fail - we don't want analytics errors to break the app\n\t\t\tif (this.config.debug) {\n\t\t\t}\n\t\t}\n\t}\n}\n\n/**\n * Global server-side analytics instance\n */\nlet serverAnalyticsInstance: ServerAnalytics | null = null;\n\n/**\n * Initialize server-side analytics\n * Call this once in your app (e.g., in a layout or middleware)\n *\n * @example\n * ```ts\n * // In your Next.js layout or API route\n * import { initServerAnalytics } from '@codaco/analytics/server';\n *\n * initServerAnalytics({\n *   installationId: 'your-unique-installation-id',\n * });\n * ```\n */\nexport function initServerAnalytics(config: AnalyticsConfig): void {\n\tif (!serverAnalyticsInstance) {\n\t\tserverAnalyticsInstance = new ServerAnalytics(config);\n\t}\n}\n\n/**\n * Get the server-side analytics instance\n * Use this in server components, API routes, and server actions\n *\n * @example\n * ```ts\n * import { getServerAnalytics } from '@codaco/analytics/server';\n *\n * export async function POST(request: Request) {\n *   const analytics = getServerAnalytics();\n *   analytics.trackEvent('data_exported', {\n *     metadata: { format: 'csv' }\n *   });\n *\n *   // ... rest of your handler\n * }\n * ```\n */\nexport function getServerAnalytics(): Analytics {\n\tif (!serverAnalyticsInstance) {\n\t\tthrow new Error(\n\t\t\t\"Server analytics not initialized. Call initServerAnalytics() first (e.g., in your root layout or middleware).\",\n\t\t);\n\t}\n\n\treturn serverAnalyticsInstance;\n}\n\n/**\n * Convenience export for direct usage\n * Requires calling initServerAnalytics() first\n */\nexport const serverAnalytics = new Proxy({} as Analytics, {\n\tget(_target, prop) {\n\t\tif (!serverAnalyticsInstance) {\n\t\t\tthrow new Error(\n\t\t\t\t\"Server analytics not initialized. Call initServerAnalytics({ installationId: '...' }) first \" +\n\t\t\t\t\t\"(e.g., in your root layout or middleware).\",\n\t\t\t);\n\t\t}\n\n\t\treturn serverAnalyticsInstance[prop as keyof Analytics];\n\t},\n});\n"],"mappings":"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","names":[]}

package/dist/types-DK5BiTnW.d.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+
+/**
+ * Event types supported by the analytics system.
+ * These are converted to snake_case for PostHog.
+ */
+declare const eventTypes: readonly ["app_setup", "protocol_installed", "interview_started", "interview_completed", "data_exported", "error"];
+type EventType = (typeof eventTypes)[number];
+/**
+ * Legacy event type mapping for backward compatibility
+ */
+declare const legacyEventTypeMap: Record<string, EventType>;
+/**
+ * Standard event properties that can be sent with any event
+ */
+declare const EventPropertiesSchema: z.ZodObject<{
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type EventProperties = z.infer<typeof EventPropertiesSchema>;
+/**
+ * Error-specific properties for error tracking
+ */
+declare const ErrorPropertiesSchema: z.ZodObject<{
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    message: z.ZodString;
+    name: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    cause: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ErrorProperties = z.infer<typeof ErrorPropertiesSchema>;
+/**
+ * Analytics configuration options
+ *
+ * This package is designed to work exclusively with the Cloudflare Worker
+ * reverse proxy at ph-relay.networkcanvas.com. All authentication is handled
+ * by the worker, so the API key is optional.
+ */
+type AnalyticsConfig = {
+    /**
+     * PostHog API host - should point to the Cloudflare Worker reverse proxy
+     * Defaults to "https://ph-relay.networkcanvas.com"
+     */
+    apiHost?: string;
+    /**
+     * PostHog project API key (optional)
+     *
+     * When using the reverse proxy (default), authentication is handled by the
+     * Cloudflare Worker. A placeholder key will be used for client-side PostHog
+     * initialization if not provided.
+     *
+     * Only set this if you need to override the default behavior.
+     */
+    apiKey?: string;
+    /**
+     * Unique identifier for this installation/deployment
+     * This is included with every event as a super property
+     */
+    installationId: string;
+    /**
+     * Disable all analytics tracking
+     * Can be set via DISABLE_ANALYTICS or NEXT_PUBLIC_DISABLE_ANALYTICS env var
+     */
+    disabled?: boolean;
+    /**
+     * Enable debug mode for PostHog
+     */
+    debug?: boolean;
+    /**
+     * Additional options to pass to PostHog initialization
+     */
+    posthogOptions?: {
+        /**
+         * Disable session recording
+         */
+        disable_session_recording?: boolean;
+        /**
+         * Autocapture settings
+         */
+        autocapture?: boolean;
+        /**
+         * Capture pageviews automatically
+         */
+        capture_pageview?: boolean;
+        /**
+         * Capture pageleave events
+         */
+        capture_pageleave?: boolean;
+        /**
+         * Cross-subdomain cookie
+         */
+        cross_subdomain_cookie?: boolean;
+        /**
+         * Advanced feature flags support
+         */
+        advanced_disable_feature_flags?: boolean;
+        /**
+         * Other PostHog options
+         */
+        [key: string]: unknown;
+    };
+};
+/**
+ * Analytics instance interface
+ */
+type Analytics = {
+    /**
+     * Track a custom event
+     */
+    trackEvent: (eventType: EventType | string, properties?: EventProperties) => void;
+    /**
+     * Track an error with full stack trace
+     */
+    trackError: (error: Error, additionalProperties?: EventProperties) => void;
+    /**
+     * Check if a feature flag is enabled
+     */
+    isFeatureEnabled: (flagKey: string) => boolean | undefined;
+    /**
+     * Get the value of a feature flag
+     */
+    getFeatureFlag: (flagKey: string) => string | boolean | undefined;
+    /**
+     * Reload feature flags from PostHog
+     */
+    reloadFeatureFlags: () => void;
+    /**
+     * Identify a user (optional - for advanced use cases)
+     * Note: By default we only track installations, not users
+     */
+    identify: (distinctId: string, properties?: Record<string, unknown>) => void;
+    /**
+     * Reset the user identity
+     */
+    reset: () => void;
+    /**
+     * Check if analytics is enabled
+     */
+    isEnabled: () => boolean;
+    /**
+     * Get the installation ID
+     */
+    getInstallationId: () => string;
+};
+
+export { type AnalyticsConfig as A, type ErrorProperties as E, type Analytics as a, type EventProperties as b, type EventType as c, eventTypes as e, legacyEventTypeMap as l };

package/package.json

@@ -1,25 +1,45 @@
 {
   "name": "@codaco/analytics",
-  "version": "8.0.0",
+  "version": "9.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
   "author": "Complex Data Collective <hello@complexdatacollective.org>",
-  "description": "Utilities for tracking analytics and error reporting in Fresco",
+  "description": "PostHog analytics wrapper for Network Canvas applications with installation ID tracking and error reporting",
+  "publishConfig": {
+    "tag": "alpha"
+  },
   "peerDependencies": {
-    "next": "15.4.7"
+    "next": "^16.0.7",
+    "react": "^19.2.0"
   },
   "devDependencies": {
-    "tsup": "^8.4.0",
-    "typescript": "^5.9.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.13",
     "@codaco/tsconfig": "0.1.0"
   },
   "dependencies": {
-    "zod": "^4.1.5"
+    "posthog-js": "^1.304.0",
+    "zod": "^4.1.13"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --sourcemap",
+    "build": "tsup src/index.ts src/server.ts --format esm --dts --clean --sourcemap",
     "dev": "npm run build -- --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   }
 }

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