@checkstack/healthcheck-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @checkstack/healthcheck-common
+
+## 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/common@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 4dd644d: Enable external application (API key) access to management endpoints
+
+  Changed `userType: "user"` to `userType: "authenticated"` for 52 endpoints across 5 packages, allowing external applications (service accounts with API keys) to call these endpoints programmatically while maintaining RBAC permission checks:
+
+  - **incident-common**: createIncident, updateIncident, addUpdate, resolveIncident, deleteIncident
+  - **maintenance-common**: createMaintenance, updateMaintenance, addUpdate, closeMaintenance, deleteMaintenance
+  - **catalog-common**: System CRUD, Group CRUD, addSystemToGroup, removeSystemFromGroup
+  - **healthcheck-common**: Configuration management, system associations, retention config, detailed history
+  - **integration-common**: Subscription management, connection management, event discovery, delivery logs
+
+  This enables automation use cases such as:
+
+  - Creating incidents from external monitoring systems (Prometheus, Grafana)
+  - Scheduling maintenances from CI/CD pipelines
+  - Managing catalog systems from infrastructure-as-code tools
+  - Configuring health checks from deployment scripts
+
+- ae19ff6: Add configurable state thresholds for health check evaluation
+
+  **@checkstack/backend-api:**
+
+  - Added `VersionedData<T>` generic interface as base for all versioned data structures
+  - `VersionedConfig<T>` now extends `VersionedData<T>` and adds `pluginId`
+  - Added `migrateVersionedData()` utility function for running migrations on any `VersionedData` subtype
+
+  **@checkstack/backend:**
+
+  - Refactored `ConfigMigrationRunner` to use the new `migrateVersionedData` utility
+
+  **@checkstack/healthcheck-common:**
+
+  - Added state threshold schemas with two evaluation modes (consecutive, window)
+  - Added `stateThresholds` field to `AssociateHealthCheckSchema`
+  - Added `getSystemHealthStatus` RPC endpoint contract
+
+  **@checkstack/healthcheck-backend:**
+
+  - Added `stateThresholds` column to `system_health_checks` table
+  - Added `state-evaluator.ts` with health status evaluation logic
+  - Added `state-thresholds-migrations.ts` with migration infrastructure
+  - Added `getSystemHealthStatus` RPC handler
+
+  **@checkstack/healthcheck-frontend:**
+
+  - Updated `SystemHealthBadge` to use new backend endpoint
+
+- 0babb9c: Add public health status access and detailed history for admins
+
+  **Permission changes:**
+
+  - Added `healthcheck.status.read` permission with `isPublicDefault: true` for anonymous access
+  - `getSystemHealthStatus`, `getSystemHealthOverview`, and `getHistory` now public
+  - `getHistory` no longer returns `result` field (security)
+
+  **New features:**
+
+  - Added `getDetailedHistory` endpoint with `healthcheck.manage` permission
+  - New `/healthcheck/history` page showing paginated run history with expandable result JSON
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [b55fae6]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/healthcheck-common",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+export * from "./permissions";
+export * from "./schemas";
+export * from "./zod-health-result";
+
+// --- DTOs for API Responses ---
+
+/**
+ * Represents a Health Check Strategy available in the system.
+ */
+export interface HealthCheckStrategyDto {
+  id: string;
+  displayName: string;
+  description?: string;
+  // schema is a JSON schema object derived from the Zod schema
+  configSchema: Record<string, unknown>;
+}
+
+/**
+ * Represents a Health Check Configuration (the check definition/template).
+ * NOTE: This is derived from Zod schema but kept as interface for explicit type documentation.
+ */
+export interface HealthCheckConfiguration {
+  id: string;
+  name: string;
+  strategyId: string;
+  config: Record<string, unknown>;
+  intervalSeconds: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// HealthCheckRun and HealthCheckStatus types are now exported from ./schemas
+
+export * from "./rpc-contract";
+export * from "./plugin-metadata";
+export { healthcheckRoutes } from "./routes";
+
+// =============================================================================
+// REALTIME SIGNALS
+// =============================================================================
+
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+
+/**
+ * Broadcast when a health check run completes.
+ * Frontend components listening to this signal can update live activity feeds.
+ */
+export const HEALTH_CHECK_RUN_COMPLETED = createSignal(
+  "healthcheck.run.completed",
+  z.object({
+    systemId: z.string(),
+    systemName: z.string(),
+    configurationId: z.string(),
+    configurationName: z.string(),
+    status: z.enum(["healthy", "degraded", "unhealthy"]),
+    latencyMs: z.number().optional(),
+  })
+);

package/src/permissions.ts

@@ -0,0 +1,39 @@
+import { createPermission } from "@checkstack/common";
+
+export const permissions = {
+  /**
+   * Status-only permission for viewing health check status.
+   * Enabled by default for anonymous and authenticated users.
+   */
+  healthCheckStatusRead: createPermission(
+    "healthcheck.status",
+    "read",
+    "View Health Check Status",
+    { isAuthenticatedDefault: true, isPublicDefault: true }
+  ),
+  /**
+   * Configuration read permission for viewing health check configurations.
+   * Restricted to users with explicit grant.
+   */
+  healthCheckRead: createPermission(
+    "healthcheck",
+    "read",
+    "Read Health Check Configurations"
+  ),
+  /**
+   * Permission for viewing detailed health check run data including metadata.
+   * Allows access to extended visualizations without full management access.
+   */
+  healthCheckDetailsRead: createPermission(
+    "healthcheck.details",
+    "read",
+    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
+  ),
+  healthCheckManage: createPermission(
+    "healthcheck",
+    "manage",
+    "Full management of Health Check Configurations"
+  ),
+};
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the healthcheck plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck",
+});

