facturx 0.2.0 → 1.1.0

data/lib/facturx/builders/base.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Builders
+    class Base
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      class << self
+        attr_reader :model, :associations
+
+        def configure(model, associations)
+          @model = model
+          @associations = associations
+          define_attribute_methods
+          self
+        end
+
+        def build(**attributes, &block)
+          builder = new(**attributes)
+          block&.call(builder)
+          builder.build
+        end
+
+        private
+
+        def define_attribute_methods
+          model.members.each do |attribute|
+            association = associations[attribute]
+            association ? define_association_methods(attribute, association) : define_scalar_methods(attribute)
+          end
+        end
+
+        def define_scalar_methods(attribute)
+          define_method(attribute) { @attributes[attribute] }
+          define_method(:"#{attribute}=") { |value| @attributes[attribute] = value }
+        end
+
+        def define_association_methods(attribute, association)
+          if association.collection
+            define_collection_helper(attribute, association)
+          else
+            define_singular_helper(attribute, association)
+          end
+          define_method(:"#{attribute}=") { |value| set_association(attribute, association, value) }
+        end
+
+        def define_singular_helper(attribute, association)
+          define_method(attribute) do |value = UNSET, **attributes, &block|
+            assign_association(attribute, association, value, attributes, block)
+          end
+        end
+
+        def define_collection_helper(attribute, association)
+          define_method(association.helper) do |value = UNSET, **attributes, &block|
+            append_association(attribute, association, value, attributes, block)
+          end
+          define_method(attribute) { @attributes.fetch(attribute, []).dup.freeze }
+        end
+      end
+
+      def initialize(**attributes)
+        unknown = attributes.keys - self.class.model.members
+        raise ArgumentError, "Unknown attributes: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
+
+        @attributes = {}
+        attributes.each { |attribute, value| public_send(:"#{attribute}=", value) }
+      end
+
+      def build
+        self.class.model.new(**@attributes)
+      end
+
+      private
+
+      def assign_association(attribute, association, value, attributes, block)
+        if @attributes.key?(attribute)
+          raise ArgumentError,
+                "#{attribute} is already set; use #{attribute}= to replace it"
+        end
+
+        object = association_value(attribute, association, value, attributes, block)
+        @attributes[attribute] = object
+      end
+
+      def append_association(attribute, association, value, attributes, block)
+        object = association_value(association.helper, association, value, attributes, block)
+        (@attributes[attribute] ||= []) << object
+        object
+      end
+
+      def set_association(attribute, association, value)
+        if association.collection
+          set_collection(attribute, association, value)
+        else
+          validate_object!(attribute, association.model, value) unless value.nil?
+          @attributes[attribute] = value
+        end
+      end
+
+      def set_collection(attribute, association, value)
+        raise TypeError, "#{attribute} must be an Array" unless value.is_a?(Array)
+
+        value.each { |object| validate_object!(attribute, association.model, object) }
+        @attributes[attribute] = value.dup
+      end
+
+      def association_value(name, association, value, attributes, block)
+        forms = [!value.equal?(UNSET), !attributes.empty?, !block.nil?]
+        unless forms.one?
+          raise ArgumentError, "#{name} accepts exactly one of an object, keyword attributes, or a block"
+        end
+
+        return validate_object!(name, association.model, value) unless value.equal?(UNSET)
+
+        builder = Builders.for(association.model)
+        attributes.empty? ? builder.build(&block) : builder.build(**attributes)
+      end
+
+      def validate_object!(attribute, model, object)
+        unless object.instance_of?(model) && object.frozen?
+          raise TypeError, "#{attribute} must be an immutable #{model.name}"
+        end
+
+        object
+      end
+    end
+  end
+end

