ksef-client-ts 0.1.0 → 0.2.0

package/README.md

@@ -6,17 +6,40 @@ TypeScript client for the Polish National e-Invoice System (KSeF) API v2.
 
 ## Features
 
-- **Complete API coverage** — auth, sessions, invoices, permissions, tokens, certificates, QR codes, and more
+- **Complete API coverage** — KSeF API v2.3.0, types aligned with the official OpenAPI spec
 - **Full-featured CLI** — `ksef` with many command groups and subcommands for day-to-day KSeF workflows
 - **Full documentation** — VitePress site: Quick Start, API reference, OpenAPI spec
-- **OpenAPI aligned** — types checked against the official KSeF spec; full spec and domain chunks in `docs/`
 - **Comprehensive test coverage** — Vitest across HTTP, crypto, services, builders; CI on every change
 - **Zero HTTP dependencies** — native `fetch` (Node 18+); dual ESM/CJS via tsup
 - **Built-in cryptography** — AES-256-CBC, RSA-OAEP, ECDH, XAdES-B, self-signed certs (Node crypto)
 - **Automatic token management** — AuthManager: token injection, 401 refresh with dedup, `loginWithToken` / `loginWithCertificate`
+- **High-level workflows** — orchestration functions for auth, online/batch sessions, invoice export with polling and decryption
 - **Typed errors & fluent builders** — `KSeFError` hierarchy (401, 403, 429, validation) and request builders
 
