en16931 0.1.0

data/lib/en16931/branding.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "prawn"
+
+module EN16931
+  # How the reference layout looks for one seller: a logo, an accent colour,
+  # an own typeface, an opening and a closing line, the GiroCode. All optional;
+  # `Branding.new` is the plain layout. Everything here stays inside PDF/A-3b:
+  # fonts are embedded, images are RGB, the QR code is drawn as vectors.
+  #
+  # @param logo [String, IO, nil] a PNG or JPEG: a path, the file's bytes, or an IO
+  # @param logo_position [:left, :right] where the logo sits in the letterhead
+  # @param logo_height [Numeric] the logo's height in points (its width follows, capped at logo_max_width)
+  # @param accent [String] six hex digits, used for the title and the rules
+  # @param font [String, Hash, nil] a TrueType file, or { normal:, bold: } paths; DejaVu Sans otherwise
+  # @param intro [String, nil] text above the lines, e.g. a salutation
+  # @param closing [String, nil] text below the payment details, e.g. thanks and a signature line
+  # @param giro_code [Boolean] print the EPC QR code (GiroCode) next to the bank details when the invoice can carry one
+  Branding = Data.define(:logo, :logo_position, :logo_height, :logo_max_width, :accent, :font, :intro, :closing, :giro_code) do
+    def initialize(logo: nil, logo_position: :left, logo_height: 40, logo_max_width: 180, accent: "15161A", font: nil,
+                   intro: nil, closing: nil, giro_code: true)
+      raise ArgumentError, "logo_position must be :left or :right" unless %i[left right].include?(logo_position)
+      raise ArgumentError, "accent must be six hex digits, e.g. \"FF5A1F\"" unless accent.to_s.match?(/\A\h{6}\z/)
+
+      super(logo: Branding.image_bytes(logo), logo_position:, logo_height:, logo_max_width:, accent: accent.to_s.upcase,
+            font: Branding.font_files(font), intro:, closing:, giro_code:)
+      logo_info # fail at construction, not at render time
+    end
+
+    # The parsed image: width, height and, for a JPEG, the channel count.
+    # CMYK images would need a CMYK output intent, so they are refused.
+    def logo_info
+      return nil unless logo
+
+      Prawn.image_handler.find(logo).new(logo).tap do |info|
+        raise ArgumentError, "CMYK JPEG logos are not PDF/A-safe with the sRGB output intent; use an RGB image" if info.respond_to?(:channels) && info.channels == 4
+        raise ArgumentError, "interlaced PNGs are not supported; export the logo without interlacing" if info.respond_to?(:interlace_method) && info.interlace_method != 0
+      end
+    end
+
+    # The logo's drawn size: scaled to logo_height, narrower if it would exceed logo_max_width.
+    def logo_size
+      info = logo_info
+      return nil unless info
+
+      scale = [logo_height.to_f / info.height, logo_max_width.to_f / info.width].min
+      [info.width * scale, info.height * scale]
+    end
+
+    # The logo bytes are not worth printing.
+    def inspect = "#<data EN16931::Branding #{to_h.merge(logo: logo && "<#{logo.bytesize} bytes>").map { |k, v| "#{k}=#{v.inspect}" }.join(", ")}>"
+
+    def self.image_bytes(logo)
+      case logo
+      when nil then nil
+      when String
+        logo.b.start_with?("\x89PNG".b, "\xFF\xD8".b) ? logo.b : File.binread(logo)
+      else
+        logo.rewind if logo.respond_to?(:rewind)
+        logo.read.b
+      end
+    end
+
+    def self.font_files(font)
+      case font
+      when nil then nil
+      when String then { normal: font, bold: font }
+      when Hash
+        normal = font[:normal] || font["normal"] or raise ArgumentError, "font needs at least a :normal file"
+        { normal:, bold: font[:bold] || font["bold"] || normal }
+      else raise ArgumentError, "font must be a file path or { normal:, bold: }"
+      end
+    end
+  end
+end

