@checkstack/notification-backstage-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @checkstack/notification-backstage-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- 97c5a6b: Add Backstage notification provider plugin
+
+  This new plugin enables forwarding Checkstack notifications to external Backstage instances via the Backstage Notifications REST API.
+
+  **Features:**
+
+  - Admin configuration for Backstage instance URL and API token
+  - User configuration for custom entity reference (e.g., `user:default/john.doe`)
+  - Automatic entity reference generation from user email when not specified
+  - Severity mapping from Checkstack importance levels to Backstage severity
+  - Full admin and user setup instructions
+
+### Patch Changes
+
+- Updated dependencies [97c5a6b]
+- Updated dependencies [8e43507]
+  - @checkstack/backend-api@0.2.0
+  - @checkstack/common@0.1.0
+  - @checkstack/notification-backend@0.0.4

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/notification-backstage-backend",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/notification-backend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "bun:test";
+import {
+  backstageConfigSchemaV1,
+  userConfigSchemaV1,
+  mapImportanceToSeverity,
+} from "./index";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Config Schema Tests
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+describe("backstageConfigSchemaV1", () => {
+  it("should accept valid config with all fields", () => {
+    const config = {
+      baseUrl: "https://backstage.example.com",
+      token: "my-secret-token",
+      defaultEntityPrefix: "user:development/",
+    };
+
+    const result = backstageConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.baseUrl).toBe("https://backstage.example.com");
+      expect(result.data.token).toBe("my-secret-token");
+      expect(result.data.defaultEntityPrefix).toBe("user:development/");
+    }
+  });
+
+  it("should accept config with only required fields (all optional)", () => {
+    const config = {};
+
+    const result = backstageConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.defaultEntityPrefix).toBe("user:default/");
+    }
+  });
+
+  it("should reject invalid URL", () => {
+    const config = {
+      baseUrl: "not-a-valid-url",
+      token: "my-token",
+    };
+
+    const result = backstageConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(false);
+  });
+
+  it("should use default entity prefix when not provided", () => {
+    const config = {
+      baseUrl: "https://backstage.example.com",
+      token: "my-token",
+    };
+
+    const result = backstageConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.defaultEntityPrefix).toBe("user:default/");
+    }
+  });
+});
+
+describe("userConfigSchemaV1", () => {
+  it("should accept valid user config with entity reference", () => {
+    const config = {
+      entityRef: "user:default/john.doe",
+    };
+
+    const result = userConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.entityRef).toBe("user:default/john.doe");
+    }
+  });
+
+  it("should accept empty user config", () => {
+    const config = {};
+
+    const result = userConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+
+  it("should accept group entity references", () => {
+    const config = {
+      entityRef: "group:default/team-platform",
+    };
+
+    const result = userConfigSchemaV1.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.entityRef).toBe("group:default/team-platform");
+    }
+  });
+});
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Severity Mapping Tests
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+describe("mapImportanceToSeverity", () => {
+  it("should map 'info' to 'normal'", () => {
+    expect(mapImportanceToSeverity("info")).toBe("normal");
+  });
+
+  it("should map 'warning' to 'high'", () => {
+    expect(mapImportanceToSeverity("warning")).toBe("high");
+  });
+
+  it("should map 'critical' to 'critical'", () => {
+    expect(mapImportanceToSeverity("critical")).toBe("critical");
+  });
+});
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Strategy Send Function Tests
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+describe("backstageStrategy.send", () => {
+  // Note: Full integration tests would require mocking the plugin registration
+  // For now, we test the exported utility functions and schema validation
+  // The send function is tested indirectly through proper config validation
+
+  it("should validate that baseUrl and token are required for sending", () => {
+    // This test verifies the config validation logic
+    // The send function checks for baseUrl and token presence
+    const emptyConfig = backstageConfigSchemaV1.parse({});
+    expect(emptyConfig.baseUrl).toBeUndefined();
+    expect(emptyConfig.token).toBeUndefined();
+    // Strategy will return error when these are missing
+  });
+
+  it("should build correct entity ref from email when user config is empty", () => {
+    // Test the entity ref construction logic
+    const prefix = "user:default/";
+    const email = "john.doe@example.com";
+    const emailPart = email.split("@")[0]?.toLowerCase() ?? "";
+    const expectedRef = `${prefix}${emailPart}`;
+
+    expect(expectedRef).toBe("user:default/john.doe");
+  });
+
+  it("should strip trailing slash from baseUrl", () => {
+    const baseUrl = "https://backstage.example.com/";
+    const normalizedUrl = baseUrl.replace(/\/$/, "");
+    expect(normalizedUrl).toBe("https://backstage.example.com");
+  });
+});

package/src/index.ts

