Support unknown and degraded status

server/private/lib/alerts/events/healthCheckEvents.ts

@@ -25,7 +25,8 @@ import { eq } from "drizzle-orm";
 import {
     fireResourceDegradedAlert,
     fireResourceHealthyAlert,
-    fireResourceUnhealthyAlert
+    fireResourceUnhealthyAlert,
+    fireResourceUnknownAlert
 } from "./resourceEvents";
 
 // ---------------------------------------------------------------------------
@@ -148,6 +149,32 @@ export async function fireHealthCheckUnhealthyAlert(
     }
 }
 
+export async function fireHealthCheckUnknownAlert(
+    orgId: string,
+    healthCheckId: number,
+    healthCheckName?: string | null,
+    healthCheckTargetId?: number | null,
+    extra?: Record<string, unknown>,
+    trx: Transaction | typeof db = db
+): Promise<void> {
+    try {
+        await trx.insert(statusHistory).values({
+            entityType: "health_check",
+            entityId: healthCheckId,
+            orgId: orgId,
+            status: "unknown",
+            timestamp: Math.floor(Date.now() / 1000)
+        });
+
+        await handleResource(orgId, healthCheckTargetId, trx);
+    } catch (err) {
+        logger.error(
+            `fireHealthCheckUnknownAlert: unexpected error for healthCheckId ${healthCheckId}`,
+            err
+        );
+    }
+}
+
 async function handleResource(orgId: string, healthCheckTargetId?: number | null, trx: Transaction | typeof db = db) {
     if (!healthCheckTargetId) {
         return;
@@ -178,10 +205,16 @@ async function handleResource(orgId: string, healthCheckTargetId?: number | null
         .where(eq(targets.resourceId, resource.resourceId));
 
     let health = "healthy";
+    const allUnknown = otherTargets.every((t) => t.hcHealth === "unknown");
     const allHealthy = otherTargets.every((t) => t.hcHealth === "healthy");
     const allUnhealthy = otherTargets.every((t) => t.hcHealth === "unhealthy");
 
-    if (allHealthy) {
+    if (allUnknown) {
+        logger.debug(
+            `Marking resource ${resource.resourceId} as unknown because all health checks are disabled`
+        );
+        health = "unknown";
+    } else if (allHealthy) {
         health = "healthy";
     } else if (allUnhealthy) {
         logger.debug(
@@ -202,7 +235,15 @@ async function handleResource(orgId: string, healthCheckTargetId?: number | null
             .set({ health })
             .where(eq(resources.resourceId, resource.resourceId));
 
-        if (health === "unhealthy") {
+        if (health === "unknown") {
+            await fireResourceUnknownAlert(
+                orgId,
+                resource.resourceId,
+                resource.name,
+                undefined,
+                trx
+            );
+        } else if (health === "unhealthy") {
             await fireResourceUnhealthyAlert(
                 orgId,
                 resource.resourceId,

server/private/lib/alerts/events/resourceEvents.ts

@@ -183,3 +183,49 @@ export async function fireResourceDegradedAlert(
         );
     }
 }
+
+/**
+ * Fire a `resource_unknown` alert for the given resource.
+ *
+ * Call this when all health checks on a resource are disabled so that the
+ * resource status transitions to unknown.
+ *
+ * @param orgId        - Organisation that owns the resource.
+ * @param resourceId   - Numeric primary key of the resource.
+ * @param resourceName - Human-readable name shown in notifications (optional).
+ * @param extra        - Any additional key/value pairs to include in the payload.
+ */
+export async function fireResourceUnknownAlert(
+    orgId: string,
+    resourceId: number,
+    resourceName?: string | null,
+    extra?: Record<string, unknown>,
+    trx: Transaction | typeof db = db
+): Promise<void> {
+    try {
+        await trx.insert(statusHistory).values({
+            entityType: "resource",
+            entityId: resourceId,
+            orgId: orgId,
+            status: "unknown",
+            timestamp: Math.floor(Date.now() / 1000)
+        });
+
+        await processAlerts({
+            eventType: "resource_toggle",
+            orgId,
+            resourceId,
+            data: {
+                resourceId,
+                status: "unknown",
+                ...(resourceName != null ? { resourceName } : {}),
+                ...extra
+            }
+        });
+    } catch (err) {
+        logger.error(
+            `fireResourceUnknownAlert: unexpected error for resourceId ${resourceId}`,
+            err
+        );
+    }
+}

server/private/lib/alerts/types.ts

@@ -0,0 +1,63 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025-2026 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
+// ---------------------------------------------------------------------------
+// Alert event types
+// ---------------------------------------------------------------------------
+
+export type AlertEventType =
+    | "site_online"
+    | "site_offline"
+    | "health_check_healthy"
+    | "health_check_not_healthy";
+
+// ---------------------------------------------------------------------------
+// Webhook authentication config (stored as encrypted JSON in the DB)
+// ---------------------------------------------------------------------------
+
+export type WebhookAuthType = "none" | "bearer" | "basic" | "custom";
+
+/**
+ * Stored as an encrypted JSON blob in `alertWebhookActions.config`.
+ */
+export interface WebhookAlertConfig {
+    /** Authentication strategy for the webhook endpoint */
+    authType: WebhookAuthType;
+    /** Bearer token – used when authType === "bearer" */
+    bearerToken?: string;
+    /** Basic credentials – "username:password" – used when authType === "basic" */
+    basicCredentials?: string;
+    /** Custom header name – used when authType === "custom" */
+    customHeaderName?: string;
+    /** Custom header value – used when authType === "custom" */
+    customHeaderValue?: string;
+    /** Extra headers to send with every webhook request */
+    headers?: Array<{ key: string; value: string }>;
+    /** HTTP method (default POST) */
+    method?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Internal alert event passed through the processing pipeline
+// ---------------------------------------------------------------------------
+
+export interface AlertContext {
+    eventType: AlertEventType;
+    orgId: string;
+    /** Set for site_online / site_offline events */
+    siteId?: number;
+    /** Set for health_check_* events */
+    healthCheckId?: number;
+    /** Human-readable context data included in emails and webhook payloads */
+    data: Record<string, unknown>;
+}