# JavaScript SDK

Use the `cronitor` package to report job runs, heartbeats, and metrics to Cronitor from Node.js, Bun, or Deno.

## Install

```bash
npm install cronitor
```

The package runs on servers. It is not for browsers.

## Configure

Set the `CRONITOR_API_KEY` environment variable to your SDK Integration key. Copy the key from Settings → API Keys at https://cronitor.io/app/settings/api. Keep the key in the environment or a secret store of the runtime. Do not commit it.

Call the package without an API key. It then reads `CRONITOR_API_KEY`:

```javascript
const cronitor = require('cronitor')();
```

## Monitor a job

`cronitor.wrap` gives a new function. Call that function to run the job:

```javascript
const cronitor = require('cronitor')();

const sendInvoices = cronitor.wrap('send-invoices', async () => {
  // the work of the job
});

sendInvoices();
```

- Before the function starts, the SDK sends a `run` event.
- When the function returns or its promise resolves, the SDK sends a `complete` event.
- When the function throws or its promise rejects, the SDK sends a `fail` event with the error. The wrapper does not throw the error again.
- Cronitor calculates the `duration` from the `run` event and the `complete` or `fail` event.
- The events go to the monitor with the key `send-invoices`. If no monitor has this key, Cronitor creates one on the first event.

If the function gives a string, the SDK sends it as the message of the `complete` event.

To monitor jobs that you schedule with [node-cron](https://github.com/node-cron/node-cron) or [cron](https://github.com/kelektiv/node-cron), use `cronitor.wraps`. See the [README](https://github.com/cronitorio/cronitor-js#integrate-with-cron-libraries).

To send the events yourself, use a `Monitor`:

```javascript
const monitor = new cronitor.Monitor('send-invoices');
await monitor.ping({ state: 'run' });
await monitor.ping({ state: 'complete' }); // or state: 'fail'
```

## Send a heartbeat

Send a ping each time the process completes a unit of useful work:

```javascript
const cronitor = require('cronitor')();

const monitor = new cronitor.Monitor('queue-worker');
monitor.ping({ message: 'Alive!' });
```

To attach metrics, give a `metrics` object. The SDK sends each item as `metric=name:value`. It ignores metrics at the top level, such as `{ count: 100 }`:

```javascript
monitor.ping({ metrics: { count: 100, error_count: 3 } });
```

If you only want to record custom metrics, use a heartbeat monitor. See [Custom Metrics](https://cronitor.io/docs/custom-metrics.md).

## Verify

After one real run, check the state of the monitor. A successful telemetry response shows only that Cronitor received the request. It does not show that Cronitor stored the event or matched it to a monitor.

With the [MCP server](https://cronitor.io/docs/mcp-server.md):

```text
get_status({"key": "send-invoices"})
```

With [CronitorCLI](https://cronitor.io/docs/using-cronitor-cli.md):

```bash
cronitor status send-invoices
```

`monitor.ping` does not throw. If the request fails, it logs the error and gives `false`.

## Reference

- [cronitor-js on GitHub](https://github.com/cronitorio/cronitor-js): the full README, including cron library integration and YAML configuration.
- [Telemetry API](https://cronitor.io/docs/telemetry-api.md): the events and parameters that the SDK sends.