open_fec 0.1.0

data/lib/open_fec/resources/contribution_aggregates.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Aggregated contribution data (by employer, occupation, size, state, zip).
+    # All endpoints use offset-based pagination.
+    #
+    # @example Top employer donors to a committee
+    #   OpenFec.contribution_aggregates.by_employer(
+    #     committee_id: 'C00213512', cycle: 2024, sort: '-total', per_page: 10
+    #   )
+    #
+    # @example Donations by zip code
+    #   OpenFec.contribution_aggregates.by_zip(
+    #     committee_id: 'C00555888', cycle: 2024, sort: '-total', per_page: 10
+    #   )
+    class ContributionAggregates < Base
+      # Contributions aggregated by employer.
+      # Returns: employer, total, count, cycle.
+      #
+      # @param committee_id [String] FEC committee ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params (:sort, :per_page, etc.)
+      # @return [OpenFec::Response]
+      def by_employer(committee_id:, cycle:, **params)
+        get('schedules/schedule_a/by_employer/',
+            params.merge(committee_id: committee_id, cycle: cycle))
+      end
+
+      # Contributions aggregated by occupation.
+      #
+      # @param committee_id [String] FEC committee ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params
+      # @return [OpenFec::Response]
+      def by_occupation(committee_id:, cycle:, **params)
+        get('schedules/schedule_a/by_occupation/',
+            params.merge(committee_id: committee_id, cycle: cycle))
+      end
+
+      # Contributions aggregated by size (small/medium/large dollar).
+      #
+      # @param candidate_id [String] FEC candidate ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params
+      # @return [OpenFec::Response]
+      def by_size(candidate_id:, cycle:, **params)
+        get('schedules/schedule_a/by_size/by_candidate/',
+            params.merge(candidate_id: candidate_id, cycle: cycle))
+      end
+
+      # Contributions aggregated by state.
+      #
+      # @param candidate_id [String] FEC candidate ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params
+      # @return [OpenFec::Response]
+      def by_state(candidate_id:, cycle:, **params)
+        get('schedules/schedule_a/by_state/by_candidate/',
+            params.merge(candidate_id: candidate_id, cycle: cycle))
+      end
+
+      # Contributions aggregated by zip code.
+      # Returns: zip, total, count, cycle.
+      #
+      # @param committee_id [String] FEC committee ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params (:sort, :per_page, etc.)
+      # @return [OpenFec::Response]
+      def by_zip(committee_id:, cycle:, **params)
+        get('schedules/schedule_a/by_zip/',
+            params.merge(committee_id: committee_id, cycle: cycle))
+      end
+
+      # Paginate through employer contribution aggregates.
+      #
+      # @param committee_id [String] FEC committee ID
+      # @param cycle [Integer] election cycle year
+      # @param params [Hash] additional params
+      # @yield [OpenFec::Response] each page of results
+      def each_employer_page(committee_id:, cycle:, **params, &)
+        client.paginate('schedules/schedule_a/by_employer/',
+                        params.merge(committee_id: committee_id, cycle: cycle), &)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/contributions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Itemized contribution records (Schedule A).
+    # Uses seek/cursor-based pagination (not offset-based).
+    #
+    # @example Get PAC contributions to a committee
+    #   OpenFec.contributions.from_pacs(committee_id: 'C00213512', cycle: 2024)
+    #
+    # @example Paginate all contributions
+    #   OpenFec.contributions.each_page(committee_id: 'C00213512') do |page|
+    #     page.each { |c| puts c['contributor_name'] }
+    #   end
+    class Contributions < Base
+      # List itemized contributions (Schedule A).
+      #
+      # @param params [Hash] filters (:committee_id, :contributor_name,
+      #   :entity_type, :two_year_transaction_period, :sort, etc.)
+      # @return [OpenFec::Response]
+      def list(**params)
+        get('schedules/schedule_a/', params)
+      end
+
+      # PAC contributions to a committee (entity_type=COM).
+      #
+      # @param committee_id [String] FEC committee ID
+      # @param cycle [Integer, nil] election cycle year
+      # @param params [Hash] additional filters
+      # @return [OpenFec::Response]
+      def from_pacs(committee_id:, cycle: nil, **params)
+        merged = params.merge(committee_id: committee_id, entity_type: 'COM')
+        merged[:two_year_transaction_period] = cycle if cycle
+        get('schedules/schedule_a/', merged)
+      end
+
+      # Paginate through itemized contributions (seek/cursor-based).
+      #
+      # @param params [Hash] filters
+      # @yield [OpenFec::Response] each page of results
+      def each_page(**params, &)
+        client.paginate_seek('schedules/schedule_a/', params, &)
+      end
+
+      # Fetch all itemized contributions (seek-based). Use with caution on
+      # large result sets.
+      #
+      # @param params [Hash] filters
+      # @return [Array<Hash>] all contribution records
+      def all_contributions(**params)
+        client.all_seek('schedules/schedule_a/', params)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/disbursements.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Itemized disbursement records (Schedule B).
+    # Uses seek/cursor-based pagination (not offset-based).
+    #
+    # @example List disbursements for a committee
+    #   OpenFec.disbursements.list(committee_id: 'C00213512')
+    class Disbursements < Base
+      # List itemized disbursements (Schedule B).
+      #
+      # @param params [Hash] filters (:committee_id, :recipient_name,
+      #   :two_year_transaction_period, :sort, etc.)
+      # @return [OpenFec::Response]
+      def list(**params)
+        get('schedules/schedule_b/', params)
+      end
+
+      # Paginate through disbursements (seek/cursor-based).
+      #
+      # @param params [Hash] filters
+      # @yield [OpenFec::Response] each page of results
+      def each_page(**params, &)
+        client.paginate_seek('schedules/schedule_b/', params, &)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/elections.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Election results and candidate comparisons for a specific race.
+    # Shows all candidates who ran in a district with financial totals side by side.
+    #
+    # @example Get all candidates who ran for VA-08 in 2024
+    #   OpenFec.elections.list(state: 'VA', district: '08', cycle: 2024, office: 'house')
+    #
+    # @example Election summary for a race
+    #   OpenFec.elections.summary(cycle: 2024, office: 'house', state: 'VA', district: '08')
+    class Elections < Base
+      # List all candidates in a specific election with financial totals.
+      # Returns candidate_name, party, total_receipts, total_disbursements,
+      # cash_on_hand_end_period, etc.
+      #
+      # @param params [Hash] filters (:state, :district, :cycle, :office — "house" or "senate")
+      # @return [OpenFec::Response]
+      def list(**params)
+        get('elections/', params)
+      end
+
+      # Search for elections by state, office, and cycle.
+      #
+      # @param params [Hash] filters (:state, :office, :cycle, :district, :zip)
+      # @return [OpenFec::Response]
+      def search(**params)
+        get('elections/search/', params)
+      end
+
+      # Election summary with aggregate spending data.
+      #
+      # @param params [Hash] filters (:cycle, :office, :state, :district, :election_full)
+      # @return [OpenFec::Response]
+      def summary(**params)
+        get('elections/summary/', params)
+      end
+    end
+  end
+end

