@horizon-js/lead-core

Tipagem universal, adapter genérico e toolkit de leads para a plataforma Horizon.

Define o padrão de como leads funcionam em toda a plataforma: Frontend (forms) → Automations (channels) → CRMs (SDKs).

O que faz

• Tipos universais — HorizonLeadBaseFields, consent, origin, UTM, extras por domínio
• Adapter — adaptGenericLead() normaliza dados brutos de formulário pro formato padrão
• Papa-tudo — campos desconhecidos vão pra extra_fields automaticamente (NUNCA perde dados)
• Observation Builder — buildObservation() monta texto formatado pra CRMs com seções de dados + metadados
• Aliases — aceita telefone, mensagem, nome etc. e resolve pra keys padrão

Instalação

pnpm add @horizon-js/lead-core

Uso rápido

Normalizar dados de formulário

import { adaptGenericLead } from "@horizon-js/lead-core"

const lead = adaptGenericLead(formData, formMeta)

// lead.name, lead.email, lead.phone, lead.message
// lead.consent.contact, lead.consent.timestamp
// lead.origin.form_id, lead.origin.page_url
// lead.utm.source, lead.utm.campaign
// lead.extra_fields = { "Tipo do Imóvel": "Casa", "Dormitórios": "3" }

Aceita dados em array flat ou objeto agrupado:

// Array flat
const data = [
  { key: "name", label: "Nome", value: "João", type: "text" },
  { key: "email", label: "E-mail", value: "[email protected]", type: "email" },
]

// Objeto agrupado (seções)
const data = {
  "Dados do Imóvel": [
    { key: "tipo", label: "Tipo", value: "Casa", type: "text" },
  ],
  "Contato": [
    { key: "name", label: "Nome", value: "João", type: "text" },
  ],
}

Montar observation pra CRMs

import { buildObservation } from "@horizon-js/lead-core"

const observation = buildObservation(lead, formData, formMeta)

Gera texto formatado:

Tenho interesse neste imóvel.

--- Dados do formulário ---
Nome: Jefferson Rosa
E-mail: [email protected]
Tipo do Imóvel: Casa
Dormitórios: 3
Diferenciais: Piscina, Churrasqueira, Jardim
Mensagem: Tenho interesse neste imóvel.

--- Metadados ---
Formulário: contato-imovel
Página: imovel
URL: https://site.com.br/imovel/855
Imóvel: Casa à venda
Referência: 855
UTM: google / cpc / campanha
Consentimento: Sim (2026-04-16T17:30:00Z)

Utilitários

import { extraFieldsToText, flattenFormData } from "@horizon-js/lead-core"

// Extras pra texto simples
const text = extraFieldsToText(lead.extra_fields)

// Achatar dados agrupados
const fields = flattenFormData(groupedData)

Campos padrão

| Key | Aliases aceitos | Tipo | |---|---|---| | name | nome, nomeCompleto, full_name | string | | email | e-mail | string | | phone | telefone, tel, celular, contact | string | | message | mensagem, observacao | string | | subject | — | string | | contact_channel | contactChannel, contato_preferido | "whatsapp" / "email" / "phone" | | consent | aceitaContato, privacy | boolean |

Tipos de valor aceitos

| Tipo | Exemplo | Tratamento | |---|---|---| | string | "Casa" | Direto | | number | 200 | Convertido pra string | | boolean | true | "Sim" / "Não" | | string[] | ["Piscina", "Jardim"] | Join com ", " |

Casos de uso

O formato data/meta é o contrato universal. Qualquer sistema que consuma leads pode usar:

• CRMs — adaptGenericLead() + buildObservation() pra extrair campos e montar observation
• E-mail — templates de automação consomem o mesmo formato pra renderizar emails inteligentes (detectam tipos, formatam links, checkmarks, listas)
• Agentes de atendimento — chatbots/WhatsApp leem os campos pra contextualizar a conversa
• Analytics — UTMs e origin rastreiam de onde veio cada lead

Filosofia

• Lead Base Fields = campos universais que TODO lead tem
• Lead Domain Extras = campos extras por módulo (property, vehicle, etc.)
• Papa-tudo = campos desconhecidos vão pra extra_fields com labels bonitos
• O adapter NÃO sabe de CRMs — normaliza pro formato Horizon
• Cada CRM usa buildObservation — recebe texto formatado pronto
• Um formato, múltiplos destinos — o mesmo dado alimenta CRM, email, chatbot e analytics

Documentação detalhada

• docs/LEAD_STANDARD.md — Padrão completo de leads, campos, regras, domain extras