refactor(core): UserManager replaced with HawkUserManager

Author: Reversean

packages/core/package.json

@@ -36,6 +36,9 @@
     "url": "https://github.com/codex-team/hawk.javascript/issues"
   },
   "homepage": "https://github.com/codex-team/hawk.javascript#readme",
+  "dependencies": {
+    "@hawk.so/types": "0.5.8"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",
     "vite": "^7.3.1",

packages/core/src/index.ts

@@ -1,3 +1,2 @@
 export type { HawkStorage } from './storages/hawk-storage';
-export type { UserManager } from './users/user-manager';
-export { HawkStorageUserManager } from './users/hawk-storage-user-manager';
+export { HawkUserManager } from './users/hawk-user-manager';

packages/core/src/users/hawk-storage-user-manager.ts

@@ -0,0 +1,71 @@
+import type { AffectedUser } from '@hawk.so/types';
+import type { HawkStorage } from '../storages/hawk-storage';
+
+/**
+ * Storage key used to persist the auto-generated user ID.
+ */
+export const HAWK_USER_ID_KEY = 'hawk-user-id';
+
+/**
+ * Manages the affected user identity.
+ *
+ * Manually provided users are kept in memory only (they don't change restarts).
+ * {@link HawkStorage} is used solely to persist the auto-generated ID
+ * so it survives across sessions.
+ */
+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.
+   */
+  private readonly storage: HawkStorage;
+
+  /**
+   * @param storage - Storage backend to use for persistence.
+   */
+  constructor(storage: HawkStorage) {
+    this.storage = storage;
+  }
+
+  /**
+   * Returns the current affected user, or `null` if none is available.
+   *
+   * Priority: in-memory user > persisted user ID.
+   */
+  public getUser(): AffectedUser | null {
+    if (this.user) {
+      return this.user;
+    }
+    const storedId = this.storage.getItem(HAWK_USER_ID_KEY);
+    return storedId ? { id: storedId } : null;
+  }
+
+  /**
+   * Sets the user explicitly (in memory only).
+   *
+   * @param user - The affected user provided by the application.
+   */
+  public setUser(user: AffectedUser): void {
+    this.user = user;
+  }
+
+  /**
+   * Persists an auto-generated user ID to storage.
+   *
+   * @param id - The generated ID to persist.
+   */
+  public persistGeneratedId(id: string): void {
+    this.storage.setItem(HAWK_USER_ID_KEY, id);
+  }
+
+  /**
+   * Clears the explicitly set user, falling back to the persisted user ID.
+   */
+  public clear(): void {
+    this.user = null;
+  }
+}

packages/core/src/users/hawk-user-manager.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { HawkUserManager } from '../../src';
+import type { HawkStorage } from '../../src';
+
+describe('HawkUserManager', () => {
+  let storage: HawkStorage;
+  let manager: HawkUserManager;
+
+  beforeEach(() => {
+    storage = {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    };
+    manager = new HawkUserManager(storage);
+  });
+
+  it('should return null when no user is set and storage is empty', () => {
+    expect(manager.getUser()).toBeNull();
+  });
+
+  it('should return in-memory user set via setUser()', () => {
+    const user = { id: 'user-1', name: 'Ryan Gosling', url: 'https://example.com', photo: 'https://example.com/photo.png' };
+
+    manager.setUser(user);
+
+    expect(manager.getUser()).toEqual(user);
+    expect(storage.setItem).not.toHaveBeenCalled();
+  });
+
+  it('should not touch storage when setUser() is called', () => {
+    manager.setUser({ id: 'user-1' });
+
+    expect(storage.setItem).not.toHaveBeenCalled();
+    expect(storage.removeItem).not.toHaveBeenCalled();
+  });
+
+  it('should return anonymous user from storage when no in-memory user is set', () => {
+    vi.mocked(storage.getItem).mockReturnValue('anon-123');
+
+    expect(manager.getUser()).toEqual({ id: 'anon-123' });
+    expect(storage.getItem).toHaveBeenCalledWith('hawk-user-id');
+  });
+
+  it('should prefer in-memory user over persisted anonymous ID', () => {
+    vi.mocked(storage.getItem).mockReturnValue('anon-123');
+    manager.setUser({ id: 'explicit-user' });
+
+    expect(manager.getUser()).toEqual({ id: 'explicit-user' });
+  });
+
+  it('should persist anonymous ID via persistGeneratedId()', () => {
+    manager.persistGeneratedId('anon-456');
+
+    expect(storage.setItem).toHaveBeenCalledWith('hawk-user-id', 'anon-456');
+  });
+
+  it('should clear in-memory user and fall back to persisted anonymous ID', () => {
+    vi.mocked(storage.getItem).mockReturnValue('anon-123');
+    manager.setUser({ id: 'user-1' });
+    manager.clear();
+
+    expect(manager.getUser()).toEqual({ id: 'anon-123' });
+  });
+
+  it('should return null after clear() when no anonymous ID is persisted', () => {
+    manager.setUser({ id: 'user-1' });
+    manager.clear();
+
+    expect(manager.getUser()).toBeNull();
+  });
+});

packages/core/src/users/user-manager.ts

@@ -18,8 +18,7 @@ import { isErrorProcessed, markErrorAsProcessed } from './utils/event';
 import { ConsoleCatcher } from './addons/consoleCatcher';
 import { BreadcrumbManager } from './addons/breadcrumbs';
 import { validateUser, validateContext, isValidEventPayload } from './utils/validation';
-import type { UserManager } from '@hawk.so/core';
-import { HawkStorageUserManager } from '@hawk.so/core';
+import { HawkUserManager } from '@hawk.so/core';
 import { HawkLocalStorage } from './storages/hawk-local-storage';
 import { id } from './utils/id';
 
@@ -112,7 +111,7 @@ export default class Catcher {
   /**
    * Current authenticated user manager instance
    */
-  private readonly userManager: UserManager = new HawkStorageUserManager(new HawkLocalStorage());
+  private readonly userManager: HawkUserManager = new HawkUserManager(new HawkLocalStorage());
 
   /**
    * Catcher constructor
@@ -517,7 +516,7 @@ export default class Catcher {
   private getIntegrationId(): string {
     try {
       const decodedIntegrationToken: DecodedIntegrationToken = JSON.parse(atob(this.token));
-      const {integrationId} = decodedIntegrationToken;
+      const { integrationId } = decodedIntegrationToken;
 
       if (!integrationId || integrationId === '') {
         throw new Error();
@@ -549,19 +548,16 @@ export default class Catcher {
   }
 
   /**
-   * Returns the current user if exists, otherwise creates and persists a new one.
+   * Returns the current user if set, otherwise generates and persists an anonymous ID.
    */
   private getUser(): AffectedUser {
     const user = this.userManager.getUser();
-
     if (user) {
       return user;
     }
-    const newUser: AffectedUser = {id: id()};
-
-    this.userManager.setUser(newUser);
-
-    return newUser;
+    const generatedId = id();
+    this.userManager.persistGeneratedId(generatedId);
+    return { id: generatedId };
   }
 
   /**
@@ -628,7 +624,7 @@ export default class Catcher {
    * @param {Error|string} error — caught error
    */
   private getAddons(error: Error | string): HawkJavaScriptEvent['addons'] {
-    const {innerWidth, innerHeight} = window;
+    const { innerWidth, innerHeight } = window;
     const userAgent = window.navigator.userAgent;
     const location = window.location.href;
     const getParams = this.getGetParams();