ksef-client-ts 0.6.2 → 0.7.1

package/dist/index.js

@@ -8,11 +8,21 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var init_esm_shims = __esm({
+  "node_modules/tsup/assets/esm_shims.js"() {
+    "use strict";
+  }
+});
+
 // src/config/environments.ts
 var Environment;
 var init_environments = __esm({
   "src/config/environments.ts"() {
     "use strict";
+    init_esm_shims();
     Environment = {
       TEST: {
         apiUrl: "https://api-test.ksef.mf.gov.pl",
@@ -43,13 +53,15 @@ function resolveOptions(options = {}) {
     apiVersion: options.apiVersion ?? DEFAULT_API_VERSION,
     timeout: options.timeout ?? DEFAULT_TIMEOUT,
     customHeaders: options.customHeaders ?? {},
-    environmentName: options.environment ?? (options.baseUrl ? void 0 : "TEST")
+    environmentName: options.environment ?? (options.baseUrl ? void 0 : "TEST"),
+    errorFormat: options.errorFormat ?? "problem-details"
   };
 }
 var DEFAULT_API_VERSION, DEFAULT_TIMEOUT;
 var init_options = __esm({
   "src/config/options.ts"() {
     "use strict";
+    init_esm_shims();
     init_environments();
     DEFAULT_API_VERSION = "v2";
     DEFAULT_TIMEOUT = 3e4;
@@ -60,6 +72,7 @@ var init_options = __esm({
 var init_config = __esm({
   "src/config/index.ts"() {
     "use strict";
+    init_esm_shims();
     init_environments();
     init_options();
   }
@@ -70,6 +83,7 @@ var KSeFError;
 var init_ksef_error = __esm({
   "src/errors/ksef-error.ts"() {
     "use strict";
+    init_esm_shims();
     KSeFError = class extends Error {
       constructor(message) {
         super(message);
@@ -84,6 +98,7 @@ var KSeFApiError;
 var init_ksef_api_error = __esm({
   "src/errors/ksef-api-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_error();
     KSeFApiError = class _KSeFApiError extends KSeFError {
       statusCode;
@@ -99,6 +114,9 @@ var init_ksef_api_error = __esm({
         const message = details?.length ? details.map((d) => d.exceptionDescription ?? "").filter(Boolean).join("; ") || `KSeF API error: HTTP ${statusCode}` : `KSeF API error: HTTP ${statusCode}`;
         return new _KSeFApiError(message, statusCode, body);
       }
+      toProblemFields() {
+        return { detail: this.message };
+      }
     };
   }
 });
@@ -108,19 +126,23 @@ var KSeFRateLimitError;
 var init_ksef_rate_limit_error = __esm({
   "src/errors/ksef-rate-limit-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_api_error();
     KSeFRateLimitError = class _KSeFRateLimitError extends KSeFApiError {
+      statusCode = 429;
       retryAfterSeconds;
       retryAfterDate;
       recommendedDelay;
-      constructor(message, statusCode, errorResponse, retryAfterSeconds, retryAfterDate) {
+      problem;
+      constructor(message, statusCode, errorResponse, retryAfterSeconds, retryAfterDate, problem) {
         super(message, statusCode, errorResponse);
         this.name = "KSeFRateLimitError";
         this.retryAfterSeconds = retryAfterSeconds;
         this.retryAfterDate = retryAfterDate;
         this.recommendedDelay = retryAfterSeconds ?? 60;
+        this.problem = problem;
       }
-      static fromRetryAfterHeader(statusCode, retryAfterHeader, body) {
+      static fromRetryAfterHeader(statusCode, retryAfterHeader, body, problem) {
         let retryAfterSeconds;
         let retryAfterDate;
         if (retryAfterHeader) {
@@ -135,8 +157,16 @@ var init_ksef_rate_limit_error = __esm({
             }
           }
         }
-        const message = retryAfterSeconds != null ? `Rate limited. Retry after ${retryAfterSeconds}s` : "Rate limited by KSeF API";
-        return new _KSeFRateLimitError(message, statusCode, body, retryAfterSeconds, retryAfterDate);
+        const message = retryAfterSeconds != null ? `Rate limited. Retry after ${retryAfterSeconds}s` : problem?.detail ?? "Rate limited by KSeF API";
+        return new _KSeFRateLimitError(message, statusCode, body, retryAfterSeconds, retryAfterDate, problem);
+      }
+      toProblemFields() {
+        return {
+          detail: this.problem?.detail,
+          traceId: this.problem?.traceId,
+          instance: this.problem?.instance,
+          timestamp: this.problem?.timestamp
+        };
       }
     };
   }
@@ -147,21 +177,30 @@ var KSeFUnauthorizedError;
 var init_ksef_unauthorized_error = __esm({
   "src/errors/ksef-unauthorized-error.ts"() {
     "use strict";
-    init_ksef_error();
-    KSeFUnauthorizedError = class extends KSeFError {
+    init_esm_shims();
+    init_ksef_api_error();
+    KSeFUnauthorizedError = class extends KSeFApiError {
       statusCode = 401;
       detail;
       traceId;
       instance;
       timestamp;
       constructor(problemDetails) {
-        super(problemDetails.detail || "Unauthorized");
+        super(problemDetails.detail || "Unauthorized", 401);
         this.name = "KSeFUnauthorizedError";
         this.detail = problemDetails.detail;
         this.traceId = problemDetails.traceId;
         this.instance = problemDetails.instance;
         this.timestamp = problemDetails.timestamp;
       }
+      toProblemFields() {
+        return {
+          detail: this.detail,
+          traceId: this.traceId,
+          instance: this.instance,
+          timestamp: this.timestamp
+        };
+      }
     };
   }
 });
@@ -171,8 +210,9 @@ var KSeFForbiddenError;
 var init_ksef_forbidden_error = __esm({
   "src/errors/ksef-forbidden-error.ts"() {
     "use strict";
-    init_ksef_error();
-    KSeFForbiddenError = class extends KSeFError {
+    init_esm_shims();
+    init_ksef_api_error();
+    KSeFForbiddenError = class extends KSeFApiError {
       statusCode = 403;
       detail;
       reasonCode;
@@ -181,7 +221,7 @@ var init_ksef_forbidden_error = __esm({
       traceId;
       timestamp;
       constructor(problemDetails) {
-        super(problemDetails.detail || "Forbidden");
+        super(problemDetails.detail || "Forbidden", 403);
         this.name = "KSeFForbiddenError";
         this.detail = problemDetails.detail;
         this.reasonCode = problemDetails.reasonCode;
@@ -190,6 +230,16 @@ var init_ksef_forbidden_error = __esm({
         this.traceId = problemDetails.traceId;
         this.timestamp = problemDetails.timestamp;
       }
+      toProblemFields() {
+        return {
+          detail: this.detail,
+          reasonCode: this.reasonCode,
+          security: this.security,
+          traceId: this.traceId,
+          instance: this.instance,
+          timestamp: this.timestamp
+        };
+      }
     };
   }
 });
@@ -199,21 +249,66 @@ var KSeFGoneError;
 var init_ksef_gone_error = __esm({
   "src/errors/ksef-gone-error.ts"() {
     "use strict";
-    init_ksef_error();
-    KSeFGoneError = class extends KSeFError {
+    init_esm_shims();
+    init_ksef_api_error();
+    KSeFGoneError = class extends KSeFApiError {
       statusCode = 410;
       detail;
       instance;
       traceId;
       timestamp;
       constructor(problemDetails) {
-        super(problemDetails.detail || "Operation status no longer available (retention expired)");
+        super(problemDetails.detail || "Operation status no longer available (retention expired)", 410);
         this.name = "KSeFGoneError";
         this.detail = problemDetails.detail;
         this.instance = problemDetails.instance;
         this.traceId = problemDetails.traceId;
         this.timestamp = problemDetails.timestamp;
       }
+      toProblemFields() {
+        return {
+          detail: this.detail,
+          traceId: this.traceId,
+          instance: this.instance,
+          timestamp: this.timestamp
+        };
+      }
+    };
+  }
+});
+
+// src/errors/ksef-bad-request-error.ts
+var KSeFBadRequestError;
+var init_ksef_bad_request_error = __esm({
+  "src/errors/ksef-bad-request-error.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ksef_api_error();
+    KSeFBadRequestError = class extends KSeFApiError {
+      statusCode = 400;
+      detail;
+      instance;
+      errors;
+      traceId;
+      timestamp;
+      constructor(problemDetails) {
+        super(problemDetails.detail || problemDetails.title || "Bad Request", 400);
+        this.name = "KSeFBadRequestError";
+        this.detail = problemDetails.detail;
+        this.instance = problemDetails.instance;
+        this.errors = problemDetails.errors ?? [];
+        this.traceId = problemDetails.traceId;
+        this.timestamp = problemDetails.timestamp;
+      }
+      toProblemFields() {
+        return {
+          detail: this.detail,
+          errors: this.errors.length ? this.errors : void 0,
+          traceId: this.traceId,
+          instance: this.instance,
+          timestamp: this.timestamp
+        };
+      }
     };
   }
 });
@@ -223,6 +318,7 @@ var KSeFAuthStatusError;
 var init_ksef_auth_status_error = __esm({
   "src/errors/ksef-auth-status-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_error();
     KSeFAuthStatusError = class extends KSeFError {
       referenceNumber;
@@ -242,6 +338,7 @@ var KSeFSessionExpiredError;
 var init_ksef_session_expired_error = __esm({
   "src/errors/ksef-session-expired-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_error();
     KSeFSessionExpiredError = class extends KSeFError {
       constructor(message = "KSeF session has expired") {
@@ -261,6 +358,7 @@ var KSeFValidationError;
 var init_ksef_validation_error = __esm({
   "src/errors/ksef-validation-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_error();
     KSeFValidationError = class _KSeFValidationError extends KSeFError {
       details;
@@ -288,6 +386,7 @@ var KSeFErrorCode;
 var init_error_codes = __esm({
   "src/errors/error-codes.ts"() {
     "use strict";
+    init_esm_shims();
     KSeFErrorCode = {
       BatchTimeout: 21208,
       DuplicateInvoice: 440
@@ -300,6 +399,7 @@ var KSeFBatchTimeoutError;
 var init_ksef_batch_timeout_error = __esm({
   "src/errors/ksef-batch-timeout-error.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_api_error();
     init_error_codes();
     KSeFBatchTimeoutError = class _KSeFBatchTimeoutError extends KSeFApiError {
@@ -319,21 +419,83 @@ var init_ksef_batch_timeout_error = __esm({
   }
 });
 
+// src/errors/ksef-circuit-open-error.ts
+var KSeFCircuitOpenError;
+var init_ksef_circuit_open_error = __esm({
+  "src/errors/ksef-circuit-open-error.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ksef_error();
+    KSeFCircuitOpenError = class extends KSeFError {
+      endpoint;
+      openedAt;
+      retryAfterMs;
+      constructor(endpoint, openedAt, retryAfterMs) {
+        super(
+          `Circuit breaker is open for '${endpoint}'. Retry after ${Math.round(retryAfterMs)}ms.`
+        );
+        this.name = "KSeFCircuitOpenError";
+        this.endpoint = endpoint;
+        this.openedAt = openedAt;
+        this.retryAfterMs = retryAfterMs;
+      }
+    };
+  }
+});
+
+// src/errors/ksef-xsd-validation-error.ts
+var KSeFXsdValidationError;
+var init_ksef_xsd_validation_error = __esm({
+  "src/errors/ksef-xsd-validation-error.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ksef_error();
+    KSeFXsdValidationError = class extends KSeFError {
+      schemaFile;
+      errors;
+      constructor(schemaFile, errors) {
+        const preview = errors.slice(0, 3).join("; ");
+        const extra = errors.length > 3 ? ` (+${errors.length - 3} more)` : "";
+        super(`XSD validation failed against ${schemaFile}: ${preview}${extra}`);
+        this.name = "KSeFXsdValidationError";
+        this.schemaFile = schemaFile;
+        this.errors = errors;
+      }
+    };
+  }
+});
+
+// src/errors/assert-never.ts
+function assertNever(value) {
+  throw new Error(`Unexpected value: ${String(value)}`);
+}
+var init_assert_never = __esm({
+  "src/errors/assert-never.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/errors/index.ts
 var init_errors = __esm({
   "src/errors/index.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_error();
     init_ksef_api_error();
     init_ksef_rate_limit_error();
     init_ksef_unauthorized_error();
     init_ksef_forbidden_error();
     init_ksef_gone_error();
+    init_ksef_bad_request_error();
     init_ksef_auth_status_error();
     init_ksef_session_expired_error();
     init_ksef_validation_error();
     init_ksef_batch_timeout_error();
+    init_ksef_circuit_open_error();
+    init_ksef_xsd_validation_error();
     init_error_codes();
+    init_assert_never();
   }
 });
 
@@ -342,6 +504,7 @@ var RouteBuilder;
 var init_route_builder = __esm({
   "src/http/route-builder.ts"() {
     "use strict";
+    init_esm_shims();
     RouteBuilder = class {
       apiVersion;
       constructor(apiVersion) {
@@ -360,6 +523,7 @@ var RestRequest;
 var init_rest_request = __esm({
   "src/http/rest-request.ts"() {
     "use strict";
+    init_esm_shims();
     RestRequest = class _RestRequest {
       method;
       path;
@@ -368,21 +532,21 @@ var init_rest_request = __esm({
       _query = [];
       _presigned = false;
       _skipAuthRetry = false;
-      constructor(method, path2) {
+      constructor(method, path4) {
         this.method = method;
-        this.path = path2;
+        this.path = path4;
       }
-      static get(path2) {
-        return new _RestRequest("GET", path2);
+      static get(path4) {
+        return new _RestRequest("GET", path4);
       }
-      static post(path2) {
-        return new _RestRequest("POST", path2);
+      static post(path4) {
+        return new _RestRequest("POST", path4);
       }
-      static put(path2) {
-        return new _RestRequest("PUT", path2);
+      static put(path4) {
+        return new _RestRequest("PUT", path4);
       }
-      static delete(path2) {
-        return new _RestRequest("DELETE", path2);
+      static delete(path4) {
+        return new _RestRequest("DELETE", path4);
       }
       body(data) {
         this._body = data;
@@ -436,6 +600,7 @@ var defaultTransport;
 var init_transport = __esm({
   "src/http/transport.ts"() {
     "use strict";
+    init_esm_shims();
     defaultTransport = (url, init) => fetch(url, init);
   }
 });
@@ -485,6 +650,7 @@ var RETRYABLE_ERROR_CODES;
 var init_retry_policy = __esm({
   "src/http/retry-policy.ts"() {
     "use strict";
+    init_esm_shims();
     RETRYABLE_ERROR_CODES = /* @__PURE__ */ new Set([
       "ECONNRESET",
       "ECONNREFUSED",
@@ -575,6 +741,7 @@ var BLOCKED_PARAMS;
 var init_presigned_url_policy = __esm({
   "src/http/presigned-url-policy.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_validation_error();
     BLOCKED_PARAMS = ["redirect", "callback", "return_url", "next"];
   }
@@ -582,15 +749,38 @@ var init_presigned_url_policy = __esm({
 
 // src/http/rest-client.ts
 import { consola } from "consola";
+function isBadRequestProblem(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.title !== "string") return false;
+  if (v.status !== void 0 && typeof v.status !== "number") return false;
+  if (v.errors !== void 0) {
+    if (!Array.isArray(v.errors)) return false;
+    for (const item of v.errors) {
+      if (typeof item !== "object" || item === null) return false;
+      const detail = item;
+      if (typeof detail.code !== "number") return false;
+      if (typeof detail.description !== "string") return false;
+    }
+  }
+  return true;
+}
+function isTooManyRequestsProblem(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.title === "string" && (v.status === void 0 || typeof v.status === "number") && (v.detail === void 0 || typeof v.detail === "string") && (v.instance === void 0 || typeof v.instance === "string") && (v.traceId === void 0 || typeof v.traceId === "string") && (v.timestamp === void 0 || typeof v.timestamp === "string");
+}
 var RestClient;
 var init_rest_client = __esm({
   "src/http/rest-client.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_api_error();
     init_ksef_rate_limit_error();
     init_ksef_unauthorized_error();
     init_ksef_forbidden_error();
     init_ksef_gone_error();
+    init_ksef_bad_request_error();
     init_ksef_batch_timeout_error();
     init_error_codes();
     init_route_builder();
@@ -603,6 +793,7 @@ var init_rest_client = __esm({
       transport;
       retryPolicy;
       rateLimitPolicy;
+      circuitBreakerPolicy;
       authManager;
       presignedUrlPolicy;
       constructor(options, config) {
@@ -611,6 +802,7 @@ var init_rest_client = __esm({
         this.transport = config?.transport ?? defaultTransport;
         this.retryPolicy = config?.retryPolicy ?? defaultRetryPolicy();
         this.rateLimitPolicy = config?.rateLimitPolicy ?? null;
+        this.circuitBreakerPolicy = config?.circuitBreakerPolicy ?? null;
         this.authManager = config?.authManager;
         this.presignedUrlPolicy = config?.presignedUrlPolicy;
       }
@@ -635,18 +827,32 @@ var init_rest_client = __esm({
         if (request.isPresigned() && this.presignedUrlPolicy) {
           validatePresignedUrl(url, this.presignedUrlPolicy);
         }
+        let ownsProbeSlot = false;
+        if (this.circuitBreakerPolicy) {
+          const claimed = this.circuitBreakerPolicy.ensureClosed(request.path);
+          if (claimed) ownsProbeSlot = true;
+        }
         if (this.rateLimitPolicy) {
-          await this.rateLimitPolicy.acquire(request.path);
+          try {
+            await this.rateLimitPolicy.acquire(request.path);
+          } catch (error) {
+            if (ownsProbeSlot) this.circuitBreakerPolicy?.releaseProbe(request.path);
+            throw error;
+          }
         }
         let lastError;
         for (let attempt = 0; attempt <= this.retryPolicy.maxRetries; attempt++) {
+          if (this.circuitBreakerPolicy) {
+            const claimed = this.circuitBreakerPolicy.ensureClosed(request.path, ownsProbeSlot);
+            if (claimed) ownsProbeSlot = true;
+          }
           try {
-            const response = await this.doRequest(request, url);
+            let response = await this.doRequest(request, url);
             if (response.status === 401 && this.authManager && attempt === 0 && !request.isSkipAuthRetry()) {
               const newToken = await this.authManager.onUnauthorized();
               if (newToken) {
                 consola.debug("Auth token refreshed, retrying request");
-                return this.doRequest(request, url, newToken);
+                response = await this.doRequest(request, url, newToken);
               }
             }
             if (isRetryableStatus(response.status, this.retryPolicy) && attempt < this.retryPolicy.maxRetries) {
@@ -656,10 +862,17 @@ var init_rest_client = __esm({
               consola.debug(`Retryable ${response.status}, attempt ${attempt + 1}/${this.retryPolicy.maxRetries}, waiting ${Math.round(delayMs)}ms`);
               await sleep(delayMs);
               if (is429 && this.rateLimitPolicy) {
-                await this.rateLimitPolicy.acquire(request.path);
+                try {
+                  await this.rateLimitPolicy.acquire(request.path);
+                } catch (error) {
+                  this.recordCircuitOutcome(request.path, 429);
+                  ownsProbeSlot = false;
+                  throw error;
+                }
               }
               continue;
             }
+            this.recordCircuitOutcome(request.path, response.status);
             return response;
           } catch (error) {
             lastError = error;
@@ -669,16 +882,31 @@ var init_rest_client = __esm({
               await sleep(delayMs);
               continue;
             }
+            if (isRetryableError(error, this.retryPolicy) || ownsProbeSlot) {
+              this.circuitBreakerPolicy?.recordFailure(request.path);
+            }
             throw error;
           }
         }
         throw lastError;
       }
+      recordCircuitOutcome(path4, status) {
+        if (!this.circuitBreakerPolicy) return;
+        if (status >= 500) {
+          this.circuitBreakerPolicy.recordFailure(path4);
+          return;
+        }
+        this.circuitBreakerPolicy.recordSuccess(path4);
+      }
       async doRequest(request, url, overrideToken) {
         const headers = {
           ...this.options.customHeaders,
           ...request.getHeaders()
         };
+        const hasHeader = (name) => Object.keys(headers).some((header) => header.toLowerCase() === name.toLowerCase());
+        if (this.options.errorFormat !== "legacy" && !hasHeader("x-error-format")) {
+          headers["X-Error-Format"] = "problem-details";
+        }
         if (!headers["Authorization"] && this.authManager) {
           const token = overrideToken ?? this.authManager.getAccessToken();
           if (token) {
@@ -705,9 +933,9 @@ var init_rest_client = __esm({
         return response;
       }
       buildUrl(request) {
-        const path2 = this.routeBuilder.build(request.path);
+        const path4 = this.routeBuilder.build(request.path);
         const base = this.options.baseUrl;
-        const url = new URL(`${base}${path2}`);
+        const url = new URL(`${base}${path4}`);
         const query = request.getQuery();
         for (const [key, value] of query) {
           url.searchParams.append(key, value);
@@ -717,19 +945,40 @@ var init_rest_client = __esm({
       async ensureSuccess(response) {
         if (response.ok) return;
         const text = await response.text().catch(() => "");
+        let jsonCache = null;
         const parseJson = () => {
-          try {
-            return JSON.parse(text);
-          } catch {
-            return void 0;
+          if (jsonCache === null) {
+            try {
+              jsonCache = { value: JSON.parse(text) };
+            } catch {
+              jsonCache = { value: void 0 };
+            }
           }
+          return jsonCache.value;
         };
-        if (response.status === 429) {
+        const tryParseProblem = (guard) => {
           const parsed = parseJson();
+          return parsed !== void 0 && guard(parsed) ? parsed : void 0;
+        };
+        if (response.status === 400) {
+          const problem = tryParseProblem(isBadRequestProblem);
+          if (problem) {
+            throw new KSeFBadRequestError(problem);
+          }
+          const legacy = parseJson();
+          if (hasErrorCode(legacy, KSeFErrorCode.BatchTimeout)) {
+            throw KSeFBatchTimeoutError.fromResponse(400, legacy);
+          }
+          throw KSeFApiError.fromResponse(400, legacy);
+        }
+        if (response.status === 429) {
+          const problem = tryParseProblem(isTooManyRequestsProblem);
+          const legacy = problem ? void 0 : parseJson();
           throw KSeFRateLimitError.fromRetryAfterHeader(
             response.status,
             response.headers.get("Retry-After"),
-            parsed
+            legacy,
+            problem
           );
         }
         if (response.status === 401) {
@@ -770,6 +1019,7 @@ var Routes;
 var init_routes = __esm({
   "src/http/routes.ts"() {
     "use strict";
+    init_esm_shims();
     Routes = {
       TestData: {
         createSubject: "testdata/subject",
@@ -902,6 +1152,7 @@ var TokenBucket, RateLimitPolicy;
 var init_rate_limit_policy = __esm({
   "src/http/rate-limit-policy.ts"() {
     "use strict";
+    init_esm_shims();
     TokenBucket = class {
       tokens;
       maxTokens;
@@ -962,11 +1213,151 @@ var init_rate_limit_policy = __esm({
   }
 });
 
+// src/http/circuit-breaker-policy.ts
+import { consola as consola2 } from "consola";
+function defaultCircuitBreakerPolicy() {
+  return new CircuitBreakerPolicy();
+}
+var GLOBAL_KEY, CircuitBreakerPolicy;
+var init_circuit_breaker_policy = __esm({
+  "src/http/circuit-breaker-policy.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ksef_circuit_open_error();
+    GLOBAL_KEY = "__global__";
+    CircuitBreakerPolicy = class _CircuitBreakerPolicy {
+      failureThreshold;
+      openMs;
+      scope;
+      states = /* @__PURE__ */ new Map();
+      constructor(config = {}) {
+        const failureThreshold = config.failureThreshold ?? 5;
+        const openMs = config.openMs ?? 3e4;
+        if (!Number.isInteger(failureThreshold) || failureThreshold <= 0) {
+          throw new RangeError("CircuitBreakerPolicy: failureThreshold must be a positive integer");
+        }
+        if (!Number.isFinite(openMs) || openMs <= 0) {
+          throw new RangeError("CircuitBreakerPolicy: openMs must be > 0");
+        }
+        const scope = config.scope ?? "global";
+        if (scope !== "global" && scope !== "endpoint") {
+          throw new RangeError(
+            "CircuitBreakerPolicy: scope must be 'global' or 'endpoint'"
+          );
+        }
+        this.failureThreshold = failureThreshold;
+        this.openMs = openMs;
+        this.scope = scope;
+      }
+      // Returns true iff this call just claimed the single probe slot for the
+      // caller. The caller MUST pass `alreadyOwnsProbe=true` on subsequent
+      // re-checks for the same logical request (e.g. a retry loop) so the probe
+      // owner cannot deadlock itself on its own in-flight slot.
+      ensureClosed(endpoint, alreadyOwnsProbe = false) {
+        const key = this.keyFor(endpoint);
+        const state = this.states.get(key);
+        if (!state || state.openedAt === null) return false;
+        const now = performance.now();
+        const elapsed = now - state.openedAt;
+        if (elapsed >= this.openMs) {
+          if (alreadyOwnsProbe) return false;
+          if (state.probeInFlight) {
+            throw new KSeFCircuitOpenError(endpoint, state.openedAt, 0);
+          }
+          state.probeInFlight = true;
+          consola2.debug(`Circuit breaker: probe after cooldown for '${key}'`);
+          return true;
+        }
+        const retryAfterMs = Math.max(0, this.openMs - elapsed);
+        throw new KSeFCircuitOpenError(endpoint, state.openedAt, retryAfterMs);
+      }
+      recordSuccess(endpoint) {
+        const key = this.keyFor(endpoint);
+        const state = this.states.get(key);
+        if (!state) return;
+        if (state.openedAt !== null || state.failures > 0) {
+          consola2.debug(`Circuit breaker: reset for '${key}'`);
+        }
+        this.states.delete(key);
+      }
+      // Release a claimed probe slot WITHOUT observing an outcome. Use this when
+      // the probe attempt was aborted before reaching upstream (e.g. rate-limit
+      // acquire rejected, client cancellation). We have no new information about
+      // upstream health, so the breaker must stay OPEN — but we do restart the
+      // cooldown clock so the next probe attempt waits a fresh `openMs`,
+      // preventing a tight loop of aborted probes from spamming the limiter.
+      releaseProbe(endpoint) {
+        const key = this.keyFor(endpoint);
+        const state = this.states.get(key);
+        if (!state || !state.probeInFlight) return;
+        state.probeInFlight = false;
+        if (state.openedAt !== null) {
+          state.openedAt = performance.now();
+        }
+        consola2.debug(`Circuit breaker: probe aborted (not observed) for '${key}', cooldown restarted`);
+      }
+      recordFailure(endpoint) {
+        const key = this.keyFor(endpoint);
+        const now = performance.now();
+        let state = this.states.get(key);
+        if (!state) {
+          state = { failures: 0, openedAt: null, lastFailureAt: null, probeInFlight: false };
+          this.states.set(key, state);
+        }
+        if (state.openedAt !== null && state.probeInFlight) {
+          state.openedAt = now;
+          state.failures = this.failureThreshold;
+          state.lastFailureAt = now;
+          state.probeInFlight = false;
+          consola2.debug(`Circuit breaker: probe failed, re-opened for '${key}'`);
+          this.maybeSweepStaleClosed(now, key);
+          return;
+        }
+        const slidingStale = state.lastFailureAt !== null && now - state.lastFailureAt > this.openMs;
+        state.failures = slidingStale ? 1 : state.failures + 1;
+        state.lastFailureAt = now;
+        if (state.openedAt === null && state.failures >= this.failureThreshold) {
+          state.openedAt = now;
+          consola2.debug(
+            `Circuit breaker: opened for '${key}' after ${state.failures} failures (cooldown ${this.openMs}ms)`
+          );
+        }
+        this.maybeSweepStaleClosed(now, key);
+      }
+      keyFor(endpoint) {
+        return this.scope === "global" ? GLOBAL_KEY : endpoint;
+      }
+      // Prevent unbounded map growth under `scope: 'endpoint'` when callers hit
+      // many distinct parameterized paths (e.g. `auth/sessions/{ref}`) that each
+      // fail once and are never revisited. Global scope is always a single entry.
+      //
+      // Runs amortized O(n) — gated on a size threshold so small workloads pay
+      // nothing. Only evicts states that are genuinely settled: closed, no probe
+      // in flight, and with the last failure older than two cooldowns.
+      maybeSweepStaleClosed(now, keepKey) {
+        if (this.scope !== "endpoint") return;
+        if (this.states.size <= _CircuitBreakerPolicy.sweepThreshold) return;
+        const staleBefore = now - 2 * this.openMs;
+        for (const [key, state] of this.states) {
+          if (key === keepKey) continue;
+          if (state.openedAt !== null) continue;
+          if (state.probeInFlight) continue;
+          if (state.lastFailureAt !== null && state.lastFailureAt < staleBefore) {
+            this.states.delete(key);
+          }
+        }
+      }
+      static sweepThreshold = 64;
+    };
+  }
+});
+
 // src/http/auth-manager.ts
 var DefaultAuthManager;
 var init_auth_manager = __esm({
   "src/http/auth-manager.ts"() {
     "use strict";
+    init_esm_shims();
     DefaultAuthManager = class {
       token;
       refreshToken;
@@ -1007,6 +1398,7 @@ var KSEF_FEATURE_HEADER, UpoVersion, ENFORCE_XADES_COMPLIANCE;
 var init_ksef_feature = __esm({
   "src/http/ksef-feature.ts"() {
     "use strict";
+    init_esm_shims();
     KSEF_FEATURE_HEADER = "X-KSeF-Feature";
     UpoVersion = {
       /** UPO v4-2 format (default before 2026-01-05). */
@@ -1106,6 +1498,7 @@ var NIP_PATTERN_CORE, VAT_UE_PATTERN_CORE, Nip, VatUe, NipVatUe, InternalId, Pep
 var init_patterns = __esm({
   "src/validation/patterns.ts"() {
     "use strict";
+    init_esm_shims();
     NIP_PATTERN_CORE = "[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}";
     VAT_UE_PATTERN_CORE = "(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))";
     Nip = new RegExp(`^${NIP_PATTERN_CORE}$`);
@@ -1222,6 +1615,7 @@ function getTextContent(el) {
 var init_xml_to_object = __esm({
   "src/validation/xml-to-object.ts"() {
     "use strict";
+    init_esm_shims();
   }
 });
 
@@ -1235,6 +1629,7 @@ var TKodFormularza, TDataCzas, TZnakowy, TNaglowek, TKodyKrajowUE, TNrNIP, TZnak
 var init_fa3 = __esm({
   "src/validation/schemas/fa3.ts"() {
     "use strict";
+    init_esm_shims();
     TKodFormularza = z.literal("FA");
     TDataCzas = z.string();
     TZnakowy = z.string().min(1).max(256);
@@ -1645,6 +2040,7 @@ var TKodFormularza2, TDataCzas2, TZnakowy3, TNaglowek2, TKodyKrajowUE2, TNrNIP2,
 var init_fa2 = __esm({
   "src/validation/schemas/fa2.ts"() {
     "use strict";
+    init_esm_shims();
     TKodFormularza2 = z2.literal("FA");
     TDataCzas2 = z2.string();
     TZnakowy3 = z2.string().min(1).max(256);
@@ -2039,6 +2435,7 @@ var TKodFormularza3, TDataCzas3, TZnakowy4, TNaglowek3, TNrNIP3, TZnakowy5123, T
 var init_rr1_v11e = __esm({
   "src/validation/schemas/rr1-v11e.ts"() {
     "use strict";
+    init_esm_shims();
     TKodFormularza3 = z3.literal("FA_RR");
     TDataCzas3 = z3.string();
     TZnakowy4 = z3.string().min(1).max(256);
@@ -2244,6 +2641,7 @@ var TKodFormularza4, TDataCzas4, TZnakowy5, TNaglowek4, TNrNIP4, TZnakowy5124, T
 var init_rr1_v10e = __esm({
   "src/validation/schemas/rr1-v10e.ts"() {
     "use strict";
+    init_esm_shims();
     TKodFormularza4 = z4.literal("FA_RR");
     TDataCzas4 = z4.string();
     TZnakowy5 = z4.string().min(1).max(256);
@@ -2449,6 +2847,7 @@ var InvoiceType, PEF3Schema;
 var init_pef3 = __esm({
   "src/validation/schemas/pef3.ts"() {
     "use strict";
+    init_esm_shims();
     InvoiceType = z5.object({
       "UBLExtensions": z5.any().optional(),
       "UBLVersionID": z5.any().optional(),
@@ -2519,6 +2918,7 @@ var CreditNoteType, PEF_KOR3Schema;
 var init_pef_kor3 = __esm({
   "src/validation/schemas/pef-kor3.ts"() {
     "use strict";
+    init_esm_shims();
     CreditNoteType = z6.object({
       "UBLExtensions": z6.any().optional(),
       "UBLVersionID": z6.any().optional(),
@@ -2581,6 +2981,7 @@ var NAMESPACE_MAP;
 var init_schemas = __esm({
   "src/validation/schemas/index.ts"() {
     "use strict";
+    init_esm_shims();
     init_fa3();
     init_fa2();
     init_rr1_v11e();
@@ -2637,6 +3038,7 @@ var ROOT_ELEMENT_MAP, schemaCache, SchemaRegistry;
 var init_schema_registry = __esm({
   "src/validation/schema-registry.ts"() {
     "use strict";
+    init_esm_shims();
     init_schemas();
     ROOT_ELEMENT_MAP = {
       Invoice: "PEF3",
@@ -2678,6 +3080,116 @@ var init_schema_registry = __esm({
   }
 });
 
+// src/validation/char-validity.ts
+function validateCharValidity(xml) {
+  return [...findProcessingInstructions(xml), ...findDiscouragedUnicode(xml)];
+}
+function findProcessingInstructionTokens(xml) {
+  const tokens = [];
+  for (let i = 0; i < xml.length; ) {
+    if (xml.startsWith("<!--", i)) {
+      const end = xml.indexOf("-->", i + 4);
+      i = end === -1 ? xml.length : end + 3;
+      continue;
+    }
+    if (xml.startsWith("<![CDATA[", i)) {
+      const end = xml.indexOf("]]>", i + 9);
+      i = end === -1 ? xml.length : end + 3;
+      continue;
+    }
+    if (xml.startsWith("<?", i)) {
+      const end = xml.indexOf("?>", i + 2);
+      if (end === -1) break;
+      tokens.push({ token: xml.slice(i, end + 2), index: i });
+      i = end + 2;
+      continue;
+    }
+    i += 1;
+  }
+  return tokens;
+}
+function findProcessingInstructions(xml) {
+  const errors = [];
+  const matches = findProcessingInstructionTokens(xml);
+  if (matches.length === 0) return errors;
+  const firstMatch = matches[0];
+  const firstTarget = firstMatch.token.match(PI_TARGET_RE)?.[1];
+  const hasBom = xml.charCodeAt(0) === 65279;
+  const prologPosition = hasBom ? 1 : 0;
+  const firstIsProlog = firstMatch.index === prologPosition && firstTarget === "xml";
+  for (let i = 0; i < matches.length; i++) {
+    if (i === 0 && firstIsProlog) continue;
+    const m = matches[i];
+    const target = m.token.match(PI_TARGET_RE)?.[1] ?? "?";
+    errors.push({
+      code: "XML_PROCESSING_INSTRUCTION",
+      message: `Processing instruction <?${target}?> at offset ${m.index} is not allowed (only <?xml ... ?> prolog is permitted)`,
+      path: `offset:${m.index}`
+    });
+  }
+  return errors;
+}
+function findDiscouragedUnicode(xml) {
+  const errors = [];
+  const seenRanges = /* @__PURE__ */ new Set();
+  let utf16Offset = 0;
+  for (const ch of xml) {
+    const cp = ch.codePointAt(0);
+    const idx = rangeIndex(cp);
+    if (idx >= 0 && !seenRanges.has(idx)) {
+      seenRanges.add(idx);
+      errors.push({
+        code: "XML_DISCOURAGED_UNICODE",
+        message: `Discouraged Unicode character U+${cp.toString(16).toUpperCase().padStart(4, "0")} found at offset ${utf16Offset} (W3C XML 1.0 \xA72.2 rejects this range)`,
+        path: `offset:${utf16Offset}`
+      });
+    }
+    utf16Offset += ch.length;
+  }
+  return errors;
+}
+function rangeIndex(cp) {
+  let lo = 0;
+  let hi = DISCOURAGED_UNICODE_RANGES.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    const [start, end] = DISCOURAGED_UNICODE_RANGES[mid];
+    if (cp < start) hi = mid - 1;
+    else if (cp > end) lo = mid + 1;
+    else return mid;
+  }
+  return -1;
+}
+var DISCOURAGED_UNICODE_RANGES, PI_TARGET_RE;
+var init_char_validity = __esm({
+  "src/validation/char-validity.ts"() {
+    "use strict";
+    init_esm_shims();
+    DISCOURAGED_UNICODE_RANGES = [
+      [127, 132],
+      [134, 159],
+      [64976, 65007],
+      [131070, 131071],
+      [196606, 196607],
+      [262142, 262143],
+      [327678, 327679],
+      [393214, 393215],
+      [458750, 458751],
+      [524286, 524287],
+      [589822, 589823],
+      [655358, 655359],
+      [720894, 720895],
+      [786430, 786431],
+      [851966, 851967],
+      [917502, 917503],
+      [983038, 983039],
+      [1048574, 1048575],
+      [1114110, 1114111]
+    ];
+    PI_TARGET_RE = /^<\?(\S+)/;
+  }
+});
+
 // src/validation/invoice-validator.ts
 var invoice_validator_exports = {};
 __export(invoice_validator_exports, {
@@ -2735,11 +3247,11 @@ async function validateSchema(xml, options, _parsed) {
   const prefix = rootElement ? `/${rootElement}/` : "/";
   const validationErrors = result.error.issues.map((issue) => {
     const zodPath = issue.path.join("/");
-    const path2 = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
+    const path4 = zodPath ? `${prefix}${zodPath}` : rootElement ? `/${rootElement}` : void 0;
     return {
       code: mapZodErrorCode(issue),
       message: issue.message,
-      path: path2
+      path: path4
     };
   });
   return { valid: false, schemaType, errors: validationErrors };
@@ -2779,9 +3291,9 @@ function validateBusinessRules(xml, _parsed) {
   collectDateErrors(object, rootElement, errors);
   return { valid: errors.length === 0, schemaType, errors };
 }
-function collectNipPeselErrors(obj, path2, errors) {
+function collectNipPeselErrors(obj, path4, errors) {
   for (const [key, value] of Object.entries(obj)) {
-    const currentPath = path2 ? `${path2}/${key}` : key;
+    const currentPath = path4 ? `${path4}/${key}` : key;
     if (key === "NIP" && typeof value === "string") {
       if (!isValidNip(value)) {
         errors.push({
@@ -2830,6 +3342,12 @@ function collectDateErrors(obj, rootElement, errors) {
   }
 }
 async function validate(xml, options) {
+  if (!options?.skipCharValidity) {
+    const l1aErrors = validateCharValidity(xml);
+    if (l1aErrors.length > 0) {
+      return { valid: false, schemaType: null, errors: l1aErrors };
+    }
+  }
   const parsed = xml && xml.trim() ? xmlToObject(xml) : void 0;
   const l1 = validateWellFormedness(xml, parsed);
   if (!l1.valid) return l1;
@@ -2854,8 +3372,10 @@ function batchValidationDetails(batch) {
 var init_invoice_validator = __esm({
   "src/validation/invoice-validator.ts"() {
     "use strict";
+    init_esm_shims();
     init_xml_to_object();
     init_schema_registry();
+    init_char_validity();
     init_patterns();
   }
 });
@@ -2865,6 +3385,7 @@ var SystemCode, FORM_CODES, DEFAULT_FORM_CODE, INVOICE_TYPES_BY_SYSTEM_CODE, FOR
 var init_types = __esm({
   "src/models/document-structures/types.ts"() {
     "use strict";
+    init_esm_shims();
     SystemCode = {
       FA_2: "FA (2)",
       FA_3: "FA (3)",
@@ -2917,6 +3438,7 @@ 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_esm_shims();
     init_types();
     SYSTEM_CODE_TO_FORM_CODE = {
       [SystemCode.FA_2]: FORM_CODES.FA_2,
@@ -2937,6 +3459,7 @@ var init_helpers = __esm({
 var init_document_structures = __esm({
   "src/models/document-structures/index.ts"() {
     "use strict";
+    init_esm_shims();
     init_types();
     init_helpers();
   }
@@ -2947,6 +3470,7 @@ var AuthService;
 var init_auth = __esm({
   "src/services/auth.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_feature();
     init_rest_request();
     init_routes();
@@ -2997,6 +3521,7 @@ var ActiveSessionsService;
 var init_active_sessions = __esm({
   "src/services/active-sessions.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     ActiveSessionsService = class {
@@ -3028,6 +3553,7 @@ var OnlineSessionService;
 var init_online_session = __esm({
   "src/services/online-session.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_feature();
     init_rest_request();
     init_routes();
@@ -3080,6 +3606,7 @@ async function runWithConcurrency(tasks, parallelism) {
 var init_concurrency = __esm({
   "src/utils/concurrency.ts"() {
     "use strict";
+    init_esm_shims();
   }
 });
 
@@ -3088,6 +3615,7 @@ var BatchSessionService;
 var init_batch_session = __esm({
   "src/services/batch-session.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_feature();
     init_rest_request();
     init_routes();
@@ -3192,6 +3720,7 @@ var SessionStatusService;
 var init_session_status = __esm({
   "src/services/session-status.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     SessionStatusService = class {
@@ -3278,6 +3807,7 @@ var InvoiceDownloadService;
 var init_invoice_download = __esm({
   "src/services/invoice-download.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     InvoiceDownloadService = class {
@@ -3320,9 +3850,11 @@ var PermissionsService;
 var init_permissions = __esm({
   "src/services/permissions.ts"() {
     "use strict";
+    init_esm_shims();
+    init_ksef_validation_error();
     init_rest_request();
     init_routes();
-    PermissionsService = class {
+    PermissionsService = class _PermissionsService {
       restClient;
       constructor(restClient) {
         this.restClient = restClient;
@@ -3380,6 +3912,7 @@ var init_permissions = __esm({
       }
       // Search methods
       async queryPersonalGrants(options, pageOffset, pageSize) {
+        _PermissionsService.validateContextIdentifier(options?.contextIdentifier);
         const req = RestRequest.post(Routes.Permissions.Query.personalGrants).body(options ?? {});
         if (pageOffset !== void 0) req.query("pageOffset", String(pageOffset));
         if (pageSize !== void 0) req.query("pageSize", String(pageSize));
@@ -3408,6 +3941,7 @@ var init_permissions = __esm({
         return response.body;
       }
       async queryEntitiesGrants(options, pageOffset, pageSize) {
+        _PermissionsService.validateContextIdentifier(options?.contextIdentifier);
         const req = RestRequest.post(Routes.Permissions.Query.entitiesGrants).body(options ?? {});
         if (pageOffset !== void 0) req.query("pageOffset", String(pageOffset));
         if (pageSize !== void 0) req.query("pageSize", String(pageSize));
@@ -3446,17 +3980,92 @@ var init_permissions = __esm({
         const response = await this.restClient.execute(req);
         return response.body;
       }
+      static validateContextIdentifier(ctx) {
+        if (!ctx) return;
+        if (ctx.type === "InternalId") {
+          const len = ctx.value.length;
+          if (len < 10 || len > 16) {
+            throw KSeFValidationError.fromField(
+              "contextIdentifier.value",
+              `InternalId must be 10-16 characters, got ${len}`
+            );
+          }
+        }
+      }
     };
   }
 });
 
+// src/utils/jwt.ts
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const payload = parts[1];
+    const json = Buffer.from(payload, "base64url").toString("utf-8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+function tryParseJson(value) {
+  if (typeof value !== "string") return void 0;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function tryParseJsonArray(value) {
+  if (typeof value !== "string") return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === "string") ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseKSeFTokenContext(token) {
+  const raw = decodeJwtPayload(token);
+  if (!raw) return null;
+  return {
+    type: typeof raw["typ"] === "string" ? raw["typ"] : void 0,
+    contextIdentifierType: typeof raw["cit"] === "string" ? raw["cit"] : void 0,
+    contextIdentifierValue: typeof raw["civ"] === "string" ? raw["civ"] : void 0,
+    authMethod: typeof raw["aum"] === "string" ? raw["aum"] : void 0,
+    permissions: tryParseJsonArray(raw["per"]),
+    subjectDetails: tryParseJson(raw["sud"]),
+    authorSubjectIdentifier: tryParseJson(raw["asi"]),
+    issuedAt: typeof raw["iat"] === "number" ? raw["iat"] : void 0,
+    expiresAt: typeof raw["exp"] === "number" ? raw["exp"] : void 0
+  };
+}
+var init_jwt = __esm({
+  "src/utils/jwt.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/services/tokens.ts
-var TokenService;
+function toTokenAuthorIdentifierType(value) {
+  return TOKEN_AUTHOR_IDENTIFIER_TYPES.has(value) ? value : void 0;
+}
+var TOKEN_AUTHOR_IDENTIFIER_TYPES, TokenService;
 var init_tokens = __esm({
   "src/services/tokens.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
+    init_jwt();
+    init_ksef_api_error();
+    init_ksef_error();
+    TOKEN_AUTHOR_IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+      "Nip",
+      "Pesel",
+      "Fingerprint"
+    ]);
     TokenService = class {
       restClient;
       constructor(restClient) {
@@ -3491,6 +4100,73 @@ var init_tokens = __esm({
         const req = RestRequest.delete(Routes.Tokens.byReference(ref));
         await this.restClient.executeVoid(req);
       }
+      /**
+       * Resolves the reference number of the token currently in use for authentication.
+       * The only JWT payload field treated as authoritative is the KSeF-specific `trn`
+       * (token reference number). Standard RFC 7519 claims such as `jti` are NOT a safe
+       * fallback — a `jti` that differs from the KSeF reference would cause a DELETE to
+       * hit a non-existent path, which `revokeSelf` treats as already-revoked, falsely
+       * reporting success while leaving the token active on the server. When `trn` is
+       * absent, we fall back to `GET /tokens` filtered by author and context; requires
+       * exactly one active match and returns undefined when ambiguous.
+       */
+      async findSelfReferenceNumber(accessToken) {
+        if (!accessToken) return void 0;
+        const payload = decodeJwtPayload(accessToken);
+        if (payload && typeof payload["trn"] === "string" && payload["trn"].length > 0) {
+          return payload["trn"];
+        }
+        const ctx = parseKSeFTokenContext(accessToken);
+        const author = ctx?.authorSubjectIdentifier;
+        if (!author?.type || !author.value) return void 0;
+        if (!ctx?.contextIdentifierType || !ctx?.contextIdentifierValue) return void 0;
+        const authorType = toTokenAuthorIdentifierType(author.type);
+        if (!authorType) return void 0;
+        let continuationToken;
+        let match;
+        do {
+          const list = await this.queryTokens({
+            status: ["Active"],
+            authorIdentifier: author.value,
+            authorIdentifierType: authorType,
+            pageSize: 50,
+            continuationToken
+          });
+          for (const t of list.tokens) {
+            if (t.status === "Active" && t.contextIdentifier?.value === ctx.contextIdentifierValue && t.contextIdentifier?.type === ctx.contextIdentifierType) {
+              if (match) return void 0;
+              match = t.referenceNumber;
+            }
+          }
+          continuationToken = list.continuationToken ?? void 0;
+        } while (continuationToken);
+        return match;
+      }
+      /**
+       * Revokes the token currently used for authentication.
+       * Treats 404/409/410 on DELETE as "already revoked" and returns successfully with
+       * `alreadyRevoked: true` so callers can still clear local state.
+       */
+      async revokeSelf(opts = {}) {
+        let ref = opts.referenceNumber;
+        if (!ref && opts.accessToken) {
+          ref = await this.findSelfReferenceNumber(opts.accessToken);
+        }
+        if (!ref) {
+          throw new KSeFError(
+            "Could not determine the current token reference number: no cache, JWT lacks the field, and the active-token list had 0 or 2+ matches in the current context."
+          );
+        }
+        try {
+          await this.revokeToken(ref);
+          return { referenceNumber: ref, alreadyRevoked: false };
+        } catch (err) {
+          if (err instanceof KSeFApiError && (err.statusCode === 404 || err.statusCode === 409 || err.statusCode === 410)) {
+            return { referenceNumber: ref, alreadyRevoked: true };
+          }
+          throw err;
+        }
+      }
     };
   }
 });
@@ -3500,6 +4176,7 @@ var CertificateApiService;
 var init_certificates = __esm({
   "src/services/certificates.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     CertificateApiService = class {
@@ -3552,6 +4229,7 @@ var LighthouseService;
 var init_lighthouse = __esm({
   "src/services/lighthouse.ts"() {
     "use strict";
+    init_esm_shims();
     init_errors();
     LighthouseService = class {
       lighthouseUrl;
@@ -3560,20 +4238,20 @@ var init_lighthouse = __esm({
         this.lighthouseUrl = options.lighthouseUrl;
         this.timeout = options.timeout;
       }
-      async fetchJson(path2) {
+      async fetchJson(path4) {
         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}${path2}`, {
+        const response = await fetch(`${this.lighthouseUrl}${path4}`, {
           headers: { Accept: "application/json" },
           signal: AbortSignal.timeout(this.timeout)
         });
         if (!response.ok) {
           const body = await response.text();
           throw new KSeFError(
-            `Lighthouse ${path2} failed: HTTP ${response.status} \u2014 ${body}`
+            `Lighthouse ${path4} failed: HTTP ${response.status} \u2014 ${body}`
           );
         }
         return await response.json();
@@ -3594,6 +4272,7 @@ var LimitsService;
 var init_limits = __esm({
   "src/services/limits.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     LimitsService = class {
@@ -3625,6 +4304,7 @@ var PeppolService;
 var init_peppol = __esm({
   "src/services/peppol.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     PeppolService = class {
@@ -3648,6 +4328,7 @@ var TestDataService;
 var init_test_data = __esm({
   "src/services/test-data.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     init_ksef_error();
@@ -3767,6 +4448,7 @@ var CertificateFetcher;
 var init_certificate_fetcher = __esm({
   "src/crypto/certificate-fetcher.ts"() {
     "use strict";
+    init_esm_shims();
     init_rest_request();
     init_routes();
     CertificateFetcher = class {
@@ -3862,6 +4544,7 @@ var CryptographyService;
 var init_cryptography_service = __esm({
   "src/crypto/cryptography-service.ts"() {
     "use strict";
+    init_esm_shims();
     CryptographyService = class {
       fetcher;
       constructor(fetcher) {
@@ -4099,6 +4782,40 @@ __export(signature_service_exports, {
 import * as crypto3 from "crypto";
 import { ExclusiveCanonicalization } from "xml-crypto";
 import { DOMParser as DOMParser2, XMLSerializer } from "@xmldom/xmldom";
+function pickRsaAlgo() {
+  return {
+    nodeHashName: "sha256",
+    signatureUri: RSA_SHA256_SIGNATURE_URI,
+    digestUri: DIGEST_URI.sha256
+  };
+}
+function pickEcdsaAlgo(privateKey) {
+  const curve = privateKey.asymmetricKeyDetails?.namedCurve;
+  switch (curve) {
+    case "prime256v1":
+      return {
+        nodeHashName: "sha256",
+        signatureUri: ECDSA_SIGNATURE_URI.sha256,
+        digestUri: DIGEST_URI.sha256
+      };
+    case "secp384r1":
+      return {
+        nodeHashName: "sha384",
+        signatureUri: ECDSA_SIGNATURE_URI.sha384,
+        digestUri: DIGEST_URI.sha384
+      };
+    case "secp521r1":
+      return {
+        nodeHashName: "sha512",
+        signatureUri: ECDSA_SIGNATURE_URI.sha512,
+        digestUri: DIGEST_URI.sha512
+      };
+    default:
+      throw new KSeFError(
+        `Unsupported ECDSA curve: ${curve ?? "unknown"}. Supported: P-256 (prime256v1), P-384 (secp384r1), P-521 (secp521r1).`
+      );
+  }
+}
 function extractDerFromPem(pem) {
   const base64 = pem.replace(/-----BEGIN [A-Z\s]+-----/g, "").replace(/-----END [A-Z\s]+-----/g, "").replace(/\s+/g, "");
   return Buffer.from(base64, "base64");
@@ -4113,22 +4830,22 @@ function canonicalize(elem) {
   const c14n = new ExclusiveCanonicalization();
   return c14n.process(elem, {});
 }
-function computeRootDigest(doc) {
+function computeRootDigest(doc, hashName) {
   const root = doc.documentElement;
   const canonical = canonicalize(root);
-  return crypto3.createHash("sha256").update(canonical, "utf-8").digest("base64");
+  return crypto3.createHash(hashName).update(canonical, "utf-8").digest("base64");
 }
-function computeSignedPropertiesDigest(qualifyingPropertiesXml) {
-  const parser = new DOMParser2();
-  const qpDoc = parser.parseFromString(qualifyingPropertiesXml, "text/xml");
+function computeSignedPropertiesDigest(qualifyingPropertiesXml, hashName) {
+  const parser2 = new DOMParser2();
+  const qpDoc = parser2.parseFromString(qualifyingPropertiesXml, "text/xml");
   const signedProps = findElementByLocalName(qpDoc.documentElement, "SignedProperties");
   if (!signedProps) {
     throw new Error("SignedProperties element not found in QualifyingProperties");
   }
   const canonical = canonicalize(signedProps);
-  return crypto3.createHash("sha256").update(canonical, "utf-8").digest("base64");
+  return crypto3.createHash(hashName).update(canonical, "utf-8").digest("base64");
 }
-function buildSignedInfo(signatureAlgorithm, rootDigest, signedPropertiesDigest) {
+function buildSignedInfo(signatureAlgorithm, digestAlgorithm, rootDigest, signedPropertiesDigest) {
   return [
     `<ds:SignedInfo xmlns:ds="${DS_NS}">`,
     `<ds:CanonicalizationMethod Algorithm="${EXC_C14N_ALGORITHM}"/>`,
@@ -4139,7 +4856,7 @@ function buildSignedInfo(signatureAlgorithm, rootDigest, signedPropertiesDigest)
     `<ds:Transform Algorithm="${ENVELOPED_SIGNATURE_TRANSFORM}"/>`,
     `<ds:Transform Algorithm="${EXC_C14N_ALGORITHM}"/>`,
     `</ds:Transforms>`,
-    `<ds:DigestMethod Algorithm="${SHA256_DIGEST_METHOD}"/>`,
+    `<ds:DigestMethod Algorithm="${digestAlgorithm}"/>`,
     `<ds:DigestValue>${rootDigest}</ds:DigestValue>`,
     `</ds:Reference>`,
     // Reference 2: SignedProperties
@@ -4147,22 +4864,22 @@ function buildSignedInfo(signatureAlgorithm, rootDigest, signedPropertiesDigest)
     `<ds:Transforms>`,
     `<ds:Transform Algorithm="${EXC_C14N_ALGORITHM}"/>`,
     `</ds:Transforms>`,
-    `<ds:DigestMethod Algorithm="${SHA256_DIGEST_METHOD}"/>`,
+    `<ds:DigestMethod Algorithm="${digestAlgorithm}"/>`,
     `<ds:DigestValue>${signedPropertiesDigest}</ds:DigestValue>`,
     `</ds:Reference>`,
     `</ds:SignedInfo>`
   ].join("");
 }
-function computeSignatureValue(canonicalSignedInfo, privateKey, isEc) {
+function computeSignatureValue(canonicalSignedInfo, privateKey, isEc, hashName) {
   const data = Buffer.from(canonicalSignedInfo, "utf-8");
   let signature;
   if (isEc) {
-    signature = crypto3.sign("sha256", data, {
+    signature = crypto3.sign(hashName, data, {
       key: privateKey,
       dsaEncoding: "ieee-p1363"
     });
   } else {
-    signature = crypto3.sign("sha256", data, privateKey);
+    signature = crypto3.sign(hashName, data, privateKey);
   }
   return signature.toString("base64");
 }
@@ -4183,7 +4900,7 @@ function buildSignatureElement(signedInfoXml, signatureValue, certBase64, qualif
     `</ds:Signature>`
   ].join("");
 }
-function buildQualifyingProperties(signatureId, signedPropertiesId, certDigest, issuerName, serialNumber, signingTime) {
+function buildQualifyingProperties(signatureId, signedPropertiesId, certDigest, issuerName, serialNumber, signingTime, digestAlgorithm) {
   return [
     `<xades:QualifyingProperties`,
     ` Target="#${signatureId}"`,
@@ -4195,7 +4912,7 @@ function buildQualifyingProperties(signatureId, signedPropertiesId, certDigest,
     `<xades:SigningCertificate>`,
     `<xades:Cert>`,
     `<xades:CertDigest>`,
-    `<DigestMethod Algorithm="${SHA256_DIGEST_METHOD}"/>`,
+    `<DigestMethod Algorithm="${digestAlgorithm}"/>`,
     `<DigestValue>${certDigest}</DigestValue>`,
     `</xades:CertDigest>`,
     `<xades:IssuerSerial>`,
@@ -4231,18 +4948,28 @@ function wrapBase64(base64) {
   }
   return lines.join("\n");
 }
-var XADES_NS, DS_NS, SIGNED_PROPERTIES_TYPE, SHA256_DIGEST_METHOD, EXC_C14N_ALGORITHM, ENVELOPED_SIGNATURE_TRANSFORM, RSA_SHA256_SIGNATURE, ECDSA_SHA256_SIGNATURE, CLOCK_SKEW_BUFFER_MS, SIGNATURE_ID, SIGNED_PROPERTIES_ID, SignatureService;
+var XADES_NS, DS_NS, SIGNED_PROPERTIES_TYPE, EXC_C14N_ALGORITHM, ENVELOPED_SIGNATURE_TRANSFORM, DIGEST_URI, ECDSA_SIGNATURE_URI, RSA_SHA256_SIGNATURE_URI, CLOCK_SKEW_BUFFER_MS, SIGNATURE_ID, SIGNED_PROPERTIES_ID, SignatureService;
 var init_signature_service = __esm({
   "src/crypto/signature-service.ts"() {
     "use strict";
+    init_esm_shims();
+    init_ksef_error();
     XADES_NS = "http://uri.etsi.org/01903/v1.3.2#";
     DS_NS = "http://www.w3.org/2000/09/xmldsig#";
     SIGNED_PROPERTIES_TYPE = "http://uri.etsi.org/01903#SignedProperties";
-    SHA256_DIGEST_METHOD = "http://www.w3.org/2001/04/xmlenc#sha256";
     EXC_C14N_ALGORITHM = "http://www.w3.org/2001/10/xml-exc-c14n#";
     ENVELOPED_SIGNATURE_TRANSFORM = "http://www.w3.org/2000/09/xmldsig#enveloped-signature";
-    RSA_SHA256_SIGNATURE = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256";
-    ECDSA_SHA256_SIGNATURE = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256";
+    DIGEST_URI = {
+      sha256: "http://www.w3.org/2001/04/xmlenc#sha256",
+      sha384: "http://www.w3.org/2001/04/xmldsig-more#sha384",
+      sha512: "http://www.w3.org/2001/04/xmlenc#sha512"
+    };
+    ECDSA_SIGNATURE_URI = {
+      sha256: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256",
+      sha384: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384",
+      sha512: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512"
+    };
+    RSA_SHA256_SIGNATURE_URI = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256";
     CLOCK_SKEW_BUFFER_MS = -6e4;
     SIGNATURE_ID = "Signature";
     SIGNED_PROPERTIES_ID = "SignedProperties";
@@ -4262,18 +4989,24 @@ var init_signature_service = __esm({
         }
         const certDer = extractDerFromPem(certPem);
         const certBase64 = certDer.toString("base64");
-        const certDigest = crypto3.createHash("sha256").update(certDer).digest("base64");
         const x5093 = new crypto3.X509Certificate(certPem);
         const issuerName = normalizeIssuerDn(x5093.issuer);
         const serialNumber = hexSerialToDecimal(x5093.serialNumber);
         const privateKey = crypto3.createPrivateKey(
           passphrase ? { key: privateKeyPem, format: "pem", passphrase } : privateKeyPem
         );
-        const isEc = privateKey.asymmetricKeyType === "ec";
-        const signatureAlgorithm = isEc ? ECDSA_SHA256_SIGNATURE : RSA_SHA256_SIGNATURE;
+        const keyType = privateKey.asymmetricKeyType;
+        if (keyType !== "ec" && keyType !== "rsa") {
+          throw new KSeFError(
+            `Unsupported private key type: ${keyType ?? "unknown"}. Supported: RSA and ECDSA.`
+          );
+        }
+        const isEc = keyType === "ec";
+        const algo = isEc ? pickEcdsaAlgo(privateKey) : pickRsaAlgo();
+        const certDigest = crypto3.createHash(algo.nodeHashName).update(certDer).digest("base64");
         const signingTime = new Date(Date.now() + CLOCK_SKEW_BUFFER_MS).toISOString();
-        const parser = new DOMParser2();
-        const doc = parser.parseFromString(xml, "text/xml");
+        const parser2 = new DOMParser2();
+        const doc = parser2.parseFromString(xml, "text/xml");
         const root = doc.documentElement;
         if (!root) {
           throw new Error("XML document has no root element");
@@ -4284,21 +5017,27 @@ var init_signature_service = __esm({
           certDigest,
           issuerName,
           serialNumber,
-          signingTime
+          signingTime,
+          algo.digestUri
+        );
+        const rootDigest = computeRootDigest(doc, algo.nodeHashName);
+        const signedPropertiesDigest = computeSignedPropertiesDigest(
+          qualifyingPropertiesXml,
+          algo.nodeHashName
         );
-        const rootDigest = computeRootDigest(doc);
-        const signedPropertiesDigest = computeSignedPropertiesDigest(qualifyingPropertiesXml);
         const signedInfoXml = buildSignedInfo(
-          signatureAlgorithm,
+          algo.signatureUri,
+          algo.digestUri,
           rootDigest,
           signedPropertiesDigest
         );
-        const signedInfoDoc = parser.parseFromString(signedInfoXml, "text/xml");
+        const signedInfoDoc = parser2.parseFromString(signedInfoXml, "text/xml");
         const canonicalSignedInfo = canonicalize(signedInfoDoc.documentElement);
         const signatureValue = computeSignatureValue(
           canonicalSignedInfo,
           privateKey,
-          isEc
+          isEc,
+          algo.nodeHashName
         );
         const signatureXml = buildSignatureElement(
           signedInfoXml,
@@ -4306,7 +5045,7 @@ var init_signature_service = __esm({
           certBase64,
           qualifyingPropertiesXml
         );
-        const signatureDoc = parser.parseFromString(signatureXml, "text/xml");
+        const signatureDoc = parser2.parseFromString(signatureXml, "text/xml");
         const importedNode = doc.importNode(signatureDoc.documentElement, true);
         root.appendChild(importedNode);
         return new XMLSerializer().serializeToString(doc);
@@ -4325,6 +5064,7 @@ var Pkcs12Loader;
 var init_pkcs12_loader = __esm({
   "src/crypto/pkcs12-loader.ts"() {
     "use strict";
+    init_esm_shims();
     Pkcs12Loader = class {
       static load(p12, password) {
         const { pki, pkcs12, asn1 } = forge;
@@ -4393,6 +5133,7 @@ var AUTH_TOKEN_REQUEST_NS;
 var init_auth_xml_builder = __esm({
   "src/crypto/auth-xml-builder.ts"() {
     "use strict";
+    init_esm_shims();
     AUTH_TOKEN_REQUEST_NS = "http://ksef.mf.gov.pl/auth/token/2.0";
   }
 });
@@ -4403,6 +5144,7 @@ var VerificationLinkService;
 var init_verification_link_service = __esm({
   "src/qr/verification-link-service.ts"() {
     "use strict";
+    init_esm_shims();
     VerificationLinkService = class {
       constructor(baseQrUrl) {
         this.baseQrUrl = baseQrUrl;
@@ -4424,11 +5166,11 @@ var init_verification_link_service = __esm({
        * Build certificate verification URL (Code II).
        * Format: {baseQrUrl}/certificate/{contextType}/{contextId}/{sellerNip}/{certSerial}/{hash_base64url}/{signature_base64url}
        */
-      buildCertificateVerificationUrl(contextType, contextId, sellerNip, certSerial, invoiceHashBase64, privateKeyPem) {
+      buildCertificateVerificationUrl(contextType, contextId, sellerNip, certSerial, invoiceHashBase64, privateKeyPem, privateKeyPassword) {
         const hashBase64Url = this.base64ToBase64Url(invoiceHashBase64);
         const pathWithoutSignature = `${this.baseQrUrl}/certificate/${contextType}/${contextId}/${sellerNip}/${certSerial}/${hashBase64Url}`;
         const dataToSign = pathWithoutSignature.replace(/^https?:\/\//, "");
-        const key = crypto5.createPrivateKey(privateKeyPem);
+        const key = privateKeyPassword !== void 0 ? crypto5.createPrivateKey({ key: privateKeyPem, format: "pem", passphrase: privateKeyPassword }) : crypto5.createPrivateKey(privateKeyPem);
         let signature;
         if (key.asymmetricKeyType === "rsa") {
           signature = crypto5.sign("sha256", Buffer.from(dataToSign), {
@@ -4544,6 +5286,7 @@ var DEFAULT_UNZIP_OPTIONS;
 var init_zip = __esm({
   "src/utils/zip.ts"() {
     "use strict";
+    init_esm_shims();
     DEFAULT_UNZIP_OPTIONS = {
       maxFiles: 1e4,
       maxTotalUncompressedSize: 2e9,
@@ -4615,6 +5358,7 @@ var holidayCache;
 var init_holidays = __esm({
   "src/offline/holidays.ts"() {
     "use strict";
+    init_esm_shims();
     holidayCache = /* @__PURE__ */ new Map();
   }
 });
@@ -4714,6 +5458,7 @@ var FAR_FUTURE;
 var init_deadline = __esm({
   "src/offline/deadline.ts"() {
     "use strict";
+    init_esm_shims();
     init_holidays();
     FAR_FUTURE = /* @__PURE__ */ new Date("9999-12-31T23:59:59Z");
   }
@@ -4725,6 +5470,7 @@ var OfflineInvoiceWorkflow;
 var init_offline_invoice_workflow = __esm({
   "src/workflows/offline-invoice-workflow.ts"() {
     "use strict";
+    init_esm_shims();
     init_ksef_api_error();
     init_deadline();
     init_document_structures();
@@ -4758,7 +5504,8 @@ var init_offline_invoice_workflow = __esm({
             input.sellerNip,
             options.certificate.certificateSerial,
             invoiceHashBase64,
-            options.certificate.privateKeyPem
+            options.certificate.privateKeyPem,
+            options.certificate.password
           );
         }
         const submitBy = options?.customDeadline ? typeof options.customDeadline === "string" ? options.customDeadline : options.customDeadline.toISOString() : calculateOfflineDeadline(mode, input.invoiceDate, options?.maintenanceWindow).toISOString();
@@ -4948,7 +5695,8 @@ var init_offline_invoice_workflow = __esm({
               original.sellerNip,
               options.certificate.certificateSerial,
               correctedHashBase64,
-              options.certificate.privateKeyPem
+              options.certificate.privateKeyPem,
+              options.certificate.password
             );
           }
           const correctionMetadata = {
@@ -5034,6 +5782,11 @@ function buildRestClientConfig(options, authManager) {
       endpointLimits: options.rateLimit.endpointLimits
     });
   }
+  if (options?.circuitBreaker === null) {
+    config.circuitBreakerPolicy = null;
+  } else if (options?.circuitBreaker) {
+    config.circuitBreakerPolicy = new CircuitBreakerPolicy(options.circuitBreaker);
+  }
   if (options?.presignedUrlHosts) {
     const base = defaultPresignedUrlPolicy();
     config.presignedUrlPolicy = {
@@ -5047,10 +5800,12 @@ var KSeFClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
+    init_esm_shims();
     init_config();
     init_rest_client();
     init_retry_policy();
     init_rate_limit_policy();
+    init_circuit_breaker_policy();
     init_presigned_url_policy();
     init_auth_manager();
     init_auth();
@@ -5184,10 +5939,12 @@ var init_client = __esm({
 });
 
 // src/index.ts
+init_esm_shims();
 init_config();
 init_errors();
 
 // src/http/index.ts
+init_esm_shims();
 init_route_builder();
 init_rest_request();
 init_rest_client();
@@ -5195,14 +5952,17 @@ init_routes();
 init_transport();
 init_retry_policy();
 init_rate_limit_policy();
+init_circuit_breaker_policy();
 init_auth_manager();
 init_presigned_url_policy();
 init_ksef_feature();
 
 // src/validation/index.ts
+init_esm_shims();
 init_patterns();
 
 // src/validation/constraints.ts
+init_esm_shims();
 var REQUIRED_CHALLENGE_LENGTH = 36;
 var CERTIFICATE_NAME_MIN_LENGTH = 5;
 var CERTIFICATE_NAME_MAX_LENGTH = 100;
@@ -5215,11 +5975,220 @@ var PERMISSION_DESCRIPTION_MAX_LENGTH = 256;
 init_xml_to_object();
 init_schema_registry();
 init_invoice_validator();
+init_char_validity();
+
+// src/validation/xsd-validator.ts
+init_esm_shims();
+import { createRequire } from "module";
+import * as fs from "fs";
+import * as path2 from "path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
+var cachedPkgRoot = null;
+function locatePackageRoot() {
+  if (cachedPkgRoot !== null) return cachedPkgRoot;
+  let dir = path2.dirname(fileURLToPath2(import.meta.url));
+  const root = path2.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path2.join(dir, "docs", "schemas");
+    if (fs.existsSync(candidate)) {
+      cachedPkgRoot = dir;
+      return dir;
+    }
+    dir = path2.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 path2.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";
+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 = path2.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 = path2.dirname(xsdPath);
+  const rawXsd = fs.readFileSync(xsdPath, "utf8");
+  const rewrittenXsd = rewriteSchemaLocations(rawXsd);
+  const baseUrl = pathToFileURL(xsdDir + path2.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();
 init_active_sessions();
 init_online_session();
@@ -5234,7 +6203,11 @@ init_limits();
 init_peppol();
 init_test_data();
 
+// src/builders/index.ts
+init_esm_shims();
+
 // src/builders/auth-token-request.ts
+init_esm_shims();
 init_ksef_validation_error();
 var AuthTokenRequestBuilder = class {
   challenge;
@@ -5289,6 +6262,7 @@ var AuthTokenRequestBuilder = class {
 };
 
 // src/builders/auth-ksef-token-request.ts
+init_esm_shims();
 init_ksef_validation_error();
 var AuthKsefTokenRequestBuilder = class {
   challenge;
@@ -5343,6 +6317,7 @@ var AuthKsefTokenRequestBuilder = class {
 };
 
 // src/builders/invoice-query-filter.ts
+init_esm_shims();
 init_ksef_validation_error();
 var InvoiceQueryFilterBuilder = class {
   subjectType;
@@ -5439,7 +6414,11 @@ var InvoiceQueryFilterBuilder = class {
   }
 };
 
+// src/builders/permissions/index.ts
+init_esm_shims();
+
 // src/builders/permissions/person-permission.ts
+init_esm_shims();
 init_ksef_validation_error();
 var PersonPermissionGrantBuilder = class {
   subjectIdentifier;
@@ -5489,6 +6468,7 @@ var PersonPermissionGrantBuilder = class {
 };
 
 // src/builders/permissions/entity-permission.ts
+init_esm_shims();
 init_ksef_validation_error();
 var EntityPermissionGrantBuilder = class {
   nip;
@@ -5538,6 +6518,7 @@ var EntityPermissionGrantBuilder = class {
 };
 
 // src/builders/permissions/authorization-permission.ts
+init_esm_shims();
 init_ksef_validation_error();
 var AuthorizationPermissionGrantBuilder = class {
   _subjectIdentifier;
@@ -5583,6 +6564,7 @@ var AuthorizationPermissionGrantBuilder = class {
 };
 
 // src/builders/batch-file.ts
+init_esm_shims();
 init_ksef_validation_error();
 import * as crypto from "crypto";
 var BATCH_MAX_PART_SIZE = 1e8;
@@ -5753,11 +6735,13 @@ function sha256Base64(data) {
 }
 
 // src/crypto/index.ts
+init_esm_shims();
 init_certificate_fetcher();
 init_cryptography_service();
 init_signature_service();
 
 // src/crypto/certificate-service.ts
+init_esm_shims();
 import * as crypto4 from "crypto";
 import * as x5092 from "@peculiar/x509";
 var CertificateService = class {
@@ -5843,9 +6827,11 @@ init_pkcs12_loader();
 init_auth_xml_builder();
 
 // src/qr/index.ts
+init_esm_shims();
 init_verification_link_service();
 
 // src/qr/qrcode-service.ts
+init_esm_shims();
 import * as QRCode from "qrcode";
 var QrCodeService = class _QrCodeService {
   static async generateQrCode(url, options) {
@@ -5905,54 +6891,12 @@ function escapeXml2(str) {
 }
 
 // src/utils/index.ts
+init_esm_shims();
 init_zip();
-
-// src/utils/jwt.ts
-function decodeJwtPayload(token) {
-  const parts = token.split(".");
-  if (parts.length !== 3) return null;
-  try {
-    const payload = parts[1];
-    const json = Buffer.from(payload, "base64url").toString("utf-8");
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
-function tryParseJson(value) {
-  if (typeof value !== "string") return void 0;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return void 0;
-  }
-}
-function tryParseJsonArray(value) {
-  if (typeof value !== "string") return void 0;
-  try {
-    const parsed = JSON.parse(value);
-    return Array.isArray(parsed) && parsed.every((item) => typeof item === "string") ? parsed : void 0;
-  } catch {
-    return void 0;
-  }
-}
-function parseKSeFTokenContext(token) {
-  const raw = decodeJwtPayload(token);
-  if (!raw) return null;
-  return {
-    type: typeof raw["typ"] === "string" ? raw["typ"] : void 0,
-    contextIdentifierType: typeof raw["cit"] === "string" ? raw["cit"] : void 0,
-    contextIdentifierValue: typeof raw["civ"] === "string" ? raw["civ"] : void 0,
-    authMethod: typeof raw["aum"] === "string" ? raw["aum"] : void 0,
-    permissions: tryParseJsonArray(raw["per"]),
-    subjectDetails: tryParseJson(raw["sud"]),
-    authorSubjectIdentifier: tryParseJson(raw["asi"]),
-    issuedAt: typeof raw["iat"] === "number" ? raw["iat"] : void 0,
-    expiresAt: typeof raw["exp"] === "number" ? raw["exp"] : void 0
-  };
-}
+init_jwt();
 
 // src/utils/hash.ts
+init_esm_shims();
 import crypto6 from "crypto";
 function sha256Base642(data) {
   return crypto6.createHash("sha256").update(data).digest("base64");
@@ -5964,7 +6908,11 @@ function verifyHash(data, expectedHash) {
 // src/utils/index.ts
 init_concurrency();
 
+// src/workflows/index.ts
+init_esm_shims();
+
 // src/workflows/polling.ts
+init_esm_shims();
 async function pollUntil(action, condition, options) {
   const intervalMs = options?.intervalMs ?? 2e3;
   const maxAttempts = options?.maxAttempts ?? 60;
@@ -5982,13 +6930,18 @@ async function pollUntil(action, condition, options) {
 }
 
 // src/workflows/online-session-workflow.ts
+init_esm_shims();
 init_ksef_session_expired_error();
 init_auth_manager();
 init_online_session();
 init_session_status();
 init_document_structures();
 
+// src/xml/index.ts
+init_esm_shims();
+
 // src/xml/upo-parser.ts
+init_esm_shims();
 init_ksef_validation_error();
 import { XMLParser } from "fast-xml-parser";
 function isRecord(value) {
@@ -6107,6 +7060,7 @@ function parseUpoXml(xml) {
 }
 
 // src/xml/invoice-field-extractor.ts
+init_esm_shims();
 import { XMLParser as XMLParser2 } from "fast-xml-parser";
 var invoiceParser = new XMLParser2({
   ignoreAttributes: false,
@@ -6146,6 +7100,529 @@ function nonEmptyString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 
+// src/xml/xml-engine.ts
+init_esm_shims();
+import { XMLBuilder, XMLParser as XMLParser3 } from "fast-xml-parser";
+var XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>\n';
+var parser = new XMLParser3({
+  ignoreAttributes: false,
+  preserveOrder: true,
+  attributeNamePrefix: "@_",
+  textNodeName: "#text",
+  allowBooleanAttributes: true,
+  // Preserve leading zeros and keep everything as strings — KSeF fields like
+  // KRS (`\d{10}`) and NIP (`\d{10}`) would otherwise be lossy through parse.
+  parseTagValue: false,
+  parseAttributeValue: false,
+  trimValues: false
+});
+var builder = new XMLBuilder({
+  ignoreAttributes: false,
+  preserveOrder: true,
+  attributeNamePrefix: "@_",
+  textNodeName: "#text",
+  format: false,
+  suppressBooleanAttributes: false,
+  suppressEmptyNode: false,
+  processEntities: true
+});
+function createObjectBuilder(pretty = false) {
+  return new XMLBuilder({
+    ignoreAttributes: false,
+    preserveOrder: false,
+    attributeNamePrefix: "@_",
+    textNodeName: "#text",
+    format: pretty,
+    suppressBooleanAttributes: false,
+    suppressEmptyNode: false,
+    processEntities: true
+  });
+}
+function prependDeclaration(xml) {
+  return xml.startsWith("<?xml") ? xml : `${XML_DECLARATION}${xml}`;
+}
+function parseXml(xml) {
+  return parser.parse(xml);
+}
+function buildXml(document) {
+  return prependDeclaration(builder.build(document));
+}
+function buildXmlFromObject(document, options) {
+  return prependDeclaration(createObjectBuilder(options?.pretty).build(document));
+}
+function stripBom(input) {
+  return input.charCodeAt(0) === 65279 ? input.slice(1) : input;
+}
+
+// src/xml/order-map.ts
+init_esm_shims();
+var ORDER_MAP = {
+  Faktura: ["Naglowek", "Podmiot1", "Podmiot2", "Podmiot3", "Fa", "Stopka"],
+  Naglowek: ["KodFormularza", "WariantFormularza", "DataWytworzeniaFa", "SystemInfo"],
+  Podmiot1: [
+    "PrefiksPodatnika",
+    "NrEORI",
+    "DaneIdentyfikacyjne",
+    "Adres",
+    "AdresKoresp",
+    "DaneKontaktowe",
+    "StatusInfoPodatnika"
+  ],
+  Podmiot2: [
+    "NrEORI",
+    "DaneIdentyfikacyjne",
+    "Adres",
+    "AdresKoresp",
+    "DaneKontaktowe",
+    "NrKlienta",
+    "IDNabywcy",
+    "JST",
+    "GV"
+  ],
+  Podmiot3: [
+    "IDNabywcy",
+    "NrEORI",
+    "DaneIdentyfikacyjne",
+    "Adres",
+    "AdresKoresp",
+    "DaneKontaktowe",
+    "Rola",
+    "Udzial"
+  ],
+  DaneIdentyfikacyjne: [
+    "NIP",
+    "IDWew",
+    "KodUE",
+    "NrVatUE",
+    "KodKraju",
+    "NrID",
+    "BrakID",
+    "Nazwa",
+    "Identyfikator",
+    "KRS"
+  ],
+  Adres: ["KodKraju", "AdresL1", "AdresL2", "AdresL3"],
+  DaneKontaktowe: ["Email", "Telefon"],
+  Fa: [
+    "KodWaluty",
+    "P_1",
+    "P_1M",
+    "P_2",
+    "WZ",
+    "P_6",
+    "OkresFa",
+    // Multi-rate interleave per VAT group — DO NOT flatten into P_13_* block then P_14_* block.
+    // See smekcio TS d1ec8fe and the "multi-rate interleave" regression test.
+    "P_13_1",
+    "P_14_1",
+    "P_14_1W",
+    "P_13_2",
+    "P_14_2",
+    "P_14_2W",
+    "P_13_3",
+    "P_14_3",
+    "P_14_3W",
+    "P_13_4",
+    "P_14_4",
+    "P_14_4W",
+    "P_13_5",
+    "P_14_5",
+    "P_13_6_1",
+    "P_13_6_2",
+    "P_13_6_3",
+    "P_13_7",
+    "P_13_8",
+    "P_13_9",
+    "P_13_10",
+    "P_13_11",
+    "P_15",
+    "KursWalutyZ",
+    "Adnotacje",
+    "RodzajFaktury",
+    "PrzyczynaKorekty",
+    "TypKorekty",
+    "DaneFaKorygowanej",
+    "OkresFaKorygowanej",
+    "NrFaKorygowany",
+    "Podmiot1K",
+    "Podmiot2K",
+    "Podmiot3K",
+    "ZaliczkaCzesciowa",
+    "FP",
+    "TP",
+    "DodatkowyOpis",
+    "FakturaZaliczkowa",
+    "ZwrotAkcyzy",
+    "FaWiersz",
+    "FaWiersze",
+    "Rozliczenie",
+    "Platnosc"
+  ],
+  Adnotacje: ["P_16", "P_17", "P_18", "P_18A", "Zwolnienie", "NoweSrodkiTransportu", "P_23", "PMarzy"],
+  OkresFa: ["P_6_Od", "P_6_Do"],
+  FaWiersz: [
+    "NrWierszaFa",
+    "UU_ID",
+    "P_6A",
+    "P_7",
+    "Indeks",
+    "GTIN",
+    "PKWiU",
+    "CN",
+    "PKOB",
+    "P_8A",
+    "P_8B",
+    "P_9A",
+    "P_9B",
+    "P_10",
+    "P_11",
+    "P_11A",
+    "P_11Vat",
+    "P_12",
+    "P_12_XII",
+    "P_12_Zal_15",
+    "KwotaAkcyzy",
+    "GTU",
+    "Procedura",
+    "KursWaluty",
+    "StanPrzed"
+  ]
+};
+function comparePKey(a, b) {
+  const normalize = (value) => value.replace(/^P_/, "").split("_").map((part) => Number.isNaN(Number(part)) ? part : Number(part));
+  const aParts = normalize(a);
+  const bParts = normalize(b);
+  const max = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < max; i += 1) {
+    const left = aParts[i];
+    const right = bParts[i];
+    if (left === void 0) return -1;
+    if (right === void 0) return 1;
+    if (typeof left === "number" && typeof right === "number") {
+      if (left !== right) return left - right;
+      continue;
+    }
+    const leftStr = String(left);
+    const rightStr = String(right);
+    if (leftStr !== rightStr) return leftStr < rightStr ? -1 : 1;
+  }
+  return 0;
+}
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValueForKey(key, value) {
+  if (Array.isArray(value)) {
+    return value.map(
+      (item) => isObject(item) ? orderXmlObject(item, key) : normalizeValue(item)
+    );
+  }
+  if (isObject(value)) return orderXmlObject(value, key);
+  return value;
+}
+function normalizeValue(value) {
+  if (Array.isArray(value)) return value.map((item) => normalizeValue(item));
+  if (isObject(value)) return orderXmlObject(value);
+  return value;
+}
+function orderXmlObject(value, contextKey) {
+  const order = contextKey ? ORDER_MAP[contextKey] : void 0;
+  const keys = Object.keys(value);
+  const used = /* @__PURE__ */ new Set();
+  const ordered = {};
+  if (order) {
+    for (const key of order) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
+        const item = value[key];
+        if (item !== void 0) ordered[key] = normalizeValueForKey(key, item);
+        used.add(key);
+      }
+    }
+  }
+  const pKeys = keys.filter((key) => !used.has(key) && key.startsWith("P_")).sort(comparePKey);
+  for (const key of pKeys) {
+    const item = value[key];
+    if (item !== void 0) ordered[key] = normalizeValueForKey(key, item);
+    used.add(key);
+  }
+  for (const key of keys) {
+    if (used.has(key)) continue;
+    const item = value[key];
+    if (item !== void 0) ordered[key] = normalizeValueForKey(key, item);
+  }
+  return ordered;
+}
+
+// src/xml/faktura-builder.ts
+init_esm_shims();
+var FAKTURA_NAMESPACE = {
+  FA2: "http://crd.gov.pl/wzor/2023/06/29/12648/",
+  FA3: "http://crd.gov.pl/wzor/2025/06/25/13775/"
+};
+var ETD_NAMESPACE = {
+  FA2: "http://crd.gov.pl/xml/schematy/2020/10/08/eDokumenty",
+  FA3: "http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
+};
+function toKodFormularza(formCode) {
+  return {
+    "@_kodSystemowy": formCode.systemCode,
+    "@_wersjaSchemy": formCode.schemaVersion,
+    "#text": formCode.value
+  };
+}
+function isFormCodeShape(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value;
+  return typeof candidate.systemCode === "string" && typeof candidate.schemaVersion === "string" && typeof candidate.value === "string";
+}
+function isObject2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeTopLevelChild(key, value) {
+  if (key === "Naglowek" && isObject2(value)) {
+    return normalizeNaglowek(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => isObject2(item) ? orderXmlObject(item, key) : item);
+  }
+  if (isObject2(value)) return orderXmlObject(value, key);
+  return value;
+}
+function normalizeNaglowek(value) {
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === void 0) continue;
+    if (key === "KodFormularza" && isFormCodeShape(item)) {
+      result[key] = toKodFormularza(item);
+      continue;
+    }
+    if (Array.isArray(item)) {
+      result[key] = item.map(
+        (entry) => isObject2(entry) ? orderXmlObject(entry, key) : entry
+      );
+      continue;
+    }
+    if (isObject2(item)) {
+      result[key] = orderXmlObject(item, key);
+      continue;
+    }
+    result[key] = item;
+  }
+  return result;
+}
+function normalizeTopLevel(input) {
+  const result = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0) continue;
+    result[key] = normalizeTopLevelChild(key, value);
+  }
+  return result;
+}
+function buildFakturaXml(faktura, options = {}) {
+  const schema = options.schema ?? "FA3";
+  const fakturaNamespace = options.fakturaNamespace ?? FAKTURA_NAMESPACE[schema];
+  const etdNamespace = options.etdNamespace ?? ETD_NAMESPACE[schema];
+  const normalized = normalizeTopLevel(faktura);
+  const ordered = orderXmlObject(normalized, "Faktura");
+  const document = {
+    Faktura: {
+      ...ordered,
+      "@_xmlns": fakturaNamespace,
+      "@_xmlns:etd": etdNamespace
+    }
+  };
+  return buildXmlFromObject(document, { pretty: options.pretty });
+}
+function isFakturaInput(input) {
+  if (!isObject2(input)) return false;
+  const candidate = input;
+  if (!Object.prototype.hasOwnProperty.call(candidate, "Naglowek")) return false;
+  if (!Object.prototype.hasOwnProperty.call(candidate, "Fa")) return false;
+  return isObject2(candidate.Naglowek) && isObject2(candidate.Fa);
+}
+
+// src/xml/pef-builder.ts
+init_esm_shims();
+init_ksef_validation_error();
+var PEF_NAMESPACE = {
+  PEF: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
+  PEF_KOR: "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
+};
+var UBL_EXT_NS = "urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2";
+var UBL_CBC_NS = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2";
+var UBL_CAC_NS = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2";
+var UBL_CBC_PL_NS = "urn:pl:extended:CommonBasicComponents-2";
+var UBL_CAC_PL_NS = "urn:pl:extended:CommonAggregateComponents-2";
+function isPefUblDocumentInput(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return false;
+  const obj = input;
+  const invoice = obj.Invoice;
+  const creditNote = obj.CreditNote;
+  const hasInvoice = typeof invoice === "object" && invoice !== null && !Array.isArray(invoice);
+  const hasCreditNote = typeof creditNote === "object" && creditNote !== null && !Array.isArray(creditNote);
+  return hasInvoice !== hasCreditNote;
+}
+function inferSchema(input) {
+  return "Invoice" in input ? "PEF" : "PEF_KOR";
+}
+function isNonArrayObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertPefShape(input) {
+  if (!isNonArrayObject(input)) {
+    throw new KSeFValidationError("PEF input must be a non-array object.");
+  }
+  const hasInvoiceKey = "Invoice" in input;
+  const hasCreditNoteKey = "CreditNote" in input;
+  if (hasInvoiceKey && hasCreditNoteKey) {
+    throw new KSeFValidationError(
+      "PEF input must contain exactly one of `Invoice` or `CreditNote`, not both."
+    );
+  }
+  if (!hasInvoiceKey && !hasCreditNoteKey) {
+    throw new KSeFValidationError(
+      "PEF input must contain either an `Invoice` or a `CreditNote` root element."
+    );
+  }
+  const rootKey = hasInvoiceKey ? "Invoice" : "CreditNote";
+  if (!isNonArrayObject(input[rootKey])) {
+    throw new KSeFValidationError(
+      `PEF \`${rootKey}\` value must be a non-array object.`
+    );
+  }
+}
+function buildPefXml(input, options = {}) {
+  assertPefShape(input);
+  const inferred = inferSchema(input);
+  const schema = options.schema ?? input.schema ?? inferred;
+  if (schema !== inferred) {
+    throw new KSeFValidationError(
+      `PEF schema mismatch: expected ${inferred} based on root element, got ${schema}.`
+    );
+  }
+  const commonNamespaces = {
+    "@_xmlns:ext": UBL_EXT_NS,
+    "@_xmlns:cbc": UBL_CBC_NS,
+    "@_xmlns:cac": UBL_CAC_NS,
+    "@_xmlns:cbc-pl": UBL_CBC_PL_NS,
+    "@_xmlns:cac-pl": UBL_CAC_PL_NS
+  };
+  const document = "Invoice" in input ? {
+    Invoice: {
+      ...input.Invoice,
+      "@_xmlns": PEF_NAMESPACE.PEF,
+      ...commonNamespaces
+    }
+  } : {
+    CreditNote: {
+      ...input.CreditNote,
+      "@_xmlns": PEF_NAMESPACE.PEF_KOR,
+      ...commonNamespaces
+    }
+  };
+  return buildXmlFromObject(document, { pretty: options.pretty });
+}
+
+// src/xml/invoice-serializer.ts
+init_esm_shims();
+init_ksef_validation_error();
+var FAKTURA_SCHEMAS = /* @__PURE__ */ new Set(["FA2", "FA3"]);
+var PEF_SCHEMAS = /* @__PURE__ */ new Set(["PEF", "PEF_KOR"]);
+function isNonArrayObject2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function classifyUnknownObject(input) {
+  const looksLikeFaktura = "Naglowek" in input || "Fa" in input || "Podmiot1" in input || "Podmiot2" in input;
+  const hasInvoice = "Invoice" in input;
+  const hasCreditNote = "CreditNote" in input;
+  if (hasInvoice && hasCreditNote) {
+    return new KSeFValidationError(
+      "Input must contain exactly one of `Invoice` or `CreditNote`, not both."
+    );
+  }
+  if (hasInvoice !== hasCreditNote) {
+    const rootKey = hasInvoice ? "Invoice" : "CreditNote";
+    if (!isNonArrayObject2(input[rootKey])) {
+      return KSeFValidationError.fromField(
+        rootKey,
+        `PEF \`${rootKey}\` value must be a non-array object.`
+      );
+    }
+  }
+  if (looksLikeFaktura) {
+    const missing = [];
+    if (!("Naglowek" in input)) missing.push("Naglowek");
+    if (!("Fa" in input)) missing.push("Fa");
+    if (missing.length > 0) {
+      return KSeFValidationError.fromField(
+        missing[0],
+        `Faktura input is missing required top-level key(s): ${missing.join(", ")}.`
+      );
+    }
+    for (const key of ["Naglowek", "Fa"]) {
+      if (!isNonArrayObject2(input[key])) {
+        return KSeFValidationError.fromField(
+          key,
+          `Faktura \`${key}\` value must be a non-null, non-array object.`
+        );
+      }
+    }
+    return new KSeFValidationError(
+      "Faktura-like input failed shape validation: `Naglowek` and `Fa` must be own enumerable properties on the input object."
+    );
+  }
+  return new KSeFValidationError(
+    "Unsupported invoice input shape: expected `FakturaInput` (with `Naglowek` + `Fa`) or `PefUblDocumentInput` (with `Invoice` or `CreditNote`)."
+  );
+}
+function serializeInvoiceXml(input, options) {
+  if (Buffer.isBuffer(input)) return input;
+  if (typeof input === "string") {
+    return Buffer.from(stripBom(input), "utf8");
+  }
+  if (Array.isArray(input)) {
+    return Buffer.from(stripBom(buildXml(input)), "utf8");
+  }
+  if (input && typeof input === "object") {
+    const schema = options?.schema;
+    if (isPefUblDocumentInput(input)) {
+      if (schema && !PEF_SCHEMAS.has(schema)) {
+        throw new KSeFValidationError(
+          `schema option ${schema} is not compatible with a PEF / PEF_KOR input.`
+        );
+      }
+      const pefSchema = schema === "PEF" || schema === "PEF_KOR" ? schema : void 0;
+      const xml = buildPefXml(input, {
+        schema: pefSchema,
+        pretty: options?.pretty
+      });
+      return Buffer.from(stripBom(xml), "utf8");
+    }
+    if (isFakturaInput(input)) {
+      if (schema && !FAKTURA_SCHEMAS.has(schema)) {
+        throw new KSeFValidationError(
+          `schema option ${schema} is not compatible with a Faktura input.`
+        );
+      }
+      const fakturaSchema = schema === "FA2" || schema === "FA3" ? schema : void 0;
+      const xml = buildFakturaXml(input, {
+        schema: fakturaSchema,
+        fakturaNamespace: options?.fakturaNamespace,
+        etdNamespace: options?.etdNamespace,
+        pretty: options?.pretty
+      });
+      return Buffer.from(stripBom(xml), "utf8");
+    }
+    throw classifyUnknownObject(input);
+  }
+  throw new KSeFValidationError(
+    "Unsupported invoice input type: expected Buffer, string, XmlDocument, FakturaInput, or PefUblDocumentInput."
+  );
+}
+function buildRawXmlString(document, options) {
+  return buildXmlFromObject(document, options);
+}
+
 // src/workflows/online-session-workflow.ts
 init_invoice_validator();
 init_ksef_validation_error();
@@ -6283,6 +7760,7 @@ async function openSendAndClose(client, invoices, options) {
 }
 
 // src/workflows/batch-session-workflow.ts
+init_esm_shims();
 init_document_structures();
 async function uploadBatch(client, zipData, options) {
   if (options?.parallelism !== void 0 && (!Number.isInteger(options.parallelism) || options.parallelism < 1)) {
@@ -6421,6 +7899,7 @@ async function uploadBatchParsed(client, zipData, options) {
 }
 
 // src/workflows/invoice-export-workflow.ts
+init_esm_shims();
 init_zip();
 async function doExport(client, filters, options) {
   await client.crypto.init();
@@ -6493,7 +7972,11 @@ async function exportAndDownload(client, filters, options) {
   };
 }
 
+// src/workflows/incremental-export-workflow.ts
+init_esm_shims();
+
 // src/workflows/hwm-coordinator.ts
+init_esm_shims();
 function updateContinuationPoint(points, subjectType, pkg) {
   if (pkg.isTruncated && pkg.lastPermanentStorageDate) {
     points[subjectType] = pkg.lastPermanentStorageDate;
@@ -6591,7 +8074,8 @@ function buildDefaultFilters(subjectType, from, to) {
 }
 
 // src/workflows/hwm-storage.ts
-import * as fs from "fs/promises";
+init_esm_shims();
+import * as fs2 from "fs/promises";
 var InMemoryHwmStore = class {
   points = {};
   async load() {
@@ -6607,7 +8091,7 @@ var FileHwmStore = class {
   }
   async load() {
     try {
-      const data = await fs.readFile(this.filePath, "utf-8");
+      const data = await fs2.readFile(this.filePath, "utf-8");
       return JSON.parse(data);
     } catch (err) {
       if (err.code === "ENOENT") {
@@ -6617,11 +8101,12 @@ var FileHwmStore = class {
     }
   }
   async save(points) {
-    await fs.writeFile(this.filePath, JSON.stringify(points, null, 2), "utf-8");
+    await fs2.writeFile(this.filePath, JSON.stringify(points, null, 2), "utf-8");
   }
 };
 
 // src/workflows/auth-workflow.ts
+init_esm_shims();
 init_auth_xml_builder();
 async function authenticateWithToken(client, options) {
   const challenge = await client.auth.getChallenge();
@@ -6718,10 +8203,12 @@ async function authenticateWithPkcs12(client, options) {
 }
 
 // src/offline/index.ts
+init_esm_shims();
 init_deadline();
 init_holidays();
 
 // src/offline/storage.ts
+init_esm_shims();
 function matchesFilter(invoice, filter) {
   if (filter.status !== void 0) {
     const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
@@ -6760,12 +8247,13 @@ var InMemoryOfflineInvoiceStorage = class {
 };
 
 // src/offline/file-storage.ts
-import * as fs2 from "fs/promises";
-import * as path from "path";
+init_esm_shims();
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
 import * as os from "os";
 function resolveDir(dir) {
   if (dir === "~" || dir.startsWith("~/")) {
-    return path.join(os.homedir(), dir.slice(1));
+    return path3.join(os.homedir(), dir.slice(1));
   }
   return dir;
 }
@@ -6781,23 +8269,23 @@ var FileOfflineInvoiceStorage = class {
     this.dir = resolveDir(directory ?? "~/.ksef/offline");
   }
   async ensureDir() {
-    await fs2.mkdir(this.dir, { recursive: true });
+    await fs3.mkdir(this.dir, { recursive: true });
   }
   filePath(id) {
     validateId(id);
-    return path.join(this.dir, `${id}.json`);
+    return path3.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);
+    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 fs2.readFile(file, "utf-8"));
+      return JSON.parse(await fs3.readFile(file, "utf-8"));
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
         return null;
@@ -6809,7 +8297,7 @@ var FileOfflineInvoiceStorage = class {
   async list(filter) {
     let files;
     try {
-      files = (await fs2.readdir(this.dir)).filter((f) => f.endsWith(".json"));
+      files = (await fs3.readdir(this.dir)).filter((f) => f.endsWith(".json"));
     } catch {
       return [];
     }
@@ -6817,7 +8305,7 @@ var FileOfflineInvoiceStorage = class {
     for (const file of files) {
       try {
         const data = JSON.parse(
-          await fs2.readFile(path.join(this.dir, file), "utf-8")
+          await fs3.readFile(path3.join(this.dir, file), "utf-8")
         );
         if (!filter || matchesFilter(data, filter)) {
           results.push(data);
@@ -6843,7 +8331,7 @@ var FileOfflineInvoiceStorage = class {
   async delete(id) {
     const file = this.filePath(id);
     try {
-      await fs2.unlink(file);
+      await fs3.unlink(file);
     } catch (e) {
       if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
     }
@@ -6872,12 +8360,17 @@ export {
   CertificateFingerprint,
   CertificateName,
   CertificateService,
+  CircuitBreakerPolicy,
   CryptographyService,
   DEFAULT_FORM_CODE,
+  DISCOURAGED_UNICODE_RANGES,
   DefaultAuthManager,
   ENFORCE_XADES_COMPLIANCE,
+  ETD_NAMESPACE,
   EntityPermissionGrantBuilder,
   Environment,
+  FAKTURA_NAMESPACE,
+  FA_XSD_PATHS,
   FORM_CODES,
   FORM_CODE_KEYS,
   FileHwmStore,
@@ -6894,7 +8387,9 @@ export {
   KSEF_FEATURE_HEADER,
   KSeFApiError,
   KSeFAuthStatusError,
+  KSeFBadRequestError,
   KSeFBatchTimeoutError,
+  KSeFCircuitOpenError,
   KSeFClient,
   KSeFError,
   KSeFErrorCode,
@@ -6904,6 +8399,7 @@ export {
   KSeFSessionExpiredError,
   KSeFUnauthorizedError,
   KSeFValidationError,
+  KSeFXsdValidationError,
   KsefNumber,
   KsefNumberV35,
   KsefNumberV36,
@@ -6911,8 +8407,11 @@ export {
   LimitsService,
   Nip,
   NipVatUe,
+  ORDER_MAP,
   OfflineInvoiceWorkflow,
   OnlineSessionService,
+  PEF_NAMESPACE,
+  PEF_XSD_PATHS,
   PERMISSION_DESCRIPTION_MAX_LENGTH,
   PERMISSION_DESCRIPTION_MIN_LENGTH,
   PeppolId,
@@ -6942,17 +8441,25 @@ export {
   VatUe,
   VerificationLinkService,
   addBusinessDays,
+  assertNever,
   authenticateWithCertificate,
   authenticateWithExternalSignature,
   authenticateWithPkcs12,
   authenticateWithToken,
   batchValidationDetails,
+  buildFakturaXml,
+  buildPefXml,
+  buildRawXmlString,
   buildUnsignedAuthTokenRequestXml,
+  buildXml,
+  buildXmlFromObject,
   calculateBackoff,
   calculateOfflineDeadline,
+  comparePKey,
   createZip,
   decodeJwtPayload,
   deduplicateByKsefNumber,
+  defaultCircuitBreakerPolicy,
   defaultPresignedUrlPolicy,
   defaultRateLimitPolicy,
   defaultRetryPolicy,
@@ -6968,6 +8475,9 @@ export {
   getTimeUntilDeadline,
   incrementalExportAndDownload,
   isExpired,
+  isFakturaInput,
+  isFormCodeShape,
+  isPefUblDocumentInput,
   isPolishHoliday,
   isRetryableError,
   isRetryableStatus,
@@ -6986,19 +8496,26 @@ export {
   isValidReferenceNumber,
   isValidSha256Base64,
   isValidVatUe,
+  libxmljsAvailable,
   nextBusinessDay,
   openOnlineSession,
   openSendAndClose,
+  orderXmlObject,
   parseFormCode,
   parseKSeFTokenContext,
   parseRetryAfter,
   parseUpoXml,
+  parseXml,
   pollUntil,
   resolveOptions,
+  resolveXsdFor,
   resumeOnlineSession,
   runWithConcurrency,
+  serializeInvoiceXml,
   sha256Base642 as sha256Base64,
   sleep,
+  stripBom,
+  toKodFormularza,
   unzip,
   updateContinuationPoint,
   uploadBatch,
@@ -7006,8 +8523,10 @@ export {
   uploadBatchStream,
   uploadBatchStreamParsed,
   validate,
+  validateAgainstXsd,
   validateBatch,
   validateBusinessRules,
+  validateCharValidity,
   validateFormCodeForSession,
   validatePresignedUrl,
   validateSchema,