@@ -0,0 +1,292 @@
+import {
+  createBackendPlugin,
+  type NotificationStrategy,
+  Versioned,
+  configString,
+  markdownToPlainText,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Admin Configuration Schema
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Backstage configuration schema with versioning support.
+ * Admins configure the Backstage instance URL and access token.
+ */
+const backstageConfigSchemaV1 = z.object({
+  baseUrl: configString({})
+    .url()
+    .optional()
+    .describe(
+      "Backstage instance base URL (e.g., https://backstage.example.com)"
+    ),
+  token: configString({ "x-secret": true })
+    .optional()
+    .describe("Backstage API access token for external service authentication"),
+  defaultEntityPrefix: configString({})
+    .optional()
+    .default("user:default/")
+    .describe("Default entity prefix for user mapping (e.g., user:default/)"),
+});
+
+type BackstageConfig = z.infer<typeof backstageConfigSchemaV1>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// User Configuration Schema
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Per-user configuration for Backstage notifications.
+ * Users can specify their entity reference in Backstage.
+ */
+const userConfigSchemaV1 = z.object({
+  entityRef: configString({})
+    .optional()
+    .describe("Your Backstage entity reference (e.g., user:default/john.doe)"),
+});
+
+type BackstageUserConfig = z.infer<typeof userConfigSchemaV1>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Backstage Configuration
+
+Connect Checkstack to your Backstage instance to forward notifications.
+
+### Prerequisites
+
+1. Your Backstage instance must have the **notifications plugin** installed
+2. You need to enable **external access** for the notifications API
+
+### Setup Steps
+
+1. Enable external service access in your Backstage instance
+2. Generate a static access token (see [Backstage docs](https://backstage.io/docs/auth/service-to-service-auth))
+3. Enter your Backstage instance URL (e.g., \`https://backstage.example.com\`)
+4. Paste the access token in the **Token** field
+
+> **Note**: The default entity prefix is used when users don't specify their own entity reference.
+`.trim();
+
+const userInstructions = `
+## Connect to Backstage
+
+Receive Checkstack notifications in your Backstage notification inbox.
+
+### Find Your Entity Reference
+
+Your entity reference is how Backstage identifies you. It typically follows the format:
+- \`user:default/your.username\`
+- \`user:default/your-email\`
+
+You can find this in your Backstage profile or catalog.
+
+> **Tip**: If you leave this blank, the system will try to use your email with the default prefix.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Severity Mapping
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Maps Checkstack importance levels to Backstage severity levels.
+ */
+function mapImportanceToSeverity(
+  importance: "info" | "warning" | "critical"
+): "low" | "normal" | "high" | "critical" {
+  switch (importance) {
+    case "info": {
+      return "normal";
+    }
+    case "warning": {
+      return "high";
+    }
+    case "critical": {
+      return "critical";
+    }
+    default: {
+      return "normal";
+    }
+  }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Backstage Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const backstageStrategy: NotificationStrategy<
+  BackstageConfig,
+  BackstageUserConfig,
+  undefined
+> = {
+  id: "backstage",
+  displayName: "Backstage",
+  description: "Send notifications to your Backstage developer portal",
+  icon: "LayoutDashboard",
+
+  config: new Versioned({
+    version: 1,
+    schema: backstageConfigSchemaV1,
+  }),
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: userConfigSchemaV1,
+  }),
+
+  contactResolution: { type: "user-config", field: "entityRef" },
+
+  adminInstructions,
+  userInstructions,
+
+  async send({
+    contact,
+    notification,
+    strategyConfig,
+    userConfig,
+    user,
+    logger,
+  }) {
+    // Validate required admin config
+    if (!strategyConfig.baseUrl || !strategyConfig.token) {
+      return {
+        success: false,
+        error:
+          "Backstage is not configured. Please configure baseUrl and token.",
+      };
+    }
+
+    // Determine the entity reference
+    let entityRef = userConfig?.entityRef;
+
+    // Fallback: construct from email using default prefix
+    if (!entityRef && user.email) {
+      const prefix = strategyConfig.defaultEntityPrefix ?? "user:default/";
+      // Convert email to entity-safe format (replace @ and . with common patterns)
+      const emailPart = user.email.split("@")[0]?.toLowerCase() ?? "";
+      entityRef = `${prefix}${emailPart}`;
+    }
+
+    // Still no entity ref? Use the contact as-is (might be set by system)
+    if (!entityRef) {
+      entityRef = contact;
+    }
+
+    if (!entityRef) {
+      return {
+        success: false,
+        error: "No Backstage entity reference configured for this user.",
+      };
+    }
+
+    // Build the notification payload
+    const description = notification.body
+      ? markdownToPlainText(notification.body)
+      : undefined;
+
+    const payload = {
+      recipients: {
+        type: "entity" as const,
+        entityRef,
+      },
+      payload: {
+        title: notification.title,
+        ...(description && { description }),
+        ...(notification.action?.url && { link: notification.action.url }),
+        severity: mapImportanceToSeverity(notification.importance),
+        ...(notification.type && { topic: notification.type }),
+      },
+    };
+
+    // Send to Backstage
+    const url = `${strategyConfig.baseUrl.replace(
+      /\/$/,
+      ""
+    )}/api/notifications/notifications`;
+
+    try {
+      logger?.debug?.("Sending notification to Backstage", {
+        url,
+        entityRef,
+        title: notification.title,
+      });
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${strategyConfig.token}`,
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger?.error?.("Backstage API error", {
+          status: response.status,
+          error: errorText,
+        });
+        return {
+          success: false,
+          error: `Backstage API error: ${response.status} - ${errorText}`,
+        };
+      }
+
+      // Try to extract notification ID from response
+      let externalId: string | undefined;
+      try {
+        const result = (await response.json()) as { id?: string };
+        externalId = result.id;
+      } catch {
+        // Response might not be JSON, that's ok
+      }
+
+      logger?.info?.("Notification sent to Backstage", {
+        entityRef,
+        externalId,
+      });
+
+      return {
+        success: true,
+        ...(externalId && { externalId }),
+      };
+    } catch (error) {
+      logger?.error?.("Failed to send notification to Backstage", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint
+    );
+
+    // Register the Backstage strategy with our plugin metadata
+    extensionPoint.addStrategy(backstageStrategy, pluginMetadata);
+  },
+});
+
+// Export for testing
+export { backstageConfigSchemaV1, userConfigSchemaV1, mapImportanceToSeverity };
+export type { BackstageConfig, BackstageUserConfig };

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Backstage Notification backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "notification-backstage",
+});

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}