pulsestack

TypeScript/JavaScript SDK for PulseStack: healthchecks and heartbeats. One API key (from API Keys in the dashboard) to create and manage healthchecks and heartbeats from code or IaC, and to build in-house dashboards.

API key and security

• Organization-scoped: Your API key is tied to a single organization. It can only access that organization’s healthchecks and heartbeats. Use one key per organization; do not reuse the same key across organizations.
• Create keys in the dashboard: API Keys → Create API key.

Setup

• Create an organization in PulseStack (if needed).
• In the dashboard go to API Keys → Create API key.
• Set PULSESTACK_API_KEY and optionally PULSESTACK_URL. Default base URL is https://pulsestack.io/api (production).

Installation

npm install @pulsestack/client

Usage

const PulseStack = require("@pulsestack/client");

const client = PulseStack({
  baseUrl: process.env.PULSESTACK_URL || "https://pulsestack.io/api",
  apiKey: process.env.PULSESTACK_API_KEY,
});

// --- Healthchecks ---
const check = await client.ensureHealthcheck("my-api", {
  interval: 60,
  url: "https://api.example.com/health",
  method: "GET",
  timeout: 10000,
  regions: ["us-east-1"],
});
const list = await client.listHealthchecks();
await client.updateHealthcheck(check.id, { enabled: false });

// Dashboard: results graph, latest (incl. errors), SLA metrics, performance
const graph = await client.getHealthcheckResultsGraph(check.id, { range: "24h" });
const latest = await client.getHealthcheckResultsLatest(check.id, { errorsOnly: true });
const sla = await client.getHealthcheckSLAMetrics(check.id, { range: "7d" });
const perf = await client.getHealthcheckPerformance(check.id, { range: "24h" });
const templates = await client.getHealthcheckSLATemplates();

// --- Heartbeats ---
const { uuid, pingUrl } = await client.ensureHeartbeat({
  name: "daily-backup",
  expectedIntervalSeconds: 86400,
  gracePeriodSeconds: 3600,
});
await client.ping(uuid);
await client.ping(uuid, { duration: 1200, source: process.env.HOSTNAME });

const heartbeats = await client.listHeartbeats({ includeLastPingSource: true });
const h = await client.getHeartbeat(heartbeats[0].id);
const history = await client.getHeartbeatHistory(h.id, { range: "7d" });

TypeScript / ESM

import PulseStack from "@pulsestack/client";
import type { HealthcheckListItem, Heartbeat } from "@pulsestack/client";

const client = PulseStack({ apiKey: process.env.PULSESTACK_API_KEY });
const list: HealthcheckListItem[] = await client.listHealthchecks();

Terraform / IaC

Use the HTTP provider or null_resource + local-exec with curl or this SDK.

Option 1: curl (no Node)

variable "pulsestack_api_key" {
  type      = string
  sensitive = true
}
variable "pulsestack_url" {
  type    = string
  default = "https://pulsestack.io/api"
}

resource "null_resource" "pulsestack_healthcheck" {
  provisioner "local-exec" {
    command = <<-EOT
      curl -s -X POST "${var.pulsestack_url}/healthchecks" \
        -H "Authorization: Bearer ${var.pulsestack_api_key}" \
        -H "Content-Type: application/json" \
        -d '{"name":"my-api","enabled":true,"config":{"interval":60,"request":{"method":"GET","url":"https://api.example.com/health","timeout":10000},"regions":["us-east-1"]}}'
    EOT
  }
}

Option 2: SDK (@pulsestack/client)

Ensure the package is installed (e.g. in a wrapper script or npm install @pulsestack/client in local-exec). Then:

resource "null_resource" "pulsestack_healthcheck_sdk" {
  provisioner "local-exec" {
    command     = "node -e \"const p=require('@pulsestack/client');(async()=>{const c=p({apiKey:process.env.PULSESTACK_API_KEY,baseUrl:process.env.PULSESTACK_URL});await c.ensureHealthcheck('my-api',{interval:60,url:'https://api.example.com/health',regions:['us-east-1']});})();\""
    environment = {
      PULSESTACK_API_KEY = var.pulsestack_api_key
      PULSESTACK_URL     = var.pulsestack_url
    }
  }
}

Do not commit API keys; use TF_VAR_pulsestack_api_key, a secrets backend, or Terraform Cloud variables.