facturx 0.1.0 → 0.2.0

data/lib/facturx/reader/semantic_mapper/helpers.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def reference(id, context: @document, base_xpath: nil, field: :id)
+        item = value(id, context:, base_xpath:)
+        DocumentReference.new(**{ field => item }) if item
+      end
+
+      def identifier(value_id, scheme_id = nil, context: @document, base_xpath: nil)
+        return unless value_id
+
+        item = value(value_id, context:, base_xpath:)
+        unless item
+          @terms.mark_value(scheme_id, context:, base_xpath:) if scheme_id
+          return
+        end
+
+        scheme = value(scheme_id, context:, base_xpath:) if scheme_id
+        Identifier.new(value: item, scheme_id: scheme)
+      end
+
+      def quantity(value_id, unit_id, context:, base_xpath:)
+        amount = value(value_id, context:, base_xpath:)
+        unless amount
+          @terms.mark_value(unit_id, context:, base_xpath:)
+          return
+        end
+
+        unit = value(unit_id, context:, base_xpath:)
+        Quantity.new(value: amount, unit_code: unit)
+      end
+
+      def tax_registration(attribute, scheme_id, node, base, group_id)
+        term = term_for(:party, group_id, attribute)
+        return unless term
+
+        nodes = node.xpath("./ram:SpecifiedTaxRegistration/ram:ID[@schemeID='#{scheme_id}']", NAMESPACES)
+        item = value(term.id, context: node, base_xpath: base, nodes:)
+        Identifier.new(value: item, scheme_id:) if item
+      end
+
+      def read_price_allowance_indicator(node, base)
+        allowance = node.at_xpath('./ram:AppliedTradeAllowanceCharge', NAMESPACES)
+        return unless allowance
+
+        indicator = allowance.at_xpath('./ram:ChargeIndicator', NAMESPACES)
+        @terms.mark(indicator)
+        allowance_base = "#{base}/ram:AppliedTradeAllowanceCharge"
+        value('BT-147-02', context: allowance, base_xpath: allowance_base)
+      end
+
+      def technical_value(xpath, context)
+        @terms.raw_value(xpath, context:)
+      end
+
+      def technical_boolean(xpath, context, term_id:, required: false, missing_path: xpath)
+        @terms.coerced_value(xpath, context:, type: :boolean, term_id:, required:, missing_path:)
+      end
+
+      def value(id, context: @document, base_group: nil, base_xpath: nil, nodes: nil)
+        return unless id
+
+        @terms.value(id, context:, base_xpath: base_xpath || (base_group && group_xpath(base_group)), nodes:)
+      end
+
+      def scalar_value(id, **)
+        Array(value(id, **)).first
+      end
+
+      def scalar_attributes(model, group_id, context: @document, base_xpath: nil, **selection)
+        only = selection[:only]
+        except = selection.fetch(:except, [])
+        model_terms(model, group_id)
+          .group_by(&:attribute)
+          .select { |attribute, terms| terms.one? && selected_attribute?(attribute, only, except) }
+          .to_h { |attribute, terms| [attribute, value(terms.first.id, context:, base_xpath:)] }
+      end
+
+      def selected_attribute?(attribute, only, except)
+        (only.nil? || only.include?(attribute)) && !except.include?(attribute)
+      end
+
+      def model_terms(model, group_id)
+        @terms_by_model_and_group.fetch([model, group_id], EMPTY_TERMS)
+      end
+
+      def term_for(model, group_id, attribute, xpath_suffix: nil)
+        terms = model_terms(model, group_id).select { |term| term.attribute == attribute }
+        terms.find { |term| xpath_suffix.nil? || term.xpath.end_with?(xpath_suffix) }
+      end
+
+      def term_for_attribute(model, attribute, xpath_suffix: nil)
+        terms = @terms_by_model_and_attribute.fetch([model, attribute], EMPTY_TERMS)
+        terms.find { |term| xpath_suffix.nil? || term.xpath.end_with?(xpath_suffix) }
+      end
+
+      def group_nodes(id, **, &)
+        @terms.group_nodes(id, **, &)
+      end
+
+      def first_group(id, **)
+        group_nodes(id, **).first
+      end
+
+      def group_xpath(id)
+        @registry.group(id).xpath
+      end
+    end
+  end
+end

