Display new notification count

2026-09-02 19:20:04 +04:00
parent 0c5089fa79
commit aff601f61a
22 changed files with 475 additions and 260 deletions
@@ -60,7 +60,8 @@
 | `ListContacts` | `11_Connections_API.md` | контакты текущего пользователя |
 | `GetUserConnectionsGraph` | `11_Connections_API.md` | граф связей пользователя |
 | `AddCloseFriend` | `11_Connections_API.md` | добавить близкого друга |
-| `GetNotifications` | `15_Notifications_API.md` | ответы и события уведомлений |
+| `GetNotifications` | `15_Notifications_API.md` | ответы, связи, события и unread-watermark |
+| `SetNotificationState` | `15_Notifications_API.md` | подписанное состояние просмотра уведомлений |
 | `UpsertPushToken` | `12_Direct_Messages_Push_Calls_API.md` | регистрация WebPush-токена |
 | `SendTestWebPush` | `12_Direct_Messages_Push_Calls_API.md` | тестовая push-доставка |
 | `SendMessagePair` | `12_Direct_Messages_Push_Calls_API.md` | отправка пары входящий/исходящий DM |
@@ -1,81 +1,42 @@
 # API для разработчиков: уведомления

-Документ описывает чтение пользовательских уведомлений, которые сервер индексирует при `AddBlock`.
+Уведомления являются серверной проекцией событий блокчейна. Сервер возвращает все непросмотренные записи независимо от возраста и просмотренные записи не старше 60 дней. Пагинации нет: выдача содержит все непросмотренные и всю доступную 60-дневную просмотренную историю.

-Текущая операция:
+## GetNotifications

- `GetNotifications`
+Авторизация обязательна. Обычно payload пустой. Legacy-поле `limit` принимается для совместимости, но в v2 игнорируется. Для обновления badge без загрузки карточек можно передать `{"countsOnly":true}`; тогда массивы лент остаются пустыми, но watermark и `*UnseenCount` возвращаются.

-## 1. `GetNotifications`
+Ответ содержит три ленты: `replies`, `connections`, `events`, а также `*SeenAtMs` и `*UnseenCount` для каждой категории.

-Метод читает уведомления текущего пользователя. В `payload.login` можно передать логин явно, но обычно клиент использует авторизованную сессию.
+- `replies`: TEXT_REPLY.
+- `connections`: friend/unfriend, close_friend/unclose_friend, shine confirmed/unconfirmed, official confirmed/unconfirmed. Контакты не создают уведомлений.
+- `events`: FOLLOW/UNFOLLOW каналов.

-Возвращаются две отдельные ленты:
+Фильтр каждой категории: `created_at_ms > seenAtMs OR created_at_ms >= now - 60 days`.

- `replies` — ответы на сообщения пользователя в каналах и тредах;
- `events` — события добавления в `close_friend`.
+## SetNotificationState

-### Запрос
+Сохраняет подписанный watermark просмотра. Сервер принимает только монотонное движение `seenAtMs` вперёд.

+Запрос:
 ```json
-{
-  "op": "GetNotifications",
-  "requestId": "notif-001",
-  "payload": {
-    "login": "alice",
-    "limit": 50
-  }
-}
+{"op":"SetNotificationState","requestId":"ntf-seen-1","payload":{"blobB64":"..."}}
 ```

-### Успешный ответ
+Бинарный контейнер `SHiNE_NTF` v1.0 (big-endian):

-```json
-{
-  "op": "GetNotifications",
-  "requestId": "notif-001",
-  "status": 200,
-  "ok": true,
-  "payload": {
-    "login": "Alice",
-    "replies": [
-      {
-        "kind": "reply",
-        "createdAtMs": 1755673200000,
-        "sourceLogin": "Bob",
-        "sourceBlockchainName": "bob-001",
-        "sourceBlockNumber": 42,
-        "sourceBlockHash": "ab12...",
-        "sourceMsgSubType": 20,
-        "sourceText": "Спасибо!",
-        "targetLogin": "Alice",
-        "targetBlockchainName": "alice-001",
-        "targetBlockNumber": 18,
-        "targetBlockHash": "cd34..."
-      }
-    ],
-    "events": [
-      {
-        "kind": "close_friend",
-        "createdAtMs": 1755673300000,
-        "sourceLogin": "Kate",
-        "sourceBlockchainName": "kate-001",
-        "sourceBlockNumber": 7,
-        "sourceBlockHash": "ef56...",
-        "sourceMsgSubType": 10,
-        "sourceText": "close_friend",
-        "targetLogin": "Alice",
-        "targetBlockchainName": "alice-001",
-        "targetBlockNumber": 0,
-        "targetBlockHash": "0000..."
-      }
-    ]
-  }
-}
+```text
+'SHiNE_NTF'                  9 bytes ASCII
+formatVersionMajor           u8 = 1
+formatVersionMinor           u8 = 0
+loginLen                     u8
+login                        ASCII[loginLen]
+timeMs                       u64
+nonce                        u32
+stateType                    u8 = 1 (SEEN_WATERMARK)
+category                     u8 (1 replies, 2 connections, 3 events)
+seenAtMs                     u64
+signature                    Ed25519[64]
 ```

-### Примечание
-
- `replies` заполняется только для `TEXT_REPLY`.
- `events` заполняется только для входящего `CONNECTION_FRIEND` / `close_friend`.
- Другие типы связей в эту ленту не попадают.
+Подпись `clientKey` вычисляется над всеми байтами контейнера до `signature`, по тому же принципу, что подписанный контейнер `SHiNE_DM`. Сервер проверяет, что `login` совпадает с авторизованным пользователем, проверяет Ed25519-подпись и сохраняет также исходный signed blob для будущей переносимой синхронизации состояния.