ecfr 1.0.0

data/lib/ecfr/admin_service/ecfr_correction.rb

@@ -0,0 +1,78 @@
+module Ecfr
+  module AdminService
+    class EcfrCorrection < Base
+      require_relative "ecfr_correction/cfr_reference"
+
+      result_key :ecfr_corrections
+
+      attribute :corrective_action,
+        desc: "description of action taken"
+      attribute :fr_citation,
+        desc: "Federal Register citation in form of '80 FR 12345'"
+
+      attribute :id,
+        type: :integer
+      attribute :position,
+        type: :integer,
+        desc: "position of correction in list"
+      attribute :title,
+        type: :integer,
+        desc: "CFR Title"
+      attribute :year,
+        type: :integer,
+        desc: "year of corrective action"
+
+      attribute :error_corrected,
+        type: :date,
+        desc: "date error was corrected"
+      attribute :error_occurred,
+        type: :date,
+        desc: "date error first occured"
+      attribute :last_modified,
+        type: :date,
+        desc: "date this correction was last modified"
+
+      attribute :cfr_references,
+        type: Array(CfrReference),
+        desc: "the portions of the CFR this correction applies to"
+
+      attribute :display_in_toc,
+        type: :boolean,
+        desc: "whether this correction should be displayed on table of contents pages"
+
+      CORRECTIONS_PATH = "v1/corrections.json"
+
+      #
+      # Retrieve the list of all corrections
+      #
+      # @return [[<EcfrCorrection>]] an array of eCFR correction records
+      #
+      def self.all
+        perform(
+          :get,
+          CORRECTIONS_PATH
+        )
+      end
+
+      #
+      # Retrieve a list of corrections filtered by the provided parameters
+      #
+      # @param [<Hash>] args parameters by which to filter the results; supported args:
+      #   - :date
+      #   - :error_corrected_date
+      #   - :title
+      #
+      # @return [[<EcfrCorrection>]] an array of eCFR correction records
+      #
+      def self.where(args)
+        args.slice!(:date, :error_corrected_date, :title)
+
+        perform(
+          :get,
+          CORRECTIONS_PATH,
+          params: args
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/editorial_note/hierarchy.rb

@@ -0,0 +1,19 @@
+module Ecfr
+  module AdminService
+    class EditorialNote
+      class Hierarchy
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :title,
+          desc: "Title number"
+        attribute :part,
+          desc: "Part identifier"
+        attribute :subpart,
+          desc: "Subpart identifier"
+        attribute :section,
+          desc: "Section identifier"
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/editorial_note.rb

@@ -0,0 +1,40 @@
+module Ecfr
+  module AdminService
+    class EditorialNote < Base
+      require_relative "editorial_note/hierarchy"
+
+      result_key :editorial_notes
+
+      attribute :editorial_note,
+        desc: "content of the editorial note"
+
+      attribute :end_date,
+        type: :date,
+        desc: "last date the editorial note applies to"
+      attribute :start_date,
+        type: :date,
+        desc: "first date the editorial note applies to"
+
+      attribute :hierarchies,
+        type: Array(Hierarchy),
+        desc: "the hierarchies of the content this editorial note applies to"
+
+      EDITORIAL_NOTES_PATH = "v1/editorial-notes"
+
+      #
+      # Retrieve a list of editorial notes
+      #
+      # @param [<Hash>] args parameters by which to filter the results; supported args:
+      #   - :title
+      #
+      # @return [[<EditorialNote>]] an array of editorial note records
+      #
+      def self.where(args)
+        perform(
+          :get,
+          "#{EDITORIAL_NOTES_PATH}/title-#{args[:title]}.json"
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/ibr_cfr_range/address.rb

@@ -0,0 +1,17 @@
+module Ecfr
+  module AdminService
+    class IbrCfrRange
+      class Address
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :address,
+          desc: "generally a physical address"
+        attribute :address_group_1,
+          desc: "first level description of address"
+        attribute :address_group_2,
+          desc: "second level description of address"
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/ibr_cfr_range/organization.rb

@@ -0,0 +1,28 @@
+module Ecfr
+  module AdminService
+    class IbrCfrRange
+      class Organization
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :details,
+          desc: "generally contact information for the organization"
+        attribute :name,
+          desc: "organization name"
+
+        class Material
+          include AttributeMethodDefinition
+
+          attribute :cfr_references,
+            desc: "locations in the CFR where this material is incorporated by reference"
+          attribute :details,
+            desc: "information about what was incorporated - generally publication title, etc."
+        end
+
+        attribute :materials,
+          type: Array(Material),
+          desc: "array of materials that have been incorporated by reference"
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/ibr_cfr_range.rb

@@ -0,0 +1,67 @@
+module Ecfr
+  module AdminService
+    class IbrCfrRange < Base
+      require_relative "ibr_cfr_range/address"
+      require_relative "ibr_cfr_range/organization"
+
+      result_key :ibr_cfr_ranges
+
+      attribute :label,
+        desc: "description - generally the agency responsible"
+      attribute :notes,
+        desc: "notes about the IBR content"
+      attribute :part_range,
+        desc: "the range of parts the IBR item applies to"
+
+      attribute :title,
+        type: :integer,
+        desc: "CFR title number"
+
+      attribute :organizations,
+        type: Array(Organization),
+        desc: "array of organizations responsible for IBR materials and more details"
+
+      attribute :addresses,
+        type: Array(Address),
+        desc: "address information for district offices, etc."
+
+      IBR_CFR_RANGES_PATH = "v1/incorporation-by-reference"
+
+      #
+      # Retrieve a summarized list of all IBR information
+      #
+      # @return [[<IbrCfrRange>]] an array of IBR information
+      #   limited to `title`, `part_range`, and `label` fields
+      #
+      def self.all
+        perform(
+          :get,
+          "#{IBR_CFR_RANGES_PATH}.json"
+        )
+      end
+
+      #
+      # Retrieve a detailed list of IBR information for the request IBR CFR range
+      #
+      # @param [<String, Integer>] title CFR title
+      # @param [<String>] part_range the part range in the form "1-99"
+      #
+      # @return [<IbrCfrRange>] contains all data available for specified params
+      #
+      def self.find(title, part_range)
+        perform(
+          :get,
+          ibr_cfr_range_path(title, part_range),
+          perform_options: {attributes_key: "ibr_cfr_range"}
+        )
+      end
+
+      def self.ibr_cfr_range_path(title, part_range)
+        part_range = ERB::Util.url_encode(part_range)
+
+        "#{IBR_CFR_RANGES_PATH}/title-#{title}/#{part_range}.json"
+      end
+      private_class_method :ibr_cfr_range_path
+    end
+  end
+end

data/lib/ecfr/admin_service/issue/change.rb

@@ -0,0 +1,19 @@
+module Ecfr
+  module AdminService
+    class Issue
+      class Change
+        extend Ecfr::Constants::ChangeTypes
+
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :change_description,
+          desc: "CFR references that this change affects"
+
+        attribute :change_type,
+          type: :symbol,
+          desc: "indicates the type of change - corresponds to the keys in {KNOWN_CHANGE_TYPES}"
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/issue.rb

@@ -0,0 +1,86 @@
+module Ecfr
+  module AdminService
+    class Issue < Base
+      require_relative "issue/change"
+
+      result_key :issues
+
+      attribute :description,
+        desc: "US standard date description"
+
+      attribute :titles,
+        type: Array(:integer),
+        desc: "array of CFR title numbers affected in this issue"
+
+      attribute :end_date,
+        type: :date,
+        desc: "end date of issue"
+      attribute :issue_date,
+        type: :date,
+        desc: "date of issue"
+      attribute :start_date,
+        type: :date,
+        desc: "start date of issue"
+
+      attribute :changes,
+        type: Array(Change),
+        desc: "array of change types and CFR reference data"
+
+      metadata_key :meta
+
+      # @return [String, nil]
+      metadata :next,
+        desc: "date of next issue in ISO format"
+      # @return [String, nil]
+      metadata :previous,
+        desc: "date of previous issue in ISO format"
+
+      ISSUES_PATH = "v1/issues"
+
+      #
+      # Retrieves a summary of all available issues
+      #
+      # @return [[<Issue>]] does not include the `changes` or `metadata` items
+      #
+      def self.all
+        perform(
+          :get,
+          "#{ISSUES_PATH}.json"
+        )
+      end
+
+      #
+      # Retrieves detailed issue data for the specified date.
+      # If the isssue spans multiple days and date in that timespan will return the issue
+      #
+      # @param [<Date, DateTime, Time, String<'current'>] date the string 'current' can be provided to retrieve the newest issue at time of request
+      #
+      # @return [[<Issue>]] returns array containing single issue for the date provided
+      #
+      def self.find(date:)
+        perform(
+          :get,
+          issues_path(date)
+        )
+      end
+
+      def self.issues_path(date)
+        "#{ISSUES_PATH}/#{date_slug_for(date)}"
+      end
+
+      # supports :current, Date, DateTime, Time
+      def self.date_slug_for(date_like)
+        return "current" if date_like == :current
+
+        if date_like.respond_to?(:to_date)
+          date_like = date_like.to_date
+        end
+
+        return date_like.iso8601 if date_like.is_a?(Date)
+
+        raise "Unknown input for Ecfr::AdminService::Issue"
+      end
+      private_class_method :date_slug_for
+    end
+  end
+end

data/lib/ecfr/admin_service/site_notification.rb

@@ -0,0 +1,34 @@
+module Ecfr
+  module AdminService
+    class SiteNotification < Base
+      result_key :notifications
+
+      attribute :last_updated_by,
+        desc: "email of user who last updated the notification"
+      attribute :message,
+        desc: "notification content"
+      attribute :notification_type,
+        desc: "where the notification should be displayed; either `global` or `global_top`"
+
+      attribute :active,
+        type: :boolean
+
+      attribute :updated_at,
+        type: :datetime
+
+      SITE_NOTIFICATIONS_PATH = "v1/notifications.json"
+
+      #
+      # Retrieves all active notifications
+      #
+      # @return [[<SiteNotification>]] array of site notifications
+      #
+      def self.all
+        perform(
+          :get,
+          SITE_NOTIFICATIONS_PATH
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/status.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module AdminService
+    class Status < Base
+      include DefaultStatusSetup
+    end
+  end
+end

data/lib/ecfr/attribute_caster.rb

@@ -0,0 +1,72 @@
+module Ecfr
+  class AttributeCaster
+    #
+    # Given a value and a type return the value cast to the type.
+    # Some types do not actually modify the value but exist in order
+    # to support automated documentation via YARD.
+    #
+    # @param [<Integer, Float, String>] val the value as
+    #   parsed from a JSON response
+    # @param [<Symbol, Class>] type a type to cast the value to,
+    #   classes will be instantiated with the value
+    # @param [<Hash>] options options are passed to classes when they
+    #   are instantiated. {base: false} is merged into these
+    #   options to indicate that metadata attributes (among other
+    #   things) should not be populated. See {Ecfr::Base#initialize}
+    #
+    # @return a typecast value
+    #
+    # @note some API endpoints do not return a key for values that are
+    #   false (such as processing_in_progress). Because the attribute
+    #   is not include in the response it can not be typecast as
+    #   boolean false (it will return nil however which is still falsey)
+    #
+    def self.cast_attr(val, type, options = {})
+      return val if val.nil?
+
+      case type
+      when :integer
+        val # JSON parse was sufficient
+      when :float
+        val # JSON parse was sufficient
+      when :boolean
+        ActiveModel::Type::Boolean.new.cast(val)
+      when :date
+        return val if val.is_a?(Date)
+        Date.parse(val.to_s)
+      when :datetime
+        return val if val.is_a?(DateTime)
+        DateTime.parse(val.to_s)
+      when :symbol
+        val.to_sym
+      when ->(type) { type.respond_to?(:new) }
+        instantiate(type, val, options.merge(base: false))
+        # type.new(val, options.merge(base: false))
+      when ->(type) { type.is_a?(Array) && type.first.respond_to?(:new) }
+        val.map { |v| instantiate(type.first, v, options.merge(base: false)) } # type.first.new(v, options.merge(base: false)) }
+      when ->(type) { type.is_a?(Array) && type.first == :symbol }
+        val.map(&:to_sym)
+      when ->(type) { type.is_a?(Array) && [:integer, :string].include?(type.first) }
+        val # JSON parse was sufficient
+      when nil
+        val # JSON parse was sufficient
+      else
+        raise "Undefined type '#{type}' provided to 'attribute'/'metadata'!"
+      end
+    end
+
+    #
+    # Support inheritance by instantiating the class
+    # inheriting from our internal class if it's been
+    # defined
+    #
+    def self.instantiate(klass, val, options)
+      if const_defined?("#{klass}::KLASS")
+        klass::KLASS.new(val, options)
+      else
+        klass.new(val, options)
+      end
+    end
+    private_class_method :instantiate
+  end
+end

data/lib/ecfr/attribute_method_definition.rb

@@ -0,0 +1,92 @@
+module Ecfr
+  #
+  # Provides the base functionality for attribute and metadata
+  # definition.
+  #
+  module AttributeMethodDefinition
+    module ClassMethods
+      #
+      # Provides attribute definition. The attribute defined is
+      # expected to be part of the response. If the key in the
+      # response is different than the attribute name (eg you want
+      # to rename it) then the `value_key` option can be used.
+      #
+      # When the :type option is :boolean we also define a
+      # predicate method (eg: we define both foo and foo?)
+      #
+      # @param [<Symbol>] attr name of the attribute to define
+      # @param [<Hash>] options
+      # @option options [<Symbol, Class>] type a type to cast the
+      #   JSON parsed value to. See {Ecfr::AttributeCaster}.
+      # @option options [<String>] desc
+      # @option options [<String>] value_key the name of the key
+      #   in the repsonse (only needed if the attribute name is
+      #   different than the key in the response)
+      # @option options [<Hash>] options options to be passed to
+      # Class when it is instantiated (when :type is a class)
+      #
+      # @note If no type option is provided, String, is assumed by
+      # the YARD documentation generated. Types other than String
+      # are expected to be explicitely defined.
+      #
+      def attribute(attr, options = {})
+        define_method attr do
+          val = extract_value(attr, options)
+
+          # sideloaded classes need their referrer to properly
+          # cache themselves
+          if options[:options] && options[:options][:self]
+            options[:options][:referrer] = self
+          end
+
+          Ecfr::AttributeCaster.cast_attr(val, options[:type], options[:options] || {})
+        end
+
+        if options[:type] == :boolean
+          define_method "#{attr}?" do
+            val = extract_value(attr, options)
+            Ecfr::AttributeCaster.cast_attr(val, options[:type], options[:options] || {})
+          end
+        end
+      end
+    end
+
+    def self.included(base)
+      base.instance_eval do
+        attr_reader :attributes, :options
+      end
+
+      base.extend(ClassMethods)
+    end
+
+    def initialize(attributes = {}, options = {})
+      @attributes = attributes
+      @options = options
+    end
+
+    private
+
+    #
+    # Returns the value for the requested attribute from the
+    # set of attributes. A value_key option can be passed
+    # for attributes that don't match the key in the response
+    # Return nil if no attributes are present at all (in the
+    # case of metadata this means the key wasn't present in the
+    # response)
+    #
+    # @param [Symbol, String] attr attribute name
+    # @param [Hash] options
+    # @option options [Symbol, String] value_key the key in the
+    #   response to retreive instead of the attribute name
+    #
+    def extract_value(attr, options)
+      return nil unless @attributes
+
+      if options[:value_key]
+        @attributes[options[:value_key].to_s]
+      else
+        @attributes[attr.to_s]
+      end
+    end
+  end
+end

data/lib/ecfr/base.rb

@@ -0,0 +1,71 @@
+module Ecfr
+  class Base < Client
+    include AttributeMethodDefinition
+    include Enumerable
+    extend Extensible
+
+    class_attribute :result_root
+    class_attribute :metadata_accessor
+    self.metadata_accessor = "metadata"
+
+    def self.result_key(key)
+      self.result_root = key.to_s
+    end
+
+    def self.metadata_key(key)
+      self.metadata_accessor = key.to_s
+    end
+
+    def self.basic_auth_client_options
+      {
+        basic_auth: {
+          username: Ecfr.config.ecfr_basic_auth_username,
+          password: Ecfr.config.ecfr_basic_auth_password
+        }
+      }
+    end
+
+    def self.metadata(*metadata)
+      Metadata.attribute(*metadata)
+    end
+
+    attr_reader :metadata, :results, :response_status, :request_data
+
+    SUPPORTED_ARRAY_ACCESSORS = %i[empty? first last size]
+    delegate(*SUPPORTED_ARRAY_ACCESSORS, to: :results)
+    alias_method :all, :results
+
+    def initialize(attributes = {}, options = {})
+      default_options = {base: true}
+      options = default_options.merge(options)
+
+      @response_status = options.delete(:response_status)
+      @request_data = options.delete(:request_data)
+
+      # - handle result_root only if the first time instantiating
+      #     the class from the results
+      # - some responses won't be a parsed attribute hash
+      if options[:base] && attributes.is_a?(Hash)
+        @metadata = Metadata.new(attributes.delete(self.class.metadata_accessor))
+
+        if result_root && attributes[result_root]
+          @results = attributes[result_root].map do |r|
+            self.class.new(r, base: false)
+          end
+        end
+      end
+
+      super(attributes)
+    end
+
+    def each
+      @results.each { |result| yield result }
+    end
+
+    class Metadata
+      include AttributeMethodDefinition
+
+      attr_reader :attributes
+    end
+  end
+end