feat(adoption-insights): add time-saved backend enrichment and notifications

workspaces/adoption-insights/.changeset/time-saved-backend.md

@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-adoption-insights-backend': minor
+---
+
+Add time-saved backend enrichment, notification scheduler, and frequency preferences

workspaces/adoption-insights/packages/backend/package.json

@@ -33,6 +33,7 @@
     "@backstage/plugin-catalog-backend-module-logs": "^0.1.23",
     "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "^0.2.21",
     "@backstage/plugin-kubernetes-backend": "^0.21.5",
+    "@backstage/plugin-notifications-backend": "^0.6.7",
     "@backstage/plugin-permission-backend": "^0.7.13",
     "@backstage/plugin-permission-backend-module-allow-all-policy": "^0.2.20",
     "@backstage/plugin-permission-common": "^0.9.9",

workspaces/adoption-insights/packages/backend/src/index.ts

@@ -60,6 +60,8 @@ backend.add(import('@backstage/plugin-search-backend-module-techdocs'));
 // kubernetes
 backend.add(import('@backstage/plugin-kubernetes-backend'));
 
+backend.add(import('@backstage/plugin-notifications-backend'));
+
 backend.add(
   import('@red-hat-developer-hub/backstage-plugin-adoption-insights-backend'),
 );

workspaces/adoption-insights/plugins/adoption-insights-backend/migrations/20260716000000_notification_preferences.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+exports.up = function (knex) {
+  return knex.schema.createTable('notification_preferences', function (table) {
+    table.text('user_ref').primary();
+    table.text('frequency').notNullable().defaultTo('weekly');
+    table.timestamp('updated_at').defaultTo(knex.fn.now());
+  });
+};
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.dropTable('notification_preferences');
+};

workspaces/adoption-insights/plugins/adoption-insights-backend/package.json

@@ -38,6 +38,7 @@
     "@backstage/core-plugin-api": "^1.12.7",
     "@backstage/errors": "^1.3.1",
     "@backstage/plugin-catalog-node": "^2.2.2",
+    "@backstage/plugin-notifications-node": "^0.2.28",
     "@backstage/plugin-permission-common": "^0.9.9",
     "@red-hat-developer-hub/backstage-plugin-adoption-insights-common": "workspace:^",
     "express": "^4.17.1",

workspaces/adoption-insights/plugins/adoption-insights-backend/src/controllers/EventApiController.test.ts

@@ -26,8 +26,17 @@ import { QUERY_TYPES, QueryParams } from '../types/event-request';
 import type { AuditorServiceEvent } from '@backstage/backend-plugin-api';
 import { toEndOfDayUTC, toStartOfDayUTC } from '../utils/date';
 import { TechDocsCount, TopTechDocsCount } from '../types/event';
+import { Event } from '../models/Event';
 
 let controller: EventApiController;
+
+const mockCatalog = {
+  getEntityByRef: jest.fn(),
+} as any;
+
+const mockAuth = {
+  getOwnServiceCredentials: jest.fn().mockResolvedValue({}),
+} as any;
 let req: Partial<Request>;
 let res: Partial<Response>;
 
@@ -42,6 +51,7 @@ const mockEventDb = {
   getTopTechDocsViews: jest.fn(),
   getTopTemplateViews: jest.fn(),
   getTopCatalogEntitiesViews: jest.fn(),
+  getTimeSavedTotals: jest.fn(),
   getTechdocsMetadata: jest.fn(),
 } as unknown as jest.Mocked<EventDatabase>;
 
