ksef-client-ts 0.6.1 → 0.7.0

package/dist/index.js

@@ -43,7 +43,8 @@ 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;
@@ -99,6 +100,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 };
+      }
     };
   }
 });
@@ -110,17 +114,20 @@ var init_ksef_rate_limit_error = __esm({
     "use strict";
     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 +142,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,18 +162,28 @@ var KSeFUnauthorizedError;
 var init_ksef_unauthorized_error = __esm({
   "src/errors/ksef-unauthorized-error.ts"() {
     "use strict";
-    init_ksef_error();
-    KSeFUnauthorizedError = class extends KSeFError {
+    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
+        };
       }
     };
   }
@@ -169,22 +194,101 @@ var KSeFForbiddenError;
 var init_ksef_forbidden_error = __esm({
   "src/errors/ksef-forbidden-error.ts"() {
     "use strict";
-    init_ksef_error();
-    KSeFForbiddenError = class extends KSeFError {
+    init_ksef_api_error();
+    KSeFForbiddenError = class extends KSeFApiError {
       statusCode = 403;
       detail;
       reasonCode;
       instance;
       security;
       traceId;
+      timestamp;
       constructor(problemDetails) {
-        super(problemDetails.detail || "Forbidden");
+        super(problemDetails.detail || "Forbidden", 403);
         this.name = "KSeFForbiddenError";
         this.detail = problemDetails.detail;
         this.reasonCode = problemDetails.reasonCode;
         this.instance = problemDetails.instance;
         this.security = problemDetails.security;
         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
+        };
+      }
+    };
+  }
+});
+
+// src/errors/ksef-gone-error.ts
+var KSeFGoneError;
+var init_ksef_gone_error = __esm({
+  "src/errors/ksef-gone-error.ts"() {
+    "use strict";
+    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)", 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_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
+        };
       }
     };
   }
@@ -252,6 +356,55 @@ var init_ksef_validation_error = __esm({
   }
 });
 
+// src/errors/error-codes.ts
+function hasErrorCode(body, code) {
+  return !!body?.exception?.exceptionDetailList?.some((d) => d.exceptionCode === code);
+}
+var KSeFErrorCode;
+var init_error_codes = __esm({
+  "src/errors/error-codes.ts"() {
+    "use strict";
+    KSeFErrorCode = {
+      BatchTimeout: 21208,
+      DuplicateInvoice: 440
+    };
+  }
+});
+
+// src/errors/ksef-batch-timeout-error.ts
+var KSeFBatchTimeoutError;
+var init_ksef_batch_timeout_error = __esm({
+  "src/errors/ksef-batch-timeout-error.ts"() {
+    "use strict";
+    init_ksef_api_error();
+    init_error_codes();
+    KSeFBatchTimeoutError = class _KSeFBatchTimeoutError extends KSeFApiError {
+      errorCode = KSeFErrorCode.BatchTimeout;
+      constructor(message, statusCode, errorResponse) {
+        super(message, statusCode, errorResponse);
+        this.name = "KSeFBatchTimeoutError";
+      }
+      static fromResponse(statusCode, body) {
+        const detail = body?.exception?.exceptionDetailList?.find(
+          (d) => d.exceptionCode === KSeFErrorCode.BatchTimeout
+        );
+        const message = detail?.exceptionDescription?.trim() || "Batch session timed out before the server completed processing (KSeF 21208).";
+        return new _KSeFBatchTimeoutError(message, statusCode, body);
+      }
+    };
+  }
+});
+
+// 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";
+  }
+});
+
 // src/errors/index.ts
 var init_errors = __esm({
   "src/errors/index.ts"() {
@@ -261,9 +414,14 @@ var init_errors = __esm({
     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_error_codes();
+    init_assert_never();
   }
 });
 
@@ -512,6 +670,27 @@ 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"() {
@@ -520,6 +699,10 @@ var init_rest_client = __esm({
     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();
     init_transport();
     init_retry_policy();
@@ -606,6 +789,10 @@ var init_rest_client = __esm({
           ...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) {
@@ -644,34 +831,70 @@ 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) {
-          const body = parseJson();
-          if (body?.detail) {
-            throw new KSeFUnauthorizedError(body);
+          const body2 = parseJson();
+          if (body2?.detail) {
+            throw new KSeFUnauthorizedError(body2);
           }
         }
         if (response.status === 403) {
-          const body = parseJson();
-          if (body?.reasonCode) {
-            throw new KSeFForbiddenError(body);
+          const body2 = parseJson();
+          if (body2?.reasonCode) {
+            throw new KSeFForbiddenError(body2);
           }
         }
-        throw KSeFApiError.fromResponse(response.status, parseJson());
+        if (response.status === 410) {
+          const body2 = parseJson();
+          throw new KSeFGoneError({
+            title: body2?.title || "Gone",
+            status: body2?.status || 410,
+            detail: body2?.detail || "Operation status no longer available (retention expired)",
+            instance: body2?.instance,
+            traceId: body2?.traceId,
+            timestamp: body2?.timestamp
+          });
+        }
+        const body = parseJson();
+        if (hasErrorCode(body, KSeFErrorCode.BatchTimeout)) {
+          throw KSeFBatchTimeoutError.fromResponse(response.status, body);
+        }
+        throw KSeFApiError.fromResponse(response.status, body);
       }
     };
   }
@@ -2590,6 +2813,115 @@ 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";
+    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, {
@@ -2742,6 +3074,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;
@@ -2768,6 +3106,7 @@ var init_invoice_validator = __esm({
     "use strict";
     init_xml_to_object();
     init_schema_registry();
+    init_char_validity();
     init_patterns();
   }
 });
@@ -3232,9 +3571,10 @@ var PermissionsService;
 var init_permissions = __esm({
   "src/services/permissions.ts"() {
     "use strict";
+    init_ksef_validation_error();
     init_rest_request();
     init_routes();
-    PermissionsService = class {
+    PermissionsService = class _PermissionsService {
       restClient;
       constructor(restClient) {
         this.restClient = restClient;
@@ -3292,6 +3632,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));
@@ -3320,6 +3661,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));
@@ -3358,17 +3700,90 @@ 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";
+  }
+});
+
 // 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_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) {
@@ -3403,6 +3818,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;
+        }
+      }
     };
   }
 });
@@ -4031,8 +4513,8 @@ function computeRootDigest(doc) {
   return crypto3.createHash("sha256").update(canonical, "utf-8").digest("base64");
 }
 function computeSignedPropertiesDigest(qualifyingPropertiesXml) {
-  const parser = new DOMParser2();
-  const qpDoc = parser.parseFromString(qualifyingPropertiesXml, "text/xml");
+  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");
@@ -4184,8 +4666,8 @@ var init_signature_service = __esm({
         const isEc = privateKey.asymmetricKeyType === "ec";
         const signatureAlgorithm = isEc ? ECDSA_SHA256_SIGNATURE : RSA_SHA256_SIGNATURE;
         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");
@@ -4205,7 +4687,7 @@ var init_signature_service = __esm({
           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,
@@ -4218,7 +4700,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);
@@ -5057,6 +5539,7 @@ var init_client = __esm({
         const tokens = await this.auth.getAccessToken(authToken);
         this.authManager.setAccessToken(tokens.accessToken.token);
         this.authManager.setRefreshToken(tokens.refreshToken.token);
+        return { clientIp: challenge.clientIp };
       }
       async loginWithCertificate(certPem, keyPem, nip, keyPassword) {
         const challenge = await this.auth.getChallenge();
@@ -5069,11 +5552,12 @@ var init_client = __esm({
         const tokens = await this.auth.getAccessToken(authToken);
         this.authManager.setAccessToken(tokens.accessToken.token);
         this.authManager.setRefreshToken(tokens.refreshToken.token);
+        return { clientIp: challenge.clientIp };
       }
       async loginWithPkcs12(p12, password, nip) {
         const { Pkcs12Loader: Pkcs12Loader2 } = await Promise.resolve().then(() => (init_pkcs12_loader(), pkcs12_loader_exports));
         const { certificatePem, privateKeyPem } = Pkcs12Loader2.load(p12, password);
-        await this.loginWithCertificate(certificatePem, privateKeyPem, nip);
+        return this.loginWithCertificate(certificatePem, privateKeyPem, nip);
       }
       async awaitAuthReady(referenceNumber, authToken) {
         for (let i = 0; i < 30; i++) {
@@ -5125,6 +5609,7 @@ var PERMISSION_DESCRIPTION_MAX_LENGTH = 256;
 init_xml_to_object();
 init_schema_registry();
 init_invoice_validator();
+init_char_validity();
 
 // src/models/index.ts
 init_document_structures();
@@ -5816,51 +6301,7 @@ function escapeXml2(str) {
 
 // src/utils/index.ts
 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
 import crypto6 from "crypto";
@@ -6056,6 +6497,524 @@ function nonEmptyString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 
+// src/xml/xml-engine.ts
+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
+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
+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_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_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();
@@ -6784,10 +7743,13 @@ export {
   CertificateService,
   CryptographyService,
   DEFAULT_FORM_CODE,
+  DISCOURAGED_UNICODE_RANGES,
   DefaultAuthManager,
   ENFORCE_XADES_COMPLIANCE,
+  ETD_NAMESPACE,
   EntityPermissionGrantBuilder,
   Environment,
+  FAKTURA_NAMESPACE,
   FORM_CODES,
   FORM_CODE_KEYS,
   FileHwmStore,
@@ -6804,9 +7766,13 @@ export {
   KSEF_FEATURE_HEADER,
   KSeFApiError,
   KSeFAuthStatusError,
+  KSeFBadRequestError,
+  KSeFBatchTimeoutError,
   KSeFClient,
   KSeFError,
+  KSeFErrorCode,
   KSeFForbiddenError,
+  KSeFGoneError,
   KSeFRateLimitError,
   KSeFSessionExpiredError,
   KSeFUnauthorizedError,
@@ -6818,8 +7784,10 @@ export {
   LimitsService,
   Nip,
   NipVatUe,
+  ORDER_MAP,
   OfflineInvoiceWorkflow,
   OnlineSessionService,
+  PEF_NAMESPACE,
   PERMISSION_DESCRIPTION_MAX_LENGTH,
   PERMISSION_DESCRIPTION_MIN_LENGTH,
   PeppolId,
@@ -6849,14 +7817,21 @@ export {
   VatUe,
   VerificationLinkService,
   addBusinessDays,
+  assertNever,
   authenticateWithCertificate,
   authenticateWithExternalSignature,
   authenticateWithPkcs12,
   authenticateWithToken,
   batchValidationDetails,
+  buildFakturaXml,
+  buildPefXml,
+  buildRawXmlString,
   buildUnsignedAuthTokenRequestXml,
+  buildXml,
+  buildXmlFromObject,
   calculateBackoff,
   calculateOfflineDeadline,
+  comparePKey,
   createZip,
   decodeJwtPayload,
   deduplicateByKsefNumber,
@@ -6875,6 +7850,9 @@ export {
   getTimeUntilDeadline,
   incrementalExportAndDownload,
   isExpired,
+  isFakturaInput,
+  isFormCodeShape,
+  isPefUblDocumentInput,
   isPolishHoliday,
   isRetryableError,
   isRetryableStatus,
@@ -6896,16 +7874,21 @@ export {
   nextBusinessDay,
   openOnlineSession,
   openSendAndClose,
+  orderXmlObject,
   parseFormCode,
   parseKSeFTokenContext,
   parseRetryAfter,
   parseUpoXml,
+  parseXml,
   pollUntil,
   resolveOptions,
   resumeOnlineSession,
   runWithConcurrency,
+  serializeInvoiceXml,
   sha256Base642 as sha256Base64,
   sleep,
+  stripBom,
+  toKodFormularza,
   unzip,
   updateContinuationPoint,
   uploadBatch,
@@ -6915,6 +7898,7 @@ export {
   validate,
   validateBatch,
   validateBusinessRules,
+  validateCharValidity,
   validateFormCodeForSession,
   validatePresignedUrl,
   validateSchema,