npm package: @hed-hog/contact-us
Description: ```markdown # @hed-hog/contact-us
Latest version: 0.0.303

```markdown
# @hed-hog/contact-us

## 1. Visão geral do módulo

O módulo `@hed-hog/contact-us` é responsável pela gestão das mensagens enviadas pelos usuários através do formulário "Contact Us". Ele permite o envio, consulta, atualização de status, resposta e exclusão dessas mensagens, além de fornecer estatísticas e configurações relacionadas ao contato.

## 2. Escopo e responsabilidades

- Receber mensagens de contato enviadas por usuários (público).
- Listar, consultar, atualizar status, responder e excluir mensagens (restrito a administradores).
- Enviar notificações por e-mail para o usuário e para o time responsável.
- Fornecer estatísticas sobre as mensagens recebidas.
- Disponibilizar configurações relacionadas ao contato.

## 3. Endpoints

### GET /contact-us/settings

- **Método:** GET  
- **Autenticação:** Pública  
- **Descrição:** Retorna as configurações relacionadas ao contato, como telefone e e-mail de contato.  
- **Parâmetros:** Nenhum  
- **Resposta:**  
  ```json
  {
    "contact-us-phone": "string",
    "contact-us-email": "string"
  }
  ```  
- **Erros:** Nenhum específico.

---

### GET /contact-us/stats

- **Método:** GET  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Retorna estatísticas das mensagens de contato, incluindo totais por status.  
- **Parâmetros:** Nenhum  
- **Resposta:**  
  ```json
  {
    "total": number,
    "totalNew": number,
    "totalResponded": number,
    "totalProgress": number,
    "totalArchived": number
  }
  ```  
- **Erros:** Nenhum específico.

---

### GET /contact-us/:id

- **Método:** GET  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Retorna os detalhes de uma mensagem de contato pelo seu ID.  
- **Parâmetros:**  
  - `id` (path): número inteiro identificador da mensagem.  
- **Resposta:**  
  ```json
  {
    "id": number,
    "name": "string",
    "email": "string",
    "message": "string",
    "response": "string | null",
    "status": "new" | "progress" | "answered" | "archived",
    "created_at": "string (datetime)",
    "updated_at": "string (datetime)",
    "response_at": "string (datetime) | null",
    "user_id": number | null,
    "response_id": number | null,
    "user_contact_us_response_idTouser": object,
    "user_contact_us_user_idTouser": object
  }
  ```  
- **Erros:**  
  - `404 Not Found`: Mensagem não encontrada.

---

### GET /contact-us

- **Método:** GET  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Lista mensagens de contato com paginação e filtro opcional por status e busca textual.  
- **Query Parameters:**  
  - `status` (string, opcional): filtro por status (`new`, `progress`, `answered`, `archived`, `all`).  
  - Parâmetros de paginação via `@hed-hog/api-pagination` (ex: `take`, `skip`, `search`).  
- **Resposta:**  
  ```json
  {
    "data": [
      {
        "id": number,
        "name": "string",
        "email": "string",
        "message": "string",
        "response": "string | null",
        "status": "new" | "progress" | "answered" | "archived",
        "created_at": "string (datetime)",
        "updated_at": "string (datetime)",
        "response_at": "string (datetime) | null",
        "user_id": number | null,
        "response_id": number | null
      }
    ],
    "total": number,
    "page": number,
    "pageSize": number,
    "prev": number | null,
    "next": number | null,
    "lastPage": number
  }
  ```  
- **Erros:** Nenhum específico.

---

### DELETE /contact-us/:id

- **Método:** DELETE  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Exclui uma mensagem de contato pelo seu ID.  
- **Parâmetros:**  
  - `id` (path): número inteiro identificador da mensagem.  
- **Resposta:** Objeto da mensagem excluída (mesma estrutura do objeto mensagem).  
- **Erros:**  
  - `404 Not Found`: Mensagem não encontrada.

---

### PATCH /contact-us/status/:id

- **Método:** PATCH  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Atualiza o status de uma mensagem de contato.  
- **Parâmetros:**  
  - `id` (path): número inteiro identificador da mensagem.  
- **Body:**  
  ```json
  {
    "status": "new" | "progress" | "answered" | "archived"
  }
  ```  
- **Resposta:** Objeto da mensagem atualizada (mesma estrutura do objeto mensagem).  
- **Erros:**  
  - `404 Not Found`: Mensagem não encontrada.  
  - `400 Bad Request`: Status inválido.

---

### POST /contact-us/response/:id

- **Método:** POST  
- **Autenticação:** Requer papel `admin` ou `admin-contact-us`  
- **Descrição:** Envia uma resposta para uma mensagem de contato e notifica o usuário por e-mail.  
- **Parâmetros:**  
  - `id` (path): número inteiro identificador da mensagem.  
- **Body:**  
  ```json
  {
    "response": "string"
  }
  ```  
- **Resposta:** Texto da resposta enviada.  
- **Erros:**  
  - `404 Not Found`: Mensagem não encontrada.  
  - `400 Bad Request`: Resposta inválida.

---

### POST /contact-us

- **Método:** POST  
- **Autenticação:** Pública  
- **Descrição:** Cria uma nova mensagem de contato.  
- **Body:**  
  ```json
  {
    "name": "string",
    "email": "string (email válido)",
    "message": "string"
  }
  ```  
- **Resposta:** Objeto da mensagem criada (mesma estrutura do objeto mensagem).  
- **Erros:**  
  - `400 Bad Request`: E-mail inválido ou dados inválidos.

## 4. Regras de autenticação e autorização

