ksef-client-rails 0.1.0 → 1.0.0

data/lib/ksef/http/pagination.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Http
+    # The two KSeF pagination mechanisms, split along "query vs list":
+    # {.by_offset} uses `pageOffset` (a 0-based page INDEX, not a record offset) + `hasMore`;
+    # {.by_continuation} reads `continuationToken` from the body but sends it in the
+    # `x-continuation-token` header. Both return a lazy enumerator, so pages are fetched on demand.
+    module Pagination
+      # A single page of offset-paginated results; +truncated+ marks the server's record limit.
+      OffsetPage = Struct.new(:items, :has_more, :truncated, keyword_init: true)
+      # A single page of continuation-token-paginated results.
+      ContinuationPage = Struct.new(:items, :continuation_token, keyword_init: true)
+      # Empty continuation pages in a row after which iteration gives up.
+      MAX_EMPTY_PAGES = 100
+
+      module_function
+
+      # Iterates over pages incrementing the page index by 1 while `has_more` is truthy; an empty page
+      # ends the iteration too, so a server that keeps answering `hasMore` cannot loop it forever. A
+      # truncated page with more behind it raises once its items are consumed: the next page index
+      # would not continue the result.
+      #
+      # @param page_size [Integer] page size
+      # @param start_page [Integer] starting page index (defaults to 0)
+      # @param truncated_hint [String] how to continue past a truncated result, for the error message
+      # @yieldparam page_index [Integer]
+      # @yieldparam page_size [Integer]
+      # @yieldreturn [OffsetPage]
+      # @return [Enumerator::Lazy]
+      # @raise [Ksef::ResultTruncated] when iteration goes past a truncated page
+      def by_offset(page_size: 10, start_page: 0, truncated_hint: "narrow the query")
+        Enumerator.new do |yielder|
+          page_index = start_page
+          loop do
+            page = yield(page_index, page_size)
+            items = Array(page.items)
+            items.each { |item| yielder << item }
+            break if !page.has_more || items.empty?
+            if page.truncated
+              raise ResultTruncated.new("The result reached the record limit (isTruncated) — #{truncated_hint}",
+                                        last_item: items.last)
+            end
+
+            page_index += 1
+          end
+        end.lazy
+      end
+
+      # Iterates over pages passing the continuation token for as long as the server returns a new one. A
+      # page may be empty and still continue; a token returned before ends the iteration (it would loop
+      # forever), and so many empty pages in a row raise.
+      #
+      # @param page_size [Integer] page size
+      # @yieldparam continuation_token [String, nil] nil on the first request
+      # @yieldparam page_size [Integer]
+      # @yieldreturn [ContinuationPage]
+      # @return [Enumerator::Lazy]
+      # @raise [Ksef::Error] after {MAX_EMPTY_PAGES} empty pages in a row
+      def by_continuation(page_size: 10)
+        Enumerator.new do |yielder|
+          seen = Set.new
+          empty = 0
+          token = nil
+          loop do
+            page = yield(token, page_size)
+            items = Array(page.items)
+            items.each { |item| yielder << item }
+            empty = items.empty? ? empty + 1 : 0
+            raise Error, "KSeF returned #{empty} empty pages in a row; stopping" if empty >= MAX_EMPTY_PAGES
+
+            seen << token if token
+            token = page.continuation_token
+            break if token.nil? || token.to_s.empty? || seen.include?(token)
+          end
+        end.lazy
+      end
+    end
+  end
+end

