ksef_client 0.1.0.rc1

data/lib/ksef/http/connection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ksef
+  module HTTP
+    # Builds the single Faraday connection a {Ksef::Client} owns.
+    #
+    # One connection per client, shared across threads — safe with the default `net_http`
+    # adapter (DESIGN.md §5.2). The adapter is kept swappable via configuration.
+    module Connection
+      # `application/problem+json` is the current error content type, so the response
+      # parser must match it as well as plain `application/json`
+      # (docs/REFERENCE.md §5.1).
+      JSON_CONTENT_TYPE = /\bjson\b/
+
+      class << self
+        # @param config [Ksef::Configuration]
+        # @return [Faraday::Connection]
+        def build(config)
+          Faraday.new(url: config.base_url, headers: default_headers(config)) do |f|
+            f.request :json
+
+            # Registration order is load-bearing. Faraday runs `on_complete` callbacks
+            # innermost-first, so the JSON parser must be registered *after* the error
+            # handler for the handler to see a decoded body rather than a raw string.
+            f.use ErrorHandler
+            f.use SystemWarning, logger: config.logger
+            f.response :json, content_type: JSON_CONTENT_TYPE
+
+            apply_transport_options(f, config)
+            f.adapter config.adapter
+          end
+        end
+
+        private
+
+        def apply_transport_options(faraday, config)
+          faraday.options.open_timeout = config.open_timeout
+          faraday.options.timeout = config.read_timeout
+          faraday.proxy = config.proxy if config.proxy
+
+          # TLS verification is never disabled, on any code path (DESIGN.md §4.5).
+          faraday.ssl.verify = true
+          faraday.ssl.min_version = :TLS1_2
+        end
+
+        def default_headers(config)
+          {
+            "Accept" => "application/json",
+            # Opts into RFC7807 error bodies. Every one of the 83 operations documents
+            # this header, and the modern envelope is opt-in: without it the API returns
+            # the deprecated shapes, which carry no traceId, no structured `errors[]`
+            # codes on 400 and no reasonCode on 403 (docs/REFERENCE.md §5.1).
+            "X-Error-Format" => "problem-details",
+            "User-Agent" => config.user_agent
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ksef/http/error_handler.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ksef
+  module HTTP
+    # Maps KSeF error responses and Faraday transport failures onto the {Ksef::Error}
+    # hierarchy (DESIGN.md §6.7).
+    #
+    # Status coverage follows what the contract actually declares — 400, 401, 403, 410
+    # and 429 (docs/REFERENCE.md §5.4). 5xx is handled defensively: the spec never
+    # declares it, so the body shape is unknown and degrades to a raw payload.
+    class ErrorHandler < Faraday::Middleware
+      STATUS_MAP = {
+        400 => ApiError,
+        401 => AuthenticationError,
+        403 => AuthorizationError,
+        410 => ResourceGoneError,
+        429 => RateLimitedError
+      }.freeze
+
+      def call(env)
+        super
+      rescue Faraday::TimeoutError => e
+        raise Ksef::TimeoutError, "KSeF request timed out: #{e.message}"
+      rescue Faraday::SSLError => e
+        raise Ksef::ConnectionError, "TLS failure talking to KSeF: #{e.message}"
+      rescue Faraday::ConnectionFailed => e
+        # The net_http adapter reports `Net::OpenTimeout` as a connection failure, which
+        # loses the distinction a caller most needs after submitting an invoice: a
+        # timeout may have been processed server-side, a refused connection was not.
+        raise Ksef::TimeoutError, "KSeF connection timed out: #{e.message}" if timeout?(e.wrapped_exception)
+
+        raise Ksef::ConnectionError, "Could not connect to KSeF: #{e.message}"
+      end
+
+      def on_complete(env)
+        status = env.status
+        return if status < 400
+
+        problem = ProblemDetails.parse(status: status, body: env.body)
+        raise build_error(status, problem, env)
+      end
+
+      private
+
+      # `Net::OpenTimeout` and `Net::ReadTimeout` both descend from `Timeout::Error`.
+      def timeout?(wrapped)
+        defined?(Timeout::Error) && wrapped.is_a?(Timeout::Error)
+      end
+
+      def build_error(status, problem, env)
+        message = "KSeF API #{status}: #{problem.summary}"
+        message = "#{message} (traceId: #{problem.trace_id})" if problem.trace_id
+
+        if status == 429
+          RateLimitedError.new(message, problem: problem, retry_after: retry_after_from(env))
+        else
+          error_class(status).new(message, problem: problem)
+        end
+      end
+
+      def error_class(status)
+        STATUS_MAP[status] || (status >= 500 ? ServerError : ApiError)
+      end
+
+      # `Retry-After` is present on every declared 429 and is expressed in seconds
+      # (docs/REFERENCE.md §5.5). The HTTP-date form is accepted defensively.
+      def retry_after_from(env)
+        raw = env.response_headers&.[]("Retry-After")
+        return if raw.nil? || raw.to_s.strip.empty?
+
+        value = raw.to_s.strip
+        return Integer(value, 10) if /\A\d+\z/.match?(value)
+
+        seconds = (Time.httpdate(value) - Time.now).ceil
+        seconds.positive? ? seconds : 0
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/ksef/http/system_warning.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ksef
+  module HTTP
+    # Surfaces the `X-System-Warning` header the API sets on every successful response
+    # (docs/REFERENCE.md §5.5).
+    #
+    # This is the Ministry's in-band channel for advisory notices — deprecations,
+    # forthcoming contract changes — and is not mentioned in DESIGN.md. Swallowing it
+    # would mean users only learn about a change when it breaks them.
+    class SystemWarning < Faraday::Middleware
+      HEADER = "X-System-Warning"
+
+      def initialize(app, logger: nil)
+        super(app)
+        @logger = logger
+      end
+
+      def on_complete(env)
+        warning = env.response_headers&.[](HEADER)
+        return if warning.nil? || warning.to_s.strip.empty?
+
+        @logger&.warn("[ksef_client] #{HEADER}: #{warning}")
+      end
+    end
+  end
+end

data/lib/ksef/problem_details.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Ksef
+  # A parsed KSeF error body.
+  #
+  # KSeF serves errors in two different envelopes and the response `Content-Type` picks
+  # between them (docs/REFERENCE.md §5.1): `application/problem+json` is current, while
+  # `application/json` returns legacy shapes the spec marks deprecated but which are
+  # still live in the wild. This class normalises all of them, and degrades to a raw
+  # payload for bodies that are neither (an HTML block page from the WAF in front of the
+  # API, for instance).
+  ProblemDetails = Data.define(
+    :status,
+    :title,
+    :detail,
+    :instance,
+    :timestamp,
+    :trace_id,
+    :entries,
+    :reason_code,
+    :security,
+    :raw
+  )
+
+  # Parsing and presentation for {Ksef::ProblemDetails}.
+  class ProblemDetails
+    # One entry of a 400's `errors[]`. Called `ApiError` in the OpenAPI spec, renamed
+    # here to avoid colliding with the {Ksef::ApiError} exception class.
+    Entry = Data.define(:code, :description, :details)
+
+    # Only `status` and `raw` are common to every envelope; everything else is absent in
+    # at least one of them, so the builders below name only what they actually have.
+    DEFAULTS = {
+      status: nil, title: nil, detail: nil, instance: nil, timestamp: nil,
+      trace_id: nil, entries: [].freeze, reason_code: nil, security: {}.freeze, raw: nil
+    }.freeze
+
+    class << self
+      # @param status [Integer] HTTP status
+      # @param body [Hash, String, nil] decoded JSON body, or the raw string
+      # @return [Ksef::ProblemDetails]
+      def parse(status:, body:)
+        return build(status: status, raw: body) unless body.is_a?(Hash)
+
+        if body["exception"].is_a?(Hash)
+          legacy_exception(status, body)
+        elsif body["status"].is_a?(Hash)
+          legacy_status(status, body)
+        else
+          problem_json(status, body)
+        end
+      end
+
+      private
+
+      def build(**attrs) = new(**DEFAULTS, **attrs)
+
+      # The current `application/problem+json` shape.
+      def problem_json(status, body)
+        build(
+          status: body["status"] || status,
+          title: body["title"],
+          detail: body["detail"],
+          instance: body["instance"],
+          timestamp: body["timestamp"],
+          trace_id: body["traceId"],
+          entries: Array(body["errors"]).filter_map { |e| entry_from_api_error(e) },
+          reason_code: body["reasonCode"],
+          security: body["security"] || {},
+          raw: body
+        )
+      end
+
+      # Deprecated `ExceptionResponse`: details nest under `exception.exceptionDetailList`.
+      def legacy_exception(status, body)
+        exception = body["exception"]
+        entries = Array(exception["exceptionDetailList"]).filter_map { |e| entry_from_exception_detail(e) }
+
+        build(
+          status: status,
+          title: exception["serviceName"],
+          detail: entries.first&.description,
+          timestamp: exception["timestamp"],
+          # The legacy envelope has no traceId; referenceNumber is its closest analogue.
+          trace_id: exception["referenceNumber"],
+          entries: entries,
+          raw: body
+        )
+      end
+
+      # Deprecated `TooManyRequestsResponse`: `status` is an object, not an integer.
+      def legacy_status(status, body)
+        inner = body["status"]
+        details = Array(inner["details"])
+        entry = Entry.new(code: inner["code"], description: inner["description"], details: details)
+
+        build(
+          status: inner["code"] || status,
+          title: inner["description"],
+          detail: details.first,
+          entries: [entry],
+          raw: body
+        )
+      end
+
+      def entry_from_api_error(entry)
+        return unless entry.is_a?(Hash)
+
+        Entry.new(
+          code: entry["code"],
+          description: entry["description"],
+          details: Array(entry["details"])
+        )
+      end
+
+      def entry_from_exception_detail(entry)
+        return unless entry.is_a?(Hash)
+
+        Entry.new(
+          code: entry["exceptionCode"],
+          description: entry["exceptionDescription"],
+          details: Array(entry["details"])
+        )
+      end
+    end
+
+    # @return [Integer, nil] the first KSeF error code, when the body carried one
+    def code = entries.first&.code
+
+    # @return [Array<String>] every detail message, across all entries
+    def details = entries.flat_map(&:details)
+
+    # A single line suitable for an exception message.
+    #
+    # @return [String]
+    def summary
+      lead = detail || title || entries.first&.description
+      parts = [lead, *details.reject { |d| d == lead }].compact
+      body = parts.empty? ? "HTTP #{status}" : parts.join(" ")
+      code ? "[#{code}] #{body}" : body
+    end
+  end
+end

data/lib/ksef/retry_policy.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ksef
+  # When the client may transparently retry a request.
+  #
+  # The governing rule from DESIGN.md §6.7 is a business one, not a technical one:
+  # **invoice submission is never auto-retried.** A duplicate invoice in KSeF is a real
+  # tax problem that the gem must not create on a user's behalf. So retries are gated on
+  # the HTTP method being idempotent, not merely on the status looking transient — a 429
+  # on a POST is surfaced as {Ksef::RateLimitedError} with `#retry_after` for the caller
+  # to act on deliberately.
+  RetryPolicy = Data.define(
+    :max_attempts,
+    :base_interval,
+    :max_interval,
+    :max_retry_after,
+    :backoff_factor,
+    :retry_statuses,
+    :respect_retry_after
+  )
+
+  # Behaviour for {Ksef::RetryPolicy}.
+  class RetryPolicy
+    # Methods with no side effects, so replaying them is safe.
+    IDEMPOTENT_METHODS = %i[get head].freeze
+
+    class << self
+      def default
+        new(
+          max_attempts: 3,
+          base_interval: 1.0,
+          max_interval: 30.0,
+          max_retry_after: 60.0,
+          backoff_factor: 2.0,
+          retry_statuses: [429, 500, 502, 503, 504].freeze,
+          respect_retry_after: true
+        )
+      end
+
+      # Disable retries entirely.
+      def none
+        default.with(max_attempts: 1)
+      end
+    end
+
+    # @param method [Symbol] the HTTP verb, lowercase
+    # @param status [Integer, nil] the response status, or nil for a transport failure
+    # @param attempt [Integer] 1-based
+    # @param retry_after [Integer, Float, nil] seconds, from the `Retry-After` header
+    def retryable?(method:, status:, attempt: 1, retry_after: nil)
+      return false if attempt >= max_attempts
+      return false unless IDEMPOTENT_METHODS.include?(method.to_s.downcase.to_sym)
+      # Waiting less than the server demanded provokes a longer block, so if we are not
+      # prepared to wait the full period we must not retry at all.
+      return false if respect_retry_after && retry_after && retry_after.to_f > max_retry_after
+      return true if status.nil? # connection reset / timeout on an idempotent request
+
+      retry_statuses.include?(status)
+    end
+
+    # Seconds to wait before the next attempt.
+    #
+    # `Retry-After` wins over the computed backoff, and is deliberately **not** clamped to
+    # `max_interval`: on 429 the block period is dynamic and lengthens with repeat
+    # offences, so retrying earlier than the server asked makes things strictly worse
+    # (docs/REFERENCE.md §6). `max_retry_after` bounds this instead, by declining the
+    # retry outright in {#retryable?}.
+    #
+    # @param attempt [Integer] 1-based
+    # @param retry_after [Integer, Float, nil] seconds, from the `Retry-After` header
+    def interval_for(attempt:, retry_after: nil)
+      return retry_after.to_f if respect_retry_after && retry_after
+
+      [base_interval * (backoff_factor**(attempt - 1)), max_interval].min
+    end
+  end
+end

data/lib/ksef/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ksef
+  VERSION = "0.1.0.rc1"
+end

data/lib/ksef.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+# Ruby client for KSeF 2.0, the Polish National e-Invoice System.
+#
+# Two decoupled subsystems live under this namespace (DESIGN.md §5):
+#   - {Ksef::Client} and friends — transport: auth, crypto, sessions, invoices.
+#   - {Ksef::FA3}                — the FA(3) invoice builder, usable with no HTTP at all.
+module Ksef
+  class << self
+    # The gem's Zeitwerk loader. Exposed for `loader.eager_load` in forking servers.
+    attr_reader :loader
+  end
+
+  @loader = Zeitwerk::Loader.new.tap do |loader|
+    loader.push_dir(__dir__)
+    # `ksef_client.rb` is the gem entry point, not a constant definition (DESIGN.md §5.3).
+    loader.ignore("#{__dir__}/ksef_client.rb")
+    # `errors.rb` defines the whole hierarchy and no `Ksef::Errors`, so it cannot follow
+    # Zeitwerk's file-to-constant rule. It is tiny and always needed — load it eagerly.
+    loader.ignore("#{__dir__}/ksef/errors.rb")
+    loader.inflector.inflect(
+      "fa3" => "FA3",
+      "http" => "HTTP",
+      "version" => "VERSION"
+    )
+    loader.setup
+  end
+end
+
+require_relative "ksef/errors"

data/lib/ksef_client.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The gem is named `ksef_client`; the namespace is `Ksef`. See DESIGN.md §5.3.
+# This file exists so `require "ksef_client"` works; all setup lives in `ksef.rb`.
+require_relative "ksef"

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: ksef_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc1
+platform: ruby
+authors:
+- Tibor Molnár
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |
+  A Ruby client for KSeF 2.0, Poland's mandatory national e-invoicing system.
+  Covers the REST transport layer (KSeF-token authentication, payload encryption,
+  interactive sessions, invoice submission, status polling and UPO retrieval) and
+  ships a standalone FA(3) invoice builder with XSD-backed validation. The builder
+  has no HTTP dependency and can be used on its own.
+email:
+- tibor@timcraft.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- docs/REFERENCE.md
+- docs/errors.md
+- lib/ksef.rb
+- lib/ksef/configuration.rb
+- lib/ksef/environments.rb
+- lib/ksef/errors.rb
+- lib/ksef/fa3/schema/LICENSE.upstream.txt
+- lib/ksef/fa3/schema/bazowe/ElementarneTypyDanych_v10-0E.xsd
+- lib/ksef/fa3/schema/bazowe/KodyKrajow_v10-0E.xsd
+- lib/ksef/fa3/schema/bazowe/StrukturyDanych_v10-0E.xsd
+- lib/ksef/fa3/schema/schemat_FA(3)_v1-0E.xsd
+- lib/ksef/http/connection.rb
+- lib/ksef/http/error_handler.rb
+- lib/ksef/http/system_warning.rb
+- lib/ksef/problem_details.rb
+- lib/ksef/retry_policy.rb
+- lib/ksef/version.rb
+- lib/ksef_client.rb
+homepage: https://github.com/tibortc/ksef_client
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/tibortc/ksef_client
+  changelog_uri: https://github.com/tibortc/ksef_client/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tibortc/ksef_client/issues
+  documentation_uri: https://rubydoc.info/gems/ksef_client/0.1.0.rc1
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Ruby client for KSeF 2.0 (Polish National e-Invoice System) with an FA(3)
+  invoice builder
+test_files: []