data/lib/facturx/reader/semantic_mapper/line_mapping.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def lines
+        group_nodes('BG-25').map { |node| line(node) }
+      end
+
+      def line(node)
+        base = group_xpath('BG-25')
+        Line.new(
+          **scalar_attributes(:line, 'BG-25', context: node, base_xpath: base),
+          **line_trade_attributes(node, base),
+          **line_reference_attributes(node, base)
+        )
+      end
+
+      def line_trade_attributes(node, base)
+        {
+          product: product(node, base),
+          quantity: quantity('BT-129', 'BT-130', context: node, base_xpath: base),
+          gross_price: price(node, base, gross: true),
+          net_price: price(node, base, gross: false),
+          tax: line_tax(node, base),
+          period: period('BG-26', context: node, base_xpath: base),
+          allowances: allowance_charges('BG-27', charge: false, context: node, base_xpath: base),
+          charges: allowance_charges('BG-28', charge: true, context: node, base_xpath: base)
+        }
+      end
+
+      def line_reference_attributes(node, base)
+        {
+          buyer_order_reference: reference('BT-132', context: node, base_xpath: base, field: :line_id),
+          invoiced_object_identifier: identifier('BT-128', 'BT-128-1', context: node, base_xpath: base)
+        }
+      end
+
+      def product(parent, parent_base)
+        node = first_group('BG-31', context: parent, base_xpath: parent_base)
+        return unless node
+
+        base = group_xpath('BG-31')
+        Product.new(**product_attributes_hash(node, base))
+      end
+
+      def product_attributes_hash(node, base)
+        identifiers = %i[seller_identifier buyer_identifier global_identifier]
+        scalar_attributes(:product, 'BG-31', context: node, base_xpath: base, except: identifiers).merge(
+          seller_identifier: identifier('BT-155', context: node, base_xpath: base),
+          buyer_identifier: identifier('BT-156', context: node, base_xpath: base),
+          global_identifier: identifier('BT-157', 'BT-157-1', context: node, base_xpath: base),
+          attributes: product_attributes(node, base),
+          classifications: product_classifications(node, base)
+        )
+      end
+
+      def product_attributes(parent, parent_base)
+        group_nodes('BG-32', context: parent, base_xpath: parent_base).map do |node|
+          base = group_xpath('BG-32')
+          ProductAttribute.new(**scalar_attributes(:product_attribute, 'BG-32', context: node, base_xpath: base))
+        end
+      end
+
+      def product_classifications(parent, parent_base)
+        nodes = parent.xpath('./ram:DesignatedProductClassification', NAMESPACES)
+        nodes.map do |node|
+          base = "#{parent_base}/ram:DesignatedProductClassification"
+          ProductClassification.new(
+            code: scalar_value('BT-158', context: node, base_xpath: base),
+            list_id: value('BT-158-1', context: node, base_xpath: base),
+            list_version_id: value('BT-158-2', context: node, base_xpath: base)
+          )
+        end
+      end
+
+      def price(parent, parent_base, gross:)
+        prefix = gross ? 'Gross' : 'Net'
+        node = parent.at_xpath("./ram:SpecifiedLineTradeAgreement/ram:#{prefix}PriceProductTradePrice", NAMESPACES)
+        unless node
+          value('BT-146', context: parent, base_xpath: parent_base) unless gross
+          return
+        end
+
+        base = "#{parent_base}/ram:SpecifiedLineTradeAgreement/ram:#{prefix}PriceProductTradePrice"
+        Price.new(**price_attributes(node, base, gross))
+      end
+
+      def price_attributes(node, base, gross)
+        ids = gross ? %w[BT-148 BT-149-1 BT-150-1 BT-147] : %w[BT-146 BT-149 BT-150]
+        {
+          amount: value(ids[0], context: node, base_xpath: base),
+          basis_quantity: quantity(ids[1], ids[2], context: node, base_xpath: base),
+          discount: gross ? price_discount(node, base, ids[3]) : nil
+        }
+      end
+
+      def price_discount(node, base, amount_id)
+        amount = value(amount_id, context: node, base_xpath: base)
+        indicator = read_price_allowance_indicator(node, base)
+        return amount if indicator == false
+        return unless indicator == true
+
+        @terms.add(:invalid_value, 'BT-147-02', base, 'Gross price discount cannot be a charge', value: indicator)
+        nil
+      end
+
+      def line_tax(parent, parent_base)
+        node = first_group('BG-30', context: parent, base_xpath: parent_base)
+        return unless node
+
+        base = group_xpath('BG-30')
+        attributes = scalar_attributes(:tax_breakdown, 'BG-30', context: node, base_xpath: base)
+        TaxBreakdown.new(type_code: technical_value('./ram:TypeCode', node), **attributes)
+      end
+    end
+  end
+end

