ksef-client-ts 0.5.2 → 0.6.0

package/dist/index.cjs

@@ -320,21 +320,21 @@ var init_rest_request = __esm({
       _query = [];
       _presigned = false;
       _skipAuthRetry = false;
-      constructor(method, path) {
+      constructor(method, path2) {
         this.method = method;
-        this.path = path;
+        this.path = path2;
       }
-      static get(path) {
-        return new _RestRequest("GET", path);
+      static get(path2) {
+        return new _RestRequest("GET", path2);
       }
-      static post(path) {
-        return new _RestRequest("POST", path);
+      static post(path2) {
+        return new _RestRequest("POST", path2);
       }
-      static put(path) {
-        return new _RestRequest("PUT", path);
+      static put(path2) {
+        return new _RestRequest("PUT", path2);
       }
-      static delete(path) {
-        return new _RestRequest("DELETE", path);
+      static delete(path2) {
+        return new _RestRequest("DELETE", path2);
       }
       body(data) {
         this._body = data;
@@ -654,9 +654,9 @@ var init_rest_client = __esm({
         return response;
       }
       buildUrl(request) {
-        const path = this.routeBuilder.build(request.path);
+        const path2 = this.routeBuilder.build(request.path);
         const base = this.options.baseUrl;
-        const url = new URL(`${base}${path}`);
+        const url = new URL(`${base}${path2}`);
         const query = request.getQuery();
         for (const [key, value] of query) {
           url.searchParams.append(key, value);
@@ -2668,11 +2668,11 @@ async function validateSchema(xml, options, _parsed) {
   const prefix = rootElement ? `/${rootElement}/` : "/";
   const validationErrors = result.error.issues.map((issue) => {
     const zodPath = issue.path.join("/");
-    const path = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
+    const path2 = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
     return {
       code: mapZodErrorCode(issue),
       message: issue.message,
-      path
+      path: path2
     };
   });
   return { valid: false, schemaType, errors: validationErrors };
@@ -2712,9 +2712,9 @@ function validateBusinessRules(xml, _parsed) {
   collectDateErrors(object, rootElement, errors);
   return { valid: errors.length === 0, schemaType, errors };
 }
-function collectNipPeselErrors(obj, path, errors) {
+function collectNipPeselErrors(obj, path2, errors) {
   for (const [key, value] of Object.entries(obj)) {
-    const currentPath = path ? `${path}/${key}` : key;
+    const currentPath = path2 ? `${path2}/${key}` : key;
     if (key === "NIP" && typeof value === "string") {
       if (!isValidNip(value)) {
         errors.push({
@@ -2793,6 +2793,88 @@ var init_invoice_validator = __esm({
   }
 });
 
+// src/models/document-structures/types.ts
+var SystemCode, FORM_CODES, DEFAULT_FORM_CODE, INVOICE_TYPES_BY_SYSTEM_CODE, FORM_CODE_KEYS;
+var init_types = __esm({
+  "src/models/document-structures/types.ts"() {
+    "use strict";
+    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)"
+    };
+    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" }
+    };
+    DEFAULT_FORM_CODE = FORM_CODES.FA_3;
+    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"]
+    };
+    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
+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);
+}
+var SYSTEM_CODE_TO_FORM_CODE, ALL_FORM_CODES, BATCH_DISALLOWED_SYSTEM_CODES;
+var init_helpers = __esm({
+  "src/models/document-structures/helpers.ts"() {
+    "use strict";
+    init_types();
+    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
+    };
+    ALL_FORM_CODES = Object.values(FORM_CODES);
+    BATCH_DISALLOWED_SYSTEM_CODES = /* @__PURE__ */ new Set([
+      SystemCode.PEF_3,
+      SystemCode.PEF_KOR_3
+    ]);
+  }
+});
+
+// src/models/document-structures/index.ts
+var init_document_structures = __esm({
+  "src/models/document-structures/index.ts"() {
+    "use strict";
+    init_types();
+    init_helpers();
+  }
+});
+
 // src/services/auth.ts
 var AuthService;
 var init_auth = __esm({
@@ -3358,20 +3440,20 @@ var init_lighthouse = __esm({
         this.lighthouseUrl = options.lighthouseUrl;
         this.timeout = options.timeout;
       }
-      async fetchJson(path) {
+      async fetchJson(path2) {
         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}${path}`, {
+        const response = await fetch(`${this.lighthouseUrl}${path2}`, {
           headers: { Accept: "application/json" },
           signal: AbortSignal.timeout(this.timeout)
         });
         if (!response.ok) {
           const body = await response.text();
           throw new KSeFError(
-            `Lighthouse ${path} failed: HTTP ${response.status} \u2014 ${body}`
+            `Lighthouse ${path2} failed: HTTP ${response.status} \u2014 ${body}`
           );
         }
         return await response.json();
@@ -4351,6 +4433,391 @@ var init_zip = __esm({
   }
 });
 
+// src/offline/deadline.ts
+function getDefaultReason(mode) {
+  switch (mode) {
+    case "offline24":
+      return "PLANNED";
+    case "offline":
+      return "SYSTEM_UNAVAILABLE";
+    case "awaryjny":
+      return "EMERGENCY";
+    case "awaria_calkowita":
+      return "TOTAL_FAILURE";
+  }
+}
+function nextBusinessDay(from) {
+  const d = new Date(from);
+  d.setUTCDate(d.getUTCDate() + 1);
+  while (d.getUTCDay() === 0 || d.getUTCDay() === 6) {
+    d.setUTCDate(d.getUTCDate() + 1);
+  }
+  return d;
+}
+function addBusinessDays(from, days) {
+  if (!Number.isInteger(days) || days < 0) {
+    throw new Error(`days must be a non-negative integer, got ${days}`);
+  }
+  const d = new Date(from);
+  let remaining = days;
+  while (remaining > 0) {
+    d.setUTCDate(d.getUTCDate() + 1);
+    if (d.getUTCDay() !== 0 && d.getUTCDay() !== 6) {
+      remaining--;
+    }
+  }
+  return d;
+}
+function endOfDay(d) {
+  const result = new Date(d);
+  result.setUTCHours(23, 59, 59, 999);
+  return result;
+}
+function getMaintenanceEndFallback(mw) {
+  if (mw.endTime) {
+    return new Date(mw.endTime);
+  }
+  const start = new Date(mw.startTime);
+  start.setUTCDate(start.getUTCDate() + 7);
+  return start;
+}
+function calculateOfflineDeadline(mode, invoiceDate, maintenanceWindow) {
+  const date = typeof invoiceDate === "string" ? new Date(invoiceDate) : invoiceDate;
+  switch (mode) {
+    case "offline24": {
+      return endOfDay(nextBusinessDay(date));
+    }
+    case "offline": {
+      const base = maintenanceWindow ? getMaintenanceEndFallback(maintenanceWindow) : date;
+      return endOfDay(nextBusinessDay(base));
+    }
+    case "awaryjny": {
+      const base = maintenanceWindow ? getMaintenanceEndFallback(maintenanceWindow) : date;
+      return endOfDay(addBusinessDays(base, 7));
+    }
+    case "awaria_calkowita": {
+      return new Date(FAR_FUTURE);
+    }
+  }
+}
+function extendDeadlineForMaintenance(currentDeadline, maintenanceWindow, mode = "awaryjny") {
+  const current = typeof currentDeadline === "string" ? new Date(currentDeadline) : new Date(currentDeadline);
+  const mwEnd = getMaintenanceEndFallback(maintenanceWindow);
+  if (mwEnd.getTime() > current.getTime()) {
+    switch (mode) {
+      case "offline24":
+      case "offline":
+        return endOfDay(nextBusinessDay(mwEnd));
+      case "awaryjny":
+        return endOfDay(addBusinessDays(mwEnd, 7));
+      case "awaria_calkowita":
+        return new Date(FAR_FUTURE);
+    }
+  }
+  return current;
+}
+function isExpired(submitBy) {
+  const deadline = typeof submitBy === "string" ? new Date(submitBy) : submitBy;
+  return Date.now() > deadline.getTime();
+}
+function getTimeUntilDeadline(submitBy) {
+  const deadline = typeof submitBy === "string" ? new Date(submitBy) : submitBy;
+  return Math.max(0, deadline.getTime() - Date.now());
+}
+var FAR_FUTURE;
+var init_deadline = __esm({
+  "src/offline/deadline.ts"() {
+    "use strict";
+    FAR_FUTURE = /* @__PURE__ */ new Date("9999-12-31T23:59:59Z");
+  }
+});
+
+// src/workflows/offline-invoice-workflow.ts
+var import_node_crypto2, OfflineInvoiceWorkflow;
+var init_offline_invoice_workflow = __esm({
+  "src/workflows/offline-invoice-workflow.ts"() {
+    "use strict";
+    import_node_crypto2 = __toESM(require("crypto"), 1);
+    init_ksef_api_error();
+    init_deadline();
+    init_document_structures();
+    OfflineInvoiceWorkflow = class {
+      constructor(qrService) {
+        this.qrService = qrService;
+      }
+      async generate(input, options) {
+        if (!input.invoiceXml || input.invoiceXml.trim().length === 0) {
+          throw new Error("invoiceXml must not be empty");
+        }
+        if (!input.invoiceNumber) {
+          throw new Error("invoiceNumber is required");
+        }
+        if (!input.sellerNip) {
+          throw new Error("sellerNip is required");
+        }
+        const mode = options?.mode ?? "offline24";
+        const reason = getDefaultReason(mode);
+        const invoiceHashBase64 = import_node_crypto2.default.createHash("sha256").update(input.invoiceXml).digest("base64");
+        const kod1Url = this.qrService.buildInvoiceVerificationUrl(
+          input.sellerNip,
+          input.invoiceDate,
+          invoiceHashBase64
+        );
+        let kod2Url;
+        if (options?.certificate) {
+          kod2Url = this.qrService.buildCertificateVerificationUrl(
+            input.sellerIdentifier.type,
+            input.sellerIdentifier.value,
+            input.sellerNip,
+            options.certificate.certificateSerial,
+            invoiceHashBase64,
+            options.certificate.privateKeyPem
+          );
+        }
+        const submitBy = options?.customDeadline ? typeof options.customDeadline === "string" ? options.customDeadline : options.customDeadline.toISOString() : calculateOfflineDeadline(mode, input.invoiceDate, options?.maintenanceWindow).toISOString();
+        const metadata = {
+          id: import_node_crypto2.default.randomUUID(),
+          mode,
+          reason,
+          status: "GENERATED",
+          invoiceNumber: input.invoiceNumber,
+          invoiceDate: input.invoiceDate,
+          invoiceXml: input.invoiceXml,
+          sellerNip: input.sellerNip,
+          sellerIdentifier: input.sellerIdentifier,
+          buyerIdentifier: input.buyerIdentifier,
+          totalAmount: input.totalAmount,
+          currency: input.currency,
+          kod1Url,
+          kod2Url,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          submitBy,
+          maintenanceWindowId: options?.maintenanceWindow?.id
+        };
+        if (options?.storage) {
+          await options.storage.save(metadata);
+        }
+        return metadata;
+      }
+      async submit(client, options) {
+        const { storage, checkExpiry = true } = options;
+        let invoices;
+        if (options.invoiceIds) {
+          invoices = [];
+          const notFound = [];
+          for (const id of options.invoiceIds) {
+            const inv = await storage.get(id);
+            if (inv) {
+              invoices.push(inv);
+            } else {
+              notFound.push(id);
+            }
+          }
+          if (notFound.length > 0) {
+            throw new Error(`Offline invoice(s) not found: ${notFound.join(", ")}`);
+          }
+        } else {
+          invoices = await storage.list({ status: ["GENERATED", "QUEUED", "SUBMITTED"] });
+        }
+        const result = {
+          total: invoices.length,
+          submitted: 0,
+          accepted: 0,
+          rejected: 0,
+          failed: 0,
+          expired: 0,
+          results: []
+        };
+        if (invoices.length === 0) return result;
+        const pending = [];
+        for (const inv of invoices) {
+          if (checkExpiry && isExpired(inv.submitBy)) {
+            await storage.update(inv.id, { status: "EXPIRED" });
+            result.expired++;
+            result.results.push({
+              invoiceId: inv.id,
+              invoiceNumber: inv.invoiceNumber,
+              status: "EXPIRED"
+            });
+          } else {
+            pending.push(inv);
+          }
+        }
+        if (pending.length === 0) return result;
+        await client.crypto.init();
+        const encData = client.crypto.getEncryptionData();
+        const formCode = options.formCode ?? DEFAULT_FORM_CODE;
+        const openResp = await client.onlineSession.openSession(
+          { formCode, encryption: encData.encryptionInfo }
+        );
+        const sessionRef = openResp.referenceNumber;
+        try {
+          for (const inv of pending) {
+            await storage.update(inv.id, { status: "QUEUED" });
+            try {
+              const data = new TextEncoder().encode(inv.invoiceXml);
+              const plainMeta = client.crypto.getFileMetadata(data);
+              const encrypted = client.crypto.encryptAES256(data, encData.cipherKey, encData.cipherIv);
+              const encMeta = client.crypto.getFileMetadata(encrypted);
+              await storage.update(inv.id, { status: "SUBMITTED", submittedAt: (/* @__PURE__ */ new Date()).toISOString() });
+              const resp = await client.onlineSession.sendInvoice(sessionRef, {
+                invoiceHash: plainMeta.hashSHA,
+                invoiceSize: plainMeta.fileSize,
+                encryptedInvoiceHash: encMeta.hashSHA,
+                encryptedInvoiceSize: encMeta.fileSize,
+                encryptedInvoiceContent: Buffer.from(encrypted).toString("base64"),
+                offlineMode: true
+              });
+              await storage.update(inv.id, {
+                status: "ACCEPTED",
+                acceptedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                ksefReferenceNumber: resp.referenceNumber
+              });
+              result.submitted++;
+              result.accepted++;
+              result.results.push({
+                invoiceId: inv.id,
+                invoiceNumber: inv.invoiceNumber,
+                status: "ACCEPTED",
+                ksefReferenceNumber: resp.referenceNumber
+              });
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              if (err instanceof KSeFApiError) {
+                await storage.update(inv.id, {
+                  status: "REJECTED",
+                  error: { code: err.statusCode, message }
+                });
+                result.submitted++;
+                result.rejected++;
+                result.results.push({
+                  invoiceId: inv.id,
+                  invoiceNumber: inv.invoiceNumber,
+                  status: "REJECTED",
+                  error: { code: err.statusCode, message }
+                });
+              } else {
+                await storage.update(inv.id, {
+                  status: "QUEUED",
+                  error: { code: 0, message }
+                });
+                result.failed++;
+                result.results.push({
+                  invoiceId: inv.id,
+                  invoiceNumber: inv.invoiceNumber,
+                  status: "QUEUED",
+                  error: { code: 0, message }
+                });
+              }
+            }
+          }
+        } finally {
+          try {
+            await client.onlineSession.closeSession(sessionRef);
+          } catch {
+          }
+        }
+        return result;
+      }
+      // TODO(perf): Each correction opens a separate KSeF session.
+      // For batch corrections, consider a correctBatch() sharing one session (like submit()).
+      async correct(client, options) {
+        const { storage, rejectedInvoiceId, correctedInvoiceXml } = options;
+        const original = await storage.get(rejectedInvoiceId);
+        if (!original) {
+          throw new Error(`Offline invoice not found: ${rejectedInvoiceId}`);
+        }
+        if (original.status !== "REJECTED") {
+          throw new Error(
+            original.status === "CORRECTED" ? `Invoice ${rejectedInvoiceId} has already been corrected (by ${original.correctedBy})` : `Only rejected invoices can be corrected (current status: ${original.status})`
+          );
+        }
+        const originalHash = import_node_crypto2.default.createHash("sha256").update(original.invoiceXml).digest("base64");
+        await client.crypto.init();
+        const encData = client.crypto.getEncryptionData();
+        const formCode = options.formCode ?? DEFAULT_FORM_CODE;
+        const openResp = await client.onlineSession.openSession(
+          { formCode, encryption: encData.encryptionInfo }
+        );
+        const sessionRef = openResp.referenceNumber;
+        try {
+          const data = new TextEncoder().encode(correctedInvoiceXml);
+          const plainMeta = client.crypto.getFileMetadata(data);
+          const encrypted = client.crypto.encryptAES256(data, encData.cipherKey, encData.cipherIv);
+          const encMeta = client.crypto.getFileMetadata(encrypted);
+          const correctionId = import_node_crypto2.default.randomUUID();
+          const submittedAt = (/* @__PURE__ */ new Date()).toISOString();
+          const correctedHashBase64 = import_node_crypto2.default.createHash("sha256").update(correctedInvoiceXml).digest("base64");
+          const kod1Url = this.qrService.buildInvoiceVerificationUrl(
+            original.sellerNip,
+            original.invoiceDate,
+            correctedHashBase64
+          );
+          let kod2Url;
+          if (options.certificate) {
+            kod2Url = this.qrService.buildCertificateVerificationUrl(
+              original.sellerIdentifier.type,
+              original.sellerIdentifier.value,
+              original.sellerNip,
+              options.certificate.certificateSerial,
+              correctedHashBase64,
+              options.certificate.privateKeyPem
+            );
+          }
+          const correctionMetadata = {
+            id: correctionId,
+            mode: original.mode,
+            reason: original.reason,
+            status: "SUBMITTED",
+            invoiceNumber: original.invoiceNumber,
+            invoiceDate: original.invoiceDate,
+            invoiceXml: correctedInvoiceXml,
+            sellerNip: original.sellerNip,
+            sellerIdentifier: original.sellerIdentifier,
+            buyerIdentifier: original.buyerIdentifier,
+            kod1Url,
+            kod2Url,
+            generatedAt: submittedAt,
+            submitBy: original.submitBy,
+            submittedAt,
+            correctedInvoiceId: rejectedInvoiceId
+          };
+          await storage.save(correctionMetadata);
+          const resp = await client.onlineSession.sendInvoice(sessionRef, {
+            invoiceHash: plainMeta.hashSHA,
+            invoiceSize: plainMeta.fileSize,
+            encryptedInvoiceHash: encMeta.hashSHA,
+            encryptedInvoiceSize: encMeta.fileSize,
+            encryptedInvoiceContent: Buffer.from(encrypted).toString("base64"),
+            offlineMode: true,
+            hashOfCorrectedInvoice: originalHash
+          });
+          await storage.update(correctionId, {
+            status: "ACCEPTED",
+            acceptedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            ksefReferenceNumber: resp.referenceNumber
+          });
+          await storage.update(rejectedInvoiceId, {
+            status: "CORRECTED",
+            correctedBy: correctionId
+          });
+          return {
+            invoiceId: correctionId,
+            invoiceNumber: correctionMetadata.invoiceNumber,
+            status: "ACCEPTED",
+            ksefReferenceNumber: resp.referenceNumber
+          };
+        } finally {
+          try {
+            await client.onlineSession.closeSession(sessionRef);
+          } catch {
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
@@ -4416,6 +4883,7 @@ var init_client = __esm({
     init_cryptography_service();
     init_verification_link_service();
     init_auth_xml_builder();
+    init_offline_invoice_workflow();
     KSeFClient = class {
       auth;
       activeSessions;
@@ -4434,6 +4902,7 @@ var init_client = __esm({
       qr;
       options;
       authManager;
+      _offline;
       constructor(options) {
         this.options = resolveOptions(options);
         const authManager = options?.authManager ?? new DefaultAuthManager(async () => {
@@ -4462,6 +4931,12 @@ var init_client = __esm({
         this.testData = new TestDataService(restClient, this.options.environmentName);
         this.qr = new VerificationLinkService(this.options.baseQrUrl);
       }
+      get offline() {
+        if (!this._offline) {
+          this._offline = new OfflineInvoiceWorkflow(this.qr);
+        }
+        return this._offline;
+      }
       async loginWithToken(token, nip) {
         const challenge = await this.auth.getChallenge();
         await this.crypto.init();
@@ -4542,8 +5017,10 @@ __export(index_exports, {
   FORM_CODES: () => FORM_CODES,
   FORM_CODE_KEYS: () => FORM_CODE_KEYS,
   FileHwmStore: () => FileHwmStore,
+  FileOfflineInvoiceStorage: () => FileOfflineInvoiceStorage,
   INVOICE_TYPES_BY_SYSTEM_CODE: () => INVOICE_TYPES_BY_SYSTEM_CODE,
   InMemoryHwmStore: () => InMemoryHwmStore,
+  InMemoryOfflineInvoiceStorage: () => InMemoryOfflineInvoiceStorage,
   InternalId: () => InternalId,
   InvoiceDownloadService: () => InvoiceDownloadService,
   InvoiceQueryFilterBuilder: () => InvoiceQueryFilterBuilder,
@@ -4567,6 +5044,7 @@ __export(index_exports, {
   LimitsService: () => LimitsService,
   Nip: () => Nip,
   NipVatUe: () => NipVatUe,
+  OfflineInvoiceWorkflow: () => OfflineInvoiceWorkflow,
   OnlineSessionService: () => OnlineSessionService,
   PERMISSION_DESCRIPTION_MAX_LENGTH: () => PERMISSION_DESCRIPTION_MAX_LENGTH,
   PERMISSION_DESCRIPTION_MIN_LENGTH: () => PERMISSION_DESCRIPTION_MIN_LENGTH,
@@ -4596,6 +5074,7 @@ __export(index_exports, {
   UpoVersion: () => UpoVersion,
   VatUe: () => VatUe,
   VerificationLinkService: () => VerificationLinkService,
+  addBusinessDays: () => addBusinessDays,
   authenticateWithCertificate: () => authenticateWithCertificate,
   authenticateWithExternalSignature: () => authenticateWithExternalSignature,
   authenticateWithPkcs12: () => authenticateWithPkcs12,
@@ -4603,6 +5082,7 @@ __export(index_exports, {
   batchValidationDetails: () => batchValidationDetails,
   buildUnsignedAuthTokenRequestXml: () => buildUnsignedAuthTokenRequestXml,
   calculateBackoff: () => calculateBackoff,
+  calculateOfflineDeadline: () => calculateOfflineDeadline,
   createZip: () => createZip,
   decodeJwtPayload: () => decodeJwtPayload,
   deduplicateByKsefNumber: () => deduplicateByKsefNumber,
@@ -4612,9 +5092,14 @@ __export(index_exports, {
   defaultTransport: () => defaultTransport,
   exportAndDownload: () => exportAndDownload,
   exportInvoices: () => exportInvoices,
+  extendDeadlineForMaintenance: () => extendDeadlineForMaintenance,
+  extractInvoiceFields: () => extractInvoiceFields,
+  getDefaultReason: () => getDefaultReason,
   getEffectiveStartDate: () => getEffectiveStartDate,
   getFormCode: () => getFormCode,
+  getTimeUntilDeadline: () => getTimeUntilDeadline,
   incrementalExportAndDownload: () => incrementalExportAndDownload,
+  isExpired: () => isExpired,
   isRetryableError: () => isRetryableError,
   isRetryableStatus: () => isRetryableStatus,
   isValidBase64: () => isValidBase64,
@@ -4632,6 +5117,7 @@ __export(index_exports, {
   isValidReferenceNumber: () => isValidReferenceNumber,
   isValidSha256Base64: () => isValidSha256Base64,
   isValidVatUe: () => isValidVatUe,
+  nextBusinessDay: () => nextBusinessDay,
   openOnlineSession: () => openOnlineSession,
   openSendAndClose: () => openSendAndClose,
   parseFormCode: () => parseFormCode,
@@ -4689,65 +5175,8 @@ init_xml_to_object();
 init_schema_registry();
 init_invoice_validator();
 
-// 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 DEFAULT_FORM_CODE = FORM_CODES.FA_3;
-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/models/index.ts
+init_document_structures();
 
 // src/services/index.ts
 init_auth();
@@ -5499,6 +5928,9 @@ async function pollUntil(action, condition, options) {
   );
 }
 
+// src/workflows/online-session-workflow.ts
+init_document_structures();
+
 // src/xml/upo-parser.ts
 var import_fast_xml_parser = require("fast-xml-parser");
 init_ksef_validation_error();
@@ -5617,6 +6049,46 @@ function parseUpoXml(xml) {
   };
 }
 
+// src/xml/invoice-field-extractor.ts
+var import_fast_xml_parser2 = require("fast-xml-parser");
+var invoiceParser = new import_fast_xml_parser2.XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  parseTagValue: false,
+  parseAttributeValue: false,
+  removeNSPrefix: true,
+  trimValues: false
+});
+function extractInvoiceFields(xml) {
+  const parsed = invoiceParser.parse(xml);
+  const root = parsed?.Faktura;
+  if (!root || typeof root !== "object") {
+    throw new Error(
+      "Cannot extract invoice fields: missing <Faktura> root element. Ensure the XML is a valid KSeF invoice (FA_2, FA_3, or FA_RR)."
+    );
+  }
+  if (root.Fa && typeof root.Fa === "object") {
+    const invoiceDate = nonEmptyString(root.Fa.P_1);
+    const invoiceNumber = nonEmptyString(root.Fa.P_2);
+    if (invoiceDate && invoiceNumber) {
+      return { invoiceNumber, invoiceDate };
+    }
+  }
+  if (root.FakturaRR && typeof root.FakturaRR === "object") {
+    const invoiceDate = nonEmptyString(root.FakturaRR.P_4B);
+    const invoiceNumber = nonEmptyString(root.FakturaRR.P_4C);
+    if (invoiceDate && invoiceNumber) {
+      return { invoiceNumber, invoiceDate };
+    }
+  }
+  throw new Error(
+    "Cannot extract invoice number and date from XML. Expected <Fa><P_1>/<P_2> (FA format) or <FakturaRR><P_4B>/<P_4C> (RR format)."
+  );
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
 // src/workflows/online-session-workflow.ts
 init_invoice_validator();
 init_ksef_validation_error();
@@ -5699,6 +6171,7 @@ async function openSendAndClose(client, invoices, options) {
 }
 
 // src/workflows/batch-session-workflow.ts
+init_document_structures();
 async function uploadBatch(client, zipData, options) {
   await client.crypto.init();
   if (options?.validate) {
@@ -6119,7 +6592,140 @@ async function authenticateWithPkcs12(client, options) {
   });
 }
 
+// src/offline/index.ts
+init_deadline();
+
+// src/offline/storage.ts
+function matchesFilter(invoice, filter) {
+  if (filter.status !== void 0) {
+    const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+    if (!statuses.includes(invoice.status)) return false;
+  }
+  if (filter.mode !== void 0 && invoice.mode !== filter.mode) return false;
+  if (filter.sellerNip !== void 0 && invoice.sellerNip !== filter.sellerNip) return false;
+  if (filter.expiringBefore !== void 0) {
+    const cutoff = typeof filter.expiringBefore === "string" ? new Date(filter.expiringBefore).getTime() : filter.expiringBefore.getTime();
+    if (new Date(invoice.submitBy).getTime() >= cutoff) return false;
+  }
+  return true;
+}
+var InMemoryOfflineInvoiceStorage = class {
+  store = /* @__PURE__ */ new Map();
+  async save(invoice) {
+    this.store.set(invoice.id, JSON.parse(JSON.stringify(invoice)));
+  }
+  async get(id) {
+    const entry = this.store.get(id);
+    return entry ? JSON.parse(JSON.stringify(entry)) : null;
+  }
+  async list(filter) {
+    const all = [...this.store.values()];
+    if (!filter) return all.map((i) => JSON.parse(JSON.stringify(i)));
+    return all.filter((i) => matchesFilter(i, filter)).map((i) => JSON.parse(JSON.stringify(i)));
+  }
+  async update(id, updates) {
+    const existing = this.store.get(id);
+    if (!existing) throw new Error(`Offline invoice not found: ${id}`);
+    this.store.set(id, JSON.parse(JSON.stringify({ ...existing, ...updates })));
+  }
+  async delete(id) {
+    this.store.delete(id);
+  }
+};
+
+// src/offline/file-storage.ts
+var fs2 = __toESM(require("fs/promises"), 1);
+var path = __toESM(require("path"), 1);
+var os = __toESM(require("os"), 1);
+function resolveDir(dir) {
+  if (dir === "~" || dir.startsWith("~/")) {
+    return path.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 fs2.mkdir(this.dir, { recursive: true });
+  }
+  filePath(id) {
+    validateId(id);
+    return path.join(this.dir, `${id}.json`);
+  }
+  async save(invoice) {
+    await this.ensureDir();
+    const file = this.filePath(invoice.id);
+    const tmp = `${file}.tmp`;
+    await fs2.writeFile(tmp, JSON.stringify(invoice, null, 2));
+    await fs2.rename(tmp, file);
+  }
+  async get(id) {
+    const file = this.filePath(id);
+    try {
+      return JSON.parse(await fs2.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 fs2.readdir(this.dir)).filter((f) => f.endsWith(".json"));
+    } catch {
+      return [];
+    }
+    const results = [];
+    for (const file of files) {
+      try {
+        const data = JSON.parse(
+          await fs2.readFile(path.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 fs2.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();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -6150,8 +6756,10 @@ init_client();
   FORM_CODES,
   FORM_CODE_KEYS,
   FileHwmStore,
+  FileOfflineInvoiceStorage,
   INVOICE_TYPES_BY_SYSTEM_CODE,
   InMemoryHwmStore,
+  InMemoryOfflineInvoiceStorage,
   InternalId,
   InvoiceDownloadService,
   InvoiceQueryFilterBuilder,
@@ -6175,6 +6783,7 @@ init_client();
   LimitsService,
   Nip,
   NipVatUe,
+  OfflineInvoiceWorkflow,
   OnlineSessionService,
   PERMISSION_DESCRIPTION_MAX_LENGTH,
   PERMISSION_DESCRIPTION_MIN_LENGTH,
@@ -6204,6 +6813,7 @@ init_client();
   UpoVersion,
   VatUe,
   VerificationLinkService,
+  addBusinessDays,
   authenticateWithCertificate,
   authenticateWithExternalSignature,
   authenticateWithPkcs12,
@@ -6211,6 +6821,7 @@ init_client();
   batchValidationDetails,
   buildUnsignedAuthTokenRequestXml,
   calculateBackoff,
+  calculateOfflineDeadline,
   createZip,
   decodeJwtPayload,
   deduplicateByKsefNumber,
@@ -6220,9 +6831,14 @@ init_client();
   defaultTransport,
   exportAndDownload,
   exportInvoices,
+  extendDeadlineForMaintenance,
+  extractInvoiceFields,
+  getDefaultReason,
   getEffectiveStartDate,
   getFormCode,
+  getTimeUntilDeadline,
   incrementalExportAndDownload,
+  isExpired,
   isRetryableError,
   isRetryableStatus,
   isValidBase64,
@@ -6240,6 +6856,7 @@ init_client();
   isValidReferenceNumber,
   isValidSha256Base64,
   isValidVatUe,
+  nextBusinessDay,
   openOnlineSession,
   openSendAndClose,
   parseFormCode,