ecfr 1.1.6 → 1.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a590084cfafab933fe619638898f62eeacb37aa183af6174cb47406df26d4c5
-  data.tar.gz: '095a4f5623deb58978f0c00941fa3c89d2f3bb2ef35bf9dff913e0648fb77af6'
+  metadata.gz: 13cc40dfeeb370c7a81be66f37bdf9f23cf4dfbb936465ce4c12b1ab88094deb
+  data.tar.gz: 6a80785bbd1e428f93f841401e678c1776f9b344a33e554738759937079eca06
 SHA512:
-  metadata.gz: 5fda252dfcbf05c0922c9c06167d2f6a99b833d60a251544a2e3cecacf990378e629b793f96da9744caddcb2819f7f417736c6ebe432174c25530bad452f3097
-  data.tar.gz: 44376ecbcfe743b0a105ae3d146a5c7abe01c304521bf140640dd0b7af67d723457df1a102f32d65f4596670d317ad1166d81130d1d456791d2e8b2d743bdd12
+  metadata.gz: 11198b0d371f4c2a49ed939af2db6f7b781809d107b1e17ef586b03676d21157f739b92e4ae681fe70112580650a7476b39cbdb0ea6e06c51067cc79943510dd
+  data.tar.gz: 3dddd1f095d6ea3015e8d4f9dfbb0d1fe9ab29cfd426274c6d646fa86bc02217c45545d2105682cf0e88ee33779b22f344c895feab0c55e2be0d036c9873332a

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [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

data/Gemfile.lock

@@ -11,94 +11,108 @@ 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)
+      uri (>= 0.13.1)
     ast (2.4.3)
-    base64 (0.2.0)
-    bigdecimal (3.1.9)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
     diff-lcs (1.6.2)
-    drb (2.2.1)
-    ethon (0.16.0)
+    drb (2.2.3)
+    ethon (0.18.0)
       ffi (>= 1.15.0)
-    factory_bot (6.5.1)
+      logger
+    factory_bot (6.5.6)
       activesupport (>= 6.1.0)
-    faraday (2.13.1)
+    faraday (2.14.0)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.0)
-      net-http (>= 0.5.0)
-    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.2-arm64-darwin)
-    ffi (1.17.2-x86_64-linux-gnu)
-    i18n (1.14.7)
+    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.12.0)
+    io-console (0.8.2)
+    json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
-    minitest (5.25.5)
-    net-http (0.6.0)
-      uri
-    net-http-persistent (4.0.5)
-      connection_pool (~> 2.2)
-    nokogiri (1.18.8-arm64-darwin)
+    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)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.19.0-x86_64-linux-musl)
       racc (~> 1.4)
-    ostruct (0.6.1)
+    ostruct (0.6.3)
     parallel (1.27.0)
     parallel_tests (4.10.1)
       parallel
-    parser (3.3.8.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
-    pry (0.15.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.14)
+    rack (3.2.4)
     rainbow (3.1.1)
-    regexp_parser (2.10.0)
+    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.3)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.4)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.4)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.3)
+    rspec-support (3.13.7)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (1.75.6)
+    rubocop (1.82.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -106,30 +120,30 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    standard (1.50.0)
+    standard (1.53.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.82.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
+      rubocop-performance (~> 1.26.0)
     turbo_tests (2.2.5)
       parallel_tests (>= 3.3.0, < 5)
       rspec (>= 3.10)
@@ -137,15 +151,17 @@ GEM
       ethon (>= 0.9.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.3)
-    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
   arm64-darwin
+  x86_64-darwin
   x86_64-linux-gnu
+  x86_64-linux-musl
 
 DEPENDENCIES
   ecfr!

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/base.rb

@@ -31,8 +31,8 @@ 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}
@@ -59,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

@@ -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/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/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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ecfr
-  VERSION = "1.1.6"
+  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.6
+  version: 1.1.7
 platform: ruby
 authors:
 - Peregrinator
 bindir: exe
 cert_chain: []
-date: 2025-09-23 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
@@ -338,7 +338,9 @@ files:
 - 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
@@ -353,26 +355,32 @@ files:
 - 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