refactor(core): BreadcrumbStore added

packages/core/src/users/hawk-user-manager.ts → packages/core/src/features/hawk-user-manager.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';
 
@@ -15,14 +15,14 @@
  * {@link HawkStorage} is used solely to persist the auto-generated ID
  * so it survives across sessions.
  *
  * @remarks changes to user data in storage from outside manager are not tracked;
  * for changes to take effect call {@link clear}.
  */
 export class HawkUserManager {
   /**
    * In-memory user set explicitly via {@link setUser}.
    */
   private user: AffectedUser | null = null;
 
   /**
    * Underlying storage used to persist auto-generated user ID.
@@ -51,7 +51,7 @@
    *
    * Priority: in-memory user > persisted user ID.
    *
    * @returns set affected user or user with generated ID
    */
   public getUser(): AffectedUser {
     if (this.user) {

packages/core/src/modules/stack-parser.ts → packages/core/src/features/stack-parser.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/index.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/types/breadcrumb-store.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/message-processor.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/utils/event.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/modules/fetch-timer.ts → packages/core/src/utils/fetch-timer.ts

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

packages/core/src/modules/sanitizer.ts → packages/core/src/utils/sanitizer.ts

@@ -49,7 +49,7 @@
   private static readonly maxArrayLength: number = 10;
 
   /**
    * Custom type handlers registered via {@link registerHandler}.
    *
    * Checked in {@link sanitize} before built-in type checks.
    */
@@ -154,7 +154,6 @@
     depth: number,
     seen: WeakSet<object>
   ): Record<string, any> | '<deep object>' | '<big object>' {
-
     // If the maximum depth is reached, return a placeholder
     if (depth > Sanitizer.maxDepth) {
       return '<deep object>';

packages/core/src/utils/validation.ts

@@ -1,4 +1,4 @@
-import { log } from '../logger/logger';
+import { log } from './logger';
 import type { AffectedUser, Breadcrumb, EventAddons, EventContext, EventData } from '@hawk.so/types';
 import { isPlainObject } from './type-guards';
 

packages/core/tests/logger/logger.test.ts → packages/core/tests/utils/logger.test.ts

@@ -10,27 +10,27 @@ describe('Logger', () => {
   });
 
   it('should return false from isLoggerSet when no logger has been registered', async () => {
-    const { isLoggerSet } = await import('../../src/logger/logger');
+    const { isLoggerSet } = await import('../../src/utils/logger');
 
     expect(isLoggerSet()).toBe(false);
   });
 
   it('should return true from isLoggerSet after setLogger is called', async () => {
-    const { isLoggerSet, setLogger } = await import('../../src/logger/logger');
+    const { isLoggerSet, setLogger } = await import('../../src/utils/logger');
 
     setLogger(vi.fn());
 
     expect(isLoggerSet()).toBe(true);
   });
 
   it('should not throw when log is called with no logger registered', async () => {
-    const { log } = await import('../../src/logger/logger');
+    const { log } = await import('../../src/utils/logger');
 
     expect(() => log('test message')).not.toThrow();
   });
 
   it('should forward msg, type, and args to the registered logger', async () => {
-    const { setLogger, log } = await import('../../src/logger/logger');
+    const { setLogger, log } = await import('../../src/utils/logger');
     const mockLogger = vi.fn();
 
     setLogger(mockLogger);
@@ -41,7 +41,7 @@ describe('Logger', () => {
   });
 
   it('should pass undefined for omitted type and args', async () => {
-    const { setLogger, log } = await import('../../src/logger/logger');
+    const { setLogger, log } = await import('../../src/utils/logger');
     const mockLogger = vi.fn();
 
     setLogger(mockLogger);
@@ -51,7 +51,7 @@ describe('Logger', () => {
   });
 
   it('should replace a previously registered logger when setLogger is called again', async () => {
-    const { setLogger, log } = await import('../../src/logger/logger');
+    const { setLogger, log } = await import('../../src/utils/logger');
     const first = vi.fn();
     const second = vi.fn();
 
@@ -64,7 +64,7 @@ describe('Logger', () => {
   });
 
   it('should clear the registered logger when resetLogger is called', async () => {
-    const { isLoggerSet, setLogger, resetLogger } = await import('../../src/logger/logger');
+    const { isLoggerSet, setLogger, resetLogger } = await import('../../src/utils/logger');
 
     setLogger(vi.fn());
     expect(isLoggerSet()).toBe(true);
@@ -74,7 +74,7 @@ describe('Logger', () => {
   });
 
   it('should become a no-op after resetLogger is called', async () => {
-    const { setLogger, resetLogger, log } = await import('../../src/logger/logger');
+    const { setLogger, resetLogger, log } = await import('../../src/utils/logger');
     const mockLogger = vi.fn();
 
     setLogger(mockLogger);

packages/javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawk.so/javascript",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "JavaScript errors tracking for Hawk.so",
   "files": [
     "dist"