iptuapi 2.1.0 → 2.1.2

package/dist/index.d.mts

@@ -1,518 +1,481 @@
 /**
- * Tipos e interfaces para a IPTU API.
+ * IPTU API - JavaScript/TypeScript SDK
+ *
+ * SDK oficial para integração com a IPTU API.
+ * Suporta retry automático, logging e rate limit tracking.
+ *
+ * @example
+ * ```typescript
+ * import { IPTUClient } from 'iptuapi';
+ *
+ * const client = new IPTUClient('sua_api_key');
+ * const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
+ * console.log(resultado);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Com configuração customizada
+ * const client = new IPTUClient('sua_api_key', {
+ *   timeout: 60000,
+ *   retries: 5,
+ *   logger: console,
+ * });
+ * ```
  */
-interface RetryConfig {
-    maxRetries: number;
-    initialDelay: number;
-    maxDelay: number;
-    backoffFactor: number;
-    retryableStatusCodes: number[];
-}
-interface ClientConfig {
-    baseUrl: string;
-    timeout: number;
-    retryConfig: RetryConfig;
-}
-interface ClientOptions {
-    baseUrl?: string;
-    timeout?: number;
-    retryConfig?: Partial<RetryConfig>;
-}
+type Cidade = 'sp' | 'bh' | 'recife' | 'poa' | 'fortaleza' | 'curitiba' | 'rj' | 'brasilia';
+declare const CidadeEnum: {
+    readonly SAO_PAULO: Cidade;
+    readonly BELO_HORIZONTE: Cidade;
+    readonly RECIFE: Cidade;
+    readonly PORTO_ALEGRE: Cidade;
+    readonly FORTALEZA: Cidade;
+    readonly CURITIBA: Cidade;
+    readonly RIO_DE_JANEIRO: Cidade;
+    readonly BRASILIA: Cidade;
+};
 interface RateLimitInfo {
     limit: number;
     remaining: number;
-    resetAt: Date;
+    reset: number;
+    resetDate: Date;
 }
