facturx 0.1.0 → 1.0.0

data/lib/facturx/writer/stage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+require_relative '../format'
+require_relative '../terms'
+require_relative 'stage_support/contact_details'
+require_relative 'stage_support/emission'
+require_relative 'stage_support/identifiers'
+require_relative 'stage_support/structure'
+
+module Facturx
+  class Writer
+    class Stage
+      include StageSupport::Emission
+      include StageSupport::Structure
+      include StageSupport::ContactDetails
+      include StageSupport::Identifiers
+
+      class << self
+        def term_ids(*ids)
+          @term_ids = ids.map(&:to_s).freeze unless ids.empty?
+          @term_ids || [].freeze
+        end
+      end
+
+      def initialize(context)
+        @context = context
+      end
+
+      private
+
+      attr_reader :context
+
+      def document
+        context.document
+      end
+
+      def profile
+        context.profile
+      end
+
+      def tracker
+        context.tracker
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/contact_details.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module ContactDetails
+        ADDRESS_ELEMENTS = {
+          postcode: 'ram:PostcodeCode',
+          line_one: 'ram:LineOne',
+          line_two: 'ram:LineTwo',
+          line_three: 'ram:LineThree',
+          city: 'ram:CityName',
+          country_code: 'ram:CountryID',
+          country_subdivision: 'ram:CountrySubDivisionName'
+        }.freeze
+
+        private
+
+        def emit_date(parent, id, value, wrapper:, value_element: 'udt:DateTimeString')
+          unless value
+            emit(id, nil, element: value_element, parent:)
+            return
+          end
+
+          container(parent, wrapper) do |node|
+            emit(id, value, element: value_element, parent: node, attributes: { 'format' => '102' })
+          end
+        end
+
+        def emit_address(parent, address, group_id, ids)
+          within_group(group_id, address, element: 'ram:PostalTradeAddress', parent:) do |node, item|
+            ADDRESS_ELEMENTS.each do |attribute, element|
+              emit(ids.fetch(attribute), item.public_send(attribute), element:, parent: node)
+            end
+          end
+        end
+
+        def emit_contact(parent, contact, group_id, ids)
+          within_group(group_id, contact, element: 'ram:DefinedTradeContact', parent:) do |node, item|
+            emit(ids.fetch(:name), item.name, element: 'ram:PersonName', parent: node)
+            communication(node, ids.fetch(:telephone), item.telephone,
+                          'ram:TelephoneUniversalCommunication', 'ram:CompleteNumber')
+            communication(node, ids.fetch(:email), item.email, 'ram:EmailURIUniversalCommunication', 'ram:URIID')
+          end
+        end
+
+        def communication(parent, id, value, wrapper, element)
+          if value
+            container(parent, wrapper) { |node| emit(id, value, element:, parent: node) }
+          else
+            emit(id, nil, element:, parent:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/emission.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Emission
+        private
+
+        def emit(id, value, **options)
+          term = Terms.fetch(id)
+          values = present_values(value)
+          return [] unless options.fetch(:group_present, true)
+
+          accepted = tracker.observe_term?(term, values:, path: term.xpath)
+          return [] unless accepted
+
+          values.filter_map { |item| emit_value(term, item, options) }
+        end
+
+        def emit_attribute(id, value, **options)
+          term = Terms.fetch(id)
+          values = present_values(value)
+          group_present = options.fetch(:group_present, !options.fetch(:node).nil?)
+          return unrepresentable(id, 'Qualifier requires its carrier') if !group_present && values.any?
+          return unless group_present
+
+          accepted = tracker.observe_term?(term, values:, path: term.xpath)
+          return unless accepted
+
+          emit_attribute_value(term, values, options)
+        end
+
+        def observe?(id, value, group_present: true)
+          return false unless group_present
+
+          term = Terms.fetch(id)
+          tracker.observe_term?(term, values: present_values(value), path: term.xpath)
+        end
+
+        def unrepresentable(id, message)
+          term = Terms.fetch(id)
+          tracker.invalid_term(term, error: FormattingError.new(message, path: term.xpath), path: term.xpath)
+        end
+
+        def present_values(value)
+          (value.is_a?(Array) ? value : [value]).compact
+        end
+
+        def format(value, term)
+          Format.call(value, term:)
+        rescue FormattingError => e
+          tracker.invalid_term(term, error: e, path: term.xpath)
+          nil
+        end
+
+        def emit_value(term, value, options)
+          formatted = format(value, term)
+          return unless formatted
+
+          context.element(
+            options.fetch(:parent),
+            options.fetch(:element),
+            text: formatted,
+            attributes: options.fetch(:attributes, {})
+          )
+        end
+
+        def emit_attribute_value(term, values, options)
+          node = options.fetch(:node)
+          return unless node && values.one?
+
+          formatted = format(values.first, term)
+          node[options.fetch(:attribute)] = formatted if formatted
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/identifiers.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Identifiers
+        private
+
+        def emit_compound_identifier(parent, identifier, **options)
+          value_id = options.fetch(:value_id)
+          value = identifier&.value
+          node = emit(value_id, value, element: options.fetch(:element), parent:).first
+          emit_identifier_scheme(node, identifier, options)
+          node
+        end
+
+        def emit_party_identifiers(parent, identifiers, value_id, scheme_id)
+          items = Array(identifiers)
+          local, global = items.partition { |item| item.scheme_id.nil? }
+          missing, global = global.partition { |item| item.value.to_s.strip.empty? }
+          emit_global_identifiers(parent, missing, value_id, scheme_id)
+
+          return unless observe?(value_id, items.map(&:value))
+
+          emit_local_identifiers(parent, local, value_id)
+          emit_global_identifiers(parent, global, value_id, scheme_id)
+        end
+
+        def format_identifier_value(id, value)
+          return if value.nil?
+
+          format(value, Terms.fetch(id))
+        end
+
+        def emit_tax_registration(parent, id, identifier, scheme)
+          report_unrepresentable_identifier_scheme(id, identifier, represented_scheme: scheme)
+          value = identifier&.value
+          unless value
+            observe?(id, nil)
+            return
+          end
+
+          container(parent, 'ram:SpecifiedTaxRegistration') do |node|
+            emit(id, value, element: 'ram:ID', parent: node, attributes: { 'schemeID' => scheme })
+          end
+        end
+
+        def emit_document_reference(parent, id, reference, element, represented_attributes: [])
+          unless reference
+            observe?(id, nil)
+            return
+          end
+
+          represented = [:id, *represented_attributes]
+          report_unrepresentable_reference_attributes(id, reference, represented_attributes: represented)
+
+          container(parent, element) do |node|
+            emit(id, reference.id, element: 'ram:IssuerAssignedID', parent: node)
+          end
+        end
+
+        def emit_invoiced_object(parent, identifier, value_id, scheme_id)
+          unless identifier&.value
+            observe?(value_id, nil)
+            report_unrepresentable_identifier_scheme(scheme_id, identifier)
+            return
+          end
+
+          container(parent, 'ram:AdditionalReferencedDocument') do |node|
+            emit(value_id, identifier.value, element: 'ram:IssuerAssignedID', parent: node)
+            technical(node, 'ram:TypeCode', '130')
+            emit(scheme_id, identifier.scheme_id, element: 'ram:ReferenceTypeCode', parent: node)
+          end
+        end
+
+        def report_unrepresentable_reference_attributes(id, reference, represented_attributes: [])
+          %i[id line_id name issue_date].each do |attribute|
+            next unless reference.public_send(attribute) && !represented_attributes.include?(attribute)
+
+            unrepresentable(id, "Document reference #{attribute} cannot be represented")
+          end
+        end
+
+        def emit_identifier_value(id, identifier, element, parent)
+          report_unrepresentable_identifier_scheme(id, identifier)
+          emit(id, identifier&.value, element:, parent:)
+        end
+
+        def report_unrepresentable_identifier_scheme(id, identifier, represented_scheme: nil)
+          scheme_id = identifier&.scheme_id
+          return unless scheme_id && scheme_id != represented_scheme
+
+          unrepresentable(id, 'Identifier scheme cannot be represented')
+        end
+
+        def emit_identifier_scheme(node, identifier, options)
+          scheme_id = options[:scheme_id]
+          return unless scheme_id
+
+          emit_attribute(
+            scheme_id,
+            identifier&.scheme_id,
+            node:,
+            attribute: options.fetch(:scheme_attribute, 'schemeID'),
+            group_present: !node.nil?
+          )
+        end
+
+        def emit_local_identifiers(parent, identifiers, value_id)
+          identifiers.each do |item|
+            technical(parent, 'ram:ID', format_identifier_value(value_id, item.value))
+          end
+        end
+
+        def emit_global_identifiers(parent, identifiers, value_id, scheme_id)
+          identifiers.each do |item|
+            if item.value.to_s.strip.empty?
+              unrepresentable(value_id, 'Global identifier requires a value')
+              next
+            end
+
+            node = technical(parent, 'ram:GlobalID', format_identifier_value(value_id, item.value))
+            emit_attribute(scheme_id, item.scheme_id, node:, attribute: 'schemeID', group_present: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/structure.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Structure
+        private
+
+        def within_group(id, value, element:, parent:, represented_attributes: [])
+          group = Terms.group(id)
+          values = present_values(value)
+          accepted = tracker.observe_group?(group, count: values.size, path: group.xpath)
+          return unless accepted
+
+          values.each do |item|
+            write_group_item(group, item, element, parent, represented_attributes) { |node| yield(node, item) }
+          end
+        end
+
+        def each_group(id, values, element:, parent:, represented_attributes: [], &)
+          within_group(id, Array(values), element:, parent:, represented_attributes:, &)
+        end
+
+        def write_group_item(group, item, element, parent, represented_attributes)
+          if group.attribute
+            report_unrepresentable_attributes(group.id, item, model: group.model,
+                                                              represented_attributes:)
+          end
+          node = context.element(parent, element)
+          yield node
+          remove_if_empty(node)
+        end
+
+        def technical(parent, element, value, default: nil)
+          text = value.to_s
+          text = default.to_s if text.strip.empty?
+          return if text.strip.empty?
+
+          context.element(parent, element, text:)
+        end
+
+        def container(parent, element)
+          node = context.element(parent, element)
+          yield node
+          remove_if_empty(node)
+          node
+        end
+
+        def remove_if_empty(node)
+          node.remove if node.element_children.empty? && node.text.empty? && node.attribute_nodes.empty?
+        end
+
+        def report_unrepresentable_attributes(group_id, item, model: model_for(item), represented_attributes: [])
+          return unless item.is_a?(Data) && model_for(item) == model
+
+          group = Terms.group(group_id)
+          item.members.each do |attribute|
+            value = item.public_send(attribute)
+            next unless unrepresentable_attribute?(group, model, attribute, value, represented_attributes)
+
+            tracker.unrepresentable_attribute(group, model:, attribute:)
+          end
+        end
+
+        def report_unrepresentable_attribute(group_id, model:, attribute:)
+          tracker.unrepresentable_attribute(Terms.group(group_id), model:, attribute:)
+        end
+
+        def attribute_supported_in_group?(group, model, attribute)
+          Terms.all.any? { |term| term.group_id == group.id && term.model == model && term.attribute == attribute }
+        end
+
+        def unrepresentable_attribute?(group, model, attribute, value, represented_attributes)
+          populated?(value) && !represented_attributes.include?(attribute) &&
+            !attribute_supported_in_group?(group, model, attribute)
+        end
+
+        def populated?(value)
+          !value.nil? && (!value.respond_to?(:empty?) || !value.empty?)
+        end
+
+        def model_for(item)
+          item.class.name.split('::').last.gsub(/([a-z\\d])([A-Z])/, '\\1_\\2').downcase.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/document_context.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class DocumentContext < Stage
+        term_ids 'BT-23', 'BT-24'
+
+        def call
+          within_group('BG-2', document, element: 'rsm:ExchangedDocumentContext', parent: context.root,
+                                         represented_attributes: [:vat_point_date_code]) do |node,|
+            emit_context_parameter(node, 'BT-23', document.business_process,
+                                   'ram:BusinessProcessSpecifiedDocumentContextParameter')
+            guideline = document.guideline_urn || profile.guideline_urn
+            emit_context_parameter(node, 'BT-24', guideline, 'ram:GuidelineSpecifiedDocumentContextParameter')
+          end
+        end
+
+        private
+
+        def emit_context_parameter(parent, id, value, element)
+          if value
+            container(parent, element) { |node| emit(id, value, element: 'ram:ID', parent: node) }
+          else
+            emit(id, nil, element: 'ram:ID', parent: parent)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/exchanged_document.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class ExchangedDocument < Stage
+        term_ids 'BT-1', 'BT-3', 'BT-2', 'BT-22', 'BT-21'
+
+        def call
+          node = context.element(context.root, 'rsm:ExchangedDocument')
+          emit('BT-1', document.invoice_number, element: 'ram:ID', parent: node)
+          emit('BT-3', document.type_code, element: 'ram:TypeCode', parent: node)
+          issue_date(node)
+          notes(node)
+        end
+
+        private
+
+        def notes(parent)
+          each_group('BG-1', document.notes, element: 'ram:IncludedNote', parent:) do |note_node, note|
+            emit('BT-22', note.content, element: 'ram:Content', parent: note_node)
+            emit('BT-21', note.subject_code, element: 'ram:SubjectCode', parent: note_node)
+          end
+        end
+
+        def issue_date(parent)
+          emit_date(parent, 'BT-2', document.issue_date, wrapper: 'ram:IssueDateTime')
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_agreement/parties.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      module TradeAgreementSupport
+        module Parties
+          private
+
+          def write_parties(parent)
+            seller(parent)
+            buyer(parent)
+            tax_representative(parent)
+          end
+
+          def seller(parent)
+            within_group('BG-4', document.seller, element: 'ram:SellerTradeParty', parent:,
+                                                  represented_attributes: %i[address contact]) do |node, party|
+              write_seller_identity(node, party)
+              write_seller_details(node, party)
+            end
+          end
+
+          def write_seller_identity(node, party)
+            emit_party_identifiers(node, party.identifiers, 'BT-29', 'BT-29-1')
+            emit('BT-27', party.name, element: 'ram:Name', parent: node)
+            emit('BT-33', party.description, element: 'ram:Description', parent: node)
+            legal_organization(node, party, 'BT-30', 'BT-30-1', trading_name_id: 'BT-28')
+          end
+
+          def write_seller_details(node, party)
+            emit_contact(node, party.contact, 'BG-6', self.class::SELLER_CONTACT)
+            emit_address(node, party.address, 'BG-5', self.class::SELLER_ADDRESS)
+            electronic_address(node, party.electronic_address, 'BT-34', 'BT-34-1')
+            emit_tax_registration(node, 'BT-31', party.vat_identifier, 'VA')
+            emit_tax_registration(node, 'BT-32', party.tax_identifier, 'FC')
+          end
+
+          def buyer(parent)
+            within_group('BG-7', document.buyer, element: 'ram:BuyerTradeParty', parent:,
+                                                 represented_attributes: %i[address contact]) do |node, party|
+              write_buyer_identity(node, party)
+              write_buyer_details(node, party)
+            end
+          end
+
+          def write_buyer_identity(node, party)
+            emit_party_identifiers(node, party.identifiers, 'BT-46', 'BT-46-1')
+            emit('BT-44', party.name, element: 'ram:Name', parent: node)
+            legal_organization(node, party, 'BT-47', 'BT-47-1', trading_name_id: 'BT-45')
+          end
+
+          def write_buyer_details(node, party)
+            emit_contact(node, party.contact, 'BG-9', self.class::BUYER_CONTACT)
+            emit_address(node, party.address, 'BG-8', self.class::BUYER_ADDRESS)
+            electronic_address(node, party.electronic_address, 'BT-49', 'BT-49-1')
+            emit_tax_registration(node, 'BT-48', party.vat_identifier, 'VA')
+          end
+
+          def tax_representative(parent)
+            within_group('BG-11', document.tax_representative, element: 'ram:SellerTaxRepresentativeTradeParty',
+                                                               parent:,
+                                                               represented_attributes: [:address]) do |node, party|
+              emit('BT-62', party.name, element: 'ram:Name', parent: node)
+              emit_address(node, party.address, 'BG-12', self.class::REPRESENTATIVE_ADDRESS)
+              emit_tax_registration(node, 'BT-63', party.vat_identifier, 'VA')
+            end
+          end
+
+          def legal_organization(parent, party, value_id, scheme_id, trading_name_id:)
+            legal = party.legal_registration
+            trading = party.trading_name
+            return observe_missing_legal_organization(value_id, scheme_id, trading_name_id) unless legal || trading
+
+            container(parent, 'ram:SpecifiedLegalOrganization') do |node|
+              emit_compound_identifier(node, legal, value_id:, scheme_id:, element: 'ram:ID')
+              emit(trading_name_id, trading, element: 'ram:TradingBusinessName', parent: node)
+            end
+          end
+
+          def observe_missing_legal_organization(value_id, scheme_id, trading_name_id)
+            observe?(value_id, nil)
+            observe?(scheme_id, nil, group_present: false)
+            observe?(trading_name_id, nil)
+            nil
+          end
+
+          def electronic_address(parent, identifier, value_id, scheme_id)
+            return observe_missing_identifier(value_id, scheme_id) unless identifier
+
+            container(parent, 'ram:URIUniversalCommunication') do |node|
+              emit_compound_identifier(node, identifier, value_id:, scheme_id:, element: 'ram:URIID')
+            end
+          end
+
+          def observe_missing_identifier(value_id, scheme_id)
+            observe?(value_id, nil)
+            observe?(scheme_id, nil, group_present: false)
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_agreement/references.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      module TradeAgreementSupport
+        module References
+          private
+
+          def write_references(parent)
+            document_references(parent)
+            additional_references(parent)
+            project(parent)
+          end
+
+          def document_references(parent)
+            emit_document_reference(parent, 'BT-14', document.sales_order_reference,
+                                    'ram:SellerOrderReferencedDocument')
+            emit_document_reference(parent, 'BT-13', document.purchase_order_reference,
+                                    'ram:BuyerOrderReferencedDocument')
+            emit_document_reference(parent, 'BT-12', document.contract_reference, 'ram:ContractReferencedDocument')
+          end
+
+          def additional_references(parent)
+            typed_reference(parent, 'BT-17', document.tender_or_lot_reference, '50')
+            invoiced_object_reference(parent)
+            each_group('BG-24', document.supporting_documents, element: 'ram:AdditionalReferencedDocument',
+                                                               parent:) do |node, item|
+              write_supporting_document(node, item)
+            end
+          end
+
+          def write_supporting_document(node, item)
+            emit('BT-122', item.reference, element: 'ram:IssuerAssignedID', parent: node)
+            emit('BT-124', item.external_location, element: 'ram:URIID', parent: node)
+            technical(node, 'ram:TypeCode', '916')
+            emit('BT-123', item.description, element: 'ram:Name', parent: node)
+            attachment(node, item)
+          end
+
+          def typed_reference(parent, id, value, type_code)
+            report_unrepresentable_reference_attributes(id, value, represented_attributes: [:id]) if value
+
+            unless value&.id
+              observe?(id, nil)
+              return
+            end
+
+            container(parent, 'ram:AdditionalReferencedDocument') do |node|
+              emit(id, value.id, element: 'ram:IssuerAssignedID', parent: node)
+              technical(node, 'ram:TypeCode', type_code)
+            end
+          end
+
+          def invoiced_object_reference(parent)
+            emit_invoiced_object(parent, document.invoiced_object_identifier, 'BT-18', 'BT-18-1')
+          end
+
+          def attachment(parent, item)
+            node = emit('BT-125', item.content, element: 'ram:AttachmentBinaryObject', parent:).first
+            present = !item.content.nil?
+            emit_attribute('BT-125-1', item.mime_code, node:, attribute: 'mimeCode', group_present: present)
+            emit_attribute('BT-125-2', item.filename, node:, attribute: 'filename', group_present: present)
+          end
+
+          def project(parent)
+            value = document.project_reference
+            return observe?('BT-11', nil) unless project_reference?(value)
+            return unless representable_project_reference?(value)
+
+            container(parent, 'ram:SpecifiedProcuringProject') do |node|
+              emit('BT-11', value.id, element: 'ram:ID', parent: node)
+              technical(node, 'ram:Name', value.name, default: value.id)
+            end
+          end
+
+          def project_reference?(value)
+            value && (value.id || value.name)
+          end
+
+          def representable_project_reference?(value)
+            report_unrepresentable_reference_attributes('BT-11', value, represented_attributes: %i[id name])
+            return true if value.id
+
+            unrepresentable('BT-11', 'Project reference requires an identifier')
+            false
+          end
+        end
+      end
+    end
+  end
+end