@codaco/analytics 8.0.0 → 9.0.0

package/src/index.ts

@@ -1,240 +1,72 @@
-import { type NextRequest, NextResponse } from "next/server";
-import z from "zod";
-import { ensureError } from "./utils";
-
-// Todo: it would be great to work out a way to support arbitrary types here.
-export const eventTypes = [
-	"AppSetup",
-	"ProtocolInstalled",
-	"InterviewStarted",
-	"InterviewCompleted",
-	"DataExported",
-] as const;
-
-const EventSchema = z.object({
-	type: z.enum(eventTypes),
-});
-
-const ErrorSchema = z.object({
-	type: z.literal("Error"),
-	message: z.string(),
-	name: z.string(),
-	stack: z.string().optional(),
-	cause: z.string().optional(),
-});
-
-const SharedEventAndErrorSchema = z.object({
-	metadata: z.record(z.string(), z.unknown()).optional(),
-});
-
-/**
- * Raw events are the payload that is sent to trackEvent, which can be either
- * general events or errors. We discriminate on the `type` property to determine
- * which schema to use, and then merge the shared properties.
- */
-export const RawEventSchema = z.discriminatedUnion("type", [
-	SharedEventAndErrorSchema.merge(EventSchema),
-	SharedEventAndErrorSchema.merge(ErrorSchema),
-]);
-export type RawEvent = z.infer<typeof RawEventSchema>;
-
-/**
- * Trackable events are the events that are sent to the route handler by
- * `trackEvent`. The function adds the timestamp to ensure it is not inaccurate
- * due to network latency or processing time.
- */
-const TrackablePropertiesSchema = z.object({
-	timestamp: z.string(),
-});
-
-export const TrackableEventSchema = z.intersection(RawEventSchema, TrackablePropertiesSchema);
-export type TrackableEvent = z.infer<typeof TrackableEventSchema>;
-
-/**
- * Dispatchable events are the events that are sent to the platform. The route
- * handler injects the installationId and countryISOCode properties.
- */
-const DispatchablePropertiesSchema = z.object({
-	installationId: z.string(),
-	countryISOCode: z.string(),
-});
-
 /**
- * The final schema for an analytics event. This is the schema that is used to
- * validate the event before it is inserted into the database. It is the
- * intersection of the trackable event and the dispatchable properties.
+ * @codaco/analytics
+ *
+ * PostHog analytics wrapper for Network Canvas applications
+ * with installation ID tracking, error reporting, and feature flags.
+ *
+ * @example Client-side usage (React):
+ * ```tsx
+ * import { AnalyticsProvider, useAnalytics } from '@codaco/analytics';
+ *
+ * // In your root layout
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <AnalyticsProvider
+ *       config={{
+ *         installationId: 'your-unique-installation-id',
+ *       }}
+ *     >
+ *       {children}
+ *     </AnalyticsProvider>
+ *   );
+ * }
+ *
+ * // In your components
+ * function MyComponent() {
+ *   const { trackEvent, trackError } = useAnalytics();
+ *
+ *   const handleAction = () => {
+ *     trackEvent('app_setup', {
+ *       metadata: { version: '1.0.0' }
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleAction}>Setup</button>;
+ * }
+ * ```
+ *
+ * @example Server-side usage (API routes, server actions):
+ * ```ts
+ * import { serverAnalytics } from '@codaco/analytics/server';
+ *
+ * export async function POST(request: Request) {
+ *   serverAnalytics.trackEvent('data_exported', {
+ *     metadata: { format: 'csv' }
+ *   });
+ *
+ *   // ... rest of your handler
+ * }
+ * ```
  */