-interface Imovel {
+interface ConsultaEnderecoParams {
+    logradouro: string;
+    numero?: string;
+    complemento?: string;
+    cidade?: Cidade;
+    incluirHistorico?: boolean;
+    incluirComparaveis?: boolean;
+    incluirZoneamento?: boolean;
+}
+interface ConsultaEnderecoResult {
     sql: string;
     logradouro: string;
-    numero: string;
-    bairro: string;
+    numero?: string;
+    complemento?: string;
+    bairro?: string;
     cep?: string;
-    areaTerreno?: number;
-    areaConstruida?: number;
-    valorVenal?: number;
-    valorVenalTerreno?: number;
-    valorVenalConstrucao?: number;
-    anoConstrucao?: number;
-    uso?: string;
-    padrao?: string;
-    testada?: number;
-    fracaoIdeal?: number;
-    quantidadePavimentos?: number;
-}
-interface Zoneamento {
-    zona: string;
-    usoPermitido: string;
-    coeficienteAproveitamento?: number;
-    taxaOcupacao?: number;
-    gabarito?: number;
-    recuoFrontal?: number;
-    legislacao?: string;
-}
-interface Valuation {
-    valorEstimado: number;
-    valorMinimo: number;
-    valorMaximo: number;
-    confianca: number;
-    valorM2: number;
-    metodologia: string;
-    dataReferencia: string;
-}
-interface ValuationParams {
-    areaTerreno: number;
-    areaConstruida: number;
-    bairro: string;
-    cidade?: string;
+    area_terreno?: number;
+    area_construida?: number;
+    valor_venal_terreno?: number;
+    valor_venal_construcao?: number;
+    valor_venal_total?: number;
+    iptu_valor?: number;
+    ano_construcao?: number;
+    tipo_uso?: string;
     zona?: string;
-    tipoUso?: string;
-    tipoPadrao?: string;
-    anoConstrucao?: number;
+    historico?: HistoricoItem[];
+    comparaveis?: ComparavelItem[];
+    zoneamento?: ZoneamentoResult;
 }
-interface Comparavel {
+interface ConsultaSQLResult {
     sql: string;
-    logradouro: string;
-    bairro: string;
-    areaConstruida: number;
-    valorVenal: number;
-    valorM2: number;
-    distanciaKm?: number;
-}
-interface ComparablesParams {
-    bairro: string;
-    areaMin: number;
-    areaMax: number;
-    cidade?: string;
-    limit?: number;
-}
-interface ITBIStatus {
-    protocolo: string;
-    status: string;
-    dataSolicitacao: string;
-    valorTransacao: number;
-    valorVenalReferencia: number;
-    baseCalculo: number;
-    aliquota: number;
-    valorITBI: number;
-    dataAprovacao?: string;
+    ano?: number;
+    valor_venal?: number;
+    valor_venal_terreno?: number;
+    valor_venal_construcao?: number;
+    valor_venal_total?: number;
+    iptu_valor?: number;
+    logradouro?: string;
+    numero?: string;
+    bairro?: string;
+    area_terreno?: number;
+    area_construida?: number;
 }
-interface ITBICalculo {
-    sql: string;
-    valorTransacao: number;
-    valorVenalReferencia: number;
-    baseCalculo: number;
-    aliquota: number;
-    valorITBI: number;
-    isencaoAplicavel: boolean;
-    fundamentacaoLegal: string;
+interface HistoricoItem {
+    ano: number;
+    valor_venal_terreno?: number;
+    valor_venal_construcao?: number;
+    valor_venal_total?: number;
+    iptu_valor?: number;
 }
-interface ITBICalculoParams {
-    sql: string;
-    valorTransacao: number;
-    cidade?: string;
+interface ComparavelItem {
+    sql?: string;
+    logradouro?: string;
+    numero?: string;
+    bairro?: string;
+    area_terreno?: number;
+    area_construida?: number;
+    valor_venal_total?: number;
+    distancia_metros?: number;
 }
-interface ITBIHistorico {
-    protocolo: string;
-    dataTransacao: string;
-    tipoTransacao: string;
-    valorTransacao: number;
-    valorITBI: number;
+interface ZoneamentoResult {
+    zona?: string;
+    zona_descricao?: string;
+    coeficiente_aproveitamento_basico?: number;
+    coeficiente_aproveitamento_maximo?: number;
+    taxa_ocupacao_maxima?: number;
+    gabarito_maximo?: number;
 }
-interface ITBIAliquota {
-    cidade: string;
-    aliquotaPadrao: number;
-    aliquotaFinanciamentoSFH: number;
-    valorMinimoIsencao: number;
-    baseLegal: string;
-    vigencia: string;
+interface ValuationParams {
+    area_terreno: number;
+    area_construida: number;
+    bairro: string;
+    zona: string;
+    tipo_uso: string;
+    tipo_padrao: string;
+    ano_construcao?: number;
+    cidade?: Cidade;
+}
+interface ValuationResult {
+    valor_estimado: number;
+    valor_minimo?: number;
+    valor_maximo?: number;
+    confianca?: number;
+    metodo?: string;
+    comparaveis_utilizados?: number;
+    data_avaliacao?: string;
+}
+interface BatchValuationResult {
+    resultados: ValuationResult[];
+    total_processados: number;
+    total_erros: number;
+    erros?: Array<{
+        index: number;
+        error: string;
+    }>;
 }
-interface ITBIIsencao {
-    tipo: string;
-    descricao: string;
-    requisitos: string[];
-    baseLegal: string;
+declare class IPTUAPIError extends Error {
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly responseBody?: Record<string, unknown>;
+    constructor(message: string, statusCode?: number, requestId?: string, responseBody?: Record<string, unknown>);
+    get isRetryable(): boolean;
 }
-interface Pessoa {
-    nome: string;
-    documento: string;
-    email?: string;
+declare class AuthenticationError extends IPTUAPIError {
+    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
-interface ITBIGuiaParams {
-    sql: string;
-    valorTransacao: number;
-    comprador: Pessoa;
-    vendedor: Pessoa;
-    cidade?: string;
+declare class ForbiddenError extends IPTUAPIError {
+    readonly requiredPlan?: string;
+    constructor(message?: string, requiredPlan?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
-interface ITBIGuia {
-    protocolo: string;
-    codigoBarras: string;
-    linhaDigitavel: string;
-    dataEmissao: string;
-    dataVencimento: string;
-    valorITBI: number;
+declare class NotFoundError extends IPTUAPIError {
+    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
-interface ITBIValidacao {
-    protocolo: string;
-    valido: boolean;
-    pago: boolean;
-    dataPagamento?: string;
-    valorPago?: number;
+declare class RateLimitError extends IPTUAPIError {
+    readonly retryAfter?: number;
+    readonly limit?: number;
+    readonly remaining?: number;
+    constructor(message?: string, retryAfter?: number, limit?: number, remaining?: number, requestId?: string, responseBody?: Record<string, unknown>);
+    get isRetryable(): boolean;
 }
-interface ITBISimularParams {
-    valorTransacao: number;
-    cidade?: string;
-    tipoFinanciamento?: 'sfh' | 'nao_sfh';
-    valorFinanciado?: number;
+declare class ValidationError extends IPTUAPIError {
+    readonly errors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message?: string, errors?: Array<{
+        field: string;
+        message: string;
+    }>, requestId?: string, responseBody?: Record<string, unknown>);
 }
-interface ITBISimulacao {
-    valorTransacao: number;
-    valorFinanciado: number;
-    valorNaoFinanciado: number;
-    aliquotaSFH: number;
-    aliquotaPadrao: number;
-    valorITBIFinanciado: number;
-    valorITBINaoFinanciado: number;
-    valorITBITotal: number;
-    economiaSFH: number;
+declare class ServerError extends IPTUAPIError {
+    constructor(message?: string, statusCode?: number, requestId?: string, responseBody?: Record<string, unknown>);
+    get isRetryable(): boolean;
 }
-interface EvaluateParams {
-    /** Numero SQL do imovel (alternativa ao endereco) */
-    sql?: string;
-    /** Nome da rua/avenida (alternativa ao SQL) */
-    logradouro?: string;
-    /** Numero do imovel */
-    numero?: number;
-    /** Apartamento, sala, etc. */
-    complemento?: string;
-    /** Bairro */
-    bairro?: string;
-    /** Codigo da cidade (sp, bh) */
-    cidade?: string;
-    /** Incluir estimativa baseada em ITBI */
-    incluirItbi?: boolean;
-    /** Incluir lista de imoveis comparaveis */
-    incluirComparaveis?: boolean;
+declare class TimeoutError extends IPTUAPIError {
+    readonly timeoutMs?: number;
+    constructor(message?: string, timeoutMs?: number);
+    get isRetryable(): boolean;
 }
-interface AVMEstimate {
-    /** Valor estimado em R$ */
-    valorEstimado: number;
-    /** Valor minimo do intervalo */
-    valorMinimo: number;
-    /** Valor maximo do intervalo */
-    valorMaximo: number;
-    /** Valor por m2 */
-    valorM2: number;
-    /** Nivel de confianca (0-1) */
-    confianca: number;
-    /** Versao do modelo */
-    modeloVersao: string;
+declare class NetworkError extends IPTUAPIError {
+    readonly originalError?: Error;
+    constructor(message?: string, originalError?: Error);
+    get isRetryable(): boolean;
 }
-interface ITBIMarketEstimate {
-    /** Valor estimado em R$ */
-    valorEstimado: number;
-    /** Valor minimo da faixa */
-    faixaMinima: number;
-    /** Valor maximo da faixa */
-    faixaMaxima: number;
-    /** Valor por m2 (mediana) */
-    valorM2Mediana: number;
-    /** Total de transacoes analisadas */
-    totalTransacoes: number;
-    /** Periodo considerado */
-    periodo: string;
-    /** Fonte dos dados */
-    fonte: string;
+interface Logger {
+    debug?(message: string, ...args: unknown[]): void;
+    info?(message: string, ...args: unknown[]): void;
+    warn?(message: string, ...args: unknown[]): void;
+    error?(message: string, ...args: unknown[]): void;
 }
-interface FinalValuation {
-    /** Valor estimado final */
-    estimado: number;
-    /** Valor minimo */
-    minimo: number;
-    /** Valor maximo */
-    maximo: number;
-    /** Metodo utilizado (blend_avm_itbi, avm_only, itbi_only) */
-    metodo: string;
-    /** Peso do AVM no calculo (0-1) */
-    pesoAvm: number;
-    /** Peso do ITBI no calculo (0-1) */
-    pesoItbi: number;
-    /** Nivel de confianca */
-    confianca: number;
-    /** Nota explicativa */
-    nota?: string;
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay in ms between retries (default: 500) */
+    initialDelay: number;
+    /** Maximum delay in ms between retries (default: 10000) */
+    maxDelay: number;
+    /** Backoff factor (default: 2) */
+    backoffFactor: number;
+    /** Status codes that trigger retry (default: [429, 500, 502, 503, 504]) */
+    retryableStatuses: number[];
 }
-interface PropertyEvaluation {
-    /** Se a avaliacao foi bem sucedida */
-    success: boolean;
-    /** Dados cadastrais do imovel */
-    imovel: Record<string, unknown>;
-    /** Avaliacao pelo modelo ML (AVM) */
-    avaliacaoAvm?: AVMEstimate;
-    /** Avaliacao por transacoes ITBI reais */
-    avaliacaoItbi?: ITBIMarketEstimate;
-    /** Valor final combinado */
-    valorFinal: FinalValuation;
-    /** Imoveis comparaveis */
-    comparaveis?: Record<string, unknown>;
-    /** Metadados da avaliacao */
-    metadata: {
-        processadoEm: string;
-        fontes: string[];
-        cidade: string;
-    };
+interface IPTUClientOptions {
+    /** Base URL for the API (default: https://iptuapi.com.br/api/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: Partial<RetryConfig>;
+    /** Logger instance for debugging */
+    logger?: Logger;
+    /** Enable request logging (default: false) */
+    logRequests?: boolean;
+    /** Enable response logging (default: false) */
+    logResponses?: boolean;
+    /** Custom User-Agent header */
+    userAgent?: string;
+}
+interface RequestOptions {
+    /** AbortSignal for request cancellation */
+    signal?: AbortSignal;
+    /** Override timeout for this specific request (in milliseconds) */
+    timeout?: number;
 }
-type Cidade = 'sp' | 'bh' | 'recife' | 'poa' | 'fortaleza' | 'curitiba' | 'rj' | 'brasilia';
-
-/**
- * Cliente principal para a IPTU API.
- */
-
-/**
- * Cliente para interagir com a IPTU API.
- */
 declare class IPTUClient {
     private readonly apiKey;
-    private readonly config;
-    private _rateLimitInfo;
-    private _lastRequestId;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly logger?;
+    private readonly logRequests;
+    private readonly logResponses;
+    private readonly userAgent;
+    private _rateLimit?;
+    private _lastRequestId?;
+    constructor(apiKey: string, options?: IPTUClientOptions);
+    /** Rate limit info from last request */
+    get rateLimit(): RateLimitInfo | undefined;
+    /** Request ID from last request (useful for support) */
+    get lastRequestId(): string | undefined;
+    private log;
+    private sleep;
+    private combineSignals;
+    private calculateDelay;
+    private extractRateLimit;
+    private handleErrorResponse;
+    private request;
     /**
-     * Cria uma nova instancia do cliente.
+     * Busca dados de IPTU por endereço.
      *
-     * @param apiKey - Chave de API para autenticacao
-     * @param options - Opcoes de configuracao
-     */
-    constructor(apiKey: string, options?: ClientOptions);
-    /**
-     * Retorna informacoes do rate limit da ultima requisicao.
-     */
-    get rateLimitInfo(): RateLimitInfo | null;
-    /**
-     * Retorna o ID da ultima requisicao.
+     * @param params - Parâmetros da consulta
+     * @param options - Opções de request (signal para cancelamento, timeout)
+     * @returns Dados do imóvel encontrado
+     * @throws {NotFoundError} Se o imóvel não for encontrado
+     * @throws {ValidationError} Se os parâmetros forem inválidos
+     * @throws {AuthenticationError} Se a API Key for inválida
+     * @throws {RateLimitError} Se exceder o limite de requisições
      */
-    get lastRequestId(): string | null;
+    consultaEndereco(params: ConsultaEnderecoParams, options?: RequestOptions): Promise<ConsultaEnderecoResult>;
+    consultaEndereco(logradouro: string, numero?: string, cidade?: Cidade, options?: RequestOptions): Promise<ConsultaEnderecoResult>;
     /**
-     * Executa uma requisicao HTTP com retry.
-     */
-    private makeRequest;
-    /**
-     * Atualiza informacoes de rate limit a partir dos headers.
-     */
-    private updateRateLimitInfo;
-    /**
-     * Converte resposta HTTP em excecao apropriada.
-     */
-    private handleError;
-    /**
-     * 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
      */
-    private sleep;
+    consultaSQL(sql: string, cidade?: Cidade, options?: {
+        incluirHistorico?: boolean;
+        incluirComparaveis?: boolean;
+    }, requestOptions?: RequestOptions): Promise<ConsultaSQLResult>;
     /**
-     * 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
      */
-    consultaEndereco(logradouro: string, numero: string, cidade?: Cidade): Promise<Imovel[]>;
+    consultaCEP(cep: string, cidade?: Cidade, requestOptions?: RequestOptions): Promise<ConsultaEnderecoResult[]>;
     /**
-     * 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
      */
-    consultaSQL(sql: string, cidade?: Cidade): Promise<Imovel[]>;
+    consultaZoneamento(latitude: number, longitude: number, requestOptions?: RequestOptions): Promise<ZoneamentoResult>;
     /**
-     * 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
      */
-    consultaCEP(cep: string, cidade?: Cidade): Promise<Imovel[]>;
+    valuationEstimate(params: ValuationParams, requestOptions?: RequestOptions): Promise<ValuationResult>;
     /**
-     * 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
      */
-    consultaZoneamento(latitude: number, longitude: number): Promise<Zoneamento>;
+    valuationBatch(imoveis: ValuationParams[], requestOptions?: RequestOptions): Promise<BatchValuationResult>;
     /**
-     * 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
      */
-    valuationEstimate(params: ValuationParams): Promise<Valuation>;
+    valuationComparables(bairro: string, areaMin: number, areaMax: number, options?: {
+        tipoUso?: string;
+        cidade?: Cidade;
+        limit?: number;
+    }, requestOptions?: RequestOptions): Promise<ComparavelItem[]>;
     /**
-     * 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
      */
-    valuationComparables(params: ComparablesParams): Promise<Comparavel[]>;
+    valuationStatistics(bairro: string, cidade?: Cidade, requestOptions?: RequestOptions): Promise<Record<string, unknown>>;
     /**
-     * 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
      */
-    valuationEvaluate(params: EvaluateParams): Promise<PropertyEvaluation>;
+    dadosIPTUHistorico(sql: string, cidade?: Cidade, requestOptions?: RequestOptions): Promise<HistoricoItem[]>;
     /**
-     * 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
      */
-    itbiStatus(protocolo: string, cidade?: Cidade): Promise<ITBIStatus>;
+    dadosCNPJ(cnpj: string, requestOptions?: RequestOptions): Promise<Record<string, unknown>>;
     /**
-     * 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
      */
-    itbiCalcular(params: ITBICalculoParams): Promise<ITBICalculo>;
+    dadosIPCA(dataInicio?: string, dataFim?: string, requestOptions?: RequestOptions): Promise<Array<Record<string, unknown>>>;
     /**
-     * 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
      */
-    itbiHistorico(sql: string, cidade?: Cidade): Promise<ITBIHistorico[]>;
+    dadosIPCACorrigir(valor: number, dataOrigem: string, dataDestino?: string, requestOptions?: RequestOptions): Promise<{
+        valor_corrigido: number;
+        fator: number;
+    }>;
     /**
-     * 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
      */
-    itbiAliquotas(cidade?: Cidade): Promise<ITBIAliquota>;
+    iptuToolsCidades(requestOptions?: RequestOptions): Promise<{
+        cidades: Array<{
+            codigo: string;
+            nome: string;
+            ano: number;
+            desconto_vista: string;
+            parcelas_max: number;
+            site_oficial: string;
+        }>;
+        total: number;
+    }>;
     /**
-     * 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
      */
-    itbiIsencoes(cidade?: Cidade): Promise<ITBIIsencao[]>;
+    iptuToolsCalendario(cidade?: Cidade, requestOptions?: RequestOptions): Promise<{
+        cidade: string;
+        ano: number;
+        desconto_vista_percentual: number;
+        desconto_vista_texto: string;
+        parcelas_max: number;
+        valor_minimo_parcela: number;
+        isencao_valor_venal?: number;
+        isencao_texto?: string;
+        site_oficial: string;
+        novidades?: string[];
+        alertas?: string[];
+        formas_pagamento?: string[];
+        vencimentos_cota_unica: string[];
+        vencimentos_parcelado: string[];
+        proximo_vencimento?: string;
+        dias_para_proximo_vencimento?: number;
+    }>;
     /**
-     * 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
      */
-    itbiGuia(params: ITBIGuiaParams): Promise<ITBIGuia>;
+    iptuToolsSimulador(valorIptu: number, cidade?: Cidade, valorVenal?: number, requestOptions?: RequestOptions): Promise<{
+        valor_original: number;
+        valor_vista: number;
+        desconto_vista: number;
+        desconto_percentual: number;
+        parcelas: number;
+        valor_parcela: number;
+        valor_total_parcelado: number;
+        economia_vista: number;
+        economia_percentual: number;
+        recomendacao: string;
+        elegivel_isencao: boolean;
+        isencao_mensagem?: string;
+        cidade: string;
+        ano: number;
+        proximo_vencimento?: string;
+    }>;
     /**
-     * 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
      */
-    itbiValidarGuia(protocolo: string, cidade?: Cidade): Promise<ITBIValidacao>;
+    iptuToolsIsencao(valorVenal: number, cidade?: Cidade, requestOptions?: RequestOptions): Promise<{
+        cidade: string;
+        valor_venal: number;
+        limite_isencao: number;
+        elegivel_isencao_total: boolean;
+        elegivel_desconto_parcial: boolean;
+        desconto_estimado_percentual?: number;
+        mensagem: string;
+        requisitos_adicionais: string[];
+    }>;
     /**
-     * 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
      */
-    itbiSimular(params: ITBISimularParams): Promise<ITBISimulacao>;
-}
-
-/**
- * Excecoes customizadas para a IPTU API.
- */
-interface ErrorDetails {
-    error: string;
-    message: string;
-    statusCode?: number;
-    requestId?: string;
-    retryable: boolean;
-    [key: string]: unknown;
-}
-/**
- * Excecao base para todos os erros da IPTU API.
- */
-declare class IPTUAPIError extends Error {
-    readonly statusCode?: number;
-    readonly requestId?: string;
-    readonly responseData: Record<string, unknown>;
-    constructor(message: string, statusCode?: number, requestId?: string, responseData?: Record<string, unknown>);
-    isRetryable(): boolean;
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro de autenticacao (401). API Key invalida ou ausente.
- */
-declare class AuthenticationError extends IPTUAPIError {
-    constructor(message?: string, requestId?: string);
-}
-/**
- * Erro de autorizacao (403). Plano nao permite acesso ao recurso.
- */
-declare class ForbiddenError extends IPTUAPIError {
-    readonly requiredPlan?: string;
-    constructor(message?: string, requiredPlan?: string, requestId?: string);
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro de recurso nao encontrado (404).
- */
-declare class NotFoundError extends IPTUAPIError {
-    readonly resource?: string;
-    constructor(message?: string, resource?: string, requestId?: string);
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro de rate limit excedido (429).
- */
-declare class RateLimitError extends IPTUAPIError {
-    readonly retryAfter: number;
-    constructor(message?: string, retryAfter?: number, requestId?: string);
-    isRetryable(): boolean;
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro de validacao de parametros (400, 422).
- */
-declare class ValidationError extends IPTUAPIError {
-    readonly errors: Record<string, string[]>;
-    constructor(message?: string, errors?: Record<string, string[]>, statusCode?: number, requestId?: string);
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro interno do servidor (5xx). Retryable.
- */
-declare class ServerError extends IPTUAPIError {
-    constructor(message?: string, statusCode?: number, requestId?: string);
-    isRetryable(): boolean;
-}
-/**
- * Erro de timeout na requisicao.
- */
-declare class TimeoutError extends IPTUAPIError {
-    readonly timeoutSeconds?: number;
-    constructor(message?: string, timeoutSeconds?: number, requestId?: string);
-    isRetryable(): boolean;
-    toJSON(): ErrorDetails;
-}
-/**
- * Erro de conexao de rede.
- */
-declare class NetworkError extends IPTUAPIError {
-    readonly originalError?: Error;
-    constructor(message?: string, originalError?: Error);
-    isRetryable(): boolean;
+    iptuToolsProximoVencimento(cidade?: Cidade, parcela?: number, requestOptions?: RequestOptions): Promise<{
+        cidade: string;
+        data_vencimento: string;
+        dias_restantes: number;
+        status: "em_dia" | "proximo" | "vence_hoje" | "vencido";
+        mensagem: string;
+        multa_estimada?: number;
+        juros_estimados?: number;
+    }>;
 }
 
-export { type AVMEstimate, AuthenticationError, type Cidade, type ClientConfig, type ClientOptions, type ComparablesParams, type Comparavel, type EvaluateParams, type FinalValuation, ForbiddenError, IPTUAPIError, IPTUClient, type ITBIAliquota, type ITBICalculo, type ITBICalculoParams, type ITBIGuia, type ITBIGuiaParams, type ITBIHistorico, type ITBIIsencao, type ITBIMarketEstimate, type ITBISimulacao, type ITBISimularParams, type ITBIStatus, type ITBIValidacao, type Imovel, NetworkError, NotFoundError, type Pessoa, type PropertyEvaluation, RateLimitError, type RateLimitInfo, type RetryConfig, ServerError, TimeoutError, ValidationError, type Valuation, type ValuationParams, type Zoneamento };
+export { AuthenticationError, type BatchValuationResult, type Cidade, CidadeEnum, type ComparavelItem, type ConsultaEnderecoParams, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, type HistoricoItem, IPTUAPIError, IPTUClient, type IPTUClientOptions, type Logger, NetworkError, NotFoundError, RateLimitError, type RateLimitInfo, type RequestOptions, type RetryConfig, ServerError, TimeoutError, ValidationError, type ValuationParams, type ValuationResult, type ZoneamentoResult, IPTUClient as default };