ksef-client-ts 0.3.0 → 0.4.0

package/dist/index.js

@@ -1106,6 +1106,36 @@ var init_batch_session = __esm({
         });
         await Promise.all(tasks);
       }
+      /**
+       * Upload parts sequentially (not in parallel) because each part uses a
+       * streaming body (`duplex: 'half'`). Parallel streaming uploads can cause
+       * backpressure issues and exceed memory limits for large payloads.
+       */
+      async sendPartsWithStream(openResponse, parts) {
+        const uploadRequests = openResponse.partUploadRequests;
+        for (const part of parts) {
+          const uploadReq = uploadRequests.find(
+            (r) => r.ordinalNumber === part.ordinalNumber
+          );
+          if (!uploadReq) {
+            throw new Error(`No upload request found for part ${part.ordinalNumber}`);
+          }
+          const headers = {};
+          for (const [k, v] of Object.entries(uploadReq.headers)) {
+            if (v != null) headers[k] = v;
+          }
+          const resp = await fetch(uploadReq.url, {
+            method: uploadReq.method,
+            headers,
+            body: part.dataStream,
+            // @ts-expect-error -- Node 18+ undici supports duplex for streaming body
+            duplex: "half"
+          });
+          if (!resp.ok) {
+            throw new Error(`Upload failed for part ${part.ordinalNumber}: HTTP ${resp.status}`);
+          }
+        }
+      }
       async closeSession(batchRef) {
         const req = RestRequest.post(Routes.Sessions.Batch.close(batchRef));
         await this.restClient.executeVoid(req);
@@ -1803,6 +1833,28 @@ var init_cryptography_service = __esm({
         const cipher = crypto2.createCipheriv("aes-256-cbc", key, iv);
         return new Uint8Array(Buffer.concat([cipher.update(content), cipher.final()]));
       }
+      /**
+       * Encrypt with AES-256-CBC as a streaming transform.
+       * Returns a ReadableStream that yields encrypted chunks as the input is read.
+       */
+      encryptAES256Stream(input, key, iv) {
+        const cipher = crypto2.createCipheriv("aes-256-cbc", key, iv);
+        const transform = new TransformStream({
+          transform(chunk, controller) {
+            const encrypted = cipher.update(chunk);
+            if (encrypted.length > 0) {
+              controller.enqueue(new Uint8Array(encrypted));
+            }
+          },
+          flush(controller) {
+            const final = cipher.final();
+            if (final.length > 0) {
+              controller.enqueue(new Uint8Array(final));
+            }
+          }
+        });
+        return input.pipeThrough(transform);
+      }
       /** Decrypt with AES-256-CBC. */
       decryptAES256(content, key, iv) {
         const decipher = crypto2.createDecipheriv("aes-256-cbc", key, iv);
@@ -1875,6 +1927,23 @@ var init_cryptography_service = __esm({
         const hash = crypto2.createHash("sha256").update(file).digest("base64");
         return { hashSHA: hash, fileSize: file.length };
       }
+      /** Compute SHA-256 hash (base64) and byte length from a ReadableStream. */
+      async getFileMetadataFromStream(stream) {
+        const hash = crypto2.createHash("sha256");
+        let fileSize = 0;
+        const reader = stream.getReader();
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            hash.update(value);
+            fileSize += value.byteLength;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        return { hashSHA: hash.digest("base64"), fileSize };
+      }
       // ---------------------------------------------------------------------------
       // CSR generation
       // ---------------------------------------------------------------------------
@@ -6789,6 +6858,32 @@ var init_pkcs12_loader = __esm({
   }
 });
 
+// src/crypto/auth-xml-builder.ts
+function buildUnsignedAuthTokenRequestXml(options) {
+  const { challenge, contextIdentifier, subjectIdentifierType = "certificateSubject" } = options;
+  const identifierElement = `<${contextIdentifier.type}>${xmlEscape(contextIdentifier.value)}</${contextIdentifier.type}>`;
+  return [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    `<AuthTokenRequest xmlns="${AUTH_TOKEN_REQUEST_NS}">`,
+    `<Challenge>${xmlEscape(challenge)}</Challenge>`,
+    `<ContextIdentifier>`,
+    identifierElement,
+    `</ContextIdentifier>`,
+    `<SubjectIdentifierType>${xmlEscape(subjectIdentifierType)}</SubjectIdentifierType>`,
+    `</AuthTokenRequest>`
+  ].join("");
+}
+function xmlEscape(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+var AUTH_TOKEN_REQUEST_NS;
+var init_auth_xml_builder = __esm({
+  "src/crypto/auth-xml-builder.ts"() {
+    "use strict";
+    AUTH_TOKEN_REQUEST_NS = "http://ksef.mf.gov.pl/auth/token/2.0";
+  }
+});
+
 // src/qr/verification-link-service.ts
 import crypto5 from "crypto";
 var VerificationLinkService;
@@ -6853,19 +6948,11 @@ __export(client_exports, {
   buildAuthTokenRequestXml: () => buildAuthTokenRequestXml
 });
 function buildAuthTokenRequestXml(challenge, nip, subjectIdentifierType = "certificateSubject") {
-  return [
-    '<?xml version="1.0" encoding="utf-8"?>',
-    `<AuthTokenRequest xmlns="${AUTH_TOKEN_REQUEST_NS}">`,
-    `<Challenge>${xmlEscape(challenge)}</Challenge>`,
-    `<ContextIdentifier>`,
-    `<Nip>${xmlEscape(nip)}</Nip>`,
-    `</ContextIdentifier>`,
-    `<SubjectIdentifierType>${xmlEscape(subjectIdentifierType)}</SubjectIdentifierType>`,
-    `</AuthTokenRequest>`
-  ].join("");
-}
-function xmlEscape(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  return buildUnsignedAuthTokenRequestXml({
+    challenge,
+    contextIdentifier: { type: "Nip", value: nip },
+    subjectIdentifierType
+  });
 }
 function buildRestClientConfig(options, authManager) {
   const config = { authManager };
@@ -6892,7 +6979,7 @@ function buildRestClientConfig(options, authManager) {
   }
   return config;
 }
-var KSeFClient, AUTH_TOKEN_REQUEST_NS;
+var KSeFClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
@@ -6918,6 +7005,7 @@ var init_client = __esm({
     init_certificate_fetcher();
     init_cryptography_service();
     init_verification_link_service();
+    init_auth_xml_builder();
     KSeFClient = class {
       auth;
       activeSessions;
@@ -7011,7 +7099,6 @@ var init_client = __esm({
         this.authManager.setRefreshToken(void 0);
       }
     };
-    AUTH_TOKEN_REQUEST_NS = "http://ksef.mf.gov.pl/auth/token/2.0";
   }
 });
 
@@ -7145,6 +7232,65 @@ var SUBUNIT_NAME_MAX_LENGTH = 256;
 var PERMISSION_DESCRIPTION_MIN_LENGTH = 5;
 var PERMISSION_DESCRIPTION_MAX_LENGTH = 256;
 
+// src/models/document-structures/types.ts
+var SystemCode = {
+  FA_2: "FA (2)",
+  FA_3: "FA (3)",
+  PEF_3: "PEF (3)",
+  PEF_KOR_3: "PEF_KOR (3)",
+  FA_RR_1: "FA_RR (1)"
+};
+var FORM_CODES = {
+  FA_2: { systemCode: "FA (2)", schemaVersion: "1-0E", value: "FA" },
+  FA_3: { systemCode: "FA (3)", schemaVersion: "1-0E", value: "FA" },
+  PEF_3: { systemCode: "PEF (3)", schemaVersion: "2-1", value: "PEF" },
+  PEF_KOR_3: { systemCode: "PEF_KOR (3)", schemaVersion: "2-1", value: "PEF" },
+  FA_RR_1_LEGACY: { systemCode: "FA_RR (1)", schemaVersion: "1-0E", value: "RR" },
+  FA_RR_1_TRANSITION: { systemCode: "FA_RR (1)", schemaVersion: "1-1E", value: "RR" },
+  FA_RR_1: { systemCode: "FA_RR (1)", schemaVersion: "1-1E", value: "FA_RR" }
+};
+var INVOICE_TYPES_BY_SYSTEM_CODE = {
+  [SystemCode.FA_2]: ["Vat", "Zal", "Kor", "Roz", "Upr", "KorZal", "KorRoz"],
+  [SystemCode.FA_3]: ["Vat", "Zal", "Kor", "Roz", "Upr", "KorZal", "KorRoz"],
+  [SystemCode.PEF_3]: ["VatPef", "VatPefSp", "KorPef"],
+  [SystemCode.PEF_KOR_3]: ["KorPef"],
+  [SystemCode.FA_RR_1]: ["VatRr", "KorVatRr"]
+};
+var FORM_CODE_KEYS = {
+  FA2: FORM_CODES.FA_2,
+  FA3: FORM_CODES.FA_3,
+  PEF3: FORM_CODES.PEF_3,
+  PEFKOR3: FORM_CODES.PEF_KOR_3,
+  FARR1: FORM_CODES.FA_RR_1
+};
+
+// src/models/document-structures/helpers.ts
+var SYSTEM_CODE_TO_FORM_CODE = {
+  [SystemCode.FA_2]: FORM_CODES.FA_2,
+  [SystemCode.FA_3]: FORM_CODES.FA_3,
+  [SystemCode.PEF_3]: FORM_CODES.PEF_3,
+  [SystemCode.PEF_KOR_3]: FORM_CODES.PEF_KOR_3,
+  [SystemCode.FA_RR_1]: FORM_CODES.FA_RR_1
+};
+var ALL_FORM_CODES = Object.values(FORM_CODES);
+var BATCH_DISALLOWED_SYSTEM_CODES = /* @__PURE__ */ new Set([
+  SystemCode.PEF_3,
+  SystemCode.PEF_KOR_3
+]);
+function getFormCode(systemCode) {
+  return SYSTEM_CODE_TO_FORM_CODE[systemCode];
+}
+function parseFormCode(raw) {
+  const match = ALL_FORM_CODES.find(
+    (fc) => fc.systemCode === raw.systemCode && fc.schemaVersion === raw.schemaVersion && fc.value === raw.value
+  );
+  return match ?? raw;
+}
+function validateFormCodeForSession(formCode, sessionType) {
+  if (sessionType === "online") return true;
+  return !BATCH_DISALLOWED_SYSTEM_CODES.has(formCode.systemCode);
+}
+
 // src/services/index.ts
 init_auth();
 init_active_sessions();
@@ -7561,6 +7707,108 @@ var BatchFileBuilder = class {
       encryptedParts
     };
   }
+  /**
+   * Stream-based variant: two-pass build from a stream factory.
+   *
+   * Pass 1: consume stream to compute ZIP hash.
+   * Pass 2: re-create stream, split into parts, encrypt each, compute per-part metadata.
+   *
+   * @param zipStreamFactory - Factory that creates a fresh ReadableStream of the ZIP data
+   * @param zipSize - Total ZIP byte size (from fs.stat or known in advance)
+   * @param encryptStreamFn - Stream-to-stream AES-256-CBC encryption function
+   * @param hashStreamFn - Stream-to-FileMetadata hashing function
+   * @param options - Optional configuration
+   */
+  static async buildFromStream(zipStreamFactory, zipSize, encryptStreamFn, hashStreamFn, options) {
+    const maxPartSize = options?.maxPartSize ?? BATCH_MAX_PART_SIZE;
+    if (maxPartSize <= 0) {
+      throw new KSeFValidationError("maxPartSize must be a positive number");
+    }
+    if (zipSize === 0) {
+      throw new KSeFValidationError("ZIP data must not be empty");
+    }
+    if (zipSize > BATCH_MAX_TOTAL_SIZE) {
+      throw new KSeFValidationError(
+        `ZIP size ${zipSize} exceeds maximum of ${BATCH_MAX_TOTAL_SIZE} bytes (5 GB)`
+      );
+    }
+    const partCount = Math.ceil(zipSize / maxPartSize);
+    if (partCount > BATCH_MAX_PARTS) {
+      throw new KSeFValidationError(
+        `Data requires ${partCount} parts, exceeding maximum of ${BATCH_MAX_PARTS}`
+      );
+    }
+    const zipMeta = await hashStreamFn(zipStreamFactory());
+    const fileParts = [];
+    const streamParts = [];
+    const reader = zipStreamFactory().getReader();
+    let pending = [];
+    let pendingSize = 0;
+    for (let partIndex = 0; partIndex < partCount; partIndex++) {
+      const isLastPart = partIndex === partCount - 1;
+      const targetSize = isLastPart ? zipSize - partIndex * maxPartSize : maxPartSize;
+      while (pendingSize < targetSize) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        pending.push(value);
+        pendingSize += value.byteLength;
+      }
+      const buffer = new Uint8Array(Buffer.concat(pending));
+      const partData = buffer.subarray(0, targetSize);
+      if (buffer.byteLength > targetSize) {
+        const remainder = buffer.subarray(targetSize);
+        pending = [remainder];
+        pendingSize = remainder.byteLength;
+      } else {
+        pending = [];
+        pendingSize = 0;
+      }
+      const partStream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(partData);
+          controller.close();
+        }
+      });
+      const encryptedStream = encryptStreamFn(partStream);
+      const encryptedChunks = [];
+      const encReader = encryptedStream.getReader();
+      for (; ; ) {
+        const { done, value } = await encReader.read();
+        if (done) break;
+        encryptedChunks.push(value);
+      }
+      const encryptedData = new Uint8Array(Buffer.concat(encryptedChunks));
+      const encryptedMeta = sha256Base64(encryptedData);
+      fileParts.push({
+        ordinalNumber: partIndex + 1,
+        fileSize: encryptedData.byteLength,
+        fileHash: encryptedMeta
+      });
+      const uploadStream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encryptedData);
+          controller.close();
+        }
+      });
+      streamParts.push({
+        dataStream: uploadStream,
+        metadata: {
+          hashSHA: encryptedMeta,
+          fileSize: encryptedData.byteLength
+        },
+        ordinalNumber: partIndex + 1
+      });
+    }
+    reader.releaseLock();
+    return {
+      batchFile: {
+        fileSize: zipSize,
+        fileHash: zipMeta.hashSHA,
+        fileParts
+      },
+      streamParts
+    };
+  }
 };
 function splitBuffer(data, maxPartSize) {
   if (data.length <= maxPartSize) {
@@ -7664,6 +7912,7 @@ ${lines.join("\n")}
 
 // src/crypto/index.ts
 init_pkcs12_loader();
+init_auth_xml_builder();
 
 // src/qr/index.ts
 init_verification_link_service();
@@ -7727,6 +7976,94 @@ function escapeXml2(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 
+// src/utils/zip.ts
+import { ZipFile } from "yazl";
+import { fromBuffer } from "yauzl";
+var DEFAULT_UNZIP_OPTIONS = {
+  maxFiles: 1e4,
+  maxTotalUncompressedSize: 2e9,
+  maxFileUncompressedSize: 5e8,
+  maxCompressionRatio: 200
+};
+async function createZip(entries) {
+  return new Promise((resolve, reject) => {
+    const zipfile = new ZipFile();
+    for (const entry of entries) {
+      zipfile.addBuffer(Buffer.from(entry.content), entry.fileName);
+    }
+    const chunks = [];
+    zipfile.outputStream.on("data", (chunk) => chunks.push(chunk));
+    zipfile.outputStream.on("error", (err) => reject(err));
+    zipfile.outputStream.on("end", () => resolve(Buffer.concat(chunks)));
+    zipfile.end();
+  });
+}
+async function unzip(buffer, options = {}) {
+  const limits = { ...DEFAULT_UNZIP_OPTIONS, ...options };
+  return new Promise((resolve, reject) => {
+    fromBuffer(buffer, { lazyEntries: true }, (err, zipfile) => {
+      if (err || !zipfile) {
+        reject(err ?? new Error("Failed to open zip buffer"));
+        return;
+      }
+      const files = /* @__PURE__ */ new Map();
+      let totalUncompressed = 0;
+      zipfile.readEntry();
+      zipfile.on("entry", (entry) => {
+        if (entry.fileName.endsWith("/")) {
+          zipfile.readEntry();
+          return;
+        }
+        if (limits.maxFiles > 0 && files.size >= limits.maxFiles) {
+          reject(new Error("zip contains too many files"));
+          return;
+        }
+        const uncompressedSize = entry.uncompressedSize ?? 0;
+        const compressedSize = entry.compressedSize ?? 0;
+        if (limits.maxFileUncompressedSize > 0 && uncompressedSize > limits.maxFileUncompressedSize) {
+          reject(new Error("zip entry exceeds max_file_uncompressed_size"));
+          return;
+        }
+        if (limits.maxTotalUncompressedSize > 0) {
+          totalUncompressed += uncompressedSize;
+          if (totalUncompressed > limits.maxTotalUncompressedSize) {
+            reject(new Error("zip exceeds max_total_uncompressed_size"));
+            return;
+          }
+        }
+        if (limits.maxCompressionRatio !== null) {
+          if (compressedSize === 0 && uncompressedSize > 0) {
+            reject(new Error("zip entry has suspicious compression metadata"));
+            return;
+          }
+          if (compressedSize > 0 && uncompressedSize > 0) {
+            const ratio = uncompressedSize / compressedSize;
+            if (ratio > limits.maxCompressionRatio) {
+              reject(new Error("zip entry exceeds max_compression_ratio"));
+              return;
+            }
+          }
+        }
+        zipfile.openReadStream(entry, (streamErr, stream) => {
+          if (streamErr || !stream) {
+            reject(streamErr ?? new Error("Failed to read zip entry"));
+            return;
+          }
+          const chunks = [];
+          stream.on("data", (chunk) => chunks.push(chunk));
+          stream.on("error", (streamError) => reject(streamError));
+          stream.on("end", () => {
+            files.set(entry.fileName, Buffer.concat(chunks));
+            zipfile.readEntry();
+          });
+        });
+      });
+      zipfile.on("end", () => resolve(files));
+      zipfile.on("error", (zipErr) => reject(zipErr));
+    });
+  });
+}
+
 // src/workflows/polling.ts
 async function pollUntil(action, condition, options) {
   const intervalMs = options?.intervalMs ?? 2e3;
@@ -7744,17 +8081,150 @@ async function pollUntil(action, condition, options) {
   );
 }
 
+// src/xml/upo-parser.ts
+init_ksef_validation_error();
+import { XMLParser } from "fast-xml-parser";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, at) {
+  if (!isRecord(value)) {
+    throw KSeFValidationError.fromField(at, `Expected object at ${at}`);
+  }
+  return value;
+}
+function requireString(value, at) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw KSeFValidationError.fromField(at, `Expected non-empty string at ${at}`);
+  }
+  return value;
+}
+function optionalRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function requireNumberFromString(value, at) {
+  const raw = requireString(value, at);
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) {
+    throw KSeFValidationError.fromField(at, `Expected integer at ${at}, got "${raw}"`);
+  }
+  return parsed;
+}
+function ensureArray(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function parseIdKontekstu(obj) {
+  const nip = optionalString(obj.Nip);
+  if (nip) return { kind: "Nip", nip };
+  const idWewnetrzny = optionalString(obj.IdWewnetrzny);
+  if (idWewnetrzny) return { kind: "IdWewnetrzny", idWewnetrzny };
+  const idZlozonyVatUE = optionalString(obj.IdZlozonyVatUE);
+  if (idZlozonyVatUE) return { kind: "IdZlozonyVatUE", idZlozonyVatUE };
+  const idDostawcyUslugPeppol = optionalString(obj.IdDostawcyUslugPeppol);
+  if (idDostawcyUslugPeppol) return { kind: "IdDostawcyUslugPeppol", idDostawcyUslugPeppol };
+  throw KSeFValidationError.fromField(
+    "Uwierzytelnienie.IdKontekstu",
+    "Unsupported context identifier. Expected Nip | IdWewnetrzny | IdZlozonyVatUE | IdDostawcyUslugPeppol"
+  );
+}
+function parseProof(obj) {
+  const tokenRef = optionalString(obj.NumerReferencyjnyTokenaKSeF);
+  if (tokenRef) return { kind: "NumerReferencyjnyTokenaKSeF", numerReferencyjnyTokenaKSeF: tokenRef };
+  const docHash = optionalString(obj.SkrotDokumentuUwierzytelniajacego);
+  if (docHash) return { kind: "SkrotDokumentuUwierzytelniajacego", skrotDokumentuUwierzytelniajacego: docHash };
+  throw KSeFValidationError.fromField(
+    "Uwierzytelnienie",
+    "Unsupported auth proof. Expected NumerReferencyjnyTokenaKSeF | SkrotDokumentuUwierzytelniajacego"
+  );
+}
+function parseUwierzytelnienie(obj) {
+  const idKontekstu = parseIdKontekstu(
+    requireRecord(obj.IdKontekstu, "Uwierzytelnienie.IdKontekstu")
+  );
+  const proof = parseProof(obj);
+  return { idKontekstu, proof };
+}
+function parseOpisPotwierdzenia(obj) {
+  return {
+    strona: requireNumberFromString(obj.Strona, "OpisPotwierdzenia.Strona"),
+    liczbaStron: requireNumberFromString(obj.LiczbaStron, "OpisPotwierdzenia.LiczbaStron"),
+    zakresDokumentowOd: requireNumberFromString(obj.ZakresDokumentowOd, "OpisPotwierdzenia.ZakresDokumentowOd"),
+    zakresDokumentowDo: requireNumberFromString(obj.ZakresDokumentowDo, "OpisPotwierdzenia.ZakresDokumentowDo"),
+    calkowitaLiczbaDokumentow: requireNumberFromString(obj.CalkowitaLiczbaDokumentow, "OpisPotwierdzenia.CalkowitaLiczbaDokumentow")
+  };
+}
+function parseDokument(obj) {
+  return {
+    nipSprzedawcy: requireString(obj.NipSprzedawcy, "Dokument.NipSprzedawcy"),
+    numerKSeFDokumentu: requireString(obj.NumerKSeFDokumentu, "Dokument.NumerKSeFDokumentu"),
+    numerFaktury: requireString(obj.NumerFaktury, "Dokument.NumerFaktury"),
+    dataWystawieniaFaktury: requireString(obj.DataWystawieniaFaktury, "Dokument.DataWystawieniaFaktury"),
+    dataPrzeslaniaDokumentu: requireString(obj.DataPrzeslaniaDokumentu, "Dokument.DataPrzeslaniaDokumentu"),
+    dataNadaniaNumeruKSeF: requireString(obj.DataNadaniaNumeruKSeF, "Dokument.DataNadaniaNumeruKSeF"),
+    skrotDokumentu: requireString(obj.SkrotDokumentu, "Dokument.SkrotDokumentu"),
+    trybWysylki: requireString(obj.TrybWysylki, "Dokument.TrybWysylki")
+  };
+}
+var upoParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  parseTagValue: false,
+  parseAttributeValue: false,
+  removeNSPrefix: true,
+  trimValues: false
+});
+function parseUpoXml(xml) {
+  const text = Buffer.isBuffer(xml) ? xml.toString("utf8") : xml;
+  const parsed = upoParser.parse(text);
+  const potwierdzenie = requireRecord(parsed?.Potwierdzenie, "Potwierdzenie");
+  const opisPotwierdzenia = optionalRecord(potwierdzenie.OpisPotwierdzenia);
+  const dokumenty = ensureArray(potwierdzenie.Dokument).map(
+    (doc, i) => parseDokument(requireRecord(doc, `Dokument[${i}]`))
+  );
+  if (dokumenty.length === 0) {
+    throw KSeFValidationError.fromField("Dokument", "Expected at least one Dokument in UPO");
+  }
+  return {
+    nazwaPodmiotuPrzyjmujacego: requireString(potwierdzenie.NazwaPodmiotuPrzyjmujacego, "NazwaPodmiotuPrzyjmujacego"),
+    numerReferencyjnySesji: requireString(potwierdzenie.NumerReferencyjnySesji, "NumerReferencyjnySesji"),
+    uwierzytelnienie: parseUwierzytelnienie(requireRecord(potwierdzenie.Uwierzytelnienie, "Uwierzytelnienie")),
+    ...opisPotwierdzenia && { opisPotwierdzenia: parseOpisPotwierdzenia(opisPotwierdzenia) },
+    nazwaStrukturyLogicznej: requireString(potwierdzenie.NazwaStrukturyLogicznej, "NazwaStrukturyLogicznej"),
+    kodFormularza: requireString(potwierdzenie.KodFormularza, "KodFormularza"),
+    dokumenty
+  };
+}
+
 // src/workflows/online-session-workflow.ts
