iptuapi 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# IPTU API - JavaScript/TypeScript SDK
+
+SDK oficial para integração com a IPTU API.
+
+## Instalação
+
+```bash
+npm install iptuapi
+# ou
+yarn add iptuapi
+# ou
+pnpm add iptuapi
+```
+
+## Uso Rápido
+
+```typescript
+import { IPTUClient } from 'iptuapi';
+
+const client = new IPTUClient('sua_api_key');
+
+// Consulta por endereço
+const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
+console.log(resultado);
+
+// Consulta por SQL (Starter+)
+const dados = await client.consultaSQL('100-01-001-001');
+
+// Avaliação de mercado (Pro+)
+const avaliacao = await client.valuationEstimate({
+  area_terreno: 250,
+  area_construida: 180,
+  bairro: 'Pinheiros',
+  zona: 'ZM',
+  tipo_uso: 'Residencial',
+  tipo_padrao: 'Médio',
+  ano_construcao: 2010,
+});
+console.log(`Valor estimado: R$ ${avaliacao.valor_estimado.toLocaleString()}`);
+```
+
+## Tratamento de Erros
+
+```typescript
+import { IPTUClient, NotFoundError, RateLimitError } from 'iptuapi';
+
+const client = new IPTUClient('sua_api_key');
+
+try {
+  const resultado = await client.consultaEndereco('Rua Inexistente');
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Imóvel não encontrado');
+  } else if (error instanceof RateLimitError) {
+    console.log('Limite de requisições excedido');
+  }
+}
+```
+
+## Tipos TypeScript
+
+O SDK inclui tipos TypeScript completos:
+
+```typescript
+import type {
+  ConsultaEnderecoResult,
+  ConsultaSQLResult,
+  ValuationParams,
+  ValuationResult,
+} from 'iptuapi';
+```
+
+## Documentação
+
+Acesse a documentação completa em [iptuapi.com.br/docs](https://iptuapi.com.br/docs)

package/dist/index.d.mts

@@ -0,0 +1,96 @@
+/**
+ * IPTU API - JavaScript/TypeScript SDK
+ *
+ * SDK oficial para integração com a IPTU API.
+ *
+ * @example
+ * ```typescript
+ * import { IPTUClient } from 'iptuapi';
+ *
+ * const client = new IPTUClient('sua_api_key');
+ * const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
+ * ```
+ */
+interface ConsultaEnderecoResult {
+    sql: string;
+    logradouro: string;
+    numero: string;
+    bairro: string;
+    cep: string;
+    area_terreno: number;
+    area_construida: number;
+    tipo_uso: string;
+    zona: string;
+}
+interface ConsultaSQLResult {
+    sql: string;
+    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;
+}
+interface ValuationParams {
+    area_terreno: number;
+    area_construida: number;
+    bairro: string;
+    zona: string;
+    tipo_uso: string;
+    tipo_padrao: string;
+    ano_construcao?: number;
+}
+interface ValuationResult {
+    success: boolean;
+    valor_estimado: number;
+    valor_minimo: number;
+    valor_maximo: number;
+    valor_m2: number;
+    confianca: number;
+    modelo_versao: string;
+}
+declare class IPTUAPIError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+declare class AuthenticationError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends IPTUAPIError {
+    constructor(message?: string);
+}
+interface IPTUClientOptions {
+    baseUrl?: string;
+    timeout?: number;
+}
+declare class IPTUClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(apiKey: string, options?: IPTUClientOptions);
+    private request;
+    /**
+     * Busca dados de IPTU por endereço
+     */
+    consultaEndereco(logradouro: string, numero?: string): Promise<ConsultaEnderecoResult>;
+    /**
+     * Busca dados de IPTU por número SQL (Starter+)
+     */
+    consultaSQL(sql: string): Promise<ConsultaSQLResult>;
+    /**
+     * Estima o valor de mercado do imóvel (Pro+)
+     */
+    valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
+}
+
+export { AuthenticationError, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * IPTU API - JavaScript/TypeScript SDK
+ *
+ * SDK oficial para integração com a IPTU API.
+ *
+ * @example
+ * ```typescript
+ * import { IPTUClient } from 'iptuapi';
+ *
+ * const client = new IPTUClient('sua_api_key');
+ * const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
+ * ```
+ */
+interface ConsultaEnderecoResult {
+    sql: string;
+    logradouro: string;
+    numero: string;
+    bairro: string;
+    cep: string;
+    area_terreno: number;
+    area_construida: number;
+    tipo_uso: string;
+    zona: string;
+}
+interface ConsultaSQLResult {
+    sql: string;
+    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;
+}
+interface ValuationParams {
+    area_terreno: number;
+    area_construida: number;
+    bairro: string;
+    zona: string;
+    tipo_uso: string;
+    tipo_padrao: string;
+    ano_construcao?: number;
+}
+interface ValuationResult {
+    success: boolean;
+    valor_estimado: number;
+    valor_minimo: number;
+    valor_maximo: number;
+    valor_m2: number;
+    confianca: number;
+    modelo_versao: string;
+}
+declare class IPTUAPIError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+declare class AuthenticationError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends IPTUAPIError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends IPTUAPIError {
+    constructor(message?: string);
+}
+interface IPTUClientOptions {
+    baseUrl?: string;
+    timeout?: number;
+}
+declare class IPTUClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(apiKey: string, options?: IPTUClientOptions);
+    private request;
+    /**
+     * Busca dados de IPTU por endereço
+     */
+    consultaEndereco(logradouro: string, numero?: string): Promise<ConsultaEnderecoResult>;
+    /**
+     * Busca dados de IPTU por número SQL (Starter+)
+     */
+    consultaSQL(sql: string): Promise<ConsultaSQLResult>;
+    /**
+     * Estima o valor de mercado do imóvel (Pro+)
+     */
+    valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
+}
+
+export { AuthenticationError, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };

package/dist/index.js

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  ForbiddenError: () => ForbiddenError,
+  IPTUAPIError: () => IPTUAPIError,
+  IPTUClient: () => IPTUClient,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var IPTUAPIError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "IPTUAPIError";
+  }
+};
+var AuthenticationError = class extends IPTUAPIError {
+  constructor(message = "API Key inv\xE1lida ou expirada") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends IPTUAPIError {
+  constructor(message = "Limite de requisi\xE7\xF5es excedido") {
+    super(message, 429);
+    this.name = "RateLimitError";
+  }
+};
+var NotFoundError = class extends IPTUAPIError {
+  constructor(message = "Recurso n\xE3o encontrado") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ForbiddenError = class extends IPTUAPIError {
+  constructor(message = "Plano n\xE3o autorizado para este recurso") {
+    super(message, 403);
+    this.name = "ForbiddenError";
+  }
+};
+var IPTUClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || "https://iptuapi.com.br/api/v1";
+    this.timeout = options.timeout || 3e4;
+  }
+  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);
+      });
+    }
+    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
+          );
+      }
+    } 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;
+    }
+  }
+  /**
+   * Busca dados de IPTU por endereço
+   */
+  async consultaEndereco(logradouro, numero) {
+    return this.request("GET", "/consulta/endereco", {
+      logradouro,
+      numero: numero || ""
+    });
+  }
+  /**
+   * Busca dados de IPTU por número SQL (Starter+)
+   */
+  async consultaSQL(sql) {
+    return this.request("GET", "/consulta/sql", { sql });
+  }
+  /**
+   * Estima o valor de mercado do imóvel (Pro+)
+   */
+  async valuationEstimate(params) {
+    return this.request(
+      "POST",
+      "/valuation/estimate",
+      void 0,
+      params
+    );
+  }
+};
+var index_default = IPTUClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  ForbiddenError,
+  IPTUAPIError,
+  IPTUClient,
+  NotFoundError,
+  RateLimitError
+});

package/dist/index.mjs

@@ -0,0 +1,126 @@
+// src/index.ts
+var IPTUAPIError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "IPTUAPIError";
+  }
+};
+var AuthenticationError = class extends IPTUAPIError {
+  constructor(message = "API Key inv\xE1lida ou expirada") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends IPTUAPIError {
+  constructor(message = "Limite de requisi\xE7\xF5es excedido") {
+    super(message, 429);
+    this.name = "RateLimitError";
+  }
+};
+var NotFoundError = class extends IPTUAPIError {
+  constructor(message = "Recurso n\xE3o encontrado") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ForbiddenError = class extends IPTUAPIError {
+  constructor(message = "Plano n\xE3o autorizado para este recurso") {
+    super(message, 403);
+    this.name = "ForbiddenError";
+  }
+};
+var IPTUClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || "https://iptuapi.com.br/api/v1";
+    this.timeout = options.timeout || 3e4;
+  }
+  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);
+      });
+    }
+    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
+          );
+      }
+    } 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;
+    }
+  }
+  /**
+   * Busca dados de IPTU por endereço
+   */
+  async consultaEndereco(logradouro, numero) {
+    return this.request("GET", "/consulta/endereco", {
+      logradouro,
+      numero: numero || ""
+    });
+  }
+  /**
+   * Busca dados de IPTU por número SQL (Starter+)
+   */
+  async consultaSQL(sql) {
+    return this.request("GET", "/consulta/sql", { sql });
+  }
+  /**
+   * Estima o valor de mercado do imóvel (Pro+)
+   */
+  async valuationEstimate(params) {
+    return this.request(
+      "POST",
+      "/valuation/estimate",
+      void 0,
+      params
+    );
+  }
+};
+var index_default = IPTUClient;
+export {
+  AuthenticationError,
+  ForbiddenError,
+  IPTUAPIError,
+  IPTUClient,
+  NotFoundError,
+  RateLimitError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "iptuapi",
+  "version": "1.0.0",
+  "description": "SDK oficial para a IPTU API - Dados de IPTU de São Paulo",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "iptu",
+    "api",
+    "são paulo",
+    "imóveis",
+    "dados",
+    "typescript"
+  ],
+  "author": "IPTU API <contato@iptuapi.com.br>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iptuapi/iptuapi-js"
+  },
+  "homepage": "https://iptuapi.com.br",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}