elia_ruby 0.1.0

data/lib/elia/mcc/data/ranges.yml

@@ -0,0 +1,126 @@
+# ISO 18245 MCC Ranges
+# Defines the standard industry classification ranges for Merchant Category Codes
+# Source: ISO 18245 Standard
+---
+- start: "0000"
+  end: "0699"
+  name: "Reserved"
+  description: "Reserved for ISO use"
+  reserved: true
+
+- start: "0700"
+  end: "0999"
+  name: "Agricultural Services"
+  description: "Agricultural services including veterinary and horticultural services"
+  reserved: false
+
+- start: "1000"
+  end: "1499"
+  name: "Reserved"
+  description: "Reserved for future use"
+  reserved: true
+
+- start: "1500"
+  end: "2999"
+  name: "Contracted Services"
+  description: "Contracted services including general and specialty construction contractors"
+  reserved: false
+
+- start: "3000"
+  end: "3350"
+  name: "Airlines"
+  description: "Specific airline codes for major carriers"
+  reserved: false
+  private_use: true
+
+- start: "3351"
+  end: "3500"
+  name: "Car Rentals"
+  description: "Specific car rental company codes"
+  reserved: false
+  private_use: true
+
+- start: "3501"
+  end: "3999"
+  name: "Lodging"
+  description: "Specific hotel and lodging establishment codes"
+  reserved: false
+  private_use: true
+
+- start: "4000"
+  end: "4799"
+  name: "Transportation"
+  description: "Transportation services including railroads, airlines, buses, and freight"
+  reserved: false
+
+- start: "4800"
+  end: "4999"
+  name: "Utilities"
+  description: "Utility services including telecommunications, electricity, gas, and water"
+  reserved: false
+
+- start: "5000"
+  end: "5599"
+  name: "Retail Outlets"
+  description: "Retail outlets including wholesale, department stores, and specialty retail"
+  reserved: false
+
+- start: "5600"
+  end: "5699"
+  name: "Clothing Outlets"
+  description: "Clothing and apparel stores"
+  reserved: false
+
+- start: "5700"
+  end: "5999"
+  name: "Miscellaneous Retail"
+  description: "Miscellaneous retail stores including food service, pharmacies, and specialty shops"
+  reserved: false
+
+- start: "6000"
+  end: "7299"
+  name: "Service Providers"
+  description: "Service provider businesses including financial services, lodging, and personal services"
+  reserved: false
+
+- start: "7300"
+  end: "7529"
+  name: "Business Services"
+  description: "Business services including advertising, consulting, and equipment rental"
+  reserved: false
+
+- start: "7530"
+  end: "7799"
+  name: "Repair Services"
+  description: "Repair and automotive services"
+  reserved: false
+
+- start: "7800"
+  end: "7999"
+  name: "Entertainment"
+  description: "Amusement and entertainment including gambling, recreation, and sports"
+  reserved: false
+
+- start: "8000"
+  end: "8999"
+  name: "Professional Services"
+  description: "Professional services and membership organizations including healthcare, legal, and education"
+  reserved: false
+
+- start: "9000"
+  end: "9199"
+  name: "Reserved for ISO"
+  description: "Reserved for ISO use"
+  reserved: true
+
+- start: "9200"
+  end: "9402"
+  name: "Government Services"
+  description: "Government services including courts, fines, taxes, and postal services"
+  reserved: false
+
+- start: "9403"
+  end: "9999"
+  name: "Other"
+  description: "Other services and intra-company purchases"
+  reserved: false

data/lib/elia/mcc/data/risk_categories.yml

