> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install and use the DevHelm TypeScript SDK to manage monitors, incidents, and alerts programmatically

The `@devhelm/sdk` package is a typed, promise-based client for the DevHelm REST API. It runs in any modern Node.js or browser environment, ships full TypeScript types, and uses Zod for runtime request/response validation.

## Install

```bash theme={null}
npm install @devhelm/sdk
```

Requires Node 18+ (for native `fetch`).

## Initialize

```typescript theme={null}
import { Devhelm } from "@devhelm/sdk";

const client = new Devhelm({
  token: process.env.DEVHELM_API_TOKEN!,
});
```

| Option        | Type     | Default                             | Description                          |
| ------------- | -------- | ----------------------------------- | ------------------------------------ |
| `token`       | `string` | —                                   | API token (Bearer). Required.        |
| `baseUrl`     | `string` | `https://api.devhelm.io`            | Override for self-hosted or testing. |
| `orgId`       | `string` | `DEVHELM_ORG_ID` env or `"1"`       | Organization ID header.              |
| `workspaceId` | `string` | `DEVHELM_WORKSPACE_ID` env or `"1"` | Workspace ID header.                 |

## Create a monitor

```typescript theme={null}
const monitor = await client.monitors.create({
  name: "API Health",
  type: "HTTP",
  config: {
    url: "https://api.example.com/health",
    method: "GET",
  },
  frequencySeconds: 60,
  regions: ["us-east", "eu-west"],
});

console.log(`Created monitor: ${monitor.id}`);
```

`managedBy` is optional — omit it (defaults to `API` server-side) or set it
explicitly to one of `API`, `DASHBOARD`, `CLI`, `TERRAFORM`, or `MCP` to
record the provenance for drift detection.

Request bodies are validated against the generated Zod schemas before any HTTP I/O — invalid payloads throw `DevhelmValidationError` with structured field errors.

## List monitors

```typescript theme={null}
// Auto-paginates through every page
const monitors = await client.monitors.list();

for (const monitor of monitors) {
  console.log(`${monitor.name}: ${monitor.currentStatus}`);
}
```

For manual pagination control:

```typescript theme={null}
const page = await client.monitors.listPage(0, 50);
console.log(`Total: ${page.totalElements}`);
for (const monitor of page.data) {
  // ...
}
```

## Update or delete a monitor

```typescript theme={null}
// Update
const updated = await client.monitors.update(monitor.id, {
  frequencySeconds: 30,
});

// Delete
await client.monitors.delete(monitor.id);
```

## Get check results

```typescript theme={null}
const results = await client.monitors.results(monitor.id, { limit: 10 });

for (const check of results.data) {
  const status = check.passed ? "OK" : "FAIL";
  console.log(`${check.region}: ${status} (${check.responseTimeMs}ms)`);
}

// Fetch the next batch
if (results.hasMore) {
  const next = await client.monitors.results(monitor.id, {
    cursor: results.nextCursor!,
    limit: 10,
  });
}
```

## Manage incidents

```typescript theme={null}
const incidents = await client.incidents.list();

for (const incident of incidents) {
  if (incident.status === "OPEN") {
    console.log(`Open: ${incident.title}`);
  }
}

await client.incidents.resolve(incidentId);
// or with a resolution note:
await client.incidents.resolve(incidentId, { body: "fixed by deploy" });
```

## Create an alert channel

```typescript theme={null}
const channel = await client.alertChannels.create({
  name: "Slack Alerts",
  config: {
    channelType: "slack",
    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
  },
});
```

The channel type is the `channelType` discriminator **inside** `config` (`slack`, `email`, `discord`, `pagerduty`, …) — there is no top-level `type` field on this request.

## Error handling

```typescript theme={null}
import {
  DevhelmError,
  DevhelmAuthError,
  DevhelmNotFoundError,
  DevhelmRateLimitError,
} from "@devhelm/sdk";

try {
  await client.monitors.get("nonexistent");
} catch (err) {
  if (err instanceof DevhelmNotFoundError) {
    console.error("Monitor not found");
  } else if (err instanceof DevhelmRateLimitError) {
    console.error(`Rate limited (request_id=${err.requestId})`);
  } else if (err instanceof DevhelmAuthError) {
    console.error("Bad token or insufficient permissions");
  } else if (err instanceof DevhelmError) {
    throw err;
  }
}
```

Full taxonomy in the [Error handling guide](/sdk/typescript/error-handling).

## Resource namespaces

The client exposes 17 resources:

| Namespace                     | Covers                                                                      |
| ----------------------------- | --------------------------------------------------------------------------- |
| `client.monitors`             | HTTP, DNS, TCP, ICMP, MCP, Heartbeat monitors + check results, versions     |
| `client.incidents`            | Manual and auto-detected incidents                                          |
| `client.forensics`            | Incident timelines, check traces, policy snapshots, rule evaluations        |
| `client.alertChannels`        | Email, Slack, Discord, webhook, PagerDuty, OpsGenie, Teams                  |
| `client.notificationPolicies` | Routing rules, schedules                                                    |
| `client.environments`         | Workspace environments (production, staging, …)                             |
| `client.secrets`              | Secret values consumed by monitor configs                                   |
| `client.tags`                 | Color-coded labels for monitors and incidents                               |
| `client.resourceGroups`       | Compose monitors and dependencies into logical units                        |
| `client.webhooks`             | Outbound event delivery                                                     |
| `client.apiKeys`              | Token issuance and revocation                                               |
| `client.dependencies`         | Tracked third-party services for status pages                               |
| `client.services`             | Third-party service status catalog (search, live status, uptime, incidents) |
| `client.deployLock`           | Acquire / release / inspect the deploy lock                                 |
| `client.maintenanceWindows`   | Scheduled alert-suppression windows                                         |
| `client.status`               | Dashboard overview metrics                                                  |
| `client.statusPages`          | Status pages, components, groups, incidents, subscribers, custom domains    |

## Next steps

<CardGroup cols={2}>
  <Card title="Client reference" icon="book" href="/sdk/typescript/client-reference">
    Every method, signature, and return type.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/sdk/typescript/error-handling">
    Exception classes and retry patterns.
  </Card>
</CardGroup>