tradedoc 0.1.0

data/lib/tradedoc/format/ubl/coder/tax_subtotal.rb

@@ -0,0 +1,29 @@
+module Tradedoc
+  module Format
+    module UBL
+      module Coder
+        class TaxSubtotal
+          def self.ruby_type
+            Model::TaxSubtotal
+          end
+
+          def self.dump(w, obj, as: "cac:TaxSubtotal")
+            w.add(as) do
+              w.render(obj.taxable_amount, as: "TaxableAmount")
+              w.render(obj.tax_amount, as: "TaxAmount")
+              w.render(obj.tax_category, as: "cac:TaxCategory")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |subtotal|
+              r.parse("cbc:TaxableAmount", :Money) { subtotal.taxable_amount = it }
+              r.parse("cbc:TaxAmount", :Money) { subtotal.tax_amount = it }
+              r.parse("cac:TaxCategory", :TaxCategory) { subtotal.tax_category = it }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/ubl/coder/trade_party.rb

@@ -0,0 +1,37 @@
+module Tradedoc
+  module Format
+    module UBL
+      module Coder
+        class TradeParty
+          def self.ruby_type
+            Model::TradeParty
+          end
+
+          def self.dump(w, obj, as: "Party")
+            w.add(as) do
+              w.add("cac:PartyName") do
+                w.add("cbc:Name", obj.name)
+              end
+              w.render(obj.address, as: "PostalAddress")
+              w.render(obj.contact, as: "cac:Contact")
+            end
+          end
+
+          def self.parse(r)
+            obj = ruby_type.new
+
+            r.with_node("cac:Party") do
+              r.with_node("cac:PartyName") do
+                r.parse("cbc:Name", :String) { obj.name = it }
+              end
+              r.parse("cac:PostalAddress", :Address) { obj.address = it }
+              r.parse("cac:Contact", :Contact) { obj.contact = it }
+            end
+
+            obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/ubl/coder.rb

@@ -0,0 +1,29 @@
+module Tradedoc
+  module Format
+    module Coder
+    end
+  end
+end
+
+require_relative "coder/address"
+require_relative "coder/big_decimal"
+require_relative "coder/contact"
+require_relative "coder/country"
+require_relative "coder/date"
+require_relative "coder/document_reference"
+require_relative "coder/exchange_rate"
+require_relative "coder/financial_account"
+require_relative "coder/financial_institution"
+require_relative "coder/invoice"
+require_relative "coder/invoice_line"
+require_relative "coder/monetary_total"
+require_relative "coder/money"
+require_relative "coder/payment_means"
+require_relative "coder/period"
+require_relative "coder/product"
+require_relative "coder/remittance_advice"
+require_relative "coder/string"
+require_relative "coder/tax_breakdown"
+require_relative "coder/tax_category"
+require_relative "coder/tax_subtotal"
+require_relative "coder/trade_party"

data/lib/tradedoc/format/ubl.rb

@@ -0,0 +1,13 @@
+module Tradedoc
+  module Format
+    # Universal Business Language
+    # A open set of standards designed by OASIS
+    module UBL
+      extend Accessors
+      extend Finders
+      extend XMLSerialization
+    end
+  end
+end
+
+require_relative "ubl/coder"

data/lib/tradedoc/format/zugferdv1/coder/invoice.rb

@@ -0,0 +1,33 @@
+module Tradedoc
+  module Format
+    module ZugferdV1
+      module Coder
+        class Invoice
+          NS = {
+            "xmlns:ram" => "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:12",
+            "xmlns:rsm" => "urn:ferd:CrossIndustryDocument:invoice:1p0",
+            "xmlns:udt" => "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:15"
+          }
+          private_constant :NS
+
+          def self.namespaces
+            NS
+          end
+
+          # @param xmldoc [Nokogiri::XML::Document]
+          def self.can_parse?(xmldoc)
+            xmldoc.root.namespace&.href == namespaces.fetch("xmlns:rsm")
+          end
+
+          def self.dump(w, obj)
+            raise NotImplementedError
+          end
+
+          def self.parse(r)
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/zugferdv1/coder.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module ZugferdV1
+    module Coder
+    end
+  end
+end
+
+require_relative "coder/invoice"

data/lib/tradedoc/format/zugferdv1.rb

@@ -0,0 +1,21 @@
+module Tradedoc
+  module Format
+    # ZUGFeRDv1 is a German standard that is the predecessor of CII and its
+    # data structures are quite similar and sometimes identical.
+    #
+    # Not officially obsolete (as of June 2026) but its website says:
+    #     ...has never been officially deprecated but is likely to be discontinued
+    #     and it's not compliant to EN16931
+    module ZugferdV1
+      extend Accessors
+      extend Finders
+      extend XMLSerialization
+
+      def self.label
+        "ZUGFeRDv1"
+      end
+    end
+  end
+end
+
+require_relative "zugferdv1/coder"

