ksef-client-ts 0.9.0 → 0.9.1

package/README.md

@@ -6,7 +6,7 @@ TypeScript client for the Polish National e-Invoice System (KSeF) API v2.
 
 ## Features
 
-- **Complete API coverage** — KSeF API v2.6.0, types aligned with the official OpenAPI spec
+- **Complete API coverage** — KSeF API v2.6.1, 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

package/dist/cli.js

@@ -238,10 +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();
+    KSeFAuthStatusError = class extends KSeFError {
+      referenceNumber;
+      statusDescription;
+      constructor(message, referenceNumber, statusDescription) {
+        super(message);
+        this.name = "KSeFAuthStatusError";
+        this.referenceNumber = referenceNumber;
+        this.statusDescription = statusDescription;
+      }
+    };
   }
 });
 
@@ -281,6 +292,14 @@ var init_ksef_validation_error = __esm({
   }
 });
 
+// src/errors/ksef-metadata-pagination-error.ts
+var init_ksef_metadata_pagination_error = __esm({
+  "src/errors/ksef-metadata-pagination-error.ts"() {
+    "use strict";
+    init_ksef_error();
+  }
+});
+
 // src/errors/error-codes.ts
 function hasErrorCode(body, code) {
   return !!body?.exception?.exceptionDetailList?.some((d) => d.exceptionCode === code);
@@ -418,6 +437,7 @@ var init_errors = __esm({
     init_ksef_auth_status_error();
     init_ksef_session_expired_error();
     init_ksef_validation_error();
+    init_ksef_metadata_pagination_error();
     init_ksef_batch_timeout_error();
     init_ksef_unknown_public_key_error();
     init_ksef_circuit_open_error();
@@ -2095,6 +2115,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 +2160,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 +2188,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;
@@ -6334,40 +6402,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, {
@@ -7288,6 +7322,33 @@ function clearCredentials() {
 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 +7363,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