invoicehn 0.1.0 → 0.2.0

data/lib/invoicehn/test_support/contracts.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "invoicehn" unless defined?(Invoicehn::Issuance)
+require "invoicehn/testing"
+
+module Invoicehn
+  # Minitest modules a host application includes to run the store, sequence
+  # and ledger contracts against its own adapters:
+  #
+  #   require "invoicehn/test_support/contracts"
+  #
+  #   class PostgresStoreContractTest < ActiveSupport::TestCase
+  #     include Invoicehn::TestSupport::StoreContract
+  #
+  #     # A store holding a complete issuer and a current authorization for
+  #     # contract_identifier ("000-001-01" unless overridden).
+  #     def contract_store = Facturacion::InvoicehnStore.new
+  #   end
+  #
+  #   class PostgresSequenceContractTest < ActiveSupport::TestCase
+  #     include Invoicehn::TestSupport::SequenceContract
+  #     def contract_sequence = Facturacion::InvoicehnSequence.new
+  #   end
+  #
+  #   class LedgerContractTest < ActiveSupport::TestCase
+  #     include Invoicehn::TestSupport::LedgerContract
+  #     def contract_ledger = Facturacion::InvoicehnLedger.new
+  #   end
+  #
+  #   class IssuanceContractTest < ActiveSupport::TestCase
+  #     include Invoicehn::TestSupport::IssuanceContract
+  #     def contract_store = Facturacion::InvoicehnStore.new
+  #     def contract_sequence = Facturacion::InvoicehnSequence.new
+  #     def contract_ledger = Facturacion::InvoicehnLedger.new
+  #   end
+  #
+  # The modules write documents; run them against a test database. They use
+  # only Minitest's assertions (assert, assert_equal, assert_raises, ...).
+  module TestSupport
+    # Fixed sample data, independent of the host's records.
+    module Samples
+      def contract_identifier = Issuance::DEFAULT_IDENTIFIER
+
+      def contract_sample_issuer
+        Issuer.new(rtn: "08011990123456", legal_name: "Contrato, S. de R.L.", trade_name: "Contrato",
+                   headquarters_address: "Tegucigalpa, M.D.C.", phone: "2222-3333", email: "contrato@ejemplo.hn")
+      end
+
+      def contract_sample_lines
+        [LineItem.new(description: "Prueba de contrato", quantity: 2, unit_price: Money.new("50.00"),
+                      treatment: :gravado_15)]
+      end
+
+      # A document numbered at the last number of `authorization`'s range, so
+      # it does not collide with the next number the host would issue.
+      def contract_sample_document(authorization:, issuer: contract_sample_issuer, **extra)
+        Invoice.new(correlative: authorization.range_end, issuer: issuer,
+                    customer: Customer::Taxpayer.new(name: "Cliente de Contrato, S.A.", rtn: "05019005123456"),
+                    authorization: authorization, line_items: contract_sample_lines,
+                    issue_date: Invoicehn.today, **extra)
+      end
+    end
+
+    # Requires #contract_store.
+    module StoreContract
+      include Samples
+
+      def contract_authorization(store = contract_store)
+        auth = store.active_authorization(contract_identifier, next_sequence: nil, on: Invoicehn.today)
+        assert auth, "contract_store debe tener una autorización vigente para #{contract_identifier}"
+        auth
+      end
+
+      def test_store_contract_interface
+        assert Testing.assert_store_contract(contract_store)
+      end
+
+      def test_store_contract_issuer_is_complete
+        issuer = contract_store.issuer
+
+        assert_kind_of Issuer, issuer
+        assert_empty issuer.missing_fields
+      end
+
+      def test_store_contract_active_authorization_covers_the_number
+        store = contract_store
+        auth = contract_authorization(store)
+
+        first = store.active_authorization(contract_identifier, next_sequence: auth.range_start.sequence,
+                                                                on: Invoicehn.today)
+
+        assert_equal auth.to_h, first.to_h
+        beyond = auth.range_end.sequence + 1
+        covering = store.active_authorization(contract_identifier, next_sequence: beyond, on: Invoicehn.today)
+
+        assert(covering.nil? || covering.covers?(auth.range_end.with_sequence(beyond)),
+               "active_authorization devolvió una autorización que no cubre #{beyond}")
+        assert_nil store.active_authorization(contract_identifier, next_sequence: auth.range_start.sequence,
+                                                                   on: auth.limit_date + 1)
+      end
+
+      def test_store_contract_round_trips_save_find_delete
+        store = contract_store
+        document = contract_sample_document(authorization: contract_authorization(store))
+
+        refute store.exists?(document.correlative)
+        store.save_document(document)
+
+        assert store.exists?(document.correlative)
+        assert_equal document.to_h, store.find(document.correlative).to_h
+        assert_raises(ImmutableDocument) { store.save_document(document) }
+
+        store.delete_document(document)
+
+        refute store.exists?(document.correlative)
+        assert_raises(DocumentNotFound) { store.find(document.correlative) }
+      ensure
+        # A failure above must not leave the sample behind for the next test.
+        store&.delete_document(document) if document
+      end
+
+      # Art. 41 — the annulled form replaces the record; the number stays.
+      def test_store_contract_keeps_the_annulled_form
+        store = contract_store
+        document = contract_sample_document(authorization: contract_authorization(store))
+        store.save_document(document)
+        store.save_document(document.annul(reason: "Prueba de contrato"))
+
+        found = store.find(document.correlative)
+
+        assert_predicate found, :annulled?
+        assert_equal "Prueba de contrato", found.annulment_reason
+      ensure
+        store&.delete_document(document) if document
+      end
+
+      # A note's reference and motivo (Arts. 26 and 28 num. 3-4) must survive
+      # the store. Runs only when the store holds an authorization for
+      # contract_note_identifier.
+      def test_store_contract_keeps_a_notes_reference_and_motivo
+        store = contract_store
+        auth = store.active_authorization(contract_note_identifier, next_sequence: nil, on: Invoicehn.today)
+        skip "sin autorización para #{contract_note_identifier}" unless auth
+
+        reference = DocumentReference.new(correlative: "#{contract_identifier}-00000001", cai: "CAI-CONTRATO",
+                                          issue_date: Invoicehn.today)
+        note = contract_sample_document(authorization: auth, reference: reference, motivo: "Devolución")
+        store.save_document(note)
+        found = store.find(note.correlative)
+
+        assert_equal reference, found.reference
+        assert_equal "Devolución", found.motivo
+        assert_equal note.to_h, found.to_h
+      ensure
+        store&.delete_document(note) if note
+      end
+
+      def contract_note_identifier = "#{contract_identifier.split("-")[0, 2].join("-")}-06"
+    end
+
+    # Requires #contract_sequence.
+    module SequenceContract
+      include Samples
+
+      def contract_other_identifier = "#{contract_identifier.split("-")[0, 2].join("-")}-07"
+
+      def test_sequence_contract_interface
+        assert Testing.assert_sequence_contract(contract_sequence)
+      end
+
+      def test_sequence_contract_peek_does_not_consume
+        sequence = contract_sequence
+        before = sequence.issued_count(contract_identifier)
+
+        assert_equal sequence.peek(contract_identifier), sequence.peek(contract_identifier)
+        assert_equal before + 1, sequence.peek(contract_identifier).sequence
+        assert_equal before, sequence.issued_count(contract_identifier)
+      end
+
+      def test_sequence_contract_allocate_yields_the_next_number_and_advances
+        sequence = contract_sequence
+        expected = sequence.peek(contract_identifier)
+        yielded = nil
+
+        result = sequence.allocate(contract_identifier) do |correlative|
+          yielded = correlative
+          :resultado
+        end
+
+        assert_equal expected, yielded
+        assert_equal :resultado, result
+        assert_equal expected.sequence, sequence.issued_count(contract_identifier)
+        assert_equal expected.succ, sequence.peek(contract_identifier)
+      end
+
+      # The property Issuance's all-or-nothing guarantee rests on.
+      def test_sequence_contract_a_failing_block_consumes_nothing
+        sequence = contract_sequence
+        before = sequence.issued_count(contract_identifier)
+
+        assert_raises(ArgumentError) { sequence.allocate(contract_identifier) { raise ArgumentError, "fallo" } }
+        assert_equal before, sequence.issued_count(contract_identifier)
+      end
+
+      # Each identificador del documento runs its own series (Art. 10 num. 7).
+      def test_sequence_contract_identifiers_are_independent
+        sequence = contract_sequence
+        other = sequence.issued_count(contract_other_identifier)
+        sequence.allocate(contract_identifier) { |c| c }
+
+        assert_equal other, sequence.issued_count(contract_other_identifier)
+      end
+    end
+
+    # Requires #contract_ledger.
+    module LedgerContract
+      include Samples
+
+      def contract_ledger_document
+        auth = Authorization.new(cai: "CAI-CONTRATO", range_start: "#{contract_identifier}-00000001",
+                                 range_end: "#{contract_identifier}-00000010", limit_date: Invoicehn.today + 30)
+        contract_sample_document(authorization: auth)
+      end
+
+      def test_ledger_contract_interface
+        assert Testing.assert_ledger_contract(contract_ledger)
+      end
+
+      def test_ledger_contract_records_issue_and_annulment
+        ledger = contract_ledger
+        document = contract_ledger_document
+
+        ledger.record(document, event: :emision)
+        ledger.record(document.annul(reason: "Prueba de contrato"), event: :anulacion)
+
+        pass
+      end
+    end
+
+    # Requires #contract_store, #contract_sequence and #contract_ledger,
+    # wired to each other. Issues one real Factura.
+    module IssuanceContract
+      include Samples
+
+      def test_issuance_contract_round_trip_and_rollback
+        document = Testing.assert_issuance_round_trip(store: contract_store, sequence: contract_sequence,
+                                                      ledger: contract_ledger, identifier: contract_identifier)
+
+        assert_equal contract_identifier, document.correlative.identifier
+      end
+    end
+  end
+end