-var DEFAULT_FORM_CODE = { systemCode: "FA", schemaVersion: "3", value: "FA (3)" };
 async function openOnlineSession(client, options) {
   await client.crypto.init();
   const encData = client.crypto.getEncryptionData();
-  const formCode = options?.formCode ?? DEFAULT_FORM_CODE;
+  const formCode = options?.formCode ?? FORM_CODES.FA_2;
   const openResp = await client.onlineSession.openSession(
     { formCode, encryption: encData.encryptionInfo },
     options?.upoVersion
   );
   const sessionRef = openResp.referenceNumber;
+  async function fetchUpo(pollOpts) {
+    const result = await pollUntil(
+      () => client.sessionStatus.getSessionStatus(sessionRef),
+      (s) => s.status.code === 200 || s.status.code >= 400,
+      { ...pollOpts, description: `UPO for session ${sessionRef}` }
+    );
+    if (result.status.code !== 200) {
+      throw new Error(`Session failed: ${result.status.code} \u2014 ${result.status.description}`);
+    }
+    return {
+      pages: result.upo?.pages ?? [],
+      invoiceCount: result.invoiceCount,
+      successfulInvoiceCount: result.successfulInvoiceCount,
+      failedInvoiceCount: result.failedInvoiceCount
+    };
+  }
   return {
     sessionRef,
     validUntil: openResp.validUntil,
@@ -7776,20 +8246,16 @@ async function openOnlineSession(client, options) {
       await client.onlineSession.closeSession(sessionRef);
     },
     async waitForUpo(pollOpts) {
-      const result = await pollUntil(
-        () => client.sessionStatus.getSessionStatus(sessionRef),
-        (s) => s.status.code === 200 || s.status.code >= 400,
-        { ...pollOpts, description: `UPO for session ${sessionRef}` }
-      );
-      if (result.status.code !== 200) {
-        throw new Error(`Session failed: ${result.status.code} \u2014 ${result.status.description}`);
-      }
-      return {
-        pages: result.upo?.pages ?? [],
-        invoiceCount: result.invoiceCount,
-        successfulInvoiceCount: result.successfulInvoiceCount,
-        failedInvoiceCount: result.failedInvoiceCount
-      };
+      return fetchUpo(pollOpts);
+    },
+    async waitForUpoParsed(pollOpts) {
+      const upoInfo = await fetchUpo(pollOpts);
+      const parsed = [];
+      for (const page of upoInfo.pages) {
+        const result = await client.sessionStatus.getSessionUpo(sessionRef, page.referenceNumber);
+        parsed.push(parseUpoXml(result.upo));
+      }
+      return { ...upoInfo, parsed };
     }
   };
 }
