ksef-client-ts 0.9.0 → 0.10.0

package/README.md

@@ -2,58 +2,18 @@
 
 TypeScript client for the Polish National e-Invoice System (KSeF) API v2.
 
-**[Documentation](https://flopsstuff.github.io/ksef-client-ts)** · **[NPM](https://www.npmjs.com/package/ksef-client-ts)**
-
-## Features
-
-- **Complete API coverage** — KSeF API v2.6.0, types aligned with the official OpenAPI spec
-- **Offline invoice mode** — full lifecycle for all 4 KSeF offline modes with QR KOD I + KOD II signing, deadline tracking, local storage, and technical correction
-- **Full-featured CLI** — `ksef` with 15 command groups for auth, sessions, invoices, offline, batch upload, export, and more
-- **High-level workflows** — auth, online/batch sessions, invoice export — full lifecycle in a single call
-- **Built-in cryptography** — AES-256-CBC, RSA-OAEP, ECDH, XAdES-B signatures, self-signed certs (Node crypto)
-- **External signing** — HSM, EPUAP, and smart card authentication via callback-based signing
-- **Automatic token management** — AuthManager: token injection, 401 refresh with dedup
-- **Opt-in circuit breaker** — pauses outgoing requests for a short cooldown window after consecutive upstream failures
-- **Streaming batch uploads** — constant-memory batch upload via Web Streams API with ZIP bomb protection
-- **Incremental export** — HWM-based paginated export with file-based state persistence
-- **Multiple document structures** — FA, PEF, PEF_KOR, FA_RR with typed FormCode constants and UPO parsing
-- **Invoice XML serialization (FA2/FA3/PEF/PEF_KOR)** — build XSD-compliant invoice XML from typed TypeScript objects with correct element ordering (including the FA3 per-VAT-rate interleave) and namespace injection; `ksef invoice build` exposes the same pipeline to shell workflows with JSON/YAML input and optional XSD validation
-- **Invoice XML validation** — three-level client-side validation (well-formedness, XSD schema via Zod, NIP/PESEL checksums, future date rejection) with auto-detection for all 6 invoice types
-- **Typed errors with RFC 7807 Problem Details** — `KSeFError` hierarchy with dedicated classes for 400/401/403/410/429 carrying structured diagnostic context; exhaustive dispatch via the `KSeFApiProblem` union and `assertNever`; fluent request builders
-- **Comprehensive test coverage** — unit + E2E tests across HTTP, crypto, services, workflows; CI on every change
-- **Interactive setup wizard** — `ksef setup` guides through environment selection, authentication, and token generation in one flow
-- **Zero HTTP dependencies** — native `fetch` (Node 18+); dual ESM/CJS via tsup
-
-Requires **Node.js 18+**.
+**[Documentation](https://flopsstuff.github.io/ksef-client-ts)** · **[GitHub](https://github.com/Flopsstuff/ksef-client-ts)**
 
 ## Install
 
-Install CLI globally:
-
-```bash
-npm i -g ksef-client-ts
-ksef --help
-```
-
-Install in a project:
-
 ```bash
-# Choose one package manager:
-# npm
-npm i ksef-client-ts
-# Yarn
-yarn add ksef-client-ts
-# pnpm
-pnpm add ksef-client-ts
+npm i ksef-client-ts      # library
+npm i -g ksef-client-ts   # ksef CLI
 ```
 
-For local development, clone and build:
+Requires **Node.js 18+**. Dual ESM/CJS output via tsup.
 
-```bash
-git clone https://github.com/Flopsstuff/ksef-client-ts.git
-cd ksef-client-ts
-yarn install && yarn build
-```
+## Quick start
 
 ```ts
 import { KSeFClient } from 'ksef-client-ts';
@@ -62,7 +22,7 @@ const client = new KSeFClient({ environment: 'TEST' });
 await client.crypto.init();
 
 const challenge = await client.auth.getChallenge();
-// ... authenticate, open session, send invoices
+// ... authenticate, open a session, send invoices
 ```
 
 ```bash
@@ -70,38 +30,19 @@ ksef auth login --token "$KSEF_TOKEN" --nip "$KSEF_NIP"
 ksef session open              # 1. Open online session (required)
 ksef invoice send invoice.xml  # 2. Send invoice
 ksef session invoices          # 3. Verify invoice status
-ksef session close             # 4. Close session (optional)
 ```
 
-See the [documentation](https://flopsstuff.github.io/ksef-client-ts) for full usage, [API reference](https://flopsstuff.github.io/ksef-client-ts/api-reference), and [CLI reference](https://flopsstuff.github.io/ksef-client-ts/cli).
-
-## Development
+Node-only helpers (filesystem storage, native XSD validation) are available from the `ksef-client-ts/node` entry point.
 
-```bash
-yarn install      # Install dependencies (yarn 4.x via Corepack)
-yarn build        # Build ESM + CJS + DTS via tsup
-yarn lint         # Type-check (tsc --noEmit)
-yarn test         # Run all tests (vitest)
-```
+## Documentation
 
-## Related
+The full feature list, guides, API and CLI reference, and the v0.10 migration guide live in the **[documentation](https://flopsstuff.github.io/ksef-client-ts)** and the **[GitHub README](https://github.com/Flopsstuff/ksef-client-ts)**:
 
-- [KSeF Web Portal](https://ap.ksef.mf.gov.pl/web/) — official KSeF web application (token management, permissions, invoices)
-- [KSeF official docs](https://github.com/CIRFMF/ksef-docs) — official documentation (Polish)
-- [KSeF docs translated](https://flopsstuff.github.io/ksef-docs/) — translated documentation (EN/RU/UK), [source on GitHub](https://github.com/Flopsstuff/ksef-docs)
-- [ksef-client-csharp](https://github.com/CIRFMF/ksef-client-csharp) — official C# reference client
-- [ksef-client-java](https://github.com/CIRFMF/ksef-client-java) — official Java reference client
+- [Quick start](https://flopsstuff.github.io/ksef-client-ts/quick-start)
+- [API reference](https://flopsstuff.github.io/ksef-client-ts/api-reference)
+- [CLI reference](https://flopsstuff.github.io/ksef-client-ts/cli)
+- [Migration guide (v0.10)](https://flopsstuff.github.io/ksef-client-ts/migration-v0.10)
 
 ## License
 
 [MIT](LICENSE)
-
----
-
-[![Tests](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Fl0p/1558034ac67a11548c7f8f0c05e8d4c0/raw/ksef-client-ts-coverage.json&cacheSeconds=300)
-![NPM Version](https://img.shields.io/npm/v/ksef-client-ts?color=green)
-![NPM Downloads](https://img.shields.io/npm/dm/ksef-client-ts)
-![GitHub Stars](https://img.shields.io/github/stars/Flopsstuff/ksef-client-ts)
-![GitHub Forks](https://img.shields.io/github/forks/Flopsstuff/ksef-client-ts)
-![GitHub License](https://img.shields.io/github/license/Flopsstuff/ksef-client-ts)

package/dist/cli.js

@@ -238,18 +238,21 @@ var init_ksef_bad_request_error = __esm({
 });
 
 // src/errors/ksef-auth-status-error.ts
+var KSeFAuthStatusError;
 var init_ksef_auth_status_error = __esm({
   "src/errors/ksef-auth-status-error.ts"() {
     "use strict";
     init_ksef_error();
-  }
-});
-
-// src/errors/ksef-session-expired-error.ts
-var init_ksef_session_expired_error = __esm({
-  "src/errors/ksef-session-expired-error.ts"() {
-    "use strict";
-    init_ksef_error();
+    KSeFAuthStatusError = class extends KSeFError {
+      referenceNumber;
+      statusDescription;
+      constructor(message, referenceNumber, statusDescription) {
+        super(message);
+        this.name = "KSeFAuthStatusError";
+        this.referenceNumber = referenceNumber;
+        this.statusDescription = statusDescription;
+      }
+    };
   }
 });
 
@@ -397,13 +400,6 @@ var init_ksef_xsd_validation_error = __esm({
   }
 });
 
-// src/errors/assert-never.ts
-var init_assert_never = __esm({
-  "src/errors/assert-never.ts"() {
-    "use strict";
-  }
-});
-
 // src/errors/index.ts
 var init_errors = __esm({
   "src/errors/index.ts"() {
@@ -415,15 +411,7 @@ var init_errors = __esm({
     init_ksef_forbidden_error();
     init_ksef_gone_error();
     init_ksef_bad_request_error();
-    init_ksef_auth_status_error();
-    init_ksef_session_expired_error();
     init_ksef_validation_error();
-    init_ksef_batch_timeout_error();
-    init_ksef_unknown_public_key_error();
-    init_ksef_circuit_open_error();
-    init_ksef_xsd_validation_error();
-    init_error_codes();
-    init_assert_never();
   }
 });
 
@@ -480,7 +468,6 @@ var init_options = __esm({
 var init_config = __esm({
   "src/config/index.ts"() {
     "use strict";
-    init_environments();
     init_options();
   }
 });
@@ -2095,6 +2082,44 @@ var init_tokens = __esm({
   }
 });
 
+// src/validation/patterns.ts
+function isValidNip(value) {
+  if (!Nip.test(value)) return false;
+  let sum = 0;
+  for (let i = 0; i < 9; i++) {
+    sum += Number(value[i]) * NIP_WEIGHTS[i];
+  }
+  const checksum = sum % 11;
+  return checksum !== 10 && checksum === Number(value[9]);
+}
+function isValidPesel(value) {
+  if (!Pesel.test(value)) return false;
+  let sum = 0;
+  for (let i = 0; i < 10; i++) {
+    sum += Number(value[i]) * PESEL_WEIGHTS[i];
+  }
+  const checksum = (10 - sum % 10) % 10;
+  return checksum === Number(value[10]);
+}
+function isValidCertificateSerialNumber(value) {
+  return CertificateSerialNumber.test(value);
+}
+var NIP_PATTERN_CORE, VAT_UE_PATTERN_CORE, Nip, VatUe, NipVatUe, Pesel, CertificateSerialNumber, NIP_WEIGHTS, PESEL_WEIGHTS;
+var init_patterns = __esm({
+  "src/validation/patterns.ts"() {
+    "use strict";
+    NIP_PATTERN_CORE = "[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}";
+    VAT_UE_PATTERN_CORE = "(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))";
+    Nip = new RegExp(`^${NIP_PATTERN_CORE}$`);
+    VatUe = new RegExp(`^${VAT_UE_PATTERN_CORE}$`);
+    NipVatUe = new RegExp(`^${NIP_PATTERN_CORE}-${VAT_UE_PATTERN_CORE}$`);
+    Pesel = /^\d{2}(?:0[1-9]|1[0-2]|2[1-9]|3[0-2]|4[1-9]|5[0-2]|6[1-9]|7[0-2]|8[1-9]|9[0-2])\d{7}$/;
+    CertificateSerialNumber = /^[0-9A-F]{16}$/;
+    NIP_WEIGHTS = [6, 5, 7, 2, 3, 4, 5, 6, 7];
+    PESEL_WEIGHTS = [1, 3, 7, 9, 1, 3, 7, 9, 1, 3];
+  }
+});
+
 // src/services/certificates.ts
 var CertificateApiService;
 var init_certificates = __esm({
@@ -2102,6 +2127,8 @@ var init_certificates = __esm({
     "use strict";
     init_rest_request();
     init_routes();
+    init_ksef_validation_error();
+    init_patterns();
     CertificateApiService = class {
       restClient;
       constructor(restClient) {
@@ -2128,6 +2155,14 @@ var init_certificates = __esm({
         return response.body;
       }
       async retrieve(request) {
+        for (const serial of request.certificateSerialNumbers ?? []) {
+          if (!isValidCertificateSerialNumber(serial)) {
+            throw KSeFValidationError.fromField(
+              "certificateSerialNumbers",
+              `Invalid certificate serial number "${serial}": must be exactly 16 uppercase hex characters (^[0-9A-F]{16}$)`
+            );
+          }
+        }
         const req = RestRequest.post(Routes.Certificates.retrieve).body(request);
         const response = await this.restClient.execute(req);
         return response.body;
@@ -2793,6 +2828,7 @@ var init_verification_link_service = __esm({
       constructor(baseQrUrl) {
         this.baseQrUrl = baseQrUrl;
       }
+      baseQrUrl;
       /**
        * Build invoice verification URL (Code I).
        * Format: {baseQrUrl}/invoice/{NIP}/{DD-MM-YYYY}/{hash_base64url}
@@ -3103,6 +3139,7 @@ var init_offline_invoice_workflow = __esm({
       constructor(qrService) {
         this.qrService = qrService;
       }
+      qrService;
       async generate(input, options) {
         if (!input.invoiceXml || input.invoiceXml.trim().length === 0) {
           throw new Error("invoiceXml must not be empty");
@@ -4650,11 +4687,6 @@ var init_xml = __esm({
   "src/xml/index.ts"() {
     "use strict";
     init_upo_parser();
-    init_invoice_field_extractor();
-    init_xml_engine();
-    init_order_map();
-    init_faktura_builder();
-    init_pef_builder();
     init_invoice_serializer();
   }
 });
@@ -6132,11 +6164,6 @@ var SCHEMA_TYPES, NAMESPACE_MAP;
 var init_schemas = __esm({
   "src/validation/schemas/index.ts"() {
     "use strict";
-    init_fa3();
-    init_fa2();
-    init_fa_rr1();
-    init_pef3();
-    init_pef_kor3();
     SCHEMA_TYPES = ["FA3", "FA2", "FA_RR1", "PEF3", "PEF_KOR3"];
     NAMESPACE_MAP = {
       "http://crd.gov.pl/wzor/2025/06/25/13775/": "FA3",
@@ -6334,40 +6361,6 @@ var init_char_validity = __esm({
   }
 });
 
-// src/validation/patterns.ts
-function isValidNip(value) {
-  if (!Nip.test(value)) return false;
-  let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    sum += Number(value[i]) * NIP_WEIGHTS[i];
-  }
-  const checksum = sum % 11;
-  return checksum !== 10 && checksum === Number(value[9]);
-}
-function isValidPesel(value) {
-  if (!Pesel.test(value)) return false;
-  let sum = 0;
-  for (let i = 0; i < 10; i++) {
-    sum += Number(value[i]) * PESEL_WEIGHTS[i];
-  }
-  const checksum = (10 - sum % 10) % 10;
-  return checksum === Number(value[10]);
-}
-var NIP_PATTERN_CORE, VAT_UE_PATTERN_CORE, Nip, VatUe, NipVatUe, Pesel, NIP_WEIGHTS, PESEL_WEIGHTS;
-var init_patterns = __esm({
-  "src/validation/patterns.ts"() {
-    "use strict";
-    NIP_PATTERN_CORE = "[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}";
-    VAT_UE_PATTERN_CORE = "(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))";
-    Nip = new RegExp(`^${NIP_PATTERN_CORE}$`);
-    VatUe = new RegExp(`^${VAT_UE_PATTERN_CORE}$`);
-    NipVatUe = new RegExp(`^${NIP_PATTERN_CORE}-${VAT_UE_PATTERN_CORE}$`);
-    Pesel = /^\d{2}(?:0[1-9]|1[0-2]|2[1-9]|3[0-2]|4[1-9]|5[0-2]|6[1-9]|7[0-2]|8[1-9]|9[0-2])\d{7}$/;
-    NIP_WEIGHTS = [6, 5, 7, 2, 3, 4, 5, 6, 7];
-    PESEL_WEIGHTS = [1, 3, 7, 9, 1, 3, 7, 9, 1, 3];
-  }
-});
-
 // src/validation/invoice-validator.ts
 var invoice_validator_exports = {};
 __export(invoice_validator_exports, {
@@ -7286,8 +7279,34 @@ function clearCredentials() {
 
 // src/workflows/auth-workflow.ts
 init_polling();
-init_auth_xml_builder();
 init_with_key_rotation_retry();
+init_ksef_auth_status_error();
+var AUTH_STATUS_SUCCESS = 200;
+var AUTH_STATUS_IN_PROGRESS = 100;
+async function awaitAuthentication(client, referenceNumber, authToken, pollOptions) {
+  const final = await pollUntil(
+    () => client.auth.getAuthStatus(referenceNumber, authToken),
+    (s) => s.status.code !== AUTH_STATUS_IN_PROGRESS,
+    { ...pollOptions, description: `auth ${referenceNumber}` }
+  );
+  if (final.status.code !== AUTH_STATUS_SUCCESS) {
+    const details = final.status.details?.length ? ` (${final.status.details.join("; ")})` : "";
+    throw new KSeFAuthStatusError(
+      `Authentication failed with status ${final.status.code}: ${final.status.description}${details}`,
+      referenceNumber,
+      final.status.description
+    );
+  }
+  const tokens = await client.auth.getAccessToken(authToken);
+  client.authManager.setAccessToken(tokens.accessToken.token);
+  client.authManager.setRefreshToken(tokens.refreshToken.token);
+  return {
+    accessToken: tokens.accessToken.token,
+    accessTokenValidUntil: tokens.accessToken.validUntil,
+    refreshToken: tokens.refreshToken.token,
+    refreshTokenValidUntil: tokens.refreshToken.validUntil
+  };
+}
 async function authenticateWithToken(client, options) {
   const challenge2 = await client.auth.getChallenge();
   await client.crypto.init();
@@ -7302,20 +7321,7 @@ async function authenticateWithToken(client, options) {
     });
   });
   const authToken = submitResult.authenticationToken.token;
-  await pollUntil(
-    () => client.auth.getAuthStatus(submitResult.referenceNumber, authToken),
-    (s) => s.status.code !== 100,
-    { ...options.pollOptions, description: `auth ${submitResult.referenceNumber}` }
-  );
-  const tokens = await client.auth.getAccessToken(authToken);
-  client.authManager.setAccessToken(tokens.accessToken.token);
-  client.authManager.setRefreshToken(tokens.refreshToken.token);
-  return {
-    accessToken: tokens.accessToken.token,
-    accessTokenValidUntil: tokens.accessToken.validUntil,
-    refreshToken: tokens.refreshToken.token,
-    refreshTokenValidUntil: tokens.refreshToken.validUntil
-  };
+  return awaitAuthentication(client, submitResult.referenceNumber, authToken, options.pollOptions);
 }
 
 // src/cli/session-recovery.ts
@@ -8321,6 +8327,7 @@ var FileHwmStore = class {
   constructor(filePath) {
     this.filePath = filePath;
   }
+  filePath;
   async load() {
     try {
       const data = await fs7.readFile(this.filePath, "utf-8");
@@ -8338,8 +8345,6 @@ var FileHwmStore = class {
 };
 
 // src/workflows/invoice-export-workflow.ts
-init_zip();
-init_targz();
 init_polling();
 init_with_key_rotation_retry();