@horizon-modules/arbo-crm-integration/README.md

Integração CRM Arbo para conversion de dados imobiliários para property-model-v3

# @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

```bash
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)

```typescript
// 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)

```typescript
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:**
```typescript
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:

```typescript
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

```typescript
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

```bash
# === 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)
```json
{
  "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)
```json
{
  "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
```json
{
  "categoria": ["Casa", "Apartamento", "Terreno"],
  "corretor.nome": ["João Silva", "Maria Santos"],
  "corretor.telefones": ["11999999999", "21888888888"],
  "fotos.url": ["foto1.jpg", "foto2.jpg", "foto3.jpg"]
}
```

## 🧪 Desenvolvimento

```bash
# Instalar dependências
pnpm install

# Build
pnpm build

# Testes
pnpm test

# Typecheck
pnpm typecheck
```

### Scripts de Desenvolvimento

```bash
# 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.