tradedoc 0.1.0

data/lib/tradedoc/format/cii/coder/date.rb

@@ -0,0 +1,87 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        # Dates and times are a bit special.
+        # (This is written for DateTime but this applies to plain Date too)
+        #
+        # Sometimes they're used as `udt:DateTime` which on its own, is an element
+        # requiring a child that is ONE OF: `udt:DateTimeString` or `xsd:DateTime`.
+        # Other times, like `qdt:FormattedIssueDateTime`, it can *only* have a `udt:DateTimeString`.
+        # Since there have been no observed cases of a type not allowing `DateTimeString`,
+        # the default is to generate those. We'll parse either format though.
+        #
+        # This class is called `Date`, but it does get used with schema elements
+        # that are technically a DateTime, so it supports formats for time as well.
+        # The reason for this: most DateTime fields in CII are only Date fields
+        # in other formats and often, a time component doesn't make sense anyway.
+        # For example: invoice date. No need for time.
+        class Date
+          # https://service.unece.org/trade/untdid/d00b/tred/tred2379.htm
+          FORMATS = {
+            "2" => "%d%m%y",
+            "3" => "%m%d%y",
+            "4" => "%d%m%Y",
+            "101" => "%y%m%d",
+            "102" => "%Y%m%d",
+
+            # These are of course time formats, but it allows us to read and write
+            # Time fields as if they're Dates and we get all zeroes for the time components.
+            "204" => "%Y%m%d%H%M%S",
+            "205" => "%Y%m%d%H%M%z"
+          }
+          NS_U = "udt"
+          NS_Q = "qdt"
+          ISO_EL_NAME = "#{NS_U}:Date"
+          UN_EL_NAME = "DateTimeString"
+          DEFAULT_DATE_FORMAT = "102"
+          DEFAULT_TIME_FORMAT = "205"
+
+          private_constant :NS_U, :NS_Q, :ISO_EL_NAME, :UN_EL_NAME
+          private_constant :FORMATS, :DEFAULT_DATE_FORMAT, :DEFAULT_TIME_FORMAT
+
+          def self.ruby_type
+            ::Date
+          end
+
+          # @param obj [Date | Time]
+          # @param format_id [String]
+          #   ID of a pre-defined UN/CEFACT format with a `udt:DateTimeString`
+          #   Use "ISO", or :iso to render an `xsd:Date` with ISO formatting.
+          # @param qualified [Boolean]
+          #   Some time fields use "qualified" times which have the same formats
+          #   as non-qualified, but they use a different namespace.
+          def self.dump(w, obj, as:, format_id: nil, qualified: false)
+            if format_id.nil?
+              format_id = obj.is_a?(::Date) ? DEFAULT_DATE_FORMAT : DEFAULT_TIME_FORMAT
+            end
+
+            w.add(as) do
+              if format_id.to_s.casecmp?("iso")
+                w.add(ISO_EL_NAME, obj.iso8601)
+              else
+                ns = qualified ? NS_Q : NS_U
+                fmt = FORMATS.fetch(format_id)
+                w.add("#{ns}:#{UN_EL_NAME}", obj.strftime(fmt), format: format_id)
+              end
+            end
+          end
+
+          def self.parse(r)
+            # Only one of these nodes will match
+            r.with_node(ISO_EL_NAME) do
+              return ruby_type.parse(r.text)
+            end
+
+            [NS_Q, NS_U].each do |ns|
+              r.with_node("#{ns}:#{UN_EL_NAME}") do
+                format_id = r.attribute("format")
+                return ruby_type.strptime(r.text, FORMATS.fetch(format_id))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/document_reference.rb

