ksef-client-ts 0.1.1 → 0.3.0

package/README.md

@@ -2,18 +2,18 @@
 
 TypeScript client for the Polish National e-Invoice System (KSeF) API v2.
 
-**[Documentation](https://flopsstuff.github.io/ksef-client-ts)**
+**[Documentation](https://flopsstuff.github.io/ksef-client-ts)** · **[NPM](https://www.npmjs.com/package/ksef-client-ts)**
 
 ## Features
 
-- **Complete API coverage** — (KSeF) API v2.3.0 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+**.
@@ -82,12 +82,16 @@ yarn test         # Run all tests (vitest)
 - [ksef-client-csharp](https://github.com/CIRFMF/ksef-client-csharp) — official C# reference client
 - [ksef-client-java](https://github.com/CIRFMF/ksef-client-java) — official Java reference client
 
-## Status
-
-[![Unit Tests](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/test.yml/badge.svg)](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/test.yml)
-
-![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Fl0p/1558034ac67a11548c7f8f0c05e8d4c0/raw/ksef-client-ts-coverage.json&cacheSeconds=300)
-
 ## License
 
 [MIT](LICENSE)
+
+---
+
+[![Tests](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/Flopsstuff/ksef-client-ts/actions/workflows/ci.yml)
+![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Fl0p/1558034ac67a11548c7f8f0c05e8d4c0/raw/ksef-client-ts-coverage.json&cacheSeconds=300)
+![NPM Version](https://img.shields.io/npm/v/ksef-client-ts)
+![NPM Downloads](https://img.shields.io/npm/dm/ksef-client-ts)
+![GitHub Stars](https://img.shields.io/github/stars/Flopsstuff/ksef-client-ts)
+![GitHub Forks](https://img.shields.io/github/forks/Flopsstuff/ksef-client-ts)
+![GitHub License](https://img.shields.io/github/license/Flopsstuff/ksef-client-ts)

package/dist/cli.js

@@ -5179,7 +5179,8 @@ function resolveOptions(options = {}) {
     lighthouseUrl: options.lighthouseUrl ?? env.lighthouseUrl,
     apiVersion: options.apiVersion ?? DEFAULT_API_VERSION,
     timeout: options.timeout ?? DEFAULT_TIMEOUT,
-    customHeaders: options.customHeaders ?? {}
+    customHeaders: options.customHeaders ?? {},
+    environmentName: options.environment ?? (options.baseUrl ? void 0 : "TEST")
   };
 }
 
@@ -5590,6 +5591,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;
@@ -5794,8 +5799,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;
   }
@@ -5853,7 +5861,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;
@@ -5878,7 +5886,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;
@@ -6303,82 +6311,108 @@ var PeppolService = class {
 // src/services/test-data.ts
 var TestDataService = class {
   restClient;
-  constructor(restClient) {
+  environmentName;
+  constructor(restClient, environmentName) {
     this.restClient = restClient;
+    this.environmentName = environmentName;
+  }
+  ensureTestEnvironment() {
+    if (this.environmentName && this.environmentName !== "TEST") {
+      throw new KSeFError(
+        `Test data APIs are only available on the TEST environment (current: ${this.environmentName})`
+      );
+    }
   }
   // Subject management
   async createSubject(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.createSubject).body(request);
     await this.restClient.executeVoid(req);
   }
   async removeSubject(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.removeSubject).body(request);
     await this.restClient.executeVoid(req);
   }
   // Person management
   async createPerson(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.createPerson).body(request);
     await this.restClient.executeVoid(req);
   }
   async removePerson(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.removePerson).body(request);
     await this.restClient.executeVoid(req);
   }
   // Permissions
   async grantPermissions(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.grantPerms).body(request);
     await this.restClient.executeVoid(req);
   }
   async revokePermissions(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.revokePerms).body(request);
     await this.restClient.executeVoid(req);
   }
   // Attachment permissions
   async enableAttachment(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.enableAttach).body(request);
     await this.restClient.executeVoid(req);
   }
   async disableAttachment(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.disableAttach).body(request);
     await this.restClient.executeVoid(req);
   }
   // Session limits
   async changeSessionLimits(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.changeSessionLimitsInCurrentContext).body(request);
     await this.restClient.executeVoid(req);
   }
   async restoreDefaultSessionLimits() {
+    this.ensureTestEnvironment();
     const req = RestRequest.delete(Routes.TestData.restoreDefaultSessionLimitsInCurrentContext);
     await this.restClient.executeVoid(req);
   }
   // Certificate limits
   async changeCertificatesLimit(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.changeCertificatesLimitInCurrentSubject).body(request);
     await this.restClient.executeVoid(req);
   }
   async restoreDefaultCertificatesLimit() {
+    this.ensureTestEnvironment();
     const req = RestRequest.delete(Routes.TestData.restoreDefaultCertificatesLimitInCurrentSubject);
     await this.restClient.executeVoid(req);
   }
   // Rate limits
   async setRateLimits(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.rateLimits).body(request);
     await this.restClient.executeVoid(req);
   }
   async restoreDefaultRateLimits() {
+    this.ensureTestEnvironment();
     const req = RestRequest.delete(Routes.TestData.rateLimits);
     await this.restClient.executeVoid(req);
   }
   async setProductionRateLimits() {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.productionRateLimits);
     await this.restClient.executeVoid(req);
   }
   // Context blocking
   async blockContext(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.blockContext).body(request);
     await this.restClient.executeVoid(req);
   }
   async unblockContext(request) {
+    this.ensureTestEnvironment();
     const req = RestRequest.post(Routes.TestData.unblockContext).body(request);
     await this.restClient.executeVoid(req);
   }
@@ -6755,7 +6789,7 @@ var KSeFClient = class {
     this.lighthouse = new LighthouseService(this.options);
     this.limits = new LimitsService(restClient);
     this.peppol = new PeppolService(restClient);
-    this.testData = new TestDataService(restClient);
+    this.testData = new TestDataService(restClient, this.options.environmentName);
     this.qr = new VerificationLinkService(this.options.baseQrUrl);
   }
   async loginWithToken(token, nip) {