@schafevormfenster/rest-commons 0.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,1190 @@
+# Contributing to @schafevormfenster/rest-commons
+
+This guide explains **how to use** this package and **how to develop** proper REST API endpoints following our standards.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Package Overview](#package-overview)
+- [REST Service Design Patterns](#rest-service-design-patterns)
+  - [Technology Stack](#technology-stack)
+  - [Response Structure Patterns](#response-structure-patterns)
+  - [Contract-First Development](#contract-first-development)
+  - [Schema-Driven Validation](#schema-driven-validation)
+- [Authentication Patterns](#authentication-patterns)
+- [Caching Strategy](#caching-strategy)
+- [Input Validation & Security](#input-validation--security)
+- [Error Handling](#error-handling)
+- [API Design Patterns](#api-design-patterns)
+  - [Unified GET/POST Endpoints](#unified-getpost-endpoints)
+  - [Static-First Processing](#static-first-processing)
+- [Testing Guidelines](#testing-guidelines)
+  - [E2E Testing with Playwright](#e2e-testing-with-playwright)
+  - [Unit Testing](#unit-testing)
+- [ESLint Rules for REST APIs](#eslint-rules-for-rest-apis)
+  - [Critical Rules](#critical-rules)
+  - [Important Rules](#important-rules)
+  - [Best Practice Rules](#best-practice-rules)
+- [Development Workflow](#development-workflow)
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pnpm add @schafevormfenster/rest-commons
+```
+
+### Basic Usage
+
+```typescript
+// Import standardized response schemas
+import {
+  ResultSchema,
+  ResultsSchema,
+  ErrorSchema,
+  HealthSchema,
+  OkaySchema,
+} from "@schafevormfenster/rest-commons";
+
+// Import primitive schemas
+import {
+  LocationSchema,
+  SlugSchema,
+  UuidSchema,
+} from "@schafevormfenster/rest-commons";
+
+// Import time utilities
+import {
+  ISO8601Schema,
+  parseRelativeTime,
+  isRelativeTime,
+} from "@schafevormfenster/rest-commons";
+
+// Import validation helpers
+import {
+  detectSuspiciousPatterns,
+  normalizeList,
+  getCorrelationId,
+} from "@schafevormfenster/rest-commons";
+```
+
+---
+
+## Package Overview
+
+**@schafevormfenster/rest-commons** is the centralized authority for REST API standards and schemas. It provides:
+
+- **Standardized Response Schemas**: Consistent wrappers for single resources, collections, errors, and health checks
+- **Primitive Schemas**: Reusable Zod schemas for common data types (UUID, slug, location, etc.)
+- **Time Utilities**: ISO 8601 handling, relative time parsing, week boundaries
+- **Validation Helpers**: Input sanitization, suspicious pattern detection, parameter validation
+- **Response Utilities**: Correlation IDs, header builders, environment detection
+
+### What This Package Contains
+
+```
+src/
+├── api-schemas/           # Standardized response schemas
+│   ├── result.schema.ts   # Single resource response
+│   ├── results.schema.ts  # Collection response
+│   ├── error.schema.ts    # Error response
+│   ├── health.schema.ts   # Health check response
+│   └── okay.schema.ts     # Success acknowledgment
+├── primitives/            # Reusable primitive schemas
+│   ├── location.schema.ts
+│   ├── slug.schema.ts
+│   ├── uuid.schema.ts
+│   └── ...
+├── time/                  # Time handling utilities
+│   ├── iso8601.types.ts
+│   ├── parse-relative-time.ts
+│   └── ...
+├── helpers/               # Validation and utilities
+│   ├── detect-suspicious-patterns.ts
+│   ├── parameter-validation.ts
+│   ├── correlation/
+│   └── response-headers/
+├── normalization/         # Data normalization
+└── validation/            # Zod utilities
+```
+
+---
+
+## REST Service Design Patterns
+
+### Technology Stack
+
+Our REST APIs are built using:
+
+- **ts-rest**: Contract-first API development
+- **Zod**: Runtime schema validation and type safety
+- **Next.js**: API routes and handlers
+- **Fetch API**: HTTP client (axios is forbidden)
+- **date-fns**: Date handling (moment is forbidden)
+
+⚠️ **Enforced by ESLint**: `stack/no-forbidden-imports` prevents usage of forbidden libraries.
+
+### Response Structure Patterns
+
+All API endpoints must use standardized response schemas from this package:
+
+#### Single Resource Response (`ResultSchema`)
+
+Use for endpoints that return a single resource:
+
+```typescript
+import { ResultSchema } from "@schafevormfenster/rest-commons";
+
+// Define your data schema
+const MyDataSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+// Response schema
+const MyResponseSchema = ResultSchema.extend({
+  data: MyDataSchema,
+});
+
+export type MyResponse = z.infer<typeof MyResponseSchema>;
+
+// Returns:
+// {
+//   status: 200,
+//   timestamp: "2024-01-15T10:30:00.000Z",
+//   data: { id: "123", name: "Example" }
+// }
+```
+
+#### Collection Response (`ResultsSchema`)
+
+Use for endpoints that return multiple resources:
+
+```typescript
+import { ResultsSchema } from "@schafevormfenster/rest-commons";
+
+const MyCollectionSchema = ResultsSchema.extend({
+  data: z.array(MyDataSchema),
+});
+
+// Returns:
+// {
+//   status: 200,
+//   timestamp: "2024-01-15T10:30:00.000Z",
+//   data: [...]
+// }
+```
+
+#### Error Response (`ErrorSchema`)
+
+All errors should use the standardized error schema:
+
+```typescript
+import { ErrorSchema } from "@schafevormfenster/rest-commons";
+
+// Returns:
+// {
+//   status: 400,
+//   timestamp: "2024-01-15T10:30:00.000Z",
+//   error: "Validation error: Required field missing"
+// }
+```
+
+#### Success Response (`OkaySchema`)
+
+For operations without data payload:
+
+```typescript
+import { OkaySchema } from "@schafevormfenster/rest-commons";
+
+// Returns:
+// {
+//   status: 200,
+//   timestamp: "2024-01-15T10:30:00.000Z",
+//   message: "Operation completed successfully"
+// }
+```
+
+#### Health Check Response (`HealthSchema`)
+
+For service monitoring:
+
+```typescript
+import { HealthSchema } from "@schafevormfenster/rest-commons";
+
+// Returns:
+// {
+//   status: 200,
+//   timestamp: "2024-01-15T10:30:00.000Z",
+//   name: "My API",
+//   version: "1.0.0",
+//   dependencies: [...]
+// }
+```
+
+### Contract-First Development
+
+API contracts define the interface before implementation:
+
+1. **Define the contract** using ts-rest
+2. **Define Zod schemas** in `*.schema.ts` files
+3. **Implement route handlers** using the contract
+4. **Write tests** against the contract
+
+⚠️ **Enforced by ESLint**: `rest/enforce-api-route-structure` ensures every route has:
+- `route.ts` - Route handler implementation
+- `route.test.ts` - Co-located tests
+- `*.contract.ts` - ts-rest API contract
+- `*.schema.ts` - Zod schemas and TypeScript types
+
+### Schema-Driven Validation
+
+Every Zod schema **must** have a corresponding TypeScript type export:
+
+```typescript
+// ✅ CORRECT: Schema with TypeScript type export
+export const UpdateRequestSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+export type UpdateRequest = z.infer<typeof UpdateRequestSchema>;
+```
+
+```typescript
+// ❌ INCORRECT: Schema without TypeScript type export
+export const UpdateRequestSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+// Missing: export type UpdateRequest = z.infer<typeof UpdateRequestSchema>;
+```
+
+⚠️ **Enforced by ESLint**: `rest/enforce-schema-type-export` ensures all schemas have type exports.
+
+**Naming Convention**:
+- Schema: `{Name}Schema` (e.g., `UpdateCalendarRequestSchema`)
+- Type: `{Name}` (e.g., `UpdateCalendarRequest`)
+
+**Reuse Common Schemas**:
+
+```typescript
+// ✅ PREFERRED: Reuse standard response wrapper
+import { ResultSchema } from "@schafevormfenster/rest-commons";
+
+export const MyResponseSchema = ResultSchema.extend({
+  data: z.object({
+    message: z.string(),
+  }),
+});
+```
+
+```typescript
+// ❌ DISCOURAGED: Defining response structure from scratch
+export const MyResponseSchema = z.object({
+  status: z.number(),
+  timestamp: z.string(),
+  data: z.object({
+    message: z.string(),
+  }),
+});
+```
+
+⚠️ **Enforced by ESLint**: `rest/prefer-schema-extension` warns when you define schemas from scratch.
+
+---
+
+## Authentication Patterns
+
+### Token-as-Path Design
+
+All authenticated endpoints require the token as a **path parameter**, not a header:
+
+✅ **Correct**: `POST /api/{token}/classify`  
+❌ **Incorrect**: Using `Sheep-Token` header
+
+**Implementation Pattern**:
+
+```typescript
+import { checkAccessToken } from "@/security/auth";
+
+export async function POST({ params }: { params: { token: string } }) {
+  // First action: validate token
+  checkAccessToken(params.token);
+  
+  // Continue with route logic...
+}
+```
+
+**Error Responses**:
+- `401 Unauthorized` - Token is missing, invalid, or not authorized
+
+**Public Endpoints** (no token required):
+- `GET /api/health`
+- `GET /api/openapi`
+- `GET /api/categories`
+- `GET /api/scopes`
+
+⚠️ **Enforced by ESLint**: `rest/enforce-token-in-path` ensures proper authentication patterns.
+
+---
+
+## Caching Strategy
+
+### GET Requests
+
+All GET route handlers **must** explicitly set `Cache-Control` headers:
+
+```typescript
+export async function GET(request: Request) {
+  const response = Response.json({ data: [] });
+  response.headers.set('Cache-Control', 'public, max-age=3600');
+  return response;
+}
+```
+
+⚠️ **Enforced by ESLint**: `caching/enforce-semantic-cache-headers` warns if Cache-Control is missing.
+
+### POST Requests
+
+**Never** use `"use cache"` directive in POST handlers. Use `unstable_cache` instead:
+
+```typescript
+// ❌ INCORRECT
+"use cache";
+
+export async function POST(request) {
+  // This won't work!
+}
+```
+
+```typescript
+// ✅ CORRECT
+import { unstable_cache } from 'next/cache';
+
+export async function POST(request) {
+  const cached = await unstable_cache(
+    async () => { /* ... */ },
+    ['cache-key']
+  )();
+}
+```
+
+⚠️ **Enforced by ESLint**: `caching/no-use-cache-in-post` prevents incorrect cache usage.
+
+---
+
+## Input Validation & Security
+
+### Suspicious Pattern Detection
+
+Always validate input for malicious patterns:
+
+```typescript
+import { detectSuspiciousPatterns } from "@schafevormfenster/rest-commons";
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  
+  // Detect suspicious patterns
+  if (detectSuspiciousPatterns(body.userInput)) {
+    return Response.json(
+      { status: 400, error: "Invalid input detected" },
+      { status: 400 }
+    );
+  }
+}
+```
+
+### Parameter Validation
+
+Use helper functions for common validation:
+
+```typescript
+import { validateRequiredParams } from "@schafevormfenster/rest-commons";
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const id = searchParams.get('id');
+  
+  if (!validateRequiredParams({ id })) {
+    return Response.json(
+      { status: 400, error: "Missing required parameter: id" },
+      { status: 400 }
+    );
+  }
+}
+```
+
+### External API Length Limitations
+
+When integrating with external APIs, implement validation and truncation directly in the client function:
+
+```typescript
+export const apiClientFunction = async (
+  query: QueryType
+): Promise<ResponseType> => {
+  // Truncate fields to respect external API's character limits
+  const processedQuery = {
+    ...query,
+    description:
+      query.description && query.description.length > 2000
+        ? query.description.substring(0, 2000)
+        : query.description,
+  };
+
+  // Log truncation events for monitoring
+  if (query.description && query.description.length > 2000) {
+    log.info(
+      {
+        originalLength: query.description.length,
+        truncatedLength: 2000,
+      },
+      "Description truncated for external API due to length constraint"
+    );
+  }
+
+  return await makeApiCall(processedQuery);
+};
+```
+
+---
+
+## Error Handling
+
+### Centralized Error Processing
+
+Use Zod error handlers for validation errors:
+
+```typescript
+import { ZodError } from "zod";
+import { ErrorSchema } from "@schafevormfenster/rest-commons";
+
+try {
+  const validated = MySchema.parse(data);
+} catch (error) {
+  if (error instanceof ZodError) {
+    return Response.json(
+      {
+        status: 400,
+        timestamp: new Date().toISOString(),
+        error: `Validation error: ${error.errors.map(e => e.message).join("; ")}`,
+      },
+      { status: 400 }
+    );
+  }
+}
+```
+
+### HTTP Status Code Patterns
+
+Use semantic HTTP status codes:
+
+- **200 OK**: Successful request with data
+- **201 Created**: Resource successfully created
+- **202 Accepted**: Request accepted for processing (async)
+- **400 Bad Request**: Client error (validation, malformed input)
+- **401 Unauthorized**: Authentication required or failed
+- **403 Forbidden**: Authenticated but not authorized
+- **404 Not Found**: Resource not found
+- **409 Conflict**: Resource already exists or conflict
+- **500 Internal Server Error**: Server-side error
+
+### Correlation IDs
+
+Include correlation IDs in all responses for request tracing:
+
+```typescript
+import { getCorrelationId } from "@schafevormfenster/rest-commons";
+
+export async function GET(request: Request) {
+  const correlationId = getCorrelationId(request);
+  
+  const response = Response.json({ data: [] });
+  response.headers.set('X-Correlation-Id', correlationId);
+  return response;
+}
+```
+
+---
+
+## API Design Patterns
+
+### Unified GET/POST Endpoints
+
+Support identical request schemas for both GET and POST methods:
+
+**GET Request** (simple parameters):
+```bash
+GET /api/{token}/classify?tags=museum,kultur
+```
+
+**POST Request** (rich context):
+```bash
+POST /api/{token}/classify
+{
+  "tags": ["museum", "kultur"],
+  "summary": "Annual city museum concert",
+  "description": "Classical music performance"
+}
+```
+
+**Implementation**:
+
+```typescript
+// Flexible schema accepts both string and array formats
+const TagsFieldSchema = z
+  .union([
+    z.string().transform((str) =>
+      str.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
+    ),
+    z.array(z.string()),
+  ])
+  .optional()
+  .default([]);
+```
+
+**When to Use GET vs POST**:
+- **GET**: Simple queries, caching, bookmarkable URLs
+- **POST**: Rich context, large payloads, sensitive data
+
+### Static-First Processing
+
+Optimize performance by checking static mappings before calling AI services:
+
+1. **Static Matching**: Check against predefined dictionary
+2. **AI Fallback**: Use AI only when no static match exists
+
+**Benefits**:
+- Fast response (no external API calls)
+- Cost reduction (fewer AI API calls)
+- Deterministic results (consistent outcomes)
+
+**Example**:
+```typescript
+// 1. Try static matching first
+const staticResult = staticMappingService.lookup(query);
+
+if (staticResult) {
+  log.info({ query }, "Static match found");
+  return staticResult;
+}
+
+// 2. Fall back to AI service
+log.info({ query }, "No static match, using AI");
+return await aiService.classify(query);
+```
+
+---
+
+## Testing Guidelines
+
+### E2E Testing with Playwright
+
+E2E tests use Playwright's request context to test HTTP endpoints directly.
+
+#### Environment Configuration
+
+**Use ONLY `APITEST_*` environment variables**:
+
+```typescript
+// ✅ Correct - Use APITEST_* env vars directly
+const baseURL = process.env.APITEST_BASE_URL;
+const readToken = process.env.APITEST_READ_ACCESS_TOKEN;
+
+// ❌ Wrong - Don't use production tokens
+const readToken = process.env.READ_ACCESS_TOKENS?.split(",")[0];
+```
+
+⚠️ **Enforced by ESLint**: `testing/enforce-apitest-env-vars` prevents incorrect environment variable usage.
+
+#### Required Environment Variables
+
+Create `.env.local` for development:
+
+```bash
+APITEST_BASE_URL=http://localhost:8000
+APITEST_READ_ACCESS_TOKEN=test-read-token
+APITEST_WRITE_ACCESS_TOKEN=test-write-token
+APITEST_ADMIN_ACCESS_TOKEN=test-admin-token
+```
+
+#### Test Commands
+
+```bash
+# Local development
+pnpm e2e
+
+# Production environment
+pnpm e2e:prod
+
+# CI environment
+pnpm e2e:ci
+```
+
+#### Test Organization
+
+```text
+e2e/
+├── health.spec.ts              # Health endpoint tests
+├── auth-access-tokens.spec.ts  # Authentication tests
+├── categories.spec.ts          # Categories API tests
+└── datasets/                   # Large dataset tests (tagged @datasets)
+    └── sample-dataset.spec.ts
+```
+
+#### Error Message Matching
+
+Use **loose regex matching** for error messages:
+
+```typescript
+// ✅ CORRECT - Loose comparison with regex
+test("should return validation error", async ({ request }) => {
+  const response = await request.post("/api/events", {
+    data: { invalid: "data" },
+  });
+
+  const body = await response.json();
+  expect(body.error).toMatch(/validation\s+error/i);
+});
+
+// ❌ WRONG - Exact string matching (brittle)
+test("should return validation error", async ({ request }) => {
+  const response = await request.post("/api/events", {
+    data: { invalid: "data" },
+  });
+
+  const body = await response.json();
+  expect(body.error).toContain("Validation Error"); // Breaks if case changes
+});
+```
+
+⚠️ **Enforced by ESLint**: `testing/prefer-loose-error-matching` encourages flexible error matching.
+
+#### Test File Naming
+
+```typescript
+// ✅ CORRECT - Playwright tests use .spec.ts
+// e2e/health.spec.ts
+
+test("should return health status", async ({ request }) => {
+  const response = await request.get("/api/health");
+  expect(response.status()).toBe(200);
+});
+```
+
+⚠️ **Enforced by ESLint**: `testing/enforce-test-file-naming` ensures proper naming conventions.
+
+### Unit Testing
+
+Unit tests use Vitest and should focus on business logic:
+
+```typescript
+// ✅ CORRECT - Vitest tests use .test.ts
+// src/helpers/slugify.test.ts
+
+import { describe, it, expect } from "vitest";
+import { slugify } from "./slugify";
+
+describe("slugify", () => {
+  it("should convert text to slug", () => {
+    expect(slugify("Hello World")).toBe("hello-world");
+  });
+});
+```
+
+---
+
+## ESLint Rules for REST APIs
+
+This section details the most important ESLint rules for REST API development. These rules are automatically enforced when you use `@schafevormfenster/eslint-config`.
+
+### Critical Rules
+
+These rules are **enabled as errors** and will break your build if violated:
+
+#### 1. `rest/enforce-api-route-structure`
+
+**Purpose**: Ensures every API route has required files (contract, schema, tests).
+
+**What it checks**:
+- Every `route.ts` must have a co-located `route.test.ts`
+- Every route directory must have a `*.contract.ts` file
+- Every route directory must have a `*.schema.ts` file
+
+**Example**:
+```text
+✅ Correct structure:
+app/api/[token]/classify/
+├── route.ts
+├── route.test.ts
+├── classify.contract.ts
+└── classify.schema.ts
+
+❌ Incorrect structure:
+app/api/classify/
+└── route.ts  # Missing required files!
+```
+
+**Why it matters**: Enforces contract-first development and ensures comprehensive test coverage.
+
+#### 2. `rest/enforce-schema-type-export`
+
+**Purpose**: Every Zod schema must have a TypeScript type export.
+
+**What it checks**:
+- All exported Zod schemas in `*.schema.ts` files
+- Ensures `z.infer<typeof Schema>` type is exported
+
+**Example**:
+```typescript
+// ✅ Correct
+export const UserSchema = z.object({ id: z.string() });
+export type User = z.infer<typeof UserSchema>;
+
+// ❌ Incorrect
+export const UserSchema = z.object({ id: z.string() });
+```
+
+**Why it matters**: Maintains type safety and ensures consistent type usage across the codebase.
+
+#### 3. `rest/enforce-token-in-path`
+
+**Purpose**: Enforces token-based authentication in API routes.
+
+**What it checks**:
+- Routes include `[token]` in path OR validate `params.token` using `checkAccessToken()`
+- Public routes (health, openapi, etc.) are automatically excluded
+
+**Example**:
+```typescript
+// ✅ Correct
+export async function GET({ params }: { params: { token: string } }) {
+  checkAccessToken(params.token);
+  // ...
+}
+
+// ❌ Incorrect
+export async function GET(request: Request) {
+  // No token validation!
+}
+```
+
+**Why it matters**: Ensures proper authentication on all protected endpoints.
+
+#### 4. `caching/no-use-cache-in-post`
+
+**Purpose**: Prevents incorrect cache directive usage in POST handlers.
+
+**What it checks**:
+- No `"use cache"` directive in POST request handlers
+
+**Example**:
+```typescript
+// ✅ Correct
+import { unstable_cache } from 'next/cache';
+export async function POST(request) {
+  const cached = await unstable_cache(async () => {...}, ['key'])();
+}
+
+// ❌ Incorrect
+"use cache";
+export async function POST(request) { ... }
+```
+
+**Why it matters**: `"use cache"` doesn't work with POST requests; prevents subtle bugs.
+
+### Important Rules
+
+These rules are **enabled as warnings** and should be addressed:
+
+#### 5. `rest/prefer-schema-extension`
+
+**Purpose**: Encourages reusing standard response schemas instead of defining from scratch.
+
+**What it checks**:
+- Warns when defining schemas with common keys (status, timestamp, data) from scratch
+- Suggests using `.extend()` or `.merge()` with standard schemas
+
+**Example**:
+```typescript
+// ✅ Preferred
+import { ResultSchema } from "@schafevormfenster/rest-commons";
+export const MyResponseSchema = ResultSchema.extend({
+  data: MyDataSchema,
+});
+
+// ⚠️ Warning
+export const MyResponseSchema = z.object({
+  status: z.number(),
+  timestamp: z.string(),
+  data: MyDataSchema,
+});
+```
+
+**Why it matters**: Maintains consistent response structures across the API.
+
+#### 6. `caching/enforce-semantic-cache-headers`
+
+**Purpose**: Ensures proper cache control headers in GET requests.
+
+**What it checks**:
+- All GET route handlers set `Cache-Control` header
+
+**Example**:
+```typescript
+// ✅ Correct
+export async function GET(request) {
+  const response = Response.json({ data: [] });
+  response.headers.set('Cache-Control', 'public, max-age=3600');
+  return response;
+}
+
+// ⚠️ Warning
+export async function GET(request) {
+  return Response.json({ data: [] }); // Missing Cache-Control
+}
+```
+
+**Why it matters**: Proper caching improves performance and prevents unintended caching issues.
+
+### Best Practice Rules
+
+These rules help maintain code quality:
+
+#### 7. `testing/enforce-apitest-env-vars`
+
+**Purpose**: Ensures E2E tests use isolated test environment variables.
+
+**What it checks**:
+- E2E tests only access `APITEST_*` environment variables
+- Prevents accidental use of production tokens
+
+**Example**:
+```typescript
+// ✅ Correct
+const baseURL = process.env.APITEST_BASE_URL;
+
+// ❌ Incorrect
+const baseURL = process.env.BASE_URL || "http://localhost:8000";
+```
+
+**Why it matters**: Prevents accidentally running tests against production.
+
+#### 8. `testing/prefer-loose-error-matching`
+
+**Purpose**: Encourages flexible error message matching in tests.
+
+**What it checks**:
+- Warns about exact string matching for error messages
+- Suggests regex-based matching
+
+**Example**:
+```typescript
+// ✅ Correct
+expect(body.error).toMatch(/validation\s+error/i);
+
+// ⚠️ Warning
+expect(body.error).toContain("Validation Error");
+```
+
+**Why it matters**: Tests remain stable when error messages are improved.
+
+#### 9. `testing/enforce-test-file-naming`
+
+**Purpose**: Enforces correct test file naming conventions.
+
+**What it checks**:
+- Playwright tests use `*.spec.ts`
+- Vitest tests use `*.test.ts`
+
+**Example**:
+```text
+✅ Correct:
+e2e/health.spec.ts      # Playwright
+src/helpers/slugify.test.ts  # Vitest
+
+❌ Incorrect:
+e2e/health.test.ts      # Should be .spec.ts
+src/helpers/slugify.spec.ts  # Should be .test.ts
+```
+
+**Why it matters**: Maintains consistent naming conventions and helps test runners find tests.
+
+#### 10. `stack/no-forbidden-imports`
+
+**Purpose**: Prevents usage of forbidden libraries with preferred alternatives.
+
+**What it checks**:
+- Forbids `axios` (use Fetch API)
+- Forbids `moment` (use date-fns)
+- Forbids `jest` (use Vitest)
+
+**Example**:
+```typescript
+// ✅ Correct
+const response = await fetch(url);
+
+// ❌ Incorrect
+import axios from 'axios';
+const response = await axios.get(url);
+```
+
+**Why it matters**: Enforces consistent tech stack choices across the monorepo.
+
+### Enabling ESLint Rules
+
+In your `eslint.config.mjs`:
+
+```javascript
+import svfNext from "@schafevormfenster/eslint-config/next";
+import svfRest from "@schafevormfenster/eslint-config/rest";
+import svfCaching from "@schafevormfenster/eslint-config/caching";
+import svfPlaywright from "@schafevormfenster/eslint-config/playwright";
+
+export default [
+  ...svfNext,      // Base Next.js rules
+  ...svfRest,      // REST API rules (includes critical rules)
+  ...svfCaching,   // Caching rules
+  ...svfPlaywright, // E2E testing rules (only for e2e/ directory)
+];
+```
+
+---
+
+## Development Workflow
+
+### 1. Create API Endpoint Structure
+
+```bash
+# Create route directory
+mkdir -p app/api/[token]/my-endpoint
+
+# Create required files
+touch app/api/[token]/my-endpoint/route.ts
+touch app/api/[token]/my-endpoint/route.test.ts
+touch app/api/[token]/my-endpoint/my-endpoint.contract.ts
+touch app/api/[token]/my-endpoint/my-endpoint.schema.ts
+```
+
+### 2. Define Zod Schemas
+
+```typescript
+// my-endpoint.schema.ts
+import { z } from "zod";
+import { ResultSchema } from "@schafevormfenster/rest-commons";
+
+export const MyRequestSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+export type MyRequest = z.infer<typeof MyRequestSchema>;
+
+export const MyDataSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: z.string(),
+});
+
+export type MyData = z.infer<typeof MyDataSchema>;
+
+export const MyResponseSchema = ResultSchema.extend({
+  data: MyDataSchema,
+});
+
+export type MyResponse = z.infer<typeof MyResponseSchema>;
+```
+
+### 3. Define API Contract
+
+```typescript
+// my-endpoint.contract.ts
+import { initContract } from "@ts-rest/core";
+import { MyRequestSchema, MyResponseSchema } from "./my-endpoint.schema";
+
+const c = initContract();
+
+export const myEndpointContract = c.router({
+  get: {
+    method: "GET",
+    path: "/api/:token/my-endpoint/:id",
+    responses: {
+      200: MyResponseSchema,
+      400: ErrorSchema,
+      401: ErrorSchema,
+    },
+  },
+  post: {
+    method: "POST",
+    path: "/api/:token/my-endpoint",
+    body: MyRequestSchema,
+    responses: {
+      201: MyResponseSchema,
+      400: ErrorSchema,
+      401: ErrorSchema,
+    },
+  },
+});
+```
+
+### 4. Implement Route Handler
+
+```typescript
+// route.ts
+import { checkAccessToken } from "@/security/auth";
+import { getCorrelationId } from "@schafevormfenster/rest-commons";
+import { MyRequestSchema } from "./my-endpoint.schema";
+
+export async function GET({
+  params,
+}: {
+  params: { token: string; id: string };
+}) {
+  checkAccessToken(params.token);
+  
+  const correlationId = getCorrelationId();
+  
+  // Business logic here
+  const data = await fetchData(params.id);
+  
+  const response = Response.json({
+    status: 200,
+    timestamp: new Date().toISOString(),
+    data,
+  });
+  
+  response.headers.set('X-Correlation-Id', correlationId);
+  response.headers.set('Cache-Control', 'public, max-age=3600');
+  
+  return response;
+}
+
+export async function POST({
+  params,
+  request,
+}: {
+  params: { token: string };
+  request: Request;
+}) {
+  checkAccessToken(params.token);
+  
+  const body = await request.json();
+  const validated = MyRequestSchema.parse(body);
+  
+  // Business logic here
+  const data = await createData(validated);
+  
+  return Response.json(
+    {
+      status: 201,
+      timestamp: new Date().toISOString(),
+      data,
+    },
+    { status: 201 }
+  );
+}
+```
+
+### 5. Write Tests
+
+```typescript
+// route.test.ts
+import { test, expect } from "@playwright/test";
+
+const READ_TOKEN = process.env.APITEST_READ_ACCESS_TOKEN;
+const WRITE_TOKEN = process.env.APITEST_WRITE_ACCESS_TOKEN;
+
+test.describe("My Endpoint API", () => {
+  test("GET requires authentication", async ({ request }) => {
+    const response = await request.get("/api/invalid-token/my-endpoint/123");
+    expect(response.status()).toBe(401);
+  });
+
+  test("GET returns data with valid token", async ({ request }) => {
+    const response = await request.get(
+      `/api/${READ_TOKEN}/my-endpoint/123`
+    );
+    
+    expect(response.status()).toBe(200);
+    
+    const body = await response.json();
+    expect(body).toHaveProperty("status", 200);
+    expect(body).toHaveProperty("timestamp");
+    expect(body).toHaveProperty("data");
+  });
+
+  test("POST creates resource", async ({ request }) => {
+    const response = await request.post(`/api/${WRITE_TOKEN}/my-endpoint`, {
+      data: {
+        id: "123",
+        name: "Test",
+      },
+    });
+    
+    expect(response.status()).toBe(201);
+  });
+
+  test("POST validates input", async ({ request }) => {
+    const response = await request.post(`/api/${WRITE_TOKEN}/my-endpoint`, {
+      data: { invalid: "data" },
+    });
+    
+    expect(response.status()).toBe(400);
+    
+    const body = await response.json();
+    expect(body.error).toMatch(/validation/i);
+  });
+});
+```
+
+### 6. Run Linter and Tests
+
+```bash
+# Run ESLint
+pnpm lint
+
+# Run unit tests
+pnpm test
+
+# Run E2E tests
+pnpm e2e
+```
+
+### 7. Build and Deploy
+
+```bash
+# Build the package
+pnpm build
+
+# The package is ready to publish
+```
+
+---
+
+## Additional Resources
+
+- **REST Service Design Guide**: See `/packages/eslint-plugin/docs/rest-service-design-guide.md`
+- **E2E Testing Guide**: See `/packages/eslint-plugin/docs/instructions/rest-api-e2e-testing-guide.md`
+- **Tech Stack**: See `/packages/eslint-plugin/docs/instructions/tech-stack.md`
+- **ESLint Plugin**: See `/packages/eslint-plugin/README.md`
+- **ESLint Config**: See `/packages/eslint-config/README.md`
+
+---
+
+## Getting Help
+
+If you have questions or need help:
+
+1. Check the documentation in `/packages/eslint-plugin/docs/`
+2. Review existing implementations in the monorepo
+3. Ask in the team chat or create an issue
+
+---
+
+## License
+
+See the root LICENSE file for license information.