openstatus.dev
Openstatus sdk
www.openstatus.dev
thibault.tngl.sh
1/**
2 * @module
3 *
4 * Official Node.js SDK for OpenStatus - the open-source monitoring platform.
5 *
6 * @example Basic usage (recommended)
7 * ```typescript
8 * import { createOpenStatusClient, Periodicity, Region } from "@openstatus/sdk-node";
9 *
10 * // Create a client with your API key
11 * const client = createOpenStatusClient({
12 * apiKey: process.env.OPENSTATUS_API_KEY,
13 * });
14 *
15 * // List all monitors - no need to pass headers
16 * const { httpMonitors, tcpMonitors, dnsMonitors } =
17 * await client.monitor.v1.MonitorService.listMonitors({});
18 *
19 * // Create an HTTP monitor
20 * const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
21 * monitor: {
22 * name: "My API",
23 * url: "https://api.example.com/health",
24 * periodicity: Periodicity.PERIODICITY_1M,
25 * regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
26 * active: true,
27 * },
28 * });
29 * ```
30 *
31 * @example Alternative: Manual headers
32 * ```typescript
33 * import { openstatus, Periodicity } from "@openstatus/sdk-node";
34 *
35 * const headers = { "x-openstatus-key": `Bearer ${process.env.OPENSTATUS_API_KEY}` };
36 * const { monitor } = await openstatus.monitor.v1.MonitorService.createHTTPMonitor({
37 * monitor: { name: "My API", url: "https://api.example.com", periodicity: Periodicity.PERIODICITY_1M, active: true },
38 * }, { headers });
39 * ```
40 */
41
42import type { Client, Interceptor } from "@connectrpc/connect";
43import { createClient } from "@connectrpc/connect";
44import { createConnectTransport } from "@connectrpc/connect-node";
45import { MonitorService } from "./gen/openstatus/monitor/v1/service_pb.ts";
46import { HealthService } from "./gen/openstatus/health/v1/health_pb.ts";
47import { StatusReportService } from "./gen/openstatus/status_report/v1/service_pb.ts";
48import { StatusPageService } from "./gen/openstatus/status_page/v1/service_pb.ts";
49import { MaintenanceService } from "./gen/openstatus/maintenance/v1/service_pb.ts";
50import { NotificationService } from "./gen/openstatus/notification/v1/service_pb.ts";
51
52// Re-export monitor types
53export type {
54 Headers,
55 HTTPMonitor,
56 OpenTelemetryConfig,
57} from "./gen/openstatus/monitor/v1/http_monitor_pb.ts";
58
59export type { TCPMonitor } from "./gen/openstatus/monitor/v1/tcp_monitor_pb.ts";
60
61export type { DNSMonitor } from "./gen/openstatus/monitor/v1/dns_monitor_pb.ts";
62
63// Re-export assertion types
64export type {
65 BodyAssertion,
66 HeaderAssertion,
67 RecordAssertion,
68 StatusCodeAssertion,
69} from "./gen/openstatus/monitor/v1/assertions_pb.ts";
70
71// Re-export assertion comparator enums
72export {
73 NumberComparator,
74 RecordComparator,
75 StringComparator,
76} from "./gen/openstatus/monitor/v1/assertions_pb.ts";
77
78// Re-export enums
79export { HTTPMethod } from "./gen/openstatus/monitor/v1/http_monitor_pb.ts";
80
81export { Periodicity, Region } from "./gen/openstatus/monitor/v1/monitor_pb.ts";
82
83export { MonitorStatus } from "./gen/openstatus/monitor/v1/monitor_pb.ts";
84
85// Re-export request/response types
86export type {
87 CreateDNSMonitorRequest,
88 CreateDNSMonitorResponse,
89 CreateHTTPMonitorRequest,
90 CreateHTTPMonitorResponse,
91 CreateTCPMonitorRequest,
92 CreateTCPMonitorResponse,
93 DeleteMonitorRequest,
94 DeleteMonitorResponse,
95 GetMonitorStatusRequest,
96 GetMonitorStatusResponse,
97 GetMonitorSummaryRequest,
98 GetMonitorSummaryResponse,
99 ListMonitorsRequest,
100 ListMonitorsResponse,
101 RegionStatus,
102 TriggerMonitorRequest,
103 TriggerMonitorResponse,
104 UpdateDNSMonitorRequest,
105 UpdateDNSMonitorResponse,
106 UpdateHTTPMonitorRequest,
107 UpdateHTTPMonitorResponse,
108 UpdateTCPMonitorRequest,
109 UpdateTCPMonitorResponse,
110} from "./gen/openstatus/monitor/v1/service_pb.ts";
111
112export { TimeRange } from "./gen/openstatus/monitor/v1/service_pb.ts";
113
114// Re-export health types
115export type {
116 CheckRequest,
117 CheckResponse,
118} from "./gen/openstatus/health/v1/health_pb.ts";
119
120export { CheckResponse_ServingStatus as ServingStatus } from "./gen/openstatus/health/v1/health_pb.ts";
121
122// Re-export status report types
123export type {
124 StatusReport,
125 StatusReportSummary,
126 StatusReportUpdate,
127} from "./gen/openstatus/status_report/v1/status_report_pb.ts";
128
129export { StatusReportStatus } from "./gen/openstatus/status_report/v1/status_report_pb.ts";
130
131// Re-export status report request/response types
132export type {
133 AddStatusReportUpdateRequest,
134 AddStatusReportUpdateResponse,
135 CreateStatusReportRequest,
136 CreateStatusReportResponse,
137 DeleteStatusReportRequest,
138 DeleteStatusReportResponse,
139 GetStatusReportRequest,
140 GetStatusReportResponse,
141 ListStatusReportsRequest,
142 ListStatusReportsResponse,
143 UpdateStatusReportRequest,
144 UpdateStatusReportResponse,
145} from "./gen/openstatus/status_report/v1/service_pb.ts";
146
147// Re-export status page types
148export type {
149 StatusPage,
150 StatusPageSummary,
151} from "./gen/openstatus/status_page/v1/status_page_pb.ts";
152
153export {
154 OverallStatus,
155 PageAccessType,
156 PageTheme,
157} from "./gen/openstatus/status_page/v1/status_page_pb.ts";
158
159// Re-export page component types
160export type {
161 PageComponent,
162 PageComponentGroup,
163} from "./gen/openstatus/status_page/v1/page_component_pb.ts";
164
165export { PageComponentType } from "./gen/openstatus/status_page/v1/page_component_pb.ts";
166
167// Re-export page subscriber types
168export type { PageSubscriber } from "./gen/openstatus/status_page/v1/page_subscriber_pb.ts";
169
170// Re-export status page request/response types
171export type {
172 AddMonitorComponentRequest,
173 AddMonitorComponentResponse,
174 AddStaticComponentRequest,
175 AddStaticComponentResponse,
176 ComponentStatus,
177 CreateComponentGroupRequest,
178 CreateComponentGroupResponse,
179 CreateStatusPageRequest,
180 CreateStatusPageResponse,
181 DeleteComponentGroupRequest,
182 DeleteComponentGroupResponse,
183 DeleteStatusPageRequest,
184 DeleteStatusPageResponse,
185 GetOverallStatusRequest,
186 GetOverallStatusResponse,
187 GetStatusPageContentRequest,
188 GetStatusPageContentResponse,
189 GetStatusPageRequest,
190 GetStatusPageResponse,
191 ListStatusPagesRequest,
192 ListStatusPagesResponse,
193 ListSubscribersRequest,
194 ListSubscribersResponse,
195 RemoveComponentRequest,
196 RemoveComponentResponse,
197 SubscribeToPageRequest,
198 SubscribeToPageResponse,
199 UnsubscribeFromPageRequest,
200 UnsubscribeFromPageResponse,
201 UpdateComponentGroupRequest,
202 UpdateComponentGroupResponse,
203 UpdateComponentRequest,
204 UpdateComponentResponse,
205 UpdateStatusPageRequest,
206 UpdateStatusPageResponse,
207} from "./gen/openstatus/status_page/v1/service_pb.ts";
208
209// Re-export maintenance types
210export type {
211 Maintenance,
212 MaintenanceSummary,
213} from "./gen/openstatus/maintenance/v1/maintenance_pb.ts";
214
215// Re-export maintenance request/response types
216export type {
217 CreateMaintenanceRequest,
218 CreateMaintenanceResponse,
219 DeleteMaintenanceRequest,
220 DeleteMaintenanceResponse,
221 GetMaintenanceRequest,
222 GetMaintenanceResponse,
223 ListMaintenancesRequest,
224 ListMaintenancesResponse,
225 UpdateMaintenanceRequest,
226 UpdateMaintenanceResponse,
227} from "./gen/openstatus/maintenance/v1/service_pb.ts";
228
229// Re-export notification types
230export type {
231 Notification,
232 NotificationSummary,
233} from "./gen/openstatus/notification/v1/notification_pb.ts";
234
235// Re-export notification provider types and data
236export type {
237 DiscordData,
238 EmailData,
239 GoogleChatData,
240 GrafanaOncallData,
241 NotificationData,
242 NtfyData,
243 OpsgenieData,
244 PagerDutyData,
245 SlackData,
246 SmsData,
247 TelegramData,
248 WebhookData,
249 WebhookHeader,
250 WhatsappData,
251} from "./gen/openstatus/notification/v1/providers_pb.ts";
252
253export {
254 NotificationProvider,
255 OpsgenieRegion,
256} from "./gen/openstatus/notification/v1/providers_pb.ts";
257
258// Re-export notification request/response types
259export type {
260 CheckNotificationLimitRequest,
261 CheckNotificationLimitResponse,
262 CreateNotificationRequest,
263 CreateNotificationResponse,
264 DeleteNotificationRequest,
265 DeleteNotificationResponse,
266 GetNotificationRequest,
267 GetNotificationResponse,
268 ListNotificationsRequest,
269 ListNotificationsResponse,
270 SendTestNotificationRequest,
271 SendTestNotificationResponse,
272 UpdateNotificationRequest,
273 UpdateNotificationResponse,
274} from "./gen/openstatus/notification/v1/service_pb.ts";
275
276/**
277 * Default OpenStatus API URL.
278 */
279const DEFAULT_API_URL = "https://api.openstatus.dev/rpc";
280
281/**
282 * Configuration options for creating an OpenStatus client.
283 */
284export interface OpenStatusClientOptions {
285 /**
286 * Your OpenStatus API key.
287 * If provided, it will be automatically included in all requests.
288 */
289 apiKey?: string;
290 /**
291 * Custom API base URL. Defaults to the OpenStatus production API.
292 */
293 baseUrl?: string;
294}
295
296/**
297 * Creates an interceptor that adds the API key header to all requests.
298 */
299function createAuthInterceptor(apiKey: string): Interceptor {
300 return (next) => (req) => {
301 req.header.set("x-openstatus-key", `${apiKey}`);
302 return next(req);
303 };
304}
305
306/**
307 * Creates a Connect RPC transport configured for the OpenStatus API.
308 */
309function createTransport(options?: OpenStatusClientOptions) {
310 const interceptors: Interceptor[] = [];
311
312 if (options?.apiKey) {
313 interceptors.push(createAuthInterceptor(options.apiKey));
314 }
315
316 return createConnectTransport({
317 baseUrl: options?.baseUrl ?? process.env.OPENSTATUS_API_URL ??
318 DEFAULT_API_URL,
319 httpVersion: "2",
320 interceptors,
321 });
322}
323
324/**
325 * OpenStatus API client interface.
326 *
327 * Provides access to Monitor and Health services.
328 */
329export interface OpenStatusClient {
330 /**
331 * Monitor service namespace (v1).
332 */
333 monitor: {
334 v1: {
335 /**
336 * MonitorService provides CRUD and operational commands for monitors.
337 *
338 * Methods:
339 * - `createHTTPMonitor` - Create a new HTTP monitor
340 * - `createTCPMonitor` - Create a new TCP monitor
341 * - `createDNSMonitor` - Create a new DNS monitor
342 * - `updateHTTPMonitor` - Update an existing HTTP monitor
343 * - `updateTCPMonitor` - Update an existing TCP monitor
344 * - `updateDNSMonitor` - Update an existing DNS monitor
345 * - `listMonitors` - List all monitors
346 * - `triggerMonitor` - Trigger an immediate check
347 * - `deleteMonitor` - Delete a monitor
348 * - `getMonitorStatus` - Get status of all regions for a monitor
349 * - `getMonitorSummary` - Get aggregated metrics for a monitor
350 */
351 MonitorService: Client<typeof MonitorService>;
352 };
353 };
354 /**
355 * Health service namespace (v1).
356 */
357 health: {
358 v1: {
359 /**
360 * HealthService provides health check endpoints.
361 *
362 * Methods:
363 * - `check` - Check API health status
364 */
365 HealthService: Client<typeof HealthService>;
366 };
367 };
368 /**
369 * Status report service namespace (v1).
370 */
371 statusReport: {
372 v1: {
373 /**
374 * StatusReportService provides CRUD operations for status reports.
375 *
376 * Methods:
377 * - `createStatusReport` - Create a new status report
378 * - `getStatusReport` - Get a status report by ID
379 * - `listStatusReports` - List all status reports
380 * - `updateStatusReport` - Update a status report
381 * - `deleteStatusReport` - Delete a status report
382 * - `addStatusReportUpdate` - Add an update to a status report
383 */
384 StatusReportService: Client<typeof StatusReportService>;
385 };
386 };
387 /**
388 * Status page service namespace (v1).
389 */
390 statusPage: {
391 v1: {
392 /**
393 * StatusPageService provides CRUD and management operations for status pages.
394 *
395 * Methods:
396 * - `createStatusPage` - Create a new status page
397 * - `getStatusPage` - Get a status page by ID
398 * - `listStatusPages` - List all status pages
399 * - `updateStatusPage` - Update a status page
400 * - `deleteStatusPage` - Delete a status page
401 * - `addMonitorComponent` - Add a monitor-based component
402 * - `addStaticComponent` - Add a static component
403 * - `removeComponent` - Remove a component
404 * - `updateComponent` - Update a component
405 * - `createComponentGroup` - Create a component group
406 * - `deleteComponentGroup` - Delete a component group
407 * - `updateComponentGroup` - Update a component group
408 * - `subscribeToPage` - Subscribe an email to a status page
409 * - `unsubscribeFromPage` - Unsubscribe from a status page
410 * - `listSubscribers` - List all subscribers
411 * - `getStatusPageContent` - Get full status page content
412 * - `getOverallStatus` - Get aggregated status
413 */
414 StatusPageService: Client<typeof StatusPageService>;
415 };
416 };
417 /**
418 * Maintenance service namespace (v1).
419 */
420 maintenance: {
421 v1: {
422 /**
423 * MaintenanceService provides CRUD operations for maintenance windows.
424 *
425 * Methods:
426 * - `createMaintenance` - Create a new maintenance window
427 * - `getMaintenance` - Get a maintenance window by ID
428 * - `listMaintenances` - List all maintenance windows
429 * - `updateMaintenance` - Update a maintenance window
430 * - `deleteMaintenance` - Delete a maintenance window
431 */
432 MaintenanceService: Client<typeof MaintenanceService>;
433 };
434 };
435 /**
436 * Notification service namespace (v1).
437 */
438 notification: {
439 v1: {
440 /**
441 * NotificationService provides CRUD operations for notification channels.
442 *
443 * Methods:
444 * - `createNotification` - Create a new notification channel
445 * - `getNotification` - Get a notification channel by ID
446 * - `listNotifications` - List all notification channels
447 * - `updateNotification` - Update a notification channel
448 * - `deleteNotification` - Delete a notification channel
449 * - `sendTestNotification` - Send a test notification
450 * - `checkNotificationLimit` - Check notification limits
451 */
452 NotificationService: Client<typeof NotificationService>;
453 };
454 };
455}
456
457/**
458 * Creates a configured OpenStatus client with optional API key authentication.
459 *
460 * Use this factory function to create a client that automatically includes
461 * your API key in all requests, eliminating the need to pass headers manually.
462 *
463 * @example
464 * ```typescript
465 * import { createOpenStatusClient, Periodicity, Region } from "@openstatus/sdk-node";
466 *
467 * // Create a configured client
468 * const client = createOpenStatusClient({
469 * apiKey: process.env.OPENSTATUS_API_KEY,
470 * });
471 *
472 * // No need to pass headers on each call
473 * const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});
474 *
475 * const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
476 * monitor: {
477 * name: "My API",
478 * url: "https://api.example.com/health",
479 * periodicity: Periodicity.PERIODICITY_1M,
480 * regions: [Region.FLY_AMS, Region.FLY_IAD],
481 * active: true,
482 * },
483 * });
484 * ```
485 */
486export function createOpenStatusClient(
487 options?: OpenStatusClientOptions,
488): OpenStatusClient {
489 const transport = createTransport(options);
490
491 return {
492 monitor: {
493 v1: {
494 MonitorService: createClient(MonitorService, transport),
495 },
496 },
497 health: {
498 v1: {
499 HealthService: createClient(HealthService, transport),
500 },
501 },
502 statusReport: {
503 v1: {
504 StatusReportService: createClient(StatusReportService, transport),
505 },
506 },
507 statusPage: {
508 v1: {
509 StatusPageService: createClient(StatusPageService, transport),
510 },
511 },
512 maintenance: {
513 v1: {
514 MaintenanceService: createClient(MaintenanceService, transport),
515 },
516 },
517 notification: {
518 v1: {
519 NotificationService: createClient(NotificationService, transport),
520 },
521 },
522 };
523}
524
525/**
526 * Default OpenStatus SDK client (without pre-configured authentication).
527 *
528 * For authenticated requests, either:
529 * 1. Use `createOpenStatusClient({ apiKey })` to create a pre-configured client (recommended)
530 * 2. Pass headers manually on each call
531 *
532 * @example Using createOpenStatusClient (recommended)
533 * ```typescript
534 * import { createOpenStatusClient, Periodicity } from "@openstatus/sdk-node";
535 *
536 * const client = createOpenStatusClient({ apiKey: process.env.OPENSTATUS_API_KEY });
537 * const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
538 * monitor: { name: "My Website", url: "https://example.com", periodicity: Periodicity.PERIODICITY_1M, active: true },
539 * });
540 * ```
541 *
542 * @example Using default client with manual headers
543 * ```typescript
544 * import { openstatus, Periodicity } from "@openstatus/sdk-node";
545 *
546 * const headers = { "x-openstatus-key": `Bearer ${process.env.OPENSTATUS_API_KEY}` };
547 * const { monitor } = await openstatus.monitor.v1.MonitorService.createHTTPMonitor({
548 * monitor: { name: "My Website", url: "https://example.com", periodicity: Periodicity.PERIODICITY_1M, active: true },
549 * }, { headers });
550 * ```
551 */
552export const openstatus: OpenStatusClient = createOpenStatusClient();