ksef-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eaa5f61dd0f2d3e8f852cb504016268c73b798da5fe1e896a821115ea01fd2a5
+  data.tar.gz: 23df18df8297859a7fdf10fe0546dc03dc49e43b7617236de86837f7d2dbbe43
+SHA512:
+  metadata.gz: a15c7b19048d06f3328c5e4cb4cbc0a85ce3d7acf4daea6af2c24ec9dc3aee09c83c391071949665fa2a9b81d6f9ac2e9a8285a9e0b582f6e8c45c1d3d764422
+  data.tar.gz: f2b4956065c21bd7ac5dde726ca129664aa04e30efea9c7ffc746cc32900b0d76d523202f63aa74c1a03105108c58b627e0d96abff8e2c54d208f3d41d90fd5b

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-05-18
+
+### Added
+- `Ksef.configure` / `Ksef::Configuration` for environment selection
+  (`:test`, `:demo`, `:production`) and request defaults.
+- `Ksef::Credentials::Token` wrapping the long-lived KSeF integration token.
+- `Ksef::Client` as the main entry point.
+- `Ksef::Sessions` implementing the interactive-session lifecycle —
+  `/auth/challenge` → RSA-OAEP/SHA-256 token encryption → `/auth/ksef-token`
+  → status polling → `/auth/token/redeem` → `DELETE /auth/sessions/current`.
+  Public API: `#with_interactive`, `#open`, `#terminate`.
+- `Ksef::Invoices` for inbound retrieval — `#query` (metadata) and
+  `#fetch_xml` (raw FA(3) XML).
+- `Ksef::InvoiceHeader` value object exposing the business-meaningful slice
+  of the `InvoiceMetadata` payload.
+- Typed errors: `Ksef::AuthError`, `Ksef::NotFoundError`,
+  `Ksef::RateLimitError` (with `retry_after`), `Ksef::ServerError`,
+  `Ksef::ClientError`, `Ksef::ConfigurationError`, plus a base `Ksef::Error`.
+- Stubs (`NotImplementedError`) for `Ksef::Credentials::Certificate`,
+  `Ksef::Invoices#fetch_visualisation`, `Ksef::Invoices#fetch_upo`.
+- RSpec suite (63 examples, ~99% line coverage) backed by WebMock plus a
+  hand-crafted VCR cassette synthesised from the OpenAPI 3.0.4 spec and the
+  CIRFMF reference clients. Re-recording against the live sandbox is gated
+  by `KSEF_RECORD=true` and a `KSEF_TOKEN`.
+
+[0.1.0]: https://github.com/skycocker/ksef-rb/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Siwek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# ksef-rb
+
+Ruby client for the Polish [KSeF 2.0](https://ksef.podatki.gov.pl/) (Krajowy
+System e-Faktur) National e-Invoicing System.
+
+Targets the FA(3) schema (mandatory since February 2026). Built against the
+official OpenAPI spec at `https://api-test.ksef.mf.gov.pl/docs/v2/openapi.json`
+and the [CIRFMF reference clients](https://github.com/CIRFMF) for C# and Java.
+
+## Status
+
+Pre-1.0. The public API is small on purpose and stable across the v0.1 line,
+but additions are expected as more KSeF features land.
+
+## Installation
+
+```ruby
+gem "ksef-rb", require: "ksef"
+```
+
+## Quick start
+
+```ruby
+require "ksef"
+
+Ksef.configure do |c|
+  c.environment = :test          # :test, :demo, or :production
+  c.user_agent  = "MyApp / ksef-rb #{Ksef::VERSION}"
+end
+
+client = Ksef::Client.new(
+  nip:         "1234567890",
+  credentials: Ksef::Credentials::Token.new(ENV.fetch("KSEF_TOKEN"))
+)
+
+client.sessions.with_interactive do |_session|
+  headers = client.invoices.query(
+    subject_type: :recipient,
+    date_from:    Time.now.utc - (7 * 24 * 3600),
+    date_to:      Time.now.utc
+  )
+
+  headers.each do |h|
+    puts "#{h.ksef_reference_number}  #{h.issuer_nip}  #{h.gross_amount} #{h.currency}"
+  end
+
+  xml = client.invoices.fetch_xml(headers.first.ksef_reference_number)
+  File.write("invoice.xml", xml)
+end
+```
+
+`Ksef::InvoiceHeader` exposes (among others):
+`ksef_reference_number`, `invoice_number`, `issuer_nip`, `issuer_name`,
+`recipient_nip`, `recipient_name`, `issued_on`, `gross_amount`, `net_amount`,
+`vat_amount`, `currency`, `invoicing_mode`, `invoice_type`, `form_code`,
+`form_schema_version`, `permanently_stored_at`, `has_attachment?`,
+`self_invoicing?`, and the original payload via `raw`.
+
+## Authentication
+
+v0.1 ships with token-based auth using the long-lived integration tokens minted
+in the KSeF portal after a Profil Zaufany / qualified-seal login.
+
+The full handshake — `/auth/challenge`, `/auth/ksef-token`, status polling at
+`/auth/{ref}`, and `/auth/token/redeem` — is performed automatically by
+`Ksef::Sessions#with_interactive`. The integration token is encrypted with
+RSA-OAEP (SHA-256) using the public key returned by
+`/security/public-key-certificates`.
+
+`with_interactive` always tears the session down by calling
+`DELETE /auth/sessions/current`, even when the block raises.
+
+## Errors
+
+All KSeF-specific errors inherit from `Ksef::Error`:
+
+| Class                  | When                                         |
+|------------------------|----------------------------------------------|
+| `Ksef::AuthError`      | 401, 403, or auth-status failure (`code: 450`, etc.) |
+| `Ksef::NotFoundError`  | 404                                          |
+| `Ksef::RateLimitError` | 429 (exposes `#retry_after` in seconds when sent) |
+| `Ksef::ServerError`    | 5xx                                          |
+| `Ksef::ClientError`    | other 4xx                                    |
+| `Ksef::ConfigurationError` | bad config                               |
+
+Every error captures `status`, `body`, and the KSeF-supplied `code`.
+
+## What's not in v0.1.0
+
+| Feature                                 | Status |
+|-----------------------------------------|--------|
+| Token-based auth                        | shipped |
+| Interactive sessions                    | shipped |
+| Inbound invoice metadata query          | shipped |
+| Inbound invoice XML fetch               | shipped |
+| Inbound invoice PDF visualisation       | **stubbed** — KSeF 2.0 has no server-side PDF endpoint; render client-side from the XML using the official XSLT (`wizualizacja-faktury_v3-0.xsl`) |
+| Certificate-based auth (qualified seal) | **stubbed** (`Ksef::Credentials::Certificate`) |
+| Batch sessions                          | not yet  |
+| Outbound invoice issuance               | not yet  |
+| UPO download                            | **stubbed** (`Ksef::Invoices#fetch_upo`) |
+| Offline / QR-code modes                 | not yet  |
+
+`NotImplementedError` is raised from the stubs.
+
+## Configuration reference
+
+```ruby
+Ksef.configure do |c|
+  c.environment  = :test        # :test, :demo, :production
+  c.user_agent   = "..."        # appended to every request
+  c.timeout      = 30           # seconds
+  c.open_timeout = 10           # seconds
+  c.api_version  = "v2"         # path segment; defaults to v2
+  c.base_url     = nil          # override entirely (useful for tests)
+  c.logger       = Logger.new($stdout)  # wires Faraday's logger middleware
+end
+```
+
+`Ksef::Client.new(configuration:)` accepts a per-client `Configuration`,
+which is the duplicated global configuration by default.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+The suite uses VCR (opt-in, via the `:vcr` metadata tag) and WebMock. Live
+re-recording against the sandbox is gated behind `KSEF_RECORD=true` and a
+real token in `KSEF_TOKEN`.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/ksef/client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Main entry point for the KSeF API.
+  #
+  # @example
+  #   client = Ksef::Client.new(
+  #     nip: "1234567890",
+  #     credentials: Ksef::Credentials::Token.new(ENV.fetch("KSEF_TOKEN"))
+  #   )
+  #
+  #   client.sessions.with_interactive do |session|
+  #     headers = client.invoices.query(
+  #       subject_type: :recipient,
+  #       date_from: Time.now.utc - (7 * 24 * 3600),
+  #       date_to:   Time.now.utc
+  #     )
+  #     xml = client.invoices.fetch_xml(headers.first.ksef_reference_number)
+  #   end
+  class Client
+    attr_reader :nip, :credentials, :configuration
+    attr_accessor :current_session
+
+    def initialize(nip:, credentials:, configuration: nil)
+      raise ConfigurationError, "nip cannot be blank" if nip.nil? || nip.to_s.empty?
+
+      @nip             = nip.to_s
+      @credentials     = credentials
+      @configuration   = configuration || Ksef.configuration.dup
+      @current_session = nil
+    end
+
+    # Lazily-built HTTP connection. Public so the resource classes can share
+    # it; not part of the supported public surface — treat as internal.
+    def connection
+      @connection ||= Internal::Connection.new(@configuration)
+    end
+
+    def sessions
+      @sessions ||= Sessions.new(self)
+    end
+
+    def invoices
+      @invoices ||= Invoices.new(self)
+    end
+  end
+end

data/lib/ksef/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Global gem configuration. Set via `Ksef.configure { |c| ... }`.
+  #
+  # Mutable defaults are exposed so callers can build a per-client
+  # `Ksef::Client` override without touching the global state.
+  class Configuration
+    # Maps environment symbol → base URL.
+    ENVIRONMENTS = {
+      test:       "https://api-test.ksef.mf.gov.pl",
+      demo:       "https://api-demo.ksef.mf.gov.pl",
+      production: "https://api.ksef.mf.gov.pl"
+    }.freeze
+
+    DEFAULT_API_VERSION = "v2"
+
+    attr_accessor :environment, :user_agent, :timeout, :open_timeout,
+                  :api_version, :base_url, :logger
+
+    def initialize
+      @environment  = :test
+      @user_agent   = "ksef-rb/#{Ksef::VERSION}"
+      @timeout      = 30
+      @open_timeout = 10
+      @api_version  = DEFAULT_API_VERSION
+      @base_url     = nil
+      @logger       = nil
+    end
+
+    # Returns the effective base URL for the configured environment, including
+    # the `/v2` (or whatever) API version path.
+    def resolved_base_url
+      root = @base_url || ENVIRONMENTS.fetch(@environment) do
+        raise ConfigurationError, "Unknown KSeF environment: #{@environment.inspect}"
+      end
+      "#{root.chomp("/")}/#{@api_version}"
+    end
+  end
+end

data/lib/ksef/credentials/certificate.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Credentials
+    # Certificate-based credential (qualified seal / XAdES signature flow).
+    #
+    # @note Stub for v0.1.0 — interactive sessions backed by a qualified seal
+    #   require XAdES-signed XML which is out of scope for this release. The
+    #   class is here so the public API shape doesn't shift when we land it.
+    class Certificate
+      def initialize(*)
+        raise NotImplementedError,
+              "Certificate-based authentication is not implemented in ksef-rb v#{Ksef::VERSION}. " \
+              "Use Ksef::Credentials::Token for now; tracked for a future release."
+      end
+    end
+  end
+end

data/lib/ksef/credentials/token.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Credentials
+    # A long-lived KSeF integration token, minted in the KSeF portal after
+    # Profil Zaufany / qualified-seal login.
+    #
+    # The raw token value is treated as opaque; it is encrypted with the KSeF
+    # public RSA key during the {Ksef::Sessions} init flow.
+    class Token
+      attr_reader :value
+
+      def initialize(value)
+        raise ConfigurationError, "Token value cannot be blank" if value.nil? || value.to_s.empty?
+
+        @value = value.to_s
+      end
+
+      def type
+        :token
+      end
+
+      def to_s
+        "#<Ksef::Credentials::Token value=[REDACTED]>"
+      end
+      alias inspect to_s
+    end
+  end
+end

data/lib/ksef/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Base class for all KSeF gem errors.
+  class Error < StandardError
+    # The underlying HTTP status code, when applicable.
+    attr_reader :status
+
+    # The parsed error body returned by the API, when applicable.
+    attr_reader :body
+
+    # The KSeF-specific exception code, when surfaced in the body.
+    attr_reader :code
+
+    def initialize(message = nil, status: nil, body: nil, code: nil)
+      super(message)
+      @status = status
+      @body = body
+      @code = code
+    end
+  end
+
+  # Raised when the API rejects authentication (401 / 403 or auth-status failure).
+  class AuthError < Error; end
+
+  # Raised when an upstream resource cannot be located (404 / invoice-not-found).
+  class NotFoundError < Error; end
+
+  # Raised on 4xx responses we don't otherwise classify.
+  class ClientError < Error; end
+
+  # Raised when the API returns 5xx.
+  class ServerError < Error; end
+
+  # Raised when the API returns 429. `retry_after` is in seconds when known.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, status: nil, body: nil, code: nil, retry_after: nil)
+      super(message, status: status, body: body, code: code)
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when configuration is missing or invalid.
+  class ConfigurationError < Error; end
+end

data/lib/ksef/internal/connection.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module Ksef
+  module Internal
+    # Thin Faraday wrapper around the KSeF HTTP API.
+    #
+    # All response-shape parsing and error classification lives here so the
+    # higher-level resource classes can treat the API as a typed boundary.
+    class Connection
+      RETRY_OPTIONS = {
+        max:                 2,
+        interval:            0.4,
+        interval_randomness: 0.2,
+        backoff_factor:      2,
+        retry_statuses:      [502, 503, 504],
+        methods:             %i[get head post delete put patch],
+        exceptions:          [
+          Errno::ETIMEDOUT,
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed
+        ]
+      }.freeze
+
+      JSON_CONTENT_TYPE = "application/json"
+
+      attr_reader :configuration
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      # Issues an HTTP request and returns a `Faraday::Response`.
+      #
+      # @param method [Symbol] :get, :post, :delete, etc.
+      # @param path   [String] path relative to `configuration.resolved_base_url`
+      # @param body         [Object, nil] hash → JSON, String → raw body
+      # @param headers      [Hash]
+      # @param query        [Hash]
+      # @param bearer_token [String, nil] sent as `Authorization: Bearer ...`
+      # @return [Faraday::Response]
+      def request(method, path, body: nil, headers: {}, query: {}, bearer_token: nil)
+        response = http.run_request(method, expand_path(path), nil,
+                                    build_headers(headers, bearer_token)) do |req|
+          req.params.update(query) unless query.empty?
+          assign_body(req, body)
+        end
+        check!(response)
+        response
+      end
+
+      # Parses a JSON response body, returning `{}` on empty bodies.
+      def self.parse_json(response)
+        return {} if response.body.nil? || response.body.to_s.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      private
+
+      # Resolves API-relative paths against the configured base URL. Faraday
+      # treats `/auth/...` as absolute and would strip the `/v2` prefix; we
+      # always pass a fully-qualified URL to avoid that pitfall.
+      def expand_path(path)
+        "#{configuration.resolved_base_url}#{path.start_with?("/") ? path : "/#{path}"}"
+      end
+
+      def http
+        @http ||= Faraday.new do |conn|
+          conn.request :retry, RETRY_OPTIONS
+          conn.options.timeout      = configuration.timeout
+          conn.options.open_timeout = configuration.open_timeout
+          conn.headers["User-Agent"] = configuration.user_agent
+          conn.headers["Accept"]     = JSON_CONTENT_TYPE
+          if configuration.logger
+            conn.response :logger, configuration.logger, headers: false, bodies: false
+          end
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def build_headers(extra, bearer_token)
+        headers = {}
+        headers["Authorization"] = "Bearer #{bearer_token}" if bearer_token
+        headers.merge(extra)
+      end
+
+      def assign_body(req, body)
+        case body
+        when nil
+          # no body
+        when String
+          req.body = body
+        else
+          req.headers["Content-Type"] ||= JSON_CONTENT_TYPE
+          req.body = JSON.dump(body)
+        end
+      end
+
+      def check!(response)
+        return if response.status.between?(200, 299)
+
+        parsed = Connection.parse_json(response)
+        code, message = extract_error_metadata(parsed)
+        klass = error_class_for(response.status)
+
+        raise build_error(klass, response, message, code, parsed)
+      end
+
+      def error_class_for(status)
+        case status
+        when 401, 403 then AuthError
+        when 404      then NotFoundError
+        when 429      then RateLimitError
+        when 400..499 then ClientError
+        when 500..599 then ServerError
+        else Error
+        end
+      end
+
+      def build_error(klass, response, message, code, body)
+        text = message || "KSeF API error (HTTP #{response.status})"
+        if klass == RateLimitError
+          retry_after = parse_retry_after(response.headers["Retry-After"])
+          klass.new(text, status: response.status, body: body, code: code, retry_after: retry_after)
+        else
+          klass.new(text, status: response.status, body: body, code: code)
+        end
+      end
+
+      def parse_retry_after(value)
+        return nil if value.nil?
+
+        Integer(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Handles both the legacy `ExceptionResponse` shape and the newer
+      # RFC 7807 `application/problem+json` payload.
+      def extract_error_metadata(parsed)
+        return [nil, nil] unless parsed.is_a?(Hash)
+
+        if parsed["exception"].is_a?(Hash)
+          details = Array(parsed["exception"]["exceptionDetailList"]).first || {}
+          [details["exceptionCode"], details["exceptionDescription"]]
+        elsif parsed["title"] || parsed["detail"]
+          [parsed["status"], parsed["detail"] || parsed["title"]]
+        else
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/ksef/internal/token_encryptor.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Ksef
+  module Internal
+    # Encrypts a KSeF integration token for the `/auth/ksef-token` endpoint.
+    #
+    # Per the KSeF 2.0 docs:
+    #   - The payload is `"{token}|{timestampMs}"`, where `timestampMs` comes
+    #     from the `/auth/challenge` response.
+    #   - Encryption is RSA-OAEP with SHA-256 (and MGF1-SHA-256).
+    #   - The ciphertext is Base64-encoded for transport.
+    #
+    # The PEM-encoded RSA public key is supplied by the caller (typically
+    # fetched from `/security/public-key-certificates`).
+    module TokenEncryptor
+      module_function
+
+      # @param token         [String] raw KSeF integration token
+      # @param timestamp_ms  [Integer] timestamp from the challenge response
+      # @param public_key_pem [String] PEM-encoded RSA public key
+      # @return [String] Base64-encoded ciphertext
+      def encrypt(token:, timestamp_ms:, public_key_pem:)
+        plaintext = "#{token}|#{timestamp_ms}"
+        key = OpenSSL::PKey::RSA.new(public_key_pem)
+        ciphertext = key.encrypt(
+          plaintext,
+          rsa_padding_mode: "oaep",
+          rsa_oaep_md:      "sha256",
+          rsa_mgf1_md:      "sha256"
+        )
+        Base64.strict_encode64(ciphertext)
+      end
+
+      # Convenience wrapper that handles raw DER-encoded (base64) keys returned
+      # by the public-key endpoint, falling back to PEM if the input already
+      # contains BEGIN markers.
+      def normalize_public_key(raw)
+        return raw if raw.to_s.include?("BEGIN")
+
+        der = Base64.decode64(raw.to_s)
+        OpenSSL::PKey::RSA.new(der).to_pem
+      end
+    end
+  end
+end

data/lib/ksef/invoice_header.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Ksef
+  # Lightweight value object describing an invoice as returned by
+  # `POST /invoices/query/metadata`. Built from a single element of the
+  # `invoices` array in the API response.
+  #
+  # The object intentionally exposes a small, business-meaningful slice of the
+  # full payload. The raw hash is preserved on {#raw} for advanced callers.
+  class InvoiceHeader
+    attr_reader :ksef_reference_number,
+                :invoice_number,
+                :issuer_nip, :issuer_name,
+                :recipient_nip, :recipient_name,
+                :issued_on, :acquired_at, :permanently_stored_at,
+                :net_amount, :gross_amount, :vat_amount, :currency,
+                :invoicing_mode, :invoice_type,
+                :form_code, :form_schema_version,
+                :self_invoicing, :has_attachment,
+                :invoice_hash, :raw
+
+      def initialize(raw)
+        @raw = raw
+        @ksef_reference_number = raw["ksefNumber"]
+        @invoice_number        = raw["invoiceNumber"]
+        @issuer_nip            = raw.dig("seller", "nip")
+        @issuer_name           = raw.dig("seller", "name")
+        @recipient_nip         = raw.dig("buyer", "identifier", "value")
+        @recipient_name        = raw.dig("buyer", "name")
+        @issued_on             = parse_date(raw["issueDate"])
+        @acquired_at           = parse_time(raw["acquisitionDate"])
+        @permanently_stored_at = parse_time(raw["permanentStorageDate"])
+        @net_amount            = raw["netAmount"]
+        @gross_amount          = raw["grossAmount"]
+        @vat_amount            = raw["vatAmount"]
+        @currency              = raw["currency"]
+        @invoicing_mode        = raw["invoicingMode"]
+        @invoice_type          = raw["invoiceType"]
+        @form_code             = raw.dig("formCode", "value")
+        @form_schema_version   = raw.dig("formCode", "schemaVersion")
+        @self_invoicing        = raw["isSelfInvoicing"]
+        @has_attachment        = raw["hasAttachment"]
+        @invoice_hash          = raw["invoiceHash"]
+      end
+
+    def self_invoicing?
+      @self_invoicing == true
+    end
+
+    def has_attachment?
+      @has_attachment == true
+    end
+
+    private
+
+    def parse_date(value)
+      return nil if value.nil? || value.empty?
+
+      Date.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_time(value)
+      return nil if value.nil? || value.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/ksef/invoices.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Inbound-invoice retrieval. All operations require an open session
+  # (see {Ksef::Sessions#with_interactive}).
+  class Invoices
+    SUBJECT_TYPE_MAP = {
+      issuer:             "Subject1",
+      seller:             "Subject1",
+      recipient:          "Subject2",
+      buyer:              "Subject2",
+      third:              "Subject3",
+      subject_authorized: "SubjectAuthorized"
+    }.freeze
+
+    DATE_TYPE_MAP = {
+      issue:             "Issue",
+      invoicing:         "Invoicing",
+      permanent_storage: "PermanentStorage"
+    }.freeze
+
+    DEFAULT_PAGE_SIZE = 100
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Queries invoice metadata.
+    #
+    # @param subject_type [Symbol] :recipient (default), :issuer, :third, :subject_authorized
+    # @param date_from    [Time, DateTime, String] start of date range (inclusive)
+    # @param date_to      [Time, DateTime, String, nil] end of date range, defaults to "now"
+    # @param date_type    [Symbol] :permanent_storage (default), :invoicing, :issue
+    # @param page_size    [Integer] 10..250
+    # @param page_offset  [Integer]
+    # @param sort_order   [String]  "Asc" (default) or "Desc"
+    # @param extra_filters [Hash]   additional InvoiceQueryFilters fields, passed through verbatim
+    # @return [Array<Ksef::InvoiceHeader>]
+    def query(subject_type: :recipient, date_from:, date_to: nil, date_type: :permanent_storage,
+              page_size: DEFAULT_PAGE_SIZE, page_offset: 0, sort_order: "Asc", extra_filters: {})
+      filters = {
+        "subjectType" => translate_subject(subject_type),
+        "dateRange"   => {
+          "dateType" => translate_date_type(date_type),
+          "from"     => to_iso8601(date_from)
+        }
+      }
+      filters["dateRange"]["to"] = to_iso8601(date_to) if date_to
+      filters.merge!(stringify_keys(extra_filters))
+
+      response = require_session.connection.request(
+        :post,
+        "/invoices/query/metadata",
+        body:         filters,
+        query:        { "pageOffset" => page_offset, "pageSize" => page_size, "sortOrder" => sort_order },
+        bearer_token: current_access_token
+      )
+      body = Internal::Connection.parse_json(response)
+      Array(body["invoices"]).map { |raw| InvoiceHeader.new(raw) }
+    end
+
+    # Fetches the raw FA(3) XML for the invoice identified by `ksef_reference_number`.
+    # @return [String] XML document bytes
+    def fetch_xml(ksef_reference_number)
+      raise ArgumentError, "ksef_reference_number cannot be blank" if blank?(ksef_reference_number)
+
+      response = require_session.connection.request(
+        :get,
+        "/invoices/ksef/#{ksef_reference_number}",
+        headers:      { "Accept" => "application/xml" },
+        bearer_token: current_access_token
+      )
+      response.body.to_s
+    end
+
+    # @note Not implemented in v0.1.0.
+    #
+    # KSeF 2.0 does not currently expose a server-rendered PDF/HTML
+    # visualisation of an invoice through the public API. The visualisation
+    # is produced client-side from the FA(3) XML using the official XSLT
+    # (`wizualizacja-faktury_v3-0.xsl`) shipped with the ksef-docs repo, or
+    # by combining the XML with a PDF rendering library (e.g. WeasyPrint,
+    # Puppeteer + the official HTML preview).
+    #
+    # @param _ksef_reference_number [String]
+    def fetch_visualisation(_ksef_reference_number)
+      raise NotImplementedError, <<~MSG
+        KSeF 2.0 has no public endpoint that returns a PDF visualisation of an
+        invoice. Generate it client-side from the XML retrieved via #fetch_xml
+        using the official XSLT (wizualizacja-faktury_v3-0.xsl) and your
+        preferred renderer. Tracked for a future ksef-rb release.
+      MSG
+    end
+
+    # @note Not implemented in v0.1.0.
+    #
+    # UPO (Urzędowe Poświadczenie Odbioru) downloads are scoped to the
+    # *sender* sessions that produced them (see `GET /sessions/{ref}/upo/...`).
+    # Recipient-side UPO retrieval is not available in v0.1.0; outbound
+    # issuance is also stubbed.
+    def fetch_upo(_ksef_reference_number)
+      raise NotImplementedError,
+            "UPO download is not implemented in ksef-rb v#{Ksef::VERSION}. " \
+            "Tracked alongside outbound invoice issuance."
+    end
+
+    private
+
+    def translate_subject(symbol)
+      SUBJECT_TYPE_MAP.fetch(symbol) do
+        raise ArgumentError,
+              "Unknown subject_type #{symbol.inspect}. " \
+              "Expected one of: #{SUBJECT_TYPE_MAP.keys.inspect}"
+      end
+    end
+
+    def translate_date_type(symbol)
+      DATE_TYPE_MAP.fetch(symbol) do
+        raise ArgumentError,
+              "Unknown date_type #{symbol.inspect}. " \
+              "Expected one of: #{DATE_TYPE_MAP.keys.inspect}"
+      end
+    end
+
+    def to_iso8601(value)
+      case value
+      when nil    then nil
+      when String then value
+      when Date   then value.iso8601
+      else value.utc.iso8601
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+
+    def require_session
+      session = @client.current_session
+      raise AuthError, "No active KSeF session. Call client.sessions.with_interactive { ... } first." if session.nil?
+      raise AuthError, "Session #{session.reference_number} has been terminated." if session.terminated?
+
+      @client
+    end
+
+    def current_access_token
+      @client.current_session.access_token
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.empty?
+    end
+  end
+end

data/lib/ksef/session.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Ksef
+  # An open authenticated session against the KSeF API.
+  #
+  # Holds the access/refresh tokens minted by `/auth/token/redeem` together
+  # with the authentication operation's reference number. Instances are
+  # produced by {Ksef::Sessions#open} (or {#with_interactive}) and consumed
+  # by resource classes through {Ksef::Client#current_session}.
+  class Session
+    attr_reader :reference_number,
+                :access_token, :access_token_valid_until,
+                :refresh_token, :refresh_token_valid_until
+
+    def initialize(reference_number:, access_token:, refresh_token:,
+                   access_token_valid_until: nil, refresh_token_valid_until: nil)
+      @reference_number          = reference_number
+      @access_token              = access_token
+      @refresh_token             = refresh_token
+      @access_token_valid_until  = access_token_valid_until
+      @refresh_token_valid_until = refresh_token_valid_until
+      @terminated                = false
+    end
+
+    def terminated?
+      @terminated
+    end
+
+    # Marks the session as closed locally. Network teardown is performed by
+    # {Ksef::Sessions#terminate}.
+    def mark_terminated!
+      @terminated = true
+    end
+
+    def to_s
+      "#<Ksef::Session reference_number=#{@reference_number.inspect} " \
+        "terminated=#{@terminated}>"
+    end
+    alias inspect to_s
+  end
+end

data/lib/ksef/sessions.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Manages the KSeF interactive session lifecycle:
+  #
+  #   1. `POST /auth/challenge`        → challenge + timestamp
+  #   2. encrypt the integration token with the KSeF public RSA key
+  #   3. `POST /auth/ksef-token`       → authentication operation token
+  #   4. poll `GET  /auth/{ref}`       → wait for status = success
+  #   5. `POST /auth/token/redeem`     → access + refresh tokens
+  #   6. on close: `DELETE /auth/sessions/current`
+  #
+  # The most common entry point is {#with_interactive}, which sets up the
+  # session, yields it to the caller's block, and tears it down on exit.
+  class Sessions
+    AUTH_SUCCESS_STATUS = 200
+    AUTH_PENDING_STATUS = 100
+    DEFAULT_POLL_INTERVAL = 1.0
+    DEFAULT_POLL_TIMEOUT  = 60
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Opens a session, yields it, and ensures it is terminated.
+    #
+    # @yield  [Ksef::Session]
+    # @return whatever the block returns
+    def with_interactive(**opts)
+      session = open(**opts)
+      @client.current_session = session
+      begin
+        yield session
+      ensure
+        terminate(session) unless session.terminated?
+        @client.current_session = nil
+      end
+    end
+
+    # Acquires a new authenticated session. Callers can then attach it via
+    # {Ksef::Client#current_session=} if they prefer manual management.
+    #
+    # @param poll_interval [Float]   seconds between status polls
+    # @param poll_timeout  [Integer] total seconds to wait for auth completion
+    # @return [Ksef::Session]
+    def open(poll_interval: DEFAULT_POLL_INTERVAL, poll_timeout: DEFAULT_POLL_TIMEOUT)
+      credentials = @client.credentials
+      case credentials
+      when Credentials::Token
+        open_with_token(credentials, poll_interval: poll_interval, poll_timeout: poll_timeout)
+      else
+        raise NotImplementedError,
+              "Only Ksef::Credentials::Token is supported in v#{Ksef::VERSION}"
+      end
+    end
+
+    # Closes the session by calling `DELETE /auth/sessions/current`.
+    def terminate(session)
+      return if session.terminated?
+
+      @client.connection.request(
+        :delete,
+        "/auth/sessions/current",
+        bearer_token: session.access_token
+      )
+      session.mark_terminated!
+      session
+    end
+
+    # Fetches the freshest public-key certificate suitable for token encryption.
+    # Cached for the lifetime of the Sessions instance.
+    def public_key_for_token_encryption
+      @public_key_for_token_encryption ||= fetch_public_key
+    end
+
+    private
+
+    def open_with_token(token_credentials, poll_interval:, poll_timeout:)
+      challenge_data = fetch_challenge
+      key_info       = public_key_for_token_encryption
+
+      encrypted = Internal::TokenEncryptor.encrypt(
+        token:          token_credentials.value,
+        timestamp_ms:   challenge_data.fetch("timestampMs"),
+        public_key_pem: key_info[:pem]
+      )
+
+      init_response = init_with_token(
+        challenge:       challenge_data.fetch("challenge"),
+        encrypted_token: encrypted,
+        public_key_id:   key_info[:id]
+      )
+
+      reference_number     = init_response.fetch("referenceNumber")
+      authentication_token = init_response.fetch("authenticationToken").fetch("token")
+
+      wait_for_authentication(reference_number, authentication_token,
+                              poll_interval: poll_interval, poll_timeout: poll_timeout)
+
+      redeem_tokens(reference_number, authentication_token)
+    end
+
+    def fetch_challenge
+      response = @client.connection.request(:post, "/auth/challenge")
+      Internal::Connection.parse_json(response)
+    end
+
+    def init_with_token(challenge:, encrypted_token:, public_key_id:)
+      body = {
+        "challenge"         => challenge,
+        "contextIdentifier" => { "type" => "Nip", "value" => @client.nip },
+        "encryptedToken"    => encrypted_token
+      }
+      body["publicKeyId"] = public_key_id if public_key_id
+
+      response = @client.connection.request(:post, "/auth/ksef-token", body: body)
+      Internal::Connection.parse_json(response)
+    end
+
+    def wait_for_authentication(reference_number, authentication_token,
+                                poll_interval:, poll_timeout:)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + poll_timeout
+
+      loop do
+        response = @client.connection.request(
+          :get,
+          "/auth/#{reference_number}",
+          bearer_token: authentication_token
+        )
+        body   = Internal::Connection.parse_json(response)
+        status = body.dig("status", "code")
+
+        return if status == AUTH_SUCCESS_STATUS
+
+        if status && status != AUTH_PENDING_STATUS
+          raise AuthError.new(
+            "KSeF authentication failed: #{body.dig("status", "description")}",
+            status: status,
+            body:   body,
+            code:   status
+          )
+        end
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise AuthError, "Timed out waiting for KSeF authentication (ref=#{reference_number})"
+        end
+
+        sleep poll_interval
+      end
+    end
+
+    def redeem_tokens(reference_number, authentication_token)
+      response = @client.connection.request(
+        :post,
+        "/auth/token/redeem",
+        bearer_token: authentication_token
+      )
+      body = Internal::Connection.parse_json(response)
+
+      access  = body.fetch("accessToken")
+      refresh = body.fetch("refreshToken")
+
+      Session.new(
+        reference_number:          reference_number,
+        access_token:              access.fetch("token"),
+        access_token_valid_until:  access["validUntil"],
+        refresh_token:             refresh.fetch("token"),
+        refresh_token_valid_until: refresh["validUntil"]
+      )
+    end
+
+    def fetch_public_key
+      response = @client.connection.request(:get, "/security/public-key-certificates")
+      list = Internal::Connection.parse_json(response)
+      list = list["items"] if list.is_a?(Hash) && list.key?("items")
+
+      candidate = Array(list).find do |entry|
+        Array(entry["usage"]).include?("KsefTokenEncryption")
+      end || Array(list).first
+
+      raise AuthError, "No public-key certificate available for KSeF token encryption" if candidate.nil?
+
+      {
+        id:  candidate["publicKeyId"],
+        pem: Internal::TokenEncryptor.normalize_public_key(candidate["certificate"])
+      }
+    end
+  end
+end

data/lib/ksef/version.rb

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

data/lib/ksef.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "ksef/version"
+require_relative "ksef/errors"
+require_relative "ksef/configuration"
+require_relative "ksef/credentials/token"
+require_relative "ksef/credentials/certificate"
+require_relative "ksef/internal/connection"
+require_relative "ksef/internal/token_encryptor"
+require_relative "ksef/session"
+require_relative "ksef/sessions"
+require_relative "ksef/invoice_header"
+require_relative "ksef/invoices"
+require_relative "ksef/client"
+
+# Ruby client for the Polish KSeF 2.0 (Krajowy System e-Faktur) API.
+#
+# @example Global configuration
+#   Ksef.configure do |c|
+#     c.environment = :test
+#     c.user_agent  = "Pro Bau / ksef-rb #{Ksef::VERSION}"
+#   end
+module Ksef
+  class << self
+    # @return [Ksef::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the singleton {Configuration} for in-place mutation.
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    # Resets the global configuration (primarily for tests).
+    # @api private
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  # Namespace for implementation details. Anything under {Ksef::Internal} is
+  # not part of the supported public API and may change without notice.
+  module Internal; end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: ksef-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michał Siwek
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: |
+  A Ruby client for the Polish National e-Invoicing System (KSeF 2.0).
+  Targets the FA(3) schema, supports token-based authentication, interactive
+  sessions, and inbound invoice retrieval (metadata, XML, and visualisation).
+  Pure Ruby with no Rails dependency.
+email:
+- michal.siwek@shape.care
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ksef.rb
+- lib/ksef/client.rb
+- lib/ksef/configuration.rb
+- lib/ksef/credentials/certificate.rb
+- lib/ksef/credentials/token.rb
+- lib/ksef/errors.rb
+- lib/ksef/internal/connection.rb
+- lib/ksef/internal/token_encryptor.rb
+- lib/ksef/invoice_header.rb
+- lib/ksef/invoices.rb
+- lib/ksef/session.rb
+- lib/ksef/sessions.rb
+- lib/ksef/version.rb
+homepage: https://github.com/skycocker/ksef-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/skycocker/ksef-rb
+  source_code_uri: https://github.com/skycocker/ksef-rb
+  changelog_uri: https://github.com/skycocker/ksef-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/skycocker/ksef-rb/issues
+  rubygems_mfa_required: 'true'
+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.3
+specification_version: 4
+summary: Ruby client for the Polish KSeF 2.0 (Krajowy System e-Faktur) API
+test_files: []