data/lib/facturx/builders/schema.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'association'
+
+module Facturx
+  module Builders
+    module Schema
+      module_function
+
+      def singular(model)
+        Association.new(model:, collection: false, helper: nil)
+      end
+
+      def collection(model, helper)
+        Association.new(model:, collection: true, helper:)
+      end
+
+      ASSOCIATIONS = {
+        Note => {},
+        Identifier => {},
+        Period => {},
+        Quantity => {},
+        Contact => {},
+        Address => {},
+        Party => {
+          identifiers: collection(Identifier, :identifier),
+          legal_registration: singular(Identifier),
+          address: singular(Address),
+          vat_identifier: singular(Identifier),
+          tax_identifier: singular(Identifier),
+          electronic_address: singular(Identifier),
+          contact: singular(Contact)
+        },
+        CreditTransfer => {
+          account_identifier: singular(Identifier),
+          provider_identifier: singular(Identifier)
+        },
+        PaymentCard => {},
+        DirectDebit => {
+          mandate_identifier: singular(Identifier),
+          creditor_identifier: singular(Identifier),
+          debtor_account_identifier: singular(Identifier)
+        },
+        PaymentInstructions => {
+          credit_transfers: collection(CreditTransfer, :credit_transfer),
+          payment_card: singular(PaymentCard),
+          direct_debit: singular(DirectDebit)
+        },
+        DocumentReference => {},
+        Delivery => {
+          location_identifier: singular(Identifier),
+          party: singular(Party)
+        },
+        SupportingDocument => {},
+        ProductAttribute => {},
+        ProductClassification => {},
+        Product => {
+          seller_identifier: singular(Identifier),
+          buyer_identifier: singular(Identifier),
+          global_identifier: singular(Identifier),
+          attributes: collection(ProductAttribute, :attribute),
+          classifications: collection(ProductClassification, :classification)
+        },
+        Price => {
+          basis_quantity: singular(Quantity)
+        },
+        TaxBreakdown => {},
+        AllowanceCharge => {
+          tax: singular(TaxBreakdown)
+        },
+        Totals => {},
+        Line => {
+          product: singular(Product),
+          quantity: singular(Quantity),
+          gross_price: singular(Price),
+          net_price: singular(Price),
+          tax: singular(TaxBreakdown),
+          period: singular(Period),
+          allowances: collection(AllowanceCharge, :allowance),
+          charges: collection(AllowanceCharge, :charge),
+          buyer_order_reference: singular(DocumentReference),
+          invoiced_object_identifier: singular(Identifier)
+        },
+        Document => {
+          project_reference: singular(DocumentReference),
+          contract_reference: singular(DocumentReference),
+          purchase_order_reference: singular(DocumentReference),
+          sales_order_reference: singular(DocumentReference),
+          receiving_advice_reference: singular(DocumentReference),
+          despatch_advice_reference: singular(DocumentReference),
+          tender_or_lot_reference: singular(DocumentReference),
+          invoiced_object_identifier: singular(Identifier),
+          seller: singular(Party),
+          buyer: singular(Party),
+          payee: singular(Party),
+          tax_representative: singular(Party),
+          delivery: singular(Delivery),
+          billing_period: singular(Period),
+          payment: singular(PaymentInstructions),
+          totals: singular(Totals),
+          notes: collection(Note, :note),
+          lines: collection(Line, :line),
+          tax_breakdowns: collection(TaxBreakdown, :tax_breakdown),
+          allowances: collection(AllowanceCharge, :allowance),
+          charges: collection(AllowanceCharge, :charge),
+          preceding_invoices: collection(DocumentReference, :preceding_invoice),
+          supporting_documents: collection(SupportingDocument, :supporting_document)
+        }
+      }.transform_values(&:freeze).freeze
+    end
+  end
+end

data/lib/facturx/builders.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'document'
+require_relative 'builders/schema'
+require_relative 'builders/base'
+
+module Facturx
+  module Builders
+    BUILDERS = Schema::ASSOCIATIONS.to_h do |model, associations|
+      name = :"#{model.name.delete_prefix('Facturx::')}Builder"
+      [model, const_set(name, Class.new(Base).configure(model, associations))]
+    end.freeze
+    private_constant :BUILDERS
+
+    module_function
+
+    def for(model)
+      BUILDERS.fetch(model)
+    end
+  end
+
+  Document.define_singleton_method(:build) do |**attributes, &block|
+    Builders::DocumentBuilder.build(**attributes, &block)
+  end
+end

data/lib/facturx/error.rb

@@ -10,9 +10,15 @@ module Facturx
     end
   end
 
-  class InvalidXmlError < Error; end
+  class ValidationError < Error; end
+  class InvalidDocumentError < ValidationError; end
+  class InvalidXmlError < ValidationError; end
   class UnknownProfileError < InvalidXmlError; end
   class XsdValidationError < InvalidXmlError; end
