congress_gov 0.1.0

data/lib/congress_gov/resources/treaty.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access treaty data from the Congress.gov API.
+    class Treaty < Base
+      # List treaties, optionally filtered by congress.
+      #
+      # @param congress [Integer, nil] filter to a specific Congress
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, limit: 20, offset: 0)
+        path = congress ? "treaty/#{congress}" : 'treaty'
+        client.get(path, { limit: limit, offset: offset })
+      end
+
+      # Fetch a treaty's full detail record.
+      #
+      # @param congress [Integer] e.g. 119
+      # @param number   [Integer] treaty number
+      # @return [CongressGov::Response]
+      def get(congress, number)
+        client.get("treaty/#{congress}/#{number}")
+      end
+
+      # Fetch a treaty with a specific suffix.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param suffix   [String]  treaty suffix
+      # @return [CongressGov::Response]
+      def get_with_suffix(congress, number, suffix)
+        client.get("treaty/#{congress}/#{number}/#{suffix}")
+      end
+
+      # Actions taken on a treaty.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def actions(congress, number, limit: 20, offset: 0)
+        client.get("treaty/#{congress}/#{number}/actions",
+                   { limit: limit, offset: offset })
+      end
+
+      # Actions for a treaty with a specific suffix.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param suffix   [String]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def actions_with_suffix(congress, number, suffix, limit: 20, offset: 0)
+        client.get("treaty/#{congress}/#{number}/#{suffix}/actions",
+                   { limit: limit, offset: offset })
+      end
+
+      # Committees associated with a treaty.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def committees(congress, number, limit: 20, offset: 0)
+        client.get("treaty/#{congress}/#{number}/committees",
+                   { limit: limit, offset: offset })
+      end
+    end
+  end
+end

data/lib/congress_gov/response.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module CongressGov
+  # Wraps a raw Faraday response body.
+  # Handles the Congress.gov pagination envelope uniformly.
+  # Includes +Enumerable+ so callers can iterate results directly.
+  class Response
+    include Enumerable
+
+    # @return [Hash, Array, nil] the parsed JSON body.
+    attr_reader :raw
+    # @return [Integer] the HTTP status code.
+    attr_reader :status
+
+    # @param body [Hash, Array, nil] parsed response body.
+    # @param status [Integer] HTTP status code.
+    def initialize(body, status)
+      @raw    = body || {}
+      @status = status
+    end
+
+    # The primary results collection. Congress.gov uses different top-level keys
+    # per endpoint ("members", "bills", "house-vote", etc.).
+    # Returns the first Array value found in the body, falling back to [].
+    #
+    # @return [Array]
+    def results
+      return raw if raw.is_a?(Array)
+      return [] unless raw.is_a?(Hash)
+
+      array_value = raw.values.find { |v| v.is_a?(Array) }
+      array_value || []
+    end
+
+    # Yields each result, enabling Enumerable methods on the response.
+    #
+    # @yield [Hash] each result item
+    # @return [Enumerator] if no block given
+    def each(&)
+      results.each(&)
+    end
+
+    # Total number of matching records across all pages.
+    #
+    # @return [Integer, nil]
+    def total_count
+      raw.dig('pagination', 'count') if raw.is_a?(Hash)
+    end
+
+    # URL of the next page, or nil if on the last page.
+    #
+    # @return [String, nil]
+    def next_url
+      raw.dig('pagination', 'next') if raw.is_a?(Hash)
+    end
+
+    # URL of the previous page, or nil if on the first page.
+    #
+    # @return [String, nil]
+    def prev_url
+      raw.dig('pagination', 'prev') if raw.is_a?(Hash)
+    end
+
+    # Whether another page of results exists.
+    #
+    # @return [Boolean]
+    def has_next_page?
+      !next_url.nil?
+    end
+
+    # The offset for the next page, parsed from next_url.
+    #
+    # @return [Integer, nil]
+    def next_offset
+      return nil unless next_url
+
+      uri    = URI.parse(next_url)
+      params = URI.decode_www_form(uri.query.to_s).to_h
+      params['offset']&.to_i
+    end
+
+    # Delegates key lookup to the raw response body.
+    #
+    # @param key [String] top-level key in the parsed JSON.
+    # @return [Object, nil]
+    def [](key)
+      raw[key] if raw.is_a?(Hash)
+    end
+
+    # Returns the raw parsed response body as a Hash.
+    #
+    # @return [Hash, Array]
+    def to_h
+      raw
+    end
+
+    # Concise representation for debugging.
+    #
+    # @return [String]
+    def inspect
+      count = results.size
+      total = total_count
+      more  = has_next_page? ? ' has_next_page' : ''
+      "#<#{self.class} status=#{status} results=#{count}#{"/#{total}" if total}#{more}>"
+    end
+
+    alias to_s inspect
+  end
+end

