eml 1.0.0

data/lib/eml/environment.rb

@@ -0,0 +1,54 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# Usually this class wouldn't be called directly, the environment can be managed
+# via the EML::Config class or one of it's sub-classes
+module EML
+  class Environment
+    class << self
+      def production?
+        to_sym == :production
+      end
+
+      def test?
+        to_sym == :test
+      end
+
+      def to_sym
+        @to_sym ||= set(default)
+      end
+
+      ENVIRONMENTS = %i[production test].freeze
+
+      def set(value)
+        return @to_sym = value if ENVIRONMENTS.include?(value)
+
+        error_value = value.is_a?(Symbol) ? ":#{value}" : value.to_s
+        raise(
+          ArgumentError,
+          "#{error_value} is not an acceptable environment; " \
+            "please use either :production or :test"
+        )
+      end
+
+      private
+
+      def default
+        return :test if ENV["ENV"] == "test"
+        return rails if rails?
+
+        :production
+      end
+
+      def rails?
+        defined?(Rails)
+      end
+
+      def rails
+        return :production if Rails.env.prod?
+
+        :test
+      end
+    end
+  end
+end

data/lib/eml/error.rb

@@ -0,0 +1,25 @@
+# typed: ignore
+# frozen_string_literal: true
+
+module EML
+  # Error is the base class for more specific EML errors
+  class Error < ::StandardError
+    extend T::Sig
+
+    attr_reader :message
+
+    sig { params(message: T.nilable(String)).void }
+    def initialize(message = nil)
+      @message = T.let(message, T.nilable(String))
+    end
+  end
+end
+
+require "eml/error/rest"
+require "eml/error/rest/authentication"
+require "eml/error/rest/bad_request"
+require "eml/error/rest/daily_funding_limit"
+require "eml/error/rest/forbidden"
+require "eml/error/rest/internal_server"
+require "eml/error/rest/not_found"
+require "eml/error/rest/unprocessable_entity"

data/lib/eml/error/rest.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  # RESTError is the parent class for errors related to connections to the EML
+  # REST Web Services APIs
+  class RESTError < Error
+    extend T::Sig
+
+    sig do
+      params(
+        message: T.nilable(String),
+        response: T.nilable(EML::Response)
+      ).void
+    end
+    def initialize(message = nil, response = nil)
+      super(message)
+
+      @response = T.let(response, EML::Response)
+    end
+
+    sig { returns(String) }
+    def http_body
+      @response.error || @response.body.to_s
+    end
+
+    sig { returns(T::Hash[Symbol, String]) }
+    def http_headers
+      @response.headers
+    end
+
+    sig { returns(Integer) }
+    def http_status
+      @response.status
+    end
+
+    sig { returns(String) }
+    def url
+      @response.url.to_s
+    end
+  end
+end

data/lib/eml/error/rest/authentication.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class AuthenticationError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response)
+        ).void
+      end
+      def initialize(message = nil, response = nil)
+        message ||= "Your credentials were rejected by the server. " \
+          "Please confirm you have set your username and password in the " \
+          "appropriate country configuration"
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/error/rest/bad_request.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class BadRequestError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response)
+        ).void
+      end
+      def initialize(message = nil, response = nil)
+        message ||= "The request could not be Fault information understood " \
+          "by the server due to malformed syntax"
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/error/rest/daily_funding_limit.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class DailyFundingLimitError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response)
+        ).void
+      end
+      def initialize(message = nil, response = nil)
+        message ||= "The daily maximum load amount has been reached"
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/error/rest/forbidden.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class ForbiddenError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response)
+        ).void
+      end
+      def initialize(message = nil, response = nil)
+        message ||= response&.body&.fetch("message", nil)
+        message ||= "The user is not authorised to perform the action"
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/error/rest/internal_server.rb

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class InternalServerError < ::EML::RESTError
+    end
+  end
+end

data/lib/eml/error/rest/not_found.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class NotFoundError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response),
+          id: String
+        ).void
+      end
+      def initialize(message = nil, response = nil, id:)
+        message ||= %(A record could not be found with ID "#{id}")
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/error/rest/unprocessable_entity.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module REST
+    class UnprocessableEntityError < ::EML::RESTError
+      sig do
+        params(
+          message: T.nilable(String),
+          response: T.nilable(EML::Response)
+        ).void
+      end
+      def initialize(message = nil, response = nil)
+        message ||= "The server understood the request but it could not be " \
+          "processed (possibly semantically erroneous)"
+        super(message, response)
+      end
+    end
+  end
+end

