eml 1.0.0

data/lib/eml/payload.rb

@@ -0,0 +1,137 @@
+# 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 Payload
+    extend T::Sig
+
+    sig { params(payload: T::Hash[Symbol, T.untyped]).void }
+    def initialize(payload)
+      assign_params(payload)
+      validate_required_payload_presence
+    end
+
+    ENDPOINT_CLASS_TYPE = "Payload"
+
+    class << self
+      extend T::Sig
+
+      sig do
+        params(
+          resource_class: T.untyped,
+          endpoint: String,
+          payload: T::Hash[Symbol, T.untyped]
+        ).returns(T.untyped)
+      end
+      def convert(resource_class, endpoint, payload)
+        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,
+          payload: payload, resource_class: resource_class
+        )
+      end
+
+      protected
+
+      sig do
+        params(
+          endpoint_class: T.nilable(T.class_of(EML::Payload)),
+          resource_class: T.untyped,
+          endpoint: String,
+          payload: T::Hash[Symbol, T.untyped]
+        ).returns(T.untyped)
+      end
+      def convert_with_endpoint_class(
+        endpoint_class:, resource_class:, endpoint:, payload:
+      )
+        return endpoint_class.new(payload) unless endpoint_class.nil?
+        return payload if payload.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: Symbol, param_value: String, values: T::Array[String]).
+        void
+    end
+    def validate_enum(param_name, param_value, values)
+      return if values.include?(param_value)
+
+      value_message = values.dup.
+        tap { |vals| vals[-1] = "or #{vals.last}" }.
+        join(", ")
+      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
+
+    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_payload_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_payload_value_presence(param_name)
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    sig { params(value_key: Symbol, object: EML::Payload).void }
+    def validate_required_payload_value_presence(value_key, object: self)
+      names = value_key.to_s.split(".")
+      value = object.instance_variable_get(:"@#{names.shift}")
+
+      if value.nil?
+        raise(
+          ArgumentError,
+          "#{value_key} was not supplied but it is a required field"
+        )
+      end
+
+      if names.length.positive?
+        value_key = names.join(".").to_sym
+        validate_required_payload_value_presence(value_key, object: value)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/eml/response.rb

@@ -0,0 +1,103 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  class Response
+    extend T::Sig
+
+    sig { params(field_name: Symbol).void }
+    def self.field(field_name)
+      define_method(field_name) do
+        string_name = field_name.to_s
+        body[string_name]
+      end
+    end
+
+    sig { params(response: HTTP::Response, id: T.nilable(String)).void }
+    def initialize(response, id: nil)
+      @response = T.let(response, HTTP::Response)
+      @body = T.let(nil, T.nilable(String))
+      @http_status = T.let(nil, T.nilable(Integer))
+      @url = T.let(nil, T.nilable(String))
+      raise_error(id: id) unless http_status == 200
+    end
+
+    # TODO: sometimes we get a string and sometimes a hash. When it's a hash,
+    #       there should be a custom response object
+    sig { returns(T.untyped) }
+    def body
+      @body ||= JSON.parse(@response.body.to_s)
+    rescue JSON::ParserError
+      @body = ""
+    end
+
+    sig { returns(T.nilable(String)) }
+    def error
+      body.fetch("message", nil) if body.respond_to?(:fetch)
+    end
+
+    sig { returns(T::Hash[Symbol, String]) }
+    def headers
+      @response.headers
+    end
+
+    sig { returns(Integer) }
+    def http_status
+      @http_status ||= @response.status.code
+    end
+
+    sig { returns(T::Boolean) }
+    def success?
+      http_status == 200
+    end
+
+    sig { returns(String) }
+    def url
+      @url ||= T.unsafe(@response).url.to_s
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    sig { params(id: T.nilable(String)).returns(EML::RESTError) }
+    def raise_error(id: nil)
+      check_for_incorrectly_categorised_errors
+
+      case http_status
+      when 400
+        raise T.unsafe(EML::REST::BadRequestError).new(error, self)
+      when 401
+        raise T.unsafe(EML::REST::AuthenticationError).new(nil, self)
+      when 403
+        raise T.unsafe(EML::REST::ForbiddenError).new(nil, self)
+      when 404
+        raise T.unsafe(EML::REST::NotFoundError).new(nil, self, id: T.must(id))
+      when 500
+        process_internal_server_error
+        raise T.unsafe(EML::REST::InternalServerError).new(error, self)
+      end
+
+      raise T.unsafe(EML::RESTError).
+        new("Unknown error (#{http_status}): #{error}", self)
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    sig { returns(T.nilable(EML::RESTError)) }
+    def check_for_incorrectly_categorised_errors
+      if error.match?(/is not in (the proper|a valid) status/)
+        raise T.unsafe(EML::REST::UnprocessableEntityError).new(error, self)
+      end
+    end
+
+    sig { returns(T.nilable(EML::RESTError)) }
+    def process_internal_server_error
+      case error
+      when "Card reload could not be completed because it violated the " \
+        "funding limit: 'Daily Max Reload Amount Funding Limit'"
+        raise T.unsafe(EML::REST::DailyFundingLimitError).new(nil, self)
+      when "Invalid username or password."
+        raise T.unsafe(EML::REST::AuthenticationError).new(nil, self)
+      end
+    end
+  end
+end

data/lib/eml/uk.rb

