sat_rfc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d546b4ca5245b4d86c98325bf2872a14268e945b8b51c0f6bee2c26e7dc9b1af
+  data.tar.gz: 6e129b4c04bfc6bb2ec397609bc408c8368094a49bc4a292fb561ff0f9bc9088
+SHA512:
+  metadata.gz: 69a47948fcfa654cacfe91d7abd919704b44be4e3fa1690a078ca48a90dec715e5635b9781103b4e3f5e8944b891063361746567b9368d14ad2267e64411fcb9
+  data.tar.gz: 928596bf9a5c0fcfd3426b839e8db8254e90c76b892ed785159a688e3d721ccc0771308f057fd04ea06daacf76e52fbd8be5cdf04a9b65c667be073e695180d6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 RFC Contributors
+
+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,92 @@
+# sat_rfc
+
+Ruby gem to generate Mexican **RFC** tax identifiers for **natural persons** (personas físicas), following the [SAT](https://www.sat.gob.mx/) algorithm.
+
+Legal entity support (personas morales) is planned for a future release.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "sat_rfc"
+```
+
+Or install from the repository:
+
+```ruby
+gem "sat_rfc", git: "https://github.com/elosnaya/rfc.git"
+```
+
+Local development install:
+
+```bash
+bundle exec rake install
+```
+
+## Usage
+
+```ruby
+require "sat_rfc"
+
+rfc = Rfc::Generator.new.for_natural_person(
+  name: "Juan Carlos",
+  first_last_name: "Perez",
+  second_last_name: "Garcia",
+  date_of_birth: "15/03/1990"
+)
+
+puts rfc # => "PEGJ900315PE9"
+```
+
+You can also pass the birth date as separate values:
+
+```ruby
+Rfc::Generator.new.for_natural_person(
+  name: "Juan Carlos",
+  first_last_name: "Perez",
+  second_last_name: "Garcia",
+  day: 15,
+  month: 3,
+  year: 1990
+)
+```
+
+`date_of_birth` accepts `DD/MM/YYYY` format or any string parseable by Ruby's `Date`.
+
+### Errors
+
+```ruby
+begin
+  Rfc::Generator.new.for_natural_person(name: "Ana", first_last_name: "Lopez", second_last_name: "Garcia")
+rescue Rfc::Generator::InvalidDateError => e
+  puts e.message # => "Date information missing"
+end
+```
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+bundle exec rspec  # run tests
+bin/console        # interactive console
+```
+
+Example in the console:
+
+```ruby
+Rfc::Generator.new.for_natural_person(
+  name: "Juan Carlos",
+  first_last_name: "Perez",
+  second_last_name: "Garcia",
+  date_of_birth: "15/03/1990"
+)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [elosnaya/rfc](https://github.com/elosnaya/rfc).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rfc/discardable_terms/natural_person.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rfc
+  module DiscardableTerms
+    # Dictionary of discardable terms and forbidden words for natural persons (personas físicas).
+    # Based on SAT specification.
+    module NaturalPerson
+      ARTICLES_AND_PREPOSITIONS = %w[
+        DE LA LAS DEL LOS Y
+        EN CON SUS PARA POR AL E
+        OF THE AND
+      ].freeze
+
+      COMPANY_TYPE_ABBREVIATIONS = %w[
+        SA SC SRL SCS CIA COOP SOC CO COMPANY
+        CV RL S A C V
+        COMPAÑIA
+      ].freeze
+
+      DISCARDABLE_TERMS = %w[MC VON MAC VAN MI].freeze
+
+      ALL = (
+        ARTICLES_AND_PREPOSITIONS +
+        COMPANY_TYPE_ABBREVIATIONS +
+        DISCARDABLE_TERMS
+      ).freeze
+
+      FORBIDDEN_WORDS = %w[
+        BUEI BUEY CACA CACO CAGA KOGE KAKA MAME KOJO KULO
+        CAGO COGE COJE COJO FETO JOTO KACO KAGO MAMO MEAR MEON
+        MION MOCO MULA PEDA PEDO PENE PUTA PUTO QULO RATA RUIN
+      ].freeze
+    end
+  end
+end

data/lib/rfc/generator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Rfc
+  class Generator
+    class InvalidDateError < Error; end
+
+    def initialize(
+      natural_ten_digits_calculator: NaturalTenDigitsCodeCalculator,
+      homoclave_calculator: HomoclaveCalculator,
+      verification_digit_calculator: VerificationDigitCalculator
+    )
+      @natural_ten_digits_calculator = natural_ten_digits_calculator
+      @homoclave_calculator = homoclave_calculator
+      @verification_digit_calculator = verification_digit_calculator
+    end
+
+    def for_natural_person(
+      name:,
+      first_last_name:,
+      second_last_name:,
+      day: nil,
+      month: nil,
+      year: nil,
+      date_of_birth: nil
+    )
+      normalized_day, normalized_month, normalized_year = normalize_date(day, month, year, date_of_birth)
+
+      ten_digits_code = @natural_ten_digits_calculator.new(
+        name: name,
+        first_last_name: first_last_name,
+        second_last_name: second_last_name,
+        day: normalized_day,
+        month: normalized_month,
+        year: normalized_year
+      ).calculate
+
+      homoclave = @homoclave_calculator.new(
+        name: name,
+        first_last_name: first_last_name,
+        second_last_name: second_last_name
+      ).calculate
+
+      build_rfc(ten_digits_code, homoclave)
+    rescue ArgumentError => e
+      raise InvalidDateError, "Invalid date parameters: #{e.message}"
+    end
+
+    private
+
+    def build_rfc(ten_digits_code, homoclave)
+      rfc12_digits = "#{ten_digits_code.gsub("-", "")}#{homoclave}"
+      verification_digit = @verification_digit_calculator.new(rfc12_digits).calculate
+
+      "#{ten_digits_code}#{homoclave}#{verification_digit}"
+    end
+
+    def normalize_date(day, month, year, date_string)
+      if !day.nil? && !month.nil? && !year.nil?
+        [day, month, year]
+      elsif present?(date_string)
+        parse_date_string(date_string)
+      else
+        raise InvalidDateError, "Date information missing"
+      end
+    end
+
+    def parse_date_string(date_string)
+      parsed_date = try_parse_date(date_string)
+      raise InvalidDateError, "Invalid date format: #{date_string}" unless parsed_date
+
+      [parsed_date.day, parsed_date.month, parsed_date.year]
+    end
+
+    def try_parse_date(date_string)
+      return nil unless present?(date_string)
+
+      Date.strptime(date_string, "%d/%m/%Y")
+    rescue ArgumentError
+      begin
+        Date.parse(date_string.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+  end
+end

data/lib/rfc/homoclave_calculator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+module Rfc
+  class HomoclaveCalculator
+    HOMOCLAVE_DIGITS = "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ".freeze
+    FULL_NAME_MAPPING = {
+      " " => "00", "0" => "00", "1" => "01", "2" => "02", "3" => "03", "4" => "04",
+      "5" => "05", "6" => "06", "7" => "07", "8" => "08", "9" => "09", "&" => "10",
+      "A" => "11", "B" => "12", "C" => "13", "D" => "14", "E" => "15", "F" => "16",
+      "G" => "17", "H" => "18", "I" => "19", "J" => "21", "K" => "22", "L" => "23",
+      "M" => "24", "N" => "25", "O" => "26", "P" => "27", "Q" => "28", "R" => "29",
+      "S" => "32", "T" => "33", "U" => "34", "V" => "35", "W" => "36", "X" => "37",
+      "Y" => "38", "Z" => "39", "Ñ" => "40"
+    }.freeze
+
+    def initialize(name:, first_last_name:, second_last_name:)
+      @name = name
+      @first_last_name = first_last_name
+      @second_last_name = second_last_name
+    end
+
+    def calculate
+      normalize_full_name
+      map_full_name_to_digits_code
+      sum_pairs_of_digits
+      build_homoclave
+
+      @homoclave
+    end
+
+    private
+
+    def build_homoclave
+      last_three_digits = (@pairs_of_digits_sum % 1000)
+      quo = (last_three_digits / 34)
+      reminder = (last_three_digits % 34)
+      @homoclave = "#{HOMOCLAVE_DIGITS[quo]}#{HOMOCLAVE_DIGITS[reminder]}"
+    end
+
+    def sum_pairs_of_digits
+      @pairs_of_digits_sum = 0
+      (0..@mapped_full_name.length - 2).each do |i|
+        num1 = @mapped_full_name[i..i + 1].to_i
+        num2 = @mapped_full_name[i + 1..i + 1].to_i
+
+        @pairs_of_digits_sum += num1 * num2
+      end
+    end
+
+    def map_full_name_to_digits_code
+      @mapped_full_name = +"0"
+      @full_name.each_char do |character|
+        @mapped_full_name << map_character_to_two_digit_code(character)
+      end
+    end
+
+    def map_character_to_two_digit_code(character)
+      return FULL_NAME_MAPPING[character] if FULL_NAME_MAPPING.key?(character)
+
+      raise ArgumentError, "No two-digit-code mapping for char: #{character}"
+    end
+
+    def normalize_full_name
+      raw_full_name = full_name_string.upcase
+      @full_name = I18n.transliterate(raw_full_name).dup
+      @full_name.gsub!(/[-.']/, "")
+      @full_name.gsub!(/[^A-Z0-9\s]/, " ")
+      @full_name.gsub!(/\s+/, " ")
+      @full_name.strip!
+      add_missing_char_to_full_name(raw_full_name, "Ñ")
+    end
+
+    def full_name_string
+      "#{@first_last_name} #{@second_last_name} #{@name}"
+    end
+
+    def add_missing_char_to_full_name(raw_full_name, missing_char)
+      index = raw_full_name.index(missing_char)
+      until index.nil?
+        @full_name[index] = missing_char
+        index = raw_full_name.index(missing_char, index + 1)
+      end
+    end
+  end
+end

data/lib/rfc/natural_ten_digits_code_calculator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Rfc
+  class NaturalTenDigitsCodeCalculator
+    VOWEL_PATTERN = /[AEIOU]+/
+    DISCARDABLE_TERMS = DiscardableTerms::NaturalPerson::ALL
+    FORBIDDEN_WORDS = DiscardableTerms::NaturalPerson::FORBIDDEN_WORDS
+
+    def initialize(name:, first_last_name:, second_last_name:, day:, month:, year:)
+      @name = name
+      @first_last_name = first_last_name
+      @second_last_name = second_last_name
+      @day = day
+      @month = month
+      @year = year
+    end
+
+    def calculate
+      obfuscate_forbidden_words(name_code) + birthday_code
+    end
+
+    private
+
+    def obfuscate_forbidden_words(name_code)
+      FORBIDDEN_WORDS.each do |forbidden|
+        return "#{name_code[0..2]}X" if forbidden == name_code
+      end
+      name_code
+    end
+
+    def name_code
+      return first_last_name_empty_form if first_last_name_empty?
+      return second_last_name_empty_form if second_last_name_empty?
+      return first_last_name_too_short_form if first_last_name_is_too_short?
+
+      normal_form
+    end
+
+    def second_last_name_empty_form
+      first_two_letters_of(@first_last_name) + first_two_letters_of(filter_name(@name))
+    end
+
+    def birthday_code
+      "#{@year.to_s[-2, 2]}#{format('%02d', @month)}#{format('%02d', @day)}"
+    end
+
+    def second_last_name_empty?
+      normalized = normalize(@second_last_name)
+      normalized.nil? || normalized.empty?
+    end
+
+    def first_last_name_empty_form
+      first_two_letters_of(@second_last_name) + first_two_letters_of(filter_name(@name))
+    end
+
+    def first_last_name_empty?
+      normalized = normalize(@first_last_name)
+      normalized.nil? || normalized.empty?
+    end
+
+    def first_last_name_too_short_form
+      first_letter_of(@first_last_name) +
+        first_letter_of(@second_last_name) +
+        first_two_letters_of(filter_name(@name))
+    end
+
+    def first_two_letters_of(word)
+      normalized_word = normalize(word)
+      normalized_word[0..1]
+    end
+
+    def first_last_name_is_too_short?
+      normalize(@first_last_name).length <= 2
+    end
+
+    def normal_form
+      first_letter_of(@first_last_name) +
+        first_vowel_excluding_first_character_of(@first_last_name) +
+        first_letter_of(@second_last_name) +
+        first_letter_of(filter_name(@name))
+    end
+
+    def filter_name(name)
+      normalize(name).strip.sub(/^(MA|MA\.|MARIA|JOSE)\s+/, "")
+    end
+
+    def first_letter_of(word)
+      normalized_word = normalize(word)
+      normalized_word[0]
+    end
+
+    def normalize(word)
+      return word if word.nil? || word.empty?
+
+      normalized_word = I18n.transliterate(word).upcase
+      remove_discardable_terms(normalized_word, DISCARDABLE_TERMS)
+    end
+
+    def remove_discardable_terms(word, discardable_terms)
+      new_word = word.dup
+      discardable_terms.each do |term|
+        new_word.gsub!("#{term} ", "")
+      end
+      new_word
+    end
+
+    def first_vowel_excluding_first_character_of(word)
+      normalized_word = normalize(word)[1..]
+      match = VOWEL_PATTERN.match(normalized_word)
+      raise ArgumentError, "Word doesn't contain a vowel: #{normalized_word}" if match.nil?
+
+      match.to_s[0]
+    end
+  end
+end

data/lib/rfc/verification_digit_calculator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rfc
+  class VerificationDigitCalculator
+    MAPPING = {
+      "0" => 0, "1" => 1, "2" => 2, "3" => 3, "4" => 4, "5" => 5, "6" => 6,
+      "7" => 7, "8" => 8, "9" => 9, "A" => 10, "B" => 11, "C" => 12, "D" => 13,
+      "E" => 14, "F" => 15, "G" => 16, "H" => 17, "I" => 18, "J" => 19, "K" => 20,
+      "L" => 21, "M" => 22, "N" => 23, "&" => 24, "O" => 25, "P" => 26, "Q" => 27,
+      "R" => 28, "S" => 29, "T" => 30, "U" => 31, "V" => 32, "W" => 33, "X" => 34,
+      "Y" => 35, "Z" => 36, " " => 37, "Ñ" => 38
+    }.freeze
+
+    def initialize(rfc12_digits)
+      @rfc12_digits = rfc12_digits
+    end
+
+    def calculate
+      rfc12_padded = @rfc12_digits.ljust(12, " ")
+      sum = 0
+      (0..11).each do |i|
+        sum += map_digit(rfc12_padded[i]) * (13 - i)
+      end
+      reminder = sum % 11
+
+      return "0" if reminder.zero?
+
+      (11 - reminder).to_s(16).upcase
+    end
+
+    private
+
+    def map_digit(character)
+      return MAPPING[character] if MAPPING.key?(character)
+
+      0
+    end
+  end
+end

data/lib/rfc/version.rb

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

data/lib/rfc.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sat_rfc"

data/lib/sat_rfc.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+I18n.available_locales = [:en]
+I18n.default_locale = :en
+
+require_relative "rfc/version"
+require_relative "rfc/discardable_terms/natural_person"
+require_relative "rfc/verification_digit_calculator"
+require_relative "rfc/homoclave_calculator"
+require_relative "rfc/natural_ten_digits_code_calculator"
+
+module Rfc
+  class Error < StandardError; end
+end
+
+require_relative "rfc/generator"

data/sig/sat_rfc.rbs

@@ -0,0 +1,3 @@
+module Rfc
+  VERSION: String
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: sat_rfc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- elOsnaya
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby library that generates RFC tax identifiers for Mexican natural persons
+  using the SAT algorithm. Supports name normalization, homoclave, and verification
+  digit calculation.
+email:
+- luisosnet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rfc.rb
+- lib/rfc/discardable_terms/natural_person.rb
+- lib/rfc/generator.rb
+- lib/rfc/homoclave_calculator.rb
+- lib/rfc/natural_ten_digits_code_calculator.rb
+- lib/rfc/verification_digit_calculator.rb
+- lib/rfc/version.rb
+- lib/sat_rfc.rb
+- sig/sat_rfc.rbs
+homepage: https://github.com/elosnaya/rfc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/elosnaya/rfc
+  source_code_uri: https://github.com/elosnaya/rfc
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Generate Mexican RFC codes for natural persons (personas físicas).
+test_files: []