data/lib/eml/lib/endpoint_class.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  class EndpointClass
+    extend T::Sig
+
+    def self.call(class_type:, resource_class:, endpoint:)
+      new(
+        class_type: class_type,
+        resource_class: resource_class,
+        endpoint: endpoint
+      ).call
+    end
+
+    def initialize(class_type:, resource_class:, endpoint:)
+      @class_type = class_type
+      @resource_class = resource_class
+      @endpoint = endpoint
+    end
+
+    def call
+      Object.const_get(class_name) if Object.const_defined?(class_name)
+    end
+
+    private
+
+    def class_name
+      @class_name ||= begin
+        name_parts = @resource_class.name.split("::")
+        name = name_parts[0..-2] << @class_type
+        name << name_parts.last
+        name << action_class_name
+        name.join("::")
+      end
+    end
+
+    def action_class_name
+      @endpoint.capitalize.sub(/s$/, "")
+    end
+  end
+end

data/lib/eml/parameters.rb

@@ -0,0 +1,153 @@
+# typed: strict
+# frozen_string_literal: true
+
+# A payload is the data sent in the body of a request such as POST or PUT
+module EML
+  class Parameters
+    extend T::Sig
+
+    sig { params(params: T::Hash[Symbol, T.untyped]).void }
+    def initialize(params)
+      assign_params(params)
+      validate_required_params_presence
+    end
+
+    ENDPOINT_CLASS_TYPE = "Parameters"
+
+    class << self
+      extend T::Sig
+
+      sig do
+        params(
+          resource_class: T.untyped,
+          endpoint: String,
+          params: T::Hash[Symbol, T.untyped]
+        ).returns(T.untyped)
+      end
+      def self.convert(resource_class, endpoint, params)
+        endpoint_class = EML::EndpointClass.(
+          class_type: ENDPOINT_CLASS_TYPE, resource_class: resource_class,
+          endpoint: endpoint
+        )
+
+        convert_with_endpoint_class(
+          endpoint: endpoint, endpoint_class: endpoint_class,
+          resource_class: resource_class, params: params
+        )
+      end
+
+      protected
+
+      sig do
+        params(
+          endpoint_class: T.nilable(T.class_of(EML::Parameters)),
+          resource_class: T.untyped,
+          endpoint: String,
+          params: T::Hash[Symbol, T.untyped]
+        ).returns(T.untyped)
+      end
+      def convert_with_endpoint_class(
+        endpoint_class:, resource_class:, endpoint:, params:
+      )
+        return endpoint_class.new(params) unless endpoint_class.nil?
+        return params if params.empty?
+
+        message = "No endpoint class can be found for resource, " \
+          "#{resource_class}, with endpoint #{endpoint}"
+        raise ArgumentError, message
+      end
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      instance_variables.each_with_object({}) do |variable_name, params|
+        key = variable_name.to_s[1..-1].to_sym
+        params[key] = instance_variable_get(variable_name)
+        params[key] = params[key].to_h if params[key].respond_to?(:to_h)
+      end
+    end
+
+    protected
+
+    sig do
+      params(
+        param_name: String,
+        param_value: String,
+        allowed_values: T::Array[String]
+      ).void
+    end
+    def validate_array(param_name, param_value, allowed_values)
+      return if allowed_values.include?(param_value)
+
+      error_message = "#{param_name} can include any of " \
+        "#{array_as_string(allowed_values)} but included #{param_value}"
+      raise ArgumentError, error_message
+    end
+
+    sig do
+      params(param_name: Symbol, param_value: String, allowed_values: T::Array[String]).
+        void
+    end
+    def validate_enum(param_name, param_value, allowed_values)
+      return if allowed_values.include?(param_value)
+
+      value_message = array_as_string(allowed_values)
+      raise(ArgumentError, "#{param_name} must be one of #{value_message}")
+    end
+
+    sig do
+      params(param_name: Symbol, param_value: String, length: Integer).void
+    end
+    def validate_max_length(param_name, param_value, length)
+      return if param_value.to_s.length <= length
+
+      raise(
+        ArgumentError,
+        "#{param_name} is expected to be no more than #{length} characters"
+      )
+    end
+
+    private
+
+    def array_as_string(array)
+      array.dup.tap { |vals| vals[-1] = "or #{vals.last}" }.join(", ")
+    end
+
+    sig { params(params: T::Hash[Symbol, T.untyped]).void }
+    def assign_params(params)
+      params.each do |name, value|
+        __send__(:"#{name}=", value)
+      end
+    end
+
+    sig { void }
+    def validate_required_params_presence
+      return unless self.class.const_defined?(:REQUIRED_VALUES)
+
+      required_params = self.class.const_get(:REQUIRED_VALUES)
+      required_params.each do |param_name|
+        validate_required_parameter_presence(param_name)
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    sig { params(param_name: Symbol, object: EML::Parameters).void }
+    def validate_required_parameter_presence(param_name, object: self)
+      names = param_name.to_s.split(".")
+      value = object.instance_variable_get(:"@#{names.shift}")
+
+      if value.nil?
+        raise(
+          ArgumentError,
+          "#{param_name} was not supplied but it is a required field"
+        )
+      end
+
+      if names.length.positive?
+        param_name = names.join(".").to_sym
+        validate_required_parameter_presence(param_name, object: value)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end