Skip to content

Open-source status page, incident response and uptime monitoring

docs: sdk (#1854)

Thibault Le Ouay929f695c8368
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
deleted file mode 100644
index 6a53d32a8..000000000
--- a/.github/pull_request_template.md
+++ /dev/null
@@ -1,26 +0,0 @@
-## Type of change
-
-<!--- What types of changes does your code introduce? Put an `x` in the box that apply: -->
-
-- [ ] πŸ› Bug fix
-- [ ] 🌟 New feature
-- [ ] πŸ”¨ Breaking change
-- [ ] πŸ“– Refactoring / dependency upgrade / documentation
-
-## Description
-
-<!--- Describe your changes in detail -->
-
-### A picture tells a thousand words (if any)
-
-### Before this PR
-
-{Please add a screenshot here}
-
-### After this PR
-
-{Please add a screenshot here}
-
-### Related Issue (optional)
-
-<!--- Please link to the issue here: -->
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
index eab336266..6e2a0bb08 100644
--- a/apps/docs/astro.config.mjs
+++ b/apps/docs/astro.config.mjs
@@ -148,6 +148,16 @@ export default defineConfig({
},
],
},
+ {
+ label: "SDK",
+ items: [
+ {
+ label: "Node SDK",
+ autogenerate: { directory: "sdk/nodejs" },
+ collapsed: true,
+ },
+ ],
+ },
{
label: "Reference",
items: [
diff --git a/apps/docs/src/content/docs/sdk/nodejs/authentication.mdx b/apps/docs/src/content/docs/sdk/nodejs/authentication.mdx
new file mode 100644
index 000000000..98358be58
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/authentication.mdx
@@ -0,0 +1,57 @@
+---
+title: Authentication
+description: "Configure API key authentication for the OpenStatus Node.js SDK"
+---
+
+## Recommended: createOpenStatusClient
+
+Create a client with your API key. The key is automatically included in all requests via an interceptor.
+
+```typescript
+import { createOpenStatusClient } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+// No headers needed on individual calls
+const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});
+```
+
+## Alternative: Manual Headers
+
+Use the default `openstatus` client and pass headers on each call.
+
+```typescript
+import { openstatus } from "@openstatus/sdk-node";
+
+const headers = {
+ "x-openstatus-key": process.env.OPENSTATUS_API_KEY,
+};
+
+await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENSTATUS_API_KEY` | Your OpenStatus API key | Required for authenticated calls |
+| `OPENSTATUS_API_URL` | Custom API endpoint | `https://api.openstatus.dev/rpc` |
+
+Get your API key from the [OpenStatus dashboard](https://www.openstatus.dev/app).
+
+## Custom Base URL
+
+For self-hosted instances or staging environments:
+
+```typescript
+import { createOpenStatusClient } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+ baseUrl: "https://api.staging.example.com/rpc",
+});
+```
+
+The `baseUrl` option takes precedence over the `OPENSTATUS_API_URL` environment variable.
diff --git a/apps/docs/src/content/docs/sdk/nodejs/error-handling.mdx b/apps/docs/src/content/docs/sdk/nodejs/error-handling.mdx
new file mode 100644
index 000000000..6e21747ad
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/error-handling.mdx
@@ -0,0 +1,60 @@
+---
+title: Error Handling
+description: "Handle errors and implement retry strategies with the OpenStatus Node.js SDK"
+---
+
+The SDK uses ConnectRPC. Errors are thrown as `ConnectError` instances from the `@connectrpc/connect` package.
+
+```typescript
+import { ConnectError } from "@connectrpc/connect";
+
+try {
+ await client.monitor.v1.MonitorService.deleteMonitor({ id: "invalid" });
+} catch (error) {
+ if (error instanceof ConnectError) {
+ console.error(`Code: ${error.code}`);
+ console.error(`Message: ${error.message}`);
+ }
+}
+```
+
+## Common Error Codes
+
+| Code | Description |
+|------|-------------|
+| `unauthenticated` | Missing or invalid API key |
+| `not_found` | Resource does not exist |
+| `invalid_argument` | Validation failure (e.g., missing required field, value out of range) |
+| `permission_denied` | No access to this workspace or resource |
+| `already_exists` | Duplicate resource (e.g., slug already taken) |
+
+## Retry Strategy
+
+ConnectRPC does not retry by default. For transient failures (`unavailable`, `deadline_exceeded`), implement your own retry logic:
+
+```typescript
+import { ConnectError } from "@connectrpc/connect";
+
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+ for (let attempt = 0; attempt <= maxRetries; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ if (
+ error instanceof ConnectError &&
+ (error.code === "unavailable" || error.code === "deadline_exceeded") &&
+ attempt < maxRetries
+ ) {
+ await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
+ continue;
+ }
+ throw error;
+ }
+ }
+ throw new Error("Unreachable");
+}
+
+const { httpMonitors } = await withRetry(() =>
+ client.monitor.v1.MonitorService.listMonitors({})
+);
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx b/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx
new file mode 100644
index 000000000..597ecf8cb
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx
@@ -0,0 +1,141 @@
+---
+title: Getting Started
+description: "Install and start using the OpenStatus Node.js SDK"
+---
+
+## Installation
+
+### npm
+
+```bash
+npm install @openstatus/sdk-node
+```
+
+### JSR
+
+```bash
+npx jsr add @openstatus/sdk-node
+```
+
+### Deno
+
+```typescript
+import { createOpenStatusClient } from "jsr:@openstatus/sdk-node";
+```
+
+### Bun
+
+```bash
+bun add @openstatus/sdk-node
+```
+
+## Quick Start
+
+```typescript
+import {
+ createOpenStatusClient,
+ Periodicity,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+// Create an HTTP monitor
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "My API",
+ url: "https://api.example.com/health",
+ periodicity: Periodicity.PERIODICITY_1M,
+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
+ active: true,
+ },
+});
+
+console.log(`Monitor created: ${monitor?.id}`);
+
+// List all monitors
+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
+ await client.monitor.v1.MonitorService.listMonitors({});
+
+console.log(`Found ${totalSize} monitors`);
+```
+
+## Runtime Support
+
+| Runtime | Version | Module Format |
+|---------|---------|---------------|
+| Node.js | 18+ | ESM and CJS |
+| Deno | 2+ | ESM (native) |
+| Bun | Latest | ESM |
+
+## Full Workflow Example
+
+A complete example: create a monitor, set up a status page, add the monitor as a component, configure a Slack notification, and check overall status.
+
+```typescript
+import {
+ createOpenStatusClient,
+ NotificationProvider,
+ Periodicity,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+// 1. Check API health
+const health = await client.health.v1.HealthService.check({});
+console.log(`API status: ${health.status}`);
+
+// 2. Create an HTTP monitor
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "Production API",
+ url: "https://api.example.com/health",
+ periodicity: Periodicity.PERIODICITY_1M,
+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
+ active: true,
+ },
+});
+
+// 3. Create a status page
+const { statusPage } = await client.statusPage.v1.StatusPageService
+ .createStatusPage({
+ title: "Example Status",
+ slug: "example-status",
+ description: "Status page for Example services",
+ });
+
+// 4. Add the monitor as a component
+const { component } = await client.statusPage.v1.StatusPageService
+ .addMonitorComponent({
+ pageId: statusPage!.id,
+ monitorId: monitor!.id,
+ name: "Production API",
+ });
+
+// 5. Set up Slack notifications
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Slack Alerts",
+ provider: NotificationProvider.SLACK,
+ data: {
+ data: {
+ case: "slack",
+ value: { webhookUrl: "https://hooks.slack.com/services/..." },
+ },
+ },
+ monitorIds: [monitor!.id],
+ });
+
+// 6. Check overall status
+const { overallStatus } = await client.statusPage.v1.StatusPageService
+ .getOverallStatus({
+ identifier: { case: "id", value: statusPage!.id },
+ });
+
+console.log(`Overall status: ${overallStatus}`);
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/health-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/health-service.mdx
new file mode 100644
index 000000000..6b211d5a5
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/health-service.mdx
@@ -0,0 +1,23 @@
+---
+title: Health Service
+description: "Check the OpenStatus API health status using the Node.js SDK"
+---
+
+Check API health status. No authentication required.
+
+```typescript
+import { openstatus, ServingStatus } from "@openstatus/sdk-node";
+
+const { status } = await openstatus.health.v1.HealthService.check({});
+console.log(ServingStatus[status]); // "SERVING"
+```
+
+Or with a configured client:
+
+```typescript
+import { createOpenStatusClient, ServingStatus } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient();
+const { status } = await client.health.v1.HealthService.check({});
+console.log(ServingStatus[status]); // "SERVING"
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/index.mdx b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
new file mode 100644
index 000000000..597ecf8cb
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
@@ -0,0 +1,141 @@
+---
+title: Getting Started
+description: "Install and start using the OpenStatus Node.js SDK"
+---
+
+## Installation
+
+### npm
+
+```bash
+npm install @openstatus/sdk-node
+```
+
+### JSR
+
+```bash
+npx jsr add @openstatus/sdk-node
+```
+
+### Deno
+
+```typescript
+import { createOpenStatusClient } from "jsr:@openstatus/sdk-node";
+```
+
+### Bun
+
+```bash
+bun add @openstatus/sdk-node
+```
+
+## Quick Start
+
+```typescript
+import {
+ createOpenStatusClient,
+ Periodicity,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+// Create an HTTP monitor
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "My API",
+ url: "https://api.example.com/health",
+ periodicity: Periodicity.PERIODICITY_1M,
+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
+ active: true,
+ },
+});
+
+console.log(`Monitor created: ${monitor?.id}`);
+
+// List all monitors
+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
+ await client.monitor.v1.MonitorService.listMonitors({});
+
+console.log(`Found ${totalSize} monitors`);
+```
+
+## Runtime Support
+
+| Runtime | Version | Module Format |
+|---------|---------|---------------|
+| Node.js | 18+ | ESM and CJS |
+| Deno | 2+ | ESM (native) |
+| Bun | Latest | ESM |
+
+## Full Workflow Example
+
+A complete example: create a monitor, set up a status page, add the monitor as a component, configure a Slack notification, and check overall status.
+
+```typescript
+import {
+ createOpenStatusClient,
+ NotificationProvider,
+ Periodicity,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+// 1. Check API health
+const health = await client.health.v1.HealthService.check({});
+console.log(`API status: ${health.status}`);
+
+// 2. Create an HTTP monitor
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "Production API",
+ url: "https://api.example.com/health",
+ periodicity: Periodicity.PERIODICITY_1M,
+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
+ active: true,
+ },
+});
+
+// 3. Create a status page
+const { statusPage } = await client.statusPage.v1.StatusPageService
+ .createStatusPage({
+ title: "Example Status",
+ slug: "example-status",
+ description: "Status page for Example services",
+ });
+
+// 4. Add the monitor as a component
+const { component } = await client.statusPage.v1.StatusPageService
+ .addMonitorComponent({
+ pageId: statusPage!.id,
+ monitorId: monitor!.id,
+ name: "Production API",
+ });
+
+// 5. Set up Slack notifications
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Slack Alerts",
+ provider: NotificationProvider.SLACK,
+ data: {
+ data: {
+ case: "slack",
+ value: { webhookUrl: "https://hooks.slack.com/services/..." },
+ },
+ },
+ monitorIds: [monitor!.id],
+ });
+
+// 6. Check overall status
+const { overallStatus } = await client.statusPage.v1.StatusPageService
+ .getOverallStatus({
+ identifier: { case: "id", value: statusPage!.id },
+ });
+
+console.log(`Overall status: ${overallStatus}`);
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/maintenance-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/maintenance-service.mdx
new file mode 100644
index 000000000..7adae5a5d
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/maintenance-service.mdx
@@ -0,0 +1,71 @@
+---
+title: Maintenance Service
+description: "Manage scheduled maintenance windows with the OpenStatus Node.js SDK"
+---
+
+Manage scheduled maintenance windows. The Maintenance Service provides 5 RPC methods.
+
+## Create Maintenance Window
+
+```typescript
+const { maintenance } = await client.maintenance.v1.MaintenanceService
+ .createMaintenance({
+ title: "Database Upgrade",
+ message: "We will be upgrading our database infrastructure.",
+ from: "2024-01-20T02:00:00Z",
+ to: "2024-01-20T04:00:00Z",
+ pageId: "page_123",
+ pageComponentIds: ["comp_456"],
+ notify: true,
+ });
+
+console.log(`Maintenance created: ${maintenance?.id}`);
+```
+
+All date fields (`from`, `to`) must be in RFC 3339 format.
+
+## List Maintenances
+
+List maintenance windows with optional page filtering.
+
+```typescript
+const { maintenances, totalSize } = await client.maintenance.v1
+ .MaintenanceService.listMaintenances({
+ limit: 10,
+ offset: 0,
+ pageId: "page_123",
+ });
+
+console.log(`Found ${totalSize} maintenance windows`);
+```
+
+## Get / Update / Delete Maintenance Windows
+
+### Get Maintenance
+
+```typescript
+const { maintenance } = await client.maintenance.v1.MaintenanceService
+ .getMaintenance({ id: "maint_123" });
+
+console.log(`Title: ${maintenance?.title}`);
+console.log(`From: ${maintenance?.from}`);
+console.log(`To: ${maintenance?.to}`);
+```
+
+### Update Maintenance
+
+```typescript
+const { maintenance } = await client.maintenance.v1.MaintenanceService
+ .updateMaintenance({
+ id: "maint_123",
+ title: "Extended Database Upgrade",
+ to: "2024-01-20T06:00:00Z",
+ });
+```
+
+### Delete Maintenance
+
+```typescript
+const { success } = await client.maintenance.v1.MaintenanceService
+ .deleteMaintenance({ id: "maint_123" });
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/monitor-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/monitor-service.mdx
new file mode 100644
index 000000000..e76cd3428
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/monitor-service.mdx
@@ -0,0 +1,347 @@
+---
+title: Monitor Service
+description: "Create and manage HTTP, TCP, and DNS monitors with the OpenStatus Node.js SDK"
+---
+
+Manage HTTP, TCP, and DNS monitors. The Monitor Service provides 12 RPC methods for creating, updating, listing, triggering, deleting, and querying monitor status and metrics.
+
+All examples assume you have created a client:
+
+```typescript
+import { createOpenStatusClient } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+```
+
+## HTTP Monitors
+
+### Create HTTP Monitor
+
+```typescript
+import {
+ createOpenStatusClient,
+ HTTPMethod,
+ NumberComparator,
+ Periodicity,
+ Region,
+ StringComparator,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "My API",
+ url: "https://api.example.com/health",
+ periodicity: Periodicity.PERIODICITY_1M,
+ method: HTTPMethod.HTTP_METHOD_GET,
+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
+ active: true,
+ timeout: BigInt(30000),
+ retry: BigInt(3),
+ followRedirects: true,
+ degradedAt: BigInt(5000),
+ headers: [
+ { key: "Authorization", value: "Bearer my-token" },
+ ],
+ statusCodeAssertions: [
+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },
+ ],
+ bodyAssertions: [
+ { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },
+ ],
+ headerAssertions: [
+ {
+ key: "content-type",
+ comparator: StringComparator.CONTAINS,
+ target: "application/json",
+ },
+ ],
+ description: "Health check for the production API",
+ public: false,
+ openTelemetry: {
+ endpoint: "https://otel.example.com/v1/traces",
+ headers: [{ key: "Authorization", value: "Bearer otel-token" }],
+ },
+ },
+});
+
+console.log(`Created monitor: ${monitor?.id}`);
+```
+
+### Update HTTP Monitor
+
+Updates are partial β€” only include the fields you want to change.
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.updateHTTPMonitor({
+ id: "mon_123",
+ monitor: {
+ name: "Updated API Monitor",
+ active: false,
+ },
+});
+```
+
+### HTTP Monitor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | Yes | Monitor name (max 256 chars) |
+| `url` | string | Yes | URL to monitor (max 2048 chars) |
+| `periodicity` | Periodicity | Yes | Check interval |
+| `method` | HTTPMethod | No | HTTP method (default: GET) |
+| `body` | string | No | Request body |
+| `headers` | Headers[] | No | Custom headers `{ key, value }[]` |
+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |
+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |
+| `followRedirects` | boolean | No | Follow redirects (default: true) |
+| `regions` | Region[] | No | Regions for checks |
+| `active` | boolean | No | Enable monitoring (default: false) |
+| `public` | boolean | No | Public visibility (default: false) |
+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |
+| `description` | string | No | Monitor description (max 1024 chars) |
+| `statusCodeAssertions` | StatusCodeAssertion[] | No | Status code assertions |
+| `bodyAssertions` | BodyAssertion[] | No | Body assertions |
+| `headerAssertions` | HeaderAssertion[] | No | Header assertions |
+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |
+
+## TCP Monitors
+
+### Create TCP Monitor
+
+```typescript
+import {
+ createOpenStatusClient,
+ Periodicity,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { monitor } = await client.monitor.v1.MonitorService.createTCPMonitor({
+ monitor: {
+ name: "Database",
+ uri: "db.example.com:5432",
+ periodicity: Periodicity.PERIODICITY_5M,
+ regions: [Region.FLY_AMS, Region.FLY_IAD],
+ active: true,
+ },
+});
+```
+
+### Update TCP Monitor
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.updateTCPMonitor({
+ id: "mon_123",
+ monitor: {
+ name: "Updated Database Monitor",
+ },
+});
+```
+
+### TCP Monitor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | Yes | Monitor name (max 256 chars) |
+| `uri` | string | Yes | `host:port` to monitor (max 2048 chars) |
+| `periodicity` | Periodicity | Yes | Check interval |
+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |
+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |
+| `regions` | Region[] | No | Regions for checks |
+| `active` | boolean | No | Enable monitoring (default: false) |
+| `public` | boolean | No | Public visibility (default: false) |
+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |
+| `description` | string | No | Monitor description (max 1024 chars) |
+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |
+
+## DNS Monitors
+
+### Create DNS Monitor
+
+```typescript
+import {
+ createOpenStatusClient,
+ Periodicity,
+ RecordComparator,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { monitor } = await client.monitor.v1.MonitorService.createDNSMonitor({
+ monitor: {
+ name: "DNS Check",
+ uri: "example.com",
+ periodicity: Periodicity.PERIODICITY_10M,
+ regions: [Region.FLY_AMS],
+ active: true,
+ recordAssertions: [
+ {
+ record: "A",
+ comparator: RecordComparator.EQUAL,
+ target: "93.184.216.34",
+ },
+ {
+ record: "CNAME",
+ comparator: RecordComparator.CONTAINS,
+ target: "cdn",
+ },
+ ],
+ },
+});
+```
+
+### Update DNS Monitor
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.updateDNSMonitor({
+ id: "mon_123",
+ monitor: {
+ name: "Updated DNS Check",
+ },
+});
+```
+
+### DNS Monitor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | Yes | Monitor name (max 256 chars) |
+| `uri` | string | Yes | Domain to resolve (max 2048 chars) |
+| `periodicity` | Periodicity | Yes | Check interval |
+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |
+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |
+| `regions` | Region[] | No | Regions for checks |
+| `active` | boolean | No | Enable monitoring (default: false) |
+| `public` | boolean | No | Public visibility (default: false) |
+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |
+| `description` | string | No | Monitor description (max 1024 chars) |
+| `recordAssertions` | RecordAssertion[] | No | DNS record assertions |
+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |
+
+## List Monitors
+
+List all monitors with offset-based pagination. Returns monitors grouped by type.
+
+```typescript
+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
+ await client.monitor.v1.MonitorService.listMonitors({
+ limit: 10,
+ offset: 0,
+ });
+
+console.log(`Total: ${totalSize}`);
+console.log(`HTTP: ${httpMonitors.length}`);
+console.log(`TCP: ${tcpMonitors.length}`);
+console.log(`DNS: ${dnsMonitors.length}`);
+```
+
+Pagination parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number (optional) | Max results to return (1–100, default 50) |
+| `offset` | number (optional) | Number of results to skip (default 0) |
+
+## Get Monitor
+
+Get a single monitor by ID. The response uses a `MonitorConfig` oneof type that contains one of HTTP, TCP, or DNS configuration.
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.getMonitor({
+ id: "mon_123",
+});
+
+if (monitor?.config.case === "http") {
+ console.log(`HTTP Monitor: ${monitor.config.value.name} β€” ${monitor.config.value.url}`);
+} else if (monitor?.config.case === "tcp") {
+ console.log(`TCP Monitor: ${monitor.config.value.name} β€” ${monitor.config.value.uri}`);
+} else if (monitor?.config.case === "dns") {
+ console.log(`DNS Monitor: ${monitor.config.value.name} β€” ${monitor.config.value.uri}`);
+}
+```
+
+## Trigger Monitor
+
+Trigger an immediate check for a monitor.
+
+```typescript
+const { success } = await client.monitor.v1.MonitorService.triggerMonitor({
+ id: "mon_123",
+});
+
+console.log(`Trigger successful: ${success}`);
+```
+
+## Delete Monitor
+
+```typescript
+const { success } = await client.monitor.v1.MonitorService.deleteMonitor({
+ id: "mon_123",
+});
+```
+
+## Get Monitor Status
+
+Get the current status of a monitor across all configured regions.
+
+```typescript
+import {
+ createOpenStatusClient,
+ MonitorStatus,
+ Region,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { id, regions } = await client.monitor.v1.MonitorService.getMonitorStatus(
+ { id: "mon_123" },
+);
+
+for (const { region, status } of regions) {
+ console.log(`${Region[region]}: ${MonitorStatus[status]}`);
+}
+```
+
+## Get Monitor Summary
+
+Get aggregated metrics and latency percentiles for a monitor over a time range.
+
+```typescript
+import { createOpenStatusClient, TimeRange } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const summary = await client.monitor.v1.MonitorService.getMonitorSummary({
+ id: "mon_123",
+ timeRange: TimeRange.TIME_RANGE_7D,
+ regions: [],
+});
+
+console.log(`Last ping: ${summary.lastPingAt}`);
+console.log(`Successful: ${summary.totalSuccessful}`);
+console.log(`Degraded: ${summary.totalDegraded}`);
+console.log(`Failed: ${summary.totalFailed}`);
+console.log(`P50: ${summary.p50}ms`);
+console.log(`P75: ${summary.p75}ms`);
+console.log(`P90: ${summary.p90}ms`);
+console.log(`P95: ${summary.p95}ms`);
+console.log(`P99: ${summary.p99}ms`);
+```
+
+The latency fields (`p50`, `p75`, `p90`, `p95`, `p99`) and count fields (`totalSuccessful`, `totalDegraded`, `totalFailed`) are `bigint` values. The `regions` parameter is optional β€” pass an empty array to get metrics across all regions.
diff --git a/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx
new file mode 100644
index 000000000..9094fb0e6
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx
@@ -0,0 +1,336 @@
+---
+title: Notification Service
+description: "Manage notification channels and providers with the OpenStatus Node.js SDK"
+---
+
+Manage notification channels for monitor alerts. Supports 12 providers. The Notification Service provides 7 RPC methods.
+
+## Create Notification
+
+```typescript
+import {
+ createOpenStatusClient,
+ NotificationProvider,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Slack Alerts",
+ provider: NotificationProvider.SLACK,
+ data: {
+ data: {
+ case: "slack",
+ value: { webhookUrl: "https://hooks.slack.com/services/..." },
+ },
+ },
+ monitorIds: ["mon_123", "mon_456"],
+ });
+
+console.log(`Notification created: ${notification?.id}`);
+```
+
+The `data` field uses a nested oneof pattern: the outer `data` is the `NotificationData` message, and `data.data` is the oneof that selects the provider-specific configuration. The `case` must match the provider type in lowercase.
+
+## Provider Configurations
+
+Each provider shown as a complete `createNotification` call.
+
+### Slack
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Slack Alerts",
+ provider: NotificationProvider.SLACK,
+ data: {
+ data: {
+ case: "slack",
+ value: { webhookUrl: "https://hooks.slack.com/services/..." },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Discord
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Discord Alerts",
+ provider: NotificationProvider.DISCORD,
+ data: {
+ data: {
+ case: "discord",
+ value: { webhookUrl: "https://discord.com/api/webhooks/..." },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Email
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Email Alerts",
+ provider: NotificationProvider.EMAIL,
+ data: {
+ data: {
+ case: "email",
+ value: { email: "[email protected]" },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### PagerDuty
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "PagerDuty Alerts",
+ provider: NotificationProvider.PAGERDUTY,
+ data: {
+ data: {
+ case: "pagerduty",
+ value: { integrationKey: "your-integration-key" },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Opsgenie
+
+```typescript
+import { NotificationProvider, OpsgenieRegion } from "@openstatus/sdk-node";
+
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Opsgenie Alerts",
+ provider: NotificationProvider.OPSGENIE,
+ data: {
+ data: {
+ case: "opsgenie",
+ value: { apiKey: "your-api-key", region: OpsgenieRegion.US },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Telegram
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Telegram Alerts",
+ provider: NotificationProvider.TELEGRAM,
+ data: {
+ data: {
+ case: "telegram",
+ value: { chatId: "123456789" },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Google Chat
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Google Chat Alerts",
+ provider: NotificationProvider.GOOGLE_CHAT,
+ data: {
+ data: {
+ case: "googleChat",
+ value: { webhookUrl: "https://chat.googleapis.com/v1/spaces/..." },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Grafana OnCall
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Grafana OnCall",
+ provider: NotificationProvider.GRAFANA_ONCALL,
+ data: {
+ data: {
+ case: "grafanaOncall",
+ value: { webhookUrl: "https://oncall.example.com/..." },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Ntfy
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Ntfy Alerts",
+ provider: NotificationProvider.NTFY,
+ data: {
+ data: {
+ case: "ntfy",
+ value: {
+ topic: "my-alerts",
+ serverUrl: "https://ntfy.sh",
+ token: "tk_...",
+ },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### SMS
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "SMS Alerts",
+ provider: NotificationProvider.SMS,
+ data: {
+ data: {
+ case: "sms",
+ value: { phoneNumber: "+1234567890" },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### WhatsApp
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "WhatsApp Alerts",
+ provider: NotificationProvider.WHATSAPP,
+ data: {
+ data: {
+ case: "whatsapp",
+ value: { phoneNumber: "+1234567890" },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+### Custom Webhook
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .createNotification({
+ name: "Custom Webhook",
+ provider: NotificationProvider.WEBHOOK,
+ data: {
+ data: {
+ case: "webhook",
+ value: {
+ endpoint: "https://api.example.com/webhook",
+ headers: [
+ { key: "Authorization", value: "Bearer token" },
+ { key: "X-Custom-Header", value: "value" },
+ ],
+ },
+ },
+ },
+ monitorIds: ["mon_123"],
+ });
+```
+
+## Send Test Notification
+
+Verify a notification configuration without creating a channel.
+
+```typescript
+import { NotificationProvider } from "@openstatus/sdk-node";
+
+const { success, errorMessage } = await client.notification.v1
+ .NotificationService.sendTestNotification({
+ provider: NotificationProvider.SLACK,
+ data: {
+ data: {
+ case: "slack",
+ value: { webhookUrl: "https://hooks.slack.com/services/..." },
+ },
+ },
+ });
+
+if (success) {
+ console.log("Test notification sent successfully");
+} else {
+ console.log(`Test failed: ${errorMessage}`);
+}
+```
+
+## Check Notification Limits
+
+Check if the workspace has reached its notification channel limit.
+
+```typescript
+const { limitReached, currentCount, maxCount } = await client.notification.v1
+ .NotificationService.checkNotificationLimit({});
+
+console.log(`${currentCount}/${maxCount} notification channels used`);
+if (limitReached) {
+ console.log("Notification limit reached β€” upgrade your plan");
+}
+```
+
+## List / Get / Update / Delete Notifications
+
+### List Notifications
+
+```typescript
+const { notifications, totalSize } = await client.notification.v1
+ .NotificationService.listNotifications({ limit: 10, offset: 0 });
+
+console.log(`Found ${totalSize} notification channels`);
+```
+
+### Get Notification
+
+```typescript
+import { NotificationProvider } from "@openstatus/sdk-node";
+
+const { notification } = await client.notification.v1.NotificationService
+ .getNotification({ id: "notif_123" });
+
+console.log(`Name: ${notification?.name}`);
+console.log(`Provider: ${NotificationProvider[notification?.provider ?? 0]}`);
+```
+
+### Update Notification
+
+```typescript
+const { notification } = await client.notification.v1.NotificationService
+ .updateNotification({
+ id: "notif_123",
+ name: "Updated Slack Alerts",
+ monitorIds: ["mon_123", "mon_456", "mon_789"],
+ });
+```
+
+### Delete Notification
+
+```typescript
+const { success } = await client.notification.v1.NotificationService
+ .deleteNotification({ id: "notif_123" });
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/reference.mdx b/apps/docs/src/content/docs/sdk/nodejs/reference.mdx
new file mode 100644
index 000000000..cd95e4c3a
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/reference.mdx
@@ -0,0 +1,375 @@
+---
+title: Reference
+description: "Complete reference for enums, regions, assertions, and TypeScript type exports in the OpenStatus Node.js SDK"
+---
+
+## Enums
+
+### Periodicity
+
+| Value | Description |
+|-------|-------------|
+| `PERIODICITY_30S` | Every 30 seconds |
+| `PERIODICITY_1M` | Every 1 minute |
+| `PERIODICITY_5M` | Every 5 minutes |
+| `PERIODICITY_10M` | Every 10 minutes |
+| `PERIODICITY_30M` | Every 30 minutes |
+| `PERIODICITY_1H` | Every 1 hour |
+
+### HTTPMethod
+
+| Value | Description |
+|-------|-------------|
+| `HTTP_METHOD_GET` | GET |
+| `HTTP_METHOD_POST` | POST |
+| `HTTP_METHOD_HEAD` | HEAD |
+| `HTTP_METHOD_PUT` | PUT |
+| `HTTP_METHOD_PATCH` | PATCH |
+| `HTTP_METHOD_DELETE` | DELETE |
+| `HTTP_METHOD_TRACE` | TRACE |
+| `HTTP_METHOD_CONNECT` | CONNECT |
+| `HTTP_METHOD_OPTIONS` | OPTIONS |
+
+### MonitorStatus
+
+| Value | Description |
+|-------|-------------|
+| `ACTIVE` | Monitor is healthy |
+| `DEGRADED` | Latency threshold exceeded |
+| `ERROR` | Monitor is failing |
+
+### TimeRange
+
+| Value | Description |
+|-------|-------------|
+| `TIME_RANGE_1D` | Last 24 hours |
+| `TIME_RANGE_7D` | Last 7 days |
+| `TIME_RANGE_14D` | Last 14 days |
+
+### StatusReportStatus
+
+| Value | Description |
+|-------|-------------|
+| `INVESTIGATING` | Actively investigating the issue |
+| `IDENTIFIED` | Root cause has been identified |
+| `MONITORING` | Fix deployed, monitoring |
+| `RESOLVED` | Issue fully resolved |
+
+### OverallStatus
+
+| Value | Description |
+|-------|-------------|
+| `OPERATIONAL` | All systems operational |
+| `DEGRADED` | Performance is degraded |
+| `PARTIAL_OUTAGE` | Some systems are down |
+| `MAJOR_OUTAGE` | Major systems are down |
+| `MAINTENANCE` | Scheduled maintenance |
+| `UNKNOWN` | Status cannot be determined |
+
+### NotificationProvider
+
+| Value | Description |
+|-------|-------------|
+| `DISCORD` | Discord webhook |
+| `EMAIL` | Email notification |
+| `GOOGLE_CHAT` | Google Chat webhook |
+| `GRAFANA_ONCALL` | Grafana OnCall |
+| `NTFY` | Ntfy push service |
+| `PAGERDUTY` | PagerDuty |
+| `OPSGENIE` | Opsgenie |
+| `SLACK` | Slack webhook |
+| `SMS` | SMS notification |
+| `TELEGRAM` | Telegram bot |
+| `WEBHOOK` | Custom webhook |
+| `WHATSAPP` | WhatsApp |
+
+### OpsgenieRegion
+
+| Value | Description |
+|-------|-------------|
+| `US` | US region |
+| `EU` | EU region |
+
+### PageAccessType
+
+| Value | Description |
+|-------|-------------|
+| `PUBLIC` | Publicly accessible |
+| `PASSWORD_PROTECTED` | Requires password |
+| `AUTHENTICATED` | Requires authentication |
+
+### PageTheme
+
+| Value | Description |
+|-------|-------------|
+| `SYSTEM` | Follow system theme |
+| `LIGHT` | Light theme |
+| `DARK` | Dark theme |
+
+### PageComponentType
+
+| Value | Description |
+|-------|-------------|
+| `MONITOR` | Linked to a monitor |
+| `STATIC` | Static component (manual) |
+
+### NumberComparator
+
+| Value | Description |
+|-------|-------------|
+| `EQUAL` | Equal to target |
+| `NOT_EQUAL` | Not equal to target |
+| `GREATER_THAN` | Greater than target |
+| `GREATER_THAN_OR_EQUAL` | Greater than or equal |
+| `LESS_THAN` | Less than target |
+| `LESS_THAN_OR_EQUAL` | Less than or equal |
+
+### StringComparator
+
+| Value | Description |
+|-------|-------------|
+| `CONTAINS` | Contains target string |
+| `NOT_CONTAINS` | Does not contain target |
+| `EQUAL` | Equal to target |
+| `NOT_EQUAL` | Not equal to target |
+| `EMPTY` | Value is empty |
+| `NOT_EMPTY` | Value is not empty |
+| `GREATER_THAN` | Lexicographically greater |
+| `GREATER_THAN_OR_EQUAL` | Lexicographically greater than or equal to target |
+| `LESS_THAN` | Lexicographically less |
+| `LESS_THAN_OR_EQUAL` | Lexicographically less than or equal to target |
+
+### RecordComparator
+
+| Value | Description |
+|-------|-------------|
+| `EQUAL` | Equal to target |
+| `NOT_EQUAL` | Not equal to target |
+| `CONTAINS` | Contains target string |
+| `NOT_CONTAINS` | Does not contain target |
+
+### ServingStatus
+
+| Value | Description |
+|-------|-------------|
+| `SERVING` | Service is healthy and serving |
+| `NOT_SERVING` | Service is not healthy |
+
+## Regions
+
+Monitor from 28 global locations across multiple providers.
+
+```typescript
+import { Region } from "@openstatus/sdk-node";
+
+regions: [Region.FLY_AMS, Region.FLY_IAD, Region.KOYEB_FRA];
+```
+
+### Fly.io Regions (18)
+
+| Enum Value | Location |
+|------------|----------|
+| `FLY_AMS` | Amsterdam |
+| `FLY_ARN` | Stockholm |
+| `FLY_BOM` | Mumbai |
+| `FLY_CDG` | Paris |
+| `FLY_DFW` | Dallas |
+| `FLY_EWR` | Newark |
+| `FLY_FRA` | Frankfurt |
+| `FLY_GRU` | SΓ£o Paulo |
+| `FLY_IAD` | Washington D.C. |
+| `FLY_JNB` | Johannesburg |
+| `FLY_LAX` | Los Angeles |
+| `FLY_LHR` | London |
+| `FLY_NRT` | Tokyo |
+| `FLY_ORD` | Chicago |
+| `FLY_SJC` | San Jose |
+| `FLY_SIN` | Singapore |
+| `FLY_SYD` | Sydney |
+| `FLY_YYZ` | Toronto |
+
+### Koyeb Regions (6)
+
+| Enum Value | Location |
+|------------|----------|
+| `KOYEB_FRA` | Frankfurt |
+| `KOYEB_PAR` | Paris |
+| `KOYEB_SFO` | San Francisco |
+| `KOYEB_SIN` | Singapore |
+| `KOYEB_TYO` | Tokyo |
+| `KOYEB_WAS` | Washington |
+
+### Railway Regions (4)
+
+| Enum Value | Location |
+|------------|----------|
+| `RAILWAY_US_WEST2` | US West |
+| `RAILWAY_US_EAST4` | US East |
+| `RAILWAY_EUROPE_WEST4` | Europe West |
+| `RAILWAY_ASIA_SOUTHEAST1` | Asia Southeast |
+
+## Assertions
+
+### Status Code Assertions
+
+Validate HTTP response status codes using `NumberComparator`.
+
+```typescript
+import { NumberComparator } from "@openstatus/sdk-node";
+
+statusCodeAssertions: [
+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },
+ { comparator: NumberComparator.LESS_THAN, target: BigInt(400) },
+];
+```
+
+### Body Assertions
+
+Validate response body content using `StringComparator`.
+
+```typescript
+import { StringComparator } from "@openstatus/sdk-node";
+
+bodyAssertions: [
+ { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },
+ { comparator: StringComparator.NOT_EMPTY, target: "" },
+];
+```
+
+### Header Assertions
+
+Validate response headers using `StringComparator` with a header `key`.
+
+```typescript
+import { StringComparator } from "@openstatus/sdk-node";
+
+headerAssertions: [
+ {
+ key: "content-type",
+ comparator: StringComparator.CONTAINS,
+ target: "application/json",
+ },
+];
+```
+
+### DNS Record Assertions
+
+Validate DNS records using `RecordComparator`. Supported record types: `A`, `AAAA`, `CNAME`, `MX`, `TXT`.
+
+```typescript
+import { RecordComparator } from "@openstatus/sdk-node";
+
+recordAssertions: [
+ {
+ record: "A",
+ comparator: RecordComparator.EQUAL,
+ target: "93.184.216.34",
+ },
+ {
+ record: "CNAME",
+ comparator: RecordComparator.CONTAINS,
+ target: "cdn",
+ },
+];
+```
+
+## TypeScript Type Exports
+
+All types and enums exported from `@openstatus/sdk-node`:
+
+### Monitor Types
+
+- `HTTPMonitor`, `Headers`, `OpenTelemetryConfig` β€” HTTP monitor configuration
+- `TCPMonitor` β€” TCP monitor configuration
+- `DNSMonitor` β€” DNS monitor configuration
+- `StatusCodeAssertion`, `BodyAssertion`, `HeaderAssertion`, `RecordAssertion` β€” assertion types
+- `CreateHTTPMonitorRequest`, `CreateHTTPMonitorResponse` β€” HTTP monitor CRUD
+- `CreateTCPMonitorRequest`, `CreateTCPMonitorResponse` β€” TCP monitor CRUD
+- `CreateDNSMonitorRequest`, `CreateDNSMonitorResponse` β€” DNS monitor CRUD
+- `UpdateHTTPMonitorRequest`, `UpdateHTTPMonitorResponse`
+- `UpdateTCPMonitorRequest`, `UpdateTCPMonitorResponse`
+- `UpdateDNSMonitorRequest`, `UpdateDNSMonitorResponse`
+- `ListMonitorsRequest`, `ListMonitorsResponse`
+- `DeleteMonitorRequest`, `DeleteMonitorResponse`
+- `TriggerMonitorRequest`, `TriggerMonitorResponse`
+- `GetMonitorStatusRequest`, `GetMonitorStatusResponse`, `RegionStatus`
+- `GetMonitorSummaryRequest`, `GetMonitorSummaryResponse`
+
+### Monitor Enums
+
+- `Periodicity` β€” check interval
+- `Region` β€” monitoring region
+- `MonitorStatus` β€” active / degraded / error
+- `HTTPMethod` β€” HTTP methods
+- `TimeRange` β€” metrics time range
+- `NumberComparator`, `StringComparator`, `RecordComparator` β€” assertion comparators
+
+### Health Types
+
+- `CheckRequest`, `CheckResponse`
+- `ServingStatus` β€” serving / not serving
+
+### Status Report Types
+
+- `StatusReport`, `StatusReportSummary`, `StatusReportUpdate`
+- `CreateStatusReportRequest`, `CreateStatusReportResponse`
+- `GetStatusReportRequest`, `GetStatusReportResponse`
+- `ListStatusReportsRequest`, `ListStatusReportsResponse`
+- `UpdateStatusReportRequest`, `UpdateStatusReportResponse`
+- `DeleteStatusReportRequest`, `DeleteStatusReportResponse`
+- `AddStatusReportUpdateRequest`, `AddStatusReportUpdateResponse`
+- `StatusReportStatus` β€” investigating / identified / monitoring / resolved
+
+### Status Page Types
+
+- `StatusPage`, `StatusPageSummary`
+- `PageComponent`, `PageComponentGroup`
+- `PageSubscriber`
+- `CreateStatusPageRequest`, `CreateStatusPageResponse`
+- `GetStatusPageRequest`, `GetStatusPageResponse`
+- `ListStatusPagesRequest`, `ListStatusPagesResponse`
+- `UpdateStatusPageRequest`, `UpdateStatusPageResponse`
+- `DeleteStatusPageRequest`, `DeleteStatusPageResponse`
+- `AddMonitorComponentRequest`, `AddMonitorComponentResponse`
+- `AddStaticComponentRequest`, `AddStaticComponentResponse`
+- `RemoveComponentRequest`, `RemoveComponentResponse`
+- `UpdateComponentRequest`, `UpdateComponentResponse`
+- `CreateComponentGroupRequest`, `CreateComponentGroupResponse`
+- `DeleteComponentGroupRequest`, `DeleteComponentGroupResponse`
+- `UpdateComponentGroupRequest`, `UpdateComponentGroupResponse`
+- `SubscribeToPageRequest`, `SubscribeToPageResponse`
+- `UnsubscribeFromPageRequest`, `UnsubscribeFromPageResponse`
+- `ListSubscribersRequest`, `ListSubscribersResponse`
+- `GetStatusPageContentRequest`, `GetStatusPageContentResponse`
+- `GetOverallStatusRequest`, `GetOverallStatusResponse`, `ComponentStatus`
+- `OverallStatus`, `PageAccessType`, `PageTheme`, `PageComponentType`
+
+### Maintenance Types
+
+- `Maintenance`, `MaintenanceSummary`
+- `CreateMaintenanceRequest`, `CreateMaintenanceResponse`
+- `GetMaintenanceRequest`, `GetMaintenanceResponse`
+- `ListMaintenancesRequest`, `ListMaintenancesResponse`
+- `UpdateMaintenanceRequest`, `UpdateMaintenanceResponse`
+- `DeleteMaintenanceRequest`, `DeleteMaintenanceResponse`
+
+### Notification Types
+
+- `Notification`, `NotificationSummary`
+- `NotificationData`
+- `DiscordData`, `EmailData`, `GoogleChatData`, `GrafanaOncallData`, `NtfyData`, `OpsgenieData`, `PagerDutyData`, `SlackData`, `SmsData`, `TelegramData`, `WebhookData`, `WebhookHeader`, `WhatsappData`
+- `CreateNotificationRequest`, `CreateNotificationResponse`
+- `GetNotificationRequest`, `GetNotificationResponse`
+- `ListNotificationsRequest`, `ListNotificationsResponse`
+- `UpdateNotificationRequest`, `UpdateNotificationResponse`
+- `DeleteNotificationRequest`, `DeleteNotificationResponse`
+- `SendTestNotificationRequest`, `SendTestNotificationResponse`
+- `CheckNotificationLimitRequest`, `CheckNotificationLimitResponse`
+- `NotificationProvider`, `OpsgenieRegion`
+
+### Client Types
+
+- `OpenStatusClient` β€” client interface
+- `OpenStatusClientOptions` β€” client configuration
+- `createOpenStatusClient` β€” factory function
+- `openstatus` β€” default client instance
diff --git a/apps/docs/src/content/docs/sdk/nodejs/status-page-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/status-page-service.mdx
new file mode 100644
index 000000000..23aed9981
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/status-page-service.mdx
@@ -0,0 +1,224 @@
+---
+title: Status Page Service
+description: "Manage status pages, components, groups, and subscribers with the OpenStatus Node.js SDK"
+---
+
+Manage status pages, components, component groups, and subscribers. The Status Page Service provides 17 RPC methods.
+
+## Status Page CRUD
+
+### Create Status Page
+
+```typescript
+const { statusPage } = await client.statusPage.v1.StatusPageService
+ .createStatusPage({
+ title: "My Service Status",
+ slug: "my-service",
+ description: "Status page for My Service",
+ homepageUrl: "https://example.com",
+ contactUrl: "https://example.com/contact",
+ });
+
+console.log(`Status page created: ${statusPage?.id}`);
+```
+
+### Get Status Page
+
+```typescript
+const { statusPage } = await client.statusPage.v1.StatusPageService
+ .getStatusPage({ id: "page_123" });
+```
+
+### List Status Pages
+
+```typescript
+const { statusPages, totalSize } = await client.statusPage.v1.StatusPageService
+ .listStatusPages({ limit: 10, offset: 0 });
+
+console.log(`Found ${totalSize} status pages`);
+```
+
+### Update Status Page
+
+```typescript
+const { statusPage } = await client.statusPage.v1.StatusPageService
+ .updateStatusPage({
+ id: "page_123",
+ title: "Updated Title",
+ description: "Updated description",
+ });
+```
+
+### Delete Status Page
+
+```typescript
+const { success } = await client.statusPage.v1.StatusPageService
+ .deleteStatusPage({ id: "page_123" });
+```
+
+## Components
+
+Components represent individual services on a status page. They can be linked to a monitor (automatically reflects monitor status) or static (manually managed).
+
+### Add Monitor Component
+
+```typescript
+const { component } = await client.statusPage.v1.StatusPageService
+ .addMonitorComponent({
+ pageId: "page_123",
+ monitorId: "mon_456",
+ name: "API Server",
+ description: "Main API endpoint",
+ order: 1,
+ groupId: "group_789",
+ });
+```
+
+### Add Static Component
+
+```typescript
+const { component } = await client.statusPage.v1.StatusPageService
+ .addStaticComponent({
+ pageId: "page_123",
+ name: "Third-party Service",
+ description: "External dependency",
+ order: 2,
+ });
+```
+
+### Update Component
+
+```typescript
+const { component } = await client.statusPage.v1.StatusPageService
+ .updateComponent({
+ id: "comp_123",
+ name: "Updated Component Name",
+ description: "Updated description",
+ order: 3,
+ groupId: "group_789",
+ groupOrder: 1,
+ });
+```
+
+### Remove Component
+
+```typescript
+const { success } = await client.statusPage.v1.StatusPageService
+ .removeComponent({ id: "comp_123" });
+```
+
+## Component Groups
+
+Group related components together on a status page.
+
+### Create Component Group
+
+```typescript
+const { group } = await client.statusPage.v1.StatusPageService
+ .createComponentGroup({
+ pageId: "page_123",
+ name: "Core Services",
+ });
+```
+
+### Update Component Group
+
+```typescript
+const { group } = await client.statusPage.v1.StatusPageService
+ .updateComponentGroup({
+ id: "group_123",
+ name: "Updated Group Name",
+ });
+```
+
+### Delete Component Group
+
+```typescript
+const { success } = await client.statusPage.v1.StatusPageService
+ .deleteComponentGroup({ id: "group_123" });
+```
+
+## Subscribers
+
+Manage email subscriptions to status page updates.
+
+### Subscribe to Page
+
+```typescript
+const { subscriber } = await client.statusPage.v1.StatusPageService
+ .subscribeToPage({
+ pageId: "page_123",
+ email: "[email protected]",
+ });
+```
+
+### Unsubscribe from Page
+
+Unsubscribe by email or subscriber ID using the `identifier` oneof:
+
+```typescript
+// By email
+const { success } = await client.statusPage.v1.StatusPageService
+ .unsubscribeFromPage({
+ pageId: "page_123",
+ identifier: { case: "email", value: "[email protected]" },
+ });
+
+// By subscriber ID
+const { success: success2 } = await client.statusPage.v1.StatusPageService
+ .unsubscribeFromPage({
+ pageId: "page_123",
+ identifier: { case: "id", value: "sub_456" },
+ });
+```
+
+### List Subscribers
+
+```typescript
+const { subscribers, totalSize } = await client.statusPage.v1.StatusPageService
+ .listSubscribers({
+ pageId: "page_123",
+ limit: 50,
+ offset: 0,
+ includeUnsubscribed: false,
+ });
+```
+
+## Get Status Page Content
+
+Get the full content of a status page including components, groups, active status reports, and maintenance windows. Identify the page by ID or slug.
+
+```typescript
+const content = await client.statusPage.v1.StatusPageService
+ .getStatusPageContent({
+ identifier: { case: "slug", value: "my-service" },
+ });
+
+console.log(`Page: ${content.statusPage?.title}`);
+console.log(`Components: ${content.components.length}`);
+console.log(`Groups: ${content.groups.length}`);
+console.log(`Active reports: ${content.statusReports.length}`);
+console.log(`Maintenances: ${content.maintenances.length}`);
+```
+
+## Get Overall Status
+
+Get the aggregated status of a status page and per-component statuses.
+
+```typescript
+import { createOpenStatusClient, OverallStatus } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { overallStatus, componentStatuses } = await client.statusPage.v1
+ .StatusPageService.getOverallStatus({
+ identifier: { case: "id", value: "page_123" },
+ });
+
+console.log(`Overall: ${OverallStatus[overallStatus]}`);
+for (const { componentId, status } of componentStatuses) {
+ console.log(` ${componentId}: ${OverallStatus[status]}`);
+}
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/status-report-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/status-report-service.mdx
new file mode 100644
index 000000000..d9b6ad22b
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/status-report-service.mdx
@@ -0,0 +1,104 @@
+---
+title: Status Report Service
+description: "Manage incident reports and status updates with the OpenStatus Node.js SDK"
+---
+
+Manage incident reports with update timelines. The Status Report Service provides 6 RPC methods.
+
+## Create Status Report
+
+```typescript
+import {
+ createOpenStatusClient,
+ StatusReportStatus,
+} from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { statusReport } = await client.statusReport.v1.StatusReportService
+ .createStatusReport({
+ title: "API Degradation",
+ status: StatusReportStatus.INVESTIGATING,
+ message: "We are investigating reports of increased latency.",
+ date: "2024-01-15T10:30:00Z",
+ pageId: "page_123",
+ pageComponentIds: ["comp_456"],
+ notify: true,
+ });
+
+console.log(`Status report created: ${statusReport?.id}`);
+```
+
+## Add Status Report Update
+
+Add a new entry to a status report's timeline.
+
+```typescript
+import { StatusReportStatus } from "@openstatus/sdk-node";
+
+const { statusReport } = await client.statusReport.v1.StatusReportService
+ .addStatusReportUpdate({
+ statusReportId: "sr_123",
+ status: StatusReportStatus.IDENTIFIED,
+ message: "The issue has been identified as a database connection problem.",
+ date: "2024-01-15T11:00:00Z",
+ notify: true,
+ });
+```
+
+## List Status Reports
+
+List status reports with optional status filtering and pagination.
+
+```typescript
+import { StatusReportStatus } from "@openstatus/sdk-node";
+
+const { statusReports, totalSize } = await client.statusReport.v1
+ .StatusReportService.listStatusReports({
+ limit: 10,
+ offset: 0,
+ statuses: [StatusReportStatus.INVESTIGATING, StatusReportStatus.IDENTIFIED],
+ });
+
+console.log(`Found ${totalSize} status reports`);
+```
+
+## Get / Update / Delete Status Reports
+
+### Get Status Report
+
+Returns the full report including the updates timeline.
+
+```typescript
+import { StatusReportStatus } from "@openstatus/sdk-node";
+
+const { statusReport } = await client.statusReport.v1.StatusReportService
+ .getStatusReport({ id: "sr_123" });
+
+console.log(`Title: ${statusReport?.title}`);
+console.log(`Status: ${StatusReportStatus[statusReport?.status ?? 0]}`);
+
+for (const update of statusReport?.updates ?? []) {
+ console.log(` ${update.date}: [${StatusReportStatus[update.status]}] ${update.message}`);
+}
+```
+
+### Update Status Report
+
+```typescript
+const { statusReport } = await client.statusReport.v1.StatusReportService
+ .updateStatusReport({
+ id: "sr_123",
+ title: "Updated Title",
+ pageComponentIds: ["comp_456", "comp_789"],
+ });
+```
+
+### Delete Status Report
+
+```typescript
+const { success } = await client.statusReport.v1.StatusReportService
+ .deleteStatusReport({ id: "sr_123" });
+```
diff --git a/apps/docs/src/content/docs/sdk/nodejs/typescript-tips.mdx b/apps/docs/src/content/docs/sdk/nodejs/typescript-tips.mdx
new file mode 100644
index 000000000..8ba4591d2
--- /dev/null
+++ b/apps/docs/src/content/docs/sdk/nodejs/typescript-tips.mdx
@@ -0,0 +1,154 @@
+---
+title: TypeScript Tips
+description: "Tips for working with bigint fields, oneof types, and migrating clients in the OpenStatus Node.js SDK"
+---
+
+## Working with bigint Fields
+
+Protocol Buffers `int64` fields map to `bigint` in TypeScript. This affects:
+
+- **Monitor configuration**: `timeout`, `retry`, `degradedAt`
+- **Assertions**: `StatusCodeAssertion.target`
+- **Monitor summary**: `totalSuccessful`, `totalDegraded`, `totalFailed`, `p50`, `p75`, `p90`, `p95`, `p99`
+
+Use `BigInt()` to create values:
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
+ monitor: {
+ name: "My API",
+ url: "https://example.com",
+ periodicity: Periodicity.PERIODICITY_1M,
+ active: true,
+ timeout: BigInt(30000), // 30 seconds
+ retry: BigInt(5), // 5 retries
+ degradedAt: BigInt(3000), // degraded after 3s
+ statusCodeAssertions: [
+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },
+ ],
+ },
+});
+```
+
+Reading bigint values:
+
+```typescript
+const summary = await client.monitor.v1.MonitorService.getMonitorSummary({
+ id: "mon_123",
+ timeRange: TimeRange.TIME_RANGE_7D,
+ regions: [],
+});
+
+// bigint values β€” use Number() for display if values are safe
+console.log(`P95 latency: ${summary.p95}ms`);
+console.log(`Total checks: ${summary.totalSuccessful + summary.totalDegraded + summary.totalFailed}`);
+```
+
+## Handling oneof Types
+
+Several responses use protobuf `oneof` fields, which map to discriminated unions in TypeScript.
+
+### MonitorConfig (getMonitor)
+
+```typescript
+const { monitor } = await client.monitor.v1.MonitorService.getMonitor({
+ id: "mon_123",
+});
+
+switch (monitor?.config.case) {
+ case "http":
+ // monitor.config.value is HTTPMonitor
+ console.log(`URL: ${monitor.config.value.url}`);
+ break;
+ case "tcp":
+ // monitor.config.value is TCPMonitor
+ console.log(`URI: ${monitor.config.value.uri}`);
+ break;
+ case "dns":
+ // monitor.config.value is DNSMonitor
+ console.log(`Domain: ${monitor.config.value.uri}`);
+ break;
+}
+```
+
+### NotificationData (createNotification)
+
+The `data.data` field selects the provider-specific configuration:
+
+```typescript
+// The case string matches the provider in camelCase
+data: {
+ data: { case: "slack", value: { webhookUrl: "..." } }
+}
+data: {
+ data: { case: "googleChat", value: { webhookUrl: "..." } }
+}
+data: {
+ data: { case: "grafanaOncall", value: { webhookUrl: "..." } }
+}
+```
+
+### Status Page Identifiers
+
+`getStatusPageContent` and `getOverallStatus` accept a page identifier by ID or slug:
+
+```typescript
+// By ID
+{ identifier: { case: "id", value: "page_123" } }
+
+// By slug
+{ identifier: { case: "slug", value: "my-service" } }
+```
+
+### Unsubscribe Identifier
+
+`unsubscribeFromPage` accepts an email or subscriber ID:
+
+```typescript
+// By email
+{ identifier: { case: "email", value: "[email protected]" } }
+
+// By subscriber ID
+{ identifier: { case: "id", value: "sub_456" } }
+```
+
+## Migrating from Default Client to createOpenStatusClient
+
+**Before** β€” manual headers on every call:
+
+```typescript
+import { openstatus } from "@openstatus/sdk-node";
+
+const headers = { "x-openstatus-key": process.env.OPENSTATUS_API_KEY };
+
+const { httpMonitors } = await openstatus.monitor.v1.MonitorService
+ .listMonitors({}, { headers });
+
+const { monitor } = await openstatus.monitor.v1.MonitorService
+ .createHTTPMonitor({
+ monitor: { name: "API", url: "https://example.com", periodicity: 2, active: true },
+ }, { headers });
+```
+
+**After** β€” configure once, use everywhere:
+
+```typescript
+import { createOpenStatusClient, Periodicity } from "@openstatus/sdk-node";
+
+const client = createOpenStatusClient({
+ apiKey: process.env.OPENSTATUS_API_KEY,
+});
+
+const { httpMonitors } = await client.monitor.v1.MonitorService
+ .listMonitors({});
+
+const { monitor } = await client.monitor.v1.MonitorService
+ .createHTTPMonitor({
+ monitor: {
+ name: "API",
+ url: "https://example.com",
+ periodicity: Periodicity.PERIODICITY_1M,
+ active: true,
+ },
+ });
+```
diff --git a/apps/server/src/routes/v1/index.ts b/apps/server/src/routes/v1/index.ts
index d6bc5c59e..602bbed65 100644
--- a/apps/server/src/routes/v1/index.ts
+++ b/apps/server/src/routes/v1/index.ts
@@ -33,77 +33,82 @@ api.openAPIRegistry.registerComponent("securitySchemes", "ApiKeyAuth", {
name: "x-openstatus-key",
"x-openstatus-key": "string",
});
-
-api.doc("/openapi", {
- openapi: "3.0.0",
- info: {
- version: "1.0.0",
- title: "OpenStatus API",
- contact: {
- email: "[email protected]",
- url: "https://www.openstatus.dev",
- },
- description: "This version is deprecated please use v2",
- },
- tags: [
- {
- name: "monitor",
- description: "Monitor related endpoints",
- "x-displayName": "Monitor",
- },
- {
- name: "page",
- description: "Page related endpoints",
- "x-displayName": "Page",
- },
- {
- name: "status_report",
- description: "Status report related endpoints",
- "x-displayName": "Status Report",
- },
- {
- name: "status_report_update",
- description: "Status report update related endpoints",
- "x-displayName": "Status Report Update",
- },
- {
- name: "incident",
- description: "Incident related endpoints",
- "x-displayName": "Incident",
- },
- {
- name: "maintenance",
- description: "Maintenance related endpoints",
- "x-displayName": "Maintenance",
- },
- {
- name: "notification",
- description: "Notification related endpoints",
- "x-displayName": "Notification",
- },
- {
- name: "page_subscriber",
- description: "Page subscriber related endpoints",
- "x-displayName": "Page Subscriber",
- },
- {
- name: "check",
- description: "Check related endpoints",
- "x-displayName": "Check",
- },
- {
- name: "whoami",
- description: "WhoAmI related endpoints",
- "x-displayName": "WhoAmI",
- },
- ],
- security: [
- {
- ApiKeyAuth: [],
+// this is a fix for the memory leak
+if (process.env.NODE_ENV === "production") {
+ api.get("/openapi", (c) =>
+ c.redirect("https://api.openstatus.dev/openapi-v1.json"),
+ );
+} else {
+ api.doc("/openapi", {
+ openapi: "3.0.0",
+ info: {
+ version: "1.0.0",
+ title: "OpenStatus API",
+ contact: {
+ email: "[email protected]",
+ url: "https://www.openstatus.dev",
+ },
+ description: "This version is deprecated please use v2",
},
- ],
-});
-
+ tags: [
+ {
+ name: "monitor",
+ description: "Monitor related endpoints",
+ "x-displayName": "Monitor",
+ },
+ {
+ name: "page",
+ description: "Page related endpoints",
+ "x-displayName": "Page",
+ },
+ {
+ name: "status_report",
+ description: "Status report related endpoints",
+ "x-displayName": "Status Report",
+ },
+ {
+ name: "status_report_update",
+ description: "Status report update related endpoints",
+ "x-displayName": "Status Report Update",
+ },
+ {
+ name: "incident",
+ description: "Incident related endpoints",
+ "x-displayName": "Incident",
+ },
+ {
+ name: "maintenance",
+ description: "Maintenance related endpoints",
+ "x-displayName": "Maintenance",
+ },
+ {
+ name: "notification",
+ description: "Notification related endpoints",
+ "x-displayName": "Notification",
+ },
+ {
+ name: "page_subscriber",
+ description: "Page subscriber related endpoints",
+ "x-displayName": "Page Subscriber",
+ },
+ {
+ name: "check",
+ description: "Check related endpoints",
+ "x-displayName": "Check",
+ },
+ {
+ name: "whoami",
+ description: "WhoAmI related endpoints",
+ "x-displayName": "WhoAmI",
+ },
+ ],
+ security: [
+ {
+ ApiKeyAuth: [],
+ },
+ ],
+ });
+}
api.get(
"/",
Scalar({