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

2026-05-24 08:04:44 +03:00
parent aa2644d812
commit 4b371e142d
53 changed files with 4317 additions and 18 deletions
@@ -0,0 +1,306 @@
+# API для разработчиков: DM, push и сигналы звонков
+
+Документ описывает WebSocket-операции для подписанных личных сообщений, WebPush и realtime-сигналов звонков.
+
+Логика личных сообщений дополнительно описана в `Dev_Docs/Personal_Messages/README.md`; этот файл фиксирует именно публичные `op`, поля запросов и поля ответов.
+
+## 1. `UpsertPushToken`
+
+Требует авторизации.
+
+### Запрос
+
+```json
+{
+  "op": "UpsertPushToken",
+  "requestId": "push-upsert-001",
+  "payload": {
+    "sessionId": "SESSION_ID",
+    "endpoint": "https://push.example/...",
+    "p256dhKey": "BASE64",
+    "authKey": "BASE64",
+    "platform": "web",
+    "userAgent": "Mozilla/5.0 ..."
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "UpsertPushToken",
+  "requestId": "push-upsert-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "tokenId": "token-1",
+    "updatedAtMs": 1774700000123
+  }
+}
+```
+
+---
+
+## 2. `SendTestWebPush`
+
+Требует авторизации. Если `login` передан, он должен совпадать с логином текущей сессии.
+
+### Запрос
+
+```json
+{
+  "op": "SendTestWebPush",
+  "requestId": "push-test-001",
+  "payload": {
+    "login": "alice",
+    "sessionId": "SESSION_ID",
+    "title": "Test",
+    "text": "Push body"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "SendTestWebPush",
+  "requestId": "push-test-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "targetLogin": "alice",
+    "attemptedSessions": 1,
+    "sessionsWithPushConfig": 1,
+    "delivered": 1,
+    "failed": 0,
+    "sentAtMs": 1774700000123
+  }
+}
+```
+
+---
+
+## 3. `SendDirectMessage`
+
+Отправляет один подписанный DM-пакет.
+
+### Запрос
+
+```json
+{
+  "op": "SendDirectMessage",
+  "requestId": "dm-001",
+  "payload": {
+    "blobB64": "BASE64_SIGNED_DM_PACKET"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "SendDirectMessage",
+  "requestId": "dm-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "messageId": "dm-1",
+    "deliveredWsSessions": 1,
+    "deliveredWebPushSessions": 0,
+    "sessionNotFound": false
+  }
+}
+```
+
+---
+
+## 4. `SendMessagePair` и `ReceiveOutcomingMessage`
+
+`ReceiveOutcomingMessage` сейчас является алиасом `SendMessagePair` и использует тот же request/handler.
+
+### Запрос
+
+```json
+{
+  "op": "SendMessagePair",
+  "requestId": "dm-pair-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK",
+    "outgoingBlobB64": "BASE64_OUTGOING_SIGNED_BLOCK"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "SendMessagePair",
+  "requestId": "dm-pair-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "baseKey": "base-key",
+    "incomingKey": "incoming-key",
+    "outgoingKey": "outgoing-key",
+    "deliveredWsSessions": 1,
+    "deliveredWebPushSessions": 0
+  }
+}
+```
+
+---
+
+## 5. `ReceiveIncomingMessage`
+
+Принимает входящий подписанный DM-блок.
+
+### Запрос
+
+```json
+{
+  "op": "ReceiveIncomingMessage",
+  "requestId": "dm-in-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "ReceiveIncomingMessage",
+  "requestId": "dm-in-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "messageKey": "incoming-key",
+    "baseKey": "base-key",
+    "deliveredWsSessions": 1,
+    "deliveredWebPushSessions": 0
+  }
+}
+```
+
+---
+
+## 6. `AckSessionDelivery`
+
+Требует авторизации. Подтверждает доставку сообщения в текущую сессию.
+
+### Запрос
+
+```json
+{
+  "op": "AckSessionDelivery",
+  "requestId": "ack-001",
+  "payload": {
+    "messageKey": "incoming-key"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "AckSessionDelivery",
+  "requestId": "ack-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "messageKey": "incoming-key"
+  }
+}
+```
+
+---
+
+## 7. `CallInviteBroadcast`
+
+Требует авторизации. Отправляет приглашение к звонку на активные сессии пользователя `toLogin`.
+
+### Запрос
+
+```json
+{
+  "op": "CallInviteBroadcast",
+  "requestId": "call-invite-001",
+  "payload": {
+    "toLogin": "bob",
+    "callId": "call-1",
+    "type": 100
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "CallInviteBroadcast",
+  "requestId": "call-invite-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "callId": "call-1",
+    "deliveredWsSessions": 1,
+    "deliveredFcmSessions": 0,
+    "deliveredWebPushSessions": 0
+  }
+}
+```
+
+---
+
+## 8. `CallSignalToSession`
+
+Требует авторизации. Отправляет сигнал звонка в конкретную сессию получателя.
+
+### Запрос
+
+```json
+{
+  "op": "CallSignalToSession",
+  "requestId": "call-signal-001",
+  "payload": {
+    "toLogin": "bob",
+    "targetSessionId": "SESSION_ID",
+    "callId": "call-1",
+    "type": 101,
+    "data": "{\"sdp\":\"...\"}"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "CallSignalToSession",
+  "requestId": "call-signal-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "delivered": true
+  }
+}
+```
+
+Если целевая сессия не найдена или доставка не удалась, сервер может вернуть `404`.
+
+## Типовые ошибки
+
+- `422 / NOT_AUTHENTICATED` — требуется авторизация.
+- `400 / BAD_FIELDS` — не заполнены обязательные поля.
+- `404 / USER_NOT_FOUND` — пользователь не найден.
+- `404 / SESSION_NOT_FOUND` — сессия не найдена.
+- `422 / BAD_SIGNATURE` — подпись DM не прошла проверку.
+- `422 / BAD_DEVICE_KEY` — некорректный device key отправителя.
+- `422 / BAD_TIME_WINDOW` — время подписанного сообщения вне допустимого окна.
+- `422 / REPLAY` — повторное сообщение заблокировано.