diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b39a2b4..70254fc 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -8,10 +8,10 @@ jobs: CI_JOB_NUMBER: 1 steps: - uses: actions/checkout@v1 - - name: Use Node.js 20.x - uses: actions/setup-node@v1 + - name: Use Node.js from .nvmrc + uses: actions/setup-node@v3 with: - node-version: 20.x + node-version-file: '.nvmrc' - 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 - uses: actions/setup-node@v1 + - name: Use Node.js from .nvmrc + uses: actions/setup-node@v3 with: - node-version: 20.x + node-version-file: '.nvmrc' - run: yarn install - run: yarn build diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml index b28f879..73df7c8 100644 --- a/.github/workflows/npm-publish.yml +++ b/.github/workflows/npm-publish.yml @@ -10,9 +10,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 + - uses: actions/setup-node@v3 with: - node-version: 20 + node-version-file: '.nvmrc' registry-url: https://registry.npmjs.org/ - run: yarn - run: yarn lint-test diff --git a/.nvmrc b/.nvmrc index 67e145b..248216a 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -v20.18.0 +24.12.0 diff --git a/packages/javascript/README.md b/packages/javascript/README.md index de92d27..3b25134 100644 --- a/packages/javascript/README.md +++ b/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, navigation, and UI clicks: + +```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: true, // Track UI clicks (default: true) + 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` | `true` | 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 diff --git a/packages/javascript/example/breadcrumbs-tests.js b/packages/javascript/example/breadcrumbs-tests.js new file mode 100644 index 0000000..96124a7 --- /dev/null +++ b/packages/javascript/example/breadcrumbs-tests.js @@ -0,0 +1,306 @@ +/** + * Breadcrumbs Management + */ +const buttonAddBreadcrumb = document.getElementById('btn-add-breadcrumb'); +const buttonGetBreadcrumbs = document.getElementById('btn-get-breadcrumbs'); +const buttonClearBreadcrumbs = document.getElementById('btn-clear-breadcrumbs'); +const breadcrumbsOutput = document.getElementById('breadcrumbs-output'); + +buttonAddBreadcrumb.addEventListener('click', () => { + const message = document.getElementById('breadcrumbMessage').value; + const type = document.getElementById('breadcrumbType').value; + const level = document.getElementById('breadcrumbLevel').value; + const category = document.getElementById('breadcrumbCategory').value; + + if (!message.trim()) { + alert('Breadcrumb message is required'); + + return; + } + + window.hawk.breadcrumbs.add({ + message, + type, + level, + ...(category.trim() && { category }), + data: { + timestamp: new Date().toISOString(), + custom: 'manual breadcrumb', + }, + }); + + breadcrumbsOutput.textContent = `✓ Breadcrumb added: ${message}`; +}); + +buttonGetBreadcrumbs.addEventListener('click', () => { + const breadcrumbs = window.hawk.breadcrumbs.get(); + + if (breadcrumbs.length === 0) { + breadcrumbsOutput.textContent = 'No breadcrumbs yet'; + + return; + } + + breadcrumbsOutput.textContent = JSON.stringify(breadcrumbs, null, 2); +}); + +buttonClearBreadcrumbs.addEventListener('click', () => { + window.hawk.breadcrumbs.clear(); + breadcrumbsOutput.textContent = '✓ Breadcrumbs cleared'; +}); + +/** + * Test All Breadcrumb Types + */ +const buttonTestDefault = document.getElementById('btn-test-default'); +const buttonTestRequest = document.getElementById('btn-test-request'); +const buttonTestUI = document.getElementById('btn-test-ui'); +const buttonTestNavigation = document.getElementById('btn-test-navigation'); +const buttonTestLogic = document.getElementById('btn-test-logic'); +const buttonTestError = document.getElementById('btn-test-error'); +const buttonTestAllTypes = document.getElementById('btn-test-all-types'); + +/** + * Test Default breadcrumb (manual) + */ +buttonTestDefault.addEventListener('click', () => { + /** + * Default breadcrumbs are always added manually via hawk.breadcrumbs.add() + */ + window.hawk.breadcrumbs.add({ + type: 'default', + level: 'info', + category: 'user.action', + message: 'User clicked on default event button', + data: { + action: 'button_click', + context: 'breadcrumb_testing', + }, + }); + breadcrumbsOutput.textContent = '✓ Default breadcrumb added manually'; +}); + +/** + * Test Request breadcrumb (automatic via fetch) + */ +buttonTestRequest.addEventListener('click', async () => { + breadcrumbsOutput.textContent = 'Testing request breadcrumb...'; + + try { + const response = await fetch('https://api.github.com/zen'); + const text = await response.text(); + + breadcrumbsOutput.textContent = `✓ Request breadcrumb added (${response.status}): "${text}"`; + } catch (error) { + breadcrumbsOutput.textContent = `✗ Request failed: ${error.message}`; + } +}); + +/** + * Test UI breadcrumb (automatic tracking) + */ +buttonTestUI.addEventListener('click', () => { + /** + * Create a test element and click it to trigger automatic UI breadcrumb + * BreadcrumbManager automatically captures click events when trackClicks: true + */ + const testElement = document.createElement('button'); + + testElement.id = 'auto-click-test'; + testElement.className = 'test-button'; + testElement.textContent = 'Auto Test'; + testElement.style.position = 'absolute'; + testElement.style.opacity = '0'; + testElement.style.pointerEvents = 'none'; + document.body.appendChild(testElement); + + /** + * Trigger a click event + */ + testElement.click(); + + /** + * Clean up + */ + setTimeout(() => { + document.body.removeChild(testElement); + }, 100); + + breadcrumbsOutput.textContent = '✓ UI Click breadcrumb added automatically'; +}); + +/** + * Test Navigation breadcrumb (automatic tracking) + */ +buttonTestNavigation.addEventListener('click', () => { + /** + * Change the hash to trigger automatic navigation breadcrumb + * BreadcrumbManager automatically captures this event + */ + window.location.hash = 'breadcrumb-test-' + Date.now(); + + breadcrumbsOutput.textContent = '✓ Navigation breadcrumb added automatically'; +}); + +/** + * Test Logic breadcrumb (manual) + */ +buttonTestLogic.addEventListener('click', () => { + /** + * Simulate some logic operations + */ + const startTime = performance.now(); + + /** + * Complex calculation for testing + * + * @param {number} n - Number of iterations + * @returns {number} Calculation result + */ + function complexCalculation(n) { + let result = 0; + + for (let i = 0; i < n; i++) { + result += Math.sqrt(i); + } + + return result; + } + + const result = complexCalculation(10000); + const duration = performance.now() - startTime; + + /** + * Logic breadcrumbs are always added manually to track application flow + */ + window.hawk.breadcrumbs.add({ + type: 'logic', + level: 'debug', + category: 'calculation.complex', + message: 'Performed complex calculation', + data: { + operation: 'complexCalculation', + iterations: 10000, + result: result, + durationMs: duration.toFixed(2), + }, + }); + + breadcrumbsOutput.textContent = `✓ Logic breadcrumb added manually (${duration.toFixed(2)}ms)`; +}); + +/** + * Test Error breadcrumb (manual) + */ +buttonTestError.addEventListener('click', () => { + try { + /** + * Intentionally cause an error but catch it + */ + JSON.parse('invalid json {{{'); + } catch (error) { + /** + * Caught errors can be manually added as breadcrumbs + * Uncaught errors are sent to Hawk automatically, not as breadcrumbs + */ + window.hawk.breadcrumbs.add({ + type: 'error', + level: 'error', + category: 'json.parse', + message: `JSON parse error: ${error.message}`, + data: { + error: error.name, + message: error.message, + input: 'invalid json {{{', + }, + }); + + breadcrumbsOutput.textContent = `✓ Error breadcrumb added manually: ${error.message}`; + } +}); + +/** + * Test All Types in sequence + */ +buttonTestAllTypes.addEventListener('click', async () => { + breadcrumbsOutput.textContent = 'Running all breadcrumb types...'; + + /** + * 1. Default + */ + window.hawk.breadcrumbs.add({ + type: 'default', + level: 'info', + message: 'Sequence started', + }); + + await new Promise(resolve => setTimeout(resolve, 200)); + + /** + * 2. Logic + */ + window.hawk.breadcrumbs.add({ + type: 'logic', + level: 'debug', + category: 'sequence.step', + message: 'Processing step 1', + data: { + step: 1, + }, + }); + + await new Promise(resolve => setTimeout(resolve, 200)); + + /** + * 3. UI (automatic) + */ + const autoClickElement = document.createElement('button'); + + autoClickElement.id = 'sequence-auto-click'; + autoClickElement.style.position = 'absolute'; + autoClickElement.style.opacity = '0'; + autoClickElement.style.pointerEvents = 'none'; + document.body.appendChild(autoClickElement); + autoClickElement.click(); + document.body.removeChild(autoClickElement); + + await new Promise(resolve => setTimeout(resolve, 200)); + + /** + * 4. Request (automatic) + */ + try { + await fetch('https://api.github.com/zen'); + } catch (error) { + /** + * Fetch will be captured automatically + */ + } + + await new Promise(resolve => setTimeout(resolve, 200)); + + /** + * 5. Navigation (automatic) + */ + window.location.hash = 'sequence-test-' + Date.now(); + + await new Promise(resolve => setTimeout(resolve, 200)); + + /** + * 6. Error + */ + try { + throw new Error('Test error in sequence'); + } catch (error) { + window.hawk.breadcrumbs.add({ + type: 'error', + level: 'warning', + message: `Caught error: ${error.message}`, + data: { + error: error.name, + }, + }); + } + + breadcrumbsOutput.textContent = '✓ All breadcrumb types added! Check "Get Breadcrumbs"'; +}); diff --git a/packages/javascript/example/index.html b/packages/javascript/example/index.html index 7b6f125..1e8aefe 100644 --- a/packages/javascript/example/index.html +++ b/packages/javascript/example/index.html @@ -174,6 +174,50 @@

