facturx 0.1.0 → 1.0.0

data/lib/facturx/diagnostic.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'model/immutable'
+
+module Facturx
+  Diagnostic = Data.define(:code, :term_id, :path, :message, :details) do
+    include Model::ValidatedWith
+
+    def initialize(code:, message:, term_id: nil, path: nil, details: {})
+      raise TypeError, 'details must be a Hash' unless details.is_a?(Hash)
+
+      bounded_details = details.to_h do |key, value|
+        [key, value.is_a?(String) ? value.byteslice(0, 200).scrub('') : value]
+      end
+      super(code: Model.copy_and_freeze(code), term_id: Model.copy_and_freeze(term_id),
+            path: Model.copy_and_freeze(path), message: Model.copy_and_freeze(message),
+            details: Model.copy_and_freeze(bounded_details))
+    end
+  end
+end

data/lib/facturx/document.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+
+module Facturx
+  Document = Model.define(
+    :guideline_urn,
+    :business_process,
+    :invoice_number,
+    :issue_date,
+    :type_code,
+    :currency,
+    :tax_currency,
+    :vat_point_date,
+    :vat_point_date_code,
+    :payment_due_date,
+    :buyer_reference,
+    :project_reference,
+    :contract_reference,
+    :purchase_order_reference,
+    :sales_order_reference,
+    :receiving_advice_reference,
+    :despatch_advice_reference,
+    :tender_or_lot_reference,
+    :invoiced_object_identifier,
+    :buyer_accounting_reference,
+    :payment_terms,
+    :notes,
+    :seller,
+    :buyer,
+    :payee,
+    :tax_representative,
+    :delivery,
+    :billing_period,
+    :payment,
+    :lines,
+    :tax_breakdowns,
+    :allowances,
+    :charges,
+    :totals,
+    :preceding_invoices,
+    :supporting_documents,
+    collections: %i[notes lines tax_breakdowns allowances charges preceding_invoices supporting_documents]
+  )
+end

data/lib/facturx/error.rb

@@ -13,6 +13,9 @@ module Facturx
   class InvalidXmlError < Error; end
   class UnknownProfileError < InvalidXmlError; end
   class XsdValidationError < InvalidXmlError; end
+  class UnsupportedProfileError < Error; end
+  class FormattingError < Error; end
+  class ConformanceError < 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 'attach'
+require_relative 'profile_resolver'
+require_relative 'writer'
+
+module Facturx
+  class Generate
+    def initialize(writer: Writer.new, attacher: Attach.new, profile_resolver: ProfileResolver.new)
+      @writer = writer
+      @attacher = attacher
+      @profile_resolver = profile_resolver
+    end
+
+    def call(pdf:, document:, profile:)
+      canonical_profile = @profile_resolver.call(profile)
+      xml = @writer.call(document:, profile: canonical_profile)
+      @attacher.call(pdf:, xml:)
+    end
+  end
+end

data/lib/facturx/group.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Facturx
+  Group = Data.define(:id, :model, :attribute, :parent_id, :xpath, :cardinalities)
+end

data/lib/facturx/model/common.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Facturx
+  Note = Model.define(:content, :subject_code)
+  Identifier = Model.define(:value, :scheme_id)
+  Period = Model.define(:start_date, :end_date)
+  Quantity = Model.define(:value, :unit_code)
+end

