healthcheck-module

TypeScript SDK for orchestrating health checks via pluggable adapters. Sensu is supported out of the box, but the core/adapter split makes it easy to add your own wires.

Quick Start

npm install healthcheck-module

import { HealthCheck, SensuHealthCheckAdapter } from 'healthcheck-module';

const client = new HealthCheck(
  {
    endpoint: 'http://localhost:58080',
    default_org_id: 'default',
    username: 'admin',
    password: 'admin',
  },
  { adapter: 'sensu' }
);
await client.waitForBootstrap();

const createResult = await client.createCheck({
  name: 'check-http',
  command: 'curl -fsS https://example.com/healthz',
  agent_id: ['agent-01'], // auto-prefixed to `entity:agent-01`
  org_id: 'default',
  interval: 30,
  handlers: ['event-forwarder'],
});
console.log(createResult); // { ok, status }

const updateResult = await client.updateCheck({
  name: 'check-http',
  command: 'curl -fsS https://example.com/healthz --timeout 3',
  agent_id: ['agent-01'],
  org_id: 'default',
  handlers: ['event-forwarder'],
});
console.log(updateResult); // { ok, status }
 
const checks = await client.listChecks({ org_id: 'default' }); // pass an org_id to override the client's default
console.log(checks);

const agents = await client.listAgents({ org_id: 'default' });
console.log(agents);

const agent = await client.getAgent({ name: 'agent-01' , org_id: 'default'});
console.log(agent);

const check = await client.getCheck({ name: 'check-http' , org_id: 'default'});
console.log(check);
// console.log(check.data.metadata); // { name: 'check-http', org_id: 'default', labels: {}, annotations: {} }
// console.log(client.getEndpoint(), client.getOrgId(), client.getConfig());

// const events = await client.listEvents({ org_id: 'default' });
// console.log(events);

// const event = await client.getEvent({ agent_id: 'agent-01', check: 'check-http' });
// console.log(event);

const deleteResult = await client.deleteCheck({ name: 'check-http', org_id: 'default' });
console.log("deleteCheck", deleteResult); // { ok, status }

// Advanced Sensu-specific helpers (namespaces, handlers, full check payloads, etc.)
// still live on the adapter. When you need one of those APIs, grab the adapter via
// `HealthCheck.getManager().getAdapter('sensu')` and call it directly.

Every facade method returns { ok, status, data? }. For mutating operations (createCheck, updateCheck, deleteCheck) the data field is omitted; list/get helpers populate data with the expected payload.

Configuration

• endpoint – base URL to your Sensu backend (http://host:port).
• authToken / apiKey – direct credentials if you already have a Sensu token.
• username + password – provide these instead of authToken to let the adapter fetch a token and mint/store an API key automatically.
• default_org_id – sets the org/namespace to use whenever a call doesn’t explicitly provide its own org_id.
• adapter – omit to use the shared Sensu adapter; pass a string or instance to override.
• waitForBootstrap() – call once after instantiating a client to ensure the adapter finishes provisioning credentials/handlers before issuing requests.

HealthCheck.createCheck expects agent_id: string[] (formerly subscriptions). Values are normalized to Sensu’s entity:* subscriptions when missing the prefix, so both bare entity names and explicit subscription strings are supported.

Facade helpers

• createCheck(options) – minimal check creation.
• updateCheck(options) – same shape as createCheck, updates an existing check.
• listChecks(options?) / getCheck(name, options?) / deleteCheck(name, options?)
• listAgents(options?) / getAgent(options) – agent summaries.
• listEvents(options?) / getEvent(options) – event summaries.
• getEndpoint(), getOrgId(), getConfig() – diagnostics.

Project Structure

• src/HealthCheck.ts – facade / public API
• src/core/* – core engine + adapter manager
• src/adapters/sensu – Sensu implementation (HTTP clients, default payloads)
• src/types/* – shared DTOs (HealthCheckConfig, CreateCheckOptions, CheckSummary, EntitySummary)
• examples/ – runnable scripts (create-checks, update-check, list-checks, get-check, delete-check, list-agents, get-agent, events, fetch-token, create-apikey, bootstrap-with-credentials)
• tests/ – Jest suites for facade and Sensu wires
• Examples accept SENSU_ENDPOINT, SENSU_ORG_ID (or legacy SENSU_NAMESPACE), SENSU_USERNAME, and SENSU_PASSWORD env vars (defaults target http://localhost:58080 and admin/admin). When only username/password are provided, the adapter will automatically fetch a token, mint an API key, and reuse it for all requests. Pass default_org_id when instantiating the client to set the initial org.

Publishing to npm

Set NPM_TOKEN in .env. Run:

./scripts/publish.sh

(Defaults publish to npmjs.org with latest tag & public access; currently runs with --dry-run.)