@backstage/plugin-notifications-node 0.0.1-next.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @backstage/plugin-notifications-node
+
+## 0.0.1-next.0
+
+### Patch Changes
+
+- fb8fc24: Initial notifications system for backstage
+- Updated dependencies
+  - @backstage/backend-common@0.21.0-next.2
+  - @backstage/plugin-signals-node@0.0.1-next.2
+  - @backstage/backend-plugin-api@0.6.10-next.2
+  - @backstage/plugin-notifications-common@0.0.1-next.0
+  - @backstage/catalog-client@1.6.0-next.1
+  - @backstage/catalog-model@1.4.4-next.0

package/README.md

@@ -0,0 +1,51 @@
+# @backstage/plugin-notifications-node
+
+Welcome to the Node.js library package for the notifications plugin!
+
+## Getting Started
+
+To be able to send notifications from other backend plugins, the `NotificationService` must be initialized for the
+environment. Add notification service to your `plugin.ts` as a dependency for init
+
+```ts
+import { notificationService } from '@backstage/plugin-notifications-node';
+
+export const myPlugin = createBackendPlugin({
+  pluginId: 'myPlugin',
+  register(env) {
+    env.registerInit({
+      deps: {
+        config: coreServices.rootConfig,
+        logger: coreServices.logger,
+        httpRouter: coreServices.httpRouter,
+        notificationService: notificationService,
+      },
+      async init({ config, logger, httpRouter, notificationService }) {
+        httpRouter.use(
+          await createRouter({
+            config,
+            logger,
+            permissions,
+            notificationService,
+          }),
+        );
+      },
+    });
+  },
+});
+```
+
+You also need to set up the `@backstage/plugin-notifications-backend` and `@backstage/plugin-notifications`
+to be able to show notifications in the UI.
+
+## Sending notifications
+
+To send notifications from backend plugin, use the `NotificationService::send` functionality. This function will
+save the notification and optionally signal the frontend to show the latest status for users.
+
+When sending notifications, you can specify the entity reference of the notification. If the entity reference is
+a user, the notification will be sent to only that user. If it's a group, the notification will be sent to all
+members of the group. If it's some other entity, the notification will be sent to the owner of that entity.
+
+If the notification has `scope` set and user already has notification with that scope, the existing notification
+will be updated with the new notification values and moved to inbox as unread.

package/dist/index.cjs.js