@@ -0,0 +1,293 @@
+# Risk-Based MCC Categories for Payment Control
+# These categories are commonly used for merchant restrictions, spend controls,
+# and risk management in payment systems.
+---
+airlines:
+  name: "Airlines"
+  description: "Airlines and air carriers only"
+  codes:
+    - "3000-3350"  # Specific airline codes (United, Delta, American, etc.)
+    - "4415"       # Air Courier Services
+    - "4511"       # Airlines, Air Carriers
+
+gambling:
+  name: "Gambling"
+  description: "Casinos, betting, lottery, and gaming"
+  codes:
+    - "7800"  # Government Owned Lotteries (US only)
+    - "7801"  # Government Licensed Casinos (Online Gambling)
+    - "7802"  # Government Licensed Horse/Dog Racing
+    - "7995"  # Betting/Casino Gambling
+    - "9406"  # Government-owned Lottery (non-US)
+
+adult:
+  name: "Adult Entertainment"
+  description: "Adult content and services"
+  codes:
+    - "5967"  # Direct Marketing - Inbound Teleservices Merchant
+    - "7273"  # Dating/Escort Services
+    - "7297"  # Massage Parlors
+
+crypto:
+  name: "Cryptocurrency"
+  description: "Cryptocurrency and digital asset exchanges"
+  codes:
+    - "6051"  # Non-FI Money Orders, Foreign Currency, Cryptocurrency
+    - "6211"  # Security Brokers/Dealers
+
+high_risk:
+  name: "High Risk"
+  description: "Industries with high chargeback or fraud rates"
+  codes:
+    - "5962"  # Direct Marketing - Travel Related
+    - "5966"  # Direct Marketing - Outbound Telemarketing
+    - "5967"  # Direct Marketing - Inbound Teleservices
+    - "5968"  # Direct Marketing - Subscription
+    - "7841"  # Video Tape Rental Stores
+    - "5933"  # Pawn Shops
+    - "5935"  # Wrecking and Salvage Yards
+
+travel:
+  name: "Travel"
+  description: "Travel services (excluding airlines)"
+  codes:
+    - "3351-3500"  # Car Rentals
+    - "3501-3999"  # Hotels and Lodging
+    - "4411"       # Cruise Lines
+    - "4722"       # Travel Agencies
+    - "4723"       # Package Tour Operators
+    - "7011"       # Hotels and Motels
+    - "7012"       # Timeshares
+    - "7032"       # Sporting and Recreational Camps
+    - "7033"       # Trailer Parks and Campgrounds
+    - "7512"       # Car Rental
+
+fuel:
+  name: "Fuel"
+  description: "Gas stations and fuel dispensers"
+  codes:
+    - "5172"  # Petroleum Products
+    - "5541"  # Service Stations
+    - "5542"  # Automated Fuel Dispensers
+    - "5983"  # Fuel Dealers
+
+financial:
+  name: "Financial Services"
+  description: "Banks, money orders, wire transfers, and stored value"
+  codes:
+    - "6010"  # Financial Institutions - Manual Cash
+    - "6011"  # Financial Institutions - Automated Cash
+    - "6012"  # Financial Institutions - Merchandise and Services
+    - "6050"  # Quasi Cash - Financial Institutions
+    - "6051"  # Non-FI Money Orders
+    - "6211"  # Security Brokers/Dealers
+    - "6300"  # Insurance Sales
+    - "6513"  # Real Estate Agents
+    - "6540"  # Non-FI Stored Value Card
+    - "4829"  # Wire Transfers and Money Orders
+
+legal_services:
+  name: "Legal Services"
+  description: "Attorneys, bail bonds, legal services"
+  codes:
+    - "8111"  # Legal Services and Attorneys
+    - "9223"  # Bail and Bond Payments
+
+healthcare:
+  name: "Healthcare"
+  description: "Medical services, hospitals, and pharmacies"
+  codes:
+    - "4119"  # Ambulance Services
+    - "5122"  # Drugs and Proprietary
+    - "5912"  # Drug Stores and Pharmacies
+    - "8011"  # Doctors
+    - "8021"  # Dentists and Orthodontists
+    - "8031"  # Osteopaths
+    - "8041"  # Chiropractors
+    - "8042"  # Optometrists
+    - "8043"  # Opticians
+    - "8049"  # Podiatrists
+    - "8050"  # Nursing and Personal Care Facilities
+    - "8062"  # Hospitals
+    - "8071"  # Medical and Dental Laboratories
+    - "8099"  # Medical Services
+
+government:
+  name: "Government"
+  description: "Government services, fines, and taxes"
+  codes:
+    - "9211"  # Court Costs
+    - "9222"  # Fines
+    - "9223"  # Bail and Bond Payments
+    - "9311"  # Tax Payments
+    - "9399"  # Government Services
+    - "9402"  # Postal Services - Government Only
+    - "9405"  # Intra-Government Purchases
+
+food_and_dining:
+  name: "Food and Dining"
+  description: "Restaurants, fast food, and grocery stores"
+  codes:
+    - "5411"  # Grocery Stores, Supermarkets
+    - "5422"  # Freezer and Locker Meat Provisioners
+    - "5441"  # Candy, Nut, Confectionery
+    - "5451"  # Dairy Products
+    - "5462"  # Bakeries
+    - "5499"  # Miscellaneous Food Stores
+    - "5811"  # Caterers
+    - "5812"  # Eating Places, Restaurants
+    - "5813"  # Drinking Places (Bars)
+    - "5814"  # Fast Food Restaurants
+
+retail:
+  name: "General Retail"
+  description: "General merchandise and department stores"
+  codes:
+    - "5300"  # Wholesale Clubs
+    - "5309"  # Duty Free Stores
+    - "5310"  # Discount Stores
+    - "5311"  # Department Stores
+    - "5331"  # Variety Stores
+    - "5399"  # Miscellaneous General Merchandise
+
+electronics:
+  name: "Electronics"
+  description: "Electronics and computer stores"
+  codes:
+    - "5045"  # Computers and Peripherals
+    - "5732"  # Electronics Stores
+    - "5734"  # Computer Software Stores
+    - "5815"  # Digital Goods - Media
+    - "5816"  # Digital Goods - Games
+    - "5817"  # Digital Goods - Applications
+    - "5818"  # Digital Goods - Large Volume
+
+office_supplies:
+  name: "Office Supplies"
+  description: "Office equipment and supplies"
+  codes:
+    - "5021"  # Office and Commercial Furniture
+    - "5044"  # Office, Photographic Equipment
+    - "5111"  # Stationery, Office Supplies
+    - "5943"  # Stationery, Office and School Supply Stores
+
+education:
+  name: "Education"
+  description: "Schools and educational services"
+  codes:
+    - "8211"  # Elementary and Secondary Schools
+    - "8220"  # Colleges, Universities
+    - "8241"  # Correspondence Schools
+    - "8244"  # Business and Secretarial Schools
+    - "8249"  # Trade and Vocational Schools
+    - "8299"  # Educational Services
+    - "8351"  # Child Care Services
+
+professional_services:
+  name: "Professional Services"
+  description: "Consulting, accounting, and other professional services"
+  codes:
+    - "7311"  # Advertising Services
+    - "7321"  # Credit Reporting Agencies
+    - "7322"  # Collection Agencies
+    - "7372"  # Computer Programming
+    - "7375"  # Information Retrieval Services
+    - "7379"  # Computer Maintenance
+    - "7392"  # Management Consulting
+    - "8911"  # Architectural, Engineering Services
+    - "8931"  # Accounting, Auditing, Bookkeeping
+    - "8999"  # Professional Services
+
+entertainment:
+  name: "Entertainment"
+  description: "Recreation and entertainment (excluding gambling)"
+  codes:
+    - "7829"  # Motion Picture Production
+    - "7832"  # Motion Picture Theaters
+    - "7841"  # Video Tape Rentals
+    - "7911"  # Dance Halls, Studios
+    - "7922"  # Theatrical Producers, Ticket Agencies
+    - "7929"  # Bands, Orchestras
+    - "7932"  # Billiard and Pool
+    - "7933"  # Bowling Alleys
+    - "7941"  # Sports Clubs
+    - "7991"  # Tourist Attractions
+    - "7992"  # Golf Courses
+    - "7993"  # Video Amusement Game Supplies
+    - "7994"  # Video Game Arcades
+    - "7996"  # Amusement Parks
+    - "7997"  # Country Clubs
+    - "7998"  # Aquariums
+    - "7999"  # Recreation Services
+
+automotive:
+  name: "Automotive"
+  description: "Automotive sales, service, and parts"
+  codes:
+    - "5013"  # Motor Vehicle Supplies
+    - "5511"  # Car and Truck Dealers (New and Used)
+    - "5521"  # Car and Truck Dealers (Used Only)
+    - "5531"  # Auto and Home Supply
+    - "5532"  # Automotive Tire Stores
+    - "5533"  # Automotive Parts
+    - "5541"  # Service Stations
+    - "5542"  # Automated Fuel Dispensers
+    - "5551"  # Boat Dealers
+    - "5561"  # Camper, Trailer Dealers
+    - "5571"  # Motorcycle Shops
+    - "5592"  # Motor Home Dealers
+    - "5598"  # Snowmobile Dealers
+    - "5599"  # Misc. Automotive Dealers
+    - "7512"  # Car Rental
+    - "7513"  # Truck Rental
+    - "7519"  # Motor Home Rental
+    - "7523"  # Parking Lots
+    - "7531"  # Automotive Body Repair
+    - "7534"  # Tire Repair
+    - "7535"  # Automotive Paint
+    - "7538"  # Automotive Service Shops
+    - "7542"  # Car Washes
+    - "7549"  # Towing Services
+
+charities:
+  name: "Charities and Non-Profits"
+  description: "Charitable organizations and religious groups"
+  codes:
+    - "8398"  # Charitable and Social Service Organizations
+    - "8641"  # Civic, Social, Fraternal Associations
+    - "8651"  # Political Organizations
+    - "8661"  # Religious Organizations
+    - "8699"  # Membership Organizations
+
+telecom:
+  name: "Telecommunications"
+  description: "Telephone and internet services"
+  codes:
+    - "4812"  # Telecommunication Equipment
+    - "4813"  # Key-entry Telecom
+    - "4814"  # Telecommunication Services
+    - "4815"  # Monthly Summary Telephone
+    - "4816"  # Computer Network Services
+    - "4821"  # Telegraph Services
+    - "4899"  # Cable and Pay Television
+
+utilities:
+  name: "Utilities"
+  description: "Electric, gas, and water services"
+  codes:
+    - "4900"  # Utilities - Electric, Gas, Water
+
+construction:
+  name: "Construction"
+  description: "General and specialty contractors"
+  codes:
+    - "1520"  # General Contractors
+    - "1711"  # Heating, Plumbing, A/C Contractors
+    - "1731"  # Electrical Contractors
+    - "1740"  # Masonry, Plastering Contractors
+    - "1750"  # Carpentry Contractors
+    - "1761"  # Roofing, Siding Contractors
+    - "1771"  # Concrete Work Contractors
+    - "1799"  # Special Trade Contractors
+    - "5039"  # Construction Materials
+    - "5211"  # Lumber and Building Materials

