Skip to main content

SDK Quick Start

The simplest way to monitor a job. wrap() automatically sends start, success, and fail pings — and captures the stack trace on error:

import { CrontifyMonitor } from '@crontify/sdk';

const monitor = new CrontifyMonitor({
  apiKey: process.env.CRONTIFY_API_KEY!,
  monitorId: process.env.CRONTIFY_MONITOR_ID!,
});

await monitor.wrap(async () => {
  await sendDailyDigestEmails();
});

If sendDailyDigestEmails() throws, wrap() calls fail() with the error message and stack trace attached, then re-throws — so your existing error handling continues to work.

With metadata​

Pass a meta object to record numeric output alongside the run. If any alert rules are configured on the monitor, they're evaluated against this data:

await monitor.wrap(async () => {
  const result = await syncInventory();
  await monitor.success({
    meta: {
      rows_synced: result.count,
      errors: result.errorCount,
    },
  });
});

For example, a rule of rows_synced eq 0 fires a silent_failure alert even though the job didn't throw — letting you catch jobs that ran but produced no output.

The manual pattern​

For more control — useful when your job has multiple phases or you want to include detailed metadata:

import { CrontifyMonitor } from '@crontify/sdk';

const monitor = new CrontifyMonitor({
  apiKey: process.env.CRONTIFY_API_KEY!,
  monitorId: process.env.CRONTIFY_MONITOR_ID!,
});

await monitor.start();

try {
  const result = await doWork();
  await monitor.success({
    meta: { rows_processed: result.count },
  });
} catch (error) {
  await monitor.fail({
    message: error instanceof Error ? error.message : 'Unknown error',
    log: error instanceof Error ? error.stack : undefined,
  });
  throw error; // Re-throw if you want the job runner to see the error
}

Managing multiple monitors​

Use CrontifyClient when you have several jobs sharing one API key:

import { CrontifyClient } from '@crontify/sdk';

const crontify = new CrontifyClient({
  apiKey: process.env.CRONTIFY_API_KEY!,
});

// Each call to .monitor() returns a cached CrontifyMonitor instance
const emailMonitor = crontify.monitor(process.env.EMAIL_MONITOR_ID!);
const reportMonitor = crontify.monitor(process.env.REPORT_MONITOR_ID!);
const cleanupMonitor = crontify.monitor(process.env.CLEANUP_MONITOR_ID!);

await emailMonitor.wrap(() => sendEmails());
await reportMonitor.wrap(() => generateReport());

Monitor instances are cached by ID — calling crontify.monitor(id) multiple times returns the same instance.

Silent mode (default)​

By default, SDK ping failures (network errors, API errors) are logged as warnings and never crash your job. A monitoring outage should never take down your scheduled tasks.

const monitor = new CrontifyMonitor({
  apiKey: process.env.CRONTIFY_API_KEY!,
  monitorId: process.env.CRONTIFY_MONITOR_ID!,
  silent: true, // This is the default
});

To disable silent mode (e.g. in tests where you want ping failures to throw):

const monitor = new CrontifyMonitor({
  apiKey: process.env.CRONTIFY_API_KEY!,
  monitorId: process.env.CRONTIFY_MONITOR_ID!,
  silent: false,
});