+  class SchemaLoadError < Error; end
+  class InvalidSourceError < Error; end
+  class UnsupportedProfileError < Error; end
+  class FormattingError < Error; end
   class InvalidPdfError < Error; end
   class ProtectedPdfError < InvalidPdfError; end
   class ComposerUnavailableError < Error; end

data/lib/facturx/format.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'date'
+require_relative 'error'
+
+module Facturx
+  module Format
+    FORMATTERS = {
+      string: :string,
+      date_102: :formatted_date,
+      decimal: :decimal,
+      boolean: :boolean,
+      binary: :binary
+    }.freeze
+
+    module_function
+
+    def call(value, term:)
+      formatter = FORMATTERS[term.type]
+      raise ArgumentError, "Unsupported format type: #{term.type.inspect}" unless formatter
+
+      begin
+        public_send(formatter, value, term.scale)
+      rescue ArgumentError, TypeError => e
+        raise FormattingError.new(
+          'Value cannot be formatted',
+          value:, type: term.type, scale: term.scale, term_id: term.id, group_id: term.group_id, path: term.xpath
+        ), cause: e
+      end
+    end
+
+    def string(value, _scale = nil)
+      raise TypeError, 'expected a String' unless value.is_a?(String)
+      raise ArgumentError, 'String must contain a non-whitespace character' if value.match?(/\A[[:space:]]*\z/)
+
+      value.dup.freeze
+    end
+
+    def formatted_date(value, _scale = nil)
+      raise TypeError, 'expected a Date' unless value.instance_of?(Date)
+
+      value.strftime('%Y%m%d').freeze
+    end
+
+    def decimal(value, scale = nil)
+      raise TypeError, 'expected a BigDecimal or Integer' unless value.is_a?(BigDecimal) || value.is_a?(Integer)
+      raise ArgumentError, 'decimal must be finite' if value.is_a?(BigDecimal) && !value.finite?
+
+      case scale
+      when nil then fixed_decimal(value)
+      when 2 then fixed_scale(value, 2)
+      else raise ArgumentError, "Unsupported decimal scale: #{scale.inspect}"
+      end.freeze
+    end
+
+    def boolean(value, _scale = nil)
+      return 'true' if value.equal?(true)
+      return 'false' if value.equal?(false)
+
+      raise TypeError, 'expected true or false'
+    end
+
+    def binary(value, _scale = nil)
+      raise TypeError, 'expected a binary String' unless value.is_a?(String) && value.encoding == Encoding::BINARY
+
+      [value].pack('m0').freeze
+    end
+
+    def fixed_decimal(value)
+      value.is_a?(Integer) ? value.to_s : value.to_s('F')
+    end
+    private_class_method :fixed_decimal
+
+    def fixed_scale(value, scale)
+      decimal_value = value.is_a?(Integer) ? BigDecimal(value) : value
+      rounded = decimal_value.round(scale)
+      raise ArgumentError, "decimal has more than #{scale} non-zero fractional digits" unless rounded == decimal_value
+
+      integer, fraction = rounded.to_s('F').split('.', 2)
+      "#{integer}.#{fraction.to_s.ljust(scale, '0')}"
+    end
+    private_class_method :fixed_scale
+  end
+end

data/lib/facturx/generate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'pdf/composer'
+require_relative 'profile_resolver'
+require_relative 'writer'
+
+module Facturx
+  class Generate
+    def initialize(writer: Writer.new, pdf_composer: Pdf::Composer.new, profile_resolver: ProfileResolver.new)
+      @writer = writer
+      @pdf_composer = pdf_composer
+      @profile_resolver = profile_resolver
+    end
+
+    def call(pdf:, document:, profile:)
+      canonical_profile = @profile_resolver.call(profile)
+      xml = @writer.call(document:, profile: canonical_profile)
+      @pdf_composer.call(pdf:, xml:, profile: canonical_profile)
+    end
+  end
+end

data/lib/facturx/pdf/composer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'inspector'
+require_relative 'extractor'
+require_relative 'verifier'
+require_relative '../composers/ghostscript'
+
+module Facturx
+  module Pdf
+    class Composer
+      def initialize(
+        inspector: Inspector.new,
+        backend: Composers::Ghostscript.new,
+        extractor: Extractor.new,
+        verifier: Verifier.new
+      )
+        @inspector = inspector
+        @backend = backend
+        @extractor = extractor
+        @verifier = verifier
+      end
+
+      def call(pdf:, xml:, profile:)
+        inspection = @inspector.call(pdf)
+        output = @backend.call(pdf:, xml:, profile:)
+        result = @extractor.call(output)
+        @verifier.call(result:, expected_xml: xml, expected_page_count: inspection.page_count, profile:)
+        output
+      end
+    end
+  end
+end

