---
name: invoice-checker
description: >
  Pull and check invoices from KSeF (Krajowy System e-Faktur) for a selected period.
  For every new invoice checks whether the contractor is in the contractors file and
  whether the contractor's bank account is on the MF white list (Biała lista podatników VAT).
  TRIGGER this skill automatically whenever the user mentions pulling, checking, reviewing,
  or auditing invoices from KSeF — especially when they mention a period like last week,
  last month, or a date range. Trigger phrases include: "check invoices", "pull invoices",
  "invoice audit", "KSeF invoices", "check KSeF", "white list check", "biała lista".
---

# Invoice Checker

Use this skill when someone needs to download purchase invoices from KSeF for a given period, verify contractors, and check bank accounts against the MF white list.

**In Claude Code, you run the full pipeline automatically.** The user provides a period — you handle everything else.

## Prerequisites

This skill reads credentials from the `.env` file in the **project root** (the working directory where Claude Code is open). The same file is shared with the timesheet-checker skill — just add the KSEF variables to it.

Add these lines to your `.env`:

```env
# KSeF — Invoice Checker
KSEF_NIP=          # 10-digit company NIP, no dashes
KSEF_TOKEN=        # Authorization token from KSeF portal → Zarządzanie tokenami
KSEF_ENV=prod      # "test" for sandbox, "prod" for production
```

The variable reference:

| Variable | What it is | Where to get it |
|---|---|---|
| `KSEF_NIP` | Company NIP (10 digits, no dashes) | Your company's tax ID |
| `KSEF_TOKEN` | KSeF authorization token | KSeF portal → Zarządzanie tokenami |
| `KSEF_ENV` | `test` or `prod` | Use `test` for the sandbox, `prod` for production |

The script also requires the `cryptography` Python package:

```bash
pip3 install cryptography
```

## Setup

Determine `SKILL_DIR` from the location of this file. Set the output directory to `./invoices-output/` in the current working directory. Create it if it does not exist.

## Load First

Read these reference files:

1. The contractors config — check `./contractors.md` in the current working directory first; if not present, fall back to `{SKILL_DIR}/references/contractors.md`. Tell the user which one is being used.
2. `{SKILL_DIR}/references/output-format.md` — the structure of `invoices_data.json` and the final report.

## Extracting the period

The user may express the period in various ways. Convert to `YYYY-MM-DD:YYYY-MM-DD` before running:

| User says | Start | End |
|---|---|---|
| "last week" | Last Monday | Last Friday |
| "last month" | 1st of previous month | Last day of previous month |
| "this month" | 1st of current month | Yesterday |
| "this year" | 1 January of current year | Yesterday |
| "June", "June 2026" | 2026-06-01 | 2026-06-30 |
| Explicit dates | As given | As given |

If the user has not specified a period, ask: "Który okres sprawdzić? (np. zeszły tydzień, zeszły miesiąc, zakres dat)"

## Workflow

**Step 1 — Fetch and check.** Run this command:

```bash
python3 {SKILL_DIR}/scripts/preprocess.py \
  --period {YYYY-MM-DD:YYYY-MM-DD} \
  --contractors {contractors_path} \
  --output-dir ./invoices-output
```

This authenticates with KSeF, downloads all purchase invoices for the period, compares against `invoices_cache.json` to identify new invoices, checks each contractor against `contractors.md`, checks bank accounts against the MF white list, and writes `invoices_data.json` to `./invoices-output/`.

**Step 2 — Interpret.** Read `./invoices-output/invoices_data.json`. Note:
- **New vs known invoices** — only new ones (not in cache) are actively checked.
- **Unknown contractors** — contractors not in `contractors.md`. Show these to the user and ask if they should be added.
- **White list failures** — bank accounts not found on the white list. These are high priority — flag them prominently.
- **White list errors** — API call failed (network issue, etc.). Note that these could not be verified.

**Step 3 — Generate report.**

```bash
python3 {SKILL_DIR}/scripts/postprocess.py \
  --data ./invoices-output/invoices_data.json \
  --output-dir ./invoices-output
```

This writes `invoices_report.md`.

**Step 4 — Present results.** Show the user:
- Summary block: total invoices, new invoices, contractor status, white list status.
- Table of new invoices with contractor and white list status.
- Any white list failures or unknown contractors — highlighted prominently.
- "Full report saved to `./invoices-output/invoices_report.md`."

**Step 5 — Handle unknown contractors.** If the user confirms any unknown contractors should be added, add them to `contractors.md`. Use the NIP and name from the invoice; leave `bank_accounts` blank if they want to fill it in later, or populate it from the invoice bank account.

## Guardrails

- Never fabricate invoice data. All data comes from KSeF.
- White list checks are always performed against the invoice issue date (not today).
- If `KSEF_NIP` or `KSEF_TOKEN` are not set, stop and ask the user for them.
- If the `cryptography` package is missing, tell the user to run `pip3 install cryptography` and stop.
- If any script step fails, show the error and stop. Do not proceed with partial output.
- Always terminate the KSeF session even if an error occurs (the script handles this internally).