Context Management



+
+

Breadcrumbs Management

+ + +

+ + +

+ + +

+ + +

+ + + + +

Test All Breadcrumb Types Quick examples for each type

+
+ + + + + + +
+
+ +
+

Test Vue integration: $root

@@ -248,6 +292,7 @@

Test Vue integration: <test-component>

+ diff --git a/packages/javascript/example/sample-errors.js b/packages/javascript/example/sample-errors.js index 6e8ab33..1f88c10 100644 --- a/packages/javascript/example/sample-errors.js +++ b/packages/javascript/example/sample-errors.js @@ -27,7 +27,9 @@ buttonRealError.addEventListener('click', realErrorSample); const buttonPromiseRejection = document.getElementById('btn-promise-rejection'); buttonPromiseRejection.addEventListener('click', function promiseRejectionSample() { - // Promise.reject('This is a sample rejected promise'); + /** + * Promise.reject('This is a sample rejected promise'); + */ Promise.resolve() .then(realErrorSample) .then(() => {}); diff --git a/packages/javascript/package.json b/packages/javascript/package.json index 081f0a1..6d8f982 100644 --- a/packages/javascript/package.json +++ b/packages/javascript/package.json @@ -1,6 +1,6 @@ { "name": "@hawk.so/javascript", - "version": "3.2.12", + "version": "3.2.13", "description": "JavaScript errors tracking for Hawk.so", "files": [ "dist" @@ -18,7 +18,8 @@ "scripts": { "dev": "vite", "build": "vite build", - "stats": "size-limit > stats.txt" + "stats": "size-limit > stats.txt", + "lint": "eslint --fix \"src/**/*.{js,ts}\"" }, "repository": { "type": "git", @@ -35,10 +36,10 @@ }, "homepage": "https://github.com/codex-team/hawk.javascript#readme", "dependencies": { - "@hawk.so/types": "^0.1.36", "error-stack-parser": "^2.1.4" }, "devDependencies": { + "@hawk.so/types": "0.5.2", "vue": "^2", "vite-plugin-dts": "^4.2.4" } diff --git a/packages/javascript/src/addons/breadcrumbs.ts b/packages/javascript/src/addons/breadcrumbs.ts new file mode 100644 index 0000000..309f1cd --- /dev/null +++ b/packages/javascript/src/addons/breadcrumbs.ts @@ -0,0 +1,659 @@ +/** + * @file Breadcrumbs module - captures chronological trail of events before an error + */ +import type { Breadcrumb, BreadcrumbLevel, BreadcrumbType, Json, JsonNode } from '@hawk.so/types'; +import Sanitizer from '../modules/sanitizer'; +import { buildElementSelector } from '../utils/selector'; +import log from '../utils/log'; + +/** + * Default maximum number of breadcrumbs to store + */ +const DEFAULT_MAX_BREADCRUMBS = 15; + +/** + * Maximum length for string values in breadcrumb data + */ +const DEFAULT_MAX_VALUE_LENGTH = 1024; + +/** + * Hint object passed to beforeBreadcrumb callback + */ +export interface BreadcrumbHint { + /** + * Original event that triggered the breadcrumb (if any) + */ + event?: Event | Response | XMLHttpRequest; + + /** + * Request info for fetch/xhr breadcrumbs + */ + input?: RequestInfo | URL; + + /** + * Response data for fetch/xhr breadcrumbs + */ + response?: Response; + + /** + * XHR instance for xhr breadcrumbs + */ + xhr?: XMLHttpRequest; +} + +/** + * Configuration options for breadcrumbs + */ +export interface BreadcrumbsOptions { + /** + * Maximum number of breadcrumbs to store (FIFO) + * + * @default 15 + */ + maxBreadcrumbs?: number; + + /** + * Maximum length for string values (will be trimmed) + * + * @default 1024 + */ + maxValueLength?: number; + + /** + * Hook called before each breadcrumb is stored + * Return null to discard the breadcrumb + * Return modified breadcrumb to store it + */ + beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null; + + /** + * Enable automatic fetch/XHR breadcrumbs + * + * @default true + */ + trackFetch?: boolean; + + /** + * Enable automatic navigation breadcrumbs (history API) + * + * @default true + */ + trackNavigation?: boolean; + + /** + * Enable automatic UI click breadcrumbs + * + * @default true + */ + trackClicks?: boolean; +} + +/** + * Breadcrumb input type - breadcrumb data with optional timestamp + * (timestamp will be auto-generated if not provided) + */ +export type BreadcrumbInput = Omit & { timestamp?: Breadcrumb['timestamp'] }; + +/** + * Internal breadcrumbs options - all fields except 'beforeBreadcrumb' are required + * (they have default values and are always set during init) + */ +interface InternalBreadcrumbsOptions { + maxBreadcrumbs: number; + maxValueLength: number; + trackFetch: boolean; + trackNavigation: boolean; + trackClicks: boolean; + beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null; +} + +/** + * BreadcrumbManager - singleton that manages breadcrumb collection and storage + */ +export class BreadcrumbManager { + /** + * Singleton instance + */ + private static instance: BreadcrumbManager | null = null; + + /** + * Breadcrumbs buffer (FIFO) + */ + private readonly breadcrumbs: Breadcrumb[] = []; + + /** + * Configuration options - all fields are guaranteed to be set (except optional beforeBreadcrumb) + */ + private options: InternalBreadcrumbsOptions; + + /** + * Initialization flag + */ + private isInitialized = false; + + /** + * Original fetch function (for restoration) + */ + private originalFetch: typeof fetch | null = null; + + /** + * Original XMLHttpRequest.open (for restoration) + */ + private originalXHROpen: typeof XMLHttpRequest.prototype.open | null = null; + + /** + * Original XMLHttpRequest.send (for restoration) + */ + private originalXHRSend: typeof XMLHttpRequest.prototype.send | null = null; + + /** + * Original history.pushState (for restoration) + */ + private originalPushState: typeof history.pushState | null = null; + + /** + * Original history.replaceState (for restoration) + */ + private originalReplaceState: typeof history.replaceState | null = null; + + /** + * Click event handler reference (for removal) + */ + private clickHandler: ((event: MouseEvent) => void) | null = null; + + /** + * Popstate event handler reference (for removal) + */ + private popstateHandler: (() => void) | null = null; + + /** + * Private constructor to enforce singleton pattern + */ + private constructor() { + this.options = { + maxBreadcrumbs: DEFAULT_MAX_BREADCRUMBS, + maxValueLength: DEFAULT_MAX_VALUE_LENGTH, + trackFetch: true, + trackNavigation: true, + trackClicks: true, + }; + } + + /** + * Get singleton instance + */ + public static getInstance(): BreadcrumbManager { + BreadcrumbManager.instance ??= new BreadcrumbManager(); + + return BreadcrumbManager.instance; + } + + /** + * Initialize breadcrumbs with options and start auto-capture + * + * @param options - Configuration options for breadcrumbs + */ + public init(options: BreadcrumbsOptions = {}): void { + if (this.isInitialized) { + log('[BreadcrumbManager] init has already been called; breadcrumb configuration is global and subsequent init options are ignored.', 'warn'); + + return; + } + + this.options = { + maxBreadcrumbs: options.maxBreadcrumbs ?? DEFAULT_MAX_BREADCRUMBS, + maxValueLength: options.maxValueLength ?? DEFAULT_MAX_VALUE_LENGTH, + beforeBreadcrumb: options.beforeBreadcrumb, + trackFetch: options.trackFetch ?? true, + trackNavigation: options.trackNavigation ?? true, + trackClicks: options.trackClicks ?? true, + }; + + this.isInitialized = true; + + /** + * Setup auto-capture handlers + */ + if (this.options.trackFetch) { + this.monkeypatchFetch(); + this.wrapXHR(); + } + + if (this.options.trackNavigation) { + this.wrapHistory(); + } + + if (this.options.trackClicks) { + this.setupClickTracking(); + } + } + + /** + * Add a breadcrumb to the buffer + * + * @param breadcrumb - The breadcrumb data to add + * @param hint - Optional hint object with original event data (Event, Response, XMLHttpRequest, etc.) + * Used by beforeBreadcrumb callback to access original event context + */ + public addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: BreadcrumbHint): void { + /** + * Ensure timestamp + */ + const bc: Breadcrumb = { + ...breadcrumb, + timestamp: breadcrumb.timestamp ?? Date.now(), + }; + + /** + * Apply beforeBreadcrumb hook + */ + if (this.options.beforeBreadcrumb) { + const result = this.options.beforeBreadcrumb(bc, hint); + + if (result === null) { + /** + * Discard breadcrumb + */ + return; + } + + Object.assign(bc, result); + } + + /** + * Sanitize and trim data + */ + if (bc.data) { + bc.data = this.sanitizeData(bc.data); + } + + if (bc.message) { + bc.message = this.trimString(bc.message, this.options.maxValueLength); + } + + /** + * Add to buffer (FIFO - keep last N breadcrumbs) + */ + this.breadcrumbs.push(bc); + + if (this.breadcrumbs.length > this.options.maxBreadcrumbs) { + this.breadcrumbs.shift(); + } + } + + /** + * Get current breadcrumbs snapshot (oldest to newest) + */ + public getBreadcrumbs(): Breadcrumb[] { + return [ ...this.breadcrumbs ]; + } + + /** + * Clear all breadcrumbs + */ + public clearBreadcrumbs(): void { + this.breadcrumbs.length = 0; + } + + /** + * Destroy the manager and restore original functions + */ + public destroy(): void { + /** + * Restore fetch + */ + if (this.originalFetch) { + window.fetch = this.originalFetch; + this.originalFetch = null; + } + + /** + * Restore XHR + */ + if (this.originalXHROpen) { + XMLHttpRequest.prototype.open = this.originalXHROpen; + this.originalXHROpen = null; + } + + if (this.originalXHRSend) { + XMLHttpRequest.prototype.send = this.originalXHRSend; + this.originalXHRSend = null; + } + + /** + * Restore history + */ + if (this.originalPushState) { + history.pushState = this.originalPushState; + this.originalPushState = null; + } + + if (this.originalReplaceState) { + history.replaceState = this.originalReplaceState; + this.originalReplaceState = null; + } + + /** + * Remove click handler + */ + if (this.clickHandler) { + document.removeEventListener('click', this.clickHandler, { capture: true }); + this.clickHandler = null; + } + + /** + * Remove popstate handler + */ + if (this.popstateHandler) { + window.removeEventListener('popstate', this.popstateHandler); + this.popstateHandler = null; + } + + this.clearBreadcrumbs(); + this.isInitialized = false; + BreadcrumbManager.instance = null; + } + + /** + * Sanitize breadcrumb data object + * Sanitizer already trims strings, so no additional trimming needed + * + * @param data - The data object to sanitize + */ + private sanitizeData(data: Record): Record { + return Sanitizer.sanitize(data) as Record; + } + + /** + * Trim string to max length + * + * @param str - The string to trim + * @param maxLength - Maximum allowed length + */ + private trimString(str: string, maxLength: number): string { + if (str.length > maxLength) { + return str.substring(0, maxLength) + '…'; + } + + return str; + } + + /** + * Monkeypatch fetch API to capture HTTP breadcrumbs + */ + private monkeypatchFetch(): void { + if (typeof fetch === 'undefined') { + return; + } + + const originalFetch = window.fetch.bind(window); + + this.originalFetch = originalFetch; + + // eslint-disable-next-line @typescript-eslint/no-this-alias + const manager = this; + + window.fetch = async function (input: RequestInfo | URL, init?: RequestInit): Promise { + const startTime = Date.now(); + const method = init?.method || 'GET'; + let url: string; + + if (typeof input === 'string') { + url = input; + } else if (input instanceof URL) { + url = input.href; + } else { + url = input.url; + } + + let response: Response; + + try { + response = await originalFetch(input, init); + + const duration = Date.now() - startTime; + + manager.addBreadcrumb({ + type: 'request', + category: 'fetch', + message: `${response.status} ${method} ${url}`, + level: response.ok ? 'info' : 'error', + data: { + url, + method, + statusCode: response.status, + durationMs: duration, + }, + }, { + input, + response, + }); + + return response; + } catch (error) { + const duration = Date.now() - startTime; + + manager.addBreadcrumb({ + type: 'request', + category: 'fetch', + message: `[FAIL] ${method} ${url}`, + level: 'error', + data: { + url, + method, + durationMs: duration, + error: error instanceof Error ? error.message : String(error), + }, + }, { + input, + }); + + throw error; + } + }; + } + + /** + * Wrap XMLHttpRequest to capture XHR breadcrumbs + */ + private wrapXHR(): void { + if (typeof XMLHttpRequest === 'undefined') { + return; + } + + // eslint-disable-next-line @typescript-eslint/no-this-alias + const manager = this; + const originalOpen = XMLHttpRequest.prototype.open; + const originalSend = XMLHttpRequest.prototype.send; + + this.originalXHROpen = originalOpen; + this.originalXHRSend = originalSend; + + /** + * Store request info on the XHR instance + */ + interface XHRWithBreadcrumb extends XMLHttpRequest { + hawkMethod?: string; + hawkUrl?: string; + hawkStart?: number; + hawkListenerAdded?: boolean; + } + + XMLHttpRequest.prototype.open = function (this: XHRWithBreadcrumb, method: string, url: string | URL, ...args: unknown[]) { + this.hawkMethod = method; + this.hawkUrl = typeof url === 'string' ? url : url.href; + + return originalOpen.apply(this, [method, url, ...args] as Parameters); + }; + + XMLHttpRequest.prototype.send = function (this: XHRWithBreadcrumb, body?: Document | XMLHttpRequestBodyInit | null) { + this.hawkStart = Date.now(); + + const onReadyStateChange = (): void => { + if (this.readyState === XMLHttpRequest.DONE) { + const duration = Date.now() - (this.hawkStart || Date.now()); + const method = this.hawkMethod || 'GET'; + const url = this.hawkUrl || ''; + const status = this.status; + + manager.addBreadcrumb({ + type: 'request', + category: 'xhr', + message: `${status} ${method} ${url}`, + level: status >= 200 && status < 400 ? 'info' : 'error', + data: { + url, + method, + statusCode: status, + durationMs: duration, + }, + }, { + xhr: this, + }); + } + }; + + /** + * Add listener only once per XHR instance to prevent duplicates + */ + if (!this.hawkListenerAdded) { + this.addEventListener('readystatechange', onReadyStateChange); + this.hawkListenerAdded = true; + } + + return originalSend.call(this, body); + }; + } + + /** + * Wrap History API to capture navigation breadcrumbs + */ + private wrapHistory(): void { + if (typeof history === 'undefined') { + return; + } + + // eslint-disable-next-line @typescript-eslint/no-this-alias + const manager = this; + let lastUrl = window.location.href; + + const createNavigationBreadcrumb = (to: string): void => { + const from = lastUrl; + + lastUrl = to; + + manager.addBreadcrumb({ + type: 'navigation', + category: 'navigation', + message: `Navigated to ${to}`, + level: 'info', + data: { + from, + to, + }, + }); + }; + + /** + * Wrap pushState + */ + this.originalPushState = history.pushState; + history.pushState = function (...args) { + const result = manager.originalPushState!.apply(this, args); + + createNavigationBreadcrumb(window.location.href); + + return result; + }; + + /** + * Wrap replaceState + */ + this.originalReplaceState = history.replaceState; + history.replaceState = function (...args) { + const result = manager.originalReplaceState!.apply(this, args); + + createNavigationBreadcrumb(window.location.href); + + return result; + }; + + /** + * Listen for popstate (back/forward) + */ + this.popstateHandler = (): void => { + createNavigationBreadcrumb(window.location.href); + }; + + window.addEventListener('popstate', this.popstateHandler); + } + + /** + * Setup click event tracking for UI breadcrumbs + */ + private setupClickTracking(): void { + // eslint-disable-next-line @typescript-eslint/no-this-alias + const manager = this; + + this.clickHandler = (event: MouseEvent): void => { + const target = event.target as HTMLElement; + + if (!target) { + return; + } + + /** + * Build a simple selector + */ + const selector = buildElementSelector(target); + + /** + * Get text content (limited) + */ + const text = (target.textContent || target.innerText || '').trim().substring(0, 50); + + manager.addBreadcrumb({ + type: 'ui', + category: 'ui.click', + message: `Click on ${selector}`, + level: 'info', + data: { + selector, + text, + tagName: target.tagName, + }, + }, { + event, + }); + }; + + document.addEventListener('click', this.clickHandler, { + capture: true, + passive: true }); + } +} + +/** + * Helper function to create a breadcrumb object + * + * @param message - The breadcrumb message + * @param options - Optional breadcrumb configuration + */ +export function createBreadcrumb( + message: string, + options?: { + type?: BreadcrumbType; + category?: string; + level?: BreadcrumbLevel; + data?: Record; + } +): Breadcrumb { + return { + timestamp: Date.now(), + message, + type: options?.type ?? 'default', + category: options?.category, + level: options?.level ?? 'info', + data: options?.data, + }; +} diff --git a/packages/javascript/src/catcher.ts b/packages/javascript/src/catcher.ts index 3511a65..313ba93 100644 --- a/packages/javascript/src/catcher.ts +++ b/packages/javascript/src/catcher.ts @@ -2,7 +2,7 @@ import Socket from './modules/socket'; import Sanitizer from './modules/sanitizer'; import log from './utils/log'; import StackParser from './modules/stackParser'; -import type { CatcherMessage, HawkInitialSettings } from './types'; +import type { CatcherMessage, HawkInitialSettings, BreadcrumbsAPI } from './types'; import { VueIntegration } from './integrations/vue'; import { id } from './utils/id'; import type { @@ -10,13 +10,14 @@ import type { EventContext, JavaScriptAddons, VueIntegrationAddons, - Json, EncodedIntegrationToken, DecodedIntegrationToken + Json, EncodedIntegrationToken, DecodedIntegrationToken, } from '@hawk.so/types'; import type { JavaScriptCatcherIntegrations } from './types/integrations'; import { EventRejectedError } from './errors'; import type { HawkJavaScriptEvent } from './types'; import { isErrorProcessed, markErrorAsProcessed } from './utils/event'; import { ConsoleCatcher } from './addons/consoleCatcher'; +import { BreadcrumbManager } from './addons/breadcrumbs'; import { validateUser, validateContext } from './utils/validation'; /** @@ -103,6 +104,11 @@ export default class Catcher { */ private readonly consoleCatcher: ConsoleCatcher | null = null; + /** + * Breadcrumb manager instance + */ + private readonly breadcrumbManager: BreadcrumbManager | null; + /** * Catcher constructor * @@ -159,6 +165,16 @@ export default class Catcher { this.consoleCatcher.init(); } + /** + * Initialize breadcrumbs + */ + if (settings.breadcrumbs !== false) { + this.breadcrumbManager = BreadcrumbManager.getInstance(); + this.breadcrumbManager.init(settings.breadcrumbs ?? {}); + } else { + this.breadcrumbManager = null; + } + /** * Set global handlers */ @@ -264,6 +280,26 @@ export default class Catcher { this.user = Catcher.getGeneratedUser(); } + /** + * Breadcrumbs API - provides convenient access to breadcrumb methods + * + * @example + * hawk.breadcrumbs.add({ + * type: 'user', + * category: 'auth', + * message: 'User logged in', + * level: 'info', + * data: { userId: '123' } + * }); + */ + public get breadcrumbs(): BreadcrumbsAPI { + return { + add: (breadcrumb, hint) => this.breadcrumbManager?.addBreadcrumb(breadcrumb, hint), + get: () => this.breadcrumbManager?.getBreadcrumbs() ?? [], + clear: () => this.breadcrumbManager?.clearBreadcrumbs(), + }; + } + /** * Update the context data that will be sent with all events * @@ -388,6 +424,7 @@ export default class Catcher { title: this.getTitle(error), type: this.getType(error), release: this.getRelease(), + breadcrumbs: this.getBreadcrumbsForEvent(), context: this.getContext(context), user: this.getUser(), addons: this.getAddons(error), @@ -504,6 +541,15 @@ export default class Catcher { return this.user || null; } + /** + * Get breadcrumbs for event payload + */ + private getBreadcrumbsForEvent(): HawkJavaScriptEvent['breadcrumbs'] { + const breadcrumbs = this.breadcrumbManager?.getBreadcrumbs(); + + return breadcrumbs && breadcrumbs.length > 0 ? breadcrumbs : null; + } + /** * Get parameters */ diff --git a/packages/javascript/src/types/breadcrumbs-api.ts b/packages/javascript/src/types/breadcrumbs-api.ts new file mode 100644 index 0000000..777dcdf --- /dev/null +++ b/packages/javascript/src/types/breadcrumbs-api.ts @@ -0,0 +1,11 @@ +import type { Breadcrumb } from '@hawk.so/types'; +import type { BreadcrumbInput, BreadcrumbHint } from '../addons/breadcrumbs'; + +/** + * Breadcrumbs API interface + */ +export interface BreadcrumbsAPI { + add: (breadcrumb: BreadcrumbInput, hint?: BreadcrumbHint) => void; + get: () => Breadcrumb[]; + clear: () => void; +} diff --git a/packages/javascript/src/types/event.ts b/packages/javascript/src/types/event.ts index eebaf63..82dec49 100644 --- a/packages/javascript/src/types/event.ts +++ b/packages/javascript/src/types/event.ts @@ -1,4 +1,4 @@ -import type { AffectedUser, BacktraceFrame, EventContext, EventData, JavaScriptAddons } from '@hawk.so/types'; +import type { AffectedUser, BacktraceFrame, EventContext, EventData, JavaScriptAddons, Breadcrumb } from '@hawk.so/types'; /** * Event data with JS specific addons @@ -10,7 +10,7 @@ type JSEventData = EventData; * * The listed EventData properties will always be sent, so we define them as required in the type */ -export type HawkJavaScriptEvent = Omit & { +export type HawkJavaScriptEvent = Omit & { /** * Event type: TypeError, ReferenceError etc * null for non-error events @@ -22,6 +22,11 @@ export type HawkJavaScriptEvent = Omit 0 && element.parentElement) { + const parentSelector = buildElementSelector(element.parentElement as HTMLElement, maxDepth - 1); + + return `${parentSelector} ${selector}`; + } + + return selector; +} diff --git a/yarn.lock b/yarn.lock index 3aa494e..a20c17c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -316,12 +316,12 @@ minimatch "^3.0.4" strip-json-comments "^3.1.1" -"@hawk.so/types@^0.1.36": - version "0.1.36" - resolved "https://registry.yarnpkg.com/@hawk.so/types/-/types-0.1.36.tgz#234b0e4c81bf5f50b1208910d45fc4ffb62e8ae1" - integrity sha512-AjW4FZPMqlDoXk63ntkTGOC1tdbHuGXIhEbVtBvz8YC9A7qcuxenzfGtjwuW6B9tqyADMGehh+/d+uQbAX7w0Q== +"@hawk.so/types@0.5.2": + version "0.5.2" + resolved "https://registry.yarnpkg.com/@hawk.so/types/-/types-0.5.2.tgz#504eabed7d510431411a3e39d8af008e76bb4f41" + integrity sha512-+7gkelP6P5VMxOLHjcWUlX8hx8OR0k0ag9EyrqvJxMF+hNW49udARNM+PU5R0MFgyyq2L4ltCy0c2BsUi9yPww== dependencies: - "@types/mongodb" "^3.5.34" + bson "^7.0.0" "@humanwhocodes/config-array@^0.5.0": version "0.5.0" @@ -559,12 +559,6 @@ resolved "https://registry.yarnpkg.com/@types/argparse/-/argparse-1.0.38.tgz#a81fd8606d481f873a3800c6ebae4f1d768a56a9" integrity sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA== -"@types/bson@*": - version "4.0.3" - resolved "https://registry.yarnpkg.com/@types/bson/-/bson-4.0.3.tgz#30889d2ffde6262abbe38659364c631454999fbf" - dependencies: - "@types/node" "*" - "@types/color-name@^1.1.1": version "1.1.1" resolved "https://registry.yarnpkg.com/@types/color-name/-/color-name-1.1.1.tgz#1c1261bbeaa10a8055bbc5d8ab84b7b2afc846a0" @@ -584,17 +578,6 @@ resolved "https://registry.yarnpkg.com/@types/json5/-/json5-0.0.29.tgz#ee28707ae94e11d2b827bcbe5270bcea7f3e71ee" integrity sha1-7ihweulOEdK4J7y+UnC86n8+ce4= -"@types/mongodb@^3.5.34": - version "3.6.11" - resolved "https://registry.yarnpkg.com/@types/mongodb/-/mongodb-3.6.11.tgz#918ecc4cbe6fa15d26c4fe12c00cf0d4c3cf421d" - dependencies: - "@types/bson" "*" - "@types/node" "*" - -"@types/node@*": - version "14.14.37" - resolved "https://registry.yarnpkg.com/@types/node/-/node-14.14.37.tgz#a3dd8da4eb84a996c36e331df98d82abd76b516e" - "@types/semver@^7.5.0": version "7.5.8" resolved "https://registry.yarnpkg.com/@types/semver/-/semver-7.5.8.tgz#8268a8c57a3e4abd25c165ecd36237db7948a55e" @@ -986,6 +969,11 @@ braces@^3.0.3: dependencies: fill-range "^7.1.1" +bson@^7.0.0: + version "7.1.1" + resolved "https://registry.yarnpkg.com/bson/-/bson-7.1.1.tgz#19965d9138e1c4d88e4690414d91c84f217c84e8" + integrity sha512-TtJgBB+QyOlWjrbM+8bRgH84VM/xrDjyBFgSgGrfZF4xvt6gbEDtcswm27Tn9F9TWsjQybxT8b8VpCP/oJK4Dw== + builtin-modules@^3.3.0: version "3.3.0" resolved "https://registry.yarnpkg.com/builtin-modules/-/builtin-modules-3.3.0.tgz#cae62812b89801e9656336e46223e030386be7b6"