# API Routes

## Visão Geral

No projeto **Newsletter Platform**, a comunicação entre a interface (front-end) e a regra de negócio (back-end) utiliza **Server Actions** do React 19 / Next.js 15. As **API Routes HTTP** em `src/app/api/` são mantidas estritamente para endpoints que atendem chamadas externas (sistemas parceiros, callbacks da AWS, navegação do usuário e webhooks).

Para consultar as Server Actions utilizadas na interface, consulte a documentação de [Módulos](modules.md).

---

## Tabela de Endpoints HTTP

| Endpoint | Método | Autenticação | Descrição |
| :--- | :---: | :--- | :--- |
| `/api/auth/[...nextauth]` | `GET` / `POST` | Cookie de Sessão / CSRF | Handler do NextAuth.js v5 para login, logout e gerenciamento de sessão |
| `/api/webhooks/ses` | `POST` | Validação de Assinatura SNS (RSA) | Webhook para notificações do AWS SES (Delivery, Bounce, Complaint) e confirmação de assinatura SNS |
| `/api/track/open/[token]` | `GET` | Pública (Sem sessão) | Retorna um GIF transparente 1x1 para rastrear abertura de e-mails |
| `/api/unsubscribe/[contactId]` | `POST` | Pública (Sem sessão) | Processa descadastramento automático "one-click" (RFC 8058) |
| `/api/domains/poll` | `POST` | Header `x-cron-secret` | Endpoint acionado por cron externo para verificar o status DNS de domínios pendentes |
| `/api/admin/ses-bootstrap` | `POST` | Header `x-admin-secret` | Endpoint administrativo para provisionar o Configuration Set e Tópico SNS no AWS SES |

---

## Detalhamento dos Endpoints

### 1. NextAuth Handler
- **Rota**: `GET /api/auth/[...nextauth]` e `POST /api/auth/[...nextauth]`
- **Descrição**: Rota gerenciada pelo NextAuth v5 (`handlers.GET` e `handlers.POST`). Trata autenticação de credenciais, geração de CSRF token e gerenciamento de sessões JWT em cookies `HttpOnly`.

### 2. Webhook AWS SES / SNS
- **Rota**: `POST /api/webhooks/ses`
- **Descrição**: Callback servidor-a-servidor acionado pela AWS quando ocorrem eventos com e-mails enviados pelo SES.
- **Validação de Segurança**: Valida a assinatura de chave pública RSA do envelope SNS utilizando a biblioteca `sns-validator`.
- **Comportamentos**:
  - `Type: SubscriptionConfirmation`: Faz um `fetch` automático na URL de confirmação fornecida pela AWS (`SubscribeURL`) para registrar a aplicação no tópico SNS.
  - `Type: Notification`: Desserializa o JSON de `Message` e executa o `HandleSesNotificationUseCase`, registrando o `EmailEvent` e adicionando o e-mail à lista de supressão se for um Hard Bounce ou reclamação de SPAM.
- **Respostas**: `200 OK` para confirmação; `400 Bad Request` se a assinatura ou o payload for inválido.

### 3. Pixel de Rastreamento de Abertura
- **Rota**: `GET /api/track/open/[token]`
- **Descrição**: Retorna uma imagem GIF estática e transparente de 1x1 pixel (43 bytes). Injetada no corpo dos e-mails enviados via SMTP.
- **Headers de Resposta**:
  ```http
  Content-Type: image/gif
  Cache-Control: no-store, no-cache, must-revalidate
  ```
- **Contrato Especial**: **Sempre responde HTTP 200 OK** com a imagem GIF estática, mesmo que o token/logId seja inválido ou inexistente. Isso evita que proxies ou clientes de e-mail (ex.: Apple Mail Privacy Protection, Gmail) identifiquem a existência de e-mails por respostas diferenciais (200 vs 404) ou quebrem a renderização do layout.

### 4. Descadastro One-Click (RFC 8058)
- **Rota**: `POST /api/unsubscribe/[contactId]`
- **Descrição**: Endpoint público acionado pelos leitores de e-mail através do cabeçalho `List-Unsubscribe-Post: List-Unsubscribe=One-Click`.
- **Efeito**: Altera o status do contato correspondente ao `contactId` para `UNSUBSCRIBED` via `UnsubscribeContactUseCase`.
- **Resposta**:
  ```json
  {
    "success": true,
    "data": {
      "message": "Contato descadastrado com sucesso"
    }
  }
  ```

### 5. Polling de Domínios Pendentes
- **Rota**: `POST /api/domains/poll`
- **Autenticação**: Requer o cabeçalho `x-cron-secret` igual à variável de ambiente `ADMIN_BOOTSTRAP_SECRET`.
- **Descrição**: Executa `PollPendingDomainsUseCase`, buscando no banco todos os domínios com status `PENDING` e consultando na API do AWS SES se a verificação DNS/DKIM foi concluída.

### 6. Bootstrap de Infraestrutura AWS SES
- **Rota**: `POST /api/admin/ses-bootstrap`
- **Autenticação**: Requer o cabeçalho `x-admin-secret` igual à variável de ambiente `ADMIN_BOOTSTRAP_SECRET`.
- **Descrição**: Executa `BootstrapSesInfraUseCase` para provisionar (de forma idempotente) o Configuration Set, o Tópico SNS e o Event Destination na conta da AWS SES.