ecfr 1.1.4 → 1.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93cb578d4fc85f48e9d1d0ac423522886fa575a2425da6836547eb075d4e6cf5
-  data.tar.gz: b896739d0023e6398da9effbab99ed0b48323d6a61b9f21b94b2680f9ed74146
+  metadata.gz: 13cc40dfeeb370c7a81be66f37bdf9f23cf4dfbb936465ce4c12b1ab88094deb
+  data.tar.gz: 6a80785bbd1e428f93f841401e678c1776f9b344a33e554738759937079eca06
 SHA512:
-  metadata.gz: cc03bfa1d18e5e202f4e3f069d4cf3f8ee3caf5aa3af26fdf0f9813a1c9c7756fe403764ac69f00268e3c96cbad85f1697e69eb8eab6f74b4d84351e74806e2e
-  data.tar.gz: 599a3c76236594b98fde583b801922b3bfb686071c9cbf2460610895d229580c428ba02026898b181dd0729dcfa18ccbecd8c1af5fde036edc17229c55ca739d
+  metadata.gz: 11198b0d371f4c2a49ed939af2db6f7b781809d107b1e17ef586b03676d21157f739b92e4ae681fe70112580650a7476b39cbdb0ea6e06c51067cc79943510dd
+  data.tar.gz: 3dddd1f095d6ea3015e8d4f9dfbb0d1fe9ab29cfd426274c6d646fa86bc02217c45545d2105682cf0e88ee33779b22f344c895feab0c55e2be0d036c9873332a

data/.rubocop.yml

@@ -18,9 +18,11 @@ inherit_mode:
   merge:
     - Exclude
 
-require:
+plugins:
   # Performance cops are bundled with Standard
   - rubocop-performance
+
+require:
   # Standard's config uses this custom cop,
   # so it must be loaded
   - standard/cop/block_single_line_braces

data/CHANGELOG.md

@@ -1,8 +1,25 @@
 ## [Unreleased]
 
+## [1.1.7] - 2026-06-29
+### Additions
+- Add authority endpoint
+- Add topic endpoint
+- Support for singular and plural change types (4552a8d5)
+
+## [1.1.6] - 2025-09-23
+### Fixes
+- Add missing Gemfile lock changes
+- See 1.1.5
+
+## [1.1.5] - 2025-09-23 - yanked
+### Additions
+- Add timeline endpoint (8490dbf1)
+- Removed puts from client to cleanup unwanted output (31846f86)
+- Add support for using 'delete' verb when attempting to clear varnish cache. (7d7a5870)
+
 ## [1.1.4] - 2025-03-27
 ### Additions
-- Add factory for Agency (38185411) 
+- Add factory for Agency (38185411)
 ### Dependencies
 - Removed lock to Rails 6 (f6c5024a)
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ecfr (1.1.3)
+    ecfr (1.1.6)
       activemodel
       activesupport
       faraday (~> 2.0)