data/lib/facturx/profile.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Facturx
-  Profile = Data.define(:id, :guideline_urn, :xsd_path, :conformance_level)
+  Profile = Data.define(:id, :guideline_urn, :conformance_level)
 end

data/lib/facturx/profile_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'profile'
+require_relative 'profiles'
+
+module Facturx
+  class ProfileResolver
+    def initialize(profiles: Profiles)
+      @profiles = profiles
+    end
+
+    def call(profile)
+      canonical = resolve(profile)
+      return canonical unless profile.is_a?(Profile) && !profile.equal?(canonical)
+
+      unsupported!(profile)
+    rescue KeyError
+      unsupported!(profile)
+    end
+
+    private
+
+    def resolve(profile)
+      case profile
+      when Symbol then @profiles.fetch(profile)
+      when Profile
+        return unsupported!(profile) unless profile.id.is_a?(Symbol)
+
+        @profiles.fetch(profile.id)
+      else unsupported!(profile)
+      end
+    end
+
+    def unsupported!(profile)
+      identifier = profile.respond_to?(:id) ? profile.id : profile
+      raise UnsupportedProfileError.new('Factur-X profile is unsupported', profile: identifier)
+    end
+  end
+end

data/lib/facturx/profiles.rb

@@ -4,44 +4,37 @@ require_relative 'profile'
 
 module Facturx
   module Profiles
-    SPECIFICATION_VERSION = '1.09.2'
-    SCHEMA_ROOT = File.expand_path("schema/#{SPECIFICATION_VERSION}", __dir__).freeze
-
     ALL = [
       Profile.new(
         id: :minimum,
         guideline_urn: 'urn:factur-x.eu:1p0:minimum',
-        xsd_path: File.join(SCHEMA_ROOT, 'minimum/Factur-X_1.09.2_MINIMUM.xsd').freeze,
         conformance_level: 'MINIMUM'
       ),
       Profile.new(
         id: :basic_wl,
         guideline_urn: 'urn:factur-x.eu:1p0:basicwl',
-        xsd_path: File.join(SCHEMA_ROOT, 'basic-wl/Factur-X_1.09.2_BASICWL.xsd').freeze,
         conformance_level: 'BASIC WL'
       ),
       Profile.new(
         id: :basic,
         guideline_urn: 'urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic',
-        xsd_path: File.join(SCHEMA_ROOT, 'basic/Factur-X_1.09.2_BASIC.xsd').freeze,
         conformance_level: 'BASIC'
       ),
       Profile.new(
         id: :en16931,
         guideline_urn: 'urn:cen.eu:en16931:2017',
-        xsd_path: File.join(SCHEMA_ROOT, 'en16931/Factur-X_1.09.2_EN16931.xsd').freeze,
         conformance_level: 'EN 16931'
       ),
       Profile.new(
         id: :extended,
         guideline_urn: 'urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended',
-        xsd_path: File.join(SCHEMA_ROOT, 'extended/Factur-X_1.09.2_EXTENDED.xsd').freeze,
         conformance_level: 'EXTENDED'
       )
     ].freeze
 
     BY_ID = ALL.to_h { |profile| [profile.id, profile] }.freeze
     BY_GUIDELINE_URN = ALL.to_h { |profile| [profile.guideline_urn, profile] }.freeze
+    private_constant :ALL, :BY_ID, :BY_GUIDELINE_URN
 
     module_function
 

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

@@ -34,7 +34,7 @@ module Facturx
       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)
+          invoiced_object_identifier: line_invoiced_object_identifier(node, base)
         }
       end
 

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def line_invoiced_object_identifier(parent, parent_base)
+        relative_path = './ram:SpecifiedLineTradeSettlement/ram:AdditionalReferencedDocument'
+        node = parent.at_xpath("#{relative_path}[ram:TypeCode='130']", NAMESPACES)
+        return unless node
+
+        technical_value('./ram:TypeCode', node)
+        base = "#{parent_base}/ram:SpecifiedLineTradeSettlement/ram:AdditionalReferencedDocument"
+        identifier('BT-128', 'BT-128-1', context: node, base_xpath: base)
+      end
+    end
+  end
+end

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

