graph + mail dispatcher, test-email endpoint, notifications global

2026-08-22 17:55:43 +02:00
parent 3d8bc9019f
commit ac48f1e9d1
40 changed files with 1336 additions and 13 deletions
@@ -0,0 +1,69 @@
+# notifications
+
+Teksty powiadomień (wyniki akcji) konfigurowane w panelu, per język, z
+fallbackiem. Na dziś obsługuje komunikaty wyników formularza (`submitForm`),
+z miejscem na przyszłe konteksty. Global **Notifications**, budowany zawsze.
+
+## Zasada
+
+Plugin daje KOD wyniku (`submitForm` zwraca `reason`), nie tekst. Ten moduł
+mapuje kod → tekst z panelu (localized), z fallbackiem angielskim per pole.
+Front dostaje gotowy string i styluje go jak chce (toast, inline, banner).
+Dzięki temu żaden komunikat nie jest zaszyty w kodzie — wszystko przez panel.
+
+## Config
+
+Brak opcji — global **Notifications** jest zawsze budowany. Edytor zarządza
+tekstami w panelu (karta Notifications), grupowane per kontekst. Grupa `form`:
+`success`, `error`, `rateLimited`, `turnstile`, `validation`, `consent`,
+`notFound`. Każde pole puste → fallback (NOTIFICATION_FALLBACK).
+
+## Helper — getNotificationTexts
+
+Pobiera teksty z globala per język, fallback per pole. Analog `getConsentTexts`:
+
+```ts
+import { getNotificationTexts } from '@intecion/ipal-kit'
+
+const notifications = await getNotificationTexts({ payload, locale })
+// notifications.form.error, notifications.form.success, ...
+```
+
+## Mapowanie wyniku — resolveFormMessage
+
+Most między `submitForm` a UI: bierze wynik i teksty, zwraca jeden komunikat.
+Interpoluje `{field}` w walidacji. NIGDY nie pokazuje surowego wyjątku
+(`error` → generyczny tekst, nie treść błędu backendu).
+
+```ts
+import { resolveFormMessage } from '@intecion/ipal-kit'
+
+const result = await submitFormAction(...)
+if (!result.success) {
+  setError(resolveFormMessage(result, notifications.form))
+}
+```
+
+To zastępuje sztywne `Błąd: ${result.reason}` — teraz przyjazny tekst z panelu,
+per język.
+
+## Interpolacja {field}
+
+Tekst `validation` może zawierać `{field}` — podstawia się nazwa pola z błędem:
+
+```
+Panel:  "Sprawdź pole {field} i spróbuj ponownie."
+Wynik:  "Sprawdź pole email i spróbuj ponownie."
+```
+
+## Rozszerzanie o nowe konteksty
+
+Grupa `form` to pierwszy kontekst. Kolejne (`newsletter`, `system`) dodaje się
+tak samo — nowa grupa w `globals/Notifications/fields.ts` + pole w typach +
+fallback. `getNotificationTexts` resolwuje, co istnieje.
+
+## Dostęp
+
+Global ma `read: () => true` — teksty są publiczne (pokazywane użytkownikom
+końcowym), więc front czyta je bez sesji. Inaczej niż SiteIntegrations
+(`read: isAdmin` — tam sekrety).