invoicehn 0.1.0

data/lib/invoicehn/cli/wizard.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module Invoicehn
+  module CLI
+    # The interactive path: `invoicehn setup`, `invoicehn auth add` and
+    # `invoicehn new`.
+    #
+    # The wizard collects input and hands it to the same Issuance service the
+    # scriptable commands use, so it cannot produce a document the compliance
+    # rules would not accept. Nothing is written until the operator confirms —
+    # an abandoned wizard consumes no correlativo.
+    class Wizard
+      def initialize(issuance, shell = nil, prompt: nil)
+        @issuance = issuance
+        @shell = shell
+        @prompt = prompt || TTY::Prompt.new(interrupt: :exit)
+      end
+
+      # Art. 10 num. 1 — datos de identificación del emisor.
+      def setup
+        header Locale.t("setup.title")
+        say Locale.t("setup.intro")
+        say ""
+
+        existing = @issuance.store.issuer
+
+        issuer = Issuer.new(
+          rtn: ask_rtn(Locale.t("setup.rtn"), default: existing&.rtn&.to_s),
+          legal_name: ask(Locale.t("setup.legal_name"), default: existing&.legal_name),
+          trade_name: ask(Locale.t("setup.trade_name"), default: existing&.trade_name),
+          headquarters_address: ask(Locale.t("setup.headquarters"),
+                                    default: existing&.headquarters_address),
+          branch_address: @prompt.ask(Locale.t("setup.branch"),
+                                      default: existing&.branch? ? existing.branch_address : nil),
+          phone: ask(Locale.t("setup.phone"), default: existing&.phone),
+          email: ask(Locale.t("setup.email"), default: existing&.email)
+        )
+
+        issuer.validate!
+        @issuance.store.save_issuer(issuer)
+        say Locale.t("setup.saved", path: @issuance.store.config.issuer_path), :green
+        issuer
+      end
+
+      # Arts. 59-61 — the values SAR grants, transcribed from the authorization
+      # document. Nothing here is generated.
+      def add_authorization
+        header Locale.t("auth.title")
+        say Locale.t("auth.intro")
+        say ""
+
+        cai = ask(Locale.t("auth.cai"))
+        establishment = ask(Locale.t("auth.establishment"), default: "000")
+        emission_point = ask(Locale.t("auth.emission_point"), default: "001")
+
+        range_start = Correlative.new(establishment: establishment, emission_point: emission_point,
+                                      document_type: Correlative::FACTURA,
+                                      sequence: ask(Locale.t("auth.range_start"), default: "1").to_i)
+        range_end = range_start.with_sequence(ask(Locale.t("auth.range_end")).to_i)
+
+        authorization = Authorization.new(
+          cai: cai, range_start: range_start, range_end: range_end,
+          limit_date: ask(Locale.t("auth.limit_date"))
+        )
+
+        @issuance.store.add_authorization(authorization)
+        @issuance.sequence.align_to(authorization)
+
+        say Locale.t("auth.saved", range: authorization.range_label), :green
+        say "Documentos autorizados: #{authorization.capacity}"
+        authorization
+      end
+
+      def issue
+        customer = ask_customer
+        currency = @prompt.select(Locale.t("invoice.currency"), %w[HNL USD], default: "HNL")
+        line_items = ask_line_items(currency)
+
+        if line_items.empty?
+          say Locale.t("invoice.cancelled"), :yellow
+          return nil
+        end
+
+        exchange_rate = currency == "HNL" ? nil : ask_exchange_rate(currency)
+        notes = @prompt.ask(Locale.t("invoice.notes"))
+
+        preview = preview_invoice(customer, line_items, currency, exchange_rate, notes)
+        say ""
+        say preview
+
+        unless @prompt.yes?(Locale.t("invoice.confirm"))
+          say Locale.t("invoice.cancelled"), :yellow
+          return nil
+        end
+
+        invoice = @issuance.issue(customer: customer, line_items: line_items,
+                                  currency: currency, exchange_rate: exchange_rate, notes: notes)
+
+        say ""
+        say Locale.t("invoice.issued", correlative: invoice.correlative), :green
+        say ""
+        say Renderers::Text.new(invoice).render
+        invoice
+      end
+
+      private
+
+      def say(message, color = nil)
+        color ? @prompt.say(message, color: color) : @prompt.say(message)
+      end
+
+      def header(text)
+        say ""
+        say text
+        say "─" * text.length
+      end
+
+      def ask(question, default: nil)
+        options = { required: true }
+        options[:default] = default if default && !default.to_s.empty?
+        @prompt.ask(question, **options)
+      end
+
+      def ask_rtn(question, default: nil)
+        loop do
+          value = ask(question, default: default)
+          return value if Rtn.valid?(value)
+
+          say "RTN inválido: se esperan 14 dígitos.", :red
+        end
+      end
+
+      # Art. 11 distinguishes three cases, and which fields are mandatory
+      # depends on which one applies.
+      def ask_customer
+        kinds = {
+          Locale.t("invoice.kind_consumidor_final") => :consumidor_final,
+          Locale.t("invoice.kind_taxpayer") => :taxpayer,
+          Locale.t("invoice.kind_exonerado") => :exonerado
+        }
+
+        case @prompt.select(Locale.t("invoice.customer_kind"), kinds)
+        when :taxpayer
+          Customer::Taxpayer.new(
+            name: ask(Locale.t("invoice.customer_name")),
+            rtn: ask_rtn(Locale.t("invoice.customer_rtn"))
+          )
+        when :exonerado
+          Customer::Exonerado.new(
+            name: ask(Locale.t("invoice.customer_name")),
+            rtn: ask_rtn(Locale.t("invoice.customer_rtn")),
+            purchase_order: @prompt.ask(Locale.t("invoice.purchase_order")),
+            exoneration_registry: @prompt.ask(Locale.t("invoice.exoneration_registry")),
+            sag_registry: @prompt.ask(Locale.t("invoice.sag_registry"))
+          )
+        else
+          ask_consumidor_final
+        end
+      end
+
+      # Art. 11 num. 2 — the client's data is only mandatory above L 10,000.00,
+      # but it may always be recorded, so it is offered rather than forced.
+      def ask_consumidor_final
+        name = @prompt.ask(Locale.t("invoice.customer_name"))
+        return Customer::ConsumidorFinal.new if name.nil? || name.strip.empty?
+
+        Customer::ConsumidorFinal.new(
+          name: name,
+          identification_type: @prompt.ask(Locale.t("invoice.id_type"), default: "DNI"),
+          identification_number: @prompt.ask(Locale.t("invoice.id_number"))
+        )
+      end
+
+      def ask_line_items(currency)
+        items = []
+
+        loop do
+          items << ask_line(currency)
+          break unless @prompt.yes?(Locale.t("invoice.add_line"), default: false)
+        end
+
+        items
+      end
+
+      def ask_line(currency)
+        treatments = TaxTreatment.all.to_h { |t| [t.label, t.key] }
+
+        LineItem.new(
+          description: ask(Locale.t("invoice.description")),
+          quantity: BigDecimal(ask(Locale.t("invoice.quantity"), default: "1")),
+          unit_price: Money.new(ask(Locale.t("invoice.unit_price")), currency),
+          discount: Money.new(@prompt.ask(Locale.t("invoice.discount"), default: "0"), currency),
+          treatment: @prompt.select(Locale.t("invoice.treatment"), treatments, default: 4)
+        )
+      rescue ArgumentError, ValidationError => e
+        say "Dato inválido: #{e.message}", :red
+        retry
+      end
+
+      # Art. 11, closing paragraph — the rate in force on the issue date.
+      def ask_exchange_rate(currency)
+        ExchangeRate.new(
+          rate: ask(Locale.t("invoice.exchange_rate")),
+          date: Date.today,
+          currency: currency,
+          source: @prompt.ask(Locale.t("invoice.exchange_source"),
+                              default: ExchangeRate::DEFAULT_SOURCE)
+        )
+      end
+
+      # Rendered against the number that *would* be allocated, without consuming
+      # it — so an operator who declines has not burned a correlativo.
+      def preview_invoice(customer, line_items, currency, exchange_rate, notes)
+        identifier = "000-001-01"
+        correlative = @issuance.sequence.peek(identifier)
+        authorization = @issuance.store.active_authorization(
+          identifier, next_sequence: correlative.sequence
+        )
+
+        raise NoAuthorization, "no hay autorización vigente para #{identifier}" if authorization.nil?
+
+        invoice = Invoice.new(
+          correlative: correlative, issuer: @issuance.store.issuer, customer: customer,
+          authorization: authorization, line_items: line_items, currency: currency,
+          exchange_rate: exchange_rate, notes: notes
+        )
+
+        Renderers::Text.new(invoice).render
+      end
+    end
+  end
+end

