@checkstack/backend-api 0.0.2

package/src/assertions.ts

@@ -0,0 +1,371 @@
+/* eslint-disable unicorn/no-null */
+import { z } from "zod";
+
+// ============================================================================
+// OPERATOR ENUMS
+// ============================================================================
+
+/**
+ * Operators for numeric comparisons.
+ */
+export const NumericOperators = z.enum([
+  "equals",
+  "notEquals",
+  "lessThan",
+  "lessThanOrEqual",
+  "greaterThan",
+  "greaterThanOrEqual",
+]);
+
+/**
+ * Operators for time thresholds (typically only "less than" makes sense).
+ */
+export const TimeThresholdOperators = z.enum(["lessThan", "lessThanOrEqual"]);
+
+/**
+ * Operators for string matching.
+ */
+export const StringOperators = z.enum([
+  "equals",
+  "notEquals",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "matches",
+  "isEmpty",
+]);
+
+/**
+ * Operators for boolean checks.
+ */
+export const BooleanOperators = z.enum(["isTrue", "isFalse"]);
+
+/**
+ * Universal operators for dynamic/unknown types (JSONPath values).
+ * Works via runtime type coercion.
+ */
+export const DynamicOperators = z.enum([
+  // String operators (always work)
+  "equals",
+  "notEquals",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "matches",
+  // Existence check
+  "exists",
+  "notExists",
+  // Numeric operators (value coerced to number at runtime)
+  "lessThan",
+  "lessThanOrEqual",
+  "greaterThan",
+  "greaterThanOrEqual",
+]);
+
+// ============================================================================
+// SCHEMA FACTORIES
+// ============================================================================
+
+/**
+ * Creates an assertion schema for numeric fields with full comparison operators.
+ */
+export function numericField(
+  name: string,
+  config?: { min?: number; max?: number }
+) {
+  return z.object({
+    field: z.literal(name),
+    operator: NumericOperators,
+    value: z
+      .number()
+      .min(config?.min ?? -Infinity)
+      .max(config?.max ?? Infinity),
+  });
+}
+
+/**
+ * Creates an assertion schema for time threshold fields (latency, query time, etc).
+ * Only supports "less than" operators since higher is typically worse.
+ */
+export function timeThresholdField(name: string) {
+  return z.object({
+    field: z.literal(name),
+    operator: TimeThresholdOperators,
+    value: z.number().min(0).describe("Threshold in milliseconds"),
+  });
+}
+
+/**
+ * Creates an assertion schema for string matching fields.
+ */
+export function stringField(name: string) {
+  return z.object({
+    field: z.literal(name),
+    operator: StringOperators,
+    value: z.string().optional().describe("Pattern (optional for isEmpty)"),
+  });
+}
+
+/**
+ * Creates an assertion schema for boolean fields.
+ * Uses isTrue/isFalse operators to explicitly check expected value.
+ */
+export function booleanField(name: string) {
+  return z.object({
+    field: z.literal(name),
+    operator: BooleanOperators,
+    // No value needed - operator determines expected boolean
+  });
+}
+
+/**
+ * Creates an assertion schema for enum fields (e.g., status codes).
+ */
+export function enumField<T extends string>(
+  name: string,
+  values: readonly T[]
+) {
+  return z.object({
+    field: z.literal(name),
+    operator: z.literal("equals"),
+    value: z.enum(values as [T, ...T[]]),
+  });
+}
+
+/**
+ * Creates an assertion schema for JSONPath fields with dynamic typing.
+ * Type is unknown at config time, so we accept string values and coerce at runtime.
+ */
+export function jsonPathField() {
+  return z.object({
+    path: z
+      .string()
+      .describe("JSONPath expression (e.g. $.status, $.data[0].id)"),
+    operator: DynamicOperators,
+    value: z
+      .string()
+      .optional()
+      .describe("Expected value (not needed for exists/notExists)"),
+  });
+}
+
+// ============================================================================
+// EVALUATION ENGINE
+// ============================================================================
+
+/**
+ * Result of evaluating a single assertion.
+ */
+export interface AssertionResult {
+  passed: boolean;
+  field: string;
+  operator?: string;
+  expected?: unknown;
+  actual?: unknown;
+  message?: string;
+}
+
+/**
+ * Evaluate a single assertion against actual values.
+ */
+export function evaluateAssertion<T extends { field: string }>(
+  assertion: T,
+  values: Record<string, unknown>
+): AssertionResult {
+  const field = assertion.field;
+  const actual = values[field];
+
+  const { operator, value: expected } = assertion as T & {
+    operator: string;
+    value?: unknown;
+  };
+
+  const passed = evaluateOperator(operator, actual, expected);
+
+  return {
+    passed,
+    field,
+    operator,
+    expected,
+    actual,
+    message: passed
+      ? undefined
+      : formatFailureMessage(field, operator, expected, actual),
+  };
+}
+
+/**
+ * Evaluate all assertions, returning the first failure or null if all pass.
+ */
+export function evaluateAssertions<T extends { field: string }>(
+  assertions: T[] | undefined,
+  values: Record<string, unknown>
+): T | null {
+  if (!assertions?.length) return null;
+
+  for (const assertion of assertions) {
+    const result = evaluateAssertion(assertion, values);
+    if (!result.passed) {
+      return assertion;
+    }
+  }
+  return null;
+}
+
+/**
+ * Evaluate JSONPath assertions against a JSON object.
+ * Requires a JSONPath extraction function to be passed in to avoid bundling jsonpath-plus.
+ */
+export function evaluateJsonPathAssertions<
+  T extends { path: string; operator: string; value?: string }
+>(
+  assertions: T[] | undefined,
+  json: unknown,
+  extractPath: (path: string, json: unknown) => unknown
+): T | null {
+  if (!assertions?.length) return null;
+
+  for (const assertion of assertions) {
+    const extractedValue = extractPath(assertion.path, json);
+    const passed = evaluateOperator(
+      assertion.operator,
+      extractedValue,
+      assertion.value
+    );
+
+    if (!passed) return assertion;
+  }
+  return null;
+}
+
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+
+/**
+ * Evaluate an operator against actual and expected values.
+ */
+function evaluateOperator(
+  op: string,
+  actual: unknown,
+  expected: unknown
+): boolean {
+  // Existence checks
+  if (op === "exists") return actual !== undefined && actual !== null;
+  if (op === "notExists") return actual === undefined || actual === null;
+
+  // Boolean operators
+  if (op === "isTrue") return actual === true;
+  if (op === "isFalse") return actual === false;
+
+  // Empty check
+  if (op === "isEmpty") return !actual || String(actual).trim() === "";
+
+  // For numeric operators, try to coerce to numbers
+  if (
+    [
+      "lessThan",
+      "lessThanOrEqual",
+      "greaterThan",
+      "greaterThanOrEqual",
+    ].includes(op)
+  ) {
+    const numActual = Number(actual);
+    const numExpected = Number(expected);
+    if (Number.isNaN(numActual) || Number.isNaN(numExpected)) return false;
+
+    switch (op) {
+      case "lessThan": {
+        return numActual < numExpected;
+      }
+      case "lessThanOrEqual": {
+        return numActual <= numExpected;
+      }
+      case "greaterThan": {
+        return numActual > numExpected;
+      }
+      case "greaterThanOrEqual": {
+        return numActual >= numExpected;
+      }
+    }
+  }
+
+  // String operators (coerce to string)
+  const strActual = String(actual ?? "");
+  const strExpected = String(expected ?? "");
+
+  switch (op) {
+    case "equals": {
+      // Try numeric equality first, then strict equality, then string equality
+      if (typeof actual === "number" && typeof expected === "number") {
+        return actual === expected;
+      }
+      if (actual === expected) return true;
+      return strActual === strExpected;
+    }
+    case "notEquals": {
+      if (actual === expected) return false;
+      return 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;
+    }
+  }
+}
+
+/**
+ * Format a human-readable failure message.
+ */
+function formatFailureMessage(
+  field: string,
+  operator: string,
+  expected: unknown,
+  actual: unknown
+): string {
+  const opLabels: Record<string, string> = {
+    equals: "to equal",
+    notEquals: "not to equal",
+    lessThan: "to be less than",
+    lessThanOrEqual: "to be at most",
+    greaterThan: "to be greater than",
+    greaterThanOrEqual: "to be at least",
+    contains: "to contain",
+    startsWith: "to start with",
+    endsWith: "to end with",
+    matches: "to match pattern",
+    isEmpty: "to be empty",
+    exists: "to exist",
+    notExists: "not to exist",
+    isTrue: "to be true",
+    isFalse: "to be false",
+  };
+
+  const opLabel = opLabels[operator] || operator;
+
+  // For operators without expected values
+  if (
+    ["isEmpty", "exists", "notExists", "isTrue", "isFalse"].includes(operator)
+  ) {
+    return `${field}: expected ${opLabel}, got ${JSON.stringify(actual)}`;
+  }
+
+  return `${field}: expected ${opLabel} ${JSON.stringify(
+    expected
+  )}, got ${JSON.stringify(actual)}`;
+}

