@checkstack/backend-api 0.0.2

package/src/config-versioning.ts

@@ -0,0 +1,310 @@
+import { z } from "zod";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Storage Interfaces (simple data shapes for DB/API)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Base interface for versioned data stored in database.
+ * Simple JSON-serializable shape.
+ */
+export interface VersionedRecord<T = unknown> {
+  /** Schema version of this record */
+  version: number;
+  /** The actual data payload */
+  data: T;
+  /** When the last migration was applied (if any) */
+  migratedAt?: Date;
+  /** Original version before any migrations were applied */
+  originalVersion?: number;
+}
+
+/**
+ * Versioned record with plugin context.
+ * Used for plugin-wide configuration storage.
+ */
+export interface VersionedPluginRecord<T = unknown> extends VersionedRecord<T> {
+  /** Plugin ID that owns this configuration */
+  pluginId: string;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Migration Types
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Type-safe migration from one data version to another.
+ * Used for backward-compatible schema evolution.
+ */
+export interface Migration<TFrom = unknown, TTo = unknown> {
+  /** Version number migrating from */
+  fromVersion: number;
+  /** Version number migrating to (must be fromVersion + 1) */
+  toVersion: number;
+  /** Human-readable description of what this migration does */
+  description: string;
+  /** Migration function that transforms old data to new format */
+  migrate(data: TFrom): TTo | Promise<TTo>;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Migration Builder
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Builder for creating type-safe migration chains.
+ * Provides better type inference for each migration step.
+ */
+export class MigrationBuilder<TCurrent> {
+  private migrations: Migration<unknown, unknown>[] = [];
+
+  /**
+   * Add a migration to the chain.
+   * Returns a new builder with updated type for the next migration.
+   */
+  addMigration<TNext>(
+    migration: Migration<TCurrent, TNext>
+  ): MigrationBuilder<TNext> {
+    this.migrations.push(migration);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return this as any as MigrationBuilder<TNext>;
+  }
+
+  /**
+   * Build the final migration chain.
+   */
+  build(): Migration<unknown, unknown>[] {
+    return this.migrations;
+  }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Parse Result Types
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export type ParseSuccess<T> = { success: true; data: T };
+export type ParseError = { success: false; error: Error };
+export type ParseResult<T> = ParseSuccess<T> | ParseError;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Versioned<T> Class
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Options for creating a Versioned instance.
+ */
+export interface VersionedOptions<T> {
+  /** Current schema version */
+  version: number;
+  /** Zod schema for validation */
+  schema: z.ZodType<T>;
+  /** Optional migrations for backward compatibility */
+  migrations?: Migration<unknown, unknown>[];
+}
+
+/**
+ * Unified versioned schema handler.
+ * Combines type definition, validation, and migration in one API.
+ *
+ * @example
+ * ```typescript
+ * const configType = new Versioned({
+ *   version: 2,
+ *   schema: configSchemaV2,
+ *   migrations: [v1ToV2Migration],
+ * });
+ *
+ * // Parse stored data (auto-migrates and validates)
+ * const config = await configType.parse(storedRecord);
+ *
+ * // Create new versioned data
+ * const record = configType.create({ url: "...", method: "GET" });
+ * ```
+ */
+export class Versioned<T> {
+  readonly version: number;
+  readonly schema: z.ZodType<T>;
+  private readonly _migrations: Migration<unknown, unknown>[];
+
+  constructor(options: VersionedOptions<T>) {
+    this.version = options.version;
+    this.schema = options.schema;
+    this._migrations = options.migrations ?? [];
+  }
+
+  /**
+   * Get the migrations chain for this versioned schema.
+   * Useful for ConfigService integration.
+   */
+  get migrations(): Migration<unknown, unknown>[] {
+    return this._migrations;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Data Parsing (load from storage)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Parse and migrate stored data to current version.
+   * Returns just the data payload.
+   * @throws ZodError on validation failure
+   * @throws Error on migration failure
+   */
+  async parse(input: VersionedRecord<unknown>): Promise<T> {
+    const migrated = await this.migrateToVersion(input);
+    return this.schema.parse(migrated.data);
+  }
+
+  /**
+   * Safe parse - returns result object instead of throwing.
+   */
+  async safeParse(input: VersionedRecord<unknown>): Promise<ParseResult<T>> {
+    try {
+      const data = await this.parse(input);
+      return { success: true, data };
+    } catch (error) {
+      return { success: false, error: error as Error };
+    }
+  }
+
+  /**
+   * Parse and return full VersionedRecord wrapper (preserves metadata).
+   */
+  async parseRecord(
+    input: VersionedRecord<unknown>
+  ): Promise<VersionedRecord<T>> {
+    const migrated = await this.migrateToVersion(input);
+    const validated = this.schema.parse(migrated.data);
+    return { ...migrated, data: validated };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Data Creation (wrap new data)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new VersionedRecord wrapper for fresh data.
+   * Validates data against schema.
+   */
+  create(data: T): VersionedRecord<T> {
+    return {
+      version: this.version,
+      data: this.schema.parse(data),
+    };
+  }
+
+  /**
+   * Create with plugin context for plugin-wide configs.
+   */
+  createForPlugin(data: T, pluginId: string): VersionedPluginRecord<T> {
+    return {
+      version: this.version,
+      data: this.schema.parse(data),
+      pluginId,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Utilities
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if data needs migration to reach current version.
+   */
+  needsMigration(input: VersionedRecord<unknown>): boolean {
+    return input.version !== this.version;
+  }
+
+  /**
+   * Validate data without migration (schema.parse wrapper).
+   * For data already at current version.
+   */
+  validate(data: unknown): T {
+    return this.schema.parse(data);
+  }
+
+  /**
+   * Safe validate - returns result object instead of throwing.
+   */
+  safeValidate(data: unknown): ReturnType<z.ZodType<T>["safeParse"]> {
+    return this.schema.safeParse(data);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal migration logic
+  // ─────────────────────────────────────────────────────────────────────────
+
+  private async migrateToVersion(
+    input: VersionedRecord<unknown>
+  ): Promise<VersionedRecord<unknown>> {
+    if (input.version === this.version) {
+      return input;
+    }
+
+    // Validate migration chain
+    this.validateMigrationChain(input.version);
+
+    // Sort and filter applicable migrations
+    const applicable = this.migrations
+      .filter(
+        (m) => m.fromVersion >= input.version && m.toVersion <= this.version
+      )
+      .toSorted((a, b) => a.fromVersion - b.fromVersion);
+
+    // Run migrations sequentially
+    let currentData = input.data;
+    let currentVersion = input.version;
+    const originalVersion = input.originalVersion ?? input.version;
+
+    for (const migration of applicable) {
+      try {
+        currentData = await migration.migrate(currentData);
+        currentVersion = migration.toVersion;
+      } catch (error) {
+        throw new Error(
+          `Migration from v${migration.fromVersion} to v${migration.toVersion} failed: ${error}`
+        );
+      }
+    }
+
+    return {
+      version: currentVersion,
+      data: currentData,
+      migratedAt: new Date(),
+      originalVersion,
+    };
+  }
+
+  private validateMigrationChain(fromVersion: number): void {
+    const sorted = this.migrations.toSorted(
+      (a, b) => a.fromVersion - b.fromVersion
+    );
+
+    let expectedVersion = fromVersion;
+    for (const migration of sorted) {
+      if (migration.fromVersion < fromVersion) continue;
+      if (migration.toVersion > this.version) break;
+
+      if (migration.fromVersion !== expectedVersion) {
+        throw new Error(
+          `Migration chain broken: expected migration from version ${expectedVersion}, ` +
+            `but found migration from version ${migration.fromVersion}`
+        );
+      }
+      if (migration.toVersion !== migration.fromVersion + 1) {
+        throw new Error(
+          `Migration must increment version by 1: migration from ${migration.fromVersion} ` +
+            `to ${migration.toVersion} is invalid`
+        );
+      }
+      expectedVersion = migration.toVersion;
+    }
+
+    if (expectedVersion !== this.version) {
+      throw new Error(
+        `Migration chain incomplete: reaches version ${expectedVersion}, ` +
+          `but target version is ${this.version}`
+      );
+    }
+  }
+}

package/src/contract.ts

@@ -0,0 +1,8 @@
+// Helper to ensure backend routers implement their RPC contracts
+// This provides compile-time type checking to prevent contract drift
+
+export function validateRouter<TContract>() {
+  return <TRouter extends TContract>(router: TRouter): TRouter => {
+    return router;
+  };
+}

package/src/core-services.ts

@@ -0,0 +1,45 @@
+import { createServiceRef } from "./service-ref";
+import type { RpcService } from "./rpc";
+import type { HealthCheckRegistry } from "./health-check";
+import type {
+  QueuePluginRegistry,
+  QueueManager,
+} from "@checkstack/queue-api";
+import type { ConfigService } from "./config-service";
+import type { SignalService } from "@checkstack/signal-common";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  Logger,
+  Fetch,
+  AuthService,
+  PluginInstaller,
+  RpcClient,
+} from "./types";
+import type { EventBus } from "./event-bus-types";
+
+export * from "./types";
+
+export const authenticationStrategyServiceRef = createServiceRef<unknown>(
+  "internal.authenticationStrategy"
+);
+
+export const coreServices = {
+  database:
+    createServiceRef<NodePgDatabase<Record<string, unknown>>>("core.database"),
+  logger: createServiceRef<Logger>("core.logger"),
+  fetch: createServiceRef<Fetch>("core.fetch"),
+  auth: createServiceRef<AuthService>("core.auth"),
+  healthCheckRegistry: createServiceRef<HealthCheckRegistry>(
+    "core.healthCheckRegistry"
+  ),
+  pluginInstaller: createServiceRef<PluginInstaller>("core.pluginInstaller"),
+  rpc: createServiceRef<RpcService>("core.rpc"),
+  rpcClient: createServiceRef<RpcClient>("core.rpcClient"),
+  queuePluginRegistry: createServiceRef<QueuePluginRegistry>(
+    "core.queuePluginRegistry"
+  ),
+  queueManager: createServiceRef<QueueManager>("core.queueManager"),
+  config: createServiceRef<ConfigService>("core.config"),
+  eventBus: createServiceRef<EventBus>("core.eventBus"),
+  signalService: createServiceRef<SignalService>("core.signalService"),
+};

package/src/email-layout.ts

@@ -0,0 +1,246 @@
+/**
+ * Email layout utilities for notification strategies.
+ *
+ * Provides a responsive HTML email template that strategies can use
+ * to wrap their content with consistent branding.
+ *
+ * @module
+ */
+
+/**
+ * Options for the email layout wrapper.
+ */
+export interface EmailLayoutOptions {
+  /** Email subject/title */
+  title: string;
+  /** Already-converted HTML body content */
+  bodyHtml: string;
+  /** Importance level affects header/button colors */
+  importance: "info" | "warning" | "critical";
+  /** Optional call-to-action button */
+  action?: {
+    label: string;
+    url: string;
+  };
+
+  // Admin-customizable options (via layoutConfig)
+  /** Logo URL (max ~200px wide recommended) */
+  logoUrl?: string;
+  /** Primary brand color (hex, e.g., "#3b82f6") */
+  primaryColor?: string;
+  /** Accent color for secondary elements */
+  accentColor?: string;
+  /** Footer text */
+  footerText?: string;
+  /** Footer links (e.g., Privacy Policy, Unsubscribe) */
+  footerLinks?: Array<{ label: string; url: string }>;
+}
+
+// Default importance-based colors
+const IMPORTANCE_COLORS = {
+  info: "#3b82f6", // blue
+  warning: "#f59e0b", // amber
+  critical: "#ef4444", // red
+} as const;
+
+/**
+ * Simple HTML escaping for security.
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+/**
+ * Wrap HTML content in a responsive email template.
+ *
+ * This template is designed to render consistently across major
+ * email clients (Gmail, Outlook, Apple Mail, etc.).
+ *
+ * @example
+ * ```typescript
+ * const html = wrapInEmailLayout({
+ *   title: "Password Reset",
+ *   bodyHtml: "<p>Click the button below to reset your password.</p>",
+ *   importance: "warning",
+ *   action: { label: "Reset Password", url: "https://..." },
+ *   primaryColor: "#10b981",
+ *   footerText: "Sent by Acme Corp",
+ * });
+ * ```
+ */
+export function wrapInEmailLayout(options: EmailLayoutOptions): string {
+  const {
+    title,
+    bodyHtml,
+    importance,
+    action,
+    logoUrl,
+    primaryColor,
+    footerText = "This is an automated notification.",
+    footerLinks = [],
+  } = options;
+
+  // Use custom color or importance-based default
+  const headerColor = primaryColor ?? IMPORTANCE_COLORS[importance];
+  const buttonColor = options.accentColor ?? headerColor;
+
+  // Build footer links HTML
+  const footerLinksHtml =
+    footerLinks.length > 0
+      ? footerLinks
+          .map(
+            (link) =>
+              `<a href="${escapeHtml(
+                link.url
+              )}" style="color: #6b7280; text-decoration: underline;">${escapeHtml(
+                link.label
+              )}</a>`
+          )
+          .join(" · ")
+      : "";
+
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light">
+  <meta name="supported-color-schemes" content="light">
+  <title>${escapeHtml(title)}</title>
+  <!--[if mso]>
+  <noscript>
+    <xml>
+      <o:OfficeDocumentSettings>
+        <o:PixelsPerInch>96</o:PixelsPerInch>
+      </o:OfficeDocumentSettings>
+    </xml>
+  </noscript>
+  <![endif]-->
+  <style>
+    /* Reset styles */
+    body, table, td, p, a, li, blockquote {
+      -webkit-text-size-adjust: 100%;
+      -ms-text-size-adjust: 100%;
+    }
+    table, td {
+      mso-table-lspace: 0pt;
+      mso-table-rspace: 0pt;
+    }
+    img {
+      -ms-interpolation-mode: bicubic;
+      border: 0;
+      height: auto;
+      line-height: 100%;
+      outline: none;
+      text-decoration: none;
+    }
+    body {
+      margin: 0 !important;
+      padding: 0 !important;
+      width: 100% !important;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      background-color: #f4f4f5;
+    }
+    /* Link styling */
+    a {
+      color: ${buttonColor};
+    }
+    /* Button styling */
+    .button {
+      display: inline-block;
+      padding: 12px 24px;
+      background-color: ${buttonColor};
+      color: #ffffff !important;
+      text-decoration: none;
+      border-radius: 6px;
+      font-weight: 600;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body style="margin: 0; padding: 0; background-color: #f4f4f5;">
+  <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="background-color: #f4f4f5;">
+    <tr>
+      <td align="center" style="padding: 24px 16px;">
+        <!-- Main container -->
+        <table role="presentation" cellpadding="0" cellspacing="0" width="600" style="max-width: 600px; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.1);">
+          ${
+            logoUrl
+              ? `
+          <!-- Logo -->
+          <tr>
+            <td align="center" style="padding: 24px 24px 0 24px;">
+              <img src="${escapeHtml(
+                logoUrl
+              )}" alt="Logo" style="max-width: 200px; height: auto;">
+            </td>
+          </tr>
+          `
+              : ""
+          }
+          <!-- Header -->
+          <tr>
+            <td style="background-color: ${headerColor}; padding: 20px 24px;">
+              <h1 style="margin: 0; color: #ffffff; font-size: 20px; font-weight: 600; line-height: 1.4;">
+                ${escapeHtml(title)}
+              </h1>
+            </td>
+          </tr>
+          <!-- Body -->
+          <tr>
+            <td style="padding: 24px;">
+              <div style="color: #374151; font-size: 16px; line-height: 1.6;">
+                ${bodyHtml}
+              </div>
+              ${
+                action
+                  ? `
+              <!-- CTA Button -->
+              <table role="presentation" cellpadding="0" cellspacing="0" style="margin-top: 24px;">
+                <tr>
+                  <td>
+                    <a href="${escapeHtml(
+                      action.url
+                    )}" class="button" style="display: inline-block; padding: 12px 24px; background-color: ${buttonColor}; color: #ffffff; text-decoration: none; border-radius: 6px; font-weight: 600; font-size: 14px;">
+                      ${escapeHtml(action.label)}
+                    </a>
+                  </td>
+                </tr>
+              </table>
+              `
+                  : ""
+              }
+            </td>
+          </tr>
+          <!-- Footer -->
+          <tr>
+            <td style="background-color: #f9fafb; padding: 16px 24px; border-top: 1px solid #e5e7eb;">
+              <p style="margin: 0; color: #6b7280; font-size: 12px; line-height: 1.5; text-align: center;">
+                ${escapeHtml(footerText)}
+              </p>
+              ${
+                footerLinksHtml
+                  ? `
+              <p style="margin: 8px 0 0 0; color: #6b7280; font-size: 12px; line-height: 1.5; text-align: center;">
+                ${footerLinksHtml}
+              </p>
+              `
+                  : ""
+              }
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>
+  `.trim();
+}