data/lib/facturx/reader/semantic_mapper/party_mapping.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def party(group_id, contact_group: nil, address_group: nil)
+        node = first_group(group_id)
+        return unless node
+
+        base = group_xpath(group_id)
+        Party.new(**party_scalar_attributes(node, base, group_id),
+                  **party_identifier_attributes(node, base, group_id),
+                  **party_group_attributes(node, base, contact_group, address_group))
+      end
+
+      def party_scalar_attributes(node, base, group_id)
+        scalar_attributes(:party, group_id, context: node, base_xpath: base,
+                                            only: %i[name description trading_name])
+      end
+
+      def party_identifier_attributes(node, base, group_id)
+        {
+          identifiers: party_identifiers(node, base, group_id),
+          legal_registration: compound_identifier(:legal_registration, node, base, group_id),
+          vat_identifier: tax_registration(:vat_identifier, 'VA', node, base, group_id),
+          tax_identifier: tax_registration(:tax_identifier, 'FC', node, base, group_id),
+          electronic_address: compound_identifier(:electronic_address, node, base, group_id)
+        }
+      end
+
+      def party_group_attributes(node, base, contact_group, address_group)
+        {
+          address: address_group && address(node, base, address_group),
+          contact: contact_group && contact(node, base, contact_group)
+        }
+      end
+
+      def party_identifiers(node, base, group_id)
+        value_term = term_for(:party, group_id, :identifiers, xpath_suffix: '/ram:ID')
+        return [] unless value_term
+
+        identifiers = local_party_identifiers(value_term, node, base)
+        scheme_term = term_for(:party, group_id, :identifiers, xpath_suffix: '/@schemeID')
+        return identifiers unless scheme_term
+
+        identifiers.concat(global_party_identifiers(node))
+      end
+
+      def local_party_identifiers(term, node, base)
+        Array(value(term.id, context: node, base_xpath: base)).compact.map { |item| Identifier.new(value: item) }
+      end
+
+      def global_party_identifiers(node)
+        node.xpath('./ram:GlobalID', NAMESPACES).map do |global_id|
+          @terms.mark(global_id)
+          Identifier.new(value: global_id.text, scheme_id: global_id['schemeID'])
+        end
+      end
+
+      def compound_identifier(attribute, node, base, group_id)
+        value_term = term_for(:party, group_id, attribute, xpath_suffix: '/ram:ID') ||
+                     term_for(:party, group_id, attribute, xpath_suffix: '/ram:URIID')
+        return unless value_term
+
+        scheme_term = term_for(:party, group_id, attribute, xpath_suffix: '/@schemeID')
+        identifier(value_term.id, scheme_term&.id, context: node, base_xpath: base)
+      end
+
+      def contact(parent, parent_base, group_id)
+        node = first_group(group_id, context: parent, base_xpath: parent_base)
+        return unless node
+
+        base = group_xpath(group_id)
+        attributes = scalar_attributes(:contact, group_id, context: node, base_xpath: base)
+        Contact.new(**attributes)
+      end
+
+      def address(parent, parent_base, group_id)
+        node = first_group(group_id, context: parent, base_xpath: parent_base)
+        return unless node
+
+        base = group_xpath(group_id)
+        attributes = scalar_attributes(:address, group_id, context: node, base_xpath: base)
+        Address.new(**attributes)
+      end
+    end
+  end
+end