data/lib/facturx/model/immutable.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Model
+    module Immutability
+      module_function
+
+      def copy(value)
+        case value
+        when Float then raise TypeError, 'Float values are not supported; use BigDecimal for decimal values'
+        when String then value.dup.freeze
+        when Array then value.map { |item| copy(item) }.freeze
+        when Hash then value.to_h { |key, item| [copy(key), copy(item)] }.freeze
+        else copy_object(value)
+        end
+      end
+
+      def copy_object(value)
+        immutable = value.nil? || value == true || value == false || value.is_a?(Numeric) || value.is_a?(Symbol)
+        return value if immutable || value.frozen?
+
+        value.dup.freeze
+      end
+    end
+
+    module ValidatedWith
+      def with(**attributes)
+        self.class.new(**to_h, **attributes)
+      end
+    end
+
+    MISSING = Object.new.freeze
+    private_constant :MISSING
+
+    module_function
+
+    def define(*members, collections: [])
+      collection_members = collections.map(&:to_sym).freeze
+
+      Data.define(*members) do
+        include ValidatedWith
+
+        define_method(:initialize) do |**attributes|
+          normalized = Model.normalize_attributes(self.class.members, collection_members, attributes)
+          super(**normalized)
+        end
+      end
+    end
+
+    def normalize_attributes(members, collections, attributes)
+      validate_attributes!(members, attributes)
+      members.to_h do |member|
+        value = attributes.fetch(member, MISSING)
+        [member, normalize_value(member, value, collections.include?(member))]
+      end
+    end
+
+    def validate_attributes!(members, attributes)
+      unknown = attributes.keys - members
+      raise ArgumentError, "Unknown attributes: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
+    end
+
+    def normalize_value(member, value, collection)
+      value = nil if value.equal?(MISSING)
+      value = [] if collection && value.nil?
+      raise TypeError, "#{member} must be an Array" if collection && !value.is_a?(Array)
+
+      copy_and_freeze(value)
+    end
+
+    def copy_and_freeze(value)
+      Immutability.copy(value)
+    end
+  end
+end

data/lib/facturx/model/line.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Facturx
+  ProductAttribute = Model.define(:name, :value)
+  ProductClassification = Model.define(:code, :list_id, :list_version_id)
+  Product = Model.define(:name, :description, :seller_identifier, :buyer_identifier, :global_identifier,
+                         :origin_country_code, :attributes, :classifications,
+                         collections: %i[attributes classifications])
+  Price = Model.define(:amount, :basis_quantity, :discount)
+  Line = Model.define(:id, :note, :product, :quantity, :gross_price, :net_price, :tax, :period, :net_amount,
+                      :allowances, :charges, :buyer_order_reference, :buyer_accounting_reference,
+                      :invoiced_object_identifier,
+                      collections: %i[allowances charges])
+end

data/lib/facturx/model/party.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Facturx
+  Contact = Model.define(:name, :telephone, :email)
+  Address = Model.define(:postcode, :line_one, :line_two, :line_three, :city, :country_code,
+                         :country_subdivision)
+  Party = Model.define(:identifiers, :name, :description, :legal_registration, :trading_name, :address,
+                       :vat_identifier, :tax_identifier, :electronic_address, :contact,
+                       collections: [:identifiers])
+end

data/lib/facturx/model/payment.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Facturx
+  CreditTransfer = Model.define(:account_identifier, :account_name, :provider_identifier)
+  PaymentCard = Model.define(:primary_account_number, :holder_name)
+  DirectDebit = Model.define(:mandate_identifier, :creditor_identifier, :debtor_account_identifier)
+  PaymentInstructions = Model.define(:means_code, :means_text, :remittance_information, :credit_transfers,
+                                     :payment_card, :direct_debit, collections: [:credit_transfers])
+end

data/lib/facturx/model/reference.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Facturx
+  DocumentReference = Model.define(:id, :line_id, :name, :issue_date)
+  Delivery = Model.define(:location_identifier, :party, :date)
+  SupportingDocument = Model.define(:reference, :description, :external_location, :content, :mime_code, :filename)
+end

data/lib/facturx/model/trade.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Facturx
+  TaxBreakdown = Model.define(:type_code, :category_code, :rate, :basis_amount, :tax_amount,
+                              :exemption_reason, :exemption_reason_code, :due_date_type_code)
+  AllowanceCharge = Model.define(:indicator, :amount, :base_amount, :percentage, :reason, :reason_code, :tax)
+  Totals = Model.define(:line_total, :charge_total, :allowance_total, :tax_basis_total, :tax_total,
+                        :tax_total_in_tax_currency, :grand_total, :prepaid, :rounding, :due_payable)
+end

