Skip to content

Commit 3bdfd78

Browse files
thibaultleouaythibaultleouay
committed
fix typo
1 parent 9cd231e commit 3bdfd78

14 files changed

Lines changed: 1953 additions & 5 deletions

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ status page with uptime monitoring.
2828
- [Error Handling](#error-handling)
2929
- [Related](#related)
3030

31+
For comprehensive documentation, see [docs/index.md](docs/index.md).
32+
3133
## Features
3234

3335
### Monitoring
@@ -279,10 +281,10 @@ const { monitor } = await client.monitor.v1.MonitorService.updateDNSMonitor({
279281
List all monitors with pagination. Returns monitors grouped by type.
280282

281283
```typescript
282-
const { httpMonitors, tcpMonitors, dnsMonitors, nextPageToken, totalSize } =
284+
const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
283285
await client.monitor.v1.MonitorService.listMonitors({
284-
pageSize: 10,
285-
pageToken: "",
286+
limit: 10,
287+
offset: 0,
286288
});
287289
```
288290

‎docs/authentication.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
[← Back to index](./index.md)
2+
3+
# Authentication
4+
5+
## Recommended: createOpenStatusClient
6+
7+
Create a client with your API key. The key is automatically included in all requests via an interceptor.
8+
9+
```typescript
10+
import { createOpenStatusClient } from "@openstatus/sdk-node";
11+
12+
const client = createOpenStatusClient({
13+
apiKey: process.env.OPENSTATUS_API_KEY,
14+
});
15+
16+
// No headers needed on individual calls
17+
const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});
18+
```
19+
20+
## Alternative: Manual Headers
21+
22+
Use the default `openstatus` client and pass headers on each call.
23+
24+
```typescript
25+
import { openstatus } from "@openstatus/sdk-node";
26+
27+
const headers = {
28+
"x-openstatus-key": process.env.OPENSTATUS_API_KEY,
29+
};
30+
31+
await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });
32+
```
33+
34+
## Environment Variables
35+
36+
| Variable | Description | Default |
37+
|----------|-------------|---------|
38+
| `OPENSTATUS_API_KEY` | Your OpenStatus API key | Required for authenticated calls |
39+
| `OPENSTATUS_API_URL` | Custom API endpoint | `https://api.openstatus.dev/rpc` |
40+
41+
Get your API key from the [OpenStatus dashboard](https://www.openstatus.dev/app).
42+
43+
## Custom Base URL
44+
45+
For self-hosted instances or staging environments:
46+
47+
```typescript
48+
import { createOpenStatusClient } from "@openstatus/sdk-node";
49+
50+
const client = createOpenStatusClient({
51+
apiKey: process.env.OPENSTATUS_API_KEY,
52+
baseUrl: "https://api.staging.example.com/rpc",
53+
});
54+
```
55+
56+
The `baseUrl` option takes precedence over the `OPENSTATUS_API_URL` environment variable.

‎docs/error-handling.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
[← Back to index](./index.md)
2+
3+
# Error Handling
4+
5+
The SDK uses ConnectRPC. Errors are thrown as `ConnectError` instances from the `@connectrpc/connect` package.
6+
7+
```typescript
8+
import { ConnectError } from "@connectrpc/connect";
9+
10+
try {
11+
await client.monitor.v1.MonitorService.deleteMonitor({ id: "invalid" });
12+
} catch (error) {
13+
if (error instanceof ConnectError) {
14+
console.error(`Code: ${error.code}`);
15+
console.error(`Message: ${error.message}`);
16+
}
17+
}
18+
```
19+
20+
## Common Error Codes
21+
22+
| Code | Description |
23+
|------|-------------|
24+
| `unauthenticated` | Missing or invalid API key |
25+
| `not_found` | Resource does not exist |
26+
| `invalid_argument` | Validation failure (e.g., missing required field, value out of range) |
27+
| `permission_denied` | No access to this workspace or resource |
28+
| `already_exists` | Duplicate resource (e.g., slug already taken) |
29+
30+
## Retry Strategy
31+
32+
ConnectRPC does not retry by default. For transient failures (`unavailable`, `deadline_exceeded`), implement your own retry logic:
33+
34+
```typescript
35+
import { ConnectError } from "@connectrpc/connect";
36+
37+
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
38+
for (let attempt = 0; attempt <= maxRetries; attempt++) {
39+
try {
40+
return await fn();
41+
} catch (error) {
42+
if (
43+
error instanceof ConnectError &&
44+
(error.code === "unavailable" || error.code === "deadline_exceeded") &&
45+
attempt < maxRetries
46+
) {
47+
await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
48+
continue;
49+
}
50+
throw error;
51+
}
52+
}
53+
throw new Error("Unreachable");
54+
}
55+
56+
const { httpMonitors } = await withRetry(() =>
57+
client.monitor.v1.MonitorService.listMonitors({})
58+
);
59+
```

‎docs/getting-started.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
[← Back to index](./index.md)
2+
3+
# Getting Started
4+
5+
## Installation
6+
7+
### npm
8+
9+
```bash
10+
npm install @openstatus/sdk-node
11+
```
12+
13+
### JSR
14+
15+
```bash
16+
npx jsr add @openstatus/sdk-node
17+
```
18+
19+
### Deno
20+
21+
```typescript
22+
import { createOpenStatusClient } from "jsr:@openstatus/sdk-node";
23+
```
24+
25+
### Bun
26+
27+
```bash
28+
bun add @openstatus/sdk-node
29+
```
30+
31+
## Quick Start
32+
33+
```typescript
34+
import {
35+
createOpenStatusClient,
36+
Periodicity,
37+
Region,
38+
} from "@openstatus/sdk-node";
39+
40+
const client = createOpenStatusClient({
41+
apiKey: process.env.OPENSTATUS_API_KEY,
42+
});
43+
44+
// Create an HTTP monitor
45+
const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
46+
monitor: {
47+
name: "My API",
48+
url: "https://api.example.com/health",
49+
periodicity: Periodicity.PERIODICITY_1M,
50+
regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
51+
active: true,
52+
},
53+
});
54+
55+
console.log(`Monitor created: ${monitor?.id}`);
56+
57+
// List all monitors
58+
const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
59+
await client.monitor.v1.MonitorService.listMonitors({});
60+
61+
console.log(`Found ${totalSize} monitors`);
62+
```
63+
64+
## Runtime Support
65+
66+
| Runtime | Version | Module Format |
67+
|---------|---------|---------------|
68+
| Node.js | >= 18 | ESM and CJS |
69+
| Deno | >= 2 | ESM (native) |
70+
| Bun | Latest | ESM |
71+
72+
## Full Workflow Example
73+
74+
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.
75+
76+
```typescript
77+
import {
78+
createOpenStatusClient,
79+
NotificationProvider,
80+
Periodicity,
81+
Region,
82+
} from "@openstatus/sdk-node";
83+
84+
const client = createOpenStatusClient({
85+
apiKey: process.env.OPENSTATUS_API_KEY,
86+
});
87+
88+
// 1. Check API health
89+
const health = await client.health.v1.HealthService.check({});
90+
console.log(`API status: ${health.status}`);
91+
92+
// 2. Create an HTTP monitor
93+
const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
94+
monitor: {
95+
name: "Production API",
96+
url: "https://api.example.com/health",
97+
periodicity: Periodicity.PERIODICITY_1M,
98+
regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
99+
active: true,
100+
},
101+
});
102+
103+
// 3. Create a status page
104+
const { statusPage } = await client.statusPage.v1.StatusPageService
105+
.createStatusPage({
106+
title: "Example Status",
107+
slug: "example-status",
108+
description: "Status page for Example services",
109+
});
110+
111+
// 4. Add the monitor as a component
112+
const { component } = await client.statusPage.v1.StatusPageService
113+
.addMonitorComponent({
114+
pageId: statusPage!.id,
115+
monitorId: monitor!.id,
116+
name: "Production API",
117+
});
118+
119+
// 5. Set up Slack notifications
120+
const { notification } = await client.notification.v1.NotificationService
121+
.createNotification({
122+
name: "Slack Alerts",
123+
provider: NotificationProvider.SLACK,
124+
data: {
125+
data: {
126+
case: "slack",
127+
value: { webhookUrl: "https://hooks.slack.com/services/..." },
128+
},
129+
},
130+
monitorIds: [monitor!.id],
131+
});
132+
133+
// 6. Check overall status
134+
const { overallStatus } = await client.statusPage.v1.StatusPageService
135+
.getOverallStatus({
136+
identifier: { case: "id", value: statusPage!.id },
137+
});
138+
139+
console.log(`Overall status: ${overallStatus}`);
140+
```

‎docs/health-service.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
[← Back to index](./index.md)
2+
3+
# Health Service
4+
5+
Check API health status. No authentication required.
6+
7+
```typescript
8+
import { openstatus, ServingStatus } from "@openstatus/sdk-node";
9+
10+
const { status } = await openstatus.health.v1.HealthService.check({});
11+
console.log(ServingStatus[status]); // "SERVING"
12+
```
13+
14+
Or with a configured client:
15+
16+
```typescript
17+
import { createOpenStatusClient, ServingStatus } from "@openstatus/sdk-node";
18+
19+
const client = createOpenStatusClient();
20+
const { status } = await client.health.v1.HealthService.check({});
21+
console.log(ServingStatus[status]); // "SERVING"
22+
```

‎docs/index.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# OpenStatus Node.js SDK Documentation
2+
3+
Official documentation for [`@openstatus/sdk-node`](https://www.npmjs.com/package/@openstatus/sdk-node) — the TypeScript SDK for the [OpenStatus](https://openstatus.dev) monitoring platform.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Getting Started](./getting-started.md)
10+
- Installation
11+
- Quick Start
12+
- Runtime Support
13+
- Full Workflow Example
14+
- [Authentication](./authentication.md)
15+
- createOpenStatusClient
16+
- Manual Headers
17+
- Environment Variables
18+
- Custom Base URL
19+
- [Monitor Service](./monitor-service.md)
20+
- HTTP Monitors
21+
- TCP Monitors
22+
- DNS Monitors
23+
- List Monitors
24+
- Get Monitor
25+
- Trigger Monitor
26+
- Delete Monitor
27+
- Get Monitor Status
28+
- Get Monitor Summary
29+
- [Status Page Service](./status-page-service.md)
30+
- Status Page CRUD
31+
- Components
32+
- Component Groups
33+
- Subscribers
34+
- Get Status Page Content
35+
- Get Overall Status
36+
- [Status Report Service](./status-report-service.md)
37+
- Create Status Report
38+
- Add Status Report Update
39+
- List Status Reports
40+
- Get / Update / Delete Status Reports
41+
- [Maintenance Service](./maintenance-service.md)
42+
- Create Maintenance Window
43+
- List Maintenances
44+
- Get / Update / Delete Maintenance Windows
45+
- [Notification Service](./notification-service.md)
46+
- Create Notification
47+
- Provider Configurations
48+
- Send Test Notification
49+
- Check Notification Limits
50+
- List / Get / Update / Delete Notifications
51+
- [Health Service](./health-service.md)
52+
- Health Check
53+
- [Reference](./reference.md)
54+
- Enums
55+
- Regions
56+
- Assertions
57+
- TypeScript Type Exports
58+
- [Error Handling](./error-handling.md)
59+
- ConnectError
60+
- Common Error Codes
61+
- Retry Strategy
62+
- [TypeScript Tips](./typescript-tips.md)
63+
- Working with bigint Fields
64+
- Handling oneof Types
65+
- Migrating from Default Client to createOpenStatusClient

0 commit comments

Comments
 (0)