data/lib/elia/mcc/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Base error class for all MCC-related errors
+    class Error < StandardError; end
+
+    # Raised when an MCC code is not found in the registry
+    class NotFound < Error
+      def initialize(code)
+        super("MCC code not found: #{code.inspect}")
+      end
+    end
+
+    # Raised when an invalid MCC code format is provided
+    class InvalidCode < Error
+      def initialize(code)
+        super("Invalid MCC code format: #{code.inspect}. Expected a 4-digit string or integer.")
+      end
+    end
+
+    # Raised when an invalid range is specified
+    class InvalidRange < Error
+      def initialize(message = "Invalid MCC range specified")
+        super
+      end
+    end
+
+    # Raised when configuration is invalid
+    class ConfigurationError < Error; end
+
+    # Raised when data files cannot be loaded
+    class DataLoadError < Error
+      def initialize(file_path, original_error = nil)
+        message = "Failed to load MCC data from: #{file_path}"
+        message += " (#{original_error.message})" if original_error
+        super(message)
+      end
+    end
+
+    # Raised when a category is not found
+    class CategoryNotFound < Error
+      def initialize(category)
+        super("Category not found: #{category.inspect}")
+      end
+    end
+  end
+end

data/lib/elia/mcc/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Rails integration for the Elia::Mcc module
+    #
+    # Provides automatic setup when used within a Rails application,
+    # including configuration and ActiveModel integration.
+    class Railtie < Rails::Railtie
+      initializer "elia_mcc.configure" do |app|
+        # Allow custom data path from Rails config directory
+        Elia::Mcc.configure do |config|
+          if app.root
+            custom_data_path = app.root.join("config", "mcc_data")
+            config.data_path = custom_data_path.to_s if custom_data_path.exist?
+          end
+        end
+      end
+
+      # Load ActiveModel validator when ActiveModel is loaded
+      initializer "elia_mcc.active_model" do
+        ActiveSupport.on_load(:active_model) do
+          require "elia/mcc/active_model_validator"
+        end
+      end
+
+      # Eager load MCC data after initialization if caching is enabled
+      config.after_initialize do
+        if Elia::Mcc.configuration.cache_enabled
+          # Touch the collection to trigger lazy loading
+          Elia::Mcc.count
+        end
+      end
+    end
+  end
+end