@@ -0,0 +1,33 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class DocumentReference
+          def self.ruby_type
+            Model::DocumentReference
+          end
+
+          def self.dump(w, obj, as: "ram:AssociatedReferencedDocument")
+            w.add(as) do
+              w.add("ram:IssuerAssignedID", obj.id)
+              w.add("ram:TypeCode", obj.type.cefact_id, listAgencyID: Code::Agency::CEFACT)
+              w.render(obj.uuid, as: "ram:GlobalID")
+              w.render(obj.issue_date, :Date, as: "ram:FormattedIssueDateTime", qualified: true)
+              w.render(obj.note, as: "ram:IncludedNote")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |dr|
+              r.with_node("ram:TypeCode") { dr.type = Code::DocumentType.get(r.text) }
+              r.parse("ram:IssuerAssignedID", :String) { dr.id = it }
+              r.parse("ram:GlobalID", :String) { dr.uuid = it }
+              r.parse("ram:IncludedNote", :String) { dr.note = it }
+              r.parse("ram:FormattedIssueDateTime", :Date) { dr.issue_date = it }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/exchange_rate.rb

@@ -0,0 +1,33 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class ExchangeRate
+          def self.ruby_type
+            Model::ExchangeRate
+          end
+
+          def self.dump(w, obj, as:)
+            w.add(as) do
+              w.render(obj.source_currency_code, as: "SourceCurrencyCode")
+              w.render(obj.target_currency_code, as: "TargetCurrencyCode")
+              w.render(obj.market_id, as: "MarketID")
+              w.render(obj.rate, as: "ConversionRate")
+              w.render(obj.date, as: "ConversionRateDateTime")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |xr|
+              r.parse("ram:SourceCurrencyCode", :String) { xr.source_currency_code = it }
+              r.parse("ram:TargetCurrencyCode", :String) { xr.target_currency_code = it }
+              r.parse("ram:MarketID", :String) { xr.market_id = it }
+              r.parse("ram:ConversionRate", :BigDecimal) { xr.rate = it }
+              r.parse("ram:ConversionRateDateTime", :Date) { xr.date = it }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/financial_account.rb

@@ -0,0 +1,45 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class FinancialAccount
+          # When an account is IBAN, it gets a node called IBANID with the account number as the text.
+          # For any other account type, the node is ProprietaryID.
+          IBAN_SCHEME = "IBAN"
+          EL_IBAN = "ram:IBANID"
+          EL_PROPRIETARY = "ram:ProprietaryID"
+
+          private_constant :IBAN_SCHEME, :EL_IBAN, :EL_PROPRIETARY
+
+          def self.ruby_type
+            Model::FinancialAccount
+          end
+
+          def self.dump(w, obj, as:)
+            w.add("ram:#{as}") do
+              case obj.scheme_name
+              in IBAN_SCHEME
+                w.add(EL_IBAN, obj.account_number)
+              in other
+                w.add(EL_PROPRIETARY, obj.account_number, schemeName: other)
+              end
+            end
+          end
+
+          def self.parse(r)
+            # only one of these nodes will be present
+
+            r.with_node(EL_IBAN) do
+              return ruby_type.new(scheme_name: IBAN_SCHEME, account_number: r.text)
+            end
+
+            r.with_node(EL_PROPRIETARY) do
+              scheme_name = r.attribute("schemeName")
+              return ruby_type.new(scheme_name:, account_number: r.text)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/financial_institution.rb

