Changelog

All notable changes to this project will be documented in this file.

[0.12.0] - 2026-08-31

Added

• Invoice and receipt PDF export — render KSeF invoices and their official UPO receipts to print-ready PDF documents offline, with Polish, English, or bilingual labels, an embedded KSeF verification code, and a choice of ready-made layouts or your own custom templates, also available from the command line.
• Optional PDF engine, kept out of the core install — PDF rendering relies on an optional add-on that is not pulled in automatically, so installing the library adds no extra dependencies until you opt into PDF output.

Fixed

[0.11.0] - 2026-08-27

Changed (breaking)

• Rate-limit overrides now require a collective identifier category — KSeF made this category mandatory, so requests that configure test-environment rate limits must supply it or be rejected (KSeF API v2.7.0).
• Session limits now include a collective identifier section — KSeF made this section mandatory when overriding session limits, so callers must now supply a maximum invoice count for collective identifiers alongside the online and batch session limits; requests without it are rejected by KSeF (KSeF API v2.7.1).

Added

• Export packages report their archive format — an export result now states whether the package came back as a Zip or a TarGz archive, so callers no longer have to assume which format to unpack (KSeF API v2.7.1).
• Collective identifiers — group invoices issued by one seller under a single collective identifier so a buyer can settle the whole batch against one payment reference. Generate identifiers, list them for the current context, look up which identifiers an invoice belongs to, and list the invoices inside up to ten identifiers at once, from both the library and the CLI (KSeF API v2.7.1).

Changed

• Updated to KSeF API v2.7.1 — the bundled API specification now tracks the current KSeF release.

[0.10.0] - 2026-06-15

Changed (breaking)

• Node.js-specific features moved to a separate entry point — filesystem-dependent and other Node-only features are no longer exported from the main ksef-client-ts entry point, to improve portability and reduce bundle size for web/edge environments. They are now available via ksef-client-ts/node; see the v0.10 migration guide for the affected exports and how to update imports.

Changed

• Smaller core bundle — certificate-based authentication now loads its cryptographic signing modules on demand instead of bundling them upfront, reducing the core bundle size. This is transparent to callers; the public API is unchanged.

[0.9.1] - 2026-06-13

Changed

• Updated to KSeF API v2.6.1 — the bundled API specification now tracks the current KSeF release; no changes to existing requests or responses.

Added

• Certificate serial number validation — retrieving certificates by serial now rejects malformed values with a clear error before the request reaches KSeF.
• Complete invoice metadata queries — a new paging helper reads metadata query results of any size, automatically crossing the server's result cap so large date ranges no longer silently drop the tail.

Fixed

• Clearer authentication failures — failed authentication now reports the reason from KSeF.

[0.9.0] - 2026-05-24

Changed (breaking)

• Removed the deprecated RR invoice form type — use FA_RR for farmer invoices instead (KSeF API v2.5.0).
• Renamed the farmer-invoice validation schema identifier — RR1_V11E is now FA_RR1, and the obsolete RR1_V10E variant was dropped.

Added

• Encryption key rotation — authentication, sessions, and exports keep working automatically across KSeF public-key rotations (KSeF API v2.5.0).
• TarGz compression — batch uploads and invoice exports can optionally use better-compressing TarGz archives, with ZIP remaining the default (KSeF API v2.6.0).
• System warnings — non-fatal technical warnings returned by KSeF are now surfaced to the application (KSeF API v2.6.0).

Changed

• Authentication request schema 2.1 — the signed authentication request now uses the current KSeF auth token schema; no action needed for existing callers (KSeF API v2.5.0).

Fixed

[0.8.0] - 2026-04-23

Changed (breaking)

• Low-level crypto helpers are now asynchronous — high-level authentication, session, and CLI flows are unaffected; programmatic callers of the low-level crypto helpers must now await them.

Fixed

• Deno / edge-runtime compatibility — token authentication and session encryption now work on Deno-based runtimes (notably Supabase Edge Functions) without any runtime workarounds.

[0.7.1] - 2026-04-22

Added

• Opt-in HTTP circuit breaker — pauses outgoing requests for a cooldown window after consecutive upstream failures, preventing retry storms during KSeF outages and resuming automatically once the service recovers.
• CLI invoice builder — generate valid KSeF invoice XML from JSON or YAML input, with optional schema and XSD validation and starter templates for FA2, FA3, PEF and PEF_KOR.

Fixed

• ECDSA signing digest matches key curve — XAdES signatures produced with an ECDSA key on curve P-384 or P-521 now use the matching SHA-384 / SHA-512 digest, so signatures verify against strict XAdES validators.
• Encrypted private keys for QR verification — signing a KOD II certificate verification URL now accepts password-protected PEM private keys, matching behavior already available for XAdES signing.

[0.7.0] - 2026-04-19

