ksef-client-rails 0.1.0 → 1.0.0

data/lib/ksef/invoices/schema_outline.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ksef
+  module Invoices
+    # The element tree of a packaged form schema — the fields an invoice may carry, with cardinality
+    # and type ({Validator#outline}). The schemas are large, so it renders a subtree to a given depth.
+    # @api private
+    class SchemaOutline
+      # @param schema_path [String] packaged XSD file
+      def initialize(schema_path)
+        @doc = Nokogiri::XML(File.read(schema_path))
+        @doc.remove_namespaces!
+        @types = @doc.xpath("/schema/complexType").to_h { |node| [node["name"], node] }
+      end
+
+      # @param path [String] slash-separated element path, e.g. "Faktura/Fa/Adnotacje"
+      # @param depth [Integer] levels below +path+
+      # @param descriptions [Boolean] add each element's description from the schema on its own line
+      # @return [String] one line per element: name (indented), cardinality, type
+      # @raise [Ksef::ConfigurationError] when the path does not exist in the schema
+      def render(path, depth, descriptions: false)
+        @descriptions = descriptions
+        lines = []
+        walk(resolve(path), depth, "", lines)
+        lines.join("\n")
+      end
+
+      private
+
+      def walk(element, depth, indent, lines)
+        type = complex_type(element)
+        return if type.nil? || depth.zero?
+
+        group_elements(type).each do |child, occurrence, branch|
+          note = cardinality(child, occurrence) + (branch ? " | #{branch}" : "")
+          lines << format("%<name>-44s %<note>-20s %<type>s",
+                          name: indent + child["name"], note: note, type: child["type"].to_s.split(":").last).rstrip
+          text = @descriptions && description(child)
+          lines << "#{indent}  — #{text}" if text
+          walk(child, depth - 1, "#{indent}  ", lines)
+        end
+      end
+
+      # The element's `xsd:documentation`, or its named type's, on one line.
+      def description(element)
+        node = element.at_xpath("./annotation/documentation") ||
+               @types[element["type"].to_s.split(":").last]&.at_xpath("./annotation/documentation")
+        text = node&.text.to_s.gsub(/\s+/, " ").strip
+        text.empty? ? nil : text
+      end
+
+      # The complexType behind an element: inline, or looked up by its type name.
+      def complex_type(element)
+        element.at_xpath("./complexType") || @types[element["type"].to_s.split(":").last]
+      end
+
+      # Elements of a model group with the occurrence of their enclosing groups (an optional or repeated
+      # sequence/choice makes its elements so) and their choice branch: "choice" for a single-element
+      # branch, "choice: A+B" for a sequence one. An extension starts with its base type's elements.
+      def group_elements(node, occurrence = { optional: false, max: nil }, branch = nil, out = [])
+        node.element_children.each do |child|
+          case child.name
+          when "element" then out << [child, occurrence, branch]
+          when "sequence", "all" then group_elements(child, within(child, occurrence), branch, out)
+          when "complexContent", "restriction" then group_elements(child, occurrence, branch, out)
+          when "extension"
+            base = @types[child["base"].to_s.split(":").last]
+            group_elements(base, occurrence, branch, out) if base
+            group_elements(child, occurrence, branch, out)
+          when "choice" then choice_elements(child, within(child, occurrence), out)
+          end
+        end
+        out
+      end
+
+      def choice_elements(choice, occurrence, out)
+        choice.element_children.each do |alternative|
+          names = alternative.name == "element" ? [] : group_elements(alternative).map { |element, *| element["name"] }
+          label = names.size > 1 ? "choice: #{names.join('+')}" : "choice"
+          case alternative.name
+          when "element" then out << [alternative, occurrence, label]
+          when "choice" then choice_elements(alternative, within(alternative, occurrence), out)
+          else group_elements(alternative, within(alternative, occurrence), label, out)
+          end
+        end
+      end
+
+      def within(group, occurrence)
+        max = group["maxOccurs"]
+        { optional: occurrence[:optional] || group["minOccurs"] == "0",
+          max: occurrence[:max] || (max && max != "1" ? max : nil) }
+      end
+
+      def cardinality(element, occurrence)
+        min = occurrence[:optional] ? "0" : element["minOccurs"] || "1"
+        max = element["maxOccurs"] || "1"
+        max = occurrence[:max] if max == "1" && occurrence[:max]
+        return "required" if [min, max] == %w[1 1]
+        return "optional" if min == "0" && max == "1"
+
+        "#{min}..#{max}"
+      end
+
+      def resolve(path)
+        names = path.to_s.split("/")
+        node = @doc.xpath("/schema/element").find { |element| element["name"] == names.first }
+        raise ConfigurationError, "No top-level element #{names.first.inspect} in the schema" unless node
+
+        names.drop(1).each do |name|
+          type = complex_type(node)
+          node = type && group_elements(type).map(&:first).find { |element| element["name"] == name }
+          raise ConfigurationError, "#{name} not found under #{path}" unless node
+        end
+        node
+      end
+    end
+  end
+end

