steuer 0.2.0.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 359109ea7cce6dd33e9fed32d083742ad20b27f97e84b3d89c4bdf73aa281dd4
+  data.tar.gz: 4fa8e2834415fc5e041a7f00ea13eac12d4340f62aed2a6168e1fac2aa6b80f2
+SHA512:
+  metadata.gz: 7c4805f2ff71eed6e1bcf2b85335226dab136107b82718fa9d223d8c83b8884b13817ba9a4dce30403bb60cac163f227f1527413b911b6f0245bc1c0748b2739
+  data.tar.gz: 126840ae3f0888c8dfc1d1eb0f0e717686b6f1b0a841fb9b18e54f3c9f408259b1576b1d2416e1428fd34529dde3460cd2a907a3d52f2143e22e3b266a461a90

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Steuer 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,212 @@
+# Steuer
+
+A Ruby gem for German tax system utilities, including Steuernummer (tax number) conversion between different formats and validation.
+
+Based on the official specifications from the [German Wikipedia page on Steuernummer](https://de.wikipedia.org/wiki/Steuernummer#Deutschland).
+
+## Features
+
+- **Format Detection**: Automatically detects the format of German tax numbers
+- **Format Conversion**: Convert between three different formats:
+  - Standard scheme (state-specific format, e.g., `93/815/08152`)
+  - Unified federal scheme (12-digit, e.g., `289381508152`)
+  - Unified federal scheme for electronic transmission (13-digit, e.g., `2893081508152`)
+- **State Detection**: Automatically detects the German state (Bundesland) from tax numbers
+- **Validation**: Validates tax numbers according to official patterns
+- **Object-Oriented**: Clean, object-oriented API design
+- **Extensible**: Designed to be extended with additional German tax utilities (VAT validation, etc.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'steuer'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install steuer
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'steuer'
+
+# Create a tax number object (auto-detects state from unambiguous formats)
+tax_number = Steuer.steuernummer('93/815/08152')  # Auto-detects Baden-Württemberg
+
+# Check if valid
+puts tax_number.valid?  # => true
+
+# Get information
+puts tax_number.state_code    # => "BW"
+puts tax_number.state_name    # => "Baden-Württemberg"
+puts tax_number.format_type   # => :standard
+
+# Convert between formats
+puts tax_number.to_federal_12  # => "289381508152"
+puts tax_number.to_federal_13  # => "2893081508152"
+puts tax_number.to_standard    # => "93/815/08152"
+```
+
+### Auto-Detection vs Explicit State
+
+```ruby
+# ✅ Auto-detects from standard format (each state has unique pattern)
+standard = Steuer.steuernummer('181/815/08155')  # Auto-detects Bayern
+puts standard.state_code  # => "BY"
+
+# ✅ Auto-detects from unambiguous federal prefixes
+federal_12 = Steuer.steuernummer('289381508152')  # Prefix '28' is unique to BW
+puts federal_12.state_name  # => "Baden-Württemberg"
+
+# ❌ Requires explicit state for ambiguous prefixes
+begin
+  Steuer.steuernummer('304881508155')  # Prefix '3' shared by BB, SN, ST
+rescue Steuer::UnsupportedStateError => e
+  puts e.message  # => "Cannot determine state from tax number..."
+end
+
+# ✅ Works with explicit state for ambiguous cases
+ambiguous = Steuer.steuernummer('304881508155', state: 'BB')
+puts ambiguous.state_code  # => "BB"
+```
+
+### Ambiguous vs Unambiguous Prefixes
+
+**✅ Unambiguous prefixes (auto-detected):**
+
+- `28` → Baden-Württemberg
+- `9` → Bayern
+- `11` → Berlin
+- `24` → Bremen
+- `22` → Hamburg
+- `26` → Hessen
+- `23` → Niedersachsen
+- `5` → Nordrhein-Westfalen
+- `27` → Rheinland-Pfalz
+- `1` → Saarland
+- `21` → Schleswig-Holstein
+
+**❌ Ambiguous prefixes (require explicit state):**
+
+- `3` → Brandenburg, Sachsen, or Sachsen-Anhalt
+- `4` → Mecklenburg-Vorpommern or Thüringen
+
+### Error Handling
+
+```ruby
+begin
+  # Invalid format
+  Steuer.steuernummer('invalid')
+rescue Steuer::InvalidTaxNumberError => e
+  puts "Invalid format: #{e.message}"
+end
+
+begin
+  # Unsupported state or undetectable
+  Steuer.steuernummer('99/999/99999')
+rescue Steuer::UnsupportedStateError => e
+  puts "Unsupported state: #{e.message}"
+end
+```
+
+## Supported German States
+
+The gem supports all 16 German states (Bundesländer):
+
+| State Code | State Name             | Standard Format Example | 12-digit Example | 13-digit Example |
+| ---------- | ---------------------- | ----------------------- | ---------------- | ---------------- |
+| BW         | Baden-Württemberg      | `93/815/08152`          | `289381508152`   | `2893081508152`  |
+| BY         | Bayern                 | `181/815/08155`         | `918181508155`   | `9181081508155`  |
+| BE         | Berlin                 | `21/815/08150`          | `112181508150`   | `1121081508150`  |
+| BB         | Brandenburg            | `048/815/08155`         | `304881508155`   | `3048081508155`  |
+| HB         | Bremen                 | `75/815/08152`          | `247581508152`   | `2475081508152`  |
+| HH         | Hamburg                | `02/815/08156`          | `220281508156`   | `2202081508156`  |
+| HE         | Hessen                 | `013/815/08153`         | `261381508153`   | `2613081508153`  |
+| MV         | Mecklenburg-Vorpommern | `79/815/08151`          | `407981508151`   | `4079081508151`  |
+| NI         | Niedersachsen          | `24/815/08151`          | `232481508151`   | `2324081508151`  |
+| NW         | Nordrhein-Westfalen    | `133/8150/8159`         | `513381508159`   | `5133081508159`  |
+| RP         | Rheinland-Pfalz        | `22/815/08154`          | `272281508154`   | `2722081508154`  |
+| SL         | Saarland               | `010/815/08182`         | `101081508182`   | `1010081508182`  |
+| SN         | Sachsen                | `201/815/08156`         | `320181508156`   | `3201081508156`  |
+| ST         | Sachsen-Anhalt         | `101/815/08153`         | `310181508153`   | `3101081508153`  |
+| SH         | Schleswig-Holstein     | `01/815/08155`          | `210181508155`   | `2101081508155`  |
+| TH         | Thüringen              | `151/815/08154`         | `415181508154`   | `4151081508154`  |
+
+## API Reference
+
+### `Steuer.steuernummer(tax_number, state_code = nil)`
+
+Creates a new `Steuer::Steuernummer` object.
+
+**Parameters:**
+
+- `tax_number` (String): The tax number in any supported format
+- `state_code` (String, optional): The German state code (auto-detected if not provided)
+
+**Returns:** `Steuer::Steuernummer` instance
+
+### `Steuer::Steuernummer` Methods
+
+#### Instance Methods
+
+- `valid?` - Returns `true` if the tax number is valid
+- `to_federal_12` - Converts to 12-digit unified federal scheme
+- `to_federal_13` - Converts to 13-digit electronic transmission format
+- `to_standard` - Converts to standard state-specific format
+- `state_code` - Returns the German state code (e.g., "BW")
+- `state_name` - Returns the full state name (e.g., "Baden-Württemberg")
+- `format_type` - Returns the detected format (`:standard`, `:federal_12`, or `:federal_13`)
+- `original_input` - Returns the original input string
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To run the tests:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Future Features
+
+This gem is designed to be extensible. Planned features include:
+
+- German VAT number validation
+- Steuer-ID (tax identification number) handling
+- Wirtschafts-Identifikationsnummer support
+- Additional German tax system utilities
+
+## References
+
+- [German Steuernummer Wikipedia Page](https://de.wikipedia.org/wiki/Steuernummer#Deutschland)
+- [Bundeszentralamt für Steuern](https://www.bzst.de/)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/steuer/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Steuer
+  class Error < StandardError; end
+  class InvalidTaxNumberError < Error; end
+  class UnsupportedStateError < Error; end
+  class ValidationError < Error; end
+end

data/lib/steuer/state_mapping.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Steuer
+  module StateMapping
+    # Mapping from state codes to their configuration
+    # Based on https://de.wikipedia.org/wiki/Steuernummer#Deutschland
+    STATES = {
+      'BW' => {
+        name: 'Baden-Württemberg',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '28',
+        federal_13_prefix: '28',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'BY' => {
+        name: 'Bayern',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '9',
+        federal_13_prefix: '9',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'BE' => {
+        name: 'Berlin',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '11',
+        federal_13_prefix: '11',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'BB' => {
+        name: 'Brandenburg',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '3',
+        federal_13_prefix: '3',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'HB' => {
+        name: 'Bremen',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '24',
+        federal_13_prefix: '24',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'HH' => {
+        name: 'Hamburg',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '22',
+        federal_13_prefix: '22',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'HE' => {
+        name: 'Hessen',
+        standard_pattern: %r{^0(1[3-9])/(\d{3})/(\d{5})$}, # More specific: 013-019 range, capture 13-19
+        federal_12_prefix: '26',
+        federal_13_prefix: '26',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'MV' => {
+        name: 'Mecklenburg-Vorpommern',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '4',
+        federal_13_prefix: '4',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'NI' => {
+        name: 'Niedersachsen',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '23',
+        federal_13_prefix: '23',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'NW' => {
+        name: 'Nordrhein-Westfalen',
+        standard_pattern: %r{^(\d{3})/(\d{4})/(\d{4})$},
+        federal_12_prefix: '5',
+        federal_13_prefix: '5',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'RP' => {
+        name: 'Rheinland-Pfalz',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '27',
+        federal_13_prefix: '27',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'SL' => {
+        name: 'Saarland',
+        standard_pattern: %r{^(01[0-2])/(\d{3})/(\d{5})$}, # Specific to 010-012 for Saarland
+        federal_12_prefix: '1',
+        federal_13_prefix: '1',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'SN' => {
+        name: 'Sachsen',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '3',
+        federal_13_prefix: '3',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'ST' => {
+        name: 'Sachsen-Anhalt',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '3',
+        federal_13_prefix: '3',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+      'SH' => {
+        name: 'Schleswig-Holstein',
+        standard_pattern: %r{^(\d{2})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '21',
+        federal_13_prefix: '21',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FF)
+      },
+      'TH' => {
+        name: 'Thüringen',
+        standard_pattern: %r{^(\d{3})/(\d{3})/(\d{5})$},
+        federal_12_prefix: '4',
+        federal_13_prefix: '4',
+        federal_13_zero_position: 4, # Insert 0 at position 4 (after FFF)
+      },
+    }.freeze
+    class << self
+      def find_state_by_standard_format(tax_number)
+        # Try more specific patterns first to avoid conflicts with general patterns
+        # Priority: character classes with ranges > specific digit patterns > general digit patterns
+        sorted_states = STATES.sort_by do |_, config|
+          pattern_str = config[:standard_pattern].source
+          if pattern_str.include?('[') # Character classes like [0-2] or [3-9]
+            0
+          elsif pattern_str.include?('0(') || pattern_str.start_with?('^0') # Patterns starting with specific digit
+            1
+          else # General patterns like (\d{3})
+            2
+          end
+        end
+
+        sorted_states.each do |code, config|
+          return code if tax_number.match?(config[:standard_pattern])
+        end
+        nil
+      end
+
+      def find_state_by_federal_12(tax_number)
+        return unless tax_number.length == 12
+
+        # Try exact prefix matches, longest first to avoid conflicts
+        # e.g., '28' should match before '2', '11' before '1'
+        sorted_states = STATES.sort_by { |_, config| -config[:federal_12_prefix].length }
+
+        sorted_states.each do |code, config|
+          prefix = config[:federal_12_prefix]
+
+          # Check if tax number starts with this exact prefix
+          next unless tax_number.start_with?(prefix)
+
+          # For single digit prefixes, ensure we don't match longer numbers
+          if prefix.length == 1
+            # For single digit, check that the next digit doesn't make it a longer prefix
+            next_char = tax_number[prefix.length]
+            return nil if next_char.nil? # Invalid tax number
+
+            # Skip if this would create a longer prefix that exists
+            longer_prefix = prefix + next_char
+            has_longer_prefix = STATES.any? { |_, c| c[:federal_12_prefix] == longer_prefix }
+            next if has_longer_prefix
+
+            # Additional validation: reject obviously invalid combinations
+            # For prefix '9' (Bayern), '99' is not a valid federal tax number start
+            if prefix == '9' && next_char == '9'
+              return nil
+            end
+          end
+
+          return code
+        end
+        nil
+      end
+
+      def find_state_by_federal_13(tax_number)
+        return unless tax_number.length == 13
+
+        # Try exact prefix matches, longest first to avoid conflicts
+        sorted_states = STATES.sort_by { |_, config| -config[:federal_13_prefix].length }
+
+        sorted_states.each do |code, config|
+          prefix = config[:federal_13_prefix]
+
+          # Check if tax number starts with this exact prefix
+          next unless tax_number.start_with?(prefix)
+
+          # For single digit prefixes, ensure we don't match longer numbers
+          if prefix.length == 1
+            # For single digit, check that the next digit doesn't make it a longer prefix
+            next_char = tax_number[prefix.length]
+            return nil if next_char.nil? # Invalid tax number
+
+            # Skip if this would create a longer prefix that exists
+            longer_prefix = prefix + next_char
+            has_longer_prefix = STATES.any? { |_, c| c[:federal_13_prefix] == longer_prefix }
+            next if has_longer_prefix
+          end
+
+          return code
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/steuer/steuernummer.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative 'state_mapping'
+
+module Steuer
+  class Steuernummer
+    attr_reader :original_input, :state_code
+
+    def initialize(tax_number, state: nil)
+      @original_input = tax_number.to_s.strip
+      @state_code = normalize_state_code(state) || auto_detect_state
+
+      validate_tax_number!
+    end
+
+    def valid?
+      return false if @original_input.empty?
+      return false unless format_type
+      return false unless @state_code
+
+      case format_type
+      when :standard
+        validate_standard_format
+      when :federal_12
+        validate_federal_12_format
+      when :federal_13
+        validate_federal_13_format
+      else
+        false
+      end
+    end
+
+    def to_federal_12
+      return unless valid?
+
+      case format_type
+      when :standard
+        convert_standard_to_federal_12
+      when :federal_12
+        normalized_input
+      when :federal_13
+        convert_federal_13_to_federal_12
+      end
+    end
+
+    def to_federal_13
+      return unless valid?
+
+      case format_type
+      when :standard
+        convert_standard_to_federal_13
+      when :federal_12
+        convert_federal_12_to_federal_13
+      when :federal_13
+        normalized_input
+      end
+    end
+
+    def to_standard
+      return unless valid?
+
+      case format_type
+      when :standard
+        @original_input
+      when :federal_12
+        convert_federal_12_to_standard
+      when :federal_13
+        convert_federal_13_to_standard
+      end
+    end
+
+    def state_name
+      return unless @state_code
+
+      StateMapping::STATES[@state_code][:name]
+    end
+
+    def format_type
+      @format_type ||= if normalized_input.include?('/')
+        :standard
+      elsif normalized_input.length == 12 && normalized_input.match?(/^\d{12}$/)
+        :federal_12
+      elsif normalized_input.length == 13 && normalized_input.match?(/^\d{13}$/)
+        :federal_13
+      end
+
+      @format_type
+    end
+
+    private
+
+    def normalized_input
+      @normalized_input_input ||= if @original_input.include?('/') || @original_input.include?('-')
+        @original_input.gsub(%r{[^0-9/\-]}, '').tr('-', '/')
+      else
+        @original_input.gsub(/[^0-9]/, '')
+      end
+      @normalized_input_input
+    end
+
+    def validate_tax_number!
+      unless format_type
+        raise InvalidTaxNumberError, "Invalid tax number format: #{@original_input}"
+      end
+
+      # Auto-detect state if not provided
+      if @state_code.nil?
+        raise UnsupportedStateError,
+          "Cannot determine state from tax number #{@original_input}. Please provide state parameter."
+      end
+
+      unless StateMapping::STATES.key?(@state_code)
+        raise UnsupportedStateError, "Unsupported state: #{@state_code}"
+      end
+
+      # Validate that the tax number matches the state's expected pattern
+      unless valid_for_state?
+        raise InvalidTaxNumberError, "Tax number #{@original_input} is not valid for state #{@state_code}"
+      end
+    end
+
+    def normalize_state_code(state)
+      return if state.nil? || state.to_s.strip.empty?
+
+      state_str = state.to_s.strip.upcase
+
+      return state_str if StateMapping::STATES.key?(state_str)
+
+      StateMapping::STATES.find { |_code, config| config[:name].upcase == state_str }&.first || state_str
+    end
+
+    def auto_detect_state
+      case format_type
+      when :standard
+        StateMapping.find_state_by_standard_format(normalized_input)
+      when :federal_12
+        # Only auto-detect if prefix is unambiguous
+        detected = StateMapping.find_state_by_federal_12(normalized_input)
+        return detected if detected && unambiguous_federal_prefix?(detected, normalized_input, :federal_12)
+
+        nil
+      when :federal_13
+        # Only auto-detect if prefix is unambiguous
+        detected = StateMapping.find_state_by_federal_13(normalized_input)
+        return detected if detected && unambiguous_federal_prefix?(detected, normalized_input, :federal_13)
+
+        nil
+      end
+    end
+
+    def unambiguous_federal_prefix?(detected_state, tax_number, format_type)
+      prefix_key = format_type == :federal_12 ? :federal_12_prefix : :federal_13_prefix
+      detected_prefix = StateMapping::STATES[detected_state][prefix_key]
+
+      # Count how many states share this prefix
+      matching_states = StateMapping::STATES.count do |_, config|
+        config[prefix_key] == detected_prefix
+      end
+
+      # Only unambiguous if exactly one state has this prefix
+      matching_states == 1
+    end
+
+    def valid_for_state?
+      return false unless @state_code && StateMapping::STATES.key?(@state_code)
+
+      case format_type
+      when :standard
+        validate_standard_format
+      when :federal_12
+        validate_federal_12_format
+      when :federal_13
+        validate_federal_13_format
+      else
+        false
+      end
+    end
+
+    def validate_standard_format
+      config = StateMapping::STATES[@state_code]
+      normalized_input.match?(config[:standard_pattern])
+    end
+
+    def validate_federal_12_format
+      return false unless normalized_input.length == 12
+      return false unless normalized_input.match?(/^\d{12}$/)
+
+      config = StateMapping::STATES[@state_code]
+      normalized_input.start_with?(config[:federal_12_prefix])
+    end
+
+    def validate_federal_13_format
+      return false unless normalized_input.length == 13
+      return false unless normalized_input.match?(/^\d{13}$/)
+
+      config = StateMapping::STATES[@state_code]
+      normalized_input.start_with?(config[:federal_13_prefix])
+    end
+
+    def convert_standard_to_federal_12
+      config = StateMapping::STATES[@state_code]
+
+      match = normalized_input.match(config[:standard_pattern])
+      return unless match
+
+      parts = match.captures
+
+      case @state_code
+      when 'NW' # Nordrhein-Westfalen has different structure (FFF/BBBB/UUUP)
+        fff, bbbb, uuup = parts
+        "#{config[:federal_12_prefix]}#{fff}#{bbbb}#{uuup}"
+      when 'HE' # Hessen (has leading zero in standard format)
+        if parts.length == 3
+          ff_or_fff, bbb, uuuup = parts
+          # Remove leading zero from Finanzamt code for federal format
+          finanzamt = ff_or_fff.sub(/^0/, '')
+          "#{config[:federal_12_prefix]}#{finanzamt}#{bbb}#{uuuup}"
+        end
+      else
+        if parts.length == 3
+          ff_or_fff, bbb, uuuup = parts
+          "#{config[:federal_12_prefix]}#{ff_or_fff}#{bbb}#{uuuup}"
+        end
+      end
+    end
+
+    def convert_standard_to_federal_13
+      federal_12 = convert_standard_to_federal_12
+      return unless federal_12
+
+      config = StateMapping::STATES[@state_code]
+      insert_position = config[:federal_13_zero_position]
+
+      result = federal_12.dup
+      result.insert(insert_position, '0')
+      result
+    end
+
+    def convert_federal_12_to_federal_13
+      config = StateMapping::STATES[@state_code]
+      insert_position = config[:federal_13_zero_position]
+
+      result = normalized_input.dup
+      result.insert(insert_position, '0')
+      result
+    end
+
+    def convert_federal_13_to_federal_12
+      config = StateMapping::STATES[@state_code]
+      remove_position = config[:federal_13_zero_position]
+
+      result = normalized_input.dup
+      result.slice!(remove_position)
+      result
+    end
+
+    def convert_federal_12_to_standard
+      federal_12_to_standard_format(normalized_input)
+    end
+
+    def convert_federal_13_to_standard
+      federal_12 = convert_federal_13_to_federal_12
+      return unless federal_12
+
+      federal_12_to_standard_format(federal_12)
+    end
+
+    def federal_12_to_standard_format(federal_12_string)
+      config = StateMapping::STATES[@state_code]
+      prefix = config[:federal_12_prefix]
+
+      # Remove the prefix
+      without_prefix = federal_12_string[prefix.length..-1]
+
+      case @state_code
+      when 'NW' # Nordrhein-Westfalen (FFF/BBBB/UUUP)
+        fff = without_prefix[0, 3]
+        bbbb = without_prefix[3, 4]
+        uuup = without_prefix[7, 4]
+        "#{fff}/#{bbbb}/#{uuup}"
+      when 'HE' # Hessen (has leading 0 in standard format)
+        ff = without_prefix[0, 2]
+        bbb = without_prefix[2, 3]
+        uuuup = without_prefix[5, 5]
+        "0#{ff}/#{bbb}/#{uuuup}"
+      else
+        if prefix.length == 1 # Single digit prefix states
+          fff = without_prefix[0, 3]
+          bbb = without_prefix[3, 3]
+          uuuup = without_prefix[6, 5]
+          "#{fff}/#{bbb}/#{uuuup}"
+        else # Two digit prefix states
+          ff = without_prefix[0, 2]
+          bbb = without_prefix[2, 3]
+          uuuup = without_prefix[5, 5]
+          "#{ff}/#{bbb}/#{uuuup}"
+        end
+      end
+    end
+
+    alias_method :to_elster, :to_federal_13
+  end
+end

data/lib/steuer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Steuer
+  VERSION = '1.0.0'
+end

data/lib/steuer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'steuer/version'
+require_relative 'steuer/steuernummer'
+require_relative 'steuer/errors'
+
+module Steuer
+  class << self
+    def steuernummer(tax_number, state: nil)
+      Steuernummer.new(tax_number, state: state)
+    end
+  end
+end

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: steuer
+version: !ruby/object:Gem::Version
+  version: 0.2.0.pre.alpha
+platform: ruby
+authors:
+- Olumuyiwa Osiname
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.56.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.56.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.19.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.19.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-shopify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: A Ruby gem for German tax system utilities including Steuernummer conversion
+  between formats, VAT validation, and other tax-related functionality
+email:
+- oluosiname@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/steuer.rb
+- lib/steuer/errors.rb
+- lib/steuer/state_mapping.rb
+- lib/steuer/steuernummer.rb
+- lib/steuer/version.rb
+homepage: https://github.com/oluosiname/steuer
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: German tax system utilities - tax numbers, VAT validation, and more
+test_files: []