iptuapi 1.1.0 → 2.0.0

package/README.md

@@ -1,8 +1,12 @@
 # IPTU API - JavaScript/TypeScript SDK
 
-SDK oficial para integração com a IPTU API.
+SDK oficial JavaScript/TypeScript para integracao com a IPTU API. Acesso a dados de IPTU de mais de 10 cidades brasileiras.
 
-## Instalação
+[![npm version](https://badge.fury.io/js/iptuapi.svg)](https://www.npmjs.com/package/iptuapi)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Instalacao
 
 ```bash
 npm install iptuapi
@@ -12,64 +16,285 @@ yarn add iptuapi
 pnpm add iptuapi
 ```
 
-## Uso Rápido
+## Uso Rapido
 
 ```typescript
 import { IPTUClient } from 'iptuapi';
 
 const client = new IPTUClient('sua_api_key');
 
-// Consulta por endereço
+// Consulta por endereco
 const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
 console.log(resultado);
 
 // Consulta por SQL (Starter+)
 const dados = await client.consultaSQL('100-01-001-001');
+```
+
+## Configuracao
+
+### Cliente Basico
+
+```typescript
+import { IPTUClient } from 'iptuapi';
+
+const client = new IPTUClient('sua_api_key');
+```
+
+### Configuracao Avancada
+
+```typescript
+import { IPTUClient, ClientConfig, RetryConfig } from 'iptuapi';
+
+const retryConfig: RetryConfig = {
+  maxRetries: 5,
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+  backoffFactor: 2.0,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
+
+const config: ClientConfig = {
+  baseUrl: 'https://iptuapi.com.br/api/v1',
+  timeout: 60000,
+  retryConfig,
+  logger: console // ou seu logger customizado
+};
+
+const client = new IPTUClient('sua_api_key', config);
+```
+
+### Logging Customizado
+
+```typescript
+import { IPTUClient, Logger } from 'iptuapi';
+
+const customLogger: Logger = {
+  debug: (msg, meta) => console.debug(`[IPTU] ${msg}`, meta),
+  info: (msg, meta) => console.info(`[IPTU] ${msg}`, meta),
+  warn: (msg, meta) => console.warn(`[IPTU] ${msg}`, meta),
+  error: (msg, meta) => console.error(`[IPTU] ${msg}`, meta)
+};
 
-// Avaliação de mercado (Pro+)
+const client = new IPTUClient('sua_api_key', { logger: customLogger });
+```
+
+## Endpoints da API
+
+### Consultas (Todos os Planos)
+
+```typescript
+// Consulta por endereco
+const resultado = await client.consultaEndereco('Avenida Paulista', '1000', 'sp');
+
+// Consulta por CEP
+const resultado = await client.consultaCEP('01310-100', 'sp');
+
+// Consulta por coordenadas (zoneamento)
+const resultado = await client.consultaZoneamento(-23.5505, -46.6333);
+```
+
+### Consultas Avancadas (Starter+)
+
+```typescript
+// Consulta por numero SQL
+const resultado = await client.consultaSQL('100-01-001-001', 'sp');
+
+// Historico de valores IPTU
+const historico = await client.dadosIPTUHistorico('100-01-001-001', 'sp');
+
+// Consulta CNPJ
+const empresa = await client.dadosCNPJ('12345678000100');
+
+// Correcao monetaria IPCA
+const corrigido = await client.dadosIPCACorrigir(100000, '2020-01', '2024-01');
+```
+
+### Valuation (Pro+)
+
+```typescript
+// Estimativa de valor de mercado
 const avaliacao = await client.valuationEstimate({
   area_terreno: 250,
   area_construida: 180,
   bairro: 'Pinheiros',
   zona: 'ZM',
   tipo_uso: 'Residencial',
-  tipo_padrao: 'Médio',
-  ano_construcao: 2010,
+  tipo_padrao: 'Medio',
+  ano_construcao: 2010
 });
 console.log(`Valor estimado: R$ ${avaliacao.valor_estimado.toLocaleString()}`);
+
+// Buscar comparaveis
+const comparaveis = await client.valuationComparables({
+  bairro: 'Pinheiros',
+  areaMin: 150,
+  areaMax: 250,
+  cidade: 'sp',
+  limit: 10
+});
+```
+
+### Batch Operations (Enterprise)
+
+```typescript
+// Valuation em lote (ate 100 imoveis)
+const imoveis = [
+  { area_terreno: 250, area_construida: 180, bairro: 'Pinheiros' },
+  { area_terreno: 300, area_construida: 200, bairro: 'Moema' }
+];
+const resultados = await client.valuationBatch(imoveis);
 ```
 
 ## Tratamento de Erros
 
 ```typescript
-import { IPTUClient, NotFoundError, RateLimitError } from 'iptuapi';
+import {
+  IPTUClient,
+  IPTUAPIError,
+  AuthenticationError,
+  ForbiddenError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  ServerError,
+  TimeoutError,
+  NetworkError
+} from 'iptuapi';
 
 const client = new IPTUClient('sua_api_key');
 
 try {
-  const resultado = await client.consultaEndereco('Rua Inexistente');
+  const resultado = await client.consultaEndereco('Rua Teste', '100');
 } catch (error) {
-  if (error instanceof NotFoundError) {
-    console.log('Imóvel não encontrado');
+  if (error instanceof AuthenticationError) {
+    console.log('API Key invalida');
+  } else if (error instanceof ForbiddenError) {
+    console.log(`Plano nao autorizado. Requer: ${error.requiredPlan}`);
+  } else if (error instanceof NotFoundError) {
+    console.log('Imovel nao encontrado');
   } else if (error instanceof RateLimitError) {
-    console.log('Limite de requisições excedido');
+    console.log(`Rate limit excedido. Retry em ${error.retryAfter}s`);
+  } else if (error instanceof ValidationError) {
+    console.log('Parametros invalidos:', error.errors);
+  } else if (error instanceof ServerError) {
+    console.log('Erro no servidor (retryable)');
+  } else if (error instanceof TimeoutError) {
+    console.log(`Timeout apos ${error.timeoutMs}ms`);
+  } else if (error instanceof NetworkError) {
+    console.log('Erro de conexao');
+  } else if (error instanceof IPTUAPIError) {
+    console.log(`Erro: ${error.message}, Request ID: ${error.requestId}`);
   }
 }
 ```
 
-## Tipos TypeScript
+### Propriedades dos Erros
 
-O SDK inclui tipos TypeScript completos:
+```typescript
+try {
+  const resultado = await client.consultaEndereco('Rua Teste', '100');
+} catch (error) {
+  if (error instanceof IPTUAPIError) {
+    console.log(`Status Code: ${error.statusCode}`);
+    console.log(`Request ID: ${error.requestId}`);
+    console.log(`Retryable: ${error.isRetryable}`);
+  }
+}
+```
+
+## Rate Limiting
+
+```typescript
+// Verificar rate limit apos requisicao
+const rateLimit = client.getRateLimitInfo();
+if (rateLimit) {
+  console.log(`Limite: ${rateLimit.limit}`);
+  console.log(`Restantes: ${rateLimit.remaining}`);
+  console.log(`Reset em: ${new Date(rateLimit.reset * 1000)}`);
+}
+
+// ID da ultima requisicao (util para suporte)
+console.log(`Request ID: ${client.getLastRequestId()}`);
+```
+
+## Tipos TypeScript
 
 ```typescript
 import type {
-  ConsultaEnderecoResult,
-  ConsultaSQLResult,
+  ClientConfig,
+  RetryConfig,
+  RateLimitInfo,
+  PropertyData,
   ValuationParams,
   ValuationResult,
+  ComparableProperty,
+  ZoningInfo,
+  IPTUHistoryItem
 } from 'iptuapi';
+
+// Exemplo de uso com tipos
+const config: ClientConfig = {
+  timeout: 30000
+};
+
+const params: ValuationParams = {
+  area_terreno: 250,
+  area_construida: 180,
+  bairro: 'Pinheiros'
+};
+
+const resultado: ValuationResult = await client.valuationEstimate(params);
+```
+
+## Browser Support
+
+O SDK funciona tanto em Node.js quanto em browsers modernos:
+
+```html
+<script type="module">
+  import { IPTUClient } from 'https://unpkg.com/iptuapi@latest/dist/browser.js';
+
+  const client = new IPTUClient('sua_api_key');
+  const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
+  console.log(resultado);
+</script>
 ```
 
-## Documentação
+## Testes
+
+```bash
+# Rodar testes
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## Cidades Suportadas
+
+| Codigo | Cidade |
+|--------|--------|
+| sp | Sao Paulo |
+| rj | Rio de Janeiro |
+| bh | Belo Horizonte |
+| recife | Recife |
+| curitiba | Curitiba |
+| poa | Porto Alegre |
+| salvador | Salvador |
+| fortaleza | Fortaleza |
+| campinas | Campinas |
+| santos | Santos |
+
+## Licenca
+
+MIT License - veja [LICENSE](LICENSE) para detalhes.
+
+## Links
 
-Acesse a documentação completa em [iptuapi.com.br/docs](https://iptuapi.com.br/docs)
+- [Documentacao](https://iptuapi.com.br/docs)
+- [API Reference](https://iptuapi.com.br/docs/api)
+- [Portal do Desenvolvedor](https://iptuapi.com.br/dashboard)