data/lib/ksef/invoices/validator.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ksef
+  module Invoices
+    # Validates an invoice locally against the form XSD KSeF applies, plus KSeF's XML rules (UTF-8 without
+    # a BOM, no processing instructions, no discouraged characters): what fails here fails on KSeF too, in
+    # libxml2's wording rather than KSeF's. Schemas ship with the gem (FA(2), FA(3), FA_RR(1)); not PEF (UBL).
+    class Validator
+      # Directory holding the schemas packaged with the gem.
+      SCHEMA_ROOT = File.expand_path("../../../schemas", __dir__)
+
+      # Form `systemCode` → schema file. The version lives in the file name, so a new
+      # `schemaVersion` means replacing the file plus the FormCode constant (schemas/README.md).
+      SCHEMAS = {
+        "FA (2)" => "FA/schemat_FA(2)_v1-0E.xsd",
+        "FA (3)" => "FA/schemat_FA(3)_v1-0E.xsd",
+        "FA_RR (1)" => "RR/schemat_FA_RR(1)_v1-1E.xsd"
+      }.freeze
+
+      # Code points KSeF refuses anywhere in an invoice (beyond what XML 1.0 itself forbids): C1 controls
+      # except U+0085, and the Unicode noncharacters.
+      DISALLOWED_CHARACTERS = Regexp.new(
+        "[\\u007F-\\u0084\\u0086-\\u009F\\uFDD0-\\uFDEF" \
+        "#{(0..16).map { |plane| format('\\u{%<p>XFFFE}\\u{%<p>XFFFF}', p: plane) }.join}]"
+      )
+
+      # One violation: `path` names the element (e.g. "Faktura/Podmiot2/DaneIdentyfikacyjne/NIP"), nil for
+      # a document that is not well-formed and for KSeF's document-level rules.
+      Issue = Struct.new(:path, :line, :message, keyword_init: true)
+
+      @schemas = {}
+      @schemas_lock = Mutex.new
+
+      # @return [String] systemCode of the form this instance validates against
+      attr_reader :system_code
+
+      # @param form_code [Ksef::FormCode, String] invoice form (object or systemCode)
+      # @raise [Ksef::ConfigurationError] when no packaged schema exists for the form
+      def initialize(form_code: FormCode::FA3)
+        @system_code = form_code.respond_to?(:system_code) ? form_code.system_code : form_code.to_s
+        @schema = self.class.schema(@system_code)
+      end
+
+      # Path to the schema for the given `systemCode`.
+      #
+      # @param system_code [String]
+      # @return [String]
+      # @raise [Ksef::ConfigurationError]
+      def self.schema_path(system_code)
+        relative = SCHEMAS[system_code]
+        if relative.nil?
+          raise ConfigurationError, "no packaged schema for form #{system_code.inspect} " \
+                                    "(available: #{SCHEMAS.keys.join(', ')})"
+        end
+
+        File.join(SCHEMA_ROOT, relative)
+      end
+
+      # The parsed schema, loaded once per process — parsing the XSD set costs far more than a
+      # validation, and a parsed schema is safe to share between threads.
+      #
+      # The schema is loaded as a document WITH the file URL — without it the relative
+      # `../bazowe/...` import has nothing to resolve against and libxml tries to fetch the schema
+      # over the network (which it refuses: "Attempt to load network entity").
+      #
+      # @param system_code [String]
+      # @return [Nokogiri::XML::Schema]
+      # @raise [Ksef::ConfigurationError]
+      def self.schema(system_code)
+        @schemas_lock.synchronize do
+          @schemas[system_code] ||= begin
+            path = schema_path(system_code)
+            Nokogiri::XML::Schema.from_document(Nokogiri::XML(File.read(path), path))
+          end
+        end
+      end
+
+      # Validates the invoice and returns the validator messages — a document that is not well-formed
+      # XML yields its parse error instead.
+      #
+      # @param xml [String] invoice XML
+      # @return [Array<String>] empty when the invoice matches the schema and KSeF's XML rules
+      def validate(xml)
+        errors(xml).map(&:message)
+      end
+
+      # Like {#validate}, with the element path and line of each violation — e.g. to show it next to a
+      # form field.
+      #
+      # @param xml [String] invoice XML
+      # @return [Array<Issue>] empty when the invoice matches the schema and KSeF's XML rules
+      def errors(xml)
+        rules = document_issues(xml.to_s)
+        doc = parse(xml)
+        namespace = doc.errors.select { |error| error.error? || error.fatal? }.map { |error| issue(error, nil) }
+        return rules + namespace unless namespace.empty?
+
+        rules + processing_instructions(doc) + @schema.validate(doc).map { |error| issue(error, doc) }
+      rescue Nokogiri::XML::SyntaxError => e
+        rules + [issue(e, nil)]
+      end
+
+      # The form's field tree — what an invoice may carry, with cardinality and type.
+      #
+      # @param path [String] slash-separated element path, e.g. "Faktura/Fa/Adnotacje"
+      # @param depth [Integer, nil] levels to show; nil — 2 for "Faktura", the whole subtree otherwise
+      # @param descriptions [Boolean] add each element's description from the schema (Polish) below it
+      # @return [String] one line per element: name (indented by depth), cardinality, type
+      # @raise [Ksef::ConfigurationError] when the path does not exist in the schema
+      def outline(path = "Faktura", depth: nil, descriptions: false)
+        depth ||= path == "Faktura" ? 2 : 99
+        SchemaOutline.new(self.class.schema_path(system_code)).render(path, depth, descriptions: descriptions)
+      end
+
+      # @param xml [String]
+      # @return [Boolean] whether the invoice matches the schema
+      def valid?(xml)
+        validate(xml).empty?
+      end
+
+      # Validates and raises when the invoice does not match.
+      #
+      # @param xml [String]
+      # @return [true]
+      # @raise [Ksef::SchemaValidationError]
+      def validate!(xml)
+        issues = errors(xml)
+        return true if issues.empty?
+
+        raise SchemaValidationError.new("invoice does not match schema #{system_code}",
+                                        messages: issues.map(&:message), errors: issues, system_code: system_code)
+      end
+
+      private
+
+      # KSeF's checks of the document itself (faktury/weryfikacja-faktury.md), before its schema.
+      def document_issues(xml)
+        bytes = xml.b
+        issues = []
+        issues << rule("the document starts with a byte order mark; KSeF requires UTF-8 without one") if
+          bytes.start_with?("\xEF\xBB\xBF".b)
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        # UTF-16 text is valid UTF-8 byte for byte only as long as it holds NULs, which XML never may.
+        return issues << rule("the document is not valid UTF-8") if !text.valid_encoding? || text.include?("\0")
+
+        declaration = text[/\A\uFEFF?<\?xml\s[^>]*\?>/].to_s
+        encoding = declaration[/encoding\s*=\s*["']([^"']+)["']/, 1]
+        issues << rule("the XML declaration names encoding #{encoding}; KSeF requires UTF-8") if
+          encoding && !encoding.casecmp?("UTF-8")
+        version = declaration[/version\s*=\s*["']([^"']+)["']/, 1]
+        issues << rule("the document declares XML #{version}; KSeF requires XML 1.0") if version && version != "1.0"
+        bad = text[DISALLOWED_CHARACTERS]
+        issues << rule("the document contains #{format('U+%04X', bad.ord)}, a character KSeF refuses") if bad
+        issues
+      end
+
+      def processing_instructions(doc)
+        doc.xpath("//processing-instruction()").map do |node|
+          Issue.new(path: nil, line: node.line, message: "processing instruction <?#{node.name}?>: KSeF refuses them")
+        end
+      end
+
+      def rule(message)
+        Issue.new(path: nil, line: nil, message: message)
+      end
+
+      def issue(error, doc)
+        Issue.new(path: element_path(error, doc), line: error.line, message: error.message.strip)
+      end
+
+      # libxml2 reports a positional path ("/*/*[3]/*[1]", "/*/f:P_2"); this walks it step by step by
+      # local name and position — the prefixes need not be declared on the root — and names each step.
+      def element_path(error, doc)
+        xpath = error.respond_to?(:path) ? error.path : nil
+        return nil if doc.nil? || xpath.nil? || !xpath.start_with?("/")
+
+        node = xpath.delete_prefix("/").split("/").inject(doc) { |parent, step| parent && child_at(parent, step) }
+        return nil unless node.is_a?(Nokogiri::XML::Element)
+
+        [*node.ancestors.reverse.grep(Nokogiri::XML::Element), node].map(&:name).join("/")
+      end
+
+      def child_at(parent, step)
+        name, index = step.match(/\A(?:[^:\[]+:)?([^\[]+)(?:\[(\d+)\])?\z/)&.captures
+        return nil unless name
+
+        candidates = parent.element_children.select { |child| name == "*" || child.name == name }
+        candidates[(index || "1").to_i - 1]
+      end
+
+      # Strict, so that a document KSeF would reject as malformed fails here too (the default RECOVER
+      # mode silently repairs it); no network access, no entity expansion.
+      def parse(xml)
+        Nokogiri::XML(xml) { |config| config.strict.nonet }
+      end
+    end
+  end
+end

data/lib/ksef/models/form_code.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Invoice schema code. The { systemCode, schemaVersion, value } object
+  # passed when opening a session.
+  #
+  # FA(2) is available on TEST only — the gem defaults to FA(3).
+  class FormCode
+    # @return [String] system code (e.g. "FA (3)")
+    attr_reader :system_code
+    # @return [String] schema version (e.g. "1-0E")
+    attr_reader :schema_version
+    # @return [String] value (e.g. "FA")
+    attr_reader :value
+    # @return [String, nil] XML namespace of the invoice document (the schema's targetNamespace);
+    #   nil for PEF, whose UBL schemas are not packaged
+    attr_reader :namespace
+
+    # @param system_code [String]
+    # @param schema_version [String]
+    # @param value [String]
+    # @param namespace [String, nil]
+    def initialize(system_code:, schema_version:, value:, namespace: nil)
+      @system_code = system_code
+      @schema_version = schema_version
+      @value = value
+      @namespace = namespace
+    end
+
+    # @return [Hash] JSON representation matching the API contract
+    def to_h
+      { "systemCode" => system_code, "schemaVersion" => schema_version, "value" => value }
+    end
+
+    # FA(2) — TEST environment only.
+    FA2 = new(system_code: "FA (2)", schema_version: "1-0E", value: "FA",
+              namespace: "http://crd.gov.pl/wzor/2023/06/29/12648/")
+    # FA(3) — the default production schema.
+    FA3 = new(system_code: "FA (3)", schema_version: "1-0E", value: "FA",
+              namespace: "http://crd.gov.pl/wzor/2025/06/25/13775/")
+    # PEF(3) — PEF invoices.
+    PEF3 = new(system_code: "PEF (3)", schema_version: "2-1", value: "PEF")
+    # PEF_KOR(3) — PEF corrections.
+    PEF_KOR3 = new(system_code: "PEF_KOR (3)", schema_version: "2-1", value: "PEF")
+    # FA_RR(1) — RR invoices (flat-rate farmers).
+    FA_RR1 = new(system_code: "FA_RR (1)", schema_version: "1-1E", value: "FA_RR",
+                 namespace: "http://crd.gov.pl/wzor/2026/03/06/14189/")
+  end
+end

data/lib/ksef/models/ksef_number.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ksef
+  # KSeF number value object, e.g. `5555555555-20250826-0100001AF629-72`.
+  #
+  # The trailing 2 HEX characters are CRC-8 (poly 0x07, init 0x00) over everything before the
+  # last "-", hyphens included. The pattern also accepts the 36-character form (with a "-" inside the
+  # 12-character hex part).
+  class KsefNumber
+    CRC8_POLYNOMIAL = 0x07
+    CRC8_INIT = 0x00
+    # `KsefNumber` in the KSeF contract: seller NIP, date (YYYYMMDD), uppercase hex, CRC.
+    PATTERN = /\A[1-9](\d[1-9]|[1-9]\d)\d{7}-(20[2-9]\d|2[1-9]\d{2}|[3-9]\d{3})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])-
+               [0-9A-F]{6}-?[0-9A-F]{6}-[0-9A-F]{2}\z/x
+
+    # @return [String] raw number value
+    attr_reader :value
+
+    # @param value [String]
+    def initialize(value)
+      @value = value.to_s
+    end
+
+    # @return [Boolean] whether the number matches the contract pattern and its CRC-8 checksum
+    def valid?
+      return false unless @value.match?(PATTERN)
+
+      data, _sep, checksum = @value.rpartition("-")
+      checksum == format("%02X", self.class.crc8(data))
+    end
+
+    # Validates and returns the object, or raises.
+    # @return [self]
+    # @raise [Ksef::ConfigurationError] when the number is invalid
+    def validate!
+      raise ConfigurationError, "Invalid KSeF number: #{@value.inspect}" unless valid?
+
+      self
+    end
+
+    # @return [String] seller tax identification number (the first 10 characters)
+    def seller_nip
+      @value[0, 10]
+    end
+
+    def to_s
+      @value
+    end
+
+    # Equal to another KsefNumber with the same value (not to a String, so that equality stays symmetric).
+    def ==(other)
+      other.is_a?(KsefNumber) && value == other.value
+    end
+    alias eql? ==
+
+    def hash
+      value.hash
+    end
+
+    # Computes CRC-8 (poly 0x07, init 0x00, no reflection or xorout) over ASCII bytes.
+    # @param string [String]
+    # @return [Integer] value 0–255
+    def self.crc8(string)
+      crc = CRC8_INIT
+      string.each_byte do |byte|
+        crc ^= byte
+        8.times do
+          crc = crc.anybits?(0x80) ? ((crc << 1) ^ CRC8_POLYNOMIAL) & 0xFF : (crc << 1) & 0xFF
+        end
+      end
+      crc
+    end
+  end
+end

