@natyapp/meta 1.6.6 → 1.7.0

package/docs/02-contexto-negocio.md

@@ -0,0 +1,596 @@
+# 02 - Contexto e Regras de Negócio
+
+[⬅️ Voltar ao Índice](README.md)
+
+---
+
+## 📋 Sumário
+- [Domínio de Negócio](#-domínio-de-negócio)
+- [Modelo Operacional](#-modelo-operacional)
+- [Regras de Negócio](#-regras-de-negócio)
+- [Políticas da Meta WhatsApp](#-políticas-da-meta-whatsapp)
+- [Multi-Tenancy e Isolamento](#-multi-tenancy-e-isolamento)
+- [Perfis e Permissões](#-perfis-e-permissões)
+- [Ciclo de Vida de Tokens](#-ciclo-de-vida-de-tokens)
+- [Limitações e Restrições](#-limitações-e-restrições)
+
+---
+
+## 🏢 Domínio de Negócio
+
+### Contexto Geral
+
+O SDK **@natyapp/meta** opera no domínio de **Comunicação Empresarial B2B via WhatsApp**, fornecendo uma camada de integração entre:
+
+- **Provedores de Software (SaaS)** que desenvolvem soluções de atendimento, e-commerce, fintech, etc.
+- **Empresas Clientes** (tenants) que possuem contas WhatsApp Business
+- **Usuários Finais** (consumidores) que interagem via WhatsApp
+
+### Modelo de Plataforma
+
+```mermaid
+graph TD
+    subgraph "Plataforma Naty"
+        PLAT[Naty Platform]
+        SDK[SDK Meta]
+        API[Naty Meta API]
+    end
+    
+    subgraph "SaaS Providers"
+        SAAS1[SaaS 1<br/>CRM/Atendimento]
+        SAAS2[SaaS 2<br/>E-commerce]
+        SAAS3[SaaS 3<br/>Chatbot]
+    end
+    
+    subgraph "Empresas Clientes"
+        TENANT1[Empresa A<br/>companyId: ABC123]
+        TENANT2[Empresa B<br/>companyId: XYZ789]
+    end
+    
+    subgraph "Meta Infrastructure"
+        META[Meta WhatsApp<br/>Business API]
+    end
+    
+    SAAS1 --> SDK
+    SAAS2 --> SDK
+    SAAS3 --> SDK
+    SDK --> API
+    API --> TENANT1
+    API --> TENANT2
+    TENANT1 --> META
+    TENANT2 --> META
+    
+    style PLAT fill:#4CAF50,color:#fff
+    style SDK fill:#66BB6A,color:#fff
+    style META fill:#25D366,color:#fff
+```
+
+### Proposta de Valor
+
+1. **Para SaaS Providers:**
+   - Redução de complexidade técnica
+   - Gestão centralizada de múltiplos clientes
+   - Atualização transparente frente a mudanças da API Meta
+
+2. **Para Empresas Clientes:**
+   - Onboarding facilitado (conexão simplificada)
+   - Gestão automática de credenciais
+   - Rastreamento e logs de todas comunicações
+
+3. **Para Usuários Finais:**
+   - Experiência nativa no WhatsApp
+   - Respostas rápidas e interativas
+   - Privacidade e segurança (E2E encryption do WhatsApp)
+
+---
+
+## 📐 Modelo Operacional
+
+### Hierarquia de Entidades
+
+```mermaid
+graph TD
+    PLATFORM[Plataforma Naty<br/>appToken]
+    
+    PLATFORM --> COMPANY1[Empresa 1<br/>companyId: ABC123]
+    PLATFORM --> COMPANY2[Empresa 2<br/>companyId: XYZ789]
+    
+    COMPANY1 --> CONN1A[Conexão 1A<br/>+55 11 99999-0001]
+    COMPANY1 --> CONN1B[Conexão 1B<br/>+55 11 99999-0002]
+    
+    COMPANY2 --> CONN2A[Conexão 2A<br/>+55 21 88888-0001]
+    
+    CONN1A --> MSG1[Mensagens]
+    CONN1A --> WH1[Webhooks]
+    CONN1A --> LOG1[Logs]
+    
+    style PLATFORM fill:#1976D2,color:#fff
+    style COMPANY1 fill:#42A5F5,color:#fff
+    style COMPANY2 fill:#42A5F5,color:#fff
+    style CONN1A fill:#90CAF9
+    style CONN1B fill:#90CAF9
+    style CONN2A fill:#90CAF9
+```
+
+### Níveis de Autenticação
+
+| Nível | Credencial | Escopo | Validade |
+|-------|-----------|--------|----------|
+| **Plataforma** | `appToken` | Acesso ao SDK e Naty Meta API | Não expira (gerenciado pela Naty) |
+| **Empresa** | `companyId` | Isolamento de dados por tenant | Permanente (identificador) |
+| **Conexão** | `accessToken` (Meta) | Acesso à API WhatsApp de um número específico | 60 dias (renovável) |
+
+---
+
+## 📜 Regras de Negócio
+
+### RN001 - Isolamento de Dados por Empresa (Multi-Tenancy)
+
+**Descrição:** Todas as operações devem ser isoladas por `companyId`.
+
+**Regra:**
+- Cada entidade (`Connection`, `Message`, `Webhook`, `Log`) possui um campo `companyId`
+- Consultas sempre filtram por `companyId` para evitar vazamento de dados entre tenants
+- Um `companyId` pode ter múltiplas conexões (múltiplos números WhatsApp)
+
+**Implementação:**
+```typescript
+// Exemplo: Buscar conexão sempre filtra por companyId
+const connection = await getConnection({
+  companyId: 'ABC123',
+  phoneNumberId: '123456789'
+});
+```
+
+**Impacto:** Garante conformidade com LGPD e isolamento de clientes.
+
+---
+
+### RN002 - Gestão Automática de Tokens
+
+**Descrição:** Tokens de acesso da Meta expiram e devem ser renovados automaticamente.
+
+**Regra:**
+- **Short-Lived Token:** Válido por ~1 hora, obtido inicialmente
+- **Long-Lived Token:** Válido por 60 dias, obtido via exchange do short-lived
+- **Refresh Automático:** Executado toda vez que um `WhatsappResponse` é instanciado
+- **Persistência:** Token atualizado é salvo na Naty Meta API automaticamente
+
+**Fluxo:**
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant SDK as SDK
+    participant Naty as Naty API
+    participant Meta as Meta API
+    
+    App->>SDK: WhatsappResponse(companyId, phoneNumberId)
+    SDK->>Naty: GET /connection (buscar accessToken)
+    Naty-->>SDK: { accessToken, appId, appSecret }
+    SDK->>Meta: POST /oauth/access_token (exchange token)
+    Meta-->>SDK: { access_token: newToken, expires_in: 5184000 }
+    SDK->>Naty: PUT /connection (salvar novo token)
+    SDK-->>App: Instância pronta para uso
+```
+
+**Exceções:**
+- Se o token não puder ser renovado (credenciais inválidas), um erro é retornado
+- Aplicação deve reagir ao erro e solicitar re-autenticação do cliente
+
+---
+
+### RN003 - Validação de Números de Telefone
+
+**Descrição:** Números devem estar no formato E.164 internacional.
+
+**Regra:**
+- **Formato:** `+[código país][DDD][número]`
+- **Exemplo válido:** `+5511999999999` (Brasil)
+- **Exemplo inválido:** `11999999999` (sem código do país)
+
+**Validação:**
+```typescript
+// O SDK não valida o formato, é responsabilidade da aplicação
+// Recomenda-se usar bibliotecas como libphonenumber-js
+import { parsePhoneNumber } from 'libphonenumber-js';
+
+const phone = parsePhoneNumber('11999999999', 'BR');
+const e164 = phone.format('E.164'); // +5511999999999
+```
+
+**Impacto:** Meta API rejeita requisições com números mal formatados (erro 400).
+
+---
+
+### RN004 - Ordem de Processamento de Webhooks
+
+**Descrição:** Webhooks de mensagens podem chegar fora de ordem.
+
+**Regra:**
+- Meta não garante ordem de entrega de webhooks
+- Aplicação deve usar `timestamp` da mensagem para ordenação
+- IDs de mensagem (`message.id`) são únicos e podem ser usados para deduplicação
+
+**Exemplo de Deduplicação:**
+```typescript
+const processedMessages = new Set<string>();
+
+sdk.on('message', async (data) => {
+  const messageId = data.message.id;
+  
+  if (processedMessages.has(messageId)) {
+    console.log('Mensagem já processada, ignorando');
+    return;
+  }
+  
+  processedMessages.add(messageId);
+  // Processar mensagem...
+});
+```
+
+---
+
+### RN005 - Janela de Mensagens (24h Message Window)
+
+**Descrição:** Empresas só podem iniciar conversas com clientes após interação do cliente ou via templates aprovados.
+
+**Regra Meta:**
+- **Dentro de 24h da última mensagem do cliente:** Empresa pode enviar qualquer mensagem
+- **Fora da janela de 24h:** Empresa só pode enviar **Message Templates** previamente aprovados pela Meta
+
+**Tipos de Template:**
+- **Marketing:** Promoções, novidades
+- **Utility:** Notificações transacionais (pedidos, agendamentos)
+- **Authentication:** OTPs, códigos de verificação
+
+**Implementação:**
+```typescript
+// Enviar template fora da janela de 24h
+await whatsapp.send_text_template({
+  to: '5511999999999',
+  template: {
+    name: 'pedido_confirmado',  // Nome do template aprovado
+    language: 'pt_BR',
+    components: [
+      {
+        type: 'body',
+        parameters: [
+          { type: 'text', text: '#12345' }  // Número do pedido
+        ]
+      }
+    ]
+  }
+});
+```
+
+**Exceção:** Esta regra não se aplica a mensagens enviadas pelo cliente (resposta via webhook sempre funciona).
+
+---
+
+### RN006 - Tipos de Mensagem Suportados
+
+**Descrição:** O SDK suporta todos os tipos de mensagem da API WhatsApp Business.
+
+**Tipos Implementados:**
+
+| Tipo | Método | Uso |
+|------|--------|-----|
+| Texto | `send_text()` | Mensagens simples de texto |
+| Imagem | `send_image()` | Fotos, infográficos |
+| Vídeo | `send_video()` | Vídeos curtos |
+| Áudio | `send_audio()` | Mensagens de voz, podcasts |
+| Documento | `send_document()` | PDFs, planilhas, apresentações |
+| Localização | `send_location()` | Coordenadas geográficas |
+| Contato | `send_contact()` | vCards |
+| Reação | `send_reaction()` | Emoji reação a mensagem |
+| Botões | `send_buttons()` | Até 3 botões de ação rápida |
+| Lista | `send_list()` | Menu com seções e múltiplas opções |
+| Template | `send_*_template()` | Templates aprovados (texto, mídia) |
+
+**Limitações por Tipo:**
+- **Botões:** Máximo 3 botões por mensagem
+- **Lista:** Máximo 10 seções, 10 itens por seção
+- **Áudio:** Apenas áudio (não pode ser música, deve ser voz)
+- **Vídeo:** Tamanho máximo ~16MB
+
+---
+
+### RN007 - Webhooks Configuráveis por Tenant
+
+**Descrição:** Cada empresa pode ter URLs de webhook personalizadas.
+
+**Regra:**
+- Webhooks de **mensagens** e **conexões** são configurados separadamente
+- Cada `companyId` pode ter suas próprias URLs de webhook
+- Campo `active` controla se o webhook está ativo ou não
+
+**Estrutura:**
+```typescript
+interface WebhooksEntity {
+  companyId: string;
+  connection: {
+    url: string;        // URL para eventos de conexão
+    active: boolean;
+  };
+  messages: {
+    url: string;        // URL para mensagens recebidas
+    active: boolean;
+  };
+}
+```
+
+**Comportamento:**
+- Se `active: false`, eventos não são enviados para aquela URL
+- Permite ativar/desativar webhooks sem remover configuração
+
+---
+
+### RN008 - Logs e Auditoria Obrigatórios
+
+**Descrição:** Todas as operações devem ser logadas para auditoria.
+
+**Tipos de Log:**
+
+| Tipo | Quando Registrar | Informações |
+|------|------------------|-------------|
+| `Access` | Toda requisição à API | IP, método, URL, user agent |
+| `Error` | Erros em operações | Stack trace, código HTTP, contexto |
+| `Update` | Modificações em entidades | Antes/depois, quem modificou |
+| `Observer` | Eventos monitorados | Tipo de evento, payload |
+| `Middleware` | Processamento de middleware | Etapa, duração |
+
+**Retenção:** Logs devem ser mantidos por no mínimo 90 dias para conformidade.
+
+---
+
+## 📱 Políticas da Meta WhatsApp
+
+### Limites de Taxa (Rate Limits)
+
+A Meta impõe limites de envio por número WhatsApp:
+
+| Tier | Mensagens/dia | Como alcançar |
+|------|---------------|---------------|
+| **Tier 1** | 1.000 | Número recém-registrado |
+| **Tier 2** | 10.000 | Após enviar 1.000 mensagens em 7 dias |
+| **Tier 3** | 100.000 | Após enviar 10.000 mensagens em 7 dias |
+| **Unlimited** | Sem limite | Aprovação manual da Meta (enterprise) |
+
+**Impacto:**
+- SDK não controla rate limiting (responsabilidade da aplicação)
+- Recomenda-se implementar throttling na camada da aplicação
+- Mensagens que excedem o limite são rejeitadas pela Meta (erro 429)
+
+---
+
+### Qualidade da Conta (Quality Rating)
+
+Meta avalia qualidade com base em:
+- **Bloqueios de usuários:** Clientes bloqueando o número da empresa
+- **Relatórios de spam:** Clientes reportando como spam
+- **Conformidade:** Uso de templates aprovados, respeito à janela de 24h
+
+**Status da Conta:**
+- 🟢 **Verde (High Quality):** Sem restrições
+- 🟡 **Amarelo (Medium Quality):** Aviso, monitoramento aumentado
+- 🔴 **Vermelho (Low Quality):** Restrições severas, risco de suspensão
+
+**Ação recomendada:** Monitorar métricas via Meta Business Manager.
+
+---
+
+### Tipos de Conteúdo Proibidos
+
+Meta proíbe envio de:
+- ❌ Conteúdo adulto ou sexual
+- ❌ Discurso de ódio, discriminação
+- ❌ Desinformação relacionada à saúde
+- ❌ Violência ou conteúdo gráfico
+- ❌ Produtos ilegais (drogas, armas)
+- ❌ Esquemas financeiros fraudulentos
+
+**Consequência:** Suspensão imediata da conta.
+
+---
+
+## 🏢 Multi-Tenancy e Isolamento
+
+### Conceito
+
+Multi-tenancy (multi-inquilinato) permite que uma única instância do SDK sirva múltiplas empresas (tenants) com isolamento completo de dados.
+
+### Arquitetura de Isolamento
+
+```mermaid
+graph TD
+    subgraph "Tenant A - companyId: ABC123"
+        A_CONN1[Conexão 1<br/>+55 11 99999-0001]
+        A_CONN2[Conexão 2<br/>+55 11 99999-0002]
+        A_MSG[Mensagens A]
+        A_WEBHOOK[Webhooks A]
+        A_LOG[Logs A]
+    end
+    
+    subgraph "Tenant B - companyId: XYZ789"
+        B_CONN1[Conexão 1<br/>+55 21 88888-0001]
+        B_MSG[Mensagens B]
+        B_WEBHOOK[Webhooks B]
+        B_LOG[Logs B]
+    end
+    
+    SDK[SDK Naty Meta] --> A_CONN1
+    SDK --> A_CONN2
+    SDK --> B_CONN1
+    
+    A_CONN1 --> A_MSG
+    A_CONN1 --> A_WEBHOOK
+    A_CONN1 --> A_LOG
+    
+    B_CONN1 --> B_MSG
+    B_CONN1 --> B_WEBHOOK
+    B_CONN1 --> B_LOG
+    
+    style SDK fill:#4CAF50,color:#fff
+```
+
+### Garantias de Isolamento
+
+1. **Dados:** Consultas sempre filtram por `companyId`
+2. **Webhooks:** Cada tenant recebe apenas seus próprios eventos
+3. **Tokens:** Cada conexão tem seu próprio `accessToken`
+4. **Logs:** Registros são isolados por `companyId`
+
+---
+
+## 🔐 Perfis e Permissões
+
+### Níveis de Acesso
+
+#### 1. **Plataforma (SDK Level)**
+
+**Autenticação:** `appToken`
+
+**Permissões:**
+- ✅ Validar credencial no Naty Meta API
+- ✅ Acessar todas as funcionalidades do SDK
+- ✅ Gerenciar múltiplos `companyId`
+
+**Quem possui:** SaaS Provider (desenvolvedor que integra o SDK)
+
+---
+
+#### 2. **Empresa (Tenant Level)**
+
+**Identificação:** `companyId`
+
+**Permissões:**
+- ✅ Gerenciar suas próprias conexões
+- ✅ Enviar mensagens via seus números WhatsApp
+- ✅ Configurar webhooks
+- ✅ Visualizar logs de suas operações
+- ❌ **NÃO pode** acessar dados de outras empresas
+
+**Quem possui:** Cliente do SaaS Provider
+
+---
+
+#### 3. **Conexão (WhatsApp Number Level)**
+
+**Autenticação:** `accessToken` (Meta), `phoneNumberId`
+
+**Permissões:**
+- ✅ Enviar mensagens via número específico
+- ✅ Receber mensagens endereçadas àquele número
+- ✅ Gerenciar mídia (upload/download)
+- ❌ **NÃO pode** enviar mensagens por outros números
+
+**Quem possui:** Número WhatsApp Business registrado na Meta
+
+---
+
+### Matriz de Permissões
+
+| Operação | appToken | companyId | accessToken |
+|----------|----------|-----------|-------------|
+| Conectar ao SDK | ✅ Obrigatório | - | - |
+| Criar Conexão | ✅ | ✅ | ✅ |
+| Enviar Mensagem | ✅ | ✅ | ✅ |
+| Receber Webhook | ✅ | ✅ | - |
+| Criar Log | ✅ | ✅ | - |
+| Visualizar Logs | ✅ | ✅ (filtrado) | - |
+
+---
+
+## 🔄 Ciclo de Vida de Tokens
+
+### Fluxo Completo de Tokens
+
+```mermaid
+sequenceDiagram
+    participant Dev as Desenvolvedor
+    participant Meta as Meta for Developers
+    participant App as Aplicação
+    participant SDK as SDK Naty
+    participant Naty as Naty API
+    participant Graph as Meta Graph API
+    
+    Note over Dev,Meta: 1. Setup Inicial
+    Dev->>Meta: Cria aplicação WhatsApp Business
+    Meta-->>Dev: Gera App ID + App Secret
+    Dev->>Meta: Adiciona número WhatsApp
+    Meta-->>Dev: Gera Short-Lived Token (1h)
+    
+    Note over App,SDK: 2. Primeira Conexão
+    Dev->>App: Configura credenciais
+    App->>SDK: CreateConnection({ appId, appSecret, accessToken })
+    SDK->>Graph: POST /oauth/access_token (exchange)
+    Graph-->>SDK: Long-Lived Token (60 dias)
+    SDK->>Naty: POST /connection (salvar)
+    Naty-->>SDK: { connectionId }
+    
+    Note over App,Graph: 3. Uso Normal (< 60 dias)
+    App->>SDK: WhatsappResponse(companyId, phoneNumberId)
+    SDK->>Naty: GET /connection (buscar token)
+    SDK->>Graph: POST /messages (usar token)
+    Graph-->>SDK: Mensagem enviada
+    
+    Note over SDK,Graph: 4. Refresh Automático
+    SDK->>Graph: POST /oauth/access_token (refresh)
+    Graph-->>SDK: Novo token (60 dias)
+    SDK->>Naty: PUT /connection (atualizar)
+    
+    Note over Dev,Meta: 5. Token Expirado (> 60 dias)
+    SDK->>Graph: POST /messages
+    Graph-->>SDK: 401 Unauthorized
+    SDK-->>App: Error: Token expirado
+    App-->>Dev: Alerta para renovar manualmente
+    Dev->>Meta: Gera novo Short-Lived Token
+    Dev->>App: Atualiza conexão
+```
+
+### Estados do Token
+
+| Estado | Duração | Ação Requerida |
+|--------|---------|---------------|
+| **Short-Lived** | ~1 hora | Exchange para long-lived imediatamente |
+| **Long-Lived** | 60 dias | Refresh automático a cada uso |
+| **Quase Expirando** | < 7 dias | Aplicação deve alertar administrador |
+| **Expirado** | > 60 dias | Reautenticação manual necessária |
+
+---
+
+## ⚠️ Limitações e Restrições
+
+### Limitações Técnicas
+
+1. **Tipos de Mídia:**
+   - Tamanho máximo: 100MB (varia por tipo)
+   - Formatos suportados: Definidos pela Meta (ver [documentação oficial](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media))
+
+2. **Mensagens Interativas:**
+   - Botões: Máximo 3 por mensagem
+   - Listas: Máximo 10 seções, 10 itens/seção
+
+3. **Webhooks:**
+   - Timeout: 15 segundos
+   - Retry: Meta tenta 3x com backoff exponencial
+
+### Limitações de Negócio
+
+1. **Custo:** Meta cobra por mensagens enviadas (varia por país)
+2. **Conformidade:** LGPD, GDPR devem ser respeitadas pela aplicação
+3. **Suporte:** Apenas contas WhatsApp Business (não suporta contas pessoais)
+
+---
+
+## 🔗 Próximos Passos
+
+Agora que você entende o contexto e regras de negócio:
+
+- **[Arquitetura Técnica](03-arquitetura.md)** - Veja como o sistema é estruturado
+- **[Fluxos Funcionais](04-fluxos-funcionais.md)** - Entenda os processos em detalhes
+- **[Guia Prático](07-guia-pratico.md)** - Implemente na prática
+
+---
+
+[⬅️ Anterior: Visão Geral](01-visao-geral.md) | [⬆️ Voltar ao Índice](README.md) | [➡️ Próximo: Arquitetura](03-arquitetura.md)