@checkstack/healthcheck-http-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# @checkstack/healthcheck-http-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/healthcheck-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/healthcheck-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- 81f3f85: ## Breaking: Unified Versioned<T> Architecture
+
+  Refactored the versioning system to use a unified `Versioned<T>` class instead of separate `VersionedSchema`, `VersionedData`, and `VersionedConfig` types.
+
+  ### Breaking Changes
+
+  - **`VersionedSchema<T>`** is replaced by `Versioned<T>` class
+  - **`VersionedData<T>`** is replaced by `VersionedRecord<T>` interface
+  - **`VersionedConfig<T>`** is replaced by `VersionedPluginRecord<T>` interface
+  - **`ConfigMigration<F, T>`** is replaced by `Migration<F, T>` interface
+  - **`MigrationChain<T>`** is removed (use `Migration<unknown, unknown>[]`)
+  - **`migrateVersionedData()`** is removed (use `versioned.parse()`)
+  - **`ConfigMigrationRunner`** is removed (migrations are internal to Versioned)
+
+  ### Migration Guide
+
+  Before:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: {
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    },
+  };
+  const data = await migrateVersionedData(stored, 1, migrations);
+  ```
+
+  After:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: new Versioned({
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    }),
+  };
+  const data = await strategy.config.parse(stored);
+  ```
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [0babb9c]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/healthcheck-common@0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/healthcheck-http-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*",
+    "jsonpath-plus": "^10.3.0",
+    "@checkstack/common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "drizzle-kit": "^0.31.8",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { HttpHealthCheckStrategy } from "./strategy";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ healthCheckRegistry, logger }) => {
+        logger.debug("🔌 Registering HTTP Health Check Strategy...");
+        const strategy = new HttpHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the HTTP Health Check backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-http",
+});

package/src/strategy.test.ts

