invoicehn 0.1.0 → 0.2.0

data/lib/invoicehn/issuance.rb

@@ -3,38 +3,64 @@
 require "date"
 
 module Invoicehn
-  # Issues a Factura: picks the authorization, allocates the correlativo,
-  # validates against the Reglamento, persists, and posts to the ledger.
+  # Issues a Factura, Nota de Crédito or Nota de Débito: picks the
+  # authorization, allocates the correlativo, validates against the
+  # Reglamento, persists, and posts to the ledger.
   #
-  # The whole sequence happens inside the allocator's lock, so a document is
+  # The whole sequence happens inside the allocator's block, so a document is
   # either fully recorded or its number was never consumed. Nothing here can
-  # produce a number without a document behind it.
+  # produce a number without a document behind it, and a failure part-way
+  # leaves nothing behind: if the ledger refuses the entry, the document just
+  # saved is deleted again before the counter would have advanced.
+  #
+  # The store, sequence and ledger are duck-typed collaborators; the README
+  # lists the exact methods each must answer, and Invoicehn::Testing checks
+  # an implementation against that list.
   class Issuance
+    DEFAULT_IDENTIFIER = "000-001-01"
+    CREDIT_NOTE_IDENTIFIER = "000-001-06"
+    DEBIT_NOTE_IDENTIFIER = "000-001-07"
+
     attr_reader :store, :sequence, :ledger
 
-    def initialize(config: Config.new, store: nil, sequence: nil, ledger: nil)
+    # The bundled JSON implementations are built only for the collaborators
+    # not injected. A host that injects all three never touches the file
+    # system: no Config is built, ~/.invoicehn is never read or created.
+    def initialize(config: nil, store: nil, sequence: nil, ledger: nil)
       @config   = config
-      @store    = store || Storage::JsonStore.new(config)
-      @sequence = sequence || Sequence.new(config)
-      @ledger   = ledger || Ledger::JsonlLedger.new(config)
+      @store    = store || Storage::JsonStore.new(default_config)
+      @sequence = sequence || Sequence.new(default_config)
+      @ledger   = ledger || Ledger::JsonlLedger.new(default_config)
     end
 
     # @param identifier [String] "NNN-NNN-NN", the establecimiento / punto de
-    #   emisión / tipo de documento triple. Defaults to the casa matriz's first
-    #   emission point issuing a Factura.
+    #   emisión / tipo de documento triple. Its last group decides the kind of
+    #   document: 01 Factura, 06 Nota de Crédito, 07 Nota de Débito. Each
+    #   identifier has its own counter and its own SAR authorization (Art. 59:
+    #   "La autorización será por punto de emisión y por tipo de documento").
     # @param issue_date [Date] pinned to today by default. Art. 43 obliges
     #   chronological custody, and a ledger whose numbering disagrees with its
     #   dates is the first thing an audit questions — so backdating is not
     #   offered through the CLI.
-    def issue(customer:, line_items:, identifier: "000-001-01", currency: "HNL",
-              exchange_rate: nil, notes: nil, issue_date: Date.today)
+    # @param reference [DocumentReference, String, Correlative, nil] notes
+    #   only: the document the note applies to. A correlative is looked up in
+    #   the store and its CAI and date copied; a DocumentReference is used as
+    #   given (for documents issued outside this store) and, if the store does
+    #   hold that document, checked against it.
+    # @param motivo [String, nil] notes only: "Motivo de la emisión del
+    #   documento" (Arts. 26 and 28 num. 4).
+    def issue(customer:, line_items:, identifier: DEFAULT_IDENTIFIER, currency: "HNL",
+              exchange_rate: nil, notes: nil, issue_date: Invoicehn.today,
+              reference: nil, motivo: nil)
       issuer = @store.issuer
       raise NoAuthorization, "no se ha configurado el emisor; ejecute «invoicehn setup»" if issuer.nil?
 
