@backstage/plugin-notifications-node 0.2.19-next.1 → 0.2.19

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @backstage/plugin-notifications-node
 
+## 0.2.19
+
+### Patch Changes
+
+- 7e7ed57: A new extension point was added that can be used to modify how the users receiving notifications
+  are resolved. The interface passed to the extension point should only return complete user entity references
+  based on the notification target references and the excluded entity references. Note that the inputs are lists
+  of entity references that can be any entity kind, not just user entities.
+
+  Using this extension point will override the default behavior of resolving users with the
+  `DefaultNotificationRecipientResolver`.
+
+- Updated dependencies
+  - @backstage/catalog-client@1.12.0
+  - @backstage/backend-plugin-api@1.4.3
+  - @backstage/plugin-signals-node@0.1.24
+
 ## 0.2.19-next.1
 
 ### Patch Changes

package/dist/extensions.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"extensions.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\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 {\n  Notification,\n  NotificationProcessorFilters as NotificationProcessorFiltersCommon,\n} from '@backstage/plugin-notifications-common';\nimport { NotificationSendOptions } from './service';\n\n/**\n * Notification processors are used to modify the notification parameters or sending the notifications\n * to external systems.\n *\n * Notification modules should utilize the `notificationsProcessingExtensionPoint` to add new processors\n * to the system.\n *\n * Notification processing flow:\n *\n * 1. New notification send request is received\n * 2. For all notification processors registered, processOptions function is called to process the notification options\n * 3. Notification recipients are resolved from the options\n * 4. For each recipient, preProcess function is called to pre-process the notification\n * 5. Notification is saved to the database and sent to the Backstage UI\n * 6. For each recipient, postProcess function is called to post-process the notification\n *\n * @public\n */\nexport interface NotificationProcessor {\n  /**\n   * Human-readable name of this processor like Email, Slack, etc.\n   */\n  getName(): string;\n\n  /**\n   * Process the notification options.\n   *\n   * Can be used to override the default recipient resolving, sending the notification to an\n   * external service or modify other notification options necessary.\n   *\n   * processOptions functions are called only once for each notification before the recipient resolving,\n   * pre-process, sending and post-process of the notification.\n   *\n   * @param options - The original options to send the notification\n   */\n  processOptions?(\n    options: NotificationSendOptions,\n  ): Promise<NotificationSendOptions>;\n\n  /**\n   * Pre-process notification before sending it to Backstage UI.\n   *\n   * Can be used to send the notification to external services or to decorate the notification with additional\n   * information. The notification is saved to database and sent to Backstage UI after all pre-process functions\n   * have run. The notification options passed here are already processed by processOptions functionality.\n   *\n   * preProcess functions are called for each notification recipient individually or once for broadcast\n   * notification BEFORE the notification has been sent to the Backstage UI.\n   *\n   * @param notification - The notification to send\n   * @param options - The options to send the notification\n   * @returns The same notification or a modified version of it\n   */\n  preProcess?(\n    notification: Notification,\n    options: NotificationSendOptions,\n  ): Promise<Notification>;\n\n  /**\n   * Post process notification after sending it to Backstage UI.\n   *\n   * Can be used to send the notification to external services.\n   *\n   * postProcess functions are called for each notification recipient individually or once for\n   * broadcast notification AFTER the notification has been sent to the Backstage UI.\n   *\n   * @param notification - The notification to send\n   * @param options - The options to send the notification\n   */\n  postProcess?(\n    notification: Notification,\n    options: NotificationSendOptions,\n  ): Promise<void>;\n\n  /**\n   * notification filters are used to call the processor only in certain conditions\n   */\n  getNotificationFilters?(): NotificationProcessorFilters;\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\n/**\n * @public\n * @deprecated Please import from `@backstage/plugin-notifications-common` instead\n */\nexport type NotificationProcessorFilters = NotificationProcessorFiltersCommon;\n"],"names":["createExtensionPoint"],"mappings":";;;;AAkHO,MAAM,wCACXA,qCAAA,CAA4D;AAAA,EAC1D,EAAA,EAAI;AACN,CAAC;;;;"}
+{"version":3,"file":"extensions.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\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 {\n  Notification,\n  NotificationProcessorFilters as NotificationProcessorFiltersCommon,\n} from '@backstage/plugin-notifications-common';\nimport { NotificationSendOptions } from './service';\n\n/**\n * Notification processors are used to modify the notification parameters or sending the notifications\n * to external systems.\n *\n * Notification modules should utilize the `notificationsProcessingExtensionPoint` to add new processors\n * to the system.\n *\n * Notification processing flow:\n *\n * 1. New notification send request is received\n * 2. For all notification processors registered, processOptions function is called to process the notification options\n * 3. Notification recipients are resolved from the options\n * 4. For each recipient, preProcess function is called to pre-process the notification\n * 5. Notification is saved to the database and sent to the Backstage UI\n * 6. For each recipient, postProcess function is called to post-process the notification\n *\n * @public\n */\nexport interface NotificationProcessor {\n  /**\n   * Human-readable name of this processor like Email, Slack, etc.\n   */\n  getName(): string;\n\n  /**\n   * Process the notification options.\n   *\n   * Can be used to override the default recipient resolving, sending the notification to an\n   * external service or modify other notification options necessary.\n   *\n   * processOptions functions are called only once for each notification before the recipient resolving,\n   * pre-process, sending and post-process of the notification.\n   *\n   * @param options - The original options to send the notification\n   */\n  processOptions?(\n    options: NotificationSendOptions,\n  ): Promise<NotificationSendOptions>;\n\n  /**\n   * Pre-process notification before sending it to Backstage UI.\n   *\n   * Can be used to send the notification to external services or to decorate the notification with additional\n   * information. The notification is saved to database and sent to Backstage UI after all pre-process functions\n   * have run. The notification options passed here are already processed by processOptions functionality.\n   *\n   * preProcess functions are called for each notification recipient individually or once for broadcast\n   * notification BEFORE the notification has been sent to the Backstage UI.\n   *\n   * @param notification - The notification to send\n   * @param options - The options to send the notification\n   * @returns The same notification or a modified version of it\n   */\n  preProcess?(\n    notification: Notification,\n    options: NotificationSendOptions,\n  ): Promise<Notification>;\n\n  /**\n   * Post process notification after sending it to Backstage UI.\n   *\n   * Can be used to send the notification to external services.\n   *\n   * postProcess functions are called for each notification recipient individually or once for\n   * broadcast notification AFTER the notification has been sent to the Backstage UI.\n   *\n   * @param notification - The notification to send\n   * @param options - The options to send the notification\n   */\n  postProcess?(\n    notification: Notification,\n    options: NotificationSendOptions,\n  ): Promise<void>;\n\n  /**\n   * notification filters are used to call the processor only in certain conditions\n   */\n  getNotificationFilters?(): NotificationProcessorFilters;\n}\n\n/**\n * NotificationRecipientResolver interface is used to resolve the individual\n * users to receive the notification.\n *\n * The `resolveNotificationRecipients` is used to resolve notifications sent for\n * entity references, and it should return object with a list of user\n * entity references that should receive the notification. In case the function\n * returns other than user entity references, those are ignored.\n *\n * @public\n */\nexport interface NotificationRecipientResolver {\n  resolveNotificationRecipients(options: {\n    entityRefs: string[];\n    excludedEntityRefs?: string[];\n  }): Promise<{ userEntityRefs: string[] }>;\n}\n\n/**\n * @public\n */\nexport interface NotificationsProcessingExtensionPoint {\n  addProcessor(\n    ...processors: Array<NotificationProcessor | Array<NotificationProcessor>>\n  ): void;\n  setNotificationRecipientResolver(\n    resolver: NotificationRecipientResolver,\n  ): void;\n}\n\n/**\n * @public\n */\nexport const notificationsProcessingExtensionPoint =\n  createExtensionPoint<NotificationsProcessingExtensionPoint>({\n    id: 'notifications.processing',\n  });\n\n/**\n * @public\n * @deprecated Please import from `@backstage/plugin-notifications-common` instead\n */\nexport type NotificationProcessorFilters = NotificationProcessorFiltersCommon;\n"],"names":["createExtensionPoint"],"mappings":";;;;AAuIO,MAAM,wCACXA,qCAAA,CAA4D;AAAA,EAC1D,EAAA,EAAI;AACN,CAAC;;;;"}

