Документировать API и сервис агента-кодера

2026-05-24 08:04:44 +03:00
parent aa2644d812
commit 4b371e142d
53 changed files with 4317 additions and 18 deletions
@@ -1,11 +1,15 @@
 # API для разработчиков: Технические запросы

-Этот файл описывает технические запросы, которые не требуют авторизации и нужны для служебной работы клиента с сервером.
+Этот файл описывает технические WebSocket-запросы, которые нужны для служебной работы клиента с сервером. Часть операций доступна без авторизации, часть требует успешной авторизованной сессии.

-Сейчас здесь два метода:
+Сейчас здесь шесть методов:

 - `Ping` — keep-alive запрос для поддержания живого WebSocket-соединения;
- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети.
+- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети;
+- `GetCallIceConfig` — выдача STUN/TURN конфигурации для звонков;
+- `ClientErrorLog` — отправка клиентской ошибки в серверный лог;
+- `ClientDebugLog` — отправка клиентского debug-события в серверный буфер;
+- `CallDeliveryReport` — диагностический отчёт клиента о доставке/установке звонка.

 Логика раздела такая:

@@ -130,14 +134,186 @@

 ---

-## 3. Короткое резюме
+## 3. `GetCallIceConfig`
+
+Доступно только после успешной авторизации.
+
+### Запрос
+
+```json
+{
+  "op": "GetCallIceConfig",
+  "requestId": "ice-001",
+  "payload": {
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "GetCallIceConfig",
+  "requestId": "ice-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "stunUrls": ["stun:stun.example.org:3478"],
+    "turnUrls": ["turn:turn.example.org:3478?transport=udp"],
+    "turnUsername": "user",
+    "turnPassword": "password",
+    "turnServers": [
+      {
+        "id": "primary",
+        "urls": ["turn:turn.example.org:3478?transport=udp"],
+        "username": "user",
+        "password": "password"
+      }
+    ],
+    "turnEnabled": true,
+    "generatedAtMs": 1774700000123,
+    "expiresAtMs": 1774700300123,
+    "ttlSec": 300
+  }
+}
+```
+
+### Специфические коды ошибок `GetCallIceConfig`
+
+- `422 / NOT_AUTHENTICATED` — требуется авторизация.
+
+---
+
+## 4. `ClientErrorLog`
+
+### Запрос
+
+```json
+{
+  "op": "ClientErrorLog",
+  "requestId": "err-001",
+  "payload": {
+    "kind": "global_error",
+    "message": "TypeError: failed",
+    "stack": "...",
+    "sourceUrl": "https://shineup.me/app.js",
+    "lineNumber": 10,
+    "columnNumber": 20,
+    "route": "#/channel-view/own-0",
+    "href": "https://shineup.me/#/channel-view/own-0",
+    "userAgent": "...",
+    "clientTs": 1774700000123,
+    "requestOp": "GetChannelMessages",
+    "requestIdRef": "GetChannelMessages-123",
+    "contextJson": "{\"screen\":\"channels\"}"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "ClientErrorLog",
+  "requestId": "err-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "serverTs": 1774700000456,
+    "accepted": true
+  }
+}
+```
+
+### Специфические коды ошибок `ClientErrorLog`
+
+- `400 / BAD_FIELDS` — обязательные поля ошибки не заполнены.
+
+---
+
+## 5. `ClientDebugLog`
+
+### Запрос
+
+```json
+{
+  "op": "ClientDebugLog",
+  "requestId": "dbg-001",
+  "payload": {
+    "runId": "ui-run-1",
+    "level": "info",
+    "message": "opened channels tab",
+    "details": "{\"route\":\"#/channels\"}"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "ClientDebugLog",
+  "requestId": "dbg-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "accepted": true,
+    "serverTs": 1774700000456
+  }
+}
+```
+
+### Специфические коды ошибок `ClientDebugLog`
+
+- `400 / BAD_FIELDS` — поле `message` не заполнено.
+
+---
+
+## 6. `CallDeliveryReport`
+
+### Запрос
+
+```json
+{
+  "op": "CallDeliveryReport",
+  "requestId": "call-report-001",
+  "payload": {
+    "type": "outgoing_failed",
+    "value": "{\"reason\":\"ice_failed\",\"callId\":\"call-1\"}"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "CallDeliveryReport",
+  "requestId": "call-report-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "serverTs": 1774700000456,
+    "accepted": true
+  }
+}
+```
+
+### Специфические коды ошибок `CallDeliveryReport`
+
+- `400 / BAD_FIELDS` — поле `type` не заполнено.
+
+---
+
+## 7. Короткое резюме

 - `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
 - `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
- Оба запроса доступны без авторизации.
+- `GetCallIceConfig` нужен для WebRTC-звонков и требует авторизации.
+- `ClientErrorLog`, `ClientDebugLog`, `CallDeliveryReport` используются для диагностики клиента и звонков.


-## 4. Прямое техническое сообщение в конкретную сессию
+## 8. Прямое техническое сообщение в конкретную сессию

 На текущий момент в публичном JSON API этого документа **нет отдельного RPC** для отправки произвольного технического сообщения в конкретную сессию пользователя (по `sessionId`).