@@ -0,0 +1,398 @@
+import { describe, expect, it, spyOn, afterEach } from "bun:test";
+import { HttpHealthCheckStrategy, HttpHealthCheckConfig } from "./strategy";
+
+describe("HttpHealthCheckStrategy", () => {
+  const strategy = new HttpHealthCheckStrategy();
+  const defaultConfig: HttpHealthCheckConfig = {
+    url: "https://example.com/api",
+    method: "GET",
+    timeout: 5000,
+  };
+
+  afterEach(() => {
+    spyOn(globalThis, "fetch").mockRestore();
+  });
+
+  describe("basic execution", () => {
+    it("should return healthy for successful response without assertions", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 200 })
+      );
+      const result = await strategy.execute(defaultConfig);
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.statusCode).toBe(200);
+    });
+
+    it("should return healthy for any status without status assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 404 })
+      );
+      const result = await strategy.execute(defaultConfig);
+      // Without assertions, any response is "healthy" if reachable
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.statusCode).toBe(404);
+    });
+  });
+
+  describe("statusCode assertions", () => {
+    it("should pass statusCode equals assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 200 })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [{ field: "statusCode", operator: "equals", value: 200 }],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail statusCode equals assertion when mismatch", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 404 })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [{ field: "statusCode", operator: "equals", value: 200 }],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("statusCode");
+    });
+
+    it("should pass statusCode lessThan assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 201 })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [{ field: "statusCode", operator: "lessThan", value: 300 }],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+  });
+
+  describe("responseTime assertions", () => {
+    it("should pass responseTime assertion when fast", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 200 })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "responseTime", operator: "lessThan", value: 10000 },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+  });
+
+  describe("contentType assertions", () => {
+    it("should pass contentType contains assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({}), {
+          status: 200,
+          headers: { "Content-Type": "application/json; charset=utf-8" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "contentType", operator: "contains", value: "json" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+  });
+
+  describe("header assertions", () => {
+    it("should pass header exists assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, {
+          status: 200,
+          headers: { "X-Request-Id": "abc123" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "header", headerName: "X-Request-Id", operator: "exists" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail header exists assertion when missing", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 200 })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "header", headerName: "X-Missing", operator: "exists" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("X-Missing");
+    });
+
+    it("should pass header equals assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, {
+          status: 200,
+          headers: { "Cache-Control": "no-cache" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          {
+            field: "header",
+            headerName: "Cache-Control",
+            operator: "equals",
+            value: "no-cache",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+  });
+
+  describe("jsonPath assertions", () => {
+    it("should pass jsonPath equals assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ status: "UP" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          {
+            field: "jsonPath",
+            path: "$.status",
+            operator: "equals",
+            value: "UP",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail jsonPath equals assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ status: "DOWN" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          {
+            field: "jsonPath",
+            path: "$.status",
+            operator: "equals",
+            value: "UP",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Actual");
+    });
+
+    it("should pass jsonPath exists assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ version: "1.0.0" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "jsonPath", path: "$.version", operator: "exists" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail jsonPath exists assertion when path not found", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ other: "data" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "jsonPath", path: "$.missing", operator: "exists" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("unhealthy");
+    });
+
+    it("should pass jsonPath contains assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ message: "Hello World" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          {
+            field: "jsonPath",
+            path: "$.message",
+            operator: "contains",
+            value: "Hello",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should pass jsonPath matches (regex) assertion", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ id: "abc-123" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          {
+            field: "jsonPath",
+            path: "$.id",
+            operator: "matches",
+            value: "^[a-z]{3}-\\d{3}$",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail when response is not JSON but jsonPath assertions exist", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response("Not JSON", {
+          status: 200,
+          headers: { "Content-Type": "text/plain" },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [{ field: "jsonPath", path: "$.id", operator: "exists" }],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("not valid JSON");
+    });
+  });
+
+  describe("combined assertions", () => {
+    it("should pass multiple assertion types", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ healthy: true }), {
+          status: 200,
+          headers: {
+            "Content-Type": "application/json",
+            "X-Request-Id": "test-123",
+          },
+        })
+      );
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        assertions: [
+          { field: "statusCode", operator: "equals", value: 200 },
+          { field: "responseTime", operator: "lessThan", value: 10000 },
+          { field: "contentType", operator: "contains", value: "json" },
+          { field: "header", headerName: "X-Request-Id", operator: "exists" },
+          {
+            field: "jsonPath",
+            path: "$.healthy",
+            operator: "equals",
+            value: "true",
+          },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+      expect(result.message).toContain("5 assertion");
+    });
+  });
+
+  describe("custom request options", () => {
+    it("should send custom headers with request", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+      spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response(null, { status: 200 });
+      }) as unknown as typeof fetch);
+
+      const config: HttpHealthCheckConfig = {
+        ...defaultConfig,
+        headers: [
+          { name: "Authorization", value: "Bearer my-token" },
+          { name: "X-Custom-Header", value: "custom-value" },
+        ],
+      };
+
+      const result = await strategy.execute(config);
+      expect(result.status).toBe("healthy");
+      expect(capturedHeaders).toBeDefined();
+      expect(capturedHeaders?.["Authorization"]).toBe("Bearer my-token");
+      expect(capturedHeaders?.["X-Custom-Header"]).toBe("custom-value");
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,513 @@
+import { JSONPath } from "jsonpath-plus";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  numericField,
+  timeThresholdField,
+  stringField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+/**
+ * Header configuration for custom HTTP headers.
+ */
+export const httpHeaderSchema = z.object({
+  name: z.string().min(1).describe("Header name"),
+  value: z.string().describe("Header value"),
+});
+
+/**
+ * JSONPath assertion for response body validation.
+ * Supports dynamic operators with runtime type coercion.
+ */
+const jsonPathAssertionSchema = z.object({
+  field: z.literal("jsonPath"),
+  path: z
+    .string()
+    .describe("JSONPath expression (e.g. $.status, $.data[0].id)"),
+  operator: z.enum([
+    "equals",
+    "notEquals",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "matches",
+    "exists",
+    "notExists",
+    "lessThan",
+    "lessThanOrEqual",
+    "greaterThan",
+    "greaterThanOrEqual",
+  ]),
+  value: z
+    .string()
+    .optional()
+    .describe("Expected value (not needed for exists/notExists)"),
+});
+
+/**
+ * Response header assertion schema.
+ * Check for specific header values in the response.
+ */
+const headerAssertionSchema = z.object({
+  field: z.literal("header"),
+  headerName: z.string().describe("Response header name to check"),
+  operator: z.enum([
+    "equals",
+    "notEquals",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "exists",
+  ]),
+  value: z.string().optional().describe("Expected header value"),
+});
+
+/**
+ * HTTP health check assertion schema using discriminated union.
+ *
+ * Assertions validate the result of a check:
+ * - statusCode: Validate HTTP status code
+ * - responseTime: Validate response latency
+ * - contentType: Validate Content-Type header
+ * - header: Validate any response header
+ * - jsonPath: Validate JSON response body content
+ */
+const httpAssertionSchema = z.discriminatedUnion("field", [
+  numericField("statusCode", { min: 100, max: 599 }),
+  timeThresholdField("responseTime"),
+  stringField("contentType"),
+  headerAssertionSchema,
+  jsonPathAssertionSchema,
+]);
+
+export type HttpAssertion = z.infer<typeof httpAssertionSchema>;
+
+/**
+ * HTTP health check configuration schema.
+ *
+ * Config defines HOW to run the check (connection details, request setup).
+ * Assertions define WHAT to validate in the result.
+ */
+export const httpHealthCheckConfigSchema = z.object({
+  url: z.string().url().describe("The full URL of the endpoint to check."),
+  method: z
+    .enum(["GET", "POST", "PUT", "DELETE", "HEAD"])
+    .default("GET")
+    .describe("The HTTP method to use for the request."),
+  headers: z
+    .array(httpHeaderSchema)
+    .optional()
+    .describe("Custom HTTP headers to send with the request."),
+  timeout: z
+    .number()
+    .min(100)
+    .default(5000)
+    .describe("Maximum time in milliseconds to wait for a response."),
+  body: z
+    .string()
+    .optional()
+    .describe(
+      "Optional request payload body (e.g. JSON for POST requests). [textarea]"
+    ),
+  assertions: z
+    .array(httpAssertionSchema)
+    .optional()
+    .describe("Validation conditions for the response."),
+});
+
+export type HttpHealthCheckConfig = z.infer<typeof httpHealthCheckConfigSchema>;
+
+/** Per-run result metadata */
+const httpResultMetadataSchema = z.object({
+  statusCode: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Status Code",
+  }).optional(),
+  contentType: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Content Type",
+  }).optional(),
+  failedAssertion: httpAssertionSchema.optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+export type HttpResultMetadata = z.infer<typeof httpResultMetadataSchema>;
+
+/** Aggregated metadata for buckets */
+const httpAggregatedMetadataSchema = z.object({
+  statusCodeCounts: z.record(z.string(), z.number()).meta({
+    "x-chart-type": "bar",
+    "x-chart-label": "Status Code Distribution",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+export type HttpAggregatedMetadata = z.infer<
+  typeof httpAggregatedMetadataSchema
+>;
+
+export class HttpHealthCheckStrategy
+  implements
+    HealthCheckStrategy<
+      HttpHealthCheckConfig,
+      HttpResultMetadata,
+      HttpAggregatedMetadata
+    >
+{
+  id = "http";
+  displayName = "HTTP/HTTPS Health Check";
+  description = "HTTP endpoint health monitoring with flexible assertions";
+
+  config: Versioned<HttpHealthCheckConfig> = new Versioned({
+    version: 2, // Bumped for breaking change
+    schema: httpHealthCheckConfigSchema,
+  });
+
+  result: Versioned<HttpResultMetadata> = new Versioned({
+    version: 2,
+    schema: httpResultMetadataSchema,
+  });
+
+  aggregatedResult: Versioned<HttpAggregatedMetadata> = new Versioned({
+    version: 1,
+    schema: httpAggregatedMetadataSchema,
+  });
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<HttpResultMetadata>[]
+  ): HttpAggregatedMetadata {
+    const statusCodeCounts: Record<string, number> = {};
+    let errorCount = 0;
+
+    for (const run of runs) {
+      if (run.metadata?.error) {
+        errorCount++;
+      }
+
+      if (run.metadata?.statusCode !== undefined) {
+        const key = String(run.metadata.statusCode);
+        statusCodeCounts[key] = (statusCodeCounts[key] || 0) + 1;
+      }
+    }
+
+    return { statusCodeCounts, errorCount };
+  }
+
+  async execute(
+    config: HttpHealthCheckConfig
+  ): Promise<HealthCheckResult<HttpResultMetadata>> {
+    // Validate and apply defaults from schema
+    const validatedConfig = this.config.validate(config);
+
+    const start = performance.now();
+    try {
+      // Convert headers array to Record for fetch API
+      const headersRecord: Record<string, string> = {};
+      if (validatedConfig.headers) {
+        for (const header of validatedConfig.headers) {
+          headersRecord[header.name] = header.value;
+        }
+      }
+
+      const response = await fetch(validatedConfig.url, {
+        method: validatedConfig.method,
+        headers: headersRecord,
+        body: validatedConfig.body,
+        signal: AbortSignal.timeout(validatedConfig.timeout),
+      });
+      const end = performance.now();
+      const latencyMs = Math.round(end - start);
+
+      // Collect response data for assertions
+      const statusCode = response.status;
+      const contentType = response.headers.get("content-type") || "";
+
+      // Collect response headers for header assertions
+      // Note: We get headers directly in the assertion loop, not pre-collected
+
+      // Build values object for standard assertions
+      const assertionValues: Record<string, unknown> = {
+        statusCode,
+        responseTime: latencyMs,
+        contentType,
+      };
+
+      // Separate assertions by type
+      const standardAssertions: Array<{
+        field: string;
+        operator: string;
+        value?: unknown;
+      }> = [];
+      const headerAssertions: Array<z.infer<typeof headerAssertionSchema>> = [];
+      const jsonPathAssertions: Array<z.infer<typeof jsonPathAssertionSchema>> =
+        [];
+
+      for (const assertion of validatedConfig.assertions || []) {
+        if (assertion.field === "header") {
+          headerAssertions.push(
+            assertion as z.infer<typeof headerAssertionSchema>
+          );
+        } else if (assertion.field === "jsonPath") {
+          jsonPathAssertions.push(
+            assertion as z.infer<typeof jsonPathAssertionSchema>
+          );
+        } else {
+          standardAssertions.push(assertion);
+        }
+      }
+
+      // Evaluate standard assertions (statusCode, responseTime, contentType)
+      const failedStandard = evaluateAssertions(
+        standardAssertions,
+        assertionValues
+      );
+      if (failedStandard) {
+        return {
+          status: "unhealthy",
+          latencyMs,
+          message: `Assertion failed: ${failedStandard.field} ${
+            failedStandard.operator
+          } ${"value" in failedStandard ? failedStandard.value : ""}`,
+          metadata: {
+            statusCode,
+            contentType,
+            failedAssertion: failedStandard as HttpAssertion,
+          },
+        };
+      }
+
+      // Evaluate header assertions
+      for (const headerAssertion of headerAssertions) {
+        // Get header value directly from the response
+        const headerValue =
+          response.headers.get(headerAssertion.headerName) ?? undefined;
+        const passed = this.evaluateHeaderAssertion(
+          headerAssertion.operator,
+          headerValue,
+          headerAssertion.value
+        );
+
+        if (!passed) {
+          return {
+            status: "unhealthy",
+            latencyMs,
+            message: `Header assertion failed: ${headerAssertion.headerName} ${
+              headerAssertion.operator
+            } ${headerAssertion.value || ""}. Actual: ${
+              headerValue ?? "(missing)"
+            }`,
+            metadata: {
+              statusCode,
+              contentType,
+              failedAssertion: headerAssertion,
+            },
+          };
+        }
+      }
+
+      // Evaluate JSONPath assertions (only if present)
+      if (jsonPathAssertions.length > 0) {
+        let responseData: unknown;
+
+        try {
+          if (contentType.includes("application/json")) {
+            responseData = await response.json();
+          } else {
+            const text = await response.text();
+            try {
+              responseData = JSON.parse(text);
+            } catch {
+              return {
+                status: "unhealthy",
+                latencyMs,
+                message:
+                  "Response is not valid JSON, but JSONPath assertions are configured",
+                metadata: { statusCode, contentType },
+              };
+            }
+          }
+        } catch (error_: unknown) {
+          return {
+            status: "unhealthy",
+            latencyMs,
+            message: `Failed to parse response body: ${
+              (error_ as Error).message
+            }`,
+            metadata: { statusCode },
+          };
+        }
+
+        const extractPath = (path: string, json: unknown) =>
+          JSONPath({ path, json: json as object, wrap: false });
+
+        for (const jsonPathAssertion of jsonPathAssertions) {
+          const actualValue = extractPath(jsonPathAssertion.path, responseData);
+          const passed = this.evaluateJsonPathAssertion(
+            jsonPathAssertion.operator,
+            actualValue,
+            jsonPathAssertion.value
+          );
+
+          if (!passed) {
+            return {
+              status: "unhealthy",
+              latencyMs,
+              message: `JSONPath assertion failed: [${
+                jsonPathAssertion.path
+              }] ${jsonPathAssertion.operator} ${
+                jsonPathAssertion.value || ""
+              }. Actual: ${JSON.stringify(actualValue)}`,
+              metadata: {
+                statusCode,
+                contentType,
+                failedAssertion: jsonPathAssertion,
+              },
+            };
+          }
+        }
+      }
+
+      const assertionCount = validatedConfig.assertions?.length || 0;
+      return {
+        status: "healthy",
+        latencyMs,
+        message: `HTTP ${statusCode}${
+          assertionCount > 0 ? ` - passed ${assertionCount} assertion(s)` : ""
+        }`,
+        metadata: { statusCode, contentType },
+      };
+    } catch (error: unknown) {
+      const end = performance.now();
+      const isError = error instanceof Error;
+      return {
+        status: "unhealthy",
+        latencyMs: Math.round(end - start),
+        message: isError ? error.message : "Request failed",
+        metadata: { error: isError ? error.name : "UnknownError" },
+      };
+    }
+  }
+
+  private evaluateHeaderAssertion(
+    operator: string,
+    actual: string | undefined,
+    expected = ""
+  ): boolean {
+    if (operator === "exists") return actual !== undefined;
+
+    if (actual === undefined) return false;
+
+    switch (operator) {
+      case "equals": {
+        return actual === expected;
+      }
+      case "notEquals": {
+        return actual !== expected;
+      }
+      case "contains": {
+        return actual.includes(expected);
+      }
+      case "startsWith": {
+        return actual.startsWith(expected);
+      }
+      case "endsWith": {
+        return actual.endsWith(expected);
+      }
+      default: {
+        return false;
+      }
+    }
+  }
+
+  private evaluateJsonPathAssertion(
+    operator: string,
+    actual: unknown,
+    expected: string | undefined
+  ): boolean {
+    // Existence checks
+
+    if (operator === "exists") return actual !== undefined && actual !== null;
+
+    if (operator === "notExists")
+      return actual === undefined || actual === null;
+
+    // Numeric operators
+    if (
+      [
+        "lessThan",
+        "lessThanOrEqual",
+        "greaterThan",
+        "greaterThanOrEqual",
+      ].includes(operator)
+    ) {
+      const numActual = Number(actual);
+      const numExpected = Number(expected);
+      if (Number.isNaN(numActual) || Number.isNaN(numExpected)) return false;
+
+      switch (operator) {
+        case "lessThan": {
+          return numActual < numExpected;
+        }
+        case "lessThanOrEqual": {
+          return numActual <= numExpected;
+        }
+        case "greaterThan": {
+          return numActual > numExpected;
+        }
+        case "greaterThanOrEqual": {
+          return numActual >= numExpected;
+        }
+      }
+    }
+
+    // String operators
+    const strActual = String(actual ?? "");
+    const strExpected = expected || "";
+
+    switch (operator) {
+      case "equals": {
+        return actual === expected || strActual === strExpected;
+      }
+      case "notEquals": {
+        return actual !== expected && strActual !== strExpected;
+      }
+      case "contains": {
+        return strActual.includes(strExpected);
+      }
+      case "startsWith": {
+        return strActual.startsWith(strExpected);
+      }
+      case "endsWith": {
+        return strActual.endsWith(strExpected);
+      }
+      case "matches": {
+        try {
+          return new RegExp(strExpected).test(strActual);
+        } catch {
+          return false;
+        }
+      }
+      default: {
+        return false;
+      }
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}