stack-api

Stack API

src/main/integrations/stack-api/ — цільові контракти Electron з нашим backend.

Для кожної операції фіксуємо поточний endpoint і рішення щодо його власника:

• shared — один endpoint для всіх проєктів;
• family — окремий endpoint проєкту;
• перенести в shared — поточний endpoint лежить у family-сервісі, але не містить проєктної логіки.

Огляд

#	Операція	Зараз	Ціль	Реально
1	Логін оператора	shared	shared	✓
2	Перевірка версії	Golden	shared	✓
3	Час сервера	Golden	shared	✓
4	Сесія оператора	Golden	shared	△
5	Стартові дані	Golden, окремі endpoint	shared	△
6	Синхронізація даних	Golden	shared	✓
7	Отримання статистики	Golden	shared	△
8	Client E-mail	Stack	shared	✓

△ — потрібне об’єднання даних family-сервісів.

Загальний HTTP-контракт

Production: https://api.besocial.tech

Кожен запит Electron передає:

X-App-Version: <version>
X-App-Info: <OS info>

Після логіну додається Authorization: Bearer <JWT>. Стандартний timeout — 7 с.

type StackResponse<T> = {
  success: boolean
  details?: string
  message?: string
  data?: T
}

1. Логін оператора

Використовує: логін оператора.

POST https://api.besocial.tech/login

Request

{
  email: string
  password: string
}

Response

{
  success: true
  data: {
    token: string
    tokenRefresh: string
    user: {
      id: string
      name: string
      surname: string
      deepL: {
        apiKey: string
        isCheckedApiKey: boolean
        language: string
      }
      golden: {
        id: string
        supervisor: string
      }
    }
  }
}

Рішення

• Endpoint: лишається shared.
• DTO: замінити user.golden на спільний список family-прив’язок оператора.
• Реально: так; автентифікація вже спільна, змінюється відповідь і її мапінг в Electron.

Запити: 1 на логін оператора.

2. Перевірка версії Electron

Використовує: логін оператора.

POST https://api.besocial.tech/golden/electron-api/updates/check

Request

{
  currentVersion: string
}

Response

{
  success: true
  data: {
    hasUpdate: boolean
    version: string
    releaseNotes: string
    releaseDate: string
  }
}

Рішення

• Endpoint: перенести в shared.
• Реально: так; запит не залежить від family або TU.

Запити: 1 на логін оператора, далі 1 / 15 хв.

3. Отримання часу сервера

Використовує: логін оператора.

GET https://api.besocial.tech/golden/electron-api/getTime

Request

Без body.

Response

{
  success: true
  data: number // timestamp ms
}

Рішення

• Endpoint: перенести в shared.
• Реально: так; запит не залежить від family або TU.

Запити: 1 на запуск програми.

4. Сесія оператора

Використовує: логін оператора.

Socket.IO https://besocial.tech/electron

Path: /sock/socket.io

Handshake

{
  token: string
  version: string
  sleepMode: boolean
}

connectionResult

{
  messageId: string
  event: 'connectionResult'
  data: {
    success: boolean
    details?: string
    ladiesStatus: Array<{
      id: string
      id_api: number
      password: string
      name: string
      last_name: string
      age: number
      photo: string
      status: 'AVAILABLE' | 'OCCUPIED' | 'WILL_BE_AVAILABLE'
    }>
  }
}

Рішення

• Socket: перенести в shared.
• DTO: повертати один нормалізований список TU з ознакою проєкту.
• Реально: так, але shared-сервіс має отримувати TU та їхні статуси з відповідних family-сервісів.

Підключення: 1 постійний socket на оператора; після розриву — reconnect.

5. Стартові дані

Використовує: отримання даних зі Stack.

GET shared endpoint — URL треба визначити під час винесення з family-сервісів.

Request

Без body. Оператор і його family-прив’язки визначаються за JWT.

Response

{
  project: Project
  globalFavorites: GlobalFavoriteWithRuProfile[]
  favorites: Favorite[]
  taskHistory: TaskHistory[]
  invites: Invite[]
  senderHistory: SenderHistory[]
  blockedByRuIds: RuId[]
  senderBlacklists: SenderBlacklist[]
  projectData: ProjectStartupData
}

senderHistory повертається лише за період, потрібний правилам повторної відправки.

Поточні Golden-запити

