Merge pull request #1 from cap-js/MVP

create notification types from the file and publish from plugin

Author: AnmolBinani

.github/workflows/node.js.yml

@@ -0,0 +1,30 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main", "MVP" ]
+  pull_request:
+    branches: [ "main", "MVP" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm i
+    - run: npm run test-with-coverage

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+    "tabWidth": 2,
+    "useTabs": false,
+    "printWidth": 200,
+    "trailingComma" : "none"
+}

README.md

@@ -1,2 +1,163 @@
-# alert-notification
+
+The `@cap-js/notifications` package is a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) providing out-of-the box support for publishing business notifications.
+
+### Table of Contents
+
+- [Setup](#setup)
+- [Usage](#usage)
+  - [Update Notification Configuration](#update-notification-configuration)
+    - [Notification Destination](#notification-destination)
+    - [Notification Types Path](#notification-types-path)
+    - [Notification Type Prefix](#notification-type-prefix)
+  - [Add Notification Types](#add-notification-types)
+  - [Update handlers to publish notification](#update-handlers-to-publish-notification)
+    - [Simple Notificaiton with title](#simple-notificaiton-with-title)
+    - [Simple Notificaiton with title & description](#simple-notificaiton-with-title)
+    - [Custom Notifications with notification types](#simple-notificaiton-with-title)
+  - [Sample Application with notifications](#sample-application-with-notifications)
+    - [In Local Environment](#in-local-environment)
+    - [In Production Environment](#in-production-environment)
+- [Contributing](#contributing)
+  - [Code of Conduct](#code-of-conduct)
+- [Licensing](#licensing)
+
+## Setup
+
+To enable notifications, simply add this self-configuring plugin package to your project:
+
+```sh
+ cds add notifications 
+```
+
+<img width="1300" alt="cds add notifications" style="border-radius:0.5rem" src="_assets/cdsAddNotifications.gif">
+
+## Usage
+
+In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base, to publish notifications.
+
+### Update Notification Configuration
+
+`cds add notifications` will add default configurations for notifications in the `package.json` file.
+
+<img width="1300" alt="Default Notification config" style="border-radius:0.5rem" src="_assets/packageJsonConfig.gif">
+
+#### **Notification Destination**
+
+As a pre-requisite to publish the notification, you need to have a [destination](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/enabling-notifications-for-custom-apps-on-sap-btp-cloud-foundry#configure-the-destination-to-the-notifications-service) configured to publish the notification. In the `package.json` by default destination name `SAP_Notification` is added, you can modify the destination name that you are configuring.
+
+#### **Notification Types Path**
+
+When you run `cds add notifications`, it will add `notificationstype.json` file with template for a notification type in the project root folder.  You can add the notification types in the `notificationtype.json` file for sending the custom notification types.
+
+#### **Notification Type Prefix**
+
+To make notification types unique to the application, prefix is added to the type key. By default, `application name` is added as the prefix. You can update the `prefix` if required.
+
+### Add Notification Types
+
+If you want to send custom notifications in your application, you can add the notification types in the `notificationtype.json` file.
+
+Sample: If you want to send the notification when the new incident is reported, you can modify the `notificationtypes.json` as below:
+
+```jsonc
+[
+  {
+    "NotificationTypeKey": "IncidentReported",
+    "NotificationTypeVersion": "1",
+    "Templates": [
+      {
+        "Language": "en",
+        "TemplatePublic": "Incident Reported",
+        "TemplateSensitive": "Incident '{{name}}' Reported",
+        "TemplateGrouped": "New Incidents",
+        "TemplateLanguage": "mustache",
+        "Subtitle": "Incident '{{name}}' reported by '{{customer}}'."
+      }
+    ]
+  }
+]
+```
+
+### Update handlers to publish notification
+
+In the handler files, connect to the notifications plugin by:
+   
+```js
+const alert = await cds.connect.to('notifications');
+```
+
+#### **Simple Notificaiton with title**
+You can use the following signature to send the simple notification with title
+```js
+alert.notify({
+  recipients: recipients,
+  priority: priority,
+  title: title
+});
+```
+#### **Simple Notificaiton with title & description**
+You can use the following signature to send the simple notification with title and description
+```js
+alert.notify({
+  recipients: recipients,
+  priority: priority,
+  title: title,
+  description: description
+});
+```
+#### **Custom Notifications with notification types**
+You can use the following signature to send the custom notification with pre-defined notification types.
+```js
+alert.notify({
+  NotificationTypeKey: 'IncidentCreated',
+  NotificationTypeVersion: '1',
+  Priority: 'NEUTRAL',
+  Properties: [
+    {
+      Key: 'name',
+      IsSensitive: false,
+      Language: 'en',
+      Value: 'Engine overheating',
+      Type: 'String'
+    },
+    {
+      Key: 'customer',
+      IsSensitive: false,
+      Language: 'en',
+      Value: 'John',
+      Type: 'String'
+    }
+  ],
+  Recipients: recipients
+});
+```
+
+### Sample Application with notifications
+
+#### **In Local Environment**
+In local environment, when you publish notification, it is mocked to publish the nofication to the console.
+
+<img width="1300" alt="Notify to console" style="border-radius:0.5rem;padding:1rem;background:rgb(24 24 24)" src="_assets/notifyToConsole.png">
+
+#### **In Production Environment**
+
+Once application is deployed and integrated with SAP Build Work Zone, you can see the notification under fiori notifications icon!
+
+<img width="1300" alt="Sample Application Demo" style="border-radius:0.5rem;" src="_assets/incidentsNotificationDemo.gif">
+
+## Contributing
+
+This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/change-tracking/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
+
+
+### Code of Conduct
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
+
+
+## Licensing
+
+Copyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js/change-tracking).
+
+
 

_assets/cdsAddNotifications.gif

@@ -0,0 +1,24 @@
+const cds = require("@sap/cds");
+const build = require('@sap/cds-dk/lib/build')
+const { validateNotificationTypes, readFile } = require("./lib/utils");
+const { createNotificationTypesMap } = require("./lib/notificationTypes");
+const { setGlobalLogLevel } = require("@sap-cloud-sdk/util");
+
+// register build plugin
+build.register('notifications', { impl: '@cap-js/notifications/lib/build', description: 'Notifications build plugin', taskDefaults: { src: cds.env.folders.srv } });
+
+cds.once("served", async () => {
+  setGlobalLogLevel("error");
+  const profiles = cds.env.profiles ?? [];
+  const production = profiles.includes("production");
+
+  // read notification types
+  const notificationTypes = readFile(cds.env.requires?.notifications?.types);
+
+  if (validateNotificationTypes(notificationTypes)) {
+    if (!production) {
+      const notificationTypesMap = createNotificationTypesMap(notificationTypes, true);
+      cds.notifications = { local: { types: notificationTypesMap } };
+    }
+  }
+});

_assets/incidentsNotificationDemo.gif

@@ -0,0 +1,9 @@
+// FIXME: should not be necessary
+process.env.CDS_ENV = 'better-sqlite'
+
+const config = {
+  testTimeout: 42222,
+  testMatch: ['**/*.test.js']
+}
+
+module.exports = config

_assets/notifyToConsole.png

@@ -0,0 +1,19 @@
+const cds = require('@sap/cds')
+const { BuildPlugin } = require('@sap/cds-dk/lib/build')
+
+const { copy, exists, path } = cds.utils
+
+module.exports = class NotificationsBuildPlugin extends BuildPlugin {
+
+  static hasTask() {
+    const notificationTypesFile = cds.env.requires?.notifications?.types;
+    return notificationTypesFile === undefined ? false : exists(notificationTypesFile);
+  }
+
+  async build() {
+    if(exists(cds.env.requires.notifications.types)) {
+      const fileName = path.basename(cds.env.requires.notifications.types);
+      await copy(cds.env.requires.notifications.types).to(path.join(this.task.dest, fileName));
+    }
+  }
+}