@checkstack/integration-backend 0.0.2

package/src/provider-registry.ts

@@ -0,0 +1,107 @@
+import type { PluginMetadata } from "@checkstack/common";
+import { toJsonSchema } from "@checkstack/backend-api";
+import type {
+  IntegrationProvider,
+  RegisteredIntegrationProvider,
+} from "./provider-types";
+
+/**
+ * Registry for integration providers.
+ * Plugins register their providers here to enable webhook delivery to external systems.
+ */
+export interface IntegrationProviderRegistry {
+  /**
+   * Register an integration provider.
+   * Called via the extension point during plugin registration.
+   */
+  register(
+    provider: IntegrationProvider<unknown>,
+    pluginMetadata: PluginMetadata
+  ): void;
+
+  /** Get all registered providers */
+  getProviders(): RegisteredIntegrationProvider<unknown>[];
+
+  /** Get a specific provider by its fully qualified ID */
+  getProvider(
+    qualifiedId: string
+  ): RegisteredIntegrationProvider<unknown> | undefined;
+
+  /** Check if a provider is registered */
+  hasProvider(qualifiedId: string): boolean;
+
+  /** Get the JSON Schema for a provider's config */
+  getProviderConfigSchema(
+    qualifiedId: string
+  ): Record<string, unknown> | undefined;
+
+  /** Get the JSON Schema for a provider's connection config (if any) */
+  getProviderConnectionSchema(
+    qualifiedId: string
+  ): Record<string, unknown> | undefined;
+}
+
+/**
+ * Create a new integration provider registry instance.
+ */
+export function createIntegrationProviderRegistry(): IntegrationProviderRegistry {
+  const providers = new Map<string, RegisteredIntegrationProvider<unknown>>();
+  const configSchemas = new Map<string, Record<string, unknown>>();
+  const connectionSchemas = new Map<string, Record<string, unknown>>();
+
+  return {
+    register(
+      provider: IntegrationProvider<unknown>,
+      pluginMetadata: PluginMetadata
+    ): void {
+      const qualifiedId = `${pluginMetadata.pluginId}.${provider.id}`;
+
+      const registered: RegisteredIntegrationProvider<unknown> = {
+        ...provider,
+        qualifiedId,
+        ownerPluginId: pluginMetadata.pluginId,
+      };
+
+      providers.set(qualifiedId, registered);
+
+      // Convert the provider's config schema to JSON Schema for UI
+      // Uses the platform's toJsonSchema which handles secrets/colors
+      const jsonSchema = toJsonSchema(provider.config.schema);
+      configSchemas.set(qualifiedId, jsonSchema);
+
+      // Also convert connection schema if present
+      if (provider.connectionSchema) {
+        const connectionJsonSchema = toJsonSchema(
+          provider.connectionSchema.schema
+        );
+        connectionSchemas.set(qualifiedId, connectionJsonSchema);
+      }
+    },
+
+    getProviders(): RegisteredIntegrationProvider<unknown>[] {
+      return [...providers.values()];
+    },
+
+    getProvider(
+      qualifiedId: string
+    ): RegisteredIntegrationProvider<unknown> | undefined {
+      return providers.get(qualifiedId);
+    },
+
+    hasProvider(qualifiedId: string): boolean {
+      return providers.has(qualifiedId);
+    },
+
+    getProviderConfigSchema(
+      qualifiedId: string
+    ): Record<string, unknown> | undefined {
+      return configSchemas.get(qualifiedId);
+    },
+
+    getProviderConnectionSchema(
+      qualifiedId: string
+    ): Record<string, unknown> | undefined {
+      return connectionSchemas.get(qualifiedId);
+    },
+  };
+}

package/src/provider-types.ts

