refactor(core): BaseCatcher added

Env-agnostic logic from Catcher in @hawk.so/javascript moved in new abstract BaseCatcher so general logic (breadcrumbs management, user management, context management, message pre-processing and sending, and other utilities) may be reused in other platform-specific implementations.

Browser-specific logic (UI-framework integrations, window event listeners, ConsoleCatcher) remain in original Catcher in @hawk.so/javascript.

Author: Reversean

packages/core/src/catcher.ts

@@ -13,3 +13,6 @@ export { buildElementSelector } from './utils/selector';
 export { isErrorProcessed, markErrorAsProcessed } from './utils/event';
 export type { BreadcrumbStore, BreadcrumbsAPI, BreadcrumbHint, BreadcrumbInput } from './types/breadcrumb-store';
 export type { MessageProcessor, ProcessingPayload } from './types/message-processor';
+export { BaseCatcher } from './catcher';
+export type { BeforeSendHook } from './catcher';
+export { decodeIntegrationId } from './utils/integration-id-decoder'

packages/core/src/index.ts

@@ -0,0 +1,27 @@
+import { DecodedIntegrationToken, EncodedIntegrationToken } from '@hawk.so/types';
+
+/**
+ * Decodes and returns integration id from integration token.
+ *
+ * @param token - encoded integration token
+ */
+export function decodeIntegrationId(token: EncodedIntegrationToken): string {
+  const integrationId = decodeIntegrationToken(token);
+
+  if (!integrationId || integrationId === '') {
+    throw new Error('Invalid integration token.');
+  }
+
+  return integrationId;
+}
+
+function decodeIntegrationToken(token: EncodedIntegrationToken): string {
+  try {
+    const decodedIntegrationToken: DecodedIntegrationToken = JSON.parse(atob(token));
+    const { integrationId } = decodedIntegrationToken;
+
+    return integrationId;
+  } catch {
+    throw new Error('Invalid integration token.');
+  }
+}

