@firebreak/vitals 2.2.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Vitals (Node.js)
 
-Structured healthcheck endpoints for Node.js services with shallow and deep response tiers. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js. A configurable depth policy controls whether callers get a lightweight "alive" response or full diagnostic results.
+Structured healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js. Health checks always run — a configurable detail policy controls whether callers see a summary status or full diagnostic results.
 
 ## Install
 
@@ -35,13 +35,13 @@ registry.add('api', httpCheck('https://api.example.com/health'));
 const app = express();
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  resolveDepth: (req) => {
+  resolveDetail: (req) => {
     const token = extractToken({
       queryParams: req.queryParams as Record<string, string>,
       authorizationHeader: req.authorizationHeader as string | null,
     });
-    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
-    return 'shallow';
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'full';
+    return 'summary';
   },
   metadata: {
     build: process.env.BUILD_SHA,
@@ -50,13 +50,13 @@ app.get('/vitals', createHealthcheckMiddleware({
 }));
 ```
 
-Hit `/vitals` without a valid token to get a shallow response:
+Hit `/vitals` without a valid token to get a summary response with real health status:
 
 ```json
-{ "status": "ok", "timestamp": "...", "build": "stg-45d76e5", "buildTimestamp": "2025-02-25T19:41:56Z" }
+{ "status": "healthy", "timestamp": "...", "build": "stg-45d76e5", "buildTimestamp": "2025-02-25T19:41:56Z" }
 ```
 
-When `resolveDepth` returns `'deep'`, the full deep response with check results is returned.
+When `resolveDetail` returns `'full'`, the full response with check results is returned.
 
 ## Quick Start (Next.js)
 
@@ -76,13 +76,13 @@ registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
 
 export const GET = createNextHandler({
   registry,
-  resolveDepth: (req) => {
+  resolveDetail: (req) => {
     const token = extractToken({
       queryParams: req.queryParams as Record<string, string>,
       authorizationHeader: req.authorizationHeader as string | null,
     });
-    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
-    return 'shallow';
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'full';
+    return 'summary';
   },
   metadata: {
     build: process.env.BUILD_SHA,
@@ -221,15 +221,15 @@ import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  resolveDepth: (req) => {     // optional — omit for always-shallow
+  resolveDetail: (req) => {    // optional — omit for always-summary
     const token = extractToken({
       queryParams: req.queryParams as Record<string, string>,
       authorizationHeader: req.authorizationHeader as string | null,
     });
-    if (token && verifyToken(token, 'my-secret-token')) return 'deep';
-    return 'shallow';
+    if (token && verifyToken(token, 'my-secret-token')) return 'full';
+    return 'summary';
   },
-  metadata: {                  // optional — included in shallow & deep responses
+  metadata: {                  // optional — included in summary & full responses
     build: 'stg-45d76e5',
   },
 }));
@@ -242,13 +242,13 @@ import { createNextHandler } from '@firebreak/vitals/next';
 
 export const GET = createNextHandler({
   registry,
-  resolveDepth: (req) => {
+  resolveDetail: (req) => {
     const token = extractToken({
       queryParams: req.queryParams as Record<string, string>,
       authorizationHeader: req.authorizationHeader as string | null,
     });
-    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
-    return 'shallow';
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'full';
+    return 'summary';
   },
   metadata: { build: process.env.BUILD_SHA },
 });
@@ -263,52 +263,52 @@ import { createHealthcheckHandler, extractToken, verifyToken } from '@firebreak/
 
 const handle = createHealthcheckHandler({
   registry,
-  resolveDepth: (req) => {
+  resolveDetail: (req) => {
     const token = extractToken({
       queryParams: req.queryParams as Record<string, string>,
       authorizationHeader: req.authorizationHeader as string | null,
     });
-    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
-    return 'shallow';
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'full';
+    return 'summary';
   },
   metadata: { build: 'stg-45d76e5' },
 });
 
-// resolveDepth returns 'shallow' → shallow response
-const shallow = await handle({});
-// { status: 200, body: { status: 'ok', timestamp: '...', build: 'stg-45d76e5' } }
+// resolveDetail returns 'summary' → summary response (real status, no checks)
+const summary = await handle({});
+// { status: 200, body: { status: 'healthy', timestamp: '...', build: 'stg-45d76e5' } }
 
-// resolveDepth returns 'deep' → deep response
-const deep = await handle({ queryParams: { token: '...' } });
+// resolveDetail returns 'full' → full response with check details
+const full = await handle({ queryParams: { token: '...' } });
 // { status: 200, body: { status: 'healthy', timestamp: '...', build: 'stg-45d76e5', checks: { ... } } }
 ```
 
-### Shallow / Deep Responses
+### Summary / Full Responses
 
-The endpoint serves two tiers from a single route, controlled by the `resolveDepth` option:
+Health checks always run. The `resolveDetail` option controls how much detail is exposed in the response:
 
-| `resolveDepth` returns | Response |
-|------------------------|----------|
-| `'shallow'` (or omitted) | **Shallow** — `200` with `{ status: "ok", timestamp, ...metadata }` |
-| `'deep'` | **Deep** — `200`/`503` with full check results + metadata |
+| `resolveDetail` returns | Response |
+|-------------------------|----------|
+| `'summary'` (or omitted) | **Summary** — real HTTP status with `{ status: "healthy"/"degraded"/"outage", timestamp, ...metadata }` |
+| `'full'` | **Full** — real HTTP status with check results + metadata |
 
-When `resolveDepth` is not provided, the handler always returns a shallow response.
+When `resolveDetail` is not provided, the handler returns a summary response.
 
-The `resolveDepth` function receives the request object (`{ ip, headers, queryParams, authorizationHeader }`) and returns `'deep'` or `'shallow'` (or a promise of either). This lets you implement any depth policy — token-based, IP-based, header-based, or always-deep for internal services:
+The `resolveDetail` function receives the request object (`{ ip, headers, queryParams, authorizationHeader }`) and returns `'full'` or `'summary'` (or a promise of either). This lets you implement any detail policy — token-based, IP-based, header-based, or always-full for internal services:
 
 ```typescript
-// Always deep (internal service behind a private network)
+// Always full (internal service behind a private network)
 createHealthcheckHandler({
   registry,
-  resolveDepth: () => 'deep',
+  resolveDetail: () => 'full',
 });
 ```
 
-The shallow response lets load balancers and uptime monitors confirm the process is alive without needing a secret. The deep response is a superset of shallow — it includes everything shallow returns plus the `checks` object and a real health status.
+Both summary and full responses reflect real health status and return the correct HTTP status code (200 for healthy, 503 for degraded/outage). The summary response lets load balancers and uptime monitors get real health status without exposing internal check details. The full response adds the `checks` object with per-check diagnostics.
 
 ### Metadata
 
-Attach static key-value pairs that appear in both shallow and deep responses:
+Attach static key-value pairs that appear in both summary and full responses:
 
 ```typescript
 createHealthcheckHandler({
@@ -323,9 +323,9 @@ createHealthcheckHandler({
 
 Metadata values can be `string`, `number`, or `boolean`. Keys `status`, `timestamp`, `checks`, and `cachedAt` are reserved -- passing them throws at handler creation time.
 
-#### `shallowMetadata`
+#### `summaryMetadata`
 
-By default, shallow responses include all `metadata` fields. Use `shallowMetadata` to override what appears in shallow responses while keeping `metadata` for deep responses:
+By default, summary responses include all `metadata` fields. Use `summaryMetadata` to override what appears in summary responses while keeping `metadata` for full responses:
 
 ```typescript
 createHealthcheckHandler({
@@ -335,8 +335,8 @@ createHealthcheckHandler({
     buildTimestamp: '2025-02-25T19:41:56Z',
     region: 'us-east-1',
   },
-  // Shallow responses only include status + timestamp (no build info)
-  shallowMetadata: {},
+  // Summary responses only include status + timestamp (no build info)
+  summaryMetadata: {},
 });
 ```
 
@@ -346,16 +346,16 @@ You can also include a subset of fields:
 createHealthcheckHandler({
   registry,
   metadata: { build: 'stg-45d76e5', region: 'us-east-1', version: '1.0.0' },
-  // Shallow responses include only version
-  shallowMetadata: { version: '1.0.0' },
+  // Summary responses include only version
+  summaryMetadata: { version: '1.0.0' },
 });
 ```
 
-When `shallowMetadata` is omitted, shallow responses fall back to using `metadata` (existing behavior).
+When `summaryMetadata` is omitted, summary responses fall back to using `metadata`.
 
 ### Utilities
 
-`extractToken` and `verifyToken` are exported helpers for use inside your `resolveDepth` function.
+`extractToken` and `verifyToken` are exported helpers for use inside your `resolveDetail` function.
 
 ```typescript
 import { verifyToken, extractToken } from '@firebreak/vitals';
@@ -372,18 +372,18 @@ verifyToken('provided-token', 'expected-token'); // boolean
 
 ## Response Format
 
-**Shallow response** (`resolveDepth` returns `'shallow'` or is omitted):
+**Summary response** (`resolveDetail` returns `'summary'` or is omitted):
 
 ```json
 {
-  "status": "ok",
+  "status": "healthy",
   "timestamp": "2025-02-26T12:00:00.000Z",
   "build": "stg-45d76e5",
   "buildTimestamp": "2025-02-25T19:41:56Z"
 }
 ```
 
-**Deep response** (`resolveDepth` returns `'deep'`):
+**Full response** (`resolveDetail` returns `'full'`):
 
 ```json
 {
@@ -406,12 +406,13 @@ verifyToken('provided-token', 'expected-token'); // boolean
 }
 ```
 
-| Condition | HTTP Code | Status |
-|-----------|-----------|--------|
-| Shallow | `200` | `"ok"` |
-| Deep — healthy | `200` | `"healthy"` |
-| Deep — degraded | `503` | `"degraded"` |
-| Deep — outage | `503` | `"outage"` |
+Both summary and full responses return real HTTP status codes:
+
+| Status | HTTP Code |
+|--------|-----------|
+| `"healthy"` | `200` |
+| `"degraded"` | `503` |
+| `"outage"` | `503` |
 
 ## Requirements
 

package/dist/checks/databricks.cjs

@@ -32,11 +32,12 @@ var Status = {
 };
 
 // src/checks/databricks.ts
-function databricksCheck(client) {
+function databricksCheck(clientOrFactory) {
   return async () => {
     let session;
     let op;
     try {
+      const client = typeof clientOrFactory === "function" ? await clientOrFactory() : clientOrFactory;
       session = await client.openSession();
       op = await session.executeStatement("SELECT 1");
       return { status: Status.HEALTHY, message: "" };

package/dist/checks/databricks.d.cts

@@ -14,10 +14,11 @@ interface DatabricksSession {
 interface DatabricksOperation {
     close(): Promise<void>;
 }
+type DatabricksClientOrFactory = DatabricksClient | (() => DatabricksClient | Promise<DatabricksClient>);
 /**
  * Creates a healthcheck function that opens a session on an existing
  * Databricks SQL client, runs `SELECT 1`, and closes the session.
  */
-declare function databricksCheck(client: DatabricksClient): AsyncCheckFn;
+declare function databricksCheck(clientOrFactory: DatabricksClientOrFactory): AsyncCheckFn;
 
-export { AsyncCheckFn, type DatabricksClient, type DatabricksOperation, type DatabricksSession, databricksCheck };
+export { AsyncCheckFn, type DatabricksClient, type DatabricksClientOrFactory, type DatabricksOperation, type DatabricksSession, databricksCheck };

package/dist/checks/databricks.d.ts

@@ -14,10 +14,11 @@ interface DatabricksSession {
 interface DatabricksOperation {
     close(): Promise<void>;
 }
+type DatabricksClientOrFactory = DatabricksClient | (() => DatabricksClient | Promise<DatabricksClient>);
 /**
  * Creates a healthcheck function that opens a session on an existing
  * Databricks SQL client, runs `SELECT 1`, and closes the session.
  */
-declare function databricksCheck(client: DatabricksClient): AsyncCheckFn;
+declare function databricksCheck(clientOrFactory: DatabricksClientOrFactory): AsyncCheckFn;
 
-export { AsyncCheckFn, type DatabricksClient, type DatabricksOperation, type DatabricksSession, databricksCheck };
+export { AsyncCheckFn, type DatabricksClient, type DatabricksClientOrFactory, type DatabricksOperation, type DatabricksSession, databricksCheck };

package/dist/checks/databricks.mjs

@@ -6,11 +6,12 @@ var Status = {
 };
 
 // src/checks/databricks.ts
-function databricksCheck(client) {
+function databricksCheck(clientOrFactory) {
   return async () => {
     let session;
     let op;
     try {
+      const client = typeof clientOrFactory === "function" ? await clientOrFactory() : clientOrFactory;
       session = await client.openSession();
       op = await session.executeStatement("SELECT 1");
       return { status: Status.HEALTHY, message: "" };

package/dist/handler-B1Omp5VP.d.ts

@@ -0,0 +1,21 @@
+import { b as HealthcheckRegistry, H as HealthcheckResponseJson, d as StatusLabel } from './core-Bee03bJm.js';
+
+type ResolveDetailFn = (req: Record<string, unknown>) => 'full' | 'summary' | Promise<'full' | 'summary'>;
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    resolveDetail?: ResolveDetailFn;
+    metadata?: Record<string, string | number | boolean>;
+    summaryMetadata?: Record<string, string | number | boolean>;
+}
+interface SummaryResponseJson {
+    status: StatusLabel;
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | SummaryResponseJson;
+}
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type ResolveDetailFn as R, type SummaryResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };

package/dist/handler-MWB6zBBG.d.cts

@@ -0,0 +1,21 @@
+import { b as HealthcheckRegistry, H as HealthcheckResponseJson, d as StatusLabel } from './core-Bee03bJm.cjs';
+
+type ResolveDetailFn = (req: Record<string, unknown>) => 'full' | 'summary' | Promise<'full' | 'summary'>;
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    resolveDetail?: ResolveDetailFn;
+    metadata?: Record<string, string | number | boolean>;
+    summaryMetadata?: Record<string, string | number | boolean>;
+}
+interface SummaryResponseJson {
+    status: StatusLabel;
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | SummaryResponseJson;
+}
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type ResolveDetailFn as R, type SummaryResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };

package/dist/index.cjs

@@ -207,8 +207,8 @@ function extractToken(options) {
   const { queryParams, authorizationHeader, queryParamName = "token" } = options;
   if (queryParams) {
     const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (raw) return String(raw);
   }
   if (authorizationHeader?.startsWith("Bearer ")) {
     const token = authorizationHeader.slice("Bearer ".length);
@@ -220,8 +220,8 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -229,29 +229,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -262,7 +262,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -274,10 +273,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -436,9 +435,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -455,7 +454,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-Bee03bJm.cjs';
-import { S as ShallowResponseJson } from './handler-C3eTDuSQ.cjs';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-C3eTDuSQ.cjs';
+import { S as SummaryResponseJson } from './handler-MWB6zBBG.cjs';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDetailFn, c as createHealthcheckHandler } from './handler-MWB6zBBG.cjs';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {
@@ -10,9 +10,9 @@ declare function extractToken(options: {
     queryParamName?: string;
 }): string | null;
 
-type HealthcheckBody = HealthcheckResponseJson | ShallowResponseJson | {
+type HealthcheckBody = HealthcheckResponseJson | SummaryResponseJson | {
     error: string;
 };
 declare function renderHealthcheckHtml(body: HealthcheckBody): string;
 
-export { HealthcheckResponseJson, ShallowResponseJson, extractToken, renderHealthcheckHtml, verifyToken };
+export { HealthcheckResponseJson, SummaryResponseJson, extractToken, renderHealthcheckHtml, verifyToken };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.js';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-Bee03bJm.js';
-import { S as ShallowResponseJson } from './handler-DaFJivGK.js';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-DaFJivGK.js';
+import { S as SummaryResponseJson } from './handler-B1Omp5VP.js';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDetailFn, c as createHealthcheckHandler } from './handler-B1Omp5VP.js';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {
@@ -10,9 +10,9 @@ declare function extractToken(options: {
     queryParamName?: string;
 }): string | null;
 
-type HealthcheckBody = HealthcheckResponseJson | ShallowResponseJson | {
+type HealthcheckBody = HealthcheckResponseJson | SummaryResponseJson | {
     error: string;
 };
 declare function renderHealthcheckHtml(body: HealthcheckBody): string;
 
-export { HealthcheckResponseJson, ShallowResponseJson, extractToken, renderHealthcheckHtml, verifyToken };
+export { HealthcheckResponseJson, SummaryResponseJson, extractToken, renderHealthcheckHtml, verifyToken };

package/dist/index.mjs

@@ -171,8 +171,8 @@ function extractToken(options) {
   const { queryParams, authorizationHeader, queryParamName = "token" } = options;
   if (queryParams) {
     const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (raw) return String(raw);
   }
   if (authorizationHeader?.startsWith("Bearer ")) {
     const token = authorizationHeader.slice("Bearer ".length);
@@ -184,8 +184,8 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -193,29 +193,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -226,7 +226,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -238,10 +237,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -400,9 +399,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -419,7 +418,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/dist/integrations/express.cjs

@@ -61,8 +61,8 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -70,29 +70,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -103,7 +103,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -115,10 +114,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -277,9 +276,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -296,7 +295,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/dist/integrations/express.d.cts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-C3eTDuSQ.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-MWB6zBBG.cjs';
 import '../core-Bee03bJm.cjs';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-DaFJivGK.js';
+import { H as HealthcheckHandlerOptions } from '../handler-B1Omp5VP.js';
 import '../core-Bee03bJm.js';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.mjs

@@ -35,8 +35,8 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -44,29 +44,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -77,7 +77,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -89,10 +88,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -251,9 +250,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -270,7 +269,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/dist/integrations/next.cjs

@@ -61,8 +61,8 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -70,29 +70,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -103,7 +103,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -115,10 +114,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -277,9 +276,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -296,7 +295,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/dist/integrations/next.d.cts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-C3eTDuSQ.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-MWB6zBBG.cjs';
 import '../core-Bee03bJm.cjs';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;
@@ -15,7 +15,7 @@ type NextHealthcheckOptions = HealthcheckHandlerOptions;
  *
  * export const GET = createNextHandler({
  *   registry,
- *   resolveDepth: (req) => req.ip === '10.0.0.1' ? 'deep' : 'shallow',
+ *   resolveDetail: (req) => req.ip === '10.0.0.1' ? 'full' : 'summary',
  * });
  * ```
  */

package/dist/integrations/next.d.ts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-DaFJivGK.js';
+import { H as HealthcheckHandlerOptions } from '../handler-B1Omp5VP.js';
 import '../core-Bee03bJm.js';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;
@@ -15,7 +15,7 @@ type NextHealthcheckOptions = HealthcheckHandlerOptions;
  *
  * export const GET = createNextHandler({
  *   registry,
- *   resolveDepth: (req) => req.ip === '10.0.0.1' ? 'deep' : 'shallow',
+ *   resolveDetail: (req) => req.ip === '10.0.0.1' ? 'full' : 'summary',
  * });
  * ```
  */

package/dist/integrations/next.mjs

@@ -35,8 +35,8 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
-  for (const bag of [metadata, shallowMetadata ?? {}]) {
+  const { registry, resolveDetail, metadata = {}, summaryMetadata } = options;
+  for (const bag of [metadata, summaryMetadata ?? {}]) {
     for (const key of Object.keys(bag)) {
       if (RESERVED_METADATA_KEYS.includes(key)) {
         throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
@@ -44,29 +44,29 @@ function createHealthcheckHandler(options) {
     }
   }
   return async (req) => {
-    let depth = "shallow";
-    if (resolveDepth) {
+    let detail = "summary";
+    if (resolveDetail) {
       try {
-        const result = await resolveDepth(req);
-        if (result === "deep" || result === "shallow") {
-          depth = result;
+        const result = await resolveDetail(req);
+        if (result === "full" || result === "summary") {
+          detail = result;
         }
       } catch {
       }
     }
-    if (depth === "deep") {
-      const response = await registry.run();
+    const response = await registry.run();
+    if (detail === "full") {
       return {
         status: httpStatusCode(response.status),
         body: { ...metadata, ...toJson(response) }
       };
     }
     const body = {
-      status: "ok",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...shallowMetadata ?? metadata
+      status: statusToLabel(response.status),
+      timestamp: response.timestamp,
+      ...summaryMetadata ?? metadata
     };
-    return { status: 200, body };
+    return { status: httpStatusCode(response.status), body };
   };
 }
 
@@ -77,7 +77,6 @@ function escapeHtml(str) {
 function statusColor(status) {
   switch (status) {
     case "healthy":
-    case "ok":
       return "#22C55E";
     case "degraded":
       return "#F59E0B";
@@ -89,10 +88,10 @@ function statusColor(status) {
 }
 var DEEP_KNOWN_KEYS = /* @__PURE__ */ new Set(["status", "timestamp", "checks", "cachedAt"]);
 function isDeepResponse(body) {
-  return "checks" in body && "status" in body && body.status !== "ok";
+  return "checks" in body && "status" in body;
 }
-function isShallowResponse(body) {
-  return "status" in body && body.status === "ok";
+function isSummaryResponse(body) {
+  return "status" in body && !("checks" in body) && !("error" in body);
 }
 function isErrorResponse(body) {
   return "error" in body && !("status" in body);
@@ -251,9 +250,9 @@ function renderHealthcheckHtml(body) {
       ">${escapeHtml(body.error)}</div>`
     );
   }
-  if (isShallowResponse(body)) {
-    const color = statusColor("ok");
-    const { status: _, timestamp, ...rest } = body;
+  if (isSummaryResponse(body)) {
+    const color = statusColor(body.status);
+    const { status, timestamp, ...rest } = body;
     const metadataItems = Object.entries(rest).map(
       ([k, v]) => [k, String(v)]
     );
@@ -270,7 +269,7 @@ function renderHealthcheckHtml(body) {
           font-weight: 700;
           color: #E4E4E7;
         ">Healthcheck</span>
-        ${renderStatusBadge("OK", color)}
+        ${renderStatusBadge(status, color)}
       </div>
       ${renderMetadataItems(allItems)}`
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {
@@ -107,6 +107,7 @@
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -130,6 +131,7 @@
     "@types/node": "^22.0.0",
     "@types/pg": "^8.0.0",
     "@types/supertest": "^6.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "express": "^4.21.0",
     "ioredis": "^5.0.0",
     "pg": "^8.13.0",

package/dist/handler-C3eTDuSQ.d.cts

@@ -1,21 +0,0 @@
-import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
-
-type ResolveDepthFn = (req: Record<string, unknown>) => 'deep' | 'shallow' | Promise<'deep' | 'shallow'>;
-interface HealthcheckHandlerOptions {
-    registry: HealthcheckRegistry;
-    resolveDepth?: ResolveDepthFn;
-    metadata?: Record<string, string | number | boolean>;
-    shallowMetadata?: Record<string, string | number | boolean>;
-}
-interface ShallowResponseJson {
-    status: 'ok';
-    timestamp: string;
-    [key: string]: string | number | boolean;
-}
-interface HealthcheckHandlerResult {
-    status: number;
-    body: HealthcheckResponseJson | ShallowResponseJson;
-}
-declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
-
-export { type HealthcheckHandlerOptions as H, type ResolveDepthFn as R, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };

package/dist/handler-DaFJivGK.d.ts

@@ -1,21 +0,0 @@
-import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.js';
-
-type ResolveDepthFn = (req: Record<string, unknown>) => 'deep' | 'shallow' | Promise<'deep' | 'shallow'>;
-interface HealthcheckHandlerOptions {
-    registry: HealthcheckRegistry;
-    resolveDepth?: ResolveDepthFn;
-    metadata?: Record<string, string | number | boolean>;
-    shallowMetadata?: Record<string, string | number | boolean>;
-}
-interface ShallowResponseJson {
-    status: 'ok';
-    timestamp: string;
-    [key: string]: string | number | boolean;
-}
-interface HealthcheckHandlerResult {
-    status: number;
-    body: HealthcheckResponseJson | ShallowResponseJson;
-}
-declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
-
-export { type HealthcheckHandlerOptions as H, type ResolveDepthFn as R, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };