feat: add breadcrumb management to Catcher class

.github/workflows/main.yml

@@ -8,10 +8,10 @@ jobs:
       CI_JOB_NUMBER: 1
     steps:
       - uses: actions/checkout@v1
-      - name: Use Node.js 20.x
+      - name: Use Node.js 24.x
         uses: actions/setup-node@v1
         with:
-          node-version: 20.x
+          node-version: 24.x
       - run: yarn install
       - run: yarn lint-test
 
@@ -21,9 +21,9 @@ jobs:
       CI_JOB_NUMBER: 2
     steps:
       - uses: actions/checkout@v1
-      - name: Use Node.js 20.x
+      - name: Use Node.js 24.x
         uses: actions/setup-node@v1
         with:
-          node-version: 20.x
+          node-version: 24.x
       - run: yarn install
       - run: yarn build

.github/workflows/npm-publish.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: 20
+          node-version: 24.x
           registry-url: https://registry.npmjs.org/
       - run: yarn
       - run: yarn lint-test

package.json

@@ -18,6 +18,7 @@
     "url": "git+https://github.com/codex-team/hawk.javascript.git"
   },
   "devDependencies": {
+    "@hawk.so/types": "0.5.2",
     "@size-limit/preset-small-lib": "^11.1.6",
     "eslint": "^7.24.0",
     "eslint-config-codex": "^1.6.1",

packages/javascript/README.md

@@ -88,6 +88,7 @@ Initialization settings:
 | `disableGlobalErrorsHandling` | boolean                                                   | optional     | Do not initialize global errors handling                                            |
 | `disableVueErrorHandler`      | boolean                                                   | optional     | Do not initialize Vue errors handling                                               |
 | `consoleTracking`             | boolean                                                   | optional     | Initialize console logs tracking                                                    |
+| `breadcrumbs`                 | false or BreadcrumbsOptions object                        | optional     | Configure breadcrumbs tracking (see below)                                          |
 | `beforeSend`                  | function(event) => event                                  | optional     | This Method allows you to filter any data you don't want sending to Hawk            |
 
 Other available [initial settings](types/hawk-initial-settings.d.ts) are described at the type definition.
@@ -145,6 +146,94 @@ hawk.setContext({
 });
 ```
 
+## Breadcrumbs
+
+Breadcrumbs track user interactions and events leading up to an error, providing context for debugging.
+
+### Default Configuration
+
+By default, breadcrumbs are enabled with tracking for fetch/XHR requests and navigation:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN'
+  // breadcrumbs enabled by default
+});
+```
+
+### Disabling Breadcrumbs
+
+To disable breadcrumbs entirely:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  breadcrumbs: false
+});
+```
+
+### Custom Configuration
+
+Configure breadcrumbs tracking behavior:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  breadcrumbs: {
+    maxBreadcrumbs: 20,         // Maximum breadcrumbs to store (default: 15)
+    maxValueLength: 512,        // Max string length (default: 1024)
+    trackFetch: true,           // Track fetch/XHR requests (default: true)
+    trackNavigation: true,      // Track navigation events (default: true)
+    trackClicks: false,         // Track UI clicks (default: false)
+    beforeBreadcrumb: (breadcrumb, hint) => {
+      // Filter or modify breadcrumbs before storing
+      if (breadcrumb.category === 'fetch' && breadcrumb.data?.url?.includes('/sensitive')) {
+        return null; // Discard this breadcrumb
+      }
+      return breadcrumb;
+    }
+  }
+});
+```
+
+### Breadcrumbs Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxBreadcrumbs` | `number` | `15` | Maximum number of breadcrumbs to store. When the limit is reached, oldest breadcrumbs are removed (FIFO). |
+| `maxValueLength` | `number` | `1024` | Maximum length for string values in breadcrumb data. Longer strings will be trimmed with `…` suffix. |
+| `trackFetch` | `boolean` | `true` | Automatically track `fetch()` and `XMLHttpRequest` calls as breadcrumbs. Captures request URL, method, status code, and response time. |
+| `trackNavigation` | `boolean` | `true` | Automatically track navigation events (History API: `pushState`, `replaceState`, `popstate`). Captures route changes. |
+| `trackClicks` | `boolean` | `false` | Automatically track UI click events. Captures element selector, coordinates, and other click metadata. |
+| `beforeBreadcrumb` | `function` | `undefined` | Hook called before each breadcrumb is stored. Receives `(breadcrumb, hint)` and can return modified breadcrumb, `null` to discard it, or the original breadcrumb. Useful for filtering sensitive data or PII. |
+
+### Manual Breadcrumbs
+
+Add custom breadcrumbs manually:
+
+```js
+hawk.breadcrumbs.add({
+  type: 'logic',
+  category: 'auth',
+  message: 'User logged in',
+  level: 'info',
+  data: { userId: '123' }
+});
+```
+
+### Breadcrumb Methods
+
+```js
+// Add a breadcrumb
+hawk.breadcrumbs.add(breadcrumb, hint);
+
+// Get current breadcrumbs
+const breadcrumbs = hawk.breadcrumbs.get();
+
+// Clear all breadcrumbs
+hawk.breadcrumbs.clear();
+```
+
 ## Source maps consuming
 
 If your bundle is minified, it is useful to pass source-map files to the Hawk. After that you will see beautiful

