@crimson-education/browser-logger 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimson-education/browser-logger",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "An abstract logger and reporting utility for browser environments",
   "scripts": {
     "prepack": "npm run build",
@@ -44,7 +44,8 @@
     "typescript": "^4.1.2"
   },
   "files": [
-    "lib"
+    "lib",
+    "src"
   ],
   "main": "lib/index.js"
 }

package/src/index.ts

@@ -0,0 +1,143 @@
+import { ILogger, Metadata, ReportError, ReportUser, ServiceInfo } from './types';
+import { IReporter, ReporterBreadcrumb, ReporterEvent, TrackedReporterEvent } from './reporters';
+import { consoleLogger } from './utils';
+import { datadogLogger, datadogReporter, DatadogReporterConfig } from './reporters/datadogReporter';
+import { gtmReporter } from './reporters/gtmReporter';
+import { amplifyReporter, AmplifyReporterConfig } from './reporters/amplifyReporter';
+
+export * from './types';
+
+export let logger: ILogger | null = null;
+
+export type ReporterConfig = ServiceInfo & {
+  // Datadog
+  datadog?: DatadogReporterConfig;
+
+  // Amplify/Pinpoint
+  amplify?: AmplifyReporterConfig;
+
+  // Google Tag Manager
+  gtm?: boolean;
+};
+
+const reporters: IReporter[] = [];
+let initialized = false;
+let ddInitialized = false;
+
+export function init(config: ReporterConfig) {
+  initialized = true;
+
+  if (config.datadog) {
+    reporters.push(datadogReporter(config, config.datadog));
+    ddInitialized = true;
+  }
+
+  if (config.amplify) {
+    reporters.push(amplifyReporter(config, config.amplify));
+  }
+
+  if (config.gtm) {
+    reporters.push(gtmReporter());
+  }
+
+  if (config.defaultMetadata) {
+    for (const reporter of reporters) {
+      reporter.addMetadata(config.defaultMetadata);
+    }
+  }
+
+  logger = createLogger('Reporter');
+}
+
+export function trackEvent(event: ReporterEvent): void {
+  for (const reporter of reporters) {
+    reporter.trackEvent(event);
+  }
+}
+
+export function addBreadcrumb(breadcrumb: ReporterBreadcrumb): void {
+  for (const reporter of reporters) {
+    reporter.addBreadcrumb(breadcrumb);
+  }
+}
+
+export function addMetadata(metadata: Metadata): void {
+  for (const reporter of reporters) {
+    reporter.addMetadata(metadata);
+  }
+}
+
+export function setUser(user: ReportUser | null): void {
+  for (const reporter of reporters) {
+    reporter.setUser(user);
+  }
+}
+
+export function setRouteName(routeName: string): void {
+  for (const reporter of reporters) {
+    reporter.setRouteName(routeName);
+  }
+}
+
+export function setPageName(pageName: string): void {
+  for (const reporter of reporters) {
+    reporter.setPageName(pageName);
+  }
+}
+
+export function reportError(error: ReportError, metadata?: Metadata): void {
+  for (const reporter of reporters) {
+    reporter.reportError(error, metadata);
+  }
+}
+
+export function recordSession(): void {
+  for (const reporter of reporters) {
+    reporter.recordSession();
+  }
+}
+
+export function recordSessionStop(): void {
+  for (const reporter of reporters) {
+    reporter.recordSessionStop();
+  }
+}
+
+export function trackEventSinceLastAction(event: ReporterEvent): void {
+  const lastEvent = getLastTrackedEvent();
+  if (lastEvent) {
+    const duration = new Date().getTime() - lastEvent.occurred.getTime();
+    trackEvent({
+      ...event,
+      metadata: {
+        ...event.metadata,
+        lastEventName: lastEvent.message,
+        timeSinceLastEvent: duration,
+      },
+    });
+  } else {
+    trackEvent(event);
+  }
+  sessionStorage.setItem('loggerLastEvent', JSON.stringify({ ...event, occurred: new Date() }));
+}
+
+export function getLastTrackedEvent(): TrackedReporterEvent | null {
+  const eventStr = sessionStorage.getItem('loggerLastEvent');
+  if (!eventStr) return null;
+
+  const event: TrackedReporterEvent = JSON.parse(eventStr);
+  event.occurred = new Date(event.occurred);
+  return event;
+}
+
+export function createLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
+  if (!initialized) {
+    throw new Error('You must call init on BrowserLogger before creating a logger');
+  }
+
+  if (ddInitialized) {
+    return datadogLogger(name, options);
+  } else {
+    return consoleLogger(name, options);
+  }
+}