data/lib/tradedoc/format.rb

@@ -0,0 +1,110 @@
+module Tradedoc
+  module Format
+    module Accessors
+      # User-friendly label for this format.
+      # @return [String]
+      def label
+        name.split("::").last
+      end
+
+      # List of classes that can dump and parse Ruby objects to/from XML
+      # @return [Array<Class>]
+      def coders
+        ns = self::Coder
+
+        ns.constants.filter_map do |const_name|
+          val = ns.const_get(const_name)
+          if val.respond_to?(:dump) && val.respond_to?(:parse)
+            val
+          end
+        end
+      end
+
+      # For faster detection of what files may be parsable by this format
+      def file_extensions
+        Set[".xml"]
+      end
+
+      # List of coders that are document types.
+      # These are the only ones that can be read/written to/from XML properly.
+      #
+      # @return [Array<Class>]
+      def document_coders
+        coders.select { it.respond_to?(:namespaces) && it.respond_to?(:can_parse?) }
+      end
+    end
+
+    module Finders
+      # Given a Ruby type, get the coder class for it.
+      #
+      # @param coder_ref [Symbol | Class]
+      #   symbol: "bare" name of a type like :Date, :BigDecimal, :TradeParty
+      #   class: one of:
+      #     - Ruby type like `::Date` or `Model::TradeParty` to encode
+      #     - A valid coder class (responds to .dump and .parse)
+      # @return [Class]
+      def coder_for(coder_ref)
+        matches = case coder_ref
+        in Class => coder if coders.include?(coder)
+          [coder]
+        in Class => ruby_type
+          coders.select { it.ruby_type == ruby_type }
+        in Symbol => type_sym
+          coders.select { it.ruby_type.name.split("::").last == type_sym.to_s }
+        end
+
+        if matches.none?
+          raise "couldn't find a coder for '#{coder_ref}'"
+        end
+
+        # This shouldn't happen unless there's a misconfigure in this library itself.
+        if matches.count > 1
+          raise "found multiple coders for #{coder_ref}: #{matches}"
+        end
+
+        matches[0]
+      end
+
+      def detect_document_coder(xmldoc)
+        document_coders.detect { it.can_parse?(xmldoc) }
+      end
+    end
+
+    module XMLSerialization
+      # @param obj [Class] A document-level model to serialize
+      # @return [Nokogiri::XML::Document]
+      def dump(obj)
+        encoding = Encoding::UTF_8.to_s
+        builder = Nokogiri::XML::Builder.new(encoding:) do |xml|
+          writer = XML::Writer.new(xml, format: self)
+          writer.render(obj)
+        end
+        builder.doc
+      end
+
+      # Given an XML document (as an object or string), detect the type
+      # and parse it into a model
+      #
+      # @param source [Nokogiri::XML::Document | String]
+      # @param coder [Class] If the coder is already known
+      # @return [Object] Model instance
+      def parse(source, coder: nil)
+        xml = Tradedoc.xml_from(source)
+        coder ||= detect_document_coder(xml)
+        reader = XML::Reader.new(xml, coder.namespaces, format: self)
+        coder.parse(reader)
+      end
+    end
+  end
+end
+
+require_relative "format/apeh"
+require_relative "format/cii"
+require_relative "format/facturae"
+require_relative "format/fatturapa"
+require_relative "format/isdoc"
+require_relative "format/ksef"
+require_relative "format/mydata"
+require_relative "format/nav"
+require_relative "format/ubl"
+require_relative "format/zugferdv1"

data/lib/tradedoc/model/address.rb

@@ -0,0 +1,21 @@
+module Tradedoc
+  module Model
+    class Address < Base
+      has :city, String
+      has :postal_code, String
+      has :country, Country
+      has :subdivision, CountrySubdivision
+
+      # According to documentation and examples from UBL and CII, address lines
+      # are used when you can't or don't want to break-down the parts of an address
+      # to specific components like building number, suite/apartment number, PO Box,
+      # attention of, care of, department code, etc. Free-form lines are easier to work with.
+      has_many :lines, String
+
+      # Optionally, the specific components of the address lines.
+      has :street_name, String
+      has :building_number, String
+      has :additional_street_name, String
+    end
+  end
+end

data/lib/tradedoc/model/base.rb

