tradedoc 0.1.0

data/lib/tradedoc/model/monetary_total.rb

@@ -0,0 +1,34 @@
+module Tradedoc
+  module Model
+    # [BG-22] Totals for a document
+    class MonetaryTotal < Base
+      # [BT-106] Sum of all line items' net amounts. No tax.
+      #   (quantity * unit price) - line-level discounts
+      has :line_items_tax_exclusive, Money
+
+      # [BT-107] Document-level discounts (aka allowances) e.g. "10% off everything"
+      has :discounts, Money
+
+      # [BT-108] Document-level charges e.g. shipping, processing
+      has :charges, Money
+
+      # [BT-109] aka. net amount
+      has :tax_exclusive, Money
+
+      has :tax_breakdown, TaxBreakdown
+
+      # [BT-112]
+      has :tax_inclusive, Money
+
+      # [BT-113] Money already paid by the buyer *before* this. e.g. deposits
+      has :prepaid, Money
+
+      # [BT-114] Adjustment of a few cents to reconcile discrepancies caused by rounding.
+      has :rounding, Money
+
+      # [BT-115] The actual total amount remaining to be paid by the buyer
+      #   tax_exclusive - prepaid + rounding
+      has :payable, Money
+    end
+  end
+end

data/lib/tradedoc/model/payment_means.rb

@@ -0,0 +1,27 @@
+module Tradedoc
+  module Model
+    class PaymentMeans < Base
+      # [BT-81]
+      has :type_code, Code::PaymentMeansType
+
+      # Multiple formats call these "Payer" and "Payee", but it's too easy to
+      # miss that single character difference which obviously makes a huge difference.
+      # Opt for the obviously distinctive naming.
+      has :sending_account, FinancialAccount
+
+      # [BG-18]
+      has :receiving_account, FinancialAccount
+
+      # [BT-83]
+      has :payment_id, String
+
+      has :instruction_id, String
+
+      # Zero or many lines of messages that were sent to the bank about the payment.
+      # This is the text that the receiving party will typically see in their account
+      # with a label like "message" or "details".
+      # Banking Circle for example allows 4 lines of "remittance information".
+      has_many :messages, String
+    end
+  end
+end

data/lib/tradedoc/model/period.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module Model
+    class Period < Base
+      has :start_date, Date
+      has :end_date, Date
+    end
+  end
+end

data/lib/tradedoc/model/price.rb

@@ -0,0 +1,21 @@
+module Tradedoc
+  module Model
+    # [BG-29]
+    # The price of the invoiced item, including the net price, base quantity,
+    # and any price discount from the gross price.
+    class Price < Base
+      # [BT-146] gross - discount
+      has :net, Money
+
+      # [BT-147] Discount applied to the gross to arrive at the net
+      has :discount, Money
+
+      # [BT-148] Price before any discounts
+      has :gross, Money
+
+      # [BT-149] The quantity to which the price applies
+      #   (e.g. price per 100 units). Defaults to 1 if not specified.
+      has :base_quantity, BigDecimal
+    end
+  end
+end

data/lib/tradedoc/model/product.rb

@@ -0,0 +1,18 @@
+module Tradedoc
+  module Model
+    # [BG-31]
+    # Known in UBL as an `Item`, this is any product or item that can be traded.
+    # Includes things like the description, colour, product code, catalogue code, weights, etc.
+    class Product < Base
+      # [BT-153] Required
+      has :name, String
+
+      # [BT-154]
+      has :description, String
+
+      has :seller_assigned_id, String
+
+      has :tax_category, TaxCategory
+    end
+  end
+end

data/lib/tradedoc/model/remittance_advice.rb

@@ -0,0 +1,20 @@
+module Tradedoc
+  module Model
+    class RemittanceAdvice < Base
+      is_document
+
+      has :id, String
+      has :uuid, String
+      has :issue_date, Date
+      has :note, String
+      has :buyer, TradeParty
+      has :supplier, TradeParty
+      has :total_payment_amount, Money
+      has :invoice_period, Period
+      has :payment_means, PaymentMeans
+
+      has_many :lines, RemittanceAdviceLine
+      alias_method :line_items, :lines
+    end
+  end
+end

data/lib/tradedoc/model/remittance_advice_line.rb