data/lib/facturx/model.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'model/immutable'
+require_relative 'model/common'
+require_relative 'model/party'
+require_relative 'model/reference'
+require_relative 'model/payment'
+require_relative 'model/trade'
+require_relative 'model/line'

data/lib/facturx/pdf/extractor.rb

@@ -7,6 +7,7 @@ require_relative '../embedding'
 module Facturx
   module Pdf
     class Extractor
+      ACCEPTED_RELATIONSHIPS = %i[Alternative Data].freeze
       Result = Data.define(:xml, :filename, :relationship, :metadata, :page_count)
       Candidate = Data.define(:file_specification, :names)
 
@@ -31,7 +32,7 @@ module Facturx
 
         Result.new(xml: embedded_xml(document, file_specification),
                    filename: FACTURX_EMBEDDING.filename,
-                   relationship: FACTURX_EMBEDDING.relationship,
+                   relationship: file_specification[:AFRelationship],
                    metadata: document.metadata,
                    page_count: document.page_count)
       end
@@ -50,7 +51,9 @@ module Facturx
       end
 
       def matching_candidates(candidates)
-        candidates.select { |candidate| candidate.names.include?(FACTURX_EMBEDDING.filename) }
+        candidates
+          .select { |candidate| candidate.names.include?(FACTURX_EMBEDDING.filename) }
+          .uniq { |candidate| candidate.file_specification.object_id }
       end
 
       def associated_file_candidates(document)
@@ -93,9 +96,9 @@ module Facturx
       end
 
       def validate_relationship!(file_specification)
-        return if file_specification[:AFRelationship] == FACTURX_EMBEDDING.relationship
+        return if ACCEPTED_RELATIONSHIPS.include?(file_specification[:AFRelationship])
 
