@coopenomics/notifications 2026.2.22-2 → 2026.3.4-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/AGENTS.md +97 -0
  2. package/README.md +97 -196
  3. package/dist/index.d.cts +101 -56
  4. package/dist/index.d.mts +101 -56
  5. package/dist/index.d.ts +101 -56
  6. package/package.json +7 -5
  7. package/test/index.test.ts +47 -0
package/AGENTS.md ADDED
@@ -0,0 +1,97 @@
1
+ # @coopenomics/notifications
2
+
3
+ ## Назначение
4
+
5
+ Библиотека типобезопасных workflow-уведомлений для Novu. Определяет 21 workflow уведомлений (email, in-app, push), валидирует payload через Zod-схемы и синхронизирует определения с Novu API.
6
+
7
+ ## Структура
8
+
9
+ ```
10
+ src/
11
+ ├── index.ts — Главный экспорт: Types, WorkflowBuilder, Workflows, defaults
12
+ ├── base/
13
+ │ ├── workflow-builder.ts — WorkflowBuilder<T> — билдер для создания workflow
14
+ │ └── defaults.ts — Фабрики шагов: createEmailStep, createInAppStep, createPushStep
15
+ │ Настройки preferences по умолчанию
16
+ ├── types/
17
+ │ └── index.ts — Типы: WorkflowDefinition, WorkflowStep, PayloadSchema,
18
+ │ BaseWorkflowPayload, NovuWorkflowData, PreferencesConfig
19
+ ├── workflows/ — 21 workflow, каждый в своей директории
20
+ │ ├── index.ts — Реестр: allWorkflows[], workflowsById{}, экспорт всех
21
+ │ ├── welcome/ — Приветственное уведомление
22
+ │ ├── email-verification/ — Подтверждение email
23
+ │ ├── reset-key/ — Сброс ключа
24
+ │ ├── invite/ — Приглашение
25
+ │ ├── approval-request/ — Запрос на одобрение
26
+ │ ├── approval-response/ — Ответ на запрос одобрения
27
+ │ ├── decision-approved/ — Решение одобрено
28
+ │ ├── decision-expired/ — Решение истекло
29
+ │ ├── incoming-transfer/ — Входящий перевод
30
+ │ ├── payment-paid/ — Платёж оплачен
31
+ │ ├── payment-cancelled/ — Платёж отменён
32
+ │ ├── new-initial-payment-request/ — Запрос начального платежа
33
+ │ ├── new-deposit-payment-request/ — Запрос депозита
34
+ │ ├── new-agenda-item/ — Новый пункт повестки
35
+ │ ├── meet-initial/ — Собрание создано
36
+ │ ├── meet-reminder-start/ — Напоминание о начале собрания
37
+ │ ├── meet-started/ — Собрание началось
38
+ │ ├── meet-reminder-end/ — Напоминание о завершении собрания
39
+ │ ├── meet-restart/ — Собрание перезапущено
40
+ │ ├── meet-ended/ — Собрание завершено
41
+ │ └── server-provisioned/ — Сервер создан
42
+ ├── sync/
43
+ │ ├── sync-runner.ts — CLI для синхронизации workflow с Novu API
44
+ │ │ --dev: режим watch (chokidar), production: одноразовая синхронизация
45
+ │ └── novu-sync.service.ts — NovuSyncService: upsert workflow в Novu через REST API
46
+ └── utils/
47
+ └── slugify/ — Транслитерация русских названий → латинские slug ID
48
+ ```
49
+
50
+ ## Ключевые концепции
51
+
52
+ ### Паттерн WorkflowBuilder
53
+
54
+ Каждый workflow создаётся через fluent-builder:
55
+ ```typescript
56
+ const workflow = WorkflowBuilder
57
+ .create<IWorkflow>()
58
+ .name('Добро пожаловать')
59
+ .workflowId(slugify('Добро пожаловать'))
60
+ .description('Приветственные уведомления')
61
+ .payloadSchema(zodSchema)
62
+ .tags(['user'])
63
+ .addSteps([
64
+ createEmailStep('step-id', 'Тема', 'Тело письма'),
65
+ createInAppStep('step-id', 'Заголовок', 'Контент'),
66
+ createPushStep('step-id', 'Заголовок', 'Тело'),
67
+ ])
68
+ .build()
69
+ ```
70
+
71
+ ### Zod-схемы
72
+
73
+ Каждый workflow определяет Zod-схему для payload. Схема автоматически конвертируется в JSON Schema для Novu API через `zod-to-json-schema`.
74
+
75
+ ### Синхронизация с Novu
76
+
77
+ - `pnpm run sync` — однократная синхронизация всех workflow
78
+ - `pnpm run sync:dev` — режим разработки с watch
79
+ - Требует переменных `NOVU_API_KEY` и `NOVU_API_URL`
80
+
81
+ ### Slugify
82
+
83
+ Названия workflow на русском языке транслитерируются в латинские slug ID через `utils/slugify/`. Это обеспечивает стабильные `workflowId` для Novu API.
84
+
85
+ ## Скрипты package.json
86
+
87
+ | Скрипт | Описание |
88
+ |--------|----------|
89
+ | `build` | Сборка через unbuild |
90
+ | `dev` | Сборка с watch |
91
+ | `test` | Vitest |
92
+ | `sync` | Синхронизация workflow с Novu (production) |
93
+ | `sync:dev` | Синхронизация с watch (development) |
94
+
95
+ ## Зависимости
96
+
97
+ Нет workspace-зависимостей. Используется контроллером (`controller`) для триггера уведомлений.
package/README.md CHANGED
@@ -1,218 +1,119 @@
1
- # Notifications Library - Типизированные Workflow для Novu
2
-
3
- Библиотека для создания типизированных workflow уведомлений с использованием Zod схем и паттерна Builder.
4
-
5
- ## Особенности
6
-
7
- - 🔒 **Типобезопасность** - Полная типизация payload с Zod
8
- - 🏗️ **Builder Pattern** - Удобное создание workflow
9
- - 📝 **Декларативный API** - Простое описание шагов уведомлений
10
- - 🔧 **Расширяемость** - Легкое добавление новых типов workflow
11
- - ⚡ **Валидация** - Автоматическая валидация данных
12
- - 🏷️ **Теги и роли** - Группировка уведомлений по ролям пользователей
1
+ # 🔔 @coopenomics/notifications
2
+
3
+ > Типобезопасная библиотека workflow-уведомлений для платформы Novu
4
+
5
+ ## Описание
6
+
7
+ `@coopenomics/notifications` — библиотека для создания и управления workflow уведомлений кооператива. Построена на Zod-схемах и паттерне Builder, обеспечивая полную типобезопасность payload каждого уведомления. Поддерживает множество каналов доставки и ролевую маршрутизацию через систему тегов.
8
+
9
+ Интегрируется с платформой [Novu](https://novu.co) для оркестрации и доставки уведомлений.
10
+
11
+ ## Возможности
12
+
13
+ - **21 workflow** — покрытие всех ключевых бизнес-процессов кооператива
14
+ - **Типобезопасность** — Zod-схемы для валидации payload каждого workflow
15
+ - **Многоканальность** — Email (HTML), In-App, Push, SMS, Chat
16
+ - **Ролевая маршрутизация** — теги для направления уведомлений по ролям (председатель, член совета, пайщик)
17
+ - **Паттерн Builder** — удобное декларативное создание новых workflow через `WorkflowBuilder`
18
+ - **Синхронизация** — автоматическая синхронизация workflow с платформой Novu
19
+
20
+ ## Workflow
21
+
22
+ | Workflow | Описание |
23
+ |----------|----------|
24
+ | `welcome` | Приветствие нового участника |
25
+ | `approval-request` | Запрос на утверждение (совету) |
26
+ | `approval-response` | Ответ на запрос утверждения |
27
+ | `decision-approved` | Решение утверждено |
28
+ | `decision-expired` | Решение просрочено |
29
+ | `payment-paid` | Платёж выполнен |
30
+ | `payment-cancelled` | Платёж отменён |
31
+ | `new-initial-payment-request` | Запрос начального взноса |
32
+ | `new-deposit-payment-request` | Запрос депозитного взноса |
33
+ | `incoming-transfer` | Входящий перевод |
34
+ | `new-agenda-item` | Новый пункт повестки |
35
+ | `meet-initial` | Инициация собрания |
36
+ | `meet-reminder-start` | Напоминание о начале собрания |
37
+ | `meet-started` | Собрание началось |
38
+ | `meet-reminder-end` | Напоминание об окончании собрания |
39
+ | `meet-restart` | Перезапуск собрания |
40
+ | `meet-ended` | Собрание завершено |
41
+ | `invite` | Приглашение в кооператив |
42
+ | `reset-key` | Сброс ключа доступа |
43
+ | `email-verification` | Подтверждение электронной почты |
44
+ | `server-provisioned` | Сервер подготовлен |
13
45
 
14
46
  ## Установка
15
47
 
16
48
  ```bash
17
- cd components/notifications
18
- pnpm install
19
- ```
20
-
21
- ## Быстрый старт
22
-
23
- ### 1. Создание нового workflow
24
-
25
- ```typescript
26
- import { z } from 'zod';
27
- import { WorkflowBuilder, createEmailStep, createInAppStep } from '@coopenomics/notifications';
28
-
29
- // Определяем схему данных
30
- const myPayloadSchema = z.object({
31
- userName: z.string(),
32
- userEmail: z.string().email(),
33
- orderTotal: z.number(),
34
- });
35
-
36
- type MyPayload = z.infer<typeof myPayloadSchema>;
37
-
38
- // Создаем workflow
39
- export const orderConfirmationWorkflow = WorkflowBuilder
40
- .create<MyPayload>()
41
- .name('Order Confirmation')
42
- .workflowId('order-confirmation')
43
- .description('Подтверждение заказа')
44
- .payloadSchema(myPayloadSchema)
45
- .addSteps([
46
- createEmailStep(
47
- 'order-email',
48
- 'Заказ подтвержден - {{payload.userName}}',
49
- 'Здравствуйте, {{payload.userName}}! Ваш заказ на сумму {{payload.orderTotal}} подтвержден.'
50
- ),
51
- createInAppStep(
52
- 'order-notification',
53
- 'Заказ обработан',
54
- 'Заказ успешно обработан и скоро будет отправлен.'
55
- ),
56
- ])
57
- .build();
49
+ pnpm install --filter @coopenomics/notifications
58
50
  ```
59
51
 
60
- ### 2. Регистрация workflow
52
+ ## Скрипты
61
53
 
62
- Добавьте ваш workflow в `src/workflows/index.ts`:
54
+ | Скрипт | Описание |
55
+ |--------|----------|
56
+ | `pnpm run build` | Сборка библиотеки (`unbuild`) |
57
+ | `pnpm run dev` | Режим разработки с отслеживанием изменений (`unbuild --watch`) |
58
+ | `pnpm run test` | Запуск тестов (`vitest`) |
59
+ | `pnpm run sync` | Синхронизация workflow с платформой Novu |
60
+ | `pnpm run sync:dev` | Синхронизация в dev-режиме |
63
61
 
64
- ```typescript
65
- import { orderConfirmationWorkflow } from './order-confirmation';
62
+ > Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter @coopenomics/notifications run <скрипт>`
66
63
 
67
- export const allWorkflows: WorkflowDefinition[] = [
68
- welcomeWorkflow,
69
- orderConfirmationWorkflow, // ← добавляем новый workflow
70
- ];
71
- ```
72
-
73
- ### 3. Использование в коде
74
-
75
- ```typescript
76
- import { orderConfirmationWorkflow } from '@coopenomics/notifications';
64
+ ## Конфигурация
77
65
 
78
- // Валидация данных
79
- const payload = orderConfirmationWorkflow.payloadZodSchema.parse({
80
- userName: 'Иван Иванов',
81
- userEmail: 'ivan@example.com',
82
- orderTotal: 1500,
83
- });
84
-
85
- // Данные для отправки в Novu
86
- const novuData = orderConfirmationWorkflow.payloadSchema;
87
- ```
66
+ Для синхронизации с Novu необходим API-ключ. Подробности о настройке — в [документации Novu](https://docs.novu.co).
88
67
 
89
- ## Структура проекта
68
+ ## Архитектура
90
69
 
91
70
  ```
92
71
  src/
93
- ├── types/ # Базовые типы и интерфейсы
94
- ├── base/ # Базовые утилиты и настройки
95
- │ ├── defaults.ts # Настройки по умолчанию
96
- │ └── workflow-builder.ts # Builder для создания workflow
97
- └── workflows/ # Папки с workflow
98
- ├── welcome/ # Приветственные уведомления
99
- ├── order/ # Уведомления о заказах
100
- └── index.ts # Экспорт всех workflow
101
- ```
102
-
103
- ## API Reference
104
-
105
- ### WorkflowBuilder
106
-
107
- Основной класс для создания workflow:
108
-
109
- ```typescript
110
- const workflow = WorkflowBuilder
111
- .create<PayloadType>()
112
- .name('Workflow Name') // Название workflow
113
- .workflowId('unique-workflow-id') // Уникальный ID
114
- .description('Описание workflow') // Описание (опционально)
115
- .payloadSchema(zodSchema) // Zod схема для валидации
116
- .addStep(step) // Добавить шаг
117
- .addSteps([step1, step2]) // Добавить несколько шагов
118
- .origin('external') // Источник (опционально)
119
- .build(); // Собрать workflow
120
- ```
121
-
122
- ### Вспомогательные функции
123
-
124
- ```typescript
125
- // Email уведомление
126
- createEmailStep(name, subject, body)
127
-
128
- // In-app уведомление
129
- createInAppStep(name, subject, body, avatar?)
130
-
131
- // Push уведомление
132
- createPushStep(name, title, body)
133
-
134
- // SMS уведомление
135
- createSmsStep(name, body)
136
- ```
137
-
138
- ## Типы workflow
139
-
140
- ### Email
141
- - `subject` - Тема письма
142
- - `body` - HTML содержимое
143
- - `editorType` - 'html' | 'text'
144
-
145
- ### In-App
146
- - `subject` - Заголовок уведомления
147
- - `body` - Текст уведомления
148
- - `avatar` - URL аватара (опционально)
149
-
150
- ### Push
151
- - `subject` - Заголовок push-уведомления
152
- - `body` - Текст push-уведомления
153
-
154
- ### SMS
155
- - `body` - Текст SMS
156
-
157
- ## Шаблонизация
158
-
159
- Используйте Handlebars синтаксис для динамических данных:
160
-
161
- ```typescript
162
- // Простая подстановка
163
- "Привет, {{payload.userName}}!"
164
-
165
- // Условные блоки
166
- "{{#payload.age}}Ваш возраст: {{payload.age}}{{/payload.age}}"
167
-
168
- // Вложенные объекты
169
- "{{payload.order.total}} руб."
72
+ ├── types/ # Базовые типы и интерфейсы
73
+ │ └── index.ts # ChannelConfig, WorkflowStep, WorkflowDefinition
74
+ ├── base/ # Ядро библиотеки
75
+ │ ├── defaults.ts # Настройки по умолчанию для каналов
76
+ │ └── workflow-builder.ts # Паттерн Builder для создания workflow
77
+ ├── utils/ # Вспомогательные утилиты
78
+ │ └── index.ts
79
+ ├── workflows/ # Определения workflow (21 директория)
80
+ │ ├── welcome/ # Приветствие
81
+ │ ├── approval-request/ # Запрос утверждения
82
+ │ ├── approval-response/ # Ответ на утверждение
83
+ │ ├── decision-approved/ # Решение утверждено
84
+ │ ├── decision-expired/ # Решение просрочено
85
+ │ ├── payment-paid/ # Платёж выполнен
86
+ │ ├── payment-cancelled/ # Платёж отменён
87
+ │ ├── meet-initial/ # Инициация собрания
88
+ │ ├── meet-started/ # Собрание началось
89
+ │ ├── meet-ended/ # Собрание завершено
90
+ │ ├── meet-reminder-start/ # Напоминание о начале
91
+ │ ├── meet-reminder-end/ # Напоминание об окончании
92
+ │ ├── meet-restart/ # Перезапуск собрания
93
+ │ ├── invite/ # Приглашение
94
+ │ ├── reset-key/ # Сброс ключа
95
+ │ ├── email-verification/ # Подтверждение email
96
+ │ ├── incoming-transfer/ # Входящий перевод
97
+ │ ├── new-agenda-item/ # Пункт повестки
98
+ │ ├── new-initial-payment-request/ # Запрос начального взноса
99
+ │ ├── new-deposit-payment-request/ # Запрос депозитного взноса
100
+ │ └── server-provisioned/ # Сервер подготовлен
101
+ ├── sync/ # Синхронизация с Novu
102
+ │ ├── novu-sync.service.ts # Сервис синхронизации
103
+ │ └── sync-runner.ts # Точка входа для sync-скриптов
104
+ └── index.ts # Главная точка входа
170
105
  ```
171
106
 
172
- ## Теги и роли
173
-
174
- Библиотека поддерживает группировку уведомлений по ролям пользователей с помощью тегов. Теги позволяют фильтровать уведомления в UI компонентах.
107
+ Каждый workflow экспортирует определение типа `WorkflowDefinition` с Zod-схемой payload, настройками каналов и шаблонами сообщений. Все workflow автоматически регистрируются через массив `allWorkflows` и доступны по идентификатору через `workflowsById`.
175
108
 
176
- ### Добавление тегов к workflow
177
-
178
- ```typescript
179
- export const newAgendaItemWorkflow = WorkflowBuilder
180
- .create<NewAgendaItemPayload>()
181
- .name('Новый вопрос на повестке')
182
- .workflowId('new-agenda-item')
183
- .description('Уведомление о новом вопросе на повестке')
184
- .payloadSchema(newAgendaItemPayloadSchema)
185
- .tags(['chairman', 'member']) // Теги для ролей пользователей
186
- .addSteps([
187
- // ... шаги
188
- ])
189
- .build();
190
- ```
109
+ ## Тестирование
191
110
 
192
- ### Использование в компонентах
193
-
194
- ```typescript
195
- // Создание табов для фильтрации по ролям
196
- const tabs = [
197
- {
198
- label: 'Все уведомления',
199
- filter: {
200
- tags: [userRole.value], // Фильтр по роли пользователя
201
- },
202
- },
203
- ];
111
+ ```bash
112
+ pnpm --filter @coopenomics/notifications run test
204
113
  ```
205
114
 
206
- ### Доступные роли
207
-
208
- - `chairman` - Председатель совета
209
- - `member` - Член совета
210
- - `user` - Обычный пользователь
211
-
212
- ## Сборка
115
+ Проект содержит 7 smoke-тестов на `vitest`, проверяющих корректность определений workflow и Zod-схем.
213
116
 
214
- ```bash
215
- pnpm build
216
- ```
117
+ ## Лицензия
217
118
 
218
- Результат сборки будет в папке `dist/`.
119
+ [BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)