@horizon-framework/automations-nextjs-docs 2.3.2

package/docs/ARQUITETURA.md

@@ -0,0 +1,85 @@
+# Horizon Automations — Arquitetura
+
+> Como funciona o projeto de automacoes do Horizon.
+> Recebe leads, envia pra canais (email, CRMs), processa integrações.
+
+---
+
+## Estrutura
+
+```
+apps/automations/src/
+├── app/api/
+│   ├── health/route.ts         ← Healthcheck
+│   └── leads/route.ts          ← Orquestrador (recebe lead, envia pros canais)
+│
+├── core/                        ← MOTORES (logica reutilizavel)
+│   └── email-engine/            ← Motor de email (Resend + React Email)
+│       ├── service.ts           ← sendEmail() generico
+│       └── types.ts
+│
+├── channels/                    ← CANAIS DE ENVIO (implementacoes)
+│   ├── email/                   ← Canal: email
+│   │   ├── templates/
+│   │   │   └── lead-form-generic/  ← Template de lead por email
+│   │   └── recipients.json      ← Destinatarios
+│   ├── si9/                     ← Canal: CRM SI9
+│   │   └── sender.ts           ← Usa SDK @horizon-integrations/si9-crm
+│   └── jetimob/                 ← Canal: CRM Jetimob
+│       └── sender.ts           ← Usa SDK @horizon-integrations/jetimob-crm
+│
+└── config/                      ← CONFIGURACAO
+    └── channels.ts              ← Ligar/desligar canais
+```
+
+---
+
+## Fluxo
+
+```
+Frontend envia POST /api/leads
+  ↓
+route.ts (orquestrador)
+  ↓ Verifica config/channels.ts (quais canais estao ativos)
+  ↓ Envia em PARALELO pra todos os canais ativos
+  ↓
+channels/email/     → Envia email com template formatado
+channels/si9/       → Envia lead pro CRM SI9 via SDK
+channels/jetimob/   → Envia lead pro CRM Jetimob via SDK
+  ↓
+Retorna resultado combinado
+```
+
+---
+
+## Camadas
+
+| Camada | O que faz | Onde fica |
+|---|---|---|
+| **route.ts** | Recebe lead, valida, orquestra canais | app/api/leads/ |
+| **core/** | Motores reutilizaveis (email engine) | core/ |
+| **channels/** | Implementacao de cada destino | channels/{nome}/ |
+| **config/** | Liga/desliga canais | config/ |
+
+---
+
+## Princípios
+
+1. **Cada canal e independente** — ligar/desligar no config sem mexer no codigo
+2. **Canais rodam em paralelo** — Promise.all, um nao bloqueia outro
+3. **Se um canal falha, os outros continuam** — erro e logado mas nao bloqueia
+4. **SDK do CRM e agnóstica** — nao sabe de Horizon. O channel faz o mapeamento
+5. **Lead-core e a fonte de verdade** — tipos e adapter vem do @horizon-framework/lead-core
+
+---
+
+## Pacotes usados
+
+| Pacote | Pra que |
+|---|---|
+| @horizon-framework/lead-core | Tipos de lead, adapter generico |
+| @horizon-modules/property-automations | Adapter de lead de imovel |
+| @horizon-integrations/si9-crm | SDK do SI9 (sendLead) |
+| @horizon-integrations/jetimob-crm | SDK do Jetimob |
+| resend | Motor de envio de email |
+| @react-email/components | Templates de email em React |

package/docs/COMO_ADICIONAR_CANAL.md

@@ -0,0 +1,103 @@
+# Como Adicionar um Novo Canal de Envio de Leads
+
+> Guia passo a passo para criar um novo canal (CRM, webhook, n8n, etc.)
+
+---
+
+## Passo 1: Criar pasta do canal
+
+```
+channels/
+└── meu-crm/
+    └── sender.ts
+```
+
+## Passo 2: Implementar sender.ts
+
+```typescript
+/**
+ * Canal: Meu CRM
+ * Envia leads para a API do Meu CRM
+ */
+
+import { sendLead } from "@horizon-integrations/meu-crm"
+// OU se nao tem SDK:
+// import fetch...
+
+interface SendResult {
+  success: boolean;
+  platform: string;
+  error?: string;
+}
+
+interface SendParams {
+  subject?: string;
+  data: any;  // FormDataInput do lead
+  meta?: any; // FormMeta
+}
+
+export async function sendToMeuCRM(params: SendParams): Promise<SendResult> {
+  try {
+    // 1. Extrair campos do lead
+    // Usar adaptGenericLead() do lead-core ou adaptPropertyLead() do property-automations
+
+    // 2. Enviar pra API do CRM
+    const result = await sendLead({ ... }, credentials)
+
+    // 3. Retornar resultado
+    return { success: true, platform: "meu-crm" }
+  } catch (error) {
+    return { success: false, platform: "meu-crm", error: error.message }
+  }
+}
+```
+
+## Passo 3: Registrar no config
+
+```typescript
+// config/channels.ts
+export const LEAD_CHANNELS = {
+  email: { enabled: true, name: "Email" },
+  jetimob: { enabled: true, name: "Jetimob CRM" },
+  si9: { enabled: true, name: "SI9 CRM" },
+  meuCrm: { enabled: true, name: "Meu CRM" },  // NOVO
+};
+```
+
+## Passo 4: Integrar na rota
+
+```typescript
+// app/api/leads/route.ts
+import { sendToMeuCRM } from "@/channels/meu-crm/sender";
+
+// Dentro do POST handler:
+if (LEAD_CHANNELS.meuCrm.enabled) {
+  channelNames.push("meuCrm");
+  promises.push(sendToMeuCRM({ subject, data, meta }));
+}
+```
+
+## Passo 5: Configurar env vars
+
+Adicionar no `.env.local`:
+```
+MEU_CRM_API_KEY=xxx
+MEU_CRM_SECRET=xxx
+```
+
+## Passo 6: Testar
+
+1. Levantar automations: `pnpm dev`
+2. Enviar lead de teste via curl ou formulario
+3. Verificar logs: `[Leads API] meuCrm: OK`
+4. Verificar no painel do CRM se o lead chegou
+
+---
+
+## Dicas
+
+- Use `adaptGenericLead()` do lead-core pra extrair campos base
+- Use `adaptPropertyLead()` do property-automations se o lead e de imovel
+- Use `extraFieldsToText()` pra concatenar extras num campo de texto
+- Se o CRM tem SDK (@horizon-integrations/*), use. Se nao, faca fetch direto
+- NUNCA hardcode credentials — sempre via env vars

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@horizon-framework/automations-nextjs-docs",
+  "version": "2.3.2",
+  "description": "Documentacao do projeto Horizon Automations — arquitetura de channels, leads, integracoes",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}