data/lib/ksef/invoices/builder/checks.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Invoices
+    class Builder
+      # The checks {Builder#to_xml} runs before rendering: required values, numbers, codes and text.
+      # @api private
+      module Checks
+        # Rates with VAT, which a foreign-currency invoice would also have to state in PLN (`P_14_xW`).
+        VAT_RATES = %w[23 8 5].freeze
+
+        private
+
+        def check!
+          check_parties!
+          raise ConfigurationError, "at least one line is required" if lines.empty?
+
+          check_required!(number: number, issue_date: issue_date)
+          check_codes!
+          check_lines!
+          check_tax!
+          check_correction!
+          check_payment!
+          check_text!
+        end
+
+        def check_parties!
+          raise ConfigurationError, "seller and buyer are required" unless seller && buyer
+
+          check_required!("seller name": seller.name, "seller address": seller.address,
+                          "buyer name": buyer.name, "buyer address": buyer.address)
+          id_type = buyer.id_type.to_s
+          unless id_type.empty? || BUYER_ID_TYPES.include?(id_type)
+            raise ConfigurationError, "Unknown buyer id_type: #{id_type}"
+          end
+          return unless %w[eu other].include?(buyer.identification) && blank?(buyer.country)
+
+          raise ConfigurationError, "buyer country is required for a buyer identified by id_type " \
+                                    "#{buyer.identification.inspect} (Adres/KodKraju)"
+        end
+
+        def check_required!(**values)
+          missing = values.select { |_, value| blank?(value) }.keys
+          raise ConfigurationError, "#{missing.join(', ')} required" unless missing.empty?
+        end
+
+        def check_codes!
+          unknown = annotations.map(&:to_sym) - ANNOTATIONS.keys
+          raise ConfigurationError, "Unknown annotation(s): #{unknown.join(', ')}" unless unknown.empty?
+          raise ConfigurationError, "Unknown invoice_type: #{invoice_type}" unless INVOICE_TYPES.include?(invoice_type)
+          unless blank?(correction_type) || CORRECTION_TYPES.include?(correction_type.to_s)
+            raise ConfigurationError, "Unknown correction_type: #{correction_type}"
+          end
+          raise ConfigurationError, "Unknown currency: #{currency}" unless CURRENCY.match?(currency.to_s)
+
+          [seller, buyer].each do |party|
+            next if blank?(party.country) || COUNTRY.match?(party.country.to_s)
+
+            raise ConfigurationError, "Unknown country: #{party.country.inspect} (an ISO 3166 code such as \"DE\")"
+          end
+        end
+
+        def check_lines!
+          unknown_rates = lines.map(&:rate).uniq - RATES.keys
+          raise ConfigurationError, "Unknown VAT rate(s): #{unknown_rates.join(', ')}" unless unknown_rates.empty?
+
+          lines.each.with_index(1) do |line, index|
+            line.net
+            next if blank?(line.gtu) || GTU_CODES.include?(line.gtu.to_s)
+
+            raise ConfigurationError, "Unknown GTU code: #{line.gtu} (GTU_01 … GTU_13)"
+          rescue ConfigurationError => e
+            raise ConfigurationError, "line #{index}: #{e.message}"
+          end
+        end
+
+        def check_tax!
+          if exempt? && blank?(exemption_reason)
+            raise ConfigurationError, "exemption_reason is required for a zw line — the legal basis of the " \
+                                      "exemption (P_19A), e.g. \"art. 113 ust. 1 ustawy o VAT\""
+          end
+          return if currency == "PLN" || lines.none? { |line| VAT_RATES.include?(line.rate) }
+
+          raise ConfigurationError, "a #{currency} invoice with a 23/8/5% line must also state the VAT in PLN " \
+                                    "(P_14_xW), which the builder does not write — issue it in PLN"
+        end
+
+        def check_correction!
+          return unless correction?
+
+          check_required!(corrected_date: corrected_date, corrected_number: corrected_number)
+        end
+
+        def check_payment!
+          payment_code
+          flag = paid_flag
+          raise ConfigurationError, "paid_date is required when paid is true" if flag && blank?(paid_date)
+          raise ConfigurationError, "paid_date is given but paid is not true" if !flag && !blank?(paid_date)
+          raise ConfigurationError, "bank_name needs bank_account" if blank?(bank_account) && !blank?(bank_name)
+        end
+
+        # Every String that ends up in the XML: valid UTF-8, no character XML or KSeF refuses.
+        def check_text!
+          texts = to_h.except(:seller, :buyer, :lines).map { |name, value| [name.to_s, value] }
+          { "seller" => seller, "buyer" => buyer }.each do |role, party|
+            texts.concat(party.to_h.map { |name, value| ["#{role} #{name}", value] })
+          end
+          lines.each.with_index(1) do |line, index|
+            texts.concat(line.to_h.map { |name, value| ["line #{index} #{name}", value] })
+          end
+          texts.each { |label, value| check_string!(label, value) if value.is_a?(String) }
+        end
+
+        def check_string!(label, value)
+          unless [Encoding::UTF_8, Encoding::US_ASCII].include?(value.encoding) && value.valid_encoding?
+            raise ConfigurationError, "#{label} is not a UTF-8 String (#{value.encoding}) — " \
+                                      "convert it with String#encode(\"UTF-8\")"
+          end
+          bad = value[XML_DISALLOWED] || value[Validator::DISALLOWED_CHARACTERS]
+          return unless bad
+
+          raise ConfigurationError, "#{label} contains #{format('U+%04X', bad.ord)}, a character KSeF refuses"
+        end
+      end
+    end
+  end
+end

