iptuapi 2.1.0 → 2.1.2

package/dist/index.mjs

@@ -1,610 +1,666 @@
-// src/errors.ts
+// src/index.ts
+var CidadeEnum = {
+  SAO_PAULO: "sp",
+  BELO_HORIZONTE: "bh",
+  RECIFE: "recife",
+  PORTO_ALEGRE: "poa",
+  FORTALEZA: "fortaleza",
+  CURITIBA: "curitiba",
+  RIO_DE_JANEIRO: "rj",
+  BRASILIA: "brasilia"
+};
 var IPTUAPIError = class _IPTUAPIError extends Error {
   statusCode;
   requestId;
-  responseData;
-  constructor(message, statusCode, requestId, responseData) {
+  responseBody;
+  constructor(message, statusCode, requestId, responseBody) {
     super(message);
     this.name = "IPTUAPIError";
     this.statusCode = statusCode;
     this.requestId = requestId;
-    this.responseData = responseData || {};
+    this.responseBody = responseBody;
     Object.setPrototypeOf(this, _IPTUAPIError.prototype);
   }
-  isRetryable() {
-    return false;
-  }
-  toJSON() {
-    return {
-      error: this.name,
-      message: this.message,
-      statusCode: this.statusCode,
-      requestId: this.requestId,
-      retryable: this.isRetryable()
-    };
+  get isRetryable() {
+    return this.statusCode ? [429, 500, 502, 503, 504].includes(this.statusCode) : false;
   }
 };
 var AuthenticationError = class _AuthenticationError extends IPTUAPIError {
-  constructor(message = "API Key invalida ou ausente", requestId) {
-    super(message, 401, requestId);
+  constructor(message = "API Key inv\xE1lida ou expirada", requestId, responseBody) {
+    super(message, 401, requestId, responseBody);
     this.name = "AuthenticationError";
     Object.setPrototypeOf(this, _AuthenticationError.prototype);
   }
 };
 var ForbiddenError = class _ForbiddenError extends IPTUAPIError {
   requiredPlan;
-  constructor(message = "Acesso negado", requiredPlan, requestId) {
-    super(message, 403, requestId);
+  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);
   }
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      requiredPlan: this.requiredPlan
-    };
-  }
 };
 var NotFoundError = class _NotFoundError extends IPTUAPIError {
-  resource;
-  constructor(message = "Recurso nao encontrado", resource, requestId) {
-    super(message, 404, requestId);
+  constructor(message = "Recurso n\xE3o encontrado", requestId, responseBody) {
+    super(message, 404, requestId, responseBody);
     this.name = "NotFoundError";
-    this.resource = resource;
     Object.setPrototypeOf(this, _NotFoundError.prototype);
   }
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      resource: this.resource
-    };
-  }
 };
 var RateLimitError = class _RateLimitError extends IPTUAPIError {
   retryAfter;
-  constructor(message = "Rate limit excedido", retryAfter = 60, requestId) {
-    super(message, 429, requestId);
+  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);
   }
