Hetzner Invoice
Turn Hetzner invoice PDFs into structured per-project spend data, surface it
as a finops cost report, and emit per-project Invoice Ninja expense candidates
written through the already-gated @shrug/invoiceninja.upsertExpenses
money-write.
The core parse/model/report/candidate path is SOURCE-AGNOSTIC via a pluggable
InvoiceSource adapter: FileSource (local path) and BytesSource (inline
base64) ship now, so the whole core is usable with no IMAP. An ImapSource
adapter is declared against the interface but GATED on pub-4
(@shrug/imap.fetchAttachment, which does not exist yet) -- it throws a clear
error until that method lands.
Methods
- parseInvoice -- parse PDF bytes (inline base64
bytesBase64, afilePath, or a resolved source) into theinvoicesresource: invoice number, customer id, date, billing period, detected ISO currency, per-project subtotals, and net/VAT/total figures. Uses a bundled pure-JS PDF text extractor (no OCR -- Hetzner invoices carry a real text layer) plus an anchor-based parser. - ingestFile -- parse a local PDF (
FileSource) intoinvoices. - buildExpenseCandidates -- build ONE BankTxn-shaped candidate PER PROJECT
(never a lump) plus the Mapping, from parsed invoice(s) passed via CEL.
Writes the
expenseCandidatesresource; NEVER POSTs. Feed its candidates + mapping to@shrug/invoiceninja.upsertExpenses.
USD-only expense sync (scope)
Expense sync is USD-ONLY. Invoice Ninja's isCandidate gate SILENTLY drops any
non-USD row, so buildExpenseCandidates runs a pre-write guard that THROWS
loudly on any detected non-USD currency AND on a mixed-currency batch -- a
visible failure rather than a silent zero-write. Run backfills PER CURRENCY.
Non-USD invoices are still VISIBLE as spend in the read-only hetzner-spend
report; only their expense sync is out of scope until isCandidate is extended.
Tenant attribution
A project named in projectClientMap is a passthrough (re-billed) line: its
candidate carries clientId, so the @shrug/invoiceninja mapTxnToExpense
passthrough writes client_id. Projects NOT in the map are Shrug-own opex and
carry no clientId. Per-project lines are always separate.
Writes
This model NEVER POSTs. The single audited money-write stays
@shrug/invoiceninja.upsertExpenses (dryRun default true); a live expense POST
needs that model's explicit dryRun=false plus a per-action sign-off. This
model only emits pure candidates plus a dry-run preview.
Rule-1 provenance
No existing extension covers the Hetzner-invoice -> per-project-spend ->
Invoice Ninja expense-candidate domain: swamp extension search found only
@swamp/hetzner-cloud (infrastructure provisioning, unrelated) and
@tagur/pdf (generic platform-gated PDF->markdown, no Hetzner/per-project/
finops/expense-candidate domain). This is a genuine last-resort build; the
reused Invoice Ninja money-write is extended, not rebuilt (repo rule 2).
| Argument | Type | Description |
|---|---|---|
| bytesBase64? | string | Inline base64-encoded PDF bytes (BytesSource). |
| filePath? | string | Local filesystem path to a PDF (FileSource). |
| imap? | object | IMAP attachment reference (ImapSource) -- GATED on pub-4; throws. |
| Argument | Type | Description |
|---|---|---|
| filePath? | string | Local PDF path; defaults to globalArguments.defaultFilePath. |
| Argument | Type | Description |
|---|---|---|
| invoices? | array | Parsed invoice records (via CEL data.latest). |
| invoice? | record | A single parsed invoice record (convenience). |
Resources
Hetzner spend broken out by project over time (per-project subtotal,
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned