congrega_plenum 0.1.0

data/lib/modules/votings_service.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # Service for voting records produced by the Chamber's Plenary and committees.
+  #
+  # A voting is a single, finished decision. It is not the legislative event in
+  # which it occurred, and a proposition can be affected by several distinct
+  # votings of amendments, reports, requests and other related propositions.
+  # rubocop:disable Metrics/ClassLength
+  class VotingsService
+    # Maximum page size documented for the voting list endpoints.
+    ITEMS_PER_PAGE = 100
+    # Default ordering used by the official API.
+    DEFAULT_ORDER = 'DESC'
+    # Default field used by the official API to order voting records.
+    DEFAULT_ORDER_BY = 'dataHoraRegistro'
+    # Tag prefix for structured logging.
+    SERVICE_TAG = 'CongregaPlenum::VotingsService'
+
+    class << self
+      # Shared client configured through {CongregaPlenum.configure}.
+      #
+      # @return [CongregaPlenum::Client]
+      def client
+        @client ||= CongregaPlenum::Client.instance
+      end
+
+      # Wraps {Client#get} with voting-specific logging while preserving errors.
+      def api_get(endpoint, params = {})
+        client.get(endpoint, params)
+      rescue StandardError => e
+        log_error("Erro ao acessar API em #{endpoint}: #{e.message}")
+        raise
+      end
+
+      # Paginated variant of {.api_get}. Incomplete synchronizations are never
+      # converted into empty results.
+      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
+
+      # Retrieves all pages matching the supplied filters.
+      #
+      # Without date or identifier filters the Câmara API limits the result to
+      # votings from the previous 30 days. When both dates are supplied they
+      # must belong to the same calendar year, as required by the upstream API.
+      #
+      # @option filters [String,Integer,Array<String>,Array<Integer>] :voting_ids
+      # @option filters [Integer,Array<Integer>] :proposition_ids
+      # @option filters [Integer,Array<Integer>] :event_ids
+      # @option filters [Integer,Array<Integer>] :body_ids identifiers from +/orgaos+
+      # @option filters [String,Date] :start_date ISO 8601 date
+      # @option filters [String,Date] :end_date ISO 8601 date
+      # @option filters [String] :order +ASC+ or +DESC+
+      # @option filters [String] :order_by field accepted by the upstream endpoint
+      # @return [Array<Hash>]
+      def fetch_all(**filters)
+        log_info('Iniciando coleta de votações')
+
+        filters[:items_per_page] = ITEMS_PER_PAGE
+        votings = api_get_paginated('votacoes', list_params(filters))
+
+        log_info("Coletamos #{votings.size} votações")
+        votings
+      end
+
+      # Retrieves one page of basic voting records.
+      #
+      # @param page [Integer]
+      # @param items_per_page [Integer]
+      # @see .fetch_all for supported filters
+      # @return [Array<Hash>]
+      def fetch_list(page: 1, items_per_page: ITEMS_PER_PAGE, **filters)
+        filters.merge!(page: page, items_per_page: items_per_page)
+        params = list_params(filters)
+        extract_collection(api_get('votacoes', params), 'lista de votações')
+      end
+
+      # Retrieves the detailed representation of a voting.
+      #
+      # The detail may contain possible voting objects and propositions affected
+      # by the result. These relationships have different legislative meanings.
+      #
+      # @param voting_id [String,Integer] alphanumeric voting identifier
+      # @return [Hash,nil]
+      def fetch_by_id(voting_id)
+        extract_detail(api_get("votacoes/#{voting_id}"), "votação #{voting_id}")
+      end
+
+      # Lists the individual positions registered in an open nominal voting.
+      # An empty response does not identify absent deputies and is normal for
+      # symbolic votings.
+      #
+      # @param voting_id [String,Integer]
+      # @return [Array<Hash>]
+      def fetch_votes(voting_id)
+        response = api_get("votacoes/#{voting_id}/votos")
+        extract_collection(response, "votos da votação #{voting_id}")
+      end
+
+      # Lists recommendations issued by parties, blocs and other leaderships.
+      # The upstream API currently provides orientations only for Plenary votes.
+      #
+      # @param voting_id [String,Integer]
+      # @return [Array<Hash>]
+      def fetch_orientations(voting_id)
+        response = api_get("votacoes/#{voting_id}/orientacoes")
+        extract_collection(response, "orientações da votação #{voting_id}")
+      end
+
+      # Lists votings that had a proposition as their object or affected it.
+      #
+      # @param proposition_id [Integer]
+      # @param order [String]
+      # @param order_by [String]
+      # @return [Array<Hash>]
+      def fetch_by_proposition(proposition_id, order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY)
+        params = { ordem: order, ordenarPor: order_by }
+        response = api_get("proposicoes/#{proposition_id}/votacoes", params)
+        extract_collection(response, "votações da proposição #{proposition_id}")
+      end
+
+      # Lists votings completed during a deliberative event.
+      #
+      # @param event_id [Integer]
+      # @return [Array<Hash>]
+      def fetch_by_event(event_id)
+        response = api_get("eventos/#{event_id}/votacoes")
+        extract_collection(response, "votações do evento #{event_id}")
+      end
+
+      # Retrieves all voting pages for a Chamber body such as the Plenary or a
+      # committee.
+      #
+      # @param body_id [Integer] identifier from +/orgaos+
+      # @param proposition_ids [Integer,Array<Integer>,nil]
+      # @param start_date [String,Date,nil]
+      # @param end_date [String,Date,nil]
+      # @param order [String]
+      # @param order_by [String]
+      # @return [Array<Hash>]
+      # rubocop:disable Metrics/ParameterLists
+      def fetch_by_body(body_id, proposition_ids: nil, start_date: nil, end_date: nil,
+                        order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY)
+        params = {
+          idProposicao: normalize_filter(proposition_ids),
+          dataInicio: normalize_date(start_date),
+          dataFim: normalize_date(end_date),
+          itens: ITEMS_PER_PAGE,
+          ordem: order,
+          ordenarPor: order_by
+        }.compact
+
+        api_get_paginated("orgaos/#{body_id}/votacoes", params)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      def list_params(filters)
+        identifiers = {
+          id: normalize_filter(filters[:voting_ids]),
+          idProposicao: normalize_filter(filters[:proposition_ids]),
+          idEvento: normalize_filter(filters[:event_ids]),
+          idOrgao: normalize_filter(filters[:body_ids]),
+          dataInicio: normalize_date(filters[:start_date]),
+          dataFim: normalize_date(filters[:end_date])
+        }
+
+        identifiers.merge(pagination_params(filters)).compact
+      end
+
+      def pagination_params(filters)
+        {
+          pagina: filters[:page],
+          itens: filters.fetch(:items_per_page, ITEMS_PER_PAGE),
+          ordem: filters.fetch(:order, DEFAULT_ORDER),
+          ordenarPor: filters.fetch(:order_by, DEFAULT_ORDER_BY)
+        }
+      end
+
+      def normalize_filter(value)
+        return if value.nil?
+
+        value.is_a?(Array) ? value.join(',') : value
+      end
+
+      def normalize_date(value)
+        value&.to_s
+      end
+
+      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 extract_collection(response, resource)
+        collection = response['dados']
+        return [] if collection.nil?
+        return collection if collection.is_a?(Array)
+
+        raise APIError, "Resposta inválida para #{resource}: esperado Array 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
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CongregaPlenum
+  # Current gem version.
+  VERSION = '0.1.0'
+end