data/lib/ksef/invoices/builder/number.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Ksef
+  module Invoices
+    class Builder
+      # Reads and writes the builder's numbers exactly — never through Float.
+      # @api private
+      module Number
+        DECIMAL = /\A[+-]?\d+(?:[.,]\d+)?\z/
+        # Thousands grouped by a space, a no-break space or a narrow no-break space: "1 234,56".
+        GROUPED = /\A[+-]?\d{1,3}(?:[   ]\d{3})+(?:[.,]\d+)?\z/
+
+        module_function
+
+        # @param value [Integer, BigDecimal, Float, String, nil]
+        # @param field [String] the name used in the error message
+        # @param places [Integer] the most decimal places allowed
+        # @return [BigDecimal]
+        # @raise [Ksef::ConfigurationError] for a blank, malformed or non-finite value, or more decimal places
+        def parse(value, field, places:)
+          text = canonical(value)
+          raise ConfigurationError, "#{field} is required" if text.nil?
+          raise ConfigurationError, "#{field} is not a decimal number: #{value.inspect}" unless DECIMAL.match?(text)
+
+          number = BigDecimal(text.tr(",", "."))
+          unless number.round(places) == number
+            raise ConfigurationError, "#{field} has more than #{places} decimal places: #{value.inspect}"
+          end
+
+          number
+        end
+
+        # @param value [BigDecimal]
+        # @return [String] the amount with 2 decimal places, rounded half up ("100.00", "-0.50")
+        def amount(value)
+          rounded = value.round(2, BigDecimal::ROUND_HALF_UP)
+          rounded = BigDecimal("0") if rounded.zero?
+          whole, fraction = rounded.to_s("F").split(".")
+          "#{whole}.#{fraction.ljust(2, '0')}"
+        end
+
+        # @param value [BigDecimal]
+        # @return [String] the number without a trailing ".0" ("2", "1.5")
+        def plain(value)
+          value.to_s("F").delete_suffix(".0")
+        end
+
+        def canonical(value)
+          case value
+          when nil then nil
+          when Integer then value.to_s
+          when BigDecimal, Float then value.finite? ? BigDecimal(value.to_s).to_s("F") : value.to_s
+          when String
+            text = value.gsub(/\A[[:space:]]+|[[:space:]]+\z/, "")
+            return nil if text.empty?
+
+            GROUPED.match?(text) ? text.delete("   ") : text
+          else value.inspect
+          end
+        end
+        private_class_method :canonical
+      end
+    end
+  end
+end

