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

[smekcio]

Summary

Ten PR domyka duży pakiet prac na gałęzi feat/sdk-workflows-fa3: rozszerzone workflow sesji KSeF, pełny typed SDK FA(3) z walidacją XSD, parytet identyfikatorów stron z Python SDK oraz aktualizację dokumentacji do KSeF API v2.6.0. Branch zawiera 3 commity względem main (~12k linii dodanych w 59 plikach).

Zmiany wg obszaru

1. CLI — checkpointy sesji (resume)

• Nowy sessionStore i komendy session online|batch z zapisywanymi checkpointami (open → send → close).
• Flagi --id, --resume, --json oraz operacje na zapisanych stanach sesji.
• Rozszerzone testy: cliSessionCommands.test.js, cliArgs.test.js, cliInternalsCoverage.test.js.
• Dokumentacja: docs/cli/README.md (sekcja Session checkpoints).

2. Workflow serwisów

• Online session: rozszerzony przepływ wysyłki / domykania sesji.
• Batch session: wsparcie dla wznowień i spójniejsza obsługa partii.
• Export / incremental export / HWM: dopasowania pod nowe scenariusze i testy regresji.
• Nowe/zmienione testy jednostkowe: batchSessionWorkflow, onlineSessionWorkflow, invoiceExportWorkflow, hwmCoordinator, invoiceFiltersValidation.

3. Typed SDK FA(3)

Nowy / rozbudowany moduł src/documents/fa3/:

Moduł	Rola
builder.ts	Fluent API (FA3Invoice, FA3Draft, FA3BatchDraft), mapowanie do XML FA(3)
types.ts	Typy wejściowe faktury, linii, płatności, korekt, rozliczeń
domain.ts	Fabryki domenowe (InvoiceParty, TaxCategory, Address, …)
identifier.ts	PartyIdentifierKind, resolve/validate/map identyfikatorów stron
sections.ts	Zamówienia, transport, załączniki, warunki transakcji
tax.ts	Kategorie VAT i procedury
importer.ts / template.ts	Import XML i szablony
xml.ts / xsd.ts	Runtime walidacji XSD
xsdMap.ts / xsdAudit.ts	Audyt pokrycia schematu
publicApi.ts	Stabilny kontrakt eksportu runtime
schemas/	Osadzone schematy FA(3) v1-0E

Rodzaje faktur: basic, simplified, correction, advance, settlement (+ warianty korekt).

Sekcje XSD: Podmiot1/2/3, płatności, korekty, rozliczenia, zamówienia, transport, załączniki, adnotacje.

Eksport pakietu: subpath ksef-client/documents/fa3 + build kopiuje schematy (scripts/copy-fa3-schemas.mjs, tsup.config.ts).

4. Parytet identyfikatorów stron (jak Python SDK)

• Jawny model PartyIdentifier / PartyIdentifierKind (NIP, EU_VAT, FOREIGN, INTERNAL, NONE).
• InvoiceParty.polishCompany, euCompany, foreignCompany, withoutTaxId ustawiają identifier na stronie.
• Sprzedawca (Podmiot1): tylko NIP — walidacja i serializacja jak w Pythonie (Podmiot1/PodmiotUpowazniony wymaga identyfikatora NIP.).
• Nabywca i Podmiot3: pełne mapowanie (NIP, VAT UE, NrID, BrakID, IDWew).
• Wsteczna kompatybilność: samo pole taxId nadal jest wnioskowane, gdy brak identifier.

5. Walidacja XSD

• libxmljs2 jako optionalDependency — toXml({ xsdValidate: true }) wymaga natywnego modułu.
• Schematy pakowane do dist przy npm run build.
• Testy XSD są skipowane w CI, gdy ABI libxmljs2 nie pasuje do wersji Node (znane ograniczenie).

6. XML / invoice builder

• src/xml/invoice.ts: wsparcie schematu FA(3) obok dotychczasowych formatów.
• Dostosowane testy xmlBuilder, pefXmlBuilder, xmlBuilder.property.

7. Dokumentacja (API v2.6.0)

• README, docs/README.md, docs/parity-ksef-docs.md, docs/api/tokens.md, docs/errors.md, docs/configuration.md, docs/maintainers.md.
• Nowy przewodnik: docs/examples/fa3-typed-sdk.md.
• OpenAPI coverage: 78/78 endpointów względem ksef-docs 2.6.0 (bez zmiany w tym PR — potwierdzone wcześniej na branchu).

8. Testy

• Rozbudowany fa3Sdk.test.js (rodzaje faktur, sekcje, płatności, strony trzecie, korekty, XSD).
• fa3PublicApiParity.test.js — kontrakt publicznego API FA(3) w TS (bez zależności od repo Python).
• Brak check-python-parity — parytet utrzymywany lokalnie przez testy kontraktu i zachowania.

Commity na branchu

1. feat: update workflows and add FA(3) draft SDK
2. feat(cli): add resumable session checkpoint commands and store
3. feat(fa3): complete typed FA(3) SDK with XSD validation and Python parity

Test plan

• npm run build
• npm run typecheck
• npm run lint
• npm run check:openapi-coverage (78/78)
• npm test (testy XSD opcjonalnie skipowane bez kompatybilnego libxmljs2)
• Review ręczny: przykłady z docs/examples/fa3-typed-sdk.md na środowisku testowym KSeF
• (Opcjonalnie) CI z Node + zainstalowanym libxmljs2 dla pełnej walidacji XSD

Uwagi dla reviewerów

• To duży PR funkcjonalny; sensowny podział na mniejsze PR-e był możliwy, ale całość jest spójna tematycznie (FA(3) + sesje + workflow).
• Seller = tylko NIP to zamierzone ograniczenie zgodne z Python SDK i XSD, nie brak funkcji buyer-side.
• Katalog .tmp/ nie jest commitowany (artefakty lokalne).