@natyapp/meta 1.6.6 → 1.7.0

package/docs/01-visao-geral.md

@@ -0,0 +1,355 @@
+# 01 - Visão Geral do Projeto
+
+[⬅️ Voltar ao Índice](README.md)
+
+---
+
+## 📋 Sumário
+- [Apresentação](#-apresentação)
+- [Propósito e Valor de Negócio](#-propósito-e-valor-de-negócio)
+- [Casos de Uso Principais](#-casos-de-uso-principais)
+- [Público-Alvo](#-público-alvo)
+- [Stack Tecnológico](#-stack-tecnológico)
+- [Requisitos](#-requisitos)
+- [Quick Start](#-quick-start)
+- [Arquitetura de Alto Nível](#-arquitetura-de-alto-nível)
+
+---
+
+## 🎯 Apresentação
+
+**@natyapp/meta** é um SDK (Software Development Kit) desenvolvido em TypeScript que simplifica a integração com a **WhatsApp Business API da Meta** (anteriormente Facebook). 
+
+O SDK atua como uma camada de abstração que encapsula a complexidade da API oficial da Meta, oferecendo aos desenvolvedores uma interface limpa, type-safe e orientada a eventos para construir soluções de comunicação empresarial via WhatsApp.
+
+### O que é este SDK?
+
+É uma biblioteca que permite que aplicações Node.js/TypeScript:
+- 📤 **Enviem mensagens** de texto, mídia, botões interativos e listas para clientes via WhatsApp
+- 📥 **Recebam mensagens** de clientes através de webhooks configuráveis
+- 🔗 **Gerenciem múltiplas conexões** WhatsApp Business de forma isolada (multi-tenancy)
+- 🔐 **Automatizem gestão de credenciais** (tokens, refresh automático)
+- 📊 **Monitorem e registrem** todas as interações e erros
+
+---
+
+## 💼 Propósito e Valor de Negócio
+
+### Problema que Resolve
+
+A API oficial do WhatsApp Business da Meta possui:
+- ❌ Estrutura de endpoints complexa e verbosa
+- ❌ Gestão manual de tokens de autenticação (curta e longa duração)
+- ❌ Payloads JSON complexos para mensagens interativas
+- ❌ Necessidade de infraestrutura para webhooks
+- ❌ Tratamento de erros não padronizado
+- ❌ Falta de type safety em JavaScript
+
+### Solução Oferecida
+
+O SDK Naty Meta oferece:
+- ✅ **Interface simplificada** - Métodos intuitivos para cada tipo de mensagem
+- ✅ **Gestão automática de tokens** - Refresh transparente de access tokens
+- ✅ **Type Safety** - Totalmente tipado em TypeScript, reduzindo erros em desenvolvimento
+- ✅ **Sistema de eventos** - Arquitetura event-driven para processar mensagens recebidas
+- ✅ **Multi-tenancy nativo** - Suporte a múltiplas empresas e números WhatsApp
+- ✅ **Tratamento de erros robusto** - Pattern Either Monad para controle de fluxo
+- ✅ **Webhooks integrados** - Rotas Express prontas para uso
+- ✅ **Logging completo** - Rastreamento de todas operações e erros
+
+### Valor para o Negócio
+
+- **Redução de Time-to-Market:** Desenvolvedores implementam chatbots e automações 10x mais rápido
+- **Menor Custo de Manutenção:** Abstração reduz dependência direta da API Meta (que muda frequentemente)
+- **Escalabilidade:** Suporta múltiplos clientes/tenants com isolamento de dados
+- **Confiabilidade:** Retry logic, error handling e logging profissional
+- **Conformidade:** Segue best practices da Meta para WhatsApp Business
+
+---
+
+## 🎯 Casos de Uso Principais
+
+### 1. **Chatbots de Atendimento ao Cliente**
+Automatize respostas a perguntas frequentes, triagem de atendimento e suporte 24/7.
+
+**Exemplo:** 
+- Cliente envia "Olá" → Bot responde com menu de opções via botões interativos
+- Cliente seleciona opção → Bot direciona para fluxo específico
+
+### 2. **Notificações Transacionais**
+Envie confirmações de pedido, atualizações de status, alertas importantes.
+
+**Exemplo:**
+- Pedido confirmado → Envio automático de mensagem com número do pedido e prazo
+- Pedido saiu para entrega → Mensagem com link de rastreamento
+
+### 3. **Campanhas de Marketing Interativas**
+Crie listas de produtos, promoções com botões de ação rápida.
+
+**Exemplo:**
+- Envio de lista de produtos em promoção
+- Cliente seleciona produto → Bot envia detalhes e link de compra
+
+### 4. **Agendamento e Lembretes**
+Confirmações de consultas, lembretes de pagamento, follow-ups.
+
+**Exemplo:**
+- 24h antes da consulta → Mensagem de lembrete com botões "Confirmar" / "Reagendar"
+
+### 5. **Coleta de Feedback**
+Pesquisas de satisfação pós-atendimento via mensagens interativas.
+
+**Exemplo:**
+- Após fechamento do ticket → Mensagem com escala de satisfação (botões 1-5 estrelas)
+
+### 6. **Integração com CRM/ERP**
+Conecte sistemas legados para comunicação via WhatsApp.
+
+**Exemplo:**
+- Novo lead no CRM → Mensagem automática de boas-vindas
+- Boleto vencendo → Notificação via WhatsApp com link de pagamento
+
+---
+
+## 👥 Público-Alvo
+
+### Desenvolvedores
+- Backend developers construindo APIs de comunicação
+- Frontend developers integrando chatbots em aplicações web
+- Full-stack developers em startups e empresas de SaaS
+
+### Empresas
+- **SaaS de Atendimento:** Plataformas de customer service
+- **E-commerce:** Lojas online com comunicação via WhatsApp
+- **Fintechs:** Notificações bancárias e de pagamento
+- **Healthtech:** Agendamentos e lembretes médicos
+- **Educação:** Comunicação com alunos e responsáveis
+
+### Perfil Técnico Esperado
+- Conhecimento intermediário de **Node.js** e **TypeScript**
+- Familiaridade com **REST APIs** e **webhooks**
+- Experiência com **Express.js** (para webhook setup)
+- Conceitos básicos de **assincronismo** (Promises, async/await)
+
+---
+
+## 🛠 Stack Tecnológico
+
+### Core
+- **Linguagem:** TypeScript 4.9+
+- **Runtime:** Node.js ≥14.x
+- **HTTP Client:** Axios 1.7
+- **Event System:** Node.js EventEmitter
+
+### Integração Opcional
+- **Web Framework:** Express.js 4.x (para webhooks)
+- **UI Components:** React 18.x (componente de cadastro)
+
+### Desenvolvimento
+- **Testes:** Jest 29
+- **Build:** TypeScript Compiler
+- **Lint:** ESLint
+- **Package Manager:** npm, yarn ou pnpm
+
+### APIs Externas
+- **Meta Graph API v18.0** - WhatsApp Business API
+- **Naty Meta API** - Backend proprietário para gestão de conexões
+
+---
+
+## ✅ Requisitos
+
+### Pré-requisitos de Negócio
+1. **Conta Meta Business** - Você precisa ter uma conta no Meta Business Manager
+2. **Aplicação Meta** - Criar uma app no Meta for Developers com WhatsApp Business API ativada
+3. **Número WhatsApp Business** - Número de telefone verificado e associado à aplicação
+4. **Credenciais de Acesso:**
+   - App ID e App Secret (da aplicação Meta)
+   - Access Token (gerado no Meta for Developers)
+   - Phone Number ID (identificador do número WhatsApp)
+
+### Pré-requisitos Técnicos
+- **Node.js:** Versão 14 ou superior
+- **TypeScript:** Versão 4.9 ou superior (para desenvolvimento)
+- **App Token Naty:** Credencial fornecida pela plataforma Naty (para autenticação no SDK)
+
+### Variáveis de Ambiente
+```bash
+# Obrigatória
+API_META=https://api.meta.naty.app/v1  # URL da API Naty Meta
+
+# Opcional (para desenvolvimento local)
+NODE_ENV=development
+PORT=3000
+```
+
+---
+
+## 🚀 Quick Start
+
+### Instalação
+
+```bash
+# Usando npm
+npm install @natyapp/meta
+
+# Usando pnpm
+pnpm add @natyapp/meta
+
+# Usando yarn
+yarn add @natyapp/meta
+```
+
+### Exemplo Básico - Enviar Mensagem
+
+```typescript
+import { NatyMeta } from '@natyapp/meta';
+
+// 1. Inicializar SDK
+const sdk = new NatyMeta();
+await sdk.connect({ appToken: 'seu-app-token-aqui' });
+
+// 2. Criar instância de resposta WhatsApp
+const whatsapp = sdk.Message.WhatsappResponse({
+  companyId: 'id-da-sua-empresa',
+  phone_number_id: 'id-do-numero-whatsapp'
+});
+
+// 3. Enviar mensagem de texto
+const result = await whatsapp.send_text({
+  to: '5511999999999',       // Número do destinatário (formato E.164)
+  message: 'Olá! Esta é uma mensagem de teste.'
+});
+
+if (result.isRight()) {
+  console.log('Mensagem enviada:', result.value);
+} else {
+  console.error('Erro ao enviar:', result.value);
+}
+```
+
+### Exemplo - Receber Mensagens
+
+```typescript
+import express from 'express';
+import { NatyMeta } from '@natyapp/meta';
+
+const app = express();
+app.use(express.json());
+
+// Inicializar SDK com Express
+const sdk = new NatyMeta();
+await sdk.connect({
+  appToken: 'seu-app-token',
+  app: app,                    // Integra rotas de webhook
+  pathname: '/webhooks'        // Base path para webhooks
+});
+
+// Escutar eventos de mensagens recebidas
+sdk.on('message', async (data) => {
+  console.log('Mensagem recebida:', data.message);
+  
+  // Responder automaticamente
+  const whatsapp = data.whatsappResponse;
+  await whatsapp.send_text({
+    to: data.sender,
+    message: 'Recebi sua mensagem!'
+  });
+});
+
+app.listen(3000, () => {
+  console.log('Servidor rodando na porta 3000');
+});
+```
+
+👉 **Para exemplos completos, consulte:** [Guia Prático](07-guia-pratico.md)
+
+---
+
+## 🏗 Arquitetura de Alto Nível
+
+```mermaid
+graph TB
+    subgraph "Aplicação do Cliente"
+        APP[Aplicação Node.js/TypeScript]
+    end
+    
+    subgraph "SDK Naty Meta"
+        SDK[NatyMeta SDK]
+        CONN[Connection Manager]
+        MSG[Message Handler]
+        WEBHOOK[Webhook Routes]
+        EVENTS[Event Emitter]
+    end
+    
+    subgraph "APIs Externas"
+        NATY_API[Naty Meta API<br/>Gestão de Conexões]
+        META_API[Meta Graph API<br/>WhatsApp Business]
+    end
+    
+    subgraph "Meta Infrastructure"
+        WHATSAPP[WhatsApp Business<br/>Platform]
+    end
+    
+    APP -->|1. Inicializa| SDK
+    SDK -->|2. Valida appToken| NATY_API
+    APP -->|3. Envia mensagem| MSG
+    MSG -->|4. Busca credenciais| NATY_API
+    MSG -->|5. Envia via API| META_API
+    META_API -->|6. Entrega| WHATSAPP
+    WHATSAPP -->|7. Recebe resposta| META_API
+    META_API -->|8. Webhook POST| WEBHOOK
+    WEBHOOK -->|9. Emite evento| EVENTS
+    EVENTS -->|10. Notifica| APP
+    
+    style SDK fill:#4CAF50,color:#fff
+    style NATY_API fill:#2196F3,color:#fff
+    style META_API fill:#FF9800,color:#fff
+    style WHATSAPP fill:#25D366,color:#fff
+```
+
+### Fluxo Simplificado
+
+1. **Inicialização:** Aplicação instancia SDK e valida credenciais
+2. **Envio de Mensagem:** SDK busca conexão, refresha token se necessário, envia via Meta API
+3. **Recepção de Mensagem:** Meta envia webhook → SDK processa → Emite evento → Aplicação responde
+
+### Camadas do Sistema
+
+```mermaid
+graph LR
+    A[API Layer<br/>NatyMeta Class] --> B[Use Cases Layer<br/>WhatsappResponse]
+    B --> C[Services Layer<br/>Mutations & Axios]
+    C --> D[Integration Layer<br/>External APIs]
+    
+    style A fill:#E3F2FD
+    style B fill:#BBDEFB
+    style C fill:#90CAF9
+    style D fill:#64B5F6
+```
+
+👉 **Para detalhes técnicos completos, consulte:** [Arquitetura Técnica](03-arquitetura.md)
+
+---
+
+## 📊 Estatísticas do Projeto
+
+- **Linguagem:** TypeScript
+- **Cobertura de Testes:** Jest configurado
+- **Estrutura:** ~50+ arquivos organizados em módulos
+- **Principais Dependências:** Axios, Express (opcional)
+- **Suporte a Mensagens:** 10+ tipos (texto, mídia, botões, listas, templates, etc.)
+
+---
+
+## 🔗 Próximos Passos
+
+Após entender a visão geral, recomendamos:
+
+1. **[Contexto de Negócio](02-contexto-negocio.md)** - Entenda as regras e políticas
+2. **[Guia Prático](07-guia-pratico.md)** - Comece a usar o SDK
+3. **[Fluxos Funcionais](04-fluxos-funcionais.md)** - Veja como tudo funciona internamente
+
+---
+
+[⬅️ Voltar ao Índice](README.md) | [➡️ Próximo: Contexto de Negócio](02-contexto-negocio.md)