feat: FA(3) typed SDK, CLI session checkpoints, and workflow extensions

.github/workflows/ci.yml

@@ -73,20 +73,25 @@ jobs:
           cache: npm
           cache-dependency-path: package-lock.json
 
+      - name: Install native build deps for optional libxmljs2
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev
+
       - name: Install dependencies
         run: npm ci
 
+      - name: Install optional libxmljs2 for XSD coverage
+        run: npm install libxmljs2 --no-save
+
       - name: Build package
         run: npm run build
 
       - name: Run tests with coverage
         run: >
-          NODE_OPTIONS=--enable-source-maps npm exec -- c8 --reporter=text-summary --reporter=text --reporter=lcov --reporter=html
+          NODE_OPTIONS=--enable-source-maps npm exec -- c8 --exclude-after-remap
+          --check-coverage --lines 100 --branches 100 --functions 100 --statements 100
+          --reporter=text-summary --reporter=text --reporter=lcov --reporter=html
           sh -lc 'node --test $(find test/unit -name "*.test.js" ! -name "cliArgs.test.js" ! -name "cliTokenStore.test.js" -print) test/e2e/*.test.js'
 
-      - name: Enforce coverage threshold
-        run: npm exec -- c8 check-coverage --statements 100 --branches 100 --functions 100 --lines 100
-
       - name: Upload coverage artifact
         uses: actions/upload-artifact@v4
         with:

README.md