package/src/routes.ts

@@ -0,0 +1,10 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the healthcheck plugin.
+ */
+export const healthcheckRoutes = createRoutes("healthcheck", {
+  config: "/config",
+  history: "/history",
+  historyDetail: "/history/:systemId/:configurationId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,347 @@
+import { oc } from "@orpc/contract";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkstack/common";
+import { pluginMetadata } from "./plugin-metadata";
+import { z } from "zod";
+import { permissions } from "./permissions";
+import {
+  HealthCheckStrategyDtoSchema,
+  HealthCheckConfigurationSchema,
+  CreateHealthCheckConfigurationSchema,
+  UpdateHealthCheckConfigurationSchema,
+  AssociateHealthCheckSchema,
+  HealthCheckRunSchema,
+  HealthCheckRunPublicSchema,
+  HealthCheckStatusSchema,
+  StateThresholdsSchema,
+  RetentionConfigSchema,
+  AggregatedBucketBaseSchema,
+  AggregatedBucketSchema,
+} from "./schemas";
+
+// Base builder with full metadata support
+const _base = oc.$meta<ProcedureMetadata>({});
+
+// --- Response Schemas for Evaluated Status ---
+
+const SystemCheckStatusSchema = z.object({
+  configurationId: z.string(),
+  configurationName: z.string(),
+  status: HealthCheckStatusSchema,
+  runsConsidered: z.number(),
+  lastRunAt: z.date().optional(),
+});
+
+const SystemHealthStatusResponseSchema = z.object({
+  status: HealthCheckStatusSchema,
+  evaluatedAt: z.date(),
+  checkStatuses: z.array(SystemCheckStatusSchema),
+});
+
+// Health Check RPC Contract using oRPC's contract-first pattern
+export const healthCheckContract = {
+  // ==========================================================================
+  // STRATEGY MANAGEMENT (userType: "authenticated" with read permission)
+  // ==========================================================================
+
+  getStrategies: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .output(z.array(HealthCheckStrategyDtoSchema)),
+
+  // ==========================================================================
+  // CONFIGURATION MANAGEMENT (userType: "authenticated")
+  // ==========================================================================
+
+  getConfigurations: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .output(z.array(HealthCheckConfigurationSchema)),
+
+  createConfiguration: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(CreateHealthCheckConfigurationSchema)
+    .output(HealthCheckConfigurationSchema),
+
+  updateConfiguration: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(
+      z.object({
+        id: z.string(),
+        body: UpdateHealthCheckConfigurationSchema,
+      })
+    )
+    .output(HealthCheckConfigurationSchema),
+
+  deleteConfiguration: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(z.string())
+    .output(z.void()),
+
+  // ==========================================================================
+  // SYSTEM ASSOCIATION (userType: "authenticated")
+  // ==========================================================================
+
+  getSystemConfigurations: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .input(z.string())
+    .output(z.array(HealthCheckConfigurationSchema)),
+
+  /**
+   * Get system associations with their threshold configurations.
+   * Returns full association data including enabled state and thresholds.
+   */
+  getSystemAssociations: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .input(z.object({ systemId: z.string() }))
+    .output(
+      z.array(
+        z.object({
+          configurationId: z.string(),
+          configurationName: z.string(),
+          enabled: z.boolean(),
+          stateThresholds: StateThresholdsSchema.optional(),
+        })
+      )
+    ),
+
+  associateSystem: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        body: AssociateHealthCheckSchema,
+      })
+    )
+    .output(z.void()),
+
+  disassociateSystem: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        configId: z.string(),
+      })
+    )
+    .output(z.void()),
+
+  // ==========================================================================
+  // RETENTION CONFIGURATION (userType: "authenticated" with manage permission)
+  // ==========================================================================
+
+  getRetentionConfig: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        configurationId: z.string(),
+      })
+    )
+    .output(
+      z.object({
+        retentionConfig: RetentionConfigSchema.nullable(),
+      })
+    ),
+
+  updateRetentionConfig: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckManage.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        configurationId: z.string(),
+        retentionConfig: RetentionConfigSchema.nullable(),
+      })
+    )
+    .output(z.void()),
+
+  // ==========================================================================
+  // HISTORY & STATUS (userType: "user" with read permission)
+  // ==========================================================================
+
+  getHistory: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.healthCheckStatusRead.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string().optional(),
+        configurationId: z.string().optional(),
+        startDate: z.date().optional(),
+        endDate: z.date().optional(),
+        limit: z.number().optional().default(10),
+        offset: z.number().optional().default(0),
+      })
+    )
+    .output(
+      z.object({
+        runs: z.array(HealthCheckRunPublicSchema),
+        total: z.number(),
+      })
+    ),
+
+  /**
+   * Get detailed health check run history with full result data.
+   * Requires permission to view detailed run data including metadata.
+   */
+  getDetailedHistory: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckDetailsRead.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string().optional(),
+        configurationId: z.string().optional(),
+        startDate: z.date().optional(),
+        endDate: z.date().optional(),
+        limit: z.number().optional().default(10),
+        offset: z.number().optional().default(0),
+      })
+    )
+    .output(
+      z.object({
+        runs: z.array(HealthCheckRunSchema),
+        total: z.number(),
+      })
+    ),
+
+  /**
+   * Get aggregated health check history for long-term analysis.
+   * Returns pre-computed buckets with core metrics only (no strategy-specific data).
+   * For strategy-specific aggregated results, use getDetailedAggregatedHistory.
+   */
+  getAggregatedHistory: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.healthCheckStatusRead.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        configurationId: z.string(),
+        startDate: z.date(),
+        endDate: z.date(),
+        bucketSize: z.enum(["hourly", "daily", "auto"]),
+      })
+    )
+    .output(
+      z.object({
+        buckets: z.array(AggregatedBucketBaseSchema),
+      })
+    ),
+
+  /**
+   * Get detailed aggregated health check history including strategy-specific data.
+   * Returns buckets with core metrics AND aggregatedResult from strategy.
+   * Requires healthCheckDetailsRead permission.
+   */
+  getDetailedAggregatedHistory: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.healthCheckDetailsRead.id],
+    })
+    .input(
+      z.object({
+        systemId: z.string(),
+        configurationId: z.string(),
+        startDate: z.date(),
+        endDate: z.date(),
+        bucketSize: z.enum(["hourly", "daily", "auto"]),
+      })
+    )
+    .output(
+      z.object({
+        buckets: z.array(AggregatedBucketSchema),
+      })
+    ),
+
+  /**
+   * Get evaluateted health status for a system based on configured thresholds.
+   * Aggregates all health check statuses for the system.
+   */
+  getSystemHealthStatus: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.healthCheckStatusRead.id],
+    })
+    .input(z.object({ systemId: z.string() }))
+    .output(SystemHealthStatusResponseSchema),
+
+  /**
+   * Get comprehensive health overview for a system.
+   * Returns all health checks with their last 25 runs for sparkline visualization.
+   */
+  getSystemHealthOverview: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.healthCheckStatusRead.id],
+    })
+    .input(z.object({ systemId: z.string() }))
+    .output(
+      z.object({
+        systemId: z.string(),
+        checks: z.array(
+          z.object({
+            configurationId: z.string(),
+            configurationName: z.string(),
+            strategyId: z.string(),
+            intervalSeconds: z.number(),
+            enabled: z.boolean(),
+            status: HealthCheckStatusSchema,
+            stateThresholds: StateThresholdsSchema.optional(),
+            recentRuns: z.array(
+              z.object({
+                id: z.string(),
+                status: HealthCheckStatusSchema,
+                timestamp: z.date(),
+              })
+            ),
+          })
+        ),
+      })
+    ),
+};
+
+// Export contract type
+export type HealthCheckContract = typeof healthCheckContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(HealthCheckApi);
+export const HealthCheckApi = createClientDefinition(
+  healthCheckContract,
+  pluginMetadata
+);