data/lib/invoicehn/test_support/memory.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "invoicehn" unless defined?(Invoicehn::Issuance)
+
+module Invoicehn
+  module TestSupport
+    # In-memory store, sequence and ledger. They exist for tests, and as the
+    # shortest complete example of the contract a host adapter (Postgres,
+    # say) has to meet — each method here is one the README lists. They hold
+    # nothing across processes and must never back real fiscal documents.
+
+    # The store: issuer, authorizations and documents.
+    class MemoryStore
+      attr_reader :documents, :issuer
+
+      def initialize(issuer: nil, authorizations: [])
+        @issuer = issuer
+        @authorizations = authorizations.dup
+        @documents = {}
+      end
+
+      def save_issuer(issuer)
+        @issuer = issuer
+      end
+
+      def add_authorization(authorization)
+        @authorizations << authorization
+        authorization
+      end
+
+      def authorizations_for(identifier) = @authorizations.select { |a| a.identifier == identifier }
+
+      # Unexpired, and — when next_sequence is given — covering that number.
+      def active_authorization(identifier, next_sequence: nil, on: Invoicehn.today)
+        candidates = authorizations_for(identifier).reject { |a| a.expired?(on) }
+        if next_sequence
+          correlative = Correlative.parse(format("%<id>s-%<n>08d", id: identifier, n: next_sequence))
+          candidates = candidates.select { |a| a.covers?(correlative) }
+        end
+        candidates.min_by { |a| a.range_start.sequence }
+      end
+
+      # An issued document is immutable; only its annulled form may replace it
+      # (Art. 41).
+      def save_document(document)
+        key = document.correlative.to_s
+        if @documents.key?(key) && !document.annulled?
+          raise ImmutableDocument, "el documento #{key} ya está registrado y no puede modificarse (Art. 41)"
+        end
+
+        @documents[key] = document.to_h
+        document
+      end
+
+      def delete_document(document)
+        @documents.delete(document.correlative.to_s)
+        document
+      end
+
+      def find(correlative)
+        hash = @documents[correlative.to_s]
+        raise DocumentNotFound, "no existe el documento #{correlative}" unless hash
+
+        Invoice.from_h(hash)
+      end
+
+      def exists?(correlative) = @documents.key?(correlative.to_s)
+    end
+
+    # The counter per identifier. The block runs inside the lock and the
+    # counter advances only after it returns — the property that keeps a
+    # failed issue from burning a number.
+    class MemorySequence
+      def initialize
+        @counters = Hash.new(0)
+        @lock = Monitor.new
+      end
+
+      def peek(identifier) = @lock.synchronize { build(identifier, @counters[identifier] + 1) }
+
+      def issued_count(identifier) = @lock.synchronize { @counters[identifier] }
+
+      def allocate(identifier)
+        @lock.synchronize do
+          correlative = build(identifier, @counters[identifier] + 1)
+          result = block_given? ? yield(correlative) : correlative
+          @counters[identifier] = correlative.sequence
+          result
+        end
+      end
+
+      private
+
+      def build(identifier, sequence) = Correlative.parse(format("%<id>s-%<n>08d", id: identifier, n: sequence))
+    end
+
+    # Keeps the entries it is handed.
+    class MemoryLedger
+      attr_reader :records
+
+      def initialize
+        @records = []
+      end
+
+      def record(document, event: :emision)
+        @records << [event, document.correlative.to_s]
+        document
+      end
+    end
+  end
+end