package/dist/index.d.ts

@@ -112,11 +112,31 @@ interface NotificationProcessor {
      */
     getNotificationFilters?(): NotificationProcessorFilters;
 }
+/**
+ * NotificationRecipientResolver interface is used to resolve the individual
+ * users to receive the notification.
+ *
+ * The `resolveNotificationRecipients` is used to resolve notifications sent for
+ * entity references, and it should return object with a list of user
+ * entity references that should receive the notification. In case the function
+ * returns other than user entity references, those are ignored.
+ *
+ * @public
+ */
+interface NotificationRecipientResolver {
+    resolveNotificationRecipients(options: {
+        entityRefs: string[];
+        excludedEntityRefs?: string[];
+    }): Promise<{
+        userEntityRefs: string[];
+    }>;
+}
 /**
  * @public
  */
 interface NotificationsProcessingExtensionPoint {
     addProcessor(...processors: Array<NotificationProcessor | Array<NotificationProcessor>>): void;
+    setNotificationRecipientResolver(resolver: NotificationRecipientResolver): void;
 }
 /**
  * @public
@@ -128,4 +148,4 @@ declare const notificationsProcessingExtensionPoint: _backstage_backend_plugin_a
  */
 type NotificationProcessorFilters = NotificationProcessorFilters$1;
 
