@checkstack/backend-api 0.6.0 → 0.8.0

package/src/aggregated-result.ts

@@ -0,0 +1,473 @@
+/**
+ * Type-safe aggregated result schema factories.
+ *
+ * These factories create aggregated result fields that automatically pair
+ * display fields with their internal state, enabling proper merging when
+ * combining buckets.
+ */
+
+import { z, type ZodTypeAny } from "zod";
+import type { HealthResultMeta } from "@checkstack/common";
+import { healthResultRegistry } from "@checkstack/healthcheck-common";
+import {
+  mergeAverageStates,
+  mergeRateStates,
+  mergeCounterStates,
+  mergeMinMaxStates,
+  type AverageState,
+  type AverageStateInput,
+  type RateState,
+  type RateStateInput,
+  type CounterState,
+  type CounterStateInput,
+  type MinMaxState,
+  type MinMaxStateInput,
+} from "./incremental-aggregation";
+import { Versioned, type Migration } from "./config-versioning";
+
+// =============================================================================
+// AGGREGATION TYPE ENUM
+// =============================================================================
+
+/**
+ * Types of aggregation supported by the system.
+ * Each type has a corresponding internal state schema and merge function.
+ */
+export type AggregationType = "average" | "rate" | "counter" | "minmax";
+
+// =============================================================================
+// AGGREGATED FIELD TYPES
+// =============================================================================
+
+/** Base metadata for chart annotations (excludes x-jsonpath) */
+type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
+
+/**
+ * Base interface for aggregated field definitions.
+ * TState is the output type (with _type), TStateInput is the input type (without _type).
+ */
+interface AggregatedFieldBase<TState, TStateInput> {
+  type: AggregationType;
+  stateSchema: ZodTypeAny;
+  meta: ChartMeta;
+  mergeStates: (a: TStateInput, b: TStateInput) => TState;
+  getDisplayValue: (state: TStateInput) => number;
+  getInitialState: () => TState;
+}
+
+export interface AggregatedAverageField extends AggregatedFieldBase<AverageState, AverageStateInput> {
+  type: "average";
+}
+
+export interface AggregatedRateField extends AggregatedFieldBase<RateState, RateStateInput> {
+  type: "rate";
+}
+
+export interface AggregatedCounterField extends AggregatedFieldBase<CounterState, CounterStateInput> {
+  type: "counter";
+}
+
+export interface AggregatedMinMaxField extends AggregatedFieldBase<MinMaxState, MinMaxStateInput> {
+  type: "minmax";
+  getMinValue: (state: MinMaxStateInput) => number;
+  getMaxValue: (state: MinMaxStateInput) => number;
+}
+
+export type AggregatedField =
+  | AggregatedAverageField
+  | AggregatedRateField
+  | AggregatedCounterField
+  | AggregatedMinMaxField;
+
+// =============================================================================
+// TYPE INFERENCE UTILITIES
+// =============================================================================
+
+/**
+ * Get the internal state type for a field.
+ */
+type InferFieldState<T extends AggregatedField> =
+  T extends AggregatedAverageField
+    ? AverageState
+    : T extends AggregatedRateField
+      ? RateState
+      : T extends AggregatedCounterField
+        ? CounterState
+        : T extends AggregatedMinMaxField
+          ? MinMaxState
+          : never;
+
+/**
+ * Infer the aggregated result type from field definitions.
+ * Each field key maps directly to its state type.
+ *
+ * @example
+ * ```typescript
+ * const fields = {
+ *   avgResponseTimeMs: aggregatedAverage({...}),
+ *   successRate: aggregatedRate({...}),
+ * };
+ * type Result = InferAggregatedResult<typeof fields>;
+ * // Result = {
+ * //   avgResponseTimeMs: AverageState;
+ * //   successRate: RateState;
+ * // }
+ * ```
+ */
+export type InferAggregatedResult<T extends AggregatedResultShape> = {
+  [K in keyof T]: InferFieldState<T[K]>;
+};
+
+/**
+ * Create an aggregated average field.
+ *
+ * @example
+ * ```typescript
+ * const fields = {
+ *   avgResponseTimeMs: aggregatedAverage({
+ *     "x-chart-type": "line",
+ *     "x-chart-label": "Avg Response Time",
+ *     "x-chart-unit": "ms",
+ *   }),
+ * };
+ * ```
+ */
+export function aggregatedAverage(meta: ChartMeta): AggregatedAverageField {
+  // Create fresh schema instance so each field gets its own chart metadata
+  const stateSchema = z.object({
+    _type: z.literal("average"),
+    _sum: z.number(),
+    _count: z.number(),
+    avg: z.number(),
+  });
+  // Register chart metadata for this field
+  stateSchema.register(healthResultRegistry, meta);
+
+  return {
+    type: "average",
+    stateSchema,
+    meta,
+    mergeStates: mergeAverageStates,
+    getDisplayValue: (state) => state.avg,
+    getInitialState: () => ({
+      _type: "average" as const,
+      _sum: 0,
+      _count: 0,
+      avg: 0,
+    }),
+  };
+}
+
+/**
+ * Create an aggregated rate/percentage field.
+ *
+ * @example
+ * ```typescript
+ * const fields = {
+ *   successRate: aggregatedRate({
+ *     "x-chart-type": "gauge",
+ *     "x-chart-label": "Success Rate",
+ *     "x-chart-unit": "%",
+ *   }),
+ * };
+ * ```
+ */
+export function aggregatedRate(meta: ChartMeta): AggregatedRateField {
+  // Create fresh schema instance so each field gets its own chart metadata
+  const stateSchema = z.object({
+    _type: z.literal("rate"),
+    _success: z.number(),
+    _total: z.number(),
+    rate: z.number(),
+  });
+  // Register chart metadata for this field
+  stateSchema.register(healthResultRegistry, meta);
+
+  return {
+    type: "rate",
+    stateSchema,
+    meta,
+    mergeStates: mergeRateStates,
+    getDisplayValue: (state) => state.rate,
+    getInitialState: () => ({
+      _type: "rate" as const,
+      _success: 0,
+      _total: 0,
+      rate: 0,
+    }),
+  };
+}
+
+/**
+ * Create an aggregated counter field.
+ *
+ * @example
+ * ```typescript
+ * const fields = {
+ *   errorCount: aggregatedCounter({
+ *     "x-chart-type": "counter",
+ *     "x-chart-label": "Errors",
+ *   }),
+ * };
+ * ```
+ */
+export function aggregatedCounter(meta: ChartMeta): AggregatedCounterField {
+  // Create fresh schema instance so each field gets its own chart metadata
+  const stateSchema = z.object({
+    _type: z.literal("counter"),
+    count: z.number(),
+  });
+  // Register chart metadata for this field
+  stateSchema.register(healthResultRegistry, meta);
+
+  return {
+    type: "counter",
+    stateSchema,
+    meta,
+    mergeStates: mergeCounterStates,
+    getDisplayValue: (state) => state.count,
+    getInitialState: () => ({ _type: "counter" as const, count: 0 }),
+  };
+}
+
+/**
+ * Create an aggregated min/max field.
+ *
+ * @example
+ * ```typescript
+ * const fields = {
+ *   latencyRange: aggregatedMinMax({
+ *     "x-chart-type": "line",
+ *     "x-chart-label": "Latency Range",
+ *     "x-chart-unit": "ms",
+ *   }),
+ * };
+ * ```
+ */
+export function aggregatedMinMax(meta: ChartMeta): AggregatedMinMaxField {
+  // Create fresh schema instance so each field gets its own chart metadata
+  const stateSchema = z.object({
+    _type: z.literal("minmax"),
+    min: z.number(),
+    max: z.number(),
+  });
+  // Register chart metadata for this field
+  stateSchema.register(healthResultRegistry, meta);
+
+  return {
+    type: "minmax",
+    stateSchema,
+    meta,
+    mergeStates: mergeMinMaxStates,
+    getDisplayValue: (state) => state.max, // Default to max
+    getMinValue: (state) => state.min,
+    getMaxValue: (state) => state.max,
+    getInitialState: () => ({ _type: "minmax" as const, min: 0, max: 0 }),
+  };
+}
+
+// =============================================================================
+// AGGREGATED RESULT SCHEMA BUILDER
+// =============================================================================
+
+/**
+ * Definition for aggregated result schema.
+ * Maps display field names to their aggregated field configurations.
+ */
+export type AggregatedResultShape = Record<string, AggregatedField>;
+
+/**
+ * Registry to store field definitions for lookup during merge operations.
+ */
+const fieldRegistry = new WeakMap<ZodTypeAny, AggregatedResultShape>();
+
+/**
+ * Build a Zod schema for aggregated results.
+ * Each field key maps directly to its state type.
+ *
+ * @param fields - Map of field names to aggregated field definitions
+ * @returns Object containing schema, fields, and merge function
+ *
+ * @example
+ * ```typescript
+ * const { schema, mergeAggregatedResults } = buildAggregatedResultSchema({
+ *   avgResponseTimeMs: aggregatedAverage({ ... }),
+ *   successRate: aggregatedRate({ ... }),
+ * });
+ * ```
+ */
+export function buildAggregatedResultSchema<T extends AggregatedResultShape>(
+  fields: T,
+): {
+  schema: z.ZodType<InferAggregatedResult<T>>;
+  fields: T;
+  mergeAggregatedResults: (
+    a: InferAggregatedResult<T> | undefined,
+    b: InferAggregatedResult<T>,
+  ) => InferAggregatedResult<T>;
+} {
+  // Build schema shape - each field key maps to its state schema
+  // Schema instances are already registered with chart metadata by the factory functions
+  const shape: Record<string, ZodTypeAny> = {};
+
+  for (const [key, field] of Object.entries(fields)) {
+    shape[key] = field.stateSchema;
+  }
+
+  const schema = z.object(shape);
+
+  // Store field definitions for later lookup
+  fieldRegistry.set(schema, fields);
+
+  // Create merge function
+  const mergeAggregatedResults = (
+    a: Record<string, unknown> | undefined,
+    b: Record<string, unknown>,
+  ): Record<string, unknown> => {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, field] of Object.entries(fields)) {
+      // Get states from both results using the field key
+      const stateA = a?.[key] as Record<string, unknown> | undefined;
+      const stateB = b[key] as Record<string, unknown> | undefined;
+
+      let mergedState: Record<string, unknown>;
+
+      if (stateA && stateB) {
+        // Both exist, merge based on type
+        switch (field.type) {
+          case "average": {
+            mergedState = mergeAverageStates(
+              stateA as AverageState,
+              stateB as AverageState,
+            );
+            break;
+          }
+          case "rate": {
+            mergedState = mergeRateStates(
+              stateA as RateState,
+              stateB as RateState,
+            );
+            break;
+          }
+          case "counter": {
+            mergedState = mergeCounterStates(
+              stateA as CounterState,
+              stateB as CounterState,
+            );
+            break;
+          }
+          case "minmax": {
+            mergedState = mergeMinMaxStates(
+              stateA as MinMaxState,
+              stateB as MinMaxState,
+            );
+            break;
+          }
+        }
+      } else if (stateA) {
+        // Only A exists
+        mergedState = stateA;
+      } else if (stateB) {
+        // Only B exists
+        mergedState = stateB as Record<string, unknown>;
+      } else {
+        // Both missing, use initial state
+        mergedState = field.getInitialState() as Record<string, unknown>;
+      }
+
+      // Store state directly at field key
+      result[key] = mergedState;
+    }
+
+    return result;
+  };
+
+  return {
+    schema: schema as unknown as z.ZodType<InferAggregatedResult<T>>,
+    fields,
+    mergeAggregatedResults: mergeAggregatedResults as (
+      a: InferAggregatedResult<T> | undefined,
+      b: InferAggregatedResult<T>,
+    ) => InferAggregatedResult<T>,
+  };
+}
+
+/**
+ * Get field definitions from a schema.
+ */
+export function getAggregatedFields(
+  schema: ZodTypeAny,
+): AggregatedResultShape | undefined {
+  return fieldRegistry.get(schema);
+}
+
+// =============================================================================
+// VERSIONED AGGREGATED
+// =============================================================================
+
+/**
+ * Options for creating a VersionedAggregated instance.
+ */
+export interface VersionedAggregatedOptions<T extends AggregatedResultShape> {
+  /** Current schema version */
+  version: number;
+  /** Aggregated result field definitions */
+  fields: T;
+  /** Optional migrations for backward compatibility */
+  migrations?: Migration<unknown, unknown>[];
+}
+
+/**
+ * Versioned schema for aggregated results that bundles the merge function.
+ * Use this instead of Versioned for collector aggregatedResult fields.
+ *
+ * @example
+ * ```typescript
+ * const aggregatedResult = new VersionedAggregated({
+ *   version: 1,
+ *   fields: {
+ *     avgResponseTimeMs: aggregatedAverage("_responseTime", {...}),
+ *     successRate: aggregatedRate("_success", {...}),
+ *   },
+ * });
+ * ```
+ */
+export class VersionedAggregated<
+  T extends AggregatedResultShape,
+> extends Versioned<Record<string, unknown>> {
+  readonly fields: T;
+  private readonly _mergeAggregatedStates: (
+    a: Record<string, unknown> | undefined,
+    b: Record<string, unknown>,
+  ) => Record<string, unknown>;
+
+  constructor(options: VersionedAggregatedOptions<T>) {
+    const { schema, mergeAggregatedResults } = buildAggregatedResultSchema(
+      options.fields,
+    );
+
+    super({
+      version: options.version,
+      schema: schema as z.ZodType<Record<string, unknown>>,
+      migrations: options.migrations,
+    });
+
+    this.fields = options.fields;
+    this._mergeAggregatedStates = mergeAggregatedResults as (
+      a: Record<string, unknown> | undefined,
+      b: Record<string, unknown>,
+    ) => Record<string, unknown>;
+  }
+
+  /**
+   * Merge two pre-aggregated states.
+   * Used when combining buckets (e.g., during re-aggregation for chart display).
+   */
+  mergeAggregatedStates(
+    a: Record<string, unknown> | undefined,
+    b: Record<string, unknown>,
+  ): Record<string, unknown> {
+    return this._mergeAggregatedStates(a, b);
+  }
+}