@@ -0,0 +1,153 @@
+module Tradedoc
+  module Model
+    # Provides a simple interface for models where you can define the attributes it has
+    # and the correct types for each, and providing some simple coercion.
+    #
+    # @example
+    #   class DocumentLine < Base
+    #     has :id, String
+    #     has :amount, Money
+    #   end
+    #
+    #   class Document < Base
+    #     has :id, String
+    #     has :issue_date, Date
+    #     has_many :lines, Line
+    #   end
+    class Base
+      Element = Data.define(:name, :type, :many)
+
+      module Serialization
+        def dump(to_format)
+          fmt = Tradedoc.format_from(to_format)
+          fmt.dump(self)
+        end
+      end
+
+      def initialize(**attrs)
+        attrs.each { |key, value| public_send(:"#{key}=", value) }
+      end
+
+      class << self
+        def is_document
+          include(Serialization)
+        end
+
+        def has(name, type)
+          def_element(name, type, false)
+
+          ivar_name = :"@#{name}"
+
+          define_method(name) { instance_variable_get(ivar_name) }
+
+          define_method("#{name}=") do |value|
+            value_to_write = self.class.coerce_for(name, value)
+            instance_variable_set(ivar_name, value_to_write)
+          end
+        end
+
+        def has_many(name, type, default: -> { [] })
+          def_element(name, type, true)
+
+          ivar_name = :"@#{name}"
+
+          define_method(name) do
+            unless instance_variable_defined?(ivar_name)
+              instance_variable_set(ivar_name, default.call)
+            end
+
+            instance_variable_get(ivar_name)
+          end
+
+          define_method("#{name}=") do |values|
+            value_to_write = values.map { |value| self.class.coerce_for(name, value) }
+            instance_variable_set(ivar_name, value_to_write)
+          end
+        end
+
+        def inherited(subclass)
+          subclass.inherit_elements(elements)
+          super
+        end
+
+        def elements
+          @elements ||= {}
+        end
+
+        def inherit_elements(other)
+          @elements ||= {}
+          @elements = @elements.merge(other)
+        end
+
+        def coerce_for(element_name, value)
+          proper_type = elements.fetch(element_name).type
+
+          case value
+          in ^proper_type | nil => as_is
+            as_is
+          in other
+            if proper_type < Base
+              proper_type.new(**other)
+            elsif proper_type.respond_to?(:parse)
+              proper_type.parse(other)
+            else
+              proper_type.new(other)
+            end
+          end
+        end
+
+        private
+
+        def def_element(name, type, many)
+          elements[name] = Element.new(name:, type:, many:)
+        end
+      end
+
+      def merge(other)
+        to_h.deep_merge(other.to_h)
+      end
+
+      def to_h
+        self.class.elements.keys.each_with_object({}) do |k, h|
+          h[k] = case send(k)
+          in nil
+            nil
+          in Array => arr
+            arr.map do |item|
+              item.respond_to?(:to_h) ? item.to_h : item
+            end
+          in obj if obj.respond_to?(:to_h)
+            obj.to_h
+          in other
+            other
+          end
+        end
+      end
+
+      def ==(other)
+        case other
+        in nil
+          false
+        in Hash
+          to_h == other
+        in obj if obj.respond_to?(:to_h)
+          to_h == other.to_h
+        in unmatched
+          raise "can't compare #{self.class.name} to #{unmatched}"
+        end
+      end
+
+      def hash
+        to_h.hash
+      end
+
+      def eql?(other)
+        to_h == other
+      end
+
+      def deconstruct_keys(keys)
+        to_h.slice(*keys)
+      end
+    end
+  end
+end

data/lib/tradedoc/model/contact.rb

@@ -0,0 +1,9 @@
+module Tradedoc
+  module Model
+    class Contact < Base
+      has :name, String
+      has :phone, String
+      has :email, String
+    end
+  end
+end

data/lib/tradedoc/model/country.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module Model
+    class Country < Base
+      has :iso_code, String
+      has :name, String
+    end
+  end
+end

data/lib/tradedoc/model/country_subdivision.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module Model
+    class CountrySubdivision < Base
+      has :code, String
+      has :name, String
+    end
+  end
+end

data/lib/tradedoc/model/document.rb

@@ -0,0 +1,9 @@
+module Tradedoc
+  module Model
+    class Document < Base
+      has :id, String
+      has :issue_date, Date
+      has :note, String
+    end
+  end
+end

data/lib/tradedoc/model/document_reference.rb

@@ -0,0 +1,11 @@
+module Tradedoc
+  module Model
+    class DocumentReference < Base
+      has :type, Code::DocumentType
+      has :id, String
+      has :uuid, String
+      has :issue_date, Date
+      has :note, String
+    end
+  end
+end

