SDK Reference

The official PingSLA SDK provides a typed Node.js/TypeScript client for the PingSLA API.

Installation

npm install @pingsla/sdk
# or
pnpm add @pingsla/sdk
# or
yarn add @pingsla/sdk

Requires Node.js ≥ 18.

Initialization

import { PingSLA } from '@pingsla/sdk';

const client = new PingSLA({
  apiKey: process.env.PINGSLA_API_KEY,
  // Optional:
  baseUrl: 'https://api.pingsla.com/v1', // default
  timeout: 10_000,                        // ms, default 10s
  retries: 3,                             // auto-retry on 5xx, default 3
});

Monitors

// List all monitors
const { data: monitors } = await client.monitors.list();

// Get a specific monitor
const { data: monitor } = await client.monitors.get('mon_xxxxxxxx');

// Create a monitor
const { data: newMonitor } = await client.monitors.create({
  name: 'Production API',
  type: 'http',
  url: 'https://api.yourapp.com/health',
  interval: 60,
  expectedStatusCode: 200,
  alertPolicyId: 'pol_xxxxxxxx',
});

// Update a monitor
await client.monitors.update('mon_xxxxxxxx', {
  interval: 30,
});

// Pause / Resume
await client.monitors.pause('mon_xxxxxxxx');
await client.monitors.resume('mon_xxxxxxxx');

// Delete
await client.monitors.delete('mon_xxxxxxxx');

Incidents

// List incidents (paginated)
const { data: incidents, pagination } = await client.incidents.list({
  status: 'open',
  page: 1,
  limit: 20,
});

// Get incident detail
const { data: incident } = await client.incidents.get('inc_xxxxxxxx');

// Acknowledge
await client.incidents.acknowledge('inc_xxxxxxxx');

// Resolve manually
await client.incidents.resolve('inc_xxxxxxxx');

Status Pages

// List status pages
const { data: pages } = await client.statusPages.list();

// Get public status (no auth required)
const { data: status } = await client.statusPages.getPublicStatus('your-slug');

// Create an incident on a status page
await client.statusPages.createIncident('sp_xxxxxxxx', {
  title: 'API performance degradation',
  status: 'investigating',
  affectedComponents: ['comp_xxxxxxxx'],
});

Alert Policies

const { data: policies } = await client.alertPolicies.list();

const { data: policy } = await client.alertPolicies.create({
  name: 'Critical Alerts',
  failureThreshold: 1,
  recoveryThreshold: 1,
  notifyOnRecovery: true,
  channels: [
    { type: 'email', target: 'ops@yourapp.com' },
  ],
});

Error Handling

import { PingSLAError, RateLimitError, NotFoundError } from '@pingsla/sdk';

try {
  await client.monitors.get('mon_doesnotexist');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Monitor not found');
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof PingSLAError) {
    console.log(`API error: ${err.message} (${err.statusCode})`);
  }
}

TypeScript Support

The SDK ships with full TypeScript declarations. All request and response types are exported:

import type { Monitor, Incident, AlertPolicy } from '@pingsla/sdk';

Changelog

SDK releases follow the API version. Breaking changes increment the minor version. Patch versions are bug fixes only.

Check npm.js/@pingsla/sdk for the latest version.