Merge 5b5b96943c into a5670e51cb

types/config.ts

@@ -1,23 +1,41 @@
 import type { Env } from '../worker/src'
 
 export type PageConfig = {
+  /** Title for your status page */
   title?: string
+  /** Links shown at the header of your status page, could set `highlight` to `true` */
   links?: PageConfigLink[]
+  /** Group your monitors; if specified, monitors will be grouped and ordered, not-listed monitors will be invisible (but still monitored) */
   group?: PageConfigGroup
+  /** Path to your favicon, defaults to '/favicon.png' if not specified */
   favicon?: string
+  /** Path to your logo, defaults to '/logo.svg' if not specified */
   logo?: string
+  /** Maintenance related settings */
   maintenances?: {
+    /** The color of upcoming maintenance alerts, default to 'gray'; active alerts use the color specified in the maintenance config */
     upcomingColor?: string
   }
+  /** Custom footer html */
   customFooter?: string
 }
 
+/**
+ * During maintenance, an alert will be shown at status page
+ * Also, related downtime notifications will be skipped (if any)
+ */
 export type MaintenanceConfig = {
+  /** Monitor IDs to be affected by this maintenance */
   monitors?: string[]
+  /** Defaults to "Scheduled Maintenance" if not specified */
   title?: string
+  /** Description of the maintenance, shown at status page */
   body: string
+  /** Start time of the maintenance, in UNIX timestamp or ISO 8601 format */
   start: number | string
+  /** End time of the maintenance, in UNIX timestamp or ISO 8601 format; if not specified, considered on-going */
   end?: number | string
+  /** Color of the maintenance alert at status page, default to "yellow" */
   color?: string
 }
 
@@ -30,51 +48,100 @@ export type PageConfigLink = {
 }
 
 export type MonitorTarget = {
+  /** `id` should be unique, history will be kept if the `id` remains constant */
   id: string
+  /** `name` is used at status page and callback message */
   name: string
+  /** `method` should be a valid HTTP Method */
   method: string
+  /** `target` is a valid URL */
   target: string
+  /** `tooltip` is ONLY used at status page to show a tooltip */
   tooltip?: string
+  /** `statusPageLink` is ONLY used for clickable link at status page */
   statusPageLink?: string
+  /** `hideLatencyChart` will hide status page latency chart if set to true */
   hideLatencyChart?: boolean
+  /** `expectedCodes` is an array of acceptable HTTP response codes, default to 2xx if not specified */
   expectedCodes?: number[]
+  /** `timeout` in millisecond, default to 10000 if not specified */
   timeout?: number
+  /** Headers to be sent */
   headers?: { [key: string]: string | number }
+  /** Body to be sent */
   body?: string
+  /** If specified, the response must contain the keyword to be considered operational */
   responseKeyword?: string
+  /** If specified, the response must NOT contain the keyword to be considered operational */
   responseForbiddenKeyword?: string
+  /** 
+   * if specified, will call the check proxy to check the monitor, mainly for geo-specific checks
+   * refer to docs https://github.com/lyc8503/UptimeFlare/wiki/Check-proxy-setup before setting this value
+   * currently supports `worker://`, `globalping://` and `http(s)://` proxies
+   */
   checkProxy?: string
+  /** If true, the check will fallback to local if the specified proxy is down */
   checkProxyFallback?: boolean
 }
 
 export type WorkerConfig<TEnv = Env> = {
+  /** Write KV at most every N minutes unless the status changed, default to 3 */
   kvWriteCooldownMinutes?: number
+  /** Enable HTTP Basic auth for status page & API by setting to `<USERNAME>:<PASSWORD>` */
   passwordProtection?: string
+  /** Define all your monitors here */
   monitors: MonitorTarget[]
+  /** Notification settings */
   notification?: Notification
+  /** Callback functions for status changes and incidents */
   callbacks?: Callbacks<TEnv>
 }
 
 export type Notification = {
+  /** Notification webhook settings; if not specified, no notification will be sent */
   webhook?: WebhookConfig
+  /** Timezone used in notification messages, default to "Etc/GMT" */
   timeZone?: string
+  /** 
+   * grace period in minutes before sending a notification
+   * notification will be sent only if the monitor is down for N continuous checks after the initial failure
+   * if not specified, notification will be sent immediately
+   */
   gracePeriod?: number
+  /** Disable notification for monitors with specified ids */
   skipNotificationIds?: string[]
+  /** Suppress extra notifications for error reason changes during an incident, default to false */
   skipErrorChangeNotification?: boolean
 }
 
 type SingleWebhook = {
+  /** Webhook URL */
   url: string
+  /** HTTP method; default to 'GET' for payloadType=param, 'POST' otherwise */
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH'
+  /** Headers to be sent */
   headers?: { [key: string]: string | number }
+  /** 
+   * How to encode the payload; one of 'param', 'json' or 'x-www-form-urlencoded'
+   * 'param': append url-encoded payload to URL search parameters
+   * 'json': POST json payload as body, set content-type header to 'application/json'
+   * 'x-www-form-urlencoded': POST url-encoded payload as body, set content-type header to 'x-www-form-urlencoded' */
   payloadType: 'param' | 'json' | 'x-www-form-urlencoded'
+  /** Payload to be sent; $MSG will be replaced with the human-readable notification message */
   payload: any
+  /** Timeout calling this webhook, in millisecond, default to 5000 */
   timeout?: number
 }
 
 export type WebhookConfig = SingleWebhook | SingleWebhook[]
 
 export type Callbacks<TEnv = Env> = {
+  /**
+   * This callback will be called when there's a status change for any monitor
+   * Write any TypeScript code here
+   * This will not follow the grace period settings and will be called immediately when the status changes
+   * You need to handle the grace period manually if you want to implement it
+   */
   onStatusChange?: (
     env: TEnv,
     monitor: MonitorTarget,
@@ -83,6 +150,10 @@ export type Callbacks<TEnv = Env> = {
     timeNow: number,
     reason: string
   ) => Promise<any> | any
+  /**
+   * This callback will be called EVERY 1 MINUTE if there's an on-going incident for any monitor
+   * Write any TypeScript code here
+   */
   onIncident?: (
     env: TEnv,
     monitor: MonitorTarget,

uptime.config.full.ts

@@ -11,7 +11,7 @@ const pageConfig: PageConfig = {
   ],
   // [OPTIONAL] Group your monitors
   // If not specified, all monitors will be shown in a single list
-  // If specified, monitors will be grouped and ordered, not-listed monitors will be invisble (but still monitored)
+  // If specified, monitors will be grouped and ordered, not-listed monitors will be invisible (but still monitored)
   group: {
     '🌐 Public (example group name)': ['foo_monitor', 'bar_monitor', 'more monitor ids...'],
     '🔐 Private': ['test_tcp_monitor'],
@@ -148,7 +148,7 @@ const workerConfig: WorkerConfig = {
       timeNow: number,
       reason: string
     ) => {
-      // This callback will be called EVERY 1 MINTUE if there's an on-going incident for any monitor
+      // This callback will be called EVERY 1 MINUTE if there's an on-going incident for any monitor
       // Write any TypeScript code here
     },
   },