package/src/schemas.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+
+// --- API Request/Response Schemas (Zod) ---
+
+export const HealthCheckStrategyDtoSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string().optional(),
+  configSchema: z.record(z.string(), z.unknown()),
+  /** JSON Schema for per-run result metadata (with chart annotations) */
+  resultSchema: z.record(z.string(), z.unknown()).optional(),
+  /** JSON Schema for aggregated result metadata (with chart annotations) */
+  aggregatedResultSchema: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const HealthCheckConfigurationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  strategyId: z.string(),
+  config: z.record(z.string(), z.unknown()),
+  intervalSeconds: z.number(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+export const CreateHealthCheckConfigurationSchema = z.object({
+  name: z.string().min(1),
+  strategyId: z.string().min(1),
+  config: z.record(z.string(), z.unknown()),
+  intervalSeconds: z.number().min(1),
+});
+
+export type CreateHealthCheckConfiguration = z.infer<
+  typeof CreateHealthCheckConfigurationSchema
+>;
+
+export const UpdateHealthCheckConfigurationSchema =
+  CreateHealthCheckConfigurationSchema.partial();
+
+export type UpdateHealthCheckConfiguration = z.infer<
+  typeof UpdateHealthCheckConfigurationSchema
+>;
+
+/**
+ * Health check status enum - same as database enum.
+ */
+export const HealthCheckStatusSchema = z.enum([
+  "healthy",
+  "unhealthy",
+  "degraded",
+]);
+
+export type HealthCheckStatus = z.infer<typeof HealthCheckStatusSchema>;
+
+// --- State Threshold Schemas ---
+
+/**
+ * Consecutive mode: evaluates based on sequential identical results.
+ * Good for stable systems where transient failures are rare.
+ */
+export const ConsecutiveThresholdsSchema = z.object({
+  mode: z.literal("consecutive"),
+  /** Minimum consecutive successes to transition to healthy */
+  healthy: z.object({
+    minSuccessCount: z.number().int().min(1).default(1),
+  }),
+  /** Minimum consecutive failures to transition to degraded */
+  degraded: z.object({
+    minFailureCount: z.number().int().min(1).default(2),
+  }),
+  /** Minimum consecutive failures to transition to unhealthy */
+  unhealthy: z.object({
+    minFailureCount: z.number().int().min(1).default(5),
+  }),
+});
+
+export type ConsecutiveThresholds = z.infer<typeof ConsecutiveThresholdsSchema>;
+
+/**
+ * Window mode: evaluates based on failure count within a sliding window.
+ * Better for flickering systems where failures are intermittent.
+ */
+export const WindowThresholdsSchema = z.object({
+  mode: z.literal("window"),
+  /** Number of recent runs to evaluate */
+  windowSize: z.number().int().min(3).max(100).default(10),
+  /** Minimum failures in window to transition to degraded */
+  degraded: z.object({
+    minFailureCount: z.number().int().min(1).default(3),
+  }),
+  /** Minimum failures in window to transition to unhealthy */
+  unhealthy: z.object({
+    minFailureCount: z.number().int().min(1).default(7),
+  }),
+});
+
+export type WindowThresholds = z.infer<typeof WindowThresholdsSchema>;
+
+/**
+ * Discriminated union of threshold modes
+ */
+export const StateThresholdsSchema = z.discriminatedUnion("mode", [
+  ConsecutiveThresholdsSchema,
+  WindowThresholdsSchema,
+]);
+
+export type StateThresholds = z.infer<typeof StateThresholdsSchema>;
+
+/**
+ * Default thresholds for backward compatibility
+ */
+export const DEFAULT_STATE_THRESHOLDS: StateThresholds = {
+  mode: "consecutive",
+  healthy: { minSuccessCount: 1 },
+  degraded: { minFailureCount: 2 },
+  unhealthy: { minFailureCount: 5 },
+};
+
+export const AssociateHealthCheckSchema = z.object({
+  configurationId: z.string().uuid(),
+  enabled: z.boolean().default(true),
+  stateThresholds: StateThresholdsSchema.optional(),
+});
+
+export type AssociateHealthCheck = z.infer<typeof AssociateHealthCheckSchema>;
+
+export const GetHealthCheckHistoryQuerySchema = z.object({
+  systemId: z.string().uuid().optional(),
+  configurationId: z.string().uuid().optional(),
+  limit: z.number().optional(),
+});
+
+export const HealthCheckRunSchema = z.object({
+  id: z.string(),
+  configurationId: z.string(),
+  systemId: z.string(),
+  status: HealthCheckStatusSchema,
+  result: z.record(z.string(), z.unknown()),
+  timestamp: z.date(),
+  latencyMs: z.number().optional(),
+});
+
+export type HealthCheckRun = z.infer<typeof HealthCheckRunSchema>;
+
+/**
+ * Schema for the result object stored in HealthCheckRun.result.
+ * Mirrors the HealthCheckResult type from backend-api but is available to frontend.
+ *
+ * Structure:
+ * - status: The health status from the strategy execution
+ * - latencyMs: Execution time in milliseconds
+ * - message: Human-readable status message
+ * - metadata: Strategy-specific fields (e.g., statusCode, contentType for HTTP)
+ */
+export const StoredHealthCheckResultSchema = z.object({
+  status: HealthCheckStatusSchema,
+  latencyMs: z.number().optional(),
+  message: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type StoredHealthCheckResult = z.infer<
+  typeof StoredHealthCheckResultSchema
+>;
+
+/**
+ * Public schema for health check runs without sensitive result data.
+ * Used by public endpoints accessible to anonymous/authenticated users.
+ */
+export const HealthCheckRunPublicSchema = z.object({
+  id: z.string(),
+  configurationId: z.string(),
+  systemId: z.string(),
+  status: HealthCheckStatusSchema,
+  timestamp: z.date(),
+  latencyMs: z.number().optional(),
+});
+
+export type HealthCheckRunPublic = z.infer<typeof HealthCheckRunPublicSchema>;
+
+// --- Retention Configuration ---
+
+/**
+ * Retention configuration for health check data.
+ * Defines how long raw runs and aggregates are kept.
+ */
+export const RetentionConfigSchema = z.object({
+  /** Days to keep raw run data before aggregating (default: 7) */
+  rawRetentionDays: z.number().int().min(1).max(30).default(7),
+  /** Days to keep hourly aggregates before rolling to daily (default: 30) */
+  hourlyRetentionDays: z.number().int().min(7).max(90).default(30),
+  /** Days to keep daily aggregates before deleting (default: 365) */
+  dailyRetentionDays: z.number().int().min(30).max(1095).default(365),
+});
+
+export type RetentionConfig = z.infer<typeof RetentionConfigSchema>;
+
+export const DEFAULT_RETENTION_CONFIG: RetentionConfig = {
+  rawRetentionDays: 7,
+  hourlyRetentionDays: 30,
+  dailyRetentionDays: 365,
+};
+
+// --- Aggregated Bucket Schema ---
+
+/**
+ * Base schema for aggregated health check data buckets.
+ * Contains core metrics only (no strategy-specific data).
+ * Used by getAggregatedHistory endpoint (healthCheckStatusRead permission).
+ */
+export const AggregatedBucketBaseSchema = z.object({
+  bucketStart: z.date(),
+  bucketSize: z.enum(["hourly", "daily"]),
+  runCount: z.number(),
+  healthyCount: z.number(),
+  degradedCount: z.number(),
+  unhealthyCount: z.number(),
+  successRate: z.number(),
+  avgLatencyMs: z.number().optional(),
+  minLatencyMs: z.number().optional(),
+  maxLatencyMs: z.number().optional(),
+  p95LatencyMs: z.number().optional(),
+});
+
+export type AggregatedBucketBase = z.infer<typeof AggregatedBucketBaseSchema>;
+
+/**
+ * Extended schema with strategy-specific aggregated result.
+ * Used by getDetailedAggregatedHistory endpoint (healthCheckDetailsRead permission).
+ */
+export const AggregatedBucketSchema = AggregatedBucketBaseSchema.extend({
+  aggregatedResult: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type AggregatedBucket = z.infer<typeof AggregatedBucketSchema>;

package/src/zod-health-result.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+// ============================================================================
+// HEALTH RESULT REGISTRY - Typed metadata for chart annotations
+// ============================================================================
+
+/**
+ * Chart types for auto-generated health check visualizations.
+ *
+ * Numeric types:
+ * - line: Time series line chart for numeric metrics over time
+ * - bar: Bar chart for distributions (record of string to number)
+ * - counter: Simple count display with trend indicator
+ * - gauge: Percentage gauge for rates/percentages (0-100)
+ *
+ * Non-numeric types:
+ * - boolean: Boolean indicator (success/failure, connected/disconnected)
+ * - text: Text display for string values
+ * - status: Status badge for error/warning states
+ */
+export type ChartType =
+  | "line"
+  | "bar"
+  | "counter"
+  | "gauge"
+  | "boolean"
+  | "text"
+  | "status";
+
+/**
+ * Metadata type for health check result schemas.
+ * Provides autocompletion for `.meta()` calls on result fields.
+ */
+export interface HealthResultMeta {
+  /** The type of chart to render for this field */
+  "x-chart-type"?: ChartType;
+  /** Human-readable label for the chart (defaults to field name) */
+  "x-chart-label"?: string;
+  /** Unit suffix for values (e.g., 'ms', '%', 'req/s') */
+  "x-chart-unit"?: string;
+}
+
+/**
+ * Registry for health result schema metadata.
+ * Used by auto-chart components for visualization inference.
+ */
+export const healthResultRegistry = z.registry<HealthResultMeta>();
+
+// ============================================================================
+// TYPED HEALTH RESULT FACTORIES
+// ============================================================================
+
+/**
+ * Create a health result string field with typed chart metadata.
+ *
+ * @example
+ * ```typescript
+ * import { healthResultString } from "@checkstack/healthcheck-common";
+ *
+ * const resultSchema = z.object({
+ *   role: healthResultString({ "x-chart-type": "text", "x-chart-label": "Role" }),
+ * });
+ * ```
+ */
+export function healthResultString(meta: HealthResultMeta) {
+  const schema = z.string();
+  schema.register(healthResultRegistry, meta);
+  return schema;
+}
+
+/**
+ * Create a health result number field with typed chart metadata.
+ */
+export function healthResultNumber(meta: HealthResultMeta) {
+  const schema = z.number();
+  schema.register(healthResultRegistry, meta);
+  return schema;
+}
+
+/**
+ * Create a health result boolean field with typed chart metadata.
+ */
+export function healthResultBoolean(meta: HealthResultMeta) {
+  const schema = z.boolean();
+  schema.register(healthResultRegistry, meta);
+  return schema;
+}

package/tsconfig.json

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