data/lib/open_fec/resources/independent_expenditures.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenFec
+  module Resources
+    # Independent expenditures (Schedule E) — Super PAC and outside group
+    # spending for or against candidates.
+    #
+    # @example Super PAC spending for/against a candidate
+    #   OpenFec.independent_expenditures.by_candidate(candidate_id: 'H4VA08224', cycle: 2024)
+    #
+    # @example Totals by candidate
+    #   OpenFec.independent_expenditures.totals_by_candidate(candidate_id: 'H4VA08224', cycle: 2024)
+    class IndependentExpenditures < Base
+      # List itemized independent expenditures (Schedule E).
+      # Uses seek/cursor-based pagination.
+      #
+      # @param params [Hash] filters (:committee_id, :candidate_id, :cycle,
+      #   :support_oppose_indicator — "S" for support, "O" for oppose, etc.)
+      # @return [OpenFec::Response]
+      def list(**params)
+        get('schedules/schedule_e/', params)
+      end
+
+      # Independent expenditures aggregated by candidate.
+      # Shows committee_name, support/oppose indicator, total amount.
+      #
+      # @param params [Hash] filters (:candidate_id, :cycle, :office, :state, :district)
+      # @return [OpenFec::Response]
+      def by_candidate(**params)
+        get('schedules/schedule_e/by_candidate/', params)
+      end
+
+      # Totals of independent expenditures by candidate.
+      #
+      # @param params [Hash] filters (:candidate_id, :cycle, :election_full)
+      # @return [OpenFec::Response]
+      def totals_by_candidate(**params)
+        get('schedules/schedule_e/totals/by_candidate/', params)
+      end
+
+      # Paginate through itemized independent expenditures (seek-based).
+      #
+      # @param params [Hash] filters
+      # @yield [OpenFec::Response] each page of results
+      def each_page(**params, &)
+        client.paginate_seek('schedules/schedule_e/', params, &)
+      end
+    end
+  end
+end