packages/core/src/utils/integration-id-decoder.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { CatcherMessage, EventContext } from '@hawk.so/types';
+import { BaseCatcher, HawkUserManager } from '../src';
+import type {
+  BeforeSendHook,
+  Transport,
+  BreadcrumbStore,
+  BreadcrumbInput,
+  MessageProcessor,
+  HawkStorage,
+  RandomGenerator,
+} from '../src';
+
+vi.mock('../../src/utils/logger', () => ({
+  log: vi.fn(),
+  isLoggerSet: vi.fn(() => false),
+  setLogger: vi.fn(),
+  resetLogger: vi.fn(),
+}));
+
+type TestType = 'errors/javascript';
+
+class TestCatcher extends BaseCatcher<TestType> {
+  constructor(
+    token: string,
+    transport: Transport<TestType>,
+    userManager: HawkUserManager,
+    release?: string,
+    context?: EventContext,
+    beforeSend?: BeforeSendHook<TestType>,
+    breadcrumbStore?: BreadcrumbStore
+  ) {
+    super(token, transport, userManager, release, context, beforeSend, breadcrumbStore);
+  }
+
+  protected getCatcherType(): TestType {
+    return 'errors/javascript';
+  }
+
+  protected getCatcherVersion(): string {
+    return '0.0.0-test';
+  }
+
+  public async run(error: Error | string, integrationAddons?: Record<string, unknown>, context?: EventContext): Promise<void> {
+    return this.formatAndSend(error, integrationAddons, context);
+  }
+
+  public addProcessor(...processors: MessageProcessor<TestType>[]): void {
+    this.addMessageProcessor(...processors);
+  }
+}
+
+function makeUserManager(): HawkUserManager {
+  const storage: HawkStorage = {
+    getItem: vi.fn().mockReturnValue('anon-id'),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+  };
+  const random: RandomGenerator = {
+    getRandomNumbers: vi.fn().mockReturnValue(new Uint8Array(40)),
+  };
+  return new HawkUserManager(storage, random);
+}
+
+function makeTransport() {
+  const send = vi.fn<[CatcherMessage<TestType>], Promise<void>>().mockResolvedValue(undefined);
+  return { send, transport: { send } as Transport<TestType> };
+}
+
+describe('BaseCatcher', () => {
+  describe('message processors', () => {
+    it('should not send event when a processor returns null', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      catcher.addProcessor({ apply: () => null });
+
+      await catcher.run(new Error('test'));
+
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it('should stop pipeline at first null-returning processor and skip remaining ones', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+      const secondProcessor: MessageProcessor<TestType> = { apply: vi.fn((p) => p) };
+
+      catcher.addProcessor({ apply: () => null }, secondProcessor);
+
+      await catcher.run(new Error('test'));
+
+      expect(send).not.toHaveBeenCalled();
+      expect(secondProcessor.apply).not.toHaveBeenCalled();
+    });
+
+    it('should send event when all processors pass the payload through', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      catcher.addProcessor({ apply: (p) => p }, { apply: (p) => p });
+
+      await catcher.run(new Error('test'));
+
+      expect(send).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('beforeSend hook', () => {
+    it('should drop event when beforeSend returns false', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, () => false);
+
+      await catcher.run(new Error('test'));
+
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it('should send returned payload when beforeSend returns a valid modified event', async () => {
+      const { send, transport } = makeTransport();
+      const beforeSend: BeforeSendHook<TestType> = (event) => ({ ...event, title: 'replaced' });
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, beforeSend);
+
+      await catcher.run(new Error('original'));
+
+      expect(send).toHaveBeenCalledOnce();
+      expect(send.mock.calls[0][0].payload.title).toBe('replaced');
+    });
+
+    it('should send original event when beforeSend mutates the clone without returning', async () => {
+      const { send, transport } = makeTransport();
+      const beforeSend: BeforeSendHook<TestType> = (event) => {
+        event.title = 'mutated';
+        // no return — clone was mutated but original should be sent
+      };
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, beforeSend);
+
+      await catcher.run(new Error('original'));
+
+      expect(send).toHaveBeenCalledOnce();
+      expect(send.mock.calls[0][0].payload.title).toBe('original');
+    });
+
+    it('should send original event when beforeSend returns an invalid value', async () => {
+      const { send, transport } = makeTransport();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const beforeSend: BeforeSendHook<TestType> = () => 42 as any;
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, beforeSend);
+
+      await catcher.run(new Error('original'));
+
+      expect(send).toHaveBeenCalledOnce();
+      expect(send.mock.calls[0][0].payload.title).toBe('original');
+    });
+  });
+
+  describe('context merging', () => {
+    it('should include instance context when no per-call context is provided', async () => {
+      const { send, transport } = makeTransport();
+      const instanceContext = { env: 'production', version: '1' };
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, instanceContext);
+
+      await catcher.run(new Error('test'));
+
+      expect(send.mock.calls[0][0].payload.context).toEqual(instanceContext);
+    });
+
+    it('should let per-call context override instance context keys', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher(
+        'token', transport, makeUserManager(), undefined,
+        { env: 'production', version: '1' }
+      );
+
+      await catcher.run(new Error('test'), undefined, { version: '2', extra: 'data' });
+
+      expect(send.mock.calls[0][0].payload.context).toEqual({ env: 'production', version: '2', extra: 'data' });
+    });
+
+    it('should use only per-call context when no instance context is set', async () => {
+      const { send, transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      await catcher.run(new Error('test'), undefined, { requestId: 'abc' });
+
+      expect(send.mock.calls[0][0].payload.context).toEqual({ requestId: 'abc' });
+    });
+  });
+
+  describe('breadcrumbs', () => {
+    it('should delegate add() to the store', () => {
+      const store: BreadcrumbStore = { add: vi.fn(), get: vi.fn().mockReturnValue([]), clear: vi.fn() };
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, undefined, store);
+      const crumb: BreadcrumbInput = { message: 'user clicked' };
+
+      catcher.breadcrumbs.add(crumb);
+
+      expect(store.add).toHaveBeenCalledWith(crumb, undefined);
+    });
+
+    it('should delegate get() to the store', () => {
+      const crumbs = [{ message: 'click', timestamp: 1000 }];
+      const store: BreadcrumbStore = { add: vi.fn(), get: vi.fn().mockReturnValue(crumbs), clear: vi.fn() };
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, undefined, store);
+
+      expect(catcher.breadcrumbs.get()).toBe(crumbs);
+    });
+
+    it('should delegate clear() to the store', () => {
+      const store: BreadcrumbStore = { add: vi.fn(), get: vi.fn().mockReturnValue([]), clear: vi.fn() };
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager(), undefined, undefined, undefined, store);
+
+      catcher.breadcrumbs.clear();
+
+      expect(store.clear).toHaveBeenCalledOnce();
+    });
+
+    it('should return empty array from get() when no store is configured', () => {
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      expect(catcher.breadcrumbs.get()).toEqual([]);
+    });
+
+    it('should not throw when add() is called without a store', () => {
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      expect(() => catcher.breadcrumbs.add({ message: 'test' })).not.toThrow();
+    });
+
+    it('should not throw when clear() is called without a store', () => {
+      const { transport } = makeTransport();
+      const catcher = new TestCatcher('token', transport, makeUserManager());
+
+      expect(() => catcher.breadcrumbs.clear()).not.toThrow();
+    });
+  });
+});

packages/core/tests/catcher.test.ts

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

packages/javascript/package.json

@@ -1,6 +1,6 @@
 import type { MessageProcessor, ProcessingPayload } from '@hawk.so/core';
-import type { BreadcrumbsOptions } from '../addons/breadcrumbs';
-import { BrowserBreadcrumbStore } from '../addons/breadcrumbs';
+import type { BreadcrumbsOptions } from './breadcrumbs';
+import { BrowserBreadcrumbStore } from './breadcrumbs';
 import type { ErrorsCatcherType } from '@hawk.so/types/src/catchers/catcher-message';
 
 /**

packages/javascript/src/addons/browser-breadcrumbs-message-processor.ts

@@ -1,5 +1,5 @@
 import type { MessageProcessor, ProcessingPayload } from '@hawk.so/core';
-import type { ConsoleCatcher } from '../addons/consoleCatcher';
+import type { ConsoleCatcher } from './consoleCatcher';
 
 /**
  * Attaches captured console output to payload addons.