refactor(javascript): MessageProcessor abstraction added and implemented in catcher event processing pipeline

- BreadcrumbStore abstraction and browser implementation added
- MessageProcessor interface and MessageHint type
- BrowserMessageProcessor, BreadcrumbsMessageProcessor, ConsoleCatcherMessageProcessor, DebugMessageProcessor
- replaced inline addon logic with sequential MessageProcessor pipeline
- rearranged core files and directories

Author: Reversean

packages/core/src/errors.ts

@@ -1,5 +1,5 @@
 import type { AffectedUser } from '@hawk.so/types';
-import type { HawkStorage } from '../storages/hawk-storage';
+import type { HawkStorage } from '../utils/hawk-storage';
 import { id } from '../utils/id';
 import type { RandomGenerator } from '../utils/random';
 

…ages/core/src/users/hawk-user-manager.ts …s/core/src/features/hawk-user-manager.tspackages/core/src/users/hawk-user-manager.ts renamed to packages/core/src/features/hawk-user-manager.ts packages/core/src/users/hawk-user-manager.ts renamed to packages/core/src/features/hawk-user-manager.ts

@@ -1,7 +1,7 @@
 import type { StackFrame } from 'error-stack-parser';
 import ErrorStackParser from 'error-stack-parser';
 import type { BacktraceFrame, SourceCodeLine } from '@hawk.so/types';
-import fetchTimer from './fetch-timer';
+import fetchTimer from '../utils/fetch-timer';
 
 /**
  * This module prepares parsed backtrace

packages/core/src/modules/stack-parser.ts …ckages/core/src/features/stack-parser.tspackages/core/src/modules/stack-parser.ts renamed to packages/core/src/features/stack-parser.ts packages/core/src/modules/stack-parser.ts renamed to packages/core/src/features/stack-parser.ts

@@ -1,14 +1,15 @@
-export type { HawkStorage } from './storages/hawk-storage';
+export type { HawkStorage } from './utils/hawk-storage';
 export type { RandomGenerator } from './utils/random';
-export { HawkUserManager } from './users/hawk-user-manager';
-export type { Logger, LogType } from './logger/logger';
-export { isLoggerSet, setLogger, resetLogger, log } from './logger/logger';
+export { HawkUserManager } from './features/hawk-user-manager';
+export type { Logger, LogType } from './utils/logger';
+export { isLoggerSet, setLogger, resetLogger, log } from './utils/logger';
 export { validateUser, validateContext, isValidEventPayload, isValidBreadcrumb } from './utils/validation';
 export { isPlainObject, isArray, isClassPrototype, isClassInstance, isString } from './utils/type-guards';
-export { Sanitizer } from './modules/sanitizer';
-export type { Transport } from './transports/transport';
-export type { SanitizerTypeHandler } from './modules/sanitizer';
-export { StackParser } from './modules/stack-parser';
+export { Sanitizer } from './utils/sanitizer';
+export type { Transport } from './utils/transport';
+export type { SanitizerTypeHandler } from './utils/sanitizer';
+export { StackParser } from './features/stack-parser';
 export { buildElementSelector } from './utils/selector';
-export { EventRejectedError } from './errors';
 export { isErrorProcessed, markErrorAsProcessed } from './utils/event';
+export type { BreadcrumbStore, BreadcrumbsAPI, BreadcrumbHint, BreadcrumbInput } from './types/breadcrumb-store';
+export type { MessageProcessor, ProcessingPayload } from './types/message-processor';

packages/core/src/index.ts

@@ -0,0 +1,27 @@
+import type { Breadcrumb } from '@hawk.so/types';
+
+/**
+ * Hint passed to beforeBreadcrumb callback.
+ */
+export interface BreadcrumbHint {
+  [key: string]: unknown;
+}
+
+/**
+ * Breadcrumb input type - breadcrumb data with optional timestamp.
+ */
+export type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & { timestamp?: number };
+
+/**
+ * Contract for breadcrumb storage. Also serves as public breadcrumbs API.
+ */
+export interface BreadcrumbStore {
+  add(breadcrumb: BreadcrumbInput, hint?: BreadcrumbHint): void;
+  get(): Breadcrumb[];
+  clear(): void;
+}
+
+/**
+ * @deprecated Use {@link BreadcrumbStore} instead.
+ */
+export type BreadcrumbsAPI = BreadcrumbStore;

packages/core/src/types/breadcrumb-store.ts

@@ -0,0 +1,43 @@
+import type { CatcherMessagePayload, CatcherMessageType } from '@hawk.so/types';
+
+/**
+ * Extracted addons type from catcher message payload.
+ *
+ * @typeParam T - catcher message type
+ */
+type ExtractAddons<T extends CatcherMessageType> =
+  CatcherMessagePayload<T> extends { addons?: infer A } ? A : never;
+
+/**
+ * Payload type used during message processing pipeline.
+ *
+ * Same as {@link CatcherMessagePayload} but with `addons` always defined and partially filled —
+ * processors may contribute individual addon fields independently of each other.
+ *
+ * @typeParam T - catcher message type this payload belongs to
+ */
+export type ProcessingPayload<T extends CatcherMessageType> =
+  Omit<CatcherMessagePayload<T>, 'addons'> & {
+    addons: Partial<ExtractAddons<T>>;
+  };
+
+/**
+ * Single step in message processing pipeline before message is sent.
+ *
+ * @typeParam T - catcher message type this processor handles
+ */
+export interface MessageProcessor<T extends CatcherMessageType = CatcherMessageType> {
+  /**
+   * Handles input message. May mutate, replace or drop it.
+   *
+   * Dropped message won't be sent.
+   *
+   * @param payload - processed event message payload with partially-built addons
+   * @param error - original error
+   * @returns modified payload, or `null` to drop message
+   */
+  apply(
+    payload: ProcessingPayload<T>,
+    error?: Error | string,
+  ): ProcessingPayload<T> | null
+}

packages/core/src/types/message-processor.ts

@@ -1,4 +1,4 @@
-import { log } from '../logger/logger';
+import { log } from './logger';
 
 /**
  * Symbol to mark error as processed by Hawk

packages/core/src/utils/event.ts

@@ -1,4 +1,4 @@
-import { log } from '../logger/logger';
+import { log } from '../utils/logger';
 
 /**
  * Sends AJAX request and wait for some time.