data/lib/ksef/models/nip.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Polish tax identification number (NIP): the contract's pattern (no leading zero, digits 2–3 not
+  # both zero) plus the mod-11 checksum — weights [6,5,7,2,3,4,5,6,7], a remainder of 10 is invalid.
+  class Nip
+    WEIGHTS = [6, 5, 7, 2, 3, 4, 5, 6, 7].freeze
+    # `Nip` in the KSeF contract.
+    PATTERN = /\A[1-9]((\d[1-9])|([1-9]\d))\d{7}\z/
+
+    # @return [String] digits only (separators and the "PL" prefix stripped)
+    attr_reader :value
+
+    # Normalizes a NIP given to the gem, refusing an invalid one before it reaches KSeF or a QR link.
+    # @param value [String, Nip] tax id; spaces (no-break ones too), dashes and a "PL" prefix are stripped
+    # @param name [String] argument name for the error message
+    # @return [String] the 10 digits
+    # @raise [Ksef::ConfigurationError] when the number is invalid
+    def self.normalize!(value, name: "NIP")
+      nip = value.is_a?(Nip) ? value : new(value)
+      raise ConfigurationError, "#{name} is not a valid NIP: #{value.to_s.dump}" unless nip.valid?
+
+      nip.value
+    end
+
+    # @param value [String] tax id; spaces (no-break ones too), dashes and a "PL" prefix are stripped
+    def initialize(value)
+      @value = value.to_s.gsub(/[[:space:]\p{Pd}]/, "").sub(/\APL/i, "")
+    end
+
+    # @return [Boolean] whether it matches the contract pattern and has a valid check digit
+    def valid?
+      return false unless @value.match?(PATTERN)
+
+      digits = @value.chars.map(&:to_i)
+      checksum = WEIGHTS.each_with_index.sum { |w, i| w * digits[i] } % 11
+      checksum != 10 && checksum == digits[9]
+    end
+
+    # @return [self]
+    # @raise [Ksef::ConfigurationError] when the number is invalid
+    def validate!
+      raise ConfigurationError, "Invalid tax identification number: #{@value.inspect}" unless valid?
+
+      self
+    end
+
+    def to_s
+      @value
+    end
+
+    # Equal to another Nip with the same digits (not to a String, so that equality stays symmetric).
+    def ==(other)
+      other.is_a?(Nip) && value == other.value
+    end
+    alias eql? ==
+
+    def hash
+      value.hash
+    end
+  end
+end