+      reference = resolve_reference(reference, customer)
+
       @sequence.allocate(identifier) do |correlative|
         authorization = pick_authorization(identifier, correlative, issue_date)
 
-        invoice = Invoice.new(
+        document = Invoice.new(
           correlative: correlative,
           issuer: issuer,
           customer: customer,
@@ -43,30 +69,60 @@ module Invoicehn
           issue_date: issue_date,
           currency: currency,
           exchange_rate: exchange_rate,
-          notes: notes
+          notes: notes,
+          reference: reference,
+          motivo: motivo
         )
 
-        invoice.validate!(on: issue_date)
-        @store.save_document(invoice)
-        @ledger.record(invoice, event: :emision)
-        invoice
+        document.validate!(on: issue_date)
+        persist(document)
       end
     end
 
+    # A Nota de Crédito (tipo 06, Arts. 25-26): returns, discounts granted after
+    # the sale, or the reversal of an operation (Art. 4 num. 32).
+    def issue_credit_note(reference:, motivo:, customer:, line_items:,
+                          identifier: CREDIT_NOTE_IDENTIFIER, **options)
+      assert_type!(identifier, Correlative::NOTA_DE_CREDITO)
+      issue(customer: customer, line_items: line_items, identifier: identifier,
+            reference: reference, motivo: motivo, **options)
+    end
+
+    # A Nota de Débito (tipo 07, Arts. 27-28): an adjustment charged on top of
+    # a Comprobante Fiscal already issued (Art. 4 num. 31).
+    def issue_debit_note(reference:, motivo:, customer:, line_items:,
+                         identifier: DEBIT_NOTE_IDENTIFIER, **options)
+      assert_type!(identifier, Correlative::NOTA_DE_DEBITO)
+      issue(customer: customer, line_items: line_items, identifier: identifier,
+            reference: reference, motivo: motivo, **options)
+    end
+
     # Art. 41 — annulment. The correlativo stays consumed; the sequence never
     # goes backwards.
-    def annul(correlative, reason:, on: Date.today)
+    # Works the same for a Factura and for a note.
+    #
+    # If the ledger refuses the entry, the issued form is put back. Otherwise
+    # the store would hold the ANULADA form with no :anulacion entry in the
+    # ledger, and a retry would fail with ImmutableDocument ("ya está
+    # anulada"), leaving no way to post the entry through this API.
+    def annul(correlative, reason:, on: Invoicehn.today)
       invoice = @store.find(correlative)
       annulled = invoice.annul(reason: reason, on: on)
 
       @store.save_document(annulled)
-      @ledger.record(annulled, event: :anulacion)
+      recorded = false
+      begin
+        @ledger.record(annulled, event: :anulacion)
+        recorded = true
+      ensure
+        restore(invoice, annulled) unless recorded
+      end
       annulled
     end
 
     # What `invoicehn check` reports: whether issuing is possible right now, and
     # what is about to go wrong.
-    def health(identifier: "000-001-01", on: Date.today)
+    def health(identifier: DEFAULT_IDENTIFIER, on: Invoicehn.today)
       issuer = @store.issuer
       next_correlative = @sequence.peek(identifier)
       authorizations = @store.authorizations_for(identifier)
@@ -81,7 +137,7 @@ module Invoicehn
         active_authorization: active,
         next_correlative: next_correlative,
         issued: @sequence.issued_count(identifier),
-        remaining: active ? (active.range_end.sequence - next_correlative.sequence + 1) : 0,
+        remaining: active ? [active.range_end.sequence - next_correlative.sequence + 1, 0].max : 0,
         days_remaining: active&.days_remaining(on),
         # Art. 42 — expired authorizations holding unused documents must be
         # reported to SAR within the first 10 business days of the next month.
@@ -92,6 +148,83 @@ module Invoicehn
 
     private
 
+    def default_config = (@config ||= Config.new) # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Saves, then posts to the ledger. If posting fails — for any reason,
+    # including an interrupt — the document is deleted again, so the store
+    # never holds a number the counter has not consumed. Without this a
+    # failing ledger left the document on disk and the counter behind it, and
+    # every later issue for that identifier failed with ImmutableDocument.
+    def persist(document)
+      @store.save_document(document)
+      recorded = false
+      begin
+        @ledger.record(document, event: :emision)
+        recorded = true
+      ensure
+        @store.delete_document(document) unless recorded
+      end
+      document
+    end
+
+    # Puts the issued form back after a failed annulment. save_document
+    # refuses to overwrite with a form that is not annulled, so the annulled
+    # one is deleted first.
+    def restore(issued, annulled)
+      @store.delete_document(annulled)
+      @store.save_document(issued)
+    end
+
+    def assert_type!(identifier, type)
+      return if identifier.to_s.split("-")[2] == type
+
+      raise ValidationError,
+            "el identificador #{identifier} no corresponde a #{Correlative::DOCUMENT_TYPES.fetch(type)} " \
+            "(tipo #{type})"
+    end
+
+    # Turns what the caller passed into a DocumentReference, cross-checking it
+    # against the original when the store holds it.
+    def resolve_reference(reference, customer)
+      return nil if reference.nil?
+
+      if reference.is_a?(DocumentReference)
+        original = @store.exists?(reference.correlative) ? @store.find(reference.correlative) : nil
+        check_reference_matches!(reference, original) if original
+      else
+        original = @store.find(reference)
+        reference = DocumentReference.from_document(original)
+      end
+
+      check_original!(original, customer) if original
+      reference
+    end
+
+    def check_reference_matches!(reference, original)
+      stored = DocumentReference.from_document(original)
+      return if stored == reference
+
+      raise ValidationError,
+            "los datos del documento de referencia no coinciden con #{original.correlative} " \
+            "registrado (CAI #{stored.cai}, fecha #{stored.issue_date})"
+    end
+
+    # Not article text but consistency: a note adjusts the operation of the
+    # document it points at, so that document must still stand and belong to
+    # the same acquirer.
+    def check_original!(original, customer)
+      if original.annulled?
+        raise ValidationError, "#{original.correlative} está ANULADA (Art. 41); no se le puede aplicar una nota"
+      end
+
+      return unless original.customer.rtn && customer.rtn
+      return if original.customer.rtn == customer.rtn
+
+      raise ValidationError,
+            "el adquirente de la nota (RTN #{customer.rtn.formatted}) no es el de " \
+            "#{original.correlative} (RTN #{original.customer.rtn.formatted})"
+    end
+
     def pick_authorization(identifier, correlative, on)
       authorization = @store.active_authorization(identifier, next_sequence: correlative.sequence, on: on)
 

data/lib/invoicehn/ledger.rb

@@ -18,7 +18,13 @@ module Invoicehn
   # software. The default implementation writes an append-only JSONL book, which
   # satisfies the requirement standalone and feeds the Art. 53 num. 5 export.
   class Ledger
-    # Called once per issued or annulled document.
+    # Called once per issued or annulled document — a Factura or a Nota de
+    # Crédito or de Débito (see #document_type on the document).
+    #
+    # If this raises during an issue, Issuance deletes the document it just
+    # saved and the correlative is not consumed, so an implementation may
+    # refuse an entry safely. During an annulment, Issuance puts the issued
+    # form back. It must not swallow its own failures.
     #
     # @param invoice [Invoice]
     # @param event [Symbol] :emision or :anulacion
@@ -63,6 +69,8 @@ module Invoicehn
           "recorded_at" => Time.now.utc.iso8601,
           "event" => event.to_s,
           "correlative" => invoice.correlative.to_s,
+          "document_type" => invoice.document_type,
+          "reference" => invoice.reference&.correlative&.to_s,
           "issue_date" => invoice.issue_date.iso8601,
           "cai" => invoice.authorization.cai,
           "customer" => invoice.customer.to_s,

data/lib/invoicehn/renderers/json.rb

@@ -46,7 +46,7 @@ module Invoicehn
       def self.export_csv(invoices)
         headers = %w[
           correlativo fecha estado cai cliente rtn_cliente moneda
-          subtotal descuentos isv total
+          subtotal descuentos isv total tipo documento_referencia motivo
         ]
 
         rows = invoices.map do |inv|
@@ -61,7 +61,10 @@ module Invoicehn
             inv.subtotal.to_fixed,
             inv.discount.to_fixed,
             inv.isv_total.to_fixed,
-            inv.total.to_fixed
+            inv.total.to_fixed,
+            inv.document_type,
+            inv.reference&.correlative&.to_s,
+            inv.motivo
           ]
         end
 

