Session Manager

Problem

Sesja KSeF ma ograniczony czas zycia. Jesli wygasnie w trakcie operacji, dostaniesz blad autoryzacji. Reczne sledzenie czasu wygasniecia jest klopliwe.

Rozwiazanie: SessionManager

SessionManager automatycznie inicjalizuje i odnawia sesje:

import { SessionManager } from '@ksefnik/core'

const sessions = new SessionManager(client, config, {
  renewThresholdMs: 60_000, // odnow 60s przed wygasnieciem
})

// Zawsze zwraca aktywna sesje
const session = await sessions.ensure()

API

class SessionManager {
  constructor(
    client: KsefClient,
    config: KsefClientConfig,
    opts?: SessionManagerOptions,
  )

  ensure(): Promise<KsefSessionState>    // pobierz lub odnow sesje
  close(): Promise<void>                 // zamknij sesje
  get current(): KsefSessionState | null // biezaca sesja
  get isActive(): boolean                // czy sesja jest aktywna
}

Metoda	Opis
`ensure()`	Zwraca aktualna sesje. Jesli nie istnieje lub wkrotce wygasnie — tworzy nowa.
`close()`	Zamyka sesje i zwalnia token. Bezpieczna do wielokrotnego wywolania.
`current`	Getter — biezacy stan sesji lub `null`.
`isActive`	Getter — `true` jesli sesja istnieje i nie wygasla.

Opcje

interface SessionManagerOptions {
  renewThresholdMs?: number  // domyslnie 60 000 ms (60 sekund)
}

renewThresholdMs okresla, ile milisekund przed wygasnieciem sesja zostanie odnowiona. Domyslnie 60 sekund — wystarczajaco dlugo, zeby nowa sesja zdazyla sie zainicjalizowac.

Flow: ensure()

Sprawdz czy sesja istnieje
Jesli nie — zainicjalizuj nowa i zwroc
Jesli tak — sprawdz czas do wygasniecia
Jesli czas < renewThresholdMs — zamknij stara, zainicjalizuj nowa
Zwroc aktualna sesje

async ensure(): Promise<KsefSessionState> {
  if (!this.session) {
    this.session = await this.client.initSession(this.config)
    return this.session
  }

  const timeLeft = this.session.expiresAt.getTime() - Date.now()
  if (timeLeft < this.renewThresholdMs) {
    await this.close()
    this.session = await this.client.initSession(this.config)
  }

  return this.session
}

Przyklad: dlugotrwaly skrypt

import { SessionManager, KsefAdapterImpl } from '@ksefnik/core'

const sessions = new SessionManager(client, {
  nip: '5213456784',
  environment: 'production',
  token: process.env.KSEF_TOKEN!,
}, {
  renewThresholdMs: 120_000, // 2 minuty zapasu
})

async function processMonthlyInvoices() {
  // ensure() zainicjalizuje sesje przy pierwszym wywolaniu
  const session = await sessions.ensure()

  for (const month of months) {
    // ensure() automatycznie odnowi sesje jesli trzeba
    await sessions.ensure()

    const invoices = await client.fetchInvoices({
      token: sessions.current!.token,
      dateFrom: month.from,
      dateTo: month.to,
    })
    // ... przetwarzanie
  }

  // Zamknij sesje po zakonczeniu
  await sessions.close()
}

Integracja z adapterem

const sessions = new SessionManager(client, config)
const adapter = new KsefAdapterImpl(client, config)

// Przed kazdym zapytaniem upewnij sie, ze sesja jest aktywna
await sessions.ensure()
const invoices = await adapter.fetchInvoices({ from: '2026-03-01', to: '2026-03-31' })