Files
SHiNE-server/docs/API/06_Channels_Read_API.md
T

28 KiB
Raw Blame History

06. Channels Read API

Человеко-читаемое объяснение

Эти функции — это чтение данных каналов для UI:

  1. ListSubscriptionsFeed — отдает данные для экрана списка каналов:

    • ваши каналы (личный + созданные вами),
    • каналы пользователей, на кого вы подписаны,
    • отдельные каналы, на которые вы подписаны напрямую.
  2. GetChannelMessages — отдает полную ленту одного канала (пока без курсоров, загружается сразу целиком), включая версии сообщений, лайки и ответы.

  3. GetMessageThread — отдает дерево обсуждения вокруг конкретного сообщения: предки, фокус-сообщение, потомки.

  4. GetMessageLikes — отдает списки пользователей, поставивших лайк сообщению, сгруппированные для UI по статусу профиля.

  5. GetPersonalDiary — отдает виртуальную ленту Личный дневник, собранную из STATUS_ACTION текущего пользователя.

  6. GetChannelsCounters — отдает счетчики разделов каналов для пользователя.

  7. SetChannelReadState — сохраняет подписанный watermark чтения канала и возвращает новый unread-счетчик.

  8. ListGroupChats200 — отдает список групповых чатов типа 200.

  9. GetGroupDialog — отдает сообщения конкретного группового чата типа 200.

На первом этапе мы не используем курсоры (nextCursor) и загружаем полные списки.

unreadCount для канала считается по подписанному состоянию чтения канала. Для собственных каналов владельцу всегда возвращается unreadCount = 0, чтобы его собственные публикации не становились «новыми» для него самого. Если для пары ownerBlockchainName/channelName ещё нет записи, канал временно считается полностью прочитанным. После появления записи новые публикации увеличивают unreadCount до продвижения курсора чтения.

Для FREE_CERT и платных пользователей ListSubscriptionsFeed использует единый реестр user_identity_current. Собственные каналы и личный корневой канал определяются по blockchain_name из этого реестра, без обязательного PDA в Solana. Подписки (connections_state) сопоставляются с логином без учёта регистра (в таблице связи нормализованы к нижнему регистру). Это обеспечивает одинаковую загрузку вкладок «Мои» и «Подписки» для бесплатных и платных аккаунтов. Сведения о публикациях в этих каналах также читаются с учётом активной цепочки из общего реестра.

ListSubscriptionsFeed технически может возвращать soft-deleted каналы с channel.deleted=true, чтобы старые ссылки и selector канала продолжали разрешаться. Обычный UI скрывает такие строки. Для deleted-канала общий unread/counters не учитываются; сама подписка сохраняется.


1) ListSubscriptionsFeed

Request

{
  "op": "ListSubscriptionsFeed",
  "requestId": "req-1",
  "payload": {
    "login": "Alice",
    "limit": 200
  }
}

Response (success)

{
  "op": "ListSubscriptionsFeed",
  "requestId": "req-1",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "Alice",
    "ownedChannels": [
      {
        "channel": {
          "ownerLogin": "Alice",
          "ownerBlockchainName": "alice-001",
          "channelName": "0",
          "displayName": "Мой канал",
          "channelDescription": "Короткое описание",
          "avaAr": "ArweaveTxId...",
          "avaSha256": "0123...",
          "avaSize": 248193,
          "metaUpdatedAtMs": 1760000000000,
          "deleted": false,
          "deletedAtMs": 0,
          "deletedBlockNumber": null,
          "personal": true,
          "channelRoot": { "blockNumber": 0, "blockHash": "..." }
        },
        "messagesCount": 120,
        "lastMessage": {
          "messageRef": { "blockNumber": 921, "blockHash": "..." },
          "text": "последняя версия текста",
          "createdAtMs": 1760000000000,
          "authorLogin": "Alice",
          "authorBlockchainName": "alice-001"
        }
      }
    ],
    "followedUsersChannels": [
      {
        "channel": {
          "ownerLogin": "Bob",
          "ownerBlockchainName": "bob-001",
          "channelName": "0",
          "personal": true,
          "channelRoot": { "blockNumber": 0, "blockHash": "..." }
        },
        "messagesCount": 540,
        "lastMessage": {
          "messageRef": { "blockNumber": 922, "blockHash": "..." },
          "text": "последняя версия текста",
          "createdAtMs": 1760000100000,
          "authorLogin": "Bob",
          "authorBlockchainName": "bob-001"
        }
      }
    ],
    "followedChannels": [
      {
        "channel": {
          "ownerLogin": "Carl",
          "ownerBlockchainName": "carl-001",
          "channelName": "market",
          "personal": false,
          "channelRoot": { "blockNumber": 456, "blockHash": "..." }
        },
        "messagesCount": 90,
        "readCount": 0,
        "unreadCount": 0,
        "readStateInitialized": false,
        "lastMessage": {
          "messageRef": { "blockNumber": 1002, "blockHash": "..." },
          "text": "актуальный текст",
          "createdAtMs": 1760001000000,
          "authorLogin": "Carl",
          "authorBlockchainName": "carl-001"
        }
      }
    ]
  }
}

