# @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.

```bash
# add to ~/.zshrc (or ~/.bashrc)
export GITEA_TOKEN=paste_your_token_here
```

Reload your shell (`source ~/.zshrc`) or open a new terminal window.

---

## 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.** Create an `.npmrc` file in your project directory
(or add these two lines to `~/.npmrc` to make it work globally):

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

Because the token lives in the `${GITEA_TOKEN}` variable, this file holds no
secret — you can safely commit it.

**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
- **[install.md](./docs/install.md)** — more on installation and troubleshooting
- **[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 **[docs/install.md](./docs/install.md)** or message the
team that maintains the plugin.