# @intecion/ipal-kit

Intecion Payload Advanced Library — a plugin for Payload CMS 3.

Provides internationalization (per-locale routing, hreflang, language switcher),
SEO (metadata, canonical, sitemap, robots), forms (Turnstile, rate limiting,
validation), consent management (consent mode), analytics (GA4/GTM), and a
blog/archive system (collections under an archive page, listing, pagination).

**Repository:** https://git.intecion.net/IntecionSoftware/ipal-kit

---

## Before you start

The `git.intecion.net` server is internal — you'll only see the code and the
package once you're signed in to your Intecion account. Every installation method
needs your personal access token. Without it you'll get a 404 or an
"Unauthorized" error.

You generate the token once. It's tied to your account — don't ask anyone for
theirs, and don't put it in any file that ends up in a repository.

### Generate a token

1. Sign in to Gitea → click your avatar → **Settings**.
2. **Applications → Generate New Token**.
3. Name it (e.g. `ipal-kit-install`) and select the scope:
   - `read:package` — if you only install the plugin in projects,
   - `write:package` — additionally, if you'll publish new versions.
4. Click **Generate**. Copy the token now — Gitea shows it only once.

### Store the token in your environment

Don't paste the token straight into project files. Keep it in an environment
variable, so your install config carries no secret. How you set it depends on
your system:

**macOS** (default shell is zsh):
```bash
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.zshrc
source ~/.zshrc
```

**Linux / Ubuntu** (default shell is bash):
```bash
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.bashrc
source ~/.bashrc
```

**Windows (PowerShell)** — set it permanently for your user, then open a new
terminal so it takes effect:
```powershell
setx GITEA_TOKEN "paste_your_token_here"
```

> On Windows, `setx` writes the variable but does **not** affect the current
> window — close it and open a new PowerShell for the token to be visible.

---

## Installation

There are two routes. Pick **Route A** if you just want to use the plugin in a
project — it's faster and versioned. Choose **Route B** only when you need a
specific, unreleased commit straight from the repository.

### Route A — from the registry (recommended)

The plugin is published to the package registry in Gitea. You pull a ready-built
package and build nothing locally.

**1. Configure the registry.** Add these two lines to an `.npmrc` file:

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

You can put this file **in the project directory** (applies to that project) or
**globally** (applies everywhere). The global location differs by system:

| System | Global `.npmrc` path |
|---|---|
| macOS | `~/.npmrc` (i.e. `/Users/you/.npmrc`) |
| Linux / Ubuntu | `~/.npmrc` (i.e. `/home/you/.npmrc`) |
| Windows | `%USERPROFILE%\.npmrc` (i.e. `C:\Users\you\.npmrc`) |

Fastest way to create the global file:

```bash
# macOS / Linux
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
```
```powershell
# Windows (PowerShell) — same command, npm handles the path
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
```

Then add the auth line manually (npm config doesn't set tokens with variables).
Because the token lives in the `${GITEA_TOKEN}` variable, the file holds no
secret — you can safely commit a project-level `.npmrc`.

> **Windows note:** the `${GITEA_TOKEN}` syntax in `.npmrc` is expanded by npm/pnpm
> itself, not by the shell — so it works the same on Windows as on macOS/Linux,
> as long as you set the variable with `setx` (see above).

**2. Install:**

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

### Route B — straight from the repository

pnpm clones the repository and uses the pre-built output. There's no `gitea:`
shorthand — give the full address.

Over HTTPS with your token:

```bash
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
```

Or over SSH, if you have a key added in Gitea:

```bash
pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git
```

Append a specific version after `#` to pin to a release:

```bash
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0
```

---

## Finish setting up your project

The plugin doesn't pull in the dependencies it shares with Payload — add them
yourself, in a version matching your Payload:

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

From here, the guide takes over: **[docs/getting-started.md](./docs/getting-started.md)** —
from an empty project to a working site.

---

## Publishing a new version

This section only applies if you develop the plugin itself and publish new
versions. You'll need a token with the `write:package` scope.

In `~/.npmrc`:

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

Build, bump the version number, publish:

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

Bump the version on every release — that way pnpm always sees the new package and
nobody gets stuck on a stale one from the cache.

---

## Documentation

Everything lives in the **[docs/](./docs)** directory. To get started:

- **[getting-started.md](./docs/getting-started.md)** — project setup, step by step
- **[publishing.md](./docs/publishing.md)** — releasing new plugin versions
- **[README.md](./docs/README.md)** — index of the plugin's modules

---

## Something not working?

| What you see | What's wrong |
|---|---|
| `404` or `Unauthorized` on `pnpm add @intecion/...` | no token in `.npmrc`, a wrong token, or you don't have access to the organization in Gitea |
| `404` when installing from the `.git` address | you're not signed in, the token is missing from the address, or you lack access to the repository |
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | an attempt to build on install from git — report it to whoever publishes the plugin |
| old code after reinstalling | cache: run `pnpm store prune`, then remove `.next` and `node_modules/@intecion` |

If you get stuck, check the troubleshooting table above, see
**[docs/publishing.md](./docs/publishing.md)** for distribution issues, or message
the team that maintains the plugin.