@hawk.so/nodejs

Node.js errors Catcher module for Hawk.so

Initial params

Initialization params:

| name | type | required | description |
| -- | -- | -- | -- |
| token | string | required | Your project's Integration Token |
| release | string | optional | Unique identifier of the release. |
| context | object | optional | Any data you want to pass with every message. |
| disableGlobalErrorsHandling | boolean | optional | Do not initialize global errors handling |
| beforeSend | function(event) => event | optional | This Method allows you to filter any data you don't want sending to Hawk |
| breadcrumbs | false or object | optional | Pass false to disable. Pass options object to configure (see Breadcrumbs). Default: enabled. |

Usage

1. Create an account and get an Integration Token.
2. Add @hawk.so/nodejs package to your project.
3. Require and initialize module.

$3

Use NPM or Yarn to install Catcher @hawk.so/nodejs.

``bash
$ npm install @hawk.so/nodejs --save
`

`bash
$ yarn add @hawk.so/nodejs
`

$3

#### For CommonJS projects

`js
const HawkCatcher = require('@hawk.so/nodejs').default;
`

#### For ESM projects

`js
import HawkCatcher from '@hawk.so/nodejs';
`

$3

Initialize HawkCatcher in the entry file of your project by passing a project token.

`js
const HAWK_TOKEN = 'eyJhb...VPsc=';

HawkCatcher.init(HAWK_TOKEN);
`

HawkCatcher adds listeners for uncaughtException and unhandledRejection itself.

#### Disable global errors handling

If you don't want to initialize handlers for global exceptions then use disableGlobalErrorsHandling param.

`js
HawkCatcher.init({
token: HAWK_TOKEN,
disableGlobalErrorsHandling: true,
});
`

Then you can catch events manually.

$3

You can define global context for all event to be caught.

`js
HawkCatcher.init({
token: HAWK_TOKEN,
context: {
myOwnDebugInfo: '1234'
}
});
`

$3

To mark events to specific release pass the release identifier string to intial config.

`js
HawkCatcher.init({
token: 'INTEGRATION TOKEN',
release: process.env.releaseId
})
`

$3

After initializing you can catch exceptions manually in try-catch constructions in any project's place.

Just require HawkCatcher and call .send() method.

`js
try {
throw new Error('My lovely error');
} catch (e) {
HawkCatcher.send(e);
}
`

If HawkCatcher was not initialized then .send() method will do nothing.


#### Event context

You can pass any information as context param for a single event.

`js
try {
throw new Error('User not found');
} catch (e) {
HawkCatcher.send(e, {
myOwnDebugInfo: '1234'
});
}
`

This context object will be merged with global context if it exists.

#### User

You can send user data as a third param.

Available fields:
| Param | Type | Is required | Description |
| --- | --- | --- | --- |
| id | string\|number | required | User's identifier |
| name | string | - | User's name |
| url | string | - | User's profile url |
| image | string | - | User's profile pic url |

`js
try {
throw new Error('Cannot create a new post');
} catch (e) {
HawkCatcher.send(e, {}, {
id: 1234,
name: 'Taly'
});
}
`

$3

Breadcrumbs track events leading up to an error, providing context for debugging. Same API as @hawk.so/javascript (add, get, clear); in Node there is no automatic tracking of fetch/navigation/clicks, only manual breadcrumbs.

#### Default configuration

By default, breadcrumbs are enabled (custom breadcrumbs only):

`js
HawkCatcher.init({
token: 'INTEGRATION_TOKEN'
// breadcrumbs enabled by default
});
`

#### Disabling breadcrumbs

To disable breadcrumbs entirely:

`js
HawkCatcher.init({
token: 'INTEGRATION_TOKEN',
breadcrumbs: false
});
`

#### Custom configuration

Configure breadcrumbs (same options as JS where applicable):

`js
HawkCatcher.init({
token: 'INTEGRATION_TOKEN',
breadcrumbs: {
maxBreadcrumbs: 20,
beforeBreadcrumb: (breadcrumb, hint) => {
if (breadcrumb.category === 'auth' && breadcrumb.data?.userId) {
return null; // Discard
}
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). |
| 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. |

#### Manual breadcrumbs

Add custom breadcrumbs manually. Breadcrumbs accumulate in a buffer and are attached to every event until explicitly cleared via HawkCatcher.breadcrumbs.clear():

`js
HawkCatcher.breadcrumbs.add({
type: 'logic',
category: 'auth',
message: 'User logged in',
level: 'info',
data: { userId: '123' }
});
`

#### Breadcrumb methods

Same as in JS catcher:

`js
// Add a breadcrumb
HawkCatcher.breadcrumbs.add(breadcrumb, hint);

// Get current breadcrumbs
const breadcrumbs = HawkCatcher.breadcrumbs.get();

// Clear all breadcrumbs
HawkCatcher.breadcrumbs.clear();
`

$3

You can filter any data that you don't want to send to Hawk. Use the beforeSend() hook for that reason.

`js
HawkCatcher.init({
token: 'INTEGRATION TOKEN',
beforeSend(event){
if (event.user && event.user.name){
delete event.user.name;
}

return event;
}
})
``

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See the LICENSE file for the full text.