data/lib/invoicehn/testing.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "invoicehn" unless defined?(Invoicehn::Issuance)
+
+module Invoicehn
+  # Checks a host application's store, sequence and ledger against the
+  # contract Invoicehn::Issuance relies on. Not loaded by `require
+  # "invoicehn"`; a host's test suite opts in:
+  #
+  #   require "invoicehn/testing"
+  #
+  #   Invoicehn::Testing.assert_store_contract(PostgresStore.new)
+  #   Invoicehn::Testing.assert_sequence_contract(PostgresSequence.new)
+  #   Invoicehn::Testing.assert_ledger_contract(AccountingLedger.new)
+  #   Invoicehn::Testing.assert_issuance_round_trip(store: ..., sequence: ..., ledger: ...)
+  #
+  # Every check raises Invoicehn::Testing::ContractError listing all the
+  # problems it found, and returns the checked object (or, for the round trip,
+  # the issued document) otherwise, so it works under minitest, RSpec or a
+  # plain script.
+  module Testing
+    # Raised when an implementation does not satisfy the contract.
+    class ContractError < Error; end
+
+    # name => [positional parameters, keyword parameters]
+    STORE_CONTRACT = {
+      issuer: [0, []],
+      authorizations_for: [1, []],
+      active_authorization: [1, %i[next_sequence on]],
+      save_document: [1, []],
+      delete_document: [1, []],
+      find: [1, []],
+      exists?: [1, []]
+    }.freeze
+
+    SEQUENCE_CONTRACT = {
+      allocate: [1, []],
+      peek: [1, []],
+      issued_count: [1, []]
+    }.freeze
+
+    LEDGER_CONTRACT = {
+      record: [1, %i[event]]
+    }.freeze
+
+    # A ledger that refuses every entry, used to prove the rollback.
+    class RefusingLedger
+      class Refused < StandardError; end
+
+      def record(_document, event: :emision)
+        raise Refused, "asiento rechazado a propósito (#{event})"
+      end
+    end
+
+    class << self
+      def assert_store_contract(store) = assert_contract(store, STORE_CONTRACT, "store")
+      def assert_sequence_contract(sequence) = assert_contract(sequence, SEQUENCE_CONTRACT, "sequence")
+      def assert_ledger_contract(ledger) = assert_contract(ledger, LEDGER_CONTRACT, "ledger")
+
+      # Behavioural check, against a store that already holds a complete
+      # issuer and a current authorization for `identifier`. Issues ONE real
+      # Factura, so run it against a test database.
+      #
+      # 1. With a ledger that refuses the entry, issuing must raise and leave
+      #    nothing behind: no document at the next number, counter unchanged.
+      #    This is what a Postgres adapter gets wrong when allocate advances
+      #    the counter outside the block, or delete_document is a no-op.
+      # 2. With the real ledger, the document must come back from find equal
+      #    to what was issued, and the counter must have advanced by one.
+      #
+      # @return [Invoice] the document issued in step 2
+      def assert_issuance_round_trip(store:, sequence:, ledger:, identifier: Issuance::DEFAULT_IDENTIFIER,
+                                     customer: Customer::ConsumidorFinal.new, line_items: nil)
+        line_items ||= [LineItem.new(description: "Prueba de contrato", quantity: 1,
+                                     unit_price: Money.new("1.00"), treatment: :exento)]
+        before = sequence.issued_count(identifier)
+        upcoming = sequence.peek(identifier)
+        problems = []
+
+        refusing = Issuance.new(store: store, sequence: sequence, ledger: RefusingLedger.new)
+        begin
+          refusing.issue(customer: customer, line_items: line_items, identifier: identifier)
+          problems << "issue no propagó el error del ledger"
+        rescue RefusingLedger::Refused
+          nil
+        end
+        problems << "el documento #{upcoming} quedó guardado aunque el ledger lo rechazó" if store.exists?(upcoming)
+        if sequence.issued_count(identifier) != before
+          problems << "el contador avanzó aunque la emisión falló (allocate debe avanzar sólo si el bloque termina)"
+        end
+        raise ContractError, problems.join("\n") if problems.any?
+
+        document = Issuance.new(store: store, sequence: sequence, ledger: ledger)
+                           .issue(customer: customer, line_items: line_items, identifier: identifier)
+
+        problems << "se emitió #{document.correlative}, se esperaba #{upcoming}" unless document.correlative == upcoming
+        problems << "issued_count no avanzó en uno" unless sequence.issued_count(identifier) == before + 1
+        problems << "exists? no encuentra #{document.correlative}" unless store.exists?(document.correlative)
+        unless store.find(document.correlative).to_h == document.to_h
+          problems << "find(#{document.correlative}) no devuelve el documento tal como se emitió"
+        end
+        raise ContractError, problems.join("\n") if problems.any?
+
+        document
+      end
+
+      private
+
+      def assert_contract(object, contract, role)
+        problems = contract.flat_map do |name, (positional, keywords)|
+          next ["#{role} debe responder a ##{name}"] unless object.respond_to?(name)
+
+          signature_problems(object.method(name), role, name, positional, keywords)
+        end
+        raise ContractError, problems.join("\n") if problems.any?
+
+        object
+      end
+
+      def signature_problems(method, role, name, positional, keywords)
+        params = method.parameters
+        problems = []
+
+        required = params.count { |type, _| type == :req }
+        accepts = params.count { |type, _| %i[req opt].include?(type) }
+        rest = params.any? { |type, _| type == :rest }
+        unless required <= positional && (rest || accepts >= positional)
+          problems << "#{role}##{name} debe aceptar #{positional} argumento(s) posicional(es)"
+        end
+
+        keyrest = params.any? { |type, _| type == :keyrest }
+        declared = params.filter_map { |type, param| param if %i[key keyreq].include?(type) }
+        (keywords - declared).each do |kw|
+          problems << "#{role}##{name} debe aceptar la palabra clave #{kw}:" unless keyrest
+        end
+        problems
+      end
+    end
+  end
+end

