init commit for iPAL-kit plugin

2026-07-18 20:30:23 +02:00
parent 10638127a9
commit 5733a9c8bf
119 changed files with 6892 additions and 411 deletions
@@ -0,0 +1,165 @@
+# forms
+
+Wpina `@payloadcms/plugin-form-builder` (kolekcje forms + form-submissions) i
+dostarcza `submitForm` — wywoływalną z frontu funkcję, która spina: weryfikację
+Turnstile → zapis zgłoszenia → wysyłkę maili (naszym senderem).
+
+## Zależność
+
+```json
+"dependencies": { "@payloadcms/plugin-form-builder": "3.84.1" }
+```
+
+## Config (payload.config.ts)
+
+```ts
+ipalKit({
+  forms: {
+    redirectRelationships: ['pages'],   // formularz może przekierować na Page
+    // fields: { text: true, textarea: true, email: true, ... },  // domyślnie włączone sensowne
+  },
+})
+```
+
+Dodaje kolekcje **Forms** (edytor buduje formularze) i **Form Submissions**
+(zgłoszenia). Wbudowany email form-buildera jest nieużywany — wysyłką zajmuje
+się `submitForm` przez nasz sender (SMTP z panelu).
+
+## Front — submitForm (server)
+
+Zwykle w Server Action wywoływanej przez formularz. HTML obu maili składasz
+na froncie (Twój wygląd):
+
+```ts
+import { submitForm } from 'ipal-kit/server'
+
+const result = await submitForm({
+  payload,
+  formId,                    // z kolekcji Forms
+  data: { name, email, message },
+  turnstileToken,            // opcjonalny — jeśli podany, weryfikowany
+  ip,
+  emails: {
+    // wiadomość do klienta/admina (np. "nowe zgłoszenie")
+    notification: {
+      to: '[email protected]',
+      subject: 'Nowe zgłoszenie',
+      html: renderAdminEmail(data),   // Twój HTML
+    },
+    // potwierdzenie do wysyłającego
+    confirmation: {
+      to: email,
+      subject: 'Dziękujemy za wiadomość',
+      html: renderUserEmail(data),    // Twój HTML
+    },
+  },
+})
+
+if (result.success) {
+  // result.submissionId
+  // result.emails.notification?.sent / result.emails.confirmation?.sent
+} else {
+  // result.error — np. Turnstile / zapis
+}
+```
+
+## Flow i gwarancje
+
+1. **Turnstile** (jeśli token) → nieudany → odrzuć **przed** zapisem (brak
+   spamu w bazie).
+2. **Zapis** submission (form-submissions).
+3. **Maile** — oba opcjonalne, HTML z frontu.
+4. Zwrot: `{ success, submissionId, emails: { notification?, confirmation? } }`.
+
+**Zapisane zgłoszenie = sukces, nawet gdy mail padnie.** Status wysyłki maili
+jest osobno w `result.emails`, żeby dane zgłoszenia nie ginęły przez chwilową
+awarię SMTP. Front może zareagować (ostrzec, ponowić).
+
+Oba maile opcjonalne — możesz wysłać jeden, drugi, oba lub żaden.
+`turnstileToken` opcjonalny — brak = pominięcie weryfikacji (decydujesz per
+formularz).
+
+## Maile
+
+Plugin nie składa maili formularzy. Po zapisie submission form-builder wysyła
+wiadomości skonfigurowane przez edytora (Forms → formularz → Emails), przez
+`payload.sendEmail`. Żeby wyszły, config musi mieć adapter:
+
+```ts
+email: panelSmtpAdapter(),   // z 'ipal-kit'
+```
+
+Wtedy idą przez SMTP z Site Integrations. Edytor ustawia odbiorców, temat i
+treść (placeholdery: `{{pole}}`, `{{*}}`, `{{*:table}}`) bez dotykania kodu.
+
+`submitForm` odpowiada tylko za weryfikację Turnstile i zapis.
+
+## Własne pola w kolekcji formularzy
+
+`formOverrides` przechodzi prosto do form-buildera — plugin nie ma opinii, czego
+formularz potrzebuje poza swoimi polami:
+
+```ts
+ipalKit({
+  forms: {
+    redirectRelationships: ['pages'],
+    formOverrides: {
+      fields: ({ defaultFields }) => [
+        ...defaultFields,
+        { name: 'internalNote', type: 'textarea' },
+      ],
+      admin: { group: 'Content' },
+    },
+    // formSubmissionOverrides: { ... }   // to samo dla zgłoszeń
+  },
+})
+```
+
+`fields` dostaje domyślne pola kolekcji i zwraca finalną listę — możesz dodawać,
+usuwać, zmieniać kolejność. Poza `fields` przyjmuje dowolne ustawienia kolekcji
+(admin, access, hooks).
+
+## Bezpieczeństwo i wynik zgłoszenia
+
+`submitForm` przechodzi trzy bramki w kolejności rosnącej po koszcie: rate limit
+(in-memory, per IP), Turnstile, walidacja względem schematu formularza. Dopiero
+potem zapis. Flood ginie, zanim dotknie sieci czy bazy.
+
+Walidacja jest istotna, bo server action to publiczny endpoint — da się go wołać
+z pominięciem formularza. Plugin ładuje definicję formularza i: odrzuca nieznane
+klucze, wymusza pola `required`, tnie długość (5000 znaków). Do bazy trafia tylko
+to, co formularz definiuje.
+
+Rate limit: 5/min/IP domyślnie, `maxPerMinute` zmienia, `0` wyłącza (gdy limiter
+jest z przodu). In-memory — przy wielu instancjach licznik jest per-proces, więc
+efektywny limit to per-instancja. Do formularza kontaktowego wystarcza.
+
+### Wynik to KOD, nie tekst
+
+`submitForm` zwraca ustrukturyzowany błąd — plugin mówi CO się stało, projekt
+decyduje JAK to pokazać (język, brzmienie, obsługa per pole):
+
+```ts
+type SubmitFormResult =
+  | { success: true; submissionId: string | number }
+  | { success: false; reason: 'rate_limited' }
+  | { success: false; reason: 'turnstile' }
+  | { success: false; reason: 'validation'; field?: string; kind?: 'required' | 'too_long' | 'unknown_fields' }
+  | { success: false; reason: 'not_found' }
+  | { success: false; reason: 'error' }
+```
+
+Front mapuje kody na własne komunikaty:
+
+```tsx
+function errorMessage(r) {
+  switch (r.reason) {
+    case 'rate_limited': return 'Zbyt wiele zgłoszeń...'
+    case 'validation':
+      if (r.kind === 'required') return 'Uzupełnij wymagane pola.'
+      // r.field → podświetl konkretne pole
+  }
+}
+```
+
+Ten sam wzorzec co consent: plugin nie zaszywa języka, oddaje dane.