@@ -0,0 +1,39 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class FinancialInstitution
+          def self.ruby_type
+            Model::FinancialInstitution
+          end
+
+          # This one is a little unusual.
+          def self.dump(w, obj, as:)
+            w.add(as) do
+              # BIC is *not* a national clearing system.
+              # If no clearing system is defined, then this is BIC.
+              if (ncs = obj.national_clearing_system)
+                w.add("ram:#{ncs.cefact_id}", obj.id)
+              else
+                w.add("ram:BICID", obj.id)
+              end
+            end
+          end
+
+          def self.parse(r)
+            r.with_node("ram:BICID") do
+              return ruby_type.new(id: r.text)
+            end
+
+            # Now we have to figure out the national clearing system by node name
+            Tradedoc::Code::NationalClearingSystem.all.each do |ncs|
+              r.with_node("ram:#{ncs.cefact_id}") do
+                return ruby_type.new(id: r.text, national_clearing_system: ncs)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class Invoice
+          NS = {
+            "xmlns:qdt" => "urn:un:unece:uncefact:data:standard:QualifiedDataType:100",
+            "xmlns:ram" => "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100",
+            "xmlns:rsm" => "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100",
+            "xmlns:udt" => "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
+          }.freeze
+          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.ruby_type
+            Model::Invoice
+          end
+
+          def self.dump(w, obj)
+            w.add("rsm:CrossIndustryInvoice", NS) do
+              if (spec_id = obj.specification_id)
+                w.add("rsm:ExchangedDocumentContext") do
+                  w.add("ram:GuidelineSpecifiedDocumentContextParameter") do
+                    w.render(spec_id, as: "ram:ID")
+                  end
+                end
+              end
+
+              w.add("rsm:ExchangedDocument") do
+                w.render(obj.invoice_number, as: "ram:ID")
+                w.render(obj.invoice_type_code, as: "ram:TypeCode")
+                w.render(obj.issue_date, as: "ram:IssueDateTime")
+                if (note = obj.note)
+                  w.add("ram:IncludedNote") do
+                    w.add("ram:Content", note)
+                  end
+                end
+              end
+
+              w.add("rsm:SupplyChainTradeTransaction") do
+                w.render_list(obj.lines)
+
+                w.add("ram:ApplicableHeaderTradeAgreement") do
+                  w.render(obj.supplier, as: "ram:SellerTradeParty")
+                  w.render(obj.buyer, as: "ram:BuyerTradeParty")
+                end
+
+                w.add("ram:ApplicableHeaderTradeDelivery")
+
+                w.add("ram:ApplicableHeaderTradeSettlement") do
+                  w.render(obj.purchase_order_number, as: "ram:PaymentReference")
+                  w.render(obj.currency_code, as: "ram:InvoiceCurrencyCode")
+
+                  w.render_list(obj.monetary_total&.tax_breakdown&.subtotals)
+
+                  w.add("ram:SpecifiedTradePaymentTerms") do
+                    w.render(obj.due_date, as: "ram:DueDateDateTime")
+                  end
+                  w.render(obj.monetary_total, as: "ram:SpecifiedTradeSettlementHeaderMonetarySummation")
+                end
+              end
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |inv|
+              r.with_node("rsm:CrossIndustryInvoice") do
+                r.with_node("rsm:ExchangedDocumentContext") do
+                  r.parse("ram:GuidelineSpecifiedDocumentContextParameter/ram:ID", :String) { inv.specification_id = it }
+                end
+                r.with_node("rsm:ExchangedDocument") do
+                  r.parse("ram:ID", :String) { inv.invoice_number = it }
+                  r.parse("ram:TypeCode", :String) { inv.invoice_type_code = it }
+                  r.parse("ram:IssueDateTime", :Date) { inv.issue_date = it }
+                  r.parse("ram:IncludedNote", :String) { inv.note = it }
+                end
+
+                # It seems common or normal in CII docs to omit the currency code for money attributes
+                # which is fair enough considering the document specifies a currency code, but
+                # we require a currency code for all `Money` types.
+                # This gets set when parsing `InvoiceCurrencyCode`
+                default_currency = nil
+
+                r.with_node("rsm:SupplyChainTradeTransaction") do
+                  r.with_node("ram:ApplicableHeaderTradeSettlement") do
+                    r.parse("ram:PaymentReference", :String) { inv.purchase_order_number = it }
+                    r.parse("ram:InvoiceCurrencyCode", :String) do
+                      inv.currency_code = it
+                      default_currency = inv.currency_code
+                    end
+                    r.parse_list("ram:SpecifiedTradeSettlementPaymentMeans", :PaymentMeans) { inv.payment_means = it }
+                    r.with_node("ram:SpecifiedTradePaymentTerms") do
+                      r.parse("ram:DueDateDateTime", :Date) { inv.due_date = it }
+                    end
+                    r.parse("ram:SpecifiedTradeSettlementHeaderMonetarySummation", :MonetaryTotal, default_currency:) do
+                      inv.monetary_total = it
+                    end
+                    r.parse_list("ram:ApplicableTradeTax", :TaxSubtotal, default_currency:) do
+                      inv.monetary_total.tax_breakdown.subtotals = it
+                    end
+                  end
+
+                  r.with_node("ram:ApplicableHeaderTradeAgreement") do
+                    r.parse("ram:SellerTradeParty", :TradeParty) { inv.supplier = it }
+                    r.parse("ram:BuyerTradeParty", :TradeParty) { inv.buyer = it }
+                  end
+
+                  r.parse_list("ram:IncludedSupplyChainTradeLineItem", :InvoiceLine, default_currency:) do
+                    inv.lines = it
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/invoice_line.rb

