{"_rev":"4-5c79178a28554ae15a8ee41d6373b870","time":{"created":"2024-10-19T07:16:59.042Z","modified":"2024-10-19T07:16:59.608Z","0.2.2":"2024-10-18T12:52:59.200Z","0.0.1":"2024-10-18T13:37:39.926Z","0.0.2":"2024-10-18T13:44:03.126Z","0.0.3":"2024-10-19T07:16:59.336Z"},"_id":"@cap-rp/notifications","name":"@cap-rp/notifications","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.3":{"name":"@cap-rp/notifications","version":"0.0.3","description":"CDS plugin providing integration to the SAP BTP Alert Notification Service.","repository":{"type":"git","url":"git+https://github.com/rohtash/notifications.git"},"author":{"name":"SAP SE","url":"https://www.sap.com"},"homepage":"https://cap.cloud.sap/","license":"SEE LICENSE IN LICENSE","main":"cds-plugin.js","peerDependencies":{"@sap/cds":">=8"},"dependencies":{"@sap-cloud-sdk/connectivity":"^3.13.0","@sap-cloud-sdk/http-client":"^3.13.0","@sap-cloud-sdk/util":"^3.13.0"},"devDependencies":{"jest":"^29.7.0","chai":"^4.3.10","@sap/cds":">=8","@sap/cds-dk":">=8"},"scripts":{"lint":"npx eslint .","test":"npx jest","test-with-coverage":"npx jest --coverage"},"cds":{"requires":{"destinations":true,"notifications":{"[development]":{"kind":"notify-to-console"},"[hybrid]":{"destination":"SAP_Notifications","kind":"notify-to-rest"},"[production]":{"destination":"SAP_Notifications","kind":"notify-to-rest"},"prefix":"$app-name","types":"srv/notification-types.json","outbox":true},"kinds":{"notify-to-console":{"impl":"@cap-rp/notifications/srv/notifyToConsole"},"notify-to-rest":{"impl":"@cap-rp/notifications/srv/notifyToRest"}}}},"_id":"@cap-rp/notifications@0.0.3","gitHead":"dce16f7a426952f406724e36a26a3d70f15668fb","bugs":{"url":"https://github.com/rohtash/notifications/issues"},"_nodeVersion":"22.10.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-DI94B5nwd4mL75DMigJDi9TAc5NIC6+4iJNMTmj1ruW6Lghk1LHyy0HX/qB1HSofcoW0CdvOY8TEgeU12bFy9w==","shasum":"a2b42be71d6d83df759a0723f9a7091321d1c89c","tarball":"https://registry.npmjs.org/@cap-rp/notifications/-/notifications-0.0.3.tgz","fileCount":10,"unpackedSize":45098,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDbjGfvX440XjszFRlqaOzzRwtB2HXw+bq9AwfWzxKxGgIhALrdCkVvsFu+9GBErhDhje1fSqqNHBH6cSIngFDzJ2xp"}]},"_npmUser":{"name":"rohtash.nitk","email":"rohtash.nitk@gmail.com"},"directories":{},"maintainers":[{"name":"rohtash.nitk","email":"rohtash.nitk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/notifications_0.0.3_1729322219142_0.6888777160485959"},"_hasShrinkwrap":false}},"maintainers":[{"name":"rohtash.nitk","email":"rohtash.nitk@gmail.com"}],"description":"CDS plugin providing integration to the SAP BTP Alert Notification Service.","homepage":"https://cap.cloud.sap/","repository":{"type":"git","url":"git+https://github.com/rohtash/notifications.git"},"author":{"name":"SAP SE","url":"https://www.sap.com"},"bugs":{"url":"https://github.com/rohtash/notifications/issues"},"license":"SEE LICENSE IN LICENSE","readme":"[![REUSE status](https://api.reuse.software/badge/github.com/cap-rp/notifications)](https://api.reuse.software/info/github.com/cap-rp/notifications)\n\n# Notifications Plugin\n\nThe `@cap-rp/notifications` package is a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) that provides support for publishing business notifications in SAP Build WorkZone.\n\n### Table of Contents\n\n- [Setup](#setup)\n- [Send Notifications](#send-notifications)\n- [Use Notification Types](#use-notification-types)\n- [API Reference](#api-reference)\n- [Test-drive Locally](#test-drive-locally)\n- [Run in Production](#run-in-production)\n- [Advanced Usage](#advanced-usage)\n- [Contributing](#contributing)\n- [Code of Conduct](#code-of-conduct)\n- [Licensing](#licensing)\n\n## Setup\n\nTo enable notifications, simply add this self-configuring plugin package to your project:\n\n```sh\n npm add @cap-rp/notifications\n```\n\nIn this guide, we use the [Incidents Management reference sample app](https://github.com/cap-rp/incidents-app) as the base, to publish notifications.\n\n## Send Notifications\n\nWith that you can use the NotificationService as any other CAP Service like so in you event handlers:\n\n```js\nconst alert = await cds.connect.to('notifications');\n```\n\nYou can use the following signature to send the simple notification with title and description\n\n```js\nalert.notify({\n recipients: [ ...supporters() ],\n priority: \"HIGH\",\n title: \"New high priority incident is assigned to you!\",\n description: \"Incident titled 'Engine overheating' created by 'customer X' with priority high is assigned to you!\"\n});\n```\n\n* **priority** - Priority of the notification, this argument is optional, it defaults to NEUTRAL\n* **description** - Subtitle for the notification, this argument is optional\n\n## Use Notification Types\n\n### 1. Add notification types\n\nIf you want to send custom notifications in your application, you can add the notification types in the `srv/notification-types.json` file.\n\nSample: If you want to send the notification when the incident is resolved, you can modify the `srv/notification-types.json` as below:\n\n```json\n [\n {\n \"NotificationTypeKey\": \"IncidentResolved\",\n \"NotificationTypeVersion\": \"1\",\n \"Templates\": [\n {\n \"Language\": \"en\",\n \"TemplatePublic\": \"Incident Resolved\",\n \"TemplateSensitive\": \"Incident '{{title}}' Resolved\",\n \"TemplateGrouped\": \"Incident Status Update\",\n \"TemplateLanguage\": \"mustache\",\n \"Subtitle\": \"Incident from '{{customer}}' resolved by {{user}}.\"\n }\n ]\n }\n ]\n```\n\n### 2. Use pre-defined types in your code like that:\n\n```js\n await alert.notify ('IncidentResolved', {\n recipients: [ customer.id ],\n data: {\n customer: customer.info,\n title: incident.title,\n user: cds.context.user.id,\n }\n })\n```\n\n## API Reference\n\n* **recipients** - List of the recipients, this argument is mandatory\n* **type** - Notification type key, this argument is mandatory\n* **priority** - Priority of the notification, this argument is optional, it defaults to NEUTRAL\n* **data** - A key-value pair that is used to fill a placeholder of the notification type template, this argument is optional\n\n## Test-drive Locally\nIn local environment, when you publish notification, it is mocked to publish the nofication to the console.\n\n\"Notify\n\n## Run in Production\n\n#### Notification Destination\n\nAs 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_Notifications` is added, you can modify the destination name that you are configuring.\n\n#### Integrate with SAP Build Work Zone\n\nOnce application is deployed and integrated with SAP Build Work Zone, you can see the notification under fiori notifications icon!\n\n\"Sample\n\n\n\n## Advanced Usage\n\n### Custom Notification Types Path\n\nNotifications plugin configures `srv/notification-types.json` as default notification types file. If you are using different file, you can update the file path in `cds.env.requires.notifications.types` \n\n### Custom Notification Type Prefix\n\nTo 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 `cds.env.requires.notifications.prefix` if required.\n\n### Low-level Notifications API\n\nYou can use these two signature to send the custom notification with pre-defined notification types.\n\n#### With pre-defined parameters\n\nBy using this approach you can send notifications with the predefined parameters - recipients, data, priority, type and other parameters listed in the [API documentation](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/developing-cloud-foundry-applications-with-notifications) \n\n```js\nalert.notify({\n recipients: [...supporters()],\n type: \"IncidentResolved\",\n priority: 'NEUTRAL',\n data: {\n customer: customer.info,\n title: incident.title,\n user: cds.context.user.id,\n },\n OriginId: \"Example Origin Id\",\n NotificationTypeVersion: \"1\",\n ProviderId: \"/SAMPLEPROVIDER\",\n ActorId: \"BACKENDACTORID\",\n ActorDisplayText: \"ActorName\",\n ActorImageURL: \"https://some-url\",\n NotificationTypeTimestamp: \"2022-03-15T09:58:42.807Z\",\n TargetParameters: [\n {\n \"Key\": \"string\",\n \"Value\": \"string\"\n }\n ]\n });\n```\n\n#### Passing the whole notification object\n\nBy using this approach you need to pass the whole notification object as described in the [API documentation](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/developing-cloud-foundry-applications-with-notifications)\n\n```js\nalert.notify({\n NotificationTypeKey: 'IncidentCreated',\n NotificationTypeVersion: '1',\n Priority: 'NEUTRAL',\n Properties: [\n {\n Key: 'name',\n IsSensitive: false,\n Language: 'en',\n Value: 'Engine overheating',\n Type: 'String'\n },\n {\n Key: 'customer',\n IsSensitive: false,\n Language: 'en',\n Value: 'Dave',\n Type: 'String'\n }\n ],\n Recipients: [{ RecipientId: \"supportuser1@mycompany.com\" },{ RecipientId: \"supportuser2@mycompany.com\" }]\n});\n```\n\n## Contributing\n\nThis project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-rp/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).\n\n## Code of Conduct\n\nWe 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.\n\n## Licensing\n\nCopyright 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-rp/change-tracking).\n","readmeFilename":"README.md"}