@@ -0,0 +1,24 @@
+module Tradedoc
+  module Model
+    class RemittanceAdviceLine < Base
+      has :id, String
+      has :uuid, String
+      has :note, String
+
+      has :document_reference, DocumentReference
+
+      # Original amount due.
+      # Not supported by CII
+      has :debit_amount, Money
+
+      # If there's any offset/credit to apply. Usually 0.
+      # Not supported by CII
+      has :credit_amount, Money
+
+      # Actual amount being paid.
+      has :balance_amount, Money
+
+      has :exchange_rate, ExchangeRate
+    end
+  end
+end

data/lib/tradedoc/model/tax_breakdown.rb

@@ -0,0 +1,11 @@
+module Tradedoc
+  module Model
+    # [BG-23]
+    class TaxBreakdown < Base
+      # [BT-110] Tax total for the whole document
+      has :total_tax, Money
+
+      has_many :subtotals, TaxSubtotal
+    end
+  end
+end

data/lib/tradedoc/model/tax_category.rb

@@ -0,0 +1,26 @@
+module Tradedoc
+  module Model
+    # [BG-30]
+    class TaxCategory < Base
+      # [BT-118] VAT category code
+      # https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred5305.htm
+      has :code, Code::TaxCategory
+
+      # [BT-119]
+      # Stores as the percentage, not as a fraction of 1. e.g. 4.5% = 4.50
+      has :rate_percent, BigDecimal
+
+      # [BT-120]
+      has :exemption_reason, String
+
+      # [BT-121]
+      # https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/
+      # https://ec.europa.eu/digital-building-blocks/sites/spaces/DIGITAL/pages/467108957/Code+lists
+      # Could also be CWA 15577 codes
+      has :exemption_reason_code, String
+
+      # https://service.unece.org/trade/untdid/d00a/tred/tred5153.htm
+      has :tax_scheme, String
+    end
+  end
+end

data/lib/tradedoc/model/tax_subtotal.rb

@@ -0,0 +1,13 @@
+module Tradedoc
+  module Model
+    class TaxSubtotal < Base
+      # [BT-116] Amount subject to tax
+      has :taxable_amount, Money
+
+      # [BT-117] Amount taxed in this category
+      has :tax_amount, Money
+
+      has :tax_category, TaxCategory
+    end
+  end
+end

data/lib/tradedoc/model/trade_party.rb

@@ -0,0 +1,9 @@
+module Tradedoc
+  module Model
+    class TradeParty < Base
+      has :name, String
+      has :address, Address
+      has :contact, Contact
+    end
+  end
+end

data/lib/tradedoc/model.rb

@@ -0,0 +1,33 @@
+module Tradedoc
+  module Model
+  end
+end
+
+require_relative "model/base"
+
+# no dependencies
+require_relative "model/contact"
+require_relative "model/country"
+require_relative "model/country_subdivision"
+require_relative "model/exchange_rate"
+require_relative "model/financial_institution"
+require_relative "model/period"
+require_relative "model/price"
+require_relative "model/tax_category"
+require_relative "model/tax_subtotal"
+
+# depends on others. order may matter
+require_relative "model/address"
+require_relative "model/financial_account"
+require_relative "model/trade_party"
+require_relative "model/document_reference"
+require_relative "model/tax_breakdown"
+require_relative "model/monetary_total"
+require_relative "model/payment_means"
+require_relative "model/product"
+
+require_relative "model/remittance_advice_line"
+require_relative "model/remittance_advice"
+
+require_relative "model/invoice_line"
+require_relative "model/invoice"

data/lib/tradedoc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tradedoc
+  VERSION = "0.1.0"
+end

data/lib/tradedoc/xml/reader.rb