package/src/reporters/amplifyReporter.test.ts

@@ -0,0 +1,74 @@
+import { asAttributeMap, filterAttributeMap } from './amplifyReporter';
+
+describe('amplifyReporter', () => {
+  it('should convert all attribute values to arrays of strings', () => {
+    const testMetadata = { a: 'a', d: ['e', 'f'] };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap.a).toEqual(['a']);
+    expect(attributeMap.d).toEqual(['e', 'f']);
+  });
+
+  it('should handle undefined / null attributes', () => {
+    const testMetadata = { a: null, d: undefined };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap.a).toBeNull();
+    expect(attributeMap.d).toBeNull();
+  });
+
+  it('should flatten hierarchies', () => {
+    const testMetadata = { foo: { bar: 'baz' } };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap['foo.bar']).toEqual(['baz']);
+  });
+
+  it('should stringify non-string array members', () => {
+    const testMetadata = { foo: 5, bar: [{ baz: 'maz' }] };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap.foo).toEqual(['5']);
+    expect(typeof attributeMap.bar?.[0]).toEqual('string');
+  });
+
+  it('should truncate attribute names', () => {
+    const testMetadata = { thisIsAVeryVeryLongAttributeNameThatNeedsToBeTruncated: 5 };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap.___VeryVeryLongAttributeNameThatNeedsToBeTruncated).toEqual(['5']);
+  });
+
+  it('should truncate attribute values', () => {
+    const testMetadata = {
+      a: 'ThisIsAVeryLongStringThatNeedsToBeTruncatedTo100CharsOrElseThereWillBeAProblemWithSendingTheBeautifulDataToPinpoint',
+    };
+    const attributeMap = asAttributeMap(testMetadata);
+
+    expect(attributeMap.a).toEqual([
+      'ThisIsAVeryLongStringThatNeedsToBeTruncatedTo100CharsOrElseThereWillBeAProblemWithSendingTheBeautifu',
+    ]);
+  });
+
+  it('should not group values into arrays when groupValues===false', () => {
+    const testMetadata = {
+      a: '5',
+    };
+
+    const attributeMap = asAttributeMap(testMetadata, false);
+    expect(attributeMap.a).toEqual('5');
+  });
+
+  it('should remove attributes which match the ignore patterns', () => {
+    const inputAttributeMap = {
+      includeme: '5',
+      excludeme: 'false',
+      differentProp: 'boo',
+    };
+
+    const filtered = filterAttributeMap(inputAttributeMap, [/exclude/g, /Prop/g]);
+    expect(filtered['includeme']).toBeTruthy();
+    expect(filtered['excludeme']).toBeFalsy();
+    expect(filtered['differentProp']).toBeFalsy();
+  });
+});

package/src/reporters/amplifyReporter.ts