@@ -7803,11 +8269,10 @@ async function openSendAndClose(client, invoices, options) {
 }
 
 // src/workflows/batch-session-workflow.ts
-var DEFAULT_FORM_CODE2 = { systemCode: "FA", schemaVersion: "3", value: "FA (3)" };
 async function uploadBatch(client, zipData, options) {
   await client.crypto.init();
   const encData = client.crypto.getEncryptionData();
-  const formCode = options?.formCode ?? DEFAULT_FORM_CODE2;
+  const formCode = options?.formCode ?? FORM_CODES.FA_2;
   const encryptFn = (part) => client.crypto.encryptAES256(part, encData.cipherKey, encData.cipherIv);
   const { batchFile, encryptedParts } = BatchFileBuilder.build(zipData, encryptFn, {
     maxPartSize: options?.maxPartSize
@@ -7849,6 +8314,72 @@ async function uploadBatch(client, zipData, options) {
     }
   };
 }
+async function uploadBatchStream(client, zipStreamFactory, zipSize, options) {
+  await client.crypto.init();
+  const encData = client.crypto.getEncryptionData();
+  const formCode = options?.formCode ?? FORM_CODES.FA_2;
+  const encryptStreamFn = (stream) => client.crypto.encryptAES256Stream(stream, encData.cipherKey, encData.cipherIv);
+  const hashStreamFn = (stream) => client.crypto.getFileMetadataFromStream(stream);
+  const { batchFile, streamParts } = await BatchFileBuilder.buildFromStream(
+    zipStreamFactory,
+    zipSize,
+    encryptStreamFn,
+    hashStreamFn,
+    { maxPartSize: options?.maxPartSize }
+  );
+  const openResp = await client.batchSession.openSession(
+    {
+      formCode,
+      encryption: encData.encryptionInfo,
+      batchFile,
+      offlineMode: options?.offlineMode
+    },
+    options?.upoVersion
+  );
+  await client.batchSession.sendPartsWithStream(openResp, streamParts);
+  await client.batchSession.closeSession(openResp.referenceNumber);
+  const result = await pollUntil(
+    () => client.sessionStatus.getSessionStatus(openResp.referenceNumber),
+    (s) => s.status.code === 200 || s.status.code >= 400,
+    { ...options?.pollOptions, description: `UPO for batch ${openResp.referenceNumber}` }
+  );
+  if (result.status.code !== 200) {
+    throw new Error(`Batch session failed: ${result.status.code} \u2014 ${result.status.description}`);
+  }
+  return {
+    sessionRef: openResp.referenceNumber,
+    upo: {
+      pages: result.upo?.pages ?? [],
+      invoiceCount: result.invoiceCount,
+      successfulInvoiceCount: result.successfulInvoiceCount,
+      failedInvoiceCount: result.failedInvoiceCount
+    }
+  };
+}
+async function uploadBatchStreamParsed(client, zipStreamFactory, zipSize, options) {
+  const result = await uploadBatchStream(client, zipStreamFactory, zipSize, options);
+  const parsed = [];
+  for (const page of result.upo.pages) {
+    const upoResult = await client.sessionStatus.getSessionUpo(result.sessionRef, page.referenceNumber);
+    parsed.push(parseUpoXml(upoResult.upo));
+  }
+  return {
+    sessionRef: result.sessionRef,
+    upo: { ...result.upo, parsed }
+  };
+}
+async function uploadBatchParsed(client, zipData, options) {
+  const result = await uploadBatch(client, zipData, options);
+  const parsed = [];
+  for (const page of result.upo.pages) {
+    const upoResult = await client.sessionStatus.getSessionUpo(result.sessionRef, page.referenceNumber);
+    parsed.push(parseUpoXml(upoResult.upo));
+  }
+  return {
+    sessionRef: result.sessionRef,
+    upo: { ...result.upo, parsed }
+  };
+}
 
 // src/workflows/invoice-export-workflow.ts
 async function doExport(client, filters, options) {
@@ -7872,6 +8403,7 @@ async function doExport(client, filters, options) {
   }
   return {
     encData,
+    referenceNumber: opResp.referenceNumber,
     result: {
       parts: result.package.parts.map((p) => ({
         ordinalNumber: p.ordinalNumber,
@@ -7884,7 +8416,8 @@ async function doExport(client, filters, options) {
       })),
       invoiceCount: result.package.invoiceCount,
       isTruncated: result.package.isTruncated,
-      permanentStorageHwmDate: result.package.permanentStorageHwmDate
+      permanentStorageHwmDate: result.package.permanentStorageHwmDate,
+      lastPermanentStorageDate: result.package.lastPermanentStorageDate
     }
   };
 }
@@ -7905,13 +8438,144 @@ async function exportAndDownload(client, filters, options) {
     const decrypted = client.crypto.decryptAES256(encryptedData, encData.cipherKey, encData.cipherIv);
     decryptedParts.push(decrypted);
   }
+  if (options?.extract) {
+    const zipBuffer = Buffer.concat(decryptedParts);
+    const files = await unzip(zipBuffer, options.unzipOptions);
+    return { ...exportResult, files };
+  }
   return {
     ...exportResult,
     decryptedParts
   };
 }
 
+// src/workflows/hwm-coordinator.ts
+function updateContinuationPoint(points, subjectType, pkg) {
+  if (pkg.isTruncated && pkg.lastPermanentStorageDate) {
+    points[subjectType] = pkg.lastPermanentStorageDate;
+  } else if (pkg.permanentStorageHwmDate) {
+    points[subjectType] = pkg.permanentStorageHwmDate;
+  } else {
+    delete points[subjectType];
+  }
+}
+function getEffectiveStartDate(points, subjectType, windowFrom) {
+  return points[subjectType] ?? windowFrom;
+}
+function deduplicateByKsefNumber(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const key = entry.ksefNumber.toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// src/workflows/incremental-export-workflow.ts
+async function incrementalExportAndDownload(client, options) {
+  const maxIterations = options.maxIterations ?? 20;
+  const points = options.continuationPoints;
+  if (options.store) {
+    const loaded = await options.store.load();
+    for (const [key, value] of Object.entries(loaded)) {
+      if (value !== void 0 && points[key] === void 0) {
+        points[key] = value;
+      }
+    }
+  }
+  const referenceNumbers = [];
+  const decryptedParts = [];
+  let previousFrom;
+  let iteration = 0;
+  for (; iteration < maxIterations; iteration++) {
+    const effectiveFrom = getEffectiveStartDate(points, options.subjectType, options.windowFrom);
+    if (previousFrom !== void 0 && effectiveFrom === previousFrom) {
+      break;
+    }
+    previousFrom = effectiveFrom;
+    const filters = options.filtersFactory ? options.filtersFactory(effectiveFrom, options.windowTo) : buildDefaultFilters(options.subjectType, effectiveFrom, options.windowTo);
+    const { result, encData, referenceNumber } = await doExport(client, filters, {
+      onlyMetadata: options.onlyMetadata,
+      pollOptions: options.pollOptions
+    });
+    referenceNumbers.push(referenceNumber);
+    const download = options.transport ?? fetch;
+    for (const part of result.parts) {
+      const resp = await download(part.url, { method: part.method });
+      if (!resp.ok) {
+        throw new Error(`Download failed for part ${part.ordinalNumber}: HTTP ${resp.status}`);
+      }
+      const encryptedData = new Uint8Array(await resp.arrayBuffer());
+      const decrypted = client.crypto.decryptAES256(encryptedData, encData.cipherKey, encData.cipherIv);
+      decryptedParts.push(decrypted);
+    }
+    updateContinuationPoint(points, options.subjectType, {
+      isTruncated: result.isTruncated,
+      lastPermanentStorageDate: result.lastPermanentStorageDate,
+      permanentStorageHwmDate: result.permanentStorageHwmDate
+    });
+    if (options.store) {
+      await options.store.save(points);
+    }
+    options.onIterationComplete?.(iteration, result);
+    if (!result.isTruncated) {
+      iteration++;
+      break;
+    }
+  }
+  return {
+    referenceNumbers,
+    invoices: [],
+    decryptedParts,
+    continuationPoints: points,
+    iterationCount: iteration
+  };
+}
+function buildDefaultFilters(subjectType, from, to) {
+  return {
+    subjectType,
+    dateRange: {
+      dateType: "PermanentStorage",
+      from,
+      to
+    }
+  };
+}
+
+// src/workflows/hwm-storage.ts
+import * as fs from "fs/promises";
+var InMemoryHwmStore = class {
+  points = {};
+  async load() {
+    return { ...this.points };
+  }
+  async save(points) {
+    this.points = { ...points };
+  }
+};
+var FileHwmStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  async load() {
+    try {
+      const data = await fs.readFile(this.filePath, "utf-8");
+      return JSON.parse(data);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return {};
+      }
+      throw err;
+    }
+  }
+  async save(points) {
+    await fs.writeFile(this.filePath, JSON.stringify(points, null, 2), "utf-8");
+  }
+};
+
 // src/workflows/auth-workflow.ts