data/lib/ksef/polish_time.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Ksef
+  # The Europe/Warsaw calendar, which KSeF dates follow (e.g. an invoice's `P_1`), without tzinfo: CET
+  # (+01:00), and CEST (+02:00) from 01:00 UTC on the last Sunday of March to 01:00 UTC on the last
+  # Sunday of October — the EU rule.
+  module PolishTime
+    module_function
+
+    # @param now [Time]
+    # @return [Date] the current calendar day in Poland
+    def today(now = Time.now)
+      at(now).to_date
+    end
+
+    # @param time [Time]
+    # @return [Time] the same instant with the Polish UTC offset
+    def at(time)
+      utc = time.getutc
+      utc.getlocal(offset(utc))
+    end
+
+    # @param date [Date]
+    # @return [Time] midnight in Poland at the start of the day
+    def midnight(date)
+      utc = Time.utc(date.year, date.month, date.day)
+      offset = offset(utc - 3600)
+      (utc - offset).getlocal(offset)
+    end
+
+    # @param utc [Time]
+    # @return [Integer] the Polish UTC offset in seconds at that instant
+    def offset(utc)
+      summer_start = switch(utc.year, 3)
+      summer_end = switch(utc.year, 10)
+      utc >= summer_start && utc < summer_end ? 7200 : 3600
+    end
+
+    # 01:00 UTC on the last Sunday of the month.
+    def switch(year, month)
+      last = Date.new(year, month, -1)
+      sunday = last - last.wday
+      Time.utc(year, month, sunday.day, 1)
+    end
+    private_class_method :switch
+  end
+end

