@andrey4emk/npm-app-back-b24 0.3.1 → 0.3.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.
- package/README.md +198 -33
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
Утилиты для работы с Bitrix24 OAuth на основе `@bitrix24/b24jssdk`.
|
|
4
4
|
|
|
5
|
+
## Содержание
|
|
6
|
+
|
|
7
|
+
- [Установка](#установка)
|
|
8
|
+
- [Использование](#использование)
|
|
9
|
+
- [API](#api)
|
|
10
|
+
- [OAuth функции](#oauth-функции)
|
|
11
|
+
- [Утилиты](#утилиты)
|
|
12
|
+
- [События](#события)
|
|
13
|
+
- [Переменные окружения](#переменные-окружения)
|
|
14
|
+
- [Скрипты](#скрипты)
|
|
15
|
+
- [Лицензия](#лицензия)
|
|
16
|
+
|
|
5
17
|
## Установка
|
|
6
18
|
|
|
7
19
|
```bash
|
|
@@ -28,7 +40,7 @@ await errTask(b24Client, {
|
|
|
28
40
|
|
|
29
41
|
// Работа с событиями
|
|
30
42
|
const eventHandler = new Event(b24Client);
|
|
31
|
-
const events = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
43
|
+
const { error, events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
32
44
|
```
|
|
33
45
|
|
|
34
46
|
## API
|
|
@@ -37,61 +49,214 @@ const events = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
|
37
49
|
|
|
38
50
|
- **`create(AuthB24Model)`** — создаёт клиента `B24OAuth` с использованием сохранённых в БД токенов.
|
|
39
51
|
|
|
40
|
-
-
|
|
52
|
+
- **Параметры:**
|
|
53
|
+
- `AuthB24Model` (Sequelize Model) — модель для получения данных авторизации из БД.
|
|
54
|
+
- **Возвращает:** промис с экземпляром `B24OAuth`, готовым к вызовам REST API.
|
|
55
|
+
- **Ошибки:** выбрасывает `Error` если запись авторизации не найдена в БД.
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
const b24 = await create(AuthB24Model);
|
|
59
|
+
const result = await b24.callMethod("crm.contact.list", { limit: 5 });
|
|
60
|
+
```
|
|
41
61
|
|
|
42
62
|
- **`refresh(AuthB24Model)`** — продлевает токены через Bitrix24 и обновляет запись в БД.
|
|
43
63
|
|
|
44
|
-
-
|
|
64
|
+
- **Параметры:**
|
|
65
|
+
- `AuthB24Model` (Sequelize Model) — модель для обновления токенов.
|
|
66
|
+
- **Возвращает:** промис с объектом `{ error: boolean, message: string }`.
|
|
67
|
+
|
|
68
|
+
```js
|
|
69
|
+
const result = await refresh(AuthB24Model);
|
|
70
|
+
if (!result.error) {
|
|
71
|
+
console.log("Токены обновлены:", result.message);
|
|
72
|
+
}
|
|
73
|
+
```
|
|
45
74
|
|
|
46
75
|
- **`save(req, res, AuthB24Model)`** — HTTP-обработчик для сохранения набора токенов из `req.body`.
|
|
47
|
-
|
|
76
|
+
|
|
77
|
+
- **Параметры:**
|
|
78
|
+
- `req` (Express Request) — объект запроса с полем `body`.
|
|
79
|
+
- `res` (Express Response) — объект ответа.
|
|
80
|
+
- `AuthB24Model` (Sequelize Model) — модель для сохранения.
|
|
81
|
+
- **Тело запроса (req.body):**
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"access_token": "string",
|
|
85
|
+
"refresh_token": "string",
|
|
86
|
+
"domain": "string",
|
|
87
|
+
"expires_in": "number",
|
|
88
|
+
"member_id": "number"
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
- **Возвращает:** HTTP-ответ с JSON `{ status, message }` (код `201` при успехе, `400`/`500` при ошибках).
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
app.post("/b24/auth", (req, res) => save(req, res, AuthB24Model));
|
|
95
|
+
```
|
|
48
96
|
|
|
49
97
|
### Утилиты
|
|
50
98
|
|
|
51
99
|
- **`errTask(b24, dataTask)`** — создаёт служебную задачу в Bitrix24 при ошибках/событиях.
|
|
52
100
|
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
101
|
+
- **Алгоритм:**
|
|
102
|
+
|
|
103
|
+
1. Сначала проверяет, сколько задач с таким `TITLE` уже создано (через `tasks.task.list`).
|
|
104
|
+
2. Если их меньше чем `maxTasks`, создаёт новую задачу (`tasks.task.add`).
|
|
105
|
+
|
|
106
|
+
- **Параметры:**
|
|
107
|
+
|
|
108
|
+
- `b24` (B24OAuth) — экземпляр клиента Bitrix24.
|
|
109
|
+
- `dataTask` (object) — объект с параметрами задачи (см. ниже).
|
|
110
|
+
|
|
111
|
+
- **Возвращает:** промис с объектом:
|
|
112
|
+
```js
|
|
113
|
+
{
|
|
114
|
+
error: false,
|
|
115
|
+
message: "Задача создана в Битрикс24.",
|
|
116
|
+
result: { /* API response */ }
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
или при превышении лимита:
|
|
120
|
+
```js
|
|
121
|
+
{
|
|
122
|
+
error: false,
|
|
123
|
+
message: "Превышено максимальное количество задач с таким названием (100). Новая задача не создана."
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
или при ошибке:
|
|
127
|
+
```js
|
|
128
|
+
{
|
|
129
|
+
error: true,
|
|
130
|
+
message: "Не удалось создать задачу в Битрикс24: <текст ошибки>"
|
|
131
|
+
}
|
|
132
|
+
```
|
|
59
133
|
|
|
60
134
|
**Параметры `dataTask`:**
|
|
61
135
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
136
|
+
| Параметр | Тип | По умолчанию | Описание |
|
|
137
|
+
| ---------------- | ------------ | ------------------------- | --------------------------------------------- |
|
|
138
|
+
| `title` | string | **обязательно** | Заголовок задачи |
|
|
139
|
+
| `description` | string | `""` | Описание задачи |
|
|
140
|
+
| `createdBy` | number | `138` | ID создателя |
|
|
141
|
+
| `responsibleId` | number | `1` | ID ответственного |
|
|
142
|
+
| `deadline` | ISO string | `DateTime.now() + 1 день` | Дедлайн в ISO формате |
|
|
143
|
+
| `groupId` | number\|null | `null` | ID группы (опционально) |
|
|
144
|
+
| `accomplices` | array | `[]` | Массив ID соисполнителей |
|
|
145
|
+
| `maxTasks` | number | `100` | Максимум существующих задач с таким названием |
|
|
146
|
+
| `entityTypeAbbr` | string | `""` | Код CRM сущности для `UF_CRM_TASK` |
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
await errTask(b24, {
|
|
150
|
+
title: "Ошибка синхронизации",
|
|
151
|
+
description: "Не удалось подключиться к API",
|
|
152
|
+
responsibleId: 42,
|
|
153
|
+
deadline: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
|
|
154
|
+
maxTasks: 50,
|
|
155
|
+
});
|
|
156
|
+
```
|
|
71
157
|
|
|
72
158
|
### События
|
|
73
159
|
|
|
74
160
|
- **`Event`** — класс для работы с офлайн-событиями Bitrix24.
|
|
75
161
|
|
|
76
162
|
```js
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
// Получить события
|
|
80
|
-
const { events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
81
|
-
// events: { processId, entitysId, arrMessageIdAndEntityId }
|
|
163
|
+
import { Event } from "@andrey4emk/npm-app-back-b24";
|
|
82
164
|
|
|
83
|
-
|
|
84
|
-
await eventHandler.clear(processId, messageId);
|
|
85
|
-
|
|
86
|
-
// Удалить messageId из массива
|
|
87
|
-
const updated = await eventHandler.deleteMessageId(entityId, arrMessageIdAndEntityId);
|
|
165
|
+
const eventHandler = new Event(b24);
|
|
88
166
|
```
|
|
89
167
|
|
|
90
168
|
**Методы:**
|
|
91
169
|
|
|
92
|
-
-
|
|
93
|
-
|
|
94
|
-
|
|
170
|
+
- **`get(eventName)`** — получить события по названию.
|
|
171
|
+
|
|
172
|
+
- **Параметры:**
|
|
173
|
+
|
|
174
|
+
- `eventName` (string) — название события (например, `'ONCRMDYNAMICITEMUPDATE_149'`).
|
|
175
|
+
|
|
176
|
+
- **Возвращает:** промис с объектом:
|
|
177
|
+
|
|
178
|
+
```js
|
|
179
|
+
{
|
|
180
|
+
error: false,
|
|
181
|
+
events: {
|
|
182
|
+
processId: "12345",
|
|
183
|
+
entitysId: [101, 102, 103],
|
|
184
|
+
arrMessageIdAndEntityId: [
|
|
185
|
+
{ messageId: "msg_1", entityId: 101 },
|
|
186
|
+
{ messageId: "msg_2", entityId: 102 },
|
|
187
|
+
{ messageId: "msg_3", entityId: 103 }
|
|
188
|
+
]
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
или при ошибке:
|
|
194
|
+
|
|
195
|
+
```js
|
|
196
|
+
{
|
|
197
|
+
error: true,
|
|
198
|
+
status: "error",
|
|
199
|
+
message: "Не удалось получить события. <текст ошибки>"
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
- **Особенности:**
|
|
204
|
+
- Автоматически фильтрует и удаляет события от пользователя с `user_id: '138'`.
|
|
205
|
+
- Если событий нет, возвращает `events` с пустыми массивами.
|
|
206
|
+
|
|
207
|
+
```js
|
|
208
|
+
const { error, events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
209
|
+
if (!error && events.entitysId.length > 0) {
|
|
210
|
+
console.log("Обработанные ID сущностей:", events.entitysId);
|
|
211
|
+
// events.processId — идентификатор процесса для очистки
|
|
212
|
+
// events.arrMessageIdAndEntityId — данные для методов clear() и deleteMessageId()
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
- **`clear(processId, messageId)`** — очистить события в Bitrix24.
|
|
217
|
+
|
|
218
|
+
- **Параметры:**
|
|
219
|
+
|
|
220
|
+
- `processId` (string|number) — ID процесса (получен из `get()`).
|
|
221
|
+
- `messageId` (array|string) — ID или массив ID сообщений для очистки.
|
|
222
|
+
|
|
223
|
+
- **Возвращает:** промис с объектом:
|
|
224
|
+
```js
|
|
225
|
+
{
|
|
226
|
+
error: false;
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
или при ошибке:
|
|
230
|
+
```js
|
|
231
|
+
{
|
|
232
|
+
error: true,
|
|
233
|
+
status: "error",
|
|
234
|
+
message: "Не удалось очистить события. <текст ошибки>"
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
```js
|
|
239
|
+
const { events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
240
|
+
if (events.processId) {
|
|
241
|
+
const messageIds = events.arrMessageIdAndEntityId.map((item) => item.messageId);
|
|
242
|
+
await eventHandler.clear(events.processId, messageIds);
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
- **`deleteMessageId(entityId, arrMessageIdAndEntityId)`** — удалить запись события из массива (локально).
|
|
247
|
+
|
|
248
|
+
- **Параметры:**
|
|
249
|
+
|
|
250
|
+
- `entityId` (number) — ID сущности для удаления.
|
|
251
|
+
- `arrMessageIdAndEntityId` (array) — исходный массив событий.
|
|
252
|
+
|
|
253
|
+
- **Возвращает:** обновлённый массив без записей с указанным `entityId`.
|
|
254
|
+
|
|
255
|
+
```js
|
|
256
|
+
const { events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
257
|
+
const updated = eventHandler.deleteMessageId(101, events.arrMessageIdAndEntityId);
|
|
258
|
+
// updated содержит все события, кроме entityId: 101
|
|
259
|
+
```
|
|
95
260
|
|
|
96
261
|
## Переменные окружения
|
|
97
262
|
|
|
@@ -105,7 +270,7 @@ const events = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
|
|
|
105
270
|
| `APP_ENV` | Определяет окружение (`DEV` или production) |
|
|
106
271
|
| `APP_NAME` | Название приложения (используется в описании задач) |
|
|
107
272
|
|
|
108
|
-
|
|
273
|
+
**Пример `.env`:**
|
|
109
274
|
|
|
110
275
|
```env
|
|
111
276
|
APP_B24_DOMEN=mycompany.bitrix24.ru
|