Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/sdk-node. SDK for openstatus www.openstatus.dev
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680/** * @module * * Official Node.js SDK for OpenStatus - the open-source monitoring platform. * * @example Basic usage (recommended) * ```typescript * import { createOpenStatusClient, Periodicity, Region } from "@openstatus/sdk-node"; * * // Create a client with your API key * const client = createOpenStatusClient({ * apiKey: process.env.OPENSTATUS_API_KEY, * }); * * // List all monitors - no need to pass headers * const { httpMonitors, tcpMonitors, dnsMonitors } = * await client.monitor.v1.MonitorService.listMonitors({}); * * // 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, * }, * }); * ``` * * @example Alternative: Manual headers * ```typescript * import { openstatus, Periodicity } from "@openstatus/sdk-node"; * * const headers = { "x-openstatus-key": `${process.env.OPENSTATUS_API_KEY}` }; * const { monitor } = await openstatus.monitor.v1.MonitorService.createHTTPMonitor({ * monitor: { name: "My API", url: "https://api.example.com", periodicity: Periodicity.PERIODICITY_1M, active: true }, * }, { headers }); * ``` */
import type { Client, Interceptor, Transport } from "@connectrpc/connect";import { createClient } from "@connectrpc/connect";import { createConnectTransport } from "@connectrpc/connect-web";import { MonitorService } from "./gen/openstatus/monitor/v1/service_pb.ts";import { HealthService } from "./gen/openstatus/health/v1/health_pb.ts";import { StatusReportService } from "./gen/openstatus/status_report/v1/service_pb.ts";import { StatusPageService } from "./gen/openstatus/status_page/v1/service_pb.ts";import { MaintenanceService } from "./gen/openstatus/maintenance/v1/service_pb.ts";import { NotificationService } from "./gen/openstatus/notification/v1/service_pb.ts";import { PrivateLocationService } from "./gen/openstatus/private_location/v1/service_pb.ts";
// Re-export the generated service descriptors and Connect transport types so// non-Node runtimes (Cloudflare Workers, browsers) can build their own// transport — e.g. `createClient(MonitorService, ownTransport)`.export type { Client, Interceptor, Transport } from "@connectrpc/connect";export { HealthService, MaintenanceService, MonitorService, NotificationService, PrivateLocationService, StatusPageService, StatusReportService,};
// Re-export monitor typesexport type { Headers, HTTPMonitor, OpenTelemetryConfig,} from "./gen/openstatus/monitor/v1/http_monitor_pb.ts";
export type { TCPMonitor } from "./gen/openstatus/monitor/v1/tcp_monitor_pb.ts";
export type { DNSMonitor } from "./gen/openstatus/monitor/v1/dns_monitor_pb.ts";
// Re-export assertion typesexport type { BodyAssertion, HeaderAssertion, RecordAssertion, StatusCodeAssertion,} from "./gen/openstatus/monitor/v1/assertions_pb.ts";
// Re-export assertion comparator enumsexport { NumberComparator, RecordComparator, StringComparator,} from "./gen/openstatus/monitor/v1/assertions_pb.ts";
// Re-export enumsexport { HTTPMethod } from "./gen/openstatus/monitor/v1/http_monitor_pb.ts";
export { Periodicity, Region } from "./gen/openstatus/monitor/v1/monitor_pb.ts";
export { MonitorStatus } from "./gen/openstatus/monitor/v1/monitor_pb.ts";
// Re-export request/response typesexport type { CreateDNSMonitorRequest, CreateDNSMonitorResponse, CreateHTTPMonitorRequest, CreateHTTPMonitorResponse, CreateTCPMonitorRequest, CreateTCPMonitorResponse, DeleteMonitorRequest, DeleteMonitorResponse, GetMonitorHTTPResponseLogRequest, GetMonitorHTTPResponseLogResponse, GetMonitorRequest, GetMonitorResponse, GetMonitorStatusRequest, GetMonitorStatusResponse, GetMonitorSummaryRequest, GetMonitorSummaryResponse, HTTPResponseLogDetail, HTTPResponseLogListItem, HTTPResponseLogPagination, HTTPResponseLogTiming, ListMonitorHTTPResponseLogsRequest, ListMonitorHTTPResponseLogsResponse, ListMonitorsRequest, ListMonitorsResponse, MonitorConfig, RegionStatus, TriggerMonitorRequest, TriggerMonitorResponse, UpdateDNSMonitorRequest, UpdateDNSMonitorResponse, UpdateHTTPMonitorRequest, UpdateHTTPMonitorResponse, UpdateTCPMonitorRequest, UpdateTCPMonitorResponse,} from "./gen/openstatus/monitor/v1/service_pb.ts";
export { HTTPResponseLogRequestStatus, HTTPResponseLogTrigger, TimeRange,} from "./gen/openstatus/monitor/v1/service_pb.ts";
// Re-export health typesexport type { CheckRequest, CheckResponse,} from "./gen/openstatus/health/v1/health_pb.ts";
export { CheckResponse_ServingStatus as ServingStatus } from "./gen/openstatus/health/v1/health_pb.ts";
// Re-export status report typesexport type { ComponentImpact, StatusReport, StatusReportSummary, StatusReportUpdate,} from "./gen/openstatus/status_report/v1/status_report_pb.ts";
export { PageComponentImpact, StatusReportStatus,} from "./gen/openstatus/status_report/v1/status_report_pb.ts";
// Re-export status report request/response typesexport type { AddStatusReportUpdateRequest, AddStatusReportUpdateResponse, CreateStatusReportRequest, CreateStatusReportResponse, DeleteStatusReportRequest, DeleteStatusReportResponse, GetStatusReportRequest, GetStatusReportResponse, ListStatusReportsRequest, ListStatusReportsResponse, UpdateStatusReportRequest, UpdateStatusReportResponse,} from "./gen/openstatus/status_report/v1/service_pb.ts";
// Re-export status page typesexport type { CustomTheme, PageConfiguration, StatusPage, StatusPageSummary,} from "./gen/openstatus/status_page/v1/status_page_pb.ts";
export { Locale, OverallStatus, PageAccessType, PageBarType, PageMetricType, PageTheme,} from "./gen/openstatus/status_page/v1/status_page_pb.ts";
// Re-export page component typesexport type { PageComponent, PageComponentGroup,} from "./gen/openstatus/status_page/v1/page_component_pb.ts";
export { PageComponentType } from "./gen/openstatus/status_page/v1/page_component_pb.ts";
// Re-export page subscriber typesexport type { PageSubscriber } from "./gen/openstatus/status_page/v1/page_subscriber_pb.ts";
export { SubscriberSource } from "./gen/openstatus/status_page/v1/page_subscriber_pb.ts";
// Re-export status page request/response typesexport type { AddMonitorComponentRequest, AddMonitorComponentResponse, AddStaticComponentRequest, AddStaticComponentResponse, ComponentDayBucket, ComponentEvent, ComponentStatus, CreateComponentGroupRequest, CreateComponentGroupResponse, CreatePageSubscriptionRequest, CreatePageSubscriptionResponse, CreateStatusPageRequest, CreateStatusPageResponse, DeleteComponentGroupRequest, DeleteComponentGroupResponse, DeleteStatusPageRequest, DeleteStatusPageResponse, EmailChannel, GetOverallStatusRequest, GetOverallStatusResponse, GetPageComponentDailySummaryRequest, GetPageComponentDailySummaryResponse, GetPageComponentRequest, GetPageComponentResponse, GetStatusPageContentRequest, GetStatusPageContentResponse, GetStatusPageOverviewRequest, GetStatusPageOverviewResponse, GetStatusPageRequest, GetStatusPageResponse, ListStatusPagesRequest, ListStatusPagesResponse, ListSubscribersRequest, ListSubscribersResponse, PageComponentDailySummary, RemoveComponentRequest, RemoveComponentResponse, SubscribeToPageRequest, SubscribeToPageResponse, UnsubscribeFromPageRequest, UnsubscribeFromPageResponse, UpdateComponentGroupRequest, UpdateComponentGroupResponse, UpdateComponentRequest, UpdateComponentResponse, UpdateStatusPageRequest, UpdateStatusPageResponse, WebhookChannel, WebhookChannelHeader,} from "./gen/openstatus/status_page/v1/service_pb.ts";
export { ComponentDayStatus, ComponentEventStatus, ComponentEventType,} from "./gen/openstatus/status_page/v1/service_pb.ts";
// Re-export maintenance typesexport type { Maintenance, MaintenanceSummary,} from "./gen/openstatus/maintenance/v1/maintenance_pb.ts";
// Re-export maintenance request/response typesexport type { CreateMaintenanceRequest, CreateMaintenanceResponse, DeleteMaintenanceRequest, DeleteMaintenanceResponse, GetMaintenanceRequest, GetMaintenanceResponse, ListMaintenancesRequest, ListMaintenancesResponse, UpdateMaintenanceRequest, UpdateMaintenanceResponse,} from "./gen/openstatus/maintenance/v1/service_pb.ts";
// Re-export notification typesexport type { Notification, NotificationSummary,} from "./gen/openstatus/notification/v1/notification_pb.ts";
// Re-export notification provider types and dataexport type { DiscordData, EmailData, GoogleChatData, GrafanaOncallData, MsTeamsData, NotificationData, NtfyData, OpsgenieData, PagerDutyData, SlackData, SmsData, TelegramData, WebhookData, WebhookHeader, WhatsappData,} from "./gen/openstatus/notification/v1/providers_pb.ts";
export { NotificationProvider, OpsgenieRegion,} from "./gen/openstatus/notification/v1/providers_pb.ts";
// Re-export notification request/response typesexport type { CheckNotificationLimitRequest, CheckNotificationLimitResponse, CreateNotificationRequest, CreateNotificationResponse, DeleteNotificationRequest, DeleteNotificationResponse, GetNotificationRequest, GetNotificationResponse, ListNotificationsRequest, ListNotificationsResponse, SendTestNotificationRequest, SendTestNotificationResponse, UpdateNotificationRequest, UpdateNotificationResponse,} from "./gen/openstatus/notification/v1/service_pb.ts";
// Re-export private location typesexport type { PrivateLocation, PrivateLocationSummary,} from "./gen/openstatus/private_location/v1/private_location_pb.ts";
export { PrivateLocationStatus } from "./gen/openstatus/private_location/v1/private_location_pb.ts";
// Re-export private location request/response typesexport type { CreatePrivateLocationRequest, CreatePrivateLocationResponse, DeletePrivateLocationRequest, DeletePrivateLocationResponse, GetPrivateLocationRequest, GetPrivateLocationResponse, ListPrivateLocationsRequest, ListPrivateLocationsResponse, UpdatePrivateLocationRequest, UpdatePrivateLocationResponse,} from "./gen/openstatus/private_location/v1/service_pb.ts";
/** * Default OpenStatus API URL. */const DEFAULT_API_URL = "https://api.openstatus.dev/rpc";
/** * Configuration options for creating an OpenStatus client. */export interface OpenStatusClientOptions { /** * Your OpenStatus API key. * If provided, it will be automatically included in all requests. */ apiKey?: string; /** * Custom API base URL. Defaults to the OpenStatus production API. */ baseUrl?: string; /** * Bring your own Connect transport — e.g. a `@connectrpc/connect-web` * transport with a custom `fetch` (Cloudflare Workers need one that * tolerates `redirect: "error"`). When set, `baseUrl` and `apiKey` are * ignored; configure auth on the transport via `createAuthInterceptor`. */ transport?: Transport;}
/** * Creates an interceptor that adds the API key header to all requests. */export function createAuthInterceptor(apiKey: string): Interceptor { return (next) => (req) => { req.header.set("x-openstatus-key", `${apiKey}`); return next(req); };}
/** * Creates a fetch-based Connect transport for the OpenStatus API. Works on any * runtime with a global `fetch` (Node 18+, Deno, Bun, edge/Workers). * Returns `options.transport` verbatim when one is provided. */export function createOpenStatusTransport( options?: OpenStatusClientOptions,): Transport { if (options?.transport) return options.transport;
const interceptors: Interceptor[] = [];
if (options?.apiKey) { interceptors.push(createAuthInterceptor(options.apiKey)); }
return createConnectTransport({ baseUrl: options?.baseUrl ?? process.env.OPENSTATUS_API_URL ?? DEFAULT_API_URL, interceptors, });}
/** * OpenStatus API client interface. * * Provides access to Monitor and Health services. */export interface OpenStatusClient { /** * Monitor service namespace (v1). */ monitor: { v1: { /** * MonitorService provides CRUD and operational commands for monitors. * * Methods: * - `createHTTPMonitor` - Create a new HTTP monitor * - `createTCPMonitor` - Create a new TCP monitor * - `createDNSMonitor` - Create a new DNS monitor * - `updateHTTPMonitor` - Update an existing HTTP monitor * - `updateTCPMonitor` - Update an existing TCP monitor * - `updateDNSMonitor` - Update an existing DNS monitor * - `listMonitors` - List all monitors * - `getMonitor` - Get a single monitor by ID * - `triggerMonitor` - Trigger an immediate check * - `deleteMonitor` - Delete a monitor * - `getMonitorStatus` - Get status of all regions for a monitor * - `getMonitorSummary` - Get aggregated metrics for a monitor * - `listMonitorHTTPResponseLogs` - List HTTP response logs for a monitor * - `getMonitorHTTPResponseLog` - Get a single HTTP response log with full details */ MonitorService: Client<typeof MonitorService>; }; }; /** * Health service namespace (v1). */ health: { v1: { /** * HealthService provides health check endpoints. * * Methods: * - `check` - Check API health status */ HealthService: Client<typeof HealthService>; }; }; /** * Status report service namespace (v1). */ statusReport: { v1: { /** * StatusReportService provides CRUD operations for status reports. * * Methods: * - `createStatusReport` - Create a new status report * - `getStatusReport` - Get a status report by ID * - `listStatusReports` - List all status reports * - `updateStatusReport` - Update a status report * - `deleteStatusReport` - Delete a status report * - `addStatusReportUpdate` - Add an update to a status report */ StatusReportService: Client<typeof StatusReportService>; }; }; /** * Status page service namespace (v1). */ statusPage: { v1: { /** * StatusPageService provides CRUD and management operations for status pages. * * Methods: * - `createStatusPage` - Create a new status page * - `getStatusPage` - Get a status page by ID * - `listStatusPages` - List all status pages * - `updateStatusPage` - Update a status page * - `deleteStatusPage` - Delete a status page * - `addMonitorComponent` - Add a monitor-based component * - `addStaticComponent` - Add a static component * - `removeComponent` - Remove a component * - `updateComponent` - Update a component * - `getPageComponent` - Get a single component by ID * - `createComponentGroup` - Create a component group * - `deleteComponentGroup` - Delete a component group * - `updateComponentGroup` - Update a component group * - `subscribeToPage` - Subscribe an email to a status page (double opt-in) * - `createPageSubscription` - Add a vendor-managed subscriber (email or webhook, no verification) * - `unsubscribeFromPage` - Unsubscribe from a status page * - `listSubscribers` - List all subscribers * - `getStatusPageContent` - Get full status page content * - `getOverallStatus` - Get aggregated status * - `getStatusPageOverview` - Get page, config, components, reports and statuses in one call * - `getPageComponentDailySummary` - Get per-component daily status buckets (status bars) */ StatusPageService: Client<typeof StatusPageService>; }; }; /** * Maintenance service namespace (v1). */ maintenance: { v1: { /** * MaintenanceService provides CRUD operations for maintenance windows. * * Methods: * - `createMaintenance` - Create a new maintenance window * - `getMaintenance` - Get a maintenance window by ID * - `listMaintenances` - List all maintenance windows * - `updateMaintenance` - Update a maintenance window * - `deleteMaintenance` - Delete a maintenance window */ MaintenanceService: Client<typeof MaintenanceService>; }; }; /** * Notification service namespace (v1). */ notification: { v1: { /** * NotificationService provides CRUD operations for notification channels. * * Methods: * - `createNotification` - Create a new notification channel * - `getNotification` - Get a notification channel by ID * - `listNotifications` - List all notification channels * - `updateNotification` - Update a notification channel * - `deleteNotification` - Delete a notification channel * - `sendTestNotification` - Send a test notification * - `checkNotificationLimit` - Check notification limits */ NotificationService: Client<typeof NotificationService>; }; }; /** * Private location service namespace (v1). */ privateLocation: { v1: { /** * PrivateLocationService provides CRUD operations for private locations — * self-hosted checker agents that run monitors from your own network. * * Methods: * - `createPrivateLocation` - Create a private location and get its agent token * - `getPrivateLocation` - Get a private location by ID (includes the agent token) * - `listPrivateLocations` - List private location summaries (no tokens) * - `updatePrivateLocation` - Update a private location * - `deletePrivateLocation` - Delete a private location */ PrivateLocationService: Client<typeof PrivateLocationService>; }; };}
/** * Creates a configured OpenStatus client with optional API key authentication. * * Use this factory function to create a client that automatically includes * your API key in all requests, eliminating the need to pass headers manually. * * @example * ```typescript * import { createOpenStatusClient, Periodicity, Region } from "@openstatus/sdk-node"; * * // Create a configured client * const client = createOpenStatusClient({ * apiKey: process.env.OPENSTATUS_API_KEY, * }); * * // No need to pass headers on each call * const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({}); * * 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], * active: true, * }, * }); * ``` */export function createOpenStatusClient( options?: OpenStatusClientOptions,): OpenStatusClient { const transport = createOpenStatusTransport(options);
return { monitor: { v1: { MonitorService: createClient(MonitorService, transport), }, }, health: { v1: { HealthService: createClient(HealthService, transport), }, }, statusReport: { v1: { StatusReportService: createClient(StatusReportService, transport), }, }, statusPage: { v1: { StatusPageService: createClient(StatusPageService, transport), }, }, maintenance: { v1: { MaintenanceService: createClient(MaintenanceService, transport), }, }, notification: { v1: { NotificationService: createClient(NotificationService, transport), }, }, privateLocation: { v1: { PrivateLocationService: createClient(PrivateLocationService, transport), }, }, };}
/** * Default OpenStatus SDK client (without pre-configured authentication). * * For authenticated requests, either: * 1. Use `createOpenStatusClient({ apiKey })` to create a pre-configured client (recommended) * 2. Pass headers manually on each call * * @example Using createOpenStatusClient (recommended) * ```typescript * import { createOpenStatusClient, Periodicity } from "@openstatus/sdk-node"; * * const client = createOpenStatusClient({ apiKey: process.env.OPENSTATUS_API_KEY }); * const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({ * monitor: { name: "My Website", url: "https://example.com", periodicity: Periodicity.PERIODICITY_1M, active: true }, * }); * ``` * * @example Using default client with manual headers * ```typescript * import { openstatus, Periodicity } from "@openstatus/sdk-node"; * * const headers = { "x-openstatus-key": `${process.env.OPENSTATUS_API_KEY}` }; * const { monitor } = await openstatus.monitor.v1.MonitorService.createHTTPMonitor({ * monitor: { name: "My Website", url: "https://example.com", periodicity: Periodicity.PERIODICITY_1M, active: true }, * }, { headers }); * ``` */export const openstatus: OpenStatusClient = createOpenStatusClient();