congress_gov 0.1.0

data/lib/congress_gov/resources/crs_report.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access Congressional Research Service reports from the Congress.gov API.
+    class CrsReport < Base
+      # List CRS reports.
+      #
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def list(limit: 20, offset: 0)
+        client.get('crsreport', { limit: limit, offset: offset })
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/daily_congressional_record.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access daily Congressional Record data from the Congress.gov API.
+    class DailyCongressionalRecord < Base
+      # List daily congressional record volumes.
+      #
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def list(limit: 20, offset: 0)
+        client.get('daily-congressional-record', { limit: limit, offset: offset })
+      end
+
+      # List issues for a specific volume.
+      #
+      # @param volume [Integer]
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def list_by_volume(volume, limit: 20, offset: 0)
+        client.get("daily-congressional-record/#{volume}", { limit: limit, offset: offset })
+      end
+
+      # Get a specific issue.
+      #
+      # @param volume [Integer]
+      # @param issue  [Integer]
+      # @return [CongressGov::Response]
+      def get_issue(volume, issue)
+        client.get("daily-congressional-record/#{volume}/#{issue}")
+      end
+
+      # Articles for a specific issue.
+      #
+      # @param volume [Integer]
+      # @param issue  [Integer]
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def articles(volume, issue, limit: 20, offset: 0)
+        client.get("daily-congressional-record/#{volume}/#{issue}/articles",
+                   { limit: limit, offset: offset })
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/hearing.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access hearing data from the Congress.gov API.
+    class Hearing < Base
+      # List hearings, optionally filtered by congress and chamber.
+      #
+      # @param congress [Integer]
+      # @param chamber  [String]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, chamber: nil, limit: 20, offset: 0)
+        params = { limit: limit, offset: offset }
+
+        if congress && chamber
+          client.get("hearing/#{congress}/#{chamber.downcase}", params)
+        elsif congress
+          client.get("hearing/#{congress}", params)
+        else
+          client.get('hearing', params)
+        end
+      end
+
+      # Fetch a specific hearing.
+      #
+      # @param congress      [Integer]
+      # @param chamber       [String]
+      # @param jacket_number [Integer]
+      # @return [CongressGov::Response]
+      def get(congress, chamber, jacket_number)
+        client.get("hearing/#{congress}/#{chamber.downcase}/#{jacket_number}")
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/house_communication.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access House communication data from the Congress.gov API.
+    class HouseCommunication < Base
+      # Valid communication type codes: ec (Executive), ml (Memorial), pm (Presidential), pt (Petition).
+      COMMUNICATION_TYPES = %w[ec ml pm pt].freeze
+
+      # List house communications.
+      #
+      # @param congress            [Integer] filter to a specific Congress
+      # @param communication_type  [String]  one of COMMUNICATION_TYPES
+      # @param limit               [Integer]
+      # @param offset              [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, communication_type: nil, limit: 20, offset: 0)
+        params = { limit: limit, offset: offset }
+
+        if congress && communication_type
+          validate_communication_type!(communication_type)
+          client.get("house-communication/#{congress}/#{communication_type.downcase}", params)
+        elsif congress
+          client.get("house-communication/#{congress}", params)
+        else
+          client.get('house-communication', params)
+        end
+      end
+
+      # Fetch a specific house communication.
+      #
+      # @param congress            [Integer]
+      # @param communication_type  [String]
+      # @param number              [Integer]
+      # @return [CongressGov::Response]
+      def get(congress, communication_type, number)
+        validate_communication_type!(communication_type)
+        client.get("house-communication/#{congress}/#{communication_type.downcase}/#{number}")
+      end
+
+      private
+
+      def validate_communication_type!(communication_type)
+        return if COMMUNICATION_TYPES.include?(communication_type.to_s.downcase)
+
+        raise ArgumentError,
+              "communication type must be one of: #{COMMUNICATION_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/house_requirement.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access House requirement data from the Congress.gov API.
+    class HouseRequirement < Base
+      # List house requirements.
+      #
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def list(limit: 20, offset: 0)
+        client.get('house-requirement', { limit: limit, offset: offset })
+      end
+
+      # Fetch a specific house requirement.
+      #
+      # @param number [Integer]
+      # @return [CongressGov::Response]
+      def get(number)
+        client.get("house-requirement/#{number}")
+      end
+
+      # Matching communications for a house requirement.
+      #
+      # @param number [Integer]
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def matching_communications(number, limit: 20, offset: 0)
+        client.get("house-requirement/#{number}/matching-communications",
+                   { limit: limit, offset: offset })
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/house_vote.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access House roll call vote data from the Congress.gov API.
+    class HouseVote < Base
+      # List all House roll call votes (no filters).
+      #
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @return [CongressGov::Response]
+      def list_all(limit: 20, offset: 0)
+        client.get('house-vote', { limit: limit, offset: offset })
+      end
+
+      # List House roll call votes for a specific Congress.
+      #
+      # @param congress [Integer] e.g. 119
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def list_by_congress(congress:, limit: 20, offset: 0)
+        client.get("house-vote/#{congress}", { limit: limit, offset: offset })
+      end
+
+      # List House roll call votes for a Congress and session.
+      #
+      # @param congress [Integer] e.g. 119
+      # @param session  [Integer] 1 or 2
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @param from_date [String] "YYYY-MM-DD"
+      # @param to_date   [String] "YYYY-MM-DD"
+      # @return [CongressGov::Response]
+      def list(congress:, session:, limit: 20, offset: 0,
+               from_date: nil, to_date: nil)
+        params = { limit: limit, offset: offset }
+        params[:startDate] = from_date if from_date
+        params[:endDate]   = to_date   if to_date
+        client.get("house-vote/#{congress}/#{session}", params)
+      end
+
+      # Fetch a single House roll call vote record.
+      #
+      # @param congress  [Integer]
+      # @param session   [Integer]
+      # @param roll_call [Integer]
+      # @return [CongressGov::Response]
+      def get(congress:, session:, roll_call:)
+        client.get("house-vote/#{congress}/#{session}/#{roll_call}")
+      end
+
+      # Fetch how each member voted on a specific roll call.
+      #
+      # @param congress  [Integer]
+      # @param session   [Integer]
+      # @param roll_call [Integer]
+      # @param limit     [Integer]
+      # @param offset    [Integer]
+      # @return [CongressGov::Response]
+      def members(congress:, session:, roll_call:, limit: 250, offset: 0)
+        client.get("house-vote/#{congress}/#{session}/#{roll_call}/members",
+                   { limit: limit, offset: offset })
+      end
+
+      # Convenience: return all member votes as a Hash keyed by bioguide ID.
+      #
+      # The members endpoint nests data under +houseRollCallVoteMemberVotes.results+.
+      # The bioguide field is +bioguideID+ (capital D).
+      #
+      # @param congress  [Integer]
+      # @param session   [Integer]
+      # @param roll_call [Integer]
+      # @return [Hash{String => String}] bioguide_id => voteCast
+      def member_votes_by_bioguide(congress:, session:, roll_call:)
+        result = {}
+        offset = 0
+        loop do
+          response = members(
+            congress: congress,
+            session: session,
+            roll_call: roll_call,
+            limit: 250,
+            offset: offset
+          )
+          member_list = extract_member_votes(response)
+          member_list.each do |member|
+            bioguide = member['bioguideID'] || member['bioguideId']
+            result[bioguide] = member['voteCast']
+          end
+          break unless response.has_next_page?
+
+          offset += 250
+        end
+        result
+      end
+
+      # Convenience: get the vote position for a single member on a roll call.
+      #
+      # @param congress    [Integer]
+      # @param session     [Integer]
+      # @param roll_call   [Integer]
+      # @param bioguide_id [String]
+      # @return [String, nil] "Aye", "Nay", "Present", "Not Voting", or nil
+      def position_for_member(congress:, session:, roll_call:, bioguide_id:)
+        member_votes_by_bioguide(
+          congress: congress, session: session, roll_call: roll_call
+        )[bioguide_id]
+      end
+
+      private
+
+      # Extract the member votes array from the nested response structure.
+      # The API nests member votes under +houseRollCallVoteMemberVotes.results+.
+      # Falls back to +Response#results+ for compatibility with stubbed tests.
+      #
+      # @param response [CongressGov::Response]
+      # @return [Array<Hash>]
+      def extract_member_votes(response)
+        nested = response.raw.dig('houseRollCallVoteMemberVotes', 'results')
+        return nested if nested.is_a?(Array)
+
+        response.results
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/law.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access law data from the Congress.gov API.
+    class Law < Base
+      # Valid law type codes: pub (public), priv (private).
+      LAW_TYPES = %w[pub priv].freeze
+
+      # List laws for a given congress.
+      #
+      # @param congress [Integer] e.g. 119
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def list(congress, limit: 20, offset: 0)
+        client.get("law/#{congress}", { limit: limit, offset: offset })
+      end
+
+      # List laws for a given congress filtered by type.
+      #
+      # @param congress [Integer]
+      # @param law_type [String] 'pub' or 'priv'
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def list_by_type(congress, law_type, limit: 20, offset: 0)
+        validate_law_type!(law_type)
+        client.get("law/#{congress}/#{law_type.downcase}", { limit: limit, offset: offset })
+      end
+
+      # Fetch a specific law.
+      #
+      # @param congress  [Integer]
+      # @param law_type  [String] 'pub' or 'priv'
+      # @param number    [Integer]
+      # @return [CongressGov::Response]
+      def get(congress, law_type, number)
+        validate_law_type!(law_type)
+        client.get("law/#{congress}/#{law_type.downcase}/#{number}")
+      end
+
+      private
+
+      def validate_law_type!(law_type)
+        return if LAW_TYPES.include?(law_type.to_s.downcase)
+
+        raise ArgumentError,
+              "law type must be one of: #{LAW_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/member.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access member data from the Congress.gov API.
+    class Member < Base
+      # Fetch the current member representing a congressional district.
+      #
+      # @param state    [String]  two-letter state abbreviation e.g. "VA", "OH"
+      # @param district [Integer, String] district number e.g. 8 or "08"
+      # @param congress [Integer] congress number e.g. 119 (default: current 119th)
+      # @param current  [Boolean] return only current members (default: true)
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def by_district(state:, district:, congress: 119, current: true, limit: 10, offset: 0)
+        district_str = district.to_s.rjust(2, '0')
+        params = {
+          currentMember: current,
+          limit: limit,
+          offset: offset
+        }
+        client.get("member/congress/#{congress}/#{state.upcase}/#{district_str}", params)
+      end
+
+      # Fetch a member's full profile by bioguide ID.
+      #
+      # @param bioguide_id [String] e.g. "B001292" (Don Beyer, VA-08)
+      # @return [CongressGov::Response]
+      def get(bioguide_id)
+        client.get("member/#{bioguide_id}")
+      end
+
+      # Get a member's sponsored legislation.
+      #
+      # @param bioguide_id [String]
+      # @param limit       [Integer] max 250
+      # @param offset      [Integer]
+      # @return [CongressGov::Response]
+      def sponsored_legislation(bioguide_id, limit: 20, offset: 0)
+        client.get("member/#{bioguide_id}/sponsored-legislation",
+                   { limit: limit, offset: offset })
+      end
+
+      # Get legislation a member has cosponsored.
+      #
+      # @param bioguide_id [String]
+      # @param limit       [Integer]
+      # @param offset      [Integer]
+      # @return [CongressGov::Response]
+      def cosponsored_legislation(bioguide_id, limit: 20, offset: 0)
+        client.get("member/#{bioguide_id}/cosponsored-legislation",
+                   { limit: limit, offset: offset })
+      end
+
+      # List all current members of Congress (House + Senate).
+      #
+      # @param current [Boolean] only current members (default: true)
+      # @param limit   [Integer]
+      # @param offset  [Integer]
+      # @return [CongressGov::Response]
+      def list(current: true, limit: 250, offset: 0)
+        client.get('member', { currentMember: current, limit: limit, offset: offset })
+      end
+
+      # List members from a specific state.
+      #
+      # @param state   [String]  two-letter state abbreviation e.g. "VA", "OH"
+      # @param current [Boolean] return only current members (default: true)
+      # @param limit   [Integer]
+      # @param offset  [Integer]
+      # @return [CongressGov::Response]
+      def by_state(state:, current: true, limit: 250, offset: 0)
+        params = {
+          currentMember: current,
+          limit: limit,
+          offset: offset
+        }
+        client.get("member/#{state.upcase}", params)
+      end
+
+      # List members from a specific state and district.
+      #
+      # Uses GET /v3/member/:stateCode/:district (distinct from
+      # #by_district which uses /member/congress/:congress/…).
+      #
+      # @param state    [String]  two-letter state abbreviation
+      # @param district [Integer, String] district number
+      # @param current  [Boolean] return only current members (default: true)
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def by_state_district(state:, district:, current: true, limit: 10, offset: 0)
+        district_str = district.to_s.rjust(2, '0')
+        params = {
+          currentMember: current,
+          limit: limit,
+          offset: offset
+        }
+        client.get("member/#{state.upcase}/#{district_str}", params)
+      end
+
+      # List members for a specific congress.
+      #
+      # @param congress [Integer] congress number e.g. 119
+      # @param current  [Boolean, nil] filter by current status (nil = omit param)
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def by_congress(congress:, current: nil, limit: 250, offset: 0)
+        params = {
+          limit: limit,
+          offset: offset
+        }
+        params[:currentMember] = current unless current.nil?
+        client.get("member/congress/#{congress}", params)
+      end
+
+      # Convenience: return all pages of current members, yielding each page.
+      #
+      # @yield [Array] results from each page
+      def all_current
+        offset = 0
+        limit  = 250
+        loop do
+          response = list(current: true, limit: limit, offset: offset)
+          yield response.results
+          break unless response.has_next_page?
+
+          offset += limit
+        end
+      end
+
+      # Convenience: returns the single current member for a district,
+      # or nil if none found.
+      #
+      # @param state    [String]
+      # @param district [Integer, String]
+      # @param congress [Integer] defaults to 119th
+      # @return [Hash, nil]
+      def current_for_district(state:, district:, congress: 119)
+        response = by_district(state: state, district: district,
+                               congress: congress, current: true, limit: 1)
+        members  = response.results
+        return nil if members.empty?
+
+        members.first
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/nomination.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access nomination data from the Congress.gov API.
+    class Nomination < Base
+      # List nominations, 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 ? "nomination/#{congress}" : 'nomination'
+        client.get(path, { limit: limit, offset: offset })
+      end
+
+      # Fetch a nomination's full detail record.
+      #
+      # @param congress [Integer] e.g. 119
+      # @param number   [Integer] nomination number
+      # @return [CongressGov::Response]
+      def get(congress, number)
+        client.get("nomination/#{congress}/#{number}")
+      end
+
+      # Fetch a specific ordinal for a nomination.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param ordinal  [Integer]
+      # @return [CongressGov::Response]
+      def get_ordinal(congress, number, ordinal)
+        client.get("nomination/#{congress}/#{number}/#{ordinal}")
+      end
+
+      # Actions taken on a nomination.
+      #
+      # @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("nomination/#{congress}/#{number}/actions",
+                   { limit: limit, offset: offset })
+      end
+
+      # Committees associated with a nomination.
+      #
+      # @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("nomination/#{congress}/#{number}/committees",
+                   { limit: limit, offset: offset })
+      end
+
+      # Hearings for a nomination.
+      #
+      # @param congress [Integer]
+      # @param number   [Integer]
+      # @param limit    [Integer]
+      # @param offset   [Integer]
+      # @return [CongressGov::Response]
+      def hearings(congress, number, limit: 20, offset: 0)
+        client.get("nomination/#{congress}/#{number}/hearings",
+                   { limit: limit, offset: offset })
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/senate_communication.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access Senate communication data from the Congress.gov API.
+    class SenateCommunication < Base
+      # Valid communication type codes: ec (Executive), ml (Memorial), pm (Presidential), pt (Petition).
+      COMMUNICATION_TYPES = %w[ec ml pm pt].freeze
+
+      # List senate communications.
+      #
+      # @param congress            [Integer] filter to a specific Congress
+      # @param communication_type  [String]  one of COMMUNICATION_TYPES
+      # @param limit               [Integer]
+      # @param offset              [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, communication_type: nil, limit: 20, offset: 0)
+        params = { limit: limit, offset: offset }
+
+        if congress && communication_type
+          validate_communication_type!(communication_type)
+          client.get("senate-communication/#{congress}/#{communication_type.downcase}", params)
+        elsif congress
+          client.get("senate-communication/#{congress}", params)
+        else
+          client.get('senate-communication', params)
+        end
+      end
+
+      # Fetch a specific senate communication.
+      #
+      # @param congress            [Integer]
+      # @param communication_type  [String]
+      # @param number              [Integer]
+      # @return [CongressGov::Response]
+      def get(congress, communication_type, number)
+        validate_communication_type!(communication_type)
+        client.get("senate-communication/#{congress}/#{communication_type.downcase}/#{number}")
+      end
+
+      private
+
+      def validate_communication_type!(communication_type)
+        return if COMMUNICATION_TYPES.include?(communication_type.to_s.downcase)
+
+        raise ArgumentError,
+              "communication type must be one of: #{COMMUNICATION_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/congress_gov/resources/summary.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CongressGov
+  module Resources
+    # Access bill summary data from the Congress.gov API.
+    class Summary < Base
+      # List bill summaries with optional congress and bill type filters.
+      #
+      # @param congress  [Integer, nil] filter to a specific congress
+      # @param bill_type [String, nil]  filter to a bill type (e.g. 'hr', 's')
+      # @param limit     [Integer]
+      # @param offset    [Integer]
+      # @return [CongressGov::Response]
+      def list(congress: nil, bill_type: nil, limit: 20, offset: 0)
+        params = { limit: limit, offset: offset }
+
+        if congress && bill_type
+          client.get("summaries/#{congress}/#{bill_type.downcase}", params)
+        elsif congress
+          client.get("summaries/#{congress}", params)
+        else
+          client.get('summaries', params)
+        end
+      end
+    end
+  end
+end