ksef_client 0.1.0.rc1 → 0.1.0

data/docs/errors.md

@@ -6,10 +6,12 @@
 Ksef::Error                        #problem → Ksef::ProblemDetails or nil
 ├── Ksef::ConfigurationError       raised locally, before any request
 ├── Ksef::AuthenticationError      challenge / token / JWT problems, and HTTP 401
-├── Ksef::ValidationError          raised locally by the FA(3) validator
+├── Ksef::ValidationError          any local input check: FA(3), identifiers, references
+├── Ksef::CryptoError              no usable published key, or bad key material
+├── Ksef::IntegrityError           downloaded bytes did not match the published hash
 ├── Ksef::ApiError                 #status #code #details #trace_id #raw
 │   ├── Ksef::InvoiceRejectedError schema or business rejection by KSeF
-│   ├── Ksef::SessionError         session could not be opened, used or closed
+│   ├── Ksef::SessionError         defined, not yet raised — see below
 │   ├── Ksef::AuthorizationError   403 — #reason_code, #security
 │   ├── Ksef::ResourceGoneError    410
 │   ├── Ksef::RateLimitedError     429 — #retry_after
@@ -22,12 +24,37 @@ Everything descends from `StandardError`, so a bare `rescue Ksef::Error` catches
 it. `#problem` is `nil` for locally raised errors and populated for anything derived from
 a response.
 
+Two branches have no HTTP status behind them.
+
+`Ksef::CryptoError` means either that no published KSeF certificate is valid for the usage
+needed, or that key material is the wrong size. The first is worth acting on: after an
+emergency key rotation it is transient, and `Ksef::Crypto::PublicKeys#refresh!` is the
+remedy (docs/REFERENCE.md §10.2, §10.3).
+
+`Ksef::SessionError` is **defined but never raised**, as of 2026-08-23. A session that
+cannot be opened, used or closed currently surfaces as a plain `Ksef::ApiError` carrying the
+status. Do not `rescue Ksef::SessionError` expecting to catch that — it will catch nothing.
+
+`Ksef::TimeoutError` has **two** meanings, and the second matters more. The first is an open
+or read timeout. The second is a **polling deadline** passing in `wait_until_accepted` or
+`wait_for_session`, where it means the operation has *not failed* — it has outlasted the
+wait. Resending there is precisely the duplicate-invoice hazard the gem works to avoid;
+poll again, or raise the `deadline:` option.
+
+`Ksef::IntegrityError` means a downloaded UPO did not match the `x-ms-meta-hash` the
+storage link published for it. **The right response is to fetch it again** — nothing is
+wrong with the request, the credentials or the document, so retrying is not a workaround
+here but the actual fix. It is deliberately not a `ValidationError` (the caller's data is
+fine) and not an `ApiError` (the response was a success). It exists as its own class
+because the artifact is legal proof that an invoice was received: archiving corrupt bytes
+as that proof is the one failure worth refusing loudly (§14.2, §12.3).
+
 ## Status mapping
 
 | Status | Class | Notes |
 |---|---|---|
 | 400 | `Ksef::ApiError` | Carries `errors[]`; `#code` is the KSeF error code |
-| 401 | `Ksef::AuthenticationError` | Refresh and replay once, for idempotent requests only |
+| 401 | `Ksef::AuthenticationError` | **Not** retried. The refresh-and-replay of DESIGN.md §6.3 is not implemented; re-authenticate yourself |
 | 403 | `Ksef::AuthorizationError` | Check `#reason_code` before retrying anything |
 | 410 | `Ksef::ResourceGoneError` | The resource existed but is gone |
 | 429 | `Ksef::RateLimitedError` | Honour `#retry_after` |
@@ -57,7 +84,7 @@ deprecated envelope, `#trace_id` falls back to `referenceNumber`, its closest an
 
 ```ruby
 begin
-  client.invoice(ksef_number)
+  client.download_invoice(ksef_number)
 rescue Ksef::RateLimitedError => e
   sleep e.retry_after if e.retry_after
   retry
@@ -107,6 +134,8 @@ is the earliest signal that something upstream is about to change.
 | Code | Meaning |
 |---|---|
 | 21405 | Input validation failure (e.g. unsupported form code) |
+| 21470 | Symmetric-key certificate unknown or withdrawn. **The one code this library remediates by itself**: `Crypto::PublicKeys#with_key_rotation` re-fetches the published keys and retries once with the new one (`docs/REFERENCE.md` §10.2) |
+| 21111 | Invalid authorisation challenge (`docs/REFERENCE.md` §4.5) |
 | 21157 | Invalid package part size |
 
 This catalogue grows as codes are encountered against the live API; the full published

data/docs/field_mapping.md

