@horizon-modules/arbo-crm-integration

Integração completa com o CRM Arbo para sincronização e conversão de dados imobiliários para o formato PropertyModelV3.

🏠 O que faz

Este pacote oferece uma solução completa para integrar sistemas imobiliários com a API do Arbo CRM:

• Download automático de imóveis da API Arbo
• Conversão de dados Arbo para PropertyModelV3
• Upload para sua API própria
• Profiling genérico de datasets JSON
• Dados de teste para desenvolvimento

📦 Instalação

npm install @horizon-modules/arbo-crm-integration
# ou
pnpm add @horizon-modules/arbo-crm-integration

🚀 Uso Rápido (v2.0.4+)

✅ Uso Mais Simples (Recomendado)

// ESM (TypeScript/Módulos modernos)
import { ArboDownloader } from '@horizon-modules/arbo-crm-integration'

// CommonJS (JavaScript tradicional)
const { ArboDownloader } = require('@horizon-modules/arbo-crm-integration')

// 🎯 Configuração mínima - baseUrl é OPCIONAL!
const downloader = new ArboDownloader({
  token: 'seu_token_arbo',
  outputDir: './data/imoveis'
  // baseUrl: automático (https://app-integracao.arboimoveis.com/api)
})

// Download simples
const result = await downloader.downloadPages({
  startPage: 1,
  endPage: 5,
  perPage: 50
})

🔧 Configuração Completa (Opcional)

import { 
  ArboDownloader, 
  ArboApiClient, 
  ProfilerService,
  convertArboToPropertyV3,
  testMocks,
  fakeData
} from '@horizon-modules/arbo-crm-integration'

// Configuração com baseUrl customizado (opcional)
const downloader = new ArboDownloader({
  token: 'seu_token_arbo',
  outputDir: './data/imoveis',
  baseUrl: 'https://app-integracao.arboimoveis.com/api' // Opcional
})

const result = await downloader.downloadPages({
  startPage: 1,
  endPage: 5,
  perPage: 50
})

// 2. Upload para sua API
await downloader.uploadToApi({
  endpoint: 'https://sua-api.com/imoveis',
  headers: { 'Authorization': 'Bearer seu_token' }
})

// 3. Conversão manual
const imovelArbo = await new ArboApiClient({ token }).getImovel(123)
const propertyV3 = convertArboToPropertyV3(imovelArbo)

// 4. Profiling de dados
const profiler = new ProfilerService({
  inputDir: './data',
  outputDir: './output',
  fieldConfigs: {
    'categoria': { maxExamples: 5 },
    'end_bairro': { maxExamples: 20 }
  }
})

const profile = await profiler.profile()
console.log(profile.categoria) // ['Casa', 'Apartamento', ...]

🛠️ API

ArboDownloader

Principais métodos:

• downloadPage(page, perPage) - Baixa uma página específica
• downloadPages(options) - Baixa múltiplas páginas
• uploadToApi(config) - Envia dados para sua API
• downloadAndUpload(downloadOpts, uploadOpts) - Operação completa

Configuração:

interface ArboDownloaderConfig {
  token: string        // Token da API Arbo (obrigatório)
  outputDir: string    // Pasta onde salvar arquivos (obrigatório)
  baseUrl?: string     // URL base da API (OPCIONAL - padrão: https://app-integracao.arboimoveis.com/api)
}

🆕 Melhorias na v2.0.4

✅ baseUrl agora é opcional - usa valor padrão automaticamente
✅ Compatibilidade ESM/CommonJS - funciona com import e require
✅ Melhor documentação - exemplos mais claros
✅ Exports corrigidos - melhor suporte TypeScript

ArboApiClient

Principais métodos:

• getImoveis(page?, perPage?) - Lista imóveis
• getImovel(id) - Busca imóvel específico
• searchImoveis(params, page?, perPage?) - Busca com filtros
• getAllPages(perPage?) - Baixa todas as páginas

ProfilerService

Ferramenta genérica para análise de datasets JSON:

const profiler = new ProfilerService({
  inputDir: './dados',           // Pasta com arquivos JSON
  outputDir: './saida',         // Onde salvar o relatório  
  fieldConfigs: {
    campo1: { maxExamples: 5 },  // Máximo 5 exemplos
    campo2: { maxExamples: 10 }  // Máximo 10 exemplos
  },
  defaultMaxExamples: 3         // Padrão para outros campos
})

const resultado = await profiler.profile()
// Resultado: { campo1: [valores únicos], campo2: [...] }

Características:

• ✅ Genérico - funciona com qualquer estrutura JSON
• ✅ Arrays concatenados - junta valores de arrays de vários objetos
• ✅ Objetos aninhados - preserva hierarquia (corretor.nome)
• ✅ Ordem alfabética - campos organizados automaticamente
• ✅ Configurável - controle de quantos exemplos por campo

Dados de Teste

import { testMocks, fakeData } from '@horizon-modules/arbo-crm-integration'