@@ -0,0 +1,51 @@
+# typed: strong
+# frozen_string_literal: true
+
+module EML
+  module UK
+  end
+end
+
+require "eml/uk/api_resource"
+require "eml/uk/config"
+
+require "eml/uk/lib/endpoint_class"
+require "eml/uk/lib/parse_date"
+
+require "eml/uk/model/transaction"
+
+require "eml/uk/parameters"
+require "eml/uk/parameters/agreement/show"
+require "eml/uk/parameters/card/activation"
+require "eml/uk/parameters/card/show"
+require "eml/uk/parameters/card/lock"
+require "eml/uk/parameters/card/register"
+require "eml/uk/parameters/card/reload"
+require "eml/uk/parameters/card/transaction"
+require "eml/uk/parameters/card/unload"
+require "eml/uk/parameters/card/unlock"
+
+require "eml/uk/payload"
+require "eml/uk/payload/agreement/show"
+require "eml/uk/payload/iso"
+require "eml/uk/payload/contactentity"
+require "eml/uk/payload/location"
+require "eml/uk/payload/nil"
+require "eml/uk/payload/card/activation"
+require "eml/uk/payload/card/show"
+require "eml/uk/payload/card/lock"
+require "eml/uk/payload/card/register"
+require "eml/uk/payload/card/reload"
+require "eml/uk/payload/card/transaction"
+require "eml/uk/payload/card/unload"
+require "eml/uk/payload/card/unlock"
+require "eml/uk/payload/card/void"
+
+require "eml/uk/resources/agreement"
+require "eml/uk/resources/card"
+
+require "eml/uk/response"
+require "eml/uk/responses/agreement/show"
+require "eml/uk/responses/card/reload"
+require "eml/uk/responses/card/show"
+require "eml/uk/responses/card/transaction"

data/lib/eml/uk/api_resource.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "cgi"
+
+module EML
+  module UK
+    class APIResource
+      extend T::Sig
+
+      LANGUAGE = "en"
+      private_constant :LANGUAGE
+
+      sig { params(id: T.nilable(String)).void }
+      def initialize(id: nil)
+        @id = T.let(id, T.nilable(String))
+        @headers = T.let(nil, T.nilable(T::Hash[String, String]))
+      end
+
+      sig do
+        params(
+          action: Symbol,
+          endpoint: String,
+          payload: T::Hash[Symbol, T.untyped],
+          params: T::Hash[Symbol, T.untyped]
+        ).returns(EML::Response)
+      end
+      def request(action, endpoint = "", payload: {}, params: {})
+        payload = EML::UK::Payload.convert(self.class, endpoint, payload)
+        params = EML::UK::Parameters.convert(self.class, endpoint, params)
+        url = resource_url(endpoint)
+
+        response = HTTP.headers(headers).
+          public_send(action, url, json: payload.to_h, params: params.to_h)
+        response_class(endpoint).new(response, id: @id)
+      end
+
+      protected
+
+      sig { params(endpoint: String).returns(String) }
+      def resource_url(endpoint)
+        endpoint_base = self.class.const_get(:ENDPOINT_BASE)
+
+        if @id.nil?
+          "#{domain}/#{endpoint_base}/#{endpoint}"
+        else
+          "#{domain}/#{endpoint_base}/#{@id}/#{endpoint}"
+        end
+      end
+
+      private
+
+      sig { returns(T::Hash[Symbol, T.nilable(String)]) }
+      def credentials
+        config = EML::UK.config
+        {
+          username: config.username,
+          password: config.password,
+        }
+      end
+
+      sig { returns(String) }
+      def domain
+        if EML::UK.config.environment.test?
+          "https://webservices.xtest.storefinancial.net/api/v1/#{LANGUAGE}"
+        else
+          "https://webservices.storefinancial.net/api/v1/#{LANGUAGE}"
+        end
+      end
+
+      sig { returns(T::Hash[String, String]) }
+      def headers
+        @headers ||= { "Authorization" => "Basic #{base64_credentials}" }
+      end
+
+      sig { returns(String) }
+      def base64_credentials
+        username = credentials[:username]
+        password = credentials[:password]
+        Base64.encode64("#{username}:#{password}").tr("\n", "")
+      end
+
+      sig { params(endpoint: String).returns(T.class_of(EML::Response)) }
+      def response_class(endpoint)
+        endpoint_class = EML::UK::EndpointClass.(
+          class_type: "Responses",
+          resource_class: self.class,
+          endpoint: endpoint
+        )
+        endpoint_class || EML::Response
+      end
+    end
+  end
+end

data/lib/eml/uk/config.rb

@@ -0,0 +1,52 @@
+# typed: ignore
+# frozen_string_literal: true
+
+module EML
+  module UK
+    class << self
+      extend T::Sig
+
+      sig { void }
+      def configure
+        yield config
+      end
+
+      sig { returns(Config) }
+      def config
+        @config ||= T.let(Config.new, Config)
+      end
+    end
+
+    class Config < ::EML::Config
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_accessor :username
+
+      sig { returns(String) }
+      attr_accessor :password
+
+      sig { returns(String) }
+      attr_accessor :merchant_group
+
+      sig { returns(String) }
+      attr_accessor :program
+
+      sig { returns(String) }
+      attr_accessor :search_parameter
+
+      private
+
+      sig { params(param: Symbol).void }
+      def require_error(param)
+        raise(
+          ArgumentError,
+          "#{param} is required but hasn't been set.\n" \
+            "EML::UK::Config.configuration do |config|\n" +
+            %(  config.#{param} = "value") + "\n" \
+            "end"
+        )
+      end
+    end
+  end
+end

data/lib/eml/uk/lib/endpoint_class.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module EML
+  module UK
+    class EndpointClass < ::EML::EndpointClass
+      extend T::Sig
+
+      private
+
+      sig { returns(String) }
+      def action_class_name
+        return "Show" if @endpoint.empty?
+
+        super
+      end
+    end
+  end
+end