# KSeF Downloader

Pobiera faktury z KSeF i zapisuje je jako XML, PDF lub Markdown. Dostępny jako CLI,
serwer MCP i biblioteka TypeScript. Wymaga Node.js 22.14+.

Obsługuje logowanie certyfikatem KSeF, automatyczne odświeżanie sesji i wznawianie
eksportu. Oryginalny XML jest zachowywany także przy wyborze PDF lub Markdown.

## Szybki start

```sh
npx -y --prefer-online ksef-downloader@latest --env-file .env download --from 2026-10-01 --to 2026-10-17 --out ./faktury --formats xml,pdf,md
```

Polecenie uruchamia najnowsze wydanie. Aby wybrać konkretną wersję, zastąp `@latest`
jej numerem, np. `@0.1.0`.

## Konfiguracja

Ustaw zmienne środowiskowe lub zapisz je w pliku wskazanym przez `--env-file`:

```dotenv
KSEF_ENVIRONMENT=test
KSEF_NIP=YOUR_COMPANY_NIP
KSEF_CERT_PATH=C:/certificates/authentication.crt
KSEF_KEY_PATH=C:/certificates/authentication.key
KSEF_KEY_PASSWORD=YOUR_PRIVATE_KEY_PASSWORD
```

Środowiska: `test` (domyślne), `demo`, `production`. Logowanie wymaga certyfikatu
uwierzytelniającego, odpowiadającego mu klucza PEM (RSA lub EC) i uprawnień do podanego NIP.
Plik z hasłem przechowuj poza repozytorium.

## CLI

```sh
# Sprawdzenie logowania
npx -y --prefer-online ksef-downloader@latest --env-file .env auth-check

# Lista faktur kosztowych
npx -y --prefer-online ksef-downloader@latest --env-file .env list --from 2026-10-01 --to 2026-10-17

# Pobranie XML i wizualizacji
npx -y --prefer-online ksef-downloader@latest --env-file .env download --from 2026-10-01 --to 2026-10-17 --out ./faktury --formats xml,pdf,md

# Konwersja lokalnego XML
npx -y --prefer-online ksef-downloader@latest render faktura.xml --out faktura.pdf --format pdf
```

Domyślnie pobierane są faktury kosztowe. Opcja `--subject sales` wybiera sprzedażowe.
Filtry: `--seller-nip`, `--invoice-number`, `--date-type` (`Issue`, `Invoicing`,
`PermanentStorage`). Daty bez godziny obejmują cały dzień w strefie `Europe/Warsaw`.
Przy podawaniu godziny dodaj offset, np. `2026-10-01T12:00:00+02:00`.

| Format | Zawartość                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------------ |
| XML    | Oryginalny dokument z KSeF, zapisywany przy każdym eksporcie                                                       |
| PDF    | Wizualizacja oparta na generatorze MF, przez pakiet [`@mdab25/ksef-pdf`](https://github.com/mdabrowski25/ksef-pdf) |
| MD     | Dane stron, daty, pozycje, kwota ogółem i wybrane informacje o płatności                                           |

Nazwy plików odpowiadają numerom KSeF. Przy ponownym eksporcie program sprawdza
istniejące pliki i pobiera brakujące. [Formaty, limity i wznawianie eksportu](docs/export.md).

## MCP

Dodaj serwer do konfiguracji klienta MCP:

```json
{
  "mcpServers": {
    "ksef-downloader": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "ksef-downloader@latest", "mcp"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_NIP": "YOUR_COMPANY_NIP",
        "KSEF_CERT_PATH": "C:/certificates/authentication.crt",
        "KSEF_KEY_PATH": "C:/certificates/authentication.key",
        "KSEF_KEY_PASSWORD": "YOUR_PRIVATE_KEY_PASSWORD"
      }
    }
  }
}
```

Podaj bezwzględne ścieżki certyfikatu i klucza. Na Windows można użyć zapisu
`C:/certificates/authentication.crt`. Jeśli klient wymaga pełnej ścieżki do programu,
wskaż `npx.cmd` z instalacji Node.js. Aktualizacja paczki jest uwzględniana po restarcie MCP.

| Narzędzie              | Działanie                                                     |
| ---------------------- | ------------------------------------------------------------- |
| `list_invoices`        | Pobiera pełną listę metadanych dla wybranego okresu i filtrów |
| `download_invoice_xml` | Pobiera pojedynczy XML według numeru KSeF                     |
| `export_invoices`      | Zapisuje faktury we wskazanym folderze i formatach            |

## Biblioteka

```ts
import { KsefClient, KsefDownloader, settingsFromEnv, invoicePdf } from 'ksef-downloader';

const downloader = new KsefDownloader(new KsefClient(settingsFromEnv()), { pdf: invoicePdf });
const result = await downloader.export({
  from: '2026-10-01',
  to: '2026-10-17',
  directory: './faktury',
  formats: ['xml', 'pdf', 'md'],
});
```

`KsefClient.list()` zwraca metadane, a `KsefClient.download()` oryginalne bajty XML.
Funkcje `invoiceMarkdown()` i `invoicePdf()` przyjmują również lokalne dokumenty.

## Rozwój

```sh
npm ci
npm run dev -- --help
npm run check
```

CI uruchamia testy na Windows i Linux dla Node.js 22 i 24.
[Wydawanie wersji](docs/releases.md).

## Licencja

[MIT](LICENSE). Licencje głównych zależności opisano w [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).