@codaco/analytics 7.0.0 → 9.0.0

package/dist/index.d.ts

@@ -1,150 +1,119 @@
-import { NextRequest } from 'next/server';
-import z from 'zod';
+import { A as AnalyticsConfig, a as Analytics } from './types-Ymgjicqi.js';
+export { E as ErrorProperties, b as EventProperties, c as EventType, e as eventTypes, l as legacyEventTypeMap } from './types-Ymgjicqi.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import 'zod';
 
-declare const eventTypes: readonly ["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported"];
 /**
- * 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.
+ * Check if analytics is disabled via environment variables
  */
-declare const RawEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodEnum<["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported"]>;
-}>, "strip", z.ZodTypeAny, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodLiteral<"Error">;
-    message: z.ZodString;
-    name: z.ZodString;
-    stack: z.ZodOptional<z.ZodString>;
-    cause: z.ZodOptional<z.ZodString>;
-}>, "strip", z.ZodTypeAny, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}>]>;
-type RawEvent = z.infer<typeof RawEventSchema>;
-declare const TrackableEventSchema: z.ZodIntersection<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodEnum<["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported"]>;
-}>, "strip", z.ZodTypeAny, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodLiteral<"Error">;
-    message: z.ZodString;
-    name: z.ZodString;
-    stack: z.ZodOptional<z.ZodString>;
-    cause: z.ZodOptional<z.ZodString>;
-}>, "strip", z.ZodTypeAny, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}>]>, z.ZodObject<{
-    timestamp: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    timestamp: string;
-}, {
-    timestamp: string;
-}>>;
-type TrackableEvent = z.infer<typeof TrackableEventSchema>;
+declare function isDisabledByEnv(): boolean;
 /**
- * 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.
+ * Default configuration for analytics
+ * API host and key are hardcoded, but disabled flag can be set via environment variables
  */
-declare const AnalyticsEventSchema: z.ZodIntersection<z.ZodIntersection<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodEnum<["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported"]>;
-}>, "strip", z.ZodTypeAny, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported";
-    metadata?: Record<string, unknown> | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, {
-    type: z.ZodLiteral<"Error">;
-    message: z.ZodString;
-    name: z.ZodString;
-    stack: z.ZodOptional<z.ZodString>;
-    cause: z.ZodOptional<z.ZodString>;
-}>, "strip", z.ZodTypeAny, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "Error";
-    message: string;
-    name: string;
-    stack?: string | undefined;
-    cause?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}>]>, z.ZodObject<{
-    timestamp: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    timestamp: string;
-}, {
-    timestamp: string;
-}>>, z.ZodObject<{
-    installationId: z.ZodString;
-    countryISOCode: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    installationId: string;
-    countryISOCode: string;
-}, {
-    installationId: string;
-    countryISOCode: string;
-}>>;
-type analyticsEvent = z.infer<typeof AnalyticsEventSchema>;
-declare const createRouteHandler: ({ platformUrl, installationId, disableAnalytics, }: {
-    platformUrl?: string;
-    installationId: string;
-    disableAnalytics?: boolean;
-}) => (request: NextRequest) => Promise<Response>;
-declare const makeEventTracker: (options?: {
-    endpoint?: string;
-}) => (event: RawEvent) => Promise<{
-    error: string | null;
-    success: boolean;
-}>;
+declare const defaultConfig: Partial<AnalyticsConfig>;
+/**
+ * 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.
+ */
+declare function mergeConfig(userConfig: AnalyticsConfig): Required<AnalyticsConfig>;
+
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useAnalytics(): 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 />;
+ * }
+ * ```
+ */
+declare function useFeatureFlag(flagKey: string): boolean;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useFeatureFlagValue(flagKey: string): string | boolean | undefined;
+
+/**
+ * Props for the AnalyticsProvider
+ */
+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>
+ *   );
+ * }
+ * ```
+ */
+declare function AnalyticsProvider({ children, config }: AnalyticsProviderProps): react.JSX.Element | null;
+
+declare function ensureError(value: unknown): Error;
 
-export { AnalyticsEventSchema, type RawEvent, RawEventSchema, type TrackableEvent, TrackableEventSchema, type analyticsEvent, createRouteHandler, eventTypes, makeEventTracker };
+export { Analytics, AnalyticsConfig, AnalyticsProvider, type AnalyticsProviderProps, defaultConfig, ensureError, isDisabledByEnv, mergeConfig, useAnalytics, useFeatureFlag, useFeatureFlagValue };

package/dist/index.js

@@ -1,205 +1,210 @@
-// src/index.ts
-import { NextResponse } from "next/server";
+import {
+  defaultConfig,
+  ensureError,
+  isDisabledByEnv,
+  mergeConfig
+} from "./chunk-3NEQVIC4.js";
 
-// src/utils.ts
-function ensureError(value) {
-  if (!value) return new Error("No value was thrown");
-  if (value instanceof Error) return value;
-  if (Object.prototype.isPrototypeOf.call(value, Error))
-    return value;
-  let stringified = "[Unable to stringify the thrown value]";
-  try {
-    stringified = JSON.stringify(value);
-  } catch (e) {
-    console.error(e);
-  }
-  const error = new Error(
-    `This value was thrown as is, not through an Error: ${stringified}`
-  );
-  return error;
-}
+// src/hooks.ts
+import { useContext } from "react";
 