data/lib/en16931/de.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EN16931
+  # German VAT presets. The texts are the customary invoice notes; whether a
+  # case applies to a transaction is a question for the tax adviser, not for
+  # this library.
+  module DE
+    STANDARD_RATE = 19
+    REDUCED_RATE = 7
+
+    module_function
+
+    # Regelbesteuerung, 19 %.
+    def standard = Tax.standard(STANDARD_RATE)
+
+    # Ermäßigter Satz, 7 %.
+    def reduced = Tax.standard(REDUCED_RATE)
+
+    # Kleinunternehmer nach § 19 UStG: no VAT, mandatory note on the invoice.
+    def small_business
+      Tax.exempt(reason: "Gemäß § 19 UStG wird keine Umsatzsteuer berechnet.")
+    end
+
+    # Reverse charge for a business customer in another EU member state
+    # (§ 13b UStG); both VAT identifiers go on the invoice.
+    def reverse_charge
+      Tax.reverse_charge(reason: "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge, § 13b UStG).")
+    end
+
+    # A service to a business outside the EU: the place of supply is abroad
+    # (§ 3a Abs. 2 UStG), nothing is taxable in Germany.
+    def not_taxable_abroad
+      Tax.not_subject(reason: "Nicht im Inland steuerbar; der Leistungsort liegt beim Leistungsempfänger (§ 3a Abs. 2 UStG).")
+    end
+
+    # Goods to a business in another EU member state (§ 4 Nr. 1b UStG).
+    def intra_community_supply
+      Tax.intra_community(reason: "Steuerfreie innergemeinschaftliche Lieferung (§ 4 Nr. 1b UStG).")
+    end
+
+    # Goods exported outside the EU (§ 4 Nr. 1a UStG).
+    def export_supply
+      Tax.export(reason: "Steuerfreie Ausfuhrlieferung (§ 4 Nr. 1a UStG).")
+    end
+  end
+end

data/lib/en16931/invoice.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module EN16931
+  # The invoice as the application knows it: who, to whom, what, under which
+  # VAT treatment. Amounts are BigDecimal, money in the document currency.
+  class Invoice
+    TYPES = {
+      invoice: "380",
+      credit_note: "381",
+      corrected: "384",
+      self_billed: "389",
+      partial: "326",
+      prepayment: "386"
+    }.freeze
+
+    attr_reader :number, :issue_date, :due_date, :seller, :buyer, :lines, :tax, :currency, :buyer_reference,
+                :type, :payment, :period, :notes, :delivery_date, :preceding, :allowances, :charges, :prepaid
+
+    # @param preceding [Hash, nil] { number:, issue_date: } of the invoice a correction refers to (BG-3)
+    # @param period [Range<Date>, nil] the invoicing period (BG-14), e.g. a retainer month
+    def initialize(number:, issue_date:, seller:, buyer:, lines:, tax:, type: :invoice, due_date: nil, currency: "EUR",
+                   buyer_reference: nil, payment: nil, period: nil, notes: [], delivery_date: nil, preceding: nil,
+                   allowances: [], charges: [], prepaid: 0)
+      raise ArgumentError, "unknown type #{type.inspect}" unless TYPES.key?(type)
+      raise ArgumentError, "an invoice needs at least one line" if lines.empty?
+
+      @number = number
+      @issue_date = issue_date
+      @due_date = due_date
+      @seller = seller
+      @buyer = buyer
+      @lines = lines
+      @tax = tax
+      @type = type
+      @currency = currency
+      @buyer_reference = buyer_reference
+      @payment = payment
+      @period = period
+      @notes = Array(notes)
+      @delivery_date = delivery_date
+      @preceding = preceding
+      # The list decides the direction; the flag follows it.
+      @allowances = allowances.map { |a| a.with(charge: false) }
+      @charges = charges.map { |c| c.with(charge: true) }
+      @prepaid = BigDecimal(prepaid.to_s)
+    end
+
+    def type_code = TYPES.fetch(type)
+    def credit_note? = type == :credit_note
+    def correction? = type == :corrected
+
+    def totals = @totals ||= Totals.compute(self)
+
+    # The tax of a line: its own, else the invoice's.
+    def tax_for(line) = line.tax || tax
+
+    # Every tax treatment that appears on the invoice, invoice-level first.
+    def taxes = ([tax] + lines.map(&:tax) + (allowances + charges).map(&:tax)).compact.uniq
+  end
+end

data/lib/en16931/line.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module EN16931
+  # One invoice line (BG-25). Quantity times unit price, rounded to cents,
+  # is the line net (BT-131). The tax defaults to the invoice's tax.
+  #
+  # Common unit codes (UN/ECE Recommendation 20): C62 piece, HUR hour,
+  # DAY day, MON month, LS lump sum, E48 service unit.
+  Line = Data.define(:description, :quantity, :unit, :unit_price, :tax, :note, :sellers_id, :period) do
+    def initialize(description:, unit_price:, quantity: 1, unit: "C62", tax: nil, note: nil, sellers_id: nil, period: nil)
+      super(description:, quantity: BigDecimal(quantity.to_s), unit:, unit_price: BigDecimal(unit_price.to_s),
+            tax:, note:, sellers_id:, period:)
+    end
+
+    def net = (quantity * unit_price).round(2)
+  end
+
+  # A document-level allowance (discount) or charge (BG-20 / BG-21).
+  AllowanceCharge = Data.define(:amount, :reason, :charge, :reason_code, :tax) do
+    def initialize(amount:, reason:, charge: false, reason_code: nil, tax: nil)
+      super(amount: BigDecimal(amount.to_s), reason:, charge:, reason_code:, tax:)
+    end
+
+    def charge? = charge
+    def signed_amount = charge? ? amount : -amount
+  end
+end