data/lib/facturx/reader/semantic_mapper/payment_mapping.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def payment
+        nodes = group_nodes('BG-16')
+        base = group_xpath('BG-16')
+        attributes = settlement_payment_attributes(nodes.first, base)
+        attributes.merge!(payment_means_attributes(nodes.first, base)) if nodes.first
+        return if attributes.empty?
+
+        PaymentInstructions.new(**attributes)
+      end
+
+      def settlement_payment_attributes(payment_means, base)
+        attributes = scalar_attributes(:payment_instructions, 'BG-19')
+        direct_debit_details = direct_debit(payment_means, base)
+        attributes[:direct_debit] = direct_debit_details if direct_debit_details
+        attributes.compact
+      end
+
+      def payment_means_attributes(node, base)
+        provider = term_for(:credit_transfer, 'BG-16', :provider_identifier)
+        provider_identifier = identifier(provider&.id, context: node, base_xpath: base)
+        scalar_attributes(:payment_instructions, 'BG-16', context: node, base_xpath: base).merge(
+          credit_transfers: credit_transfers(node, base, provider_identifier),
+          payment_card: payment_card(node, base)
+        )
+      end
+
+      def credit_transfers(parent, parent_base, provider_identifier)
+        group_nodes('BG-17', context: parent, base_xpath: parent_base).map do |node|
+          credit_transfer(node, provider_identifier)
+        end
+      end
+
+      def credit_transfer(node, provider_identifier)
+        base = group_xpath('BG-17')
+        account = term_for(:credit_transfer, 'BG-17', :account_identifier)
+        attributes = scalar_attributes(:credit_transfer, 'BG-17', context: node, base_xpath: base,
+                                                                  except: [:account_identifier])
+        CreditTransfer.new(**attributes, account_identifier: identifier(account.id, context: node, base_xpath: base),
+                                         provider_identifier:)
+      end
+
+      def payment_card(parent, parent_base)
+        node = first_group('BG-18', context: parent, base_xpath: parent_base)
+        return unless node
+
+        base = group_xpath('BG-18')
+        PaymentCard.new(**scalar_attributes(:payment_card, 'BG-18', context: node, base_xpath: base))
+      end
+
+      def direct_debit(payment_means, base)
+        values = %i[mandate_identifier creditor_identifier].to_h do |attribute|
+          [attribute, identifier(term_for_attribute(:direct_debit, attribute)&.id)]
+        end
+        if payment_means
+          values[:debtor_account_identifier] = identifier(
+            term_for(:direct_debit, 'BG-16', :debtor_account_identifier)&.id,
+            context: payment_means, base_xpath: base
+          )
+        end
+        DirectDebit.new(**values) if values.values.any?
+      end
+    end
+  end
+end