-export const AnalyticsEventSchema = z.intersection(TrackableEventSchema, DispatchablePropertiesSchema);
-export type analyticsEvent = z.infer<typeof AnalyticsEventSchema>;
-
-type GeoData = {
-	status: "success" | "fail";
-	countryCode: string;
-	message: string;
-};
-
-export const createRouteHandler = ({
-	platformUrl = "https://analytics.networkcanvas.com",
-	installationId,
-	disableAnalytics,
-}: {
-	platformUrl?: string;
-	installationId: string;
-	disableAnalytics?: boolean;
-}) => {
-	return async (request: NextRequest) => {
-		try {
-			const incomingEvent = (await request.json()) as unknown;
-
-			// Check if analytics is disabled
-			if (disableAnalytics) {
-				console.info("🛑 Analytics disabled. Payload not sent.");
-				try {
-					console.info("Payload:", "\n", JSON.stringify(incomingEvent, null, 2));
-				} catch (e) {
-					console.error("Error stringifying payload:", e);
-				}
-
-				return NextResponse.json({ message: "Analytics disabled" }, { status: 200 });
-			}
-
-			// Validate the event
-			const trackableEvent = TrackableEventSchema.safeParse(incomingEvent);
-
-			if (!trackableEvent.success) {
-				console.error("Invalid event:", trackableEvent.error);
-				return NextResponse.json({ error: "Invalid event" }, { status: 400 });
-			}
-
-			// We don't want failures in third party services to prevent us from
-			// tracking analytics events, so we'll catch any errors and log them
-			// and continue with an 'Unknown' country code.
-			let countryISOCode = "Unknown";
-			try {
-				const ip = await fetch("https://api64.ipify.org").then((res) => res.text());
-
-				if (!ip) {
-					throw new Error("Could not fetch IP address");
-				}
-
-				const geoData = (await fetch(`http://ip-api.com/json/${ip}`).then((res) => res.json())) as GeoData;
-
-				if (geoData.status === "success") {
-					countryISOCode = geoData.countryCode;
-				} else {
-					throw new Error(geoData.message);
-				}
-			} catch (e) {
-				console.error("Geolocation failed:", e);
-			}
-
-			const analyticsEvent: analyticsEvent = {
-				...trackableEvent.data,
-				installationId,
-				countryISOCode,
-			};
-
-			// Forward to backend
-			const response = await fetch(`${platformUrl}/api/event`, {
-				keepalive: true,
-				method: "POST",
-				headers: {
-					"Content-Type": "application/json",
-				},
-				body: JSON.stringify(analyticsEvent),
-			});
-
-			if (!response.ok) {
-				let error = `Analytics platform returned an unexpected error: ${response.statusText}`;
-
-				if (response.status === 400) {
-					error = "Analytics platform rejected the event as invalid. Please check the event schema";
-				}
-
-				if (response.status === 404) {
-					error =
-						"Analytics platform could not be reached. Please specify a valid platform URL, or check that the platform is online.";
-				}
-
-				if (response.status === 500) {
-					error = "Analytics platform returned an internal server error. Please check the platform logs.";
-				}
-
-				console.info(`⚠️ Analytics platform rejected event: ${error}`);
-				return Response.json(
-					{
-						error,
-					},
-					{ status: 500 },
-				);
-			}
-			console.info("🚀 Analytics event sent to platform!");
-			return Response.json({ message: "Event forwarded successfully" });
-		} catch (e) {
-			const error = ensureError(e);
-			console.info("🚫 Internal error with sending analytics event.");
-
-			return Response.json({ error: `Error in analytics route handler: ${error.message}` }, { status: 500 });
-		}
-	};
-};
-
-export const makeEventTracker =
-	(options?: { endpoint?: string }) =>
-	async (
-		event: RawEvent,
-	): Promise<{
-		error: string | null;
-		success: boolean;
-	}> => {
-		// We use a relative path by default, which should automatically use the
-		// same origin as the page that is sending the event.
-		const endpoint = options?.endpoint ?? "/api/analytics";
-
-		const eventWithTimeStamp: TrackableEvent = {
-			...event,
-			timestamp: new Date().toJSON(),
-		};
-
-		try {
-			const response = await fetch(endpoint, {
-				method: "POST",
-				keepalive: true,
-				body: JSON.stringify(eventWithTimeStamp),
-				headers: {
-					"Content-Type": "application/json",
-				},
-			});
-
-			if (!response.ok) {
-				if (response.status === 404) {
-					return {
-						error: "Analytics endpoint not found, did you forget to add the route?",
-						success: false,
-					};
-				}
-
-				// createRouteHandler will return a 400 if the event failed schema validation.
-				if (response.status === 400) {
-					return {
-						error: `Invalid event sent to analytics endpoint: ${response.statusText}`,
-						success: false,
-					};
-				}
-
-				// createRouteHandler will return a 500 for all error states
-				return {
-					error: `Internal server error when sending analytics event: ${response.statusText}. Check the route handler implementation.`,
-					success: false,
-				};
-			}
 
-			return { error: null, success: true };
-		} catch (e) {
-			const error = ensureError(e);
-			return {
-				error: `Internal error when sending analytics event: ${error.message}`,
-				success: false,
-			};
-		}
-	};
+// Re-export config helpers
+export { defaultConfig, isDisabledByEnv, mergeConfig } from "./config";
+export { useAnalytics, useFeatureFlag, useFeatureFlagValue } from "./hooks";
+
+// Re-export provider and hooks for client-side usage
+export { AnalyticsProvider, type AnalyticsProviderProps } from "./provider";
+// Re-export types
+export type {
+	Analytics,
+	AnalyticsConfig,
+	ErrorProperties,
+	EventProperties,
+	EventType,
+} from "./types";
+export { eventTypes, legacyEventTypeMap } from "./types";
+
+// Re-export utilities
+export { ensureError } from "./utils";
+
+// Note: Server-side exports are in a separate entry point
+// Import from '@codaco/analytics/server' for server-side usage

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