@checkstack/integration-backend 0.0.2

package/src/index.ts

@@ -0,0 +1,306 @@
+import {
+  createBackendPlugin,
+  coreServices,
+  createExtensionPoint,
+  createServiceRef,
+} from "@checkstack/backend-api";
+import {
+  permissionList,
+  pluginMetadata,
+  integrationContract,
+  integrationRoutes,
+  permissions,
+} from "@checkstack/integration-common";
+import { resolveRoute } from "@checkstack/common";
+import type { PluginMetadata } from "@checkstack/common";
+import type {
+  IntegrationEventDefinition,
+  IntegrationProvider,
+} from "./provider-types";
+
+import * as schema from "./schema";
+import {
+  createIntegrationEventRegistry,
+  type IntegrationEventRegistry,
+} from "./event-registry";
+import {
+  createIntegrationProviderRegistry,
+  type IntegrationProviderRegistry,
+} from "./provider-registry";
+import { createDeliveryCoordinator } from "./delivery-coordinator";
+import {
+  createConnectionStore,
+  type ConnectionStore,
+} from "./connection-store";
+import { subscribeToRegisteredEvents } from "./hook-subscriber";
+import { createIntegrationRouter } from "./router";
+import { registerSearchProvider } from "@checkstack/command-backend";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Service References
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Service reference for the connection store.
+ * Provider plugins can inject this to access connection credentials.
+ */
+export const connectionStoreRef = createServiceRef<ConnectionStore>(
+  "integration.connectionStore"
+);
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Extension Points
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Extension point for registering integration events.
+ * Plugins use this to expose their hooks for external webhook subscriptions.
+ */
+export interface IntegrationEventExtensionPoint {
+  /**
+   * Register a hook as an integration event.
+   * The event will be namespaced by the plugin's ID automatically.
+   */
+  registerEvent<T>(
+    definition: IntegrationEventDefinition<T>,
+    pluginMetadata: PluginMetadata
+  ): void;
+}
+
+export const integrationEventExtensionPoint =
+  createExtensionPoint<IntegrationEventExtensionPoint>(
+    "integration.eventExtensionPoint"
+  );
+
+/**
+ * Extension point for registering integration providers.
+ * Plugins use this to register webhook delivery providers.
+ */
+export interface IntegrationProviderExtensionPoint {
+  /**
+   * Register an integration provider.
+   * The provider will be namespaced by the plugin's ID automatically.
+   * @template TConfig - Per-subscription configuration type
+   * @template TConnection - Site-wide connection configuration type (optional)
+   */
+  addProvider<TConfig, TConnection = undefined>(
+    provider: IntegrationProvider<TConfig, TConnection>,
+    pluginMetadata: PluginMetadata
+  ): void;
+}
+
+export const integrationProviderExtensionPoint =
+  createExtensionPoint<IntegrationProviderExtensionPoint>(
+    "integration.providerExtensionPoint"
+  );
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Create the registries
+    const eventRegistry = createIntegrationEventRegistry();
+    const providerRegistry = createIntegrationProviderRegistry();
+
+    // Register static permissions
+    env.registerPermissions(permissionList);
+
+    // Register the event extension point
+    env.registerExtensionPoint(integrationEventExtensionPoint, {
+      registerEvent: <T>(
+        definition: IntegrationEventDefinition<T>,
+        metadata: PluginMetadata
+      ) => {
+        // Type erasure: cast to unknown for storage (the registry handles this internally)
+        eventRegistry.register(
+          definition as IntegrationEventDefinition<unknown>,
+          metadata
+        );
+      },
+    });
+
+    // Register the provider extension point
+    env.registerExtensionPoint(integrationProviderExtensionPoint, {
+      addProvider: (provider, metadata) => {
+        // Type erasure: cast to unknown for storage (the registry handles this internally)
+        providerRegistry.register(
+          provider as IntegrationProvider<unknown>,
+          metadata
+        );
+      },
+    });
+
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+        rpc: coreServices.rpc,
+        config: coreServices.config,
+        signalService: coreServices.signalService,
+        queueManager: coreServices.queueManager,
+      },
+      init: async ({
+        logger,
+        database,
+        rpc,
+        config,
+        signalService,
+        queueManager,
+      }) => {
+        logger.debug("🔌 Initializing Integration Backend...");
+
+        const db = database;
+
+        // Create connection store for generic connection management
+        const connectionStore = createConnectionStore({
+          configService: config,
+          providerRegistry,
+          logger,
+        });
+
+        // Publish connection store for provider plugins to inject
+        env.registerService(connectionStoreRef, connectionStore);
+
+        // Create delivery coordinator
+        const deliveryCoordinator = createDeliveryCoordinator({
+          db,
+          providerRegistry,
+          connectionStore,
+          queueManager,
+          signalService,
+          logger,
+        });
+
+        // Store for afterPluginsReady access
+        (
+          env as unknown as {
+            eventRegistry: IntegrationEventRegistry;
+            providerRegistry: IntegrationProviderRegistry;
+            deliveryCoordinator: typeof deliveryCoordinator;
+          }
+        ).eventRegistry = eventRegistry;
+        (
+          env as unknown as {
+            eventRegistry: IntegrationEventRegistry;
+            providerRegistry: IntegrationProviderRegistry;
+            deliveryCoordinator: typeof deliveryCoordinator;
+          }
+        ).providerRegistry = providerRegistry;
+        (
+          env as unknown as {
+            eventRegistry: IntegrationEventRegistry;
+            providerRegistry: IntegrationProviderRegistry;
+            deliveryCoordinator: typeof deliveryCoordinator;
+          }
+        ).deliveryCoordinator = deliveryCoordinator;
+
+        // Create and register the router
+        const router = createIntegrationRouter({
+          db,
+          eventRegistry,
+          providerRegistry,
+          deliveryCoordinator,
+          connectionStore,
+          signalService,
+          logger,
+        });
+        rpc.registerRouter(router, integrationContract);
+
+        // Register command palette commands
+        registerSearchProvider({
+          pluginMetadata,
+          commands: [
+            {
+              id: "create",
+              title: "Create Integration Subscription",
+              subtitle: "Create a new subscription for integration events",
+              iconName: "Webhook",
+              route:
+                resolveRoute(integrationRoutes.routes.list) + "?action=create",
+              requiredPermissions: [permissions.integrationManage],
+            },
+            {
+              id: "manage",
+              title: "Manage Integrations",
+              subtitle: "Manage integration subscriptions and connections",
+              iconName: "Webhook",
+              shortcuts: ["meta+shift+g", "ctrl+shift+g"],
+              route: resolveRoute(integrationRoutes.routes.list),
+              requiredPermissions: [permissions.integrationManage],
+            },
+            {
+              id: "logs",
+              title: "View Integration Logs",
+              subtitle: "View integration delivery logs",
+              iconName: "FileText",
+              route: resolveRoute(integrationRoutes.routes.logs),
+              requiredPermissions: [permissions.integrationManage],
+            },
+          ],
+        });
+
+        logger.debug("✅ Integration Backend initialized.");
+      },
+      afterPluginsReady: async ({ logger, onHook }) => {
+        // Get registries from env
+        const stored = env as unknown as {
+          eventRegistry: IntegrationEventRegistry;
+          providerRegistry: IntegrationProviderRegistry;
+          deliveryCoordinator: ReturnType<typeof createDeliveryCoordinator>;
+        };
+
+        const events = stored.eventRegistry.getEvents();
+        const providers = stored.providerRegistry.getProviders();
+
+        logger.debug(
+          `🔌 Registered ${events.length} integration events: ${events
+            .map((e) => e.eventId)
+            .join(", ")}`
+        );
+
+        logger.debug(
+          `📡 Registered ${providers.length} integration providers: ${providers
+            .map((p) => p.qualifiedId)
+            .join(", ")}`
+        );
+
+        // Subscribe to all registered integration events
+        // Uses work-queue mode to ensure only ONE instance processes each event
+        subscribeToRegisteredEvents({
+          onHook,
+          eventRegistry: stored.eventRegistry,
+          deliveryCoordinator: stored.deliveryCoordinator,
+          logger,
+        });
+
+        // Start the delivery worker
+        await stored.deliveryCoordinator.startWorker();
+
+        logger.debug("✅ Integration Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});
+
+// Re-export extension points for consumer plugins
+export { integrationEventExtensionPoint as eventExtensionPoint };
+export { integrationProviderExtensionPoint as providerExtensionPoint };
+
+// Re-export provider types for consumer plugins
+// All backend-only types are defined here (not in integration-common)
+export type {
+  IntegrationEventDefinition,
+  IntegrationDeliveryContext,
+  IntegrationDeliveryResult,
+  TestConnectionResult,
+  ProviderDocumentation,
+  ConnectionOption,
+  GetConnectionOptionsParams,
+  IntegrationProvider,
+  RegisteredIntegrationProvider,
+  RegisteredIntegrationEvent,
+} from "./provider-types";

package/src/provider-registry.test.ts

@@ -0,0 +1,314 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import {
+  createIntegrationProviderRegistry,
+  type IntegrationProviderRegistry,
+} from "./provider-registry";
+import type { IntegrationProvider } from "./provider-types";
+import { Versioned } from "@checkstack/backend-api";
+
+/**
+ * Unit tests for IntegrationProviderRegistry.
+ *
+ * Tests cover:
+ * - Provider registration with proper namespacing
+ * - Provider retrieval by qualified ID
+ * - Config schema JSON conversion
+ */
+
+// Test plugin metadata
+const testPluginMetadata = {
+  pluginId: "test-plugin",
+  displayName: "Test Plugin",
+} as const;
+
+// Test config schemas
+const webhookConfigSchema = z.object({
+  url: z.string().url(),
+  method: z.enum(["GET", "POST"]),
+  timeout: z.number().default(5000),
+});
+
+const slackConfigSchema = z.object({
+  webhookUrl: z.string().url(),
+  channel: z.string(),
+});
+
+// Create test providers
+function createTestProvider(
+  id: string,
+  schema: z.ZodType<unknown>
+): IntegrationProvider<unknown> {
+  return {
+    id,
+    displayName: `${id.charAt(0).toUpperCase()}${id.slice(1)} Provider`,
+    description: `Deliver events via ${id}`,
+    icon: "Webhook",
+    config: new Versioned({
+      version: 1,
+      schema,
+    }),
+    deliver: async () => ({ success: true }),
+  };
+}
+
+describe("IntegrationProviderRegistry", () => {
+  let registry: IntegrationProviderRegistry;
+
+  beforeEach(() => {
+    registry = createIntegrationProviderRegistry();
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider Registration
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("register", () => {
+    it("registers a provider with a fully qualified ID", () => {
+      const provider = createTestProvider("webhook", webhookConfigSchema);
+
+      registry.register(provider, testPluginMetadata);
+
+      expect(registry.hasProvider("test-plugin.webhook")).toBe(true);
+    });
+
+    it("generates correct qualified ID", () => {
+      const provider = createTestProvider("webhook", webhookConfigSchema);
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.webhook");
+      expect(registered?.qualifiedId).toBe("test-plugin.webhook");
+      expect(registered?.ownerPluginId).toBe("test-plugin");
+    });
+
+    it("preserves provider metadata", () => {
+      const provider: IntegrationProvider<unknown> = {
+        id: "custom",
+        displayName: "Custom Provider",
+        description: "A custom provider for testing",
+        icon: "Cog",
+        config: new Versioned({ version: 1, schema: webhookConfigSchema }),
+        deliver: async () => ({ success: true }),
+      };
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.custom");
+      expect(registered?.displayName).toBe("Custom Provider");
+      expect(registered?.description).toBe("A custom provider for testing");
+      expect(registered?.icon).toBe("Cog");
+    });
+
+    it("preserves deliver function", () => {
+      const deliverFn = async () => ({ success: true, externalId: "ext-123" });
+      const provider: IntegrationProvider<unknown> = {
+        id: "webhook",
+        displayName: "Webhook",
+        config: new Versioned({ version: 1, schema: webhookConfigSchema }),
+        deliver: deliverFn,
+      };
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.webhook");
+      expect(registered?.deliver).toBeDefined();
+    });
+
+    it("preserves testConnection function if provided", () => {
+      const provider: IntegrationProvider<unknown> = {
+        id: "webhook",
+        displayName: "Webhook",
+        config: new Versioned({ version: 1, schema: webhookConfigSchema }),
+        deliver: async () => ({ success: true }),
+        testConnection: async () => ({ success: true, message: "OK" }),
+      };
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.webhook");
+      expect(registered?.testConnection).toBeDefined();
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider Retrieval
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("getProviders", () => {
+    it("returns empty array when no providers registered", () => {
+      expect(registry.getProviders()).toEqual([]);
+    });
+
+    it("returns all registered providers", () => {
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        testPluginMetadata
+      );
+      registry.register(
+        createTestProvider("slack", slackConfigSchema),
+        testPluginMetadata
+      );
+
+      const providers = registry.getProviders();
+      expect(providers.length).toBe(2);
+      expect(providers.map((p) => p.id).sort()).toEqual(["slack", "webhook"]);
+    });
+  });
+
+  describe("getProvider", () => {
+    it("returns undefined for non-existent provider", () => {
+      expect(registry.getProvider("non-existent.provider")).toBeUndefined();
+    });
+
+    it("returns provider by qualified ID", () => {
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        testPluginMetadata
+      );
+
+      const provider = registry.getProvider("test-plugin.webhook");
+      expect(provider?.displayName).toBe("Webhook Provider");
+    });
+  });
+
+  describe("hasProvider", () => {
+    it("returns false for non-existent provider", () => {
+      expect(registry.hasProvider("non-existent.provider")).toBe(false);
+    });
+
+    it("returns true for registered provider", () => {
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        testPluginMetadata
+      );
+
+      expect(registry.hasProvider("test-plugin.webhook")).toBe(true);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("getProviderConfigSchema", () => {
+    it("returns undefined for non-existent provider", () => {
+      expect(
+        registry.getProviderConfigSchema("non-existent.provider")
+      ).toBeUndefined();
+    });
+
+    it("returns JSON Schema for provider config", () => {
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        testPluginMetadata
+      );
+
+      const schema = registry.getProviderConfigSchema("test-plugin.webhook");
+      expect(schema).toBeDefined();
+      expect(typeof schema).toBe("object");
+      expect(schema?.type).toBe("object");
+    });
+
+    it("JSON Schema includes property definitions", () => {
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        testPluginMetadata
+      );
+
+      const schema = registry.getProviderConfigSchema("test-plugin.webhook");
+      const properties = schema?.properties as Record<string, unknown>;
+
+      expect(properties).toBeDefined();
+      expect(properties.url).toBeDefined();
+      expect(properties.method).toBeDefined();
+      expect(properties.timeout).toBeDefined();
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Multi-Plugin Registration
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("multi-plugin registration", () => {
+    it("handles providers from multiple plugins", () => {
+      const plugin1 = { pluginId: "plugin-1" } as const;
+      const plugin2 = { pluginId: "plugin-2" } as const;
+
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        plugin1
+      );
+      registry.register(
+        createTestProvider("webhook", webhookConfigSchema),
+        plugin2
+      );
+
+      expect(registry.hasProvider("plugin-1.webhook")).toBe(true);
+      expect(registry.hasProvider("plugin-2.webhook")).toBe(true);
+
+      const providers = registry.getProviders();
+      expect(providers.length).toBe(2);
+    });
+
+    it("correctly namespaces providers by plugin", () => {
+      const plugin1 = { pluginId: "integration-webhook" } as const;
+      const plugin2 = { pluginId: "integration-slack" } as const;
+
+      registry.register(
+        {
+          ...createTestProvider("default", webhookConfigSchema),
+          displayName: "Webhook",
+        },
+        plugin1
+      );
+      registry.register(
+        {
+          ...createTestProvider("default", slackConfigSchema),
+          displayName: "Slack",
+        },
+        plugin2
+      );
+
+      expect(
+        registry.getProvider("integration-webhook.default")?.displayName
+      ).toBe("Webhook");
+      expect(
+        registry.getProvider("integration-slack.default")?.displayName
+      ).toBe("Slack");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Supported Events
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("supportedEvents", () => {
+    it("preserves supportedEvents array", () => {
+      const provider: IntegrationProvider<unknown> = {
+        id: "limited",
+        displayName: "Limited Provider",
+        config: new Versioned({ version: 1, schema: webhookConfigSchema }),
+        supportedEvents: ["incident.created", "incident.resolved"],
+        deliver: async () => ({ success: true }),
+      };
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.limited");
+      expect(registered?.supportedEvents).toEqual([
+        "incident.created",
+        "incident.resolved",
+      ]);
+    });
+
+    it("handles provider with no supportedEvents (accepts all)", () => {
+      const provider = createTestProvider("webhook", webhookConfigSchema);
+
+      registry.register(provider, testPluginMetadata);
+
+      const registered = registry.getProvider("test-plugin.webhook");
+      expect(registered?.supportedEvents).toBeUndefined();
+    });
+  });
+});