@@ -0,0 +1,73 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+class DefaultNotificationService {
+  constructor(discovery, tokenManager, pluginId) {
+    this.discovery = discovery;
+    this.tokenManager = tokenManager;
+    this.pluginId = pluginId;
+  }
+  static create({
+    tokenManager,
+    discovery,
+    pluginId
+  }) {
+    return new DefaultNotificationService(discovery, tokenManager, pluginId);
+  }
+  async send(notification) {
+    try {
+      const baseUrl = await this.discovery.getBaseUrl("notifications");
+      const { token } = await this.tokenManager.getToken();
+      const response = await fetch(`${baseUrl}/`, {
+        method: "POST",
+        body: JSON.stringify({
+          ...notification,
+          // TODO: Should retrieve this in the backend from service auth instead
+          origin: `plugin-${this.pluginId}`
+        }),
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          Authorization: `Bearer ${token}`
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Request failed with status ${response.status}`);
+      }
+    } catch (error) {
+      throw new Error(`Failed to send notifications: ${error}`);
+    }
+  }
+}
+
+const notificationService = backendPluginApi.createServiceRef({
+  id: "notifications.service",
+  scope: "plugin",
+  defaultFactory: async (service) => backendPluginApi.createServiceFactory({
+    service,
+    deps: {
+      discovery: backendPluginApi.coreServices.discovery,
+      tokenManager: backendPluginApi.coreServices.tokenManager,
+      pluginMetadata: backendPluginApi.coreServices.pluginMetadata
+    },
+    factory({ discovery, tokenManager, pluginMetadata }) {
+      return DefaultNotificationService.create({
+        discovery,
+        tokenManager,
+        pluginId: pluginMetadata.getId()
+      });
+    }
+  })
+});
+
+const notificationsProcessingExtensionPoint = backendPluginApi.createExtensionPoint({
+  id: "notifications.processing"
+});
+
+exports.DefaultNotificationService = DefaultNotificationService;
+exports.notificationService = notificationService;
+exports.notificationsProcessingExtensionPoint = notificationsProcessingExtensionPoint;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/service/DefaultNotificationService.ts","../src/lib.ts","../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { TokenManager } from '@backstage/backend-common';\nimport { NotificationService } from './NotificationService';\nimport { DiscoveryService } from '@backstage/backend-plugin-api';\nimport { NotificationPayload } from '@backstage/plugin-notifications-common';\n\n/** @public */\nexport type NotificationServiceOptions = {\n  discovery: DiscoveryService;\n  tokenManager: TokenManager;\n  pluginId: string;\n};\n\n/** @public */\nexport type NotificationRecipients = {\n  type: 'entity';\n  entityRef: string | string[];\n};\n\n// TODO: Support for broadcast messages\n//  | { type: 'broadcast' };\n\n/** @public */\nexport type NotificationSendOptions = {\n  recipients: NotificationRecipients;\n  payload: NotificationPayload;\n};\n\n/** @public */\nexport class DefaultNotificationService implements NotificationService {\n  private constructor(\n    private readonly discovery: DiscoveryService,\n    private readonly tokenManager: TokenManager,\n    private readonly pluginId: string,\n  ) {}\n\n  static create({\n    tokenManager,\n    discovery,\n    pluginId,\n  }: NotificationServiceOptions): DefaultNotificationService {\n    return new DefaultNotificationService(discovery, tokenManager, pluginId);\n  }\n\n  async send(notification: NotificationSendOptions): Promise<void> {\n    try {\n      const baseUrl = await this.discovery.getBaseUrl('notifications');\n      const { token } = await this.tokenManager.getToken();\n      const response = await fetch(`${baseUrl}/`, {\n        method: 'POST',\n        body: JSON.stringify({\n          ...notification,\n          // TODO: Should retrieve this in the backend from service auth instead\n          origin: `plugin-${this.pluginId}`,\n        }),\n        headers: {\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          Authorization: `Bearer ${token}`,\n        },\n      });\n\n      if (!response.ok) {\n        throw new Error(`Request failed with status ${response.status}`);\n      }\n    } catch (error) {\n      // TODO: Should not throw in optimal case, see BEP\n      throw new Error(`Failed to send notifications: ${error}`);\n    }\n  }\n}\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  coreServices,\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { DefaultNotificationService } from './service';\nimport { NotificationService } from './service/NotificationService';\n\n/** @public */\nexport const notificationService = createServiceRef<NotificationService>({\n  id: 'notifications.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        discovery: coreServices.discovery,\n        tokenManager: coreServices.tokenManager,\n        pluginMetadata: coreServices.pluginMetadata,\n      },\n      factory({ discovery, tokenManager, pluginMetadata }) {\n        return DefaultNotificationService.create({\n          discovery,\n          tokenManager,\n          pluginId: pluginMetadata.getId(),\n        });\n      },\n    }),\n});\n","/*\n * Copyright 2024 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport { Notification } from '@backstage/plugin-notifications-common';\n\n/**\n * @public\n */\nexport interface NotificationProcessor {\n  /**\n   * Decorate notification before sending it\n   *\n   * @param notification - The notification to decorate\n   * @returns The same notification or a modified version of it\n   */\n  decorate?(notification: Notification): Promise<Notification>;\n\n  /**\n   * Send notification using this processor.\n   *\n   * @param notification - The notification to send\n   */\n  send?(notification: Notification): Promise<void>;\n}\n\n/**\n * @public\n */\nexport interface NotificationsProcessingExtensionPoint {\n  addProcessor(\n    ...processors: Array<NotificationProcessor | Array<NotificationProcessor>>\n  ): void;\n}\n\n/**\n * @public\n */\nexport const notificationsProcessingExtensionPoint =\n  createExtensionPoint<NotificationsProcessingExtensionPoint>({\n    id: 'notifications.processing',\n  });\n"],"names":["createServiceRef","createServiceFactory","coreServices","createExtensionPoint"],"mappings":";;;;;;AA2CO,MAAM,0BAA0D,CAAA;AAAA,EAC7D,WAAA,CACW,SACA,EAAA,YAAA,EACA,QACjB,EAAA;AAHiB,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA,CAAA;AACA,IAAA,IAAA,CAAA,YAAA,GAAA,YAAA,CAAA;AACA,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA,CAAA;AAAA,GAChB;AAAA,EAEH,OAAO,MAAO,CAAA;AAAA,IACZ,YAAA;AAAA,IACA,SAAA;AAAA,IACA,QAAA;AAAA,GACyD,EAAA;AACzD,IAAA,OAAO,IAAI,0BAAA,CAA2B,SAAW,EAAA,YAAA,EAAc,QAAQ,CAAA,CAAA;AAAA,GACzE;AAAA,EAEA,MAAM,KAAK,YAAsD,EAAA;AAC/D,IAAI,IAAA;AACF,MAAA,MAAM,OAAU,GAAA,MAAM,IAAK,CAAA,SAAA,CAAU,WAAW,eAAe,CAAA,CAAA;AAC/D,MAAA,MAAM,EAAE,KAAM,EAAA,GAAI,MAAM,IAAA,CAAK,aAAa,QAAS,EAAA,CAAA;AACnD,MAAA,MAAM,QAAW,GAAA,MAAM,KAAM,CAAA,CAAA,EAAG,OAAO,CAAK,CAAA,CAAA,EAAA;AAAA,QAC1C,MAAQ,EAAA,MAAA;AAAA,QACR,IAAA,EAAM,KAAK,SAAU,CAAA;AAAA,UACnB,GAAG,YAAA;AAAA;AAAA,UAEH,MAAA,EAAQ,CAAU,OAAA,EAAA,IAAA,CAAK,QAAQ,CAAA,CAAA;AAAA,SAChC,CAAA;AAAA,QACD,OAAS,EAAA;AAAA,UACP,cAAgB,EAAA,kBAAA;AAAA,UAChB,MAAQ,EAAA,kBAAA;AAAA,UACR,aAAA,EAAe,UAAU,KAAK,CAAA,CAAA;AAAA,SAChC;AAAA,OACD,CAAA,CAAA;AAED,MAAI,IAAA,CAAC,SAAS,EAAI,EAAA;AAChB,QAAA,MAAM,IAAI,KAAA,CAAM,CAA8B,2BAAA,EAAA,QAAA,CAAS,MAAM,CAAE,CAAA,CAAA,CAAA;AAAA,OACjE;AAAA,aACO,KAAO,EAAA;AAEd,MAAA,MAAM,IAAI,KAAA,CAAM,CAAiC,8BAAA,EAAA,KAAK,CAAE,CAAA,CAAA,CAAA;AAAA,KAC1D;AAAA,GACF;AACF;;AC5DO,MAAM,sBAAsBA,iCAAsC,CAAA;AAAA,EACvE,EAAI,EAAA,uBAAA;AAAA,EACJ,KAAO,EAAA,QAAA;AAAA,EACP,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAqB,CAAA;AAAA,IACnB,OAAA;AAAA,IACA,IAAM,EAAA;AAAA,MACJ,WAAWC,6BAAa,CAAA,SAAA;AAAA,MACxB,cAAcA,6BAAa,CAAA,YAAA;AAAA,MAC3B,gBAAgBA,6BAAa,CAAA,cAAA;AAAA,KAC/B;AAAA,IACA,OAAQ,CAAA,EAAE,SAAW,EAAA,YAAA,EAAc,gBAAkB,EAAA;AACnD,MAAA,OAAO,2BAA2B,MAAO,CAAA;AAAA,QACvC,SAAA;AAAA,QACA,YAAA;AAAA,QACA,QAAA,EAAU,eAAe,KAAM,EAAA;AAAA,OAChC,CAAA,CAAA;AAAA,KACH;AAAA,GACD,CAAA;AACL,CAAC;;ACOM,MAAM,wCACXC,qCAA4D,CAAA;AAAA,EAC1D,EAAI,EAAA,0BAAA;AACN,CAAC;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { TokenManager } from '@backstage/backend-common';
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { DiscoveryService } from '@backstage/backend-plugin-api';
+import { NotificationPayload, Notification } from '@backstage/plugin-notifications-common';
+
+/** @public */
+interface NotificationService {
+    send(options: NotificationSendOptions): Promise<void>;
+}
+
+/** @public */
+type NotificationServiceOptions = {
+    discovery: DiscoveryService;
+    tokenManager: TokenManager;
+    pluginId: string;
+};
+/** @public */
+type NotificationRecipients = {
+    type: 'entity';
+    entityRef: string | string[];
+};
+/** @public */
+type NotificationSendOptions = {
+    recipients: NotificationRecipients;
+    payload: NotificationPayload;
+};
+/** @public */
+declare class DefaultNotificationService implements NotificationService {
+    private readonly discovery;
+    private readonly tokenManager;
+    private readonly pluginId;
+    private constructor();
+    static create({ tokenManager, discovery, pluginId, }: NotificationServiceOptions): DefaultNotificationService;
+    send(notification: NotificationSendOptions): Promise<void>;
+}
+
+/** @public */
+declare const notificationService: _backstage_backend_plugin_api.ServiceRef<NotificationService, "plugin">;
+
+/**
+ * @public
+ */
+interface NotificationProcessor {
+    /**
+     * Decorate notification before sending it
+     *
+     * @param notification - The notification to decorate
+     * @returns The same notification or a modified version of it
+     */
+    decorate?(notification: Notification): Promise<Notification>;
+    /**
+     * Send notification using this processor.
+     *
+     * @param notification - The notification to send
+     */
+    send?(notification: Notification): Promise<void>;
+}
+/**
+ * @public
+ */
+interface NotificationsProcessingExtensionPoint {
+    addProcessor(...processors: Array<NotificationProcessor | Array<NotificationProcessor>>): void;
+}
+/**
+ * @public
+ */
+declare const notificationsProcessingExtensionPoint: _backstage_backend_plugin_api.ExtensionPoint<NotificationsProcessingExtensionPoint>;
+
+export { DefaultNotificationService, NotificationProcessor, NotificationRecipients, NotificationSendOptions, NotificationService, NotificationServiceOptions, NotificationsProcessingExtensionPoint, notificationService, notificationsProcessingExtensionPoint };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@backstage/plugin-notifications-node",
+  "description": "Node.js library for the notifications plugin",
+  "version": "0.0.1-next.0",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.25.2-next.2",
+    "@backstage/test-utils": "^1.5.0-next.2",
+    "msw": "^1.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@backstage/backend-common": "^0.21.0-next.2",
+    "@backstage/backend-plugin-api": "^0.6.10-next.2",
+    "@backstage/catalog-client": "^1.6.0-next.1",
+    "@backstage/catalog-model": "^1.4.4-next.0",
+    "@backstage/plugin-notifications-common": "^0.0.1-next.0",
+    "@backstage/plugin-signals-node": "^0.0.1-next.2",
+    "knex": "^3.0.0",
+    "uuid": "^8.0.0"
+  }
+}