2) GetChannelMessages

Request

{
  "op": "GetChannelMessages",
  "requestId": "req-2",
  "payload": {
    "channel": {
      "ownerBlockchainName": "bob-001",
      "channelRootBlockNumber": 123,
      "channelRootBlockHash": "..."
    },
    "limit": 200,
    "sort": "asc"
  }
}

limit необязателен. Если поле отсутствует или равно 0, сервер возвращает всю ленту канала. Положительное значение ограничивает количество сообщений для совместимых клиентов.

Response (success)

{
  "op": "GetChannelMessages",
  "requestId": "req-2",
  "status": 200,
  "ok": true,
  "payload": {
    "channel": {
      "ownerLogin": "Bob",
      "ownerBlockchainName": "bob-001",
      "channelName": "news",
      "displayName": "Новости Bob",
      "channelDescription": "Канал о новостях",
      "avaAr": "ArweaveTxId...",
      "avaSha256": "0123...",
      "avaSize": 248193,
      "metaUpdatedAtMs": 1760000000000,
      "deleted": false,
      "deletedAtMs": 0,
      "deletedBlockNumber": null,
      "subscribersCount": 128,
      "channelRoot": { "blockNumber": 123, "blockHash": "..." }
    },
    "metaEvents": [
      {
        "kind": "created",
        "messageRef": { "blockNumber": 123, "blockHash": "..." },
        "authorLogin": "Bob",
        "authorBlockchainName": "bob-001",
        "lineStep": 1,
        "createdAtMs": 1760000000000,
        "title": "news",
        "description": "",
        "avaAr": "",
        "avaSha256": "",
        "avaSize": 0
      },
      {
        "kind": "profile_updated",
        "messageRef": { "blockNumber": 130, "blockHash": "..." },
        "authorLogin": "Bob",
        "authorBlockchainName": "bob-001",
        "lineStep": 2,
        "createdAtMs": 1760000500000,
        "title": "Новости Bob",
        "description": "Канал о новостях",
        "avaAr": "ArweaveTxId...",
        "avaSha256": "0123...",
        "avaSize": 248193
      }
    ],
    "messages": [
      {
        "messageRef": { "blockNumber": 140, "blockHash": "..." },
        "authorLogin": "Bob",
        "authorBlockchainName": "bob-001",
        "createdAtMs": 1760000000000,
        "text": "текущая версия",
        "likesCount": 12,
        "repliesCount": 3,
        "ratingsCount": 2,
        "versionsTotal": 4,
        "versions": [
          { "versionIndex": 1, "blockNumber": 140, "blockHash": "...", "text": "v1", "createdAtMs": 1760000000000 },
          { "versionIndex": 2, "blockNumber": 155, "blockHash": "...", "text": "v2", "createdAtMs": 1760001000000 },
          { "versionIndex": 3, "blockNumber": 170, "blockHash": "...", "text": "v3", "createdAtMs": 1760002000000 },
          { "versionIndex": 4, "blockNumber": 199, "blockHash": "...", "text": "v4", "createdAtMs": 1760003000000 }
        ]
      }
    ]
  }
}

Для soft-deleted канала channel.deleted=true; deletedAtMs и deletedBlockNumber указывают последний delete-блок. В metaEvents delete-блоки возвращаются как kind: "deleted". После новой самостоятельной публикации канал снова активен (deleted=false), при этом исторические deleted meta-events остаются частью истории.


3) GetMessageThread

Request

{
  "op": "GetMessageThread",
  "requestId": "req-3",
  "payload": {
    "message": {
      "blockchainName": "bob-001",
      "blockNumber": 333,
      "blockHash": "..."
    },
    "depthUp": 20,
    "depthDown": 2,
    "limitChildrenPerNode": 50
  }
}

Response (success)

{
  "op": "GetMessageThread",
  "requestId": "req-3",
  "status": 200,
  "ok": true,
  "payload": {
    "ancestors": [MessageNode],
    "focus": MessageNode,
    "descendants": [MessageNodeTree]
  }
}