data/lib/invoicehn/renderers/pdf.rb

@@ -2,7 +2,7 @@
 
 module Invoicehn
   module Renderers
-    # Renders the Factura as a PDF.
+    # Renders a Factura, Nota de Crédito or Nota de Débito 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.
@@ -70,6 +70,7 @@ module Invoicehn
         issuer_section(pdf)
         document_section(pdf)
         customer_section(pdf)
+        reference_section(pdf)
         line_items_section(pdf)
         totals_section(pdf)
         footer_section(pdf)
@@ -94,7 +95,7 @@ module Invoicehn
       # 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.title_for(@invoice)), size: TITLE_SIZE, align: :center, style: :bold
 
         pdf.text e(Text::ANNULLED_LEGEND), size: TITLE_SIZE, align: :center, style: :bold if @invoice.annulled?
 
@@ -129,6 +130,16 @@ module Invoicehn
         pdf.move_down 8
       end
 
+      # Art. 26 num. 3 and 4; Art. 28 num. 3 and 4.
+      def reference_section(pdf)
+        return unless @invoice.note?
+
+        pdf.text e(Text::REFERENCE_HEADING), style: :bold
+        Text.reference_lines(@invoice).each { |label, value| pdf.text e("#{label}: #{value}") }
+        pdf.text e("Motivo: #{@invoice.motivo}")
+        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) }
@@ -201,7 +212,7 @@ module Invoicehn
       end
 
       def footer_section(pdf)
