@codaco/analytics 3.1.0 → 5.0.0

package/src/index.ts

@@ -1,185 +1,242 @@
-import type { NextRequest } from "next/server";
-import { WebServiceClient } from "@maxmind/geoip2-node";
-import { ensureError, getBaseUrl } from "./utils";
-import z from "zod";
-
-export const eventTypes = [
-  "AppSetup",
-  "ProtocolInstalled",
-  "InterviewStarted",
-  "InterviewCompleted",
-  "DataExported",
-  "Error",
-] as const;
-
-export type EventType = (typeof eventTypes)[number];
-type EventTypeWithoutError = Exclude<EventType, "Error">;
-
-export const EventsSchema = z.object({
-  type: z.enum(eventTypes),
-  installationId: z.string(),
-  timestamp: z.string(),
-  isocode: z.string().optional(),
-  error: z
-    .object({
-      message: z.string(),
-      name: z.string(),
-      stack: z.string().optional(),
-    })
-    .optional(),
-  metadata: z.record(z.unknown()).optional(),
-});
-
-export type Event = z.infer<typeof EventsSchema>;
-
-export type AnalyticsEvent = {
-  type: EventTypeWithoutError;
-  metadata?: Record<string, unknown>;
-};
-
-export type AnalyticsError = {
-  type: "Error";
-  error: Error;
-  metadata?: Record<string, unknown>;
-};
-
-export type AnalyticsEventOrError = AnalyticsEvent | AnalyticsError;
-
-export type AnalyticsEventOrErrorWithTimestamp = AnalyticsEventOrError & {
-  timestamp: string;
-};
-
-type RouteHandlerConfiguration = {
-  platformUrl?: string;
-  installationId: string;
-  maxMindClient: WebServiceClient;
-};
-
-export const createRouteHandler = ({
-  platformUrl = "https://analytics.networkcanvas.com",
-  installationId,
-  maxMindClient,
-}: RouteHandlerConfiguration) => {
-  return async (request: NextRequest) => {
-    try {
-      const event =
-        (await request.json()) as AnalyticsEventOrErrorWithTimestamp;
-
-      const ip = await fetch("https://api64.ipify.org").then((res) =>
-        res.text()
-      );
-
-      const { country } = await maxMindClient.country(ip);
-      const countryCode = country?.isoCode ?? "Unknown";
-
-      const dispatchableEvent: Event = {
-        ...event,
-        installationId,
-        isocode: countryCode,
-      };
-
-      // Forward to microservice
-      const response = await fetch(`${platformUrl}/api/event`, {
-        keepalive: true,
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(dispatchableEvent),
-      });
-
-      if (!response.ok) {
-        if (response.status === 404) {
-          console.error(
-            `Analytics platform not found. Please specify a valid platform URL.`
-          );
-        } else if (response.status === 500) {
-          console.error(
-            `Internal server error on analytics platform when forwarding event: ${response.statusText}.`
-          );
-        } else {
-          console.error(
-            `General error when forwarding event: ${response.statusText}`
-          );
-        }
-
-        return new Response(
-          JSON.stringify({ error: "Internal Server Error" }),
-          {
-            status: 500,
-            headers: {
-              "Content-Type": "application/json",
-            },
-          }
-        );
-      }
-
-      return new Response(
-        JSON.stringify({ message: "Event forwarded successfully" }),
-        {
-          status: 200,
-          headers: {
-            "Content-Type": "application/json",
-          },
-        }
-      );
-    } catch (e) {
-      const error = ensureError(e);
-      console.error("Error in route handler:", error);
-
-      // Return an appropriate error response
-      return new Response(JSON.stringify({ error: "Internal Server Error" }), {
-        status: 500,
-        headers: {
-          "Content-Type": "application/json",
-        },
-      });
-    }
-  };
-};
-
-export const makeEventTracker =
-  (endpoint: string = "/api/analytics") =>
-  async (event: AnalyticsEventOrError) => {
-    const endpointWithHost = getBaseUrl() + endpoint;
-
-    const eventWithTimeStamp = {
-      ...event,
-      timestamp: new Date(),
-    };
-
-    try {
-      const response = await fetch(endpointWithHost, {
-        method: "POST",
-        keepalive: true,
-        body: JSON.stringify(eventWithTimeStamp),
-        headers: {
-          "Content-Type": "application/json",
-        },
-      });
-
-      if (!response.ok) {
-        if (response.status === 404) {
-          console.error(
-            `Analytics endpoint not found, did you forget to add the route?`
-          );
-          return;
-        }
-
-        if (response.status === 500) {
-          console.error(
-            `Internal server error when sending analytics event: ${response.statusText}. Check the route handler implementation.`
-          );
-          return;
-        }
-
-        console.error(
-          `General error sending analytics event: ${response.statusText}`
-        );
-      }
-    } catch (e) {
-      const error = ensureError(e);
-
-      console.error("Internal error with analytics:", error.message);
-    }
-  };
+import { type NextRequest } from "next/server";
+import { WebServiceClient } from "@maxmind/geoip2-node";
+import { ensureError, getBaseUrl } 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 events that are sent trackEvent. They are 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. The
+ * `trackEvent` 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.
+ */
+export const AnalyticsEventSchema = z.intersection(
+  TrackableEventSchema,
+  DispatchablePropertiesSchema
+);
+export type analyticsEvent = z.infer<typeof AnalyticsEventSchema>;
+
+export const createRouteHandler = ({
+  platformUrl = "https://analytics.networkcanvas.com",
+  installationId,
+  maxMindClient,
+}: {
+  platformUrl?: string;
+  installationId: string;
+  maxMindClient: WebServiceClient;
+}) => {
+  return async (request: NextRequest) => {
+    try {
+      const incomingEvent = (await request.json()) as unknown;
+
+      // Validate the event
+      const trackableEvent = TrackableEventSchema.safeParse(incomingEvent);
+
+      if (!trackableEvent.success) {
+        console.error("Invalid event:", trackableEvent.error);
+        return new Response(JSON.stringify({ error: "Invalid event" }), {
+          status: 400,
+          headers: {
+            "Content-Type": "application/json",
+          },
+        });
+      }
+
+      // 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 { country } = await maxMindClient.country(ip);
+        countryISOCode = country?.isoCode ?? "Unknown";
+      } 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 =
+  ({
+    enabled = false,
+    endpoint = "/api/analytics",
+  }: {
+    enabled?: boolean;
+    endpoint?: string;
+  }) =>
+  async (
+    event: RawEvent
+  ): Promise<{
+    error: string | null;
+    success: boolean;
+  }> => {
+    if (!enabled) {
+      console.log("Analytics disabled - event not sent.");
+      return { error: null, success: true };
+    }
+
+    const endpointWithHost = getBaseUrl() + endpoint;
+
+    const eventWithTimeStamp: TrackableEvent = {
+      ...event,
+      timestamp: new Date().toJSON(),
+    };
+
+    try {
+      const response = await fetch(endpointWithHost, {
+        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,
+      };
+    }
+  };

package/src/utils.ts

@@ -1,36 +1,36 @@
-// 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 instanceof Error) return value;
-
-  // Test if value inherits from Error
-  if (value.isPrototypeOf(Error)) return value as Error & typeof value;
-
-  let stringified = "[Unable to stringify the thrown value]";
-  try {
-    stringified = JSON.stringify(value);
-  } catch {}
-
-  const error = new Error(
-    `This value was thrown as is, not through an Error: ${stringified}`
-  );
-  return error;
-}
-
-export function getBaseUrl() {
-  if (typeof window !== "undefined")
-    // browser should use relative path
-    return "";
-
-  if (process.env.VERCEL_URL)
-    // reference for vercel.com
-    return `https://${process.env.VERCEL_URL}`;
-
-  if (process.env.NEXT_PUBLIC_URL)
-    // Manually set deployment URL from env
-    return process.env.NEXT_PUBLIC_URL;
-
-  // assume localhost
-  return `http://127.0.0.1:3000`;
-}
+// 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 instanceof Error) return value;
+
+  // Test if value inherits from Error
+  if (value.isPrototypeOf(Error)) return value as Error & typeof value;
+
+  let stringified = "[Unable to stringify the thrown value]";
+  try {
+    stringified = JSON.stringify(value);
+  } catch {}
+
+  const error = new Error(
+    `This value was thrown as is, not through an Error: ${stringified}`
+  );
+  return error;
+}
+
+export function getBaseUrl() {
+  if (typeof window !== "undefined")
+    // browser should use relative path
+    return "";
+
+  if (process.env.VERCEL_URL)
+    // reference for vercel.com
+    return `https://${process.env.VERCEL_URL}`;
+
+  if (process.env.NEXT_PUBLIC_URL)
+    // Manually set deployment URL from env
+    return process.env.NEXT_PUBLIC_URL;
+
+  // assume localhost
+  return `http://127.0.0.1:3000`;
+}

package/tsconfig.json

@@ -1,11 +1,11 @@
-{
-  "extends": "tsconfig/react-library.json",
-  "include": [
-    "."
-  ],
-  "exclude": [
-    "dist",
-    "build",
-    "node_modules"
-  ]
+{
+  "extends": "tsconfig/react-library.json",
+  "include": [
+    "."
+  ],
+  "exclude": [
+    "dist",
+    "build",
+    "node_modules"
+  ]
 }

package/dist/index.d.mts

@@ -1,72 +0,0 @@
-import { NextRequest } from 'next/server';
-import { WebServiceClient } from '@maxmind/geoip2-node';
-import z from 'zod';
-
-declare const eventTypes: readonly ["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported", "Error"];
-type EventType = (typeof eventTypes)[number];
-type EventTypeWithoutError = Exclude<EventType, "Error">;
-declare const EventsSchema: z.ZodObject<{
-    type: z.ZodEnum<["AppSetup", "ProtocolInstalled", "InterviewStarted", "InterviewCompleted", "DataExported", "Error"]>;
-    installationId: z.ZodString;
-    timestamp: z.ZodString;
-    isocode: z.ZodOptional<z.ZodString>;
-    error: z.ZodOptional<z.ZodObject<{
-        message: z.ZodString;
-        name: z.ZodString;
-        stack: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        message: string;
-        name: string;
-        stack?: string | undefined;
-    }, {
-        message: string;
-        name: string;
-        stack?: string | undefined;
-    }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported" | "Error";
-    installationId: string;
-    timestamp: string;
-    isocode?: string | undefined;
-    error?: {
-        message: string;
-        name: string;
-        stack?: string | undefined;
-    } | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}, {
-    type: "AppSetup" | "ProtocolInstalled" | "InterviewStarted" | "InterviewCompleted" | "DataExported" | "Error";
-    installationId: string;
-    timestamp: string;
-    isocode?: string | undefined;
-    error?: {
-        message: string;
-        name: string;
-        stack?: string | undefined;
-    } | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}>;
-type Event = z.infer<typeof EventsSchema>;
-type AnalyticsEvent = {
-    type: EventTypeWithoutError;
-    metadata?: Record<string, unknown>;
-};
-type AnalyticsError = {
-    type: "Error";
-    error: Error;
-    metadata?: Record<string, unknown>;
-};
-type AnalyticsEventOrError = AnalyticsEvent | AnalyticsError;
-type AnalyticsEventOrErrorWithTimestamp = AnalyticsEventOrError & {
-    timestamp: string;
-};
-type RouteHandlerConfiguration = {
-    platformUrl?: string;
-    installationId: string;
-    maxMindClient: WebServiceClient;
-};
-declare const createRouteHandler: ({ platformUrl, installationId, maxMindClient, }: RouteHandlerConfiguration) => (request: NextRequest) => Promise<Response>;
-declare const makeEventTracker: (endpoint?: string) => (event: AnalyticsEventOrError) => Promise<void>;
-
-export { AnalyticsError, AnalyticsEvent, AnalyticsEventOrError, AnalyticsEventOrErrorWithTimestamp, Event, EventType, EventsSchema, createRouteHandler, eventTypes, makeEventTracker };