-// src/index.ts
-import z from "zod";
-var eventTypes = [
-  "AppSetup",
-  "ProtocolInstalled",
-  "InterviewStarted",
-  "InterviewCompleted",
-  "DataExported"
-];
-var EventSchema = z.object({
-  type: z.enum(eventTypes)
-});
-var ErrorSchema = z.object({
-  type: z.literal("Error"),
-  message: z.string(),
-  name: z.string(),
-  stack: z.string().optional(),
-  cause: z.string().optional()
-});
-var SharedEventAndErrorSchema = z.object({
-  metadata: z.record(z.unknown()).optional()
-});
-var RawEventSchema = z.discriminatedUnion("type", [
-  SharedEventAndErrorSchema.merge(EventSchema),
-  SharedEventAndErrorSchema.merge(ErrorSchema)
-]);
-var TrackablePropertiesSchema = z.object({
-  timestamp: z.string()
-});
-var TrackableEventSchema = z.intersection(
-  RawEventSchema,
-  TrackablePropertiesSchema
-);
-var DispatchablePropertiesSchema = z.object({
-  installationId: z.string(),
-  countryISOCode: z.string()
-});
-var AnalyticsEventSchema = z.intersection(
-  TrackableEventSchema,
-  DispatchablePropertiesSchema
-);
-var createRouteHandler = ({
-  platformUrl = "https://analytics.networkcanvas.com",
-  installationId,
-  disableAnalytics
-}) => {
-  return async (request) => {
-    try {
-      const incomingEvent = await request.json();
-      if (disableAnalytics) {
-        console.info("\u{1F6D1} Analytics disabled. Payload not sent.");
-        try {
-          console.info(
-            "Payload:",
-            "\n",
-            JSON.stringify(incomingEvent, null, 2)
-          );
-        } catch (e) {
-          console.error("Error stringifying payload:", e);
+// src/provider.tsx
+import { createContext, useEffect, useRef } from "react";
+
+// src/client.ts
+import posthog from "posthog-js";
+function createAnalytics(config) {
+  const { apiHost, apiKey, installationId, disabled, debug, posthogOptions } = config;
+  if (disabled) {
+    return createNoOpAnalytics(installationId);
+  }
+  posthog.init(apiKey, {
+    api_host: apiHost,
+    loaded: (posthogInstance) => {
+      posthogInstance.register({
+        installation_id: installationId
+      });
+      if (debug) {
+        posthogInstance.debug();
+      }
+    },
+    ...posthogOptions
+  });
+  return {
+    trackEvent: (eventType, properties) => {
+      if (disabled) return;
+      try {
+        posthog.capture(eventType, {
+          ...properties,
+          // Flatten metadata into properties for better PostHog integration
+          ...properties?.metadata ?? {}
+        });
+      } catch (_e) {
+        if (debug) {
         }
-        return NextResponse.json(
-          { message: "Analytics disabled" },
-          { status: 200 }
-        );
       }
-      const trackableEvent = TrackableEventSchema.safeParse(incomingEvent);
-      if (!trackableEvent.success) {
-        console.error("Invalid event:", trackableEvent.error);
-        return NextResponse.json({ error: "Invalid event" }, { status: 400 });
+    },
+    trackError: (error, additionalProperties) => {
+      if (disabled) return;
+      try {
+        const errorObj = ensureError(error);
+        const errorProperties = {
+          message: errorObj.message,
+          name: errorObj.name,
+          stack: errorObj.stack,
+          cause: errorObj.cause ? String(errorObj.cause) : void 0,
+          ...additionalProperties
+        };
+        posthog.capture("error", {
+          ...errorProperties,
+          // Flatten metadata
+          ...additionalProperties?.metadata ?? {}
+        });
+      } catch (_e) {
+        if (debug) {
+        }
       }
-      let countryISOCode = "Unknown";
+    },
+    isFeatureEnabled: (flagKey) => {
+      if (disabled) return false;
       try {
-        const ip = await fetch("https://api64.ipify.org").then(
-          (res) => res.text()
-        );
-        if (!ip) {
-          throw new Error("Could not fetch IP address");
+        return posthog.isFeatureEnabled(flagKey);
+      } catch (_e) {
+        if (debug) {
         }
-        const geoData = await fetch(`http://ip-api.com/json/${ip}`).then(
-          (res) => res.json()
-        );
-        if (geoData.status === "success") {
-          countryISOCode = geoData.countryCode;
-        } else {
-          throw new Error(geoData.message);
+        return void 0;
+      }
+    },
+    getFeatureFlag: (flagKey) => {
+      if (disabled) return void 0;
+      try {
+        return posthog.getFeatureFlag(flagKey);
+      } catch (_e) {
+        if (debug) {
         }
-      } catch (e) {
-        console.error("Geolocation failed:", e);
+        return void 0;
       }
-      const analyticsEvent = {
-        ...trackableEvent.data,
-        installationId,
-        countryISOCode
-      };
-      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`;
+    },
+    reloadFeatureFlags: () => {
+      if (disabled) return;
+      try {
+        posthog.reloadFeatureFlags();
+      } catch (_e) {
+        if (debug) {
         }
-        if (response.status === 404) {
-          error = `Analytics platform could not be reached. Please specify a valid platform URL, or check that the platform is online.`;
+      }
+    },
+    identify: (distinctId, properties) => {
+      if (disabled) return;
+      try {
+        posthog.identify(distinctId, properties);
+      } catch (_e) {
+        if (debug) {
         }
-        if (response.status === 500) {
-          error = `Analytics platform returned an internal server error. Please check the platform logs.`;
+      }
+    },
+    reset: () => {
+      if (disabled) return;
+      try {
+        posthog.reset();
+      } catch (_e) {
+        if (debug) {
         }
-        console.info(`\u26A0\uFE0F Analytics platform rejected event: ${error}`);
-        return Response.json(
-          {
-            error
-          },
-          { status: 500 }
-        );
       }
-      console.info("\u{1F680} Analytics event sent to platform!");
-      return Response.json({ message: "Event forwarded successfully" });
-    } catch (e) {
-      const error = ensureError(e);
-      console.info("\u{1F6AB} Internal error with sending analytics event.");
-      return Response.json(
-        { error: `Error in analytics route handler: ${error.message}` },
-        { status: 500 }
-      );
-    }
+    },
+    isEnabled: () => !disabled,
+    getInstallationId: () => installationId
   };
-};
-var makeEventTracker = (options) => async (event) => {
-  const endpoint = options?.endpoint ?? "/api/analytics";
-  const eventWithTimeStamp = {
-    ...event,
-    timestamp: (/* @__PURE__ */ new Date()).toJSON()
+}
+function createNoOpAnalytics(installationId) {
+  return {
+    trackEvent: () => {
+    },
+    trackError: () => {
+    },
+    isFeatureEnabled: () => false,
+    getFeatureFlag: () => void 0,
+    reloadFeatureFlags: () => {
+    },
+    identify: () => {
+    },
+    reset: () => {
+    },
+    isEnabled: () => false,
+    getInstallationId: () => installationId
   };
-  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
-        };
-      }
-      if (response.status === 400) {
-        return {
-          error: `Invalid event sent to analytics endpoint: ${response.statusText}`,
-          success: false
-        };
-      }
-      return {
-        error: `Internal server error when sending analytics event: ${response.statusText}. Check the route handler implementation.`,
-        success: false
-      };
+}
+
+// src/provider.tsx
+var AnalyticsContext = createContext(null);
+function AnalyticsProvider({ children, config }) {
+  const analyticsRef = useRef(null);
+  useEffect(() => {
+    if (!analyticsRef.current) {
+      const mergedConfig = mergeConfig(config);
+      analyticsRef.current = createAnalytics(mergedConfig);
     }
-    return { error: null, success: true };
-  } catch (e) {
-    const error = ensureError(e);
-    return {
-      error: `Internal error when sending analytics event: ${error.message}`,
-      success: false
-    };
+  }, []);
+  if (!analyticsRef.current) {
+    return null;
+  }
+  return /* @__PURE__ */ React.createElement(AnalyticsContext.Provider, { value: analyticsRef.current }, children);
+}
+
+// src/hooks.ts
+function useAnalytics() {
+  const analytics = useContext(AnalyticsContext);
+  if (!analytics) {
+    throw new Error("useAnalytics must be used within an AnalyticsProvider");
   }
+  return analytics;
+}
+function useFeatureFlag(flagKey) {
+  const analytics = useAnalytics();
+  return analytics.isFeatureEnabled(flagKey) ?? false;
+}
+function useFeatureFlagValue(flagKey) {
+  const analytics = useAnalytics();
+  return analytics.getFeatureFlag(flagKey);
+}
+
+// src/types.ts
+import z from "zod";
+var eventTypes = [
+  "app_setup",
+  "protocol_installed",
+  "interview_started",
+  "interview_completed",
+  "data_exported",
+  "error"
+];
+var legacyEventTypeMap = {
+  AppSetup: "app_setup",
+  ProtocolInstalled: "protocol_installed",
+  InterviewStarted: "interview_started",
+  InterviewCompleted: "interview_completed",
+  DataExported: "data_exported",
+  Error: "error"
 };
+var EventPropertiesSchema = z.object({
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var ErrorPropertiesSchema = EventPropertiesSchema.extend({
+  message: z.string(),
+  name: z.string(),
+  stack: z.string().optional(),
+  cause: z.string().optional()
+});
 export {
-  AnalyticsEventSchema,
-  RawEventSchema,
-  TrackableEventSchema,
-  createRouteHandler,
+  AnalyticsProvider,
+  defaultConfig,
+  ensureError,
   eventTypes,
-  makeEventTracker
+  isDisabledByEnv,
+  legacyEventTypeMap,
+  mergeConfig,
+  useAnalytics,
+  useFeatureFlag,
+  useFeatureFlagValue
 };
 //# sourceMappingURL=index.js.map