congrega_plenum 0.1.0

data/lib/client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # HTTP client responsible for talking to the Câmara API endpoints and dealing
+  # with retries, pagination and response parsing.
+  #
+  # All methods are thread-safe because the heavy collaborators ({HttpAdapter},
+  # {RetryPolicy} and {ResponseHandler}) are stateless.
+  class Client
+    include Singleton
+
+    attr_reader :http_adapter, :retry_policy, :response_handler
+
+    def initialize
+      configuration = CongregaPlenum.configuration
+      @http_adapter = HttpAdapter.new(configuration: configuration)
+      @retry_policy = RetryPolicy.new(configuration: configuration)
+      @response_handler = ResponseHandler.new
+    end
+
+    # Performs a single HTTP GET to the given +endpoint+ and returns the parsed
+    # JSON body.
+    #
+    # @param endpoint [String] the relative path (e.g. +deputados+)
+    # @param params [Hash] query parameters merged into the request
+    # @return [Hash] parsed response body
+    def get(endpoint, params = {})
+      url = build_url(endpoint, params)
+
+      retry_policy.with_retries(url) { execute_request(url) }
+    end
+
+    # Retrieves all pages for an endpoint, flattening the +dados+ payloads into a
+    # single array. Automatically respects the configured rate limit delay.
+    #
+    # @param endpoint [String]
+    # @param params [Hash]
+    # @return [Array<Hash>]
+    def get_paginated(endpoint, params = {})
+      # @type var results: Array[Hash[String, untyped]]
+      results = []
+      each_response_page(endpoint, params) { |page_data| results.concat(page_data) }
+
+      results
+    end
+
+    private
+
+    def each_response_page(endpoint, params)
+      page = 1
+
+      loop do
+        response = request_page(endpoint, params, page)
+        data = response.fetch('dados', [])
+        break if data.empty?
+
+        yield(data)
+        break unless next_page?(response)
+
+        page += 1
+        apply_rate_limit_delay
+      end
+    end
+
+    # Fetches a single page enforcing +formato=json+ and the requested page index.
+    def request_page(endpoint, params, page)
+      get(endpoint, params.merge(pagina: page, formato: 'json'))
+    end
+
+    def next_page?(response)
+      response.fetch('links', []).any? { |link| link['rel'] == 'next' }
+    end
+
+    # Sleep between page fetches to respect the rate limit exposed by the API.
+    # This is configurable because not every consumer has the same tolerance.
+    def apply_rate_limit_delay
+      delay = configuration.rate_limit_delay
+
+      sleep(delay) if delay.positive?
+    end
+
+    def execute_request(url)
+      response = http_adapter.get(url)
+
+      response_handler.handle(response, url)
+    end
+
+    # Builds the full URL pointing to the Câmara API, ensuring +formato=json+ is present.
+    #
+    # @param endpoint [String]
+    # @param params [Hash]
+    # @return [String]
+    def build_url(endpoint, params = {})
+      uri = URI("#{configuration.base_url}/#{endpoint.gsub(%r{^/}, '')}")
+
+      # Ensure formato=json is always present
+      normalized_params = params.transform_keys(&:to_sym)
+      normalized_params[:formato] ||= 'json'
+
+      uri.query = URI.encode_www_form(normalized_params)
+
+      uri.to_s
+    end
+
+    def configuration
+      CongregaPlenum.configuration
+    end
+  end
+end