data/lib/invoicehn/cli.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "cli/builder"
+require_relative "cli/reporter"
+require_relative "cli/wizard"
+require_relative "cli/main"
+
+module Invoicehn
+  # The terminal interface.
+  #
+  # Interface strings are translatable (es/en); the fiscal document's own
+  # legends are not — they are legal text fixed by the Reglamento and live as
+  # constants in Renderers::Text.
+  module CLI
+  end
+end

data/lib/invoicehn/compliance/validator.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Invoicehn
+  module Compliance
+    # Checks an invoice against the Reglamento del Régimen de Facturación.
+    #
+    # Every rule cites the article it enforces. The validator reports all
+    # failures at once rather than stopping at the first, so an operator fixing
+    # a document sees the whole list.
+    #
+    # Scope: this validates *document content*. It cannot verify that the
+    # operator is registered in the Régimen de Facturación (Art. 45), enrolled
+    # as autoimpresor (Art. 47), or that the CAI it was handed is genuine —
+    # those are obligations the software cannot discharge.
+    class Validator
+      RULES = [
+        :issuer_identification,      # Art. 10 num. 1
+        :authorization_present,      # Art. 10 num. 3, 4, 5
+        :authorization_current,      # Art. 62
+        :correlative_in_range,       # Art. 10 num. 5, 7
+        :document_type_is_factura,   # Art. 10 num. 7 lit. c
+        :line_items_present,         # Art. 11 num. 1 lit. d, e, f
+        :customer_identification,    # Art. 11 num. 1 lit. a, b / num. 2 lit. a
+        :consumidor_final_threshold, # Art. 11 num. 2
+        :exonerado_documents,        # Art. 10 num. 8 / Art. 11 num. 4
+        :foreign_currency_rate,      # Art. 11 closing paragraph
+        :mixed_supply_notice         # Art. 11 num. 3
+      ].freeze
+
+      attr_reader :invoice, :on
+
+      def initialize(invoice, on: Date.today)
+        @invoice = invoice
+        @on = on
+      end
+
+      def violations
+        @violations ||= RULES.flat_map { |rule| Array(send(rule)) }.compact.freeze
+      end
+
+      def errors = violations.select(&:error?)
+      def warnings = violations.select(&:warning?)
+      def valid? = errors.empty?
+
+      private
+
+      def violation(article, requirement, detail = nil, severity: :error)
+        Violation.new(article: article, requirement: requirement, detail: detail, severity: severity)
+      end
+
+      # Art. 10 num. 1 — "Datos de identificación del emisor".
+      def issuer_identification
+        if invoice.issuer.nil?
+          return violation("Art. 10 num. 1", "Datos de identificación del emisor",
+                           "no se configuró el emisor")
+        end
+
+        missing = invoice.issuer.missing_fields
+        return if missing.empty?
+
+        violation("Art. 10 num. 1", "Datos de identificación del emisor",
+                  "faltan: #{missing.join("; ")}")
+      end
+
+      # Art. 10 num. 3, 4 and 5 — CAI, fecha límite and rango must appear.
+      def authorization_present
+        return if invoice.authorization
+
+        violation("Art. 10 num. 3, 4 y 5",
+                  "Clave de Autorización de Impresión (CAI), fecha límite de emisión y rango autorizado",
+                  "la factura no tiene autorización asociada")
+      end
+
+      # Art. 62 — documents lose validity once the authorized period expires.
+      def authorization_current
+        auth = invoice.authorization
+        return if auth.nil?
+        return unless auth.expired?(invoice.issue_date)
+
+        violation("Art. 62", "Fecha límite de emisión vigente",
+                  "la autorización venció el #{auth.limit_date} y la factura se emitió el #{invoice.issue_date}")
+      end
+
+      # Art. 10 num. 5 and 7 — the number must fall inside the authorized range.
+      def correlative_in_range
+        auth = invoice.authorization
+        return if auth.nil?
+        return if auth.covers?(invoice.correlative)
+
+        violation("Art. 10 num. 5", "Rango autorizado vigente",
+                  "el correlativo #{invoice.correlative} está fuera del rango #{auth.range_label}")
+      end
+
+      # Art. 10 num. 7 lit. c — "01 = Factura".
+      def document_type_is_factura
+        return if invoice.correlative.factura?
+
+        violation("Art. 10 num. 7 lit. c", "Código de tipo de documento 01 para la Factura",
+                  "el correlativo declara el tipo #{invoice.correlative.document_type} " \
+                  "(#{invoice.correlative.document_type_name})")
+      end
+
+      # Art. 11 num. 1 lit. d, e, f — a document with nothing on it describes no
+      # transferencia de bienes ni prestación de servicios.
+      def line_items_present
+        return if invoice.line_items.any?
+
+        violation("Art. 11 num. 1 lit. d, e y f",
+                  "Descripción detallada, cantidad de unidades y valor unitario",
+                  "la factura no tiene líneas de detalle")
+      end
+
+      # Art. 11 num. 1 lit. a and b for taxpayers; num. 2 lit. a for final
+      # consumers.
+      def customer_identification
+        customer = invoice.customer
+        return violation("Art. 11", "Datos del cliente", "no se configuró el cliente") if customer.nil?
+
+        if customer.taxpayer? || customer.exonerado?
+          return if !customer.name.empty? && customer.rtn
+
+          return violation("Art. 11 num. 1 lit. a y b",
+                           "Nombres y Apellidos o Razón Social, y RTN del cliente",
+                           "el cliente que sustenta crédito fiscal debe identificarse con nombre y RTN")
+        end
+
+        nil
+      end
+
+      # Art. 11 num. 2 — above L 10,000.00 the consumidor final's data becomes
+      # mandatory: "nombres y apellidos, el tipo y número de documento de
+      # identificación en el espacio destinado al RTN".
+      def consumidor_final_threshold
+        customer = invoice.customer
+        return unless customer.is_a?(Customer::ConsumidorFinal)
+
+        # The threshold is a sum *in lempiras*, so a foreign-currency invoice is
+        # measured by its Lempira equivalent — otherwise an anonymous sale of
+        # US$50,000 would slip past a rule written for L 10,000. A foreign
+        # invoice without a rate cannot be converted, but it already fails the
+        # Art. 11 closing-paragraph rule, so nothing goes unreported.
+        amount = invoice.foreign_currency? ? invoice.total_in_lempiras : invoice.total
+        return if amount.nil?
+        return unless customer.identification_required?(amount)
+        return if customer.identified?
+
+        violation("Art. 11 num. 2",
+                  "Datos del consumidor final en ventas superiores a L 10,000.00",
+                  "el total (#{invoice.total}#{" ≡ #{amount}" if invoice.foreign_currency?}) " \
+                  "excede el umbral y deben consignarse nombres y apellidos junto al tipo y " \
+                  "número de documento de identificación")
+      end
+
+      # Art. 10 num. 8 and Art. 11 num. 4 — an exonerated purchaser's supporting
+      # numbers.
+      def exonerado_documents
+        customer = invoice.customer
+        results = []
+
+        if customer.is_a?(Customer::Exonerado) && !customer.supported?
+          results << violation("Art. 10 num. 8 y Art. 11 num. 4",
+                               "Orden de Compra Exenta, Constancia del Registro de Exonerados o Registro SAG",
+                               "el adquirente exonerado no tiene ninguno de los tres documentos de respaldo")
+        end
+
+        # An exonerado line without an exonerado buyer is a contradiction the
+        # document would carry on its face.
+        exonerado_lines = invoice.line_items.any? { |item| item.treatment.exonerado? }
+        if exonerado_lines && !customer.exonerado?
+          results << violation("Art. 11 num. 4",
+                               "Ventas a Obligados Tributarios Exonerados",
+                               "hay líneas con tratamiento exonerado pero el cliente no está registrado como exonerado")
+        end
+
+        results
+      end
+
+      # Art. 11, closing paragraph: "En ambos casos, cuando el Obligado
+      # Tributario emita facturas con otra denominación monetaria, debe indicar
+      # la tasa de cambio vigente a la fecha de emisión."
+      def foreign_currency_rate
+        return unless invoice.foreign_currency?
+
+        rate = invoice.exchange_rate
+        if rate.nil?
+          return violation("Art. 11 (párrafo final)",
+                           "Tasa de cambio vigente a la fecha de emisión",
+                           "la factura está en #{invoice.currency} y no indica tasa de cambio")
+        end
+
+        unless rate.currency == invoice.currency
+          return violation("Art. 11 (párrafo final)",
+                           "Tasa de cambio vigente a la fecha de emisión",
+                           "la tasa convierte desde #{rate.currency} pero la factura está en #{invoice.currency}")
+        end
+
+        return if rate.current_on?(invoice.issue_date)
+
+        violation("Art. 11 (párrafo final)",
+                  "Tasa de cambio vigente a la fecha de emisión",
+                  "la tasa es del #{rate.date} y la factura se emitió el #{invoice.issue_date}")
+      end
+
+      # Art. 11 num. 3 — "Para respaldar el crédito fiscal en los casos que la
+      # factura sustente ventas exentas y gravadas, se reconocerán únicamente
+      # las ventas gravadas." Not a defect: a notice, so the document can say so
+      # and the buyer is not misled about what it supports.
+      def mixed_supply_notice
+        return unless invoice.summary.mixed_supply?
+        return unless invoice.customer.taxpayer?
+
+        violation("Art. 11 num. 3",
+                  "Crédito fiscal limitado a las ventas gravadas",
+                  "la factura mezcla ventas gravadas y no gravadas; sólo #{invoice.summary.credito_fiscal_base} " \
+                  "sustenta crédito fiscal",
+                  severity: :warning)
+      end
+    end
+  end
+end

