brasilapi 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d4feae01c7e83e53c8f30fe32b71bb335e64d17a05874b0e465abc695ba518a
-  data.tar.gz: 8d36f60325e36d611da49f21a513fbe6e8551fea5f44446e7b9106c6d16ae221
+  metadata.gz: 67529435e017f1d14417130add2c21a99acc47126d6a0a15d8e7b308d3ede0e8
+  data.tar.gz: 3c83bc926f7873c8d973bb0433386b5ae937bca70b1ef5861322eab3e158a71b
 SHA512:
-  metadata.gz: df32ff8fb00d74216638a81b683e1ca95abd42be4f0404deff5ada20ec1b52d411711a854aed8c4650e93b76d81ac587dab67db54c08abfa36907fbf9c987de8
-  data.tar.gz: 005a4a9b91af86ad408f2f8fb5293d5285b2a974b4720d9b884c2e657f84286add533d0ed6a2d3cea75105c3ed4583ea89738fa44396b4e94430c421ba011b39
+  metadata.gz: 396e12a440bd9dfefd950016396c254c2816343a56ca5db4d34f8f433c8a99cae790f4620072270676cd128d774a36fd2adb7f76f6ccf851b92775a19d7b76b4
+  data.tar.gz: 721fe3a6d163b204cf5e065bd49c43116dc834ac8daa50a0e70909a038619f33cdfdf8770cfc1ae231f5c3ac3b7f4310a8bea3628b5099051b36e1080e12ccf2

data/.rubocop.yml

@@ -1,8 +1,10 @@
-require: rubocop-rspec
+plugins:
+  - rubocop-rspec
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.3
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: true

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-20
+
+- `BrasilAPI::NotFound` passa a herdar de `BrasilAPI::Error`, então `rescue BrasilAPI::Error` também captura 404
+- Erros HTTP preservam status, corpo e os campos `message`/`type` da BrasilAPI; qualquer resposta 2xx é sucesso
+- Novas subclasses `BadRequest` (400), `ServerError` (5xx) e `Timeout`, todas filhas de `BrasilAPI::Error`
+- Timeout padrão de 10 segundos, configurável com `BrasilAPI.configure { |config| config.timeout = 30 }`
+- Segmentos de URL são escapados com `URI.encode_uri_component`, sem `URI::Parser#escape` (obsoleto no Ruby 3.4+)
+- FIPE deixa de enviar `tabela_referencia` vazio quando o parâmetro é nil
+- CI dispara em push na `main` e em pull requests, nas Rubies suportadas 3.3, 3.4 e 4.0
+- Ruby mínima sobe de 2.6 para 3.3, porque 2.6–3.2 estão fora de manutenção
+- Publicação automática no RubyGems via Trusted Publishing (OIDC), sem API key
+- Testes da API do CPTEC
+- Metadado `github_repo` no gemspec
+- Correção do texto "Dado aisso" na descrição do gemspec
+
 ## [0.7.0] - 2025-04-21
 
 - Integração da API do CPTEC

data/Gemfile

@@ -7,8 +7,8 @@ gemspec
 group :development do
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.0"
-  gem "rubocop", "~> 1.21"
-  gem "rubocop-rspec", "~> 2.24"
+  gem "rubocop", "~> 1.86"
+  gem "rubocop-rspec", "~> 3.0"
   gem "vcr", "~> 6.3"
   gem "webmock", "~> 3.25"
 end

data/Gemfile.lock

@@ -1,88 +1,87 @@
 PATH
   remote: .
   specs:
-    brasilapi (0.7.0)
+    brasilapi (0.8.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    ast (2.4.2)
-    base64 (0.1.1)
-    bigdecimal (3.1.9)
-    crack (1.0.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.1.3)
+    crack (1.0.1)
       bigdecimal
       rexml
-    diff-lcs (1.5.0)
-    hashdiff (1.1.2)
-    json (2.6.3)
-    language_server-protocol (3.17.0.3)
-    parallel (1.23.0)
-    parser (3.2.2.4)
+    diff-lcs (1.6.2)
+    hashdiff (1.2.1)
+    json (3.1.0)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    parallel (2.3.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    public_suffix (6.0.1)
-    racc (1.7.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.8.2)
-    rexml (3.4.1)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.3)
+    rake (13.4.2)
+    regexp_parser (2.13.1)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.6)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.1)
-    rubocop (1.57.1)
-      base64 (~> 0.1.1)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
-      parser (>= 3.2.2.4)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.92.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.1, < 2.0)
+      regexp_parser (>= 2.11.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.29.0)
-      parser (>= 3.2.1.0)
-    rubocop-capybara (2.19.0)
-      rubocop (~> 1.41)
-    rubocop-factory_bot (2.24.0)
-      rubocop (~> 1.33)
-    rubocop-rspec (2.24.1)
-      rubocop (~> 1.33)
-      rubocop-capybara (~> 2.17)
-      rubocop-factory_bot (~> 2.22)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
-    unicode-display_width (2.5.0)
-    vcr (6.3.1)
-      base64
-    webmock (3.25.1)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    vcr (6.4.0)
+    webmock (3.34.0)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  ruby
   x86_64-linux
 
 DEPENDENCIES
   brasilapi!
   rake (~> 13.0)
   rspec (~> 3.0)
-  rubocop (~> 1.21)
-  rubocop-rspec (~> 2.24)
+  rubocop (~> 1.86)
+  rubocop-rspec (~> 3.0)
   vcr (~> 6.3)
   webmock (~> 3.25)
 
 BUNDLED WITH
-   2.4.10
+  4.0.23

data/README.md

