congress_gov 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e7b32276ee034d37d47c0fbe21485df9fd922f51fc56623cccd567e1d3884ad
+  data.tar.gz: 5f4986720a61399f43c8c7bfe6ed14c9e64db870f6f281e766193a215f8014a2
+SHA512:
+  metadata.gz: 8d1bc89489d8626316023c668ea5b131531405ae1ba0e13a2ac142d6186470e5e333c32da42cbb4b217c7cacdb02ab33b7dd0912dad8434b4fa44c43fa0281e6
+  data.tar.gz: d7ae6017db8987dd0b224434aee920e46a3c0e14bc000efa420ba2e3c5f6f78c2cf4b6206800aa00dad6be9766f052ce783cff7b9f035f05f41a9f583da8792f

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2025-09-20
+
+### Added
+- Initial release
+- Member lookup by district, bioguide ID, sponsored/cosponsored legislation
+- Bill detail, actions, subjects, summaries, cosponsors
+- House roll call vote listing, detail, and per-member vote positions
+- Clerk of the House XML fallback parser for vote records
+- Committee listing and membership
+- Full error hierarchy with retry support for rate limits
+- VCR-based test suite with real Clerk XML fixture

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 ThePublicTab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,156 @@
+# congress_gov
+
+Ruby client for the [Congress.gov REST API v3](https://api.congress.gov/). Access member data, roll call votes, bill details, committee information, and more. Includes a fallback parser for Clerk of the House XML vote records.
+
+The first Ruby client targeting the current v3 API.
+
+## Installation
+
+```ruby
+gem "congress_gov"
+```
+
+Then `bundle install`, or install directly:
+
+```
+gem install congress_gov
+```
+
+## Configuration
+
+Get an API key at https://api.congress.gov/sign-up/
+
+```ruby
+CongressGov.configure do |config|
+  config.api_key = ENV["CONGRESS_GOV_API_KEY"]
+  config.timeout = 30       # optional, default 30s
+  config.retries = 3        # optional, default 3 (handles 429s with exponential backoff)
+  config.logger  = Logger.new($stdout)  # optional
+end
+```
+
+## Usage
+
+### Member Lookup
+
+```ruby
+# Get the current rep for a congressional district
+rep = CongressGov.member.current_for_district(state: "VA", district: 8)
+rep["bioguideId"]  #=> "B001292"
+
+# Full member profile
+profile = CongressGov.member.get("B001292")
+profile["member"]["directOrderName"]  #=> "Donald S. Beyer"
+
+# Sponsored legislation
+CongressGov.member.sponsored_legislation("B001292", limit: 50)
+
+# List all current members (paginated, max 250 per page)
+CongressGov.member.list(current: true, limit: 250)
+```
+
+### Roll Call Votes
+
+```ruby
+# How did a member vote on a specific roll call?
+position = CongressGov.house_vote.position_for_member(
+  congress: 119, session: 1, roll_call: 281, bioguide_id: "B001292"
+)
+position  #=> "Nay"
+
+# All member votes as a hash keyed by bioguide ID
+votes = CongressGov.house_vote.member_votes_by_bioguide(
+  congress: 119, session: 1, roll_call: 281
+)
+# { "B001292" => "Nay", "A000055" => "Aye", ... }
+```
+
+### Bills
+
+```ruby
+# Bill detail
+bill = CongressGov.bill.get(119, "hr", 5371)
+
+# Find House roll call votes associated with a bill
+refs = CongressGov.bill.house_vote_references(119, "hr", 5371)
+# [{ "rollNumber" => 281, "chamber" => "House", "url" => "https://clerk.house.gov/..." }]
+
+# Actions, subjects, summaries, cosponsors
+CongressGov.bill.actions(119, "hr", 5371)
+CongressGov.bill.subjects(119, "hr", 5371)
+CongressGov.bill.summaries(119, "hr", 5371)
+CongressGov.bill.cosponsors(119, "hr", 5371)
+```
+
+### Clerk of the House XML (Fallback)
+
+Parse vote records directly from Clerk XML — no API key needed:
+
+```ruby
+vote = CongressGov.clerk_vote.fetch(year: 2025, roll_call: 281)
+vote[:result]              #=> "Passed"
+vote[:totals][:yea]        #=> 217
+vote[:members]["B001292"]  #=> { name: "Beyer", party: "D", state: "VA", vote: "Nay" }
+
+# Or from a URL returned by bill actions
+vote = CongressGov.clerk_vote.fetch_by_url("https://clerk.house.gov/evs/2025/roll281.xml")
+```
+
+### Committees
+
+```ruby
+CongressGov.committee.list(chamber: "house")
+CongressGov.committee.get("senate", "ssap00")
+CongressGov.committee.for_member("B001292")
+```
+
+### Error Handling
+
+```ruby
+begin
+  CongressGov.member.get("Z999999")
+rescue CongressGov::NotFoundError
+  puts "Member not found"
+rescue CongressGov::AuthenticationError
+  puts "Check your API key"
+rescue CongressGov::RateLimitError
+  puts "Rate limited (5,000 req/hour)"
+rescue CongressGov::ParseError => e
+  puts "Clerk XML parse failed: #{e.message}"
+rescue CongressGov::ConnectionError => e
+  puts "Network issue: #{e.message}"
+end
+```
+
+## The Data Chain
+
+This gem enables crossreferencing congressional votes with federal spending:
+
+```
+District
+  -> CongressGov.member.current_for_district(state:, district:)
+     -> bioguide_id
+  -> CongressGov.bill.house_vote_references(congress, type, number)
+     -> roll_call numbers
+  -> CongressGov.house_vote.position_for_member(congress:, session:, roll_call:, bioguide_id:)
+     -> "Yea" or "Nay"
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+To record VCR cassettes against the live API:
+
+```bash
+export CONGRESS_GOV_API_KEY="your_real_key"
+VCR_RECORD=new_episodes bundle exec rspec
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/congress_gov/client.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'faraday/http_cache'
+require 'json'
+
+module CongressGov
+  # Low-level HTTP client that wraps Faraday for Congress.gov API requests.
+  # Handles authentication, retries, timeout, and error mapping.
+  class Client
+    # @return [CongressGov::Configuration]
+    attr_reader :config
+
+    # Creates a new client and validates the configuration.
+    #
+    # @param config [CongressGov::Configuration] configuration to use.
+    def initialize(config = CongressGov.configuration)
+      @config = config
+      config.validate!
+    end
+
+    # Returns a memoized Faraday connection configured for the Congress.gov API.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= Faraday.new(url: config.base_url) do |f|
+        f.options.timeout      = config.timeout
+        f.options.open_timeout = 10
+
+        # Inject API key into every request as a query param
+        f.request :url_encoded
+        f.response :json, content_type: /\bjson$/
+
+        if config.cache_store
+          f.use :http_cache,
+                store: config.cache_store,
+                shared_cache: false
+        end
+
+        f.request :retry,
+                  max: config.retries,
+                  interval: 1.0,
+                  interval_randomness: 0.5,
+                  backoff_factor: 2,
+                  retry_statuses: [429, 500, 502, 503, 504],
+                  exceptions: [
+                    Faraday::TimeoutError,
+                    Faraday::ConnectionFailed,
+                    Faraday::RetriableResponse
+                  ]
+
+        f.response :logger, config.logger if config.logger
+        f.adapter config.adapter
+      end
+    end
+
+    # Plain HTTP client for fetching Clerk XML — no auth, no JSON parsing.
+    def clerk_connection
+      @clerk_connection ||= Faraday.new(url: config.clerk_base_url) do |f|
+        f.options.timeout      = config.timeout
+        f.options.open_timeout = 10
+        f.adapter config.adapter
+      end
+    end
+
+    # GET request — automatically appends api_key to params.
+    #
+    # @param path   [String]
+    # @param params [Hash]
+    # @return [CongressGov::Response]
+    def get(path, params = {})
+      response = connection.get(path, params.merge(api_key: config.api_key, format: 'json'))
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise ConnectionError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    # Fetch raw XML from clerk.house.gov. Returns the raw body string.
+    # Does not raise on HTTP errors — callers handle nil/blank responses.
+    #
+    # @param path [String] e.g. "2025/roll281.xml"
+    # @return [String, nil]
+    def get_clerk_xml(path)
+      response = clerk_connection.get(path)
+      return nil unless response.status == 200
+
+      response.body
+    rescue Faraday::Error
+      nil
+    end
+
+    private
+
+    # Maps an HTTP response to a {Response} or raises an appropriate error.
+    #
+    # @param response [Faraday::Response]
+    # @return [CongressGov::Response]
+    # @raise [CongressGov::Error] on non-2xx status codes.
+    def handle_response(response)
+      case response.status
+      when 200..299
+        Response.new(response.body, response.status)
+      when 403
+        raise AuthenticationError.new(
+          'Invalid or missing API key',
+          status: 403,
+          body: response.body
+        )
+      when 404
+        raise NotFoundError.new(status: 404, body: response.body)
+      when 429
+        raise RateLimitError.new('Rate limit exceeded', status: 429, body: response.body)
+      when 400..499
+        raise ClientError.new(status: response.status, body: response.body)
+      when 500..599
+        raise ServerError.new(status: response.status, body: response.body)
+      else
+        raise Error, "Unexpected HTTP status: #{response.status}"
+      end
+    end
+  end
+end

data/lib/congress_gov/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CongressGov
+  # Stores runtime settings for the CongressGov client.
+  # Use {CongressGov.configure} to modify these values.
+  class Configuration
+    # Default base URL for the Congress.gov API.
+    DEFAULT_BASE_URL  = 'https://api.congress.gov/v3/'
+    # Default HTTP timeout in seconds.
+    DEFAULT_TIMEOUT   = 30
+    # Default number of automatic retries on transient failures.
+    DEFAULT_RETRIES   = 3
+    # Base URL for the House Clerk electronic voting system.
+    CLERK_BASE_URL    = 'https://clerk.house.gov/evs/'
+
+    # @return [String, nil] API key used to authenticate requests.
+    # @return [String] base URL for the Congress.gov API.
+    # @return [String] base URL for the House Clerk voting site.
+    # @return [Integer] HTTP timeout in seconds.
+    # @return [Integer] number of automatic retries on transient failures.
+    # @return [Logger, nil] optional logger for request/response debugging.
+    # @return [Symbol] Faraday adapter to use for HTTP requests.
+    attr_accessor :api_key, :base_url, :clerk_base_url,
+                  :timeout, :retries, :logger, :adapter,
+                  :cache_store
+
+    # Initializes a new Configuration with sensible defaults.
+    # Reads +CONGRESS_GOV_API_KEY+ from the environment when available.
+    def initialize
+      @api_key        = ENV.fetch('CONGRESS_GOV_API_KEY', nil)
+      @base_url       = DEFAULT_BASE_URL
+      @clerk_base_url = CLERK_BASE_URL
+      @timeout        = DEFAULT_TIMEOUT
+      @retries        = DEFAULT_RETRIES
+      @logger         = nil
+      @adapter        = Faraday.default_adapter
+      @cache_store    = nil
+    end
+
+    # Raises {ConfigurationError} unless a valid API key is present.
+    #
+    # @return [void]
+    # @raise [ConfigurationError] if api_key is nil or empty.
+    def validate!
+      raise ConfigurationError, 'api_key is required' if api_key.nil? || api_key.empty?
+    end
+  end
+end

data/lib/congress_gov/error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module CongressGov
+  # Base error class. All gem errors inherit from this.
+  class Error < StandardError; end
+
+  # Raised when api_key is missing or blank.
+  class ConfigurationError < Error; end
+
+  # Raised on 4xx responses (excluding 429).
+  class ClientError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body   = body
+      super(message || "HTTP #{status}: #{body}")
+    end
+  end
+
+  # Raised on 403 — usually means invalid or missing API key.
+  class AuthenticationError < ClientError; end
+
+  # Raised on 404.
+  class NotFoundError < ClientError; end
+
+  # Raised on 429 after retries are exhausted.
+  class RateLimitError < ClientError; end
+
+  # Raised on 5xx responses.
+  class ServerError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body   = body
+      super(message || "Server error HTTP #{status}")
+    end
+  end
+
+  # Raised on network-level failures (timeout, connection refused).
+  class ConnectionError < Error; end
+
+  # Raised when Clerk XML cannot be parsed or is malformed.
+  class ParseError < Error; end
+end

data/lib/congress_gov/resources/amendment.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access amendment data from the Congress.gov API.
+    class Amendment < Base
+      # Valid amendment type codes: samdt (Senate), hamdt (House), suamdt (Senate unprinted).
+      AMENDMENT_TYPES = %w[samdt hamdt suamdt].freeze
+
+      # List amendments with optional congress and type filters.
+      #
+      # @param congress       [Integer, nil] e.g. 119
+      # @param amendment_type [String, nil]  one of AMENDMENT_TYPES
+      # @param limit          [Integer]
+      # @param offset         [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, amendment_type: nil, limit: 20, offset: 0)
+        params = { limit: limit, offset: offset }
+
+        if congress && amendment_type
+          validate_type!(amendment_type)
+          client.get("amendment/#{congress}/#{amendment_type.downcase}", params)
+        elsif congress
+          client.get("amendment/#{congress}", params)
+        else
+          client.get('amendment', params)
+        end
+      end
+
+      # Fetch a single amendment record.
+      #
+      # @param congress [Integer]
+      # @param type     [String]  one of AMENDMENT_TYPES
+      # @param number   [Integer]
+      # @return [CongressGov::Response]
+      def get(congress, type, number)
+        validate_type!(type)
+        client.get("amendment/#{congress}/#{type.downcase}/#{number}")
+      end
+
+      # Actions taken on an amendment.
+      #
+      # @param congress [Integer]
+      # @param type     [String]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def actions(congress, type, number, limit: 20, offset: 0)
+        validate_type!(type)
+        client.get("amendment/#{congress}/#{type.downcase}/#{number}/actions",
+                   { limit: limit, offset: offset })
+      end
+
+      # Sub-amendments to an amendment.
+      #
+      # @param congress [Integer]
+      # @param type     [String]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def amendments(congress, type, number, limit: 20, offset: 0)
+        validate_type!(type)
+        client.get("amendment/#{congress}/#{type.downcase}/#{number}/amendments",
+                   { limit: limit, offset: offset })
+      end
+
+      # Cosponsors of an amendment.
+      #
+      # @param congress [Integer]
+      # @param type     [String]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def cosponsors(congress, type, number, limit: 20, offset: 0)
+        validate_type!(type)
+        client.get("amendment/#{congress}/#{type.downcase}/#{number}/cosponsors",
+                   { limit: limit, offset: offset })
+      end
+
+      # Text versions of an amendment.
+      #
+      # @param congress [Integer]
+      # @param type     [String]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def text(congress, type, number, limit: 20, offset: 0)
+        validate_type!(type)
+        client.get("amendment/#{congress}/#{type.downcase}/#{number}/text",
+                   { limit: limit, offset: offset })
+      end
+
+      private
+
+      def validate_type!(type)
+        return if AMENDMENT_TYPES.include?(type.to_s.downcase)
+
+        raise ArgumentError,
+              "amendment type must be one of: #{AMENDMENT_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CongressGov
+  # Namespace for all Congress.gov API resource classes.
+  module Resources
+    # Abstract base class for all Congress.gov resource endpoints.
+    # Provides a shared client reference, a convenience +get+ wrapper,
+    # and generic auto-pagination via {#each_page} and {#paginate}.
+    class Base
+      # Creates a new resource bound to the given client.
+      #
+      # @param client [CongressGov::Client] the HTTP client to use.
+      def initialize(client = CongressGov.client)
+        @client = client
+      end
+
+      # Iterate through every page of a paginated endpoint.
+      # Yields each {CongressGov::Response} page.
+      #
+      # @param path [String] API path.
+      # @param params [Hash] query parameters (should include :limit).
+      # @yield [CongressGov::Response] each page of results.
+      # @return [Enumerator] if no block given.
+      #
+      # @example
+      #   CongressGov.bill.each_page('bill/119', limit: 250) do |page|
+      #     page.results.each { |bill| process(bill) }
+      #   end
+      def each_page(path, params = {}, &block)
+        return enum_for(:each_page, path, params) unless block
+
+        limit  = params.fetch(:limit, 20)
+        offset = params.fetch(:offset, 0)
+
+        loop do
+          response = client.get(path, params.merge(limit: limit, offset: offset))
+          yield response
+          break unless response.has_next_page?
+
+          offset += limit
+        end
+      end
+
+      # Collect all results across all pages of a paginated endpoint.
+      # Returns a flat Array of all result hashes.
+      #
+      # @param path [String] API path.
+      # @param params [Hash] query parameters.
+      # @return [Array<Hash>] all results across all pages.
+      #
+      # @example
+      #   all_bills = CongressGov.bill.paginate('bill/119/hr', limit: 250)
+      def paginate(path, params = {})
+        results = []
+        each_page(path, params) { |page| results.concat(page.results) }
+        results
+      end
+
+      private
+
+      # @return [CongressGov::Client]
+      attr_reader :client
+
+      # Shorthand for {Client#get}.
+      #
+      # @param path [String] API path relative to the base URL.
+      # @param params [Hash] optional query parameters.
+      # @return [CongressGov::Response]
+      def get(path, params = {})
+        client.get(path, params)
+      end
+    end
+  end
+end