data/lib/open_fec/response.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module OpenFec
+  # Wraps FEC API JSON responses with pagination metadata and Enumerable access.
+  #
+  # The FEC API uses two pagination models:
+  # - **Offset-based** (most endpoints): uses `page`/`pages` counters
+  # - **Seek/cursor-based** (itemized transactions): uses `last_indexes` cursors
+  #
+  # This class auto-detects which model is in use and exposes a unified
+  # {#next_page_params} method for both.
+  #
+  # @example Iterating results
+  #   response = OpenFec.candidates.search(name: 'Pelosi')
+  #   response.each { |candidate| puts candidate['name'] }
+  #
+  # @example Checking pagination
+  #   response.next_page?       # => true
+  #   response.next_page_params # => { page: 2 } or { last_index: '456', ... }
+  class Response
+    include Enumerable
+
+    # @return [Hash, Array] raw parsed JSON body
+    attr_reader :raw
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @param body [Hash, Array] parsed JSON response body
+    # @param status [Integer] HTTP status code
+    def initialize(body, status)
+      @raw    = body
+      @status = status
+    end
+
+    # Yields each result record.
+    # @yield [Hash] individual result record
+    def each(&)
+      results.each(&)
+    end
+
+    # Returns the results array from the response.
+    # @return [Array<Hash>]
+    def results
+      return raw if raw.is_a?(Array)
+      return [] unless raw.is_a?(Hash)
+
+      raw['results'] || []
+    end
+
+    # @return [Integer] number of results in this page
+    def size
+      results.size
+    end
+    alias length size
+
+    # @return [Boolean] true if no results in this page
+    def empty?
+      results.empty?
+    end
+
+    # --- Pagination metadata ---
+
+    # @return [Hash] raw pagination metadata from the API
+    def pagination
+      return {} unless raw.is_a?(Hash)
+
+      raw['pagination'] || {}
+    end
+
+    # @return [Integer, nil] total number of matching records across all pages
+    def total_count
+      pagination['count']
+    end
+
+    # @return [Integer, nil] total number of pages (offset-based only)
+    def total_pages
+      pagination['pages']
+    end
+
+    # @return [Integer, nil] current page number (offset-based only)
+    def current_page
+      pagination['page']
+    end
+
+    # @return [Integer, nil] results per page
+    def per_page
+      pagination['per_page']
+    end
+
+    # Whether there are more pages of results to fetch.
+    # Works for both offset-based and seek-based pagination.
+    #
+    # @return [Boolean]
+    def next_page?
+      return seek_next_page? if seek_paginated?
+
+      page = current_page
+      pages = total_pages
+      return false if page.nil? || pages.nil?
+
+      page < pages
+    end
+
+    # @return [Integer, nil] the next page number (offset-based only)
+    def next_page_number
+      return nil unless next_page? && !seek_paginated?
+
+      current_page + 1
+    end
+
+    # Whether this response uses seek/cursor-based pagination.
+    # True for itemized transaction endpoints (Schedule A, Schedule B).
+    #
+    # @return [Boolean]
+    def seek_paginated?
+      pagination.key?('last_indexes')
+    end
+
+    # @return [Hash] cursor keys for seek-based pagination
+    def last_indexes
+      pagination['last_indexes'] || {}
+    end
+
+    # Returns the query params to fetch the next page of results.
+    # For offset-based: `{ page: N }`.
+    # For seek-based: `{ last_index: "...", last_<sort_field>: "..." }`.
+    #
+    # @return [Hash, nil] params for next page, or nil if no more pages
+    def next_page_params
+      return nil unless next_page?
+
+      if seek_paginated?
+        last_indexes.transform_keys(&:to_sym)
+      else
+        { page: next_page_number }
+      end
+    end
+
+    # --- Direct access ---
+
+    # Access a top-level key from the raw response.
+    # @param key [String]
+    # @return [Object, nil]
+    def [](key)
+      return nil unless raw.is_a?(Hash)
+
+      raw[key]
+    end
+
+    # Dig into nested keys in the raw response.
+    # @param keys [Array<String>]
+    # @return [Object, nil]
+    def dig(*keys)
+      return nil unless raw.is_a?(Hash)
+
+      raw.dig(*keys)
+    end
+
+    # @return [Hash]
+    def to_h
+      raw.is_a?(Hash) ? raw : { 'results' => raw }
+    end
+
+    # @return [String] JSON representation
+    def to_json(*)
+      to_h.to_json
+    end
+
+    # @return [Boolean] true if HTTP status is 2xx
+    def success?
+      status >= 200 && status < 300
+    end
+
+    def inspect
+      "#<#{self.class} status=#{status} size=#{size} total_count=#{total_count.inspect} next_page?=#{next_page?}>"
+    end
+
+    private
+
+    def seek_next_page?
+      !last_indexes.empty? && !results.empty?
+    end
+  end
+end