data/lib/elia/mcc/range.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Elia
+  module Mcc
+    # Represents an ISO 18245 MCC range
+    #
+    # Ranges define groups of related MCC codes by industry segment
+    # according to the ISO 18245 standard.
+    class Range
+      # @return [String] the starting MCC code (inclusive)
+      attr_reader :start_code
+
+      # @return [String] the ending MCC code (inclusive)
+      attr_reader :end_code
+
+      # @return [String] the name of this range
+      attr_reader :name
+
+      # @return [String] description of this range
+      attr_reader :description
+
+      # @return [Boolean] whether this range is reserved
+      attr_reader :reserved
+
+      # Creates a new Range instance
+      #
+      # @param attributes [Hash] the range attributes
+      # @option attributes [String, Integer] :start the starting MCC code
+      # @option attributes [String, Integer] :end the ending MCC code
+      # @option attributes [String] :name the name of the range
+      # @option attributes [String] :description description of the range
+      # @option attributes [Boolean] :reserved whether the range is reserved
+      # @raise [InvalidRange] if the range is invalid
+      def initialize(attributes = {})
+        attributes = attributes.transform_keys(&:to_sym)
+
+        @start_code = normalize_code(attributes[:start] || attributes[:start_code])
+        @end_code = normalize_code(attributes[:end] || attributes[:end_code])
+        @name = attributes[:name].to_s
+        @description = attributes[:description].to_s
+        @reserved = attributes[:reserved] == true
+
+        validate!
+      end
+
+      # Returns whether the given code falls within this range
+      #
+      # @param mcc [String, Integer, Code] the code to check
+      # @return [Boolean] true if the code is within the range
+      def include?(mcc)
+        code = mcc.respond_to?(:mcc) ? mcc.mcc : mcc
+        normalized = normalize_code(code)
+        normalized.between?(start_code, end_code)
+      end
+
+      alias cover? include?
+
+      # Returns whether this range is reserved
+      #
+      # @return [Boolean] true if reserved
+      def reserved?
+        @reserved == true
+      end
+
+      # Returns the number of codes in this range
+      #
+      # @return [Integer] the count of codes
+      def size
+        end_code.to_i - start_code.to_i + 1
+      end
+
+      alias count size
+      alias length size
+
+      # Returns all codes in this range as an array of strings
+      #
+      # @return [Array<String>] all codes in the range
+      def to_a
+        (start_code.to_i..end_code.to_i).map { |n| n.to_s.rjust(4, "0") }
+      end
+
+      # Iterates over each code in the range
+      #
+      # @yield [String] each code in the range
+      # @return [Enumerator] if no block given
+      def each(&block)
+        return to_enum(:each) unless block_given?
+
+        to_a.each(&block)
+      end
+
+      # Returns whether this range equals another
+      #
+      # @param other [Range] the range to compare
+      # @return [Boolean] true if the ranges are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        start_code == other.start_code && end_code == other.end_code
+      end
+
+      alias eql? ==
+
+      # Returns a hash code for this instance
+      #
+      # @return [Integer] the hash code
+      def hash
+        [start_code, end_code].hash
+      end
+
+      # Returns a human-readable representation
+      #
+      # @return [String] the inspection string
+      def inspect
+        "#<#{self.class.name} #{start_code}..#{end_code} name=#{name.inspect} reserved=#{reserved?}>"
+      end
+
+      # Returns the range as a string
+      #
+      # @return [String] the range representation
+      def to_s
+        "#{start_code}-#{end_code}"
+      end
+
+      # Returns a hash representation
+      #
+      # @return [Hash] the range as a hash
+      def to_h
+        {
+          start_code: start_code,
+          end_code: end_code,
+          name: name,
+          description: description,
+          reserved: reserved,
+        }
+      end
+
+      private
+
+      # Validates that the range is valid
+      #
+      # @raise [InvalidRange] if the range is invalid
+      def validate!
+        return unless start_code.to_i > end_code.to_i
+
+        raise InvalidRange, "Start code (#{start_code}) cannot be greater than end code (#{end_code})"
+      end
+
+      # Normalizes a code value to a 4-digit string
+      #
+      # @param value [String, Integer] the value to normalize
+      # @return [String] the normalized 4-digit string
+      def normalize_code(value)
+        value.to_s.strip.rjust(4, "0")
+      end
+    end
+  end
+end