-export { DefaultNotificationService, type NotificationProcessor, type NotificationProcessorFilters, type NotificationRecipients, type NotificationSendOptions, type NotificationService, type NotificationServiceOptions, type NotificationsProcessingExtensionPoint, notificationService, notificationsProcessingExtensionPoint };
+export { DefaultNotificationService, type NotificationProcessor, type NotificationProcessorFilters, type NotificationRecipientResolver, type NotificationRecipients, type NotificationSendOptions, type NotificationService, type NotificationServiceOptions, type NotificationsProcessingExtensionPoint, notificationService, notificationsProcessingExtensionPoint };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-notifications-node",
-  "version": "0.2.19-next.1",
+  "version": "0.2.19",
   "description": "Node.js library for the notifications plugin",
   "backstage": {
     "role": "node-library",
@@ -37,18 +37,18 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "1.4.3-next.0",
-    "@backstage/catalog-client": "1.12.0-next.0",
-    "@backstage/catalog-model": "1.7.5",
-    "@backstage/plugin-notifications-common": "0.1.0",
-    "@backstage/plugin-signals-node": "0.1.24-next.0",
+    "@backstage/backend-plugin-api": "^1.4.3",
+    "@backstage/catalog-client": "^1.12.0",
+    "@backstage/catalog-model": "^1.7.5",
+    "@backstage/plugin-notifications-common": "^0.1.0",
+    "@backstage/plugin-signals-node": "^0.1.24",
     "knex": "^3.0.0",
     "uuid": "^11.0.0"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "1.9.0-next.1",
-    "@backstage/cli": "0.34.2-next.2",
-    "@backstage/test-utils": "1.7.11",
+    "@backstage/backend-test-utils": "^1.9.0",
+    "@backstage/cli": "^0.34.2",
+    "@backstage/test-utils": "^1.7.11",
     "msw": "^1.0.0"
   },
   "typesVersions": {