-  isRetryable() {
+  get isRetryable() {
     return true;
   }
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      retryAfter: this.retryAfter
-    };
-  }
 };
 var ValidationError = class _ValidationError extends IPTUAPIError {
   errors;
-  constructor(message = "Parametros invalidos", errors, statusCode = 422, requestId) {
-    super(message, statusCode, requestId);
+  constructor(message = "Par\xE2metros inv\xE1lidos", errors, requestId, responseBody) {
+    super(message, 400, requestId, responseBody);
     this.name = "ValidationError";
-    this.errors = errors || {};
+    this.errors = errors;
     Object.setPrototypeOf(this, _ValidationError.prototype);
   }
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      validationErrors: this.errors
-    };
-  }
 };
 var ServerError = class _ServerError extends IPTUAPIError {
-  constructor(message = "Erro interno do servidor", statusCode = 500, requestId) {
-    super(message, statusCode, requestId);
+  constructor(message = "Erro interno do servidor", statusCode = 500, requestId, responseBody) {
+    super(message, statusCode, requestId, responseBody);
     this.name = "ServerError";
     Object.setPrototypeOf(this, _ServerError.prototype);
   }
-  isRetryable() {
+  get isRetryable() {
     return true;
   }
 };
 var TimeoutError = class _TimeoutError extends IPTUAPIError {
-  timeoutSeconds;
-  constructor(message = "Timeout na requisicao", timeoutSeconds, requestId) {
-    super(message, 408, requestId);
+  timeoutMs;
+  constructor(message = "Timeout na requisi\xE7\xE3o", timeoutMs) {
+    super(message, 408);
     this.name = "TimeoutError";
-    this.timeoutSeconds = timeoutSeconds;
+    this.timeoutMs = timeoutMs;
     Object.setPrototypeOf(this, _TimeoutError.prototype);
   }
-  isRetryable() {
+  get isRetryable() {
     return true;
   }
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      timeoutSeconds: this.timeoutSeconds
-    };
-  }
 };
 var NetworkError = class _NetworkError extends IPTUAPIError {
   originalError;
-  constructor(message = "Erro de conexao", originalError) {
-    super(message, void 0, void 0);
+  constructor(message = "Erro de conex\xE3o com a API", originalError) {
+    super(message);
     this.name = "NetworkError";
     this.originalError = originalError;
     Object.setPrototypeOf(this, _NetworkError.prototype);
   }
-  isRetryable() {
+  get isRetryable() {
     return true;
   }
 };
-
-// src/client.ts
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
-  initialDelay: 1e3,
-  maxDelay: 3e4,
+  initialDelay: 500,
+  maxDelay: 1e4,
   backoffFactor: 2,
-  retryableStatusCodes: [429, 500, 502, 503, 504]
+  retryableStatuses: [429, 500, 502, 503, 504]
 };
-var DEFAULT_CONFIG = {
-  baseUrl: "https://iptuapi.com.br/api/v1",
-  timeout: 3e4,
-  retryConfig: DEFAULT_RETRY_CONFIG
-};
-function toCamelCase(obj) {
-  const result = {};
-  for (const [key, value] of Object.entries(obj)) {
-    const camelKey = key.replace(
-      /_([a-z])/g,
-      (_, letter) => letter.toUpperCase()
-    );
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      result[camelKey] = toCamelCase(value);
-    } else if (Array.isArray(value)) {
-      result[camelKey] = value.map(
-        (item) => typeof item === "object" && item !== null ? toCamelCase(item) : item
-      );
-    } else {
-      result[camelKey] = value;
+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.1.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;
   }
-  return result;
-}
-function toSnakeCase(obj) {
-  const result = {};
-  for (const [key, value] of Object.entries(obj)) {
-    const snakeKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      result[snakeKey] = toSnakeCase(value);
-    } else if (Array.isArray(value)) {
-      result[snakeKey] = value.map(
-        (item) => typeof item === "object" && item !== null ? toSnakeCase(item) : item
-      );
-    } else {
-      result[snakeKey] = value;
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+  log(level, message, ...args) {
+    if (this.logger && this.logger[level]) {
+      this.logger[level](message, ...args);
     }
   }
-  return result;
-}
-var IPTUClient = class {
-  apiKey;
-  config;
-  _rateLimitInfo = null;
-  _lastRequestId = null;
-  /**
-   * Cria uma nova instancia do cliente.
-   *
-   * @param apiKey - Chave de API para autenticacao
-   * @param options - Opcoes de configuracao
-   */
-  constructor(apiKey, options) {
-    this.apiKey = apiKey;
-    this.config = {
-      baseUrl: options?.baseUrl || DEFAULT_CONFIG.baseUrl,
-      timeout: options?.timeout || DEFAULT_CONFIG.timeout,
-      retryConfig: {
-        ...DEFAULT_RETRY_CONFIG,
-        ...options?.retryConfig
-      }
-    };
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  /**
-   * Retorna informacoes do rate limit da ultima requisicao.
-   */
-  get rateLimitInfo() {
-    return this._rateLimitInfo;
+  combineSignals(signal1, signal2) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal1.aborted || signal2.aborted) {
+      controller.abort();
+      return controller.signal;
+    }
+    signal1.addEventListener("abort", abort, { once: true });
+    signal2.addEventListener("abort", abort, { once: true });
+    return controller.signal;
   }
-  /**
-   * Retorna o ID da ultima requisicao.
-   */
-  get lastRequestId() {
-    return this._lastRequestId;
+  calculateDelay(attempt) {
+    const delay = this.retryConfig.initialDelay * Math.pow(this.retryConfig.backoffFactor, attempt);
+    return Math.min(delay, this.retryConfig.maxDelay);
   }
-  /**
-   * Executa uma requisicao HTTP com retry.
-   */
-  async makeRequest(method, endpoint, params, body) {
-    const url = new URL(`${this.config.baseUrl}/${endpoint.replace(/^\//, "")}`);
+  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 };
+    }
+    let message;
+    const detail = body.detail;
+    if (detail && typeof detail === "object") {
+      const detailObj = detail;
+      message = detailObj.error || detailObj.detail || detailObj.message || JSON.stringify(detail);
+    } else {
+      message = 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, options) {
+    const url = new URL(`${this.baseUrl}${endpoint}`);
     if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        if (value !== void 0 && value !== null) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null && value !== "") {
           url.searchParams.append(key, String(value));
         }
-      }
+      });
     }
-    const { maxRetries, initialDelay, maxDelay, backoffFactor } = this.config.retryConfig;
-    let delay = initialDelay;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const headers = {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": this.userAgent
+    };
+    const requestTimeout = options?.timeout ?? this.timeout;
+    const externalSignal = options?.signal;
+    let lastError;
+    let attempt = 0;
+    while (attempt <= this.retryConfig.maxRetries) {
+      if (externalSignal?.aborted) {
+        throw new IPTUAPIError("Request aborted", void 0, void 0, void 0);
+      }
       const controller = new AbortController();
-      const timeoutId = setTimeout(
-        () => controller.abort(),
-        this.config.timeout
-      );
+      const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+      const combinedSignal = externalSignal ? this.combineSignals(externalSignal, controller.signal) : controller.signal;
       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: {
-            "X-API-Key": this.apiKey,
-            "Content-Type": "application/json",
-            Accept: "application/json",
-            "User-Agent": "iptuapi-js/1.0.0"
-          },
-          body: body ? JSON.stringify(toSnakeCase(body)) : void 0,
-          signal: controller.signal
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: combinedSignal
         });
         clearTimeout(timeoutId);