@@ -0,0 +1,88 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class InvoiceLine
+          def self.ruby_type
+            Model::InvoiceLine
+          end
+
+          def self.dump(w, obj)
+            w.add("ram:IncludedSupplyChainTradeLineItem") do
+              w.add("ram:AssociatedDocumentLineDocument") do
+                w.render(obj.id, as: "ram:LineID")
+              end
+
+              w.add("ram:SpecifiedTradeProduct") do
+                w.render(obj.product.seller_assigned_id, as: "ram:SellerAssignedID")
+                w.render(obj.product.name, as: "ram:Name")
+                w.render(obj.product.description, as: "ram:Description")
+              end
+
+              w.add("ram:SpecifiedLineTradeAgreement") do
+                if (gross = obj.price.gross)
+                  w.add("ram:GrossPriceProductTradePrice") do
+                    w.render(gross, as: "ram:ChargeAmount")
+                  end
+                end
+
+                if (net = obj.price.net)
+                  w.add("ram:NetPriceProductTradePrice") do
+                    w.render(net, as: "ram:ChargeAmount")
+                  end
+                end
+              end
+
+              w.add("ram:SpecifiedLineTradeDelivery") do
+                w.render(obj.invoiced_quantity, as: "ram:BilledQuantity")
+              end
+
+              w.add("ram:SpecifiedLineTradeSettlement") do
+                w.render(obj.tax_subtotal)
+                w.add("ram:SpecifiedTradeSettlementLineMonetarySummation") do
+                  w.render(obj.total_excluding_tax, as: "ram:LineTotalAmount")
+                end
+              end
+            end
+          end
+
+          def self.parse(r, default_currency: nil)
+            line = ruby_type.new
+            price = Model::Price.new
+
+            r.parse("ram:AssociatedDocumentLineDocument/ram:LineID", :String) { line.id = it }
+            r.with_node("ram:SpecifiedLineTradeAgreement") do
+              r.with_node("ram:GrossPriceProductTradePrice") do
+                r.parse("ram:ChargeAmount", :Money, default_currency:) { price.gross = it }
+              end
+              r.with_node("ram:NetPriceProductTradePrice") do
+                r.parse("ram:ChargeAmount", :Money, default_currency:) { price.net = it }
+              end
+            end
+            r.with_node("ram:SpecifiedTradeProduct") do
+              line.product = Model::Product.new.tap do |product|
+                r.parse("ram:SellerAssignedID", :String) { product.seller_assigned_id = it }
+                r.parse("ram:Name", :String) { product.name = it }
+                r.parse("ram:Description", :String) { product.description = it }
+              end
+            end
+            r.with_node("ram:SpecifiedLineTradeDelivery") do
+              r.parse("ram:BilledQuantity", :BigDecimal) { line.invoiced_quantity = it }
+            end
+
+            r.with_node("ram:SpecifiedLineTradeSettlement") do
+              r.parse("ram:ApplicableTradeTax", :TaxSubtotal) { line.tax_subtotal = it }
+              r.with_node("ram:SpecifiedTradeSettlementLineMonetarySummation") do
+                r.parse("ram:LineTotalAmount", :Money, default_currency:) { line.total_excluding_tax = it }
+              end
+            end
+
+            line.price = price
+
+            line
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/monetary_total.rb