data/lib/en16931/party.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module EN16931
+  # Seller (BG-4) or buyer (BG-7). XRechnung needs for the seller a contact
+  # (name, phone, email), an electronic address and a VAT id or tax number;
+  # for the buyer an electronic address. Email is the electronic address
+  # (scheme EM) unless another one is given.
+  Party = Data.define(:name, :street, :postal_code, :city, :country, :vat_id, :tax_number, :email, :phone,
+                      :contact_name, :legal_form, :registration_id, :trading_name, :electronic_address,
+                      :electronic_address_scheme, :identifier, :address_line_2) do
+    def initialize(name:, country:, street: nil, postal_code: nil, city: nil, vat_id: nil, tax_number: nil, email: nil,
+                   phone: nil, contact_name: nil, legal_form: nil, registration_id: nil, trading_name: nil,
+                   electronic_address: nil, electronic_address_scheme: nil, identifier: nil, address_line_2: nil)
+      super
+    end
+
+    def electronic_address_value = electronic_address || email
+    def electronic_address_scheme_value = electronic_address_scheme || "EM"
+
+    # The lines of a postal address as printed.
+    def address_lines
+      [[postal_code, city].compact.join(" ").then { |s| s.empty? ? nil : s }, street, address_line_2].then do |(place, st, extra)|
+        [st, extra, place].compact
+      end
+    end
+  end
+end

data/lib/en16931/payment.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module EN16931
+  # Payment instructions (BG-16): SEPA credit transfer (code 58) by default.
+  # `terms` is the payment terms text (BT-20); `reference` the remittance
+  # information the buyer should quote (BT-83).
+  Payment = Data.define(:iban, :bic, :holder, :means_code, :reference, :terms) do
+    def initialize(iban: nil, bic: nil, holder: nil, means_code: nil, reference: nil, terms: nil)
+      super(iban: iban&.delete(" "), bic: bic&.delete(" "), holder:, means_code: means_code || (iban ? "58" : "1"), reference:, terms:)
+    end
+  end
+end

data/lib/en16931/pdf/a3.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "digest"
+require "zlib"
+
+module EN16931
+  module PDF
+    # Turns a Prawn document into a PDF/A-3b with the invoice XML embedded,
+    # in pure Ruby: PDF 1.7, document identifier, Info dictionary mirrored
+    # in XMP, sRGB output intent, the XML as an associated file (AF) with
+    # the relationship the profile asks for. Fonts must be TrueType, since
+    # PDF/A forbids the unembedded base-14 fonts; the renderer uses DejaVu.
+    module A3
+      ICC_PROFILE = File.join(ROOT, "icc", "sRGB-v2-micro.icc")
+      PRODUCER = "en16931 #{VERSION} (Prawn)".freeze
+
+      # Filename and AF relationship per ZUGFeRD 2.x profile.
+      PROFILES = {
+        xrechnung: { conformance: "XRECHNUNG", filename: "xrechnung.xml", relationship: :Alternative },
+        en16931: { conformance: "EN 16931", filename: "factur-x.xml", relationship: :Alternative },
+        extended: { conformance: "EXTENDED", filename: "factur-x.xml", relationship: :Alternative },
+        basic: { conformance: "BASIC", filename: "factur-x.xml", relationship: :Alternative }
+      }.freeze
+
+      module_function
+
+      # @param pdf [Prawn::Document] a document drawn with embedded TrueType fonts
+      # @param xml [String] the CII invoice XML
+      # @return [Prawn::Document] the same document, ready to `render`
+      def attach(pdf, xml, title:, author:, profile: :xrechnung, created_at: Time.now, creator_tool: PRODUCER, document_type: "INVOICE")
+        spec = PROFILES.fetch(profile) { raise ArgumentError, "unknown profile #{profile.inspect}" }
+        pdf.renderer.min_version(1.7)
+        set_info(pdf, title:, author:, created_at:, creator_tool:)
+        set_identifier(pdf, xml, created_at)
+        add_output_intent(pdf)
+        filespec = embed_file(pdf, xml, spec, created_at)
+        pdf.renderer.names.data[:EmbeddedFiles] = pdf.ref!(Names: [::PDF::Core::LiteralString.new(spec[:filename]), filespec])
+        pdf.state.store.root.data[:AF] = [filespec]
+        add_metadata(pdf, XMP.build(title:, author:, created_at:, producer: PRODUCER, creator_tool:,
+                                    filename: spec[:filename], conformance: spec[:conformance], document_type:))
+        pdf
+      end
+
+      def set_info(pdf, title:, author:, created_at:, creator_tool:)
+        pdf.state.store.info.data.merge!(
+          Title: title, Author: author, Creator: creator_tool, Producer: PRODUCER,
+          CreationDate: created_at, ModDate: created_at
+        )
+      end
+
+      # PDF/A-2 and -3 require the file identifier in the trailer.
+      def set_identifier(pdf, xml, created_at)
+        id = ::PDF::Core::LiteralString.new(Digest::MD5.digest("#{xml}#{created_at.to_f}"))
+        pdf.state.trailer[:ID] = [id, id]
+      end
+
+      # DeviceRGB content needs an output intent; sRGB covers screens and print.
+      def add_output_intent(pdf)
+        icc = pdf.ref!(N: 3)
+        icc << File.binread(ICC_PROFILE)
+        icc.stream.compress!
+        intent = pdf.ref!(
+          Type: :OutputIntent, S: :GTS_PDFA1,
+          OutputConditionIdentifier: ::PDF::Core::LiteralString.new("sRGB"),
+          Info: ::PDF::Core::LiteralString.new("sRGB IEC61966-2.1"),
+          RegistryName: ::PDF::Core::LiteralString.new("http://www.color.org"),
+          DestOutputProfile: icc
+        )
+        pdf.state.store.root.data[:OutputIntents] = [intent]
+      end
+
+      def embed_file(pdf, xml, spec, created_at)
+        bytes = xml.b
+        file = pdf.ref!(Type: :EmbeddedFile, Subtype: :"text/xml", Params: { ModDate: created_at, Size: bytes.bytesize })
+        file << bytes
+        file.stream.compress!
+        pdf.ref!(
+          Type: :Filespec, F: ::PDF::Core::LiteralString.new(spec[:filename]), UF: spec[:filename],
+          Desc: "Invoice data (EN 16931, #{spec[:conformance]})", AFRelationship: spec[:relationship],
+          EF: { F: file, UF: file }
+        )
+      end
+
+      # XMP goes in uncompressed so any reader can find it.
+      def add_metadata(pdf, xmp)
+        metadata = pdf.ref!(Type: :Metadata, Subtype: :XML)
+        metadata << xmp.b
+        pdf.state.store.root.data[:Metadata] = metadata
+      end
+    end
+  end
+end