+init_auth_xml_builder();
 async function authenticateWithToken(client, options) {
   const challenge = await client.auth.getChallenge();
   await client.crypto.init();
@@ -7965,6 +8629,34 @@ async function authenticateWithCertificate(client, options) {
     refreshTokenValidUntil: tokens.refreshToken.validUntil
   };
 }
+async function authenticateWithExternalSignature(client, options) {
+  const challenge = await client.auth.getChallenge();
+  const unsignedXml = buildUnsignedAuthTokenRequestXml({
+    challenge: challenge.challenge,
+    contextIdentifier: options.contextIdentifier
+  });
+  const signedXml = await options.signXml(unsignedXml);
+  const submitResult = await client.auth.submitXadesAuthRequest(
+    signedXml,
+    options.verifyCertificateChain ?? false,
+    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
+  };
+}
 async function authenticateWithPkcs12(client, options) {
   const { Pkcs12Loader: Pkcs12Loader2 } = await Promise.resolve().then(() => (init_pkcs12_loader(), pkcs12_loader_exports));
   const { certificatePem, privateKeyPem } = Pkcs12Loader2.load(options.p12, options.password);
@@ -8004,6 +8696,11 @@ export {
   ENFORCE_XADES_COMPLIANCE,
   EntityPermissionGrantBuilder,
   Environment,
+  FORM_CODES,
+  FORM_CODE_KEYS,
+  FileHwmStore,
+  INVOICE_TYPES_BY_SYSTEM_CODE,
+  InMemoryHwmStore,
   InternalId,
   InvoiceDownloadService,
   InvoiceQueryFilterBuilder,
@@ -8049,21 +8746,29 @@ export {
   SessionStatusService,
   Sha256Base64,
   SignatureService,
+  SystemCode,
   TestDataService,
   TokenService,
   UpoVersion,
   VatUe,
   VerificationLinkService,
   authenticateWithCertificate,
+  authenticateWithExternalSignature,
   authenticateWithPkcs12,
   authenticateWithToken,
+  buildUnsignedAuthTokenRequestXml,
   calculateBackoff,
+  createZip,
+  deduplicateByKsefNumber,
   defaultPresignedUrlPolicy,
   defaultRateLimitPolicy,
   defaultRetryPolicy,
   defaultTransport,
   exportAndDownload,
   exportInvoices,
+  getEffectiveStartDate,
+  getFormCode,
+  incrementalExportAndDownload,
   isRetryableError,
   isRetryableStatus,
   isValidBase64,
@@ -8083,11 +8788,19 @@ export {
   isValidVatUe,
   openOnlineSession,
   openSendAndClose,
+  parseFormCode,
   parseRetryAfter,
+  parseUpoXml,
   pollUntil,
   resolveOptions,
   sleep,
+  unzip,
+  updateContinuationPoint,
   uploadBatch,
+  uploadBatchParsed,
+  uploadBatchStream,
+  uploadBatchStreamParsed,
+  validateFormCodeForSession,
   validatePresignedUrl
 };
 //# sourceMappingURL=index.js.map