@@ -138,6 +138,30 @@ BrasilAPI::IBGE.cities_by_state('CE')
 ```
 
 
+## Configuration
+
+Requests time out after 10 seconds (`open_timeout` and `read_timeout`). Override the default when a provider is slow:
+
+```ruby
+BrasilAPI.configure do |config|
+  config.timeout = 30
+end
+```
+
+`Net::OpenTimeout` and `Net::ReadTimeout` are raised as `BrasilAPI::Timeout`. HTTP failures are `BrasilAPI::Error` (or a subclass such as `NotFound`, `BadRequest` and `ServerError`) and expose `status`, `message`, `type` and `body`.
+
+## Release
+
+Publishing to RubyGems happens when a pull request that bumps the version is merged into `main`:
+
+1. Bump `BrasilAPI::VERSION` in `lib/brasil_api/version.rb`.
+2. Move the `[Unreleased]` section of `CHANGELOG.md` into that version, with the date.
+3. Open a pull request and merge it into `main`.
+
+`.github/workflows/release.yml` runs the test suite, creates the `vX.Y.Z` tag, publishes a GitHub Release using that version's changelog notes, and pushes the gem with RubyGems Trusted Publishing (OIDC). If the version already has a `vX.Y.Z` tag, the workflow does nothing.
+
+Before the first automated publish, register a trusted publisher on rubygems.org for `dayvidemerson/brasilapi-rb` and the workflow file `release.yml`, with no GitHub environment. The gemspec keeps `rubygems_mfa_required`.
+
 # License
 [MIT](./LICENSE)
 

data/lib/brasil_api/base.rb

@@ -2,44 +2,122 @@
 
 require "json"
 require "net/http"
+require "uri"
 
 module BrasilAPI
   class Base
     BASE_URL = "https://brasilapi.com.br/api"
+
     class << self
       def get(path, params = {})
-        uri = URI("#{BASE_URL}#{path}")
-        uri.query = URI.encode_www_form(params) if params.any?
-
-        request_data(uri)
+        request_data(build_uri(path, params))
       end
 
       protected
 
       def request_data(uri)
-        response = Net::HTTP.get_response(uri)
+        response = perform_request(uri)
+        return parsed_body(response) if response.is_a?(Net::HTTPSuccess)
 
-        case status_for(response)
-        when 200
-          parsed_body(response)
-        when 404
-          raise BrasilAPI::NotFound
-        else
-          raise BrasilAPI::Error
-        end
+        raise_api_error(response)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise BrasilAPI::Timeout, e.message
+      end
+
+      private
+
+      def build_uri(path, params)
+        uri = URI.parse("#{BASE_URL}#{encode_path(path)}")
+        query = params.compact
+        uri.query = URI.encode_www_form(query) unless query.empty?
+        uri
+      end
+
+      def encode_path(path)
+        path.split("/", -1).map { |segment| encode_segment(segment) }.join("/")
       end
 
-      def status_for(response)
-        status = {
-          Net::HTTPOK => 200,
-          Net::HTTPNotFound => 404
-        }
+      # Encode each segment on its own so "?", "#" and spaces stay inside the path.
+      # encode_uri_component keeps spaces as %20, matching the recorded cassettes.
+      def encode_segment(segment)
+        URI.encode_uri_component(segment)
+      end
 
-        status[response.class]
+      def perform_request(uri)
+        Net::HTTP.start(
+          uri.hostname,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: BrasilAPI.config.timeout,
+          read_timeout: BrasilAPI.config.timeout
+        ) do |http|
+          http.request(Net::HTTP::Get.new(uri))
+        end
       end
 
       def parsed_body(response)
-        JSON.parse(response.body) if response.body
+        body = utf8_body(response)
+        return if body.nil? || body.empty?
+
+        JSON.parse(body)
+      end
+
+      def raise_api_error(response)
+        parsed = parse_error_body(response)
+        raise error_class_for(response).new(
+          error_message(parsed, response),
+          status: response.code.to_i,
+          body: error_body(parsed, response),
+          type: error_type(parsed)
+        )
+      end
+
+      def parse_error_body(response)
+        body = utf8_body(response)
+        return if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def utf8_body(response)
+        body = response.body
+        return if body.nil?
+
+        body.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      def error_message(parsed, response)
+        return parsed["message"] if parsed.is_a?(Hash) && parsed["message"]
+
+        body = utf8_body(response)
+        return body if body && !body.empty?
+
+        "HTTP #{response.code}"
+      end
+
+      def error_body(parsed, response)
+        return parsed unless parsed.nil?
+
+        utf8_body(response)
+      end
+
+      def error_type(parsed)
+        parsed["type"] if parsed.is_a?(Hash)
+      end
+
+      def error_class_for(response)
+        case response.code.to_i
+        when 400
+          BrasilAPI::BadRequest
+        when 404
+          BrasilAPI::NotFound
+        when 500..599
+          BrasilAPI::ServerError
+        else
+          BrasilAPI::Error
+        end
       end
     end
   end

data/lib/brasil_api/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BrasilAPI
+  class Configuration
+    DEFAULT_TIMEOUT = 10
+
+    attr_accessor :timeout
+
+    def initialize
+      @timeout = DEFAULT_TIMEOUT
+    end
+  end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/brasil_api/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BrasilAPI
+  class Error < StandardError
+    attr_reader :status, :body, :type
+
+    def initialize(message = nil, status: nil, body: nil, type: nil)
+      @status = status
+      @body = body
+      @type = type
+      super(message)
+    end
+  end
+
+  class NotFound < Error; end
+
+  class BadRequest < Error; end
+
+  class ServerError < Error; end
+
+  class Timeout < Error; end
+end

data/lib/brasil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrasilAPI
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/brasil_api.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "brasil_api/version"
+require_relative "brasil_api/configuration"
+require_relative "brasil_api/error"
 require_relative "brasil_api/base"
 require_relative "brasil_api/address"
 require_relative "brasil_api/bank"
@@ -15,8 +17,3 @@ require_relative "brasil_api/ncm"
 require_relative "brasil_api/pix"
 require_relative "brasil_api/registrobr"
 require_relative "brasil_api/taxas"
-
-module BrasilAPI
-  class Error < StandardError; end
-  class NotFound < StandardError; end
-end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: brasilapi
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Dayvid Emerson
 bindir: exe
 cert_chain: []
-date: 2025-04-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Acesso programático de informações é algo fundamental na comunicação
   entre sistemas, mas, para nossa surpresa, uma informação tão útil e pública quanto
   um CEP não consegue ser acessada diretamente por um navegador por conta da API dos
-  Correios não possuir CORS habilitado. Dado aisso, este projeto experimental tem
-  como objetivo centralizar e disponibilizar endpoints modernos com baixíssima latência
+  Correios não possuir CORS habilitado. Dado isso, este projeto experimental tem como
+  objetivo centralizar e disponibilizar endpoints modernos com baixíssima latência
   utilizando tecnologias como Vercel Smart CDN responsável por fazer o cache das informações
   em atualmente 23 regiões distribuídas ao longo do mundo (incluindo Brasil). Então
   não importa o quão devagar for a fonte dos dados, nós queremos disponibilizá-la
@@ -33,14 +33,15 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- brasilapi.gemspec
 - lib/brasil_api.rb
 - lib/brasil_api/address.rb
 - lib/brasil_api/bank.rb
 - lib/brasil_api/base.rb
 - lib/brasil_api/company.rb
+- lib/brasil_api/configuration.rb
 - lib/brasil_api/cptec.rb
 - lib/brasil_api/cvm.rb
+- lib/brasil_api/error.rb
 - lib/brasil_api/fipe.rb
 - lib/brasil_api/holiday.rb
 - lib/brasil_api/ibge.rb
@@ -59,6 +60,7 @@ metadata:
   source_code_uri: https://github.com/dayvidemerson/brasilapi-rb
   changelog_uri: https://github.com/dayvidemerson/brasilapi-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+  github_repo: ssh://github.com/dayvidemerson/brasilapi-rb
 rdoc_options: []
 require_paths:
 - lib
@@ -66,14 +68,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Cliente desenvolvido em Ruby para o consumo da Brasil API que permite buscar
   informações públicas referentes ao Brasil de modo eficiente e simplificado.

data/brasilapi.gemspec

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/brasil_api/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "brasilapi"
-  spec.version = BrasilAPI::VERSION
-  spec.authors = ["Dayvid Emerson"]
-  spec.email = ["dayvidemerson96@gmail.com"]
-
-  spec.summary = "Cliente desenvolvido em Ruby para o consumo da Brasil API que permite buscar informações públicas " \
-                 "referentes ao Brasil de modo eficiente e simplificado."
-
-  spec.description = "Acesso programático de informações é algo fundamental na comunicação entre sistemas, mas, para " \
-                     "nossa surpresa, uma informação tão útil e pública quanto um CEP não consegue ser acessada " \
-                     "diretamente por um navegador por conta da API dos Correios não possuir CORS habilitado. Dado a" \
-                     "isso, este projeto experimental tem como objetivo centralizar e disponibilizar endpoints " \
-                     "modernos com baixíssima latência utilizando tecnologias como Vercel Smart CDN responsável por " \
-                     "fazer o cache das informações em atualmente 23 regiões distribuídas ao longo do mundo " \
-                     "(incluindo Brasil). Então não importa o quão devagar for a fonte dos dados, nós queremos " \
-                     "disponibilizá-la da forma mais rápida e moderna possível."
-
-  spec.homepage = "https://brasilapi.com.br"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/dayvidemerson/brasilapi-rb"
-  spec.metadata["changelog_uri"] = "https://github.com/dayvidemerson/brasilapi-rb/blob/main/CHANGELOG.md"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-end