@@ -6,10 +6,13 @@ module Facturx
       private
 
       def payment
-        nodes = group_nodes('BG-16')
+        nodes = group_nodes('BG-16', collapse_if: method(:projected_credit_transfers?))
         base = group_xpath('BG-16')
         attributes = settlement_payment_attributes(nodes.first, base)
-        attributes.merge!(payment_means_attributes(nodes.first, base)) if nodes.first
+        if nodes.any?
+          attributes.merge!(payment_means_attributes(nodes, base,
+                                                     projected: projected_credit_transfers?(nodes)))
+        end
         return if attributes.empty?
 
         PaymentInstructions.new(**attributes)
@@ -22,18 +25,52 @@ module Facturx
         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)
+      def payment_means_attributes(nodes, base, projected:)
+        attributes = scalar_attributes(:payment_instructions, 'BG-16', context: nodes.first, base_xpath: base)
+        payment_nodes = projected ? nodes : [nodes.first]
+        mark_repeated_payment_attributes(payment_nodes.drop(1), base) if projected
+        attributes.merge(
+          credit_transfers: credit_transfers(payment_nodes, base),
+          payment_card: payment_nodes.filter_map { |node| payment_card(node, base) }.first
         )
       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)
+      def mark_repeated_payment_attributes(nodes, base)
+        %w[BT-81 BT-82].each do |term_id|
+          nodes.each { |node| @terms.mark_value(term_id, context: node, base_xpath: base) }
+        end
+      end
+
+      def projected_credit_transfers?(nodes)
+        return false unless nodes.size > 1
+        return false unless nodes.all? { |node| payment_account_count(node) == 1 }
+
+        repeated_payment_attributes?(nodes) && nodes.drop(1).all? { |node| supplemental_payment_node?(node) }
+      end
+
+      def repeated_payment_attributes?(nodes)
+        %w[ram:TypeCode ram:Information].all? do |xpath|
+          nodes.map { |node| node.at_xpath("./#{xpath}", NAMESPACES)&.text }.uniq.one?
+        end
+      end
+
+      def supplemental_payment_node?(node)
+        allowed = %w[TypeCode Information PayeePartyCreditorFinancialAccount
+                     PayeeSpecifiedCreditorFinancialInstitution]
+        node.element_children.all? { |child| allowed.include?(child.name) }
+      end
+
+      def payment_account_count(node)
+        node.xpath('./ram:PayeePartyCreditorFinancialAccount', NAMESPACES).size
+      end
+
+      def credit_transfers(parents, parent_base)
+        provider = term_for(:credit_transfer, 'BG-16', :provider_identifier)
+        parents.flat_map do |parent|
+          provider_identifier = identifier(provider&.id, context: parent, base_xpath: parent_base)
+          group_nodes('BG-17', context: parent, base_xpath: parent_base).map do |node|
+            credit_transfer(node, provider_identifier)
+          end
         end
       end
 

data/lib/facturx/reader/semantic_mapper.rb

@@ -21,6 +21,7 @@ module Facturx
         attributes = document_attributes(tax_breakdowns).merge(
           party_attributes, transaction_attributes, collection_attributes(tax_breakdowns.items)
         )
+        attributes[:tax_currency] ||= minimum_tax_currency(attributes[:currency])
         attributes[:totals] = totals(attributes[:currency], attributes[:tax_currency])
         Document.new(**attributes)
       end
@@ -31,6 +32,13 @@ module Facturx
 
       private
 
+      def minimum_tax_currency(currency)
+        return unless @profile.id == :minimum
+
+        nodes = @document.xpath("#{group_xpath('BG-22')}/ram:TaxTotalAmount", NAMESPACES)
+        nodes.filter_map { |node| node['currencyID'] }.find { |value| value != currency }
+      end
+
       def party_attributes
         {
           seller: party('BG-4', contact_group: 'BG-6', address_group: 'BG-5'),
@@ -63,5 +71,6 @@ 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/line_references'
 require_relative 'semantic_mapper/trade_mapping'
 require_relative 'semantic_mapper/helpers'