API Reference

MESSAGE
SCHEMA.

Формат payload повідомлень, типи подій Socket.IO та структура даних для клієнта і бекенду LUMYN.

// 01

Base Message Payload

Базова структура зашифрованого повідомлення. Всі поля, крім ciphertext, передаються у відкритому вигляді для маршрутизації. Ciphertext — зашифрований AES-256-GCM контент.

JSON · Message Envelope
{
  "type":         "text",           // тип повідомлення
  "senderName":   "alice",          // ідентифікатор відправника
  "receiverName": "bob",            // або "GROUP_uuid" для груп
  "ciphertext":   "base64...",      // AES-256-GCM зашифрований контент
  "nonce":        "base64...",      // 96-bit унікальний nonce
  "mac":          "base64...",      // 128-bit GCM authentication tag
  "timestamp":    "2026-03-30T...", // ISO-8601
  "messageId":    "uuid-v4",        // UUID v4 для дедуплікації
  "isEphemeral":  false             // true = ефірне повідомлення
}

// 02

Типи повідомлень

Поле type визначає як клієнт декодує та відображає вміст ciphertext після розшифрування.

text

Звичайне текстове повідомлення. Ciphertext містить UTF-8 рядок.

image

Зображення. Ciphertext — зашифрований base64 JPEG/PNG файл.

voice

Голосове повідомлення. Ciphertext — зашифрований аудіофайл.

ephemeral_text

Ефірний текст. Видаляється після прочитання на всіх пристроях.

ephemeral_image

Ефірне зображення. Автоматично знищується після перегляду.

reaction

Emoji реакція на повідомлення. Містить messageId та emoji символ.

system

Системне повідомлення: учасник приєднався, ключі синхронізовано.

deleted

Маркер видаленого повідомлення. Замінює вміст на стороні клієнта.

// 03

Socket.IO Events

Транспортний рівень LUMYN базується на Socket.IO. Нижче наведені ключові події клієнт↔сервер.

Подія	Напрям	Опис
register	emit →	Реєстрація клієнта: передає username та публічний ключ X25519.
sendMessage	emit →	Надсилання зашифрованого повідомлення одному отримувачу.
sendGroupMessage	emit →	Надсилання повідомлення до групи по groupId.
sendEphemeral	emit →	Ефірне повідомлення для прямого чату. Видаляється після доставки.
sendEphemeralGroup	emit →	Ефірне повідомлення для групи.
sendVoice	emit →	Передача зашифрованого голосового повідомлення.
sendImage	emit →	Передача зашифрованого зображення.
receiveMessage	← on	Клієнт отримує нове зашифроване повідомлення від сервера.
getPublicKey	emit →	Запит публічного ключа іншого користувача для ECDH обміну.
typing	emit →	Індикатор набору тексту. Передає sender, receiver, isTyping.
deleteMessage	emit →	Видалення повідомлення по messageId. Сервер розсилає всім учасникам.
createGroup	emit →	Створення групи з назвою та списком учасників.
fcmToken	emit →	Реєстрація FCM токена для push-повідомлень через Firebase.

// 04

Group Schema

JSON · Group Object
{
  "groupId":      "GROUP_uuid-v4",  // унікальний префікс GROUP_
  "groupName":    "Team Alpha",
  "members":      ["alice", "bob", "carol"],
  "createdBy":    "alice",
  "createdAt":    "2026-03-30T12:00:00Z",
  "avatarBase64": "base64..."          // nullable
}

MESSAGESCHEMA.

MESSAGE
SCHEMA.