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