@openstatus/sdk-node 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Openstatus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# OpenStatus Node.js SDK
+
+[![JSR](https://jsr.io/badges/@openstatus/node-sdk)](https://jsr.io/@openstatus/node-sdk)
+[![npm](https://img.shields.io/npm/v/@openstatus/node-sdk)](https://www.npmjs.com/package/@openstatus/node-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Node.js SDK for [OpenStatus](https://openstatus.dev) - the open-source
+monitoring platform.
+
+## Features
+
+- **HTTP Monitoring** - Monitor websites and APIs with customizable assertions
+- **TCP Monitoring** - Check database connections and other TCP services
+- **DNS Monitoring** - Verify DNS records and resolution
+- **Global Regions** - Monitor from 28 locations worldwide
+- **Type-safe** - Full TypeScript support with generated types
+
+## Installation
+
+### JSR
+
+```bash
+npx jsr add @openstatus/node-sdk
+```
+
+### npm
+
+```bash
+npm install @openstatus/node-sdk
+```
+
+### Deno
+
+```typescript
+import { openstatus } from "jsr:@openstatus/node-sdk";
+```
+
+## Quick Start
+
+```typescript
+import { openstatus } from "@openstatus/node-sdk";
+
+const headers = {
+  "x-openstatus-key": `Bearer ${process.env.OPENSTATUS_API_KEY}`,
+};
+
+// Create a monitor
+const monitor = await openstatus.monitor.v1.MonitorService.createHTTPMonitor(
+  {
+    name: "My API",
+    url: "https://api.example.com/health",
+    periodicity: "1m",
+    method: "GET",
+    regions: ["ams", "iad", "syd"],
+    active: true,
+    statusCodeAssertions: [{ comparator: "EQUAL", target: 200 }],
+  },
+  { headers },
+);
+
+console.log(`Monitor created: ${monitor.monitor?.id}`);
+
+// List all monitors
+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
+  await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });
+
+console.log(`Found ${totalSize} monitors`);
+```
+
+## Authentication
+
+All API requests require an API key. Get yours from the
+[OpenStatus dashboard](https://www.openstatus.dev/app).
+
+```typescript
+const headers = {
+  "x-openstatus-key": `Bearer ${process.env.OPENSTATUS_API_KEY}`,
+};
+
+// Pass headers to any service method
+await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });
+```
+
+## Environment Variables
+
+| Variable             | Description             | Default                          |
+| -------------------- | ----------------------- | -------------------------------- |
+| `OPENSTATUS_API_KEY` | Your OpenStatus API key | -                                |
+| `OPENSTATUS_API_URL` | Custom API endpoint     | `https://api.openstatus.dev/rpc` |
+
+## API Reference
+
+### Monitor Service
+
+#### `createHTTPMonitor(request, options)`
+
+Create an HTTP/HTTPS monitor.
+
+```typescript
+const { monitor } = await openstatus.monitor.v1.MonitorService
+  .createHTTPMonitor(
+    {
+      name: "My Website",
+      url: "https://example.com",
+      periodicity: "1m",
+      method: "GET",
+      regions: ["ams", "iad", "syd"],
+      active: true,
+    },
+    { headers },
+  );
+```
+
+#### `createTCPMonitor(request, options)`
+
+Create a TCP connection monitor.
+
+```typescript
+const { monitor } = await openstatus.monitor.v1.MonitorService.createTCPMonitor(
+  {
+    name: "Database",
+    uri: "db.example.com:5432",
+    periodicity: "5m",
+    regions: ["ams", "iad"],
+    active: true,
+  },
+  { headers },
+);
+```
+
+#### `createDNSMonitor(request, options)`
+
+Create a DNS resolution monitor.
+
+```typescript
+const { monitor } = await openstatus.monitor.v1.MonitorService.createDNSMonitor(
+  {
+    name: "DNS Check",
+    uri: "example.com",
+    periodicity: "10m",
+    regions: ["ams"],
+    active: true,
+    recordAssertions: [{
+      recordType: "A",
+      comparator: "EQUAL",
+      target: "93.184.216.34",
+    }],
+  },
+  { headers },
+);
+```
+
+#### `listMonitors(request, options)`
+
+List all monitors with pagination. Returns monitors grouped by type.
+
+```typescript
+const { httpMonitors, tcpMonitors, dnsMonitors, nextPageToken, totalSize } =
+  await openstatus.monitor.v1.MonitorService.listMonitors(
+    { pageSize: 10, pageToken: "" },
+    { headers },
+  );
+```
+
+#### `triggerMonitor(request, options)`
+
+Trigger an immediate check.
+
+```typescript
+await openstatus.monitor.v1.MonitorService.triggerMonitor(
+  { id: "mon_123" },
+  { headers },
+);
+```
+
+#### `deleteMonitor(request, options)`
+
+Delete a monitor.
+
+```typescript
+await openstatus.monitor.v1.MonitorService.deleteMonitor(
+  { id: "mon_123" },
+  { headers },
+);
+```
+
+#### `getMonitorStatus(request, options)`
+
+Get the current status of a monitor across all configured regions.
+
+```typescript
+const { id, regions } =
+  await openstatus.monitor.v1.MonitorService.getMonitorStatus(
+    { id: "mon_123" },
+    { headers },
+  );
+
+// regions is an array of { region, status }
+// status: ACTIVE, DEGRADED, or ERROR
+for (const { region, status } of regions) {
+  console.log(`${region}: ${status}`);
+}
+```
+
+#### `getMonitorSummary(request, options)`
+
+Get aggregated metrics and latency percentiles for a monitor.
+
+```typescript
+import { TimeRange } from "@openstatus/node-sdk";
+
+const summary = await openstatus.monitor.v1.MonitorService.getMonitorSummary(
+  {
+    id: "mon_123",
+    timeRange: TimeRange.TIME_RANGE_7D, // 1D, 7D, or 14D
+    regions: [], // optional: filter by specific regions
+  },
+  { headers },
+);
+
+console.log(`Last ping: ${summary.lastPingAt}`);
+console.log(`Success: ${summary.totalSuccessful}`);
+console.log(`Degraded: ${summary.totalDegraded}`);
+console.log(`Failed: ${summary.totalFailed}`);
+console.log(`P50 latency: ${summary.p50}ms`);
+console.log(`P95 latency: ${summary.p95}ms`);
+console.log(`P99 latency: ${summary.p99}ms`);
+```
+
+### Health Service
+
+Check API health status (no authentication required).
+
+```typescript
+const { status } = await openstatus.health.v1.HealthService.check({});
+console.log(status); // "SERVING"
+```
+
+## Monitor Options
+
+### HTTP Monitor
+
+| Option                 | Type     | Required | Description                                       |
+| ---------------------- | -------- | -------- | ------------------------------------------------- |
+| `name`                 | string   | Yes      | Monitor name (max 256 chars)                      |
+| `url`                  | string   | Yes      | URL to monitor                                    |
+| `periodicity`          | string   | No       | `30s`, `1m`, `5m`, `10m`, `30m`, `1h`             |
+| `method`               | string   | No       | `GET`, `POST`, `HEAD`, `PUT`, `PATCH`, `DELETE`   |
+| `body`                 | string   | No       | Request body                                      |
+| `headers`              | object   | No       | Custom headers                                    |
+| `timeout`              | number   | No       | Timeout in ms (default: 45000, max: 120000)       |
+| `retry`                | number   | No       | Retry attempts (default: 3, max: 10)              |
+| `followRedirects`      | boolean  | No       | Follow redirects (default: true)                  |
+| `regions`              | string[] | No       | [Regions](#regions) for checks                    |
+| `active`               | boolean  | No       | Enable monitoring (default: false)                |
+| `public`               | boolean  | No       | Public visibility (default: false)                |
+| `degradedAt`           | number   | No       | Latency threshold (ms) for degraded status        |
+| `statusCodeAssertions` | array    | No       | [Status code assertions](#status-code-assertions) |
+| `bodyAssertions`       | array    | No       | [Body assertions](#body-assertions)               |
+| `headerAssertions`     | array    | No       | [Header assertions](#header-assertions)           |
+
+### TCP Monitor
+
+| Option        | Type     | Required | Description                    |
+| ------------- | -------- | -------- | ------------------------------ |
+| `name`        | string   | Yes      | Monitor name                   |
+| `uri`         | string   | Yes      | `host:port` to monitor         |
+| `periodicity` | string   | No       | Check interval                 |
+| `timeout`     | number   | No       | Timeout in ms (default: 45000) |
+| `retry`       | number   | No       | Retry attempts (default: 3)    |
+| `regions`     | string[] | No       | [Regions](#regions) for checks |
+| `active`      | boolean  | No       | Enable monitoring              |
+
+### DNS Monitor
+
+| Option             | Type     | Required | Description                                     |
+| ------------------ | -------- | -------- | ----------------------------------------------- |
+| `name`             | string   | Yes      | Monitor name                                    |
+| `uri`              | string   | Yes      | Domain to resolve                               |
+| `periodicity`      | string   | No       | Check interval                                  |
+| `timeout`          | number   | No       | Timeout in ms (default: 45000)                  |
+| `retry`            | number   | No       | Retry attempts (default: 3)                     |
+| `regions`          | string[] | No       | [Regions](#regions) for checks                  |
+| `recordAssertions` | array    | No       | [DNS record assertions](#dns-record-assertions) |
+
+## Assertions
+
+### Status Code Assertions
+
+Validate HTTP response status codes.
+
+```typescript
+{
+  statusCodeAssertions: [
+    { comparator: "EQUAL", target: 200 },
+    { comparator: "LESS_THAN", target: 400 },
+  ];
+}
+```
+
+**Comparators:** `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`,
+`LESS_THAN`, `LESS_THAN_OR_EQUAL`
+
+### Body Assertions
+
+Validate response body content.
+
+```typescript
+{
+  bodyAssertions: [
+    { comparator: "CONTAINS", target: '"status":"ok"' },
+    { comparator: "NOT_EMPTY" },
+  ];
+}
+```
+
+**Comparators:** `CONTAINS`, `NOT_CONTAINS`, `EQUAL`, `NOT_EQUAL`, `EMPTY`,
+`NOT_EMPTY`
+
+### Header Assertions
+
+Validate response headers.
+
+```typescript
+{
+  headerAssertions: [
+    { key: "content-type", comparator: "CONTAINS", target: "application/json" },
+  ];
+}
+```
+
+### DNS Record Assertions
+
+Validate DNS records.
+
+```typescript
+{
+  recordAssertions: [
+    { recordType: "A", comparator: "EQUAL", target: "93.184.216.34" },
+    { recordType: "CNAME", comparator: "CONTAINS", target: "cdn" },
+  ];
+}
+```
+
+**Record types:** `A`, `AAAA`, `CNAME`, `MX`, `TXT`
+
+## Regions
+
+Monitor from 28 global locations across multiple providers:
+
+### Fly.io Regions
+
+| Code  | Location        | Code  | Location     |
+| ----- | --------------- | ----- | ------------ |
+| `ams` | Amsterdam       | `lax` | Los Angeles  |
+| `arn` | Stockholm       | `lhr` | London       |
+| `bom` | Mumbai          | `nrt` | Tokyo        |
+| `cdg` | Paris           | `ord` | Chicago      |
+| `dfw` | Dallas          | `sjc` | San Jose     |
+| `ewr` | Newark          | `sin` | Singapore    |
+| `fra` | Frankfurt       | `syd` | Sydney       |
+| `gru` | São Paulo       | `yyz` | Toronto      |
+| `iad` | Washington D.C. | `jnb` | Johannesburg |
+
+### Koyeb Regions
+
+| Code        | Location      |
+| ----------- | ------------- |
+| `koyeb_fra` | Frankfurt     |
+| `koyeb_par` | Paris         |
+| `koyeb_sfo` | San Francisco |
+| `koyeb_sin` | Singapore     |
+| `koyeb_tyo` | Tokyo         |
+| `koyeb_was` | Washington    |
+
+### Railway Regions
+
+| Code                    | Location       |
+| ----------------------- | -------------- |
+| `railway_us_west2`      | US West        |
+| `railway_us_east4`      | US East        |
+| `railway_europe_west4`  | Europe West    |
+| `railway_asia_southeast1` | Asia Southeast |
+
+## Error Handling
+
+The SDK uses Connect RPC. Errors include a `code` and `message`:
+
+```typescript
+import { ConnectError } from "@connectrpc/connect";
+
+try {
+  await openstatus.monitor.v1.MonitorService.deleteMonitor(
+    { id: "invalid" },
+    { headers },
+  );
+} catch (error) {
+  if (error instanceof ConnectError) {
+    console.error(`Error ${error.code}: ${error.message}`);
+  }
+}
+```
+
+## Related
+
+- [OpenStatus](https://openstatus.dev) - Open-source monitoring platform
+- [Documentation](https://docs.openstatus.dev) - Full API documentation
+- [Status Page](https://status.openstatus.dev) - OpenStatus service status
+
+## License
+
+MIT