data/sig/congrega_plenum.rbs

@@ -0,0 +1,205 @@
+module CongregaPlenum
+  VERSION: String
+  type params_hash = ::Hash[::Symbol, untyped]
+  type payload_hash = ::Hash[String, untyped]
+  type payload_list = ::Array[payload_hash]
+  type detail_payload = payload_hash?
+  type identifier_filter = Integer | String | ::Array[Integer] | ::Array[String]
+  type numeric_filter = Integer | ::Array[Integer]
+  type date_filter = String | Date
+
+  class Error < ::StandardError
+  end
+
+  class ConnectionError < Error
+  end
+
+  class APIError < Error
+  end
+
+  class ServerError < APIError
+  end
+
+  class RateLimitError < Error
+  end
+
+  @configuration: Configuration
+
+  def self.configuration: () -> Configuration
+  def self.configuration=: (Configuration) -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+
+  class Configuration
+    attr_accessor base_url: String
+    attr_accessor timeout: Integer
+    attr_accessor retries: Integer
+    attr_accessor retry_delay: Float
+    attr_accessor rate_limit_delay: Float
+    attr_accessor logger: Logger
+
+    def initialize: () -> void
+  end
+
+  class HttpAdapter
+    attr_reader configuration: Configuration
+
+    def initialize: (?configuration: Configuration) -> void
+    def get: (String) -> ::Net::HTTPResponse
+    def build_http_client: (::URI::Generic) -> ::Net::HTTP
+    def build_http_request: (::URI::Generic) -> ::Net::HTTP::Get
+    def logger: () -> Logger
+  end
+
+  class RetryPolicy
+    attr_reader configuration: Configuration
+
+    def initialize: (?configuration: Configuration) -> void
+    def with_retries: [T] (String) { () -> T } -> T
+    def retry_request: (Integer, String, Error) -> void
+    def handle_retry_failure: (String, Error) -> bot
+    def calculate_backoff_delay: (Integer) -> Float
+    def max_retries: () -> Integer
+    def logger: () -> Logger
+  end
+
+  class ResponseHandler
+    def handle: (::Net::HTTPResponse, String) -> payload_hash
+    def parse_json_response: (::Net::HTTPResponse, String) -> payload_hash
+  end
+
+  class Client
+    include ::Singleton
+
+    def self.instance: () -> Client
+    attr_reader http_adapter: HttpAdapter
+    attr_reader retry_policy: RetryPolicy
+    attr_reader response_handler: ResponseHandler
+
+    def initialize: () -> void
+    def get: (String, ?params_hash) -> payload_hash
+    def get_paginated: (String, ?params_hash) -> payload_list
+    def each_response_page: (String, params_hash) { (payload_list) -> void } -> void
+    def request_page: (String, params_hash, Integer) -> payload_hash
+    def next_page?: (payload_hash) -> bool
+    def apply_rate_limit_delay: () -> void
+    def execute_request: (String) -> payload_hash
+    def build_url: (String, ?params_hash) -> String
+    def configuration: () -> Configuration
+  end
+
+  class CongressmenService
+    ITEMS_PER_PAGE: Integer
+    PROGRESS_INTERVAL: Integer
+    SERVICE_TAG: String
+
+    def self.client: () -> CongregaPlenum::Client
+    def self.api_get: (String, ?params_hash) -> payload_hash
+    def self.api_get_paginated: (String, ?params_hash) -> payload_list
+    def self.fetch_all: () -> payload_list
+    def self.fetch_all_by_legislature: (Integer) -> payload_list
+    def self.fetch_by_id: (Integer) -> detail_payload
+    def self.fetch_list: (?page: Integer, ?items_per_page: Integer, ?legislature_id: Integer?) -> payload_list
+    def self.fetch_deputies_collection: (context: String, params: params_hash) -> payload_list
+    def self.extract_detail: (payload_hash, String) -> detail_payload
+    def self.build_detailed_deputies: (payload_list, String) -> payload_list
+    def self.log_progress: (Integer, Integer, String) -> void
+    def self.logger: () -> Logger
+    def self.log_info: (String) -> void
+    def self.log_error: (String) -> void
+    def self.log_debug: (String) -> void
+  end
+
+  class PartiesService
+    ITEMS_PER_PAGE: Integer
+    PROGRESS_INTERVAL: Integer
+    SERVICE_TAG: String
+
+    def self.client: () -> CongregaPlenum::Client
+    def self.api_get: (String, ?params_hash) -> payload_hash
+    def self.api_get_paginated: (String, ?params_hash) -> payload_list
+    def self.fetch_all: () -> payload_list
+    def self.fetch_by_id: (Integer) -> detail_payload
+    def self.fetch_list: (?page: Integer, ?items_per_page: Integer) -> payload_list
+    def self.extract_detail: (payload_hash, String) -> detail_payload
+    def self.build_detailed_parties: (payload_list) -> payload_list
+    def self.log_progress: (Integer, Integer) -> void
+    def self.logger: () -> Logger
+    def self.log_info: (String) -> void
+    def self.log_error: (String) -> void
+    def self.log_debug: (String) -> void
+  end
+
+  class LegislaturesService
+    PAGE_SIZE: Integer
+    DEPUTIES_PAGE_SIZE: Integer
+    SERVICE_TAG: String
+
+    def self.client: () -> CongregaPlenum::Client
+    def self.api_get: (String, ?params_hash) -> payload_hash
+    def self.api_get_paginated: (String, ?params_hash) -> payload_list
+    def self.fetch_all: () -> payload_list
+    def self.fetch_by_id: (Integer) -> detail_payload
+    def self.fetch_mesa: (Integer) -> payload_list
+    def self.fetch_deputies: (Integer) -> payload_list
+    def self.extract_detail: (payload_hash, String) -> detail_payload
+    def self.logger: () -> Logger
+    def self.log_info: (String) -> void
+    def self.log_error: (String) -> void
+    def self.log_debug: (String) -> void
+  end
+
+  class VotingsService
+    ITEMS_PER_PAGE: Integer
+    DEFAULT_ORDER: String
+    DEFAULT_ORDER_BY: String
+    SERVICE_TAG: String
+
+    def self.client: () -> CongregaPlenum::Client
+    def self.api_get: (String, ?params_hash) -> payload_hash
+    def self.api_get_paginated: (String, ?params_hash) -> payload_list
+    def self.fetch_all: (?
+      voting_ids: identifier_filter?,
+      proposition_ids: numeric_filter?,
+      event_ids: numeric_filter?,
+      body_ids: numeric_filter?,
+      start_date: date_filter?,
+      end_date: date_filter?,
+      order: String,
+      order_by: String
+    ) -> payload_list
+    def self.fetch_list: (?
+      page: Integer,
+      items_per_page: Integer,
+      voting_ids: identifier_filter?,
+      proposition_ids: numeric_filter?,
+      event_ids: numeric_filter?,
+      body_ids: numeric_filter?,
+      start_date: date_filter?,
+      end_date: date_filter?,
+      order: String,
+      order_by: String
+    ) -> payload_list
+    def self.fetch_by_id: (String | Integer) -> detail_payload
+    def self.fetch_votes: (String | Integer) -> payload_list
+    def self.fetch_orientations: (String | Integer) -> payload_list
+    def self.fetch_by_proposition: (Integer, ?order: String, ?order_by: String) -> payload_list
+    def self.fetch_by_event: (Integer) -> payload_list
+    def self.fetch_by_body: (
+      Integer,
+      ?proposition_ids: numeric_filter?,
+      ?start_date: date_filter?,
+      ?end_date: date_filter?,
+      ?order: String,
+      ?order_by: String
+    ) -> payload_list
+    def self.list_params: (params_hash) -> params_hash
+    def self.pagination_params: (params_hash) -> params_hash
+    def self.normalize_filter: (identifier_filter?) -> (String | Integer)?
+    def self.normalize_date: (date_filter?) -> String?
+    def self.extract_detail: (payload_hash, String) -> detail_payload
+    def self.extract_collection: (payload_hash, String) -> payload_list
+    def self.logger: () -> Logger
+    def self.log_info: (String) -> void
+    def self.log_error: (String) -> void
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: congrega_plenum
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- zarbielli
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: HTTP client with pagination, retries and logging for Câmara dos Deputados
+  open data endpoints.
+email:
+- joao.zarbielli@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/adapters/http_adapter.rb
+- lib/adapters/response_handler.rb
+- lib/adapters/retry_policy.rb
+- lib/client.rb
+- lib/congrega_plenum.rb
+- lib/modules/congressmen_service.rb
+- lib/modules/legislatures_service.rb
+- lib/modules/parties_service.rb
+- lib/modules/votings_service.rb
+- lib/version.rb
+- sig/congrega_plenum.rbs
+homepage: https://github.com/zarbielli/CongregaPlenum
+licenses:
+- GPL-2.0-only
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/zarbielli/CongregaPlenum
+  source_code_uri: https://github.com/zarbielli/CongregaPlenum
+  changelog_uri: https://github.com/zarbielli/CongregaPlenum/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for Câmara dos Deputados open data API
+test_files: []