init commit for iPAL-kit plugin

docs/payload-helpers.md

@@ -0,0 +1,54 @@
+# payload-helpers
+
+Typowany dostęp do globali pluginu (SiteSettings, SiteIntegrations) przez
+Local API. Zgodnie z zasadą: helpery przyjmują `payload` jako argument —
+plugin nigdy nie woła `getPayload` sam.
+
+## Config
+
+Brak — te globale są zawsze budowane przez plugin. Nie ma osobnej opcji.
+
+## Front — odczyt globali
+
+```ts
+import { getSiteSettings, getSiteIntegrations } from 'ipal-kit'
+import type { SiteSetting, SiteIntegration } from '@/payload-types'
+
+const payload = await getPayload({ config })
+
+// SiteSettings (publiczne — siteName, logo, favicon, theme, system pages)
+const settings = await getSiteSettings<SiteSetting>(payload, { locale: 'pl' })
+
+// SiteIntegrations (admin-only; Local API omija access control)
+const integrations = await getSiteIntegrations<SiteIntegration>(payload)
+```
+
+Generyk `<T>` pozwala wstrzyknąć wygenerowany typ klienta. Bez niego zwraca
+`Record<string, unknown>`.
+
+## ⚠️ SiteIntegrations zawiera sekrety
+
+Local API domyślnie omija access control (`overrideAccess: true`), więc
+`getSiteIntegrations` **zwróci sekrety** (SMTP password, Turnstile secret,
+R2 keys) mimo bariery admin-only na globalu. To zamierzone — logika serwerowa
+tego potrzebuje.
+
+**Nigdy nie przekazuj surowego wyniku do przeglądarki.** Czytaj konkretne
+wartości server-side, do klienta wysyłaj tylko bezpieczne (np. `turnstileSiteKey`,
+nie `turnstileSecretKey`):
+
+```ts
+// ŹLE — wyciek sekretów do klienta
+return <Form data={await getSiteIntegrations(payload)} />
+
+// DOBRZE — tylko publiczna wartość
+const { turnstileSiteKey } = await getSiteIntegrations(payload)
+return <Form siteKey={turnstileSiteKey} />
+```
+
+## Niższy poziom: getGlobal
+
+```ts
+import { getGlobal } from 'ipal-kit'
+const data = await getGlobal<MyType>(payload, 'moj-global', { locale: 'pl', depth: 1 })
+```