- Endpoints de listagem, consulta, atualização, resposta e exclusão requerem autenticação com papel `admin` ou `admin-contact-us`.
- Endpoints de criação de mensagem e obtenção de configurações são públicos.
- O papel `admin-contact-us` é um administrador com acesso total à gestão de mensagens de contato.

## 5. Estruturas de request/response

### ContactUsSendDTO (criação de mensagem)

```ts
{
  name: string; // obrigatório, string
  email: string; // obrigatório, email válido
  message: string; // obrigatório, string
}
```

### ContactUsResponseDTO (resposta a mensagem)

```ts
{
  response: string; // obrigatório, string
}
```

### ContactUsStatusDTO (atualização de status)

```ts
{
  status: 'new' | 'progress' | 'answered' | 'archived'; // obrigatório, enum válido
}
```

### Resposta padrão de listagem

```ts
{
  data: ContactUsMessage[],
  total: number,
  page: number,
  pageSize: number,
  prev: number | null,
  next: number | null,
  lastPage: number
}
```

### ContactUsMessage (exemplo de objeto mensagem)

```ts
{
  id: number,
  name: string,
  email: string,
  message: string,
  response?: string | null,
  status: 'new' | 'progress' | 'answered' | 'archived',
  created_at: string (datetime),
  updated_at: string (datetime),
  response_at?: string | null,
  user_id?: number | null,
  response_id?: number | null,
  user_contact_us_response_idTouser?: object,
  user_contact_us_user_idTouser?: object
}
```

## 6. Erros comuns

- `404 Not Found`: Mensagem de contato não encontrada para o ID informado.
- `400 Bad Request`: Dados inválidos, como e-mail mal formatado ou status inválido.
- `401 Unauthorized` / `403 Forbidden`: Acesso negado para endpoints restritos sem o papel adequado.

## 7. Banco de dados (tabela contact_us)

```yaml
finalidade: Armazenar mensagens enviadas pelo formulário "Contact Us" e suas respostas.

colunas:
  - id: primary key (auto-increment)
  - name: string, não nulo
  - email: string, não nulo
  - message: text, não nulo
  - response: text, nulo permitido
  - status: enum ['new', 'progress', 'answered', 'archived'], padrão 'new', não nulo
  - response_at: datetime, nulo permitido
  - user_id: foreign key para user.id, nulo permitido, onDelete CASCADE
  - response_id: foreign key para user.id, nulo permitido, onDelete SET NULL
  - created_at: datetime, não nulo, timestamp de criação
  - updated_at: datetime, não nulo, timestamp de atualização

defaults:
  - status: 'new'

nulabilidade:
  - response: nullable
  - response_at: nullable
  - user_id: nullable
  - response_id: nullable

integridade:
  - user_id referencia user.id com onDelete CASCADE
  - response_id referencia user.id com onDelete SET NULL

indices:
  - primary key em id

enums:
  - status: ['new', 'progress', 'answered', 'archived']
```

## 8. Regras de negócio relevantes

- O status inicial de uma mensagem é sempre `new`.
- A resposta a uma mensagem atualiza o status para `answered`, registra o usuário que respondeu e a data da resposta.
- Mensagens podem ser filtradas por status e texto em nome, e-mail, mensagem ou resposta.
- Ao criar uma mensagem, se o e-mail estiver associado a um usuário, o `user_id` é vinculado automaticamente.
- Envio automático de e-mails:
  - Confirmação para o cliente que enviou a mensagem.
  - Notificação para o e-mail configurado em `contact-us-email-to`.
  - Resposta enviada ao cliente quando um administrador responde.
- Validação rigorosa do e-mail no momento da criação da mensagem.
- Exclusão de mensagens remove o registro do banco.
- Atualização de status aceita somente os valores válidos do enum, ignorando o valor `all` (que é convertido para `new` internamente).

## 9. Guia rápido de uso (exemplos)

### Criar mensagem (público)

```http
POST /contact-us
Content-Type: application/json

{
  "name": "João Silva",
  "email": "joao@example.com",
  "message": "Gostaria de mais informações sobre o produto."
}
```

Resposta:

```json
{
  "id": 123,
  "name": "João Silva",
  "email": "joao@example.com",
  "message": "Gostaria de mais informações sobre o produto.",
  "status": "new",
  "created_at": "2024-06-01T12:00:00Z",
  ...
}
```

---

### Listar mensagens com filtro e paginação (admin)

```http
GET /contact-us?status=new&search=joao&take=10&skip=0
Authorization: Bearer <token>
```

Resposta:

```json
{
  "data": [ /* array de mensagens filtradas */ ],
  "total": 5,
  "page": 1,
  "pageSize": 10,
  "prev": null,
  "next": 2,
  "lastPage": 1
}
```

---

### Atualizar status de mensagem (admin)

```http
PATCH /contact-us/status/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "progress"
}
```

Resposta: objeto da mensagem atualizada.

---

### Responder mensagem (admin)

```http
POST /contact-us/response/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "response": "Olá João, obrigado pelo contato. Vamos enviar as informações solicitadas."
}
```

Resposta:

```json
"Olá João, obrigado pelo contato. Vamos enviar as informações solicitadas."
```

---

### Excluir mensagem (admin)

```http
DELETE /contact-us/123
Authorization: Bearer <token>
```

Resposta: objeto da mensagem excluída.

---

Este módulo integra-se com os módulos `@hed-hog/api-locale`, `@hed-hog/api-prisma`, `@hed-hog/api-pagination` e `@hed-hog/core` para funcionalidades de localização, acesso ao banco de dados, paginação e envio de e-mails.
```