@@ -0,0 +1,390 @@
+<!-- GENERATED by `rake fa3:field_mapping` from FA(3) 1-0E — DO NOT EDIT. -->
+
+# FA(3) field mapping
+
+Every field this gem's model carries, and the FA(3) element it reads and writes.
+
+**Generated**, not written: attribute names come from the model classes, and element names,
+types, cardinalities and descriptions from the pinned XSD. Edit `tasks/field_mapping.rb`
+rather than this file — a declared element that does not exist in the schema fails the
+build rather than appearing here, and a model field nobody has mapped fails it too.
+
+**One language per column.** The *Ministry's description* column is the Ministry's own
+`xsd:documentation`, in Polish, **complete, unabridged and quoted rather than translated** —
+only runs of whitespace are collapsed. Nothing this project wrote appears in it: our own
+remarks are in *Notes*, in English, and every heading and column label is English too.
+Several descriptions are long, and several say different things for a correction than for
+an ordinary invoice — that is exactly why they are quoted whole.
+
+The Polish is not translated because it is the operative text: it carries statutory
+citations, and a paraphrase of a tax rule is a different tax rule. **Field-name truth is
+the XSD**, not this table.
+
+"Required?" is **effective** cardinality: an element inside an optional group is optional
+however it declares itself, and a branch of a choice is never required on its own.
+
+Section references such as (§8.4) are to `docs/REFERENCE.md`, which ships with this gem.
+
+
+## Invoice
+
+`Ksef::FA3::Invoice` — The document itself. `Faktura` in the schema; its scalar fields live under `Fa`, its parties directly under the root.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `attachment` | `Zalacznik` | *(inline)* | optional | Załącznik do faktury VAT | — |
+| `number` | `P_2` | `TZnakowy` | **yes** | Kolejny numer faktury, nadany w ramach jednej lub więcej serii, który w sposób jednoznaczny identyfikuje fakturę | — |
+| `issue_date` | `P_1` | `TDataT` | **yes** | Data wystawienia, z zastrzeżeniem art. 106na ust. 1 ustawy | — |
+| `currency` | `KodWaluty` | `TKodWaluty` | **yes** | Kod waluty (ISO 4217) | — |
+| `invoice_type` | `RodzajFaktury` | `TRodzajFaktury` | **yes** | Rodzaj faktury | — |
+| `issued_at` | `DataWytworzeniaFa` | *(inline)* | **yes** | Data i czas wytworzenia faktury | — |
+| `seller` | `Podmiot1` | *(inline)* | **yes** | Dane podatnika. Imię i nazwisko lub nazwa sprzedawcy towarów lub usług | — |
+| `buyer` | `Podmiot2` | *(inline)* | **yes** | Dane nabywcy | — |
+| `lines` | `FaWiersz` | *(inline)* | optional, up to 10000 | Szczegółowe pozycje faktury w walucie, w której wystawiono fakturę - węzeł opcjonalny dla faktury zaliczkowej, faktury korygującej fakturę zaliczkową oraz faktur korygujących dotyczących wszystkich dostaw towarów lub usług dokonanych lub świadczonych w danym okresie, o których mowa w art. 106j ust. 3 ustawy, dla których należy podać dane dotyczące opustu lub obniżki w podziale na stawki podatku i procedury w części Fa. W przypadku faktur korygujących, o których mowa w art. 106j ust. 3 ustawy, gdy opust lub obniżka ceny odnosi się do części dostaw towarów lub usług dokonanych lub świadczonych w danym okresie w części FaWiersz należy podać nazwy (rodzaje) towarów lub usług objętych korektą. W przypadku faktur, o których mowa w art. 106f ust. 3 ustawy, należy wykazać pełne wartości zamówienia lub umowy. W przypadku faktur korygujących pozycje faktury (w tym faktur korygujących faktury, o których mowa w art. 106f ust. 3 ustawy, jeśli korekta dotyczy wartości zamówienia) należy wykazać różnice wynikające z korekty poszczególnych pozycji lub dane pozycji korygowanych wg stanu przed korektą i po korekcie jako osobne wiersze. W przypadku faktur korygujących faktury, o których mowa w art. 106f ust. 3 ustawy, jeśli korekta nie dotyczy wartości zamówienia i jednocześnie zmienia wysokość podstawy opodatkowania lub podatku, należy wprowadzić zapis wg stanu przed korektą i zapis wg stanu po korekcie w celu potwierdzenia braku zmiany wartości danej pozycji faktury | A true container: everything a line writes is under it. |
+| `annotations` | `Adnotacje` | *(inline)* | **yes** | Inne adnotacje na fakturze | — |
+| `correction` | `DaneFaKorygowanej` | *(inline)* | optional, up to 50000 | Dane faktury korygowanej | **A group, not one element.** The attribute also writes `PrzyczynaKorekty`, `TypKorekty`, `OkresFaKorygowanej`, `NrFaKorygowany`, `Podmiot1K`, `Podmiot2K`, `P_15ZK` and `KursWalutyZK` as siblings; this is the one that is mandatory once any of them is present. See the Correction section. |
+| `totals` | `P_15` | `TKwotowy` | **yes** | Kwota należności ogółem. W przypadku faktur zaliczkowych - kwota zapłaty dokumentowana fakturą. W przypadku faktur, o których mowa w art. 106f ust. 3 ustawy - kwota pozostała do zapłaty. W przypadku faktur korygujących - korekta kwoty wynikającej z faktury korygowanej. W przypadku, o którym mowa w art. 106j ust. 3 ustawy - korekta kwot wynikających z faktur korygowanych | **The buckets are the substance**, and they are listed under Summary buckets. Note `P_15` is written for every invoice, whether or not a summary is stated — see `#gross_total` under Computed readers. |
+| `order` | `Zamowienie` | *(inline)* | optional | Zamówienie lub umowa, o których mowa w art. 106f ust. 1 pkt 4 ustawy (dla faktur zaliczkowych), w walucie, w której wystawiono fakturę zaliczkową. W przypadku faktury korygującej fakturę zaliczkową należy wykazać różnice wynikające z korekty poszczególnych pozycji zamówienia lub umowy lub dane pozycji korygowanych wg stanu przed korektą i po korekcie jako osobne wiersze, jeśli korekta dotyczy wartości zamówienia lub umowy. W przypadku faktur korygujących faktury zaliczkowe, jeśli korekta nie dotyczy wartości zamówienia lub umowy i jednocześnie zmienia wysokość podstawy opodatkowania lub podatku, należy wprowadzić zapis wg stanu przed korektą i zapis wg stanu po korekcie w celu potwierdzenia braku zmiany wartości danej pozycji | — |
+| `advances` | `FakturaZaliczkowa` | *(inline)* | optional, up to 100 | Numery faktur zaliczkowych lub ich numery KSeF, jeśli zostały wystawione z użyciem KSeF | — |
+| `rounding` | — | — | — | — | **Not in the document at all.** Which rounding strategy produced the summaries is inferred when parsing (`RoundingInference`); FA(3) never states it. |
+| `raw_document` | — | — | — | — | **Not an element.** Provenance rather than content — the retained source document, excluded from this invoice's identity. |
+| `stated_gross` | `P_15` | — | — | — | The same `P_15` that `#gross_total` writes, carried only when the document's figure differs from what the rows derive. Not a second element. |
+
+
+## Subject as the seller — `Podmiot1`
+
+`Ksef::FA3::Subject` — **The seller and the buyer are different XSD types**, `TPodmiot1` and `TPodmiot2`, and they disagree about what is required — so they get a section each rather than one section with a footnote. A seller must state a name and an address; a buyer need not. `Podmiot1K` on a correction uses this type.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `nip` | `NIP` | `etd:TNrNIP` | **yes** | Identyfikator podatkowy NIP | — |
+| `name` | `Nazwa` | `TZnakowy512` | **yes** | Imię i nazwisko lub nazwa | — |
+| `address` | `Adres` | `TAdres` | **yes** | Adres podatnika | — |
+| `local_government_unit` | — | — | — | — | **Buyer-only.** `TPodmiot1` declares no `JST`; see the buyer section. |
+| `vat_group_member` | — | — | — | — | **Buyer-only.** `TPodmiot1` declares no `GV`; see the buyer section. |
+| `buyer_id` | — | — | — | — | **Buyer-only.** `TPodmiot1` declares no `IDNabywcy`; see the buyer section. |
+
+
+## Subject as the buyer — `Podmiot2`
+
+`Ksef::FA3::Subject` — `Podmiot2`, and `Podmiot2K` on a correction. **The buyer's name and address are both optional** — a fact this project got wrong three times before (§8.2a) — and the identity is a four-way choice of which this model carries only the NIP branch.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `nip` | `NIP` | `etd:TNrNIP` | one of a choice | Identyfikator podatkowy NIP | — |
+| `name` | `Nazwa` | `TZnakowy512` | optional | Imię i nazwisko lub nazwa | — |
+| `address` | `Adres` | `TAdres` | optional | Adres nabywcy. Pola opcjonalne dla przypadków określonych w art. 106e ust. 5 pkt 3 ustawy | — |
+| `local_government_unit` | `JST` | *(inline)* | **yes** | Znacznik jednostki podrzędnej JST. Wartość "1" oznacza, że faktura dotyczy jednostki podrzędnej JST. W takim przypadku, aby udostępnić fakturę jednostce podrzędnej JST, należy wypełnić sekcję Podmiot3, w szczególności podać NIP lub ID-Wew i określić rolę jako 8. Wartość "2" oznacza, że faktura nie dotyczy jednostki podrzędnej JST | — |
+| `vat_group_member` | `GV` | *(inline)* | **yes** | Znacznik członka grupy VAT. Wartość "1" oznacza, że faktura dotyczy członka grupy VAT. W takim przypadku, aby udostępnić fakturę członkowi grupy VAT, należy wypełnić sekcję Podmiot3, w szczególności podać NIP lub ID-Wew i określić rolę jako 10. Wartość "2" oznacza, że faktura nie dotyczy członka grupy VAT | — |
+| `buyer_id` | `IDNabywcy` | *(inline)* | optional | Unikalny klucz powiązania danych nabywcy na fakturach korygujących, w przypadku gdy dane nabywcy na fakturze korygującej zmieniły się w stosunku do danych na fakturze korygowanej | — |
+
+
+## Address
+
+`Ksef::FA3::Address` — FA(3) has no street/city/postcode fields: it takes two free-text lines. `Address` composes them at construction and keeps the composed form (§8.2b), so `street`/`city`/`postal_code` are constructor sugar rather than attributes.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `line1` | `AdresL1` | `TZnakowy512` | **yes** | Adres [Address] | — |
+| `line2` | `AdresL2` | `TZnakowy512` | optional | Adres [Address] | — |
+| `country` | `KodKraju` | `etd:TKodKraju` | **yes** | Kod Kraju [Country Code] | — |
+
+
+## Line — an invoice row
+
+`Ksef::FA3::Line` — One `FaWiersz`. Every child but `NrWierszaFa` is optional, so most fields here may be absent from a legal document (§8.6).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `name` | `P_7` | `TZnakowy512` | optional | Nazwa (rodzaj) towaru lub usługi. Pole opcjonalne wyłącznie dla przypadku określonego w art 106j ust. 3 pkt 2 ustawy (faktura korygująca) | — |
+| `unit` | `P_8A` | `TZnakowy` | optional | Miara dostarczonych towarów lub zakres wykonanych usług. Pole opcjonalne dla przypadku określonego w art. 106e ust. 5 pkt 3 ustawy | — |
+| `quantity` | `P_8B` | `TIlosci` | optional | Ilość (liczba) dostarczonych towarów lub zakres wykonanych usług. Pole opcjonalne dla przypadku określonego w art. 106e ust. 5 pkt 3 ustawy | Also feeds `P_11` when the row states no net. |
+| `net_unit_price` | `P_9A` | `TKwotowy2` | optional | Cena jednostkowa towaru lub usługi bez kwoty podatku (cena jednostkowa netto). Pole opcjonalne dla przypadków określonych w art. 106e ust. 2 i 3 oraz ust. 5 pkt 3 ustawy | `TKwotowy2` — **eight decimal places**, four times the amount it produces. Also feeds `P_11` when the row states no net. |
+| `net_amount` | `P_11` | `TKwotowy` | optional | Wartość dostarczonych towarów lub wykonanych usług, objętych transakcją, bez kwoty podatku (wartość sprzedaży netto). Pole opcjonalne dla przypadków określonych w art. 106e ust. 2 i 3 oraz ust. 5 pkt 3 ustawy | **`P_11` has two sources.** Stated here when the row states one; otherwise derived from `quantity` × `net_unit_price`. `Line#net` is the reader that answers either way, and nil when the row states no amount at all. |
+| `vat_rate` | `P_12` | `TStawkaPodatku` | optional | Stawka podatku. Pole opcjonalne dla przypadków określonych w art. 106e ust. 2, 3, ust. 4 pkt 3 i ust. 5 pkt 3 ustawy | — |
+| `row_number` | `NrWierszaFa` | `TNaturalny` | **yes** | Kolejny numer wiersza faktury | — |
+| `state_before` | `StanPrzed` | `etd:TWybor1` | optional | Znacznik stanu przed korektą w przypadku faktury korygującej lub faktury korygującej fakturę wystawioną w związku z art. 106f ust. 3 ustawy, w przypadku gdy korekta dotyczy danych wykazanych w pozycjach faktury i jest dokonywana w sposób polegający na wykazaniu danych przed korektą i po korekcie jako osobnych wierszy z odrębną numeracją oraz w przypadku potwierdzania braku zmiany wartości danej pozycji | — |
+
+
+## Totals — a stated summary
+
+`Ksef::FA3::Totals` — What a document states rather than what its rows imply. Present on the six types in `Invoice::STATED_TOTALS_TYPES`; a `VAT` invoice derives its summary instead (§8.4, §8.5).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `gross` | `P_15` | `TKwotowy` | **yes** | Kwota należności ogółem. W przypadku faktur zaliczkowych - kwota zapłaty dokumentowana fakturą. W przypadku faktur, o których mowa w art. 106f ust. 3 ustawy - kwota pozostała do zapłaty. W przypadku faktur korygujących - korekta kwoty wynikającej z faktury korygowanej. W przypadku, o którym mowa w art. 106j ust. 3 ustawy - korekta kwot wynikających z faktur korygowanych | — |
+| `buckets` | `P_13_*`, `P_14_*` | — | — | — | A Hash **keyed by element name**, so each key is its own element. See *Summary buckets* below. |
+
+
+## Correction
+
+`Ksef::FA3::Correction` — The group that makes a `KOR`, `KOR_ZAL` or `KOR_ROZ` a correction. Optional as a whole; `DaneFaKorygowanej` is mandatory once any of it is present (§8.4).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `reason` | `PrzyczynaKorekty` | `TZnakowy` | optional | Przyczyna korekty dla faktur korygujących | — |
+| `effect` | `TypKorekty` | `TTypKorekty` | optional | Typ skutku korekty w ewidencji dla podatku od towarów i usług | — |
+| `corrected` | `DaneFaKorygowanej` | *(inline)* | optional, up to 50000 | Dane faktury korygowanej | — |
+| `period` | `OkresFaKorygowanej` | `TZnakowy` | optional | Dla faktury korygującej, o której mowa w art. 106j ust. 3 ustawy - okres, do którego odnosi się udzielany opust lub udzielana obniżka, w przypadku gdy podatnik udziela opustu lub obniżki ceny w odniesieniu do dostaw towarów lub usług dokonanych lub świadczonych na rzecz jednego odbiorcy w danym okresie | — |
+| `corrected_number` | `NrFaKorygowany` | `TZnakowy` | optional | Poprawny numer faktury korygowanej w przypadku, gdy przyczyną korekty jest błędny numer faktury korygowanej. W takim przypadku błędny numer faktury należy wskazać w polu NrFaKorygowanej | — |
+| `previous_seller` | `Podmiot1K` | *(inline)* | optional | W przypadku korekty danych sprzedawcy należy podać pełne dane sprzedawcy występujące na fakturze korygowanej. Pole nie dotyczy przypadku korekty błędnego NIP występującego na fakturze pierwotnej - wówczas wymagana jest korekta faktury do wartości zerowych | — |
+| `previous_buyers` | `Podmiot2K` | *(inline)* | optional, up to 101 | W przypadku korekty danych nabywcy występującego jako Podmiot2 lub dodatkowego nabywcy występującego jako Podmiot3 należy podać pełne dane tego podmiotu występujące na fakturze korygowanej. Korekcie nie podlegają błędne numery NIP identyfikujące nabywcę oraz dodatkowego nabywcę - wówczas wymagana jest korekta faktury do wartości zerowych. W przypadku korygowania pozostałych danych nabywcy lub dodatkowego nabywcy wskazany numer identyfikacyjny ma być tożsamy z numerem w części Podmiot2 względnie Podmiot3 faktury korygującej | — |
+| `paid_before` | `P_15ZK` | `TKwotowy` | optional | W przypadku korekt faktur zaliczkowych - kwota zapłaty przed korektą. W przypadku korekt faktur, o których mowa w art. 106f ust. 3 ustawy - kwota pozostała do zapłaty przed korektą | — |
+| `exchange_rate_before` | `KursWalutyZK` | `TIlosci` | optional | Kurs waluty stosowany do wyliczenia kwoty podatku w przypadkach, o których mowa w dziale VI ustawy przed korektą | — |
+
+
+## CorrectedInvoice — which invoice is corrected
+
+`Ksef::FA3::CorrectedInvoice` — One `DaneFaKorygowanej`. Its choice group names the corrected invoice either by KSeF number or by number-and-date, and the branches are not symmetrical with `FakturaZaliczkowa`'s (§8.5).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `number` | `NrFaKorygowanej` | `TZnakowy` | **yes** | Numer faktury korygowanej | — |
+| `issue_date` | `DataWystFaKorygowanej` | `TDataT` | **yes** | Data wystawienia faktury korygowanej | — |
+| `ksef_number` | `NrKSeFFaKorygowanej` | `TNumerKSeF` | one of a choice | Numer identyfikujący fakturę korygowaną w KSeF | — |
+
+
+## Order — an advance invoice's order
+
+`Ksef::FA3::Order` — `Zamowienie`, which replaces `FaWiersz` entirely on a `ZAL`. `WartoscZamowienia` is the whole order **including tax** (§8.5).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `total` | `WartoscZamowienia` | `TKwotowy` | **yes** | Wartość zamówienia lub umowy z uwzględnieniem kwoty podatku | — |
+| `lines` | `ZamowienieWiersz` | *(inline)* | yes, 1–10000 | Szczegółowe pozycje zamówienia lub umowy w walucie, w której wystawiono fakturę zaliczkową | — |
+
+
+## Attachment — the invoice attachment
+
+`Ksef::FA3::Attachment` — `Zalacznik`, a **sibling of `Fa`** rather than one of its children, so it takes part in no summary and no arithmetic. FA(3) carries no bytes and no MIME type: an attachment here is a structured document of headings, key/value metadata, paragraphs and tables. Operational constraints on sending one are out of 0.1 scope (DESIGN.md §7.4).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `blocks` | `BlokDanych` | *(inline)* | yes, 1–1000 | Szczegółowe dane załącznika | — |
+
+
+## DataBlock — one block of an attachment
+
+`Ksef::FA3::DataBlock` — `BlokDanych`. `MetaDane` is the one child the schema requires, which is why a block describing itself only with a heading or a table is refused at construction.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `heading` | `ZNaglowek` | `TZnakowy512` | optional | Nagłówek bloku danych | — |
+| `metadata` | `MetaDane` | *(inline)* | yes, 1–1000 | Dane opisowe | — |
+| `paragraphs` | `Akapit` | `TZnakowy512` | optional, up to 10 | Opis | — |
+| `tables` | `Tabela` | *(inline)* | optional, up to 1000 | Tabele | — |
+
+
+## MetaEntry — one key/value pair
+
+`Ksef::FA3::MetaEntry` — `MetaDane` on a block and `TMetaDane` on a table are the same shape under different names, so one class serves both. Mapped against the block's names; the table's are `TKlucz`/`TWartosc`.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `key` | `ZKlucz` | `TZnakowy` | **yes** | Klucz | — |
+| `value` | `ZWartosc` | `TZnakowy` | **yes** | Wartość | — |
+
+
+## AttachmentTable — a table inside a block
+
+`Ksef::FA3::AttachmentTable` — `Tabela`. **Rows are ragged**: `Kol` and `WKom` each repeat 1..20 and the schema ties them together nowhere, so a row need not carry one cell per column — both Ministry samples alternate one-cell label rows with full-width ones.
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `metadata` | `TMetaDane` | *(inline)* | optional, up to 1000 | Dane opisowe dotyczące tabeli | — |
+| `caption` | `Opis` | `TZnakowy512` | optional | Opis | — |
+| `columns` | `Kol` | *(inline)* | yes, 1–20 | — | — |
+| `rows` | `Wiersz` | *(inline)* | yes, 1–1000 | Wiersze tabeli | An Array of rows, each an Array of `WKom` cells (1–20, and **ragged** — a row need not carry one per column). |
+| `totals` | `SKom` | `TZnakowy2` | optional, up to 20 | Zawartość pola | — |
+
+
+## TableColumn — one column heading
+
+`Ksef::FA3::TableColumn` — `Kol`. Its `Typ` attribute is FA(3)'s **only** inline attribute enumeration, and the six permitted values are read from the generated metadata rather than restated in Ruby (`docs/REFERENCE.md` §18.2).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `name` | `NKom` | *(inline)* | **yes** | Zawartość pola | — |
+| `type` | `Kol/@Typ` | — | — | — | **An attribute, not an element** — the only one in FA(3) carrying an inline enumeration (`date`, `datetime`, `dec`, `int`, `time`, `txt`). Required by the schema, and the permitted values are read from the generated metadata rather than restated (`docs/REFERENCE.md` §18.2). |
+
+
+## OrderLine — an order position
+
+`Ksef::FA3::OrderLine` — One `ZamowienieWiersz`. Unlike {Line} nothing here is derived: the document states both the net and the tax, so both are read (§8.5).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `name` | `P_7Z` | `TZnakowy512` | optional | Nazwa (rodzaj) towaru lub usługi | — |
+| `unit` | `P_8AZ` | `TZnakowy` | optional | Miara zamówionego towaru lub zakres usługi | — |
+| `quantity` | `P_8BZ` | `TIlosci` | optional | Ilość zamówionego towaru lub zakres usługi | — |
+| `net_unit_price` | `P_9AZ` | `TKwotowy2` | optional | Cena jednostkowa netto | — |
+| `net_amount` | `P_11NettoZ` | `TKwotowy` | optional | Wartość zamówionego towaru lub usługi bez kwoty podatku | — |
+| `vat_amount` | `P_11VatZ` | `TKwotowy` | optional | Kwota podatku od zamówionego towaru lub usługi | — |
+| `vat_rate` | `P_12Z` | `TStawkaPodatku` | optional | Stawka podatku | — |
+| `row_number` | `NrWierszaZam` | `TNaturalny` | **yes** | Kolejny numer wiersza zamówienia lub umowy | — |
+| `state_before` | `StanPrzedZ` | `etd:TWybor1` | optional | Znacznik stanu przed korektą w przypadku faktury korygującej fakturę dokumentującą otrzymanie zapłaty lub jej części przed dokonaniem czynności oraz fakturę wystawioną w związku z art. 106f ust. 4 ustawy (faktura korygująca fakturę zaliczkową), w przypadku gdy korekta dotyczy danych wykazanych w pozycjach zamówienia i jest dokonywana w sposób polegający na wykazaniu danych przed korektą i po korekcie jako osobnych wierszy z odrębną numeracją oraz w przypadku potwierdzania braku zmiany wartości danej pozycji | — |
+
+
+## AdvanceInvoice — an advance already settled
+
+`Ksef::FA3::AdvanceInvoice` — One `FakturaZaliczkowa` on a `ROZ` or `KOR_ROZ`. Its choice is **inverted** from `DaneFaKorygowanej`'s: the marker `NrKSeFZN` pairs with the plain number, and the KSeF branch is the number alone (§8.5).
+
+| Attribute | FA(3) element | Type | Required? | The Ministry's description (Polish, verbatim) | Notes |
+|---|---|---|---|---|---|
+| `number` | `NrFaZaliczkowej` | `TZnakowy` | one of a choice | Numer faktury zaliczkowej wystawionej poza KSeF. Pole obowiązkowe dla faktury wystawianej po wydaniu towaru lub wykonaniu usługi, o której mowa w art. 106f ust. 3 ustawy i ostatniej z faktur, o której mowa w art. 106f ust. 4 ustawy | — |
+| `ksef_number` | `NrKSeFFaZaliczkowej` | `TNumerKSeF` | one of a choice | Numer identyfikujący fakturę zaliczkową w KSeF. Pole obowiązkowe w przypadku, gdy faktura zaliczkowa była wystawiona za pomocą KSeF | — |
+
+
+## Computed readers
+
+These are methods, not stored fields, and for several elements they are what you actually read. **`P_15` is here, not in the Invoice table** — on a `VAT` invoice nothing stores it.
+
+| Reader | FA(3) element | What it does |
+|---|---|---|
+| `Invoice#gross_total` | `P_15` | The total amount due. Read from a stated summary when there is one, otherwise net + VAT from the rows. |
+| `Invoice#net_total` | `P_13_*` (sum) | Total net. Stated summary if present, else the sum of the rows. |
+| `Invoice#vat_total` | `P_14_*` (sum) | Total VAT, by the invoice's `rounding` strategy. |
+| `Invoice#summary_buckets` | `P_13_*`, `P_14_*` | **The way to reach one bucket**: `invoice.summary_buckets["P_13_4"]`. All seven types. |
+| `Invoice#net_by_rate` | — | Net per `P_12` rate code, before bucketing. Several codes share a bucket. |
+| `Invoice#vat_by_rate` | — | VAT per rate code. |
+| `Invoice#unmapped_elements` | — | For a parsed invoice, the element paths `#to_xml` would drop. |
+| `Invoice#errors` | — | Validator tiers 1a, 1b and 2. Empty means the document is well-formed and schema-valid. |
+| `Invoice#warnings` | — | Tier 3, advisory: figures the document states that do not reconcile. |
+| `Line#net` | `P_11` | The row's net — **read from `P_11` when stated**, else quantity × unit price. nil when the row states no amount, which is legal. |
+| `Line#vat` | — | Tax on the row, from its rate code. nil when the row states no amount. |
+| `Line#gross` | — | net + VAT, or nil. |
+| `Totals#net` | `P_13_*` (sum) | Sum of the stated net buckets. |
+| `Totals#vat` | `P_14_*` (sum) | Sum of the stated tax buckets. |
+
+
+## Annotations
+
+`Invoice#annotations` is a Hash keyed by element name, and these eight are the declarations it carries. Each has tax consequences, and the parser **reads them rather than defaulting them** — emitting the defaults regardless would silently deny every declaration an invoice made.
+
+| Element | Required? | The Ministry's description (Polish, verbatim) |
+|---|---|---|
+| `P_16` | **yes** | W przypadku dostawy towarów lub świadczenia usług, w odniesieniu do których obowiązek podatkowy powstaje zgodnie z art. 19a ust. 5 pkt 1 lub art. 21 ust. 1 ustawy - wyrazy "metoda kasowa"; należy podać wartość "1", w przeciwnym przypadku - wartość "2" |
+| `P_17` | **yes** | W przypadku faktur, o których mowa w art. 106d ust. 1 ustawy - wyraz "samofakturowanie"; należy podać wartość "1", w przeciwnym przypadku - wartość "2" |
+| `P_18` | **yes** | W przypadku dostawy towarów lub wykonania usługi, dla których obowiązanym do rozliczenia podatku od wartości dodanej lub podatku o podobnym charakterze jest nabywca towaru lub usługi - wyrazy "odwrotne obciążenie"; należy podać wartość "1", w przeciwnym przypadku - wartość "2" |
+| `P_18A` | **yes** | W przypadku faktur, w których kwota należności ogółem przekracza kwotę 15 000 zł lub jej równowartość wyrażoną w walucie obcej, obejmujących dokonaną na rzecz podatnika dostawę towarów lub świadczenie usług, o których mowa w załączniku nr 15 do ustawy - wyrazy "mechanizm podzielonej płatności", przy czym do przeliczania na złote kwot wyrażonych w walucie obcej stosuje się zasady przeliczania kwot stosowane w celu określenia podstawy opodatkowania; należy podać wartość "1", w przeciwnym przypadku - wartość "2" |
+| `Zwolnienie` | **yes** | — |
+| `NoweSrodkiTransportu` | **yes** | — |
+| `P_23` | **yes** | W przypadku faktur wystawianych w procedurze uproszczonej przez drugiego w kolejności podatnika, o którym mowa w art. 135 ust. 1 pkt 4 lit. b i c oraz ust. 2 ustawy, zawierającej adnotację, o której mowa w art. 136 ust. 1 pkt 1 ustawy i stwierdzenie, o którym mowa w art. 136 ust. 1 pkt 2 ustawy, należy podać wartość "1", w przeciwnym przypadku - wartość "2" |
+| `PMarzy` | **yes** | — |
+
+
+## Summary buckets
+
+`Totals#buckets` is keyed by element name, and `Invoice#summary_buckets` returns the same shape for every invoice type. Which bucket a row lands in is decided by its `P_12` rate code, and **the map is not invertible** — several codes share one bucket. Three buckets have no rate code at all, which is a limit of this model rather than of FA(3): a document may state them, and this model will read and re-write them only as part of a stated summary.
+
+| Element | Rate codes | The Ministry's description (Polish, verbatim) |
+|---|---|---|
+| `P_13_1` | `23`, `22` | Suma wartości sprzedaży netto objętej stawką podstawową - aktualnie 23% albo 22%. W przypadku faktur zaliczkowych - wartość zaliczki netto. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_14_1` | `23`, `22` | Kwota podatku od sumy wartości sprzedaży netto objętej stawką podstawową - aktualnie 23% albo 22%. W przypadku faktur zaliczkowych - kwota podatku wyliczona według wzoru, o którym mowa w art. 106f ust. 1 pkt 3 ustawy. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_2` | `8`, `7` | Suma wartości sprzedaży netto objętej stawką obniżoną pierwszą - aktualnie 8 % albo 7%. W przypadku faktur zaliczkowych - wartość zaliczki netto. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_14_2` | `8`, `7` | Kwota podatku od sumy wartości sprzedaży netto objętej stawką obniżoną pierwszą - aktualnie 8% albo 7%. W przypadku faktur zaliczkowych - kwota podatku wyliczona według wzoru, o którym mowa w art. 106f ust. 1 pkt 3 ustawy. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_3` | `5` | Suma wartości sprzedaży netto objętej stawką obniżoną drugą - aktualnie 5%. W przypadku faktur zaliczkowych - wartość zaliczki netto. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_14_3` | `5` | Kwota podatku od sumy wartości sprzedaży netto objętej stawką obniżoną drugą - aktualnie 5%. W przypadku faktur zaliczkowych - kwota podatku wyliczona według wzoru, o którym mowa w art. 106f ust. 1 pkt 3 ustawy. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_4` | `4`, `3` | Suma wartości sprzedaży netto objętej ryczałtem dla taksówek osobowych. W przypadku faktur zaliczkowych - wartość zaliczki netto. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_14_4` | `4`, `3` | Kwota podatku od sumy wartości sprzedaży netto w przypadku ryczałtu dla taksówek osobowych. W przypadku faktur zaliczkowych - kwota podatku wyliczona według wzoru, o którym mowa w art. 106f ust. 1 pkt 3 ustawy. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_5` | *(none)* | Suma wartości sprzedaży netto w przypadku procedury szczególnej, o której mowa w dziale XII w rozdziale 6a ustawy. W przypadku faktur zaliczkowych - wartość zaliczki netto. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_14_5` | *(none)* | Kwota podatku od wartości dodanej w przypadku procedury szczególnej, o której mowa w dziale XII w rozdziale 6a ustawy. W przypadku faktur zaliczkowych - kwota podatku wyliczona według wzoru, o którym mowa w art. 106f ust. 1 pkt 3 ustawy. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_6_1` | `0 KR` | Suma wartości sprzedaży objętej stawką 0% z wyłączeniem wewnątrzwspólnotowej dostawy towarów i eksportu. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_6_2` | `0 WDT` | Suma wartości sprzedaży objętej stawką 0% w przypadku wewnątrzwspólnotowej dostawy towarów. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_6_3` | `0 EX` | Suma wartości sprzedaży objętej stawką 0% w przypadku eksportu. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_7` | `zw` | Suma wartości sprzedaży zwolnionej od podatku. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy wartości sprzedaży |
+| `P_13_8` | `np I` | Suma wartości sprzedaży w przypadku dostawy towarów oraz świadczenia usług poza terytorium kraju, z wyłączeniem kwot wykazanych w polach P_13_5 i P_13_9. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy wartości sprzedaży |
+| `P_13_9` | `np II` | Suma wartości świadczenia usług, o których mowa w art. 100 ust. 1 pkt 4 ustawy. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy wartości sprzedaży |
+| `P_13_10` | `oo` | Suma wartości sprzedaży w procedurze odwrotnego obciążenia, dla której podatnikiem jest nabywca zgodnie z art. 17 ust. 1 pkt 7 i 8 ustawy oraz innych przypadków odwrotnego obciążenia występujących w obrocie krajowym. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy, o której mowa w art. 106j ust. 2 pkt 5 ustawy |
+| `P_13_11` | *(none)* | Suma wartości sprzedaży w procedurze marży, o której mowa w art. 119 i art. 120 ustawy. W przypadku faktur zaliczkowych - wartość zaliczki. W przypadku faktur korygujących - kwota różnicy wartości sprzedaży |
+
+
+## What this model does not carry
+
+Listed rather than omitted, because an absent row would otherwise read as "not supported" when it may only mean "not modelled". A document carrying any of these still parses; `Invoice#unmapped_elements` names exactly what `#to_xml` would drop for a given document, and `#raw_document` keeps the original.
+
+| Under | Elements |
+|---|---|
+| `Faktura` | `Podmiot3`, `PodmiotUpowazniony`, `Stopka` |
+| `Faktura/Fa` | `P_1M`, `WZ`, `P_6`, `OkresFa`, `P_14_1W`, `P_14_2W`, `P_14_3W`, `P_14_4W`, `KursWalutyZ`, `ZaliczkaCzesciowa`, `FP`, `TP`, `DodatkowyOpis`, `ZwrotAkcyzy`, `Rozliczenie`, `Platnosc`, `WarunkiTransakcji` |
+
+
+## Element index
+
+The reverse direction: an element from a Polish invoice, and the attribute that carries it. An element listed twice is carried by two different models — `P_9A` on an invoice row and `P_9AZ` on an order position are different elements.
+
+| FA(3) element | Attribute |
+|---|---|
+| `Adnotacje` | `Invoice#annotations` |
+| `Adres` | `Buyer#address`, `Seller#address` |
+| `AdresL1` | `Address#line1` |
+| `AdresL2` | `Address#line2` |
+| `Akapit` | `DataBlock#paragraphs` |
+| `BlokDanych` | `Attachment#blocks` |
+| `DaneFaKorygowanej` | `Correction#corrected`, `Invoice#correction` |
+| `DataWystFaKorygowanej` | `CorrectedInvoice#issue_date` |
+| `DataWytworzeniaFa` | `Invoice#issued_at` |
+| `FaWiersz` | `Invoice#lines` |
+| `FakturaZaliczkowa` | `Invoice#advances` |
+| `GV` | `Buyer#vat_group_member` |
+| `IDNabywcy` | `Buyer#buyer_id` |
+| `JST` | `Buyer#local_government_unit` |
+| `KodKraju` | `Address#country` |
+| `KodWaluty` | `Invoice#currency` |
+| `Kol` | `AttachmentTable#columns` |
+| `KursWalutyZK` | `Correction#exchange_rate_before` |
+| `MetaDane` | `DataBlock#metadata` |
+| `NIP` | `Buyer#nip`, `Seller#nip` |
+| `NKom` | `TableColumn#name` |
+| `Nazwa` | `Buyer#name`, `Seller#name` |
+| `NrFaKorygowanej` | `CorrectedInvoice#number` |
+| `NrFaKorygowany` | `Correction#corrected_number` |
+| `NrFaZaliczkowej` | `AdvanceInvoice#number` |
+| `NrKSeFFaKorygowanej` | `CorrectedInvoice#ksef_number` |
+| `NrKSeFFaZaliczkowej` | `AdvanceInvoice#ksef_number` |
+| `NrWierszaFa` | `Line#row_number` |
+| `NrWierszaZam` | `OrderLine#row_number` |
+| `OkresFaKorygowanej` | `Correction#period` |
+| `Opis` | `AttachmentTable#caption` |
+| `P_1` | `Invoice#issue_date` |
+| `P_11` | `Line#net_amount` |
+| `P_11NettoZ` | `OrderLine#net_amount` |
+| `P_11VatZ` | `OrderLine#vat_amount` |
+| `P_12` | `Line#vat_rate` |
+| `P_12Z` | `OrderLine#vat_rate` |
+| `P_15` | `Invoice#totals`, `Totals#gross` |
+| `P_15ZK` | `Correction#paid_before` |
+| `P_2` | `Invoice#number` |
+| `P_7` | `Line#name` |
+| `P_7Z` | `OrderLine#name` |
+| `P_8A` | `Line#unit` |
+| `P_8AZ` | `OrderLine#unit` |
+| `P_8B` | `Line#quantity` |
+| `P_8BZ` | `OrderLine#quantity` |
+| `P_9A` | `Line#net_unit_price` |
+| `P_9AZ` | `OrderLine#net_unit_price` |
+| `Podmiot1` | `Invoice#seller` |
+| `Podmiot1K` | `Correction#previous_seller` |
+| `Podmiot2` | `Invoice#buyer` |
+| `Podmiot2K` | `Correction#previous_buyers` |
+| `PrzyczynaKorekty` | `Correction#reason` |
+| `RodzajFaktury` | `Invoice#invoice_type` |
+| `SKom` | `AttachmentTable#totals` |
+| `StanPrzed` | `Line#state_before` |
+| `StanPrzedZ` | `OrderLine#state_before` |
+| `TMetaDane` | `AttachmentTable#metadata` |
+| `Tabela` | `DataBlock#tables` |
+| `TypKorekty` | `Correction#effect` |
+| `WartoscZamowienia` | `Order#total` |
+| `Wiersz` | `AttachmentTable#rows` |
+| `ZKlucz` | `MetaEntry#key` |
+| `ZNaglowek` | `DataBlock#heading` |
+| `ZWartosc` | `MetaEntry#value` |
+| `Zalacznik` | `Invoice#attachment` |
+| `Zamowienie` | `Invoice#order` |
+| `ZamowienieWiersz` | `Order#lines` |
+
+---
+
+*Schema: `lib/ksef/fa3/schema/schemat_FA(3)_v1-0E.xsd`. Regenerate with `rake fa3:field_mapping`; `rake fa3:verify` fails if
+this file is stale.*

