open_fec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8dd8d770d0957b0f17a29d0e4197501679ed4a7dea95790483bcdf4dbaa6a156
+  data.tar.gz: 0560f6316507f7cecfb1e307275010299f3a548810b989b53d628dfb789ef971
+SHA512:
+  metadata.gz: 806ebc183c698c3db5b814b7cfd537afa003dfae26ab853a3b4826638d31734dad89fac780a265cacd860aeadbbb8683eb90b937ce7e7bc8eaf563dfab4d71f4
+  data.tar.gz: 10df7ef81f0c814c29aff29fe9e574b3797d6fd9e99229de061abc5330aa6db8bafd78c2c0452b9a7c2ae65c56ad00e44d8baf5348abb36903222c6e5370b61f

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-03-25
+
+### Added
+- Initial release
+- Candidates resource: search, find, committees
+- CandidateTotals resource: financial summaries per cycle
+- Committees resource: search, find
+- Contributions resource: itemized Schedule A (seek-paginated)
+- ContributionAggregates resource: by_employer, by_occupation, by_size, by_state
+- Disbursements resource: itemized Schedule B (seek-paginated)
+- Dual pagination support (offset-based and seek/cursor-based)
+- Thread-safe configuration with Mutex
+- Faraday 2.0 with retry middleware (429, 5xx)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jack Killilea
+
+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,104 @@
+# OpenFec
+
+Ruby client for the [Federal Election Commission (FEC) API](https://api.open.fec.gov/developers/).
+
+Part of the [govapi-rb](https://github.com/govapi-rb) collection of Ruby clients for US government APIs.
+
+## Installation
+
+```ruby
+gem 'open_fec'
+```
+
+## Configuration
+
+Get a free API key at [api.data.gov/signup](https://api.data.gov/signup/).
+
+```ruby
+# Via environment variable (recommended)
+ENV['OPEN_FEC_API_KEY'] = 'your-api-key'
+
+# Or via configuration block
+OpenFec.configure do |c|
+  c.api_key = 'your-api-key'
+end
+```
+
+## Usage
+
+### Candidates
+
+```ruby
+# Search for candidates
+results = OpenFec.candidates.search(name: 'Pelosi', state: 'CA')
+results.each { |c| puts "#{c['name']} (#{c['party']})" }
+
+# Find a specific candidate
+candidate = OpenFec.candidates.find('H8CA05035')
+candidate.results.first['name'] # => "PELOSI, NANCY"
+
+# Get a candidate's committees
+committees = OpenFec.candidates.committees('H8CA05035')
+```
+
+### Campaign Finance Totals
+
+```ruby
+# Financial totals for a candidate
+totals = OpenFec.candidate_totals.list('H8CA05035')
+totals.each do |t|
+  puts "Cycle #{t['cycle']}: raised #{t['receipts']}, spent #{t['disbursements']}"
+end
+
+# For a specific cycle
+totals = OpenFec.candidate_totals.for_cycle('H8CA05035', 2024)
+```
+
+### Contributions by Employer
+
+```ruby
+# Top employer donors to a committee
+employers = OpenFec.contribution_aggregates.by_employer(
+  committee_id: 'C00213512',
+  cycle: 2024,
+  sort: '-total',
+  per_page: 10
+)
+employers.each { |e| puts "#{e['employer']}: $#{e['total']}" }
+```
+
+### PAC Contributions
+
+```ruby
+# PAC contributions to a committee
+pacs = OpenFec.contributions.from_pacs(committee_id: 'C00213512', cycle: 2024)
+pacs.each { |c| puts "#{c['contributor_name']}: $#{c['contribution_receipt_amount']}" }
+```
+
+### Pagination
+
+Most endpoints use offset-based pagination:
+
+```ruby
+OpenFec.candidates.each_page(state: 'VA') do |page|
+  page.results.each { |c| puts c['name'] }
+end
+```
+
+Itemized transaction endpoints (Schedule A, Schedule B) use seek/cursor pagination:
+
+```ruby
+OpenFec.contributions.each_page(committee_id: 'C00213512') do |page|
+  page.results.each { |c| puts c['contributor_name'] }
+end
+```
+
+## Rate Limits
+
+- `DEMO_KEY`: 30 requests/hour
+- Registered key: 1,000 requests/hour
+- Contact `APIinfo@fec.gov` for higher limits
+
+## License
+
+MIT

data/lib/open_fec/client.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+
+module OpenFec
+  # HTTP client for the FEC API. Handles authentication, retries, and pagination.
+  #
+  # @example Direct usage
+  #   client = OpenFec.client
+  #   response = client.get('candidates/search/', name: 'Pelosi')
+  class Client
+    # @return [OpenFec::Configuration]
+    attr_reader :config
+
+    # @param config [OpenFec::Configuration]
+    # @raise [ConfigurationError] if api_key is missing
+    def initialize(config = OpenFec.configuration)
+      @config = config
+      config.validate!
+    end
+
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= build_connection
+    end
+
+    # Make a GET request to the FEC API.
+    #
+    # @param path [String] API endpoint path (e.g. "candidates/search/")
+    # @param params [Hash] query parameters
+    # @return [OpenFec::Response]
+    # @raise [ClientError, ServerError, ConnectionError]
+    def get(path, params = {})
+      response = connection.get(path, with_api_key(compact_params(params)))
+      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
+
+    # Iterate through offset-paginated results, yielding each page.
+    # Used by most FEC API endpoints.
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @yield [OpenFec::Response] each page of results
+    def paginate(path, params = {})
+      page = 1
+      iterations = 0
+      loop do
+        iterations += 1
+        response = get(path, params.merge(page: page, per_page: config.per_page))
+        yield response
+        break if response.empty?
+        break unless response.next_page?
+
+        page = response.next_page_number
+        break if page.nil?
+        break if iterations >= config.max_pages
+      end
+    end
+
+    # Iterate through seek/cursor-paginated results, yielding each page.
+    # Used by itemized transaction endpoints (Schedule A, Schedule B).
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @yield [OpenFec::Response] each page of results
+    def paginate_seek(path, params = {})
+      iterations = 0
+      cursor_params = {}
+      loop do
+        iterations += 1
+        response = get(path, params.merge(per_page: config.per_page, **cursor_params))
+        yield response
+        break if response.empty?
+        break unless response.next_page?
+
+        cursor_params = response.next_page_params || {}
+        break if cursor_params.empty?
+        break if iterations >= config.max_pages
+      end
+    end
+
+    # Fetch all results from an offset-paginated endpoint.
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @return [Array<Hash>] all result records
+    def all(path, params = {})
+      records = []
+      paginate(path, params) { |response| records.concat(response.results) }
+      records
+    end
+
+    # Fetch all results from a seek-paginated endpoint.
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @return [Array<Hash>] all result records
+    def all_seek(path, params = {})
+      records = []
+      paginate_seek(path, params) { |response| records.concat(response.results) }
+      records
+    end
+
+    # Resource accessors
+
+    # @return [OpenFec::Resources::Candidates]
+    def candidates
+      @candidates ||= Resources::Candidates.new(self)
+    end
+
+    # @return [OpenFec::Resources::CandidateTotals]
+    def candidate_totals
+      @candidate_totals ||= Resources::CandidateTotals.new(self)
+    end
+
+    # @return [OpenFec::Resources::Committees]
+    def committees
+      @committees ||= Resources::Committees.new(self)
+    end
+
+    # @return [OpenFec::Resources::Contributions]
+    def contributions
+      @contributions ||= Resources::Contributions.new(self)
+    end
+
+    # @return [OpenFec::Resources::ContributionAggregates]
+    def contribution_aggregates
+      @contribution_aggregates ||= Resources::ContributionAggregates.new(self)
+    end
+
+    # @return [OpenFec::Resources::Disbursements]
+    def disbursements
+      @disbursements ||= Resources::Disbursements.new(self)
+    end
+
+    # @return [OpenFec::Resources::Elections]
+    def elections
+      @elections ||= Resources::Elections.new(self)
+    end
+
+    # @return [OpenFec::Resources::IndependentExpenditures]
+    def independent_expenditures
+      @independent_expenditures ||= Resources::IndependentExpenditures.new(self)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} base_url=#{config.base_url.inspect} timeout=#{config.timeout}>"
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: config.base_url) do |f|
+        f.options.timeout      = config.timeout
+        f.options.open_timeout = 10
+
+        f.headers['User-Agent'] = "open_fec-rb/#{OpenFec::VERSION}"
+
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+
+        f.request :retry,
+                  max: config.retries,
+                  interval: 0.5,
+                  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
+
+    def with_api_key(params)
+      params.merge('api_key' => config.api_key)
+    end
+
+    def compact_params(params)
+      params.compact.transform_keys(&:to_s)
+    end
+
+    def handle_response(response) # rubocop:disable Metrics/MethodLength
+      case response.status
+      when 200..299
+        Response.new(response.body, response.status)
+      when 400
+        raise BadRequestError.new(status: response.status, body: response.body)
+      when 401
+        raise UnauthorizedError.new(status: response.status, body: response.body)
+      when 403
+        raise ForbiddenError.new(status: response.status, body: response.body)
+      when 404
+        raise NotFoundError.new(status: response.status, body: response.body)
+      when 422
+        raise UnprocessableEntityError.new(status: response.status, body: response.body)
+      when 429
+        raise RateLimitError.new(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/open_fec/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenFec
+  # Configuration for the OpenFEC API client.
+  #
+  # @example
+  #   OpenFec.configure do |c|
+  #     c.api_key  = 'your-api-key'
+  #     c.per_page = 50
+  #     c.timeout  = 60
+  #   end
+  class Configuration
+    DEFAULT_BASE_URL  = 'https://api.open.fec.gov/v1/'
+    DEFAULT_TIMEOUT   = 30
+    DEFAULT_RETRIES   = 3
+    DEFAULT_PER_PAGE  = 20
+    DEFAULT_MAX_PAGES = 100
+
+    # @return [String] base URL for the FEC API
+    attr_accessor :base_url
+    # @return [Integer] HTTP timeout in seconds
+    attr_accessor :timeout
+    # @return [Integer] number of retries on 429/5xx
+    attr_accessor :retries
+    # @return [Logger, nil] optional logger for HTTP requests
+    attr_accessor :logger
+    # @return [Symbol] Faraday adapter (default: system default)
+    attr_accessor :adapter
+    # @return [String, nil] FEC API key (get one free at https://api.data.gov/signup)
+    attr_accessor :api_key
+    # @return [Integer] default results per page
+    attr_accessor :per_page
+    # @return [Integer] max pages to fetch during pagination
+    attr_accessor :max_pages
+
+    def initialize
+      @base_url  = DEFAULT_BASE_URL
+      @timeout   = DEFAULT_TIMEOUT
+      @retries   = DEFAULT_RETRIES
+      @per_page  = DEFAULT_PER_PAGE
+      @max_pages = DEFAULT_MAX_PAGES
+      @logger    = nil
+      @adapter   = Faraday.default_adapter
+      @api_key   = ENV.fetch('OPEN_FEC_API_KEY', nil)
+    end
+
+    # Validates that required configuration is present.
+    #
+    # @raise [ConfigurationError] if api_key is missing
+    # @return [void]
+    def validate!
+      return unless api_key.nil? || api_key.empty?
+
+      raise ConfigurationError,
+            'api_key is required (get one free at https://api.data.gov/signup)'
+    end
+
+    # @return [Hash] all configuration values
+    def to_h
+      {
+        base_url: base_url,
+        timeout: timeout,
+        retries: retries,
+        per_page: per_page,
+        max_pages: max_pages,
+        logger: logger,
+        adapter: adapter,
+        api_key: api_key
+      }
+    end
+
+    def inspect
+      "#<#{self.class} base_url=#{base_url.inspect} timeout=#{timeout} retries=#{retries}>"
+    end
+  end
+end

data/lib/open_fec/error.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module OpenFec
+  # Base error class for all OpenFec errors.
+  class Error < StandardError; end
+
+  # Raised for 4xx HTTP responses.
+  class ClientError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+    # @return [Hash, String, nil] response body
+    attr_reader :body
+
+    # @param message [String, nil]
+    # @param status [Integer, nil]
+    # @param body [Hash, String, nil]
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body   = body
+      super(message || "HTTP #{status}: #{body}")
+    end
+  end
+
+  # Raised on 400 Bad Request.
+  class BadRequestError < ClientError; end
+  # Raised on 401 Unauthorized (invalid or missing API key).
+  class UnauthorizedError < ClientError; end
+  # Raised on 403 Forbidden.
+  class ForbiddenError < ClientError; end
+  # Raised on 404 Not Found.
+  class NotFoundError < ClientError; end
+  # Raised on 429 Too Many Requests (rate limit exceeded).
+  class RateLimitError < ClientError; end
+  # Raised on 422 Unprocessable Entity.
+  class UnprocessableEntityError < ClientError; end
+
+  # Raised for 5xx HTTP responses.
+  class ServerError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+    # @return [Hash, String, nil] response body
+    attr_reader :body
+
+    # @param message [String, nil]
+    # @param status [Integer, nil]
+    # @param body [Hash, String, nil]
+    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 configuration is invalid (e.g. missing API key).
+  class ConfigurationError < Error; end
+end

data/lib/open_fec/resources/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenFec
+  # Resource classes for interacting with FEC API endpoints.
+  module Resources
+    # Base class for all FEC API resource classes.
+    class Base
+      # @param client [OpenFec::Client]
+      def initialize(client = OpenFec.client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      # @param path [String]
+      # @param params [Hash]
+      # @return [OpenFec::Response]
+      def get(path, params = {})
+        client.get(path, params)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/candidate_totals.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Campaign finance totals for candidates across election cycles.
+    #
+    # @example Get all cycles for a candidate
+    #   OpenFec.candidate_totals.list('H8CA05035')
+    #
+    # @example Get totals for a specific cycle
+    #   OpenFec.candidate_totals.for_cycle('H8CA05035', 2024)
+    class CandidateTotals < Base
+      # Financial totals for a candidate across election cycles.
+      # Returns receipts, disbursements, cash_on_hand, individual_contributions,
+      # other_political_committee_contributions (PAC money), etc.
+      #
+      # @param candidate_id [String] FEC candidate ID (e.g. "H8CA05035")
+      # @param params [Hash] optional filters (:cycle, :election_full, etc.)
+      # @return [OpenFec::Response]
+      def list(candidate_id, **params)
+        get("candidate/#{candidate_id}/totals/", params)
+      end
+
+      # Fetch totals for a specific election cycle.
+      #
+      # @param candidate_id [String] FEC candidate ID
+      # @param cycle [Integer] election cycle year (e.g. 2024)
+      # @return [OpenFec::Response]
+      def for_cycle(candidate_id, cycle)
+        list(candidate_id, cycle: cycle)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/candidates.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Search and retrieve FEC candidate records.
+    #
+    # @example Search by name
+    #   OpenFec.candidates.search(name: 'Pelosi', state: 'CA')
+    #
+    # @example Get a candidate with their principal committees
+    #   candidate = OpenFec.candidates.find('H8CA05035')
+    #   committee_id = candidate.results.first.dig('principal_committees', 0, 'committee_id')
+    class Candidates < Base
+      # Search for candidates by name, state, district, party, etc.
+      #
+      # @param params [Hash] search filters (:name, :state, :district, :party, :office, etc.)
+      # @return [OpenFec::Response]
+      def search(**params)
+        get('candidates/search/', params)
+      end
+
+      # Fetch a single candidate by FEC candidate ID.
+      # Includes principal_committees in the response.
+      #
+      # @param candidate_id [String] FEC candidate ID (e.g. "H8CA05035")
+      # @return [OpenFec::Response]
+      def find(candidate_id)
+        get("candidate/#{candidate_id}/")
+      end
+
+      # List committees associated with a candidate.
+      #
+      # @param candidate_id [String] FEC candidate ID
+      # @param params [Hash] optional filters (:designation, :organization_type, etc.)
+      # @return [OpenFec::Response]
+      def committees(candidate_id, **params)
+        get("candidate/#{candidate_id}/committees/", params)
+      end
+
+      # Paginate through candidate search results (offset-based).
+      #
+      # @param params [Hash] search filters
+      # @yield [OpenFec::Response] each page of results
+      def each_page(**params, &)
+        client.paginate('candidates/search/', params, &)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/committees.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Search and retrieve FEC committee records (PACs, campaign committees, etc.).
+    #
+    # @example Find committees for a candidate
+    #   OpenFec.committees.search(candidate_id: 'H8CA05035')
+    #
+    # @example Get a specific committee
+    #   OpenFec.committees.find('C00213512')
+    class Committees < Base
+      # Search committees by name, candidate_id, state, committee_type, etc.
+      #
+      # @param params [Hash] search filters
+      # @return [OpenFec::Response]
+      def search(**params)
+        get('committees/', params)
+      end
+
+      # Fetch a single committee by FEC committee ID.
+      #
+      # @param committee_id [String] FEC committee ID (e.g. "C00213512")
+      # @return [OpenFec::Response]
+      def find(committee_id)
+        get("committee/#{committee_id}/")
+      end
+
+      # Paginate through committee search results (offset-based).
+      #
+      # @param params [Hash] search filters
+      # @yield [OpenFec::Response] each page of results
+      def each_page(**params, &)
+        client.paginate('committees/', params, &)
+      end
+    end
+  end
+end