-        if @invoice.summary.mixed_supply?
+        if @invoice.factura? && @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
@@ -215,11 +226,20 @@ module Invoicehn
 
         pdf.text e(@invoice.notes), size: 8 unless @invoice.notes.empty?
 
+        # Art. 26 num. 7 — completed by hand by whoever receives the note.
+        if @invoice.credit_note?
+          pdf.move_down 10
+          Text::RECEIVER_FIELDS.each do |label|
+            pdf.text e("#{label}: #{"_" * 50}")
+            pdf.move_down 6
+          end
+        end
+
         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
+        # Art. 10 num. 6; Arts. 25 and 27 num. 7.
+        pdf.text e(Text.copy_legend(@invoice, @copy)), align: :center, style: :bold
       end
     end
   end

data/lib/invoicehn/renderers/text.rb

@@ -2,7 +2,8 @@
 
 module Invoicehn
   module Renderers
-    # Renders the Factura as plain text for the terminal or a printer.
+    # Renders a Factura, Nota de Crédito or Nota de Débito 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
@@ -13,10 +14,50 @@ module Invoicehn
       # Art. 10 num. 2 — "Denominación del documento: 'Factura'".
       DOCUMENT_NAME = "FACTURA"
 
+      # Art. 25 num. 2 — "Nota de Crédito"; Art. 27 num. 2 — "Nota de Débito".
+      TITLES = {
+        Correlative::FACTURA => DOCUMENT_NAME,
+        Correlative::NOTA_DE_CREDITO => "NOTA DE CRÉDITO",
+        Correlative::NOTA_DE_DEBITO => "NOTA DE DÉBITO"
+      }.freeze
+
       # Art. 10 num. 6 — "Destino de los ejemplares de la factura".
       COPY_ORIGINAL = "Original: Cliente"
       COPY_ISSUER   = "Copia: Obligado tributario emisor"
 