data/lib/congrega_plenum.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'singleton'
+require 'logger'
+
+# CongregaPlenum centralizes access to the Brazilian Chamber of Deputies public API.
+# It exposes a global configuration and service objects for each resource.
+module CongregaPlenum
+  # Base error class for all domain-specific exceptions in the gem.
+  class Error < StandardError; end
+  # Raised when connectivity fails before receiving a valid HTTP response.
+  class ConnectionError < Error; end
+  # Raised when the API responds with an unexpected status code or payload.
+  class APIError < Error; end
+  # Raised for transient 5xx responses that are safe to retry.
+  class ServerError < APIError; end
+  # Raised when the API signals that the rate limit has been exceeded.
+  class RateLimitError < Error; end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Yields the current {Configuration} so callers can override defaults.
+  #
+  # @yieldparam config [Configuration] the mutable configuration object
+  def self.configure
+    self.configuration ||= Configuration.new
+
+    yield(configuration)
+  end
+
+  # Shared configuration used by the client and services to tweak base URL,
+  # timeouts and retry policies. Defaults focus on the public APIs hosted by the
+  # Câmara so a regular application can simply call {CongregaPlenum.configure} and
+  # override what differs (timeouts, logger, etc.).
+  class Configuration
+    # @return [String] Base endpoint for all requests.
+    attr_accessor :base_url
+    # @return [Integer] Timeout (seconds) applied to open/read operations.
+    attr_accessor :timeout
+    # @return [Integer] How many times requests are retried on transient errors.
+    attr_accessor :retries
+    # @return [Float] Initial backoff delay in seconds.
+    attr_accessor :retry_delay
+    # @return [Float] Delay between paginated calls to respect rate limits.
+    attr_accessor :rate_limit_delay
+    # @return [Logger] Logger used across adapters/services.
+    attr_accessor :logger
+
+    # Builds a configuration instance with safe defaults tuned for the Câmara APIs.
+    # Those endpoints are known to be HTTPS-only, relatively slow, and rate-limited,
+    # so the defaults try to smooth that out.
+    def initialize
+      @base_url = 'https://dadosabertos.camara.leg.br/api/v2'
+      @timeout = 30
+      @retries = 3
+      @retry_delay = 1.0
+      @rate_limit_delay = 0.1
+      @logger = Logger.new($stdout)
+    end
+  end
+
+  # Initialize with default configuration
+  configure do |_config|
+    # Defaults are already set in Configuration#initialize
+  end
+end
+
+# Load all sub-modules
+require_relative 'adapters/http_adapter'
+require_relative 'adapters/retry_policy'
+require_relative 'adapters/response_handler'
+require_relative 'client'
+require_relative 'modules/congressmen_service'
+require_relative 'modules/parties_service'
+require_relative 'modules/legislatures_service'
+require_relative 'modules/votings_service'

