@checkstack/integration-backend 0.0.2

package/src/event-registry.test.ts

@@ -0,0 +1,396 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import {
+  createIntegrationEventRegistry,
+  type IntegrationEventRegistry,
+} from "./event-registry";
+import type { IntegrationEventDefinition } from "./provider-types";
+import { createHook } from "@checkstack/backend-api";
+
+/**
+ * Unit tests for IntegrationEventRegistry.
+ *
+ * Tests cover:
+ * - Event registration with proper namespacing
+ * - Event retrieval by ID and category
+ * - JSON Schema generation from Zod
+ * - Transform function preservation
+ */
+
+// Test plugin metadata
+const testPluginMetadata = {
+  pluginId: "test-plugin",
+  displayName: "Test Plugin",
+  description: "A test plugin",
+} as const;
+
+// Test hook definitions
+const testHook1 = createHook<{ incidentId: string; severity: string }>(
+  "incident.created"
+);
+const testHook2 = createHook<{ systemId: string; status: string }>(
+  "system.updated"
+);
+const testHook3 = createHook<{ maintenanceId: string }>("maintenance.started");
+
+// Test payload schemas
+const incidentPayloadSchema = z.object({
+  incidentId: z.string(),
+  severity: z.string(),
+});
+
+const systemPayloadSchema = z.object({
+  systemId: z.string(),
+  status: z.string(),
+});
+
+const maintenancePayloadSchema = z.object({
+  maintenanceId: z.string(),
+});
+
+describe("IntegrationEventRegistry", () => {
+  let registry: IntegrationEventRegistry;
+
+  beforeEach(() => {
+    registry = createIntegrationEventRegistry();
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Event Registration
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("register", () => {
+    it("registers an event with a fully qualified ID", () => {
+      const definition: IntegrationEventDefinition<{
+        incidentId: string;
+        severity: string;
+      }> = {
+        hook: testHook1,
+        displayName: "Incident Created",
+        description: "Fired when an incident is created",
+        category: "Incidents",
+        payloadSchema: incidentPayloadSchema,
+      };
+
+      registry.register(definition, testPluginMetadata);
+
+      expect(registry.hasEvent("test-plugin.incident.created")).toBe(true);
+    });
+
+    it("generates correct fully qualified event ID", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.eventId).toBe("test-plugin.incident.created");
+      expect(event?.ownerPluginId).toBe("test-plugin");
+    });
+
+    it("preserves display metadata", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          description: "Fired when an incident is created",
+          category: "Incidents",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.displayName).toBe("Incident Created");
+      expect(event?.description).toBe("Fired when an incident is created");
+      expect(event?.category).toBe("Incidents");
+    });
+
+    it("defaults category to Uncategorized", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.category).toBe("Uncategorized");
+    });
+
+    it("generates JSON Schema from Zod schema", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.payloadJsonSchema).toBeDefined();
+      expect(typeof event?.payloadJsonSchema).toBe("object");
+
+      // JSON Schema should have properties for the payload fields
+      const schema = event?.payloadJsonSchema as Record<string, unknown>;
+      expect(schema.type).toBe("object");
+    });
+
+    it("preserves transform function", () => {
+      const transform = (payload: {
+        incidentId: string;
+        severity: string;
+      }) => ({
+        id: payload.incidentId,
+        level: payload.severity.toUpperCase(),
+      });
+
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+          transformPayload: transform,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.transformPayload).toBeDefined();
+
+      const transformed = event?.transformPayload?.({
+        incidentId: "inc-123",
+        severity: "critical",
+      });
+      expect(transformed).toEqual({ id: "inc-123", level: "CRITICAL" });
+    });
+
+    it("preserves hook reference", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.hook.id).toBe("incident.created");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Event Retrieval
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("getEvents", () => {
+    it("returns empty array when no events registered", () => {
+      expect(registry.getEvents()).toEqual([]);
+    });
+
+    it("returns all registered events", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+      registry.register(
+        {
+          hook: testHook2,
+          displayName: "System Updated",
+          payloadSchema: systemPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const events = registry.getEvents();
+      expect(events.length).toBe(2);
+      expect(events.map((e) => e.displayName).sort()).toEqual([
+        "Incident Created",
+        "System Updated",
+      ]);
+    });
+  });
+
+  describe("getEvent", () => {
+    it("returns undefined for non-existent event", () => {
+      expect(registry.getEvent("non-existent.event")).toBeUndefined();
+    });
+
+    it("returns event by fully qualified ID", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const event = registry.getEvent("test-plugin.incident.created");
+      expect(event?.displayName).toBe("Incident Created");
+    });
+  });
+
+  describe("hasEvent", () => {
+    it("returns false for non-existent event", () => {
+      expect(registry.hasEvent("non-existent.event")).toBe(false);
+    });
+
+    it("returns true for registered event", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      expect(registry.hasEvent("test-plugin.incident.created")).toBe(true);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Category Grouping
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("getEventsByCategory", () => {
+    it("returns empty map when no events registered", () => {
+      const byCategory = registry.getEventsByCategory();
+      expect(byCategory.size).toBe(0);
+    });
+
+    it("groups events by category", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Incident Created",
+          category: "Incidents",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+      registry.register(
+        {
+          hook: testHook2,
+          displayName: "System Updated",
+          category: "Catalog",
+          payloadSchema: systemPayloadSchema,
+        },
+        testPluginMetadata
+      );
+      registry.register(
+        {
+          hook: testHook3,
+          displayName: "Maintenance Started",
+          category: "Incidents",
+          payloadSchema: maintenancePayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const byCategory = registry.getEventsByCategory();
+
+      expect(byCategory.size).toBe(2);
+      expect(byCategory.get("Incidents")?.length).toBe(2);
+      expect(byCategory.get("Catalog")?.length).toBe(1);
+    });
+
+    it("groups uncategorized events together", () => {
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Event 1",
+          payloadSchema: incidentPayloadSchema,
+        },
+        testPluginMetadata
+      );
+      registry.register(
+        {
+          hook: testHook2,
+          displayName: "Event 2",
+          payloadSchema: systemPayloadSchema,
+        },
+        testPluginMetadata
+      );
+
+      const byCategory = registry.getEventsByCategory();
+      expect(byCategory.get("Uncategorized")?.length).toBe(2);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Multi-Plugin Registration
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("multi-plugin registration", () => {
+    it("handles events from multiple plugins", () => {
+      const plugin1 = { pluginId: "plugin-1" } as const;
+      const plugin2 = { pluginId: "plugin-2" } as const;
+
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Plugin 1 Event",
+          payloadSchema: incidentPayloadSchema,
+        },
+        plugin1
+      );
+      registry.register(
+        {
+          hook: testHook1,
+          displayName: "Plugin 2 Event",
+          payloadSchema: incidentPayloadSchema,
+        },
+        plugin2
+      );
+
+      expect(registry.hasEvent("plugin-1.incident.created")).toBe(true);
+      expect(registry.hasEvent("plugin-2.incident.created")).toBe(true);
+
+      const events = registry.getEvents();
+      expect(events.length).toBe(2);
+    });
+
+    it("correctly namespaces events by plugin", () => {
+      const plugin1 = { pluginId: "incident" } as const;
+      const plugin2 = { pluginId: "maintenance" } as const;
+
+      registry.register(
+        {
+          hook: createHook("created"),
+          displayName: "Incident Created",
+          payloadSchema: incidentPayloadSchema,
+        },
+        plugin1
+      );
+      registry.register(
+        {
+          hook: createHook("created"),
+          displayName: "Maintenance Created",
+          payloadSchema: maintenancePayloadSchema,
+        },
+        plugin2
+      );
+
+      expect(registry.getEvent("incident.created")?.displayName).toBe(
+        "Incident Created"
+      );
+      expect(registry.getEvent("maintenance.created")?.displayName).toBe(
+        "Maintenance Created"
+      );
+    });
+  });
+});

package/src/event-registry.ts

@@ -0,0 +1,99 @@
+import type { PluginMetadata } from "@checkstack/common";
+import { toJsonSchema } from "@checkstack/backend-api";
+import type {
+  IntegrationEventDefinition,
+  RegisteredIntegrationEvent,
+} from "./provider-types";
+
+/**
+ * Registry for integration events.
+ * Plugins register their hooks here to expose them for external webhook subscriptions.
+ */
+export interface IntegrationEventRegistry {
+  /**
+   * Register a hook as an integration event.
+   * Called via the extension point during plugin registration.
+   */
+  register<T>(
+    definition: IntegrationEventDefinition<T>,
+    pluginMetadata: PluginMetadata
+  ): void;
+
+  /** Get all registered events */
+  getEvents(): RegisteredIntegrationEvent[];
+
+  /** Get events grouped by category */
+  getEventsByCategory(): Map<string, RegisteredIntegrationEvent[]>;
+
+  /** Get a specific event by its fully qualified ID */
+  getEvent(eventId: string): RegisteredIntegrationEvent | undefined;
+
+  /** Check if an event is registered */
+  hasEvent(eventId: string): boolean;
+}
+
+/**
+ * Create a new integration event registry instance.
+ */
+export function createIntegrationEventRegistry(): IntegrationEventRegistry {
+  const events = new Map<string, RegisteredIntegrationEvent>();
+
+  return {
+    register<T>(
+      definition: IntegrationEventDefinition<T>,
+      pluginMetadata: PluginMetadata
+    ): void {
+      // Extract hook ID from the hook reference
+      const hookId = definition.hook.id;
+
+      // Create fully qualified event ID
+      const eventId = `${pluginMetadata.pluginId}.${hookId}`;
+
+      // Convert Zod schema to JSON Schema for UI preview
+      // Uses the platform's toJsonSchema which handles secrets/colors
+      const payloadJsonSchema = toJsonSchema(definition.payloadSchema);
+
+      const registered: RegisteredIntegrationEvent<T> = {
+        eventId,
+        hook: definition.hook,
+        ownerPluginId: pluginMetadata.pluginId,
+        displayName: definition.displayName,
+        description: definition.description,
+        category: definition.category ?? "Uncategorized",
+        payloadJsonSchema,
+        payloadSchema: definition.payloadSchema,
+        transformPayload: definition.transformPayload,
+      };
+
+      // We cast to RegisteredIntegrationEvent (with unknown) when storing because
+      // the Map erases the specific type T anyway. This is type-safe because
+      // the transformPayload function will only be called with the correct type.
+      events.set(eventId, registered as RegisteredIntegrationEvent);
+    },
+
+    getEvents(): RegisteredIntegrationEvent[] {
+      return [...events.values()];
+    },
+
+    getEventsByCategory(): Map<string, RegisteredIntegrationEvent[]> {
+      const byCategory = new Map<string, RegisteredIntegrationEvent[]>();
+
+      for (const event of events.values()) {
+        const category = event.category ?? "Uncategorized";
+        const existing = byCategory.get(category) ?? [];
+        existing.push(event);
+        byCategory.set(category, existing);
+      }
+
+      return byCategory;
+    },
+
+    getEvent(eventId: string): RegisteredIntegrationEvent | undefined {
+      return events.get(eventId);
+    },
+
+    hasEvent(eventId: string): boolean {
+      return events.has(eventId);
+    },
+  };
+}

package/src/hook-subscriber.ts

@@ -0,0 +1,104 @@
+import type {
+  Logger,
+  HookSubscribeOptions,
+} from "@checkstack/backend-api";
+import type { IntegrationEventRegistry } from "./event-registry";
+import type { DeliveryCoordinator } from "./delivery-coordinator";
+import type { RegisteredIntegrationEvent } from "./provider-types";
+
+/**
+ * Hook subscription function type (matches env.onHook signature)
+ */
+type OnHookFn = <T>(
+  hook: { id: string; _type?: T },
+  listener: (payload: T) => Promise<void>,
+  options?: HookSubscribeOptions
+) => () => Promise<void>;
+
+/**
+ * Subscribe to all registered integration events.
+ *
+ * This function is called during afterPluginsReady to set up hook listeners
+ * for each registered integration event. It uses work-queue mode to ensure
+ * that only ONE backend instance processes each event (important for horizontal scaling).
+ *
+ * @param onHook - The onHook function from the plugin environment
+ * @param eventRegistry - The registry of integration events
+ * @param deliveryCoordinator - The coordinator that routes events to subscriptions
+ * @param logger - Logger for debugging
+ */
+export function subscribeToRegisteredEvents({
+  onHook,
+  eventRegistry,
+  deliveryCoordinator,
+  logger,
+}: {
+  onHook: OnHookFn;
+  eventRegistry: IntegrationEventRegistry;
+  deliveryCoordinator: DeliveryCoordinator;
+  logger: Logger;
+}): void {
+  const events = eventRegistry.getEvents();
+
+  logger.debug(`Subscribing to ${events.length} integration events...`);
+
+  for (const event of events) {
+    subscribeToEvent(event, onHook, deliveryCoordinator, logger);
+  }
+
+  logger.info(
+    `Subscribed to ${events.length} integration events for webhook delivery`
+  );
+}
+
+/**
+ * Subscribe to a single integration event
+ */
+function subscribeToEvent(
+  event: RegisteredIntegrationEvent,
+  onHook: OnHookFn,
+  deliveryCoordinator: DeliveryCoordinator,
+  logger: Logger
+): void {
+  // Create a unique worker group for this event
+  // This ensures competing consumer behavior across instances
+  const workerGroup = `webhook-${event.eventId}`;
+
+  onHook(
+    event.hook,
+    async (payload: unknown) => {
+      logger.debug(`Received integration event: ${event.eventId}`);
+
+      try {
+        // Apply optional payload transformation
+        const transformedPayload = event.transformPayload
+          ? event.transformPayload(payload)
+          : (payload as Record<string, unknown>);
+
+        // Route to matching subscriptions
+        await deliveryCoordinator.routeEvent({
+          eventId: event.eventId,
+          payload: transformedPayload,
+          timestamp: new Date().toISOString(),
+        });
+      } catch (error) {
+        logger.error(
+          `Failed to route integration event ${event.eventId}:`,
+          error instanceof Error ? error.message : String(error)
+        );
+        // Don't re-throw - we don't want to fail the entire hook chain
+        // The event will be logged but not retried at the hook level
+      }
+    },
+    {
+      // CRITICAL: Use work-queue mode to ensure only ONE instance processes each event
+      // This prevents duplicate webhook deliveries when horizontally scaled
+      mode: "work-queue",
+      workerGroup,
+    }
+  );
+
+  logger.debug(
+    `Subscribed to event: ${event.eventId} (workerGroup: ${workerGroup})`
+  );
+}