-Requires **Node.js 18+**. Package not yet published — clone and build locally:
+Requires **Node.js 18+**.
+
+## Install
+
+Install CLI globally:
+
+```bash
+npm i -g ksef-client-ts
+ksef --help
+```
+
+Install in a project:
+
+```bash
+# Choose one package manager:
+# npm
+npm i ksef-client-ts
+# Yarn
+yarn add ksef-client-ts
+# pnpm
+pnpm add ksef-client-ts
+```
+
+For local development, clone and build:
 
 ```bash
 git clone https://github.com/Flopsstuff/ksef-client-ts.git

package/dist/cli.js

@@ -4789,6 +4789,62 @@ var init_signature_service = __esm({
   }
 });
 
+// src/crypto/pkcs12-loader.ts
+var pkcs12_loader_exports = {};
+__export(pkcs12_loader_exports, {
+  Pkcs12Loader: () => Pkcs12Loader
+});
+import forge from "node-forge";
+var Pkcs12Loader;
+var init_pkcs12_loader = __esm({
+  "src/crypto/pkcs12-loader.ts"() {
+    "use strict";
+    Pkcs12Loader = class {
+      static load(p12, password) {
+        const { pki, pkcs12, asn1 } = forge;
+        const p12Der = Buffer.from(p12).toString("binary");
+        const p12Asn1 = asn1.fromDer(p12Der);
+        const p12Parsed = pkcs12.pkcs12FromAsn1(p12Asn1, password);
+        const certBagType = pki.oids.certBag;
+        const certBags = p12Parsed.getBags({ bagType: certBagType });
+        const certs = certBags[certBagType];
+        if (!certs || certs.length === 0) {
+          throw new Error("PKCS#12 file does not contain a certificate.");
+        }
+        const shroudedType = pki.oids.pkcs8ShroudedKeyBag;
+        let keyBags = p12Parsed.getBags({ bagType: shroudedType });
+        let keys = keyBags[shroudedType];
+        if (!keys || keys.length === 0) {
+          const plainType = pki.oids.keyBag;
+          keyBags = p12Parsed.getBags({ bagType: plainType });
+          keys = keyBags[plainType];
+        }
+        if (!keys || keys.length === 0) {
+          throw new Error("PKCS#12 file does not contain a private key.");
+        }
+        const cert = certs[0].cert;
+        const key = keys[0].key;
+        if (!cert) {
+          throw new Error("PKCS#12 certificate bag is empty.");
+        }
+        if (!key) {
+          throw new Error("PKCS#12 key bag is empty.");
+        }
+        const certificatePem = pki.certificateToPem(cert);
+        let privateKeyPem;
+        try {
+          privateKeyPem = pki.privateKeyToPem(key);
+        } catch {
+          throw new Error(
+            "Failed to export private key from PKCS#12 to PEM. This can happen with EC keys. Use separate --cert and --key PEM files instead."
+          );
+        }
+        return { certificatePem, privateKeyPem };
+      }
+    };
+  }
+});
+
 // src/cli/index.ts
 import { defineCommand as defineCommand15, runMain } from "citty";
 
@@ -4804,7 +4860,7 @@ import * as os from "os";
 var ENV_MAP = {
   test: "TEST",
   demo: "DEMO",
-  prod: "PRD"
+  prod: "PROD"
 };
 function toEnvironmentName(env) {
   return ENV_MAP[env];
@@ -5105,7 +5161,7 @@ var Environment = {
     qrUrl: "https://qr-demo.ksef.mf.gov.pl",
     lighthouseUrl: ""
   },
-  PRD: {
+  PROD: {
     apiUrl: "https://api.ksef.mf.gov.pl",
     qrUrl: "https://qr.ksef.mf.gov.pl",
     lighthouseUrl: "https://api-latarnia.ksef.mf.gov.pl"
@@ -5313,6 +5369,10 @@ var RestClient = class {
     const body = await response.json();
     return { body, headers: response.headers, statusCode: response.status };
   }
+  async executeVoid(request) {
+    const response = await this.sendRequest(request);
+    await this.ensureSuccess(response);
+  }
   async executeRaw(request) {
     const response = await this.sendRequest(request);
     await this.ensureSuccess(response);
@@ -5530,6 +5590,10 @@ var DefaultAuthManager = class {
   }
 };
 
+// src/http/ksef-feature.ts
+var KSEF_FEATURE_HEADER = "X-KSeF-Feature";
+var ENFORCE_XADES_COMPLIANCE = "enforce-xades-compliance";
+
 // src/http/rest-request.ts
 var RestRequest = class _RestRequest {
   method;
@@ -5734,8 +5798,11 @@ var AuthService = class {
     const response = await this.restClient.execute(request);
     return response.body;
   }
-  async submitXadesAuthRequest(signedXml, verifyCertificateChain = false) {
+  async submitXadesAuthRequest(signedXml, verifyCertificateChain = false, enforceXadesCompliance = false) {
     const request = RestRequest.post(Routes.Authorization.xadesSignature).body(signedXml).header("Content-Type", "application/xml").query("verifyCertificateChain", String(verifyCertificateChain));
+    if (enforceXadesCompliance) {
+      request.header(KSEF_FEATURE_HEADER, ENFORCE_XADES_COMPLIANCE);
+    }
     const response = await this.restClient.execute(request);
     return response.body;
   }
@@ -5776,11 +5843,11 @@ var ActiveSessionsService = class {
   }
   async revokeCurrentSession() {
     const request = RestRequest.delete(Routes.ActiveSessions.currentSession);
-    await this.restClient.execute(request);
+    await this.restClient.executeVoid(request);
   }
   async revokeSession(sessionRef) {
     const request = RestRequest.delete(Routes.ActiveSessions.delete(sessionRef));
-    await this.restClient.execute(request);
+    await this.restClient.executeVoid(request);
   }
 };
 
@@ -5793,7 +5860,7 @@ var OnlineSessionService = class {
   async openSession(request, upoVersion) {
     const req = RestRequest.post(Routes.Sessions.Online.open).body(request);
     if (upoVersion) {
-      req.header("X-KSeF-Feature", upoVersion);
+      req.header(KSEF_FEATURE_HEADER, upoVersion);
     }
     const response = await this.restClient.execute(req);
     return response.body;
@@ -5805,7 +5872,7 @@ var OnlineSessionService = class {
   }
   async closeSession(sessionRef) {
     const req = RestRequest.post(Routes.Sessions.Online.close(sessionRef));
-    await this.restClient.execute(req);
+    await this.restClient.executeVoid(req);
   }
 };
 
@@ -5818,7 +5885,7 @@ var BatchSessionService = class {
   async openSession(request, upoVersion) {
     const req = RestRequest.post(Routes.Sessions.Batch.open).body(request);
     if (upoVersion) {
-      req.header("X-KSeF-Feature", upoVersion);
+      req.header(KSEF_FEATURE_HEADER, upoVersion);
     }
     const response = await this.restClient.execute(req);
     return response.body;
@@ -5846,7 +5913,7 @@ var BatchSessionService = class {
   }
   async closeSession(batchRef) {
     const req = RestRequest.post(Routes.Sessions.Batch.close(batchRef));
-    await this.restClient.execute(req);
+    await this.restClient.executeVoid(req);
   }
 };
 
@@ -6119,7 +6186,7 @@ var TokenService = class {
   }
   async revokeToken(ref) {
     const req = RestRequest.delete(Routes.Tokens.byReference(ref));
-    await this.restClient.execute(req);
+    await this.restClient.executeVoid(req);
   }
 };
 
@@ -6156,7 +6223,7 @@ var CertificateApiService = class {
   }
   async revoke(serialNumber, request) {
     const req = RestRequest.post(Routes.Certificates.revoke(serialNumber)).body(request);
-    await this.restClient.execute(req);
+    await this.restClient.executeVoid(req);
   }
   async query(request, pageSize, pageOffset) {
     const req = RestRequest.post(Routes.Certificates.query).body(request);
@@ -6249,95 +6316,78 @@ var TestDataService = class {
   // Subject management
   async createSubject(request) {
     const req = RestRequest.post(Routes.TestData.createSubject).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async removeSubject(request) {
     const req = RestRequest.post(Routes.TestData.removeSubject).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Person management
   async createPerson(request) {
     const req = RestRequest.post(Routes.TestData.createPerson).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async removePerson(request) {
     const req = RestRequest.post(Routes.TestData.removePerson).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Permissions
   async grantPermissions(request) {
     const req = RestRequest.post(Routes.TestData.grantPerms).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async revokePermissions(request) {
     const req = RestRequest.post(Routes.TestData.revokePerms).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Attachment permissions
   async enableAttachment(request) {
     const req = RestRequest.post(Routes.TestData.enableAttach).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async disableAttachment(request) {
     const req = RestRequest.post(Routes.TestData.disableAttach).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Session limits
   async changeSessionLimits(request) {
     const req = RestRequest.post(Routes.TestData.changeSessionLimitsInCurrentContext).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async restoreDefaultSessionLimits() {
     const req = RestRequest.delete(Routes.TestData.restoreDefaultSessionLimitsInCurrentContext);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Certificate limits
   async changeCertificatesLimit(request) {
     const req = RestRequest.post(Routes.TestData.changeCertificatesLimitInCurrentSubject).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async restoreDefaultCertificatesLimit() {
     const req = RestRequest.delete(Routes.TestData.restoreDefaultCertificatesLimitInCurrentSubject);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Rate limits
   async setRateLimits(request) {
     const req = RestRequest.post(Routes.TestData.rateLimits).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async restoreDefaultRateLimits() {
     const req = RestRequest.delete(Routes.TestData.rateLimits);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async setProductionRateLimits() {
     const req = RestRequest.post(Routes.TestData.productionRateLimits);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   // Context blocking
   async blockContext(request) {
     const req = RestRequest.post(Routes.TestData.blockContext).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
   async unblockContext(request) {
     const req = RestRequest.post(Routes.TestData.unblockContext).body(request);
-    const response = await this.restClient.execute(req);
-    return response.body;
+    await this.restClient.executeVoid(req);
   }
 };
 
@@ -6725,6 +6775,7 @@ var KSeFClient = class {
       encryptedToken: Buffer.from(encryptedToken).toString("base64")
     });
     const authToken = submitResult.authenticationToken.token;
+    await this.awaitAuthReady(submitResult.referenceNumber, authToken);
     const tokens = await this.auth.getAccessToken(authToken);
     this.authManager.setAccessToken(tokens.accessToken.token);
     this.authManager.setRefreshToken(tokens.refreshToken.token);
@@ -6736,10 +6787,26 @@ var KSeFClient = class {
     const signedXml = SignatureService2.sign(authRequestXml, certPem, keyPem);
     const submitResult = await this.auth.submitXadesAuthRequest(signedXml);
     const authToken = submitResult.authenticationToken.token;
+    await this.awaitAuthReady(submitResult.referenceNumber, authToken);
     const tokens = await this.auth.getAccessToken(authToken);
     this.authManager.setAccessToken(tokens.accessToken.token);
     this.authManager.setRefreshToken(tokens.refreshToken.token);
   }
+  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);
+  }
+  async awaitAuthReady(referenceNumber, authToken) {
+    for (let i = 0; i < 30; i++) {
+      const status6 = await this.auth.getAuthStatus(referenceNumber, authToken);
+      if (status6.status.code === 200) return;
+      if (status6.status.code !== 100) {
+        throw new Error(`Authentication failed with status ${status6.status.code}: ${status6.status.description}`);
+      }
+      await new Promise((r) => setTimeout(r, 1e3));
+    }
+  }
   async logout() {
     this.authManager.setAccessToken(void 0);
     this.authManager.setRefreshToken(void 0);
@@ -6901,6 +6968,8 @@ var login = defineCommand2({
     token: { type: "string", description: "KSeF authorization token" },
     cert: { type: "string", description: "Path to PEM certificate file (XAdES auth)" },
     key: { type: "string", description: "Path to PEM private key file (XAdES auth)" },
+    p12: { type: "string", description: "Path to PKCS#12 (.p12/.pfx) certificate file" },
+    "p12-password": { type: "string", description: "Password for the PKCS#12 file (default: empty)" },
     env: { type: "string", description: "Environment (test/demo/prod)" },
     json: { type: "boolean", description: "Output as JSON" },
     verbose: { type: "boolean", description: "Show HTTP request/response details" },
@@ -6918,13 +6987,17 @@ var login = defineCommand2({
       }
       if (args.token) {
         await client.loginWithToken(args.token, nip);
+      } else if (args.p12) {
+        const fs7 = await import("fs");
+        const p12Buffer = fs7.readFileSync(args.p12);
+        await client.loginWithPkcs12(p12Buffer, args["p12-password"] ?? "", nip);
       } else if (args.cert && args.key) {
         const fs7 = await import("fs");
         const certPem = fs7.readFileSync(args.cert, "utf-8");
         const keyPem = fs7.readFileSync(args.key, "utf-8");
         await client.loginWithCertificate(certPem, keyPem, nip);
       } else {
-        throw new Error("Provide --token or both --cert and --key for authentication.");
+        throw new Error("Provide --token, --p12, or both --cert and --key for authentication.");
       }
       const session = {
         accessToken: client.authManager.getAccessToken(),
@@ -9221,15 +9294,11 @@ function requireNonProd(globalOpts) {
     throw new Error("Test data commands are only available in test/demo environments.");
   }
 }
-function outputStatus(result, json) {
+function outputDone(json) {
   if (json) {
-    outputResult(result, { json: true });
+    outputResult({ status: "ok" }, { json: true });
   } else {
     outputSuccess("Done.");
-    outputKeyValue({
-      "Code": result.code,
-      "Description": result.description
-    }, { json: false });
   }
 }
 var createSubject = defineCommand10({
@@ -9254,8 +9323,8 @@ var createSubject = defineCommand10({
         description: args.description,
         createdDate: args["created-date"]
       };
-      const result = await createClient(globalOpts).testData.createSubject(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.createSubject(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9273,8 +9342,8 @@ var removeSubject = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const request = { subjectNip: args.nip };
-      const result = await createClient(globalOpts).testData.removeSubject(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.removeSubject(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9304,8 +9373,8 @@ var createPerson = defineCommand10({
         isDeceased: args.deceased,
         createdDate: args["created-date"]
       };
-      const result = await createClient(globalOpts).testData.createPerson(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.createPerson(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9323,8 +9392,8 @@ var removePerson = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const request = { nip: args.nip };
-      const result = await createClient(globalOpts).testData.removePerson(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.removePerson(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9354,8 +9423,8 @@ var grantPermissions = defineCommand10({
         },
         permissions
       };
-      const result = await createClient(globalOpts).testData.grantPermissions(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.grantPermissions(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9382,8 +9451,8 @@ var revokePermissions = defineCommand10({
           value: args.identifier
         }
       };
-      const result = await createClient(globalOpts).testData.revokePermissions(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.revokePermissions(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9401,8 +9470,8 @@ var enableAttachment = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const request = { nip: args.nip };
-      const result = await createClient(globalOpts).testData.enableAttachment(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.enableAttachment(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9424,8 +9493,8 @@ var disableAttachment = defineCommand10({
         nip: args.nip,
         expectedEndDate: args["end-date"]
       };
-      const result = await createClient(globalOpts).testData.disableAttachment(request);
-      outputStatus(result, args.json);
+      await createClient(globalOpts).testData.disableAttachment(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9461,8 +9530,8 @@ var changeSessionLimits = defineCommand10({
           maxInvoices: parseInt(args["batch-max-invoices"], 10)
         }
       };
-      const result = await client.testData.changeSessionLimits(request);
-      outputStatus(result, args.json);
+      await client.testData.changeSessionLimits(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9480,8 +9549,8 @@ var restoreSessionLimits = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const { client } = requireSession(globalOpts);
-      const result = await client.testData.restoreDefaultSessionLimits();
-      outputStatus(result, args.json);
+      await client.testData.restoreDefaultSessionLimits();
+      outputDone(args.json);
     });
   }
 });
@@ -9507,8 +9576,8 @@ var changeCertLimits = defineCommand10({
         enrollment: args["max-enrollments"] !== void 0 ? { maxEnrollments: parseInt(args["max-enrollments"], 10) } : void 0,
         certificate: args["max-certificates"] !== void 0 ? { maxCertificates: parseInt(args["max-certificates"], 10) } : void 0
       };
-      const result = await client.testData.changeCertificatesLimit(request);
-      outputStatus(result, args.json);
+      await client.testData.changeCertificatesLimit(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9526,8 +9595,8 @@ var restoreCertLimits = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const { client } = requireSession(globalOpts);
-      const result = await client.testData.restoreDefaultCertificatesLimit();
-      outputStatus(result, args.json);
+      await client.testData.restoreDefaultCertificatesLimit();
+      outputDone(args.json);
     });
   }
 });
@@ -9549,8 +9618,8 @@ var setRateLimits = defineCommand10({
       const request = {
         rateLimits: JSON.parse(args.limits)
       };
-      const result = await client.testData.setRateLimits(request);
-      outputStatus(result, args.json);
+      await client.testData.setRateLimits(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9568,8 +9637,8 @@ var restoreRateLimits = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const { client } = requireSession(globalOpts);
-      const result = await client.testData.restoreDefaultRateLimits();
-      outputStatus(result, args.json);
+      await client.testData.restoreDefaultRateLimits();
+      outputDone(args.json);
     });
   }
 });
@@ -9587,8 +9656,8 @@ var setProductionRateLimits = defineCommand10({
       const globalOpts = getGlobalOpts9(args);
       requireNonProd(globalOpts);
       const { client } = requireSession(globalOpts);
-      const result = await client.testData.setProductionRateLimits();
-      outputStatus(result, args.json);
+      await client.testData.setProductionRateLimits();
+      outputDone(args.json);
     });
   }
 });
@@ -9614,8 +9683,8 @@ var blockContext = defineCommand10({
           value: args["context-value"]
         }
       };
-      const result = await client.testData.blockContext(request);
-      outputStatus(result, args.json);
+      await client.testData.blockContext(request);
+      outputDone(args.json);
     });
   }
 });
@@ -9641,8 +9710,8 @@ var unblockContext = defineCommand10({
           value: args["context-value"]
         }
       };
-      const result = await client.testData.unblockContext(request);
-      outputStatus(result, args.json);
+      await client.testData.unblockContext(request);
+      outputDone(args.json);
     });
   }
 });