data/lib/facturx/reader/semantic_mapper/trade_mapping.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def read_tax_breakdowns
+        nodes = group_nodes('BG-23')
+        base = group_xpath('BG-23')
+        vat_point_date = nil
+        items = nodes.map do |node|
+          tax_point_date = value('BT-7', context: node, base_xpath: base)
+          vat_point_date ||= tax_point_date
+          attributes = scalar_attributes(:tax_breakdown, 'BG-23', context: node, base_xpath: base)
+          TaxBreakdown.new(type_code: technical_value('./ram:TypeCode', node), **attributes)
+        end
+        TaxBreakdownResult.new(items:, vat_point_date:)
+      end
+
+      def allowance_charges(group_id, charge:, context: @document, base_xpath: nil)
+        group_nodes(group_id, context:, base_xpath:) { |node| charge_indicator(node, group_id) == charge }.map do |node|
+          base = group_xpath(group_id)
+          AllowanceCharge.new(**allowance_attributes(node, base, group_id), indicator: charge,
+                                                                            tax: allowance_tax(node, base, group_id))
+        end
+      end
+
+      def allowance_attributes(node, base, group_id)
+        scalar_attributes(:allowance_charge, group_id, context: node, base_xpath: base, except: [:tax])
+      end
+
+      def allowance_tax(node, base, group_id)
+        technical_value('./ram:CategoryTradeTax/ram:TypeCode', node)
+        category = value(term_for(:allowance_charge, group_id, :tax,
+                                  xpath_suffix: '/ram:CategoryTradeTax/ram:CategoryCode')&.id,
+                         context: node, base_xpath: base)
+        rate = value(term_for(:allowance_charge, group_id, :tax,
+                              xpath_suffix: '/ram:CategoryTradeTax/ram:RateApplicablePercent')&.id,
+                     context: node, base_xpath: base)
+        TaxBreakdown.new(category_code: category, rate:) if category || rate
+      end
+
+      def charge_indicator(node, group_id)
+        @charge_indicators ||= {}.compare_by_identity
+        @charge_indicators.fetch(node) do
+          path = './ram:ChargeIndicator/udt:Indicator'
+          @charge_indicators[node] = technical_boolean(
+            path, node, term_id: "#{group_id}-1", required: true, missing_path: group_xpath("#{group_id}-1")
+          )
+        end
+      end
+
+      def period(group_id, context: @document, base_xpath: nil)
+        node = first_group(group_id, context:, base_xpath:)
+        return unless node
+
+        base = group_xpath(group_id)
+        Period.new(**scalar_attributes(:period, group_id, context: node, base_xpath: base))
+      end
+
+      def totals(currency, tax_currency)
+        node = first_group('BG-22')
+        return unless node
+
+        base = group_xpath('BG-22')
+        attributes = scalar_attributes(:totals, 'BG-22', context: node, base_xpath: base,
+                                                         except: %i[tax_total tax_total_in_tax_currency])
+        Totals.new(**attributes, **tax_total_attributes(node, base, currency, tax_currency))
+      end
+
+      def tax_total_attributes(node, base, currency, tax_currency)
+        total_nodes = node.xpath('./ram:TaxTotalAmount', NAMESPACES)
+        invoice_tax = total_nodes.select { |item| tax_currency.nil? || item['currencyID'] == currency }
+        accounting_tax = total_nodes.select { |item| tax_currency && item['currencyID'] == tax_currency }
+        {
+          tax_total: value('BT-110', context: node, base_xpath: base, nodes: invoice_tax),
+          tax_total_in_tax_currency: value('BT-111', context: node, base_xpath: base, nodes: accounting_tax)
+        }
+      end
+    end
+  end
+end

data/lib/facturx/reader/semantic_mapper.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      EMPTY_TERMS = [].freeze
+      TaxBreakdownResult = Data.define(:items, :vat_point_date)
+
+      def initialize(document:, profile:, registry:, coercer:, diagnostics:)
+        @document = document
+        @profile = profile
+        @terms = TermReader.new(document:, profile:, registry:, coercer:, diagnostics:)
+        @registry = registry
+        active_terms = registry.for_profile(profile)
+        @terms_by_model_and_group = active_terms.group_by { |term| [term.model, term.group_id] }.freeze
+        @terms_by_model_and_attribute = active_terms.group_by { |term| [term.model, term.attribute] }.freeze
+      end
+
+      def call
+        tax_breakdowns = read_tax_breakdowns
+        attributes = document_attributes(tax_breakdowns).merge(
+          party_attributes, transaction_attributes, collection_attributes(tax_breakdowns.items)
+        )
+        attributes[:totals] = totals(attributes[:currency], attributes[:tax_currency])
+        Document.new(**attributes)
+      end
+
+      def add_unmapped(root)
+        @terms.add_unmapped(root)
+      end
+
+      private
+
+      def party_attributes
+        {
+          seller: party('BG-4', contact_group: 'BG-6', address_group: 'BG-5'),
+          buyer: party('BG-7', contact_group: 'BG-9', address_group: 'BG-8'),
+          payee: party('BG-10'),
+          tax_representative: party('BG-11', address_group: 'BG-12')
+        }
+      end
+
+      def transaction_attributes
+        {
+          delivery: delivery, billing_period: period('BG-14'), payment: payment
+        }
+      end
+
+      def collection_attributes(tax_breakdowns)
+        {
+          notes: notes, lines: lines, tax_breakdowns:,
+          allowances: allowance_charges('BG-20', charge: false),
+          charges: allowance_charges('BG-21', charge: true),
+          preceding_invoices: preceding_invoices, supporting_documents: supporting_documents
+        }
+      end
+    end
+  end
+end
+
+require_relative 'semantic_mapper/document_mapping'
+require_relative 'semantic_mapper/party_mapping'
+require_relative 'semantic_mapper/delivery_mapping'
+require_relative 'semantic_mapper/payment_mapping'
+require_relative 'semantic_mapper/line_mapping'
+require_relative 'semantic_mapper/trade_mapping'
+require_relative 'semantic_mapper/helpers'