@@ -0,0 +1,36 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class MonetaryTotal
+          def self.ruby_type
+            Model::MonetaryTotal
+          end
+
+          def self.dump(w, obj, as:)
+            w.add(as) do
+              w.render(obj.line_items_tax_exclusive, as: "ram:LineTotalAmount")
+              w.render(obj.tax_exclusive, as: "ram:TaxBasisTotalAmount")
+              w.render(obj.tax_breakdown.total_tax, as: "ram:TaxTotalAmount")
+              w.render(obj.tax_inclusive, as: "ram:GrandTotalAmount")
+              w.render(obj.payable, as: "ram:DuePayableAmount")
+            end
+          end
+
+          def self.parse(r, **opts)
+            ruby_type.new.tap do |mt|
+              r.parse("ram:LineTotalAmount", :Money, **opts) { mt.line_items_tax_exclusive = it }
+              r.parse("ram:TaxBasisTotalAmount", :Money, **opts) { mt.tax_exclusive = it }
+              r.parse("ram:TaxTotalAmount", :Money, **opts) do
+                mt.tax_breakdown ||= Model::TaxBreakdown.new
+                mt.tax_breakdown.total_tax = it
+              end
+              r.parse("ram:GrandTotalAmount", :Money, **opts) { mt.tax_inclusive = it }
+              r.parse("ram:DuePayableAmount", :Money, **opts) { mt.payable = it }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/money.rb

@@ -0,0 +1,27 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class Money
+          def self.ruby_type
+            ::Money
+          end
+
+          def self.dump(w, obj, as:)
+            formatted = obj.to_d.to_s("F")
+            w.add(as, formatted, currencyID: obj.currency.iso_code)
+          end
+
+          # @param default_currency [String]
+          #   Documents specify a top-level currency that indicate a default.
+          #   Money amount fields may not include the currency code as attributes,
+          #   so in those cases we'll fall-back to the document currency.
+          def self.parse(r, default_currency: nil)
+            iso_code = r.attribute("currencyID") || default_currency
+            ruby_type.from_amount(BigDecimal(r.text), iso_code)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/payment_means.rb

@@ -0,0 +1,49 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class PaymentMeans
+          def self.ruby_type
+            Model::PaymentMeans
+          end
+
+          def self.dump(w, obj)
+            w.add("ram:SpecifiedTradeSettlementPaymentMeans") do
+              w.add("ram:TypeCode", obj.type_code.code, listAgencyID: Code::Agency::CEFACT)
+
+              obj.messages.each do |msg|
+                w.add("ram:Information", msg)
+              end
+
+              w.render(obj.sending_account, as: "PayerPartyDebtorFinancialAccount")
+              w.render(obj.receiving_account, as: "PayeePartyCreditorFinancialAccount")
+
+              w.render(obj.sending_account.financial_institution, as: "PayerSpecifiedDebtorFinancialInstitution")
+              w.render(obj.receiving_account.financial_institution, as: "PayeeSpecifiedCreditorFinancialInstitution")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |pm|
+              r.parse("ram:TypeCode", :String) { pm.type_code = it }
+
+              r.with_nodes("ram:Information") do
+                pm.messages.push(r.text)
+              end
+
+              r.parse("ram:PayerPartyDebtorFinancialAccount", :FinancialAccount) { pm.sending_account = it }
+              r.parse("ram:PayerSpecifiedDebtorFinancialInstitution", :FinancialInstitution) do
+                pm.sending_account.financial_institution = it
+              end
+
+              r.parse("ram:PayeePartyCreditorFinancialAccount", :FinancialAccount) { pm.receiving_account = it }
+              r.parse("ram:PayeeSpecifiedCreditorFinancialInstitution", :FinancialInstitution) do
+                pm.receiving_account.financial_institution = it
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tradedoc/format/cii/coder/period.rb

@@ -0,0 +1,27 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class Period
+          def self.ruby_type
+            Model::Period
+          end
+
+          def self.dump(w, obj, as:)
+            w.add(as) do
+              w.render(obj.start_date, as: "ram:StartDateTime")
+              w.render(obj.end_date, as: "ram:EndDateTime")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |obj|
+              r.parse("ram:StartDateTime", :Date) { obj.start_date = it }
+              r.parse("ram:EndDateTime", :Date) { obj.end_date = it }
+            end
+          end
+        end
+      end
+    end
+  end
+end