usaspending-rb 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f51a07faf6f074e31046ff7938b346bef6b19733eef7036861f157d388b1ca1f
+  data.tar.gz: 1547247f8b6dbdad18bc27b484e65e49905c67ea6d55f89244423485fe5e1c2a
+SHA512:
+  metadata.gz: 3f62a38fcc8302ea54b37f1de49eeebab30d43843351bec16b2be1029ff79450593b7f76e33d54ce630d678f1aaf31f0411d4f8888bd1f04bc56a0bd68dfa35e
+  data.tar.gz: 6ffcb3b9f7c27046c530b90419f5875d95110c664b308e66d82e1229739f2c12804a3f8e67c173d1543a98d96fc8abb701771b4cfd605ed334f74d6f5f107cad

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.2] - 2026-03-10
+
+### Fixed
+- Fix geo_layer values: `congressional_district` → `district` to match actual API
+- Fix NAICS autocomplete response key in examples
+- Fix basic_search example referencing unavailable `total_count`
+- Update YARD docs for correct geo_layer values across Search, Spending, Disaster
+
+### Changed
+- Author and license updated to Jack Killilea
+
+### Added
+- `bin/console` for interactive IRB sessions
+
+## [0.1.0] - 2026-03-10
+
+### Added
+- **21 resource classes** covering ~120 USAspending.gov v2 API endpoints
+- **Awards**: search, detail, accounts, funding, counts, and cursor-paginated `search_all`
+- **Agency**: overview, budgets, sub-agencies, federal accounts, object classes, program activities, and TAS breakdowns (20 endpoints)
+- **Search**: spending by award, geography, category (15 category methods via metaprogramming), transaction, time series, and counts
+- **Spending**: validated geographic and categorical breakdowns with `for_district` convenience method
+- **Recipient**: search, profiles, child entities, state-level data
+- **Autocomplete**: agencies, recipients, locations, NAICS, PSC, CFDA, glossary, city, and TAS components (19 endpoints)
+- **References**: CFDA/assistance listings, NAICS, PSC trees, TAS trees, DEF codes, glossary, data dictionary, submission periods
+- **Disaster**: COVID/IIJA emergency fund spending — overview, agency/recipient/CFDA/federal account breakdowns, loans, geography
+- **Federal Accounts**: list, detail, snapshots, program activities, object classes
+- **Downloads**: award/transaction/account CSV generation, status polling, bulk downloads, monthly file listings
+- **IDV**: indefinite delivery vehicle awards, activity, funding, amounts
+- **Subawards & Transactions**: paginated listings for prime awards
+- **Spending Explorer**: drill-down visualization data
+- **Reporting**: agency submission history, discrepancies, unlinked awards
+- **Financial**: balances by agency, spending by object class, federal obligations, budget functions
+- **Award Spending**: recipient breakdowns by fiscal year and agency
+- Configurable timeouts, retries, and exponential backoff on 429/5xx
+- Response wrapper with `Enumerable`, pagination helpers, `inspect`, `to_json`, `success?`
+- Error hierarchy: `HttpError` base with `BadRequestError`, `NotFoundError`, `UnprocessableEntityError`, `RateLimitError`, `ServerError`, `ConnectionError`
+- Per-instance client support (`USAspending::Client.new(config)`) with memoized resource accessors
+- User-Agent header (`usaspending-rb/VERSION`)
+- YARD documentation with `@param`, `@return`, `@raise`, `@example` tags
+- RSpec test suite (181 specs, 91%+ coverage)
+- SimpleCov with 85% minimum coverage threshold
+- RuboCop + rubocop-rspec (0 offenses)
+- VCR + WebMock for HTTP fixture recording
+- Rakefile with `spec`, `rubocop`, and `yard` tasks

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,354 @@
+# USAspending
+
+A Ruby client for the [USAspending.gov](https://api.usaspending.gov) REST API v2. Access federal award data, agency spending, geographic breakdowns, recipient profiles, and more.
+
+No API key required. The USAspending.gov API is fully public.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'usaspending'
+```
+
+Then `bundle install`, or install directly:
+
+```bash
+gem install usaspending
+```
+
+## Quick Start
+
+```ruby
+require 'usaspending'
+
+# Search for contracts
+response = USAspending.awards.search(
+  filters: { award_type_codes: %w[A B C D] },
+  limit: 10
+)
+response.each { |award| puts award['Recipient Name'] }
+```
+
+## Usage
+
+### Award Search
+
+```ruby
+response = USAspending.awards.search(
+  filters: {
+    award_type_codes: %w[A B C D],
+    place_of_performance_locations: [
+      { country: 'USA', state: 'VA', congressional_district: '08' }
+    ]
+  },
+  fields: ['Award ID', 'Recipient Name', 'Award Amount'],
+  sort: 'Award Amount',
+  limit: 25
+)
+
+response.results       # => [{ "Award ID" => "...", ... }, ...]
+response.size          # => 25
+response.total_count   # => 1234
+response.next_page?    # => true
+```
+
+### Paginate All Results
+
+Uses cursor pagination for reliability with large result sets:
+
+```ruby
+USAspending.awards.search_all(
+  filters: { award_type_codes: %w[A B C D] },
+  limit: 100
+) do |page|
+  page.each { |award| save_to_db(award) }
+end
+```
+
+### Award Detail
+
+```ruby
+award = USAspending.awards.find('CONT_AWD_N0018923C0001_9700_-NONE-_-NONE-')
+award['description']
+award['total_obligation']
+
+# Related data
+USAspending.awards.accounts(award_id: 'CONT_AWD_...')
+USAspending.awards.funding(award_id: 'CONT_AWD_...')
+USAspending.awards.transaction_count('CONT_AWD_...')
+```
+
+### Geographic Spending
+
+```ruby
+# State-level breakdown
+response = USAspending.spending.by_geography(
+  scope: 'place_of_performance',
+  geo_layer: 'state',
+  filters: { fiscal_years: [2025] }
+)
+
+# Congressional district convenience method
+response = USAspending.spending.for_district(
+  state_abbr: 'VA',
+  district: '08',
+  fiscal_years: [2025]
+)
+```
+
+### Category Breakdown
+
+```ruby
+# By NAICS industry code
+USAspending.spending.by_category(
+  category: 'naics',
+  filters: { fiscal_years: [2025] },
+  limit: 25
+)
+
+# Or use Search directly for any of the 15 categories
+USAspending.search.spending_by_awarding_agency(filters: { fiscal_years: [2025] })
+USAspending.search.spending_by_recipient(filters: { fiscal_years: [2025] })
+USAspending.search.spending_by_cfda(filters: { fiscal_years: [2025] })
+USAspending.search.spending_by_naics(filters: { fiscal_years: [2025] })
+USAspending.search.spending_by_psc(filters: { fiscal_years: [2025] })
+# ... and 10 more category methods
+```
+
+### Agency Data
+
+```ruby
+# List all top-tier agencies
+agencies = USAspending.agency.list
+
+# Agency overview (e.g. Treasury = "020")
+treasury = USAspending.agency.overview('020', fiscal_year: 2025)
+
+# Drill down
+USAspending.agency.sub_agencies('020', fiscal_year: 2025)
+USAspending.agency.federal_accounts('020', fiscal_year: 2025)
+USAspending.agency.budget_function('020', fiscal_year: 2025)
+USAspending.agency.obligations_by_award_category('020', fiscal_year: 2025)
+USAspending.agency.budgetary_resources('020')
+```
+
+### Recipient Data
+
+```ruby
+# Search recipients
+results = USAspending.recipient.search('Lockheed Martin')
+
+# Recipient profile
+profile = USAspending.recipient.find('abc123-hash-value')
+
+# State-level data
+states = USAspending.recipient.states
+virginia = USAspending.recipient.state('51') # FIPS code
+```
+
+### Autocomplete
+
+```ruby
+USAspending.autocomplete.location('22201', geo_layer: 'zip_code')
+USAspending.autocomplete.naics('541')
+USAspending.autocomplete.recipient('Lockheed')
+USAspending.autocomplete.awarding_agency('Treasury')
+USAspending.autocomplete.city('Arlington', state_code: 'VA')
+USAspending.autocomplete.psc('R425')
+```
+
+### Reference Data
+
+```ruby
+USAspending.references.toptier_agencies
+USAspending.references.assistance_listings  # CFDA programs
+USAspending.references.def_codes            # Disaster emergency fund codes
+USAspending.references.naics(depth: 2)      # NAICS industry codes
+USAspending.references.psc_tree             # Product service codes
+USAspending.references.data_dictionary
+USAspending.references.glossary
+USAspending.references.submission_periods
+```
+
+### Disaster / Emergency Fund Spending
+
+```ruby
+# COVID spending overview
+USAspending.disaster.overview(def_codes: %w[L M N])
+
+# Drill down by entity
+USAspending.disaster.agency_spending(def_codes: %w[L M])
+USAspending.disaster.recipient_spending(def_codes: %w[L])
+USAspending.disaster.cfda_spending(def_codes: %w[L])
+
+# Geographic breakdown
+USAspending.disaster.spending_by_geography(def_codes: %w[L], geo_layer: 'state')
+```
+
+### Spending Explorer
+
+```ruby
+USAspending.spending_explorer.explore(
+  type: 'budget_function',
+  filters: { fy: '2025', quarter: '1' }
+)
+```
+
+### Downloads
+
+```ruby
+# Generate a CSV download
+response = USAspending.download.awards(
+  filters: { award_type_codes: %w[A], fiscal_years: [2025] }
+)
+file_name = response['file_name']
+
+# Check status
+USAspending.download.status(file_name)
+
+# Bulk downloads
+USAspending.bulk_download.awards(filters: { fiscal_years: [2025] })
+```
+
+### Federal Accounts
+
+```ruby
+USAspending.federal_accounts.list
+USAspending.federal_accounts.find('020-0001') # by account code
+USAspending.federal_accounts.fiscal_year_snapshot(1234) # by numeric ID
+```
+
+### Additional Resources
+
+```ruby
+# Transactions for an award
+USAspending.transactions.list(award_id: 'CONT_AWD_...')
+
+# Subawards
+USAspending.subawards.list(award_id: 'CONT_AWD_...')
+
+# IDV (Indefinite Delivery Vehicles)
+USAspending.idv.amounts('IDV_AWD_...')
+USAspending.idv.awards(award_id: 'IDV_AWD_...')
+
+# Reporting
+USAspending.reporting.agencies_overview(fiscal_year: 2025, fiscal_period: 6)
+
+# Financial data
+USAspending.financial_balances.agencies(funding_agency_identifier: '020', fiscal_year: 2025)
+USAspending.budget_functions.list
+```
+
+## Configuration
+
+```ruby
+USAspending.configure do |config|
+  config.timeout = 60                      # Request timeout in seconds (default: 30)
+  config.retries = 5                       # Max retries on 429/5xx (default: 3)
+  config.logger  = Logger.new($stdout)     # Optional request logging
+end
+```
+
+### Rails Initializer
+
+```ruby
+# config/initializers/usaspending.rb
+USAspending.configure do |config|
+  config.timeout = 30
+  config.retries = 3
+  config.logger  = Rails.logger if Rails.env.development?
+end
+```
+
+### Per-Instance Client
+
+For different configurations in the same process:
+
+```ruby
+client = USAspending::Client.new(custom_config)
+client.awards.search(filters: { ... })
+client.agency.overview('020')
+```
+
+## Response Object
+
+All API calls return a `USAspending::Response`:
+
+```ruby
+response = USAspending.awards.search(filters: { ... })
+
+response.results             # Array of result hashes
+response.each { |r| ... }   # Enumerable — supports map, select, first, etc.
+response.size                # Results on this page
+response.empty?              # No results?
+response.total_count         # Total matching records (not just this page)
+response.next_page?          # More pages available?
+response.last_record_unique_id  # Cursor for next page
+response.success?            # HTTP 2xx?
+
+response['key']              # Direct hash access
+response.dig('nested', 'key')
+response.raw                 # Raw parsed JSON body
+response.to_h                # Always returns a Hash
+response.to_json             # JSON string
+```
+
+## Error Handling
+
+```ruby
+begin
+  USAspending.awards.find('INVALID')
+rescue USAspending::BadRequestError => e
+  puts "Bad request: #{e.status} — #{e.body}"
+rescue USAspending::NotFoundError => e
+  puts "Not found: #{e.status}"
+rescue USAspending::UnprocessableEntityError => e
+  puts "Invalid filters: #{e.body}"
+rescue USAspending::RateLimitError
+  puts 'Rate limited — retries exhausted'
+rescue USAspending::ServerError => e
+  puts "Server error: #{e.status}"
+rescue USAspending::ConnectionError => e
+  puts "Network issue: #{e.message}"
+end
+```
+
+Error hierarchy:
+
+```
+USAspending::Error
+├── HttpError
+│   ├── ClientError
+│   │   ├── BadRequestError      (400)
+│   │   ├── NotFoundError        (404)
+│   │   ├── UnprocessableEntityError (422)
+│   │   └── RateLimitError       (429)
+│   └── ServerError              (500+)
+└── ConnectionError              (timeouts, DNS, refused)
+```
+
+All `HttpError` subclasses expose `.status` and `.body`.
+
+## Development
+
+```bash
+git clone https://github.com/thepublictab/usaspending-rb.git
+cd usaspending-rb
+bundle install
+
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Lint
+bundle exec yard        # Generate docs
+bundle exec rake        # Default: runs rspec
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- Faraday ~> 2.0
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/usaspending/client.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module USAspending
+  # HTTP client that wraps Faraday with retry logic and error handling.
+  # Supports both module-level and per-instance usage patterns.
+  #
+  # @example Module-level (shared client)
+  #   USAspending.awards.search(filters: { ... })
+  #
+  # @example Per-instance (custom config)
+  #   client = USAspending::Client.new(config)
+  #   client.awards.search(filters: { ... })
+  class Client
+    # @return [Configuration] the configuration used by this client
+    attr_reader :config
+
+    # @param config [Configuration] configuration object (defaults to global config)
+    def initialize(config = USAspending.configuration)
+      @config = config
+    end
+
+    # Returns the Faraday connection, lazily built.
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= Faraday.new(url: config.base_url) do |f|
+        f.options.timeout      = config.timeout
+        f.options.open_timeout = 10
+
+        f.headers['User-Agent'] = "usaspending-rb/#{USAspending::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
+
+    # Performs a GET request.
+    #
+    # @param path [String] API endpoint path relative to base URL
+    # @param params [Hash] query parameters
+    # @return [Response]
+    # @raise [HttpError] on any non-2xx response
+    # @raise [ConnectionError] on network failures or timeouts
+    def get(path, params = {})
+      response = connection.get(path, 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
+
+    # Performs a POST request with a JSON body.
+    #
+    # @param path [String] API endpoint path relative to base URL
+    # @param body [Hash] request body (serialized to JSON)
+    # @return [Response]
+    # @raise [HttpError] on any non-2xx response
+    # @raise [ConnectionError] on network failures or timeouts
+    def post(path, body = {})
+      response = connection.post(path, body)
+      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
+
+    # @!group Resource Accessors
+
+    # @!macro [attach] resource_accessor
+    #   @return [Resources::$1]
+    RESOURCE_ACCESSORS = {
+      awards: 'Awards',
+      agency: 'Agency',
+      spending: 'Spending',
+      recipient: 'Recipient',
+      autocomplete: 'Autocomplete',
+      references: 'References',
+      disaster: 'Disaster',
+      search: 'Search',
+      federal_accounts: 'FederalAccounts',
+      download: 'Download',
+      bulk_download: 'BulkDownload',
+      idv: 'Idv',
+      subawards: 'Subawards',
+      transactions: 'Transactions',
+      spending_explorer: 'SpendingExplorer',
+      reporting: 'Reporting',
+      federal_obligations: 'FederalObligations',
+      financial_balances: 'FinancialBalances',
+      financial_spending: 'FinancialSpending',
+      budget_functions: 'BudgetFunctions',
+      award_spending: 'AwardSpending'
+    }.freeze
+
+    RESOURCE_ACCESSORS.each do |method_name, class_name|
+      define_method(method_name) do
+        ivar = "@#{method_name}"
+        instance_variable_get(ivar) || instance_variable_set(ivar, Resources.const_get(class_name).new(self))
+      end
+    end
+
+    # @!endgroup
+
+    # Concise representation for IRB/Pry debugging.
+    # @return [String]
+    def inspect
+      "#<#{self.class} base_url=#{config.base_url.inspect} timeout=#{config.timeout}>"
+    end
+
+    private
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        Response.new(response.body, response.status)
+      when 400
+        raise BadRequestError.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 401..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/usaspending/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module USAspending
+  # Holds configuration options for the USAspending client.
+  #
+  # @example
+  #   USAspending.configure do |config|
+  #     config.base_url = "https://api.usaspending.gov/api/v2/"
+  #     config.timeout  = 60
+  #     config.retries  = 5
+  #     config.logger   = Logger.new($stdout)
+  #   end
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.usaspending.gov/api/v2/'
+    DEFAULT_TIMEOUT  = 30
+    DEFAULT_RETRIES  = 3
+
+    # @return [String] base URL for the USAspending API
+    attr_accessor :base_url
+
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] maximum number of retries on 429/5xx responses
+    attr_accessor :retries
+
+    # @return [Logger, nil] optional logger for request/response logging
+    attr_accessor :logger
+
+    # @return [Symbol] Faraday adapter to use (default: Faraday.default_adapter)
+    attr_accessor :adapter
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @timeout  = DEFAULT_TIMEOUT
+      @retries  = DEFAULT_RETRIES
+      @logger   = nil
+      @adapter  = Faraday.default_adapter
+    end
+
+    # @return [Hash] configuration as a plain hash
+    def to_h
+      {
+        base_url: base_url,
+        timeout: timeout,
+        retries: retries,
+        logger: logger,
+        adapter: adapter
+      }
+    end
+
+    # Concise representation for IRB/Pry debugging.
+    # @return [String]
+    def inspect
+      "#<#{self.class} base_url=#{base_url.inspect} timeout=#{timeout} retries=#{retries}>"
+    end
+  end
+end