// Mocks para testes
const validData = testMocks.validos      // Dados válidos para testes
const problematicData = testMocks.problematicos  // Casos edge

// Dados falsos para desenvolvimento
const apartments = fakeData.apartamentos
const houses = fakeData.casas
const commercial = fakeData.comerciais  
const land = fakeData.terrenos

🔧 Configuração via .env

# === ARBO API ===
ARBO_TOKEN=seu_token_arbo
ARBO_START_PAGE=1
ARBO_END_PAGE=10
ARBO_PER_PAGE=50

# === SUA API ===
API_ENDPOINT=https://sua-api.com/imoveis
API_TOKEN=seu_bearer_token
API_BATCH_SIZE=10

# === OPERAÇÃO ===
OPERATION_MODE=download-and-upload  # download-only | upload-only | download-and-upload
DATA_DIR=./data/arbo-imports

📁 Estrutura de Dados

Entrada (Arbo)

{
  "ref_id": 3015393,
  "codigo": "SO0001_TB",
  "titulo": "Sobrado à venda 2 Quadras do lago",
  "categoria": "Sobrado",
  "finalidade": "Venda",
  "ativo": true,
  "publicado": true,
  "valor_venda": 510000,
  "qtd_quartos": 3,
  "qtd_banheiro": 2,
  "qtd_suites": 1,
  "qtd_vagas": 2,
  "area_total": 100,
  "area_privativa": 98.25,
  "end_bairro": "Oficinas",
  "end_cidade": "Ponta Grossa",
  "end_estado": "PR",
  "end_cep": "84036140",
  "fotos": [
    {
      "url": "https://static.arboimoveis.com.br/SO0001_TB/sobrado_1683719500639.jpeg",
      "ordem": 0,
      "principal": true,
      "marcadagua_url": "https://...",
      "sizes": {
        "medium": "https://...640x480/...",
        "small": "https://...320x240/..."
      }
    }
  ],
  "corretor": {
    "codigo": 908223,
    "nome": "Fabiano Garbuio",
    "telefones": ["42998000149"]
  }
}

Saída (PropertyV3)

{
  "reference": "SO0001_TB",
  "title": "Sobrado à venda 2 Quadras do lago",
  "description": "Residencial com seis sobrados, todos independentes...",
  "media_assets": {
    "images": [
      {
        "full": "https://static.arboimoveis.com.br/SO0001_TB/sobrado_1683719500639.jpeg",
        "md": "https://static.arboimoveis.com.br/SO0001_TB/640x480/sobrado_1683719500639.jpeg",
        "sm": "https://static.arboimoveis.com.br/SO0001_TB/320x240/sobrado_1683719500639.jpeg",
        "cover": true
      }
    ],
    "videos": [{"embed_url": "https://youtu.be/96d17X77UZo"}]
  },
  "attributes": {
    "operacao": ["Venda"],
    "valor_venda": 510000,
    "area_total": 100,
    "area_util": 98.25,
    "dormitorios": 3,
    "suites": 1,
    "banheiros": 2,
    "vagas": 2,
    "tipo": "Sobrado",
    "finalidade": "Residencial",
    "endereco_cep": "84036140",
    "endereco_estado": "PR",
    "endereco_cidade": "Ponta Grossa",
    "endereco_bairro": "Oficinas",
    "endereco_logradouro": "Rua Mathias de Albuquerque",
    "endereco_numero": 179,
    "mobiliado": false,
    "financiavel": true
  },
  "settings": {
    "currency_unit": "BRL",
    "area_unit": "m2",
    "exibir_no_mapa": true
  }
}

Profiling

{
  "categoria": ["Casa", "Apartamento", "Terreno"],
  "corretor.nome": ["João Silva", "Maria Santos"],
  "corretor.telefones": ["11999999999", "21888888888"],
  "fotos.url": ["foto1.jpg", "foto2.jpg", "foto3.jpg"]
}

🧪 Desenvolvimento

# Instalar dependências
pnpm install

# Build
pnpm build

# Testes
pnpm test

# Typecheck
pnpm typecheck

Scripts de Desenvolvimento

# Download de propriedades reais
node __dev__/scripts/download-properties.js

# Profiling dos dados baixados  
node __dev__/scripts/profile-properties.js

# Gerar dados falsos
pnpm tsx __dev__/scripts/generate-fake-data.ts

# Gerar mocks para testes
pnpm tsx __dev__/scripts/generate-mocks.ts

🎯 Casos de Uso

1. Sincronização Automática

Script diário para manter seu sistema atualizado com dados do Arbo.

2. Migração de Dados

Conversão em lote de propriedades existentes do Arbo para seu formato.

3. Análise de Dados

Profiling para entender estrutura e qualidade dos dados imobiliários.

4. Desenvolvimento

Dados falsos e mocks para testes e desenvolvimento local.

📝 Licença

MIT

🤝 Contribuição

Este é um pacote interno da Horizon Labs. Para suporte, abra uma issue no repositório principal.