ksef-client-ts

TypeScript client for the Polish National e-Invoice System (KSeF) API v2.

Documentation · NPM

Features

• Complete API coverage — KSeF API v2.3.0, types aligned with the official OpenAPI spec
• Full-featured CLI — ksef with 14 command groups for auth, sessions, invoices, batch upload, export, and more
• High-level workflows — auth, online/batch sessions, invoice export — full lifecycle in a single call
• Built-in cryptography — AES-256-CBC, RSA-OAEP, ECDH, XAdES-B signatures, self-signed certs (Node crypto)
• External signing — HSM, EPUAP, and smart card authentication via callback-based signing
• Automatic token management — AuthManager: token injection, 401 refresh with dedup
• Streaming batch uploads — constant-memory batch upload via Web Streams API with ZIP bomb protection
• Incremental export — HWM-based paginated export with file-based state persistence
• Multiple document structures — FA, PEF, PEF_KOR, FA_RR with typed FormCode constants and UPO parsing
• Invoice XML validation — three-level client-side validation (well-formedness, XSD schema via Zod, NIP/PESEL checksums, future date rejection) with auto-detection for all 6 invoice types
• Typed errors & fluent builders — KSeFError hierarchy (401, 403, 429, validation) and request builders
• Comprehensive test coverage — unit + E2E tests across HTTP, crypto, services, workflows; CI on every change
• Interactive setup wizard — ksef setup guides through environment selection, authentication, and token generation in one flow
• Zero HTTP dependencies — native fetch (Node 18+); dual ESM/CJS via tsup

Requires Node.js 18+.

Install

Install CLI globally:

npm i -g ksef-client-ts
ksef --help

Install in a project:

# 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:

git clone https://github.com/Flopsstuff/ksef-client-ts.git
cd ksef-client-ts
yarn install && yarn build

import { KSeFClient } from 'ksef-client-ts';

const client = new KSeFClient({ environment: 'TEST' });
await client.crypto.init();

const challenge = await client.auth.getChallenge();
// ... authenticate, open session, send invoices

ksef auth login --token "$KSEF_TOKEN" --nip "$KSEF_NIP"
ksef session open
ksef invoice send invoice.xml
ksef session close

See the documentation for full usage, API reference, and CLI reference.

Development

yarn install      # Install dependencies (yarn 4.x via Corepack)
yarn build        # Build ESM + CJS + DTS via tsup
yarn lint         # Type-check (tsc --noEmit)
yarn test         # Run all tests (vitest)

Related

• KSeF Web Portal — official KSeF web application (token management, permissions, invoices)
• KSeF official docs — official documentation (Polish)
• KSeF docs translated — translated documentation (EN/RU/UK)
• ksef-client-csharp — official C# reference client
• ksef-client-java — official Java reference client

License

MIT