steuer 1.1.0 → 1.2.0

data/lib/steuer/finanzamt_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Steuer
+  # Lookup of Bundesfinanzamtsnummer (BUFA-Nr, the four-digit prefix of the
+  # federal-13 form) to the office's name, backed by the BZSt BUFA-Tabelle
+  # bundled in data/finanzaemter.yml.
+  #
+  # Unlike the structural data in StateMapping, these names go stale: offices
+  # merge and get renamed several times a year. Lookups therefore return nil
+  # rather than raising, so a number issued after the bundled table's revision
+  # still converts -- it just has no name yet.
+  module FinanzamtRegistry
+    DATA_PATH = File.expand_path('data/finanzaemter.yml', __dir__)
+
+    class << self
+      def name_for(code)
+        entries[code.to_s]&.fetch(:name, nil)
+      end
+
+      def state_for(code)
+        entries[code.to_s]&.fetch(:state, nil)
+      end
+
+      def known?(code)
+        entries.key?(code.to_s)
+      end
+
+      def revision
+        data[:revision]
+      end
+
+      def entries
+        @entries ||= data[:finanzaemter].to_h do |code, attrs|
+          [code.to_s, { name: attrs['name'], state: attrs['state'] }.freeze]
+        end.freeze
+      end
+
+      private
+
+      def data
+        @data ||= begin
+          loaded = YAML.safe_load_file(DATA_PATH)
+          { revision: loaded['revision'], finanzaemter: loaded['finanzaemter'] || {} }
+        end
+      end
+    end
+  end
+end

data/lib/steuer/steuernummer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'state_mapping'
+require_relative 'finanzamt_registry'
 
 module Steuer
   class Steuernummer
@@ -76,6 +77,19 @@ module Steuer
       StateMapping::STATES[@state_code][:name]
     end
 
+    # The BUFA-Nr: the leading four digits of the federal-13 form, identifying
+    # the issuing Finanzamt (the Empfaenger in an ELSTER transmission).
+    def finanzamt_code
+      to_federal_13&.slice(0, 4)
+    end
+
+    def finanzamt_name
+      code = finanzamt_code
+      return unless code
+
+      FinanzamtRegistry.name_for(code)
+    end
+
     def format_type
       @format_type ||= if normalized_input.include?('/')
         :standard

data/lib/steuer/version.rb

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

data/lib/steuer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'steuer/version'
 require_relative 'steuer/steuernummer'
+require_relative 'steuer/finanzamt_registry'
 require_relative 'steuer/errors'
 
 module Steuer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steuer
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Olumuyiwa Osiname
@@ -133,7 +133,9 @@ files:
 - LICENSE
 - README.md
 - lib/steuer.rb
+- lib/steuer/data/finanzaemter.yml
 - lib/steuer/errors.rb
+- lib/steuer/finanzamt_registry.rb
 - lib/steuer/state_mapping.rb
 - lib/steuer/steuernummer.rb
 - lib/steuer/version.rb