package/src/auth-strategy.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { Migration } from "./config-versioning";
+import type { LucideIconName } from "@checkstack/common";
+
+/**
+ * Migration chain for auth strategy configurations.
+ */
+export type AuthStrategyMigrationChain<_T> = Migration<unknown, unknown>[];
+
+/**
+ * Defines an authentication strategy for better-auth integration.
+ * Strategies provide configuration schemas for OAuth providers and other auth methods.
+ */
+export interface AuthStrategy<Config = unknown> {
+  /** Unique identifier for the strategy (e.g., "github", "google") */
+  id: string;
+
+  /** Display name shown in UI */
+  displayName: string;
+
+  /** Optional description of the strategy */
+  description?: string;
+
+  /** Lucide icon name in PascalCase (e.g., 'Github', 'Chrome', 'Mail') */
+  icon?: LucideIconName;
+
+  /** Current version of the configuration schema */
+  configVersion: number;
+
+  /** Zod validation schema for the strategy-specific config */
+  configSchema: z.ZodType<Config>;
+
+  /** Optional migrations for backward compatibility */
+  migrations?: AuthStrategyMigrationChain<Config>;
+
+  /**
+   * Whether this strategy requires manual user registration via a signup form.
+   * - `true` for strategies like credentials where users explicitly register
+   * - `false` for strategies like social providers or LDAP where users are auto-registered on first login
+   */
+  requiresManualRegistration: boolean;
+
+  /**
+   * Markdown instructions shown when admins configure the strategy settings.
+   * Displayed in the StrategyConfigCard before the configuration form.
+   */
+  adminInstructions?: string;
+}
+
+/**
+ * Registry for authentication strategies.
+ * Allows plugins to register custom auth strategies.
+ */
+export interface AuthStrategyRegistry {
+  register(strategy: AuthStrategy<unknown>): void;
+  getStrategy(id: string): AuthStrategy<unknown> | undefined;
+  getStrategies(): AuthStrategy<unknown>[];
+}