MessageNode (дополнение)

  • MessageNode расширяет формат сообщения из GetChannelMessages и дополнительно содержит:
    • channelInfo — мета-информация о канале (если применимо);
    • rawBlockB64 — сырой block_bytes текущего блока в Base64.
  • Поле rawBlockB64 присутствует у узлов во всех частях ответа GetMessageThread: focus, ancestors[], descendants[].
  • В GetChannelMessages поле rawBlockB64 не добавляется (лента канала без сырого блока, чтобы не раздувать ответ).
  • И в GetChannelMessages, и в GetMessageThread каждое сообщение теперь содержит:
    • repliesCount — число дочерних сообщений типа TEXT_REPLY;
    • ratingsCount — число дочерних сообщений типа TEXT_RATING.
  • В descendants[] операции GetMessageThread возвращаются оба типа дочерних текстовых сообщений:
    • TEXT_REPLY;
    • TEXT_RATING. Они идут в одной общей ветке обсуждения и сортируются по времени создания.

4) GetMessageLikes

Возвращает пользователей, которые поставили лайк конкретному сообщению канала.

  • message.blockchainName, message.blockNumber, message.blockHash должны указывать на исходное сообщение.
  • limit в текущей реализации не требуется: сервер возвращает полный найденный список лайков.
  • Пользователи группируются по состоянию профиля:
    • shining — account_role=primary и shine_status=shining;
    • official — account_role=primary, но без shine_status=shining;
    • others — остальные пользователи.

Request

{
  "op": "GetMessageLikes",
  "requestId": "req-4",
  "payload": {
    "message": {
      "blockchainName": "bob-001",
      "blockNumber": 140,
      "blockHash": "..."
    }
  }
}

Response (success)

{
  "op": "GetMessageLikes",
  "requestId": "req-4",
  "status": 200,
  "ok": true,
  "payload": {
    "shining": [
      { "login": "Alice", "firstName": "Alice", "lastName": "", "avatarAr": "ArweaveTxId..." }
    ],
    "official": [],
    "others": [
      { "login": "Carl", "firstName": "", "lastName": "", "avatarAr": "" }
    ],
    "total": 2,
    "truncated": false
  }
}

Ошибки

  • bad_fields — не передан message или обязательные поля ссылки на сообщение.
  • bad_hash — message.blockHash не является корректным hex-хэшем блока.
  • internal_error — внутренняя ошибка чтения.

truncated сейчас всегда false; поле оставлено в ответе для совместимости с UI и возможной будущей пагинацией.


5) GetPersonalDiary

Возвращает виртуальный канал Личный дневник для самого пользователя.

  • Вызов доступен только владельцу дневника.
  • Сообщения в ответе строятся из блоков STATUS_ACTION.
  • Поля targetMsgSubType, targetText, targetAuthorLogin, targetAuthorBlockchainName, targetCreatedAtMs описывают исходный материал, к которому относится действие.

Request

{
  "op": "GetPersonalDiary",
  "requestId": "req-4",
  "payload": {
    "login": "Alice",
    "limit": 200,
    "sort": "asc"
  }
}

6) GetChannelsCounters

Request

{
  "op": "GetChannelsCounters",
  "requestId": "req-4",
  "payload": {
    "login": "Alice"
  }
}

Response (success)

{
  "op": "GetChannelsCounters",
  "requestId": "req-4",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "Alice",
    "feedCount": 12,
    "dialogs100Count": 3,
    "groupChats200Count": 4,
    "myChannelsCount": 2
  }
}

7) SetChannelReadState

Сохраняет подписанную позицию чтения для одного канала, на который пользователь подписан.

  • Требует авторизованное WebSocket-соединение.
  • login должен совпадать с текущим авторизованным пользователем.
  • Подпись строится client key пользователя по строке:
SHiNe/ChannelReadState:<login>|<owner_bch_name>|<channel_name>|<time_ms>|<read_count>

Request

{
  "op": "SetChannelReadState",
  "requestId": "req-7",
  "payload": {
    "login": "Alice",
    "owner_bch_name": "bob-001",
    "channel_name": "news",
    "read_count": 90,
    "time_ms": 1760000000000,
    "client_key": "<base64-client-public-key>",
    "signature": "<base64-ed25519-signature>"
  }
}

Response (success)

{
  "op": "SetChannelReadState",
  "requestId": "req-7",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "Alice",
    "owner_bch_name": "bob-001",
    "channel_name": "news",
    "read_count": 90,
    "unread_count": 0,
    "time_ms": 1760000000000,
    "applied": true
  }
}

