official-api

OfficialApi

src/golden/official-api/official-api.service.ts

HTTP-клієнт до партнерського API goldenbride.net. Через нього ходять усі запити що стосуються TU/RU/повідомлень/онлайну/фінансів. Викликається тільки внутрішньо (контролера нема): statistics-downloading, ai-notes, workspace.

Партнерський сервлет: AgencyHelperV2 — POST /usermodule/services/agencyhelper/v2. Вкладення листів — окремий REST /goldenbride/services/upload/attach.

Авторизація і сесія

id_api+password (з golden_admins / golden_ladies) → команда login видає JSESSIONID. Далі на кожен наступний запит шлемо лише куку JSESSIONID, а не login/pass.

• Сесії кешуються у пам’яті по login (рядок id_api), TTL 3 хв (= idle-timeout сервера).
• ensureSession() піднімає сесію командою login, якщо в кеші нема або застаріла. Тільки login читає login/pass — решта команд їх не передає.
• При втраті сесії (X-Missing-JSESSIONID: true, або 401 від REST, або тіло success:false з помилкою про сесію) — один автоматичний перелогін + ретрай.
• Авторизації не вимагає лише ping. country раніше теж була публічною, але з 2026-07 партнер і для неї вимагає сесію (422 Session expired or missing без куки) — тому country() тепер приймає auth.

Чому так: партнер задеприкейтив неявний логін через login/pass на будь-якій команді. З ~2 тижні після релізу 2026-06-22 приймається лише JSESSIONID. Тому ми логінимось явно командою login і переюзаємо куку.

Команди й ендпоінти

• Фінанси/профілі/чат/онлайн — команди AgencyHelperV2 (finances, chatHistory, getMail, getLady, getMan, getPaidAttach, getOnlineLadies, getLadies, online, blackList, loadLetter, saveLetter, send/status/stop, country).
• Сесія — login / logout / ping.
• Вкладення листів — переїхали в MediaApiService (media-api): getAttach()/deleteAttach() через REST /goldenbride/services/upload/attach. Deprecated-команди attach/deleteAttach на AgencyHelperV2 повністю прибрані з коду (enum і commands map).

Нюанси

• chatHistory.media — для повідомлень з медіабібліотеки message === null, а медіа (фото/відео URL) приходить у result[].media ({type, small, large, url}). У ai-notes такі повідомлення підставляються як [photo]/[video].
• Rate-limit партнера — send/status/stop обмежені 1 запит / 5 сек. Ліміт зачіпає і saveLetter: send одразу після нього відбивається тим самим 422 (перевірено e2e 2026-07-03).
• status/stop без активної розсилки — партнер віддає урізане тіло (напр. {status:'end', id} або {status:'stop'}), тому count/id/list в інтерфейсах опціональні.
• Дрейф відповідей від доки партнера (зафіксовано e2e 2026-07-03): у фото-DTO зник urlThumbnailSmall, додались userId і webp-URL; у листах зʼявився letterType; у chatHistory — timestamp; у getMan нема publicId; finances[].isFinish приходить лише для чат-операцій.
• Помилки — усі неуспішні відповіді логуються у golden_error_report (error-report).
• official-api-test.service.ts — smoke-харнес для CI/staging: проганяє основні команди по тестовій парі TU/RU і повертає {success, message, time} на кожну.
• official-api.e2e-spec.ts — повний e2e усіх команд проти живого партнера (npm run test:official): strictCheck відповідей по інтерфейсах, write-тести (saveLetter, send→status→stop) під прапорцем RUN_WRITES.