Installation

npm install @beacon-status/node

Initialization

Create a client instance with your API token and page slug.

import { Beacon } from '@beacon-status/node';

const beacon = new Beacon({
  token: process.env.BEACON_API_TOKEN!,
  baseUrl: process.env.BEACON_BASE_URL ?? 'https://app.beaconstatus.com',
  pageSlug: process.env.BEACON_PAGE_SLUG!,
});

Create an incident

await beacon.createIncident({
  title: 'Payment processing delays',
  impact: 'major',
  state: 'investigating',
  message: 'Stripe webhook delivery is delayed.',
});

Update component status

await beacon.updateComponent(componentId, {
  status: 'degraded',
});

Resolve an incident

await beacon.resolveIncident(incidentId,
  'Webhook delivery restored.'
);

Heartbeat

Send a heartbeat after your scheduled job completes.

import cron from 'node-cron';

cron.schedule('0 * * * *', async () => {
  await processInvoices();
  await beacon.heartbeat('invoice-processing-token');
});

Express middleware

import { beaconHealthCheck } from '@beacon-status/node/express';

app.get('/health', beaconHealthCheck(beacon));

Error handler

app.use((err, req, res, next) => {
  if (err.critical) {
    beacon.createIncident({
      title: `Critical: ${err.message}`,
      impact: 'critical',
    });
  }
  next(err);
});

TypeScript types

All types are exported from the main package.

import type {
  BeaconConfig,
  CreateIncidentData,
  UpdateIncidentData,
  UpdateComponentData,
  IncidentResponse,
  ComponentResponse,
  Impact,       // 'none' | 'minor' | 'major' | 'critical'
  State,        // 'investigating' | 'identified' | 'monitoring' | 'resolved'
  ComponentStatus, // 'operational' | 'degraded' | 'partial_outage' | ...
} from '@beacon-status/node';

Features

• TypeScript-first with full type definitions
• Zero runtime dependencies (native fetch, Node 18+)
• Automatic retries with exponential backoff (3 retries)
• Configurable timeout via AbortController
• Never throws on API errors — logs to console.warn
• Works with Express, Fastify, Next.js, NestJS
• ESM + CommonJS exports