@crimson-education/browser-logger 5.0.1-beta.3 → 5.0.1

package/src/reporters/posthogReporter.ts

@@ -0,0 +1,374 @@
+import posthog, { BeforeSendFn, CaptureResult, PostHogConfig, Properties } from 'posthog-js';
+import {
+  IReporter,
+  Metadata,
+  ReportError,
+  ReporterBreadcrumb,
+  ReporterConfigBase,
+  ReporterEvent,
+  ReporterFlag,
+  ReportUser,
+  ServiceInfo,
+} from '../types';
+
+type PostHogValue = Properties[string];
+
+type PostHogReporterSdkConfig = Partial<
+  Omit<
+    PostHogConfig,
+    | 'api_host'
+    | 'autocapture'
+    | 'before_send'
+    | 'bootstrap'
+    | 'capture_pageleave'
+    | 'capture_pageview'
+    | 'cross_subdomain_cookie'
+    | 'debug'
+    | 'defaults'
+    | 'disable_session_recording'
+    | 'loaded'
+    | 'person_profiles'
+    | 'persistence'
+    | 'persistence_name'
+  >
+>;
+
+export interface PostHogReporterConfig extends ReporterConfigBase {
+  /** The PostHog project API key. */
+  apiKey: string;
+  /** The PostHog ingest host, e.g. https://eu.i.posthog.com */
+  apiHost: string;
+  /** Optional PostHog bootstrap config. */
+  bootstrap?: PostHogConfig['bootstrap'];
+  /** Optional PostHog SDK defaults mode. */
+  defaults?: PostHogConfig['defaults'];
+  /** Optional PostHog before-send hook. */
+  beforeSend?: PostHogConfig['before_send'];
+  /** Controls PostHog autocapture. Defaults to true. */
+  autocapture?: PostHogConfig['autocapture'];
+  /** Controls automatic pageview capture. Defaults to history_change for SPAs. */
+  capturePageview?: PostHogConfig['capture_pageview'];
+  /** Controls automatic pageleave capture. Defaults to if_capture_pageview. */
+  capturePageleave?: PostHogConfig['capture_pageleave'];
+  /** Share cookies across subdomains. Defaults to true. */
+  crossSubdomainCookie?: PostHogConfig['cross_subdomain_cookie'];
+  /** PostHog persistence mode. */
+  persistence?: PostHogConfig['persistence'];
+  /** Optional persistence name. */
+  persistenceName?: PostHogConfig['persistence_name'];
+  /** Enable PostHog debug mode. */
+  debug?: PostHogConfig['debug'];
+  /** Controls when person processing happens. Defaults to identified_only. */
+  personProfiles?: PostHogConfig['person_profiles'];
+  /** Disable session recording at startup. */
+  disableSessionRecording?: boolean;
+  /**
+   * Compatibility alias for Datadog-style replay gating.
+   * Values <= 0 disable recording at startup; values > 0 leave it enabled.
+   */
+  replaySampleRate?: number;
+  /**
+   * When true, automatic pageview capture is disabled and `Logger.setPageName()`
+   * will emit manual `$pageview` events instead.
+   */
+  trackViewsManually?: boolean;
+  /** Optional PostHog loaded callback. */
+  loaded?: PostHogConfig['loaded'];
+  /** Optional raw PostHog SDK overrides for advanced use cases. */
+  sdkConfig?: PostHogReporterSdkConfig;
+}
+
+type CompatibilityUser = ReportUser & {
+  role?: unknown;
+  roles?: unknown;
+  userRole?: unknown;
+  userRoles?: unknown;
+};
+
+function hasActiveUser(user: ReportUser | null): user is ReportUser {
+  if (!user) {
+    return false;
+  }
+
+  return !!String(user.id ?? '').trim();
+}
+
+function getCurrentUrl(captureResult: CaptureResult): string | undefined {
+  const currentUrl = captureResult.properties?.$current_url;
+  if (typeof currentUrl === 'string' && currentUrl) {
+    return currentUrl;
+  }
+
+  if (typeof window !== 'undefined') {
+    return window.location.href;
+  }
+
+  return undefined;
+}
+
+function getUserRoleValue(user: CompatibilityUser | null, metadata: Metadata): PostHogValue | undefined {
+  const candidate =
+    user?.userRole ?? user?.role ?? user?.userRoles ?? user?.roles ?? metadata.userRole ?? metadata.userRoles;
+
+  return normalizeValue(candidate);
+}
+
+function buildCompatibilityProperties(
+  info: ServiceInfo,
+  metadata: Metadata,
+  user: CompatibilityUser | null,
+  captureResult: CaptureResult,
+): Properties {
+  const url = getCurrentUrl(captureResult);
+  const baseOrigin = typeof window !== 'undefined' ? window.location.origin : 'https://example.invalid';
+  const urlObject = url ? new URL(url, baseOrigin) : null;
+  const urlPath = urlObject?.pathname;
+  const pageName = typeof metadata.pageName === 'string' ? metadata.pageName : undefined;
+
+  return {
+    app_name: String(metadata.application ?? info.application ?? info.service),
+    domain: String(
+      metadata.domain ?? urlObject?.hostname ?? (typeof window !== 'undefined' ? window.location.hostname : ''),
+    ),
+    event_type: captureResult.event,
+    session_id: posthog.get_session_id(),
+    rum_session_id: posthog.get_session_id(),
+    user_id: user?.id,
+    user_email: user?.email,
+    user_name: user?.name ?? user?.username,
+    user_role: getUserRoleValue(user, metadata),
+    url,
+    url_path: urlPath,
+    view_id: posthog.getPageViewId(),
+    view_name: pageName,
+    browser: captureResult.properties?.$browser,
+    device: captureResult.properties?.$device_type,
+    geo: captureResult.properties?.$geoip_country_name ?? captureResult.properties?.$geoip_country_code,
+  };
+}
+
+function composeBeforeSend(
+  info: ServiceInfo,
+  currentMetadata: Metadata,
+  getCurrentUser: () => CompatibilityUser | null,
+  beforeSend?: PostHogReporterConfig['beforeSend'],
+): BeforeSendFn {
+  const beforeSendFns = Array.isArray(beforeSend) ? beforeSend : beforeSend ? [beforeSend] : [];
+
+  return (captureResult) => {
+    if (!captureResult) {
+      return captureResult;
+    }
+
+    captureResult.properties = {
+      ...captureResult.properties,
+      ...buildCompatibilityProperties(info, currentMetadata, getCurrentUser(), captureResult),
+    };
+
+    let nextResult: CaptureResult | null = captureResult;
+    for (const beforeSendFn of beforeSendFns) {
+      nextResult = beforeSendFn(nextResult);
+      if (!nextResult) {
+        return null;
+      }
+    }
+
+    return nextResult;
+  };
+}
+
+function normalizeError(error: unknown): Record<string, string | undefined> {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    };
+  }
+
+  return {
+    message: typeof error === 'string' ? error : JSON.stringify(error),
+  };
+}
+
+function normalizeValue(value: unknown): PostHogValue | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (value instanceof Error) {
+    return normalizeError(value);
+  }
+
+  if (Array.isArray(value)) {
+    const result = value
+      .map((item) => normalizeValue(item))
+      .filter((item): item is NonNullable<PostHogValue> => item !== undefined);
+    return result;
+  }
+
+  if (typeof value === 'object') {
+    const result: Properties = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      const normalized = normalizeValue(child);
+      if (normalized !== undefined) {
+        result[key] = normalized;
+      }
+    }
+    return result;
+  }
+
+  return String(value);
+}
+
+export function normalizeProperties(metadata?: Metadata): Properties | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+
+  const result: Properties = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    const normalized = normalizeValue(value);
+    if (normalized !== undefined && normalized !== null) {
+      result[key] = normalized;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function shouldDisableSessionRecording(config: PostHogReporterConfig): boolean {
+  if (config.disableSessionRecording !== undefined) {
+    return config.disableSessionRecording;
+  }
+
+  if (config.replaySampleRate !== undefined) {
+    return config.replaySampleRate <= 0;
+  }
+
+  return false;
+}
+
+export function posthogReporter(info: ServiceInfo, config: PostHogReporterConfig): IReporter {
+  const manualPageviews = config.trackViewsManually ?? false;
+  const currentMetadata: Metadata = {};
+  let currentUser: CompatibilityUser | null = null;
+
+  posthog.init(config.apiKey, {
+    api_host: config.apiHost,
+    autocapture: config.autocapture ?? true,
+    before_send: composeBeforeSend(info, currentMetadata, () => currentUser, config.beforeSend),
+    bootstrap: config.bootstrap,
+    capture_pageleave: manualPageviews ? false : config.capturePageleave ?? 'if_capture_pageview',
+    capture_pageview: manualPageviews ? false : config.capturePageview ?? 'history_change',
+    cross_subdomain_cookie: config.crossSubdomainCookie ?? true,
+    debug: config.debug ?? false,
+    defaults: config.defaults ?? '2025-05-24',
+    disable_session_recording: shouldDisableSessionRecording(config),
+    loaded: config.loaded ?? (() => {}),
+    persistence: config.persistence,
+    persistence_name: config.persistenceName,
+    person_profiles: config.personProfiles ?? 'identified_only',
+    ...config.sdkConfig,
+  });
+
+  const reporter: IReporter = {
+    ...config,
+    trackEvent: function (event: ReporterEvent): void {
+      posthog.capture(event.message, {
+        message: event.message,
+        level: event.level,
+        ...normalizeProperties(event.metadata),
+        ...normalizeProperties(event.tags),
+        ...normalizeProperties(event.metrics),
+      });
+    },
+    addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      posthog.capture(breadcrumb.message, {
+        message: breadcrumb.message,
+        category: breadcrumb.category,
+        breadcrumb: true,
+        ...normalizeProperties(breadcrumb.metadata),
+      });
+    },
+    addMetadata: function (metadata: Metadata): void {
+      const nextProperties = normalizeProperties(metadata);
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value === null) {
+          delete currentMetadata[key];
+          posthog.unregister(key);
+        } else {
+          currentMetadata[key] = value;
+        }
+      }
+
+      if (!nextProperties) {
+        return;
+      }
+
+      posthog.register(nextProperties);
+    },
+    setUser: function (user: ReportUser | null): void {
+      currentUser = user as CompatibilityUser | null;
+
+      if (!hasActiveUser(user)) {
+        posthog.reset();
+        const restoredMetadata = normalizeProperties(currentMetadata);
+        if (restoredMetadata) {
+          posthog.register(restoredMetadata);
+        }
+        currentUser = null;
+        return;
+      }
+
+      const { id, ...rest } = user;
+      posthog.identify(String(id), normalizeProperties(rest));
+      posthog.register({
+        user_id: String(id),
+        user_email: user.email,
+        user_name: user.name ?? user.username,
+        user_role: getUserRoleValue(user as CompatibilityUser, currentMetadata),
+      });
+    },
+    setRouteName: function (routeName: string): void {
+      reporter.addMetadata({ routeName });
+    },
+    setPageName: function (pageName: string): void {
+      if (manualPageviews) {
+        posthog.capture('$pageview', {
+          pageName,
+        });
+        return;
+      }
+
+      reporter.addMetadata({ pageName });
+    },
+    reportError: function (error: ReportError, metadata?: Metadata): void {
+      posthog.captureException(error, {
+        ...normalizeProperties(metadata),
+        ...normalizeError(error),
+      });
+    },
+    reportFeatureFlag: function (flag: ReporterFlag): void {
+      reporter.addMetadata({
+        [`featureFlag.${flag.name}`]: flag.value,
+      });
+    },
+    recordSession: function (): void {
+      posthog.startSessionRecording(true);
+    },
+    recordSessionStop: function (): void {
+      posthog.stopSessionRecording();
+    },
+  };
+
+  return reporter;
+}