+      # Art. 25 num. 7 and Art. 27 num. 7 word the issuer's copy differently:
+      # "Copia: Obligado Tributario".
+      COPY_ISSUER_NOTE = "Copia: Obligado Tributario"
+
+      # Art. 26 num. 3 — the block that identifies the original document.
+      REFERENCE_HEADING = "Documento al que se aplica la nota"
+
+      # Art. 26 num. 7 — "Apellidos, Nombres, Tarjeta de Identidad o documento
+      # de identificación, y firma de la persona que recibe la Nota de
+      # Crédito." Filled in by hand when the note is delivered.
+      RECEIVER_FIELDS = ["Recibido por (nombres y apellidos)", "Identidad o documento de identificación",
+                         "Firma"].freeze
+
+      def self.title_for(invoice) = TITLES.fetch(invoice.document_type, invoice.document_name.upcase)
+
+      def self.copy_legend(invoice, copy)
+        return COPY_ORIGINAL unless copy == :copia
+
+        invoice.factura? ? COPY_ISSUER : COPY_ISSUER_NOTE
+      end
+
+      # [label, value] pairs printed for a note's reference and motivo.
+      def self.reference_lines(invoice)
+        reference = invoice.reference
+        return [] unless invoice.note? && reference
+
+        [
+          ["#{reference.document_type_name} No.", reference.correlative.to_s],
+          ["CAI", reference.cai],
+          ["Fecha de emisión", reference.issue_date.to_s]
+        ]
+      end
+
       # Art. 41 — "consignando en los mismos la leyenda 'ANULADA'".
       ANNULLED_LEGEND = "ANULADA"
 
@@ -40,6 +81,7 @@ module Invoicehn
           issuer_block,
           document_block,
           customer_block,
+          reference_block,
           line_items_block,
           totals_block,
           footer_block
@@ -86,7 +128,7 @@ module Invoicehn
       def document_block
         auth = @invoice.authorization
         lines = []
-        lines << centre(DOCUMENT_NAME)
+        lines << centre(self.class.title_for(@invoice))
         lines << centre(ANNULLED_LEGEND) if @invoice.annulled?
         lines << ""
         lines << pair("No.: #{@invoice.correlative}", "Fecha de emisión: #{@invoice.issue_date}")
@@ -119,6 +161,17 @@ module Invoicehn
         lines.join("\n")
       end
 
+      # Art. 26 num. 3 and 4; Art. 28 num. 3 and 4.
+      def reference_block
+        return nil unless @invoice.note?
+
+        lines = [REFERENCE_HEADING]
+        lines += self.class.reference_lines(@invoice).map { |label, value| "  #{label}: #{value}" }
+        lines += wrap("Motivo: #{@invoice.motivo}")
+        lines << rule
+        lines.join("\n")
+      end
+
       # Art. 11 num. 1 lit. d), e), f) and l).
       def line_items_block
         lines = [header_row, rule("·")]
@@ -228,7 +281,7 @@ module Invoicehn
         # 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?
+        if @invoice.factura? && @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 << ""
@@ -241,8 +294,14 @@ module Invoicehn
 
         lines += wrap(@invoice.notes) unless @invoice.notes.empty?
 
-        # Art. 10 num. 6.
-        lines << centre(COPIES.fetch(@copy, COPY_ORIGINAL))
+        # Art. 26 num. 7.
+        if @invoice.credit_note?
+          RECEIVER_FIELDS.each { |label| lines << "#{label}: #{"_" * [@width - label.length - 2, 10].max}" }
+          lines << ""
+        end
+
+        # Art. 10 num. 6; Arts. 25 and 27 num. 7.
+        lines << centre(self.class.copy_legend(@invoice, @copy))
         lines << rule("═")
         lines.join("\n")
       end

