{"id":13464995,"url":"https://github.com/notifme/notifme-sdk","last_synced_at":"2025-03-25T13:32:54.240Z","repository":{"id":37742977,"uuid":"99807438","full_name":"notifme/notifme-sdk","owner":"notifme","description":"A Node.js library to send all kinds of transactional notifications.","archived":false,"fork":false,"pushed_at":"2024-10-29T10:41:29.000Z","size":2328,"stargazers_count":1944,"open_issues_count":12,"forks_count":150,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-10-29T12:35:30.306Z","etag":null,"topics":["email","hacktoberfest","multi-provider-strategies","nodejs","notification","push-notifications","sms","strategy","transactional-notifications","webpush"],"latest_commit_sha":null,"homepage":"https://notifme.github.io/www/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notifme.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-09T12:46:11.000Z","updated_at":"2024-10-29T10:41:40.000Z","dependencies_parsed_at":"2024-01-13T10:42:01.252Z","dependency_job_id":"913cd014-4347-43de-82c7-1cd972071e32","html_url":"https://github.com/notifme/notifme-sdk","commit_stats":{"total_commits":235,"total_committers":17,"mean_commits":"13.823529411764707","dds":"0.31063829787234043","last_synced_commit":"1a70dab409085dc0781f02c21d63354860d96ed0"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notifme%2Fnotifme-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notifme%2Fnotifme-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notifme%2Fnotifme-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notifme%2Fnotifme-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notifme","download_url":"https://codeload.github.com/notifme/notifme-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245449531,"owners_count":20617187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","hacktoberfest","multi-provider-strategies","nodejs","notification","push-notifications","sms","strategy","transactional-notifications","webpush"],"created_at":"2024-07-31T14:00:54.492Z","updated_at":"2025-03-25T13:32:53.913Z","avatar_url":"https://github.com/notifme.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","🤖 AI \u0026 Machine Learning"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.notif.me\"\u003e\n    \u003cimg alt=\"Notif.me\" src=\"https://notifme.github.io/notifme-sdk/img/logo.png\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A Node.js library to send all kinds of transactional notifications.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/notifme-sdk\"\u003e\u003cimg alt=\"npm-status\" src=\"https://img.shields.io/npm/v/notifme-sdk.svg?style=flat\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codeclimate.com/github/notifme/notifme-sdk/test_coverage\"\u003e\u003cimg src=\"https://api.codeclimate.com/v1/badges/2d2cc6d915094ddb50b7/test_coverage\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/notifme/notifme-sdk/blob/master/LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT_License-blue.svg?style=flat\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://slackin-notifme.now.sh\"\u003e\u003cimg alt=\"slack\" src=\"https://img.shields.io/badge/Slack-Join_us!-e01563.svg?style=flat\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n- [Features](#features)\n- [Getting started](#getting-started)\n- [How to use](#how-to-use)\n  - [1. General options](#1-general-options)\n  - [2. Providers](#2-providers)\n  - [3. Custom channels](#3-custom-channels)\n  - [4. Send a notification](#4-send-a-notification)\n  - [5. In production](#5-in-production)\n- [Contributing](#contributing)\n- [Need help? Found a bug?](#need-help-found-a-bug)\n- [Related Projects](#related-projects)\n\n## Features\n\n* **Easy channel integration** — Want to start sending `emails` | `SMS` | `pushes` | `webpushes` | `slack`? Do so in no time!\n\n* **Unique documentation** — Don't look everywhere for the parameters you need to pass, just do it once. **Switching provider becomes a no-brainer**.\n\n* **Multiple providers strategies** — Want to use more than one provider? Use `fallback` and `round-robin` strategies out of the box.\n\n* **Tools for local testing** — Run a catcher locally to intercept all your notifications and display them in a web interface.\n\n* **MIT license** — Use it like you want.\n\n## Getting Started\n\n```shell\n$ yarn add notifme-sdk\n```\n\n```javascript\nimport NotifmeSdk from 'notifme-sdk'\n\nconst notifmeSdk = new NotifmeSdk({}) // empty config = all providers are set to console.log\nnotifmeSdk\n  .send({sms: {from: '+15000000000', to: '+15000000001', text: 'Hello, how are you?'}})\n  .then(console.log)\n```\n\n:sparkles: Congratulations, you should see the following lines in your console:\n\n![Getting started SMS log](https://notifme.github.io/notifme-sdk/img/getting-started-sms-log.png)\n\u003cbr\u003e\u003cbr\u003e\n\n### [Recommended] Setup Notification Catcher for your local tests\n\n[Notification Catcher](https://github.com/notifme/catcher) is a web interface for viewing and testing notifications during development.\n\n```shell\n$ yarn add --dev notification-catcher\n$ yarn run notification-catcher\n```\n\n```javascript\nimport NotifmeSdk from 'notifme-sdk'\n\nconst notifmeSdk = new NotifmeSdk({\n  useNotificationCatcher: true // \u003c= this sends all your notifications to the catcher running on port 1025\n})\nnotifmeSdk\n  .send({sms: {from: '+15000000000', to: '+15000000001', text: 'Hello, how are you?'}})\n  .then(console.log)\n```\n\n:heart_eyes_cat: Open [http://localhost:1080](http://localhost:1080) on your favorite browser, you should see the notification:\n\n![Getting started SMS catcher](https://notifme.github.io/notifme-sdk/img/getting-started-sms-catcher.png)\n\n#### Custom connection settings\n\nIf you have the Notification Catcher running on a custom port, domain, or you need to change any other connection setting, set the environment variable `NOTIFME_CATCHER_OPTIONS` with your [custom connection smtp url](https://nodemailer.com/smtp/).\n\n```shell\n$ # Example\n$ NOTIFME_CATCHER_OPTIONS=smtp://127.0.0.1:3025?ignoreTLS=true node your-script-using-notifme.js\n```\n\n## How to use\n\n- [1. General options](#1-general-options)\n- [2. Providers](#2-providers)\n- [3. Custom channels](#3-custom-channels)\n- [4. Send a notification](#4-send-a-notification)\n- [5. In production](#5-in-production)\n\n### 1. General options\n\n```javascript\nnew NotifmeSdk({\n  channels: ..., // Object\n  useNotificationCatcher: ... // boolean\n})\n```\n\n| Option name | Required | Type | Description |\n| --- | --- | --- | --- |\n| `channels` | `false` | `Object` | Define `providers` (`Array`) and `multiProviderStrategy` (`string`) for each channel (email, sms, push, webpush, slack).\u003cbr\u003e\u003cbr\u003eSee all details below: [2. Providers](#2-providers). |\n| `useNotificationCatcher` | `false` | `boolean` | If true, all your notifications are sent to the catcher running on localhost:1025 (channels option will be completely ignored!) |\n\n#### Complete examples\n\n```javascript\n// Env: development\nnew NotifmeSdk({\n  useNotificationCatcher: true\n})\n\n// Env: production\nnew NotifmeSdk({\n  channels: {\n    email: {\n      // If \"Provider1\" fails, use \"Provider2\"\n      multiProviderStrategy: 'fallback',\n      providers: [{\n        type: 'Provider1',\n        // ...credentials\n      }, {\n        type: 'Provider2',\n        // ...credentials\n      }]\n    },\n    sms: {\n      // Use \"Provider1\" and \"Provider2\" in turns (and fallback if error)\n      multiProviderStrategy: 'roundrobin',\n      providers: [{\n        type: 'Provider1',\n        // ...credentials\n      }, {\n        type: 'Provider2',\n        // ...credentials\n      }]\n    }\n  }\n})\n```\n\n#### HTTP proxy option\n\nIf you want to use a HTTP proxy, set an environment variable `NOTIFME_HTTP_PROXY`.\n\n```shell\n$ # Example\n$ NOTIFME_HTTP_PROXY=http://127.0.0.1:8580 node your-script-using-notifme.js\n```\n\n### 2. Providers\n\n#### Email providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSMTP \u003ci\u003e(can be used for almost all providers)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'smtp',\n        host: 'smtp.example.com',\n        port: 465,\n        secure: true,\n        auth: {\n          user: 'xxxxx',\n          pass: 'xxxxx'\n        }\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSendmail\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'sendmail',\n        sendmail: true,\n        newline: 'unix',\n        path: '/usr/sbin/sendmail'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eMailgun\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'mailgun',\n        apiKey: 'xxxxx',\n        domainName: 'example.com'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eMandrill\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'mandrill',\n        apiKey: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSendgrid\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'sendgrid',\n        apiKey: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSES\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'ses',\n        region: 'xxxxx',\n        accessKeyId: 'xxxxx',\n        secretAccessKey: 'xxxxx',\n        sessionToken: 'xxxxx' // optional\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSparkPost\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'sparkpost',\n        apiKey: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    email: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-email-provider...',\n        send: async (request) =\u003e {\n          // Send email\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L8-L31).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [Email provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-email.js)\n\n#### SMS providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e46elks\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: '46elks',\n        apiUsername: 'xxxxx',\n        apiPassword: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCallr\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'callr',\n        login: 'xxxxx',\n        password: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eClickatell\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'clickatell',\n        apiKey: 'xxxxx' // One-way integration API key\n      }]\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eInfobip\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'infobip',\n        username: 'xxxxx',\n        password: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eNexmo\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'nexmo',\n        apiKey: 'xxxxx',\n        apiSecret: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eOVH\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'ovh',\n        appKey: 'xxxxx',\n        appSecret: 'xxxxx',\n        consumerKey: 'xxxxx',\n        account: 'xxxxx',\n        host: 'xxxxx' // https://github.com/ovh/node-ovh/blob/master/lib/endpoints.js\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003ePlivo\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'plivo',\n        authId: 'xxxxx',\n        authToken: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eTwilio\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'twilio',\n        accountSid: 'xxxxx',\n        authToken: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eSeven\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'seven',\n        apiKey: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    sms: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-sms-provider...',\n        send: async (request) =\u003e {\n          // Send SMS\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L76-L92).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [SMS provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-sms.js)\n\n#### Voice providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    voice: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eTwilio\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    voice: {\n      providers: [{\n        type: 'twilio',\n        accountSid: 'xxxxx',\n        authToken: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    voice: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-voice-provider...',\n        send: async (request) =\u003e {\n          // Send Voice\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L94-L111).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [Voice provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-voice.js)\n\n#### Push providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eAPN (Apple Push Notification)\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'apn',\n        token: {\n          key: './certs/key.p8',\n          keyId: 'xxxxx',\n          teamId: 'xxxxx'\n        }\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eFCM (Firebase Cloud Messaging, previously called GCM, Google Cloud Messaging)\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'fcm',\n        id: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eWNS (Windows Push Notification)\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'wns',\n        clientId: 'xxxxx',\n        clientSecret: 'xxxxx',\n        notificationMethod: 'sendTileSquareBlock'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eADM (Amazon Device Messaging)\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'adm',\n        clientId: 'xxxxx',\n        clientSecret: 'xxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    push: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-push-provider...',\n        send: async (request) =\u003e {\n          // Send push\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L33-L74).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [Push provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-push.js)\n\n#### Webpush providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    webpush: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eGCM (Google Cloud Messaging) - uses W3C endpoints if possible\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    webpush: {\n      providers: [{\n        type: 'gcm',\n        gcmAPIKey: 'xxxxx',\n        vapidDetails: {\n          subject: 'mailto: contact@example.com',\n          publicKey: 'xxxxx',\n          privateKey: 'xxxxx'\n        }\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    webpush: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-webpush-provider...',\n        send: async (request) =\u003e {\n          // Send webpush\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L113-L134).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [Webpush provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-webpush.js)\n\n#### Slack providers\n\n\u003cdetails\u003e\u003csummary\u003eLogger \u003ci\u003e(for development)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    slack: {\n      providers: [{\n        type: 'logger'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSlack\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    slack: {\n      providers: [{\n        type: 'webhook',\n        webhookUrl: 'https://hooks.slack.com/services/Txxxxxxxx/Bxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxx'\n      }]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCustom \u003ci\u003e(define your own)\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnew NotifmeSdk({\n  channels: {\n    slack: {\n      providers: [{\n        type: 'custom',\n        id: 'my-custom-slack-provider...',\n        send: async (request) =\u003e {\n          // Send slack\n          return 'id...'\n        }\n      }]\n    }\n  }\n})\n```\n\n`request` being of [the following type](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L136-L138).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\nSee all options: [Slack provider options](https://github.com/notifme/notifme-sdk/blob/master/src/models/provider-slack.js)\n\n#### Multi-provider strategies\n\nA multi-provider strategy allows you to customize the send process on a channel.\n\n##### Predefined strategies\n\n| Strategy name | Description |\n| --- | --- |\n| `fallback` | If the used provider returns an error, try the next in the list. |\n| `roundrobin` | Use every provider in turns. If one of them returns an error, fallback to the next. |\n| `no-fallback` | Deactivates fallback strategy. |\n\n##### Custom\n\nYou can also provide your own strategy. You have to pass a function implementing:\n\n```javascript\n(Provider[]) =\u003e Sender\n// See examples below for more details\n```\n\nExamples:\n\n\u003cdetails\u003e\u003csummary\u003eRandom strategy\u003c/summary\u003e\u003cp\u003e\n\n```javascript\n/*\n * `providers` is an array containing all the instances that were\n * created from your configuration.\n */\nconst randomStrategy = (providers) =\u003e async (request) =\u003e {\n  // Choose one provider at random\n  const provider = providers[Math.floor(Math.random() * providers.length)];\n\n  try {\n    const id = await provider.send(request)\n    return {id, providerId: provider.id}\n  } catch (error) {\n    error.providerId = provider.id\n    throw error\n  }\n}\n\nnew NotifmeSdk({\n  channels: {\n    email: { // Example for email channel\n      providers: [...],\n      multiProviderStrategy: randomStrategy\n    }\n  }\n})\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCheap SMS strategy with fallback\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nimport strategyFallback from 'notifme-sdk/lib/strategies/fallback'\n\nfunction getCountryFromNumber(number) {\n  // extract the country from a phone number (+33670707070) -\u003e 'fr'\n}\nfunction orderProvidersByPrice(country, providers) {\n  // giving a country return an array of ordered providers by price\n}\n\nconst smsCheapStrategy = (providers) =\u003e async (request) =\u003e {\n  const country = getCountryFromNumber(request.from)\n  const providersOrdered = orderProvidersByPrice(country, providers)\n\n  return strategyFallback(providersOrdered)(request)\n}\n```\n\u003c/p\u003e\u003c/details\u003e\n\u003cbr\u003e\n\n#### Adding a provider or a channel\n\nIf you would like to see another provider or channel, please [upvote the corresponding issue](https://github.com/notifme/notifme-sdk/issues) (or create one if it does not exist yet).\n\n### 3. Custom channels\n\nIf you want to have custom channels (and providers) you can add them.\n\nExample:\n\n\u003cdetails\u003e\u003csummary\u003eCustom channel and provider\u003c/summary\u003e\u003cp\u003e\n\n```\nnew NotifmeSdk({\n  channels: {\n    socket: {\n      multiProviderStrategy: 'fallback',\n      providers: [\n        {\n          type: 'custom',\n          id: 'my-socket-sender',\n          send: async () =\u003e {\n            return 'custom-socket-id'\n          }\n        }\n      ]\n    }\n  }\n})\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\n### 4. Send a notification\n\n#### Parameters\n\n_New: you can check [notifme-template](https://github.com/notifme/notifme-template) to help you define your templates._\n\n\u003cdetails\u003e\u003csummary\u003eSend an email\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  email: {\n    from: 'me@example.com',\n    to: 'john@example.com',\n    subject: 'Hi John',\n    html: '\u003cb\u003eHello John! How are you?\u003c/b\u003e'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L8).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSend a SMS\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  sms: {\n    from: '+15000000000',\n    to: '+15000000001',\n    text: 'Hello John! How are you?'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L76).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCall using Voice\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  voice: {\n    from: '+15000000000',\n    to: '+15000000001',\n    url: 'http://demo.twilio.com/docs/voice.xml'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L94).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSend a push\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  push: {\n    registrationToken: 'xxxxx',\n    title: 'Hi John',\n    body: 'Hello John! How are you?',\n    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L33).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSend a webpush\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  webpush: {\n    subscription: {\n      keys: {\n        auth: 'xxxxx',\n        p256dh: 'xxxxx'\n      },\n      endpoint: 'xxxxx'\n    },\n    title: 'Hi John',\n    body: 'Hello John! How are you?',\n    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L109).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSend a Slack message\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  slack: {\n    text: 'Slack webhook text'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js#L132).\n\n\u003c/p\u003e\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSend a multi-channel notification\u003c/summary\u003e\u003cp\u003e\n\n```javascript\nnotifmeSdk.send({\n  email: {\n    from: 'me@example.com',\n    to: 'john@example.com',\n    subject: 'Hi John',\n    html: '\u003cb\u003eHello John! How are you?\u003c/b\u003e'\n  },\n  sms: {\n    from: '+15000000000',\n    to: '+15000000001',\n    text: 'Hello John! How are you?'\n  },\n  push: {\n    registrationToken: 'xxxxx',\n    title: 'Hi John',\n    body: 'Hello John! How are you?',\n    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'\n  },\n  webpush: {\n    subscription: {\n      keys: {\n        auth: 'xxxxx',\n        p256dh: 'xxxxx'\n      },\n      endpoint: 'xxxxx'\n    },\n    title: 'Hi John',\n    body: 'Hello John! How are you?',\n    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'\n  },\n  slack: {\n    text: 'Slack webhook text'\n  }\n})\n```\n\nSee [all parameters](https://github.com/notifme/notifme-sdk/blob/master/src/models/notification-request.js).\n\n\u003c/p\u003e\u003c/details\u003e\n\n#### Returned type\n\n`send` returns a Promise resolving with an `Object` of the following type:\n\n```javascript\ntype NotificationStatusType = {\n  status: 'success' | 'error',\n  channels?: {[channel: ChannelType]: {\n    id: string,\n    providerId: ?string\n  }},\n  errors?: {[channel: ChannelType]: Error}\n}\n```\n\nExamples:\n\n| Case | Returned JSON |\n| --- | --- |\n| Success\u003cbr\u003e(when Promise resolves) | `{status: 'success', channels: {sms: {id: 'id-116561976', providerId: 'sms-default-provider'}}}` |\n| Error\u003cbr\u003e(here Notification Catcher is not running) | `{status: 'error', channels: {sms: {id: undefined, providerId: 'sms-notificationcatcher-provider'}}, errors: {sms: 'connect ECONNREFUSED 127.0.0.1:1025'}}` |\n\n### 5. In production\n\n#### Recommended options\n\n| Option name | Usage in production | Comment |\n| --- | --- | --- |\n| useNotificationCatcher | `false` | Don't forget to deactivate notification catcher (it overrides channels configuration). |\n\n#### Logger\n\nThis project uses [winston](https://github.com/winstonjs/winston) as logging library. You can add or remove loggers as you wish.\n\n```javascript\nimport NotifmeSdk from 'notifme-sdk'\nimport winston from 'winston'\n\nconst notifmeSdk = new NotifmeSdk({})\n\n// To deactivate all loggers\nnotifmeSdk.logger.mute()\n\n// Or set the loggers you want\nnotifmeSdk.logger.configure([\n  new (winston.transports.File)({filename: 'somefile.log'})\n])\n```\n\nSee [winston's documentation](https://github.com/winstonjs/winston) for more details.\n\n#### Use a request queue\n\n- RabbitMQ: see [RabbitMQ Notif.me plugin documentation](https://github.com/notifme/notifme-sdk-queue-rabbitmq).\n\n#### Send us a message\n\nSo that we can make a list of people using this library ;)\n\n## Contributing\n\n[![test framework](https://img.shields.io/badge/test_framework-Jest-brightgreen.svg?style=flat)](https://facebook.github.io/jest/)\n[![js-standard-style](https://img.shields.io/badge/codestyle-Standard_JS-brightgreen.svg?style=flat)](https://github.com/standard/standard)\n[![flow-typed](https://img.shields.io/badge/typing-Flow_Type-brightgreen.svg?style=flat)](https://flow.org/)\n[![Greenkeeper badge](https://badges.greenkeeper.io/notifme/notifme-sdk.svg)](https://greenkeeper.io/)\n\nContributions are very welcome!\n\nTo get started: [fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.\n\n```shell\n$ git clone git@github.com:[YOUR_USERNAME]/notifme-sdk.git \u0026\u0026 cd notifme-sdk\n$ yarn install\n```\n\nBefore making a [pull request](https://help.github.com/articles/creating-a-pull-request/), check that the code passes all the unit tests, respects the [Standard JS rules](https://standardjs.com/), and the [Flow type checker](https://flow.org/).\n\nTests will also run automatically with GitHub Actions when you open a PR.\n\n```shell\n$ yarn run test\n```\n\n### Next for this project\n\n- Implement other providers for each channel ([ask or vote for a provider](https://github.com/notifme/notifme-sdk/issues))\n- Add other types of notifications based on what people ask (slack, messenger, skype, telegram, kik, spark...)\n- A plugin system (for queues, retry system on error, templating, strategies...)\n\n## Need Help? Found a bug?\n\n[Submit an issue](https://github.com/notifme/notifme-sdk/issues) to the project Github if you need any help.\nAnd, of course, feel free to submit pull requests with bug fixes or changes.\n\n## Related Projects\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/notifme/notifme-history\"\u003e\n    \u003cimg alt=\"Notif.me SDK\" src=\"https://notifme.github.io/notifme-history/img/logo.png\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003cem\u003eA pretty history of the conversations with your users.\u003c/em\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotifme%2Fnotifme-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotifme%2Fnotifme-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotifme%2Fnotifme-sdk/lists"}