@codaco/analytics 7.0.0 → 9.0.0

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

package/src/index.ts

@@ -1,267 +1,72 @@
-import { NextResponse, type NextRequest } from 'next/server';
-import { ensureError } from './utils';
-import z from 'zod';
-
-// 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.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) {
-        // eslint-disable-next-line no-console
-        console.info('🛑 Analytics disabled. Payload not sent.');
-        try {
-          // eslint-disable-next-line no-console
-          console.info(
-            'Payload:',
-            '\n',
-            JSON.stringify(incomingEvent, null, 2),
-          );
-        } catch (e) {
-          // eslint-disable-next-line no-console
-          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) {
-        // eslint-disable-next-line no-console
-        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) {
-        // eslint-disable-next-line no-console
-        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.`;
-        }
-
-        // eslint-disable-next-line no-console
-        console.info(`⚠️ Analytics platform rejected event: ${error}`);
-        return Response.json(
-          {
-            error,
-          },
-          { status: 500 },
-        );
-      }
-      // eslint-disable-next-line no-console
-      console.info('🚀 Analytics event sent to platform!');
-      return Response.json({ message: 'Event forwarded successfully' });
-    } catch (e) {
-      const error = ensureError(e);
-      // eslint-disable-next-line no-console
-      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