data/lib/invoicehn/settings.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Invoicehn
+  # Process-wide settings, set once at boot with Invoicehn.configure.
+  #
+  # Not to be confused with Invoicehn::Config, which is where the bundled JSON
+  # store keeps its files.
+  #
+  # == The clock
+  #
+  # Every date this library defaults — the fecha de emisión (Art. 10 num. 7 /
+  # Art. 11 num. 1 lit. c), the day an authorization is checked against its
+  # fecha límite (Art. 62), the day of an annulment (Art. 41) — comes from
+  # Invoicehn.today. The default is Date.today, which reads the *process* time
+  # zone. A server running in UTC is six hours ahead of Honduras (UTC-6, no
+  # daylight saving), so between 18:00 and midnight in Tegucigalpa it would
+  # stamp tomorrow's date on the document and could even treat an
+  # authorization as expired a few hours early.
+  #
+  # A Rails host should point the clock at its configured zone:
+  #
+  #   # config/application.rb: config.time_zone = "America/Tegucigalpa"
+  #   Invoicehn.configure { |c| c.today = -> { Date.current } }
+  class Settings
+    DEFAULT_TODAY = -> { Date.today }
+
+    attr_reader :today
+
+    def initialize
+      @today = DEFAULT_TODAY
+    end
+
+    # @param provider [#call] returns the current Date in Honduras.
+    def today=(provider)
+      unless provider.respond_to?(:call)
+        raise ArgumentError, "today debe responder a #call (p. ej. -> { Date.current })"
+      end
+
+      @today = provider
+    end
+  end
+end

data/lib/invoicehn/storage/json_store.rb

@@ -58,13 +58,16 @@ module Invoicehn
 
       # The authorization that should be used next for an identifier: still
       # current, and with room left in its range.
-      def active_authorization(identifier, next_sequence: nil, on: Date.today)
+      #
+      # With next_sequence, only an authorization whose range covers that
+      # number qualifies. An exhausted range is not "active" just because its
+      # fecha límite has not passed — reporting it as such made «check» say
+      # the point was ready with a negative count of documents left.
+      def active_authorization(identifier, next_sequence: nil, on: Invoicehn.today)
         candidates = authorizations_for(identifier).reject { |a| a.expired?(on) }
-        return nil if candidates.empty?
-
         if next_sequence
-          covering = candidates.select { |a| a.covers?(sequence_to_correlative(identifier, next_sequence)) }
-          return covering.min_by { |a| a.range_start.sequence } if covering.any?
+          correlative = sequence_to_correlative(identifier, next_sequence)
+          candidates = candidates.select { |a| a.covers?(correlative) }
         end
 
         candidates.min_by { |a| a.range_start.sequence }
@@ -78,17 +81,29 @@ module Invoicehn
 
         if File.exist?(path) && !invoice.annulled?
           raise ImmutableDocument,
-                "la factura #{invoice.correlative} ya está registrada y no puede modificarse (Art. 41)"
+                "el documento #{invoice.correlative} ya está registrado y no puede modificarse (Art. 41)"
         end
 
         write_json(path, invoice.to_h)
         invoice
       end
 
+      # Removes a document whose issuance failed before it was complete — the
+      # ledger refused it, inside the allocator's block, so the counter never
+      # advanced past it — or the ANULADA form of a document whose annulment the
+      # ledger refused, before the issued form is saved back. Issuance calls
+      # this and nothing else should: an issued document is corrected by
+      # annulment (Art. 41), never deleted.
+      def delete_document(invoice)
+        path = @config.document_path(invoice.correlative, invoice.issue_date)
+        FileUtils.rm_f(path)
+        invoice
+      end
+
       def find(correlative)
         correlative = Correlative.parse(correlative.to_s)
         path = Dir.glob(File.join(@config.documents_dir, "*", "*", "#{correlative}.json")).first
-        raise DocumentNotFound, "no existe la factura #{correlative}" unless path
+        raise DocumentNotFound, "no existe el documento #{correlative}" unless path
 
         Invoice.from_h(read_json(path))
       end