createKsefnik()

Funkcja createKsefnik() to jedyny punkt wejścia do SDK. Tworzy instancję Ksefnik z pięcioma namespace’ami.

Sygnatura

function createKsefnik(opts: CreateKsefnikOpts): Ksefnik

CreateKsefnikOpts

Pole	Typ	Wymagane	Opis
`config`	`KsefnikConfig`	tak	Konfiguracja SDK (NIP, środowisko, token)
`adapter`	`KsefAdapter`	nie	Adapter do komunikacji z KSeF API
`storage`	`Storage`	nie	Implementacja storage (domyślnie `InMemoryStorage`)

Namespace’y instancji Ksefnik

invoices

Pobieranie, wysyłanie i listowanie faktur z KSeF.

bank

Import i listowanie transakcji bankowych.

reconciliation

Uruchamianie pipeline uzgadniania faktur z transakcjami.

validation

Walidacja faktur za pomocą 20 wbudowanych reguł.

plugins

Rejestracja, ładowanie i listowanie pluginów.

Przykłady

Minimalna konfiguracja

import { createKsefnik } from '@ksefnik/core'

const ksefnik = createKsefnik({
  config: {
    nip: '1234567890',
    environment: 'test',
  },
})

// Gotowe do użycia — InMemoryStorage, bez adaptera KSeF
const report = await ksefnik.validation.validate(invoices)

Z symulatorem KSeF

import { createKsefnik } from '@ksefnik/core'
import { createSimulatorAdapter } from '@ksefnik/simulator'

const ksefnik = createKsefnik({
  config: {
    nip: '1234567890',
    environment: 'test',
  },
  adapter: createSimulatorAdapter({ scenario: 'happy-path' }),
})

// Symulator odpowiada jak prawdziwy KSeF — offline
const invoices = await ksefnik.invoices.fetch({
  from: '2025-01-01',
  to: '2025-12-31',
})

Z SQLite storage

import { createKsefnik } from '@ksefnik/core'

const ksefnik = createKsefnik({
  config: {
    nip: '1234567890',
    environment: 'production',
    token: process.env.KSEFNIK_TOKEN,
    storage: 'sqlite',
    sqlitePath: './data/ksefnik.db',
  },
})

// Dane persystowane między uruchomieniami
const invoices = await ksefnik.invoices.list()

Z własnym adapterem

import { createKsefnik } from '@ksefnik/core'
import type { KsefAdapter } from '@ksefnik/shared'

const myAdapter: KsefAdapter = {
  async fetchInvoices(opts) {
    const res = await fetch(`https://my-api.pl/invoices?from=${opts.from}&to=${opts.to}`)
    return res.json()
  },
  async sendInvoice(input) {
    const res = await fetch('https://my-api.pl/invoices', {
      method: 'POST',
      body: input.xml,
    })
    return res.json()
  },
  async getUpo(ref) {
    const res = await fetch(`https://my-api.pl/upo/${ref}`)
    return res.json()
  },
}

const ksefnik = createKsefnik({
  config: { nip: '1234567890', environment: 'production' },
  adapter: myAdapter,
})

Z automatycznym ładowaniem pluginów

const ksefnik = createKsefnik({
  config: {
    nip: '1234567890',
    environment: 'production',
    plugins: ['@ksefnik/pro-reconciliation', '@ksefnik/pro-analytics'],
  },
})

// Pluginy są ładowane leniwie — brak pakietu = brak feature (bez błędu)
for (const name of ksefnik.config?.plugins ?? []) {
  await ksefnik.plugins.load(name)
}