data/lib/ksef/invoices/builder/xml.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "date"
+require "forwardable"
+require "nokogiri"
+
+module Ksef
+  module Invoices
+    class Builder
+      # Writes a {Builder}'s invoice as FA(3) XML, element by element in the schema's sequence.
+      # @api private
+      class Xml
+        extend Forwardable
+
+        def_delegators :@invoice, *(ATTRIBUTES - %i[annotations]), :totals_by_rate, :gross_total, :correction?,
+                       :annotation?, :exempt?, :payment_code, :paid_flag
+
+        # @param invoice [Builder]
+        def initialize(invoice)
+          @invoice = invoice
+        end
+
+        # @param created_at [Time]
+        # @return [String]
+        def render(created_at)
+          Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+            xml.Faktura(xmlns: FormCode::FA3.namespace) do
+              header(xml, created_at)
+              seller_element(xml)
+              buyer_element(xml)
+              invoice_body(xml)
+              footer_element(xml)
+            end
+          end.to_xml
+        end
+
+        private
+
+        def header(xml, created_at)
+          xml.Naglowek do
+            xml.KodFormularza("FA", kodSystemowy: FormCode::FA3.system_code, wersjaSchemy: FormCode::FA3.schema_version)
+            xml.WariantFormularza "3"
+            xml.DataWytworzeniaFa created_at.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+            xml.SystemInfo system_info
+          end
+        end
+
+        def seller_element(xml)
+          xml.Podmiot1 do
+            xml.DaneIdentyfikacyjne do
+              xml.NIP Nip.normalize!(seller.nip, name: "seller NIP")
+              xml.Nazwa seller.name
+            end
+            address(xml, seller)
+            contact(xml, seller)
+          end
+        end
+
+        def buyer_element(xml)
+          xml.Podmiot2 do
+            xml.DaneIdentyfikacyjne do
+              buyer_identifier(xml, buyer)
+              xml.Nazwa buyer.name
+            end
+            address(xml, buyer)
+            contact(xml, buyer)
+            xml.JST "2"
+            xml.GV "2"
+          end
+        end
+
+        # A choice: NIP | KodUE + NrVatUE | KodKraju + NrID | BrakID.
+        def buyer_identifier(xml, party)
+          case party.identification
+          when "nip" then xml.NIP Nip.normalize!(party.nip, name: "buyer NIP")
+          when "eu"
+            xml.KodUE party.eu_code.to_s.strip.upcase
+            xml.NrVatUE party.vat_eu.to_s.strip
+          when "other"
+            xml.KodKraju party.country
+            xml.NrID party.id_number.to_s.strip
+          else xml.BrakID "1"
+          end
+        end
+
+        # Without a country, a party identified by a NIP or by nothing is in Poland.
+        def address(xml, party)
+          xml.Adres do
+            xml.KodKraju blank?(party.country) ? "PL" : party.country
+            xml.AdresL1 party.address
+          end
+        end
+
+        def contact(xml, party)
+          email = party.email.to_s.strip
+          phone = party.phone.to_s.strip
+          return if email.empty? && phone.empty?
+
+          xml.DaneKontaktowe do
+            xml.Email email unless email.empty?
+            xml.Telefon phone unless phone.empty?
+          end
+        end
+
+        def invoice_body(xml)
+          xml.Fa do
+            xml.KodWaluty currency
+            xml.P_1 iso(issue_date, "issue_date")
+            xml.P_1M place unless blank?(place)
+            xml.P_2 number
+            xml.P_6 iso(sale_date, "sale_date") if sale_date
+            summary(xml)
+            annotations_element(xml)
+            xml.RodzajFaktury invoice_type
+            correction(xml) if correction?
+            lines.each_with_index { |line, i| invoice_line(xml, line, i + 1) }
+            payment(xml)
+          end
+        end
+
+        def summary(xml)
+          totals = totals_by_rate
+          RATES.each do |rate, fields|
+            next unless totals[rate]
+
+            xml.public_send(fields[:net], amount(totals[rate][:net]))
+            xml.public_send(fields[:vat], amount(totals[rate][:vat])) if fields[:vat]
+          end
+          xml.P_15 amount(gross_total)
+        end
+
+        def annotations_element(xml)
+          flag = ->(key) { annotation?(key) ? "1" : "2" }
+          xml.Adnotacje do
+            %i[cash_method self_billing reverse_charge split_payment].each do |key|
+              xml.public_send(ANNOTATIONS[key], flag.call(key))
+            end
+            exemption(xml)
+            xml.NoweSrodkiTransportu { xml.P_22N "1" }
+            xml.P_23 flag.call(:triangular)
+            xml.PMarzy { xml.P_PMarzyN "1" }
+          end
+        end
+
+        def exemption(xml)
+          xml.Zwolnienie do
+            if exempt?
+              xml.P_19 "1"
+              xml.P_19A exemption_reason
+            else
+              xml.P_19N "1"
+            end
+          end
+        end
+
+        # `DaneFaKorygowanej` holds a choice: NrKSeF=1 + the KSeF number, or NrKSeFN=1 (issued outside KSeF).
+        def correction(xml)
+          xml.PrzyczynaKorekty correction_reason unless blank?(correction_reason)
+          xml.TypKorekty correction_type unless blank?(correction_type)
+          xml.DaneFaKorygowanej do
+            xml.DataWystFaKorygowanej iso(corrected_date, "corrected_date")
+            xml.NrFaKorygowanej corrected_number
+            if blank?(corrected_ksef_number)
+              xml.NrKSeFN "1"
+            else
+              xml.NrKSeF "1"
+              xml.NrKSeFFaKorygowanej corrected_ksef_number.strip
+            end
+          end
+        end
+
+        def invoice_line(xml, line, index)
+          xml.FaWiersz do
+            xml.NrWierszaFa index
+            xml.P_7 line.name
+            optional(xml, Indeks: line.index, GTIN: line.gtin, PKWiU: line.pkwiu, CN: line.cn, P_8A: line.unit)
+            xml.P_8B Number.plain(line.number(:quantity))
+            xml.P_9A amount(line.number(:unit_price))
+            xml.P_10 amount(line.number(:discount)) if line.discount?
+            xml.P_11 amount(line.net)
+            xml.P_12 line.rate
+            xml.GTU line.gtu unless blank?(line.gtu)
+          end
+        end
+
+        # Written when any payment field is given. `Zaplacono` + `DataZaplaty` is the first branch of an
+        # optional choice, ahead of the due date.
+        def payment(xml)
+          code = payment_code
+          return if code.nil? && !paid_flag && due_date.nil? && blank?(bank_account)
+
+          xml.Platnosc do
+            if paid_flag
+              xml.Zaplacono "1"
+              xml.DataZaplaty iso(paid_date, "paid_date")
+            end
+            xml.TerminPlatnosci { xml.Termin iso(due_date, "due_date") } if due_date
+            xml.FormaPlatnosci code if code
+            bank_account_element(xml)
+          end
+        end
+
+        def bank_account_element(xml)
+          return if blank?(bank_account)
+
+          xml.RachunekBankowy do
+            xml.NrRB bank_account.delete(" ")
+            xml.NazwaBanku bank_name unless blank?(bank_name)
+          end
+        end
+
+        def footer_element(xml)
+          registers = { KRS: krs, REGON: regon, BDO: bdo }.reject { |_, v| blank?(v) }
+          return if blank?(footer) && registers.empty?
+
+          xml.Stopka do
+            xml.Informacje { xml.StopkaFaktury footer } unless blank?(footer)
+            xml.Rejestry { optional(xml, **registers) } if registers.any?
+          end
+        end
+
+        # Emits each non-blank field in the given (schema) order.
+        def optional(xml, **fields)
+          fields.each { |tag, value| xml.public_send(tag, value.to_s.strip) unless blank?(value) }
+        end
+
+        def blank?(value)
+          value.to_s.strip.empty?
+        end
+
+        # Only a Date or "YYYY-MM-DD": a Time or a timestamp String is refused, as its calendar day depends
+        # on its zone.
+        def iso(date, name)
+          return nil if date.nil?
+
+          if date.is_a?(String)
+            raise Date::Error unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+            return Date.iso8601(date).strftime("%Y-%m-%d")
+          end
+          unless date.is_a?(Date) && !date.is_a?(DateTime)
+            raise ConfigurationError, "#{name} must be a Date or \"YYYY-MM-DD\", not a #{date.class}"
+          end
+
+          date.strftime("%Y-%m-%d")
+        rescue Date::Error
+          raise ConfigurationError, "#{name} is not a valid date (\"YYYY-MM-DD\"): #{date.inspect}"
+        end
+
+        def amount(value)
+          Number.amount(value)
+        end
+      end
+    end
+  end
+end