-        this.updateRateLimitInfo(response.headers);
-        this._lastRequestId = response.headers.get("X-Request-ID");
-        if (!response.ok) {
-          await this.handleError(response);
+        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)`
+          );
         }
-        const data = await response.json();
-        return toCamelCase(data.data || data);
+        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) {
-          if (error.isRetryable() && attempt < maxRetries && this.config.retryConfig.retryableStatusCodes.includes(
-            error.statusCode || 0
-          )) {
-            await this.sleep(delay);
-            delay = Math.min(delay * backoffFactor, maxDelay);
-            continue;
-          }
           throw error;
         }
         if (error instanceof Error) {
           if (error.name === "AbortError") {
-            if (attempt < maxRetries) {
-              await this.sleep(delay);
-              delay = Math.min(delay * backoffFactor, maxDelay);
-              continue;
-            }
-            throw new TimeoutError(
-              `Timeout apos ${this.config.timeout}ms`,
-              this.config.timeout / 1e3
+            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 < maxRetries) {
+          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);
-            delay = Math.min(delay * backoffFactor, maxDelay);
+            attempt++;
             continue;
           }
-          throw new NetworkError(`Erro de conexao: ${error.message}`, error);
         }
-        throw new NetworkError("Erro desconhecido");
+        throw lastError || error;
       }
     }
-    throw new NetworkError("Maximo de tentativas excedido");
-  }
-  /**
-   * Atualiza informacoes de rate limit a partir dos headers.
-   */
-  updateRateLimitInfo(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) {
-      this._rateLimitInfo = {
-        limit: parseInt(limit, 10),
-        remaining: parseInt(remaining, 10),
-        resetAt: new Date(parseInt(reset, 10) * 1e3)
+    throw lastError || new IPTUAPIError("Max retries exceeded");
+  }
+  async consultaEndereco(paramsOrLogradouro, numeroOrOptions, cidade, options) {
+    let params;
+    let requestOptions;
+    if (typeof paramsOrLogradouro === "string") {
+      const numero = typeof numeroOrOptions === "string" ? numeroOrOptions : void 0;
+      requestOptions = typeof numeroOrOptions === "object" ? numeroOrOptions : options;
+      params = {
+        logradouro: paramsOrLogradouro,
+        numero,
+        cidade: cidade || "sp"
+      };
+    } else {
+      requestOptions = numeroOrOptions;
+      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,
+      void 0,
+      requestOptions
+    );
   }
   /**
-   * Converte resposta HTTP em excecao apropriada.
-   */
-  async handleError(response) {
-    const requestId = response.headers.get("X-Request-ID") || void 0;
-    let data = {};
-    let message = "Erro desconhecido";
-    try {
-      data = await response.json();
-      message = data.detail || data.message || message;
-    } catch {
-      message = response.statusText || message;
-    }
-    switch (response.status) {
-      case 401:
-        throw new AuthenticationError(message, requestId);
-      case 403:
-        throw new ForbiddenError(
-          message,
-          data.required_plan,
-          requestId
-        );
-      case 404:
-        throw new NotFoundError(
-          message,
-          data.resource,
-          requestId
-        );
-      case 429: {
-        const retryAfter = parseInt(
-          response.headers.get("Retry-After") || "60",
-          10
-        );
-        throw new RateLimitError(message, retryAfter, requestId);
-      }
-      case 400:
-      case 422:
-        throw new ValidationError(
-          message,
-          data.errors,
-          response.status,
-          requestId
-        );
-      default:
-        if (response.status >= 500) {
-          throw new ServerError(message, response.status, requestId);
-        }
-        throw new IPTUAPIError(message, response.status, requestId, data);
-    }
-  }
-  /**
-   * Aguarda um tempo em milissegundos.
+   * 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 (incluirHistorico, incluirComparaveis)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Dados completos do imóvel
    */
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+  async consultaSQL(sql, cidade = "sp", options, requestOptions) {
+    return this.request("GET", `/consulta/sql/${sql}`, {
+      cidade,
+      incluir_historico: options?.incluirHistorico,
+      incluir_comparaveis: options?.incluirComparaveis
+    }, void 0, requestOptions);
   }
-  // ==================== CONSULTAS IPTU ====================
   /**
-   * Consulta imoveis por endereco.
+   * Busca imóveis por CEP.
    *
-   * @param logradouro - Nome da rua/avenida
-   * @param numero - Numero do imovel
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Lista de imoveis encontrados
+   * @param cep - CEP do imóvel
+   * @param cidade - Cidade da consulta
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Lista de imóveis no CEP
    */
-  async consultaEndereco(logradouro, numero, cidade = "sp") {
-    const response = await this.makeRequest("GET", "/consulta/endereco", {
-      logradouro,
-      numero,
-      cidade
-    });
-    return Array.isArray(response) ? response : [];
+  async consultaCEP(cep, cidade = "sp", requestOptions) {
+    const cleanCep = cep.replace(/\D/g, "");
+    return this.request(
+      "GET",
+      `/consulta/cep/${cleanCep}`,
+      { cidade },
+      void 0,
+      requestOptions
+    );
   }
   /**
-   * Consulta imovel por numero SQL/Indice Cadastral.
-   * Requer plano Starter ou superior.
+   * Consulta zoneamento por coordenadas.
    *
-   * @param sql - Numero SQL (SP), Indice Cadastral (BH) ou Sequencial (Recife)
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Lista de imoveis encontrados
+   * @param latitude - Latitude do ponto
+   * @param longitude - Longitude do ponto
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Dados de zoneamento
    */
-  async consultaSQL(sql, cidade = "sp") {
-    const response = await this.makeRequest("GET", "/consulta/sql", {
-      sql,
-      cidade
-    });
-    return Array.isArray(response) ? response : [];
-  }
+  async consultaZoneamento(latitude, longitude, requestOptions) {
+    return this.request("GET", "/consulta/zoneamento", {
+      latitude,
+      longitude
+    }, void 0, requestOptions);
+  }
+  // ===========================================================================
+  // Valuation Endpoints (Pro+)
+  // ===========================================================================
   /**
-   * Consulta imoveis por CEP.
+   * Estima o valor de mercado do imóvel usando ML.
+   * Disponível apenas para planos Pro e Enterprise.
    *
-   * @param cep - CEP do endereco
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Lista de imoveis encontrados
+   * @param params - Parâmetros do imóvel
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Estimativa de valor
+   * @throws {ForbiddenError} Se o plano não permitir
    */
-  async consultaCEP(cep, cidade = "sp") {
-    const response = await this.makeRequest("GET", "/consulta/cep", {
-      cep,
-      cidade
-    });
-    return Array.isArray(response) ? response : [];
+  async valuationEstimate(params, requestOptions) {
+    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"
+      },
+      requestOptions
+    );
   }
   /**
-   * Consulta zoneamento por coordenadas.
+   * Valuation em lote (até 100 imóveis).
+   * Disponível apenas para plano Enterprise.
    *
-   * @param latitude - Latitude do ponto
-   * @param longitude - Longitude do ponto
-   * @returns Informacoes de zoneamento
+   * @param imoveis - Lista de imóveis para avaliar
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Resultados de valuation para cada imóvel
    */
-  async consultaZoneamento(latitude, longitude) {
-    return this.makeRequest("GET", "/consulta/zoneamento", {
-      lat: latitude,
-      lng: longitude
-    });
+  async valuationBatch(imoveis, requestOptions) {
+    return this.request(
+      "POST",
+      "/valuation/estimate/batch",
+      void 0,
+      { imoveis },
+      requestOptions
+    );
   }
-  // ==================== VALUATION ====================
   /**
-   * Calcula estimativa de valor de mercado.
-   * Requer plano Pro ou superior.
+   * Busca imóveis comparáveis para análise.
    *
-   * @param params - Parametros da avaliacao
-   * @returns Avaliacao de mercado
+   * @param bairro - Nome do bairro
+   * @param areaMin - Área mínima em m²
+   * @param areaMax - Área máxima em m²
+   * @param options - Opções adicionais
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Lista de imóveis comparáveis
    */
-  async valuationEstimate(params) {
-    return this.makeRequest("GET", "/valuation/estimate", {
-      area_terreno: params.areaTerreno,
-      area_construida: params.areaConstruida,
-      bairro: params.bairro,
-      cidade: params.cidade || "sp",
-      zona: params.zona,
-      tipo_uso: params.tipoUso,
-      tipo_padrao: params.tipoPadrao,
-      ano_construcao: params.anoConstrucao
-    });
+  async valuationComparables(bairro, areaMin, areaMax, options, requestOptions) {
+    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
+    }, void 0, requestOptions);
   }
   /**
-   * Busca imoveis comparaveis.
-   * Requer plano Pro ou superior.
+   * Estatísticas de valores por bairro.
    *
-   * @param params - Parametros da busca
-   * @returns Lista de imoveis comparaveis
+   * @param bairro - Nome do bairro
+   * @param cidade - Cidade da consulta
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Estatísticas: média, mediana, min, max, etc
    */
-  async valuationComparables(params) {
-    const response = await this.makeRequest(
+  async valuationStatistics(bairro, cidade = "sp", requestOptions) {
+    return this.request(
       "GET",
-      "/valuation/comparables",
-      {
-        bairro: params.bairro,
-        area_min: params.areaMin,
-        area_max: params.areaMax,
-        cidade: params.cidade || "sp",
-        limit: params.limit || 10
-      }
+      `/valuation/statistics/${encodeURIComponent(bairro)}`,
+      { cidade },
+      void 0,
+      requestOptions
     );
-    return Array.isArray(response) ? response : [];
   }
+  // ===========================================================================
+  // Dados Endpoints
+  // ===========================================================================
   /**
-   * Avalia imovel por endereco OU SQL.
-   * Combina dados do modelo AVM (ML) com transacoes ITBI reais.
-   * Requer plano Pro ou superior.
+   * Histórico de valores IPTU de um imóvel.
    *
-   * @param params - Parametros da avaliacao (sql OU logradouro+numero)
-   * @returns Avaliacao completa do imovel
+   * @param sql - Número SQL do imóvel
+   * @param cidade - Cidade da consulta
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Lista com histórico anual
    */
-  async valuationEvaluate(params) {
-    const body = {
-      cidade: params.cidade || "sp",
-      incluirItbi: params.incluirItbi ?? true,
-      incluirComparaveis: params.incluirComparaveis ?? true
-    };
-    if (params.sql) {
-      body.sql = params.sql;
-    } else {
-      if (params.logradouro) body.logradouro = params.logradouro;
-      if (params.numero !== void 0) body.numero = params.numero;
-      if (params.complemento) body.complemento = params.complemento;
-      if (params.bairro) body.bairro = params.bairro;
-    }
-    return this.makeRequest(
-      "POST",
-      "/valuation/evaluate",
+  async dadosIPTUHistorico(sql, cidade = "sp", requestOptions) {
+    return this.request(
+      "GET",
+      `/dados/iptu/historico/${sql}`,
+      { cidade },
       void 0,
-      body
+      requestOptions
     );
   }
-  // ==================== ITBI ====================
   /**
-   * Consulta status de transacao ITBI.
+   * Consulta dados de empresa por CNPJ.
    *
-   * @param protocolo - Numero do protocolo ITBI
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Status da transacao
+   * @param cnpj - CNPJ da empresa
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Dados cadastrais
    */
-  async itbiStatus(protocolo, cidade = "sp") {
-    return this.makeRequest("GET", "/itbi/status", {
-      protocolo,
-      cidade
-    });
+  async dadosCNPJ(cnpj, requestOptions) {
+    const cleanCnpj = cnpj.replace(/\D/g, "");
+    return this.request(
+      "GET",
+      `/dados/cnpj/${cleanCnpj}`,
+      void 0,
+      void 0,
+      requestOptions
+    );
   }
   /**
-   * Calcula valor do ITBI.
+   * Índice IPCA histórico.
    *
-   * @param params - Parametros do calculo
-   * @returns Calculo do ITBI
+   * @param dataInicio - Data inicial (YYYY-MM)
+   * @param dataFim - Data final (YYYY-MM)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Série histórica do IPCA
    */
-  async itbiCalcular(params) {
-    return this.makeRequest("POST", "/itbi/calcular", void 0, {
-      sql: params.sql,
-      valorTransacao: params.valorTransacao,
-      cidade: params.cidade || "sp"
-    });
+  async dadosIPCA(dataInicio, dataFim, requestOptions) {
+    return this.request(
+      "GET",
+      "/dados/ipca",
+      {
+        data_inicio: dataInicio,
+        data_fim: dataFim
+      },
+      void 0,
+      requestOptions
+    );
   }
   /**
-   * Consulta historico de transacoes ITBI de um imovel.
-   * Requer plano Starter ou superior.
+   * Correção monetária pelo IPCA.
    *
-   * @param sql - Numero SQL do imovel
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Lista de transacoes historicas
+   * @param valor - Valor a corrigir
+   * @param dataOrigem - Data do valor original (YYYY-MM)
+   * @param dataDestino - Data destino (default: atual)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Valor corrigido e fator de correção
    */
-  async itbiHistorico(sql, cidade = "sp") {
-    const response = await this.makeRequest(
+  async dadosIPCACorrigir(valor, dataOrigem, dataDestino, requestOptions) {
+    return this.request(
       "GET",
-      "/itbi/historico",
-      { sql, cidade }
+      "/dados/ipca/corrigir",
+      {
+        valor,
+        data_origem: dataOrigem,
+        data_destino: dataDestino
+      },
+      void 0,
+      requestOptions
     );
-    return Array.isArray(response) ? response : [];
   }
+  // ===========================================================================
+  // IPTU Tools Endpoints (Ferramentas IPTU 2026)
+  // ===========================================================================
   /**
-   * Consulta aliquotas ITBI vigentes.
+   * Lista todas as cidades com calendario de IPTU disponivel.
    *
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Aliquotas vigentes
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Lista de cidades com codigo, nome, desconto e parcelas
    */
-  async itbiAliquotas(cidade = "sp") {
-    return this.makeRequest("GET", "/itbi/aliquotas", { cidade });
+  async iptuToolsCidades(requestOptions) {
+    return this.request("GET", "/iptu-tools/cidades", void 0, void 0, requestOptions);
   }
   /**
-   * Consulta isencoes ITBI disponiveis.
+   * Retorna o calendario completo de IPTU para a cidade especificada.
    *
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Lista de isencoes disponiveis
+   * @param cidade - Codigo da cidade (sp, bh, rj, recife, curitiba, poa, fortaleza)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Calendario com vencimentos, descontos, alertas e novidades
    */
-  async itbiIsencoes(cidade = "sp") {
-    const response = await this.makeRequest(
-      "GET",
-      "/itbi/isencoes",
-      { cidade }
-    );
-    return Array.isArray(response) ? response : [];
+  async iptuToolsCalendario(cidade = "sp", requestOptions) {
+    return this.request("GET", "/iptu-tools/calendario", { cidade }, void 0, requestOptions);
   }
   /**
-   * Gera guia de pagamento ITBI.
-   * Requer plano Starter ou superior.
+   * Simula as opcoes de pagamento do IPTU (a vista vs parcelado).
    *
-   * @param params - Parametros da guia
-   * @returns Guia de pagamento gerada
+   * @param valorIptu - Valor total do IPTU
+   * @param cidade - Codigo da cidade
+   * @param valorVenal - Valor venal do imovel (para verificar isencao)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Comparativo entre pagamento a vista e parcelado com recomendacao
    */
-  async itbiGuia(params) {
-    return this.makeRequest("POST", "/itbi/guia", void 0, {
-      sql: params.sql,
-      valorTransacao: params.valorTransacao,
-      comprador: params.comprador,
-      vendedor: params.vendedor,
-      cidade: params.cidade || "sp"
-    });
+  async iptuToolsSimulador(valorIptu, cidade = "sp", valorVenal, requestOptions) {
+    const body = {
+      valor_iptu: valorIptu,
+      cidade
+    };
+    if (valorVenal !== void 0) {
+      body.valor_venal = valorVenal;
+    }
+    return this.request("POST", "/iptu-tools/simulador", void 0, body, requestOptions);
   }
   /**
-   * Valida autenticidade de uma guia ITBI.
+   * Verifica se um imovel e elegivel para isencao de IPTU.
    *
-   * @param protocolo - Numero do protocolo da guia
-   * @param cidade - Codigo da cidade (sp, bh, recife)
-   * @returns Resultado da validacao
+   * @param valorVenal - Valor venal do imovel
+   * @param cidade - Codigo da cidade
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Elegibilidade para isencao total ou parcial
    */
-  async itbiValidarGuia(protocolo, cidade = "sp") {
-    return this.makeRequest("GET", "/itbi/validar", {
-      protocolo,
+  async iptuToolsIsencao(valorVenal, cidade = "sp", requestOptions) {
+    return this.request("GET", "/iptu-tools/isencao", {
+      valor_venal: valorVenal,
       cidade
-    });
+    }, void 0, requestOptions);
   }
   /**
-   * Simula calculo de ITBI.
+   * Retorna informacoes sobre o proximo vencimento do IPTU.
    *
-   * @param params - Parametros da simulacao
-   * @returns Resultado da simulacao
+   * @param cidade - Codigo da cidade
+   * @param parcela - Numero da parcela (1-12)
+   * @param requestOptions - Opções de request (signal para cancelamento, timeout)
+   * @returns Data de vencimento, dias restantes e status
    */
-  async itbiSimular(params) {
-    return this.makeRequest("POST", "/itbi/simular", void 0, {
-      valorTransacao: params.valorTransacao,
-      cidade: params.cidade || "sp",
-      tipoFinanciamento: params.tipoFinanciamento,
-      valorFinanciado: params.valorFinanciado
-    });
+  async iptuToolsProximoVencimento(cidade = "sp", parcela = 1, requestOptions) {
+    return this.request("GET", "/iptu-tools/proximo-vencimento", {
+      cidade,
+      parcela
+    }, void 0, requestOptions);
   }
 };
+var index_default = IPTUClient;
 export {
   AuthenticationError,
+  CidadeEnum,
   ForbiddenError,
   IPTUAPIError,
   IPTUClient,
@@ -613,5 +669,6 @@ export {
   RateLimitError,
   ServerError,
   TimeoutError,
-  ValidationError
+  ValidationError,
+  index_default as default
 };