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

Integração CRM Jetimob para conversão de dados imobiliários para property-model-v3

# @horizon-modules/jetimob-crm-integration

Integração completa com o CRM Jetimob 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 Jetimob CRM:

- **Download automático** de imóveis da API Jetimob
- **Conversão** de dados Jetimob 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/jetimob-crm-integration
# ou
pnpm add @horizon-modules/jetimob-crm-integration
```

## 🚀 Uso Rápido

### ✅ Uso Mais Simples (Recomendado)

```typescript
// ESM (TypeScript/Módulos modernos)
import { JetimobDownloader } from '@horizon-modules/jetimob-crm-integration'

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

// 🎯 Configuração mínima - baseUrl é OPCIONAL!
const downloader = new JetimobDownloader({
  webserviceKey: 'sua_webservice_key_jetimob',
  outputDir: './data/imoveis'
  // baseUrl: automático (https://api.jetimob.com)
})

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

### 🔧 Configuração Completa (Opcional)

```typescript
import { 
  JetimobDownloader, 
  JetimobApiClient, 
  ProfilerService,
  convertJetimobToPropertyV3,
  testMocks,
  fakeData
} from '@horizon-modules/jetimob-crm-integration'

// Configuração com baseUrl customizado (opcional)
const downloader = new JetimobDownloader({
  webserviceKey: 'sua_webservice_key_jetimob',
  outputDir: './data/imoveis',
  baseUrl: 'https://api.jetimob.com' // Opcional
})

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

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

// 3. Conversão manual
const imovelJetimob = await new JetimobApiClient({ webserviceKey }).getImovel(123)
const propertyV3 = convertJetimobToPropertyV3(imovelJetimob)

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

const profile = await profiler.profile()
console.log(profile.tipo) // ['Residencial', 'Comercial', ...]
```

## 🛠️ API

### JetimobDownloader

**Principais métodos:**
- `downloadPage(page, pageSize)` - 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 JetimobDownloaderConfig {
  webserviceKey: string // Webservice Key da API Jetimob (obrigatório)
  outputDir: string     // Pasta onde salvar arquivos (obrigatório)
  baseUrl?: string      // URL base da API (OPCIONAL - padrão: https://api.jetimob.com)
}
```

### JetimobApiClient

**Principais métodos:**
- `getImoveis(page?, pageSize?)` - Lista imóveis
- `getImovel(id)` - Busca imóvel específico
- `testConnection()` - Testa conexão com a API

### 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/jetimob-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
const coberturas = fakeData.coberturas
```

## 🔧 Configuração via .env

```bash
# === JETIMOB API ===
JETIMOB_WEBSERVICE_KEY=sua_webservice_key_jetimob
JETIMOB_START_PAGE=1
JETIMOB_END_PAGE=10
JETIMOB_PAGE_SIZE=100

# === 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/jetimob-imports
```

## 📁 Estrutura de Dados

### Entrada (Jetimob)
```json
{
  "codigo": "427",
  "contrato": "Compra",
  "tipo": "Residencial",
  "subtipo": "Cobertura",
  "titulo_anuncio": "Cobertura com 4 dormitórios à venda",
  "observacoes": "Imponente cobertura duplex com vista panorâmica...",
  "valor_venda": 2500000,
  "valor_venda_visivel": true,
  "dormitorios": 4,
  "suites": 3,
  "banheiros": 5,
  "garagens": 3,
  "area_total": 350,
  "area_privativa": 320,
  "endereco_estado": "Rio Grande do Sul",
  "endereco_cidade": "Torres", 
  "endereco_bairro": "Centro",
  "endereco_logradouro": "Rua XV de Novembro",
  "endereco_numero": "250",
  "endereco_cep": "95560000",
  "latitude": "-29.334722",
  "longitude": "-49.727500",
  "situacao": "Desocupado",
  "destaque": "Sem destaque",
  "imagens": [
    {
      "link": "https://s01.jetimgs.com/427_1.jpg",
      "titulo": "Sala de estar",
      "link_thumb": "https://s01.jetimgs.com/427_1_thumb.jpg"
    }
  ]
}
```

### Saída (PropertyV3)
```json
{
  "reference": "427",
  "title": "Cobertura com 4 dormitórios à venda",
  "description": "Imponente cobertura duplex com vista panorâmica...",
  "media_assets": {
    "images": [
      {
        "full": "https://s01.jetimgs.com/427_1.jpg",
        "md": "https://s01.jetimgs.com/427_1_thumb.jpg",
        "sm": "https://s01.jetimgs.com/427_1_thumb.jpg",
        "cover": true
      }
    ]
  },
  "attributes": {
    "operacao": ["Compra"],
    "tipo": "Residencial",
    "subtipo": "Cobertura",
    "valor_venda": 2500000,
    "area_total": 350,
    "area_util": 320,
    "dormitorios": 4,
    "suites": 3,
    "banheiros": 5,
    "vagas": 3,
    "endereco_cep": "95560000",
    "endereco_estado": "Rio Grande do Sul",
    "endereco_cidade": "Torres",
    "endereco_bairro": "Centro",
    "endereco_logradouro": "Rua XV de Novembro",
    "endereco_numero": "250",
    "latitude": -29.334722,
    "longitude": -49.727500,
    "situacao": "Desocupado",
    "destaque": false
  },
  "settings": {
    "currency_unit": "BRL",
    "area_unit": "m2",
    "distance_unit": "meters",
    "exibir_no_mapa": true
  }
}
```

### Profiling
```json
{
  "tipo": ["Residencial", "Comercial", "Rural"],
  "subtipo": ["Casa", "Apartamento", "Cobertura", "Terreno"],
  "endereco_cidade": ["Torres", "Capão da Canoa", "Xangri-lá"],
  "imagens.link": ["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

# Converter downloads para PropertyV3
pnpm convert:downloads
```

## 🎯 Casos de Uso

### 1. Sincronização Automática
Script diário para manter seu sistema atualizado com dados do Jetimob.

### 2. Migração de Dados
Conversão em lote de propriedades existentes do Jetimob 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.

## 🔑 Autenticação Jetimob

A API Jetimob utiliza **apenas a Webservice Key** na URL:
- ✅ **Webservice Key**: Incluída na URL do endpoint (obrigatória)
- ❌ **Headers de autenticação**: Não são necessários
- ❌ **Bearer tokens**: Não são utilizados

```javascript
// URL de exemplo
https://api.jetimob.com/webservice/{WEBSERVICE_KEY}/imoveis?v=4&page=1&pageSize=100
```

## 📝 Licença

MIT

## 🤝 Contribuição

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