@@ -82,6 +92,8 @@ describe('trackEvents', () => {
       mockProcessor,
       mockServices.rootConfig.mock(),
       mockAuditor,
+      mockCatalog,
+      mockAuth,
     );
 
     mockProcessIncomingEvents = jest.spyOn(
@@ -228,6 +240,8 @@ describe('GetInsights', () => {
       mockProcessor,
       mockServices.rootConfig.mock(),
       mockAuditor,
+      mockCatalog,
+      mockAuth,
     );
 
     global.fetch = jest.fn().mockResolvedValue({} as any);
@@ -301,6 +315,7 @@ describe('GetInsights', () => {
     mockEventDb.getTopTemplateViews.mockResolvedValue({} as any);
     mockEventDb.getTopTechDocsViews.mockResolvedValue({} as any);
     mockEventDb.getTopCatalogEntitiesViews.mockResolvedValue({} as any);
+    mockEventDb.getTimeSavedTotals.mockResolvedValue({} as any);
 
     for (const type of QUERY_TYPES) {
       req.query = {
@@ -321,6 +336,7 @@ describe('GetInsights', () => {
     expect(mockEventDb.getTopTemplateViews).toHaveBeenCalled();
     expect(mockEventDb.getTopTechDocsViews).toHaveBeenCalled();
     expect(mockEventDb.getTopCatalogEntitiesViews).toHaveBeenCalled();
+    expect(mockEventDb.getTimeSavedTotals).toHaveBeenCalled();
   });
 
   it('should call getTechdocsMetadata method', async () => {
@@ -474,4 +490,159 @@ describe('GetInsights', () => {
 
     expect(res.status).toHaveBeenCalledWith(500);
   });
+
+  it('should return time_saved_totals data', async () => {
+    const timeSavedData = {
+      data: {
+        total_time_saved_minutes: 540,
+        templates: [
+          {
+            entityref: 'template:default/example-nodejs-template',
+            execution_count: 3,
+            time_saved_per_execution: 180,
+            total_time_saved_minutes: 540,
+          },
+        ],
+      },
+    };
+    mockEventDb.getTimeSavedTotals.mockResolvedValue(timeSavedData as any);
+
+    req.query = {
+      ...req.query,
+      type: 'time_saved_totals',
+    };
+
+    await controller.getInsights(
+      req as unknown as Request<{}, {}, {}, QueryParams>,
+      res as Response,
+    );
+
+    expect(mockEventDb.getTimeSavedTotals).toHaveBeenCalled();
+    expect(res.json).toHaveBeenCalledWith(timeSavedData);
+  });
+});
+
+describe('enrichScaffolderEvent', () => {
+  let enrichFn: (event: Event) => Promise<Event>;
+
+  beforeEach(() => {
+    controller = new EventApiController(
+      mockEventDb,
+      mockProcessor,
+      mockServices.rootConfig.mock(),
+      mockAuditor,
+      mockCatalog,
+      mockAuth,
+    );
+    enrichFn = (controller as any).enrichScaffolderEvent.bind(controller);
+    jest.clearAllMocks();
+  });
+
+  const makeScaffolderEvent = (entityRef: string): Event => {
+    const analyticsEvent: AnalyticsEvent = {
+      action: 'create',
+      subject: 'Task has been created',
+      context: {
+        routeRef: 'scaffolder',
+        pluginId: 'scaffolder',
+        extension: 'routeRef',
+        userName: 'user:default/guest',
+        userId: 'user:default/guest',
+        entityRef,
+      },
+    };
+    return new Event(analyticsEvent, false);
+  };
+
+  it('should enrich scaffolder event with time-saved value from catalog', async () => {
+    mockCatalog.getEntityByRef.mockResolvedValue({
+      metadata: {
+        annotations: { 'rhdh.redhat.com/time-saved': '180' },
+      },
+    });
+
+    const event = makeScaffolderEvent('template:default/my-template');
+    const result = await enrichFn(event);
+
+    expect(result.value).toBe(180);
+    expect(mockCatalog.getEntityByRef).toHaveBeenCalledWith(
+      'template:default/my-template',
+      expect.any(Object),
+    );
+  });
+
+  it('should skip non-scaffolder events', async () => {
+    const analyticsEvent: AnalyticsEvent = {
+      action: 'navigate',
+      subject: 'some page',
+      context: {
+        routeRef: 'catalog',
+        pluginId: 'catalog',
+        extension: 'routeRef',
+      },
+    };
+    const event = new Event(analyticsEvent, false);
+    const result = await enrichFn(event);
+
+    expect(result.value).toBeUndefined();
+    expect(mockCatalog.getEntityByRef).not.toHaveBeenCalled();
+  });
+
+  it('should return event unchanged when entity is not found', async () => {
+    mockCatalog.getEntityByRef.mockResolvedValue(null);
+
+    const event = makeScaffolderEvent('template:default/missing');
+    const result = await enrichFn(event);
+
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should return event unchanged when annotation is missing', async () => {
+    mockCatalog.getEntityByRef.mockResolvedValue({
+      metadata: { annotations: {} },
+    });
+
+    const event = makeScaffolderEvent('template:default/no-annotation');
+    const result = await enrichFn(event);
+
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should return event unchanged when annotation is not a positive number', async () => {
+    mockCatalog.getEntityByRef.mockResolvedValue({
+      metadata: {
+        annotations: { 'rhdh.redhat.com/time-saved': '-10' },
+      },
+    });
+
+    const event = makeScaffolderEvent('template:default/negative');
+    const result = await enrichFn(event);
+
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should handle catalog errors gracefully', async () => {
+    mockCatalog.getEntityByRef.mockRejectedValue(new Error('catalog down'));
+
+    const event = makeScaffolderEvent('template:default/error');
+    const result = await enrichFn(event);
+
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should parse context when stored as JSON string', async () => {
+    mockCatalog.getEntityByRef.mockResolvedValue({
+      metadata: {
+        annotations: { 'rhdh.redhat.com/time-saved': '60' },
+      },
+    });
+
+    const event = makeScaffolderEvent('template:default/stringified');
+    (event as any).context = JSON.stringify({
+      entityRef: 'template:default/stringified',
+    });
+    const result = await enrichFn(event);
+
+    expect(result.value).toBe(60);
+  });
 });