Added

• Invoice XML serialization — generate valid KSeF invoice XML (FA2, FA3, PEF, PEF_KOR) directly from typed application data, with XSD-compliant element ordering handled automatically (KSeF API v2.4.0).
• Stricter invoice XML validation — invoices containing XML processing instructions or characters discouraged by the W3C XML specification are now rejected client-side with precise offsets, matching server-side rules enforced on the KSeF production environment from 2026-07-16 (KSeF API v2.4.0).
• Structured 400 validation errors — KSeF server-side validation failures now expose the full list of error codes and descriptions instead of a single flat message (KSeF API v2.4.0).
• Richer rate-limit errors — applications now receive clearer retry guidance and full server diagnostic context when requests are throttled (KSeF API v2.4.0).
• Typed 403 permission context — forbidden errors now expose structured required/present permission lists for easier troubleshooting.
• Safer server-error handling — applications can handle every documented Problem Details response with compile-time exhaustiveness checks.
• One-step self-revoke — a new CLI command revokes the token used for the current login and clears local state in a single step (KSeF API v2.4.0).
• Subunit permission filtering — VAT-group users can narrow personal and entity permission queries to a specific member subunit (KSeF API v2.2.0).

Changed

• Unified error hierarchy — all server HTTP errors now share a common base class, so one catch branch can handle every server-returned failure.
• Problem Details responses — the client requests structured error responses by default while preserving compatibility with legacy error bodies.
• Richer CLI error output — the CLI now prints the full server-side diagnostic context for every failure and can emit structured payloads for machine consumption.
• Cached token reference in local credentials — logging in with a long-lived token now caches its reference so self-revoke works in one step without an extra lookup.

Fixed

[0.6.2] - 2026-04-12

Added

• KSeF API v2.4.0 support — aligned with the latest KSeF API contract; see the dedicated entries below for the user-facing changes (KSeF API v2.4.0).
• Negative amounts in invoice queries — invoice metadata queries now accept negative amount filters to target corrective invoices and refunds (KSeF API v2.3.0).
• Client IP in login result — login results expose the client IP observed by KSeF so callers can populate authorization policies on future auth requests (KSeF API v2.2.0).
• Batch timeout handling — batch-session timeouts are now reported distinctly from other failures so callers can apply timeout-specific recovery logic (KSeF API v2.0.0).
• Introspection token permission — KSeF tokens can be issued with the Introspection permission for session history browsing and UPO generation (KSeF API v2.1.2).
• Retention-expired operations — polling an aged-out async operation now returns a clear retention-expiry response instead of a generic failure (KSeF API v2.4.0).
• Timestamp on auth errors — authentication and authorization errors now expose the server-recorded UTC timestamp, making it easier to correlate errors with server logs (KSeF API v2.4.0).

Changed

• Session list shows last activity — session listings now display the last-update timestamp alongside the creation date, making it easier to spot stale sessions (KSeF API v2.0.0).
• Documented v2.4.0 export rate limits — invoice export rate limits were increased server-side in KSeF API v2.4.0; the rate-limit guide reflects the new ceilings for users who configure client-side back-pressure.

Fixed

[0.6.1] - 2026-04-06

Added

• Session state serialization — online sessions can be saved to JSON and restored across process restarts for fault-tolerant invoice sending.
• File hash verification — downloaded invoices and export parts are verified against SHA-256 checksums to detect corruption or tampering. Enabled by default for exports (opt out with verifyHash: false).
• Parallel batch upload — batch parts can be uploaded concurrently with a configurable concurrency limit (CLI: --parallelism).
• Documentation — added a Polish Holidays reference page.

Fixed

• Batch upload error detection — presigned URL upload errors are now surfaced correctly instead of being silently ignored.
• Polish holidays in deadline calculation — business-day calculations now correctly account for all 14 Polish statutory holidays (since 2025), not just weekends.

[0.6.0] - 2026-04-05

Added

• Offline invoice mode — full lifecycle for offline invoices: generate locally with QR KOD I + KOD II codes, store in ~/.ksef/offline/, track submission deadlines, submit to KSeF when available. Supports all 4 KSeF offline modes (offline24, offline, awaryjny, awaria_calkowita) with business day deadline calculation and maintenance window cascading.
• Technical correction — resubmit rejected offline invoices with automatic hash-based linking to the original.
• CLI ksef offline — 6 subcommands: generate, list, status, submit, correct, delete for managing offline invoices from the terminal.
• CLI ksef qr invoice --offline — generates KOD I QR with "OFFLINE" label for SVG output.
• Documentation — new VitePress page: Offline Mode.

[0.5.2] - 2026-04-05

Added

