@firebreak/vitals 1.2.3 → 1.3.0

package/dist/index.mjs

@@ -23,7 +23,7 @@ function statusFromString(value) {
   return mapping[value.toLowerCase()] ?? Status.OUTAGE;
 }
 function toJson(response) {
-  return {
+  const json = {
     status: statusToLabel(response.status),
     timestamp: response.timestamp,
     checks: Object.fromEntries(
@@ -33,6 +33,10 @@ function toJson(response) {
       ])
     )
   };
+  if (response.cachedAt !== void 0) {
+    json.cachedAt = response.cachedAt;
+  }
+  return json;
 }
 function httpStatusCode(status) {
   return status === Status.HEALTHY ? 200 : 503;
@@ -43,8 +47,11 @@ import { performance } from "perf_hooks";
 var HealthcheckRegistry = class {
   checks = [];
   defaultTimeout;
+  cacheTtlMs;
+  cache = null;
   constructor(options) {
     this.defaultTimeout = options?.defaultTimeout ?? 5e3;
+    this.cacheTtlMs = options?.cacheTtlMs ?? 0;
   }
   add(name, fn, options) {
     if (this.checks.some((c) => c.name === name)) {
@@ -69,6 +76,27 @@ var HealthcheckRegistry = class {
     };
   }
   async run() {
+    if (this.cacheTtlMs <= 0) {
+      return this.executeChecks();
+    }
+    if (this.cache !== null && Date.now() < this.cache.expiresAt) {
+      return {
+        status: this.cache.status,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        checks: structuredClone(this.cache.checks),
+        cachedAt: this.cache.cachedAt
+      };
+    }
+    const response = await this.executeChecks();
+    this.cache = {
+      checks: structuredClone(response.checks),
+      status: response.status,
+      cachedAt: response.timestamp,
+      expiresAt: Date.now() + this.cacheTtlMs
+    };
+    return response;
+  }
+  async executeChecks() {
     if (this.checks.length === 0) {
       return {
         status: Status.HEALTHY,
@@ -154,10 +182,16 @@ function extractToken(options) {
 }
 
 // src/handler.ts
-var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, queryParamName = "token", metadata = {} } = options;
-  const token = rawToken || null;
+  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
+  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
+  if (deep && isEmptyToken) {
+    throw new Error(
+      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
+    );
+  }
+  const token = rawToken == null || isEmptyToken ? null : rawToken;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -165,6 +199,13 @@ function createHealthcheckHandler(options) {
   }
   return async (req) => {
     if (token === null) {
+      if (deep) {
+        const response2 = await registry.run();
+        return {
+          status: httpStatusCode(response2.status),
+          body: { ...metadata, ...toJson(response2) }
+        };
+      }
       const body = {
         status: "ok",
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -195,12 +236,247 @@ function createHealthcheckHandler(options) {
     };
   };
 }
+
+// src/html.ts
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function statusColor(status) {
+  switch (status) {
+    case "healthy":
+    case "ok":
+      return "#22C55E";
+    case "degraded":
+      return "#F59E0B";
+    case "outage":
+      return "#ED1C24";
+    default:
+      return "#ED1C24";
+  }
+}
+var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
+function isDeepResponse(body) {
+  return "checks" in body && "status" in body && body.status !== "ok";
+}
+function isShallowResponse(body) {
+  return "status" in body && body.status === "ok";
+}
+function isErrorResponse(body) {
+  return "error" in body && !("status" in body);
+}
+function renderStatusBadge(label, color) {
+  return `<span style="
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 4px 12px;
+    border-radius: 9999px;
+    background: ${color}1A;
+    font-family: 'Inter', system-ui, sans-serif;
+    font-size: 12px;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    color: ${color};
+  "><span style="
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: ${color};
+    box-shadow: 0 0 6px ${color}80;
+  "></span>${escapeHtml(label)}</span>`;
+}
+function renderMetadataItems(items) {
+  if (items.length === 0) return "";
+  return `<div style="
+    display: flex;
+    flex-wrap: wrap;
+    gap: 24px;
+    margin-top: 16px;
+  ">${items.map(
+    ([label, value]) => `<div>
+      <div style="
+        font-family: 'Inter', system-ui, sans-serif;
+        font-size: 10px;
+        font-weight: 600;
+        letter-spacing: 0.05em;
+        text-transform: uppercase;
+        color: #A1A1AA;
+        margin-bottom: 4px;
+      ">${escapeHtml(label)}</div>
+      <div style="
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 13px;
+        color: #E4E4E7;
+      ">${escapeHtml(value)}</div>
+    </div>`
+  ).join("")}</div>`;
+}
+function renderCheckRow(name, check) {
+  const color = statusColor(check.status);
+  return `<div style="
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 0;
+    border-top: 1px solid #27272A;
+  ">
+    <span style="
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: ${color};
+      box-shadow: 0 0 6px ${color}80;
+      flex-shrink: 0;
+    "></span>
+    <span style="
+      font-family: 'Inter', system-ui, sans-serif;
+      font-size: 12px;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: ${color};
+      font-weight: 600;
+      min-width: 72px;
+    ">${escapeHtml(check.status)}</span>
+    <span style="
+      font-family: 'Inter', system-ui, sans-serif;
+      font-size: 14px;
+      font-weight: 500;
+      color: #E4E4E7;
+      flex: 1;
+    ">${escapeHtml(name)}</span>
+    <span style="
+      font-family: 'JetBrains Mono', monospace;
+      font-size: 12px;
+      color: #A1A1AA;
+      min-width: 60px;
+      text-align: right;
+    ">${escapeHtml(String(check.latencyMs))}ms</span>
+    <span style="
+      font-family: 'JetBrains Mono', monospace;
+      font-size: 12px;
+      color: #71717A;
+      max-width: 200px;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    ">${escapeHtml(check.message)}</span>
+  </div>`;
+}
+function renderPage(borderColor, content) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Healthcheck</title>
+  <style></style>
+</head>
+<body style="
+  margin: 0;
+  padding: 40px 20px;
+  background: #08080A;
+  min-height: 100vh;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  box-sizing: border-box;
+">
+  <div style="
+    width: 100%;
+    max-width: 560px;
+    background: #18181B;
+    border: 1px solid #27272A;
+    border-left: 3px solid ${borderColor};
+    border-radius: 8px;
+    padding: 24px;
+  ">
+    ${content}
+  </div>
+</body>
+</html>`;
+}
+function renderHealthcheckHtml(body) {
+  if (isErrorResponse(body)) {
+    const color = "#ED1C24";
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge("ERROR", color)}
+      </div>
+      <div style="
+        margin-top: 16px;
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 13px;
+        color: #EF4444;
+      ">${escapeHtml(body.error)}</div>`
+    );
+  }
+  if (isShallowResponse(body)) {
+    const color = statusColor("ok");
+    const { status: _, timestamp, ...rest } = body;
+    const metadataItems = Object.entries(rest).map(
+      ([k, v]) => [k, String(v)]
+    );
+    const allItems = [
+      ["timestamp", timestamp],
+      ...metadataItems
+    ];
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge("OK", color)}
+      </div>
+      ${renderMetadataItems(allItems)}`
+    );
+  }
+  if (isDeepResponse(body)) {
+    const color = statusColor(body.status);
+    const { timestamp, checks } = body;
+    const metadataItems = Object.entries(body).filter(([k]) => !DEEP_KNOWN_KEYS.has(k)).map(([k, v]) => [k, String(v)]);
+    const allItems = [
+      ["timestamp", timestamp],
+      ...metadataItems
+    ];
+    const checkRows = Object.entries(checks).sort(([a], [b]) => a.localeCompare(b)).map(([name, check]) => renderCheckRow(name, check)).join("");
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge(body.status, color)}
+      </div>
+      ${renderMetadataItems(allItems)}
+      <div style="margin-top: 20px;">
+        ${checkRows}
+      </div>`
+    );
+  }
+  return renderPage("#ED1C24", `<pre style="color: #E4E4E7; font-family: 'JetBrains Mono', monospace;">${escapeHtml(JSON.stringify(body, null, 2))}</pre>`);
+}
 export {
   HealthcheckRegistry,
   Status,
   createHealthcheckHandler,
   extractToken,
   httpStatusCode,
+  renderHealthcheckHtml,
   statusFromString,
   statusToLabel,
   syncCheck,

package/dist/integrations/express.cjs

@@ -61,7 +61,7 @@ function statusToLabel(status) {
   return labels[status];
 }
 function toJson(response) {
-  return {
+  const json = {
     status: statusToLabel(response.status),
     timestamp: response.timestamp,
     checks: Object.fromEntries(
@@ -71,16 +71,26 @@ function toJson(response) {
       ])
     )
   };
+  if (response.cachedAt !== void 0) {
+    json.cachedAt = response.cachedAt;
+  }
+  return json;
 }
 function httpStatusCode(status) {
   return status === Status.HEALTHY ? 200 : 503;
 }
 
 // src/handler.ts
-var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, queryParamName = "token", metadata = {} } = options;
-  const token = rawToken || null;
+  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
+  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
+  if (deep && isEmptyToken) {
+    throw new Error(
+      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
+    );
+  }
+  const token = rawToken == null || isEmptyToken ? null : rawToken;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -88,6 +98,13 @@ function createHealthcheckHandler(options) {
   }
   return async (req) => {
     if (token === null) {
+      if (deep) {
+        const response2 = await registry.run();
+        return {
+          status: httpStatusCode(response2.status),
+          body: { ...metadata, ...toJson(response2) }
+        };
+      }
       const body = {
         status: "ok",
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -119,6 +136,240 @@ function createHealthcheckHandler(options) {
   };
 }
 
+// src/html.ts
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function statusColor(status) {
+  switch (status) {
+    case "healthy":
+    case "ok":
+      return "#22C55E";
+    case "degraded":
+      return "#F59E0B";
+    case "outage":
+      return "#ED1C24";
+    default:
+      return "#ED1C24";
+  }
+}
+var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
+function isDeepResponse(body) {
+  return "checks" in body && "status" in body && body.status !== "ok";
+}
+function isShallowResponse(body) {
+  return "status" in body && body.status === "ok";
+}
+function isErrorResponse(body) {
+  return "error" in body && !("status" in body);
+}
+function renderStatusBadge(label, color) {
+  return `<span style="
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 4px 12px;
+    border-radius: 9999px;
+    background: ${color}1A;
+    font-family: 'Inter', system-ui, sans-serif;
+    font-size: 12px;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    color: ${color};
+  "><span style="
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: ${color};
+    box-shadow: 0 0 6px ${color}80;
+  "></span>${escapeHtml(label)}</span>`;
+}
+function renderMetadataItems(items) {
+  if (items.length === 0) return "";
+  return `<div style="
+    display: flex;
+    flex-wrap: wrap;
+    gap: 24px;
+    margin-top: 16px;
+  ">${items.map(
+    ([label, value]) => `<div>
+      <div style="
+        font-family: 'Inter', system-ui, sans-serif;
+        font-size: 10px;
+        font-weight: 600;
+        letter-spacing: 0.05em;
+        text-transform: uppercase;
+        color: #A1A1AA;
+        margin-bottom: 4px;
+      ">${escapeHtml(label)}</div>
+      <div style="
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 13px;
+        color: #E4E4E7;
+      ">${escapeHtml(value)}</div>
+    </div>`
+  ).join("")}</div>`;
+}
+function renderCheckRow(name, check) {
+  const color = statusColor(check.status);
+  return `<div style="
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 0;
+    border-top: 1px solid #27272A;
+  ">
+    <span style="
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: ${color};
+      box-shadow: 0 0 6px ${color}80;
+      flex-shrink: 0;
+    "></span>
+    <span style="
+      font-family: 'Inter', system-ui, sans-serif;
+      font-size: 12px;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: ${color};
+      font-weight: 600;
+      min-width: 72px;
+    ">${escapeHtml(check.status)}</span>
+    <span style="
+      font-family: 'Inter', system-ui, sans-serif;
+      font-size: 14px;
+      font-weight: 500;
+      color: #E4E4E7;
+      flex: 1;
+    ">${escapeHtml(name)}</span>
+    <span style="
+      font-family: 'JetBrains Mono', monospace;
+      font-size: 12px;
+      color: #A1A1AA;
+      min-width: 60px;
+      text-align: right;
+    ">${escapeHtml(String(check.latencyMs))}ms</span>
+    <span style="
+      font-family: 'JetBrains Mono', monospace;
+      font-size: 12px;
+      color: #71717A;
+      max-width: 200px;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    ">${escapeHtml(check.message)}</span>
+  </div>`;
+}
+function renderPage(borderColor, content) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Healthcheck</title>
+  <style></style>
+</head>
+<body style="
+  margin: 0;
+  padding: 40px 20px;
+  background: #08080A;
+  min-height: 100vh;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  box-sizing: border-box;
+">
+  <div style="
+    width: 100%;
+    max-width: 560px;
+    background: #18181B;
+    border: 1px solid #27272A;
+    border-left: 3px solid ${borderColor};
+    border-radius: 8px;
+    padding: 24px;
+  ">
+    ${content}
+  </div>
+</body>
+</html>`;
+}
+function renderHealthcheckHtml(body) {
+  if (isErrorResponse(body)) {
+    const color = "#ED1C24";
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge("ERROR", color)}
+      </div>
+      <div style="
+        margin-top: 16px;
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 13px;
+        color: #EF4444;
+      ">${escapeHtml(body.error)}</div>`
+    );
+  }
+  if (isShallowResponse(body)) {
+    const color = statusColor("ok");
+    const { status: _, timestamp, ...rest } = body;
+    const metadataItems = Object.entries(rest).map(
+      ([k, v]) => [k, String(v)]
+    );
+    const allItems = [
+      ["timestamp", timestamp],
+      ...metadataItems
+    ];
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge("OK", color)}
+      </div>
+      ${renderMetadataItems(allItems)}`
+    );
+  }
+  if (isDeepResponse(body)) {
+    const color = statusColor(body.status);
+    const { timestamp, checks } = body;
+    const metadataItems = Object.entries(body).filter(([k]) => !DEEP_KNOWN_KEYS.has(k)).map(([k, v]) => [k, String(v)]);
+    const allItems = [
+      ["timestamp", timestamp],
+      ...metadataItems
+    ];
+    const checkRows = Object.entries(checks).sort(([a], [b]) => a.localeCompare(b)).map(([name, check]) => renderCheckRow(name, check)).join("");
+    return renderPage(
+      color,
+      `<div style="display: flex; align-items: center; justify-content: space-between;">
+        <span style="
+          font-family: 'Inter', system-ui, sans-serif;
+          font-size: 18px;
+          font-weight: 700;
+          color: #E4E4E7;
+        ">Healthcheck</span>
+        ${renderStatusBadge(body.status, color)}
+      </div>
+      ${renderMetadataItems(allItems)}
+      <div style="margin-top: 20px;">
+        ${checkRows}
+      </div>`
+    );
+  }
+  return renderPage("#ED1C24", `<pre style="color: #E4E4E7; font-family: 'JetBrains Mono', monospace;">${escapeHtml(JSON.stringify(body, null, 2))}</pre>`);
+}
+
 // src/integrations/express.ts
 function createHealthcheckMiddleware(options) {
   const handle = createHealthcheckHandler(options);
@@ -128,7 +379,12 @@ function createHealthcheckMiddleware(options) {
         queryParams: req.query,
         authorizationHeader: req.headers.authorization ?? null
       });
-      res.status(result.status).json(result.body);
+      const preferred = req.accepts(["json", "html"]);
+      if (preferred === "html") {
+        res.status(result.status).type("html").send(renderHealthcheckHtml(result.body));
+      } else {
+        res.status(result.status).json(result.body);
+      }
     } catch {
       res.status(500).json({ error: "Internal Server Error" });
     }

package/dist/integrations/express.d.cts

@@ -1,6 +1,6 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-Bvf66wzh.cjs';
-import '../core-BJ2Z0rRi.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-COH7lot9.cjs';
+import '../core-Bee03bJm.cjs';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;
 declare function createHealthcheckMiddleware(options: HealthcheckMiddlewareOptions): RequestHandler;

package/dist/integrations/express.d.ts

@@ -1,6 +1,6 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-R2U3ygLo.js';
-import '../core-BJ2Z0rRi.js';
+import { H as HealthcheckHandlerOptions } from '../handler-CVYUad84.js';
+import '../core-Bee03bJm.js';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;
 declare function createHealthcheckMiddleware(options: HealthcheckMiddlewareOptions): RequestHandler;