KSeF

KSeF client project currently centered on a Terminal UI, with a Rails Web UI being rebuilt and expanded.

Project Status

• Terminal UI based on RatatuiRuby for previewing invoices
• Rails Web UI is in progress and will become a first-class interface.
• Core KSeF client/domain logic is shared so both interfaces can evolve together.

Current Capabilities (TUI)

• Token-based authentication with KSeF API.
• Interactive invoice list and detail view.
• Debug/API inspection views.
• Profile-based configuration from ~/.ksef.yml.

Current Capabilities (Web)

• Profile-based sign-in and session handling.
• Invoice list and invoice detail pages.
• XML download for invoice source documents.
• Browser-side PDF generation from invoice XML on the invoice detail page.

Web PDF Notes

• The PDF download button in the web UI uses the official KSeF browser-side generator.
• The generated bundle is vendored in vendor/javascript/ksef_pdf_generator.js and pinned through importmap.
• No extra JavaScript build step is required in app development to use this PDF feature.

Requirements

• Ruby 4.0.1
• Access to KSeF API credentials (NIP + token).

Configuration

Create ~/.ksef.yml:

settings:
  locale: "en"
  default_host: "api.ksef.mf.gov.pl"
  max_retries: 3
  open_timeout: 10
  read_timeout: 15
  write_timeout: 10

default_profile: "Production"
profiles:
  - name: "Production"
    nip: "1111111111"
    token: "prod-token"
  - name: "Test"
    nip: "2222222222"
    token: "test-token"
    host: "api-test.ksef.mf.gov.pl"

Run TUI

From project root:

rake tui

You can also pass profile:

rake "tui[Test]"

or:

PROFILE=Test rake tui

If your shell does not auto-activate bundle context, use bundle exec rake tui.

Keyboard Shortcuts

Key	Action
c	Connect to KSeF
r	Refresh invoices
p	Profile selector
Shift+D	Debug view
L	Toggle locale
Enter	Open details
Esc	Back
q	Quit

Screenshots

Main View (Disconnected)

Invoice List (Connected)

Profile Selector

Invoice Detail

Debug View

Tests

Run full suite:

bin/rails test

Roadmap

• Complete Rails Web UI
• Add notifications for new invoices
  • email notifications
  • SMS notifications
• Add background jobs for monitoring, alerts, and periodic sync.

License

MIT - see LICENSE.