@natyapp/meta 1.6.7 → 1.7.0

package/.github/copilot-instructions.md

@@ -0,0 +1,1540 @@
+# GitHub Copilot Custom Instructions - @natyapp/meta SDK
+
+## 📋 Visão Geral
+
+**@natyapp/meta** é um SDK TypeScript que abstrai a integração com a WhatsApp Business API da Meta. Este documento define os padrões arquiteturais, convenções de código e práticas obrigatórias para manter consistência e qualidade no desenvolvimento.
+
+### Filosofia do Projeto
+
+- **Type-Safe First**: TypeScript strict mode com interfaces explícitas
+- **Functional Error Handling**: Either monad ao invés de exceptions
+- **Imutabilidade**: Entities com campos readonly
+- **Separation of Concerns**: Arquitetura em 4 camadas bem definidas
+- **Multi-Tenancy Native**: `companyId` obrigatório em todas operações
+- **Developer Experience**: APIs fluentes, builders, e abstrações intuitivas
+
+---
+
+## 🏗️ Arquitetura em Camadas
+
+O SDK segue uma arquitetura em 4 camadas com responsabilidades claras:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Layer 1: PUBLIC API (src/index.ts, src/useCases/sdk/)         │
+│  • Exports públicos que consumidores do SDK usam                │
+│  • Classe NatyMeta como ponto de entrada principal              │
+│  • Tipos e interfaces exportadas                                │
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 2: USE CASES (src/useCases/)                            │
+│  • Lógica de negócio e orquestração                            │
+│  • Implementam interfaces (IConnection, IMessage, etc.)         │
+│  • Coordenam chamadas entre services e entities                 │
+│  • Gerenciam eventos e estado                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 3: SERVICES (src/services/)                             │
+│  • Comunicação com APIs externas (Meta, Naty backend)          │
+│  • Mutations (CRUD operations)                                  │
+│  • Axios instances e interceptors                               │
+│  • Middlewares e validações                                     │
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 4: DATA & DOMAIN (src/entities/, src/interfaces/)       │
+│  • Domain models (ConnectionEntity, MessageEntity, etc.)        │
+│  • Interfaces que definem contratos                             │
+│  • Types e constantes                                           │
+│  • Message builders (src/elements/)                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Onde cada tipo de código deve residir
+
+| Tipo de Código          | Localização                      | Exemplo                                      |
+| ----------------------- | -------------------------------- | -------------------------------------------- |
+| **CRUD de API externa** | `src/services/mutations/`        | `connectionMutations.getSingle()`            |
+| **Lógica de negócio**   | `src/useCases/`                  | `Connections.getSingle()` com error handling |
+| **Domain models**       | `src/entities/`                  | `ConnectionEntity`, `MessageEntity`          |
+| **Type definitions**    | `src/types/`                     | `WhatsappResponse`, `contactType`            |
+| **Interfaces**          | `src/interfaces/`                | `IConnection`, `IMessage`                    |
+| **Message builders**    | `src/elements/`                  | `Button`, `List`, `Text`                     |
+| **HTTP clients**        | `src/services/axiosInstances.ts` | Factory functions para axios                 |
+| **Utility functions**   | `src/utils/`                     | `genUuid`, `parseError`, `tryCatch`          |
+| **Routes/webhooks**     | `src/routes/`                    | Express route handlers                       |
+| **Error handling**      | `src/errors/`                    | `Either`, `ErrorHandling`                    |
+
+### Fluxo de Dados Típico
+
+```
+User Code
+    ↓
+sdk.connection.getSingle(id)  ← Layer 1: Public API
+    ↓
+Connections.getSingle(id)     ← Layer 2: Use Case (wraps with Try)
+    ↓
+connectionMutations.getSingle ← Layer 3: Service (axios call)
+    ↓
+api.get('/connections')       ← External API
+    ↓
+ConnectionEntity constructor  ← Layer 4: Domain model
+    ↓
+Either<Error, ConnectionEntity> ← Return to user
+```
+
+---
+
+## ⚡ Error Handling Funcional (OBRIGATÓRIO)
+
+### Either Monad Pattern
+
+**REGRA FUNDAMENTAL**: Todas operações assíncronas DEVEM retornar `Either<Error, T>`. NUNCA use `throw`.
+
+#### Definição do Either Type
+
+```typescript
+// src/errors/Either.ts
+export type Either<T, U> =
+  | { isError: T; isSuccess?: never }
+  | { isError?: never; isSuccess: U };
+
+export const throwError = <T>(value: T): { isError: T } => ({ isError: value });
+export const throwSuccess = <U>(value: U): { isSuccess: U } => ({
+  isSuccess: value,
+});
+```
+
+#### Try Wrapper (src/utils/tryCatch.ts)
+
+Use `Try` para envolver qualquer operação que possa falhar:
+
+```typescript
+import { Try } from "../utils/tryCatch";
+
+// ✅ CORRETO
+const result = await Try(connectionMutations.getSingle, connectionId);
+if (result.isError) {
+  console.error("Failed:", result.isError);
+  return;
+}
+const connection = result.isSuccess; // Type-safe!
+```
+
+#### Pattern Completo: Mutation → Use Case → Consumer
+
+**1. Service Layer (Mutation)**
+
+```typescript
+// src/services/mutations/connection.ts
+import { throwError, throwSuccess } from "../../errors";
+import { api } from "../axiosInstances";
+
+export const connectionMutations = {
+  getSingle: async (id: string) => {
+    const { data } = await api.get(`/connections/${id}`);
+    return throwSuccess(new ConnectionEntity(data));
+  },
+};
+```
+
+**2. Use Case Layer**
+
+```typescript
+// src/useCases/connection/index.ts
+import { Try } from "../../utils/tryCatch";
+import { IConnection } from "../../interfaces";
+
+export class Connections implements IConnection {
+  getSingle = async (id: string) => {
+    return Try(connectionMutations.getSingle, id);
+  };
+}
+```
+
+**3. Consumer (User Code)**
+
+```typescript
+const result = await sdk.connection.getSingle(connectionId);
+
+if (result.isError) {
+  // Handle error - result.isError has error details
+  console.error("Failed to get connection:", result.isError);
+  return;
+}
+
+// Type-safe access to success value
+const connection = result.isSuccess;
+console.log("Phone:", connection.phone_number);
+```
+
+### Error Parsing
+
+Use `parseError` para extrair mensagens consistentes:
+
+```typescript
+// src/utils/parseError.ts
+import { parseError } from "../utils";
+
+const result = await someOperation();
+if (result.isError) {
+  const { message, code } = parseError(result.isError, "Operation failed");
+  console.error(`[${code}] ${message}`);
+}
+```
+
+### ❌ ANTI-PATTERNS de Error Handling
+
+```typescript
+// ❌ NUNCA faça isso
+async function badExample() {
+  throw new Error("Something failed"); // ❌ Não use throw
+}
+
+// ❌ NUNCA acesse .isSuccess sem checar .isError
+const result = await operation();
+console.log(result.isSuccess.id); // ❌ Pode crashear!
+
+// ❌ NUNCA use try/catch diretamente (use Try wrapper)
+try {
+  await externalCall();
+} catch (err) {
+  // ❌ Pattern inconsistente
+}
+
+// ✅ CORRETO
+async function goodExample() {
+  const result = await Try(externalOperation);
+  if (result.isError) return throwError(result.isError);
+  return throwSuccess(result.isSuccess);
+}
+```
+
+---
+
+## 📝 Convenções de Código (OBRIGATÓRIAS)
+
+### Naming Conventions
+
+| Tipo                  | Pattern                                       | Exemplos                                     |
+| --------------------- | --------------------------------------------- | -------------------------------------------- |
+| **Entities**          | PascalCase, campos `readonly`                 | `ConnectionEntity`, `MessageEntity`          |
+| **Interfaces**        | `I` prefix + PascalCase                       | `IConnection`, `IMessage`, `IWebhook`        |
+| **Types**             | camelCase + `Type` suffix                     | `contactType`, `flowMessageType`, `btnType`  |
+| **Enums**             | PascalCase para enum, UPPER_CASE para valores | `enum Status { ACTIVE = 'ACTIVE' }`          |
+| **Files (classes)**   | camelCase matching entity name                | `connection.ts`, `messages.ts`               |
+| **Files (utilities)** | camelCase descriptive                         | `tryCatch.ts`, `parseError.ts`, `genUuid.ts` |
+| **Folders**           | camelCase or PascalCase by type               | `useCases/`, `Entities/`, `elements/`        |
+| **Functions**         | camelCase                                     | `getSingle`, `sendMessage`, `updateToken`    |
+| **Constants**         | UPPER_SNAKE_CASE                              | `API_META`, `VERIFY_TOKEN`                   |
+| **Private fields**    | camelCase with `_` prefix                     | `_connection`, `_axiosInstance`              |
+| **Props/Params**      | camelCase                                     | `phoneNumberId`, `accessToken`, `companyId`  |
+
+### File Organization
+
+**Regra: One Class Per File**
+
+```typescript
+// ✅ CORRETO: src/entities/connection.ts
+export class ConnectionEntity {
+  // Single class per file
+}
+
+// ❌ ERRADO: Múltiplas classes no mesmo arquivo
+export class ConnectionEntity {}
+export class MessageEntity {} // ❌ Separar em outro arquivo
+```
+
+**Barrel Exports via index.ts**
+
+```typescript
+// ✅ CORRETO: src/entities/index.ts
+export * from "./connection";
+export * from "./messages";
+export * from "./webhooks";
+export * from "./whatsappMessage";
+
+// Permite imports limpos:
+import { ConnectionEntity, MessageEntity } from "../entities";
+```
+
+### Import Organization
+
+```typescript
+// 1. External dependencies
+import axios from "axios";
+import { EventEmitter } from "events";
+
+// 2. Internal modules (absolute paths via tsconfig)
+import { ConnectionEntity } from "../entities";
+import { Try } from "../utils/tryCatch";
+
+// 3. Types e interfaces
+import type { IConnection, IMessage } from "../interfaces";
+import type { WhatsappResponse } from "../types";
+```
+
+### Function Signatures
+
+**Sempre inclua type annotations explícitas:**
+
+```typescript
+// ✅ CORRETO
+async function getSingle(id: string): Promise<Either<Error, ConnectionEntity>> {
+  return Try(connectionMutations.getSingle, id);
+}
+
+// ✅ CORRETO - Arrow function
+const sendMessage = async (
+  params: SendMessageParams,
+): Promise<Either<Error, WhatsappResponse>> => {
+  return Try(messageMutations.send, params);
+};
+
+// ❌ ERRADO - Sem type annotations
+async function getSingle(id) {
+  // ❌ Tipo inferido
+  return Try(connectionMutations.getSingle, id);
+}
+```
+
+### Entity Fields (Imutabilidade)
+
+**REGRA: Todos campos de entities são `readonly`**
+
+```typescript
+// ✅ CORRETO
+export class ConnectionEntity {
+  readonly _id: string;
+  readonly id: string;
+  readonly companyId: string;
+  readonly phone_number_id: string;
+  readonly waba_id: string;
+  readonly accessToken: string;
+  readonly systemUserAccessToken: string;
+  readonly businessAccountId: string;
+
+  constructor(data: any) {
+    Object.assign(this, data);
+    this.id = data.id || genId("connection");
+  }
+}
+
+// ❌ ERRADO - Campos mutáveis
+export class ConnectionEntity {
+  _id: string; // ❌ Sem readonly
+  companyId: string; // ❌ Permite mutação acidental
+}
+```
+
+### ID Generation Pattern
+
+```typescript
+import { genId } from '../utils';
+
+// ✅ CORRETO - Cada entity type tem seu prefix
+const connectionId = genId("connection");  // → "CONNECTION_a1b2-34567"
+const messageId = genId("message");        // → "MESSAGE_xyz9-12345"
+const webhookId = genId("webhook");        // → "WEBHOOK_def3-98765"
+
+// Entity constructor deve usar genId se ID não fornecido
+constructor(data: any) {
+  Object.assign(this, data);
+  this.id = data.id || genId("connection");  // ✅ Fallback para novo ID
+}
+```
+
+---
+
+## 🎨 Design Patterns do SDK
+
+### 1. Builder Pattern (Message Construction)
+
+Todos os message builders em `src/elements/` usam fluent APIs:
+
+```typescript
+import { List, Button, Text } from "@natyapp/meta/elements";
+
+// ✅ Builder Pattern - Fluent API
+const list = new List()
+  .setBody("Escolha uma opção:")
+  .setButtonText("Ver Menu")
+  .addSection("Produtos")
+  .addItem({
+    id: "prod1",
+    title: "Produto 1",
+    description: "Descrição do produto",
+  })
+  .addItem({ id: "prod2", title: "Produto 2" })
+  .addSection("Serviços")
+  .addItem({ id: "srv1", title: "Serviço A" })
+  .build();
+
+// ✅ Button Builder
+const buttons = new Button()
+  .setBodyText("Mensagem principal")
+  .addButton({ id: "btn1", title: "Opção 1" })
+  .addButton({ id: "btn2", title: "Opção 2" })
+  .build();
+```
+
+**Pattern para criar novos builders:**
+
+```typescript
+// src/elements/newType.ts
+export class NewTypeBuilder {
+  private body: string = "";
+  private items: any[] = [];
+
+  setBody(text: string): this {
+    this.body = text;
+    return this; // ✅ Retorna 'this' para chaining
+  }
+
+  addItem(item: any): this {
+    this.items.push(item);
+    return this;
+  }
+
+  build(): object {
+    // Validação antes de retornar
+    if (!this.body) throw new Error("Body is required");
+
+    return {
+      type: "new_type",
+      body: { text: this.body },
+      items: this.items,
+    };
+  }
+}
+```
+
+### 2. Factory Pattern (Axios Instances)
+
+Diferentes axios instances são criados por factory functions baseado no contexto:
+
+```typescript
+// src/services/axiosInstances.ts
+
+// ✅ Factory para mensagens WhatsApp
+export const newAxiosInstance = ({
+  phone_number_id,
+  accessToken,
+}: AxiosInstanceParams) => {
+  return axios.create({
+    baseURL: `https://graph.facebook.com/v18.0/${phone_number_id}`,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+};
+
+// ✅ Factory para download de media
+export const axiosInstanceForDownloadMedia = ({ accessToken }: TokenParam) => {
+  return axios.create({
+    baseURL: "https://graph.facebook.com/v18.0",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+    responseType: "arraybuffer",
+  });
+};
+
+// ✅ Factory para Facebook token refresh
+export const newFacebookInstance = () => {
+  return axios.create({
+    baseURL: "https://graph.facebook.com/v18.0/oauth",
+    headers: { "Content-Type": "application/json" },
+  });
+};
+```
+
+**REGRA**: Nunca crie axios instances ad-hoc. Use factories existentes ou crie nova factory.
+
+### 3. Event Emitter Pattern (Webhooks)
+
+```typescript
+// src/useCases/events/NatyEvents.ts
+import { EventEmitter } from "events";
+
+export class NatyEvents extends EventEmitter {
+  constructor() {
+    super();
+  }
+
+  emitMessage(data: WhatsappResponse): void {
+    this.emit("message", data);
+  }
+
+  emitConnection(event: connectionEvent): void {
+    this.emit("connection", event);
+  }
+
+  emitError(error: Error): void {
+    this.emit("error", error);
+  }
+}
+
+// ✅ Consumer usage
+sdk.on("message", (data: WhatsappResponse) => {
+  console.log("New message:", data.id);
+});
+
+sdk.on("connection", (event) => {
+  console.log("Connection event:", event.type);
+});
+
+sdk.on("error", (error) => {
+  console.error("SDK error:", error.message);
+});
+```
+
+### 4. Interface Implementation Pattern
+
+**REGRA**: Interfaces definem contratos, classes implementam com Try wrapper
+
+```typescript
+// 1. Definir interface
+// src/interfaces/IConnection.ts
+export interface IConnection {
+  getSingle(id: string): Promise<Either<Error, ConnectionEntity>>;
+  insert(data: ConnectionInsertData): Promise<Either<Error, ConnectionEntity>>;
+  update(
+    id: string,
+    data: ConnectionUpdateData,
+  ): Promise<Either<Error, ConnectionEntity>>;
+}
+
+// 2. Implementar com Try wrapper
+// src/useCases/connection/index.ts
+export class Connections implements IConnection {
+  getSingle = (id: string) => Try(connectionMutations.getSingle, id);
+
+  insert = (data: ConnectionInsertData) =>
+    Try(connectionMutations.insert, data);
+
+  update = (id: string, data: ConnectionUpdateData) =>
+    Try(connectionMutations.update, id, data);
+}
+```
+
+---
+
+## 🌐 Regras de Negócio WhatsApp
+
+### 1. Janela de 24 Horas
+
+**REGRA CRÍTICA**: Mensagens free-form só podem ser enviadas dentro de 24h da última mensagem do cliente.
+
+```typescript
+// Fora da janela de 24h: OBRIGATÓRIO usar template
+const result = await sdk.message.send_text_template({
+  companyId,
+  to: phoneNumber,
+  template: {
+    name: "hello_world",
+    language: { code: "pt_BR" },
+  },
+});
+
+// Dentro da janela: Pode usar mensagem livre
+const result = await sdk.message.send_text_message({
+  companyId,
+  to: phoneNumber,
+  bodyText: "Mensagem personalizada",
+});
+```
+
+### 2. Multi-Tenancy (companyId OBRIGATÓRIO)
+
+**REGRA**: TODO método que acessa dados DEVE receber `companyId` para isolamento de tenant.
+
+```typescript
+// ✅ CORRETO - companyId presente
+await sdk.connection.getSingle(connectionId, { companyId });
+
+await sdk.message.send_text_message({
+  companyId, // ✅ Obrigatório
+  to: phoneNumber,
+  bodyText: "Hello",
+});
+
+// ❌ ERRADO - Esqueceu companyId
+await sdk.connection.getSingle(connectionId); // ❌ Faltando companyId
+```
+
+**Pattern em mutations:**
+
+```typescript
+// src/services/mutations/connection.ts
+export const connectionMutations = {
+  getSingle: async (id: string, companyId?: string) => {
+    const params = companyId ? { companyId } : {};
+    const { data } = await api.get(`/connections/${id}`, { params });
+    return throwSuccess(new ConnectionEntity(data));
+  },
+};
+```
+
+### 3. Token Refresh Automático
+
+**REGRA**: SDK gerencia refresh automático. Ao criar `WhatsappResponse`, token é renovado se necessário.
+
+```typescript
+// src/useCases/message/whatsappResponse.ts
+export class WhatsappResponse {
+  private async getApiInstanceToken() {
+    // 1. Busca connection
+    const result = await this.getConnection({
+      companyId: this.companyId,
+      phoneNumberId: this.phone_number_id,
+    });
+
+    if (result.isError) return result.isError;
+
+    // 2. Exchange para long-lived token se necessário
+    const connection = result.isSuccess;
+    const tokenResult = await this.exchangeForLongLivedToken(connection);
+
+    // 3. Atualiza no banco
+    await this.updateConnectionToken(connection.id, tokenResult.access_token);
+
+    // 4. Cria axios instance com token atualizado
+    this._axiosInstance = newAxiosInstance({
+      phone_number_id: this.phone_number_id,
+      accessToken: tokenResult.access_token,
+    });
+  }
+}
+```
+
+### 4. Formato de Phone Number
+
+**REGRA**: Sempre use formato E.164 (`+5511999999999`)
+
+```typescript
+// ✅ CORRETO - E.164 format
+const phoneNumber = "+5511987654321";
+
+// ❌ ERRADO - Formatos inválidos
+const phoneNumber = "11987654321"; // ❌ Sem código do país
+const phoneNumber = "(11) 98765-4321"; // ❌ Formatação
+```
+
+**Nota**: SDK não valida formato. Aplicação consumidora é responsável pela validação.
+
+### 5. Webhook Deduplication
+
+**REGRA**: Use `message.id` para evitar processar duplicatas (Meta pode enviar o mesmo webhook múltiplas vezes).
+
+```typescript
+// ✅ CORRETO - Deduplicação com Set/Cache
+const processedIds = new Set<string>();
+
+sdk.on("message", async (data: WhatsappResponse) => {
+  if (processedIds.has(data.id)) {
+    console.log("Duplicate webhook ignored:", data.id);
+    return;
+  }
+
+  processedIds.add(data.id);
+
+  // Processar mensagem...
+});
+```
+
+### 6. Rate Limits Meta (Informativo)
+
+| Tier   | Limite Diário | Obs                  |
+| ------ | ------------- | -------------------- |
+| Tier 1 | 1,000 msgs    | Conta nova           |
+| Tier 2 | 10,000 msgs   | Após verificação     |
+| Tier 3 | 100,000 msgs  | Volume alto aprovado |
+
+**SDK não implementa throttling**. Aplicação consumidora deve gerenciar rate limits se necessário.
+
+---
+
+## 🔧 Guidelines de Integração
+
+### Criar Nova Mutation
+
+```typescript
+// 1. Adicionar em src/services/mutations/messages.ts
+export const messageMutations = {
+  // ... existing mutations
+
+  deleteMessage: async (messageId: string, companyId: string) => {
+    const { data } = await api.delete(`/messages/${messageId}`, {
+      params: { companyId },
+    });
+    return throwSuccess(data);
+  },
+};
+```
+
+### Criar Novo Use Case
+
+```typescript
+// 2. Adicionar método na interface src/interfaces/IMessage.ts
+export interface IMessage {
+  // ... existing methods
+  deleteMessage(
+    messageId: string,
+    companyId: string,
+  ): Promise<Either<Error, any>>;
+}
+
+// 3. Implementar em src/useCases/messages/index.ts
+export class Messages implements IMessage {
+  // ... existing methods
+
+  deleteMessage = (messageId: string, companyId: string) =>
+    Try(messageMutations.deleteMessage, messageId, companyId);
+}
+
+// 4. Se for public API, adicionar no SDK principal
+// src/useCases/sdk/index.ts
+export class NatyMeta extends NatyEvents {
+  message: IMessage;
+
+  constructor() {
+    super();
+    this.message = new Messages();
+  }
+}
+```
+
+### Estender Entity
+
+```typescript
+// 1. Adicionar campo em src/entities/connection.ts
+export class ConnectionEntity {
+  // ... existing readonly fields
+  readonly newField: string; // ✅ Sempre readonly
+  readonly createdAt?: Date;
+
+  constructor(data: any) {
+    Object.assign(this, data);
+    this.id = data.id || genId("connection");
+
+    // ✅ Transformações no constructor
+    if (data.createdAt) {
+      this.createdAt = new Date(data.createdAt);
+    }
+  }
+}
+
+// 2. Atualizar interface se necessário
+// src/interfaces/IConnection.ts
+export interface IConnectionData {
+  // ... existing fields
+  newField?: string;
+  createdAt?: string | Date;
+}
+```
+
+### Criar Novo Message Builder
+
+```typescript
+// src/elements/carousel.ts
+export class Carousel {
+  private header: string = "";
+  private cards: any[] = [];
+
+  setHeader(text: string): this {
+    this.header = text;
+    return this;
+  }
+
+  addCard(card: { title: string; body: string; image?: string }): this {
+    this.cards.push(card);
+    return this;
+  }
+
+  build(): object {
+    if (!this.header) throw new Error("Header is required");
+    if (this.cards.length === 0) throw new Error("At least one card required");
+
+    return {
+      type: "carousel",
+      header: { text: this.header },
+      cards: this.cards,
+    };
+  }
+}
+
+// Exportar em src/elements/index.ts
+export * from "./carousel";
+```
+
+### Configurar Axios Interceptor
+
+```typescript
+// src/configs/axiosInterceptors.ts
+
+// ✅ Adicionar novo header globalmente
+export const updateInterceptor = (headers: Record<string, string>) => {
+  Object.assign(configInterceptors, headers);
+};
+
+// Usage:
+updateInterceptor({
+  "x-access-token": appToken,
+  "x-custom-header": "value",
+});
+```
+
+---
+
+## 🧪 Testing Guidelines
+
+### Configuração
+
+```javascript
+// jest.config.js
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/*.spec.ts", "**/*.test.ts"],
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"],
+};
+```
+
+### Naming Conventions
+
+- Test files: `*.spec.ts` ou `*.test.ts`
+- Location: `Tests/` folder ou colocated com source
+- Suite: `describe('EntityName ou functionName', () => {})`
+- Cases: `it('should do something specific', () => {})`
+
+### Testes de Either Returns
+
+```typescript
+// Tests/entities/connection.spec.ts
+import { Connections } from "../../src/useCases/connection";
+import { ConnectionEntity } from "../../src/Entities";
+
+describe("Connections", () => {
+  let connections: Connections;
+
+  beforeEach(() => {
+    connections = new Connections();
+  });
+
+  it("should return ConnectionEntity on success", async () => {
+    const result = await connections.getSingle("CONNECTION_123");
+
+    expect(result.isError).toBeUndefined();
+    expect(result.isSuccess).toBeDefined();
+    expect(result.isSuccess).toBeInstanceOf(ConnectionEntity);
+    expect(result.isSuccess?.id).toBe("CONNECTION_123");
+  });
+
+  it("should return error on failure", async () => {
+    const result = await connections.getSingle("INVALID_ID");
+
+    expect(result.isSuccess).toBeUndefined();
+    expect(result.isError).toBeDefined();
+    expect(result.isError).toHaveProperty("message");
+  });
+});
+```
+
+### Mocking External APIs
+
+```typescript
+// ✅ Mock axios
+jest.mock("../../src/services/axiosInstances", () => ({
+  api: {
+    get: jest.fn(),
+    post: jest.fn(),
+    put: jest.fn(),
+    delete: jest.fn(),
+  },
+}));
+
+import { api } from "../../src/services/axiosInstances";
+
+describe("ConnectionMutations", () => {
+  it("should call API with correct params", async () => {
+    const mockData = { id: "CONNECTION_123", phone_number_id: "123456" };
+    (api.get as jest.Mock).mockResolvedValue({ data: mockData });
+
+    const result = await connectionMutations.getSingle("CONNECTION_123");
+
+    expect(api.get).toHaveBeenCalledWith("/connections/CONNECTION_123");
+    expect(result.isSuccess).toEqual(expect.objectContaining(mockData));
+  });
+});
+```
+
+### Testing Builders
+
+```typescript
+describe("List Builder", () => {
+  it("should build valid list structure", () => {
+    const list = new List()
+      .setBody("Choose option")
+      .setButtonText("Select")
+      .addSection("Section 1")
+      .addItem({ id: "item1", title: "Item 1" })
+      .build();
+
+    expect(list).toHaveProperty("type", "list");
+    expect(list).toHaveProperty("body");
+    expect(list).toHaveProperty("action.button", "Select");
+    expect(list).toHaveProperty("action.sections");
+    expect(list.action.sections).toHaveLength(1);
+  });
+
+  it("should throw error if required fields missing", () => {
+    expect(() => {
+      new List().build(); // Missing body
+    }).toThrow();
+  });
+});
+```
+
+---
+
+## ❌ Anti-Patterns (EVITAR)
+
+### Error Handling
+
+```typescript
+// ❌ NUNCA use throw diretamente
+function badFunction() {
+  if (error) throw new Error("Failed");
+}
+
+// ✅ USE Either
+function goodFunction() {
+  if (error) return throwError(new Error("Failed"));
+  return throwSuccess(data);
+}
+
+// ❌ NUNCA acesse .isSuccess sem checar .isError
+const result = await operation();
+console.log(result.isSuccess.id); // ❌ Crashea se houver erro!
+
+// ✅ SEMPRE cheque primeiro
+if (result.isError) return;
+console.log(result.isSuccess.id); // ✅ Type-safe
+
+// ❌ NUNCA use try/catch direto (use Try wrapper)
+try {
+  await externalCall();
+} catch (err) {
+  // ❌ Inconsistente
+}
+
+// ✅ USE Try wrapper
+const result = await Try(externalCall);
+if (result.isError) {
+  /* handle */
+}
+```
+
+### Mutabilidade
+
+```typescript
+// ❌ NUNCA mute entities
+connection.phone_number_id = "new_value"; // ❌ Fields são readonly
+
+// ✅ Crie nova instância
+const updated = new ConnectionEntity({
+  ...connection,
+  phone_number_id: "new_value",
+});
+```
+
+### Axios Instances
+
+```typescript
+// ❌ NUNCA crie axios ad-hoc
+const api = axios.create({ baseURL: "..." }); // ❌ Inconsistente
+
+// ✅ USE factories
+const api = newAxiosInstance({ phone_number_id, accessToken });
+```
+
+### Multi-Tenancy
+
+```typescript
+// ❌ NUNCA esqueça companyId
+await connection.getSingle(id); // ❌ Quebra isolamento
+
+// ✅ SEMPRE inclua companyId
+await connection.getSingle(id, { companyId });
+```
+
+### Imports
+
+```typescript
+// ❌ NUNCA importe tudo
+import * as everything from "./module"; // ❌ Poluição de namespace
+
+// ✅ Seja específico
+import { ConnectionEntity, MessageEntity } from "./entities";
+```
+
+### Hardcoding
+
+```typescript
+// ❌ NUNCA hardcode URLs ou tokens
+const url = "https://graph.facebook.com/v18.0"; // ❌
+
+// ✅ USE variáveis de ambiente
+const url = process.env.META_API_URL || "https://graph.facebook.com/v18.0";
+```
+
+---
+
+## 📚 Exemplos Completos End-to-End
+
+### Exemplo 1: Criar Método para Enviar Reação a Mensagem
+
+**Objetivo**: Adicionar funcionalidade `send_reaction` para reagir a mensagens.
+
+#### Passo 1: Criar Mutation
+
+```typescript
+// src/services/mutations/messages.ts
+export const messageMutations = {
+  // ... existing methods
+
+  sendReaction: async (params: {
+    phone_number_id: string;
+    accessToken: string;
+    to: string;
+    message_id: string;
+    emoji: string;
+  }) => {
+    const axiosInstance = newAxiosInstance({
+      phone_number_id: params.phone_number_id,
+      accessToken: params.accessToken,
+    });
+
+    const payload = {
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to: params.to,
+      type: "reaction",
+      reaction: {
+        message_id: params.message_id,
+        emoji: params.emoji,
+      },
+    };
+
+    const { data } = await axiosInstance.post("/messages", payload);
+    return throwSuccess(data);
+  },
+};
+```
+
+#### Passo 2: Adicionar Interface
+
+```typescript
+// src/interfaces/IMessage.ts
+export interface IMessage {
+  // ... existing methods
+
+  send_reaction(params: {
+    companyId: string;
+    to: string;
+    message_id: string;
+    emoji: string;
+  }): Promise<Either<Error, any>>;
+}
+```
+
+#### Passo 3: Implementar Use Case
+
+```typescript
+// src/useCases/messages/index.ts
+export class Messages implements IMessage {
+  // ... existing methods
+
+  send_reaction = async (params: {
+    companyId: string;
+    to: string;
+    message_id: string;
+    emoji: string;
+  }) => {
+    // 1. Obter connection
+    const connectionResult = await this.getConnection({
+      companyId: params.companyId,
+      to: params.to,
+    });
+
+    if (connectionResult.isError) return connectionResult;
+    const connection = connectionResult.isSuccess;
+
+    // 2. Chamar mutation com Try wrapper
+    return Try(messageMutations.sendReaction, {
+      phone_number_id: connection.phone_number_id,
+      accessToken: connection.accessToken,
+      to: params.to,
+      message_id: params.message_id,
+      emoji: params.emoji,
+    });
+  };
+}
+```
+
+#### Passo 4: Usar na Aplicação
+
+```typescript
+// Consumer code
+const result = await sdk.message.send_reaction({
+  companyId: "COMPANY_123",
+  to: "+5511987654321",
+  message_id: "wamid.HBgLNT...",
+  emoji: "👍",
+});
+
+if (result.isError) {
+  console.error("Failed to send reaction:", result.isError);
+  return;
+}
+
+console.log("Reaction sent:", result.isSuccess);
+```
+
+### Exemplo 2: Criar Handler para Novo Tipo de Webhook
+
+**Objetivo**: Adicionar handler para eventos de status de mensagem.
+
+#### Passo 1: Criar Route Handler
+
+```typescript
+// src/routes/webhooks/methods/messageStatus.ts
+import { Request, Response } from "express";
+import { NatyEvents } from "../../../useCases/events/NatyEvents";
+
+export const messageStatusHandler = (events: NatyEvents) => {
+  return async (req: Request, res: Response) => {
+    try {
+      const { entry } = req.body;
+
+      for (const change of entry[0].changes) {
+        const { statuses } = change.value;
+
+        if (!statuses) continue;
+
+        for (const status of statuses) {
+          // Emitir evento
+          events.emit("message_status", {
+            id: status.id,
+            status: status.status, // sent, delivered, read
+            timestamp: status.timestamp,
+            recipient_id: status.recipient_id,
+          });
+        }
+      }
+
+      res.sendStatus(200);
+    } catch (error) {
+      console.error("Message status webhook error:", error);
+      res.sendStatus(500);
+    }
+  };
+};
+```
+
+#### Passo 2: Registrar Route
+
+```typescript
+// src/routes/webhooks/index.ts
+import { messageStatusHandler } from "./methods/messageStatus";
+
+export const setupWebhookRoutes = (app: Express, events: NatyEvents) => {
+  // ... existing routes
+
+  app.post("/webhooks/message-status", messageStatusHandler(events));
+};
+```
+
+#### Passo 3: Adicionar Type
+
+```typescript
+// src/types/whatsappTypes.ts
+export type MessageStatusEvent = {
+  id: string;
+  status: "sent" | "delivered" | "read" | "failed";
+  timestamp: string;
+  recipient_id: string;
+};
+```
+
+#### Passo 4: Usar na Aplicação
+
+```typescript
+// Consumer code
+sdk.on("message_status", (event: MessageStatusEvent) => {
+  console.log(`Message ${event.id} is now ${event.status}`);
+
+  // Atualizar status no banco de dados
+  if (event.status === "read") {
+    markAsRead(event.id);
+  }
+});
+```
+
+### Exemplo 3: Estender ConnectionEntity com Metadata
+
+**Objetivo**: Adicionar campo `metadata` para dados customizados.
+
+#### Passo 1: Atualizar Entity
+
+```typescript
+// src/entities/connection.ts
+export class ConnectionEntity {
+  // ... existing readonly fields
+  readonly metadata?: Record<string, any>; // ✅ Novo campo
+
+  constructor(data: any) {
+    Object.assign(this, data);
+    this.id = data.id || genId("connection");
+
+    // ✅ Parse metadata se for string
+    if (typeof data.metadata === "string") {
+      try {
+        this.metadata = JSON.parse(data.metadata);
+      } catch {
+        this.metadata = {};
+      }
+    }
+  }
+}
+```
+
+#### Passo 2: Atualizar Interface
+
+```typescript
+// src/interfaces/IConnection.ts
+export interface IConnectionData {
+  // ... existing fields
+  metadata?: Record<string, any>;
+}
+
+export interface IConnection {
+  // ... existing methods
+
+  updateMetadata(
+    id: string,
+    metadata: Record<string, any>,
+    companyId: string,
+  ): Promise<Either<Error, ConnectionEntity>>;
+}
+```
+
+#### Passo 3: Adicionar Mutation
+
+```typescript
+// src/services/mutations/connection.ts
+export const connectionMutations = {
+  // ... existing methods
+
+  updateMetadata: async (
+    id: string,
+    metadata: Record<string, any>,
+    companyId: string,
+  ) => {
+    const { data } = await api.put(
+      `/connections/${id}`,
+      { metadata },
+      { params: { companyId } },
+    );
+    return throwSuccess(new ConnectionEntity(data));
+  },
+};
+```
+
+#### Passo 4: Implementar Use Case
+
+```typescript
+// src/useCases/connection/index.ts
+export class Connections implements IConnection {
+  // ... existing methods
+
+  updateMetadata = (
+    id: string,
+    metadata: Record<string, any>,
+    companyId: string,
+  ) => Try(connectionMutations.updateMetadata, id, metadata, companyId);
+}
+```
+
+#### Passo 5: Usar na Aplicação
+
+```typescript
+// Consumer code
+const result = await sdk.connection.updateMetadata(
+  "CONNECTION_123",
+  {
+    department: "Sales",
+    responsible: "john@company.com",
+    custom_field: "value",
+  },
+  "COMPANY_456",
+);
+
+if (result.isError) {
+  console.error("Failed to update metadata:", result.isError);
+  return;
+}
+
+console.log("Metadata updated:", result.isSuccess.metadata);
+```
+
+---
+
+## 📖 Referências à Documentação
+
+### Documentação Principal
+
+- [Visão Geral](../docs/01-visao-geral.md) - Propósito e escopo do SDK
+- [Contexto de Negócio](../docs/02-contexto-negocio.md) - Domínio WhatsApp Business
+- [Arquitetura](../docs/03-arquitetura.md) - Detalhes das 4 camadas
+- [Fluxos Funcionais](../docs/04-fluxos-funcionais.md) - Sequências de operações
+- [Integrações](../docs/05-integracoes.md) - APIs externas (Meta, Naty)
+- [Entidades](../docs/06-entidades.md) - Domain models documentados
+- [Guia Prático](../docs/07-guia-pratico.md) - Exemplos de uso
+- [Troubleshooting](../docs/08-troubleshooting.md) - Problemas comuns
+
+### Arquivos Chave de Referência
+
+- [src/index.ts](../src/index.ts) - API pública exportada
+- [src/interfaces/ISdk.ts](../src/interfaces/ISdk.ts) - Contrato principal do SDK
+- [src/errors/Either.ts](../src/errors/Either.ts) - Implementação do Either monad
+- [src/utils/tryCatch.ts](../src/utils/tryCatch.ts) - Try wrapper
+- [src/useCases/sdk/index.ts](../src/useCases/sdk/index.ts) - Classe NatyMeta
+- [tsconfig.json](../tsconfig.json) - Configuração TypeScript
+- [jest.config.js](../jest.config.js) - Configuração de testes
+
+---
+
+## 🎯 Checklist para Novos Desenvolvedores
+
+Ao contribuir com o SDK, verifique:
+
+- [ ] Todos métodos async retornam `Either<Error, T>`
+- [ ] Usou `Try` wrapper ao invés de try/catch
+- [ ] Entities têm campos `readonly`
+- [ ] Incluiu `companyId` em todas operações que acessam dados
+- [ ] Nomes seguem convenções (interfaces com `I`, types com `Type`, etc.)
+- [ ] Criou barrel export (`index.ts`) se adicionou novo módulo
+- [ ] Usou factory para axios instances (não criou ad-hoc)
+- [ ] Builders usam fluent API (retornam `this`)
+- [ ] Adicionou type annotations explícitas
+- [ ] Testou com Jest (coverage > 70%)
+- [ ] Documentou parâmetros complexos com JSDoc
+- [ ] Validou formato E.164 se aceita phone numbers (ou documentou)
+- [ ] Tratou casos de erro com parseError
+- [ ] Evitou hardcode de URLs/tokens (usou env vars)
+
+---
+
+## 🚀 Comandos Úteis
+
+```bash
+# Desenvolvimento
+npm run dev       # Inicia com nodemon (hot reload)
+
+# Build
+npm run build     # Compila TypeScript para dist/
+
+# Testes
+npm run test      # Executa Jest em watch mode
+npm run test:ci   # Executa testes uma vez (CI/CD)
+
+# Linting
+npm run lint      # ESLint check
+npm run lint:fix  # ESLint auto-fix
+
+# Type Check
+npm run type-check  # TypeScript compiler check (sem emitir arquivos)
+```
+
+---
+
+## � Logging Guidelines
+
+### Logger Integration
+
+O SDK suporta logging configurável via injeção de dependência. Um logger customizado pode ser fornecido ao inicializar o SDK, caso contrário, um console logger padrão é usado.
+
+#### Logger Interface
+
+```typescript
+// src/interfaces/ILogger.ts
+export interface ILogger {
+  log(
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    meta?: Record<string, any>,
+  ): void;
+}
+```
+
+#### Onde Usar Logger
+
+| Contexto               | Nível | Quando Usar                                       |
+| ---------------------- | ----- | ------------------------------------------------- |
+| **SDK Initialization** | info  | NatyMeta constructor, connect()                   |
+| **HTTP Requests**      | debug | Axios interceptors (automático)                   |
+| **HTTP Responses**     | debug | Axios interceptors (automático)                   |
+| **HTTP Errors**        | error | Axios interceptors (automático)                   |
+| **Token Refresh**      | info  | WhatsappResponse.getApiInstanceToken()            |
+| **Message Sent**       | info  | Após envio bem-sucedido (send_text_message, etc.) |
+| **Message Failed**     | error | Catch blocks em métodos de envio                  |
+| **Webhook Received**   | info  | Webhook handlers (messages, connection)           |
+| **Webhook Error**      | error | Catch blocks em webhook handlers                  |
+| **Event Emitted**      | debug | NatyEvents.emit()                                 |
+| **Operation Failed**   | error | Try wrapper catch block                           |
+
+#### Padrões de Uso
+
+```typescript
+// ✅ CORRETO - Info para operações principais
+this.logger.log("info", "Sending text message", {
+  to: this.clientNumber,
+  textLength: text.length,
+});
+
+// ✅ CORRETO - Debug para detalhes técnicos
+this.logger.log("debug", "HTTP Request", {
+  method: "POST",
+  url: "/messages",
+  hasData: true,
+});
+
+// ✅ CORRETO - Error com contexto útil
+this.logger.log("error", "Failed to send message", {
+  to: this.clientNumber,
+  error: err.message,
+  code: err.code,
+});
+
+// ❌ ERRADO - Logging sem contexto
+this.logger.log("error", "Error occurred");
+
+// ❌ ERRADO - Expor dados sensíveis
+this.logger.log("debug", "Token", {
+  accessToken: token, // ❌ Nunca logue tokens
+});
+```
+
+#### Segurança
+
+**REGRA**: Nunca logue dados sensíveis diretamente. Use sanitização:
+
+```typescript
+// ✅ CORRETO - Headers sanitizados
+function sanitizeHeaders(headers: any): any {
+  const sanitized = { ...headers };
+  if (sanitized.Authorization) {
+    sanitized.Authorization = "Bearer [REDACTED]";
+  }
+  if (sanitized["x-access-token"]) {
+    sanitized["x-access-token"] = "[REDACTED]";
+  }
+  return sanitized;
+}
+
+logger.log("debug", "HTTP Request", {
+  headers: sanitizeHeaders(config.headers),
+});
+```
+
+#### Acesso ao Logger
+
+**Context Global:**
+
+```typescript
+import { getGlobalLogger } from "../utils/loggerContext";
+
+const logger = getGlobalLogger();
+logger.log("info", "Operation started");
+```
+
+**Injetado via Constructor:**
+
+```typescript
+export class WhatsappResponse {
+  private logger: ILogger;
+
+  constructor(..., logger?: ILogger) {
+    this.logger = logger || getGlobalLogger();
+  }
+}
+```
+
+#### Criando Adapter para Logger Externo
+
+```typescript
+// Exemplo: Adapter para Pino
+export function createPinoAdapter(pinoLogger: any): ILogger {
+  return {
+    log(level, message, meta) {
+      if (meta) {
+        pinoLogger[level](meta, message);
+      } else {
+        pinoLogger[level](message);
+      }
+    },
+  };
+}
+```
+
+#### Best Practices
+
+1. **Use níveis apropriados**:
+   - `debug`: Detalhes técnicos (HTTP, tokens refresh, state changes)
+   - `info`: Operações principais (mensagens enviadas, webhooks recebidos)
+   - `warn`: Situações anormais mas não críticas
+   - `error`: Falhas que impedem operação
+
+2. **Inclua contexto útil**:
+   - IDs relevantes (`companyId`, `messageId`, `connectionId`)
+   - Parâmetros de entrada (sanitizados)
+   - Estado relevante antes/depois
+   - Stack trace em errors (via meta)
+
+3. **Evite noise excessivo**:
+   - Não logue em loops high-frequency
+   - Use `debug` para logs verbose
+   - Considere sampling para operações muito frequentes
+
+4. **Estruture metadata consistentemente**:
+
+   ```typescript
+   // ✅ CORRETO - Estrutura consistente
+   logger.log("info", "Message sent", {
+     operation: "send_message",
+     to: phoneNumber,
+     messageType: "text",
+     messageId: response.id,
+     duration: Date.now() - startTime,
+   });
+   ```
+
+5. **Logger é opcional**: SDK deve funcionar sem logger customizado (fallback para console)
+
+---
+
+## �💡 Dicas Finais
+
+1. **Leia a documentação em docs/** antes de fazer mudanças significativas
+2. **Consulte código existente** para entender patterns na prática
+3. **Either é obrigatório** - não há exceções a essa regra
+4. **Multi-tenancy é crítico** - nunca esqueça companyId
+5. **Imutabilidade ajuda debug** - entities readonly previnem bugs sutis
+6. **Type safety é seu amigo** - não use `any` sem justificativa forte
+7. **Teste seus changes** - Jest deve passar em todos os casos
+8. **Documente APIs públicas** - JSDoc para parâmetros não óbvios
+
+---
+
+**Versão**: 1.0.0  
+**Última Atualização**: Fevereiro 2026  
+**Mantido por**: Time @natyapp/meta