fix(infakt): implement real PDF download via RegulatoryDocumentReader

[norbert-kulus-blockydevs]

Summary

• InfaktInvoicingAdapter read a pdf_url field that does not exist on Infakt's invoice resource (verified live against the sandbox), so InvoiceRecord.pdfUrl was always null and the "download PDF" affordance never worked for Infakt connections.
• The adapter now implements RegulatoryDocumentReader.getRegulatoryDocument for kind: 'rendered', calling the real GET /invoices/{uuid}/pdf.json?document_type=original&invoice_type={kind} endpoint (confirmed live: returns a valid PDF binary directly).
• The dead pdf_url / print_url fields are removed from the Infakt wire type; InvoiceRecord.pdfUrl stays on core (Subiekt's FE still reads it) but Infakt no longer fakes it — it's null now, with the real path routed through the existing GET /invoices/:invoiceId/document?kind=rendered controller route (unchanged, already supports this).
• FE: new useInvoiceRenderedDocumentDownload hook + a working "Download PDF" button in the Infakt invoice detail section.

Base branch is 1282-infakt-fe-plugin (PR #1300, still open) because the touched FE component (infakt-invoice-detail-section.tsx) only exists on that branch — will retarget to main once it merges, matching PR #1307's precedent.

Test plan

• pnpm --filter @openlinker/integrations-infakt build/lint/test — 115/115 passing, new getRegulatoryDocument + getBinary coverage (happy path, no-content-type fallback, unsupported kind, oversized-body cap)
• pnpm --filter @openlinker/web type-check clean
• New FE test: clicking "Download PDF" calls apiClient.invoicing.downloadDocument(id, 'rendered')
• pnpm check:invariants clean (no cross-context/service-interface violations)
• Live sandbox verification of the real PDF endpoint before implementation (see issue [BUG] Integration — Infakt adapter's pdfUrl is always null; real PDF download endpoint unused #1321)

Closes #1321

[norbert-kulus-blockydevs]

Summary

Small, well-scoped fix: implements RegulatoryDocumentReader on InfaktInvoicingAdapter against the real pdf.json endpoint, removes the dead pdf_url/print_url fields, and wires a "Download PDF" button on the FE. The pattern (capped streaming binary read, UnsupportedRegulatoryDocumentKindError for unsupported kinds, hook shape) faithfully mirrors the existing KSeF RegulatoryDocumentReader implementation, and the port contract (kind?: RegulatoryDocumentKind = 'confirmation') is honored correctly. The main concern is a missing null-guard on record.providerInvoiceId in the new adapter method — inconsistent with this same file's own established pattern two methods above.

Issues

[IMPORTANT] — libs/integrations/infakt/src/infrastructure/adapters/infakt-invoicing.adapter.ts (line ~510)

getRegulatoryDocument builds the request path as `invoices/${record.providerInvoiceId}/pdf.json` without checking for null, even though InvoiceRecord.providerInvoiceId is typed string | null. This adapter already has an established guard for exactly this in getClearanceStatus (line 357: if (!record.providerInvoiceId) { return { regulatoryStatus: 'not-applicable' }; }), a few methods above. Without the same guard here, a null id silently builds the literal path invoices/null/pdf.json and hits the Infakt API with a nonsensical URL instead of failing predictably (e.g. via a clear domain exception). The port docstring says "callers gate on the record being cleared before invoking," which reduces the odds of hitting this in practice, but the existing in-file precedent shows the adapter itself doesn't currently rely on callers to enforce that — it guards defensively. No test exercises a providerInvoiceId: null record either. Add the same early guard (or throw a clear exception) before building the URL.

[SUGGESTION] — apps/web/src/features/invoicing/hooks/use-invoice-rendered-document-download.ts

triggerBlobDownload (lines ~45-54) and extensionForBlob/EXTENSION_BY_MIME are copy-pasted verbatim (down to the comment about deferred revokeObjectURL) from use-ksef-upo-download.ts. Per engineering-standards.md's "prefer reusing existing abstractions" principle, this is a good candidate to extract into a shared helper (e.g. features/invoicing/lib/blob-download.ts) that both hooks import, rather than maintaining two copies of the same anchor-click/object-URL lifecycle logic. Not blocking — the PR description explains why the hooks aren't merged (different API routes), but that reasoning doesn't apply to the private download-trigger helper, which is identical in both files.

[SUGGESTION] — libs/integrations/infakt/src/infrastructure/http/infakt-http-client.ts (getBinary)

The streaming byte-cap only checks the running total as chunks arrive. KSeF's readBinaryBodyCapped (which this is documented to mirror) additionally pre-checks the advertised Content-Length header before starting to stream, for an earlier fail-fast. Not a correctness or security gap here (the streaming cap alone still bounds memory), just a minor inconsistency with the pattern it says it mirrors — worth adding for parity if convenient, otherwise fine to leave as a smaller v1.

Verdict

🔄 Approve with changes — the providerInvoiceId null-guard (IMPORTANT) should be fixed before merge to keep behavior consistent with this adapter's own established defensive pattern; the two SUGGESTIONs are optional follow-ups.

[norbert-kulus-blockydevs]

Code Review — PR #1323

Scope reviewed: all 12 changed files (Infakt adapter + HTTP client, core RegulatoryDocumentReader wiring, FE hook + Infakt detail-section button, tests, implementation plan doc).

Findings

No BLOCKING, IMPORTANT, or SUGGESTION findings.

Verification performed

• Confirmed RegulatoryDocumentReader / RegulatoryDocumentKind / UnsupportedRegulatoryDocumentKindError are pre-existing, unmodified core contracts — no new port/capability surface introduced.
• Confirmed the controller route (GET /invoices/:invoiceId/document?kind=rendered) and FE apiClient.invoicing.downloadDocument(id, 'rendered') contract were already in place and unchanged — this PR only fills in the previously-missing real implementation.
• Confirmed toInfaktInvoiceType mapping and providerInvoiceId usage are correct against the existing adapter conventions.
• Confirmed the getBinary streaming-cap implementation correctly bounds memory (same pattern as KsefHttpClient.readBinaryBodyCapped).
• Confirmed the FE gating (invoice.regulatoryStatus === 'accepted') is consistent with the backend's record.status === 'issued' && record.regulatoryStatus === 'accepted' guard, mirroring the existing KSeF UPO-download gating precedent.
• Ran and verified green:
  • pnpm --filter @openlinker/integrations-infakt test — 115/115 passing
  • pnpm --filter @openlinker/integrations-infakt lint — clean, no diff from --fix
  • pnpm --filter @openlinker/web type-check — clean
  • FE test infakt-invoice-detail-section.test.tsx — 8/8 passing

Positive observations

• Correctly kept InvoiceRecord.pdfUrl on core (Subiekt's FE still reads it) while explicitly nulling it out at all 3 Infakt call sites with an explanatory comment pointing at the real path — avoids a needless core-wide breaking change while being explicit about the dead field.
• getBinary's streaming byte cap mirrors the established KSeF pattern (defense against a mendacious/oversized body) rather than inventing a new approach.
• Test coverage includes the happy path, missing-content-type fallback, unsupported-kind rejection, and the oversized-body cap — good edge-case coverage on both the adapter and the HTTP client.

Verdict: No issues found. This PR looks ready to merge (note: approval was not submitted by this session since it was flagged as a self-approval — this is the same branch/worktree as the PR author).

[piotrswierzy]

Tech Lead Review — Approve

Clean, well-scoped fix. The adapter now implements the RegulatoryDocumentReader sub-capability for kind: 'rendered', routing through the existing neutral GET /invoices/:invoiceId/document?kind=rendered controller instead of the phantom pdf_url field. Verified end to end:

• Capability + guard: getRegulatoryDocument(record, kind) matches the core contract, kind defaults to confirmation (consistent with the interface), and unsupported kinds throw UnsupportedRegulatoryDocumentKindError → the controller maps that to 409. The controller's availability gate (status === 'issued' && regulatoryStatus === 'accepted') is mirrored exactly by the FE button's accepted gate, so no dead-end 409s from the UI.
• ADR-026 neutrality: Infakt wire vocab (document_type: 'original', invoice_type: 'vat') stays in the adapter; core only ever sees the neutral kind='rendered'.
• No Subiekt regression: dead-field removal is confined to the InfaktInvoice wire type. InvoiceRecord.pdfUrl stays on core and Subiekt still populates it (subiekt-invoicing.adapter.ts:166); Infakt just returns null.
• Binary safety: getBinary streams with a 10 MB accumulation cap mirroring the KSeF client — an oversized/mendacious body can't drive an unbounded read.
• FE: imperative one-shot hook (no raw fetch, goes through apiClient.invoicing.downloadDocument), object-URL revoke deferred past the click tick. Tests cover the click → downloadDocument(id, 'rendered') path.
• Test coverage is solid on both halves (adapter happy / no-content-type / unsupported-confirmation / unsupported-source; http-client happy / non-2xx / oversized-cap; FE click).

Suggestions (non-blocking)

• triggerBlobDownload (object-URL + <a download> + deferred revoke) is now the fifth copy of this primitive across features/invoicing/hooks and features/shipments/lib/label-download.ts. Consider extracting a shared downloadBlob(blob, filename) util. The hook itself is rightly kept separate (documented reason: neutral /document route vs. UPO's dedicated route).
• Download filename uses the internal ol-invoice-{id}; a provider invoice number would read nicer for operators. Minor.

Merge order: this is stacked on 1282-infakt-fe-plugin (#1300) — it targets that branch, not main, and must not merge before #1300 lands.

Verdict: Approve.