@@ -0,0 +1,257 @@
+/**
+ * Integration Provider Types
+ *
+ * These types define the contract for integration provider plugins.
+ * All backend-only types live here - frontend uses Zod schemas from integration-common.
+ */
+import { z } from "zod";
+import type { Versioned, Logger, Hook } from "@checkstack/backend-api";
+import type { LucideIconName } from "@checkstack/common";
+
+// =============================================================================
+// Integration Event Definition Types
+// =============================================================================
+
+/**
+ * Metadata for registering a hook as an integration event.
+ * Plugins use this to expose their hooks for external webhook subscriptions.
+ */
+export interface IntegrationEventDefinition<T = unknown> {
+  /** The hook to expose (from the owning plugin) */
+  hook: Hook<T>;
+
+  /** Human-readable name for the UI */
+  displayName: string;
+
+  /** Description of when this event fires */
+  description?: string;
+
+  /** Category for UI grouping (e.g., "Health", "Incidents", "Maintenance") */
+  category?: string;
+
+  /** Zod schema for the payload (used for UI preview and validation) */
+  payloadSchema: z.ZodType<T>;
+
+  /**
+   * Optional: Transform hook payload before sending to webhooks.
+   * Use this to enrich the payload with additional context or
+   * redact sensitive fields.
+   */
+  transformPayload?: (payload: T) => Record<string, unknown>;
+}
+
+// =============================================================================
+// Integration Provider Types
+// =============================================================================
+
+/**
+ * Context passed to the provider's deliver() method.
+ */
+export interface IntegrationDeliveryContext<TConfig = unknown> {
+  event: {
+    /** Fully qualified event ID */
+    eventId: string;
+    /** Event payload (possibly transformed) */
+    payload: Record<string, unknown>;
+    /** ISO timestamp when the event was emitted */
+    timestamp: string;
+    /** Unique ID for this delivery attempt */
+    deliveryId: string;
+  };
+  subscription: {
+    /** Subscription ID */
+    id: string;
+    /** Subscription name */
+    name: string;
+  };
+  /** Provider-specific configuration */
+  providerConfig: TConfig;
+  /** Scoped logger for delivery tracing */
+  logger: Logger;
+  /**
+   * Get connection credentials by ID (for providers with connectionSchema).
+   * Only available when provider has a connectionSchema defined.
+   */
+  getConnectionWithCredentials?: (
+    connectionId: string
+  ) => Promise<{ config: Record<string, unknown> } | undefined>;
+}
+
+/**
+ * Result of a provider delivery attempt.
+ */
+export interface IntegrationDeliveryResult {
+  success: boolean;
+  /** External ID returned by the target system (e.g., Jira issue key) */
+  externalId?: string;
+  /** Error message if delivery failed */
+  error?: string;
+  /** Milliseconds to wait before retrying (if applicable) */
+  retryAfterMs?: number;
+}
+
+/**
+ * Result of testing a provider connection.
+ */
+export interface TestConnectionResult {
+  success: boolean;
+  message?: string;
+}
+
+/**
+ * Documentation that helps users implement their endpoint for this provider.
+ */
+export interface ProviderDocumentation {
+  /** Brief setup instructions (rendered as markdown) */
+  setupGuide?: string;
+  /** Example request body (JSON string for syntax highlighting) */
+  examplePayload?: string;
+  /** HTTP headers that will be sent with each request */
+  headers?: Array<{ name: string; description: string }>;
+  /** Link to external documentation */
+  externalDocsUrl?: string;
+}
+
+/**
+ * Option returned by getConnectionOptions for dynamic dropdowns.
+ */
+export interface ConnectionOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+/**
+ * Parameters for getConnectionOptions method.
+ */
+export interface GetConnectionOptionsParams {
+  /** The connection ID to use for fetching options */
+  connectionId: string;
+  /** Name of the resolver (matches x-options-resolver in schema) */
+  resolverName: string;
+  /** Current form values for dependent fields */
+  context: Record<string, unknown>;
+  /** Logger for logging */
+  logger: Logger;
+  /**
+   * Get connection credentials by ID.
+   * Provided by the integration backend for providers to access connection config.
+   */
+  getConnectionWithCredentials: (
+    connectionId: string
+  ) => Promise<{ config: Record<string, unknown> } | undefined>;
+}
+
+/**
+ * Integration provider definition.
+ * Providers define how to deliver events to specific external systems.
+ *
+ * @template TConfig - Per-subscription configuration type
+ * @template TConnection - Site-wide connection configuration type (optional)
+ */
+export interface IntegrationProvider<
+  TConfig = unknown,
+  TConnection = undefined
+> {
+  /** Local identifier, namespaced on registration to {pluginId}.{id} */
+  id: string;
+
+  /** Display name for UI */
+  displayName: string;
+
+  /** Description of what this provider does */
+  description?: string;
+
+  /** Lucide icon name in PascalCase (e.g., 'Webhook') */
+  icon?: LucideIconName;
+
+  /** Per-subscription configuration schema */
+  config: Versioned<TConfig>;
+
+  /**
+   * Optional site-wide connection schema.
+   * When provided, the platform will:
+   * - Store connections centrally via ConfigService
+   * - Show a "Connections" management UI
+   * - Add a connection dropdown to subscription config
+   */
+  connectionSchema?: Versioned<TConnection>;
+
+  /**
+   * Events this provider can handle.
+   * If undefined, provider accepts all events.
+   * Event IDs are fully qualified: {pluginId}.{hookId}
+   */
+  supportedEvents?: string[];
+
+  /**
+   * Optional documentation to help users configure their endpoints.
+   * Displayed in the UI when creating/editing subscriptions.
+   */
+  documentation?: ProviderDocumentation;
+
+  /**
+   * Transform and deliver the event to the external system.
+   */
+  deliver(
+    context: IntegrationDeliveryContext<TConfig>
+  ): Promise<IntegrationDeliveryResult>;
+
+  /**
+   * Optional: Test the connection configuration.
+   * Called when admin clicks "Test Connection" in the connections UI.
+   * Only applicable when connectionSchema is defined.
+   */
+  testConnection?(config: TConnection): Promise<TestConnectionResult>;
+
+  /**
+   * Optional: Fetch dynamic options for cascading dropdowns.
+   * Called when subscription config has fields with x-options-resolver.
+   * Only applicable when connectionSchema is defined.
+   */
+  getConnectionOptions?(
+    params: GetConnectionOptionsParams
+  ): Promise<ConnectionOption[]>;
+}
+
+/**
+ * Registered provider with full namespace information.
+ */
+export interface RegisteredIntegrationProvider<
+  TConfig = unknown,
+  TConnection = unknown
+> extends IntegrationProvider<TConfig, TConnection> {
+  /** Fully qualified ID: {pluginId}.{id} */
+  qualifiedId: string;
+
+  /** Plugin that registered this provider */
+  ownerPluginId: string;
+}
+
+/**
+ * Registered integration event with full namespace information.
+ */
+export interface RegisteredIntegrationEvent<T = unknown> {
+  /** Fully qualified event ID: {pluginId}.{hookId} */
+  eventId: string;
+
+  /** Original hook reference */
+  hook: Hook<T>;
+
+  /** Plugin that registered this event */
+  ownerPluginId: string;
+
+  /** UI metadata */
+  displayName: string;
+  description?: string;
+  category?: string;
+
+  /** JSON Schema for payload (derived from Zod) */
+  payloadJsonSchema: Record<string, unknown>;
+
+  /** Original Zod schema */
+  payloadSchema: z.ZodType<T>;
+
+  /** Optional payload transformer */
+  transformPayload?: (payload: T) => Record<string, unknown>;
+}