Ошибки

  • NOT_AUTHENTICATED — нет авторизованной сессии.
  • BAD_FIELDS — не переданы обязательные поля.
  • LOGIN_MISMATCH — login не совпадает с текущей сессией.
  • BAD_TIME — время подписи слишком далеко в будущем.
  • BAD_BASE64 — client_key или signature не являются корректным Base64.
  • DEVICE_KEY_MISMATCH — client_key не совпадает с текущим client key пользователя.
  • INVALID_SIGNATURE — подпись watermark не прошла проверку.
  • CHANNEL_NOT_FOLLOWED — пользователь не подписан на канал.
  • CHANNEL_NOT_FOUND — канал не найден.
  • INTERNAL_ERROR — внутренняя ошибка записи.

8) ListGroupChats200

Request

{
  "op": "ListGroupChats200",
  "requestId": "req-5",
  "payload": {
    "login": "Alice"
  }
}

Response (success)

{
  "op": "ListGroupChats200",
  "requestId": "req-5",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "Alice",
    "chats": [
      {
        "ownerLogin": "Alice",
        "ownerBlockchainName": "alice-001",
        "channelRootBlockNumber": 123,
        "channelRootBlockHash": "...",
        "channelName": "team",
        "chatTitle": "Team chat",
        "membersCount": 3,
        "updatedAtMs": 1760000000000
      }
    ]
  }
}

9) GetGroupDialog

Request

{
  "op": "GetGroupDialog",
  "requestId": "req-6",
  "payload": {
    "login": "Alice",
    "group": {
      "ownerBlockchainName": "alice-001",
      "channelRootBlockNumber": 123
    }
  }
}

Response (success)

{
  "op": "GetGroupDialog",
  "requestId": "req-6",
  "status": 200,
  "ok": true,
  "payload": {
    "group": {
      "ownerLogin": "Alice",
      "ownerBlockchainName": "alice-001",
      "channelRootBlockNumber": 123,
      "channelName": "team",
      "chatTitle": "Team chat"
    },
    "messages": [
      {
        "authorLogin": "Bob",
        "authorBlockchainName": "bob-001",
        "blockNumber": 140,
        "blockHash": "...",
        "createdAtMs": 1760000000000,
        "text": "Привет"
      }
    ]
  }
}

Reason codes

  • bad_fields
  • user_not_found
  • channel_not_found
  • message_not_found
  • bad_limit
  • channel_name_already_exists
  • CHANNEL_NOT_FOLLOWED
  • CHANNEL_NOT_FOUND
  • internal_error

Profile public-channel lists (v18)

ListUserProfileChannels

Returns lightweight public-channel cards for profile counters. mode is owned or following; only channel_type_code=1 is returned.

{
  "op": "ListUserProfileChannels",
  "requestId": "profile-ch-1",
  "payload": { "login": "Alice", "mode": "owned", "includeDeleted": false, "limit": 100, "offset": 0 }
}

includeDeleted необязателен и по умолчанию равен false. При true ответ включает как активные, так и soft-deleted каналы.

Channel items contain ownerLogin, slug, displayName, avatarAr, ownerBlockchainName, rootBlockNumber, rootBlockHashHex, deleted, deletedAtMs, and deletedBlockNumber.

Qualified likes (v18)

Channel/message responses expose three counters:

  • likesCount — all active likes;
  • primaryLikesCount — likes from users whose current account_role=primary;
  • shiningLikesCount — likes from users who are currently both primary and shining.

Changing account_role or shine does not alter the raw reaction. The two qualified counters are recalculated from reactions_state; therefore old likes automatically enter or leave qualified counters when the actor's current status changes.

SearchChannels — публичный поиск каналов (v32)

Операция без авторизации, на текущем сервере (не федеративный поиск). Результаты берутся из актуального состояния channel_names_state; публичные каналы — channel_type_code = 1, не удалённые (is_deleted = false).

Запрос:

{
  "op": "SearchChannels",
  "requestId": "search-ch-1",
  "payload": { "query": "гриб", "limit": 10 }
}
  • query — текст от 1 до 120 символов. Не обязателен, если указан ownerLogin.
  • ownerLogin — дополнительное ограничение по началу логина владельца, до 80 символов.
  • limit — число результатов, по умолчанию 10, допустимо 1–50. Курсора и пагинации нет.
  • @anna — каналы владельцев, чьи логины содержат anna.
  • anna/art — каналы владельца anna, у которых публичное либо техническое название содержит art.
  • anna/ — все доступные каналы владельца anna.
  • В обычном запросе ищутся подстроки в публичном имени display_name, техническом slug и логине owner_login. Регистр не важен, ё приравнивается к е. Вводимые %, _ и ! не работают как SQL-маски.
  • Сначала идут точные совпадения с названием или slug, затем префиксные, затем частичные, далее учитывается количество подписчиков.

