bitrix24-mcp-bridge 0.1.1 → 0.2.1
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 +48 -13
- package/actions.example.json +27 -31
- package/dist/cli.js +190 -45
- package/docs/api-notes.md +234 -45
- package/extension/dist/connector.js +8 -4
- package/extension/dist/connector.js.map +2 -2
- package/package.json +7 -2
package/docs/api-notes.md
CHANGED
|
@@ -12,15 +12,29 @@
|
|
|
12
12
|
|
|
13
13
|
## 1. Как вызывать
|
|
14
14
|
|
|
15
|
-
- **Типизированные инструменты** (`bitrix_tasks_list`, `bitrix_task_get`, `bitrix_projects_list`,
|
|
16
|
-
`bitrix_project_get`, `bitrix_chats_recent`, `bitrix_chat_messages`) — с разумными дефолтами.
|
|
17
|
-
Точная выборка — через опциональный аргумент **`params`** (нативный формат Bitrix), он мержится
|
|
18
|
-
**последним** и перекрывает дефолты. Подсказки по параметрам есть в описании каждого инструмента.
|
|
19
15
|
- **`bitrix_call { name, params }`** — универсальный вызов любого разрешённого имени из каталога
|
|
20
|
-
(`actions.json`).
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
16
|
+
(`actions.json`). `params` — нативный формат Bitrix (см. раздел 3). Каталог может включать
|
|
17
|
+
мутирующие вызовы; allowlist (`actions.json`) — единственная граница, не режим чтения.
|
|
18
|
+
- **Типизированные инструменты** — обёртки с разумными дефолтами над каталогом. Точная выборка — через
|
|
19
|
+
опциональный `params`, он мержится **последним** и перекрывает дефолты. Регистрируются только те,
|
|
20
|
+
чьё имя есть в каталоге (`actions.json`); иначе инструмент пропускается. Текущий набор:
|
|
21
|
+
- Задачи: `bitrix_tasks_list`, `bitrix_task_get`, `bitrix_task_get_v2` (v2/JSON),
|
|
22
|
+
`bitrix_task_scrum_info`, `bitrix_task_files`, `bitrix_task_views_count`,
|
|
23
|
+
`bitrix_task_subtasks` (подзадачи), `bitrix_task_related` (связанные).
|
|
24
|
+
- Проекты: `bitrix_projects_list`, `bitrix_project_get`.
|
|
25
|
+
- Чаты: `bitrix_chats_recent`, `bitrix_recent_load` (недавние по секции — в т.ч. `tasksTask` =
|
|
26
|
+
чаты задач), `bitrix_recent_tail` (листать недавние вглубь), `bitrix_chat_load` (открыть по
|
|
27
|
+
`dialogId`/`chatId`), `bitrix_chat_messages`, `bitrix_chat_history` (листать вглубь по `beforeId`),
|
|
28
|
+
`bitrix_chat_get_dialog_id` (dialogId по externalId), `bitrix_chat_mark_read` (⚠ мутирующий),
|
|
29
|
+
`bitrix_chat_read_all` (⚠ мутирующий).
|
|
30
|
+
- Люди/поиск: `bitrix_user_get` (карточка юзера), `bitrix_entity_selector` (загрузка селектора),
|
|
31
|
+
`bitrix_entity_search` (текстовый поиск чатов/сущностей через `ui.entityselector.doSearch`).
|
|
32
|
+
|
|
33
|
+
Любое имя каталога всегда доступно и напрямую через `bitrix_call { name, params }`.
|
|
34
|
+
- **`bitrix_help`** — этот же гайд, отдаётся через MCP (инструмент + resource `bitrix://api-notes`).
|
|
35
|
+
Источник — **этот файл** (`docs/api-notes.md`).
|
|
36
|
+
|
|
37
|
+
Полный список имён каталога отдаёт `bitrix_call` в своём описании (`deps.catalog.names()`).
|
|
24
38
|
|
|
25
39
|
---
|
|
26
40
|
|
|
@@ -35,44 +49,83 @@ Ajax-контроллеры (`/bitrix/services/main/ajax.php`) отвечают
|
|
|
35
49
|
```
|
|
36
50
|
|
|
37
51
|
- Успех определяется `status:"success"` и/или **пустым** `errors`. Непустой `errors` / `status:"error"` /
|
|
38
|
-
top-level `error` — реальная
|
|
52
|
+
top-level `error` — реальная ошибка (мост маппит это в `ok:false`).
|
|
39
53
|
- REST-эндпоинты (`/rest/*.json`) отвечают иначе: `{ "result": …, "next", "total", "time" }` — без `errors`.
|
|
40
54
|
|
|
41
55
|
---
|
|
42
56
|
|
|
43
|
-
## 3.
|
|
57
|
+
## 3. Транспорт: form vs json (различается по методу!)
|
|
44
58
|
|
|
45
|
-
|
|
46
|
-
PHP-стилем (`filter[STATUS]=2`, `select[0]=ID`). Объект в `params` рекурсивно разворачивается в такие ключи.
|
|
59
|
+
У каждой записи каталога есть **`bodyType`** — как мост кодирует тело:
|
|
47
60
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
61
|
+
- **`bodyType: "form"`** (по умолчанию) — `application/x-www-form-urlencoded`; вложенность кодируется
|
|
62
|
+
PHP-стилем (`filter[STATUS]=2`, `select[0]=ID`). Объект в `params` рекурсивно разворачивается в такие
|
|
63
|
+
ключи. Классические `tasks.task.*`, мессенджер `im.v2.*`, REST — всё это форма.
|
|
64
|
+
- **`bodyType: "json"`** — тело уходит как `JSON.stringify(params)` с `Content-Type: application/json`.
|
|
65
|
+
Так работают **`tasks.v2.*`** (напр. `tasks.v2.Task.get` ждёт `{"task":{"id":N}}`) и `ui.entityselector.*`.
|
|
66
|
+
`params` при этом сохраняет вложенную структуру как есть (не разворачивается в bracket-ключи).
|
|
67
|
+
|
|
68
|
+
> Историческая заметка: раньше мост умел только форму, и `tasks.v2.*` были непригодны. Теперь
|
|
69
|
+
> поддержаны — в записи каталога ставь `"bodyType": "json"`, и мост отправит их корректно.
|
|
56
70
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
71
|
+
**CSRF / sessid:** мост всегда шлёт заголовок **`X-Bitrix-Csrf-Token: <sessid>`** (свежий
|
|
72
|
+
`BX.bitrix_sessid()`). Form-тела дополнительно несут `sessid` полем в теле (legacy REST это требует);
|
|
73
|
+
JSON-тела несут sessid **только** в заголовке. Ответ `invalid_csrf`/`invalid_authentication` = сессия
|
|
74
|
+
протухла (перелогинься в браузере).
|
|
60
75
|
|
|
61
|
-
|
|
62
|
-
|
|
76
|
+
| Метод (action / endpoint) | bodyType | Где `select`/`filter`/`order` | Пагинация |
|
|
77
|
+
|---|---|---|---|
|
|
78
|
+
| `tasks.task.list` | form | **верхний уровень**: `select[]`, `filter{}`, `order{}` | `start` (сдвиг, шаг 50) |
|
|
79
|
+
| `tasks.task.get` | form | верхний уровень: `taskId`, `select[]` | — |
|
|
80
|
+
| `tasks.v2.Task.get` | **json** | `{"task": {"id": N}}` | — |
|
|
81
|
+
| `tasks.v2.Scrum.getTaskInfo` | **json** | `{"taskId": N}` | — |
|
|
82
|
+
| `tasks.v2.File.listObjects` | **json** | `{"ids": [N,…]}` | — |
|
|
83
|
+
| `tasks.v2.Task.View.User.count` | **json** | `{"task": {"id": N}}` | — |
|
|
84
|
+
| `tasks.v2.Task.Relation.Child.list` | **json** | `{"taskId": N, "withIds":true, "navigation":{"size":N}}` | `navigation` |
|
|
85
|
+
| `tasks.v2.Task.Relation.Related.list` | **json** | `{"taskId": N, …}` (как Child) | `navigation` |
|
|
86
|
+
| `socialnetwork.api.workgroup.list` | form | **верхний уровень**: `select[]`, `order{}`, `filter{}` | (nav — не проверено) |
|
|
87
|
+
| `socialnetwork.api.workgroup.get` | form | **обёрнуто**: `params[groupId]`, `params[select][]` | — |
|
|
88
|
+
| `/rest/im.recent.list.json` | form (rest) | плоско: `LIMIT`, `SKIP_OPENLINES`, `UNREAD_ONLY`, … | `LIMIT` |
|
|
89
|
+
| `/rest/im.user.get.json` | form (rest) | плоско: `ID` | — |
|
|
90
|
+
| `im.v2.Recent.load` | form | плоско: `limit`, `filter[recentSection]`, `filter[unread]`, `filter[parentId]` | `im.v2.Recent.tail` |
|
|
91
|
+
| `im.v2.Recent.tail` | form | плоско: `limit`, `filter[lastMessageDate]` (курсор), `filter[recentSection]` | `filter[lastMessageDate]` |
|
|
92
|
+
| `im.v2.Chat.load` | form | плоско: `dialogId`\|`chatId`, `messageLimit` | — |
|
|
93
|
+
| `im.v2.Chat.getDialogId` | form | плоско: `externalId` | — |
|
|
94
|
+
| `im.v2.Chat.Message.list` | form | плоско: `chatId`, `limit` | только последняя страница — назад **не листает**, используй `.tail` |
|
|
95
|
+
| `im.v2.Chat.Message.tail` | form | плоско: `chatId`, `limit`, `filter[lastId]`, `order[id]` | **см. раздел 6** |
|
|
96
|
+
| `im.v2.Chat.Message.read` | form | плоско: `chatId`, `ids[]`, `actionUuid` | — (мутирующий) |
|
|
97
|
+
| `im.v2.Chat.readAll` | form | без параметров | — (мутирующий) |
|
|
98
|
+
| `ui.entityselector.load` | **json** | `{"dialog": {entities,preselectedItems,…}}` | — |
|
|
99
|
+
| `ui.entityselector.doSearch` | **json** | `{"dialog": {…}, "searchQuery": {"query": "...", "queryWords": ["..."]}}` | — |
|
|
63
100
|
|
|
64
101
|
---
|
|
65
102
|
|
|
66
|
-
## 4.
|
|
103
|
+
## 4. Каталог: имя → action → параметры
|
|
67
104
|
|
|
68
|
-
|
|
|
105
|
+
| Имя (`actions.json`) | action / endpoint | bodyType | Ключевые params |
|
|
69
106
|
|---|---|---|---|
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
107
|
+
| `tasks.list` | `tasks.task.list` | form | `filter{RESPONSIBLE_ID,REAL_STATUS,GROUP_ID,…}`, `select[]`, `order{}`, `start` |
|
|
108
|
+
| `task.get` | `tasks.task.get` | form | `taskId`, `select[]` |
|
|
109
|
+
| `task.v2.get` | `tasks.v2.Task.get` | json | `task.id` (id задачи) |
|
|
110
|
+
| `task.scrum.info` | `tasks.v2.Scrum.getTaskInfo` | json | `taskId` |
|
|
111
|
+
| `task.files` | `tasks.v2.File.listObjects` | json | `ids` (массив id) |
|
|
112
|
+
| `task.views.count` | `tasks.v2.Task.View.User.count` | json | `task.id` (id задачи) |
|
|
113
|
+
| `task.subtasks` | `tasks.v2.Task.Relation.Child.list` | json | `taskId`, `navigation{size}` |
|
|
114
|
+
| `task.related` | `tasks.v2.Task.Relation.Related.list` | json | `taskId`, `navigation{size}` |
|
|
115
|
+
| `projects.list` | `socialnetwork.api.workgroup.list` | form | `select[]`, `order{}`, `filter{}` |
|
|
116
|
+
| `projects.get` | `socialnetwork.api.workgroup.get` | form | `params[groupId]`, `params[select][]` |
|
|
117
|
+
| `chats.recent` | `/rest/im.recent.list.json` | form | `LIMIT`, `UNREAD_ONLY`, `SKIP_OPENLINES` |
|
|
118
|
+
| `recent.load` | `im.v2.Recent.load` | form | `filter[recentSection]` (`tasksTask`/`collab`/…), `limit`, `filter[unread]` |
|
|
119
|
+
| `recent.tail` | `im.v2.Recent.tail` | form | `filter[lastMessageDate]`, `filter[recentSection]`, `limit` |
|
|
120
|
+
| `chat.load` | `im.v2.Chat.load` | form | `dialogId`\|`chatId`, `messageLimit` |
|
|
121
|
+
| `chat.dialogId` | `im.v2.Chat.getDialogId` | form | `externalId` (напр. `"sg"+groupId`) |
|
|
122
|
+
| `chat.messages` | `im.v2.Chat.Message.list` | form | `chatId`, `limit` (последние; вглубь — `chat.messages.tail`) |
|
|
123
|
+
| `chat.messages.tail` | `im.v2.Chat.Message.tail` | form | `chatId`, `filter[lastId]`, `order[id]`, `limit` |
|
|
124
|
+
| `chat.message.read` | `im.v2.Chat.Message.read` | form | `chatId`, `ids[0]`, `actionUuid` |
|
|
125
|
+
| `chat.read.all` | `im.v2.Chat.readAll` | form | — (⚠ мутирующий) |
|
|
126
|
+
| `im.user.get` | `/rest/im.user.get.json` | form | `ID` |
|
|
127
|
+
| `entityselector.load` | `ui.entityselector.load` | json | `dialog` (объект) |
|
|
128
|
+
| `entityselector.search` | `ui.entityselector.doSearch` | json | `dialog`, `searchQuery{query,queryWords}` |
|
|
76
129
|
|
|
77
130
|
---
|
|
78
131
|
|
|
@@ -85,6 +138,10 @@ CSRF: контроллеры требуют `sessid` в теле — расши
|
|
|
85
138
|
Статусы задачи (`STATUS`): `1` Новая · `2` Ждёт выполнения · `3` Выполняется · `4` Ждёт контроля ·
|
|
86
139
|
`5` Завершена · `6` Отложена · `7` Отклонена.
|
|
87
140
|
|
|
141
|
+
**Задача v2** (`tasks.v2.*`): id задачи передаётся вложенно — **`{"task": {"id": N}}`** (у `Task.get` и
|
|
142
|
+
`Task.View.User.count`), а у `Scrum.getTaskInfo` и `Relation.*` — плоско `{"taskId": N}`. Это отдельная
|
|
143
|
+
подсистема scrum-борда; структуру ответа сверь реверсом — в захвате видны только параметры запроса.
|
|
144
|
+
|
|
88
145
|
**Группа/проект — список** (`workgroup.list`, camelCase в ответе): `ID`, `NAME`, `DESCRIPTION`,
|
|
89
146
|
`NUMBER_OF_MEMBERS`, `OWNER_ID`, `DATE_CREATE`, `PROJECT` (Y/N), `TYPE`.
|
|
90
147
|
**Группа — карточка** (`workgroup.get`): плюс `OWNER_DATA`, `SUBJECT_DATA`, `MEMBERS[]`,
|
|
@@ -92,12 +149,26 @@ CSRF: контроллеры требуют `sessid` в теле — расши
|
|
|
92
149
|
|
|
93
150
|
**Недавний чат** (`im.recent.list`): `chat_id`, `title`, `type`, `message{id,text,date,author_id}`,
|
|
94
151
|
`last_id`, `unread`, `pinned`, `user{…}`, `chat{…}`.
|
|
95
|
-
|
|
152
|
+
**Недавние по секции** (`im.v2.Recent.load`): фильтр `filter[recentSection]` — `default` (обычные
|
|
153
|
+
диалоги), **`tasksTask` (чаты задач)**, `collab`/`collabDefault` (коллабы). Листание вглубь —
|
|
154
|
+
`im.v2.Recent.tail` с курсором `filter[lastMessageDate]` (ISO-дата последнего элемента страницы).
|
|
155
|
+
**Карточка юзера** (`im.user.get`): `id`, `name`, `first_name`, `last_name`, `avatar`, `work_position`,
|
|
156
|
+
`gender`, `status`, `online` — резолв автора сообщения (`authorId`) в имя.
|
|
157
|
+
**Сообщение** (`im.v2.Chat.Message.*`): `id`, `chatId`, `authorId`, `date`, `text`, `params`, `viewed`.
|
|
96
158
|
Ответ также несёт `users[]` (участники), `additionalMessages[]`, `hasPrevPage`/`hasNextPage`.
|
|
159
|
+
`chatId` берётся из `im.recent.list` (`chat_id`) или из `workgroup.get` (`CHAT_ID`/`DIALOG_ID`).
|
|
160
|
+
|
|
161
|
+
**Адресация чата (`chat.load`): `dialogId` vs `chatId`.** `chat.load` принимает любой из двух:
|
|
162
|
+
- `dialogId` = **ID пользователя** (число, напр. `11`) → **личный чат 1-на-1** с этим пользователем.
|
|
163
|
+
- `dialogId` = **`"chat"+CHAT_ID`** (напр. `"chat7111"`) → **групповой чат** (проекта/задачи/канала).
|
|
164
|
+
- `chatId` = числовой `CHAT_ID` — то же, что групповой `dialogId`, но без префикса.
|
|
165
|
+
|
|
166
|
+
Ответ `chat.load` возвращает числовой `chatId` — используй его дальше для `chat.messages` /
|
|
167
|
+
`chat.messages.tail` (листание вглубь) и `chat.message.read` (эти три работают по `chatId`, не по `dialogId`).
|
|
97
168
|
|
|
98
169
|
---
|
|
99
170
|
|
|
100
|
-
## 6. Примеры
|
|
171
|
+
## 6. Примеры вызовов
|
|
101
172
|
|
|
102
173
|
```jsonc
|
|
103
174
|
// открытые задачи ответственного 55, по дедлайну, вторая страница
|
|
@@ -107,24 +178,142 @@ bitrix_tasks_list { "params": { "filter": {"RESPONSIBLE_ID":55,"REAL_STATUS":2},
|
|
|
107
178
|
// карточка задачи с расширенным набором полей
|
|
108
179
|
bitrix_task_get { "taskId": 4229, "params": { "select": ["ID","TITLE","DESCRIPTION","TAGS","TIME_ESTIMATE"] } }
|
|
109
180
|
|
|
110
|
-
//
|
|
111
|
-
|
|
181
|
+
// карточка задачи через v2-подсистему (JSON-тело; id вложен в task)
|
|
182
|
+
bitrix_task_get_v2 { "taskId": 4229 } // → { "task": { "id": 4229 } }
|
|
183
|
+
bitrix_call { "name": "task.v2.get", "params": { "task": { "id": 4229 } } }
|
|
112
184
|
|
|
113
|
-
//
|
|
185
|
+
// файлы задачи и счётчик просмотров (v2, JSON-тело); подзадачи/связанные
|
|
186
|
+
bitrix_call { "name": "task.files", "params": { "ids": [4229] } }
|
|
187
|
+
bitrix_call { "name": "task.views.count", "params": { "task": { "id": 4229 } } }
|
|
188
|
+
bitrix_task_subtasks { "taskId": 4229 }
|
|
189
|
+
bitrix_task_related { "taskId": 4229 }
|
|
190
|
+
|
|
191
|
+
// проекты по дате создания; полная карточка группы
|
|
192
|
+
bitrix_projects_list { "params": { "order": {"DATE_CREATE":"desc"} } }
|
|
114
193
|
bitrix_project_get { "groupId": 15 }
|
|
115
194
|
|
|
116
|
-
//
|
|
117
|
-
|
|
195
|
+
// открыть чат (первые сообщения)
|
|
196
|
+
bitrix_chat_load { "chatId": 485, "messageLimit": 50 }
|
|
197
|
+
|
|
198
|
+
// ЛИСТАНИЕ ИСТОРИИ ВГЛУБЬ (старые сообщения): beforeId = минимальный id сообщения
|
|
199
|
+
// из текущей страницы. Повторяй, уменьшая beforeId, до начала истории (order DESC — дефолт).
|
|
200
|
+
bitrix_chat_history { "chatId": 485, "beforeId": 1861279 }
|
|
201
|
+
|
|
202
|
+
// пометить сообщения прочитанными (МУТИРУЮЩИЙ). actionUuid генерируется автоматически.
|
|
203
|
+
bitrix_chat_mark_read { "chatId": 40271, "ids": [1884131] }
|
|
118
204
|
```
|
|
119
205
|
|
|
206
|
+
### 6.1. Сценарий: чат с конкретным пользователем
|
|
207
|
+
|
|
208
|
+
Личный чат 1-на-1 адресуется `dialogId` = **ID пользователя**. Id берётся из задачи
|
|
209
|
+
(`RESPONSIBLE_ID`/`CREATED_BY`), из `bitrix_chats_recent`, либо резолвится поиском (§6.3).
|
|
210
|
+
|
|
211
|
+
```jsonc
|
|
212
|
+
// 1) открыть личный чат с пользователем 11 → в ответе будет числовой chatId
|
|
213
|
+
bitrix_chat_load { "dialogId": 11 }
|
|
214
|
+
// 2) листать его историю вглубь по chatId из ответа шага 1
|
|
215
|
+
bitrix_chat_history { "chatId": 485, "beforeId": 1861279 }
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### 6.2. Сценарий: обсуждение (чат) конкретной задачи
|
|
219
|
+
|
|
220
|
+
У каждой задачи есть свой im-чат-обсуждение. Два пути найти его `chatId`:
|
|
221
|
+
|
|
222
|
+
**А. Через список чатов задач (прямой).** `im.v2.Recent.load` с секцией `tasksTask` отдаёт чаты задач
|
|
223
|
+
(в `bitrix_chats_recent` / `/rest/im.recent.list` их НЕТ). Листать вглубь — `bitrix_recent_tail`.
|
|
224
|
+
|
|
225
|
+
```jsonc
|
|
226
|
+
bitrix_recent_load { "section": "tasksTask" } // → чаты задач с chatId/dialogId
|
|
227
|
+
bitrix_recent_tail { "section": "tasksTask", "lastMessageDate": "2026-06-29T17:25:38+03:00" }
|
|
228
|
+
// открыть найденный чат и листать историю
|
|
229
|
+
bitrix_chat_load { "dialogId": "chat38849" } // или { "chatId": 38849 }
|
|
230
|
+
bitrix_chat_history { "chatId": 38849, "beforeId": 1722353 }
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
**Б. Поиском по названию задачи** — `bitrix_entity_search` с секцией `tasksTask`:
|
|
234
|
+
|
|
235
|
+
```jsonc
|
|
236
|
+
bitrix_entity_search { "query": "трекер", "section": "tasksTask" }
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
**Чат ПРОЕКТА задачи** (обсуждение группы, не самой задачи) — через `GROUP_ID`:
|
|
240
|
+
|
|
241
|
+
```jsonc
|
|
242
|
+
bitrix_task_get { "taskId": 4229, "params": { "select": ["ID","GROUP_ID"] } }
|
|
243
|
+
bitrix_project_get { "groupId": 15 } // отдаёт CHAT_ID / DIALOG_ID
|
|
244
|
+
bitrix_chat_load { "dialogId": "chat7111" }
|
|
245
|
+
bitrix_chat_get_dialog_id { "externalId": "sg15" } // либо резолв dialogId соцгруппы напрямую
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### 6.3. Сценарий: поиск чата / пользователя
|
|
249
|
+
|
|
250
|
+
Текстовый поиск — `bitrix_entity_search` (обёртка над `ui.entityselector.doSearch`): сам собирает
|
|
251
|
+
диалог `IM_CHAT_SEARCH` и `searchQuery` из строки:
|
|
252
|
+
|
|
253
|
+
```jsonc
|
|
254
|
+
bitrix_entity_search { "query": "дмитрий" } // среди всех чатов/диалогов
|
|
255
|
+
bitrix_entity_search { "query": "трекер", "section": "tasksTask" } // среди чатов задач
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Быстрый путь без поиска — недавние чаты и фильтрация на стороне агента; карточка автора по id:
|
|
259
|
+
|
|
260
|
+
```jsonc
|
|
261
|
+
bitrix_chats_recent { } // сопоставь по title / user
|
|
262
|
+
bitrix_recent_load { "section": "tasksTask" }
|
|
263
|
+
bitrix_user_get { "userId": 11 } // резолв authorId → имя
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### 6.4. Легаси-комментарии задачи (HTML-поддомен — пока НЕ в мосте)
|
|
267
|
+
|
|
268
|
+
У задач два независимых фида обсуждения:
|
|
269
|
+
- **im.v2-чат** — структурный JSON, читается уже сейчас (§6.2); обычно этого достаточно.
|
|
270
|
+
- **Форумные легаси-комментарии** — рендерятся как **HTML** в side-slider'е. Это отдельный
|
|
271
|
+
«HTML-поддомен» внутреннего API, который **текущий мост не поддерживает** (блокеры ниже).
|
|
272
|
+
|
|
273
|
+
**Как грузятся (реверс).** Первая страница — GET HTML-страницы iframe (сервер тут же минтит подпись):
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
GET /task/comments/<taskId>/?IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER → HTML (комментарии + signedParameters)
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Листание — POST компонентного ajax (форма, отдаёт HTML-фрагмент):
|
|
280
|
+
|
|
281
|
+
```
|
|
282
|
+
POST /bitrix/services/main/ajax.php?mode=class&c=bitrix:forum.comments&action=navigateComment
|
|
283
|
+
form: AJAX_POST=Y, ENTITY_XML_ID=TASK_<taskId>, taskId=<taskId>, MODE=LIST,
|
|
284
|
+
FILTER[<ID]=<курсор: id, ДО которого грузить старые>, PAGEN_1=1,
|
|
285
|
+
signedParameters=<подписанный blob>, IFRAME=Y, IFRAME_TYPE=SIDE_SLIDER
|
|
286
|
+
headers: bx-ajax: true, x-bitrix-site-id: s1 (плюс обычный X-Bitrix-Csrf-Token)
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
`signedParameters` — base64 PHP-массива + HMAC-подпись сервера; кодирует
|
|
290
|
+
`FORUM_ID, ENTITY_TYPE=TK, ENTITY_ID=<taskId>, ENTITY_XML_ID=TASK_<taskId>, …`. **Подделать нельзя** —
|
|
291
|
+
берётся из HTML первой страницы.
|
|
292
|
+
|
|
293
|
+
**Почему пока не в каталоге (3 блокера):**
|
|
294
|
+
1. Мост парсит ответ только как JSON (`extension/src/connector.ts` → `resp.json()`) — HTML бросит исключение.
|
|
295
|
+
2. Path-параметр в URL (`/task/comments/<taskId>/`) — записи каталога статичны, шаблонов пути нет.
|
|
296
|
+
3. `signedParameters` + заголовки `bx-ajax`/`x-bitrix-site-id` — нужен предварительный GET HTML-страницы.
|
|
297
|
+
|
|
298
|
+
**Чтобы подключить** (будущая работа): научить мост возвращать text/HTML при не-JSON ответе и
|
|
299
|
+
поддержать path-шаблон эндпоинта; затем обёртка `bitrix_task_comments { taskId }` (GET первой
|
|
300
|
+
страницы), а листание — через `navigateComment` с выпарсенным `signedParameters`.
|
|
301
|
+
|
|
302
|
+
> Тот же HTML-поддомен: **детали звонка** — `GET /call/detail/<callId>?IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER`
|
|
303
|
+
> (отдаёт HTML). Ограничения идентичны.
|
|
304
|
+
|
|
120
305
|
---
|
|
121
306
|
|
|
122
307
|
## 7. Как расширить (новый домен: календарь, диск, CRM, …)
|
|
123
308
|
|
|
124
|
-
1. Сними реальные вызовы (`docs/reconnaissance.md` — авто-запись `bun run capture` или HAR
|
|
125
|
-
|
|
126
|
-
|
|
309
|
+
1. Сними реальные вызовы (`docs/reconnaissance.md` — авто-запись `bun run capture` или HAR →
|
|
310
|
+
`bun run catalog:draft`). Черновик `actions.draft.json` накапливает **все уникальные комбинации
|
|
311
|
+
параметров** на экшен и проставляет `bodyType` (form/json) автоматически.
|
|
312
|
+
2. Определи транспорт по разделу 3: если черновик показал `"bodyType": "json"` — перенеси его в запись.
|
|
313
|
+
3. Добавь запись в `actions.json` (может быть мутирующей — каталог это допускает). Проверь через
|
|
314
|
+
`bitrix_call { name, params }`.
|
|
127
315
|
4. Если удобно — оберни в типизированный инструмент в `src/tools/register.ts` (с дефолтным `select`).
|
|
128
316
|
|
|
129
|
-
> `actions.json` — данные конкретного портала (gitignored). Этот файл
|
|
130
|
-
> знания о самом API; держи его в актуальном состоянии при добавлении
|
|
317
|
+
> `actions.json` / `actions.draft.json` — данные конкретного портала (gitignored). Этот файл
|
|
318
|
+
> (`api-notes.md`) — переносимые знания о самом API; держи его в актуальном состоянии при добавлении
|
|
319
|
+
> новых методов.
|
|
@@ -12,8 +12,11 @@
|
|
|
12
12
|
return out.toString();
|
|
13
13
|
}
|
|
14
14
|
function buildRequest(origin, req, sessid) {
|
|
15
|
-
let q = req.action ? `?action=${encodeURIComponent(req.action)}` : "", url = `${origin}${req.endpoint}${q}
|
|
16
|
-
|
|
15
|
+
let q = req.action ? `?action=${encodeURIComponent(req.action)}` : "", url = `${origin}${req.endpoint}${q}`;
|
|
16
|
+
if (req.bodyType === "json")
|
|
17
|
+
return { url, body: JSON.stringify(req.params), contentType: "application/json" };
|
|
18
|
+
let body = encodeForm({ ...req.params, sessid });
|
|
19
|
+
return { url, body, contentType: "application/x-www-form-urlencoded" };
|
|
17
20
|
}
|
|
18
21
|
function interpret(json) {
|
|
19
22
|
let list = json && (Array.isArray(json.errors) ? json.errors : json.error ? [{ code: json.error }] : []), hasErrors = Array.isArray(list) && list.length > 0;
|
|
@@ -72,10 +75,11 @@
|
|
|
72
75
|
async function handleCall(req) {
|
|
73
76
|
let sessid = await freshSessid();
|
|
74
77
|
if (!sessid) return { ok: !1, error: "session context not ready \u2014 open a normal Bitrix24 portal tab" };
|
|
75
|
-
let { url, body } = buildRequest(ORIGIN, req, sessid), init = {
|
|
78
|
+
let { url, body, contentType } = buildRequest(ORIGIN, req, sessid), init = {
|
|
76
79
|
method: req.method,
|
|
77
80
|
credentials: "include",
|
|
78
|
-
|
|
81
|
+
// sessid rides the CSRF header for all ajax (v2 form + json); form bodies also carry it inline.
|
|
82
|
+
headers: { "Content-Type": contentType, "X-Bitrix-Csrf-Token": sessid }
|
|
79
83
|
}, finalUrl = url;
|
|
80
84
|
req.method === "POST" ? init.body = body : finalUrl += (url.includes("?") ? "&" : "?") + body;
|
|
81
85
|
let json = await (await fetch(finalUrl, init)).json();
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["../src/bridge-core.ts", "../src/bridge-protocol.ts", "../src/connector.ts"],
|
|
4
|
-
"sourcesContent": ["// Pure, browser-agnostic \u2014 unit-tested.\n\n// Wire types come from the shared single source; re-exported so downstream\n// extension modules keep importing them from here.\nimport type { CallRequest } from \"../../shared/wire.ts\";\nexport type { CallRequest, CapturedEntry } from \"../../shared/wire.ts\";\n\n// Extension-only: the shape handleCall returns to the bridge (not a wire message).\nexport interface InterpretResult {\n ok: boolean;\n data?: unknown;\n error?: string;\n}\n\nexport function encodeForm(params: Record<string, unknown>): string {\n const out = new URLSearchParams();\n const add = (key: string, val: unknown): void => {\n if (val === null || val === undefined) return;\n if (Array.isArray(val)) val.forEach((v, i) => add(`${key}[${i}]`, v));\n else if (typeof val === \"object\") for (const [k, v] of Object.entries(val)) add(`${key}[${k}]`, v);\n else out.set(key, String(val));\n };\n for (const [k, v] of Object.entries(params)) add(k, v);\n return out.toString();\n}\n\nexport function buildRequest(\n origin: string,\n req: CallRequest,\n sessid: string,\n): { url: string; body: string } {\n const q = req.action ? `?action=${encodeURIComponent(req.action)}` : \"\";\n const url = `${origin}${req.endpoint}${q}`;\n const body = encodeForm({ ...req.params, sessid });\n return { url, body };\n}\n\n// Bitrix wraps errors in HTTP 200: { status:\"error\", errors:[{code}] } or { error, error_description }.\n// NOTE: successful ajax responses carry an EMPTY `errors: []` array \u2014 a truthy value in JS \u2014 so we\n// must treat only a NON-EMPTY errors list (or status:\"error\"/a top-level error) as a real failure.\nexport function interpret(json: any): InterpretResult {\n const list = json && (Array.isArray(json.errors) ? json.errors : json.error ? [{ code: json.error }] : []);\n const hasErrors = Array.isArray(list) && list.length > 0;\n if (json && (json.status === \"error\" || hasErrors)) {\n const first = list[0];\n const code = (first && (first.code || first.message)) || json.error || \"bitrix_error\";\n const description = json.error_description || (first && first.message);\n const error = description && description !== code ? `${code}: ${description}` : code;\n return { ok: false, error, data: json };\n }\n return { ok: true, data: json };\n}\n", "// Pure, browser-agnostic \u2014 unit-tested. No DOM / chrome / window.BX here.\n//\n// Two concerns live together because both are the *contract* between the extension's\n// two content scripts and the packaged config, and both are pure/testable:\n// 1) parseConfig \u2014 validate the per-user config.json ({ token, port }).\n// 2) the postMessage protocol \u2014 the envelopes the ISOLATED connector and the MAIN\n// script exchange over window.postMessage (sessid request/response, and \u2014 in the\n// capture build \u2014 MAIN-observed capture entries forwarded to the connector).\n\nimport type { CapturedEntry } from \"./bridge-core.ts\";\n\nexport interface BridgeConfig {\n token: string;\n port: number;\n}\n\n/**\n * Parse and validate the packaged config.json body. Throws with a clear,\n * user-facing message (mentioning config.json) on any malformed input so the\n * connector can surface why it failed to start.\n */\nexport function parseConfig(raw: string): BridgeConfig {\n let doc: unknown;\n try {\n doc = JSON.parse(raw);\n } catch {\n throw new Error(\"config.json is not valid JSON\");\n }\n if (typeof doc !== \"object\" || doc === null) {\n throw new Error(\"config.json must be an object like { token, port }\");\n }\n const obj = doc as Record<string, unknown>;\n const token = typeof obj.token === \"string\" ? obj.token.trim() : \"\";\n if (!token) throw new Error(\"config.json is missing a non-empty `token`\");\n const port = Number(obj.port);\n if (!Number.isInteger(port) || port < 1 || port > 65535) {\n throw new Error(\"config.json is missing a numeric `port`\");\n }\n return { token, port };\n}\n\n// --- sessid postMessage protocol -------------------------------------------\n//\n// window.postMessage is delivered to BOTH the MAIN and ISOLATED worlds of the same\n// frame (they share the DOM window), and each world also receives its own posts. So\n// every envelope is tagged with a fixed `source` and a `kind`, and each side ignores\n// anything that isn't addressed to it. Responses additionally carry the request nonce\n// so the connector can match a reply to the exact in-flight request it issued.\n\nexport const BRIDGE_MSG_SOURCE = \"bitrix24-mcp-bridge\";\n\nexport interface SessidRequestMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"sessid-request\";\n nonce: string;\n}\n\nexport interface SessidResponseMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"sessid-response\";\n nonce: string;\n sessid: string;\n}\n\nexport function buildSessidRequest(nonce: string): SessidRequestMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-request\", nonce };\n}\n\nexport function buildSessidResponse(nonce: string, sessid: string): SessidResponseMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-response\", nonce, sessid };\n}\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n return typeof v === \"object\" && v !== null;\n}\n\n/** For the MAIN shim: a well-formed request from our connector, or null. */\nexport function parseSessidRequest(data: unknown): SessidRequestMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"sessid-request\") return null;\n if (typeof data.nonce !== \"string\") return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-request\", nonce: data.nonce };\n}\n\n/** For the ISOLATED connector: a response matching `expectedNonce`, or null. */\nexport function parseSessidResponse(data: unknown, expectedNonce: string): SessidResponseMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"sessid-response\") return null;\n if (typeof data.nonce !== \"string\" || data.nonce !== expectedNonce) return null;\n if (typeof data.sessid !== \"string\") return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-response\", nonce: data.nonce, sessid: data.sessid };\n}\n\n// --- capture forwarding (capture build only) -------------------------------\n//\n// The capture hooks must observe the PAGE's fetch/XHR, so they run in the MAIN world.\n// The socket lives only in the ISOLATED connector, so MAIN forwards each observed entry\n// to the connector over postMessage; the connector relays it to the daemon.\n\nexport interface CaptureForwardMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"capture\";\n call: CapturedEntry;\n}\n\nexport function buildCaptureForward(call: CapturedEntry): CaptureForwardMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"capture\", call };\n}\n\n/** For the ISOLATED connector: a capture entry forwarded by the MAIN script, or null. */\nexport function parseCaptureForward(data: unknown): CaptureForwardMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"capture\") return null;\n if (!isRecord(data.call)) return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"capture\", call: data.call as unknown as CapturedEntry };\n}\n", "// ISOLATED-world connector. This is where the token and the WebSocket live \u2014 never in\n// the page's MAIN world, so the page cannot read the token without knowing the dynamic\n// (`use_dynamic_url`) resource URL for config.json, and cannot hijack the socket. It has\n// `chrome.runtime`, so it loads the per-user config from the packaged config.json at\n// runtime (nothing per-user is baked into this JS \u2014 the file is static). The actual\n// boundary is `use_dynamic_url: true` on config.json in the manifest: it makes the\n// resource URL unguessable from the page while `chrome.runtime.getURL()` here still\n// resolves it.\n//\n// Per daemon call it asks the MAIN shim for a FRESH sessid over postMessage (nonce-matched),\n// then reuses the pure bridge-core helpers to build the request, fetch it with the page's\n// cookies, and interpret the response.\n\nimport { buildRequest, interpret, type CallRequest, type InterpretResult } from \"./bridge-core.ts\";\nimport {\n parseConfig,\n buildSessidRequest,\n parseSessidResponse,\n parseCaptureForward,\n type BridgeConfig,\n} from \"./bridge-protocol.ts\";\n\n// Gates the capture relay listener; stripped from normal builds via esbuild `define`.\ndeclare const __BITRIX_CAPTURE__: boolean;\n\n// Minimal ambient for the one chrome API we use (no @types/chrome dependency).\ndeclare const chrome: { runtime: { getURL(path: string): string } };\n\nconst ORIGIN = location.origin;\nconst SESSID_TIMEOUT_MS = 2000;\nconst RECONNECT_MS = 3000;\n\nlet socket: WebSocket | null = null;\nlet nonceSeq = 0;\n\n/** Ask the MAIN shim for a fresh sessid; resolves \"\" if it doesn't answer in time. */\nfunction freshSessid(): Promise<string> {\n const nonce = `${Date.now()}-${nonceSeq++}-${Math.random().toString(36).slice(2)}`;\n return new Promise((resolve) => {\n const onMsg = (ev: MessageEvent): void => {\n if (ev.source !== window) return;\n const res = parseSessidResponse(ev.data, nonce);\n if (!res) return;\n cleanup();\n resolve(res.sessid);\n };\n const timer = setTimeout(() => {\n cleanup();\n resolve(\"\");\n }, SESSID_TIMEOUT_MS);\n const cleanup = (): void => {\n clearTimeout(timer);\n window.removeEventListener(\"message\", onMsg);\n };\n window.addEventListener(\"message\", onMsg);\n window.postMessage(buildSessidRequest(nonce), ORIGIN);\n });\n}\n\nasync function handleCall(req: CallRequest): Promise<InterpretResult> {\n const sessid = await freshSessid();\n if (!sessid) return { ok: false, error: \"session context not ready \u2014 open a normal Bitrix24 portal tab\" }; // G5\n const { url, body } = buildRequest(ORIGIN, req, sessid);\n const init: RequestInit = {\n method: req.method,\n credentials: \"include\",\n headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n };\n let finalUrl = url;\n if (req.method === \"POST\") init.body = body;\n else finalUrl += (url.includes(\"?\") ? \"&\" : \"?\") + body;\n const resp = await fetch(finalUrl, init);\n const json = await resp.json();\n return interpret(json); // G3\n}\n\nfunction connect(config: BridgeConfig): void {\n const ws = new WebSocket(`ws://127.0.0.1:${config.port}`);\n ws.addEventListener(\"open\", () => {\n ws.send(JSON.stringify({ type: \"auth\", token: config.token })); // auth first (server closes non-auth)\n socket = ws;\n });\n ws.addEventListener(\"message\", async (ev: MessageEvent) => {\n let req: CallRequest;\n try {\n req = JSON.parse(ev.data) as CallRequest;\n } catch (e) {\n console.error(\"[bitrix-bridge] malformed WS frame, dropping:\", e);\n return;\n }\n if (req.type !== \"call\") return;\n try {\n const r = await handleCall(req);\n ws.send(JSON.stringify({ type: \"result\", id: req.id, ok: r.ok, data: r.data, error: r.error }));\n } catch (e) {\n ws.send(JSON.stringify({ type: \"result\", id: req.id, ok: false, error: String(e) }));\n }\n });\n ws.addEventListener(\"close\", () => {\n if (socket === ws) socket = null;\n setTimeout(() => connect(config), RECONNECT_MS); // auto-reconnect\n });\n}\n\n// Capture build only: relay MAIN-observed capture entries to the daemon.\nif (__BITRIX_CAPTURE__) {\n window.addEventListener(\"message\", (ev: MessageEvent) => {\n if (ev.source !== window) return;\n const fwd = parseCaptureForward(ev.data);\n if (!fwd) return;\n if (socket && socket.readyState === WebSocket.OPEN) {\n socket.send(JSON.stringify({ type: \"capture\", call: fwd.call }));\n }\n });\n}\n\nasync function start(): Promise<void> {\n let config: BridgeConfig;\n try {\n const resp = await fetch(chrome.runtime.getURL(\"config.json\"));\n if (!resp.ok) throw new Error(`HTTP ${resp.status}`);\n config = parseConfig(await resp.text());\n } catch (e) {\n // Nothing to fall back to \u2014 surface why the bridge won't start and stop.\n console.error(\"[bitrix-bridge] cannot load config.json:\", e);\n return;\n }\n connect(config);\n}\n\nstart();\n"],
|
|
5
|
-
"mappings": ";;;AAcO,WAAS,WAAW,QAAyC;AAClE,QAAM,MAAM,IAAI,gBAAgB,GAC1B,MAAM,CAAC,KAAa,QAAuB;AAC/C,UAAI,OAAQ;AACZ,YAAI,MAAM,QAAQ,GAAG,EAAG,KAAI,QAAQ,CAAC,GAAG,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AAAA,iBAC3D,OAAO,OAAQ,SAAU,UAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,EAAG,KAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;AAAA,YAC5F,KAAI,IAAI,KAAK,OAAO,GAAG,CAAC;AAAA,IAC/B;AACA,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,MAAM,EAAG,KAAI,GAAG,CAAC;AACrD,WAAO,IAAI,SAAS;AAAA,EACtB;AAEO,WAAS,aACd,QACA,KACA,
|
|
4
|
+
"sourcesContent": ["// Pure, browser-agnostic \u2014 unit-tested.\n\n// Wire types come from the shared single source; re-exported so downstream\n// extension modules keep importing them from here.\nimport type { CallRequest } from \"../../shared/wire.ts\";\nexport type { CallRequest, CapturedEntry } from \"../../shared/wire.ts\";\n\n// Extension-only: the shape handleCall returns to the bridge (not a wire message).\nexport interface InterpretResult {\n ok: boolean;\n data?: unknown;\n error?: string;\n}\n\nexport function encodeForm(params: Record<string, unknown>): string {\n const out = new URLSearchParams();\n const add = (key: string, val: unknown): void => {\n if (val === null || val === undefined) return;\n if (Array.isArray(val)) val.forEach((v, i) => add(`${key}[${i}]`, v));\n else if (typeof val === \"object\") for (const [k, v] of Object.entries(val)) add(`${key}[${k}]`, v);\n else out.set(key, String(val));\n };\n for (const [k, v] of Object.entries(params)) add(k, v);\n return out.toString();\n}\n\nexport function buildRequest(\n origin: string,\n req: CallRequest,\n sessid: string,\n): { url: string; body: string; contentType: string } {\n const q = req.action ? `?action=${encodeURIComponent(req.action)}` : \"\";\n const url = `${origin}${req.endpoint}${q}`;\n // JSON actions (ui.entityselector.*, tasks.v2.*) send a JSON body; sessid rides the\n // X-Bitrix-Csrf-Token header (added by the caller), never the body.\n if (req.bodyType === \"json\") {\n return { url, body: JSON.stringify(req.params), contentType: \"application/json\" };\n }\n const body = encodeForm({ ...req.params, sessid });\n return { url, body, contentType: \"application/x-www-form-urlencoded\" };\n}\n\n// Bitrix wraps errors in HTTP 200: { status:\"error\", errors:[{code}] } or { error, error_description }.\n// NOTE: successful ajax responses carry an EMPTY `errors: []` array \u2014 a truthy value in JS \u2014 so we\n// must treat only a NON-EMPTY errors list (or status:\"error\"/a top-level error) as a real failure.\nexport function interpret(json: any): InterpretResult {\n const list = json && (Array.isArray(json.errors) ? json.errors : json.error ? [{ code: json.error }] : []);\n const hasErrors = Array.isArray(list) && list.length > 0;\n if (json && (json.status === \"error\" || hasErrors)) {\n const first = list[0];\n const code = (first && (first.code || first.message)) || json.error || \"bitrix_error\";\n const description = json.error_description || (first && first.message);\n const error = description && description !== code ? `${code}: ${description}` : code;\n return { ok: false, error, data: json };\n }\n return { ok: true, data: json };\n}\n", "// Pure, browser-agnostic \u2014 unit-tested. No DOM / chrome / window.BX here.\n//\n// Two concerns live together because both are the *contract* between the extension's\n// two content scripts and the packaged config, and both are pure/testable:\n// 1) parseConfig \u2014 validate the per-user config.json ({ token, port }).\n// 2) the postMessage protocol \u2014 the envelopes the ISOLATED connector and the MAIN\n// script exchange over window.postMessage (sessid request/response, and \u2014 in the\n// capture build \u2014 MAIN-observed capture entries forwarded to the connector).\n\nimport type { CapturedEntry } from \"./bridge-core.ts\";\n\nexport interface BridgeConfig {\n token: string;\n port: number;\n}\n\n/**\n * Parse and validate the packaged config.json body. Throws with a clear,\n * user-facing message (mentioning config.json) on any malformed input so the\n * connector can surface why it failed to start.\n */\nexport function parseConfig(raw: string): BridgeConfig {\n let doc: unknown;\n try {\n doc = JSON.parse(raw);\n } catch {\n throw new Error(\"config.json is not valid JSON\");\n }\n if (typeof doc !== \"object\" || doc === null) {\n throw new Error(\"config.json must be an object like { token, port }\");\n }\n const obj = doc as Record<string, unknown>;\n const token = typeof obj.token === \"string\" ? obj.token.trim() : \"\";\n if (!token) throw new Error(\"config.json is missing a non-empty `token`\");\n const port = Number(obj.port);\n if (!Number.isInteger(port) || port < 1 || port > 65535) {\n throw new Error(\"config.json is missing a numeric `port`\");\n }\n return { token, port };\n}\n\n// --- sessid postMessage protocol -------------------------------------------\n//\n// window.postMessage is delivered to BOTH the MAIN and ISOLATED worlds of the same\n// frame (they share the DOM window), and each world also receives its own posts. So\n// every envelope is tagged with a fixed `source` and a `kind`, and each side ignores\n// anything that isn't addressed to it. Responses additionally carry the request nonce\n// so the connector can match a reply to the exact in-flight request it issued.\n\nexport const BRIDGE_MSG_SOURCE = \"bitrix24-mcp-bridge\";\n\nexport interface SessidRequestMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"sessid-request\";\n nonce: string;\n}\n\nexport interface SessidResponseMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"sessid-response\";\n nonce: string;\n sessid: string;\n}\n\nexport function buildSessidRequest(nonce: string): SessidRequestMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-request\", nonce };\n}\n\nexport function buildSessidResponse(nonce: string, sessid: string): SessidResponseMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-response\", nonce, sessid };\n}\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n return typeof v === \"object\" && v !== null;\n}\n\n/** For the MAIN shim: a well-formed request from our connector, or null. */\nexport function parseSessidRequest(data: unknown): SessidRequestMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"sessid-request\") return null;\n if (typeof data.nonce !== \"string\") return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-request\", nonce: data.nonce };\n}\n\n/** For the ISOLATED connector: a response matching `expectedNonce`, or null. */\nexport function parseSessidResponse(data: unknown, expectedNonce: string): SessidResponseMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"sessid-response\") return null;\n if (typeof data.nonce !== \"string\" || data.nonce !== expectedNonce) return null;\n if (typeof data.sessid !== \"string\") return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"sessid-response\", nonce: data.nonce, sessid: data.sessid };\n}\n\n// --- capture forwarding (capture build only) -------------------------------\n//\n// The capture hooks must observe the PAGE's fetch/XHR, so they run in the MAIN world.\n// The socket lives only in the ISOLATED connector, so MAIN forwards each observed entry\n// to the connector over postMessage; the connector relays it to the daemon.\n\nexport interface CaptureForwardMsg {\n source: typeof BRIDGE_MSG_SOURCE;\n kind: \"capture\";\n call: CapturedEntry;\n}\n\nexport function buildCaptureForward(call: CapturedEntry): CaptureForwardMsg {\n return { source: BRIDGE_MSG_SOURCE, kind: \"capture\", call };\n}\n\n/** For the ISOLATED connector: a capture entry forwarded by the MAIN script, or null. */\nexport function parseCaptureForward(data: unknown): CaptureForwardMsg | null {\n if (!isRecord(data)) return null;\n if (data.source !== BRIDGE_MSG_SOURCE || data.kind !== \"capture\") return null;\n if (!isRecord(data.call)) return null;\n return { source: BRIDGE_MSG_SOURCE, kind: \"capture\", call: data.call as unknown as CapturedEntry };\n}\n", "// ISOLATED-world connector. This is where the token and the WebSocket live \u2014 never in\n// the page's MAIN world, so the page cannot read the token without knowing the dynamic\n// (`use_dynamic_url`) resource URL for config.json, and cannot hijack the socket. It has\n// `chrome.runtime`, so it loads the per-user config from the packaged config.json at\n// runtime (nothing per-user is baked into this JS \u2014 the file is static). The actual\n// boundary is `use_dynamic_url: true` on config.json in the manifest: it makes the\n// resource URL unguessable from the page while `chrome.runtime.getURL()` here still\n// resolves it.\n//\n// Per daemon call it asks the MAIN shim for a FRESH sessid over postMessage (nonce-matched),\n// then reuses the pure bridge-core helpers to build the request, fetch it with the page's\n// cookies, and interpret the response.\n\nimport { buildRequest, interpret, type CallRequest, type InterpretResult } from \"./bridge-core.ts\";\nimport {\n parseConfig,\n buildSessidRequest,\n parseSessidResponse,\n parseCaptureForward,\n type BridgeConfig,\n} from \"./bridge-protocol.ts\";\n\n// Gates the capture relay listener; stripped from normal builds via esbuild `define`.\ndeclare const __BITRIX_CAPTURE__: boolean;\n\n// Minimal ambient for the one chrome API we use (no @types/chrome dependency).\ndeclare const chrome: { runtime: { getURL(path: string): string } };\n\nconst ORIGIN = location.origin;\nconst SESSID_TIMEOUT_MS = 2000;\nconst RECONNECT_MS = 3000;\n\nlet socket: WebSocket | null = null;\nlet nonceSeq = 0;\n\n/** Ask the MAIN shim for a fresh sessid; resolves \"\" if it doesn't answer in time. */\nfunction freshSessid(): Promise<string> {\n const nonce = `${Date.now()}-${nonceSeq++}-${Math.random().toString(36).slice(2)}`;\n return new Promise((resolve) => {\n const onMsg = (ev: MessageEvent): void => {\n if (ev.source !== window) return;\n const res = parseSessidResponse(ev.data, nonce);\n if (!res) return;\n cleanup();\n resolve(res.sessid);\n };\n const timer = setTimeout(() => {\n cleanup();\n resolve(\"\");\n }, SESSID_TIMEOUT_MS);\n const cleanup = (): void => {\n clearTimeout(timer);\n window.removeEventListener(\"message\", onMsg);\n };\n window.addEventListener(\"message\", onMsg);\n window.postMessage(buildSessidRequest(nonce), ORIGIN);\n });\n}\n\nasync function handleCall(req: CallRequest): Promise<InterpretResult> {\n const sessid = await freshSessid();\n if (!sessid) return { ok: false, error: \"session context not ready \u2014 open a normal Bitrix24 portal tab\" }; // G5\n const { url, body, contentType } = buildRequest(ORIGIN, req, sessid);\n const init: RequestInit = {\n method: req.method,\n credentials: \"include\",\n // sessid rides the CSRF header for all ajax (v2 form + json); form bodies also carry it inline.\n headers: { \"Content-Type\": contentType, \"X-Bitrix-Csrf-Token\": sessid },\n };\n let finalUrl = url;\n if (req.method === \"POST\") init.body = body;\n else finalUrl += (url.includes(\"?\") ? \"&\" : \"?\") + body;\n const resp = await fetch(finalUrl, init);\n const json = await resp.json();\n return interpret(json); // G3\n}\n\nfunction connect(config: BridgeConfig): void {\n const ws = new WebSocket(`ws://127.0.0.1:${config.port}`);\n ws.addEventListener(\"open\", () => {\n ws.send(JSON.stringify({ type: \"auth\", token: config.token })); // auth first (server closes non-auth)\n socket = ws;\n });\n ws.addEventListener(\"message\", async (ev: MessageEvent) => {\n let req: CallRequest;\n try {\n req = JSON.parse(ev.data) as CallRequest;\n } catch (e) {\n console.error(\"[bitrix-bridge] malformed WS frame, dropping:\", e);\n return;\n }\n if (req.type !== \"call\") return;\n try {\n const r = await handleCall(req);\n ws.send(JSON.stringify({ type: \"result\", id: req.id, ok: r.ok, data: r.data, error: r.error }));\n } catch (e) {\n ws.send(JSON.stringify({ type: \"result\", id: req.id, ok: false, error: String(e) }));\n }\n });\n ws.addEventListener(\"close\", () => {\n if (socket === ws) socket = null;\n setTimeout(() => connect(config), RECONNECT_MS); // auto-reconnect\n });\n}\n\n// Capture build only: relay MAIN-observed capture entries to the daemon.\nif (__BITRIX_CAPTURE__) {\n window.addEventListener(\"message\", (ev: MessageEvent) => {\n if (ev.source !== window) return;\n const fwd = parseCaptureForward(ev.data);\n if (!fwd) return;\n if (socket && socket.readyState === WebSocket.OPEN) {\n socket.send(JSON.stringify({ type: \"capture\", call: fwd.call }));\n }\n });\n}\n\nasync function start(): Promise<void> {\n let config: BridgeConfig;\n try {\n const resp = await fetch(chrome.runtime.getURL(\"config.json\"));\n if (!resp.ok) throw new Error(`HTTP ${resp.status}`);\n config = parseConfig(await resp.text());\n } catch (e) {\n // Nothing to fall back to \u2014 surface why the bridge won't start and stop.\n console.error(\"[bitrix-bridge] cannot load config.json:\", e);\n return;\n }\n connect(config);\n}\n\nstart();\n"],
|
|
5
|
+
"mappings": "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",
|
|
6
6
|
"names": []
|
|
7
7
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"type": "module",
|
|
3
3
|
"name": "bitrix24-mcp-bridge",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.2.1",
|
|
5
5
|
"description": "MCP bridge server for Bitrix24 — exposes REST API access, tasks, projects and chat to MCP clients like Claude Code.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"repository": {
|
|
@@ -12,7 +12,12 @@
|
|
|
12
12
|
"bitrix24-bridge": "dist/cli.js",
|
|
13
13
|
"bitrix24-mcp-bridge": "dist/cli.js"
|
|
14
14
|
},
|
|
15
|
-
"files": [
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"extension/dist",
|
|
18
|
+
"docs/api-notes.md",
|
|
19
|
+
"actions.example.json"
|
|
20
|
+
],
|
|
16
21
|
"scripts": {
|
|
17
22
|
"test": "bun test",
|
|
18
23
|
"dev": "bun run src/index.ts",
|