@@ -0,0 +1,163 @@
+module Tradedoc
+  module XML
+    # Provides an XML reading experience similar to the `Nokogiri::XML::Builder`
+    # experience where you can traverse a document by selecting nodes without
+    # having to constantly do `nil` checks and assign ephemeral variables.
+    class Reader
+      attr_reader :node, :namespaces, :format
+
+      # @param node [Nokogiri::XML::Node]
+      #   XML::Document is also considered a node
+      # @param namespaces [Hash]
+      #   Namespaces *with aliases* to use when reading the document.
+      #  	You must not rely on namespace aliases defined in the source document
+      #   since they can easily be different to what you expect.
+      #   Define a list of all namespaces you'll read from with aliases.
+      #
+      #   { "xmlns:foo" => "urn:example:Foo", "xmlns:bar" => "urn:example:Bar" }
+      # @param format [Module]
+      #   The format to use for parsing.
+      #   Must repond to `.coder_for(type)` to get a coder for a destination type.
+      def initialize(node, namespaces = {}, format:)
+        @node = node
+        @namespaces = namespaces
+        @format = format
+      end
+
+      # If a node exists at the given xpath, yield a reader for that node.
+      # This avoids the pattern nil-checking every single read operation.
+      #
+      # This pattern of swapping-out the current node makes reading XML similar
+      # to building a document with Nokogiri.
+      #
+      # @example
+      #   reader = Reader.new(Nokogiri::XML.parse(str))
+      #   obj = Person.new
+      #
+      #   reader.with_node("Person") do
+      #     obj.id = reader.at_xpath("ID").text
+      #     reader.with_node("Address") do
+      #       obj.address.city = reader.at_xpath("City").text
+      #     end
+      #   end
+      #
+      # @param input [String | Nokogiri::XML::Node] XPath or Node
+      def with_node(input)
+        previous_node = node
+
+        next_node = case input
+        in ::String => xpath
+          at_xpath(xpath)
+        in Nokogiri::XML::Node => n
+          n
+        end
+
+        if next_node.nil?
+          return
+        end
+
+        @node = next_node
+        yield
+      ensure
+        @node = previous_node
+      end
+
+      # Given an xpath that matches 0 or more nodes, maps each element using
+      # the given block. The block will reference the current node.
+      #
+      # @example
+      #   r.with_nodes("LineItem") do
+      #     Model::LineItem.new(description: r.at_xpath("Description").text)
+      #   end
+      #   => [Model::LineItem, Model::LineItem...]
+      def with_nodes(xpath, &block)
+        previous_node = node
+
+        self.xpath(xpath).map do |current|
+          @node = current
+          yield
+        end
+      ensure
+        @node = previous_node
+      end
+
+      # Given an xpath and a type coder class, if that node exists, parse it into
+      # an instance of the "real" type we want out of this node.
+      # Yields the parsed value so that callers can do something with it if
+      # the given node is present
+      #
+      # @example
+      #   r.parse("udt:IssueDate", :Date) { doc.issue_date = it }
+      #
+      # @param xpath [String]
+      # @param coder_ref [Class | Symbol]
+      #   Any class that responds to `.parse(r)` where r is this `Reader`
+      # @param opts [Hash] Options to pass to the underlying parser
+      # @return [Object | nil]
+      def parse(xpath, coder_ref, **opts)
+        coder_class = self.format.coder_for(coder_ref)
+        node_exists = false
+        value = with_node(xpath) do
+          node_exists = true
+          coder_class.parse(self, **opts)
+        end
+
+        # Allows parse callers to do something with the parsed value e.g.
+        # parse("//node", Address) { some_obj.address = it }
+        if block_given? && node_exists
+          yield value
+        else
+          value
+        end
+      end
+
+      def parse_list(xpath, coder_ref, **opts)
+        coder_class = self.format.coder_for(coder_ref)
+
+        values = with_nodes(xpath) do
+          coder_class.parse(self, **opts)
+        end
+
+        if block_given?
+          yield values
+        end
+
+        values
+      end
+
+      def text(strip: true, nilify: true)
+        v = node.text
+
+        return if v.nil?
+
+        if strip
+          v = v.strip
+        end
+
+        if nilify && v.empty?
+          v = nil
+        end
+
+        v
+      end
+
+      def at_xpath(path)
+        node.at_xpath(path, namespaces)
+      end
+
+      def xpath(path)
+        node.xpath(path, namespaces)
+      end
+
+      def attribute(name)
+        attribute!(name)
+      rescue KeyError
+        nil
+      end
+
+      def attribute!(name)
+        node.attributes.fetch(name).text
+      end
+    end
+  end
+end

data/lib/tradedoc/xml/writer.rb