data/lib/ksef/auth/access_token.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # Holds the redeemed token pair and keeps the access token fresh
+    # (DESIGN.md §5.1, §6.3; docs/REFERENCE.md §4.2).
+    #
+    # ## Expiry comes from the response, never from the JWT
+    #
+    # The access token is a JWT, and it is tempting to read `exp` out of it. This gem does
+    # not, and that is a locked decision: DESIGN.md §4.3 excludes the `jwt` dependency and
+    # treats the token as an opaque bearer string, and the contract's `TokenInfo` carries
+    # `validUntil` precisely so no decoding is needed. (§6.3 used to say "expiry in `exp`",
+    # contradicting §4.3; corrected 2026-08-23.)
+    #
+    # ## Why refresh early rather than on expiry
+    #
+    # Refreshing at ~80% of the token's life means a request never carries a credential that
+    # expires mid-flight. Waiting for expiry guarantees the opposite: the first request after
+    # the deadline fails, and on a non-idempotent call — an invoice submission — a failure
+    # that *might* have been delivered is exactly the situation this gem works hardest to
+    # avoid (DESIGN.md §6.7).
+    #
+    # ## Thread safety
+    #
+    # A `Ksef::Client` is shareable across threads (DESIGN.md §5.2), so this is the piece
+    # that has to be safe: one mutex guards the pair, and the staleness check is re-run
+    # inside the lock so a burst of threads produces one refresh rather than a stampede.
+    #
+    # **Not in scope here:** the 401 refresh-and-replay of §6.3. That needs to see the
+    # response, so it belongs to the HTTP layer; this class only refreshes on time.
+    class AccessToken
+      REDACTED = "[REDACTED]"
+
+      # Fraction of the access token's observed lifetime after which it is considered stale.
+      # "~80%" per §6.3 — the docs describe the lifetime only as "kilkanaście minut", so a
+      # proportion travels better than a fixed number of seconds.
+      REFRESH_THRESHOLD = 0.8
+
+      # @param tokens [Tokens] the pair from `POST /auth/token/redeem`
+      # @param client [Client] used for `POST /auth/token/refresh`
+      # @param clock [#call] injected for tests; returns the current {Time}
+      # @param threshold [Float] override for {REFRESH_THRESHOLD}
+      def initialize(tokens, client:, clock: -> { Time.now }, threshold: REFRESH_THRESHOLD)
+        @client = client
+        @clock = clock
+        @threshold = threshold
+        @mutex = Mutex.new
+        @access = tokens.access_token
+        @refresh = tokens.refresh_token
+        # The issue time is not in the response, so the lifetime is measured from when we
+        # took delivery. That can only *under*-estimate the remaining life, which errs the
+        # safe way: we refresh slightly early rather than slightly late.
+        @acquired_at = @clock.call
+      end
+
+      # The bearer string for an `Authorization` header, refreshing first if the token has
+      # gone stale.
+      #
+      # **This may perform a network call** — deliberately named `#bearer` rather than
+      # `#token` so that is not a surprise at the call site.
+      #
+      # @return [String]
+      # `@access.nil?` is not a paranoid guard: `TokenInfo.from(nil)` returns nil, so a
+      # redeem response missing its `accessToken` produces a pair with no token at all.
+      # Without this arm that state reaches `nil.token` and reports `NoMethodError` from
+      # deep inside the client, instead of saying the credential is unusable.
+      def bearer
+        @mutex.synchronize do
+          renew! if @access.nil? || stale_unlocked?
+          @access.token
+        end
+      end
+
+      # Forces a refresh regardless of staleness.
+      #
+      # @return [self]
+      def refresh!
+        @mutex.synchronize { renew! }
+        self
+      end
+
+      # @return [Time, nil] when the current access token stops being valid
+      def valid_until = @access&.valid_until
+
+      def expired?(now = @clock.call) = @access.nil? || @access.expired?(now)
+
+      # True once the token is past {REFRESH_THRESHOLD} of its observed lifetime.
+      #
+      # False when the lifetime cannot be established, which is the conservative answer: a
+      # `validUntil` we could not parse is no reason to spend a refresh, and a genuinely
+      # expired token still surfaces as a 401 from the API.
+      def stale?(now = @clock.call)
+        deadline = refresh_deadline
+        !deadline.nil? && now >= deadline
+      end
+
+      # The refresh token is valid up to seven days and is reusable (§4.2). Once it lapses
+      # there is no way back but a full re-authentication.
+      def refresh_token_expired?(now = @clock.call) = @refresh.nil? || @refresh.expired?(now)
+
+      # Both redacted, `#to_s` included: these are live credentials, and interpolating one
+      # into a log line is how they escape (DESIGN.md §4.5).
+      def to_s = REDACTED
+
+      def inspect
+        "#<Ksef::Auth::AccessToken token=#{REDACTED} valid_until=#{valid_until.inspect} " \
+          "stale=#{stale?} refresh=#{REDACTED}>"
+      end
+
+      private
+
+      # Callers hold the mutex, and it is the *caller* that decides whether a refresh is
+      # wanted: {#bearer} asks only when stale, {#refresh!} always. Guarding staleness in
+      # here as well would silently make `refresh!` conditional, which is not what it says.
+      #
+      # The stampede protection lives in {#bearer} instead, and works because the check
+      # happens inside the lock: the first thread through refreshes, `@acquired_at` moves,
+      # and every thread behind it sees a fresh token.
+      def renew!
+        if refresh_token_expired?
+          raise AuthenticationError,
+                "The refresh token expired at #{@refresh&.valid_until.inspect}, so the access token " \
+                "cannot be renewed. Re-authenticate from the challenge (docs/REFERENCE.md §4.2)."
+        end
+
+        @access = @client.refresh(refresh_token: @refresh.token)
+        @acquired_at = @clock.call
+      end
+
+      def stale_unlocked?
+        deadline = refresh_deadline
+        !deadline.nil? && @clock.call >= deadline
+      end
+
+      # `nil` when the lifetime is unknowable — no token, or no parsed `validUntil`.
+      def refresh_deadline
+        return nil if @access.nil?
+
+        expiry = @access.valid_until
+        return nil if expiry.nil?
+
+        lifetime = expiry - @acquired_at
+        return @acquired_at if lifetime <= 0
+
+        @acquired_at + (lifetime * @threshold)
+      end
+    end
+  end
+end