# Уведомления: Gnexus Synapse

Исходящие уведомления сервисов (email, Telegram, web-push, system-to-system
доставка) идут через хаб Gnexus Synapse. Каждый сервис, который шлёт уведомления,
интегрируется с Synapse и не держит собственных каналов доставки. Как Synapse
доставляет и кому — решает маршрутизация Synapse, не отправитель.

## Правила
- Каналы доставки (email, Telegram, push) и их секреты живут в Synapse, а не в каждом сервисе. Секреты интеграции — в `.env` и gnexus-creds.
- Что шлёт сервис — это его знание («что случилось у меня»): конверт события. Кому и куда доставить — решают правила маршрутизации в Synapse. В конверте **нет получателей, каналов и топиков**.
- Свой очередь/механизм ретраев для уведомлений не строить — это забота Synapse.

## Интеграция отправителя

1. **Регистрация источника**: админка Synapse → Источники → создать (или MCP-инструментом). На выходе — API-ключ `syn_*`, показывается ровно один раз: в `.env` сервиса и в gnexus-creds. Ключ — только удостоверение источника; имя `source` в конверте должно совпадать с источником ключа (анти-спуфинг).
2. **Отправка**: `POST https://synapse.gnexus.space/api/v1/events`, заголовок `Authorization: Bearer syn_*`. Приём мгновенно возвращает `202` — обработка асинхронная. Статус доставки — `GET /api/v1/events/{id}`.
3. **Конверт v1**: поля `source`, `subject`, `action`, `priority` (`low|normal|high|critical`), `payload` (объект), `dedup_key`, `ttl_seconds`, `scheduled_at`. Полный контракт — `docs/05-ingestion-api.md` в репо Synapse.
4. **Адресное уведомление пользователю** — конвенция `payload.user_id` = `sub` gnexus-auth (это часть payload-конвенции, не получатель).
5. **Client-libs**: тонкие клиенты без очередей — `gn-synapse-client-py` (PyPI `gnexus-synapse`), `gn-synapse-client-php` (Composer `gnexus/synapse-client`), установка по свежему тегу (`v0.1.2`). Конфиг только env:

   | env | что |
   |---|---|
   | `SYNAPSE_URL` | базовый URL хаба |
   | `SYNAPSE_API_KEY` | ключ `syn_*` источника |
   | `SYNAPSE_TIMEOUT` | таймаут HTTP, сек |
   | `SYNAPSE_DEFAULT_SOURCE` | умолчание `source` (смягчает 403 анти-спуфинга) |

## Интеграция получателя (system-to-system)

Сервис, который *хочет получать* события (Navi-инстансы и др.), отдаёт webhook-эндпоинт, и он регистрируется в Synapse как **цель** (Target). Дальше Synapse сам шлёт deliveries с ретраями; статусы видны в логе доставок админки.

## Ссылки
- Репозиторий: https://git.gnexus.space/root/gnexus-synapse (контракт v1 — `docs/05-ingestion-api.md`)
- Факты: gnexus-book → `10-systems/services/gnexus-synapse.md`