@crimson-education/browser-logger 5.0.0-beta.19 → 5.0.0-beta.20

package/src/reporters/amplifyReporter.ts

@@ -0,0 +1,486 @@
+import { identifyUser, record } from '@aws-amplify/analytics';
+// import { Endpoint, FinalizeRequestMiddleware } from '@aws-sdk/types';
+// import { HttpRequest } from '@aws-sdk/protocol-http';
+// import { PinpointClient, ServiceInputTypes, ServiceOutputTypes } from '@aws-sdk/client-pinpoint';
+
+import {
+  IReporter,
+  Metadata,
+  ReporterBreadcrumb,
+  ReporterConfigBase,
+  ReporterEvent,
+  ReportUser,
+  ServiceInfo,
+} from '../types';
+import { logger } from '../logger';
+// Note: fetchAuthSession was previously imported but unused; removing to satisfy linter
+import { Amplify } from 'aws-amplify';
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+type AttributeMap = Record<string, string[] | string | null>;
+
+type AmplifyAutoTrackSource = 'pageView' | 'event' | 'session';
+
+// Auto-tracking implementation for Gen2
+class AmplifyAutoTracker {
+  private config: AmplifyReporterConfig;
+  private allMetadata: AttributeMap;
+  private currentUser: ReportUser | null = null;
+  private sessionStartTime: number = Date.now();
+  private pageViewCount: number = 0;
+  private lastPageUrl: string = window.location.href;
+  private isPageVisible: boolean = !document.hidden;
+
+  constructor(config: AmplifyReporterConfig, allMetadata: AttributeMap) {
+    this.config = config;
+    this.allMetadata = allMetadata;
+    this.setupEventListeners();
+  }
+
+  private setupEventListeners() {
+    // Page visibility tracking
+    document.addEventListener('visibilitychange', () => {
+      this.isPageVisible = !document.hidden;
+      if (this.config.autoTrackSessions) {
+        this.trackSessionState();
+      }
+    });
+
+    // Page view tracking
+    if (this.config.autoTrackPageViews) {
+      // Delay initial page view to ensure Amplify is fully configured
+      // Using setTimeout(0) to defer to the next event loop tick
+      setTimeout(() => {
+        this.trackPageView();
+      }, 0);
+
+      // Track route changes for SPAs
+      let currentUrl = window.location.href;
+      const observer = new MutationObserver(() => {
+        if (window.location.href !== currentUrl) {
+          currentUrl = window.location.href;
+          this.trackPageView();
+        }
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+
+    // User interaction tracking
+    if (this.config.autoTrackEvents) {
+      this.setupInteractionTracking();
+    }
+  }
+
+  private trackPageView() {
+    this.pageViewCount++;
+    const pageViewEvent = {
+      message: 'Page View',
+      metadata: {
+        url: window.location.href,
+        title: document.title,
+        referrer: document.referrer,
+        pageViewCount: this.pageViewCount,
+        ...this.getAutoTrackMetadata('pageView'),
+      },
+    };
+
+    try {
+      record({
+        name: pageViewEvent.message,
+        attributes: asAttributeMap(
+          {
+            ...this.allMetadata,
+            ...pageViewEvent.metadata,
+          },
+          false,
+        ) as Record<string, string>,
+      });
+    } catch (error) {
+      logger.warn('Failed to record page view event', { error });
+    }
+  }
+
+  private trackSessionState() {
+    const sessionDuration = Date.now() - this.sessionStartTime;
+    const sessionEvent = {
+      message: this.isPageVisible ? 'Session Active' : 'Session Inactive',
+      metadata: {
+        sessionDuration,
+        isVisible: this.isPageVisible,
+        ...this.getAutoTrackMetadata('session'),
+      },
+    };
+
+    try {
+      record({
+        name: sessionEvent.message,
+        attributes: asAttributeMap(
+          {
+            ...this.allMetadata,
+            ...sessionEvent.metadata,
+          },
+          false,
+        ) as Record<string, string>,
+      });
+    } catch (error) {
+      logger.warn('Failed to record session state event', { error });
+    }
+  }
+
+  private setupInteractionTracking() {
+    const selectorPrefix = this.config.selectorPrefix ?? 'data-analytics-';
+
+    document.addEventListener('click', (event) => {
+      const target = event.target as HTMLElement;
+      if (!target) return;
+
+      // Find the closest element with analytics attributes
+      const analyticsElement = target.closest(`[${selectorPrefix}name]`);
+      if (!analyticsElement) return;
+
+      const analyticsName = analyticsElement.getAttribute(`${selectorPrefix}name`);
+      if (!analyticsName) return;
+
+      const interactionEvent = {
+        message: 'User Interaction',
+        metadata: {
+          elementName: analyticsName,
+          elementType: target.tagName.toLowerCase(),
+          elementText: target.textContent?.slice(0, 100),
+          interactionType: 'click',
+          ...this.getAutoTrackMetadata('event'),
+        },
+      };
+
+      try {
+        record({
+          name: interactionEvent.message,
+          attributes: asAttributeMap(
+            {
+              ...this.allMetadata,
+              ...interactionEvent.metadata,
+            },
+            false,
+          ) as Record<string, string>,
+        });
+      } catch (error) {
+        logger.warn('Failed to record interaction event', { error });
+      }
+    });
+  }
+
+  private getAutoTrackMetadata(source: AmplifyAutoTrackSource): Metadata {
+    const { beforeAutoTrack } = this.config;
+    return typeof beforeAutoTrack === 'function' ? (beforeAutoTrack(source) ?? {}) : {};
+  }
+
+  public setUser(user: ReportUser | null) {
+    this.currentUser = user;
+  }
+
+  public updateMetadata(metadata: AttributeMap) {
+    Object.assign(this.allMetadata, metadata);
+  }
+}
+
+export interface AmplifyReporterConfig extends ReporterConfigBase {
+  /**
+   * AWS Region for Amplify.
+   */
+  region: string;
+  /**
+   * The Identity Pool Id to use for reporting, if set to false, Auth.configure is not called.
+   * This must be called manually for the reporter to work.
+   */
+  identityPoolId: string;
+  /**
+   * The Pinpoint App Id to report to.
+   */
+  analyticsAppId: string;
+  /** Optional proxy URL */
+  proxyUrl?: string;
+  /**
+   * The Cognito User Pool to configure in Auth.configure.
+   * If you are using Cognito, it is better to set identityPoolId to false and configure Auth manually.
+   */
+  userPoolId?: string;
+  /**
+   * The Cognito Web Client Id to configure in Auth.configure.
+   * If you are using Cognito, it is better to set identityPoolId to false and configure Auth manually.
+   */
+  userPoolWebClientId?: string;
+
+  /**
+   * If you want to track which page/url in your webapp is the most frequently viewed one, you can use this feature.
+   * It will automatically send events containing url information when the page is visited.
+   */
+  autoTrackPageViews?: boolean;
+  /**
+   * If you want to track user interactions with elements on the page, you can use this feature.
+   * All you need to do is attach the specified selectors to your dom element and turn on the auto tracking.
+   */
+  autoTrackEvents?: boolean;
+  /**
+   * A web session can be defined in different ways.
+   * To keep it simple we define that the web session is active when the page is not hidden and inactive when the page is hidden.
+   */
+  autoTrackSessions?: boolean;
+  /**
+   * Optional function to run before autotracked analytics events are sent out.
+   * The returned metadata is attached to the event.
+   */
+  beforeAutoTrack?(source: AmplifyAutoTrackSource): Metadata | undefined;
+
+  /**
+   * The data tag prefix to use for attributing HTML elements. Defaults to data-analytics-
+   */
+  selectorPrefix?: string;
+
+  /**
+   * Modify how the reporter sends events to Amplify.
+   */
+  buffering?: AmplifyReporterBufferingConfig;
+}
+
+/**
+ * Configuration options for the buffering behavior of Pinpoint's event tracker.
+ *
+ * @see https://docs.amplify.aws/lib/analytics/getting-started/q/platform/js/#set-up-existing-analytics-backend
+ */
+type AmplifyReporterBufferingConfig = {
+  /** Number of items to buffer for sending. */
+  bufferSize?: number;
+  /** Number of events sent each time Pinpoint flushes. */
+  flushSize?: number;
+  /** Interval Pinpoint flushes analytics events. Measured in milliseconds. */
+  flushInterval?: number;
+  /** The maximum number of times Pinpoint will retry to send an event. */
+  resendLimit?: number;
+};
+
+export function amplifyReporter(info: ServiceInfo, config: AmplifyReporterConfig): IReporter {
+  Amplify.configure({
+    Auth: {
+      Cognito: {
+        identityPoolId: config.identityPoolId,
+        allowGuestAccess: true,
+      },
+    },
+    Analytics: {
+      Pinpoint: {
+        appId: config.analyticsAppId,
+        region: config.region,
+        ...config.buffering,
+      },
+    },
+  });
+
+  const allMetadata = asAttributeMap({
+    appName: info.service,
+    service: info.service,
+    domain: window.location.host,
+    environment: info.environment,
+    version: info.version,
+  });
+
+  // Initialize auto-tracker for Gen2
+  const autoTracker = new AmplifyAutoTracker(config, allMetadata);
+
+  if (config.proxyUrl) {
+    // installPinpointProxy(new URL(config.proxyUrl));
+  }
+
+  const reporter: IReporter = {
+    trackEvent: function (event: ReporterEvent): void {
+      try {
+        record({
+          name: event.message,
+          attributes: asAttributeMap(
+            {
+              ...allMetadata,
+              ...event.metadata,
+              ...event.tags,
+            },
+            false,
+          ) as Record<string, string>,
+          metrics: event.metrics,
+        });
+      } catch (error) {
+        logger.warn('Failed to record event', { error, eventName: event.message });
+      }
+    },
+    addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      reporter.trackEvent({
+        message: breadcrumb.message,
+        metadata: {
+          category: breadcrumb.category,
+          ...breadcrumb.metadata,
+        },
+      });
+    },
+    addMetadata: function (metadata: Metadata): void {
+      Object.assign(allMetadata, asAttributeMap(metadata, true));
+      autoTracker.updateMetadata(asAttributeMap(metadata, true));
+      // Note: updateEndpoint is not available in Amplify v7
+      // Metadata updates would need to be handled differently
+    },
+    setUser: function (user: ReportUser | null): void {
+      const userMetadata = user
+        ? asAttributeMap({
+            userId: user.id,
+          })
+        : {};
+      Object.assign(allMetadata, asAttributeMap(userMetadata, true));
+      autoTracker.setUser(user);
+      // Only call identifyUser when we have a valid user ID
+      // Calling with empty string can cause issues with Pinpoint USER_ID
+      if (user?.id) {
+        try {
+          identifyUser({
+            userId: user.id,
+            userProfile: {
+              email: user.email,
+            },
+          });
+        } catch (error) {
+          // Credentials may not be ready yet, log warning and continue
+          // The userId is still stored in allMetadata for event tracking
+          logger.warn('Failed to identify user in Pinpoint', { error });
+        }
+      }
+    },
+    setRouteName: function (routeName: string): void {
+      reporter.addMetadata({ routeName });
+    },
+    setPageName: function (pageName: string): void {
+      reporter.addMetadata({ pageName });
+    },
+  };
+
+  return reporter;
+}
+
+/**
+ * Pinpoint has strict attribute name and value length limits
+ */
+export function asAttributeMap(values: Record<string, unknown>, groupValues = true): AttributeMap {
+  const attributeMap = buildAttributeMap(values, undefined, groupValues);
+
+  const checkedEntries = Object.entries(attributeMap).map(([key, value]) => {
+    const truncatedKey = key.length > 50 ? `___${key.slice(-47)}` : key;
+    const truncatedValue = Array.isArray(value)
+      ? (value?.map((val) => val.slice(0, 100)) ?? null)
+      : (value?.slice(0, 100) ?? null);
+
+    return [truncatedKey, truncatedValue];
+  });
+
+  // Pinpoint only accepts 40 attributes
+  if (checkedEntries.length > 40) {
+    logger.error(`Amplify only allows 40 attributes per event, truncating to 40 attributes`, {
+      attributes: checkedEntries,
+    });
+    checkedEntries.length = 40;
+  }
+
+  return Object.fromEntries(checkedEntries);
+}
+
+/**
+ * Pinpoint expects `endpoint.attributes` and `endpoint.userAttributes` to have
+ * values which are string arrays. This function takes in an object and ensures
+ * all of its values are of type `string[]` to appease Pinpoint.
+ */
+export function buildAttributeMap(
+  values: Record<string, any>,
+  parentKey: string | undefined = undefined,
+  groupValues = true,
+): AttributeMap {
+  const valuesWithStringArrays: AttributeMap = {};
+
+  Object.entries(values).forEach(([key, value]) => {
+    const combinedKey = parentKey ? [parentKey, key].join('.') : key;
+
+    // Only treat undefined or null as empty; avoid converting falsy values like ''/0/false to null
+    if (value === undefined || value === null) {
+      // For event attributes (groupValues === false), Pinpoint rejects null values.
+      // In that case we omit the key entirely to avoid "Event attribute value can not be null".
+      if (groupValues) {
+        valuesWithStringArrays[combinedKey] = null;
+      }
+    } else if (groupValues && Array.isArray(value)) {
+      valuesWithStringArrays[combinedKey] = value.map((element) =>
+        typeof element === 'string' ? element : JSON.stringify(element),
+      );
+    } else if (typeof value === 'object') {
+      const flattenedAttribute = buildAttributeMap(value, combinedKey, groupValues);
+      Object.assign(valuesWithStringArrays, flattenedAttribute);
+    } else {
+      const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
+      valuesWithStringArrays[combinedKey] = groupValues ? [stringValue] : stringValue;
+    }
+  });
+
+  return valuesWithStringArrays;
+}
+
+// function installPinpointProxy(proxyUrl: URL) {
+//   // No public API for overriding where the Pinpoint client sends events to... 🤮
+//   // In theory you can pass in an `endpoint` to the Pinpoint client's constructor like any other AWS
+//   // client, but Amplify's analytics doesn't expose anything we can use to get an endpoint threaded
+//   // down to the Pinpoint client's constructor.
+//   //
+//   // The Pinpoint client _also_ isn't available synchronously because it is instantiated when events
+//   // get sent out, and then reconfigured whenever the API credentials change. We need to hook `_initClients`
+//   // to ensure that the Pinpoint client being used is always patched with our custom endpoint.
+//   const provider = (globalThis as any).Analytics?.getPluggable?.('AWSPinpoint') as any;
+//   if (!provider || typeof provider._initClients !== 'function') {
+//     logger.error(
+//       'Installation of the Pinpoint proxy failed. This likely means the internals of the @aws-amplify/analytics package have changed.',
+//     );
+//     return;
+//   }
+
+//   const originalInitClients = provider._initClients;
+//   const requestMiddleware: FinalizeRequestMiddleware<ServiceInputTypes, ServiceOutputTypes> =
+//     (next) => async (args) => {
+//       const pinpointClient = provider.pinpointClient as PinpointClient | undefined;
+
+//       if (pinpointClient && proxyUrl.pathname !== '/' && HttpRequest.isInstance(args.request)) {
+//         // Add proxyUrl.pathname to final request url if it was provided
+//         const shouldStripSlash = proxyUrl.pathname.endsWith('/');
+//         args.request.path = `${proxyUrl.pathname}${args.request.path.slice(shouldStripSlash ? 1 : 0)}`;
+
+//         // Wrap request body so the proxy has signing info
+//         if (typeof args.request.body === 'string') {
+//           const credentials = await pinpointClient.config.credentials();
+//           args.request.body = JSON.stringify({
+//             credentials,
+//             data: JSON.parse(args.request.body),
+//           });
+//         }
+//       }
+
+//       return next(args);
+//     };
+
+//   provider._initClients = async (credentials: unknown) => {
+//     const result = await originalInitClients.call(provider, credentials);
+//     const pinpointClient = provider.pinpointClient as PinpointClient | undefined;
+
+//     if (pinpointClient) {
+//       pinpointClient.config.endpoint = (): Promise<Endpoint> =>
+//         Promise.resolve({
+//           hostname: proxyUrl.hostname,
+//           // Passing proxyUrl.pathname here doesn't work; it gets overridden
+//           path: '/',
+//           port: undefined,
+//           protocol: proxyUrl.protocol,
+//         });
+
+//       pinpointClient.middlewareStack.remove(requestMiddleware);
+//       pinpointClient.middlewareStack.add(requestMiddleware, { step: 'finalizeRequest' });
+//     }
+//     return result;
+//   };
+// }