Contrasync Docs

Appearance

Estrutura do Projeto ​

Organização de arquivos e pastas do contrasync-whatsapp-bot.

Visão Geral ​

contrasync-whatsapp-bot/
├── bin/
│   └── app.ts                                CDK entry
├── infra/
│   └── whatsapp-bot-stack.ts                 Stack (Lambda + API Gateway + Alarms)
├── scripts/
│   └── dev-server.ts                         HTTP wrapper local para o handler
├── src/
│   ├── handler.ts                            Lambda entrypoint (route + DI)
│   ├── handler.spec.ts                       Integração end-to-end
│   ├── handlers/
│   │   ├── inbound-webhook.handler.ts        POST /webhook (parse + idempotência + dispatch)
│   │   └── inbound-webhook.handler.spec.ts
│   ├── services/
│   │   ├── bot-router.service.ts             State machine: connect | empresa pendente | linked
│   │   └── bot-router.service.spec.ts
│   ├── adapters/
│   │   ├── zapi/
│   │   │   ├── zapi.client.ts                Envio (POST /send-text)
│   │   │   ├── zapi.client.spec.ts
│   │   │   ├── zapi.types.ts                 Contrato do Z-API (entrada)
│   │   │   ├── zapi.mapper.ts                Payload Z-API → IncomingMessage
│   │   │   └── zapi.mapper.spec.ts
│   │   └── contrasync-api/
│   │       ├── contrasync-api.client.ts      Cliente HTTP do nest-api (x-bot-api-key)
│   │       ├── contrasync-api.client.spec.ts
│   │       └── contrasync-api.types.ts       Tipos de resposta da API
│   ├── domain/
│   │   ├── constants/
│   │   │   ├── bot-commands.const.ts         Comandos planejados (Fase 4+)
│   │   │   └── bot-replies.const.ts          Mensagens devolvidas pelo bot
│   │   ├── enums/
│   │   │   └── bot-state.enum.ts             Estados planejados (Fase 4+)
│   │   └── interfaces/
│   │       ├── incoming-message.interface.ts
│   │       └── outgoing-message.interface.ts
│   ├── helpers/
│   │   ├── phone-normalize.ts                normalizePhone + formatPhoneForDisplay
│   │   └── phone-normalize.spec.ts
│   └── common/
│       ├── logger.ts                         Logger JSON estruturado
│       ├── logger.spec.ts
│       ├── error-boundary.ts                 BotError/ValidationError/UnauthorizedError
│       └── error-boundary.spec.ts
├── vitest.config.ts                          Threshold 100% coverage
├── vitest.setup.ts                           Mock global de console.*
├── tsconfig.json
├── cdk.json
├── package.json
├── .env.example
└── README.md

Responsabilidades por Pasta ​

PastaResponsabilidade
bin/Entry-point do CDK
infra/Stack CDK (Lambda, API Gateway, LogGroup, Alarms, Tags, Outputs)
scripts/Utilitários de desenvolvimento (dev-server HTTP local)
src/handler.tsBootstrap das dependências + roteamento HTTP
src/handlers/Orquestram parse, validação, idempotência e dispatch
src/services/Lógica de negócio (state machine de comandos)
src/adapters/zapi/Cliente do gateway WhatsApp e mapper para o domínio
src/adapters/contrasync-api/Cliente HTTP do WhatsappModule no nest-api
src/domain/Interfaces, enums, constantes zero dependência externa
src/helpers/Funções puras reutilizáveis
src/common/Logger e error boundary compartilhados

Testes Co-locados ​

Todo .ts de lógica tem .spec.ts ao lado:

src/services/bot-router.service.ts
src/services/bot-router.service.spec.ts

Coverage thresholds em vitest.config.ts: 100% statements / branches / functions / lines.

O Que NÃO Está no Projeto ​

  • Sem controllers/: Lambda + API Gateway substitui (roteamento em handler.ts)
  • Sem repositories/: bot não acessa o DB diretamente; faz HTTP no WhatsappModule da nest-api
  • Sem dto/: contrato de entrada é ZapiWebhookPayload; contrato de saída é APIGatewayProxyResultV2
  • Sem auto-reply / business-hours: removidos junto com o desligamento programado da API nest

Documento atualizado em Maio 2026