• Batch invoice validation — --validate flag now works for directory batch sends in CLI and validate option in programmatic uploadBatch(). Invalid invoices are caught before upload with per-file error reporting.
• OnlyMetadata export — --onlyMetadata flag for invoice export and invoice export-incremental CLI commands to download metadata without invoice XML files.
• SCHEMA_TYPES runtime array — exported list of all valid schema type identifiers for runtime use.

Fixed

• Strict Invoice validation — unknown XML elements not defined in KSeF schemas now rejected client-side instead of silently passing through to KSeF (error 450).

[0.5.1] - 2026-03-30

Added

• Interactive setup wizard — ksef setup guides users through NIP configuration, authentication, and optional API token generation in a single interactive session. Supports self-signed certificate quick auth on the test environment and external signature flow for demo/production.
• Credentials store — persistent storage for long-lived API tokens in ~/.ksef/credentials.json, separate from session and config files. Tokens saved during setup or manually are automatically used by ksef auth login as a fallback when --token is not provided.
• Cross-platform folder opener — ksef setup opens the ~/.ksef/ folder in the system file manager during external signing to streamline the workflow.
• Automatic session recovery — all CLI commands automatically restore expired sessions by refreshing the token or re-authenticating with stored credentials. No more manual ksef auth login after session expiry.
• Future invoice date validation — invoice validator now rejects P_1 (invoice issue date) set in the future, which KSeF silently rejects with a 445 error.

Fixed

• Encryption key mismatch on invoice send — ksef session open and ksef invoice send each generated independent AES-256 keys, causing KSeF to reject every invoice with status 445. Encryption keys are now persisted in the session store and reused across commands.

[0.5.0] - 2026-03-29

Added

• Invoice XML validation — client-side validation of invoice XML against official KSeF XSD schemas before submission. Three levels: XML well-formedness, Zod schema validation (generated from XSD at build time), and business rules (NIP/PESEL checksums). Auto-detects schema type from XML namespace. Supports all 6 invoice types (FA2, FA3, PEF3, PEF_KOR3, RR v1-0E, RR v1-1E). Available via ksef invoice validate CLI command, programmatic validate() API, and opt-in --validate flag on ksef invoice send.
• Official XSD invoice schemas — all KSeF invoice XSD schemas (FA, PEF, RR) bundled in docs/schemas/ with yarn sync-schemas to update from the official Ministry of Finance repository.
• Encrypted PEM key support — --key-password option for ksef auth login to use encrypted PEM private keys without manual decryption.
• whoami identity context — ksef auth whoami now displays NIP, auth method, permissions, and token type parsed from the JWT access token. Full context available in --json mode.
• Advanced E2E scenarios — RR invoicing (FA-RR agricultural invoice lifecycle), self-invoicing (buyer-seller cross-entity flow with seller verification), enforcement operations, technical corrections, incremental export with HWM, and duplicate invoice detection.

Changed

• Default form code switched to FA(3) — CLI commands, workflows, and E2E tests now default to FA(3), the invoice schema required by KSeF on DEMO and PROD since February 2026. FA(2) remains available via --form-code FA2 for backward compatibility.
• CLI defaults to PROD environment — ksef commands now target the production KSeF API when --env is not specified. Use --env test or ksef config set --env test for development. The library (KSeFClient) still defaults to TEST as a safety measure.

Fixed

• CLI date format — --from and --to date arguments in invoice query, invoice export, and invoice export-incremental are now normalized to full ISO-8601 datetime, fixing HTTP 400 errors when using short YYYY-MM-DD format.

[0.4.0] - 2026-03-28

Added

• External signing support — buildUnsignedAuthTokenRequestXml() generates unsigned KSeF auth XML for external signing (HSM, EPUAP, smart cards). Supports all 4 context identifier types. Includes authenticateWithExternalSignature() callback-based workflow and CLI ksef auth login-external with two-phase --generate / --submit flow.
• Multiple document structures — SystemCode enum (FA v2/v3, PEF, PEF_KOR, FA_RR), typed FORM_CODES constants (7 variants), session-type constrained unions, helper functions (getFormCode, parseFormCode, validateFormCodeForSession), InvoiceType mapping per document type. CLI --form-code option on ksef session open and ksef invoice send with PEF batch rejection.
• Stream-based batch upload — uploadBatchStream() workflow with constant memory usage via Web Streams API. Stream-based AES-256-CBC encryption, SHA-256 hashing, and ZIP splitting with two-pass stream factory pattern. Sequential part upload for O(max_part_size) memory. CLI --stream flag on ksef invoice send for .zip files.
• Incremental export (HWM) — iterative export of invoices with automatic high-water-mark tracking. Resumes from the last processed date across runs, handles truncated results with multiple iterations, and saves state to a JSON file for reliable long-running syncs. Includes CLI command and pluggable storage for custom integrations.
• UPO XML parsing — parse official KSeF receipt confirmations (UPO) into structured typed objects. Supports all authentication context variants and multi-document session receipts. Integrated into online and batch session workflows, with --parsed CLI option for JSON output.
• ZIP bomb protection — safe unzip() / createZip() with configurable limits (file count, total/per-file size, compression ratio). Export workflow supports opt-in extraction via extract option.
• Documentation — 6 new VitePress pages: Workflows, Batch Processing, HTTP Resilience, Cryptography, QR Codes, Validation & Data Integrity.
• E2E test expansion — 6 new E2E tests across 4 files

