# @alt-point/notificator

> Adonis notification library

Latest version **1.0.10** (published 2020-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @alt-point/notificator
pnpm add @alt-point/notificator
yarn add @alt-point/notificator
bun add @alt-point/notificator
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2020-08-05 |
| First published | 2020-08-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 10.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Vladislav O. Muschinskikh |
| Maintainers | vladismus |

## Links

- npm: https://www.npmjs.com/package/@alt-point/notificator
- Repository: https://gitlab.com/altpoint-services/adonis-packages/notificator
- Homepage: https://gitlab.com/altpoint-services/adonis-packages/notificator#readme
- Issues: https://gitlab.com/altpoint-services/adonis-packages/notificator/issues
- npm.io page: https://npm.io/package/@alt-point/notificator

## Dependencies (4)

- [lodash](https://npm.io/package/lodash.md) *
- [moment](https://npm.io/package/moment.md) *
- [@adonisjs/fold](https://npm.io/package/@adonisjs/fold.md) *
- [firebase-admin](https://npm.io/package/firebase-admin.md) ^8.12.1

## Recent versions

- 1.0.10 (latest) — 2020-08-05
- 1.0.9 — 2020-08-05

## README

Что это?
========

Пакет предназначен для отправки оповещений, используя [событийно-ориентированный подход в AdonisJS](https://adonisjs.com/docs/4.1/events)

# Quick start

### Подготовка

##### [Firebase](https://firebase.google.com)
1. В [консоли GCP](https://console.cloud.google.com/iam-admin/serviceaccounts) создайте ключ сервисного аккаунта (при необходимости — создайте сервисный аккаунт) и скачайте его в виде JSON-файла.
Этот файл будет использоваться в проекте для авторизации в сервисах Google, в частности, в Firebase

2. Установите ENV-переменную `SERVICE_ACCOUNT_FIREBASE`, в которой укажите путь к JSON-файлу сервисного аккаунта (из предыдущего пункта).

### Настройка проекта
1. Установите пакет
    ```sh
    $ adonis install @alt-point/notificator
    ```
2. Добавьте сервис-провайдер в файл `start/app.js`:
    ```js
    const providers = [
        …
        '@alt-point/notificator/providers/NotifyProvider',
    ]
    ```
### Отправка уведомлений

Отправлять оповещения можно из любого участка проекта путём вызова _событий_:
 - `notify::push` — Push-уведомление
 - `notify::sms` — SMS _(не реализовано)_
 - `notify::email` — Email-сообщение _(не реализовано)_

##### PUSH

###### Объект `event`
_Событие_ является JS-объектом и имеет следующие свойства:
 - `to` — **массив**, содержащий _push-токены_ получателей
 - `payload` — Содержимое push-уведомления, соответствующий [объекту Notification](https://firebase.google.com/docs/reference/admin/node/admin.messaging.Notification)
   - `title` — Заголовок сообщения
   - `body` — Текст сообщения
   - `imageUrl` — URL-изображения
- `options` — Дополнительные параметры уведомления
   - `priority` — строка; `normal` либо `high`
    Подробнее о приоритетах рассказано [в документации по Firebase](https://firebase.google.com/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message)
   - `ttl` — число; срок жизни уведомления **в секундах**

###### Пример

```js
const Event = use('Event')

Event.emit('notify::push', {
    to: [
        'fZX8gkoESG2giOS2HufEe7:APA91bEvJ91ol20GaJlHJIZnbo1XgyXK-lgt-lmGMeR-l6k2pPttL6DKpX66MTw4aj1nW8JOLNc6UfobBcx47IXd2jkmJAaU8hg2lQ5PlX0awYtmrlAKHN5CAD7APT5bdtgi5U8k9zOf'
    ],
    payload: {
        title: 'Test notification',
        body: 'Hello, world!'
    },
})
```

### Продвинутое использование

Помимо использования событий, также можно вызывать функцию отправки сообщений напрямую через класс Firebase:
```js
const Firebase = use('AltPoint/Notify/Firebase')

// Для отправки одному получателю
Firebase.sendNotification(token, payload, options)
    .then(console.info)
    .catch(console.error)

// Для отправки нескольким получателям
Firebase.sendNotificationMulticast(tokens, payload, options)
    .then(console.info)
    .catch(console.error)
```

> **Обратите внимание!**
> При отправке одному полчателю в качестве параметра `token` передаётся **один** push-токен (как строка), а при отправке мультикаст-сообщения нескольким получателям в качестве `tokens` передаётся **массив** строк с токенами получателей.
> В качестве аргументов `payload` и `options` используются объекты того же формата, что используется в объекте `event` при отправке через `Event.emit()`

### Супер-продвинутое использование

Для более тонкой настройки отправляемых сообщений можно использовать функции `send()` и `sendMulticast()`:
```js
const Firebase = use('AltPoint/Notify/Firebase')

Firebase.send(message)
    .then(console.info)
    .catch(console.error)

Firebase.sendMulticast(message)
    .then(console.info)
    .catch(console.error)
```

Данные функции являются обёртками для SDK-функций [send()](https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#send) и [sendMulticast()](https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendmulticast) соответственно.
В качестве аргумента `message` передаётся [объект Message](https://firebase.google.com/docs/reference/admin/node/admin.messaging#message)

> **Обратите внимание!**
> При отправке через функцию [sendMulticast()](https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendmulticast) в одном сообщении можно передать **не более 500** токенов-получателей, в то время как через `Firebase.sendNotificationMulticast()` позволяет передать неограниченное количество токенов — в этом случае массив получателей будет автоматически разделён на чанки по 500 токенов, и сообщение (при необходимости) будет разбито на несколько.

### Ninja-style

Если нужен более продвинутый функционал, то через свойство `Firebase.app` можно получить [объект App](https://firebase.google.com/docs/reference/admin/node/admin.app.App) из Firebase Admin SDK и работать с ним напрямую:

```js
const Firebase = use('AltPoint/Notify/Firebase')

Firebase.app.messaging()
    .send(message)
    .then(console.info)
    .catch(console.error)
```

# TODO
- Реализовать поддержку прочих траспортов для отправки уведомлений
  - SMS
  - Email

# CREDITS

[Vladislav O. Muschinskikh](https://t.me/VladisMus), [i@vlad.guru](mailto:i+notificator@vlad.guru)

© 2020

---
_Source: https://npm.io/package/@alt-point/notificator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._