@codaco/analytics 7.0.0 → 9.0.0

package/src/provider.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { createContext, type ReactNode, useEffect, useRef } from "react";
+import { createAnalytics } from "./client";
+import { mergeConfig } from "./config";
+import type { Analytics, AnalyticsConfig } from "./types";
+
+/**
+ * React Context for analytics
+ */
+export const AnalyticsContext = createContext<Analytics | null>(null);
+
+/**
+ * Props for the AnalyticsProvider
+ */
+export interface AnalyticsProviderProps {
+	children: ReactNode;
+	config: AnalyticsConfig;
+}
+
+/**
+ * Provider component that initializes PostHog and provides analytics context
+ *
+ * @example
+ * ```tsx
+ * import { AnalyticsProvider } from '@codaco/analytics';
+ *
+ * function App({ children }) {
+ *   return (
+ *     <AnalyticsProvider
+ *       config={{
+ *         installationId: 'your-installation-id',
+ *         apiKey: 'phc_your_api_key', // optional if set via env
+ *         apiHost: 'https://ph-relay.networkcanvas.com', // optional
+ *       }}
+ *     >
+ *       {children}
+ *     </AnalyticsProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AnalyticsProvider({ children, config }: AnalyticsProviderProps) {
+	const analyticsRef = useRef<Analytics | null>(null);
+
+	// Initialize analytics only once
+	useEffect(() => {
+		if (!analyticsRef.current) {
+			const mergedConfig = mergeConfig(config);
+			analyticsRef.current = createAnalytics(mergedConfig);
+		}
+	}, []); // Empty deps - only initialize once
+
+	// Don't render children until analytics is initialized
+	if (!analyticsRef.current) {
+		return null;
+	}
+
+	return <AnalyticsContext.Provider value={analyticsRef.current}>{children}</AnalyticsContext.Provider>;
+}

package/src/server.ts

@@ -0,0 +1,213 @@
+import { mergeConfig } from "./config";
+import type { Analytics, AnalyticsConfig, ErrorProperties, EventProperties, EventType } from "./types";
+import { ensureError } from "./utils";
+
+/**
+ * Server-side analytics implementation
+ * This uses PostHog's API directly for server-side tracking
+ */
+class ServerAnalytics implements Analytics {
+	private config: Required<AnalyticsConfig>;
+	private disabled: boolean;
+
+	constructor(config: AnalyticsConfig) {
+		this.config = mergeConfig(config);
+		this.disabled = this.config.disabled;
+	}
+
+	/**
+	 * Track an event on the server-side
+	 */
+	trackEvent(eventType: EventType | string, properties?: EventProperties): void {
+		if (this.disabled) return;
+
+		// Send event to PostHog using fetch
+		this.sendToPostHog(eventType, {
+			...properties,
+			...(properties?.metadata ?? {}),
+		}).catch((_error) => {
+			if (this.config.debug) {
+			}
+		});
+	}
+
+	/**
+	 * Track an error on the server-side
+	 */
+	trackError(error: Error, additionalProperties?: EventProperties): void {
+		if (this.disabled) return;
+
+		const errorObj = ensureError(error);
+		const errorProperties: ErrorProperties = {
+			message: errorObj.message,
+			name: errorObj.name,
+			stack: errorObj.stack,
+			cause: errorObj.cause ? String(errorObj.cause) : undefined,
+			...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: string): boolean {
+		return false;
+	}
+
+	/**
+	 * Feature flags are not supported in server-side mode
+	 */
+	getFeatureFlag(_flagKey: string): string | boolean | undefined {
+		return undefined;
+	}
+
+	/**
+	 * Feature flags are not supported in server-side mode
+	 */
+	reloadFeatureFlags(): void {}
+
+	/**
+	 * User identification on the server-side
+	 */
+	identify(distinctId: string, properties?: Record<string, unknown>): void {
+		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(): void {}
+
+	isEnabled(): boolean {
+		return !this.disabled;
+	}
+
+	getInstallationId(): string {
+		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.
+	 */
+	private async sendToPostHog(event: string, properties: Record<string, unknown>): Promise<void> {
+		if (this.disabled) return;
+
+		const payload = {
+			event,
+			properties: {
+				...properties,
+				installation_id: this.config.installationId,
+			},
+			timestamp: 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) {
+			// Silently fail - we don't want analytics errors to break the app
+			if (this.config.debug) {
+			}
+		}
+	}
+}
+
+/**
+ * Global server-side analytics instance
+ */
+let serverAnalyticsInstance: ServerAnalytics | null = null;
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+export function initServerAnalytics(config: AnalyticsConfig): void {
+	if (!serverAnalyticsInstance) {
+		serverAnalyticsInstance = new ServerAnalytics(config);
+	}
+}
+
+/**
+ * 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
+ * }
+ * ```
+ */
+export function getServerAnalytics(): Analytics {
+	if (!serverAnalyticsInstance) {
+		throw new Error(
+			"Server analytics not initialized. Call initServerAnalytics() first (e.g., in your root layout or middleware).",
+		);
+	}
+
+	return serverAnalyticsInstance;
+}
+
+/**
+ * Convenience export for direct usage
+ * Requires calling initServerAnalytics() first
+ */
+export const serverAnalytics = new Proxy({} as Analytics, {
+	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 as keyof Analytics];
+	},
+});

package/src/types.ts

@@ -0,0 +1,183 @@
+import z from "zod";
+
+/**
+ * Event types supported by the analytics system.
+ * These are converted to snake_case for PostHog.
+ */
+export const eventTypes = [
+	"app_setup",
+	"protocol_installed",
+	"interview_started",
+	"interview_completed",
+	"data_exported",
+	"error",
+] as const;
+
+export type EventType = (typeof eventTypes)[number];
+
+/**
+ * Legacy event type mapping for backward compatibility
+ */
+export const legacyEventTypeMap: Record<string, EventType> = {
+	AppSetup: "app_setup",
+	ProtocolInstalled: "protocol_installed",
+	InterviewStarted: "interview_started",
+	InterviewCompleted: "interview_completed",
+	DataExported: "data_exported",
+	Error: "error",
+};
+
+/**
+ * Standard event properties that can be sent with any event
+ */
+export const EventPropertiesSchema = z.object({
+	metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type EventProperties = z.infer<typeof EventPropertiesSchema>;
+
+/**
+ * Error-specific properties for error tracking
+ */
+export const ErrorPropertiesSchema = EventPropertiesSchema.extend({
+	message: z.string(),
+	name: z.string(),
+	stack: z.string().optional(),
+	cause: z.string().optional(),
+});
+
+export 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.
+ */
+export interface 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
+ */
+export interface 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;
+}

package/src/utils.ts

@@ -1,23 +1,20 @@
 // Helper function that ensures that a value is an Error
 export function ensureError(value: unknown): Error {
-  if (!value) return new Error('No value was thrown');
+	if (!value) return new Error("No value was thrown");
 
-  if (value instanceof Error) return value;
+	if (value instanceof Error) return value;
 
-  // Test if value inherits from Error
-  if (Object.prototype.isPrototypeOf.call(value, Error))
-    return value as Error & typeof value;
+	// Test if value inherits from Error
+	if (Object.prototype.isPrototypeOf.call(value, Error)) return value as Error & typeof value;
 
-  let stringified = '[Unable to stringify the thrown value]';
-  try {
-    stringified = JSON.stringify(value);
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error(e);
-  }
+	let stringified = "[Unable to stringify the thrown value]";
+	try {
+		stringified = JSON.stringify(value);
+	} catch (e) {
+		// biome-ignore lint/suspicious/noConsole: logging
+		console.error(e);
+	}
 
-  const error = new Error(
-    `This value was thrown as is, not through an Error: ${stringified}`,
-  );
-  return error;
+	const error = new Error(`This value was thrown as is, not through an Error: ${stringified}`);
+	return error;
 }

package/tsconfig.json

@@ -1,9 +1,9 @@
 {
-  "extends": "@codaco/tsconfig/base.json",
-  "compilerOptions": {
-    "baseUrl": ".",
-    "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
-  },
-  "include": ["."],
-  "exclude": ["dist", "build", "node_modules"]
+	"extends": "@codaco/tsconfig/web.json",
+	"compilerOptions": {
+		"baseUrl": ".",
+		"tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+	},
+	"include": ["."],
+	"exclude": ["dist", "build", "node_modules"]
 }

package/vitest.config.ts

@@ -0,0 +1,18 @@
+/// <reference types="vitest" />
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+	resolve: {
+		alias: {
+			"~": resolve(__dirname, "./src"),
+		},
+	},
+	test: {
+		disableConsoleIntercept: true,
+	},
+});

package/.turbo/turbo-build.log

@@ -1,16 +0,0 @@
-
-
-> @codaco/analytics@6.0.0 build /Users/buckhalt/Code/complexdatacollective/network-canvas-monorepo/packages/analytics
-> tsup src/index.ts --format esm --dts --clean --sourcemap
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.0.2
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js     6.32 KB
-ESM dist/index.js.map 13.22 KB
-ESM ⚡️ Build success in 167ms
-DTS Build start
- ELIFECYCLE  Command failed.

package/.turbo/turbo-lint.log

@@ -1,7 +0,0 @@
-
-
-> @codaco/analytics@7.0.0 lint /Users/buckhalt/Code/complexdatacollective/network-canvas-monorepo/packages/analytics
-> eslint .
-
-Warning: React version was set to "detect" in eslint-plugin-react settings, but the "react" package is not installed. Assuming latest React version for linting.
-Pages directory cannot be found at /Users/buckhalt/Code/complexdatacollective/network-canvas-monorepo/packages/analytics/pages or /Users/buckhalt/Code/complexdatacollective/network-canvas-monorepo/packages/analytics/src/pages. If using a custom path, please configure with the `no-html-link-for-pages` rule in your eslint config file.