data/lib/ksef/polling.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Polling helper for async operations: auth, sessions, export, enrollment, permissions.
+  # The block returns {.pending} to keep waiting (backoff + Retry-After); any other value is the
+  # result. Backoff is a deliberate improvement over both SDKs, which poll only in their tests.
+  module Polling
+    # "Operation in progress" signal — optionally carries retry_after (seconds) from the server.
+    Pending = Struct.new(:retry_after, keyword_init: true)
+
+    module_function
+
+    # @param retry_after [Numeric, nil] suggested delay before the next attempt (from Retry-After)
+    # @return [Pending]
+    def pending(retry_after: nil)
+      Pending.new(retry_after: retry_after)
+    end
+
+    # Polls with exponential backoff until the block returns a value other than {.pending}.
+    #
+    # @param timeout [Numeric] maximum total wait time (s)
+    # @param interval [Numeric] initial delay between attempts (s)
+    # @param max_interval [Numeric] upper bound for the delay (s)
+    # @param backoff [Numeric] delay growth multiplier
+    # @param logger [Logger, nil]
+    # @param description [String] operation description for logs and the timeout message
+    # @yieldreturn [Pending, Object] {.pending} to continue, anything else is the final result
+    # @return [Object] the value returned by the block
+    # @raise [Ksef::PollingTimeout] once +timeout+ is exceeded
+    def run(timeout: 300, interval: 2.0, max_interval: 30.0, backoff: 1.5, logger: nil, description: "operation")
+      start = clock
+      current = interval.to_f
+      last = nil
+      loop do
+        result = yield
+        return result unless result.is_a?(Pending)
+
+        last = result
+        elapsed = clock - start
+        if elapsed >= timeout
+          raise PollingTimeout.new("Wait limit exceeded (#{timeout}s) for: #{description}",
+                                   last_status: describe(last))
+        end
+
+        wait = wait_seconds(result, current, timeout - elapsed)
+        logger&.debug("[ksef] polling #{description}: waiting #{wait.round(1)}s (elapsed #{elapsed.round(1)}s)")
+        sleep(wait) if wait.positive?
+        current = [current * backoff, max_interval.to_f].min
+      end
+    end
+
+    def wait_seconds(pending, current, remaining)
+      wait = (pending.retry_after || current).to_f
+      [wait, remaining].min
+    end
+
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def describe(pending)
+      pending.retry_after ? "pending(retry_after=#{pending.retry_after})" : "pending"
+    end
+  end
+end