data/lib/congress_gov/version.rb

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

data/lib/congress_gov.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'congress_gov/version'
+require 'congress_gov/configuration'
+require 'congress_gov/error'
+require 'congress_gov/response'
+require 'congress_gov/client'
+require 'congress_gov/resources/base'
+require 'congress_gov/resources/member'
+require 'congress_gov/resources/bill'
+require 'congress_gov/resources/house_vote'
+require 'congress_gov/resources/clerk_vote'
+require 'congress_gov/resources/committee'
+require 'congress_gov/resources/amendment'
+require 'congress_gov/resources/nomination'
+require 'congress_gov/resources/treaty'
+require 'congress_gov/resources/house_communication'
+require 'congress_gov/resources/senate_communication'
+require 'congress_gov/resources/house_requirement'
+require 'congress_gov/resources/law'
+require 'congress_gov/resources/congress_info'
+require 'congress_gov/resources/summary'
+require 'congress_gov/resources/committee_report'
+require 'congress_gov/resources/committee_print'
+require 'congress_gov/resources/committee_meeting'
+require 'congress_gov/resources/hearing'
+require 'congress_gov/resources/daily_congressional_record'
+require 'congress_gov/resources/bound_congressional_record'
+require 'congress_gov/resources/crs_report'
+
+# Ruby client for the Congress.gov REST API v3.
+# @see https://api.congress.gov/
+module CongressGov
+  # Mutex for thread-safe initialization of configuration and client.
+  @mutex = Mutex.new
+
+  class << self
+    # Returns the current configuration instance.
+    # Thread-safe via Mutex.
+    #
+    # @return [CongressGov::Configuration]
+    def configuration
+      @mutex.synchronize { @configuration ||= Configuration.new }
+    end
+
+    # Yields the configuration instance for modification.
+    #
+    # @yieldparam config [CongressGov::Configuration]
+    # @return [void]
+    def configure
+      @mutex.synchronize { yield(@configuration ||= Configuration.new) }
+    end
+
+    # Resets configuration and client to defaults.
+    # Thread-safe via Mutex.
+    #
+    # @return [void]
+    def reset!
+      @mutex.synchronize do
+        @configuration = Configuration.new
+        @client        = nil
+      end
+    end
+
+    # Returns the shared API client instance.
+    # Thread-safe via Mutex.
+    #
+    # @return [CongressGov::Client]
+    def client
+      @mutex.synchronize { @client ||= Client.new(@configuration || Configuration.new) }
+    end
+
+    # Resource shorthand accessors
+
+    # @return [CongressGov::Resources::Member]
+    def member
+      Resources::Member.new(client)
+    end
+
+    # @return [CongressGov::Resources::Bill]
+    def bill
+      Resources::Bill.new(client)
+    end
+
+    # @return [CongressGov::Resources::HouseVote]
+    def house_vote
+      Resources::HouseVote.new(client)
+    end
+
+    # @return [CongressGov::Resources::ClerkVote]
+    def clerk_vote
+      Resources::ClerkVote.new(client)
+    end
+
+    # @return [CongressGov::Resources::Committee]
+    def committee
+      Resources::Committee.new(client)
+    end
+
+    # @return [CongressGov::Resources::Amendment]
+    def amendment
+      Resources::Amendment.new(client)
+    end
+
+    # @return [CongressGov::Resources::Nomination]
+    def nomination
+      Resources::Nomination.new(client)
+    end
+
+    # @return [CongressGov::Resources::Treaty]
+    def treaty
+      Resources::Treaty.new(client)
+    end
+
+    # @return [CongressGov::Resources::HouseCommunication]
+    def house_communication
+      Resources::HouseCommunication.new(client)
+    end
+
+    # @return [CongressGov::Resources::SenateCommunication]
+    def senate_communication
+      Resources::SenateCommunication.new(client)
+    end
+
+    # @return [CongressGov::Resources::HouseRequirement]
+    def house_requirement
+      Resources::HouseRequirement.new(client)
+    end
+
+    # @return [CongressGov::Resources::Law]
+    def law
+      Resources::Law.new(client)
+    end
+
+    # @return [CongressGov::Resources::CongressInfo]
+    def congress_info
+      Resources::CongressInfo.new(client)
+    end
+
+    # @return [CongressGov::Resources::Summary]
+    def summary
+      Resources::Summary.new(client)
+    end
+
+    # @return [CongressGov::Resources::CommitteeReport]
+    def committee_report
+      Resources::CommitteeReport.new(client)
+    end
+
+    # @return [CongressGov::Resources::CommitteePrint]
+    def committee_print
+      Resources::CommitteePrint.new(client)
+    end
+
+    # @return [CongressGov::Resources::CommitteeMeeting]
+    def committee_meeting
+      Resources::CommitteeMeeting.new(client)
+    end
+
+    # @return [CongressGov::Resources::Hearing]
+    def hearing
+      Resources::Hearing.new(client)
+    end
+
+    # @return [CongressGov::Resources::DailyCongressionalRecord]
+    def daily_congressional_record
+      Resources::DailyCongressionalRecord.new(client)
+    end
+
+    # @return [CongressGov::Resources::BoundCongressionalRecord]
+    def bound_congressional_record
+      Resources::BoundCongressionalRecord.new(client)
+    end
+
+    # @return [CongressGov::Resources::CrsReport]
+    def crs_report
+      Resources::CrsReport.new(client)
+    end
+  end
+end