data/lib/tradedoc/model/exchange_rate.rb

@@ -0,0 +1,17 @@
+module Tradedoc
+  module Model
+    class ExchangeRate < Base
+      has :source_currency_code, String
+      has :target_currency_code, String
+
+      # e.g. 1 USD = 0.92 EU, calculation rate is 0.92
+      has :rate, BigDecimal
+
+      # FX date
+      has :date, Date
+
+      # Where did the exchange rate come from?
+      has :market_id, String
+    end
+  end
+end

data/lib/tradedoc/model/financial_account.rb

@@ -0,0 +1,19 @@
+module Tradedoc
+  module Model
+    class FinancialAccount < Base
+      # Identifies the kind of account numbering scheme
+      # Documentation for this is hard to come by. "IBAN" is for sure one of them,
+      # and "SWIFT" and "SWIFTBIC" have both been observed in samples and docs
+      has :scheme_name, String
+
+      # [BT-84]
+      has :account_number, String
+
+      # [BT-85]
+      has :name, String
+
+      # Only necessary for non-IBAN
+      has :financial_institution, FinancialInstitution
+    end
+  end
+end

data/lib/tradedoc/model/financial_institution.rb

@@ -0,0 +1,11 @@
+module Tradedoc
+  module Model
+    class FinancialInstitution < Base
+      # For SWIFT, this is the BIC
+      # For national clearing systems, this is the member ID e.g. US Routing, UK Sort
+      has :id, String
+
+      has :national_clearing_system, Code::NationalClearingSystem
+    end
+  end
+end

data/lib/tradedoc/model/invoice.rb

@@ -0,0 +1,57 @@
+module Tradedoc
+  module Model
+    class Invoice < Base
+      is_document
+
+      # [BT-1]
+      has :invoice_number, String
+
+      # [BT-2]
+      has :issue_date, Date
+
+      # [BT-3]
+      has :invoice_type_code, String
+
+      # [BT-5]
+      has :currency_code, String
+
+      # [BT-9]
+      has :due_date, Date
+
+      # [BT-10] Identifier created by the buyer for internal routing e.g. cost centre
+      #   If you're looking for a PO number, see BT-13
+      has :buyer_reference, String
+
+      # [BT-13] PO number created by the buyer for three-way matching.
+      has :purchase_order_number, String
+
+      # [BT-22]
+      has :note, String
+      has :payment_means, PaymentMeans
+
+      # [BT-24]
+      # Identifier for the set of rules, content, conformity, etc.
+      # The standard seen for EU invoice is `urn:cen.eu:en16931:2017`
+      has :specification_id, String
+
+      # [BG-5]
+      has :invoice_period, Period
+
+      # [BG-7]
+      has :supplier, TradeParty
+
+      # [BG-10]
+      has :buyer, TradeParty
+
+      # [BG-17]
+      has_many :payment_means, PaymentMeans
+
+      # [BG-22]
+      has :monetary_total, MonetaryTotal
+
+      # [BG-25]
+      has_many :lines, InvoiceLine
+      alias_method :line_items, :lines
+    end
+  end
+end

data/lib/tradedoc/model/invoice_line.rb

@@ -0,0 +1,46 @@
+module Tradedoc
+  module Model
+    class InvoiceLine < Base
+      # [BT-126] Unique ID for the invoice line within the invoice itself
+      has :id, String
+
+      # [BT-127]
+      has :note, String
+
+      # [BT-129]
+      has :invoiced_quantity, BigDecimal
+
+      # [BT-131] Total after discounts and charges, excluding vat
+      has :total_excluding_tax, Money
+
+      has :product, Product
+
+      # [BG-29] Price breakdown / details
+      has :price, Price
+
+      # UBL and CII deal with line-level tax differently.
+      # UBL has a `TaxTotal` at the line level with the amount under it,
+      # then under `Item` has the `ClassifiedTaxCategory`, so they're totally separate.
+      #
+      # CII by contrast uses one `ApplicableTradeTax` element for `TaxSubtotal` which
+      # combines the total tax and tax category into one.
+      # To make access easier, we'll store the amount and category separately and then
+      # have accessors for reading and writing as a `TaxSubtotal`.
+      has :total_tax, Money
+
+      def tax_subtotal
+        TaxSubtotal.new(tax_amount: total_tax, tax_category: product.tax_category).freeze
+      end
+
+      def tax_subtotal=(ts)
+        if (total_tax = ts.tax_amount)
+          self.total_tax = total_tax
+        end
+
+        if (tax_category = ts.tax_category)
+          product.tax_category = tax_category
+        end
+      end
+    end
+  end
+end