@@ -0,0 +1,56 @@
+module Tradedoc
+  module XML
+    # Wrapper for a `Nokogiri::XML::Builder` that creates an interface for common
+    # build actions, namely rendering "components" easily.
+    class Writer
+      InvalidNodeNameError = Class.new(Error)
+
+      # @param xml [Nokogiri::XML::Builder]
+      # @param format [Module]
+      #   Any module responding to `.coder_for` and returning a coder.
+      #   In reality, should be one of the `Tradedoc.coders`
+      def initialize(xml, format:)
+        @xml = xml
+        @format = format
+      end
+
+      # Directly adds an element to the document without any processing.
+      # Normally with a Nokogiri builder you'd do `xml["ns"].ElemName(text)`
+      # but with this you'd do `writer.add("ns:ElemName", value)`
+      def add(name, ...)
+        if name.include?("/")
+          raise InvalidNodeNameError, "element name #{name} includes `/`"
+        end
+
+        if (c = name.scan(":").count) && c > 1
+          raise InvalidNodeNameError, "element name #{name} includes `:` multiple times"
+        end
+
+        xml.public_send(name, ...)
+      end
+
+      # Given an object, figure out how to dump/render it into the XML builder.
+      #
+      # If the given object/value is `nil`, nothing is rendered. No empty element.
+      # Otherwise, a coder is looked-up and used for the given type.
+      # Assumes that the de-namespaced class name has a matching local coder.
+      #   e.g. `Tradedoc::Model::Country` rendered by `Tradedoc::Format::UBL::Coder::Country`
+      def render(obj, coder_ref = nil, **opts)
+        return if obj.nil?
+
+        coder_class = self.format.coder_for(coder_ref || obj.class)
+        coder_class.dump(self, obj, **opts)
+      end
+
+      def render_list(objects, coder_ref = nil, **opts)
+        return if objects.nil? || objects.none?
+
+        objects.each { render(it, coder_ref, **opts) }
+      end
+
+      private
+
+      attr_reader :xml, :format
+    end
+  end
+end

data/lib/tradedoc/xml.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module XML
+    Error = Class.new(Tradedoc::Error)
+  end
+end
+
+require_relative "xml/reader"
+require_relative "xml/writer"

data/lib/tradedoc.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "nokogiri"
+require "money"
+
+module Tradedoc
+  Error = Class.new(StandardError)
+end
+
+# no dependencies
+require_relative "tradedoc/version"
+require_relative "tradedoc/xml"
+require_relative "tradedoc/code"
+
+# may have dependencies and order may matter
+require_relative "tradedoc/format"
+require_relative "tradedoc/model"
+
+module Tradedoc
+  # List of formats supports for reading and writing documents
+  #
+  # @return [Set<Module>]
+  def self.formats
+    Set[
+      Format::APEH,
+      Format::CII,
+      Format::FacturaE,
+      Format::FatturaPA,
+      Format::ISDOC,
+      Format::KSEF,
+      Format::MyData,
+      Format::NAV,
+      Format::UBL,
+      Format::ZugferdV1
+    ]
+  end
+
+  # List of all possible file extensions that may be parsable by a format in this library
+  #
+  # @return [Set<String>]
+  def self.file_extensions
+    formats.reduce(Set[]) { |memo, fmt| memo + fmt.file_extensions }
+  end
+
+  # Detect the format and document type of a given source
+  #
+  # @return [Array<Module, Class>]
+  def self.detect(source)
+    xml = xml_from(source)
+    formats.each do |fmt|
+      if (dt = fmt.detect_document_coder(xml))
+        return [fmt, dt]
+      end
+    end
+
+    nil
+  end
+
+  # Given an XML document or XML string, detect the format, document type, and
+  # parse it into a model.
+  #
+  # Returns `nil` when the format or document type isn't supported.
+  #
+  # @param source [Nokogiri::XML::Document | String]
+  # @return [Object | nil]
+  def self.parse(source)
+    xml = xml_from(source)
+    if detect(xml) in [fmt, coder]
+      fmt.parse(xml, coder:)
+    end
+  end
+
+  # Get a format by a flexible source selector
+  #
+  # @param source [Symbol | String | Module]
+  # @return [Module]
+  def self.format_from(source)
+    case source
+    in Module => m if formats.include?(m)
+      m
+    in String | Symbol => name
+      name = name.to_s
+      formats.detect { it.label.casecmp?(name) || it.name.split("::").last.casecmp?(name) }
+    end
+  end
+
+  # @param source [String | Nokogiri::XML::Document]
+  # @return [Nokogiri::XML::Document]
+  def self.xml_from(source)
+    case source
+    in Nokogiri::XML::Document => doc
+      doc
+    in String => str
+      Nokogiri::XML.parse(str)
+    end
+  end
+end

data/sig/tradedoc.rbs

@@ -0,0 +1,4 @@
+module Tradedoc
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end