@@ -0,0 +1,208 @@
+import { IReporter, ReporterBreadcrumb, ReporterEvent } from '.';
+import { Metadata, ReportUser, ServiceInfo } from '../types';
+import { Auth } from '@aws-amplify/auth';
+import { Analytics } from '@aws-amplify/analytics';
+
+export type AmplifyReporterConfig = {
+  region: string;
+  identityPoolId: string;
+  analyticsAppId: string;
+  autoTrackPageViews?: boolean;
+  autoTrackEvents?: boolean;
+  autoTrackSessions?: boolean;
+  selectorPrefix?: string;
+  ignoreBreadcrumbCategories?: string[];
+  buffering?: AmplifyReporterBufferingConfig;
+  userPoolId?: string;
+  userPoolWebClientId?: string;
+  ignoreMetadataPatterns?: RegExp[];
+};
+
+/**
+ * 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 {
+  Auth.configure({
+    region: config.region,
+    identityPoolId: config.identityPoolId,
+    userPoolId: config.userPoolId,
+    userPoolWebClientId: config.userPoolWebClientId,
+  });
+
+  const allMetadata = asAttributeMap({
+    appName: info.service,
+    service: info.service,
+    domain: window.location.host,
+    environment: info.service,
+    version: info.version,
+  });
+
+  Analytics.configure({
+    region: config.region,
+    appId: config.analyticsAppId,
+    autoSessionRecord: config.autoTrackSessions,
+    endpoint: {
+      attributes: allMetadata,
+    },
+    ...config.buffering,
+  });
+
+  if (config.autoTrackPageViews) {
+    Analytics.autoTrack('pageView', {
+      enable: true,
+      eventName: 'pageView',
+      type: 'SPA',
+      provider: 'AWSPinpoint',
+    });
+  }
+
+  if (config.autoTrackEvents) {
+    Analytics.autoTrack('event', {
+      enable: true,
+      selectorPrefix: config.selectorPrefix ?? 'data-analytics-',
+    });
+  }
+
+  const reporter: IReporter = {
+    trackEvent: function (event: ReporterEvent): void {
+      Analytics.record({
+        name: event.message,
+        attributes: asAttributeMap(
+          {
+            ...event.metadata,
+            ...event.tags,
+          },
+          false,
+          config.ignoreMetadataPatterns,
+        ) as Record<string, string>,
+        metrics: event.metrics,
+      });
+    },
+    addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      if (breadcrumb.category && config.ignoreBreadcrumbCategories?.includes(breadcrumb.category)) {
+        return;
+      }
+
+      reporter.trackEvent({
+        message: breadcrumb.message,
+        metadata: {
+          category: breadcrumb.category,
+          ...breadcrumb.metadata,
+        },
+      });
+    },
+    addMetadata: function (metadata: Metadata): void {
+      Object.assign(allMetadata, asAttributeMap(metadata, true, config.ignoreMetadataPatterns));
+      Analytics.updateEndpoint({
+        attributes: allMetadata,
+      }).catch(() => {
+        // Swallow; see: https://crimsonhq.slack.com/archives/G4UN6Q4KF/p1648599302847539
+      });
+    },
+    setUser: function (user: ReportUser | null): void {
+      Analytics.updateEndpoint({
+        userId: user?.id ?? '',
+        userAttributes: user
+          ? asAttributeMap({
+              id: user.id,
+              email: user.email,
+              name: user.name ?? user.email,
+              username: user.username,
+            })
+          : {},
+      }).catch(() => {
+        // Swallow; see: https://crimsonhq.slack.com/archives/G4UN6Q4KF/p1648599302847539
+      });
+    },
+    setRouteName: function (routeName: string): void {
+      reporter.addMetadata({ routeName });
+    },
+    setPageName: function (pageName: string): void {
+      reporter.addMetadata({ pageName });
+    },
+    reportError: function (): void {},
+    recordSession: function (): void {},
+    recordSessionStop: function (): void {},
+  };
+
+  return reporter;
+}
+
+type AttributeMap = Record<string, string[] | string | null>;
+
+/**
+ * Pinpoint has strict attribute name and value length limits
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function asAttributeMap(
+  values: Record<string, any>,
+  groupValues = true,
+  ignorePatterns: RegExp[] = [],
+): AttributeMap {
+  const attributeMap = buildAttributeMap(values, undefined, groupValues);
+  const filteredAttributeMap = filterAttributeMap(attributeMap, ignorePatterns);
+
+  const checkedEntries = Object.entries(filteredAttributeMap).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];
+  });
+
+  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(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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;
+
+    if (!value) {
+      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;
+}
+
+export function filterAttributeMap(attributes: AttributeMap | Record<string, string>, ignorePatterns: RegExp[]) {
+  const entries = Object.entries(attributes);
+
+  return Object.fromEntries(entries.filter(([key]) => !ignorePatterns.some((pattern) => pattern.test(key))));
+}

package/src/reporters/datadogReporter.ts

@@ -0,0 +1,208 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { IReporter, ReporterBreadcrumb, ReporterEvent } from '.';
+import { Metadata, Profiler, ReportError, ReportUser, ServiceInfo } from '../types';
+import { datadogLogs, HandlerType, StatusType } from '@datadog/browser-logs';
+import { datadogRum, DefaultPrivacyLevel } from '@datadog/browser-rum';
+import { ILogger, LogLevel } from '..';
+
+export type DatadogReporterConfig = {
+  applicationId: string;
+  clientToken: string;
+  version?: string;
+  site?: string;
+  proxyUrl?: string;
+  forwardConsoleLogs?: boolean;
+  trackInteractions?: boolean;
+  sampleRate?: number;
+  replaySampleRate?: number;
+  defaultPrivacyLevel?: DefaultPrivacyLevel;
+  useSecureSessionCookie?: boolean;
+  useCrossSiteSessionCookie?: boolean;
+  allowedTracingOrigins?: (string | RegExp)[];
+  trackSessionAcrossSubdomains?: boolean;
+  actionNameAttribute?: string;
+  trackViewsManually?: boolean;
+};
+
+function getDatadogStatusType(level: LogLevel): StatusType {
+  switch (level) {
+    case LogLevel.Error:
+      return StatusType.error;
+
+    case LogLevel.Warn:
+      return StatusType.warn;
+
+    case LogLevel.Info:
+      return StatusType.info;
+
+    case LogLevel.Debug:
+    default:
+      return StatusType.debug;
+  }
+}
+
+export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig): IReporter {
+  const isLocalhost = window.location.hostname === 'localhost';
+
+  datadogLogs.init({
+    site: config.site,
+    proxyUrl: config.proxyUrl,
+    clientToken: config.clientToken,
+    service: info.service,
+    env: info.environment,
+    version: config.version ?? info.version,
+
+    useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
+    useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
+    trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
+
+    forwardErrorsToLogs: config.forwardConsoleLogs ?? false,
+  });
+
+  datadogRum.init({
+    site: config.site,
+    proxyUrl: config.proxyUrl,
+    clientToken: config.clientToken,
+    applicationId: config.applicationId,
+    service: info.service,
+    env: info.environment,
+    version: config.version ?? info.version,
+
+    useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
+    useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
+    trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
+
+    // Set sampleRate to 100 to capture 100%
+    // of transactions for performance monitoring.
+    sampleRate: config.sampleRate ?? 100,
+    replaySampleRate: config.replaySampleRate ?? 100,
+    trackInteractions: config.trackInteractions ?? false,
+    defaultPrivacyLevel: config.defaultPrivacyLevel ?? 'mask-user-input',
+    allowedTracingOrigins: config.allowedTracingOrigins,
+    actionNameAttribute: config.actionNameAttribute ?? 'data-analytics-name',
+    trackViewsManually: config.trackViewsManually ?? false,
+  });
+
+  const reporter: IReporter = {
+    trackEvent: function (event: ReporterEvent): void {
+      const context = {
+        level: event.level,
+        ...event.metadata,
+        ...event.tags,
+        ...event.metrics,
+      };
+      datadogRum.addAction(event.message, context);
+      datadogLogs.logger?.log(event.message, context, getDatadogStatusType(event.level ?? LogLevel.Info));
+    },
+    addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      const context = {
+        ...breadcrumb.metadata,
+        category: breadcrumb.category,
+      };
+      datadogRum.addAction(breadcrumb.message, context);
+    },
+    addMetadata: function (metadata: Metadata): void {
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value !== null) {
+          datadogRum.addRumGlobalContext(key, value);
+          datadogLogs.addLoggerGlobalContext(key, value);
+        } else {
+          datadogRum.removeRumGlobalContext(key);
+          datadogLogs.removeLoggerGlobalContext(key);
+        }
+      }
+    },
+    setUser: function (user: ReportUser | null): void {
+      if (user) {
+        datadogRum.setUser({
+          id: user.id,
+          email: user.email,
+          name: user.name ?? user.email,
+        });
+
+        datadogLogs.addLoggerGlobalContext('user_id', user.id);
+        datadogLogs.addLoggerGlobalContext('user_email', user.email);
+        datadogLogs.addLoggerGlobalContext('user_username', user.username);
+      } else {
+        datadogRum.removeUser();
+
+        datadogLogs.removeLoggerGlobalContext('user_id');
+        datadogLogs.removeLoggerGlobalContext('user_email');
+        datadogLogs.removeLoggerGlobalContext('user_username');
+      }
+    },
+    setRouteName: function (routeName: string): void {
+      reporter.addMetadata({ routeName });
+    },
+    setPageName: function (pageName: string): void {
+      if (config.trackViewsManually) {
+        datadogRum.startView(pageName);
+      } else {
+        reporter.addMetadata({ pageName });
+      }
+    },
+    reportError: function (error: ReportError, metadata?: Metadata): void {
+      // Note, datadog should pick up the console error above
+      datadogRum.addError(error, metadata);
+    },
+    recordSession: function (): void {
+      datadogRum.startSessionReplayRecording();
+    },
+    recordSessionStop: function (): void {
+      datadogRum.stopSessionReplayRecording();
+    },
+  };
+  return reporter;
+}
+
+export function datadogLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
+  const loggerName = name ?? 'root';
+  const ddLogger = datadogLogs.createLogger(loggerName, {
+    context: options?.metadata,
+  });
+  // Send to datadog and console.
+  ddLogger.setHandler([HandlerType.http, HandlerType.console]);
+
+  const logger: ILogger = {
+    startTimer: function (): Profiler {
+      const start = new Date();
+
+      return {
+        logger: this,
+        done: ({ message, level } = {}) => {
+          const duration = new Date().getTime() - start.getTime();
+          logger[level ?? LogLevel.Info](message ?? 'Timer Completed', { duration });
+          return true;
+        },
+      };
+    },
+    child: function (metadata?: Metadata, name?: string): ILogger {
+      return datadogLogger(name ?? `${loggerName}.child`, metadata);
+    },
+    log: (level: LogLevel, message: string, metadata?: any) => {
+      switch (level) {
+        case LogLevel.Debug:
+          ddLogger.debug(message, metadata);
+          break;
+
+        case LogLevel.Info:
+          ddLogger.info(message, metadata);
+          break;
+
+        case LogLevel.Warn:
+          ddLogger.warn(message, metadata);
+          break;
+
+        case LogLevel.Error:
+          ddLogger.error(message, metadata);
+          break;
+      }
+      return logger;
+    },
+    debug: (message: string, metadata?: any) => logger.log(LogLevel.Debug, message, metadata),
+    info: (message: string, metadata?: any) => logger.log(LogLevel.Info, message, metadata),
+    warn: (message: string, metadata?: any) => logger.log(LogLevel.Warn, message, metadata),
+    error: (message: string, metadata?: any) => logger.log(LogLevel.Error, message, metadata),
+  };
+  return logger;
+}

package/src/reporters/gtmReporter.ts

@@ -0,0 +1,47 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { IReporter, ReporterBreadcrumb, ReporterEvent } from '.';
+import { Metadata, ReportUser } from '../types';
+
+declare global {
+  interface Window {
+    dataLayer?: Record<string, any>[];
+  }
+}
+
+export function gtmReporter(): IReporter {
+  const reporter: IReporter = {
+    addMetadata: function (metadata: Metadata): void {
+      window.dataLayer?.push(metadata);
+    },
+    trackEvent: function (event: ReporterEvent): void {
+      reporter.addMetadata({
+        ...event.metadata,
+        ...event.tags,
+        ...event.metrics,
+        event: event.message,
+        level: event.level,
+      });
+    },
+    addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      reporter.addMetadata({
+        ...breadcrumb.metadata,
+        event: breadcrumb.message,
+      });
+    },
+    setUser: function (user: ReportUser | null): void {
+      if (user) {
+        reporter.addMetadata({ user });
+      }
+    },
+    setRouteName: function (routeName: string): void {
+      reporter.addMetadata({ routeName });
+    },
+    setPageName: function (pageName: string): void {
+      reporter.addMetadata({ pageName });
+    },
+    reportError: function (): void {},
+    recordSession: function (): void {},
+    recordSessionStop: function (): void {},
+  };
+  return reporter;
+}

package/src/reporters/index.ts

@@ -0,0 +1,32 @@
+import { LogLevel } from '..';
+import { Metadata, Metrics, ReportError, ReportUser } from '../types';
+
+export interface ReporterEvent {
+  level?: LogLevel;
+  message: string;
+  metadata?: Metadata | undefined;
+  tags?: Metadata | undefined;
+  metrics?: Metrics | undefined;
+}
+
+export interface TrackedReporterEvent extends ReporterEvent {
+  occurred: Date;
+}
+
+export interface ReporterBreadcrumb {
+  message: string;
+  category?: string | undefined;
+  metadata?: Metadata | undefined;
+}
+
+export interface IReporter {
+  trackEvent(event: ReporterEvent): void;
+  addBreadcrumb(breadcrumb: ReporterBreadcrumb): void;
+  addMetadata(metadata: Metadata): void;
+  setUser(user: ReportUser | null): void;
+  setRouteName(routeName: string): void;
+  setPageName(pageName: string): void;
+  reportError(error: ReportError, metadata?: Metadata): void;
+  recordSession(): void;
+  recordSessionStop(): void;
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type Metadata = Record<string, any>;
+
+export type Metrics = Record<string, number>;
+
+export type ServiceInfo = {
+  service: string;
+  environment: string;
+  version: string;
+  defaultMetadata?: Metadata;
+};
+
+export type ReportUser = { id: string; email?: string; username?: string; name?: string };
+
+export type ReportError = Error | string;
+
+export enum LogLevel {
+  Debug = 'debug',
+  Info = 'info',
+  Warn = 'warn',
+  Error = 'error',
+}
+
+export interface LogLevelMethod {
+  (message: string, metadata?: any): ILogger;
+  (message: string, ...meta: any[]): ILogger;
+  (message: any): ILogger;
+}
+
+export interface LogMethod {
+  (level: LogLevel, message: string, metadata?: any): ILogger;
+  (level: LogLevel, message: string, ...meta: any[]): ILogger;
+  (level: LogLevel, message: any): ILogger;
+}
+
+export interface Profiler {
+  logger: ILogger;
+  done(info?: { message?: string; level?: LogLevel }): boolean;
+}
+
+export interface ILogger {
+  startTimer(): Profiler;
+  child(metadata?: Metadata, name?: string): ILogger;
+
+  log: LogMethod;
+  debug: LogLevelMethod;
+  info: LogLevelMethod;
+  warn: LogLevelMethod;
+  error: LogLevelMethod;
+}

package/src/utils.ts

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ILogger, Profiler, LogMethod, LogLevelMethod, Metadata, LogLevel } from '.';
+
+export function consoleLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
+  const logger: ILogger = {
+    startTimer(): Profiler {
+      const start = new Date();
+
+      return {
+        logger: this,
+        done: (args) => {
+          const duration = new Date().getTime() - start.getTime();
+          logger[args?.level ?? LogLevel.Info](`${args?.message ?? 'Timer'} completed in: ${duration}`);
+          return true;
+        },
+      };
+    },
+
+    child(metadata?: Record<string, any>, name?: string): ILogger {
+      return consoleLogger(name, { metadata });
+    },
+
+    log: (level: LogLevel, message: string, metadata?: any) => {
+      return logger[level](message, message);
+    },
+
+    debug: (...args: any[]) => {
+      console.debug(...args);
+      return logger;
+    },
+
+    info: (...args: any[]) => {
+      console.log(...args);
+      return logger;
+    },
+
+    warn: (...args: any[]) => {
+      console.warn(...args);
+      return logger;
+    },
+
+    error: (...args: any[]) => {
+      console.error(...args);
+      return logger;
+    },
+  };
+
+  return logger;
+}