data/lib/facturx/reader/term_reader/coercion.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class TermReader
+      def coerced_value(xpath, context:, type:, term_id: nil, **options)
+        node = context.at_xpath(xpath, NAMESPACES)
+        return diagnose_raw_missing(options.fetch(:missing_path, xpath), term_id) if node.nil? && options[:required]
+        return unless node
+
+        coerce_raw_value(node, type:, term_id:)
+      rescue CoercionError => e
+        add(:invalid_value, term_id, node.path, e.message, e.details)
+        nil
+      end
+
+      private
+
+      def coerce_raw_value(node, type:, term_id:)
+        mark(node)
+        return diagnose_raw_empty(node, term_id) if node.text.strip.empty?
+
+        @coercer.call(node.text, type:, term_id:, path: node.path)
+      end
+
+      def coerce_term_value(node, term)
+        @coercer.call(node.text, type: term.type, scale: term.scale, term_id: term.id, path: node.path)
+      end
+
+      def coerce(node, term)
+        return diagnose_date_format(node, term) if invalid_date_format?(node, term)
+        return diagnose_empty(node, term) if node.text.strip.empty?
+
+        coerce_term_value(node, term)
+      rescue CoercionError => e
+        add(:invalid_value, term.id, node.path, e.message, e.details)
+        nil
+      end
+
+      def diagnose_empty(node, term)
+        add(:empty_value, term.id, node.path, 'Value is empty', value: node.text)
+        nil
+      end
+
+      def diagnose_raw_empty(node, term_id)
+        add(:empty_value, term_id, node.path, 'Value is empty', value: node.text)
+        nil
+      end
+
+      def diagnose_raw_missing(path, term_id)
+        add(:missing_required_term, term_id, path, 'Required value is missing')
+        nil
+      end
+
+      def invalid_date_format?(node, term)
+        return false unless term.type == :date_102
+
+        format = node.attribute('format')
+        mark(format)
+        format&.value != '102'
+      end
+
+      def diagnose_date_format(node, term)
+        add(:invalid_value, term.id, node.path, 'Date format must be 102', format: node['format'])
+        nil
+      end
+    end
+  end
+end

data/lib/facturx/reader/term_reader/unmapped.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class TermReader
+      IGNORED_ATTRIBUTES = %w[currencyID schemeID].freeze
+
+      def add_unmapped(root)
+        add_unmapped_elements(root)
+        add_unmapped_attributes(root)
+      end
+
+      private
+
+      def add_unmapped_elements(root)
+        root.xpath('.//*[not(*)]').each do |node|
+          next if node.text.empty? || matched?(node)
+
+          add(:unmapped_element, nil, node.path, 'Element is not mapped to the EN16931 model', value: node.text)
+        end
+      end
+
+      def add_unmapped_attributes(root)
+        root.xpath('.//@*').each do |attribute|
+          next if IGNORED_ATTRIBUTES.include?(attribute.name) || matched?(attribute)
+
+          add(:unmapped_element, nil, attribute.path, 'Attribute is not mapped to the EN16931 model',
+              value: attribute.value)
+        end
+      end
+
+      def matched?(node)
+        @matched_nodes.key?(node)
+      end
+    end
+  end
+end