iptuapi 1.1.0 → 2.0.0

package/dist/index.mjs

@@ -1,166 +1,513 @@
 // src/index.ts
-var IPTUAPIError = class extends Error {
-  constructor(message, statusCode) {
+var CidadeEnum = {
+  SAO_PAULO: "sp",
+  BELO_HORIZONTE: "bh",
+  RECIFE: "recife"
+};
+var IPTUAPIError = class _IPTUAPIError extends Error {
+  statusCode;
+  requestId;
+  responseBody;
+  constructor(message, statusCode, requestId, responseBody) {
     super(message);
-    this.statusCode = statusCode;
     this.name = "IPTUAPIError";
+    this.statusCode = statusCode;
+    this.requestId = requestId;
+    this.responseBody = responseBody;
+    Object.setPrototypeOf(this, _IPTUAPIError.prototype);
+  }
+  get isRetryable() {
+    return this.statusCode ? [429, 500, 502, 503, 504].includes(this.statusCode) : false;
   }
 };
-var AuthenticationError = class extends IPTUAPIError {
-  constructor(message = "API Key inv\xE1lida ou expirada") {
-    super(message, 401);
+var AuthenticationError = class _AuthenticationError extends IPTUAPIError {
+  constructor(message = "API Key inv\xE1lida ou expirada", requestId, responseBody) {
+    super(message, 401, requestId, responseBody);
     this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
   }
 };
-var RateLimitError = class extends IPTUAPIError {
-  constructor(message = "Limite de requisi\xE7\xF5es excedido") {
-    super(message, 429);
-    this.name = "RateLimitError";
+var ForbiddenError = class _ForbiddenError extends IPTUAPIError {
+  requiredPlan;
+  constructor(message = "Plano n\xE3o autorizado para este recurso", requiredPlan, requestId, responseBody) {
+    super(message, 403, requestId, responseBody);
+    this.name = "ForbiddenError";
+    this.requiredPlan = requiredPlan;
+    Object.setPrototypeOf(this, _ForbiddenError.prototype);
   }
 };
-var NotFoundError = class extends IPTUAPIError {
-  constructor(message = "Recurso n\xE3o encontrado") {
-    super(message, 404);
+var NotFoundError = class _NotFoundError extends IPTUAPIError {
+  constructor(message = "Recurso n\xE3o encontrado", requestId, responseBody) {
+    super(message, 404, requestId, responseBody);
     this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
   }
 };
-var ForbiddenError = class extends IPTUAPIError {
-  constructor(message = "Plano n\xE3o autorizado para este recurso") {
-    super(message, 403);
-    this.name = "ForbiddenError";
+var RateLimitError = class _RateLimitError extends IPTUAPIError {
+  retryAfter;
+  limit;
+  remaining;
+  constructor(message = "Limite de requisi\xE7\xF5es excedido", retryAfter, limit, remaining, requestId, responseBody) {
+    super(message, 429, requestId, responseBody);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    this.limit = limit;
+    this.remaining = remaining;
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+  get isRetryable() {
+    return true;
+  }
+};
+var ValidationError = class _ValidationError extends IPTUAPIError {
+  errors;
+  constructor(message = "Par\xE2metros inv\xE1lidos", errors, requestId, responseBody) {
+    super(message, 400, requestId, responseBody);
+    this.name = "ValidationError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
   }
 };
+var ServerError = class _ServerError extends IPTUAPIError {
+  constructor(message = "Erro interno do servidor", statusCode = 500, requestId, responseBody) {
+    super(message, statusCode, requestId, responseBody);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+  get isRetryable() {
+    return true;
+  }
+};
+var TimeoutError = class _TimeoutError extends IPTUAPIError {
+  timeoutMs;
+  constructor(message = "Timeout na requisi\xE7\xE3o", timeoutMs) {
+    super(message, 408);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+  get isRetryable() {
+    return true;
+  }
+};
+var NetworkError = class _NetworkError extends IPTUAPIError {
+  originalError;
+  constructor(message = "Erro de conex\xE3o com a API", originalError) {
+    super(message);
+    this.name = "NetworkError";
+    this.originalError = originalError;
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+  get isRetryable() {
+    return true;
+  }
+};
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelay: 500,
+  maxDelay: 1e4,
+  backoffFactor: 2,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
 var IPTUClient = class {
   apiKey;
   baseUrl;
   timeout;
+  retryConfig;
+  logger;
+  logRequests;
+  logResponses;
+  userAgent;
+  _rateLimit;
+  _lastRequestId;
   constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error("API Key \xE9 obrigat\xF3ria");
+    }
     this.apiKey = apiKey;
     this.baseUrl = options.baseUrl || "https://iptuapi.com.br/api/v1";
     this.timeout = options.timeout || 3e4;
+    this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...options.retry };
+    this.logger = options.logger;
+    this.logRequests = options.logRequests || false;
+    this.logResponses = options.logResponses || false;
+    this.userAgent = options.userAgent || "iptuapi-js/2.0.0";
+  }
+  // ===========================================================================
+  // Properties
+  // ===========================================================================
+  /** Rate limit info from last request */
+  get rateLimit() {
+    return this._rateLimit;
+  }
+  /** Request ID from last request (useful for support) */
+  get lastRequestId() {
+    return this._lastRequestId;
+  }
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+  log(level, message, ...args) {
+    if (this.logger && this.logger[level]) {
+      this.logger[level](message, ...args);
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  calculateDelay(attempt) {
+    const delay = this.retryConfig.initialDelay * Math.pow(this.retryConfig.backoffFactor, attempt);
+    return Math.min(delay, this.retryConfig.maxDelay);
+  }
+  extractRateLimit(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      const resetTimestamp = parseInt(reset, 10);
+      return {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: resetTimestamp,
+        resetDate: new Date(resetTimestamp * 1e3)
+      };
+    }
+    return void 0;
+  }
+  async handleErrorResponse(response, requestId) {
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+      body = { detail: response.statusText };
+    }
+    const message = body.detail || `HTTP ${response.status}`;
+    switch (response.status) {
+      case 400:
+      case 422:
+        throw new ValidationError(
+          message,
+          body.errors,
+          requestId,
+          body
+        );
+      case 401:
+        throw new AuthenticationError(message, requestId, body);
+      case 403:
+        throw new ForbiddenError(
+          message,
+          body.required_plan,
+          requestId,
+          body
+        );
+      case 404:
+        throw new NotFoundError(message, requestId, body);
+      case 429:
+        const retryAfter = response.headers.get("Retry-After");
+        throw new RateLimitError(
+          message,
+          retryAfter ? parseInt(retryAfter, 10) : void 0,
+          this._rateLimit?.limit,
+          this._rateLimit?.remaining,
+          requestId,
+          body
+        );
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        throw new ServerError(message, response.status, requestId, body);
+      default:
+        throw new IPTUAPIError(message, response.status, requestId, body);
+    }
   }
   async request(method, endpoint, params, body) {
     const url = new URL(`${this.baseUrl}${endpoint}`);
     if (params) {
       Object.entries(params).forEach(([key, value]) => {
-        if (value) url.searchParams.append(key, value);
+        if (value !== void 0 && value !== null && value !== "") {
+          url.searchParams.append(key, String(value));
+        }
       });
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url.toString(), {
-        method,
-        headers: {
-          "X-API-Key": this.apiKey,
-          "Content-Type": "application/json"
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (response.ok) {
-        return response.json();
-      }
-      switch (response.status) {
-        case 401:
-          throw new AuthenticationError();
-        case 403:
-          throw new ForbiddenError();
-        case 404:
-          throw new NotFoundError();
-        case 429:
-          throw new RateLimitError();
-        default:
-          const errorData = await response.json().catch(() => ({}));
-          throw new IPTUAPIError(
-            errorData.detail || `Erro na API: ${response.statusText}`,
-            response.status
+    const headers = {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": this.userAgent
+    };
+    let lastError;
+    let attempt = 0;
+    while (attempt <= this.retryConfig.maxRetries) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        if (this.logRequests) {
+          this.log(
+            "debug",
+            `Request: ${method} ${url}`,
+            params ? { params } : {},
+            body ? { body } : {}
           );
+        }
+        const startTime = Date.now();
+        const response = await fetch(url.toString(), {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const elapsedMs = Date.now() - startTime;
+        this._rateLimit = this.extractRateLimit(response.headers);
+        this._lastRequestId = response.headers.get("X-Request-ID") || void 0;
+        if (this.logResponses) {
+          this.log(
+            "debug",
+            `Response: ${response.status} ${url} (${elapsedMs}ms)`
+          );
+        }
+        if (response.ok) {
+          return await response.json();
+        }
+        if (this.retryConfig.retryableStatuses.includes(response.status) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
+          this.log(
+            "warn",
+            `Request failed with ${response.status}, retrying in ${delay}ms (attempt ${attempt + 1}/${this.retryConfig.maxRetries})`
+          );
+          await this.sleep(delay);
+          attempt++;
+          continue;
+        }
+        await this.handleErrorResponse(response, this._lastRequestId);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof IPTUAPIError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            lastError = new TimeoutError(
+              `Timeout ap\xF3s ${this.timeout}ms`,
+              this.timeout
+            );
+          } else if (error.message.includes("fetch") || error.message.includes("network")) {
+            lastError = new NetworkError(
+              `Erro de conex\xE3o: ${error.message}`,
+              error
+            );
+          } else {
+            lastError = error;
+          }
+          if (attempt < this.retryConfig.maxRetries) {
+            const delay = this.calculateDelay(attempt);
+            this.log(
+              "warn",
+              `Request failed: ${error.message}, retrying in ${delay}ms (attempt ${attempt + 1}/${this.retryConfig.maxRetries})`
+            );
+            await this.sleep(delay);
+            attempt++;
+            continue;
+          }
+        }
+        throw lastError || error;
       }
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof IPTUAPIError) throw error;
-      if (error instanceof Error && error.name === "AbortError") {
-        throw new IPTUAPIError("Timeout na requisi\xE7\xE3o", 408);
-      }
-      throw error;
     }
+    throw lastError || new IPTUAPIError("Max retries exceeded");
+  }
+  async consultaEndereco(paramsOrLogradouro, numero, cidade) {
+    let params;
+    if (typeof paramsOrLogradouro === "string") {
+      params = {
+        logradouro: paramsOrLogradouro,
+        numero,
+        cidade: cidade || "sp"
+      };
+    } else {
+      params = {
+        logradouro: paramsOrLogradouro.logradouro,
+        numero: paramsOrLogradouro.numero,
+        complemento: paramsOrLogradouro.complemento,
+        cidade: paramsOrLogradouro.cidade || "sp",
+        incluir_historico: paramsOrLogradouro.incluirHistorico,
+        incluir_comparaveis: paramsOrLogradouro.incluirComparaveis,
+        incluir_zoneamento: paramsOrLogradouro.incluirZoneamento
+      };
+    }
+    return this.request(
+      "GET",
+      "/consulta/endereco",
+      params
+    );
   }
   /**
-   * Busca dados de IPTU por endereço
+   * Busca dados de IPTU por número SQL (contribuinte).
+   *
+   * @param sql - Número SQL do imóvel
+   * @param cidade - Cidade da consulta
+   * @param options - Opções adicionais
+   * @returns Dados completos do imóvel
    */
-  async consultaEndereco(logradouro, numero) {
-    return this.request("GET", "/consulta/endereco", {
-      logradouro,
-      numero: numero || ""
+  async consultaSQL(sql, cidade = "sp", options) {
+    return this.request("GET", `/consulta/sql/${sql}`, {
+      cidade,
+      incluir_historico: options?.incluirHistorico,
+      incluir_comparaveis: options?.incluirComparaveis
     });
   }
   /**
-   * Busca dados de IPTU por número SQL (Starter+)
+   * Busca imóveis por CEP.
+   *
+   * @param cep - CEP do imóvel
+   * @param cidade - Cidade da consulta
+   * @returns Lista de imóveis no CEP
    */
-  async consultaSQL(sql) {
-    return this.request("GET", "/consulta/sql", { sql });
+  async consultaCEP(cep, cidade = "sp") {
+    const cleanCep = cep.replace(/\D/g, "");
+    return this.request(
+      "GET",
+      `/consulta/cep/${cleanCep}`,
+      { cidade }
+    );
   }
   /**
-   * Busca dados de IPTU por endereço para qualquer cidade suportada
-   * @param cidade - Cidade ("sao_paulo" ou "belo_horizonte")
-   * @param logradouro - Nome da rua/avenida
-   * @param numero - Número do imóvel (opcional)
-   * @param ano - Ano de referência (default: 2024)
-   * @param limit - Limite de resultados (default: 20)
+   * Consulta zoneamento por coordenadas.
+   *
+   * @param latitude - Latitude do ponto
+   * @param longitude - Longitude do ponto
+   * @returns Dados de zoneamento
    */
-  async consultaIPTU(cidade, logradouro, numero, ano = 2024, limit = 20) {
-    const params = {
-      logradouro,
-      ano: ano.toString(),
-      limit: limit.toString()
-    };
-    if (numero !== void 0) {
-      params.numero = numero.toString();
-    }
+  async consultaZoneamento(latitude, longitude) {
+    return this.request("GET", "/consulta/zoneamento", {
+      latitude,
+      longitude
+    });
+  }
+  // ===========================================================================
+  // Valuation Endpoints (Pro+)
+  // ===========================================================================
+  /**
+   * Estima o valor de mercado do imóvel usando ML.
+   * Disponível apenas para planos Pro e Enterprise.
+   *
+   * @param params - Parâmetros do imóvel
+   * @returns Estimativa de valor
+   * @throws {ForbiddenError} Se o plano não permitir
+   */
+  async valuationEstimate(params) {
+    return this.request(
+      "POST",
+      "/valuation/estimate",
+      void 0,
+      {
+        area_terreno: params.area_terreno,
+        area_construida: params.area_construida,
+        bairro: params.bairro,
+        zona: params.zona,
+        tipo_uso: params.tipo_uso,
+        tipo_padrao: params.tipo_padrao,
+        ano_construcao: params.ano_construcao,
+        cidade: params.cidade || "sp"
+      }
+    );
+  }
+  /**
+   * Valuation em lote (até 100 imóveis).
+   * Disponível apenas para plano Enterprise.
+   *
+   * @param imoveis - Lista de imóveis para avaliar
+   * @returns Resultados de valuation para cada imóvel
+   */
+  async valuationBatch(imoveis) {
+    return this.request(
+      "POST",
+      "/valuation/estimate/batch",
+      void 0,
+      { imoveis }
+    );
+  }
+  /**
+   * Busca imóveis comparáveis para análise.
+   *
+   * @param bairro - Nome do bairro
+   * @param areaMin - Área mínima em m²
+   * @param areaMax - Área máxima em m²
+   * @param options - Opções adicionais
+   * @returns Lista de imóveis comparáveis
+   */
+  async valuationComparables(bairro, areaMin, areaMax, options) {
+    return this.request("GET", "/valuation/comparables", {
+      bairro,
+      area_min: areaMin,
+      area_max: areaMax,
+      tipo_uso: options?.tipoUso,
+      cidade: options?.cidade || "sp",
+      limit: options?.limit || 10
+    });
+  }
+  // ===========================================================================
+  // Dados Endpoints
+  // ===========================================================================
+  /**
+   * Histórico de valores IPTU de um imóvel.
+   *
+   * @param sql - Número SQL do imóvel
+   * @param cidade - Cidade da consulta
+   * @returns Lista com histórico anual
+   */
+  async dadosIPTUHistorico(sql, cidade = "sp") {
     return this.request(
       "GET",
-      `/dados/iptu/${cidade}/endereco`,
-      params
+      `/dados/iptu/historico/${sql}`,
+      { cidade }
     );
   }
   /**
-   * Busca dados de IPTU pelo identificador único do imóvel
-   * @param cidade - Cidade ("sao_paulo" ou "belo_horizonte")
-   * @param identificador - Número SQL (SP) ou Índice Cadastral (BH)
-   * @param ano - Ano de referência (opcional)
+   * Consulta dados de empresa por CNPJ.
+   *
+   * @param cnpj - CNPJ da empresa
+   * @returns Dados cadastrais
    */
-  async consultaIPTUSQL(cidade, identificador, ano) {
-    const params = {};
-    if (ano !== void 0) {
-      params.ano = ano.toString();
-    }
+  async dadosCNPJ(cnpj) {
+    const cleanCnpj = cnpj.replace(/\D/g, "");
     return this.request(
       "GET",
-      `/dados/iptu/${cidade}/sql/${encodeURIComponent(identificador)}`,
-      params
+      `/dados/cnpj/${cleanCnpj}`
     );
   }
   /**
-   * Estima o valor de mercado do imóvel (Pro+)
+   * Correção monetária pelo IPCA.
+   *
+   * @param valor - Valor a corrigir
+   * @param dataOrigem - Data do valor original (YYYY-MM)
+   * @param dataDestino - Data destino (default: atual)
+   * @returns Valor corrigido e fator de correção
    */
-  async valuationEstimate(params) {
+  async dadosIPCACorrigir(valor, dataOrigem, dataDestino) {
     return this.request(
-      "POST",
-      "/valuation/estimate",
-      void 0,
-      params
+      "GET",
+      "/dados/ipca/corrigir",
+      {
+        valor,
+        data_origem: dataOrigem,
+        data_destino: dataDestino
+      }
     );
   }
 };
 var index_default = IPTUClient;
 export {
   AuthenticationError,
+  CidadeEnum,
   ForbiddenError,
   IPTUAPIError,
   IPTUClient,
+  NetworkError,
   NotFoundError,
   RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
   index_default as default
 };

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "iptuapi",
-  "version": "1.1.0",
-  "description": "SDK oficial para a IPTU API - Dados de IPTU de São Paulo e Belo Horizonte",
+  "version": "2.0.0",
+  "description": "SDK oficial para a IPTU API - Dados de IPTU de São Paulo, Belo Horizonte e Recife",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -17,9 +29,13 @@
     "api",
     "são paulo",
     "belo horizonte",
+    "recife",
     "imóveis",
     "dados",
-    "typescript"
+    "real estate",
+    "property",
+    "typescript",
+    "sdk"
   ],
   "author": "IPTU API <contato@iptuapi.com.br>",
   "license": "MIT",
@@ -28,9 +44,16 @@
     "url": "https://github.com/iptuapi/iptuapi-js"
   },
   "homepage": "https://iptuapi.com.br",
+  "bugs": {
+    "url": "https://github.com/iptuapi/iptuapi-js/issues"
+  },
   "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "msw": "^2.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
   },
   "engines": {
     "node": ">=18"