ksef-client-ts 0.9.0 → 0.10.0

package/dist/index.js

@@ -8,9 +8,9 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// node_modules/tsup/assets/esm_shims.js
+// ../../node_modules/tsup/assets/esm_shims.js
 var init_esm_shims = __esm({
-  "node_modules/tsup/assets/esm_shims.js"() {
+  "../../node_modules/tsup/assets/esm_shims.js"() {
     "use strict";
   }
 });
@@ -376,6 +376,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_esm_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);
@@ -523,6 +542,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();
@@ -565,21 +585,21 @@ var init_rest_request = __esm({
       _query = [];
       _presigned = false;
       _skipAuthRetry = false;
-      constructor(method, path3) {
+      constructor(method, path) {
         this.method = method;
-        this.path = path3;
+        this.path = path;
       }
-      static get(path3) {
-        return new _RestRequest("GET", path3);
+      static get(path) {
+        return new _RestRequest("GET", path);
       }
-      static post(path3) {
-        return new _RestRequest("POST", path3);
+      static post(path) {
+        return new _RestRequest("POST", path);
       }
-      static put(path3) {
-        return new _RestRequest("PUT", path3);
+      static put(path) {
+        return new _RestRequest("PUT", path);
       }
-      static delete(path3) {
-        return new _RestRequest("DELETE", path3);
+      static delete(path) {
+        return new _RestRequest("DELETE", path);
       }
       body(data) {
         this._body = data;
@@ -943,13 +963,13 @@ var init_rest_client = __esm({
         }
         throw lastError;
       }
-      recordCircuitOutcome(path3, status) {
+      recordCircuitOutcome(path, status) {
         if (!this.circuitBreakerPolicy) return;
         if (status >= 500) {
-          this.circuitBreakerPolicy.recordFailure(path3);
+          this.circuitBreakerPolicy.recordFailure(path);
           return;
         }
-        this.circuitBreakerPolicy.recordSuccess(path3);
+        this.circuitBreakerPolicy.recordSuccess(path);
       }
       async doRequest(request, url, overrideToken) {
         const headers = {
@@ -986,9 +1006,9 @@ var init_rest_client = __esm({
         return response;
       }
       buildUrl(request) {
-        const path3 = this.routeBuilder.build(request.path);
+        const path = this.routeBuilder.build(request.path);
         const base = this.options.baseUrl;
-        const url = new URL(`${base}${path3}`);
+        const url = new URL(`${base}${path}`);
         const query = request.getQuery();
         for (const [key, value] of query) {
           url.searchParams.append(key, value);
@@ -1544,6 +1564,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);
 }
@@ -1553,7 +1576,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";
@@ -1572,6 +1595,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}$/;
@@ -2835,11 +2859,6 @@ var init_schemas = __esm({
   "src/validation/schemas/index.ts"() {
     "use strict";
     init_esm_shims();
-    init_fa3();
-    init_fa2();
-    init_fa_rr1();
-    init_pef3();
-    init_pef_kor3();
     NAMESPACE_MAP = {
       "http://crd.gov.pl/wzor/2025/06/25/13775/": "FA3",
       "http://crd.gov.pl/wzor/2023/06/29/12648/": "FA2",
@@ -3095,11 +3114,11 @@ async function validateSchema(xml, options, _parsed) {
   const prefix = rootElement ? `/${rootElement}/` : "/";
   const validationErrors = result.error.issues.map((issue) => {
     const zodPath = issue.path.join("/");
-    const path3 = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
+    const path = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
     return {
       code: mapZodErrorCode(issue),
       message: issue.message,
-      path: path3
+      path
     };
   });
   return { valid: false, schemaType, errors: validationErrors };
@@ -3139,9 +3158,9 @@ function validateBusinessRules(xml, _parsed) {
   collectDateErrors(object, rootElement, errors);
   return { valid: errors.length === 0, schemaType, errors };
 }
-function collectNipPeselErrors(obj, path3, errors) {
+function collectNipPeselErrors(obj, path, errors) {
   for (const [key, value] of Object.entries(obj)) {
-    const currentPath = path3 ? `${path3}/${key}` : key;
+    const currentPath = path ? `${path}/${key}` : key;
     if (key === "NIP" && typeof value === "string") {
       if (!isValidNip(value)) {
         errors.push({
@@ -4027,6 +4046,8 @@ var init_certificates = __esm({
     init_esm_shims();
     init_rest_request();
     init_routes();
+    init_ksef_validation_error();
+    init_patterns();
     CertificateApiService = class {
       restClient;
       constructor(restClient) {
@@ -4053,6 +4074,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;
@@ -4086,20 +4115,20 @@ var init_lighthouse = __esm({
         this.lighthouseUrl = options.lighthouseUrl;
         this.timeout = options.timeout;
       }
-      async fetchJson(path3) {
+      async fetchJson(path) {
         if (!this.lighthouseUrl) {
           throw new KSeFError(
             "Lighthouse API is not available for the DEMO environment. Use TEST or PROD instead."
           );
         }
-        const response = await fetch(`${this.lighthouseUrl}${path3}`, {
+        const response = await fetch(`${this.lighthouseUrl}${path}`, {
           headers: { Accept: "application/json" },
           signal: AbortSignal.timeout(this.timeout)
         });
         if (!response.ok) {
           const body = await response.text();
           throw new KSeFError(
-            `Lighthouse ${path3} failed: HTTP ${response.status} \u2014 ${body}`
+            `Lighthouse ${path} failed: HTTP ${response.status} \u2014 ${body}`
           );
         }
         return await response.json();
@@ -5070,6 +5099,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}
@@ -5550,6 +5580,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");
@@ -6062,219 +6093,6 @@ init_schema_registry();
 init_invoice_validator();
 init_char_validity();
 
-// src/validation/xsd-validator.ts
-init_esm_shims();
-import { createRequire } from "node:module";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-var cachedPkgRoot = null;
-function locatePackageRoot() {
-  if (cachedPkgRoot !== null) return cachedPkgRoot;
-  let dir = path.dirname(fileURLToPath(import.meta.url));
-  const root = path.parse(dir).root;
-  while (dir !== root) {
-    const candidate = path.join(dir, "docs", "schemas");
-    if (fs.existsSync(candidate)) {
-      cachedPkgRoot = dir;
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  throw new Error("Could not locate ksef-client-ts package root (docs/schemas not found).");
-}
-var XSD_RELATIVE = {
-  FA2: ["FA", "schemat_FA(2)_v1-0E.xsd"],
-  FA3: ["FA", "schemat_FA(3)_v1-0E.xsd"],
-  PEF: ["PEF", "Schemat_PEF(3)_v2-1.xsd"],
-  PEF_KOR: ["PEF", "Schemat_PEF_KOR(3)_v2-1.xsd"]
-};
-var FA_XSD_PATHS = {
-  get FA2() {
-    return resolveXsdFor("FA2");
-  },
-  get FA3() {
-    return resolveXsdFor("FA3");
-  }
-};
-var PEF_XSD_PATHS = {
-  get PEF() {
-    return resolveXsdFor("PEF");
-  },
-  get PEF_KOR() {
-    return resolveXsdFor("PEF_KOR");
-  }
-};
-function resolveXsdFor(schema) {
-  const rel = XSD_RELATIVE[schema];
-  if (!rel) throw new Error(`Unknown invoice schema: ${String(schema)}`);
-  return path.join(locatePackageRoot(), "docs", "schemas", ...rel);
-}
-var requireModule = createRequire(import.meta.url);
-var libxmljs = null;
-var libxmljsLoadError = null;
-try {
-  libxmljs = requireModule("libxmljs2");
-} catch (err) {
-  const code = err?.code;
-  if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
-    libxmljs = null;
-  } else {
-    libxmljs = null;
-    libxmljsLoadError = err instanceof Error ? err : new Error(String(err));
-  }
-}
-var libxmljsAvailable = libxmljs !== null;
-var MISSING_LIBXMLJS_MESSAGE_PREFIX = "libxmljs2 is not installed";
-function isMissingLibxmljsError(err) {
-  return err instanceof Error && err.message.startsWith(MISSING_LIBXMLJS_MESSAGE_PREFIX);
-}
-var EXTERNAL_STRUKTURY_DANYCH_URL = /schemaLocation="http:\/\/crd\.gov\.pl\/xml\/schematy\/dziedzinowe\/mf\/2022\/01\/05\/eD\/DefinicjeTypy\/StrukturyDanych_v10-0E\.xsd"/;
-function rewriteSchemaLocations(xsdContent) {
-  if (!EXTERNAL_STRUKTURY_DANYCH_URL.test(xsdContent)) {
-    return xsdContent;
-  }
-  const bazoweStrukturyPath = path.join(
-    locatePackageRoot(),
-    "docs",
-    "schemas",
-    "FA",
-    "bazowe",
-    "StrukturyDanych_v10-0E.xsd"
-  );
-  const bazoweStrukturyUrl = pathToFileURL(bazoweStrukturyPath).href;
-  const rewritten = xsdContent.replace(
-    EXTERNAL_STRUKTURY_DANYCH_URL,
-    `schemaLocation="${bazoweStrukturyUrl}"`
-  );
-  if (rewritten === xsdContent) {
-    throw new Error(
-      "FA XSD schemaLocation rewrite produced no replacement despite URL being present; regex likely out of sync with docs/schemas/FA/. Re-check after `yarn sync-schemas`."
-    );
-  }
-  return rewritten;
-}
-function validateAgainstXsd(xml, xsdPath) {
-  if (!libxmljs) {
-    const loadSuffix = libxmljsLoadError ? ` (load failed: ${libxmljsLoadError.message})` : "";
-    throw new Error(
-      `${MISSING_LIBXMLJS_MESSAGE_PREFIX}${loadSuffix}; cannot run XSD validation. Install it as an optional peer dependency (e.g. \`yarn add -O libxmljs2\` or \`npm i -O libxmljs2\`).`
-    );
-  }
-  const xsdDir = path.dirname(xsdPath);
-  const rawXsd = fs.readFileSync(xsdPath, "utf8");
-  const rewrittenXsd = rewriteSchemaLocations(rawXsd);
-  const baseUrl = pathToFileURL(xsdDir + path.sep).href;
-  let schemaDoc;
-  try {
-    schemaDoc = libxmljs.parseXml(rewrittenXsd, { baseUrl });
-  } catch (err) {
-    return { valid: false, errors: [`XSD parse failed: ${err.message}`] };
-  }
-  let xmlDoc;
-  try {
-    xmlDoc = libxmljs.parseXml(xml);
-  } catch (err) {
-    return { valid: false, errors: [`XML parse failed: ${err.message}`] };
-  }
-  const valid = xmlDoc.validate(schemaDoc);
-  const errors = valid ? [] : xmlDoc.validationErrors.map((err) => err.message.trim());
-  return { valid, errors };
-}
-
-// src/models/index.ts
-init_esm_shims();
-
-// src/models/common.ts
-init_esm_shims();
-
-// src/models/auth/index.ts
-init_esm_shims();
-
-// src/models/auth/types.ts
-init_esm_shims();
-
-// src/models/auth/active-sessions-types.ts
-init_esm_shims();
-
-// src/models/sessions/index.ts
-init_esm_shims();
-
-// src/models/sessions/online-types.ts
-init_esm_shims();
-
-// src/models/sessions/batch-types.ts
-init_esm_shims();
-
-// src/models/sessions/status-types.ts
-init_esm_shims();
-
-// src/models/sessions/session-state.ts
-init_esm_shims();
-
-// src/models/invoices/index.ts
-init_esm_shims();
-
-// src/models/invoices/types.ts
-init_esm_shims();
-
-// src/models/permissions/index.ts
-init_esm_shims();
-
-// src/models/permissions/types.ts
-init_esm_shims();
-
-// src/models/tokens/index.ts
-init_esm_shims();
-
-// src/models/tokens/types.ts
-init_esm_shims();
-
-// src/models/certificates/index.ts
-init_esm_shims();
-
-// src/models/certificates/types.ts
-init_esm_shims();
-
-// src/models/lighthouse/index.ts
-init_esm_shims();
-
-// src/models/lighthouse/types.ts
-init_esm_shims();
-
-// src/models/limits/index.ts
-init_esm_shims();
-
-// src/models/limits/types.ts
-init_esm_shims();
-
-// src/models/peppol/index.ts
-init_esm_shims();
-
-// src/models/peppol/types.ts
-init_esm_shims();
-
-// src/models/test-data/index.ts
-init_esm_shims();
-
-// src/models/test-data/types.ts
-init_esm_shims();
-
-// src/models/crypto/index.ts
-init_esm_shims();
-
-// src/models/crypto/types.ts
-init_esm_shims();
-
-// src/models/qrcode/index.ts
-init_esm_shims();
-
-// src/models/qrcode/types.ts
-init_esm_shims();
-
-// src/models/index.ts
-init_document_structures();
-
 // src/services/index.ts
 init_esm_shims();
 init_auth();
@@ -8192,7 +8010,6 @@ function buildDefaultFilters(subjectType, from, to) {
 
 // src/workflows/hwm-storage.ts
 init_esm_shims();
-import * as fs2 from "node:fs/promises";
 var InMemoryHwmStore = class {
   points = {};
   async load() {
@@ -8202,30 +8019,38 @@ var InMemoryHwmStore = class {
     this.points = { ...points };
   }
 };
-var FileHwmStore = class {
-  constructor(filePath) {
-    this.filePath = filePath;
-  }
-  async load() {
-    try {
-      const data = await fs2.readFile(this.filePath, "utf-8");
-      return JSON.parse(data);
-    } catch (err) {
-      if (err.code === "ENOENT") {
-        return {};
-      }
-      throw err;
-    }
-  }
-  async save(points) {
-    await fs2.writeFile(this.filePath, JSON.stringify(points, null, 2), "utf-8");
-  }
-};
 
 // src/workflows/auth-workflow.ts
 init_esm_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();
@@ -8240,20 +8065,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();
@@ -8267,20 +8079,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();
@@ -8295,20 +8094,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));
@@ -8323,6 +8109,95 @@ async function authenticateWithPkcs12(client, options) {
   });
 }
 
+// src/workflows/metadata-query-paging.ts
+init_esm_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_esm_shims();
 init_deadline();
@@ -8367,98 +8242,6 @@ var InMemoryOfflineInvoiceStorage = class {
   }
 };
 
-// src/offline/file-storage.ts
-init_esm_shims();
-import * as fs3 from "node:fs/promises";
-import * as path2 from "node:path";
-import * as os from "node:os";
-function resolveDir(dir) {
-  if (dir === "~" || dir.startsWith("~/")) {
-    return path2.join(os.homedir(), dir.slice(1));
-  }
-  return dir;
-}
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function validateId(id) {
-  if (!UUID_RE.test(id)) {
-    throw new Error(`Invalid invoice ID: ${id}`);
-  }
-}
-var FileOfflineInvoiceStorage = class {
-  dir;
-  constructor(directory) {
-    this.dir = resolveDir(directory ?? "~/.ksef/offline");
-  }
-  async ensureDir() {
-    await fs3.mkdir(this.dir, { recursive: true });
-  }
-  filePath(id) {
-    validateId(id);
-    return path2.join(this.dir, `${id}.json`);
-  }
-  async save(invoice) {
-    await this.ensureDir();
-    const file = this.filePath(invoice.id);
-    const tmp = `${file}.tmp`;
-    await fs3.writeFile(tmp, JSON.stringify(invoice, null, 2));
-    await fs3.rename(tmp, file);
-  }
-  async get(id) {
-    const file = this.filePath(id);
-    try {
-      return JSON.parse(await fs3.readFile(file, "utf-8"));
-    } catch (err) {
-      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-        return null;
-      }
-      console.warn(`Warning: Failed to read offline invoice ${id}: ${err instanceof Error ? err.message : String(err)}`);
-      return null;
-    }
-  }
-  async list(filter) {
-    let files;
-    try {
-      files = (await fs3.readdir(this.dir)).filter((f) => f.endsWith(".json"));
-    } catch {
-      return [];
-    }
-    const results = [];
-    for (const file of files) {
-      try {
-        const data = JSON.parse(
-          await fs3.readFile(path2.join(this.dir, file), "utf-8")
-        );
-        if (!filter || matchesFilter(data, filter)) {
-          results.push(data);
-        }
-      } catch (err) {
-        console.warn(`Warning: Skipping corrupt offline invoice file ${file}: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    }
-    return results;
-  }
-  /**
-   * Update invoice metadata (read-modify-write).
-   *
-   * Note: No file locking — concurrent updates to the same ID may cause
-   * lost writes. Acceptable for CLI (single process). Library consumers
-   * running parallel operations should use external locking.
-   */
-  async update(id, updates) {
-    const existing = await this.get(id);
-    if (!existing) throw new Error(`Offline invoice not found: ${id}`);
-    await this.save({ ...existing, ...updates });
-  }
-  async delete(id) {
-    const file = this.filePath(id);
-    try {
-      await fs3.unlink(file);
-    } catch (e) {
-      if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
-    }
-  }
-};
-
 // src/index.ts
 init_offline_invoice_workflow();
 init_client();
@@ -8480,6 +8263,7 @@ export {
   CertificateFetcher,
   CertificateFingerprint,
   CertificateName,
+  CertificateSerialNumber,
   CertificateService,
   CircuitBreakerPolicy,
   CryptographyService,
@@ -8491,11 +8275,8 @@ export {
   EntityPermissionGrantBuilder,
   Environment,
   FAKTURA_NAMESPACE,
-  FA_XSD_PATHS,
   FORM_CODES,
   FORM_CODE_KEYS,
-  FileHwmStore,
-  FileOfflineInvoiceStorage,
   INVOICE_TYPES_BY_SYSTEM_CODE,
   InMemoryHwmStore,
   InMemoryOfflineInvoiceStorage,
@@ -8516,6 +8297,7 @@ export {
   KSeFErrorCode,
   KSeFForbiddenError,
   KSeFGoneError,
+  KSeFMetadataPaginationError,
   KSeFRateLimitError,
   KSeFSessionExpiredError,
   KSeFUnauthorizedError,
@@ -8533,7 +8315,6 @@ export {
   OfflineInvoiceWorkflow,
   OnlineSessionService,
   PEF_NAMESPACE,
-  PEF_XSD_PATHS,
   PERMISSION_DESCRIPTION_MAX_LENGTH,
   PERMISSION_DESCRIPTION_MIN_LENGTH,
   PeppolId,
@@ -8577,6 +8358,7 @@ export {
   buildXmlFromObject,
   calculateBackoff,
   calculateOfflineDeadline,
+  collectAllInvoiceMetadata,
   comparePKey,
   createTarGz,
   createZip,
@@ -8601,7 +8383,6 @@ export {
   isExpired,
   isFakturaInput,
   isFormCodeShape,
-  isMissingLibxmljsError,
   isPefUblDocumentInput,
   isPolishHoliday,
   isRetryableError,
@@ -8609,6 +8390,7 @@ export {
   isValidBase64,
   isValidCertificateFingerprint,
   isValidCertificateName,
+  isValidCertificateSerialNumber,
   isValidInternalId,
   isValidIp4Address,
   isValidKsefNumber,
@@ -8621,7 +8403,6 @@ export {
   isValidReferenceNumber,
   isValidSha256Base64,
   isValidVatUe,
-  libxmljsAvailable,
   nextBusinessDay,
   openOnlineSession,
   openSendAndClose,
@@ -8632,8 +8413,8 @@ export {
   parseUpoXml,
   parseXml,
   pollUntil,
+  queryAllInvoiceMetadata,
   resolveOptions,
-  resolveXsdFor,
   resumeOnlineSession,
   runWithConcurrency,
   serializeInvoiceXml,
@@ -8648,7 +8429,6 @@ export {
   uploadBatchStream,
   uploadBatchStreamParsed,
   validate,
-  validateAgainstXsd,
   validateBatch,
   validateBusinessRules,
   validateCharValidity,