# Migration Guide: 11.18.x → 11.19.0

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | REST controller path prefix `api/` removed from ErrorCode and SystemSetup endpoints |
| **New Features** | None |
| **Bugfixes** | None |
| **Migration Effort** | Minimal (~2 minutes) - update proxy config and/or hardcoded fetch URLs |

---

## Quick Migration

```bash
# Update package
npm install @lenne.tech/nest-server@11.19.0

# Verify build
npm run build

# Run tests
npm test
```

---

## Breaking Changes

### 1. REST Endpoint Paths Changed (Removed `api/` Prefix)

The `api/` prefix has been removed from two controller route paths to avoid conflicts with the Nuxt frontend proxy, which uses `/api/...` to forward requests to the backend.

**Affected endpoints:**

| Before | After |
|--------|-------|
| `GET /api/i18n/errors/:locale` | `GET /i18n/errors/:locale` |
| `GET /api/i18n/errors/codes` | `GET /i18n/errors/codes` |
| `GET /api/system-setup/status` | `GET /system-setup/status` |
| `POST /api/system-setup/init` | `POST /system-setup/init` |

**Why:** The Nuxt frontend proxy intercepts all `/api/...` requests and forwards them to the backend. When backend controllers also use `/api/...` as a route prefix, the paths conflict and cause issues with CORS and cookies during local development.

All other controllers (`auth`, `iam`, `files`, `tus`, `users`, etc.) already used paths without the `api/` prefix and are unaffected.

---

## Detailed Migration Steps

### Step 1: Update Package

```bash
npm install @lenne.tech/nest-server@11.19.0
```

### Step 2: Update Custom Controllers (If Applicable)

If your project has a custom controller extending `CoreErrorCodeController` or `CoreSystemSetupController`, update the `@Controller()` decorator:

**ErrorCode Controller:**

```typescript
// Before
@Controller('api/i18n/errors')
export class ErrorCodeController { ... }

// After
@Controller('i18n/errors')
export class ErrorCodeController { ... }
```

**SystemSetup Controller:**

```typescript
// Before
@Controller('api/system-setup')
export class SystemSetupController extends CoreSystemSetupController { ... }

// After
@Controller('system-setup')
export class SystemSetupController extends CoreSystemSetupController { ... }
```

### Step 3: Update Frontend Fetch Calls

If your frontend makes direct fetch calls to these endpoints (without the Nuxt proxy), update the URLs:

```typescript
// Before
const status = await fetch('/api/system-setup/status');
const errors = await fetch('/api/i18n/errors/de');

// After (direct backend calls)
const status = await fetch('/system-setup/status');
const errors = await fetch('/i18n/errors/de');

// If using Nuxt proxy (no change needed - proxy maps /api/* automatically)
const status = await fetch('/api/system-setup/status'); // proxy strips /api/
```

### Step 4: Update Reverse Proxy / Nginx Config (If Applicable)

If your deployment uses a reverse proxy with explicit route rules for these endpoints, update accordingly.

---

## Compatibility Notes

- **Nuxt proxy users:** If your Nuxt frontend uses the `/api/...` proxy (default in nuxt-extensions), no frontend changes are needed. The proxy strips the `/api/` prefix before forwarding to the backend.
- **Direct API consumers:** Any client calling the backend directly (e.g., mobile apps, scripts, Postman collections) must update the endpoint URLs.
- **Other endpoints unaffected:** `auth`, `iam`, `files`, `tus`, `users`, `avatar`, `health-check`, and `permissions` endpoints remain unchanged.

---

## Troubleshooting

### Endpoints return 404 after update

**Cause:** Still using the old `/api/...` paths.

**Solution:** Remove the `api/` prefix from the endpoint URL:
- `/api/i18n/errors/de` → `/i18n/errors/de`
- `/api/system-setup/status` → `/system-setup/status`

### Custom ErrorCode controller not working

**Cause:** Custom controller still uses `@Controller('api/i18n/errors')`.

**Solution:** Update the decorator to `@Controller('i18n/errors')`.

---

## Module Documentation

### ErrorCode Module

- **README:** [src/core/modules/error-code/](../src/core/modules/error-code/)
- **Integration Checklist:** [INTEGRATION-CHECKLIST.md](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)

### System Setup Module

- **README:** [src/core/modules/system-setup/README.md](../src/core/modules/system-setup/README.md)
- **Integration Checklist:** [INTEGRATION-CHECKLIST.md](../src/core/modules/system-setup/INTEGRATION-CHECKLIST.md)

---

## References

- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
