elia_ruby 0.1.0

data/lib/elia/mcc/serializer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Serializer for MCC codes and related objects
+    #
+    # Provides consistent JSON/Hash representations for API responses.
+    class Serializer
+      DEFAULT_CODE_OPTIONS = {
+        include_all_descriptions: false,
+        include_categories: true,
+        include_range: true,
+      }.freeze
+
+      # Serializes a Code object
+      #
+      # @param code [Code] the code to serialize
+      # @param options [Hash] serialization options
+      # @option options [Boolean] :include_all_descriptions (false) include all source descriptions
+      # @option options [Boolean] :include_categories (true) include category data
+      # @option options [Boolean] :include_range (true) include range data
+      # @return [Hash] the serialized code
+      def self.serialize_code(code, options = {})
+        options = DEFAULT_CODE_OPTIONS.merge(options)
+        result = base_code_hash(code)
+        result.merge!(all_descriptions_hash(code)) if options[:include_all_descriptions]
+        result[:categories] = code.categories.map(&:id) if options[:include_categories]
+        result[:range] = code.range&.name if options[:include_range]
+        result
+      end
+
+      def self.base_code_hash(code)
+        { mcc: code.mcc, description: code.description,
+          stripe_code: code.stripe_code, irs_reportable: code.irs_reportable?, }
+      end
+
+      def self.all_descriptions_hash(code)
+        { iso_description: code.iso_description, usda_description: code.usda_description,
+          stripe_description: code.stripe_description, visa_description: code.visa_description,
+          visa_clearing_name: code.visa_clearing_name, mastercard_description: code.mastercard_description,
+          amex_description: code.amex_description, alipay_description: code.alipay_description,
+          irs_description: code.irs_description, }
+      end
+
+      private_class_method :base_code_hash, :all_descriptions_hash
+
+      # Serializes a Category object
+      #
+      # @param category [Category] the category to serialize
+      # @param options [Hash] serialization options
+      # @return [Hash] the serialized category
+      def self.serialize_category(category, options = {})
+        result = {
+          id: category.id,
+          name: category.name,
+          description: category.description,
+        }
+
+        result[:codes] = category.codes if options[:include_codes]
+
+        result
+      end
+
+      # Serializes a Range object
+      #
+      # @param range [Range] the range to serialize
+      # @param options [Hash] serialization options
+      # @return [Hash] the serialized range
+      def self.serialize_range(range, _options = {})
+        {
+          start_code: range.start_code,
+          end_code: range.end_code,
+          name: range.name,
+          description: range.description,
+          reserved: range.reserved?,
+        }
+      end
+
+      # Serializes a collection of codes
+      #
+      # @param codes [Array<Code>] the codes to serialize
+      # @param options [Hash] serialization options
+      # @return [Array<Hash>] the serialized codes
+      def self.serialize_collection(codes, options = {})
+        codes.map { |code| serialize_code(code, options) }
+      end
+    end
+  end
+end

data/lib/elia/mcc/validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Standalone validator for MCC codes
+    #
+    # Can be used independently of ActiveModel for basic validation.
+    #
+    # @example Basic usage
+    #   validator = Elia::Mcc::Validator.new
+    #   validator.valid?("5411")  # => true
+    #   validator.valid?("XXXX")  # => false
+    #
+    # @example With category restrictions
+    #   validator = Elia::Mcc::Validator.new(deny_categories: [:gambling, :adult])
+    #   validator.valid?("7995")  # => false (gambling)
+    class Validator
+      # Default error messages
+      MESSAGES = {
+        invalid_format: "must be a valid 4-digit MCC code",
+        not_found: "is not a recognized MCC code",
+        denied_category: "is in a denied category",
+      }.freeze
+
+      # @return [Hash] validation options
+      attr_reader :options
+
+      # Creates a new Validator instance
+      #
+      # @param options [Hash] validation options
+      # @option options [Boolean] :strict (true) require code to exist in registry
+      # @option options [Array<Symbol>] :deny_categories categories to reject
+      # @option options [Array<Symbol>] :allow_categories only allow these categories
+      def initialize(options = {})
+        @options = {
+          strict: true,
+          deny_categories: [],
+          allow_categories: nil,
+        }.merge(options)
+      end
+
+      # Validates the given value
+      #
+      # @param value [String, Integer, nil] the value to validate
+      # @return [Array<String>] error messages (empty if valid)
+      def validate(value)
+        errors = []
+
+        return errors if value.nil?
+
+        # Check format
+        unless valid_format?(value)
+          errors << MESSAGES[:invalid_format]
+          return errors
+        end
+
+        # Check if code exists (strict mode)
+        if options[:strict]
+          code = Elia::Mcc.find(value)
+          if code.nil?
+            errors << MESSAGES[:not_found]
+            return errors
+          end
+
+          # Check category restrictions
+          if options[:deny_categories].any?
+            denied = options[:deny_categories].any? { |cat| code.in_category?(cat) }
+            errors << MESSAGES[:denied_category] if denied
+          end
+
+          if options[:allow_categories]
+            allowed = options[:allow_categories].any? { |cat| code.in_category?(cat) }
+            errors << MESSAGES[:denied_category] unless allowed
+          end
+        end
+
+        errors
+      end
+
+      # Returns whether the value is valid
+      #
+      # @param value [String, Integer, nil] the value to validate
+      # @return [Boolean] true if valid
+      def valid?(value)
+        validate(value).empty?
+      end
+
+      private
+
+      # Checks if the value has a valid MCC format
+      #
+      # @param value [String, Integer, nil] the value to check
+      # @return [Boolean] true if the format is valid
+      def valid_format?(value)
+        return false if value.nil?
+
+        normalized = value.to_s.strip
+        normalized.match?(/\A\d{1,4}\z/)
+      end
+    end
+  end
+end