package/src/base-strategy-config.ts

@@ -0,0 +1,26 @@
+import z from "zod";
+import { configNumber } from "./zod-config";
+
+/**
+ * Base configuration schema that all strategy configs should extend.
+ * Provides the required `timeout` field with a sensible default.
+ *
+ * @example
+ * ```typescript
+ * const myConfigSchema = baseStrategyConfigSchema.extend({
+ *   host: z.string().describe("Server hostname"),
+ *   port: z.number().default(22),
+ * });
+ * ```
+ */
+export const baseStrategyConfigSchema = z.object({
+  timeout: configNumber({})
+    .min(100)
+    .default(30_000)
+    .describe("Execution timeout in milliseconds"),
+});
+
+/**
+ * Base config type that all strategy configs must satisfy.
+ */
+export type BaseStrategyConfig = z.infer<typeof baseStrategyConfigSchema>;

package/src/collector-strategy.ts

@@ -2,6 +2,10 @@ import type { PluginMetadata } from "@checkstack/common";
 import type { TransportClient } from "./transport-client";
 import type { Versioned } from "./config-versioning";
 import type { HealthCheckRunForAggregation } from "./health-check";
+import type {
+  VersionedAggregated,
+  AggregatedResultShape,
+} from "./aggregated-result";
 
 /**
  * Result from a collector execution.
@@ -58,8 +62,8 @@ export interface CollectorStrategy<
   /** Per-execution result schema (with x-chart-* metadata) */
   result: Versioned<TResult>;
 
