invoicehn 0.1.0

data/lib/invoicehn/renderers/json.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Invoicehn
+  module Renderers
+    # Machine-readable form of the document.
+    #
+    # This serves Art. 53 num. 5 — "El Sistema debe tener la capacidad de
+    # generación de archivos tipo texto para su almacenamiento y traslado hacia
+    # la Administración Tributaria a través de servicios web o intercambio de
+    # protocolo" — and is the shape a future electronic-emission module (Art. 54,
+    # CAEE) would build its payload from.
+    #
+    # Every monetary figure is a string. A JSON number would invite the reader
+    # to parse it as a float, and Ley del ISV Art. 9 makes a mis-rounded charge
+    # an offence.
+    class Json
+      attr_reader :invoice
+
+      def initialize(invoice, pretty: true)
+        @invoice = invoice
+        @pretty = pretty
+      end
+
+      def render
+        @pretty ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      end
+      alias to_s render
+
+      def payload = @invoice.to_h
+
+      # A batch export, for handing a period's documents to SAR or to an
+      # accounting system.
+      def self.export(invoices, pretty: true)
+        payload = {
+          "generated_at" => Time.now.utc.iso8601,
+          "count" => invoices.size,
+          "documents" => invoices.map(&:to_h)
+        }
+        pretty ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      end
+
+      # Flat, one row per document — the shape a spreadsheet or an accounting
+      # import expects.
+      def self.export_csv(invoices)
+        headers = %w[
+          correlativo fecha estado cai cliente rtn_cliente moneda
+          subtotal descuentos isv total
+        ]
+
+        rows = invoices.map do |inv|
+          [
+            inv.correlative.to_s,
+            inv.issue_date.iso8601,
+            inv.status,
+            inv.authorization.cai,
+            inv.customer.to_s,
+            inv.customer.rtn&.to_s,
+            inv.currency,
+            inv.subtotal.to_fixed,
+            inv.discount.to_fixed,
+            inv.isv_total.to_fixed,
+            inv.total.to_fixed
+          ]
+        end
+
+        ([headers] + rows).map { |row| row.map { |cell| quote_csv(cell) }.join(",") }.join("\n")
+      end
+
+      def self.quote_csv(value)
+        value = value.to_s
+        value.match?(/[",\n]/) ? "\"#{value.gsub('"', '""')}\"" : value
+      end
+    end
+  end
+end

data/lib/invoicehn/renderers/pdf.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  module Renderers
+    # Renders the Factura as a PDF.
+    #
+    # The legends are the same constants the text renderer uses, so the two
+    # outputs cannot drift apart on the wording the decree fixes.
+    #
+    # Art. 38 forbids issuing fiscal documents on thermal paper and requires the
+    # information to be legible and permanent — a PDF printed on ordinary paper
+    # satisfies that; the operator remains responsible for the medium.
+    class Pdf
+      # Loaded lazily so the rest of the library works without prawn installed.
+      #
+      # LoadError also covers Gem::ConflictError, which is what actually surfaces
+      # when prawn's ttfunk dependency pins bigdecimal and a newer bigdecimal has
+      # already been activated — a conflict rather than a missing file.
+      def self.available?
+        require "prawn"
+        require "prawn/table"
+        true
+      rescue LoadError
+        false
+      end
+
+      # Prawn's built-in AFM fonts encode as Windows-1252. That covers every
+      # accented character Spanish needs, but a name or description carrying
+      # anything outside it would raise mid-render — so text is transcoded with
+      # a replacement rather than allowed to abort a fiscal document.
+      def self.encode(text)
+        text.to_s.encode("Windows-1252", invalid: :replace, undef: :replace, replace: "?")
+            .encode("UTF-8")
+      end
+
+      MARGIN = 36
+      TITLE_SIZE = 16
+      BODY_SIZE = 9
+
+      attr_reader :invoice, :copy
+
+      def initialize(invoice, copy: :original)
+        @invoice = invoice
+        @copy = copy
+      end
+
+      def render_file(path)
+        document.render_file(path)
+        path
+      end
+
+      def render = document.render
+
+      private
+
+      # Shorthand for the Windows-1252 transcode every string on the page goes
+      # through.
+      def e(text) = self.class.encode(text)
+
+      def document
+        unless self.class.available?
+          raise Error, "se requiere la gema «prawn» para generar PDF: gem install prawn prawn-table"
+        end
+
+        Prawn::Fonts::AFM.hide_m17n_warning = true if defined?(Prawn::Fonts::AFM)
+
+        pdf = Prawn::Document.new(page_size: "LETTER", margin: MARGIN)
+        pdf.font_size BODY_SIZE
+
+        issuer_section(pdf)
+        document_section(pdf)
+        customer_section(pdf)
+        line_items_section(pdf)
+        totals_section(pdf)
+        footer_section(pdf)
+
+        pdf
+      end
+
+      # Art. 10 num. 1.
+      def issuer_section(pdf)
+        issuer = @invoice.issuer
+        pdf.text e(issuer.trade_name.upcase), size: 14, align: :center, style: :bold
+        pdf.text e(issuer.legal_name), align: :center
+        pdf.text e("RTN: #{issuer.rtn.formatted}"), align: :center
+        pdf.text e("Casa matriz: #{issuer.headquarters_address}"), align: :center
+        pdf.text e("Establecimiento: #{issuer.branch_address}"), align: :center if issuer.branch?
+        pdf.text e("Tel.: #{issuer.phone}   Correo: #{issuer.email}"), align: :center
+        pdf.move_down 8
+        pdf.stroke_horizontal_rule
+        pdf.move_down 8
+      end
+
+      # Art. 10 num. 2, 3, 4, 5 and 7.
+      def document_section(pdf)
+        auth = @invoice.authorization
+        pdf.text e(Text::DOCUMENT_NAME), size: TITLE_SIZE, align: :center, style: :bold
+
+        pdf.text e(Text::ANNULLED_LEGEND), size: TITLE_SIZE, align: :center, style: :bold if @invoice.annulled?
+
+        pdf.move_down 6
+        pdf.text e("No.: <b>#{@invoice.correlative}</b>"), inline_format: true
+        pdf.text e("Fecha de emisión: #{@invoice.issue_date}")
+        pdf.move_down 4
+        pdf.text e("CAI: #{auth.cai}")
+        pdf.text e("Rango autorizado: #{auth.range_label}")
+        pdf.text e("Fecha límite de emisión: #{auth.limit_date}")
+        pdf.move_down 8
+        pdf.stroke_horizontal_rule
+        pdf.move_down 8
+      end
+
+      # Art. 11 num. 1 lit. a) b), num. 2 lit. a), Art. 10 num. 8.
+      def customer_section(pdf)
+        customer = @invoice.customer
+
+        if customer.is_a?(Customer::ConsumidorFinal)
+          pdf.text e("Cliente: #{customer.display_name}")
+          pdf.text e("Identificación: #{customer.identification_line}")
+        else
+          pdf.text e("Cliente: #{customer.name}")
+          pdf.text e("RTN: #{customer.rtn.formatted}")
+        end
+
+        if customer.is_a?(Customer::Exonerado)
+          customer.supporting_documents.each { |label, value| pdf.text e("#{label}: #{value}") }
+        end
+
+        pdf.move_down 8
+      end
+
+      # Art. 11 num. 1 lit. d) e) f) and l).
+      def line_items_section(pdf)
+        header = ["Descripción", "Cant.", "V. unitario", "Descuento", "Tratamiento", "Valor"].map { |h| e(h) }
+        rows = @invoice.line_items.map do |item|
+          [
+            e(item.description),
+            item.quantity.frac.zero? ? item.quantity.to_i.to_s : item.quantity.to_s("F"),
+            item.unit_price.to_fixed,
+            item.discount.to_fixed,
+            e(item.treatment.label),
+            item.taxable_base.to_fixed
+          ]
+        end
+
+        pdf.table([header] + rows, width: pdf.bounds.width, header: true) do |t|
+          t.cells.size = BODY_SIZE
+          t.cells.padding = [3, 4, 3, 4]
+          t.row(0).font_style = :bold
+          t.row(0).background_color = "EEEEEE"
+          t.columns(1..3).align = :right
+          t.column(5).align = :right
+        end
+
+        pdf.move_down 8
+      end
+
+      # Art. 11 num. 1 lit. g) h) i) j) k) l); Art. 10 num. 10.
+      def totals_section(pdf)
+        summary = @invoice.summary
+        rows = []
+
+        rows += summary.untaxed_buckets.map do |b|
+          [e("Importe #{b.treatment.label.downcase}:"), e(b.base.to_s)]
+        end
+        rows += summary.taxed_buckets.map do |b|
+          [e("Importe gravado #{b.treatment.rate_percent}%:"), e(b.base.to_s)]
+        end
+
+        rows << [e("Subtotal:"), e(summary.gross.to_s)]
+        # Art. 10 num. 10 — part of the required format, printed whether or not
+        # a discount was granted.
+        rows << [e("Descuentos y rebajas otorgados:"), e(summary.discount.to_s)]
+
+        rows += summary.taxed_buckets.map do |b|
+          [e("ISV #{b.treatment.rate_percent}%:"), e(b.isv.to_s)]
+        end
+
+        rows << [e("TOTAL:"), e(@invoice.total.to_s)]
+
+        pdf.table(rows, position: :right, width: pdf.bounds.width * 0.55) do |t|
+          t.cells.size = BODY_SIZE
+          t.cells.borders = []
+          t.cells.padding = [2, 4, 2, 4]
+          t.column(1).align = :right
+          t.row(-1).font_style = :bold
+          t.row(-1).borders = [:top]
+        end
+
+        pdf.move_down 8
+        pdf.text e(@invoice.total_in_words), style: :italic
+
+        if @invoice.foreign_currency?
+          pdf.move_down 4
+          pdf.text e("Tasa de cambio a la fecha de emisión: #{@invoice.exchange_rate}")
+          equivalent = @invoice.total_in_lempiras
+          pdf.text e("Equivalente en Lempiras: #{equivalent}") if equivalent
+        end
+
+        pdf.move_down 8
+      end
+
+      def footer_section(pdf)
+        if @invoice.summary.mixed_supply?
+          pdf.text e("Esta factura sustenta crédito fiscal únicamente por las ventas gravadas: " \
+                     "#{@invoice.summary.credito_fiscal_base} (Art. 11 num. 3)."), size: 8
+          pdf.move_down 4
+        end
+
+        if @invoice.annulled?
+          pdf.text e("#{Text::ANNULLED_LEGEND} el #{@invoice.annulled_at}: #{@invoice.annulment_reason}"),
+                   style: :bold
+          pdf.move_down 4
+        end
+
+        pdf.text e(@invoice.notes), size: 8 unless @invoice.notes.empty?
+
+        pdf.move_down 6
+        pdf.stroke_horizontal_rule
+        pdf.move_down 4
+        # Art. 10 num. 6.
+        pdf.text e(Text::COPIES.fetch(@copy, Text::COPY_ORIGINAL)), align: :center, style: :bold
+      end
+    end
+  end
+end

data/lib/invoicehn/renderers/text.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  module Renderers
+    # Renders the Factura as plain text for the terminal or a printer.
+    #
+    # Every legend here is legal text fixed by the Reglamento, not interface
+    # copy, so it lives as a constant rather than in the i18n catalog: an
+    # English-locale CLI must never leak English onto a fiscal document.
+    class Text
+      WIDTH = 78
+
+      # Art. 10 num. 2 — "Denominación del documento: 'Factura'".
+      DOCUMENT_NAME = "FACTURA"
+
+      # Art. 10 num. 6 — "Destino de los ejemplares de la factura".
+      COPY_ORIGINAL = "Original: Cliente"
+      COPY_ISSUER   = "Copia: Obligado tributario emisor"
+
+      # Art. 41 — "consignando en los mismos la leyenda 'ANULADA'".
+      ANNULLED_LEGEND = "ANULADA"
+
+      COPIES = { original: COPY_ORIGINAL, copia: COPY_ISSUER }.freeze
+
+      DESCRIPTION_WIDTH = 30
+      ROW_TEMPLATE = "%-#{DESCRIPTION_WIDTH}s %8s %12s %11s %13s".freeze
+
+      attr_reader :invoice, :copy
+
+      # @param copy [Symbol] :original or :copia — Art. 5 requires documents to
+      #   be generated "en original y copia".
+      def initialize(invoice, copy: :original, width: WIDTH)
+        @invoice = invoice
+        @copy = copy
+        @width = width
+      end
+
+      def render
+        sections = [
+          issuer_block,
+          document_block,
+          customer_block,
+          line_items_block,
+          totals_block,
+          footer_block
+        ].compact
+
+        "#{sections.join("\n")}\n"
+      end
+      alias to_s render
+
+      private
+
+      def rule(char = "─") = char * @width
+
+      def centre(text) = text.to_s.center(@width).rstrip
+
+      # Label on the left, value on the right, dot-filled between.
+      def pair(label, value)
+        value = value.to_s
+        space = @width - label.length - value.length
+        space = 1 if space < 1
+        "#{label}#{" " * space}#{value}"
+      end
+
+      def wrap(text, indent: 0)
+        limit = @width - indent
+        text.to_s.scan(/\S.{0,#{limit - 1}}(?:\s|$)/).map { |l| "#{" " * indent}#{l.strip}" }
+      end
+
+      # Art. 10 num. 1 — datos de identificación del emisor.
+      def issuer_block
+        issuer = @invoice.issuer
+        lines = [rule("═")]
+        lines << centre(issuer.trade_name.upcase)
+        lines << centre(issuer.legal_name)
+        lines << centre("RTN: #{issuer.rtn.formatted}")
+        lines += wrap("Casa matriz: #{issuer.headquarters_address}").map { |l| centre(l) }
+        lines += wrap("Establecimiento: #{issuer.branch_address}").map { |l| centre(l) } if issuer.branch?
+        lines << centre("Tel.: #{issuer.phone}   Correo: #{issuer.email}")
+        lines << rule("═")
+        lines.join("\n")
+      end
+
+      # Art. 10 num. 2, 3, 4, 5, 6 and 7.
+      def document_block
+        auth = @invoice.authorization
+        lines = []
+        lines << centre(DOCUMENT_NAME)
+        lines << centre(ANNULLED_LEGEND) if @invoice.annulled?
+        lines << ""
+        lines << pair("No.: #{@invoice.correlative}", "Fecha de emisión: #{@invoice.issue_date}")
+        lines << ""
+        lines += wrap("CAI: #{auth.cai}")
+        lines << "Rango autorizado: #{auth.range_label}"
+        lines << "Fecha límite de emisión: #{auth.limit_date}"
+        lines << rule
+        lines.join("\n")
+      end
+
+      # Art. 11 num. 1 lit. a) and b), or num. 2 lit. a).
+      def customer_block
+        customer = @invoice.customer
+        lines = []
+
+        if customer.is_a?(Customer::ConsumidorFinal)
+          lines << pair("Cliente: #{customer.display_name}", customer.identification_line)
+        else
+          lines << "Cliente: #{customer.name}"
+          lines << "RTN: #{customer.rtn.formatted}"
+        end
+
+        # Art. 10 num. 8 / Art. 11 num. 4 — datos del adquirente exonerado.
+        if customer.is_a?(Customer::Exonerado)
+          customer.supporting_documents.each { |label, value| lines << "#{label}: #{value}" }
+        end
+
+        lines << rule
+        lines.join("\n")
+      end
+
+      # Art. 11 num. 1 lit. d), e), f) and l).
+      def line_items_block
+        lines = [header_row, rule("·")]
+
+        @invoice.line_items.each do |item|
+          lines += item_rows(item)
+        end
+
+        lines << rule
+        lines.join("\n")
+      end
+
+      # Header and detail rows share one template, so the columns cannot drift
+      # apart.
+      def header_row
+        row("Descripción", "Cant.", "V. unitario", "Descuento", "Valor")
+      end
+
+      def row(*cells) = format(ROW_TEMPLATE, *cells)
+
+      def item_rows(item)
+        # Art. 11 requires the description to be "detallada", so a long one
+        # continues on its own lines instead of being truncated — and it breaks
+        # between words, not mid-word.
+        head, *rest = wrap_words(item.description, DESCRIPTION_WIDTH)
+
+        rows = [row(head,
+                    trim_quantity(item.quantity),
+                    item.unit_price.to_fixed,
+                    item.discount.to_fixed,
+                    item.taxable_base.to_fixed)]
+
+        rows += rest.map { |line| "  #{line}" }
+        rows << "  (#{item.treatment.label})"
+        rows
+      end
+
+      def wrap_words(text, limit)
+        words = text.to_s.split
+        return [""] if words.empty?
+
+        words.each_with_object([+""]) do |word, lines|
+          if lines.last.empty?
+            lines[-1] = word.length > limit ? word[0, limit] : word
+          elsif lines.last.length + 1 + word.length <= limit
+            lines[-1] = "#{lines.last} #{word}"
+          else
+            lines << word
+          end
+        end
+      end
+
+      def trim_quantity(quantity)
+        whole = quantity.frac.zero?
+        whole ? quantity.to_i.to_s : quantity.to_s("F")
+      end
+
+      # Art. 11 num. 1 lit. g), h), i), j), k) and l); Art. 10 num. 10.
+      def totals_block
+        summary = @invoice.summary
+        lines = []
+
+        # lit. g) — the untaxed categories, each shown separately.
+        lines += summary.untaxed_buckets.map do |bucket|
+          pair("Importe #{bucket.treatment.label.downcase}:", bucket.base.to_s)
+        end
+
+        # lit. h) — subtotals by rate.
+        lines += summary.taxed_buckets.map do |bucket|
+          pair("Importe gravado #{bucket.treatment.rate_percent}%:", bucket.base.to_s)
+        end
+
+        lines << pair("Subtotal:", summary.gross.to_s)
+
+        # Art. 10 num. 10 and Art. 11 num. 1 lit. l) — the discounts line is
+        # part of the required format, so it is printed whether or not a
+        # discount was granted.
+        lines << pair("Descuentos y rebajas otorgados:", summary.discount.to_s)
+
+        # lit. i) — taxes by rate.
+        lines += summary.taxed_buckets.map do |bucket|
+          pair("ISV #{bucket.treatment.rate_percent}%:", bucket.isv.to_s)
+        end
+
+        lines << rule("·")
+        lines << pair("TOTAL:", @invoice.total.to_s)
+        lines << ""
+
+        # lit. k) — the total in words.
+        lines += wrap(@invoice.total_in_words)
+
+        # Art. 11, closing paragraph — the rate in force on the issue date.
+        if @invoice.foreign_currency?
+          lines << ""
+          lines << "Tasa de cambio a la fecha de emisión: #{@invoice.exchange_rate}"
+          equivalent = @invoice.total_in_lempiras
+          lines << pair("Equivalente en Lempiras:", equivalent.to_s) if equivalent
+        end
+
+        lines << rule
+        lines.join("\n")
+      end
+
+      def footer_block
+        lines = []
+
+        # Art. 11 num. 3 — where the invoice mixes exempt and taxed sales, only
+        # the taxed sales support crédito fiscal. Saying so on the document
+        # keeps the buyer from over-claiming.
+        if @invoice.summary.mixed_supply?
+          lines += wrap("Esta factura sustenta crédito fiscal únicamente por las ventas gravadas: " \
+                        "#{@invoice.summary.credito_fiscal_base} (Art. 11 num. 3).")
+          lines << ""
+        end
+
+        if @invoice.annulled?
+          lines += wrap("#{ANNULLED_LEGEND} el #{@invoice.annulled_at}: #{@invoice.annulment_reason}")
+          lines << ""
+        end
+
+        lines += wrap(@invoice.notes) unless @invoice.notes.empty?
+
+        # Art. 10 num. 6.
+        lines << centre(COPIES.fetch(@copy, COPY_ORIGINAL))
+        lines << rule("═")
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/invoicehn/rtn.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  # Registro Tributario Nacional — 14 digits, for both personas naturales and
+  # personas jurídicas.
+  #
+  # Validation is deliberately limited to length and digits. There is no
+  # publicly documented check digit for the Honduran RTN: the word "dígito"
+  # appears nowhere in the Código Tributario (Decreto 170-2016), Acuerdo
+  # 481-2017 requires the RTN on invoices without ever specifying its structure,
+  # and SAR publishes no algorithm. Porting a mod-11 scheme by analogy from the
+  # Chilean RUT or Mexican RFC would reject valid Honduran RTNs, so this class
+  # does not attempt it. Verify a real RTN against SAR's consulta, not
+  # arithmetic.
+  #
+  # Note also that primary sources disagree on how a natural person's RTN is
+  # derived — Código Tributario Art. 66 num. 3 says it *is* the RNP number,
+  # while SAR states it is the 13-digit DNI plus one digit. Nothing here assumes
+  # either, and nothing here assumes RTN and DNI are interchangeable.
+  class Rtn
+    LENGTH = 14
+    PATTERN = /\A\d{#{LENGTH}}\z/
+
+    attr_reader :digits
+
+    class << self
+      def parse(value)
+        new(value)
+      rescue ValidationError
+        nil
+      end
+
+      def valid?(value)
+        normalize(value).match?(PATTERN)
+      end
+
+      # Dashes and spaces are a display convention with no basis in any norm,
+      # so they are accepted on input and discarded.
+      def normalize(value)
+        value.to_s.gsub(/[\s-]/, "")
+      end
+    end
+
+    def initialize(value)
+      @digits = self.class.normalize(value)
+
+      unless @digits.match?(PATTERN)
+        raise ValidationError,
+              "RTN inválido: se esperan #{LENGTH} dígitos, se recibió #{@digits.inspect}"
+      end
+
+      freeze
+    end
+
+    # "0801-1990-123456" — the 4-4-6 grouping is customary, not prescribed.
+    def formatted
+      "#{@digits[0, 4]}-#{@digits[4, 4]}-#{@digits[8, 6]}"
+    end
+
+    def to_s = @digits
+    def inspect = "#<Invoicehn::Rtn #{formatted}>"
+
+    def ==(other)
+      other.is_a?(self.class) && other.digits == @digits
+    end
+    alias eql? ==
+
+    def hash = @digits.hash
+  end
+end