data/lib/elia/mcc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    VERSION = "0.1.0"
+  end
+end

data/lib/elia/mcc.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Elia
+  # MCC (Merchant Category Code) module provides tools for working with
+  # payment industry merchant category codes, including validation,
+  # categorization, and risk assessment.
+  module Mcc
+    class << self
+      # Returns the configuration object for the Mcc module
+      #
+      # @return [Configuration] the configuration instance
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Yields the configuration object for block-based configuration
+      #
+      # @yield [Configuration] the configuration instance
+      # @return [Configuration] the configuration instance
+      def configure
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      # Resets the configuration to defaults and clears the collection cache
+      #
+      # @return [Configuration] a new configuration instance
+      def reset!
+        @configuration = Configuration.new
+        @collection = nil
+        @configuration
+      end
+
+      alias reset_configuration! reset!
+
+      # Delegate query methods to Collection
+      delegate :all, :find, :find!, :[], :where, :in_range, :search,
+               :in_category, :valid?, :count, :size, :reload!,
+               to: :collection
+
+      # Returns all ISO 18245 ranges
+      #
+      # @return [Array<Range>] all ranges
+      def ranges
+        collection.all_ranges
+      end
+
+      # Returns all risk categories
+      #
+      # @return [Array<Category>] all categories
+      def categories
+        collection.all_categories
+      end
+
+      private
+
+      # Returns the collection instance, creating it if necessary
+      #
+      # @return [Collection] the collection instance
+      def collection
+        @collection ||= Collection.new
+      end
+    end
+  end
+end

data/lib/elia_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Elia
+  VERSION = "0.1.0"
+end

data/lib/elia_ruby.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "active_support"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/blank"
+
+# Define the Elia module at the top level
+module Elia
+  class Error < StandardError; end
+end
+
+require_relative "elia_ruby/version"
+
+# Set up Zeitwerk loader for Elia::Mcc namespace
+loader = Zeitwerk::Loader.new
+loader.tag = "elia_mcc"
+loader.push_dir(File.expand_path("elia", __dir__), namespace: Elia)
+
+# Ignore files that don't follow Zeitwerk conventions
+loader.ignore(File.expand_path("elia/mcc/version.rb", __dir__))
+loader.ignore(File.expand_path("elia/mcc/errors.rb", __dir__))
+loader.ignore(File.expand_path("elia/mcc/railtie.rb", __dir__))
+loader.ignore(File.expand_path("elia/mcc/active_model_validator.rb", __dir__))
+loader.ignore(File.expand_path("elia/mcc/data", __dir__))
+
+loader.setup
+
+# Load files that don't follow Zeitwerk conventions manually
+require_relative "elia/mcc/version"
+require_relative "elia/mcc/errors"
+require_relative "elia/mcc"
+
+# Load the Railtie if Rails is present
+require_relative "elia/mcc/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: elia_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Elia Pay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A comprehensive library for working with Merchant Category Codes (MCC),
+  including validation, categorization, and risk assessment.
+email: support@eliapay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/elia/mcc.rb
+- lib/elia/mcc/active_model_validator.rb
+- lib/elia/mcc/category.rb
+- lib/elia/mcc/code.rb
+- lib/elia/mcc/collection.rb
+- lib/elia/mcc/configuration.rb
+- lib/elia/mcc/data/.gitkeep
+- lib/elia/mcc/data/mcc_codes.yml
+- lib/elia/mcc/data/ranges.yml
+- lib/elia/mcc/data/risk_categories.yml
+- lib/elia/mcc/errors.rb
+- lib/elia/mcc/railtie.rb
+- lib/elia/mcc/range.rb
+- lib/elia/mcc/serializer.rb
+- lib/elia/mcc/validator.rb
+- lib/elia/mcc/version.rb
+- lib/elia_ruby.rb
+- lib/elia_ruby/version.rb
+homepage: https://github.com/eliapay/elia-ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/eliapay/elia-ruby/issues
+  changelog_uri: https://github.com/eliapay/elia-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/eliapay/elia-ruby#readme
+  github_repo: ssh://github.com/eliapay/elia-ruby
+  homepage_uri: https://github.com/eliapay/elia-ruby
+  source_code_uri: https://github.com/eliapay/elia-ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: MCC (Merchant Category Code) library for payment processing
+test_files: []