data/lib/modules/congressmen_service.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # Service responsible for interacting with congressmen endpoints, wrapping both
+  # list and detail requests into high level helpers.
+  class CongressmenService
+    # Default page size for list endpoints.
+    ITEMS_PER_PAGE = 100
+    # Interval used to emit progress logs while iterating.
+    PROGRESS_INTERVAL = 50
+    # Tag prefix for structured logging.
+    SERVICE_TAG = 'CongregaPlenum::CongressmenService'
+
+    class << self
+      # Shared client instance configured via {CongregaPlenum.configure}.
+      #
+      # @return [CongregaPlenum::Client]
+      def client
+        @client ||= CongregaPlenum::Client.instance
+      end
+
+      # Wraps {Client#get} to add service context without hiding request failures.
+      def api_get(endpoint, params = {})
+        client.get(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro ao acessar API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Same as {.api_get}, but for bulk pagination calls. Failures are propagated
+      # so consumers can abort an incomplete synchronization.
+      def api_get_paginated(endpoint, params = {})
+        client.get_paginated(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro paginando API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Fetches the entire list of congressmen regardless of legislature.
+      #
+      # @return [Array<Hash>]
+      def fetch_all
+        fetch_deputies_collection(context: 'todos os deputados', params: { itens: ITEMS_PER_PAGE })
+      end
+
+      # Fetches all congressmen for a given legislature, enriching each entry with
+      # its detailed payload.
+      #
+      # @param legislature_id [Integer]
+      # @return [Array<Hash>]
+      def fetch_all_by_legislature(legislature_id)
+        fetch_deputies_collection(
+          context: "legislatura #{legislature_id}",
+          params: { itens: ITEMS_PER_PAGE, idLegislatura: legislature_id }
+        )
+      end
+
+      # Retrieves the detailed payload of a single congressman.
+      #
+      # @param deputy_id [Integer]
+      # @return [Hash, nil]
+      # @raise [CongregaPlenum::APIError] if +dados+ has an unexpected type
+      def fetch_by_id(deputy_id)
+        log_debug("Buscando deputado #{deputy_id}")
+
+        response = api_get("deputados/#{deputy_id}")
+        extract_detail(response, "deputado #{deputy_id}")
+      end
+
+      # Returns a paginated list of congressmen straight from the API, without
+      # making detail calls.
+      #
+      # @param page [Integer]
+      # @param items_per_page [Integer]
+      # @param legislature_id [Integer,nil]
+      # @return [Array<Hash>]
+      def fetch_list(page: 1, items_per_page: ITEMS_PER_PAGE, legislature_id: nil)
+        log_debug("Buscando lista de deputados página #{page}")
+
+        params = { pagina: page, itens: items_per_page }
+        params[:idLegislatura] = legislature_id if legislature_id
+
+        response = api_get('deputados', params)
+        response['dados'] || []
+      end
+
+      private
+
+      def extract_detail(response, resource)
+        detail = response['dados']
+        return detail if detail.nil? || detail.is_a?(Hash)
+
+        raise APIError, "Resposta inválida para #{resource}: esperado Hash ou nil em dados"
+      end
+
+      # Coordinates pagination and detail fetches so the long running process can
+      # log progress and reuse error handling in one place.
+      def fetch_deputies_collection(context:, params:)
+        log_info("Iniciando coleta de #{context}")
+
+        deputies = api_get_paginated('deputados', params)
+
+        log_info("Coletamos #{deputies.length} registros de #{context}")
+
+        detailed_deputies = build_detailed_deputies(deputies, context)
+
+        log_info("Finalizamos a coleta detalhada de #{detailed_deputies.length} registros para #{context}")
+        detailed_deputies
+      end
+
+      # Walks the basic list and replaces each entry with its detailed payload.
+      # Having this call separated from {#fetch_deputies_collection} keeps the
+      # public method compact and enables targeted testing of the detail logic.
+      def build_detailed_deputies(deputies, context)
+        deputies.each_with_index.with_object([]) do |(deputy, index), collected|
+          detailed_deputy = fetch_by_id(deputy['id'])
+          collected << detailed_deputy if detailed_deputy
+          log_progress(index, deputies.length, context)
+        end
+      end
+
+      # Emits progress logs every {PROGRESS_INTERVAL} items so long running
+      # synchronisations give users feedback without spamming the console.
+      def log_progress(index, total, context)
+        return unless ((index + 1) % PROGRESS_INTERVAL).zero?
+
+        log_info("Processamos #{index + 1}/#{total} registros para #{context}")
+      end
+
+      def logger
+        CongregaPlenum.configuration.logger
+      end
+
+      def log_info(message)
+        logger.info("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_error(message)
+        logger.error("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_debug(message)
+        logger.debug("#{SERVICE_TAG}: #{message}")
+      end
+    end
+  end
+end

data/lib/modules/legislatures_service.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # Service responsible for interacting with legislature endpoints including mesa
+  # composition and deputies per legislature.
+  class LegislaturesService
+    # Default pagination size for legislature listings.
+    PAGE_SIZE = 50
+    # Pagination size for deputies per legislature.
+    DEPUTIES_PAGE_SIZE = 100
+    # Tag prefix for structured logging.
+    SERVICE_TAG = 'CongregaPlenum::LegislaturesService'
+
+    class << self
+      # Shared client instance configured via {CongregaPlenum.configure}.
+      #
+      # @return [CongregaPlenum::Client]
+      def client
+        @client ||= CongregaPlenum::Client.instance
+      end
+
+      # Wraps {Client#get} to add service context without hiding request failures.
+      def api_get(endpoint, params = {})
+        client.get(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro ao acessar API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Bulk variant of {.api_get}. Failures are propagated so consumers can
+      # abort an incomplete synchronization.
+      def api_get_paginated(endpoint, params = {})
+        client.get_paginated(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro paginando API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Returns every legislature exposed by a API.
+      #
+      # @return [Array<Hash>]
+      def fetch_all
+        log_info('Iniciando busca de todas as legislaturas')
+
+        legislatures = api_get_paginated('legislaturas', itens: PAGE_SIZE)
+
+        log_info("Total de #{legislatures.size} legislaturas encontradas")
+        legislatures
+      end
+
+      # Fetches a single legislature payload.
+      #
+      # @param legislature_id [Integer]
+      # @return [Hash, nil]
+      # @raise [CongregaPlenum::APIError] if +dados+ has an unexpected type
+      def fetch_by_id(legislature_id)
+        log_debug("Buscando legislatura #{legislature_id}")
+
+        response = api_get("legislaturas/#{legislature_id}")
+        extract_detail(response, "legislatura #{legislature_id}")
+      end
+
+      # Retrieves the mesa composition for the provided legislature ID.
+      #
+      # @param legislature_id [Integer]
+      # @return [Array<Hash>]
+      def fetch_mesa(legislature_id)
+        response = api_get("legislaturas/#{legislature_id}/mesa")
+        mesa_data = response['dados'] || []
+
+        log_info("Mesa da legislatura #{legislature_id} coletada com #{mesa_data.size} integrantes")
+        mesa_data
+      end
+
+      # Lists every deputy that served/serves in the given legislature using the
+      # +idLegislatura+ filter supported by the deputies endpoint.
+      #
+      # @param legislature_id [Integer]
+      # @return [Array<Hash>]
+      def fetch_deputies(legislature_id)
+        log_info("Iniciando coleta de deputados da legislatura #{legislature_id}")
+
+        deputies = api_get_paginated('deputados', itens: DEPUTIES_PAGE_SIZE, idLegislatura: legislature_id)
+
+        log_info("Coletamos #{deputies.size} deputados para a legislatura #{legislature_id}")
+        deputies
+      end
+
+      private
+
+      def extract_detail(response, resource)
+        detail = response['dados']
+        return detail if detail.nil? || detail.is_a?(Hash)
+
+        raise APIError, "Resposta inválida para #{resource}: esperado Hash ou nil em dados"
+      end
+
+      def logger
+        CongregaPlenum.configuration.logger
+      end
+
+      def log_info(message)
+        logger.info("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_error(message)
+        logger.error("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_debug(message)
+        logger.debug("#{SERVICE_TAG}: #{message}")
+      end
+    end
+  end
+end

data/lib/modules/parties_service.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # Service responsible for interacting with party endpoints. It exposes class
+  # methods that hide pagination, retries and detail lookups.
+  class PartiesService
+    # Default page size for party listings.
+    ITEMS_PER_PAGE = 100
+    # Interval used to emit progress logs while iterating.
+    PROGRESS_INTERVAL = 20
+    # Tag prefix for structured logging.
+    SERVICE_TAG = 'CongregaPlenum::PartiesService'
+
+    class << self
+      # Shared client instance configured via {CongregaPlenum.configure}.
+      #
+      # @return [CongregaPlenum::Client]
+      def client
+        @client ||= CongregaPlenum::Client.instance
+      end
+
+      # Wraps {Client#get} to add service context without hiding request failures.
+      def api_get(endpoint, params = {})
+        client.get(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro ao acessar API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Bulk variant of {.api_get}. Failures are propagated so consumers can
+      # abort an incomplete synchronization.
+      def api_get_paginated(endpoint, params = {})
+        client.get_paginated(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro paginando API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Fetches every party registered na API, enriquecendo com payload detalhado.
+      #
+      # @return [Array<Hash>]
+      def fetch_all
+        log_info('Iniciando coleta de todos os partidos')
+
+        parties = api_get_paginated('partidos', itens: ITEMS_PER_PAGE)
+
+        log_info("Coletamos #{parties.length} partidos da listagem")
+
+        detailed_parties = build_detailed_parties(parties)
+
+        log_info("Finalizamos a coleta detalhada de #{detailed_parties.length} partidos")
+        detailed_parties
+      end
+
+      # Retrieves the detailed payload for a single party.
+      #
+      # @param party_id [Integer]
+      # @return [Hash, nil]
+      # @raise [CongregaPlenum::APIError] if +dados+ has an unexpected type
+      def fetch_by_id(party_id)
+        log_debug("Buscando partido #{party_id}")
+
+        response = api_get("partidos/#{party_id}")
+        extract_detail(response, "partido #{party_id}")
+      end
+
+      # Returns a paginated list of parties, without triggering detail lookups.
+      #
+      # @param page [Integer]
+      # @param items_per_page [Integer]
+      # @return [Array<Hash>]
+      def fetch_list(page: 1, items_per_page: ITEMS_PER_PAGE)
+        log_debug("Buscando lista de partidos página #{page}")
+
+        response = api_get('partidos', pagina: page, itens: items_per_page)
+        response['dados'] || []
+      end
+
+      private
+
+      def extract_detail(response, resource)
+        detail = response['dados']
+        return detail if detail.nil? || detail.is_a?(Hash)
+
+        raise APIError, "Resposta inválida para #{resource}: esperado Hash ou nil em dados"
+      end
+
+      # Converts the lightweight list into the detailed payload expected by
+      # consumers. Extracted to simplify instrumentation/tests.
+      def build_detailed_parties(parties)
+        parties.each_with_index.with_object([]) do |(party, index), collected|
+          detailed_party = fetch_by_id(party['id'])
+          collected << detailed_party if detailed_party
+          log_progress(index, parties.length)
+        end
+      end
+
+      # Emits periodic progress updates so users know long iterations are still
+      # alive.
+      def log_progress(index, total)
+        return unless ((index + 1) % PROGRESS_INTERVAL).zero?
+
+        log_info("Processamos #{index + 1}/#{total} partidos")
+      end
+
+      def logger
+        CongregaPlenum.configuration.logger
+      end
+
+      def log_info(message)
+        logger.info("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_error(message)
+        logger.error("#{SERVICE_TAG}: #{message}")
+      end
+
+      def log_debug(message)
+        logger.debug("#{SERVICE_TAG}: #{message}")
+      end
+    end
+  end
+end