metadata

@@ -0,0 +1,237 @@
+--- !ruby/object:Gem::Specification
+name: congress_gov
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ThePublicTab
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: faraday-http-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  A Ruby client for the Congress.gov REST API v3. 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.
+email:
+- dev@thepublictab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/congress_gov.rb
+- lib/congress_gov/client.rb
+- lib/congress_gov/configuration.rb
+- lib/congress_gov/error.rb
+- lib/congress_gov/resources/amendment.rb
+- lib/congress_gov/resources/base.rb
+- lib/congress_gov/resources/bill.rb
+- lib/congress_gov/resources/bound_congressional_record.rb
+- lib/congress_gov/resources/clerk_vote.rb
+- lib/congress_gov/resources/committee.rb
+- lib/congress_gov/resources/committee_meeting.rb
+- lib/congress_gov/resources/committee_print.rb
+- lib/congress_gov/resources/committee_report.rb
+- lib/congress_gov/resources/congress_info.rb
+- lib/congress_gov/resources/crs_report.rb
+- lib/congress_gov/resources/daily_congressional_record.rb
+- lib/congress_gov/resources/hearing.rb
+- lib/congress_gov/resources/house_communication.rb
+- lib/congress_gov/resources/house_requirement.rb
+- lib/congress_gov/resources/house_vote.rb
+- lib/congress_gov/resources/law.rb
+- lib/congress_gov/resources/member.rb
+- lib/congress_gov/resources/nomination.rb
+- lib/congress_gov/resources/senate_communication.rb
+- lib/congress_gov/resources/summary.rb
+- lib/congress_gov/resources/treaty.rb
+- lib/congress_gov/response.rb
+- lib/congress_gov/version.rb
+homepage: https://github.com/xjackk/congress-gov-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/xjackk/congress-gov-rb
+  source_code_uri: https://github.com/xjackk/congress-gov-rb
+  changelog_uri: https://github.com/xjackk/congress-gov-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/xjackk/congress-gov-rb/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: Ruby client for the Congress.gov API v3
+test_files: []