data/lib/en16931/pdf/giro_code.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rqrcode_core"
+
+module EN16931
+  module PDF
+    # The EPC QR code ("GiroCode"): scanned by a banking app, it prefills a
+    # SEPA credit transfer with the seller's IBAN, the amount and the
+    # remittance text. Version 002 of the EPC guideline; euro only.
+    module GiroCode
+      NAME_LENGTH = 70
+      REMITTANCE_LENGTH = 140
+      MAX_AMOUNT = BigDecimal("999999999.99")
+
+      module_function
+
+      # @return [String, nil] the payload, or nil when the invoice cannot carry a GiroCode
+      def payload(invoice, remittance:)
+        payment = invoice.payment
+        return nil unless payment&.iban && invoice.currency == "EUR"
+
+        amount = invoice.totals.payable
+        return nil unless amount.positive? && amount <= MAX_AMOUNT
+
+        name = (payment.holder || invoice.seller.name).to_s[0, NAME_LENGTH]
+        [
+          "BCD", "002", "1", "SCT",
+          payment.bic.to_s,
+          name,
+          payment.iban,
+          "EUR#{format("%.2f", amount)}",
+          "",
+          "",
+          (payment.reference || remittance).to_s[0, REMITTANCE_LENGTH]
+        ].join("\n")
+      end
+
+      # Draws the code as filled rectangles (no raster image, no transparency),
+      # top-left corner at the current cursor inside the current bounds.
+      def draw(pdf, payload, size:)
+        qr = RQRCodeCore::QRCode.new(payload, level: :m)
+        count = qr.module_count
+        unit = size.to_f / count
+        x0 = pdf.bounds.left
+        y0 = pdf.cursor
+        previous = pdf.fill_color
+        pdf.fill_color "000000"
+        count.times do |row|
+          runs(qr, row, count).each do |start, length|
+            pdf.fill_rectangle [x0 + (start * unit), y0 - (row * unit)], length * unit, unit
+          end
+        end
+        pdf.fill_color previous
+        pdf.move_down size
+      end
+
+      # Consecutive dark modules in a row as [start, length] pairs: fewer objects in the PDF.
+      def runs(qr, row, count)
+        result = []
+        col = 0
+        while col < count
+          if qr.checked?(row, col)
+            start = col
+            col += 1 while col < count && qr.checked?(row, col)
+            result << [start, col - start]
+          else
+            col += 1
+          end
+        end
+        result
+      end
+    end
+  end
+end