availsync 0.1.0

package/plan.md

@@ -0,0 +1,923 @@
+# PLAN.md — Availsync MVP
+
+## Goal contract (læs dette først)
+
+Du bygger Availsync: en REST API der fungerer som scheduling source-of-truth for AI-agenter.
+Kerneproblemet: flere AI-agenter (salgs-bot, rekrutteringsbot, kalenderagent) booker møder
+uafhængigt og laver double-bookings. Availsync løser det ved at alle agenter tjekker ét
+fælles lag af regler og holds, inden de booker.
+
+**Done-betingelse:**
+`npm test` kører grønt (alle test passes), `npm run build` producerer fejlfri TypeScript-build,
+og `docker compose up` starter systemet lokalt. Alle tre endpoints svarer korrekt på
+de smoke tests beskrevet i `/tests/smoke.sh`.
+
+**Stop hvis:**
+- En migration fejler og kan ikke rettes automatisk — log fejlen og stop
+- En afhængighed ikke kan installeres — prøv alternativ, ellers stop og skriv til BLOCKERS.md
+- Du er i tvivl om forretningslogik — se kommentarer i denne fil, lav ikke antagelser
+
+**Rør ikke:**
+- Denne PLAN.md fil
+- .env.example (kun tilføj, aldrig slet eksisterende variabler)
+- Eventuelle filer brugeren har lagt i /existing/ mappen
+
+---
+
+## Stack
+
+| Lag | Teknologi | Begrundelse |
+|---|---|---|
+| Runtime | Node.js 20 + TypeScript 5 | Async-first, god type-støtte til DB |
+| Web framework | Express.js 4 | Simpelt, veldokumenteret |
+| Database | PostgreSQL 16 via `pg` driver | Row-level locking til konfliktresolution |
+| Validation | Zod | Skema-validation + TypeScript-inferens |
+| Testing | Jest + Supertest | Enkel setup, god Express-integration |
+| Containerisering | Docker + docker-compose | Reproducerbar lokal kørsel |
+| Linting | ESLint + Prettier | Konsistent kode |
+
+**Brug ikke** Prisma, TypeORM, Sequelize eller andre ORMs — brug rå `pg`-queries.
+Det giver fuld kontrol over `SELECT FOR UPDATE SKIP LOCKED` som konfliktmotoren kræver.
+
+---
+
+## Mappestruktur (opret præcis dette)
+
+```
+availsync/
+├── PLAN.md                    ← denne fil
+├── BLOCKERS.md                ← opret som tom fil, log blokeringer her
+├── package.json
+├── tsconfig.json
+├── .env.example
+├── docker-compose.yml
+├── Dockerfile
+├── jest.config.js
+├── src/
+│   ├── index.ts               ← Express app entry point
+│   ├── db/
+│   │   ├── client.ts          ← pg Pool singleton
+│   │   └── migrations/
+│   │       └── 001_init.sql   ← hele databaseskemaet
+│   ├── core/
+│   │   ├── availability.ts    ← getAvailableSlots()
+│   │   └── conflict.ts        ← resolveConflict()
+│   ├── middleware/
+│   │   └── auth.ts            ← Bearer token validering
+│   ├── routes/
+│   │   ├── availability.ts    ← GET /v1/availability
+│   │   ├── holds.ts           ← POST /v1/holds, DELETE /v1/holds/:id
+│   │   ├── preferences.ts     ← GET + PUT /v1/preferences/:agent_id
+│   │   └── orgs.ts            ← POST /v1/orgs, POST /v1/orgs/:id/agents
+│   └── types/
+│       └── index.ts           ← delte TypeScript-typer
+└── tests/
+    ├── unit/
+    │   ├── conflict.test.ts
+    │   └── availability.test.ts
+    ├── integration/
+    │   ├── availability.route.test.ts
+    │   ├── holds.route.test.ts
+    │   └── preferences.route.test.ts
+    └── smoke.sh               ← curl-baserede smoke tests
+```
+
+---
+
+## Checkpoint 1 — Projektopsætning og databaseskema
+
+**Valider med:** `npm run build` producerer ingen fejl. `psql $DATABASE_URL -f src/db/migrations/001_init.sql` kører uden fejl.
+
+### 1.1 — Initialiser projektet
+
+Opret `package.json` med disse præcise scripts:
+```json
+{
+  "name": "availsync",
+  "version": "0.1.0",
+  "scripts": {
+    "build": "tsc --noEmit",
+    "start": "ts-node src/index.ts",
+    "dev": "ts-node-dev --respawn src/index.ts",
+    "test": "jest --runInBand",
+    "migrate": "psql $DATABASE_URL -f src/db/migrations/001_init.sql",
+    "lint": "eslint src --ext .ts"
+  }
+}
+```
+
+Installer disse dependencies (ikke mere):
+```
+npm install express pg zod bcrypt uuid date-fns
+npm install --save-dev typescript ts-node ts-node-dev @types/express @types/pg @types/bcrypt @types/uuid jest @types/jest supertest @types/supertest ts-jest eslint prettier
+```
+
+### 1.2 — TypeScript-konfiguration
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+`jest.config.js`:
+```js
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts'],
+  runInBand: true,
+  setupFiles: ['<rootDir>/tests/setup.ts']
+};
+```
+
+Opret `tests/setup.ts`:
+```typescript
+process.env.DATABASE_URL = process.env.TEST_DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/availsync_test';
+process.env.NODE_ENV = 'test';
+```
+
+### 1.3 — Miljøvariabler
+
+`.env.example`:
+```
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/availsync
+TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/availsync_test
+PORT=3000
+NODE_ENV=development
+API_KEY_SALT_ROUNDS=10
+CORS_ORIGINS=http://localhost:3000
+```
+
+### 1.4 — Databaseskema
+
+`src/db/migrations/001_init.sql` — implementér disse tabeller præcis:
+
+```sql
+-- Aktiver UUID-extension
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- Organisationer (en org kan have mange agenter)
+CREATE TABLE IF NOT EXISTS orgs (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name        TEXT NOT NULL,
+  plan        TEXT NOT NULL DEFAULT 'free' CHECK (plan IN ('free', 'individual', 'team')),
+  agent_limit INTEGER NOT NULL DEFAULT 3,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Agenter (en per AI-tool: sales_bot, recruiting_bot, osv.)
+CREATE TABLE IF NOT EXISTS agents (
+  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id       UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  name         TEXT NOT NULL,
+  api_key_hash TEXT NOT NULL,
+  agent_type   TEXT NOT NULL DEFAULT 'generic'
+                 CHECK (agent_type IN ('external_meeting', 'internal', 'focus', 'generic')),
+  priority     INTEGER NOT NULL DEFAULT 0,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_agents_org_id ON agents(org_id);
+
+-- Ledige tidsvinduet en agent opererer inden for
+CREATE TABLE IF NOT EXISTS availability_windows (
+  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id   UUID NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  start_at   TIMESTAMPTZ NOT NULL,
+  end_at     TIMESTAMPTZ NOT NULL,
+  window_type TEXT NOT NULL DEFAULT 'available'
+                CHECK (window_type IN ('available', 'focus', 'blocked')),
+  recurrence TEXT,   -- null = engangshændelse, 'daily'/'weekly' = gentagen
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT chk_window_order CHECK (end_at > start_at)
+);
+CREATE INDEX IF NOT EXISTS idx_windows_agent_time
+  ON availability_windows(agent_id, start_at, end_at);
+
+-- En agent reserverer et tidsrum (hold) inden commit
+CREATE TABLE IF NOT EXISTS holds (
+  id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id           UUID NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  org_id             UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  start_at           TIMESTAMPTZ NOT NULL,
+  end_at             TIMESTAMPTZ NOT NULL,
+  reason             TEXT,
+  status             TEXT NOT NULL DEFAULT 'confirmed'
+                       CHECK (status IN ('confirmed', 'superseded', 'released')),
+  booked_by_agent_id UUID REFERENCES agents(id),
+  metadata           JSONB,
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT chk_hold_order CHECK (end_at > start_at)
+);
+CREATE INDEX IF NOT EXISTS idx_holds_org_time
+  ON holds(org_id, start_at, end_at) WHERE status = 'confirmed';
+CREATE INDEX IF NOT EXISTS idx_holds_agent_id ON holds(agent_id);
+
+-- Konfliktregler pr. org
+CREATE TABLE IF NOT EXISTS conflict_rules (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id      UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  rule_type   TEXT NOT NULL CHECK (rule_type IN ('priority', 'buffer', 'focus')),
+  config      JSONB NOT NULL DEFAULT '{}',
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Agent-præferencer (buffer, focus-blokke, osv.)
+CREATE TABLE IF NOT EXISTS agent_preferences (
+  agent_id                  UUID PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+  buffer_minutes_after      INTEGER NOT NULL DEFAULT 15,
+  buffer_minutes_before     INTEGER NOT NULL DEFAULT 0,
+  focus_blocks              JSONB NOT NULL DEFAULT '[]',
+  priority_over_agents      JSONB NOT NULL DEFAULT '[]',
+  booking_window_days       INTEGER NOT NULL DEFAULT 30,
+  allow_back_to_back        BOOLEAN NOT NULL DEFAULT false,
+  updated_at                TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Audit log — ét event per hændelse
+CREATE TABLE IF NOT EXISTS hold_events (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  hold_id         UUID NOT NULL REFERENCES holds(id) ON DELETE CASCADE,
+  event_type      TEXT NOT NULL
+                    CHECK (event_type IN ('created', 'superseded', 'released', 'conflict_won', 'conflict_lost')),
+  agent_id        UUID NOT NULL REFERENCES agents(id),
+  org_id          UUID NOT NULL REFERENCES orgs(id),
+  conflicting_hold_id UUID REFERENCES holds(id),
+  rule_applied    TEXT,
+  metadata        JSONB,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_hold_events_org ON hold_events(org_id, created_at DESC);
+```
+
+### 1.5 — Database-klient
+
+`src/db/client.ts`:
+```typescript
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+export default pool;
+```
+
+### 1.6 — Delte typer
+
+`src/types/index.ts` — definer disse interfaces:
+```typescript
+export interface Org {
+  id: string;
+  name: string;
+  plan: 'free' | 'individual' | 'team';
+  agent_limit: number;
+  created_at: Date;
+}
+
+export interface Agent {
+  id: string;
+  org_id: string;
+  name: string;
+  api_key_hash: string;
+  agent_type: 'external_meeting' | 'internal' | 'focus' | 'generic';
+  priority: number;
+  created_at: Date;
+}
+
+export interface Hold {
+  id: string;
+  agent_id: string;
+  org_id: string;
+  start_at: Date;
+  end_at: Date;
+  reason?: string;
+  status: 'confirmed' | 'superseded' | 'released';
+  booked_by_agent_id?: string;
+  metadata?: Record<string, unknown>;
+  created_at: Date;
+}
+
+export interface AvailabilityWindow {
+  id: string;
+  agent_id: string;
+  start_at: Date;
+  end_at: Date;
+  window_type: 'available' | 'focus' | 'blocked';
+  recurrence?: string;
+}
+
+export interface AgentPreferences {
+  agent_id: string;
+  buffer_minutes_after: number;
+  buffer_minutes_before: number;
+  focus_blocks: FocusBlock[];
+  priority_over_agents: string[];
+  booking_window_days: number;
+  allow_back_to_back: boolean;
+}
+
+export interface FocusBlock {
+  weekday: number;  // 0 = søndag, 6 = lørdag
+  start_time: string;  // "HH:MM"
+  end_time: string;    // "HH:MM"
+}
+
+export interface AvailableSlot {
+  start: Date;
+  end: Date;
+  confidence: number;
+  competing_holds_count: number;
+}
+
+export interface RequestWithAgent extends Express.Request {
+  agent: Agent;
+  org: Org;
+}
+```
+
+---
+
+## Checkpoint 2 — Kernelogik
+
+**Valider med:** `npm test -- tests/unit/` kører grønt (alle unit tests passes).
+
+### 2.1 — Auth-middleware
+
+`src/middleware/auth.ts`:
+
+Implementér en Express middleware der:
+1. Læser `Authorization: Bearer <token>` headeren — returnér 401 `{"error": "missing_auth", "message": "Authorization header required"}` hvis den mangler
+2. Slår token op i `agents`-tabellen med `SELECT agents.*, orgs.* FROM agents JOIN orgs ON agents.org_id = orgs.id WHERE agents.api_key_hash = $1` — brug bcrypt.compare(token, row.api_key_hash)
+3. Returnér 401 `{"error": "invalid_key"}` hvis ingen match
+4. Sætter `req.agent` og `req.org` på request-objektet
+5. Kalder `next()`
+
+Eksportér typen `AuthenticatedRequest extends Request` med `agent: Agent` og `org: Org`.
+
+### 2.2 — Konfliktresolution-motor
+
+`src/core/conflict.ts`:
+
+Implementér disse to funktioner:
+
+**`determineWinner(holdA: Hold, agentA: Agent, holdB: Hold, agentB: Agent, prefs: AgentPreferences[]): Hold`**
+
+Prioritetslogik i denne rækkefølge (returnér vinderen):
+1. Eksplicit `priority_over_agents`-liste: hvis agentA har agentB's ID i sin `priority_over_agents`-liste → agentA vinder
+2. `agent_type`-hierarki: `external_meeting` (4) > `internal` (3) > `focus` (2) > `generic` (1)
+3. Eksplicit `priority`-felt på agent: højere vinder
+4. Tie-breaker: ældste `created_at` på hold vinder (first-come-first-served)
+
+**`checkAndResolveConflict(newHold: Omit<Hold, 'id'|'created_at'>, client: PoolClient): Promise<{winner: 'new'|'existing', conflictingHold?: Hold}>`**
+
+Flowet:
+1. Kør `SELECT * FROM holds WHERE org_id = $1 AND status = 'confirmed' AND start_at < $3 AND end_at > $2 FOR UPDATE SKIP LOCKED` — brug $1=org_id, $2=start_at, $3=end_at for at finde overlappende confirmed holds
+2. Hvis ingen overlap → returnér `{winner: 'new'}`
+3. For hvert overlappende hold: hent begge agenter, kald `determineWinner()`
+4. Hvis new hold vinder alle sammenstød → returnér `{winner: 'new', conflictingHold: losingHold}`
+5. Hvis new hold taber ét sammenstød → returnér `{winner: 'existing', conflictingHold: winningHold}`
+
+### 2.3 — Availability-beregning
+
+`src/core/availability.ts`:
+
+**`getAvailableSlots(params: GetSlotsParams, client?: PoolClient): Promise<AvailableSlot[]>`**
+
+```typescript
+interface GetSlotsParams {
+  agent_id: string;
+  org_id: string;
+  from: Date;
+  to: Date;
+  duration_minutes: number;
+  include_competing_agents?: boolean;
+}
+```
+
+Algoritme:
+1. Hent `availability_windows` for agenten hvor `window_type = 'available'` og perioden overlapper `from`–`to`
+2. Hent `agent_preferences` for agenten
+3. Hent alle confirmed holds i org i perioden (hvis `include_competing_agents = true`) eller kun agentens egne holds
+4. For hvert availability-vindue: generer slots med `duration_minutes` skridt (tætpakket, ikke hvert minut)
+5. Filtrer slots der overlapper med:
+   - Existing holds (direkte overlap)
+   - Focus blocks fra preferences (omregn weekday+tidspunkt til konkrete datoer i perioden)
+   - Buffer-tid rundt om eksisterende holds (brug `buffer_minutes_after` og `buffer_minutes_before`)
+6. For hvert tilbageværende slot: tæl `competing_holds_count` (antal holds fra andre agenter tæt på slottet, indenfor 30 min)
+7. Sæt `confidence = 1.0 - (competing_holds_count * 0.15)`, minimum 0.1
+8. Returnér sorteret liste af `AvailableSlot`
+
+### 2.4 — Unit tests
+
+`tests/unit/conflict.test.ts` — skriv tests der dækker:
+- To agenter med ingen priority_over_agents → agent_type-hierarki afgør
+- external_meeting vinder over internal
+- Tie på agent_type → priority-felt afgør
+- Komplet tie → ældste hold vinder (first-come-first-served)
+- Eksplicit priority_over_agents-liste tilsidesætter alt andet
+
+`tests/unit/availability.test.ts` — skriv tests der dækker:
+- Slot inden for vindue returneres
+- Slot overlappende med hold filtreres
+- Buffer-tid fjerner slots tæt på hold
+- Focus-blok fjerner slots der overlapper
+- confidence beregnes korrekt ved competing holds
+- Tom liste returneres hvis ingen ledige slots
+
+---
+
+## Checkpoint 3 — REST API endpoints
+
+**Valider med:** `npm test -- tests/integration/` kører grønt.
+
+For alle endpoints gælder:
+- Content-Type: application/json på alle responses
+- Fejl returneres altid som `{"error": "<machine_readable_code>", "message": "<human_readable>", "details"?: {...}}`
+- Alle timestamps i ISO 8601 / UTC
+- Auth-middleware skal køre på alle endpoints undtagen `POST /v1/orgs` og `GET /health`
+
+### 3.1 — Health check og app entry point
+
+`src/index.ts`:
+```typescript
+import express from 'express';
+import availabilityRouter from './routes/availability';
+import holdsRouter from './routes/holds';
+import preferencesRouter from './routes/preferences';
+import orgsRouter from './routes/orgs';
+
+const app = express();
+app.use(express.json());
+
+app.get('/health', async (req, res) => {
+  try {
+    await pool.query('SELECT 1');
+    res.json({ status: 'ok', db: 'connected', timestamp: new Date().toISOString() });
+  } catch {
+    res.status(503).json({ status: 'error', db: 'disconnected' });
+  }
+});
+
+app.use('/v1', orgsRouter);
+app.use('/v1', availabilityRouter);
+app.use('/v1', holdsRouter);
+app.use('/v1', preferencesRouter);
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => console.log(`Availsync running on :${PORT}`));
+
+export default app;
+```
+
+### 3.2 — Org og agent provisioning
+
+`src/routes/orgs.ts` — implementér:
+
+**`POST /v1/orgs`** (ingen auth krævet)
+- Body (Zod-valideret): `{ name: string }`
+- Opret org med `plan = 'free'` og `agent_limit = 3`
+- Returnér 201: `{ org: Org }`
+
+**`POST /v1/orgs/:org_id/agents`** (ingen auth krævet til MVP)
+- Body (Zod-valideret): `{ name: string, agent_type?: AgentType, priority?: number }`
+- Check at org ikke overskrider `agent_limit` — returnér 402 `{"error": "agent_limit_reached"}` hvis den gør
+- Generer API-nøgle: `crypto.randomBytes(32).toString('hex')`
+- Hash nøglen: `bcrypt.hash(apiKey, parseInt(process.env.API_KEY_SALT_ROUNDS || '10'))`
+- Gem agent med hash
+- Opret `agent_preferences`-række med defaults
+- Returnér 201: `{ agent: Agent, api_key: string }` — vis `api_key` kun i dette svar
+
+**`GET /v1/orgs/:org_id/agents`** (ingen auth krævet til MVP)
+- Returnér alle agenter i org (uden api_key_hash)
+
+### 3.3 — Availability-endpoint
+
+`src/routes/availability.ts` — implementér:
+
+**`GET /v1/availability`** (auth krævet)
+
+Query params — valider med Zod:
+```
+agent_id: string (UUID)
+from: string (ISO8601, skal være fremtidig)
+to: string (ISO8601, skal være efter from)
+duration_minutes: number (1–480)
+include_competing_agents?: boolean (default: false)
+```
+
+Flow:
+1. Valider at `req.agent.id === agent_id` ELLER `req.agent.org_id === org_id_for_agent` — en agent må kun se sin egen org's availability
+2. Kald `getAvailableSlots(params)`
+3. Returnér 200:
+```json
+{
+  "slots": [
+    { "start": "ISO8601", "end": "ISO8601", "confidence": 0.85, "competing_holds_count": 1 }
+  ],
+  "rules_applied": ["buffer_15min", "focus_block_mornings"],
+  "generated_at": "ISO8601",
+  "total_slots": 12
+}
+```
+
+Fejlcases:
+- Manglende params → 400 med Zod-fejldetaljer
+- `to` mere end `booking_window_days` ude i fremtiden → 400 `{"error": "outside_booking_window"}`
+- `from` i fortiden → 400 `{"error": "past_datetime"}`
+
+### 3.4 — Holds-endpoints
+
+`src/routes/holds.ts` — implementér:
+
+**`POST /v1/holds`** (auth krævet)
+
+Body (Zod-valideret):
+```
+agent_id: string (UUID)
+start_at: string (ISO8601)
+end_at: string (ISO8601)
+reason?: string (max 500 chars)
+metadata?: object
+```
+
+Flow — ALT SKAL SKE I ÉN POSTGRESQL-TRANSAKTION:
+1. Valider agent tilhører req.org
+2. Check at start_at/end_at falder inden for et availability_window for agenten
+3. Kald `checkAndResolveConflict()`
+4. **Hvis winner = 'new':**
+   - Indsæt hold med `status = 'confirmed'`
+   - Opret `hold_events` event: `type = 'created'`
+   - Hvis der var et superseded hold: opdatér det til `status = 'superseded'`, opret event `type = 'superseded'`
+   - COMMIT
+   - Returnér 201: `{ hold: Hold, conflict_resolved: boolean, superseded_hold_id?: string }`
+5. **Hvis winner = 'existing':**
+   - ROLLBACK
+   - Hent 3 alternative slots via `getAvailableSlots()`
+   - Returnér 409:
+   ```json
+   {
+     "error": "slot_taken",
+     "message": "Another agent has priority for this time slot",
+     "winning_hold_id": "uuid",
+     "suggested_alternatives": [ { "start": "...", "end": "...", "confidence": 0.9 } ]
+   }
+   ```
+
+**`DELETE /v1/holds/:hold_id`** (auth krævet)
+- Valider at hold tilhører req.agent
+- Opdatér `status = 'released'`
+- Opret `hold_events` event: `type = 'released'`
+- Returnér 200: `{ hold: Hold }`
+
+**`GET /v1/holds`** (auth krævet)
+- Query params: `agent_id?`, `from?`, `to?`, `status?` (default: 'confirmed')
+- Returnér holds filtreret af params, sorteret by start_at ASC
+- Kun holds inden for req.org
+
+### 3.5 — Preferences-endpoints
+
+`src/routes/preferences.ts` — implementér:
+
+**`GET /v1/preferences/:agent_id`** (auth krævet)
+- Valider agent tilhører req.org
+- Hent fra `agent_preferences`
+- Returnér 200: `{ preferences: AgentPreferences }`
+
+**`PUT /v1/preferences/:agent_id`** (auth krævet)
+
+Body — validér med Zod præcis:
+```typescript
+const PreferencesSchema = z.object({
+  buffer_minutes_after: z.number().int().min(0).max(120).optional(),
+  buffer_minutes_before: z.number().int().min(0).max(120).optional(),
+  focus_blocks: z.array(z.object({
+    weekday: z.number().int().min(0).max(6),
+    start_time: z.string().regex(/^\d{2}:\d{2}$/),
+    end_time: z.string().regex(/^\d{2}:\d{2}$/)
+  })).max(20).optional(),
+  priority_over_agents: z.array(z.string().uuid()).max(50).optional(),
+  booking_window_days: z.number().int().min(1).max(365).optional(),
+  allow_back_to_back: z.boolean().optional()
+});
+```
+
+- UPSERT til `agent_preferences` (kun opdatér felter der er tilsendt)
+- Returnér 200: `{ preferences: AgentPreferences }`
+- Returnér 422 med Zod-fejldetaljer ved ugyldige felter
+
+### 3.6 — Availability windows-endpoint
+
+`src/routes/availability.ts` — tilføj:
+
+**`POST /v1/availability-windows`** (auth krævet)
+
+Body:
+```
+agent_id: string (UUID)
+start_at: string (ISO8601)
+end_at: string (ISO8601)
+window_type: 'available' | 'focus' | 'blocked'
+recurrence?: 'daily' | 'weekly'
+```
+
+- Indsæt i `availability_windows`
+- Returnér 201: `{ window: AvailabilityWindow }`
+
+**`GET /v1/availability-windows`** (auth krævet)
+- Query params: `agent_id`, `from?`, `to?`
+- Returnér windows for agenten
+
+### 3.7 — Integration tests
+
+`tests/integration/availability.route.test.ts`:
+- Opret test-org og test-agent i beforeAll
+- Test: GET /v1/availability med gyldige params returnerer slots
+- Test: GET /v1/availability uden auth returnerer 401
+- Test: GET /v1/availability med ugyldig agent_id returnerer 403
+- Test: GET /v1/availability med `from` i fortiden returnerer 400
+
+`tests/integration/holds.route.test.ts`:
+- Test: POST /v1/holds booker succesfuldt og returnerer 201
+- Test: POST /v1/holds med overlappende hold fra lavere-prioritet agent: returnerer 201 med conflict_resolved=true
+- Test: POST /v1/holds med overlappende hold fra højere-prioritet agent: returnerer 409 med suggested_alternatives
+- Test: DELETE /v1/holds/:id frigiver holdet korrekt
+- Test: Concurrent booking — kør 10 simultane POST /v1/holds til samme slot, verificér at præcis 1 lykkes
+
+`tests/integration/preferences.route.test.ts`:
+- Test: GET /v1/preferences returnerer defaults
+- Test: PUT /v1/preferences opdaterer buffer_minutes_after
+- Test: PUT /v1/preferences med ugyldig weekday returnerer 422
+
+---
+
+## Checkpoint 4 — Docker og smoke tests
+
+**Valider med:** `docker compose up -d` starter uden fejl, `bash tests/smoke.sh` printer kun OK-linjer.
+
+### 4.1 — Dockerfile
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/tsconfig.json ./
+USER nodejs
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["node", "-r", "ts-node/register", "src/index.ts"]
+```
+
+### 4.2 — docker-compose.yml
+
+```yaml
+version: '3.9'
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@db:5432/availsync
+      PORT: 3000
+      NODE_ENV: production
+      API_KEY_SALT_ROUNDS: 10
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: availsync
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./src/db/migrations/001_init.sql:/docker-entrypoint-initdb.d/001_init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    ports:
+      - "5432:5432"
+
+volumes:
+  postgres_data:
+```
+
+### 4.3 — Smoke tests
+
+`tests/smoke.sh` — en serie curl-kald der verificerer hele API'et end-to-end:
+
+```bash
+#!/bin/bash
+set -e
+BASE="http://localhost:3000"
+ERRORS=0
+
+check() {
+  local desc=$1
+  local expected=$2
+  local actual=$3
+  if [ "$actual" = "$expected" ]; then
+    echo "OK: $desc"
+  else
+    echo "FAIL: $desc (expected $expected, got $actual)"
+    ERRORS=$((ERRORS + 1))
+  fi
+}
+
+echo "=== Availsync Smoke Tests ==="
+
+# Health check
+STATUS=$(curl -s -o /dev/null -w "%{http_code}" $BASE/health)
+check "Health endpoint" "200" "$STATUS"
+
+# Opret org
+ORG_RESPONSE=$(curl -s -X POST $BASE/v1/orgs \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Test Org"}')
+ORG_ID=$(echo $ORG_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Create org returns id" "true" "$([ -n "$ORG_ID" ] && echo true || echo false)"
+
+# Opret agent
+AGENT_RESPONSE=$(curl -s -X POST $BASE/v1/orgs/$ORG_ID/agents \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Sales Bot", "agent_type": "external_meeting"}')
+API_KEY=$(echo $AGENT_RESPONSE | grep -o '"api_key":"[^"]*"' | cut -d'"' -f4)
+AGENT_ID=$(echo $AGENT_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Create agent returns api_key" "true" "$([ -n "$API_KEY" ] && echo true || echo false)"
+
+# Opret availability window (næste uge, man-fre 9-17)
+TOMORROW=$(date -d "+1 day" +%Y-%m-%dT09:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT09:00:00Z)
+TOMORROW_END=$(date -d "+1 day" +%Y-%m-%dT17:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT17:00:00Z)
+WIN_STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST $BASE/v1/availability-windows \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"agent_id\":\"$AGENT_ID\",\"start_at\":\"$TOMORROW\",\"end_at\":\"$TOMORROW_END\",\"window_type\":\"available\"}")
+check "Create availability window" "201" "$WIN_STATUS"
+
+# Hent availability
+AVAIL_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  "$BASE/v1/availability?agent_id=$AGENT_ID&from=$TOMORROW&to=$TOMORROW_END&duration_minutes=30" \
+  -H "Authorization: Bearer $API_KEY")
+check "Get availability" "200" "$AVAIL_STATUS"
+
+# Book hold
+HOLD_RESPONSE=$(curl -s -X POST $BASE/v1/holds \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"agent_id\":\"$AGENT_ID\",\"start_at\":\"$TOMORROW\",\"end_at\":\"$(date -d "+1 day" +%Y-%m-%dT10:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT10:00:00Z)\",\"reason\":\"Test booking\"}")
+HOLD_STATUS=$(echo $HOLD_RESPONSE | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Book hold returns confirmed status" "confirmed" "$HOLD_STATUS"
+
+# Test auth fejl
+UNAUTH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $BASE/v1/availability?agent_id=$AGENT_ID)
+check "Unauthenticated request returns 401" "401" "$UNAUTH_STATUS"
+
+echo ""
+echo "=== Results: $ERRORS failure(s) ==="
+exit $ERRORS
+```
+
+---
+
+## Checkpoint 5 — MCP-server (bonus, byg kun hvis alle tests er grønne)
+
+**Valider med:** `node src/mcp/server.js --help` kører uden fejl.
+
+Kun hvis checkpoints 1–4 er bestået: Byg en minimal MCP-server i `src/mcp/server.ts`
+med `@modelcontextprotocol/sdk`. Installér: `npm install @modelcontextprotocol/sdk`
+
+Eksponér præcis tre tools:
+
+**`check_availability`**
+```typescript
+{
+  name: "check_availability",
+  description: "Check available time slots for an AI scheduling agent before booking. Always call this before book_slot.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      agent_id: { type: "string", description: "UUID of the agent to check availability for" },
+      from: { type: "string", description: "Start of search window (ISO 8601 UTC)" },
+      to: { type: "string", description: "End of search window (ISO 8601 UTC)" },
+      duration_minutes: { type: "number", description: "Required meeting duration in minutes" }
+    },
+    required: ["agent_id", "from", "to", "duration_minutes"]
+  }
+}
+```
+
+**`book_slot`**
+```typescript
+{
+  name: "book_slot",
+  description: "Reserve a time slot. Returns confirmed hold or 409 with alternative suggestions if slot is taken by higher-priority agent.",
+  inputSchema: { /* agent_id, start_at, end_at, reason */ }
+}
+```
+
+**`release_slot`**
+```typescript
+{
+  name: "release_slot",
+  description: "Release a previously booked hold so other agents can use the time.",
+  inputSchema: { /* hold_id */ }
+}
+```
+
+Server læser `AVAILSYNC_API_URL` og `AVAILSYNC_API_KEY` fra environment.
+Start på stdio transport: `new StdioServerTransport()`.
+
+Tilføj til `package.json`:
+```json
+"mcp": "ts-node src/mcp/server.ts"
+```
+
+Opret `MCP_SETUP.md` med:
+```markdown
+# Tilslut Availsync til Claude Desktop
+
+Tilføj til ~/Library/Application Support/Claude/claude_desktop_config.json:
+
+{
+  "mcpServers": {
+    "availsync": {
+      "command": "npx",
+      "args": ["ts-node", "/path/to/availsync/src/mcp/server.ts"],
+      "env": {
+        "AVAILSYNC_API_URL": "http://localhost:3000",
+        "AVAILSYNC_API_KEY": "din-agent-api-nøgle-her"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Vigtige implementeringsnoter
+
+**Race conditions:** `SELECT FOR UPDATE SKIP LOCKED` er kritisk i `checkAndResolveConflict()`.
+Uden det kan to agenter booke samme slot simultant. Alle holds-operationer skal køre
+i en eksplicit transaktion: `BEGIN` → conflict check → INSERT/UPDATE → `COMMIT`.
+
+**Timezone-håndtering:** Gem ALT i UTC i databasen (TIMESTAMPTZ). Frontend konverterer
+til lokal tid. Brug aldrig `new Date()` uden eksplicit timezone. `date-fns` bruges
+til dato-matematik i `getAvailableSlots()`.
+
+**Zod-validering:** Validér altid input med Zod FØR det rammer databasen.
+Returnér Zod-fejl direkte som 422-response:
+```typescript
+const result = Schema.safeParse(req.body);
+if (!result.success) {
+  return res.status(422).json({
+    error: 'validation_error',
+    details: result.error.flatten()
+  });
+}
+```
+
+**Error handling:** Pak alle route-handlers ind i try/catch.
+Log fejlen til console.error og returnér 500:
+```typescript
+} catch (err) {
+  console.error('[holds] unexpected error:', err);
+  return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+}
+```
+
+**Test-isolation:** Hvert integration-test-suite skal:
+- I `beforeAll`: kør migration på test-DB, opret test-org og test-agent
+- I `afterAll`: `DELETE FROM hold_events; DELETE FROM holds; DELETE FROM agents; DELETE FROM orgs;`
+- Brug `TEST_DATABASE_URL` (separat test-database, aldrig production-DB)