Ответ:

{
  "op": "SearchChannels",
  "requestId": "search-ch-1",
  "status": 200,
  "ok": true,
  "payload": {
    "channels": [{
      "ownerLogin": "anna",
      "slug": "fungal-art",
      "displayName": "Грибной мир",
      "description": "Картины и грибы",
      "avatarAr": "",
      "avatarSha256": "",
      "ownerBlockchainName": "anna-001",
      "rootBlockNumber": 12,
      "rootBlockHashHex": "<hex>",
      "subscribersCount": 128
    }]
  }
}

Массив channels пустой при отсутствии совпадений; URL не возвращается. ownerBlockchainName и корневой блок позволяют клиенту открыть канонический канал через существующую маршрутизацию. Неверные поля: HTTP-подобный статус 400, код BAD_FIELDS; ошибки чтения БД: SERVER_DATA_ERROR, DB_ERROR. Структура блокчейна не меняется. Индексы поиска добавлены миграцией БД v32 (pg_trgm).

2026-10-28 — Официальный регистр логинов при чтении

В ответах GetChannelMessages, GetMessageThread, ListSubscriptionsFeed поля authorLogin и ownerLogin показывают регистрационное написание из user_identity_current, например AlexSmith@shine. В БД блока и в blockchainName по-прежнему возможен lowercase, используемый как нормализованный идентификатор. Это не меняет имена JSON-полей или типы значений, а уточняет их семантику. Для поиска и переходов разные варианты регистра по-прежнему ссылаются на одну идентичность; байты уже подписанных блоков не переписываются.

GetSupportTotals — проверенная поддержка канала

Запрос: {"op":"GetSupportTotals", "channelRootBlockNumber":12, "channelRootBlockHash":"<64 hex>"}.

Ответ (при status=200): channelReceivedLamports — десятичная строка суммы реально полученных авторами средств (90% донатов); messages — массив {blockNumber,blockHash,receivedLamports}. Все значения в lamports представлены строками, не JavaScript Number. В результате возвращаются не более 2000 сообщений с максимальными суммами, агрегат канала включает все проверенные операции.

API считает только support_user из таблицы solana_support_transfers. Для CHANNEL проверяет, что адресат равен владельцу существующего канала. Для MESSAGE проверяет наличие блока с точным номером/хешем, авторство получателя и принадлежность блока цепочке владельца канала. Не соответствующие этим условиям донаты остаются в истории, но не включаются в публичные суммы. Поддержка ответов в других пользовательских цепочках не попадает в агрегат до добавления полной проверки принадлежности обсуждению.

Таблицы истории автоматически создаются финансовым индексатором. Пока он не синхронизирован, операция может возвращать support_totals_unavailable — клиент не должен подменять отсутствие данных нулями.

GetSupportStats — публичные счётчики поддержки Paid-пользователя

Счётчики загружаются из PostgreSQL, а не через отдельный RPC Solana при каждом открытии профиля. Серверный SupportHistoryIndexer собирает кеш из успешных финализированных транзакций shine_users (opcodes 9 и 10). Исходная проверяемая финансовая статистика хранится в Solana PDA; кеш может отставать до следующего sync.

Запрос:

{"op":"GetSupportStats","requestId":"support-1","payload":{"login":"Alice@namespace"}}

Ответ:

{
  "op":"GetSupportStats", "requestId":"support-1", "status":200, "ok":true,
  "payload":{
    "login":"Alice@namespace", "available":true, "ready":true,
    "supportSentLamports":"1000000000",
    "supportReceivedLamports":"900000000",
    "daoDirectLamports":"100000000"
  }
}
  • available=false — локальный Solana sync не содержит Paid PDA (например, Free-аккаунт). Поля сумм в этом случае не показывать.
  • ready=false — сервер ещё не закончил первичную индексацию всей доступной истории; суммы нельзя показывать как окончательные (даже если возвращены нули).
  • available=true, ready=true, а строки сумм равны "0" — корректная нулевая статистика зарегистрированного Paid-пользователя без донатов.
  • Все значения lamports передаются строками (без преобразования в JS Number). Показатель «Поддержал SHiNE» вычисляется как supportSentLamports / 10 + daoDirectLamports. Регистрация и изменение PDA сюда не входят.

При отсутствии таблиц/соединения БД сервер возвращает ошибку, а не фиктивные нули. API не запускает RPC-вызовы; для свежих значений сразу после оплаты необходимо дождаться следующего прохода SupportHistoryIndexer.