ksef-client-ts 0.9.0 → 0.9.1

package/dist/index.cjs

@@ -401,6 +401,25 @@ var init_ksef_validation_error = __esm({
   }
 });
 
+// src/errors/ksef-metadata-pagination-error.ts
+var KSeFMetadataPaginationError;
+var init_ksef_metadata_pagination_error = __esm({
+  "src/errors/ksef-metadata-pagination-error.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_ksef_error();
+    KSeFMetadataPaginationError = class extends KSeFError {
+      /** The boundary date value that failed to advance. */
+      boundaryValue;
+      constructor(message, boundaryValue) {
+        super(message);
+        this.name = "KSeFMetadataPaginationError";
+        this.boundaryValue = boundaryValue;
+      }
+    };
+  }
+});
+
 // src/errors/error-codes.ts
 function hasErrorCode(body, code) {
   return !!body?.exception?.exceptionDetailList?.some((d) => d.exceptionCode === code);
@@ -548,6 +567,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();
@@ -1569,6 +1589,9 @@ function isValidCertificateName(value) {
 function isValidCertificateFingerprint(value) {
   return CertificateFingerprint.test(value);
 }
+function isValidCertificateSerialNumber(value) {
+  return CertificateSerialNumber.test(value);
+}
 function isValidBase64(value) {
   return Base64String.test(value);
 }
@@ -1578,7 +1601,7 @@ function isValidIp4Address(value) {
 function isValidSha256Base64(value) {
   return Sha256Base64.test(value);
 }
-var NIP_PATTERN_CORE, VAT_UE_PATTERN_CORE, Nip, VatUe, NipVatUe, InternalId, PeppolId, ReferenceNumber, KsefNumber, KsefNumberV35, KsefNumberV36, CertificateName, Pesel, CertificateFingerprint, Base64String, Ip4Address, Ip4Range, Ip4Mask, Sha256Base64, NIP_WEIGHTS, PESEL_WEIGHTS, CRC8_POLY;
+var NIP_PATTERN_CORE, VAT_UE_PATTERN_CORE, Nip, VatUe, NipVatUe, InternalId, PeppolId, ReferenceNumber, KsefNumber, KsefNumberV35, KsefNumberV36, CertificateName, Pesel, CertificateFingerprint, CertificateSerialNumber, Base64String, Ip4Address, Ip4Range, Ip4Mask, Sha256Base64, NIP_WEIGHTS, PESEL_WEIGHTS, CRC8_POLY;
 var init_patterns = __esm({
   "src/validation/patterns.ts"() {
     "use strict";
@@ -1597,6 +1620,7 @@ var init_patterns = __esm({
     CertificateName = /^[a-zA-Z0-9_\- ąćęłńóśźżĄĆĘŁŃÓŚŹŻ]+$/;
     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}$/;
     CertificateFingerprint = /^[0-9A-F]{64}$/;
+    CertificateSerialNumber = /^[0-9A-F]{16}$/;
     Base64String = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
     Ip4Address = /^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/;
     Ip4Range = /^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}-((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/;
@@ -4053,6 +4077,8 @@ var init_certificates = __esm({
     init_cjs_shims();
     init_rest_request();
     init_routes();
+    init_ksef_validation_error();
+    init_patterns();
     CertificateApiService = class {
       restClient;
       constructor(restClient) {
@@ -4079,6 +4105,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;
@@ -6069,6 +6103,7 @@ __export(index_exports, {
   CertificateFetcher: () => CertificateFetcher,
   CertificateFingerprint: () => CertificateFingerprint,
   CertificateName: () => CertificateName,
+  CertificateSerialNumber: () => CertificateSerialNumber,
   CertificateService: () => CertificateService,
   CircuitBreakerPolicy: () => CircuitBreakerPolicy,
   CryptographyService: () => CryptographyService,
@@ -6105,6 +6140,7 @@ __export(index_exports, {
   KSeFErrorCode: () => KSeFErrorCode,
   KSeFForbiddenError: () => KSeFForbiddenError,
   KSeFGoneError: () => KSeFGoneError,
+  KSeFMetadataPaginationError: () => KSeFMetadataPaginationError,
   KSeFRateLimitError: () => KSeFRateLimitError,
   KSeFSessionExpiredError: () => KSeFSessionExpiredError,
   KSeFUnauthorizedError: () => KSeFUnauthorizedError,
@@ -6166,6 +6202,7 @@ __export(index_exports, {
   buildXmlFromObject: () => buildXmlFromObject,
   calculateBackoff: () => calculateBackoff,
   calculateOfflineDeadline: () => calculateOfflineDeadline,
+  collectAllInvoiceMetadata: () => collectAllInvoiceMetadata,
   comparePKey: () => comparePKey,
   createTarGz: () => createTarGz,
   createZip: () => createZip,
@@ -6198,6 +6235,7 @@ __export(index_exports, {
   isValidBase64: () => isValidBase64,
   isValidCertificateFingerprint: () => isValidCertificateFingerprint,
   isValidCertificateName: () => isValidCertificateName,
+  isValidCertificateSerialNumber: () => isValidCertificateSerialNumber,
   isValidInternalId: () => isValidInternalId,
   isValidIp4Address: () => isValidIp4Address,
   isValidKsefNumber: () => isValidKsefNumber,
@@ -6221,6 +6259,7 @@ __export(index_exports, {
   parseUpoXml: () => parseUpoXml,
   parseXml: () => parseXml,
   pollUntil: () => pollUntil,
+  queryAllInvoiceMetadata: () => queryAllInvoiceMetadata,
   resolveOptions: () => resolveOptions,
   resolveXsdFor: () => resolveXsdFor,
   resumeOnlineSession: () => resumeOnlineSession,
@@ -8451,6 +8490,33 @@ var FileHwmStore = class {
 init_cjs_shims();
 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 challenge = await client.auth.getChallenge();
   await client.crypto.init();
@@ -8465,20 +8531,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);
 }
 async function authenticateWithCertificate(client, options) {
   const challenge = await client.auth.getChallenge();
@@ -8492,20 +8545,7 @@ async function authenticateWithCertificate(client, options) {
     options.enforceXadesCompliance ?? false
   );
   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);
 }
 async function authenticateWithExternalSignature(client, options) {
   const challenge = await client.auth.getChallenge();
@@ -8520,20 +8560,7 @@ async function authenticateWithExternalSignature(client, options) {
     options.enforceXadesCompliance ?? false
   );
   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);
 }
 async function authenticateWithPkcs12(client, options) {
   const { Pkcs12Loader: Pkcs12Loader2 } = await Promise.resolve().then(() => (init_pkcs12_loader(), pkcs12_loader_exports));
@@ -8548,6 +8575,95 @@ async function authenticateWithPkcs12(client, options) {
   });
 }
 
+// src/workflows/metadata-query-paging.ts
+init_cjs_shims();
+init_ksef_metadata_pagination_error();
+init_ksef_validation_error();
+var DEFAULT_PAGE_SIZE = 100;
+var DEFAULT_MAX_BOUNDARY_CROSSINGS = 1e3;
+function boundaryFieldFor(dateType) {
+  switch (dateType) {
+    case "Issue":
+      return "issueDate";
+    case "Invoicing":
+      return "invoicingDate";
+    case "PermanentStorage":
+      return "permanentStorageDate";
+  }
+}
+async function* queryAllInvoiceMetadata(client, filters, options = {}) {
+  const sortOrder = options.sortOrder ?? "Asc";
+  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+  const maxBoundaryCrossings = options.maxBoundaryCrossings ?? DEFAULT_MAX_BOUNDARY_CROSSINGS;
+  if (!Number.isInteger(pageSize) || pageSize <= 0) {
+    throw new KSeFValidationError("`pageSize` must be a positive integer.");
+  }
+  if (!Number.isInteger(maxBoundaryCrossings) || maxBoundaryCrossings < 0) {
+    throw new KSeFValidationError("`maxBoundaryCrossings` must be a non-negative integer.");
+  }
+  const boundaryField = boundaryFieldFor(filters.dateRange.dateType);
+  let dateRange = { ...filters.dateRange };
+  let boundaryCrossings = 0;
+  let carryKeys = /* @__PURE__ */ new Set();
+  let carryValue;
+  for (; ; ) {
+    let pageIndex = 0;
+    let lastBoundaryValue;
+    let isTruncated = false;
+    let boundaryKeys = /* @__PURE__ */ new Set();
+    for (; ; ) {
+      const window = { ...filters, dateRange };
+      const response = await client.invoices.queryInvoiceMetadata(
+        window,
+        pageIndex,
+        pageSize,
+        sortOrder
+      );
+      isTruncated = response.isTruncated;
+      for (const invoice of response.invoices) {
+        const boundaryValue = invoice[boundaryField];
+        const key = invoice.ksefNumber.toLowerCase();
+        if (boundaryValue === carryValue && carryKeys.has(key)) continue;
+        if (boundaryValue !== lastBoundaryValue) {
+          lastBoundaryValue = boundaryValue;
+          boundaryKeys = /* @__PURE__ */ new Set();
+        }
+        boundaryKeys.add(key);
+        yield invoice;
+      }
+      if (response.hasMore) {
+        pageIndex += 1;
+        continue;
+      }
+      break;
+    }
+    if (!isTruncated || lastBoundaryValue === void 0) return;
+    const previousBoundary = sortOrder === "Asc" ? dateRange.from : dateRange.to;
+    if (previousBoundary === lastBoundaryValue) {
+      throw new KSeFMetadataPaginationError(
+        `Metadata paging stalled: a truncated window did not advance past ${boundaryField}=${lastBoundaryValue}. The result set likely exceeds the server cap within a single ${boundaryField} value; narrow the query further.`,
+        lastBoundaryValue
+      );
+    }
+    if (++boundaryCrossings > maxBoundaryCrossings) {
+      throw new KSeFMetadataPaginationError(
+        `Metadata paging exceeded ${maxBoundaryCrossings} truncation boundaries; aborting to avoid an unbounded loop.`,
+        lastBoundaryValue
+      );
+    }
+    carryKeys = boundaryKeys;
+    carryValue = lastBoundaryValue;
+    dateRange = sortOrder === "Asc" ? { ...dateRange, from: lastBoundaryValue } : { ...dateRange, to: lastBoundaryValue };
+  }
+}
+async function collectAllInvoiceMetadata(client, filters, options = {}) {
+  const all = [];
+  for await (const invoice of queryAllInvoiceMetadata(client, filters, options)) {
+    all.push(invoice);
+  }
+  return all;
+}
+
 // src/offline/index.ts
 init_cjs_shims();
 init_deadline();
@@ -8706,6 +8822,7 @@ init_client();
   CertificateFetcher,
   CertificateFingerprint,
   CertificateName,
+  CertificateSerialNumber,
   CertificateService,
   CircuitBreakerPolicy,
   CryptographyService,
@@ -8742,6 +8859,7 @@ init_client();
   KSeFErrorCode,
   KSeFForbiddenError,
   KSeFGoneError,
+  KSeFMetadataPaginationError,
   KSeFRateLimitError,
   KSeFSessionExpiredError,
   KSeFUnauthorizedError,
@@ -8803,6 +8921,7 @@ init_client();
   buildXmlFromObject,
   calculateBackoff,
   calculateOfflineDeadline,
+  collectAllInvoiceMetadata,
   comparePKey,
   createTarGz,
   createZip,
@@ -8835,6 +8954,7 @@ init_client();
   isValidBase64,
   isValidCertificateFingerprint,
   isValidCertificateName,
+  isValidCertificateSerialNumber,
   isValidInternalId,
   isValidIp4Address,
   isValidKsefNumber,
@@ -8858,6 +8978,7 @@ init_client();
   parseUpoXml,
   parseXml,
   pollUntil,
+  queryAllInvoiceMetadata,
   resolveOptions,
   resolveXsdFor,
   resumeOnlineSession,