-  /** Aggregated result schema for bucket storage */
-  aggregatedResult: Versioned<TAggregated>;
+  /** Aggregated result schema for bucket storage with merge function */
+  aggregatedResult: VersionedAggregated<AggregatedResultShape>;
 
   /**
    * Execute the collector using the provided transport client.

package/src/health-check.ts

@@ -1,5 +1,10 @@
 import { Versioned } from "./config-versioning";
 import type { TransportClient } from "./transport-client";
+import type {
+  VersionedAggregated,
+  AggregatedResultShape,
+} from "./aggregated-result";
+import type { BaseStrategyConfig } from "./base-strategy-config";
 
 /**
  * Health check result with typed metadata.
@@ -27,7 +32,7 @@ export interface HealthCheckRunForAggregation<
  * Connected transport client with cleanup capability.
  */
 export interface ConnectedClient<
-  TClient extends TransportClient<unknown, unknown>,
+  TClient extends TransportClient<never, unknown>,
 > {
   /** The connected transport client */
   client: TClient;
@@ -42,19 +47,19 @@ export interface ConnectedClient<
  * and returns a transport client. The platform executor handles running
  * collectors and basic health check logic (connectivity test, latency measurement).
  *
- * @template TConfig - Configuration type for this strategy
+ * @template TConfig - Configuration type for this strategy (must include timeout)
  * @template TClient - Transport client type (e.g., SshTransportClient)
  * @template TResult - Per-run result type (for aggregation)
- * @template TAggregatedResult - Aggregated result type for buckets
+ * @template TAggregatedFields - Aggregated field definitions for VersionedAggregated
  */
 export interface HealthCheckStrategy<
-  TConfig = unknown,
-  TClient extends TransportClient<unknown, unknown> = TransportClient<
-    unknown,
+  TConfig extends BaseStrategyConfig = BaseStrategyConfig,
+  TClient extends TransportClient<never, unknown> = TransportClient<
+    never,
     unknown
   >,
-  TResult = Record<string, unknown>,
-  TAggregatedResult = Record<string, unknown>,
+  TResult = unknown,
+  TAggregatedFields extends AggregatedResultShape = AggregatedResultShape,
 > {
   id: string;
   displayName: string;
@@ -66,18 +71,18 @@ export interface HealthCheckStrategy<
   /** Optional result schema with versioning and migrations */
   result?: Versioned<TResult>;
 
-  /** Aggregated result schema for long-term bucket storage */
-  aggregatedResult: Versioned<TAggregatedResult>;
+  /** Aggregated result schema for long-term bucket storage with automatic merging */
+  aggregatedResult: VersionedAggregated<TAggregatedFields>;
 
   /**
    * Create a connected transport client from the configuration.
    * The platform will use this client to execute collectors.
    *
-   * @param config - Validated strategy configuration
+   * @param config - Strategy configuration (use config.validate() to narrow type)
    * @returns Connected client wrapper with close() method
    * @throws Error if connection fails (will be caught by executor)
    */
-  createClient(config: TConfig): Promise<ConnectedClient<TClient>>;
+  createClient(config: unknown): Promise<ConnectedClient<TClient>>;
 
   /**
    * Incrementally merge new run data into an existing aggregate.
@@ -90,50 +95,24 @@ export interface HealthCheckStrategy<
    * @returns Updated aggregated result
    */
   mergeResult(
-    existing: TAggregatedResult | undefined,
+    existing: Record<string, unknown> | undefined,
     newRun: HealthCheckRunForAggregation<TResult>,
-  ): TAggregatedResult;
+  ): Record<string, unknown>;
 }
 
 /**
  * A registered strategy with its owning plugin metadata and qualified ID.
  */
 export interface RegisteredStrategy {
-  strategy: HealthCheckStrategy<
-    unknown,
-    TransportClient<unknown, unknown>,
-    unknown,
-    unknown
-  >;
+  strategy: HealthCheckStrategy;
   ownerPluginId: string;
   qualifiedId: string;
 }
 
 export interface HealthCheckRegistry {
-  register(
-    strategy: HealthCheckStrategy<
-      unknown,
-      TransportClient<unknown, unknown>,
-      unknown,
-      unknown
-    >,
-  ): void;
-  getStrategy(
-    id: string,
-  ):
-    | HealthCheckStrategy<
-        unknown,
-        TransportClient<unknown, unknown>,
-        unknown,
-        unknown
-      >
-    | undefined;
-  getStrategies(): HealthCheckStrategy<
-    unknown,
-    TransportClient<unknown, unknown>,
-    unknown,
-    unknown
-  >[];
+  register<S extends HealthCheckStrategy>(strategy: S): void;
+  getStrategy(id: string): HealthCheckStrategy | undefined;
+  getStrategies(): HealthCheckStrategy[];
   /**
    * Get all registered strategies with their metadata (qualified ID, owner plugin).
    */