data/lib/invoicehn/compliance/violation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  module Compliance
+    # One failed legal requirement, carrying the article it comes from so the
+    # operator can look it up rather than trust the library's paraphrase.
+    class Violation
+      SEVERITIES = %i[error warning].freeze
+
+      attr_reader :article, :requirement, :detail, :severity
+
+      def initialize(article:, requirement:, detail: nil, severity: :error)
+        raise ArgumentError, "severidad desconocida: #{severity.inspect}" unless SEVERITIES.include?(severity)
+
+        @article = article
+        @requirement = requirement
+        @detail = detail
+        @severity = severity
+        freeze
+      end
+
+      def error? = @severity == :error
+      def warning? = @severity == :warning
+
+      def to_s
+        base = "#{@article}: #{@requirement}"
+        @detail ? "#{base} — #{@detail}" : base
+      end
+
+      def to_h
+        {
+          "article" => @article,
+          "requirement" => @requirement,
+          "detail" => @detail,
+          "severity" => @severity.to_s
+        }.compact
+      end
+
+      def inspect = "#<Invoicehn::Compliance::Violation #{self}>"
+    end
+  end
+end

data/lib/invoicehn/config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Invoicehn
+  # Where the library keeps the issuer profile, the authorizations, the
+  # correlative counters and the issued documents.
+  #
+  # Art. 43 obliges the operator to keep fiscal documents ordered and
+  # chronological for the Código Tributario prescription period, and Art. 53
+  # num. 3 requires "la persistencia y disponibilidad inmediata de la
+  # información actual e histórica". A directory of plain JSON files satisfies
+  # both and stays readable without this library — which matters for records
+  # that must outlive the software that wrote them.
+  class Config
+    DEFAULT_DIRNAME = ".invoicehn"
+    ENV_VAR = "INVOICEHN_HOME"
+
+    attr_reader :home
+
+    def initialize(home: nil)
+      @home = File.expand_path(home || ENV[ENV_VAR] || File.join(Dir.home, DEFAULT_DIRNAME))
+    end
+
+    def issuer_path = File.join(@home, "issuer.json")
+    def authorizations_path = File.join(@home, "authorizations.json")
+    def sequences_path     = File.join(@home, "sequences.json")
+    def settings_path      = File.join(@home, "settings.json")
+    def documents_dir      = File.join(@home, "documentos")
+    def ledger_path        = File.join(@home, "ledger.jsonl")
+    def lock_path          = File.join(@home, "sequence.lock")
+
+    # Issued documents are filed by year and month so the directory stays
+    # navigable and mirrors the chronological order Art. 43 asks for.
+    def document_path(correlative, issue_date)
+      dir = File.join(documents_dir, format("%04d", issue_date.year), format("%02d", issue_date.month))
+      File.join(dir, "#{correlative}.json")
+    end
+
+    def ensure_home!
+      FileUtils.mkdir_p(@home)
+      FileUtils.mkdir_p(documents_dir)
+      @home
+    end
+
+    def initialized? = File.exist?(issuer_path)
+
+    def to_s = @home
+  end
+end