# @intecion/ipal-kit

Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n
(routing per-locale, hreflang, przełącznik języka), SEO (metadane, canonical,
sitemapa, robots), formularze (Turnstile, rate limit, walidacja), consent mode,
analytics (GA4/GTM), oraz system bloga/archiwów (kolekcje pod stroną-archiwum,
listing, paginacja).

Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit
(dostęp tylko dla zalogowanych pracowników Intecion).

---

## Instalacja

> **Serwer jest prywatny.** Zarówno kod, jak i pakiet w Gitea są widoczne tylko
> po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta
> pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji.

### Krok 1 — token dostępu (raz na osobę)

W Gitea: **Ustawienia → Aplikacje → Wygeneruj token dostępu**. Nadaj zakresy:
- `read:package` — do instalacji (wystarczy pracownikowi)
- `write:package` — dodatkowo, jeśli będziesz publikować wydania

Skopiuj token (pokazuje się raz).

### Krok 2 — wybierz drogę instalacji

Dwie drogi. **A (rejestr Gitea)** jest zalecana dla zespołu — daje wersjonowanie
i szybką instalację gotowego builda. **B (bezpośrednio z git)** nie wymaga
publikowania, ale buduje/pobiera z repo.

---

## Droga A — rejestr npm w Gitea (zalecana)

Gitea ma wbudowany rejestr npm. Publikujesz zbudowany pakiet, pracownicy pobierają
gotowy `dist` — bez budowania u siebie.

### Konfiguracja u pracownika (instalacja)

`.npmrc` w projekcie **albo** globalnie (`~/.npmrc`):

```
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
```

Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — `.npmrc` można
wtedy nawet zacommitować):

```bash
# ~/.zshrc
export GITEA_TOKEN=twój_token_z_gitea
```

Instalacja:

```bash
pnpm add @intecion/ipal-kit
```

### Publikacja (osoba wydająca)

W `package.json` pluginu (jest już ustawione):
```json
"publishConfig": {
  "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
}
```

`~/.npmrc` z tokenem `write:package`:
```
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
```

Wydanie:
```bash
pnpm clean && pnpm build
npm version patch          # 1.0.0 → 1.0.1
npm publish
```

Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym
czyszczeniem cache. `publishConfig` działa poprawnie (exports z dist), nie musisz
ruszać głównego `exports`.

---

## Droga B — bezpośrednio z repozytorium git

Bez publikowania. pnpm klonuje repo i bierze zacommitowany `dist`.

### Uwierzytelnienie

Serwer prywatny, więc git musi mieć dostęp. Dwie opcje:

**SSH** (jeśli masz klucz w Gitea):
```bash
pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git
```

**HTTPS z tokenem**:
```bash
pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
```

Konkretny tag (stabilniej niż główny branch):
```bash
pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0
```

> Nie ma skrótu `gitea:` (jak `github:`). Zawsze pełny URL `git+https://` lub
> `git+ssh://`.

### Wymagania po stronie repo (dla wydającego)

Instalacja z git NIE buduje pakietu, więc:
- **`dist/` musi być zacommitowany** — zbuduj i zacommituj przed każdym wydaniem
- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować
  i żąda `onlyBuiltDependencies`
- **główny `exports` wskazuje `dist`** (nie `src`) — instalacja z git czyta
  główny exports, `publishConfig` jest ignorowane przy git

---

## Po instalacji (obie drogi)

Dodaj peer-zależności — plugin ich nie zaciąga:

```bash
pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \
         nodemailer lucide-react slugify server-only
```

Konfiguracja pluginu, krok po kroku: [docs/getting-started.md](./docs/getting-started.md).

---

## Dokumentacja

Pełna dokumentacja w [docs/](./docs). Start:
- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu
- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka
- [docs/README.md](./docs/README.md) — spis modułów

---

## Diagnostyka instalacji

| Objaw | Przyczyna |
|---|---|
| `404` / `Unauthorized` przy `pnpm add @intecion/...` | brak/zły token w `.npmrc`, albo brak dostępu do organizacji w Gitea |
| `404` na `git.intecion.net/.../ipal-kit.git` | nie zalogowany / brak tokenu w URL / brak uprawnień do repo |
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (Droga B) — usuń, `dist` jest w repo |
| `Cannot find module .../src/...ts` | główny `exports` wskazuje src zamiast dist |
| stary kod mimo reinstall | cache; `pnpm store prune && rm -rf .next node_modules/@intecion` |

Więcej: [docs/install.md](./docs/install.md).