package/src/chart-metadata.ts

@@ -0,0 +1,77 @@
+/**
+ * Chart metadata types for auto-generated health check visualizations.
+ *
+ * Use Zod's .meta() to annotate result schema fields with chart information.
+ * The metadata flows through toJSONSchema() and is rendered by auto-chart components.
+ *
+ * Uses x- prefixed keys for consistency with platform patterns (x-secret, x-color, x-hidden).
+ *
+ * @example
+ * ```typescript
+ * const aggregatedSchema = z.object({
+ *   avgResponseTime: z.number().meta({
+ *     "x-chart-type": "line",
+ *     "x-chart-label": "Avg Response Time",
+ *     "x-chart-unit": "ms"
+ *   }),
+ *   statusCodeCounts: z.record(z.string(), z.number()).meta({
+ *     "x-chart-type": "bar",
+ *     "x-chart-label": "Status Codes"
+ *   }),
+ *   connected: z.boolean().meta({
+ *     "x-chart-type": "boolean",
+ *     "x-chart-label": "Connected"
+ *   }),
+ * });
+ * ```
+ */
+
+/**
+ * Available chart types for auto-generated 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
+ *
+ * Note: Fields without chart annotations simply won't render - no "hidden" type needed.
+ */
+export type ChartType =
+  | "line"
+  | "bar"
+  | "counter"
+  | "gauge"
+  | "boolean"
+  | "text"
+  | "status";
+
+/**
+ * Chart metadata to attach to Zod schema fields via .meta().
+ * Uses x- prefixed keys for consistency with platform patterns.
+ */
+export interface ChartMeta {
+  /** 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;
+}
+
+/**
+ * Type guard to check if metadata contains chart information.
+ */
+export function isChartMeta(meta: unknown): meta is ChartMeta {
+  return (
+    typeof meta === "object" &&
+    meta !== null &&
+    "x-chart-type" in meta &&
+    typeof (meta as ChartMeta)["x-chart-type"] === "string"
+  );
+}

package/src/config-service.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import type { Migration } from "./config-versioning";
+
+/**
+ * Service for managing plugin configurations with automatic secret handling.
+ * Each plugin gets its own scoped instance that can only access its own configs.
+ */
+export interface ConfigService {
+  /**
+   * Store a configuration with automatic secret encryption and migration support.
+   *
+   * @param configId - Unique identifier for this config (e.g., "github-strategy", "smtp-settings")
+   * @param schema - Zod schema that defines the config structure and marks secret fields
+   * @param version - Current schema version
+   * @param data - The configuration data to store
+   * @param migrations - Optional migration chain for backward compatibility
+   */
+  set<T>(
+    configId: string,
+    schema: z.ZodType<T>,
+    version: number,
+    data: T,
+    migrations?: Migration<unknown, unknown>[]
+  ): Promise<void>;
+
+  /**
+   * Load a configuration with automatic secret decryption and migration.
+   * Returns undefined if config doesn't exist.
+   *
+   * @param configId - Unique identifier for the config
+   * @param schema - Zod schema for validation and secret detection
+   * @param version - Expected schema version
+   * @param migrations - Optional migration chain
+   */
+  get<T>(
+    configId: string,
+    schema: z.ZodType<T>,
+    version: number,
+    migrations?: Migration<unknown, unknown>[]
+  ): Promise<T | undefined>;
+
+  /**
+   * Load a configuration without decrypting secrets (safe for frontend).
+   * Returns the data with secret fields removed.
+   *
+   * @param configId - Unique identifier for the config
+   * @param schema - Zod schema for secret detection
+   * @param version - Expected schema version
+   * @param migrations - Optional migration chain
+   */
+  getRedacted<T>(
+    configId: string,
+    schema: z.ZodType<T>,
+    version: number,
+    migrations?: Migration<unknown, unknown>[]
+  ): Promise<Partial<T> | undefined>;
+
+  /**
+   * Delete a configuration.
+   *
+   * @param configId - Unique identifier for the config to delete
+   */
+  delete(configId: string): Promise<void>;
+
+  /**
+   * List all config IDs for this plugin.
+   *
+   * @returns Array of config IDs belonging to this plugin
+   */
+  list(): Promise<string[]>;
+}