# 📡 API Endpoints Documentation

## Índice
- [Autenticación](#autenticación)
- [Usuarios](#usuarios)
- [Compañías](#compañías)
- [Posts](#posts)
- [Comentarios](#comentarios)
- [Búsqueda](#búsqueda)

---

## Autenticación

### `POST /auth/register-company`
**Descripción:** Registra una nueva compañía con su administrador principal  
**Autenticación:** ❌ No requerida  

**Request Body:**
```json
{
  "companyName": "string (requerido)",
  "companyEmail": "string (opcional)",
  "industry": "string (opcional)",
  "size": "string (opcional)",
  "adminEmail": "string (requerido)",
  "adminPassword": "string (requerido)",
  "adminName": "string (requerido)"
}
```

**Response:**
```json
{
  "message": "Compañía y admin registrados",
  "company": {
    "id": "uuid",
    "name": "string",
    "email": "string",
    "industry": "string",
    "size": "string",
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}
```

---

### `POST /auth/register`
**Descripción:** Registra un nuevo usuario en una compañía existente  
**Autenticación:** ❌ No requerida  

**Request Body:**
```json
{
  "email": "string (requerido)",
  "password": "string (requerido)",
  "fullName": "string (requerido)",
  "companyId": "uuid (requerido)",
  "department": "string (opcional)"
}
```

**Response:**
```json
{
  "message": "Usuario registrado",
  "user": {
    "id": "uuid",
    "companyId": "uuid",
    "email": "string",
    "fullName": "string",
    "role": "employee",
    "department": "string | null",
    "internalAnonId": "string",
    "externalAnonId": "string",
    "isActive": true,
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}
```

---

### `POST /auth/login`
**Descripción:** Inicia sesión y obtiene token JWT  
**Autenticación:** ❌ No requerida  

**Request Body:**
```json
{
  "email": "string (requerido)",
  "password": "string (requerido)"
}
```

**Response:**
```json
{
  "token": "string (JWT)",
  "user": {
    "id": "uuid",
    "companyId": "uuid",
    "email": "string",
    "fullName": "string",
    "role": "employee | company_manager | company_admin | super_admin",
    "department": "string | null",
    "internalAnonId": "string",
    "externalAnonId": "string",
    "isActive": true,
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}
```

---

### `POST /auth/logout`
**Descripción:** Cierra sesión del usuario  
**Autenticación:** ✅ Requerida  

**Request Body:** Ninguno

**Response:**
```json
{
  "message": "Sesión cerrada correctamente"
}
```

---

### `GET /auth/profile`
**Descripción:** Obtiene el perfil del usuario autenticado  
**Autenticación:** ✅ Requerida  

**Request Body:** Ninguno

**Response:**
```json
{
  "id": "uuid",
  "companyId": "uuid",
  "email": "string",
  "fullName": "string",
  "role": "string",
  "department": "string | null",
  "internalAnonId": "string",
  "externalAnonId": "string",
  "isActive": true,
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

---

### `GET /auth/me`
**Descripción:** Alias de `/auth/profile`  
**Autenticación:** ✅ Requerida  

**Request Body:** Ninguno

**Response:** Igual que `/auth/profile`

---

## Usuarios

### `GET /users/me`
**Descripción:** Obtiene información del usuario actual  
**Autenticación:** ✅ Requerida  

**Request Body:** Ninguno

**Response:**
```json
{
  "id": "uuid",
  "companyId": "uuid",
  "email": "string",
  "fullName": "string",
  "role": "string",
  "department": "string | null",
  "internalAnonId": "string",
  "externalAnonId": "string",
  "isActive": true,
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

---

### `PATCH /users/me`
**Descripción:** Actualiza información del usuario actual  
**Autenticación:** ✅ Requerida  

**Request Body:**
```json
{
  "fullName": "string (opcional)",
  "department": "string (opcional)"
}
```

**Response:**
```json
{
  "id": "uuid",
  "companyId": "uuid",
  "email": "string",
  "fullName": "string",
  "role": "string",
  "department": "string | null",
  "internalAnonId": "string",
  "externalAnonId": "string",
  "isActive": true,
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

---

### `GET /users/me/posts`
**Descripción:** Obtiene todos los posts del usuario actual  
**Autenticación:** ✅ Requerida  

**Query Params:**
```
?page=1 (opcional, default: 1)
&limit=20 (opcional, default: 20)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "userId": "uuid",
      "companyId": "uuid",
      "content": "string",
      "postType": "idea | suggestion | criticism | question",
      "visibility": "internal | external",
      "moderationStatus": "pending | approved | rejected",
      "likesCount": 0,
      "commentsCount": 0,
      "createdAt": "timestamp",
      "updatedAt": "timestamp"
    }
  ]
}
```

---

## Compañías

### `GET /companies`
**Descripción:** Lista todas las compañías (para selección en registro)  
**Autenticación:** ❌ No requerida  

**Request Body:** Ninguno

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "name": "string",
      "email": "string",
      "industry": "string",
      "size": "string",
      "createdAt": "timestamp"
    }
  ]
}
```

---

### `GET /companies/:id`
**Descripción:** Obtiene detalle de una compañía con sus usuarios  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
id: uuid (requerido)
```

**Response:**
```json
{
  "id": "uuid",
  "name": "string",
  "email": "string",
  "industry": "string",
  "size": "string",
  "createdAt": "timestamp",
  "updatedAt": "timestamp",
  "Users": [
    {
      "id": "uuid",
      "email": "string",
      "fullName": "string",
      "role": "string",
      "department": "string | null",
      "isActive": true
    }
  ]
}
```

---

### `POST /companies`
**Descripción:** Crea una nueva compañía  
**Autenticación:** ✅ Requerida (solo `super_admin`)  

**Request Body:**
```json
{
  "name": "string (requerido)",
  "email": "string (opcional)",
  "industry": "string (opcional)",
  "size": "string (opcional)"
}
```

**Response:**
```json
{
  "id": "uuid",
  "name": "string",
  "email": "string",
  "industry": "string",
  "size": "string",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

---

### `PATCH /companies/:id`
**Descripción:** Actualiza una compañía  
**Autenticación:** ✅ Requerida (solo `super_admin` o `company_admin`)  

**Request Params:**
```
id: uuid (requerido)
```

**Request Body:**
```json
{
  "name": "string (opcional)",
  "email": "string (opcional)",
  "industry": "string (opcional)",
  "size": "string (opcional)"
}
```

**Response:**
```json
{
  "id": "uuid",
  "name": "string",
  "email": "string",
  "industry": "string",
  "size": "string",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

---

### `DELETE /companies/:id`
**Descripción:** Elimina una compañía  
**Autenticación:** ✅ Requerida (solo `super_admin`)  

**Request Params:**
```
id: uuid (requerido)
```

**Response:**
```json
{
  "message": "Compañía eliminada"
}
```

---

### `GET /companies/:id/users`
**Descripción:** Lista usuarios de una compañía  
**Autenticación:** ✅ Requerida (solo `super_admin`, `company_admin`, `company_manager`)  

**Request Params:**
```
id: uuid (requerido)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "companyId": "uuid",
      "email": "string",
      "fullName": "string",
      "role": "string",
      "department": "string | null",
      "internalAnonId": "string",
      "externalAnonId": "string",
      "isActive": true,
      "createdAt": "timestamp",
      "updatedAt": "timestamp"
    }
  ]
}
```

---

## Posts

### `POST /posts`
**Descripción:** Crea un nuevo post  
**Autenticación:** ✅ Requerida  

**Request Body:**
```json
{
  "content": "string (requerido)",
  "postType": "idea | suggestion | criticism | question (opcional, default: idea)",
  "visibility": "internal | external (opcional, default: internal)"
}
```

**Response:**
```json
{
  "id": "uuid",
  "userId": "uuid",
  "companyId": "uuid",
  "content": "string",
  "postType": "idea | suggestion | criticism | question",
  "visibility": "internal | external",
  "moderationStatus": "approved",
  "likesCount": 0,
  "commentsCount": 0,
  "createdAt": "timestamp",
  "updatedAt": "timestamp",
  "author": {
    "id": "uuid",
    "internalAnonId": "string",
    "externalAnonId": "string"
  },
  "authorDisplay": "string (AN-XXXXXX o EX-XXXXXX según visibility)"
}
```

---

### `GET /posts`
**Descripción:** Lista posts de una compañía  
**Autenticación:** ✅ Requerida  

**Query Params:**
```
?companyId=uuid (opcional, default: compañía del usuario)
&page=1 (opcional, default: 1)
&limit=10 (opcional, default: 10)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "userId": "uuid",
      "companyId": "uuid",
      "content": "string",
      "postType": "idea | suggestion | criticism | question",
      "visibility": "internal | external",
      "moderationStatus": "pending | approved | rejected",
      "likesCount": 10,
      "commentsCount": 5,
      "createdAt": "timestamp",
      "updatedAt": "timestamp",
      "author": {
        "id": "uuid",
        "internalAnonId": "string",
        "externalAnonId": "string"
      },
      "authorDisplay": "string",
      "reactions": {
        "like": 5,
        "love": 3,
        "insightful": 2
      },
      "myReaction": "like | null"
    }
  ]
}
```

---

### `GET /posts/:postId`
**Descripción:** Obtiene detalle de un post específico  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Response:**
```json
{
  "id": "uuid",
  "userId": "uuid",
  "companyId": "uuid",
  "content": "string",
  "postType": "idea | suggestion | criticism | question",
  "visibility": "internal | external",
  "moderationStatus": "pending | approved | rejected",
  "likesCount": 10,
  "commentsCount": 5,
  "createdAt": "timestamp",
  "updatedAt": "timestamp",
  "author": {
    "id": "uuid",
    "internalAnonId": "string",
    "externalAnonId": "string"
  },
  "authorDisplay": "string",
  "reactions": {
    "like": 5,
    "love": 3,
    "insightful": 2
  },
  "myReaction": "like | null"
}
```

---

### `POST /posts/:postId/react`
**Descripción:** Reacciona a un post (agregar, cambiar o remover reacción)  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Request Body:**
```json
{
  "reactionType": "like | love | insightful | celebrate | support | curious (requerido)"
}
```

**Response:**
```json
{
  "myReaction": "like | null"
}
```

---

### `GET /posts/:postId/reactions`
**Descripción:** Lista todas las reacciones de un post  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "userId": "uuid",
      "postId": "uuid",
      "commentId": null,
      "reactionType": "like | love | insightful | celebrate | support | curious",
      "createdAt": "timestamp",
      "updatedAt": "timestamp",
      "user": {
        "id": "uuid",
        "internalAnonId": "string",
        "externalAnonId": "string"
      },
      "userDisplay": "string (AN-XXXXXX o EX-XXXXXX)"
    }
  ]
}
```