package/src/types/reporter.ts

@@ -1,6 +1,8 @@
+import { AmplifyReporterConfig } from '../reporters/amplifyReporter';
 import { DatadogReporterConfig } from '../reporters/datadogReporter';
 import { GTMReporterConfig } from '../reporters/gtmReporter';
 import { LogReporterConfig } from '../reporters/logReporter';
+import { PostHogReporterConfig } from '../reporters/posthogReporter';
 import { LogLevel, Metadata } from './logger';
 
 export type ReporterConfigurations = {
@@ -16,6 +18,18 @@ export type ReporterConfigurations = {
    */
   datadog?: DatadogReporterConfig;
 
+  /**
+   * Amplify/Pinpoint reporter configuration.
+   * If not set, the amplify reporter will not be used.
+   */
+  amplify?: AmplifyReporterConfig;
+
+  /**
+   * PostHog reporter configuration.
+   * If not set, the PostHog reporter will not be used.
+   */
+  posthog?: PostHogReporterConfig;
+
   /**
    *  Google Tag Manager reporter configuration.
    * If not set, the gtm reporter will not be used.
@@ -30,6 +44,8 @@ export type Metrics = Record<string, number>;
 export type ServiceInfo = {
   /** The Application's name. */
   service: string;
+  /** Optional product/application identifier shared across services. */
+  application?: string;
   /** The Application's Environment */
   environment: string;
   /** The Application's Version. */