data/lib/invoicehn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Invoicehn
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/invoicehn.rb

@@ -2,11 +2,13 @@
 
 require_relative "invoicehn/version"
 require_relative "invoicehn/errors"
+require_relative "invoicehn/settings"
 require_relative "invoicehn/locale"
 require_relative "invoicehn/money"
 require_relative "invoicehn/spanish_numerals"
 require_relative "invoicehn/rtn"
 require_relative "invoicehn/correlative"
+require_relative "invoicehn/document_reference"
 require_relative "invoicehn/tax_treatment"
 require_relative "invoicehn/line_item"
 require_relative "invoicehn/tax_summary"
@@ -37,4 +39,30 @@ require_relative "invoicehn/renderers/pdf"
 # límite de emisión (Arts. 59-61) all remain the operator's obligations before
 # any document produced here is valid.
 module Invoicehn
+  # Invoicehn.configure / Invoicehn.today — see Invoicehn::Settings.
+  class << self
+    def settings
+      @settings ||= Settings.new
+    end
+
+    def configure
+      yield settings
+      settings
+    end
+
+    # Restores the defaults. Meant for test suites.
+    def reset_settings!
+      @settings = Settings.new
+    end
+
+    # Today's date in Honduras, as the configured clock reports it. Raises if
+    # the clock returns something that is not a Date — a Time or a String here
+    # would silently shift fiscal dates.
+    def today
+      value = settings.today.call
+      return value if value.instance_of?(Date)
+
+      raise Error, "el reloj configurado devolvió #{value.inspect}; se espera un Date"
+    end
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: invoicehn
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jorge Padilla
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -81,9 +80,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.23'
 description: |