---

### `DELETE /posts/:postId`
**Descripción:** Elimina un post (solo autor o super_admin)  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Response:**
```json
{
  "message": "Post eliminado"
}
```

---

### `POST /posts/upload`
**Descripción:** Sube una imagen/archivo para un post  
**Autenticación:** ✅ Requerida  

**Request Body:** FormData con archivo

**Response:**
```json
{
  "url": "string (URL del archivo subido)"
}
```

---

## Comentarios

### `POST /posts/:postId/comments`
**Descripción:** Crea un comentario en un post  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Request Body:**
```json
{
  "content": "string (requerido)",
  "parentCommentId": "uuid (opcional, para respuestas)"
}
```

**Response:**
```json
{
  "id": "uuid",
  "postId": "uuid",
  "userId": "uuid",
  "parentCommentId": "uuid | null",
  "content": "string",
  "moderationStatus": "approved",
  "likesCount": 0,
  "repliesCount": 0,
  "createdAt": "timestamp",
  "updatedAt": "timestamp",
  "author": {
    "id": "uuid",
    "internalAnonId": "string",
    "externalAnonId": "string"
  },
  "authorDisplay": "string"
}
```

---

### `GET /posts/:postId/comments`
**Descripción:** Lista comentarios de un post (solo nivel superior)  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
postId: uuid (requerido)
```

**Query Params:**
```
?page=1 (opcional, default: 1)
&limit=20 (opcional, default: 20)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "postId": "uuid",
      "userId": "uuid",
      "parentCommentId": null,
      "content": "string",
      "moderationStatus": "pending | approved | rejected",
      "likesCount": 5,
      "repliesCount": 2,
      "createdAt": "timestamp",
      "updatedAt": "timestamp",
      "author": {
        "id": "uuid",
        "internalAnonId": "string",
        "externalAnonId": "string"
      },
      "authorDisplay": "string",
      "reactions": {
        "like": 3,
        "love": 2
      },
      "myReaction": "like | null"
    }
  ]
}
```

---

### `GET /comments/:commentId/replies`
**Descripción:** Lista respuestas de un comentario  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
commentId: uuid (requerido)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "postId": "uuid",
      "userId": "uuid",
      "parentCommentId": "uuid",
      "content": "string",
      "moderationStatus": "pending | approved | rejected",
      "likesCount": 2,
      "repliesCount": 0,
      "createdAt": "timestamp",
      "updatedAt": "timestamp",
      "author": {
        "id": "uuid",
        "internalAnonId": "string",
        "externalAnonId": "string"
      },
      "authorDisplay": "string",
      "reactions": {
        "like": 2
      },
      "myReaction": "like | null"
    }
  ]
}
```

