# IPAL — Dokumentacja modułów

**Instalacja pakietu** (token Gitea, rejestr vs repozytorium) → główny
[README](../README.md).
**Nowy projekt krok po kroku** → [getting-started.md](./getting-started.md).

Ta dokumentacja opisuje **konfigurację i moduły** pluginu — zakłada, że
`@intecion/ipal-kit` jest już zainstalowany.

IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który
dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
wizualne i podłączenia do Next.js.

## Zasada

- **Plugin** = logika, helpery, konfiguracja, globale.
- **Klient (projekt)** = komponenty (wygląd), pliki-podłączenia Next.js
  (jednolinijkowe re-eksporty), konfiguracja front.

## Konfiguracja i wpięcie

### Wymagane zależności

Projekt klienta musi mieć (poza payloadem):

```json
"dependencies": {
  "@payloadcms/plugin-seo": "3.84.1",
  "@payloadcms/plugin-form-builder": "3.84.1",
  "nodemailer": "^8.0.1",
  "lucide-react": "^0.400.0",
  "slugify": "^1.6.6",
  "server-only": "^0.0.1"
}
```

Wersje `@payloadcms/*` **muszą** być identyczne z wersją `payload`. Wymuś
spójność przez `pnpm.overrides` (patrz niżej), inaczej Payload odrzuci wpięcie
pluginów (pusty tab SEO, brak kolekcji Forms) albo crashuje.

```json
"pnpm": {
  "overrides": {
    "payload": "3.84.1",
    "@payloadcms/ui": "3.84.1",
    "@payloadcms/next": "3.84.1",
    "@payloadcms/db-sqlite": "3.84.1",
    "@payloadcms/richtext-lexical": "3.84.1",
    "@payloadcms/plugin-seo": "3.84.1",
    "@payloadcms/plugin-form-builder": "3.84.1"
  }
}
```

### Po wpięciu — wygeneruj importMap

Plugin dostarcza komponenty admina (pola SEO). Po dodaniu uruchom:

```bash
pnpm payload generate:importmap
```

Bez tego pola SEO nie wyrenderują się (błąd `PayloadComponent not found in
importMap`).

```ts
// payload.config.ts
import { ipalKit } from '@intecion/ipal-kit'

export default buildConfig({
  // ...
  plugins: [
    ipalKit({
      i18n: {
        defaultLocale: 'pl',
        locales: [
          { code: 'pl', label: 'Polski' },
          { code: 'en', label: 'English' },
        ],
      },
      access: { authCollection: 'users' },
      pages: { slug: 'pages' },
      seo: { collections: ['pages', 'posts'] },
      forms: { redirectRelationships: ['pages'] },
    }),
  ],
})
```

## Entry pointy pakietu

| Import | Zawiera | Kontekst |
|---|---|---|
| `@intecion/ipal-kit` | logika server-safe, plugin, helpery | server / config |
| `@intecion/ipal-kit/server` | runtime server-only (sendEmail, verifyTurnstile, submitForm) | Server Actions / route handlers |
| `@intecion/ipal-kit/client` | komponenty client (consent, Turnstile, Analytics) | `'use client'` |
| `@intecion/ipal-kit/rsc` | RenderBlocks (RSC) | server component |
| `@intecion/ipal-kit/next/middleware` | locale middleware | middleware.ts / proxy.ts |

## Moduły

| Moduł | Opis | Dok |
|---|---|---|
| i18n | Lokalizacja, negocjacja locale, ścieżki URL | [i18n.md](./i18n.md) |
| pages | System pages (homepage/privacy/cookies) → ścieżki | [pages.md](./pages.md) |
| access | Role admin > editor > user, kontrola dostępu | [access.md](./access.md) |
| payload-helpers | getSiteSettings / getSiteIntegrations | [payload-helpers.md](./payload-helpers.md) |
| seo | Metadata, hreflang, auto-fill, plugin-seo | [seo.md](./seo.md) |
| blocks | RenderBlocks — silnik renderowania bloków | [blocks.md](./blocks.md) |
| consent | Banner cookies GDPR, Google Consent Mode | [consent.md](./consent.md) |
| turnstile | Cloudflare Turnstile (widget + verify) | [turnstile.md](./turnstile.md) |
| email | SMTP z panelu: adapter Payloada + sendEmail | [email.md](./email.md) |
| forms | Form-builder + submitForm (Turnstile + zapis) | [forms.md](./forms.md) |
| analytics | GA4 / GTM spięte z Consent Mode | [analytics.md](./analytics.md) |
| slug | Auto-slug z tytułu, per locale | [slug.md](./slug.md) |
| content | Blog/archiwa: kolekcje pod stroną-archiwum, listing, paginacja | [content.md](./content.md) |

Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
Referencja wdrożenia frontu: [frontend-setup.md](./frontend-setup.md)
Wydawanie nowych wersji wtyczki: [publishing.md](./publishing.md)

## Zasady dla wszystkich modułów

1. **Helpery przyjmują `payload` jako argument** — plugin nigdy nie woła
   `getPayload` sam.
2. **Sekrety w panelu** — SMTP, Turnstile secret, R2 w SiteIntegrations
   (admin-only). Odczyt server-side przez Local API.
3. **Client/server split** — kod z sekretami ma `server-only`; komponenty
   client w `@intecion/ipal-kit/client`.
4. **Generyki na typy klienta** — helpery przyjmują `<T>` (np. wygenerowany
   `SiteSetting`), bo plugin nie zna typów projektu.