ksef_client 0.1.0.rc2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b5b053e552c5e8bc2617a54eb8633a8550eec66488e719528e129adc5eca666
-  data.tar.gz: c9b45d61c673e7bd94db8a9c2a152efa3dd1763a35b548879c3901436792acd6
+  metadata.gz: 417315e4a0a7bef0cffda15bbdd96925f6f1e5a20f9a31fd122736c7ec156f27
+  data.tar.gz: f78102d55b9da5b25be64bca58e48017b5bb4da1de91b90f01fbce6fe9a27147
 SHA512:
-  metadata.gz: 75a9e7c57346538eecb3604bef97631812e57f3e3665e89c56ebbacafcdb2d856dae464c99753f719a676dfc0f2d690fee2bf2c8d112a0781db7fb265289edf0
-  data.tar.gz: 929346fec0ca70501a53a80d7f34065f9f385f3f993a26041bd1bac192467d95fadeb96e7658f81ff8dee03bcbd9967832ad50a0a96544dab8da547f76651fdc
+  metadata.gz: 7f89a321f6c580dd96e832361c803b9f3cc1fc1844164dea3111e720b1f5955cf5d0ba26de6113cd80a663a55135de1b6dde6472589e5c54f7b020638ceb8594
+  data.tar.gz: 568038ebc5f9306e3375eb4039592ebeb7badfc8d34c598f719dc4f5c7be19ebcf0744d5f96eeb2280f8131f2c50d7334b53b9a53b949a215be3d9b3e6bc25b2

data/CHANGELOG.md

@@ -10,6 +10,8 @@ gem version for which API state".
 
 ## [Unreleased]
 
+## [0.1.0] — 2026-09-14
+
 **Targets:** KSeF API 2.0 · FA(3) `1-0E` · upstream `CIRFMF/ksef-api@1c34fe27`,
 `CIRFMF/ksef-client-csharp@406904d6`, `CIRFMF/ksef-pdf-generator@2b7c1dae` (sample corpus,
 `docs/REFERENCE.md` §1.4)
@@ -25,6 +27,21 @@ gem version for which API state".
 > code at all yet, so it is absent rather than stubbed.
 
 ### Added
+
+- **`Ksef::Client#wait_for_session`** — waits until KSeF has finished processing a whole
+  session, rather than just closing it.
+
+  **Closing and finishing are two different clocks.** `#session` closes on the way out, which
+  *starts* asynchronous generation of the collective UPO; the session then sits at `170` until
+  that completes at `200`. `#wait_until_accepted` does not cover it — an accepted invoice says
+  nothing about the session's own progress — so a caller that sends, waits for the invoice and
+  then asks for `#collective_upo` is racing.
+
+  The wait already existed on `Sessions::Status` and simply was not reachable through the
+  facade, which left `#collective_upo`'s own documentation instructing callers to poll
+  `#session_status` by hand. Two places in this repository did exactly that, and the live one
+  got it wrong — see below.
+
 - **A recorded flow for the two retrieval paths nothing had ever run**:
   `GET /invoices/ksef/{ksefNumber}` and the pre-signed **storage** leg. All 31 interactions in
   the first three cassettes were on the API host, and none touched `/invoices/ksef/` — so
@@ -177,6 +194,15 @@ gem version for which API state".
 
 ### Fixed
 
+- **The live integration suite asserted a terminal session code without waiting for one**, so
+  the nightly of 2026-09-13 went red on a commit that passed on 09-12 and 09-14. It read
+  `session_status` once, immediately after `wait_until_accepted`, and required `code >= 200` —
+  but `170` means closed with the collective UPO still generating, exactly as
+  `SessionCodes`' own documentation says. A race, not a flake: roughly one night in ten on
+  this sample, which is enough to reset a three-consecutive-night release gate. It now uses
+  the new `Client#wait_for_session`.
+
+
 - **`json` 3.0.0 broke every API response, for users as well as CI.** json 3 dropped the second
   *positional* argument to `JSON.parse`, and `Faraday::Response::Json#parse` still passes one —
   so every JSON response from KSeF raised