---

### `POST /comments/:commentId/react`
**Descripción:** Reacciona a un comentario  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
commentId: uuid (requerido)
```

**Request Body:**
```json
{
  "reactionType": "like | love | insightful | celebrate | support | curious (requerido)"
}
```

**Response:**
```json
{
  "myReaction": "like | null"
}
```

---

### `DELETE /comments/:commentId`
**Descripción:** Elimina un comentario (solo autor o super_admin)  
**Autenticación:** ✅ Requerida  

**Request Params:**
```
commentId: uuid (requerido)
```

**Response:**
```json
{
  "message": "Comentario eliminado"
}
```

---

## Búsqueda

### `GET /search/posts`
**Descripción:** Busca posts con filtros  
**Autenticación:** ✅ Requerida  

**Query Params:**
```
?q=texto (opcional, búsqueda en contenido)
&companyId=uuid (opcional, default: compañía del usuario)
&tag=string (opcional)
&from=2024-01-01 (opcional, fecha desde)
&to=2024-12-31 (opcional, fecha hasta)
&page=1 (opcional, default: 1)
&limit=10 (opcional, default: 10)
```

**Response:**
```json
{
  "items": [
    {
      "id": "uuid",
      "userId": "uuid",
      "companyId": "uuid",
      "content": "string",
      "postType": "idea | suggestion | criticism | question",
      "visibility": "internal | external",
      "moderationStatus": "pending | approved | rejected",
      "likesCount": 10,
      "commentsCount": 5,
      "createdAt": "timestamp",
      "updatedAt": "timestamp",
      "author": {
        "id": "uuid",
        "internalAnonId": "string",
        "externalAnonId": "string"
      },
      "authorDisplay": "string"
    }
  ],
  "hasMore": true
}
```

---

### `GET /search/trending-tags`
**Descripción:** Obtiene tags/tipos de posts más populares  
**Autenticación:** ✅ Requerida  

**Query Params:**
```
?companyId=uuid (opcional, default: compañía del usuario)
```

**Response:**
```json
{
  "items": [
    "idea",
    "suggestion",
    "question",
    "criticism"
  ]
}
```

---

## Notas Importantes

### Headers Requeridos
Para endpoints protegidos (✅):
```
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
```

### Códigos de Estado HTTP
- `200` - OK
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `500` - Internal Server Error

### Roles de Usuario
- `employee` - Usuario estándar
- `company_manager` - Manager de compañía
- `company_admin` - Administrador de compañía
- `super_admin` - Administrador global

### Tipos de Post
- `idea` - Idea
- `suggestion` - Sugerencia
- `criticism` - Crítica
- `question` - Pregunta

### Tipos de Reacción
- `like` - Me gusta
- `love` - Me encanta
- `insightful` - Perspicaz
- `celebrate` - Celebrar
- `support` - Apoyo
- `curious` - Curioso

### Visibilidad de Posts
- `internal` - Solo visible dentro de la compañía (muestra `internalAnonId`)
- `external` - Visible externamente (muestra `externalAnonId`)

### Estados de Moderación
- `pending` - Pendiente de revisión
- `approved` - Aprobado
- `rejected` - Rechazado