Дані	Endpoint
Golden public key	GET /golden/api/getGoldenKey
Профілі RU	GET /golden/electron-api/getMenStore
Agency RU	GET /golden/electron-api/getActualAgencyStore
Фаворити	GET /golden/electron-api/getBaseFavorites
Email-дані фаворитів	GET /golden/electron-api/getFavoritesEmailInfo
Task history	POST /golden/electron-api/getTasks
Активні інвайти	POST /golden/electron-api/senders/getState + POST /golden/electron-api/sender-chat/getMessages + POST /golden/electron-api/sender-mail/getMessages
Sender history	POST /golden/electron-api/sender-chat/getHistory + POST /golden/electron-api/sender-mail/getHistory
White-list і блоки	POST /golden/extension/getWhiteList + POST /golden/electron-api/sender-mail/getBlockList
Sender blacklists	POST /golden/electron-api/sender-mail/getBlackLists

Рішення

• Endpoint: один shared startup endpoint.
• Family-сервіс активного проєкту: віддає свої дані shared-сервісу; назовні повертається один нормалізований пакет.
• Профілі RU: повний Golden RU store замінюється короткими профілями глобальних фаворитів.
• Реально: так, але потрібні нормалізатори Golden, Chathouse і Prime.

Запити: ціль 1 на логін оператора. Поточний Golden startup — 6 + 6T..8T, де T — кількість TU.

6. Синхронізація даних

Використовує: DataSyncService.

POST https://api.besocial.tech/golden/electron-api/syncData

Request

{
  supervisorFamilyId: string
  streams: StreamInterval[]
  online: TuOnlineInterval[]
  chats: ChatSenderResult[]
  mails: MailSenderResult[]
  senderAnswers?: SenderAnswer[] // додати
  views: ProfileView[]
  criticalLogs: CriticalLog[]
  actions: OperatorAction[]
  favoriteProfiles?: GlobalFavoriteProfileUpdate[] // додати
}

Response

{
  success: true
  data: {
    streamIds: string[]
    chatIds: string[]
    mailIds: string[]
    senderAnswerIds?: string[] // додати
    onlineIds: string[]
    viewsIds: string[]
    logIds: string[]
    actionIds: string[]
    favoriteProfileIds?: string[] // додати
  }
}

Рішення

• Endpoint: перенести в shared.
• DTO: додати project, favoriteProfiles, senderAnswers і відповідні ids в ack.
• Ack: кожна колекція повертає id реально збережених записів; тільки вони видаляються з SQLite.
• Реально: так; батч уже обробляє незалежні колекції та повертає ack окремо для кожної.

Запити: 1 / 60 с на оператора; якщо у колекції понад 200 записів — наступний батч через 3 с.

7. Отримання статистики

Використовує: StatisticsService.

Поточний Golden:

POST https://api.besocial.tech/golden/electron-api/getTempStatistics

Request

{
  ladyIds_api: number[]
  first: boolean
}

Response

{
  success: true
  data: {
    temp: Array<{
      ladyId_api: number
      manId_api: number
      date: string
      time: string
      sum: number
      operation: string
    }>
    history: Array<{
      ladyId_api: number
      manId_api: number
    }>
  }
}

Рішення

• Endpoint: один shared endpoint для Golden і Chathouse.
• Golden: shared-сервіс використовує наявний getTempStatistics.
• Chathouse: family-сервіс формує такий самий нормалізований знімок зі своєї статистики; окремого Electron endpoint зараз немає.
• DTO: у shared-контракті замінити проєктні ladyId_api/manId_api на tuId/ruId і додати project.
• Реально: потрібен shared endpoint і Chathouse-адаптер.

Запити: 1 / 60 с на оператора для всіх його TU активного проєкту.

8. Client E-mail Golden

Client E-mail повністю належить нашій системі. Family-сервіс і partner API для нього не потрібні.

Stack:

1. Підключає email-акаунт до Stack TU Card.
2. Керує доступом operator/teamlead до акаунта.
3. Зберігає листування та media зі status on_moderation, approved або rejected.
4. Виконує upload, delete і moderation media.

Electron через Stack API:

1. Отримує доступні оператору email-акаунти TU.
2. Читає і відправляє листи.
3. Отримує approved media для вкладень.
4. Передає непрочитаний вхідний лист у Task Factory як Unanswered e-mail.

Підключення акаунта, призначення доступів і moderation залишаються на нашому frontend та не переносяться в Electron.