tradedoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d87493b2d1156cf4362761b4dc3398dad0c6348ce3170826baec0bfba4828e89
+  data.tar.gz: 24977f17f5d160e53db9bce2515ebf54f8230803dfd29421b70b0481999f9d93
+SHA512:
+  metadata.gz: c557ebc83e0c24369c8fa95290fe21814709f4d87b6b0f7877d98dd6cf5ea6d1805a4a5ba6e087a25b00c5a2ded4fbaabdc237eddfafc802792e5603f3eb3489
+  data.tar.gz: 85ef013be857e6ee3d4038c94aec51f06552d0e34daa75cd63a1e6755df6ed27accb484e5cc63478383382d85c3c6afd52547ef148034dcc95814b9a45616f43

data/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+indent_size = 4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-29
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 mroach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Tradedoc
+
+A Ruby library for reading and writing business trade documents such as invoices,
+credit notes, remittance advice, etc.
+
+## Formats
+
+There are multiple formats for business documents in current use around the world
+and this library aims to be able to support them natively or easily add support for more.
+
+Currently supported:
+
+* **UN/CEFACT** also known as *CII* (Cross-Industry Invoice)
+* **UBL**, Universal Business Language
+
+## Installation
+
+Add it to your Gemfile
+
+```ruby
+gem "tradedoc"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Style
+
+This project uses [Standard](https://github.com/standardrb/standard) as the code style
+and all pull requests must be linted using `standardrb`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dknmz/tradedoc.
+
+## Resources
+
+### EN 16931
+
+* List of business terms: https://peppolvalidator.com/en16931-business-terms
+
+### UBL
+
+* XSD and sample XML files: https://docs.oasis-open.org/ubl/os-UBL-2.4/
+
+### UN/CEFACT / CII
+
+* XSD: https://unece.org/trade/uncefact/mainstandards
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/tradedoc/code/agency.rb

@@ -0,0 +1,8 @@
+module Tradedoc
+  module Code
+    module Agency
+      # https://unece.org/fileadmin/DAM/trade/edifact/code/3055cl.htm
+      CEFACT = "6"
+    end
+  end
+end

data/lib/tradedoc/code/document_type.rb

@@ -0,0 +1,95 @@
+module Tradedoc
+  module Code
+    # Both CII and UBL share the same document type list and codes.
+    # If other formats use different codes, they can be added here to avoid
+    # gnarly and verbose mapping when generating and parsing documents.
+    class DocumentType
+      class << self
+        def get(input)
+          case input
+          in String => cefact_id if cefact_id.match?(/^\d{3}/)
+            @values.values.detect { it.cefact_id == cefact_id }
+          in Symbol => id
+            @values[id]
+          in other
+            raise "can't lookup by '#{other.class}'"
+          end
+        end
+
+        def get!(input)
+          if (v = get(input))
+            return v
+          end
+
+          raise NotFoundError, "no document type could be found from '#{input}'"
+        end
+
+        def parse(input)
+          get!(input)
+        end
+
+        private
+
+        def register(cefact_id, id, label: nil)
+          @values ||= {}
+          if @values.key?(id)
+            raise ArgumentError, "id '#{id}' already registered"
+          end
+
+          @values[id] = new(id:, cefact_id:, label:)
+        end
+      end
+
+      attr_reader :id, :cefact_id, :label
+
+      # @param id [Symbol] Our own identifier for the document type
+      # @param cefact_id [String]
+      #   Numeric code from UN/CEFACT: https://vocabulary.uncefact.org/DocumentCodeList
+      # @param label [String] Optional user-friendly label
+      def initialize(id:, cefact_id:, label: nil)
+        @id = id
+        @cefact_id = cefact_id
+        @label = label || id.to_s.tr("_", " ").capitalize
+      end
+
+      def to_h
+        {id:, cefact_id:, label:}
+      end
+
+      def deconstruct_keys(keys)
+        to_h
+      end
+
+      def hash
+        to_h.hash
+      end
+
+      def ==(other)
+        case other
+        in DocumentType => t
+          t.hash == hash
+        in String | Symbol => pattern
+          self == self.class.get(pattern)
+        in Hash => h
+          to_h == h
+        in _
+          false
+        end
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      # https://vocabulary.uncefact.org/DocumentCodeList
+      register "326", :partial_invoice
+      register "380", :commercial_invoice
+      register "381", :credit_note
+      register "383", :debit_note
+      register "384", :corrected_invoice
+      register "386", :prepayment_invoice
+      register "389", :self_billed_invoice
+      register "481", :remittance_advice
+    end
+  end
+end

data/lib/tradedoc/code/national_clearing_system.rb

@@ -0,0 +1,97 @@
+module Tradedoc
+  module Code
+    # Most bank accounts aside from IBAN will have two components: account number + clearing ID
+    # For example in the US, the clearing ID is the routing number.
+    #
+    # For CII/CEFACT, each type gets mapped to an XML element name. Though this is technically
+    # "not the right" place for this, it's less bad than defining a list and then a mapping separately.
+    #
+    # This list comes from ISO-20022 `ExternalClearingSystemIdentificationCode`
+    class NationalClearingSystem
+      attr_reader :iso_code, :cefact_id, :label
+
+      def initialize(iso_code:, cefact_id:, label: nil)
+        @iso_code = iso_code
+        @cefact_id = cefact_id
+        @label = label || cefact_id.sub(/ID$/, "")
+      end
+
+      def to_h
+        {iso_code:, cefact_id:, label:}
+      end
+
+      def deconstruct_keys(keys)
+        to_h
+      end
+
+      def hash
+        to_h.hash
+      end
+
+      def ==(other)
+        case other
+        in NationalClearingSystem => t
+          t.hash == hash
+        in String | Symbol => pattern
+          self == self.class.get(pattern)
+        in Hash => h
+          to_h == h
+        in _
+          false
+        end
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      class << self
+        def all
+          @values.values
+        end
+
+        def find_by_iso_code(input)
+          @values[input]
+        end
+
+        def find_by_cefact_id(cefact_id)
+          @values.detect { it.cefact_id == cefact_id }
+        end
+
+        def parse(input)
+          if (v = find_by_iso_code(input))
+            return v
+          end
+
+          raise "couldn't parse '#{input}' to a clearing code"
+        end
+
+        private
+
+        def register(iso_code, cefact_id, label: nil)
+          @values ||= {}
+          if @values.key?(iso_code)
+            raise ArgumentError, "'#{iso_code}' already registered"
+          end
+
+          @values[iso_code] = new(iso_code:, cefact_id:, label:).freeze
+        end
+
+        def lock_registry!
+          @values.freeze
+        end
+      end
+
+      register "AUBSB", "AustralianBSBID"
+      register "CACPA", "CanadianPaymentsAssociationID"
+      register "GBDSC", "UKSortCodeID"
+      register "HKNCC", "HongKongBankID"
+      register "NZRSA", "NewZealandNCCID"
+      register "USABA", "FedwireRoutingNumberID"
+      register "USPID", "CHIPSUniversalID"
+      register "ZANCC", "SouthAfricanNCCID"
+
+      lock_registry!
+    end
+  end
+end

data/lib/tradedoc/code/payment_means_type.rb

@@ -0,0 +1,107 @@
+module Tradedoc
+  module Code
+    class PaymentMeansType
+      class << self
+        def get(input)
+          case input
+          in String => code
+            @values.values.detect { it.code == code }
+          in Symbol => id
+            @values[id]
+          in other
+            raise "can't lookup by '#{other.class}'"
+          end
+        end
+
+        def get!(input)
+          if (v = get(input))
+            return v
+          end
+
+          raise NotFoundError, "no payment means type could be found from '#{input}'"
+        end
+
+        def parse(input)
+          get!(input)
+        end
+
+        def register(code, id, label: nil)
+          @values ||= {}
+          if @values.key?(id)
+            raise ArgumentError, "id '#{id}' already registered"
+          end
+
+          @values[id] = new(id:, code:, label:)
+        end
+      end
+
+      attr_reader :id, :code, :label
+
+      # @param id [Symbol] Our own internal identifier
+      # @param code [String]
+      #   UN/ECE 4461: https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred4461.htm
+      # @param label [String] Optional user-friendly label.
+      def initialize(id:, code:, label: nil)
+        @id = id
+        @code = code
+        @label = label || id.to_s.tr("_", " ").capitalize
+      end
+
+      def to_h
+        {id:, code:, label:}
+      end
+
+      def deconstruct_keys(keys)
+        to_h
+      end
+
+      def hash
+        to_h.hash
+      end
+
+      def ==(other)
+        case other
+        in PaymentMeansType => t
+          t.hash == hash
+        in String | Symbol => pattern
+          self == self.class.get(pattern)
+        in Hash => h
+          to_h == h
+        in _
+          false
+        end
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      register "1", :instrument_not_defined
+      register "2", :ach_credit, label: "ACH credit"
+      register "3", :ach_debit, label: "ACH debit"
+      register "8", :hold
+      register "9", :national_clearing
+      register "10", :cash
+      register "20", :cheque
+      register "30", :credit_transfer
+      register "31", :debit_transfer
+      register "42", :payment_to_bank_account
+      register "48", :bank_card
+      register "50", :postgiro
+      register "52", :urgent_commercial_payment
+      register "54", :credit_card
+      register "55", :debit_card
+      register "56", :bankgiro
+      register "57", :standing_agreement
+      register "58", :sepa_credit_transfer, label: "SEPA credit transfer"
+      register "59", :sepa_direct_debit, label: "SEPA direct debit"
+      register "68", :online_payment_service
+
+      # From the docs:
+      #   A code assigned within a code list to be used on an
+      #   interim basis and as defined among trading partners
+      #   until a precise code can be assigned to the code list.
+      register "ZZZ", :mutually_defined
+    end
+  end
+end

data/lib/tradedoc/code/tax_category.rb

@@ -0,0 +1,97 @@
+module Tradedoc
+  module Code
+    # UN/EDIFACT 5305 Duty or tax or fee category code
+    # https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred5305.htm
+    class TaxCategory
+      class << self
+        def get(input)
+          case input
+          in String => edifact_id if edifact_id.match?(/^[A-Z]{1,2}$/)
+            @values.values.detect { it.edifact_id == edifact_id }
+          in Symbol => id
+            @values[id]
+          in other
+            raise "can't lookup by '#{other.class}'"
+          end
+        end
+
+        def get!(input)
+          if (v = get(input))
+            return v
+          end
+
+          raise NotFoundError, "no tax category could be found from '#{input}'"
+        end
+
+        def parse(input)
+          get!(input)
+        end
+
+        private
+
+        def register(edifact_id, id)
+          @values ||= {}
+          @values[id] = new(id:, edifact_id:)
+        end
+      end
+
+      attr_reader :id, :edifact_id
+
+      def initialize(id:, edifact_id:)
+        @id = id
+        @edifact_id = edifact_id
+      end
+
+      def to_h
+        {id:, edifact_id:}
+      end
+
+      def deconstruct_keys(keys)
+        to_h
+      end
+
+      def hash
+        to_h.hash
+      end
+
+      def ==(other)
+        case other
+        in TaxCategory => tc
+          tc.hash == hash
+        in String | Symbol => pattern
+          self == self.class.get(pattern)
+        in Hash => h
+          to_h == h
+        in _
+          false
+        end
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      register "A", :mixed_rate
+      register "AA", :lower_rate
+      register "AB", :exempt_for_resale
+      register "AC", :not_due_now
+      register "AD", :due_from_previous
+      register "AE", :reverse_charge
+      register "B", :transferred
+      register "C", :duty_paid_by_supplier
+      register "D", :travel_agent
+      register "E", :exempt
+      register "F", :second_hand_goods
+      register "G", :free_export
+      register "H", :higher_rate
+      register "I", :works_of_art
+      register "J", :collectables_and_antiques
+      register "K", :eea_intra_community_exempt
+      register "L", :canary_islands_general_indirect
+      register "M", :ceuta_melilla
+      register "O", :services_outside_scope
+      register "S", :standard
+      register "Z", :zero_rated
+    end
+  end
+end

data/lib/tradedoc/code.rb

@@ -0,0 +1,12 @@
+module Tradedoc
+  module Code
+    Error = Class.new(Tradedoc::Error)
+    NotFoundError = Class.new(Error)
+  end
+end
+
+require_relative "code/agency"
+require_relative "code/document_type"
+require_relative "code/national_clearing_system"
+require_relative "code/payment_means_type"
+require_relative "code/tax_category"

data/lib/tradedoc/format/apeh.rb

@@ -0,0 +1,36 @@
+module Tradedoc
+  module Format
+    # Legacy Hungarian invoice format that still appears embedded in PDFs on occasion.
+    # We're unlikely to implement support for it, but being able to detect it is a nice feature.
+    module APEH
+      extend Accessors
+      extend Finders
+      extend XMLSerialization
+
+      module Coder
+        class Invoice
+          NS = {
+            "xmlns" => "http://www.apeh.hu/2005/szamla"
+          }
+          private_constant :NS
+
+          def self.namespaces
+            NS
+          end
+
+          def self.can_parse?(xmldoc)
+            xmldoc.root.namespace&.href == namespaces.fetch("xmlns")
+          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/cii/coder/address.rb

@@ -0,0 +1,55 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class Address
+          # Address lines are limited to 5, and each node gets its own name including
+          # the number in English.
+          LINE_WORDS = ["One", "Two", "Three", "Four", "Five"]
+          private_constant :LINE_WORDS
+
+          def self.ruby_type
+            Model::Address
+          end
+
+          def self.dump(w, obj, as:)
+            w.add(as) do
+              w.render(obj.postal_code, as: "PostcodeCode")
+              obj.lines.each_with_index do |line, ix|
+                w.add("Line#{LINE_WORDS[ix]}", line)
+              end
+              w.render(obj.street_name, as: "StreetName")
+              w.render(obj.city, as: "CityName")
+              w.render(obj.country.iso_code, as: "CountryID")
+              w.render(obj.country.name, as: "CountryName")
+              w.render(obj.subdivision&.code, as: "CountrySubDivisionID")
+              w.render(obj.subdivision&.name, as: "CountrySubDivisionName")
+              w.render(obj.building_number, as: "BuildingNumber")
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |obj|
+              obj.subdivision = {}
+              r.parse("ram:PostcodeCode", :String) { obj.postal_code = it }
+              r.parse("ram:StreetName", :String) { obj.street_name = it }
+              r.parse("ram:CityName", :String) { obj.city = it }
+              r.parse("ram:CountrySubDivisionName", :String) { obj.subdivision.name = it }
+              r.parse("ram:CountrySubDivisionID", :String) { obj.subdivision.code = it }
+              r.parse("ram:BuildingNumber", :String) { obj.building_number = it }
+
+              obj.country = Model::Country.new.tap do |c|
+                r.parse("ram:CountryID", :String) { c.iso_code = it }
+                r.parse("ram:CountryName", :String) { c.name = it }
+              end
+
+              LINE_WORDS.each do |word|
+                r.with_node("ram:Line#{word}") { obj.lines.push(r.text) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class BigDecimal
+          def self.ruby_type
+            ::BigDecimal
+          end
+
+          def self.dump(w, obj, as:)
+            w.add(as, obj.to_s("F"))
+          end
+
+          def self.parse(r)
+            ruby_type.interpret_loosely(r.text)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Tradedoc
+  module Format
+    module CII
+      module Coder
+        class Contact
+          def self.ruby_type
+            Model::Contact
+          end
+
+          def self.dump(w, obj, as: "ram:DefinedTradeContact")
+            w.add(as) do
+              w.render(obj.name, as: "ram:PersonName")
+
+              if (tel = obj.phone)
+                w.add("ram:TelephoneUniversalCommunication") do
+                  w.render(tel, as: "ram:CompleteNumber")
+                end
+              end
+
+              if (email = obj.email)
+                w.add("ram:EmailURIUniversalCommunication") do
+                  w.render(email, as: "ram:URIID")
+                end
+              end
+            end
+          end
+
+          def self.parse(r)
+            ruby_type.new.tap do |c|
+              r.parse("ram:PersonName", :String) { c.name = it }
+              r.with_node("ram:TelephoneUniversalCommunication") do
+                r.parse("ram:CompleteNumber", :String) { c.phone = it }
+              end
+              r.with_node("ram:EmailURIUniversalCommunication") do
+                r.parse("ram:URIID", :String) { c.email = it }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end