ksef_client 0.1.0.rc1

data/lib/ksef/environments.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ksef
+  # The three public KSeF API 2.0 environments.
+  #
+  # Every base URL here was read from that environment's *own* OpenAPI document
+  # (`servers[0].url`, served at `https://<host>/docs/v2/openapi.json`) on 2026-08-21,
+  # rather than inferred by analogy. See docs/REFERENCE.md §2. Do not edit a URL without
+  # re-verifying it against that source and updating the ledger.
+  #
+  # Note the base URL already carries `/v2`; endpoint paths are appended bare. There is
+  # no `/api` segment (docs/REFERENCE.md §7.2).
+  module Environments
+    Environment = Data.define(:name, :base_url, :supports_test_data) do
+      # TEST alone exposes the `/testdata/*` helper API and `/collective-identifiers*`.
+      # Code touching those paths must be guarded on this.
+      def test_data_api? = supports_test_data
+
+      def production? = name == :prod
+    end
+
+    TEST = Environment.new(
+      name: :test,
+      base_url: "https://api-test.ksef.mf.gov.pl/v2",
+      supports_test_data: true
+    )
+
+    DEMO = Environment.new(
+      name: :demo,
+      base_url: "https://api-demo.ksef.mf.gov.pl/v2",
+      supports_test_data: false
+    )
+
+    PROD = Environment.new(
+      name: :prod,
+      base_url: "https://api.ksef.mf.gov.pl/v2",
+      supports_test_data: false
+    )
+
+    ALL = { test: TEST, demo: DEMO, prod: PROD }.freeze
+    NAMES = ALL.keys.freeze
+
+    class << self
+      # @param env [Symbol, String, Environment]
+      # @return [Environment]
+      # @raise [Ksef::ConfigurationError] on an unknown environment
+      def fetch(env)
+        return env if env.is_a?(Environment)
+
+        key = env.respond_to?(:to_sym) ? env.to_sym : nil
+        ALL.fetch(key) do
+          raise ConfigurationError,
+                "Unknown KSeF environment #{env.inspect}. Known: #{NAMES.map(&:inspect).join(", ")}. " \
+                "For a non-public deployment, pass Ksef::Environments.custom(base_url: ...)."
+        end
+      end
+
+      # Escape hatch for deployments not covered by the three published environments
+      # (DESIGN.md §6.1).
+      #
+      # @param base_url [String] must be HTTPS, and should include the `/v2` suffix
+      # @return [Environment]
+      def custom(base_url:, name: :custom, supports_test_data: false)
+        uri = begin
+          URI.parse(base_url)
+        rescue URI::InvalidURIError => e
+          raise ConfigurationError, "Invalid base_url #{base_url.inspect}: #{e.message}"
+        end
+
+        unless uri.is_a?(URI::HTTPS)
+          raise ConfigurationError,
+                "base_url must be HTTPS, got #{base_url.inspect}. TLS is not optional (DESIGN.md §4.5)."
+        end
+
+        Environment.new(
+          name: name.to_sym,
+          base_url: base_url.chomp("/"),
+          supports_test_data: supports_test_data
+        )
+      end
+    end
+  end
+end

data/lib/ksef/errors.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# The error hierarchy from DESIGN.md §6.7, extended with the 403 and 410 branches the
+# API actually returns (docs/REFERENCE.md §7.4).
+#
+# This file defines many constants and no `Ksef::Errors`, so Zeitwerk cannot manage it —
+# `lib/ksef.rb` ignores it and requires it eagerly.
+module Ksef
+  # Base class for everything this gem raises. Rescue this to catch all of it.
+  #
+  # `#problem` carries the parsed KSeF error body when the error came from an API
+  # response, and is nil for locally-raised errors.
+  class Error < StandardError
+    # @return [Ksef::ProblemDetails, nil]
+    attr_reader :problem
+
+    def initialize(message = nil, problem: nil)
+      @problem = problem
+      super(message)
+    end
+  end
+
+  # Invalid or missing client configuration. Raised locally, before any request.
+  class ConfigurationError < Error; end
+
+  # Challenge, KSeF-token, signature or JWT problems, including HTTP 401.
+  class AuthenticationError < Error; end
+
+  # Raised locally by the FA(3) validator (DESIGN.md §7.7), never by the transport layer.
+  class ValidationError < Error; end
+
+  # Any error response from the KSeF API.
+  class ApiError < Error
+    # @return [Integer, nil] HTTP status
+    def status = problem&.status
+
+    # @return [Integer, nil] the first KSeF error code, when the body carried one
+    def code = problem&.code
+
+    # @return [Array<String>] flattened detail messages
+    def details = problem&.details || []
+
+    # @return [String, nil] the Ministry's correlation id — quote this in support requests
+    def trace_id = problem&.trace_id
+
+    # @return [Object, nil] the undecoded response body
+    def raw = problem&.raw
+  end
+
+  # The invoice was rejected by KSeF on schema or business grounds.
+  class InvoiceRejectedError < ApiError; end
+
+  # A session could not be opened, used or closed.
+  class SessionError < ApiError; end
+
+  # HTTP 403. Carries a structured reason (docs/REFERENCE.md §5.3) rather than just prose.
+  class AuthorizationError < ApiError
+    # @return [String, nil] one of `missing-permissions`, `ip-not-allowed`,
+    #   `insufficient-resource-access`, `auth-method-not-allowed`,
+    #   `security-service-blocked`, `context-type-not-allowed`
+    def reason_code = problem&.reason_code
+
+    # @return [Hash] reason-dependent payload, e.g. `requiredAnyOfPermissions`
+    def security = problem&.security || {}
+  end
+
+  # HTTP 410. The resource existed but is no longer available.
+  class ResourceGoneError < ApiError; end
+
+  # HTTP 429. Retryable, but only for idempotent requests (DESIGN.md §6.7).
+  class RateLimitedError < ApiError
+    # @return [Integer, nil] seconds to wait, from the `Retry-After` header.
+    #   Authoritative — the block period is dynamic and lengthens with repeat offences
+    #   (docs/REFERENCE.md §6). Never work around a 429 by rotating IPs.
+    attr_reader :retry_after
+
+    def initialize(message = nil, problem: nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message, problem: problem)
+    end
+  end
+
+  # HTTP 5xx. Not declared anywhere in the OpenAPI contract (docs/REFERENCE.md §5.4), so
+  # the body shape is unknown and `#problem` may hold only a raw payload.
+  class ServerError < ApiError; end
+
+  # The request exceeded the configured open or read timeout.
+  class TimeoutError < Error; end
+
+  # The connection failed, TLS included.
+  class ConnectionError < Error; end
+end

data/lib/ksef/fa3/schema/LICENSE.upstream.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ministerstwo Finansów
+
+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/lib/ksef/fa3/schema/bazowe/ElementarneTypyDanych_v10-0E.xsd

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?>