data/README.md

@@ -88,21 +88,22 @@ submitted.
 
 ## Installation
 
-**0.1.0 is not released yet.** Only `0.1.0.rc1` is on RubyGems — a name-claiming
-placeholder that deliberately contains none of the API below — and Bundler will not select a
-prerelease for an unconstrained requirement, so `gem "ksef_client"` fails outright. Until
-0.1.0 ships, install from git:
-
 ```ruby
-gem "ksef_client", github: "tibortc/ksef_client"
+gem "ksef_client"
 ```
 
-After release, the usual line will work:
+Or track the branch, where fixes land first:
 
 ```ruby
-gem "ksef_client"   # once 0.1.0 is published
+gem "ksef_client", github: "tibortc/ksef_client"
 ```
 
+**Not the `0.1.0.rc1` prerelease**, if you go looking. It predates this API — a name-claiming
+placeholder holding the transport layer and nothing else, with no authentication, no FA(3) and
+no sessions. It is still on RubyGems because a published version cannot be withdrawn and
+replaced; the line above will not select it, since Bundler skips prereleases for an
+unconstrained requirement.
+
 The gem is named `ksef_client`; the namespace is `Ksef`.
 
 ```ruby

data/lib/ksef/client.rb

@@ -159,8 +159,8 @@ module Ksef
     end
 
     # The collective UPO for a whole session, following the unmetered link when it is still
-    # valid. Available only after the session has closed *and* finished processing — poll
-    # {#session_status} until it reports success, since `170` means closed but not done.
+    # valid. Available only after the session has closed *and* finished processing, so call
+    # {#wait_for_session} first — `170` means closed but not done.
     #
     # @param session_reference [String]
     # @return [Array<Ksef::UPO::Document>] one per page; a collective UPO holds at most
@@ -174,6 +174,30 @@ module Ksef
     # @return [Ksef::Sessions::SessionState]
     def session_status(session_reference) = status_client.session(session_reference)
 
+    # Waits until KSeF has finished processing a whole session.
+    #
+    # **Closing a session and finishing it are two different clocks.** {#session} closes on
+    # the way out, which *starts* asynchronous generation of the collective UPO; the session
+    # then sits at `170` until that finishes at `200`. {#wait_until_accepted} does not cover
+    # it — an accepted invoice says nothing about the session's own progress — so a caller
+    # that sends, waits for the invoice and then asks for {#collective_upo} is racing.
+    #
+    # This existed on {Sessions::Status} from the start and was simply not reachable through
+    # the facade, which left `#collective_upo`'s own documentation telling callers to poll
+    # {#session_status} by hand. Two places in this repository did exactly that, and one of
+    # them got it wrong: `spec/integration/session_flow_spec.rb` read the status once and
+    # asserted a terminal code, which passed until the nightly of 2026-09-13 found TEST still
+    # at `170`.
+    #
+    # @param session_reference [String]
+    # @param deadline [Numeric] seconds; defaults to {Sessions::Status::DEFAULT_DEADLINE}
+    # @yieldparam state [Ksef::Sessions::SessionState] after each poll, for progress reporting
+    # @return [Ksef::Sessions::SessionState] no longer in progress
+    # @raise [Ksef::TimeoutError] when the deadline passes with the session still working
+    def wait_for_session(session_reference, **, &)
+      status_client.wait_for_session(session_reference, **, &)
+    end
+
     # Downloads an invoice KSeF holds, by its KSeF number.
     #
     # @param ksef_number [String, Ksef::KsefNumber]

data/lib/ksef/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ksef_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc2
+  version: 0.1.0
 platform: ruby
 authors:
 - Tibor Molnár
@@ -209,7 +209,7 @@ metadata:
   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.rc2
+  documentation_uri: https://rubydoc.info/gems/ksef_client/0.1.0
 rdoc_options: []
 require_paths:
 - lib