elia_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49ae65cb7eaefca01091ebcc4f6b23a6030459ebc92d23e3d1cf89296ac91a01
+  data.tar.gz: d27b6d6b4418647ef1609f20cb6174eda07d83f33c6b96bf6112913823c7711a
+SHA512:
+  metadata.gz: 31265e6712f5095ba8dd6329c468e3265df7a20e3db31a97134f8953395454dbecaec7a479d1aa745f409942958aa2597bf63c1c15550990eb78efd920cc8a89
+  data.tar.gz: d9a7358755aa6582481abe977820f4d160b8416b5865dd829c26cbcde70a849f73448f79c8be642b202f2f25d742252aa11cccdf47b2cadabfad588ecdf30f65

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Elia Pay SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# Elia Ruby
+
+A comprehensive Ruby gem for working with Merchant Category Codes (MCC) in payment processing. Provides validation, categorization, risk assessment, and multi-source data aggregation.
+
+## Features
+
+- **Multi-source MCC data** - Aggregates descriptions from ISO 18245, USDA, Stripe, Visa, Mastercard, American Express, Alipay, and IRS
+- **Risk categories** - Pre-defined categories for payment control (gambling, airlines, adult, crypto, etc.)
+- **ISO 18245 ranges** - Standard category ranges from the official specification
+- **Fuzzy search** - Search across all descriptions to find relevant MCCs
+- **Rails integration** - ActiveModel validators and serializers
+- **IRS reportable flags** - Know which MCCs require 1099-K reporting
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elia_ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install elia_ruby
+```
+
+## Usage
+
+### Basic Lookup
+
+```ruby
+require 'elia_ruby'
+
+# Find an MCC
+code = Elia::Mcc.find("5411")
+code.mcc                    # => "5411"
+code.iso_description        # => "Grocery Stores, Supermarkets"
+code.stripe_code            # => "grocery_stores_supermarkets"
+code.irs_reportable?        # => false
+
+# Strict lookup (raises if not found)
+Elia::Mcc.find!("5411")     # => Elia::Mcc::Code
+Elia::Mcc.find!("99999")    # => raises Elia::Mcc::NotFound
+
+# Shorthand
+Elia::Mcc["5411"]           # => same as find
+```
+
+### Collections and Queries
+
+```ruby
+# Get all MCCs
+Elia::Mcc.all                          # => Array of all codes
+
+# Filter by attributes
+Elia::Mcc.where(irs_reportable: true)  # => IRS reportable codes
+
+# Range queries
+Elia::Mcc.in_range("5000", "5999")     # => Retail MCCs
+
+# Search descriptions
+Elia::Mcc.search("restaurant")         # => fuzzy search results
+```
+
+### Risk Categories
+
+```ruby
+# Available categories
+Elia::Mcc.categories  # => [:airlines, :gambling, :adult, :crypto, ...]
+
+# Get codes in a category
+Elia::Mcc.in_category(:gambling)       # => gambling-related MCCs
+Elia::Mcc.in_category(:airlines)       # => airline MCCs only
+
+# Check a code's categories
+code = Elia::Mcc.find("7995")
+code.categories                        # => [:gambling]
+code.in_category?(:gambling)           # => true
+```
+
+### ISO 18245 Ranges
+
+```ruby
+# Get all ranges
+Elia::Mcc.ranges  # => Array of Elia::Mcc::Range objects
+
+# Check a code's range
+code = Elia::Mcc.find("5411")
+code.range.name   # => "Retail Outlets"
+```
+
+### Validation
+
+```ruby
+# Check if valid
+Elia::Mcc.valid?("5411")   # => true
+Elia::Mcc.valid?("99999")  # => false
+```
+
+### Rails Integration
+
+#### ActiveModel Validator
+
+```ruby
+class Transaction < ApplicationRecord
+  validates :mcc_code, mcc: true
+
+  # Or with category restrictions
+  validates :mcc_code, mcc: {
+    deny_categories: [:gambling, :adult],
+    message: "category is blocked"
+  }
+end
+```
+
+#### Configuration
+
+```ruby
+# config/initializers/elia_mcc.rb
+Elia::Mcc.configure do |config|
+  config.default_description_source = :stripe  # or :iso, :visa, etc.
+  config.include_reserved_ranges = false
+end
+```
+
+### Code Attributes
+
+```ruby
+code = Elia::Mcc.find("5411")
+
+# Core
+code.mcc                     # => "5411"
+
+# Multi-source descriptions
+code.iso_description
+code.usda_description
+code.stripe_description
+code.stripe_code             # => programmatic identifier
+code.visa_description
+code.visa_clearing_name
+code.mastercard_description
+code.amex_description
+code.alipay_description
+
+# IRS
+code.irs_description
+code.irs_reportable?
+
+# Categorization
+code.range                   # => Elia::Mcc::Range
+code.categories              # => Array of symbols
+
+# Serialization
+code.to_h                    # => Hash with all attributes
+code.as_json                 # => JSON-ready hash
+```
+
+## Data Sources
+
+This gem aggregates MCC data from multiple authoritative sources:
+
+- **ISO 18245:2023** - The official international standard for MCC definitions
+- **USDA** - Comprehensive list including private-use ranges
+- **Stripe** - Descriptions with programmatic codes
+- **Visa** - Descriptions with clearing names
+- **Mastercard** - Descriptions with abbreviated names
+- **American Express** - Descriptions
+- **Alipay** - Descriptions
+- **IRS** - Reportable flags for 1099-K compliance
+
+## Inspiration and Credits
+
+This gem was inspired by and incorporates ideas from several excellent projects:
+
+- [python-iso18245](https://github.com/alubbock/python-iso18245) - Comprehensive Python MCC library with multi-source data aggregation
+- [mcc-ruby](https://github.com/singlebrook/mcc-ruby) - Ruby gem with IRS reportable data
+- [mcc](https://github.com/maximbilan/mcc) - MCC data collection by Maxim Bilan
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eliapay/elia-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/elia/mcc/active_model_validator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+# ActiveModel validator for MCC codes
+#
+# @example Basic usage
+#   class Transaction < ApplicationRecord
+#     validates :mcc_code, mcc: true
+#   end
+#
+# @example With category restrictions
+#   class Transaction < ApplicationRecord
+#     validates :mcc_code, mcc: { deny_categories: [:gambling, :adult] }
+#   end
+#
+# @example With custom message
+#   class Transaction < ApplicationRecord
+#     validates :mcc_code, mcc: {
+#       deny_categories: [:gambling],
+#       message: "category is blocked"
+#     }
+#   end
+class MccValidator < ActiveModel::EachValidator
+  # Validates an attribute on a record
+  #
+  # @param record [Object] the record being validated
+  # @param attribute [Symbol] the attribute name
+  # @param value [Object] the attribute value
+  def validate_each(record, attribute, value)
+    return if value.blank? && options[:allow_blank]
+
+    validator = Elia::Mcc::Validator.new(validator_options)
+    errors = validator.validate(value)
+
+    errors.each do |message|
+      record.errors.add(attribute, options[:message] || message)
+    end
+  end
+
+  private
+
+  def validator_options
+    {
+      strict: options.fetch(:strict, true),
+      deny_categories: Array(options[:deny_categories]),
+      allow_categories: options[:allow_categories],
+    }
+  end
+end

data/lib/elia/mcc/category.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Represents a risk category for MCC codes
+    #
+    # Categories help organize MCC codes by risk level, industry type,
+    # or other business classification criteria for payment controls.
+    class Category
+      # @return [Symbol] unique identifier for this category
+      attr_reader :id
+
+      # @return [String] human-readable name
+      attr_reader :name
+
+      # @return [String] detailed description
+      attr_reader :description
+
+      # @return [Array<String>] array of codes and ranges (e.g., "7995" or "3000-3350")
+      attr_reader :codes
+
+      # Creates a new Category instance
+      #
+      # @param attributes [Hash] the category attributes
+      # @option attributes [String, Symbol] :id unique identifier
+      # @option attributes [String] :name human-readable name
+      # @option attributes [String] :description detailed description
+      # @option attributes [Array<String>] :codes array of codes and ranges
+      def initialize(attributes = {})
+        attributes = attributes.transform_keys(&:to_sym)
+
+        @id = attributes[:id].to_sym
+        @name = attributes[:name].to_s
+        @description = attributes[:description].to_s
+        @codes = Array(attributes[:codes]).map(&:to_s)
+      end
+
+      # Returns whether the given MCC code is in this category
+      # Supports individual codes ("7995") and ranges ("3000-3350")
+      #
+      # @param mcc [String, Integer, Code] the code to check
+      # @return [Boolean] true if the code is in this category
+      def include?(mcc)
+        code = mcc.respond_to?(:mcc) ? mcc.mcc : mcc
+        normalized = code.to_s.strip.rjust(4, "0")
+
+        codes.any? do |entry|
+          if entry.include?("-")
+            # Range entry like "3000-3350"
+            start_code, end_code = entry.split("-").map { |c| c.strip.rjust(4, "0") }
+            normalized.between?(start_code, end_code)
+          else
+            # Individual code like "7995"
+            entry.strip.rjust(4, "0") == normalized
+          end
+        end
+      end
+
+      alias cover? include?
+
+      # Returns whether this category equals another
+      #
+      # @param other [Category] the category to compare
+      # @return [Boolean] true if the categories are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        id == other.id
+      end
+
+      alias eql? ==
+
+      # Returns a hash code for this instance
+      #
+      # @return [Integer] the hash code
+      def hash
+        id.hash
+      end
+
+      # Returns a human-readable representation
+      #
+      # @return [String] the inspection string
+      def inspect
+        "#<#{self.class.name} id=#{id.inspect} name=#{name.inspect} codes_count=#{codes.size}>"
+      end
+
+      # Returns the category as a string
+      #
+      # @return [String] the category name
+      def to_s
+        name
+      end
+
+      # Returns a hash representation
+      #
+      # @return [Hash] the category as a hash
+      def to_h
+        {
+          id: id,
+          name: name,
+          description: description,
+          codes: codes,
+        }
+      end
+    end
+  end
+end

data/lib/elia/mcc/code.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Represents a single Merchant Category Code (MCC)
+    #
+    # MCC codes are 4-digit numbers used to classify businesses
+    # by the type of goods or services they provide.
+    class Code
+      # @return [String] the 4-digit MCC code
+      attr_reader :mcc
+
+      # @return [String, nil] Official ISO 18245 description
+      attr_reader :iso_description
+
+      # @return [String, nil] USDA description
+      attr_reader :usda_description
+
+      # @return [String, nil] Stripe API description
+      attr_reader :stripe_description
+
+      # @return [String, nil] Stripe's snake_case identifier
+      attr_reader :stripe_code
+
+      # @return [String, nil] Visa description
+      attr_reader :visa_description
+
+      # @return [String, nil] Visa's abbreviated clearing name
+      attr_reader :visa_clearing_name
+
+      # @return [String, nil] Mastercard description
+      attr_reader :mastercard_description
+
+      # @return [String, nil] American Express description
+      attr_reader :amex_description
+
+      # @return [String, nil] Alipay description
+      attr_reader :alipay_description
+
+      # @return [String, nil] IRS description for tax reporting
+      attr_reader :irs_description
+
+      # @return [Boolean, nil] Whether transactions are reportable under IRS 6050W
+      attr_reader :irs_reportable
+
+      # Description source mapping
+      DESCRIPTION_FIELDS = {
+        iso: :iso_description,
+        usda: :usda_description,
+        stripe: :stripe_description,
+        visa: :visa_description,
+        mastercard: :mastercard_description,
+        amex: :amex_description,
+        alipay: :alipay_description,
+        irs: :irs_description,
+      }.freeze
+
+      # Creates a new Code instance
+      #
+      # @param attributes [Hash] the code attributes
+      # @option attributes [String, Integer] :mcc the 4-digit MCC code
+      # @option attributes [String] :iso_description Official ISO 18245 description
+      # @option attributes [String] :usda_description USDA description
+      # @option attributes [String] :stripe_description Stripe API description
+      # @option attributes [String] :stripe_code Stripe's snake_case identifier
+      # @option attributes [String] :visa_description Visa description
+      # @option attributes [String] :visa_clearing_name Visa's clearing name
+      # @option attributes [String] :mastercard_description Mastercard description
+      # @option attributes [String] :amex_description American Express description
+      # @option attributes [String] :alipay_description Alipay description
+      # @option attributes [String] :irs_description IRS description
+      # @option attributes [Boolean] :irs_reportable Whether IRS reportable
+      # @raise [InvalidCode] if the code format is invalid
+      def initialize(attributes = {})
+        attributes = attributes.transform_keys(&:to_sym)
+
+        @mcc = normalize_code(attributes[:mcc])
+        @iso_description = attributes[:iso_description]&.to_s.presence
+        @usda_description = attributes[:usda_description]&.to_s.presence
+        @stripe_description = attributes[:stripe_description]&.to_s.presence
+        @stripe_code = attributes[:stripe_code]&.to_s.presence
+        @visa_description = attributes[:visa_description]&.to_s.presence
+        @visa_clearing_name = attributes[:visa_clearing_name]&.to_s.presence
+        @mastercard_description = attributes[:mastercard_description]&.to_s.presence
+        @amex_description = attributes[:amex_description]&.to_s.presence
+        @alipay_description = attributes[:alipay_description]&.to_s.presence
+        @irs_description = attributes[:irs_description]&.to_s.presence
+        @irs_reportable = attributes[:irs_reportable]
+      end
+
+      # Returns whether this code is IRS reportable
+      #
+      # @return [Boolean] true if the code is IRS reportable
+      def irs_reportable?
+        @irs_reportable == true
+      end
+
+      # Returns the description based on the configured default source
+      # Falls back through sources if the default is blank
+      #
+      # @param source [Symbol, nil] override the default source
+      # @return [String, nil] the description
+      def description(source: nil)
+        source ||= Elia::Mcc.configuration.default_description_source
+
+        # Try the requested source first
+        field = DESCRIPTION_FIELDS[source]
+        result = send(field) if field
+
+        return result if result.present?
+
+        # Fall back through other sources in order
+        DESCRIPTION_FIELDS.each_value do |field_name|
+          result = send(field_name)
+          return result if result.present?
+        end
+
+        nil
+      end
+
+      # Returns the ISO 18245 range this code belongs to
+      #
+      # @return [Range, nil] the range containing this code
+      def range
+        Elia::Mcc.ranges.find { |r| r.include?(mcc) }
+      end
+
+      # Returns all categories this code belongs to
+      #
+      # @return [Array<Category>] the categories containing this code
+      def categories
+        Elia::Mcc.categories.select { |c| c.include?(mcc) }
+      end
+
+      # Returns whether this code is in the given category
+      #
+      # @param category [Category, Symbol, String] the category to check
+      # @return [Boolean] true if in the category
+      def in_category?(category)
+        category_id = case category
+                      when Category then category.id
+                      when Symbol then category
+                      else category.to_s.to_sym
+                      end
+
+        Elia::Mcc.in_category(category_id).any? { |c| c.mcc == mcc }
+      end
+
+      # Returns whether this code matches the given value
+      #
+      # @param other [String, Integer, Code] the value to compare
+      # @return [Boolean] true if the codes match
+      def ==(other)
+        case other
+        when Code
+          mcc == other.mcc
+        when String, Integer
+          mcc == normalize_code(other)
+        else
+          false
+        end
+      end
+
+      alias eql? ==
+
+      # Returns a hash code for this instance
+      #
+      # @return [Integer] the hash code
+      def hash
+        mcc.hash
+      end
+
+      # Returns the code as an integer
+      #
+      # @return [Integer] the numeric value of the code
+      def to_i
+        mcc.to_i
+      end
+
+      # Returns the code as a string
+      #
+      # @return [String] the 4-digit code string
+      def to_s
+        mcc
+      end
+
+      # Returns a human-readable representation
+      #
+      # @return [String] the inspection string
+      def inspect
+        "#<#{self.class.name} mcc=#{mcc.inspect} description=#{description.inspect}>"
+      end
+
+      # Returns a hash representation of all attributes
+      #
+      # @return [Hash] all attributes as a hash
+      def to_h
+        {
+          mcc: mcc,
+          iso_description: iso_description,
+          usda_description: usda_description,
+          stripe_description: stripe_description,
+          stripe_code: stripe_code,
+          visa_description: visa_description,
+          visa_clearing_name: visa_clearing_name,
+          mastercard_description: mastercard_description,
+          amex_description: amex_description,
+          alipay_description: alipay_description,
+          irs_description: irs_description,
+          irs_reportable: irs_reportable,
+        }
+      end
+
+      # Returns a JSON-compatible hash representation
+      #
+      # @param options [Hash] JSON options (unused, for compatibility)
+      # @return [Hash] JSON-compatible hash
+      def as_json(_options = {})
+        to_h.merge(
+          description: description,
+          categories: categories.map(&:id),
+          range: range&.name
+        )
+      end
+
+      private
+
+      # Normalizes a code value to a 4-digit string
+      #
+      # @param value [String, Integer] the value to normalize
+      # @return [String] the normalized 4-digit string
+      # @raise [InvalidCode] if the value cannot be normalized
+      def normalize_code(value)
+        normalized = value.to_s.strip.rjust(4, "0")
+
+        raise InvalidCode, value unless normalized.match?(/\A\d{4}\z/)
+
+        normalized
+      end
+    end
+  end
+end