Package Exports

@cronbeats/cronbeats-node
@cronbeats/cronbeats-node/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cronbeats/cronbeats-node) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CronBeats Node SDK (Ping)

Official Node.js SDK for CronBeats ping telemetry.

Install (local/dev)

npm install

SDK API

ping()
start()
end("success" | "fail")
success()
fail()
progress(seqOrOptions, message?)

Quick Usage

import { PingClient } from "./dist/index.js";

const client = new PingClient("abc123de", {
  baseUrl: "https://cronbeats.io",
  timeoutMs: 5000,
  maxRetries: 2,
});

await client.start();
// ...your work...
await client.success();

Progress Tracking

Track your job's progress in real-time. CronBeats supports two distinct modes:

Mode 1: With Percentage (0-100)

Shows a progress bar and your status message on the dashboard.

✓ Use when: You can calculate meaningful progress (e.g., processed 750 of 1000 records)

// Percentage mode: 0-100 with message
await client.progress(50, "Processing batch 500/1000");

// Or using options object
await client.progress({
  seq: 75,
  message: "Almost done - 750/1000",
});

Mode 2: Message Only

Shows only your status message (no percentage bar) on the dashboard.

✓ Use when: Progress isn't measurable or you only want to send status updates

// Message-only mode: null seq, just status updates
await client.progress(null, "Connecting to database...");
await client.progress(null, "Starting data sync...");

What you see on the dashboard

Mode 1: Progress bar (0-100%) + your message → "75% - Processing batch 750/1000"
Mode 2: Only your status message → "Connecting to database..."

Complete Example

import { PingClient } from "@cronbeats/cronbeats-node";

const client = new PingClient("abc123de");
await client.start();

try {
  // Message-only updates for non-measurable steps
  await client.progress(null, "Connecting to database...");
  const db = await connectToDatabase();
  
  await client.progress(null, "Fetching records...");
  const total = await db.count();
  
  // Percentage updates for measurable progress
  for (let i = 0; i < total; i++) {
    await processRecord(i);
    
    if (i % 100 === 0) {
      const percent = Math.floor((i * 100) / total);
      await client.progress(percent, `Processed ${i} / ${total} records`);
    }
  }
  
  await client.progress(100, "All records processed");
  await client.success();
  
} catch (err) {
  await client.fail();
  throw err;
}

Error Handling

import { ApiError, ValidationError } from "./dist/index.js";

try {
  await client.ping();
} catch (err) {
  if (err instanceof ValidationError) {
    // Invalid local inputs
  } else if (err instanceof ApiError) {
    // API/network issue
    console.log(err.code, err.httpStatus, err.retryable);
  }
}

Notes

Uses POST for telemetry requests.
jobKey must be exactly 8 Base62 characters.
Retries only for network errors, HTTP 429, and HTTP 5xx.
Default timeout is 5s to avoid blocking cron jobs.