-  Genera Facturas que cumplen los requisitos de contenido de los Artículos 10 y 11 del
-  Reglamento del Régimen de Facturación (Acuerdo 481-2017 y sus reformas), incluyendo el
-  correlativo de 16 dígitos, control del CAI, rango autorizado y fecha límite de emisión,
+  Genera Facturas, Notas de Crédito y Notas de Débito que cumplen los requisitos de contenido
+  de los Artículos 10-11 y 25-28 del Reglamento del Régimen de Facturación (Acuerdo 481-2017
+  y sus reformas), incluyendo el correlativo de 16 dígitos con los códigos de tipo de
+  documento reformados, control del CAI, rango autorizado y fecha límite de emisión,
   discriminación del ISV por tarifa, y el redondeo estatutario del Artículo 9 de la Ley
   del Impuesto Sobre Ventas. Incluye biblioteca Ruby y una interfaz de terminal.
 email:
@@ -111,6 +111,7 @@ files:
 - lib/invoicehn/config.rb
 - lib/invoicehn/correlative.rb
 - lib/invoicehn/customer.rb
+- lib/invoicehn/document_reference.rb
 - lib/invoicehn/errors.rb
 - lib/invoicehn/exchange_rate.rb
 - lib/invoicehn/invoice.rb
@@ -125,10 +126,14 @@ files:
 - lib/invoicehn/renderers/text.rb
 - lib/invoicehn/rtn.rb
 - lib/invoicehn/sequence.rb
+- lib/invoicehn/settings.rb
 - lib/invoicehn/spanish_numerals.rb
 - lib/invoicehn/storage/json_store.rb
 - lib/invoicehn/tax_summary.rb
 - lib/invoicehn/tax_treatment.rb
+- lib/invoicehn/test_support/contracts.rb
+- lib/invoicehn/test_support/memory.rb
+- lib/invoicehn/testing.rb
 - lib/invoicehn/version.rb
 homepage: https://github.com/JorgePadilla/invoicehn
 licenses:
@@ -139,7 +144,6 @@ metadata:
   changelog_uri: https://github.com/JorgePadilla/invoicehn/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/JorgePadilla/invoicehn/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -154,8 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Facturación para Honduras conforme al Régimen de Facturación (Acuerdo 481-2017)
 test_files: []