@@ -5,11 +5,11 @@ Biblioteka udostępnia typowane klienty endpointów, gotowe workflowy (auth/sesj
 
 ## Kompatybilność
 
-- KSeF API: `v2.4.0`
+- KSeF API: `v2.6.0`
 - Node.js: `>= 20`
 - Środowiska: `TEST`, `DEMO`, `PRD`
 
-KSeF `2.4.0` rozszerza obsługę błędów o `application/problem+json` oraz doprecyzowuje operacje
+KSeF `2.6.0` obejmuje obsługę `application/problem+json`, doprecyzowane operacje
 na tokenie użytym do bieżącego uwierzytelnienia. SDK zachowuje dotychczasowe metody klientów,
 a bogatszy format błędów możesz wymusić przez nagłówek
 `X-Error-Format: problem-details` ustawiony w `KsefClientOptions.headers`.
@@ -23,11 +23,12 @@ npm install ksef-client
 Opcjonalne zależności:
 
 ```bash
-npm install qrcode node-forge
+npm install qrcode node-forge libxmljs2
 ```
 
 - `qrcode` jest wymagane dla `client.qr`
 - `node-forge` jest wymagane dla `XadesKeyPair.fromPkcs12*`
+- `libxmljs2` jest wymagane tylko dla runtime walidacji `FA3Draft.toXml({ xsdValidate: true })`; schematy FA(3) są pakowane z biblioteką
 
 ## Quick Start
 

docs/README.md

@@ -4,7 +4,7 @@ Dokumentacja opisuje publiczne API biblioteki `ksef-client-typescript` oraz goto
 
 Kontrakt API (OpenAPI), dokumenty procesowe i ograniczenia systemu znajdują się w `ksef-docs/`.
 
-Kompatybilność SDK: **KSeF API `v2.4.0`**.
+Kompatybilność SDK: **KSeF API `v2.6.0`**.
 
 ## Status parity
 
@@ -16,6 +16,7 @@ Aktualny status zgodności SDK względem `ksef-docs` znajdziesz w raporcie:
 - Node.js `>= 20`
 - dostęp do środowiska KSeF (`TEST`, `DEMO`, `PRD`)
 - dane uwierzytelniające (token KSeF lub certyfikat/XAdES)
+- opcjonalnie `qrcode`, `node-forge` i `libxmljs2` dla QR, PKCS#12/XAdES i runtime walidacji XSD FA(3)
 
 ## Instalacja (lokalnie)
 

docs/api/tokens.md

@@ -21,9 +21,9 @@ Token KSeF możesz wykorzystać np. w autoryzacji przez `authenticateWithKsefTok
   `"InvoiceRead"`, `"InvoiceWrite"`, `"CredentialsRead"`, `"CredentialsManage"`, `"SubunitManage"`,
   `"EnforcementOperations"`, `"Introspection"`.
 - Stronicowanie listy tokenów działa przez nagłówek `x-continuation-token` (potwierdzone testami jednostkowymi).
-- Od KSeF API `2.4.0` `GET /tokens` może zwrócić także informacje o tokenie użytym do bieżącego
+- Od KSeF API `2.6.0` `GET /tokens` może zwrócić także informacje o tokenie użytym do bieżącego
   uwierzytelnienia, nawet bez `CredentialsManage` / `CredentialsRead`.
-- Od KSeF API `2.4.0` `GET /tokens/{referenceNumber}` oraz `DELETE /tokens/{referenceNumber}`
+- Od KSeF API `2.6.0` `GET /tokens/{referenceNumber}` oraz `DELETE /tokens/{referenceNumber}`
   mogą dotyczyć bieżącego tokenu uwierzytelniającego również bez dodatkowego uprawnienia
   `CredentialsManage`.
 

docs/cli/README.md

@@ -36,6 +36,33 @@ Podstawowe uzycie CLI:
 node dist/cli/index.js --help
 ```
 
+## Session checkpoints (resume)
+
+CLI wspiera zapisywalne checkpointy sesji online/batch:
+
+```bash
+# online
+node dist/cli/index.js --json session online open --id demo-online --form-code FA3
+node dist/cli/index.js --json session online send --id demo-online --invoice-file ./invoice.xml --wait-status
+node dist/cli/index.js --json session online close --id demo-online
+
+# batch
+node dist/cli/index.js --json session batch open --id demo-batch --dir ./invoices
+node dist/cli/index.js --json session batch upload --id demo-batch --parallelism 4
+node dist/cli/index.js --json session batch close --id demo-batch --wait-status --wait-upo
+```
+
+Operacje na zapisanych checkpointach:
+
+```bash
+node dist/cli/index.js --json session list
+node dist/cli/index.js --json session show --id demo-online
+node dist/cli/index.js --json session status --id demo-online --invoice-ref INV-1
+node dist/cli/index.js --json session export --id demo-online --out ./artifacts/
+node dist/cli/index.js --json session import --in ./artifacts/session-demo-online.json --id demo-online-copy
+node dist/cli/index.js --json session drop --id demo-online
+```
+
 ## Wskazowki
 
 - `src/types/openapi.generated.ts` jest plikiem generowanym; nie edytuj go recznie.

docs/configuration.md

@@ -8,7 +8,7 @@ Konfiguracja dotyczy zarówno `new KsefClient(...)`, jak i `KsefClient.connect(.
 - gdy ustawisz `baseUrl` bez sufiksu `/v2`, biblioteka automatycznie doda `/v2` (chyba ze `appendV2: false`),
 - `KsefClient.connect(...)` rozszerza `KsefClientOptions` o opcje potrzebne do logowania tokenem KSeF,
 - `headers` są globalne i trafiają do wszystkich requestów klienta, także do requestów na pre-signed URL (upload/download), więc nie należy umieszczać tam `Authorization`.
-- dla KSeF `2.4.0` możesz przez `headers` włączyć `X-Error-Format: problem-details`, aby otrzymywać bogatsze odpowiedzi błędów dla `400` i `429`.
+- dla KSeF `2.6.0` możesz przez `headers` włączyć `X-Error-Format: problem-details`, aby otrzymywać bogatsze odpowiedzi błędów dla `400` i `429`.
 
 ## `KsefClientOptions`
 

docs/errors.md

@@ -14,7 +14,7 @@ SDK mapuje błędy HTTP i błędy walidacji na dedykowane klasy wyjątków.
 | `KsefSessionExpiredError` | Brak tokena dostępowego lub nieudane odświeżenie sesji.                         | `message`                                     |
 | `KsefValidationError`     | Błąd lokalnej walidacji danych wejściowych.                                     | `message`, `details`                          |
 
-## `problem` i KSeF API `2.4.0`
+## `problem` i KSeF API `2.6.0`
 
 Przy odpowiedziach JSON SDK próbuje zmapować `error.problem` do jednego z modeli:
 
@@ -27,7 +27,7 @@ Przy odpowiedziach JSON SDK próbuje zmapować `error.problem` do jednego z mode
 - fallback `UnknownApiProblem`, gdy JSON nie pasuje do znanego modelu
 
 Mapowanie do konkretnego typed modelu następuje tylko wtedy, gdy payload spełnia wymagane pola
-kontraktu `ksef-docs 2.4.0`. Przy częściowym albo niepoprawnym `problem+json` SDK zachowuje
+kontraktu `ksef-docs 2.6.0`. Przy częściowym albo niepoprawnym `problem+json` SDK zachowuje
 `responseBody`, a `error.problem` przechodzi do `UnknownApiProblem`.
 
 `410 Gone` może pojawić się po wygaśnięciu retencji technicznych statusów operacji asynchronicznych

docs/examples/README.md

@@ -245,3 +245,10 @@ await client.testdata.unblockContext({
 - Workflowy i scenariusze: [../workflows/README.md](../workflows/README.md)
 - API reference: [../api/README.md](../api/README.md)
 - Błędy i retry: [../errors.md](../errors.md)
+- FA(3) typed SDK examples: [./fa3-typed-sdk.md](./fa3-typed-sdk.md)
+
+## Kontrakt FA(3) typed SDK
+
+- Publiczne API FA(3) jest utrzymywane jako lokalny kontrakt TypeScript z testami jednostkowymi.
+- Runtime walidacji `xsdValidate` korzysta ze schematów pakowanych w `dist`; do samej walidacji XSD potrzebna jest opcjonalna zależność `libxmljs2`.
+- Przykłady FA(3) znajdują się w [`fa3-typed-sdk.md`](./fa3-typed-sdk.md).

docs/examples/fa3-typed-sdk.md

@@ -0,0 +1,93 @@
+# FA(3) typed SDK examples
+
+Typed SDK FA(3) działa samodzielnie w repo TypeScript. Schematy XSD są pakowane do `dist`, a runtime
+walidacji `toXml({ xsdValidate: true })` wymaga opcjonalnej zależności `libxmljs2`.
+
+## Single invoice
+
+```ts
+import { FA3Invoice } from "ksef-client";
+
+const draft = FA3Invoice.basic("FV/1")
+  .issueDate("2026-05-18T10:00:00Z")
+  .seller({ name: "Sprzedawca", taxId: "1111111111" })
+  .buyer({ name: "Nabywca", taxId: "2222222222" })
+  .addLine({
+    description: "Usługa",
+    quantity: 1,
+    unit: "szt",
+    unitNetPrice: 100,
+    vatRate: 23,
+  })
+  .build();
+
+const xml = await draft.toXml({ xsdValidate: true });
+```
+
+## Correction before/after
+
+```ts
+import { FA3Invoice } from "ksef-client";
+
+const correction = FA3Invoice.correction("KOR/1")
+  .issueDate("2026-05-18T10:00:00Z")
+  .seller({ name: "Sprzedawca", taxId: "1111111111" })
+  .buyer({ name: "Nabywca", taxId: "2222222222" })
+  .correction({
+    reason: "Korekta ceny",
+    correctedInvoiceNumber: "FV/OLD/1",
+    correctedInvoiceDate: "2026-05-01",
+  })
+  .addCorrectedLineBeforeAfter({
+    before: { description: "Usługa", quantity: 1, unit: "szt", unitNetPrice: 200, vatRate: 23 },
+    after: { description: "Usługa", quantity: 1, unit: "szt", unitNetPrice: 100, vatRate: 23 },
+  })
+  .build();
+
+const correctionXml = await correction.toXml();
+```
+
+## Settlement invoice
+
+```ts
+import { FA3Invoice } from "ksef-client";
+
+const settlement = FA3Invoice.settlement("ROZ/1")
+  .issueDate("2026-05-18T10:00:00Z")
+  .seller({ name: "Sprzedawca", taxId: "1111111111" })
+  .buyer({ name: "Nabywca", taxId: "2222222222" })
+  .advanceReference({ invoiceNumber: "FV/ZAL/1" })
+  .addServiceLine("Usługa", { quantity: 1, unitNetPrice: 100, vatRate: 23 })
+  .settlementDetails({
+    amountDue: "125.00",
+    charges: [{ amount: "3.00", reason: "Dopłata" }],
+    deductions: [{ amount: "1.00", reason: "Rabat" }],
+  })
+  .build();
+
+const settlementXml = await settlement.toXml();
+```
+
+## JSON roundtrip
+
+```ts
+import { FA3BatchDraft } from "ksef-client";
+
+const batch = new FA3BatchDraft([draft]);
+const json = batch.toJson();
+const restored = FA3BatchDraft.fromJson(json);
+
+await restored.drafts[0].toXml();
+```
+
+## Batch ZIP flow
+
+```ts
+import { FA3BatchDraft } from "ksef-client";
+
+const batch = new FA3BatchDraft([draftA, draftB]);
+
+await batch.toXmlFiles("./out/fa3");
+await batch.toXmlZip("./out/fa3.zip");
+```
+

docs/maintainers.md

@@ -29,7 +29,7 @@ Uwaga: CI wymaga 100% coverage (statement/branch/function/line).
 
 ## Kontrola zgodności z OpenAPI
 
-Aktualny target kompatybilności repo: **KSeF API `2.4.0`**.
+Aktualny target kompatybilności repo: **KSeF API `2.6.0`**.
 
 Regeneracja modeli:
 

docs/parity-ksef-docs.md

@@ -1,11 +1,11 @@
 # Raport parity: `ksef-client-typescript` vs `ksef-docs`
 
-Data analizy: **2026-04-13**
+Data analizy: **2026-05-26**
 
 ## Zakres i źródła
 
-- Kontrakt API: `ksef-docs/open-api.json` (`2.4.0`)
-- Changelog: `ksef-docs/api-changelog.md` (wersje do `2.4.0`)
+- Kontrakt API: `ksef-docs/open-api.json` (`2.6.0`)
+- Changelog: `ksef-docs/api-changelog.md` (wersje do `2.6.0`)
 - Implementacja TypeScript: `src/api/*`, `src/types/*`, `src/services/*`, `src/client/*`, `docs/*`
 - Weryfikacja dodatkowa: `temp/openapi-test-v2.json` (`https://api-test.ksef.mf.gov.pl/docs/v2/openapi.json`)
 
@@ -16,10 +16,10 @@ Data analizy: **2026-04-13**
 - Nadmiarowe endpointy po stronie TS: **0**
 - Zgodność kontraktu `ksef-docs` vs `api-test`: **zgodna** (po odfiltrowaniu opisów/metadanych)
 
-## Zmiany uwzględnione po stronie SDK (2.4.0)
+## Zmiany uwzględnione po stronie SDK (2.6.0)
 
 1. Modele OpenAPI
-   - odświeżono `src/types/openapi.generated.ts` do `ksef-docs 2.4.0`;
+   - odświeżono `src/types/openapi.generated.ts` do kontraktu `ksef-docs 2.6.0`;
    - liczba schematów wzrosła do `287`;
    - modele obejmują nowe typy `ApiError`, `BadRequestProblemDetails`, `GoneProblemDetails`,
      `TooManyRequestsProblemDetails` oraz pola `timestamp` w `ForbiddenProblemDetails`
@@ -31,12 +31,12 @@ Data analizy: **2026-04-13**
    - `KsefRateLimitError` udostępnia również `retryAfterSeconds`, obok dotychczasowego `retryAfter`.
 
 3. Tokeny KSeF
-   - kontrakt i dokumentacja odzwierciedlają semantykę `2.4.0` dla operacji na bieżącym tokenie
+   - kontrakt i dokumentacja odzwierciedlają semantykę `2.6.0` dla operacji na bieżącym tokenie
      uwierzytelniającym przy `GET /tokens`, `GET /tokens/{referenceNumber}` i
      `DELETE /tokens/{referenceNumber}`.
 
 4. Dokumentacja SDK
-   - deklaracje kompatybilności API w README i `docs/*` wskazują `v2.4.0`;
+   - deklaracje kompatybilności API w README i `docs/*` wskazują `v2.6.0`;
    - dokumentacja opisuje `X-Error-Format: problem-details`, `410 Gone` oraz zaktualizowane
      zachowanie endpointów tokenów.
 
@@ -58,9 +58,9 @@ Data analizy: **2026-04-13**
 
 ## Parity dokumentacji
 
-Dokumentacja TS została uaktualniona do spójności z KSeF `2.4.0`:
+Dokumentacja TS została uaktualniona do spójności z KSeF `2.6.0`:
 
-- deklaracje kompatybilności API (`v2.4.0`) w README i docs,
+- deklaracje kompatybilności API (`v2.6.0`) w README i docs,
 - opis `problem+json` i `X-Error-Format` w dokumentacji błędów i konfiguracji,
 - opis self-token semantics w dokumentacji `tokens`,
 - zaktualizowany raport parity i wyniki walidacji.