data/lib/open_fec/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenFec
+  VERSION = '0.1.0'
+end

data/lib/open_fec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'open_fec/version'
+require 'open_fec/configuration'
+require 'open_fec/error'
+require 'open_fec/response'
+require 'open_fec/client'
+require 'open_fec/resources/base'
+require 'open_fec/resources/candidates'
+require 'open_fec/resources/candidate_totals'
+require 'open_fec/resources/committees'
+require 'open_fec/resources/contributions'
+require 'open_fec/resources/contribution_aggregates'
+require 'open_fec/resources/disbursements'
+require 'open_fec/resources/elections'
+require 'open_fec/resources/independent_expenditures'
+
+# Ruby client for the Federal Election Commission (FEC) API.
+# @see https://api.open.fec.gov/developers/
+#
+# @example Basic usage
+#   OpenFec.configure { |c| c.api_key = 'your-api-key' }
+#   results = OpenFec.candidates.search(name: 'Pelosi')
+#   totals  = OpenFec.candidate_totals.for_cycle('H8CA05035', 2024)
+module OpenFec
+  # Mutex for thread-safe initialization of configuration and client.
+  @mutex = Mutex.new
+
+  class << self
+    # Returns the current configuration instance.
+    # Thread-safe via Mutex.
+    #
+    # @return [OpenFec::Configuration]
+    def configuration
+      @mutex.synchronize { @configuration ||= Configuration.new }
+    end
+
+    # Yields the configuration instance for modification.
+    #
+    # @yieldparam config [OpenFec::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 [OpenFec::Client]
+    def client
+      @mutex.synchronize { @client ||= Client.new(@configuration || Configuration.new) }
+    end
+
+    # Resource shorthand accessors
+
+    # @return [OpenFec::Resources::Candidates]
+    def candidates
+      Resources::Candidates.new(client)
+    end
+
+    # @return [OpenFec::Resources::CandidateTotals]
+    def candidate_totals
+      Resources::CandidateTotals.new(client)
+    end
+
+    # @return [OpenFec::Resources::Committees]
+    def committees
+      Resources::Committees.new(client)
+    end
+
+    # @return [OpenFec::Resources::Contributions]
+    def contributions
+      Resources::Contributions.new(client)
+    end
+
+    # @return [OpenFec::Resources::ContributionAggregates]
+    def contribution_aggregates
+      Resources::ContributionAggregates.new(client)
+    end
+
+    # @return [OpenFec::Resources::Disbursements]
+    def disbursements
+      Resources::Disbursements.new(client)
+    end
+
+    # @return [OpenFec::Resources::Elections]
+    def elections
+      Resources::Elections.new(client)
+    end
+
+    # @return [OpenFec::Resources::IndependentExpenditures]
+    def independent_expenditures
+      Resources::IndependentExpenditures.new(client)
+    end
+  end
+end