-        raise ExtractionError.new('Factur-X attachment must use the Alternative relationship',
+        raise ExtractionError.new('Factur-X attachment uses an unsupported relationship',
                                   reason: :invalid_relationship,
                                   relationship: file_specification[:AFRelationship])
       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/reader/semantic_mapper/delivery_mapping.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      private
+
+      def delivery
+        node = first_group('BG-13-00')
+        return unless node
+
+        base = group_xpath('BG-13-00')
+        party_node = first_group('BG-13', context: node, base_xpath: base)
+        party = delivery_party(party_node) if party_node
+        Delivery.new(
+          location_identifier: party_node && delivery_identifier(party_node),
+          party:,
+          date: value('BT-72', context: node, base_xpath: base)
+        )
+      end
+
+      def delivery_party(node)
+        base = group_xpath('BG-13')
+        Party.new(
+          name: value('BT-70', context: node, base_xpath: base),
+          address: address(node, base, 'BG-15')
+        )
+      end
+
+      def delivery_identifier(node)
+        base = group_xpath('BG-13')
+        global_id = node.at_xpath('./ram:GlobalID', NAMESPACES)
+        @terms.mark(global_id) if global_id
+        local_id = value('BT-71', context: node, base_xpath: base)
+        return Identifier.new(value: local_id) if local_id
+
+        return unless global_id
+
+        Identifier.new(value: global_id.text, scheme_id: global_id['schemeID'])
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Reader
+    class SemanticMapper
+      DOCUMENT_REFERENCE_ATTRIBUTES = %i[
+        sales_order_reference purchase_order_reference contract_reference receiving_advice_reference
+        despatch_advice_reference
+      ].freeze
+      DOCUMENT_COMPOSITE_ATTRIBUTES = [
+        *DOCUMENT_REFERENCE_ATTRIBUTES, :tender_or_lot_reference, :invoiced_object_identifier, :project_reference
+      ].freeze
+
+      private
+
+      def document_attributes(tax_breakdowns)
+        scalar_document_attributes(tax_breakdowns).merge(
+          reference_document_attributes,
+          tender_or_lot_reference: additional_reference(:tender_or_lot_reference, type_code: '50'),
+          invoiced_object_identifier: invoiced_object_identifier,
+          project_reference: project_reference
+        )
+      end
+
+      def scalar_document_attributes(tax_breakdowns)
+        attributes = [nil, 'BG-2', 'BG-19'].each_with_object({}) do |group_id, result|
+          result.merge!(scalar_attributes(:document, group_id, except: DOCUMENT_COMPOSITE_ATTRIBUTES))
+        end
+        attributes.merge(vat_point_date: tax_breakdowns.vat_point_date,
+                         vat_point_date_code: tax_breakdowns.items.find(&:due_date_type_code)&.due_date_type_code)
+      end
+
+      def reference_document_attributes
+        DOCUMENT_REFERENCE_ATTRIBUTES.to_h do |attribute|
+          [attribute, reference(term_for_attribute(:document, attribute)&.id)]
+        end
+      end
+
+      def notes
+        group_nodes('BG-1').map do |node|
+          Note.new(**scalar_attributes(:note, 'BG-1', context: node, base_xpath: group_xpath('BG-1')))
+        end
+      end
+
+      def preceding_invoices
+        group_nodes('BG-3').map do |node|
+          base = group_xpath('BG-3')
+          DocumentReference.new(**scalar_attributes(:document_reference, 'BG-3', context: node, base_xpath: base))
+        end
+      end
+
+      def supporting_documents
+        group_nodes('BG-24') { |node| supporting_document?(node) }.map do |node|
+          base = group_xpath('BG-24')
+          SupportingDocument.new(**supporting_document_attributes(node, base))
+        end
+      end
+
+      def supporting_document_attributes(node, base)
+        binary = %i[content mime_code filename]
+        attributes = scalar_attributes(:supporting_document, 'BG-24', context: node, base_xpath: base, except: binary)
+        attributes.merge!(embedded_document_attributes(node, base)) if node.at_xpath('./ram:AttachmentBinaryObject',
+                                                                                     NAMESPACES)
+        attributes
+      end
+
+      def embedded_document_attributes(node, base)
+        scalar_attributes(:supporting_document, 'BG-24', context: node, base_xpath: base,
+                                                         only: %i[content mime_code filename])
+      end
+
+      def supporting_document?(node)
+        technical_value('./ram:TypeCode', node) == '916'
+      end
+
+      def additional_reference(attribute, type_code:)
+        node = @document.at_xpath("#{group_xpath('BG-24')}[ram:TypeCode='#{type_code}']", NAMESPACES)
+        return unless node
+
+        technical_value('./ram:TypeCode', node)
+        term = term_for_attribute(:document, attribute)
+        reference(term&.id, context: node, base_xpath: group_xpath('BG-24'))
+      end
+
+      def invoiced_object_identifier
+        node = @document.at_xpath("#{group_xpath('BG-24')}[ram:TypeCode='130']", NAMESPACES)
+        return unless node
+
+        technical_value('./ram:TypeCode', node)
+        value_term = term_for_attribute(:document, :invoiced_object_identifier, xpath_suffix: '/ram:IssuerAssignedID')
+        scheme_term = term_for_attribute(:document, :invoiced_object_identifier, xpath_suffix: '/ram:ReferenceTypeCode')
+        identifier(value_term&.id, scheme_term&.id, context: node, base_xpath: group_xpath('BG-24'))
+      end
+
+      def project_reference
+        node = @document.at_xpath(
+          '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/' \
+          'ram:ApplicableHeaderTradeAgreement/ram:SpecifiedProcuringProject',
+          NAMESPACES
+        )
+        return unless node
+
+        id = value(term_for_attribute(:document, :project_reference)&.id)
+        name = technical_value('./ram:Name', node)
+        DocumentReference.new(id:, name:)
+      end
+    end
+  end
+end