Changed

• TBD

Fixed

• Incremental export decryption — incrementalExportAndDownload used its own AES key instead of the one from doExport, causing bad decrypt on downloaded parts.
• DEFAULT_FORM_CODE — systemCode/schemaVersion/value fields were swapped in both workflow files; corrected to match OpenAPI spec (FA (2) / 1-0E / FA).
• CLI version — ksef --version was hardcoded to 0.1.0; now reads from package.json at runtime.

[0.3.0] - 2026-03-25

Added

• Test data environment guard — TestDataService now throws KSeFError when called on DEMO or PROD environments.
• Batch auto-split — BatchFileBuilder automatically splits large ZIP files into parts (100 MB default), encrypts each part with AES-256-CBC, and computes SHA-256 hashes.
• E2E test coverage expansion — 5 new E2E test suites: test-data limits & attachments, workflow auth, online session workflow, invoice export workflow, error handling. Existing suites extended with additional assertions.

Changed

• uploadBatch() API — now accepts raw Uint8Array ZIP data instead of separate encryption parameters. Encryption, splitting, and hash computation are handled internally by BatchFileBuilder.

Fixed

• Export workflow — exportAndDownload() now correctly initializes crypto before decrypting parts.
• Session polling — waitForUpo() now checks for terminal status codes (200 or >=400) instead of just "not 100".

[0.2.0] - 2026-03-22

Added

• Workflows — high-level orchestration functions for multi-step KSeF operations:
  • openOnlineSession() / openSendAndClose() — online session: open, send invoices, close, poll UPO.
  • uploadBatch() — batch session: open, upload parts, close, poll UPO.
  • exportInvoices() / exportAndDownload() — invoice export: initiate, poll status, download and decrypt parts.
  • authenticateWithToken() / authenticateWithCertificate() / authenticateWithPkcs12() — full auth flow orchestration.
  • Shared pollUntil() utility extracted from E2E helpers.
• UPO versioning — type-safe UpoVersion constants (V4_2, V4_3) and KSEF_FEATURE_HEADER for X-KSeF-Feature header support on session open requests.
• XAdES compliance header — enforceXadesCompliance parameter on AuthService.submitXadesAuthRequest() with ENFORCE_XADES_COMPLIANCE constant.
• KSeF number CRC-8 validation — isValidKsefNumber() now verifies CRC-8 checksum (polynomial 0x07) per official KSeF spec. New isValidKsefNumberV35() and isValidKsefNumberV36() validators for version-specific formats.

Fixed

• Added missing context-type-not-allowed literal to ForbiddenReasonCode type union (aligns with OpenAPI spec).

[0.1.1] - 2026-03-22

Added

• PKCS#12 authentication support (src/crypto/pkcs12-loader.ts) for certificate-based login.
• Full E2E test suite — 13 base suites + 5 permission suites (18 files total), zero secrets in code.
• E2E test helpers: auth, env, identifiers, invoices, polling; FA2/FA3 invoice fixtures.
• scripts/check-openapi-coverage.mjs to validate OpenAPI spec coverage.
• scripts/whoami.ts diagnostic script.
• GitHub Actions: release.yml (automated releases from v* tags), e2e.yml (E2E tests).
• E2E test documentation (docs/e2e-tests.md).
• Installation instructions in README.

Changed

• Updated OpenAPI source to KSeF API version 2.3.0.
• Renamed PRD environment to PROD across the codebase.
• Aligned TestData service with OpenAPI spec — methods return void instead of OperationStatusInfo.
• Refactored status handling and type definitions across services.
• Updated invoice types: replaced deprecated RR usage with FA_RR.
• Improved NIP/PESEL validation patterns.
• Updated bearer auth scheme casing in the OpenAPI definition.

[0.1.0] - 2026-03-22

Added

• Initial public release of ksef-client-ts on npm.
• OpenAPI source to KSeF API version 2.2.1
• TypeScript client for KSeF API v2 with typed models and service-based API.
• Dual ESM/CJS build output with generated type declarations.
• Built-in CLI (ksef) with command groups for common KSeF operations.
• Documentation site powered by VitePress.

Info

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Format:

## [{VERSION}] - {DATE}

### Added
- TBD
### Changed
- TBD
### Fixed
- TBD