iptuapi 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * 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
@@ -9,59 +10,98 @@
  *
  * 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,
+ * });
  * ```
  */
-/** Cidades suportadas pela API */
-type Cidade = 'sao_paulo' | 'belo_horizonte' | 'recife';
-interface ConsultaEnderecoResult {
-    sql: string;
+type Cidade = 'sp' | 'bh' | 'recife';
+declare const CidadeEnum: {
+    readonly SAO_PAULO: Cidade;
+    readonly BELO_HORIZONTE: Cidade;
+    readonly RECIFE: Cidade;
+};
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+    resetDate: Date;
+}
+interface ConsultaEnderecoParams {
     logradouro: string;
-    numero: string;
-    bairro: string;
-    cep: string;
-    area_terreno: number;
-    area_construida: number;
-    tipo_uso: string;
-    zona: string;
+    numero?: string;
+    complemento?: string;
+    cidade?: Cidade;
+    incluirHistorico?: boolean;
+    incluirComparaveis?: boolean;
+    incluirZoneamento?: boolean;
 }
-/** Resultado da consulta multi-cidade */
-interface ConsultaIPTUResult {
+interface ConsultaEnderecoResult {
     sql: string;
-    ano: number;
     logradouro: string;
-    numero: number | string | null;
-    complemento: string | null;
-    bairro: string | null;
-    cep: string;
-    area_terreno: number | null;
-    area_construida: number | null;
-    valor_terreno: number | null;
-    valor_construcao: number | null;
-    valor_venal: number;
-    valor_imovel?: number | null;
-    valor_iptu?: number | null;
-    finalidade: string | null;
-    tipo_construcao: string | null;
-    ano_construcao: number | null;
-    pavimentos?: number | null;
-    fracao_ideal?: string | null;
-    latitude?: number | null;
-    longitude?: number | null;
-    cidade: string;
-    fonte: string;
+    numero?: string;
+    complemento?: string;
+    bairro?: string;
+    cep?: 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;
+    historico?: HistoricoItem[];
+    comparaveis?: ComparavelItem[];
+    zoneamento?: ZoneamentoResult;
 }
 interface ConsultaSQLResult {
     sql: 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 HistoricoItem {
     ano: number;
-    valor_venal: number;
-    valor_venal_terreno: number;
-    valor_venal_construcao: number;
-    iptu_valor: number;
-    logradouro: string;
-    numero: string;
-    bairro: string;
-    area_terreno: number;
-    area_construida: number;
+    valor_venal_terreno?: number;
+    valor_venal_construcao?: number;
+    valor_venal_total?: number;
+    iptu_valor?: number;
+}
+interface ComparavelItem {
+    sql?: string;
+    logradouro?: string;
+    numero?: string;
+    bairro?: string;
+    area_terreno?: number;
+    area_construida?: number;
+    valor_venal_total?: number;
+    distancia_metros?: number;
+}
+interface ZoneamentoResult {
+    zona?: string;
+    zona_descricao?: string;
+    coeficiente_aproveitamento_basico?: number;
+    coeficiente_aproveitamento_maximo?: number;
+    taxa_ocupacao_maxima?: number;
+    gabarito_maximo?: number;
 }
 interface ValuationParams {
     area_terreno: number;
@@ -71,70 +111,228 @@ interface ValuationParams {
     tipo_uso: string;
     tipo_padrao: string;
     ano_construcao?: number;
+    cidade?: Cidade;
 }
 interface ValuationResult {
-    success: boolean;
     valor_estimado: number;
-    valor_minimo: number;
-    valor_maximo: number;
-    valor_m2: number;
-    confianca: number;
-    modelo_versao: string;
+    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;
+    }>;
 }
 declare class IPTUAPIError extends Error {
-    statusCode?: number | undefined;
-    constructor(message: string, statusCode?: number | undefined);
+    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;
 }
 declare class AuthenticationError extends IPTUAPIError {
-    constructor(message?: string);
+    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
-declare class RateLimitError extends IPTUAPIError {
-    constructor(message?: string);
+declare class ForbiddenError extends IPTUAPIError {
+    readonly requiredPlan?: string;
+    constructor(message?: string, requiredPlan?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
 declare class NotFoundError extends IPTUAPIError {
-    constructor(message?: string);
+    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
 }
-declare class ForbiddenError extends IPTUAPIError {
-    constructor(message?: string);
+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;
+}
+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>);
+}
+declare class ServerError extends IPTUAPIError {
+    constructor(message?: string, statusCode?: number, requestId?: string, responseBody?: Record<string, unknown>);
+    get isRetryable(): boolean;
+}
+declare class TimeoutError extends IPTUAPIError {
+    readonly timeoutMs?: number;
+    constructor(message?: string, timeoutMs?: number);
+    get isRetryable(): boolean;
+}
+declare class NetworkError extends IPTUAPIError {
+    readonly originalError?: Error;
+    constructor(message?: string, originalError?: Error);
+    get isRetryable(): boolean;
+}
+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 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 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;
 }
 declare class IPTUClient {
-    private apiKey;
-    private baseUrl;
-    private timeout;
+    private readonly apiKey;
+    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 calculateDelay;
+    private extractRateLimit;
+    private handleErrorResponse;
     private request;
     /**
-     * Busca dados de IPTU por endereço
+     * Busca dados de IPTU por endereço.
+     *
+     * @param params - Parâmetros da consulta
+     * @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
      */
-    consultaEndereco(logradouro: string, numero?: string): Promise<ConsultaEnderecoResult>;
+    consultaEndereco(params: ConsultaEnderecoParams): Promise<ConsultaEnderecoResult>;
+    consultaEndereco(logradouro: string, numero?: string, cidade?: Cidade): Promise<ConsultaEnderecoResult>;
     /**
-     * Busca dados de IPTU por número SQL (Starter+)
+     * 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
      */
-    consultaSQL(sql: string): Promise<ConsultaSQLResult>;
+    consultaSQL(sql: string, cidade?: Cidade, options?: {
+        incluirHistorico?: boolean;
+        incluirComparaveis?: boolean;
+    }): Promise<ConsultaSQLResult>;
     /**
-     * Busca dados de IPTU por endereço para qualquer cidade suportada
-     * @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
-     * @param logradouro - Nome da rua/avenida
-     * @param numero - Número do imóvel (opcional)
-     * @param ano - Ano de referência (default: 2025)
-     * @param limit - Limite de resultados (default: 20)
+     * Busca imóveis por CEP.
+     *
+     * @param cep - CEP do imóvel
+     * @param cidade - Cidade da consulta
+     * @returns Lista de imóveis no CEP
      */
-    consultaIPTU(cidade: Cidade, logradouro: string, numero?: number, ano?: number, limit?: number): Promise<ConsultaIPTUResult[]>;
+    consultaCEP(cep: string, cidade?: Cidade): Promise<ConsultaEnderecoResult[]>;
     /**
-     * Busca dados de IPTU pelo identificador único do imóvel
-     * @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
-     * @param identificador - Número SQL (SP), Índice Cadastral (BH) ou Contribuinte (Recife)
-     * @param ano - Ano de referência (opcional)
+     * Consulta zoneamento por coordenadas.
+     *
+     * @param latitude - Latitude do ponto
+     * @param longitude - Longitude do ponto
+     * @returns Dados de zoneamento
      */
-    consultaIPTUSQL(cidade: Cidade, identificador: string, ano?: number): Promise<ConsultaIPTUResult[]>;
+    consultaZoneamento(latitude: number, longitude: number): Promise<ZoneamentoResult>;
     /**
-     * Estima o valor de mercado do imóvel (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
      */
     valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
+    /**
+     * 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
+     */
+    valuationBatch(imoveis: ValuationParams[]): Promise<BatchValuationResult>;
+    /**
+     * 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
+     */
+    valuationComparables(bairro: string, areaMin: number, areaMax: number, options?: {
+        tipoUso?: string;
+        cidade?: Cidade;
+        limit?: number;
+    }): Promise<ComparavelItem[]>;
+    /**
+     * 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
+     */
+    dadosIPTUHistorico(sql: string, cidade?: Cidade): Promise<HistoricoItem[]>;
+    /**
+     * Consulta dados de empresa por CNPJ.
+     *
+     * @param cnpj - CNPJ da empresa
+     * @returns Dados cadastrais
+     */
+    dadosCNPJ(cnpj: string): Promise<Record<string, unknown>>;
+    /**
+     * 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
+     */
+    dadosIPCACorrigir(valor: number, dataOrigem: string, dataDestino?: string): Promise<{
+        valor_corrigido: number;
+        fator: number;
+    }>;
 }
 
-export { AuthenticationError, type Cidade, type ConsultaEnderecoResult, type ConsultaIPTUResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };
+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 RetryConfig, ServerError, TimeoutError, ValidationError, type ValuationParams, type ValuationResult, type ZoneamentoResult, IPTUClient as default };