@@ -11,133 +11,157 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.2.1)
-      activesupport (= 7.2.1)
-    activesupport (7.2.1)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activesupport (8.1.2)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    ast (2.4.2)
-    base64 (0.2.0)
-    bigdecimal (3.1.8)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.4)
-    connection_pool (2.4.1)
-    diff-lcs (1.5.1)
-    drb (2.2.1)
-    ethon (0.16.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    ethon (0.18.0)
       ffi (>= 1.15.0)
-    factory_bot (6.5.0)
-      activesupport (>= 5.0.0)
-    faraday (2.12.0)
-      faraday-net_http (>= 2.0, < 3.4)
+      logger
+    factory_bot (6.5.6)
+      activesupport (>= 6.1.0)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.3.0)
-      net-http
-    faraday-net_http_persistent (2.3.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    faraday-net_http_persistent (2.3.1)
       faraday (~> 2.5)
       net-http-persistent (>= 4.0.4, < 5)
     faraday-typhoeus (1.1.0)
       faraday (~> 2.0)
       typhoeus (~> 1.4)
-    ffi (1.17.0)
-    i18n (1.14.6)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    io-console (0.8.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    logger (1.6.1)
+    logger (1.7.0)
     method_source (1.1.0)
-    mini_portile2 (2.8.7)
-    minitest (5.25.1)
-    net-http (0.4.1)
-      uri
-    net-http-persistent (4.0.4)
-      connection_pool (~> 2.2)
-    nokogiri (1.16.7)
-      mini_portile2 (~> 2.8.2)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    net-http-persistent (4.0.8)
+      connection_pool (>= 2.2.4, < 4)
+    nokogiri (1.19.0-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-linux-gnu)
       racc (~> 1.4)
-    ostruct (0.6.1)
-    parallel (1.26.3)
-    parallel_tests (4.7.2)
+    nokogiri (1.19.0-x86_64-linux-musl)
+      racc (~> 1.4)
+    ostruct (0.6.3)
+    parallel (1.27.0)
+    parallel_tests (4.10.1)
       parallel
-    parser (3.3.5.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    pry (0.14.2)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
+      reline (>= 0.6.0)
     racc (1.8.1)
-    rack (3.1.7)
+    rack (3.2.4)
     rainbow (3.1.1)
-    regexp_parser (2.9.2)
+    regexp_parser (2.11.3)
+    reline (0.6.3)
+      io-console (~> 0.5)
     request_store (1.7.0)
       rack (>= 1.4)
-    rspec (3.13.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.1)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
+    rspec-support (3.13.7)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (1.66.1)
+    rubocop (1.82.1)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rubocop-ast (>= 1.32.2, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.32.3)
-      parser (>= 3.3.1.0)
-    rubocop-performance (1.22.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    securerandom (0.3.1)
-    standard (1.41.0)
+    securerandom (0.4.1)
+    standard (1.53.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.66.0)
+      rubocop (~> 1.82.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.5)
+      standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.5.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.22.0)
-    turbo_tests (2.2.4)
+      rubocop-performance (~> 1.26.0)
+    turbo_tests (2.2.5)
       parallel_tests (>= 3.3.0, < 5)
       rspec (>= 3.10)
     typhoeus (1.4.1)
       ethon (>= 0.9.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.6.0)
-    uri (0.13.1)
-    yard (0.9.37)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    yard (0.9.38)
 
 PLATFORMS
-  ruby
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
 
 DEPENDENCIES
   ecfr!
@@ -155,4 +179,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.6.5
+   2.6.7

data/lib/ecfr/admin_service/base.rb

@@ -5,7 +5,6 @@ module Ecfr
       require_relative "status"
 
       require_relative "agency"
-      require_relative "build"
       require_relative "ecfr_correction"
       require_relative "editorial_note"
       require_relative "ibr_cfr_range"

data/lib/ecfr/attribute_method_definition.rb

@@ -43,10 +43,7 @@ module Ecfr
         end
 
         if options[:type] == :boolean
-          define_method :"#{attr}?" do
-            val = extract_value(attr, options)
-            Ecfr::AttributeCaster.cast_attr(val, options[:type], options[:options] || {})
-          end
+          alias_method :"#{attr}?", :"#{attr}"
         end
       end
     end

data/lib/ecfr/base.rb

@@ -31,13 +31,14 @@ module Ecfr
 
     attr_reader :metadata, :results, :response_status, :request_data
 
-    SUPPORTED_ARRAY_ACCESSORS = %i[empty? first last size]
-    delegate(*SUPPORTED_ARRAY_ACCESSORS, to: :results)
+    SUPPORTED_ARRAY_ACCESSORS = %i[each empty? first last size]
+    delegate(*SUPPORTED_ARRAY_ACCESSORS, to: :results, allow_nil: true)
     alias_method :all, :results
 
+    DEFAULT_OPTIONS = {base: true}
+
     def initialize(attributes = {}, options = {})
-      default_options = {base: true}
-      options = default_options.merge(options)
+      options.reverse_merge!(DEFAULT_OPTIONS)
 
       @response_status = options.delete(:response_status)
       @request_data = options.delete(:request_data)
@@ -58,10 +59,6 @@ module Ecfr
       super(attributes)
     end
 
-    def each
-      @results.each { |result| yield result }
-    end
-
     class Metadata
       include AttributeMethodDefinition
 

data/lib/ecfr/client.rb

@@ -142,7 +142,8 @@ module Ecfr
 
         response = instrument("Ecfr::Perform #{cache_key.to_s.tr("\"", "'")}") do
           RequestStore.fetch(cache_key) do
-            puts "Request not in eCFR gem cache, fetching..."
+            # TODO: replace this puts with a logger
+            # puts "Request not in eCFR gem cache, fetching..."
 
             response = fetch(method, path, params: params,
               client_options: client_options)
@@ -201,7 +202,6 @@ module Ecfr
     #
     def self.build(response:,
       request_data: {}, build_options: {})
-
       default_build_options = {parse_response: true}
       build_options = default_build_options.merge(build_options)
 
@@ -236,6 +236,7 @@ module Ecfr
 
       execute do
         c.get(path, params) do |req|
+          yield(req) if block_given?
           Ecfr.config.request_hook.call(req)
         end
       end
@@ -246,6 +247,7 @@ module Ecfr
 
       execute do
         c.post(path, params) do |req|
+          yield(req) if block_given?
           Ecfr.config.request_hook.call(req)
         end
       end
@@ -256,6 +258,7 @@ module Ecfr
 
       execute do
         c.delete(path, params) do |req|
+          yield(req) if block_given?
           Ecfr.config.request_hook.call(req)
         end
       end
@@ -268,6 +271,7 @@ module Ecfr
       execute do
         c.run_request(:purge, path, nil, nil) do |request|
           request.params.update(params)
+          yield(req) if block_given?
           Ecfr.config.request_hook.call(request)
         end
       end

data/lib/ecfr/client_configuration.rb

@@ -0,0 +1,122 @@
+module Ecfr
+  #
+  # Configures the Ecfr gem from a consuming application's settings and
+  # credentials. Lives in the gem (rather than each app) so the contract
+  # between app config and the gem is defined and validated in one place.
+  #
+  # Everything the gem can't assume exists is passed in explicitly:
+  #   - settings:    the app's Settings object (duck-typed; dotted/[] access)
+  #   - env:         the app environment, used in the user_agent string
+  #   - credentials: optional; anything responding to #dig (e.g. Rails credentials)
+  #
+  # An optional block is yielded the config last, after every settings-derived
+  # assignment, so the app can override any value (request hooks, timeouts,
+  # urls, ...) without the gem depending on app-level constants.
+  #
+  class ClientConfiguration
+    class InvalidSettings < StandardError; end
+    class InvalidCredentials < StandardError; end
+
+    # Settings with no gem-side default must be present. Everything else has a
+    # default in Ecfr::Configuration::CONFIG_DEFAULTS and is therefore optional.
+    REQUIRED_SETTINGS = [
+      %i[container process],
+      %i[container role],
+      %i[container hostname]
+    ].freeze
+
+    def self.initialize_for(service, settings, env, credentials = nil)
+      validate_settings!(settings)
+      validate_credentials!(credentials)
+
+      Ecfr.configure do |config|
+        config.user_agent = [
+          "ecfr", service, env,
+          dig_setting(settings, :container, :process),
+          dig_setting(settings, :container, :role),
+          dig_setting(settings, :container, :hostname)
+        ].join("-")
+
+        log_http_requests = dig_setting(settings, :services, :ecfr, :log_http_requests)
+        config.log_http_requests = log_http_requests unless log_http_requests.nil?
+
+        cache_responses = dig_setting(settings, :services, :ecfr, :cache_responses)
+        config.cache_responses = cache_responses unless cache_responses.nil?
+
+        # prefer internal urls when setting up gem
+        base_url = dig_setting(settings, :services, :ecfr, :internal_base_url) ||
+          dig_setting(settings, :services, :ecfr, :base_url)
+        config.base_url = base_url if base_url.present?
+
+        profile_base_url = dig_setting(settings, :services, :ofr, :profile, :internal_base_url) ||
+          dig_setting(settings, :services, :ofr, :profile, :base_url)
+        config.ofr_profile_service_base_url = profile_base_url if profile_base_url.present?
+
+        profile_path = dig_setting(settings, :services, :ofr, :profile, :path)
+        config.ofr_profile_service_path = profile_path if profile_path.present?
+
+        # configure services according to settings
+        service_keys = Ecfr.services.filter_map do |service_module|
+          # ofr profile is configured separately above
+          next if service_module::Base.service_name == "OFR Profile"
+
+          service_module::Base.service_name.downcase.tr(" ", "_")
+        end
+
+        service_keys.each do |service_key|
+          url = dig_setting(settings, :services, :ecfr, service_key, :url)
+          config.send(:"#{service_key}_url=", url) if url.present?
+
+          path = dig_setting(settings, :services, :ecfr, service_key, :path)
+          config.send(:"#{service_key}_path=", path) if path.present?
+        end
+
+        open_timeout = dig_setting(settings, :services, :ecfr, :open_timeout)
+        config.open_timeout = open_timeout unless open_timeout.nil?
+
+        pdf_timeout = dig_setting(settings, :app, :timeouts, :pdf_timeout)
+        config.prince_xml_service_pdf_timeout = pdf_timeout unless pdf_timeout.nil?
+
+        # basic auth - some endpoints require auth (optional)
+        config.ecfr_basic_auth_username = credentials&.dig(:services, :ecfr, :http_basic, :username)
+        config.ecfr_basic_auth_password = credentials&.dig(:services, :ecfr, :http_basic, :password)
+
+        # let the app override any of the above (request hooks, urls, timeouts)
+        yield config if block_given?
+      end
+    end
+
+    def self.validate_settings!(settings)
+      raise InvalidSettings, "settings is required" if settings.nil?
+
+      missing = REQUIRED_SETTINGS.select { |path| dig_setting(settings, *path).blank? }
+      return if missing.empty?
+
+      raise InvalidSettings,
+        "missing required setting(s): #{missing.map { |path| path.join(".") }.join(", ")}"
+    end
+
+    def self.validate_credentials!(credentials)
+      return if credentials.nil?
+      return if credentials.respond_to?(:dig)
+
+      raise InvalidCredentials, "credentials must respond to #dig (got #{credentials.class})"
+    end
+
+    # Safely walk a settings tree via method or [] access, returning nil if any
+    # segment is missing rather than raising NoMethodError.
+    def self.dig_setting(node, *path)
+      path.reduce(node) do |obj, key|
+        break nil if obj.nil?
+
+        if obj.respond_to?(key)
+          obj.public_send(key)
+        elsif obj.respond_to?(:[])
+          obj[key]
+        end
+      end
+    end
+
+    private_class_method :validate_settings!, :validate_credentials!, :dig_setting
+  end
+end

data/lib/ecfr/configuration.rb

@@ -26,6 +26,7 @@ module Ecfr
       subscriptions_service_path: nil,
       varnish_cache_service_url: nil,
       varnish_cache_service_path: nil,
+      varnish_cache_service_clear_method: "purge",
       versioner_service_url: nil,
       versioner_service_path: nil,
       # basic auth - some endpoints require auth

data/lib/ecfr/constants.rb

@@ -2,13 +2,15 @@ module Ecfr
   module Constants
     module ChangeTypes
       KNOWN_CHANGE_TYPES = {
+        cross_reference: "Regulations linked from the above-dated Federal Register:",
         cross_references: "Regulations linked from the above-dated Federal Register:",
         delayed: "Regulations delayed in the above-dated Federal Register:",
         delayed_withdrawn: "Regulations delayed or withdrawn in the above-dated Federal Register:",
         delayed_withdrawn_extended: "Regulations delayed, withdrawn, or extended in the above-dated Federal Register:",
         effective: "Effective regulations inserted from the above-dated Federal Register:",
+        effective_cross_reference: "Regulations inserted that were previously linked and became effective on the date listed above:",
         effective_cross_references: "Regulations inserted that were previously linked and became effective on the date listed above:",
-        expired: "Effective dates that expire on this date:",
+        expired: "Effective regulations that expire on this date:",
         extended: "Regulations extended in the above-dated Federal Register",
         initial: "Initial import of this content - change type is indeterminate"
       }

data/lib/ecfr/parallel_client.rb

@@ -1,24 +1,29 @@
 module Ecfr
   module ParallelClient
     module ClassMethods
-      def parallel_client(base_url:, client_options: {})
+      def parallel_client(base_url: self.base_url, client_options: {})
         client(
           base_url: base_url,
           client_options: client_options.merge({adapter: :typhoeus})
         )
       end
 
-      # currently only handles expected cases when calling -renderer
-      def parallel_get(requests, client)
+      def parallel(method, requests, client = parallel_client)
         client.in_parallel do
           requests.each do |request|
-            request.response = client.get(request.path, request.args) do |req|
+            request.response = client.send(method, request.path, request.args) do |req|
               Ecfr.config.request_hook.call(req)
             end
           end
         end
+      end
+
+      def parallel_get(requests, client = parallel_client)
+        parallel(:get, requests, client)
+      end
 
-        requests
+      def parallel_post(requests, client = parallel_client)
+        parallel(:post, requests, client)
       end
     end
 

data/lib/ecfr/renderer_service/origin.rb

@@ -40,10 +40,7 @@ module Ecfr
       ORIGIN_PATH = "v1/origin"
 
       def self.find(date, title_number, params = {})
-        supported_params = (
-          Ecfr::Constants::Hierarchy::HIERARCHY_LEVELS[1, 8] +
-            [:build_id]
-        ).map(&:to_sym)
+        supported_params = Ecfr::Constants::Hierarchy::HIERARCHY_LEVELS[1, 8].map(&:to_sym)
 
         perform(
           :get,

data/lib/ecfr/search_service/base.rb

@@ -7,6 +7,7 @@ module Ecfr
       require_relative "content_version"
       require_relative "facet_base"
       require_relative "date_facet"
+      require_relative "timeline"
       require_relative "title_facet"
 
       def self.base_url

data/lib/ecfr/search_service/timeline.rb

@@ -0,0 +1,29 @@
+module Ecfr
+  module SearchService
+    class Timeline < FacetBase
+      include AttributeMethodDefinition
+
+      class Entry < Base
+        include AttributeMethodDefinition
+
+        def initialize(attributes = {}, options = {})
+          date, attributes, _ = attributes
+          attributes["date"] = date
+          attributes["change_types"].compact!
+          super
+        end
+
+        attribute :change_types, type: Array(:symbol)
+        attribute :count, type: :integer
+        attribute :date, type: :date, as: :key
+      end
+
+      attribute :timeline, type: Array(Entry)
+
+      # @return [<Timeline::Entry>]
+      def self.search(options = {})
+        super(:timeline, options)
+      end
+    end
+  end
+end

data/lib/ecfr/testing/extensions/search_service/timeline_extensions.rb

@@ -0,0 +1,13 @@
+class Ecfr::SearchService::Timeline
+  extend ResponseHelper
+
+  def self.response_for(timeline)
+    results = {
+      timeline: timeline
+    }.to_json
+
+    build(
+      response: stubbed_response(results)
+    )
+  end
+end

data/lib/ecfr/testing/extensions/versioner_service/reference_extensions.rb

@@ -0,0 +1,15 @@
+class Ecfr::VersionerService::Reference
+  extend ResponseHelper
+
+  def self.response_for(references)
+    references = references.is_a?(Array) ? references : [references]
+
+    results = {
+      references: references
+    }.compact
+
+    build(
+      response: stubbed_response(results.to_json)
+    )
+  end
+end

data/lib/ecfr/testing/extensions/versioner_service/topic_extensions.rb

@@ -0,0 +1,16 @@
+class Ecfr::VersionerService::Topic
+  extend ResponseHelper
+
+  def self.response_for(topics, meta: {})
+    topics = topics.is_a?(Array) ? topics : [topics]
+
+    results = {
+      topics: topics,
+      meta: meta
+    }.compact
+
+    build(
+      response: stubbed_response(results.to_json)
+    )
+  end
+end

data/lib/ecfr/testing/factories/search_service/timeline_factory.rb

@@ -0,0 +1,9 @@
+FactoryBot.define do
+  factory :timeline, class: "Ecfr::SearchService::Timeline" do
+    skip_create
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/reference_factory.rb

@@ -0,0 +1,16 @@
+FactoryBot.define do
+  factory :versioner_service_reference, class: "Ecfr::VersionerService::Reference" do
+    skip_create
+
+    reference { "1 CFR 1" }
+    description { "Definitions" }
+
+    initialize_with do
+      new(attributes.deep_stringify_keys)
+    end
+
+    trait :minimal do
+      description { "" }
+    end
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/topic_factory.rb

@@ -0,0 +1,34 @@
+FactoryBot.define do
+  factory :topic, class: "Ecfr::VersionerService::Topic" do
+    skip_create
+
+    name { "Sample Topic" }
+    references { ["1 CFR 1", "1 CFR 2"] }
+    see_also { ["Related Topic"] }
+    see { [] }
+
+    initialize_with do
+      new(attributes.deep_stringify_keys)
+    end
+
+    trait :with_references do
+      references { ["1 CFR 1", "1 CFR 2", "1 CFR 3"] }
+    end
+
+    trait :with_see_also do
+      see_also { ["Related Topic 1", "Related Topic 2"] }
+    end
+
+    trait :with_see do
+      see { ["Redirect Topic"] }
+      references { [] }
+      see_also { [] }
+    end
+
+    trait :minimal do
+      references { [] }
+      see_also { [] }
+      see { [] }
+    end
+  end
+end

data/lib/ecfr/varnish_cache_service/base.rb

@@ -14,7 +14,13 @@ module Ecfr
       end
 
       def self.expire(path)
-        purge(path)
+        # not all backends support the purge verb
+        # - the varnish purge proxy expects delete
+        if Ecfr.config.varnish_cache_service_clear_method.to_s == "delete"
+          delete(path)
+        else
+          purge(path)
+        end
       end
 
       def self.expire_everything

data/lib/ecfr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ecfr
-  VERSION = "1.1.4"
+  VERSION = "1.1.7"
 end

data/lib/ecfr/versioner_service/agency.rb

@@ -0,0 +1,9 @@
+module Ecfr
+  module VersionerService
+    class Agency < Ecfr::AdminService::Agency
+      attribute :references,
+        type: Array(:string),
+        desc: "array of CFR references for this topic"
+    end
+  end
+end

data/lib/ecfr/versioner_service/ancestors.rb

@@ -65,8 +65,6 @@ module Ecfr
       #   hierarchy of the requested content
       # @option options [<Integer>] :descendant_depth the number of
       #   levels of descendents to include in the structure
-      # @option options [<Integer>] :build_id internal use only - used to
-      #   retreive data about a specific build
       # @option options [<Boolean>] :metadata whether to include metadata in
       #   the response
       # @option options [<Integer>] :max_items
@@ -80,8 +78,7 @@ module Ecfr
         hierarchy_args = hierarchy_args.symbolize_keys
         options = options.symbolize_keys
 
-        options = hierarchy_args.merge(options).except(:title, :metadata)
-        options[:metadata] = true
+        options = hierarchy_args.merge(options).except(:title)
 
         perform(
           :get,

data/lib/ecfr/versioner_service/authority.rb

@@ -0,0 +1,48 @@
+module Ecfr
+  module VersionerService
+    #
+    # Authority entries represent individual references in the
+    # Parallel Table of Authorities.
+    #
+    class Authority < Base
+      result_key :authorities
+
+      attribute :kind,
+        desc: "authority reference kind"
+
+      attribute :components,
+        desc: "authority citation components"
+
+      attribute :date,
+        type: :date,
+        desc: "authority citation date"
+
+      attribute :references,
+        desc: "CFR titles, parts, and hierarchies that cite this authority"
+
+      AUTHORITIES_PATH = "v1/authorities"
+
+      metadata_key :meta
+
+      metadata :categories,
+        desc: "reference categories included in this response"
+
+      #
+      # Retrieves the Parallel Table of Authorities data.
+      #
+      # @param [<Hash>] options
+      # @option options [String] :year ("current") the year or 'current' to retrieve authorities for
+      #
+      # @return [Authority] grouped authority data and metadata
+      #
+      def self.all(options = {})
+        year = options.fetch(:year, "current")
+
+        perform(
+          :get,
+          "#{AUTHORITIES_PATH}/#{year}"
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/base.rb

@@ -6,9 +6,13 @@ module Ecfr
 
       # note: structure must be required before ancestors
       require_relative "structure"
+      require_relative "agency"
       require_relative "ancestors"
+      require_relative "authority"
       require_relative "issue_package"
       require_relative "title"
+      require_relative "reference"
+      require_relative "topic"
       require_relative "xml_content"
 
       def self.base_url

data/lib/ecfr/versioner_service/reference.rb

@@ -0,0 +1,19 @@
+module Ecfr
+  module VersionerService
+    #
+    # References in the topics endpoint provide detailed information
+    # about CFR references mentioned in topics and agencies.
+    #
+    # Each reference contains a CFR reference string and a description.
+    #
+    class Reference < Base
+      result_key :references
+
+      attribute :reference,
+        desc: "CFR reference ('1 CFR 1')"
+
+      attribute :description,
+        desc: "description of the reference"
+    end
+  end
+end

data/lib/ecfr/versioner_service/title.rb

@@ -61,8 +61,6 @@ module Ecfr
       # Retreive the list of all Titles
       #
       # @param [<Hash>] options
-      # @option options [String] :build_id internal use only - used
-      #   to retreive data about a specific build
       #
       # @return [<Title>] array of Titles with data
       #

data/lib/ecfr/versioner_service/topic.rb

@@ -0,0 +1,74 @@
+module Ecfr
+  module VersionerService
+    #
+    # Topics represent entries in the CFR Index and Finding Aids.
+    #
+    # Each topic contains a name and may have references to specific
+    # CFR sections, see_also references to other topics, or see
+    # references for redirects.
+    #
+    class Topic < Base
+      result_key :topics
+
+      attribute :adhoc,
+        type: :boolean,
+        desc: "distinguish informal topics from thesaurus entries"
+
+      attribute :name,
+        desc: "name of the topic"
+
+      attribute :references,
+        type: Array(:string),
+        desc: "array of CFR references for this topic"
+
+      attribute :see_also,
+        type: Array(:string),
+        desc: "array of related topic names to see also"
+
+      attribute :see,
+        type: Array(:string),
+        desc: "array of topic names to redirect to"
+
+      attribute :slug,
+        desc: "normalized topic identifier for URLs"
+
+      TOPICS_PATH = "v1/topics" # /current | /2024
+
+      metadata_key :meta
+
+      metadata :agencies,
+        type: Array(Ecfr::VersionerService::Agency),
+        desc: "array of agencies referenced in topics"
+
+      metadata :references,
+        type: Array(Ecfr::VersionerService::Reference),
+        desc: "array of CFR references with descriptions"
+
+      #
+      # Retrieves the list of all Topics
+      #
+      # @param [<Hash>] options
+      # @option options [String] :year ("current") the year or 'current' to retrieve topics for
+      # @option options [Boolean] :include_agencies (false) whether to include agencies in the response
+      #
+      # @return [<Topic>] array of Topics with their references and relationships
+      #
+      def self.all(options = {})
+        year = options.fetch(:year, "current")
+        include_agencies = options.fetch(:include_agencies, false)
+
+        params = {}
+        params[:include_agencies] = true if include_agencies
+
+        perform(
+          :get,
+          "#{TOPICS_PATH}/#{year}",
+          params: params,
+          perform_options: {
+            attributes_key: nil
+          }
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/xml_content.rb

@@ -19,7 +19,6 @@ module Ecfr
       # @param [<Date, String, 'current'>] date ISO string or 'current'
       # @param [<Integer, String>] title_number the title of interest
       # @param [<Hash>] options a hash of hierarchy levels for the content desired - see attributes defined in {Ecfr::Common::Hierarchy} for acceptable keys
-      # @option options [<String>] build_id internal use only - a specific build id
       #
       # @return [<XML>] XML for the full title or pared down to the requested hierarchy
       #
@@ -40,7 +39,6 @@ module Ecfr
       # @param [<Date, String, 'current'>] date ISO string or 'current'
       # @param [<Integer, String>] title_number the title of interest
       # @param [<Hash>] options a hash of hierarchy levels for the content desired - see attributes defined in {Ecfr:Common::Hierarchy} for acceptable keys
-      # @option options [<String>] build_id internal use only - a specific build id
       #
       # @return [<String>] URL to retreive XML content for the given parameters
       #

data/lib/ecfr.rb

@@ -5,6 +5,7 @@ require "active_model/type"
 
 require "active_support"
 require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/enumerable"
 require "active_support/core_ext/hash"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/string"
@@ -92,3 +93,5 @@ require_relative "ecfr/search_service/base"
 require_relative "ecfr/subscriptions_service/base"
 require_relative "ecfr/varnish_cache_service/base"
 require_relative "ecfr/versioner_service/base"
+
+require_relative "ecfr/client_configuration"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ecfr
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.7
 platform: ruby
 authors:
 - Peregrinator
 bindir: exe
 cert_chain: []
-date: 2025-03-27 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -274,7 +274,6 @@ files:
 - lib/ecfr/admin_service/agency.rb
 - lib/ecfr/admin_service/api_documentation.rb
 - lib/ecfr/admin_service/base.rb
-- lib/ecfr/admin_service/build.rb
 - lib/ecfr/admin_service/ecfr_correction.rb
 - lib/ecfr/admin_service/ecfr_correction/cfr_reference.rb
 - lib/ecfr/admin_service/editorial_note.rb
@@ -290,6 +289,7 @@ files:
 - lib/ecfr/attribute_method_definition.rb
 - lib/ecfr/base.rb
 - lib/ecfr/client.rb
+- lib/ecfr/client_configuration.rb
 - lib/ecfr/common/hierarchy.rb
 - lib/ecfr/configuration.rb
 - lib/ecfr/constants.rb
@@ -325,6 +325,7 @@ files:
 - lib/ecfr/search_service/date_facet.rb
 - lib/ecfr/search_service/facet_base.rb
 - lib/ecfr/search_service/status.rb
+- lib/ecfr/search_service/timeline.rb
 - lib/ecfr/search_service/title_facet.rb
 - lib/ecfr/subscriptions_service/base.rb
 - lib/ecfr/subscriptions_service/status.rb
@@ -335,8 +336,11 @@ files:
 - lib/ecfr/testing/extensions/renderer_service/origin_extensions.rb
 - lib/ecfr/testing/extensions/search_service/content_version_result_extensions.rb
 - lib/ecfr/testing/extensions/search_service/date_facet_extensions.rb
+- lib/ecfr/testing/extensions/search_service/timeline_extensions.rb
 - lib/ecfr/testing/extensions/versioner_service/ancestors_extensions.rb
+- lib/ecfr/testing/extensions/versioner_service/reference_extensions.rb
 - lib/ecfr/testing/extensions/versioner_service/title_extenstions.rb
+- lib/ecfr/testing/extensions/versioner_service/topic_extensions.rb
 - lib/ecfr/testing/factories/admin_service/agency_factory.rb
 - lib/ecfr/testing/factories/admin_service/cfr_reference_factory.rb
 - lib/ecfr/testing/factories/admin_service/ecfr_correction_factory.rb
@@ -347,29 +351,36 @@ files:
 - lib/ecfr/testing/factories/search_service/content_version_count_factory.rb
 - lib/ecfr/testing/factories/search_service/content_version_result_factory.rb
 - lib/ecfr/testing/factories/search_service/date_facet_factory.rb
+- lib/ecfr/testing/factories/search_service/timeline_factory.rb
 - lib/ecfr/testing/factories/versioner_service/ancestors_factory.rb
 - lib/ecfr/testing/factories/versioner_service/metadata_node_info_factory.rb
 - lib/ecfr/testing/factories/versioner_service/node_summary_factory.rb
+- lib/ecfr/testing/factories/versioner_service/reference_factory.rb
 - lib/ecfr/testing/factories/versioner_service/structure_factory.rb
 - lib/ecfr/testing/factories/versioner_service/title_factory.rb
+- lib/ecfr/testing/factories/versioner_service/topic_factory.rb
 - lib/ecfr/testing/factory_bot_helpers/content_version.rb
 - lib/ecfr/testing/factory_bot_helpers/ecfr_gem_initialize_helpers.rb
 - lib/ecfr/testing/helpers/response_helper.rb
 - lib/ecfr/testing/strategies/ecfr_attribute_hash_strategy.rb
 - lib/ecfr/varnish_cache_service/base.rb
 - lib/ecfr/version.rb
+- lib/ecfr/versioner_service/agency.rb
 - lib/ecfr/versioner_service/ancestors.rb
 - lib/ecfr/versioner_service/ancestors/metadata_node_info.rb
 - lib/ecfr/versioner_service/ancestors/node_summary.rb
 - lib/ecfr/versioner_service/api_documentation.rb
+- lib/ecfr/versioner_service/authority.rb
 - lib/ecfr/versioner_service/base.rb
 - lib/ecfr/versioner_service/issue_package.rb
 - lib/ecfr/versioner_service/issue_package/issue_volume.rb
 - lib/ecfr/versioner_service/issue_package/sha_comparison.rb
 - lib/ecfr/versioner_service/issue_package/title_version.rb
+- lib/ecfr/versioner_service/reference.rb
 - lib/ecfr/versioner_service/status.rb
 - lib/ecfr/versioner_service/structure.rb
 - lib/ecfr/versioner_service/title.rb
+- lib/ecfr/versioner_service/topic.rb
 - lib/ecfr/versioner_service/xml_content.rb
 - lib/yard/attribute_handler.rb
 - lib/yard/metadata_handler.rb

data/lib/ecfr/admin_service/build.rb

@@ -1,38 +0,0 @@
-module Ecfr
-  module AdminService
-    class Build < Base
-      result_key :builds
-
-      attribute :id,
-        desc: "build id"
-      attribute :status,
-        desc: "build status - either *Success* or *Failure*"
-
-      attribute :expired,
-        type: :boolean
-      attribute :previewable,
-        type: :boolean
-
-      BUILDS_PATH = "v1/builds"
-
-      #
-      # Retrieve a Build by id
-      #
-      # @param [<String>] build_id - id of the desired build
-      #
-      # @return [<Build>] data for a single build
-      #
-      def self.find(build_id)
-        perform(
-          :get,
-          build_path(build_id)
-        )
-      end
-
-      def self.build_path(build_id)
-        "#{BUILDS_PATH}/#{build_id}"
-      end
-      private_class_method :build_path
-    end
-  end
-end