packages/javascript/example/index.html

@@ -174,6 +174,50 @@ <h2>Context Management</h2>
       <br /><br />
       <button id="btn-set-context">Set Context</button>
     </section>
+    <section>
+      <h2>Breadcrumbs Management</h2>
+      <label for="breadcrumbMessage">Breadcrumb Message</label>
+      <input type="text" id="breadcrumbMessage" placeholder="User performed action" />
+      <br /><br />
+      <label for="breadcrumbType">Type</label>
+      <select id="breadcrumbType">
+        <option value="default">default</option>
+        <option value="request">request</option>
+        <option value="ui">ui</option>
+        <option value="navigation">navigation</option>
+        <option value="logic">logic</option>
+        <option value="error">error</option>
+      </select>
+      <br /><br />
+      <label for="breadcrumbLevel">Level</label>
+      <select id="breadcrumbLevel">
+        <option value="info">info</option>
+        <option value="debug">debug</option>
+        <option value="warning">warning</option>
+        <option value="error">error</option>
+        <option value="fatal">fatal</option>
+      </select>
+      <br /><br />
+      <label for="breadcrumbCategory">Category (optional)</label>
+      <input type="text" id="breadcrumbCategory" placeholder="ui.click" />
+      <br /><br />
+      <button id="btn-add-breadcrumb">Add Breadcrumb</button>
+      <button id="btn-get-breadcrumbs">Get Breadcrumbs</button>
+      <button id="btn-clear-breadcrumbs">Clear Breadcrumbs</button>
+      <div id="breadcrumbs-output" style="margin-top: 15px; margin-bottom: 30px; padding: 10px; background: rgba(36, 39, 50, 0.68); border-radius: 3px; max-height: 200px; overflow-y: auto; white-space: pre-wrap; font-family: monospace; font-size: 12px;"></div>
+      <h2>Test All Breadcrumb Types <small>Quick examples for each type</small></h2>
+      <div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px;">
+        <button id="btn-test-default">Default Event (Manual)</button>
+        <button id="btn-test-request">Request (Auto via Fetch)</button>
+        <button id="btn-test-ui">UI Click (Auto)</button>
+        <button id="btn-test-navigation">Navigation (Auto)</button>
+        <button id="btn-test-logic">Logic Operation (Manual)</button>
+        <button id="btn-test-error">Error Event (Manual)</button>
+      </div>
+      <div style="margin-top: 10px; display: flex; gap: 10px;">
+        <button id="btn-test-all-types" style="flex: 1; background: #2ecc71;">▶Run All Types Sequence</button>
+      </div>
+    </section>
     <script src="https://unpkg.com/vue@2"></script>
     <section>
       <h2>Test Vue integration: $root</h2>
@@ -259,6 +303,20 @@ <h2>Test Vue integration: &lt;test-component&gt;</h2>
         context: {
           rootContextSample: '12345',
         },
+        // breadcrumbs: {
+        //   maxBreadcrumbs: 20,         // Maximum breadcrumbs to store (default: 15)
+        //   maxValueLength: 512,        // Max string length (default: 1024)
+        //   trackFetch: true,           // Track fetch/XHR requests (default: true)
+        //   trackNavigation: true,      // Track navigation events (default: true)
+        //   trackClicks: false,         // Track UI clicks (default: false)
+        //   beforeBreadcrumb: (breadcrumb, hint) => {
+        //     // Filter or modify breadcrumbs before storing
+        //     if (breadcrumb.category === 'fetch' && breadcrumb.data?.url?.includes('/sensitive')) {
+        //       return null; // Discard this breadcrumb
+        //     }
+        //     return breadcrumb;
+        //   }
+        // }
       });
     </script>
   </body>