feat(web): inFakt FE plugin — connection setup + invoice detail + KOR correction

[norbert-kulus-blockydevs]

Summary

Frontend half of the inFakt accounting integration (epic #1279). Backend capability surface (InvoicingPort + RegulatoryStatusReader + CorrectionIssuer) is code-complete on PR #1292 (merged) and PR #1293 (registration + webhook, stacked on #1292) — this PR consumes that contract.

• Guided connection setup: /connections/new/infakt — name + API key + optional sandbox baseUrl override, mirroring the Erli setup-flow pattern (single credential, "Test connection" affordance after create). This corrects issue feat(infakt): FE plugin – connection setup + invoice detail section #1282's original text, which implied wiring StructuredConfigSection into the generic inline create form — verified against the real PlatformPicker/CreateConnectionForm source that every plugin with a setupCard routes to its own guided page instead.
• Credentials rotation (InfaktCredentialsPanel) and post-create baseUrl editing (InfaktStructuredSection) — near-identical ports of the Erli / WooCommerce equivalents.
• Invoice detail section (InfaktInvoiceDetailSection) — renders submitted / accepted / rejected regulatory states with the new .reg-card treatment (see below). Based on Subiekt's simpler badge+KV structure rather than KSeF's UPO/FA3-owning one, since inFakt exposes no UPO/FA3 document endpoints of its own.
• KOR correction flow (InfaktInvoiceCorrectionFlow) — near-1:1 port of KsefInvoiceCorrectionFlow (same line-row model, same generic useIssueCorrectionMutation + POST /invoices/:invoiceId/correct contract). This scope item was missing from the original issue feat(infakt): FE plugin – connection setup + invoice detail section #1282 text; added to the issue body once the backend CorrectionIssuer capability was confirmed real (PR feat(integrations): production-harden Infakt plugin - validators, retry classifier, NestJS module, tests #1292).
• Shared .reg-card redesign: a severity-stripe card treatment for the invoiceDetailSection provider slot (progress bar for pending, copyable clearance chip for accepted, proper alert styling for rejected). Applied additively to KSeF's and Subiekt's existing sections too (their original root class stays, so no existing DOM-shape assertions break) — inFakt ships with it from day one, its siblings get it as a drive-by improvement. Validated in a design mockup approved by the user before implementation: https://claude.ai/code/artifact/2c542a0c-0719-4db1-b9d0-c962be23dadb

Full plan: docs/plans/implementation-plan-infakt-fe-plugin.md (research trail, alternatives considered, risk analysis).

E2E verification — complete

Two Playwright evidence scripts (apps/web/e2e/infakt-connection.mjs, apps/web/e2e/infakt-invoice.mjs) drove the full connect → issue → KSeF-clearance → correction flow against the real inFakt sandbox. Full walkthrough with screenshots posted here: #1300 (comment)

Screenshots committed at libs/integrations/infakt/docs/assets/ (mirrors the KSeF/Subiekt tutorial-asset convention from PR #1284).

This walkthrough surfaced three real backend bugs, all found, fixed, and re-verified live against the sandbox on #1293:

1. Missing ConnectionTesterPort registration for infakt.accounting.v1
2. Invoice amounts sent ~100x too low (decimal-string vs. integer-groszy format) — a compliance-relevant bug, since these amounts go to KSeF
3. KSeF success status mapped to the neutral cleared instead of accepted, so the terminal-success UI (clearance reference chip) never rendered

Test plan

• pnpm --filter @openlinker/web lint — 0 errors (pre-existing warnings only)
• pnpm --filter @openlinker/web type-check — 0 errors
• pnpm --filter @openlinker/web test — all new + existing suites green (one pre-existing, unrelated local-env-only failure in settings-page.test.tsx caused by a stale local .env.local VITE_API_BASE_URL override — not present in CI, not touched by this diff)
• Bumped EXPECTED_LAZY_ROUTE_COUNT 48 → 49 for the new infakt-setup.route.tsx
• Live sandbox E2E: connect → issue → real KSeF clearance → correction, confirmed with exact PLN amounts against inFakt's own API responses (see walkthrough comment)

Follow-up fix merged into this branch — PDF download (#1321 / #1323)

The E2E walkthrough's "Download PDF" affordance turned out to be non-functional: InfaktInvoicingAdapter was reading a pdf_url field that doesn't exist on inFakt's invoice resource (verified live against the sandbox), so InvoiceRecord.pdfUrl was always null. Filed as #1321, fixed and merged on #1323:

• InfaktInvoicingAdapter 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.
• FE: new useInvoiceRenderedDocumentDownload hook + a working "Download PDF" button in InfaktInvoiceDetailSection, routed through the existing GET /invoices/:invoiceId/document?kind=rendered controller route.
• pnpm --filter @openlinker/integrations-infakt build/lint/test — 115/115 passing, new adapter coverage; pnpm --filter @openlinker/web type-check clean; pnpm check:invariants clean; live sandbox verification of the real PDF endpoint before implementation.

Closes #1282

[norbert-kulus-blockydevs]

Live sandbox walkthrough — inFakt connect → issue → KSeF clearance → correction

Full E2E run against the real inFakt sandbox, confirming the FE plugin works end to end (not just that the components render). Order: 1 x product, gross total PLN 259.00.

(Updated — both backend bugs found during this walkthrough are now fixed and re-verified; screenshots below reflect the fixed behavior.)

1. Get your inFakt API key (inFakt dashboard, manual)

2. Create the connection in OpenLinker

3. Wire up the webhook (inFakt dashboard, manual)

4. An order arrives from PrestaShop

5. Issue the invoice

Order gross total PLN 259.00 matches inFakt's own record exactly (gross_price: 25900 groszy), KSeF number 8201194127-20260702-04CF63400000-1D, badge correctly shows ACCEPTED (not stuck on CLEARING).

6. Verify in inFakt

7. Full invoice detail page

8. Issue a correction (KOR)

Correction combines the original + corrected line correctly: PLN 259.00 + 99.99 = 358.99 PLN, verified against the sandbox (gross_price: 35899 groszy).

---

Three real backend gaps surfaced by this walkthrough, all fixed and re-verified on #1293:

1. Missing ConnectionTesterPort registration for infakt.accounting.v1 — finding → fixed
2. Invoice amounts sent ~100x too low (decimal-string vs. integer-groszy) — finding → fixed → confirmed
3. KSeF success status mapped to cleared instead of accepted, so the terminal state never rendered — finding → fixed → confirmed

Screenshots committed at libs/integrations/infakt/docs/assets/ for reuse in the eventual operator tutorial (mirroring the KSeF/Subiekt convention from PR #1284). This branch is up to date with main (includes #1292).

[norbert-kulus-blockydevs]

Tech-review (senior-level, /tech-review)

Scope: full PR (holistic pass against main, all 19 changed .ts/.tsx/.css files, ~1737 insertions) plus an independent second pass scoped strictly to the diff, run by a separate subagent. Findings below are merged from both passes.

Summary

Clean, well-scoped port of the existing KSeF/Erli/Subiekt plugin patterns to a new infakt FE plugin. It correctly uses the OpenLinkerPlugin contract, resolves everything through the platform registry (no platformType === 'infakt' string-matching outside plugins/infakt/), imports only from feature public barrels, uses design tokens throughout the new CSS, and ships solid test coverage per component. Architecture boundaries (plugin dependency direction, capability registry usage, kebab-case.tsx / *.test.tsx / use-*.ts naming, TanStack Query + RHF/Zod state ownership, no raw fetch()) are all respected. No BLOCKING issues.

Two things are worth fixing before merge: a real client-side validation gap in the correction flow, and a helper this PR triples across three files.

Issues

[IMPORTANT] - apps/web/src/plugins/infakt/components/infakt-invoice-correction-flow.tsx (parseLineRows, handleSubmit)

parseLineRows builds a CorrectionLineInput for any row with a non-empty originalLineNumber, even if both newQuantity and newUnitPriceGross are blank. The sibling KsefInvoiceCorrectionFlow.parseLineRows explicitly guards this: it returns null when a filled row has neither delta, and handleSubmit shows a specific inline error ("Each line must specify a new quantity and/or a new price."). The backend enforces exactly this invariant (HasCorrectionDeltaConstraint in apps/api/src/invoicing/http/dto/issue-correction-request.dto.ts), so submitting a bare line number here doesn't silently succeed, it 400s - but the operator only sees a generic "KOR failed: {backend message}" toast instead of the pre-submit inline guidance KSeF gives. Since this component is documented as a "near-1:1 port" of KSeF's, this divergence looks unintentional. Port the same null-return + dedicated error-message pattern from ksef-invoice-correction-flow.tsx.

[IMPORTANT] - apps/web/src/plugins/infakt/components/infakt-invoice-detail-section.tsx (new resolveRegCardTone), apps/web/src/plugins/ksef/components/ksef-invoice-detail-section.tsx:54-59, apps/web/src/plugins/subiekt/components/subiekt-invoice-detail-section.tsx:22-27

resolveRegCardTone is now defined three times with byte-for-byte identical bodies. This PR is the one introducing the third copy and simultaneously retrofitting the other two with the same helper instead of sharing one. All three call sites already import from the features/invoicing barrel (which the barrel doc comment explicitly carves out as the cross-plugin exception for exactly this kind of shared invoicing UI logic), so exporting one regCardToneFor(status) from that barrel costs no new import surface and removes the triplication.

Suggestions (non-blocking)

• infakt-invoice-detail-section.tsx: resolveRegCardTone returns a bare string instead of the narrow literal union ('reg-card--info' | 'reg-card--success' | 'reg-card--error' | ''). Worth tightening when the helper above gets extracted. Also takes InvoiceDetailSectionProps['invoice']['regulatoryStatus'] as its param type where importing the named RegulatoryStatus type (as Subiekt's copy does) reads clearer.
• infakt-invoice-detail-section.tsx: inline style={{ fontSize: '12px', margin: 0 }} on two <p> elements instead of a class. This mirrors a pre-existing pattern in subiekt-invoice-detail-section.tsx so it's not a regression, but since this file is new and "ships with the redesigned look from day one" per its own header comment, it was a good opportunity to use a type-scale class instead.
• InvoiceCorrectionFlowProps.connection is a required prop that neither InfaktInvoiceCorrectionFlow nor the pre-existing KsefInvoiceCorrectionFlow use. Not introduced by this PR, but with 2 of 3 implementers now ignoring a required prop it may be worth revisiting whether it should be optional on the interface.
• The .textarea className used in the reason field has no dedicated CSS rule (only the bare textarea element selector applies) - same gap already present in ksef-invoice-correction-flow.tsx, so not new, but a good candidate for a follow-up cleanup pass across all correction flows.

Verdict

Approve with changes - the two IMPORTANT items are both small, mechanical fixes (port the existing KSeF validation branch; extract one 4-line helper to the invoicing barrel) that should land before merge given the PR's own "near-1:1 port" / "shared .reg-card treatment" framing. Everything else is optional polish.

[norbert-kulus-blockydevs]

Tech-review findings addressed (23ae0ab)

Both IMPORTANT findings and all four suggestions from the tech-review comment are fixed:

IMPORTANT

• InfaktInvoiceCorrectionFlow.parseLineRows now returns null when a filled line has neither a new quantity nor a new price (ported 1:1 from KsefInvoiceCorrectionFlow), and handleSubmit shows the same inline "Each line must specify a new quantity and/or a new price." error instead of letting a no-op line reach the backend and 400. Added a regression test (blocks submit when a filled line has neither new quantity nor new price) and fixed the pre-existing does not include empty line rows in the submission test, which had accidentally been exercising the bug it was meant to guard against (it never gave the filled row a delta).
• Extracted the triplicated resolveRegCardTone into a single regCardToneFor(status) helper in features/invoicing/lib/derive-invoice-display.ts, exported from the invoicing barrel. KSeF, Subiekt, and inFakt detail sections now import it instead of each carrying their own copy.

Suggestions

• regCardToneFor returns the narrow RegCardTone union ('reg-card--info' | 'reg-card--success' | 'reg-card--error' | '') instead of a bare string.
• infakt-invoice-detail-section.tsx's two inline style={{ fontSize: '12px', margin: 0 }} blocks are replaced with a new .reg-card__note CSS class (added to index.css alongside the other .reg-card__* rules).
• InvoiceCorrectionFlowProps.connection is now optional — none of the three current implementers (KSeF, Subiekt, inFakt) read it.
• .textarea now has an actual CSS rule (merged into the existing bare textarea selector) instead of relying only on the element selector.

Verified: pnpm --filter @openlinker/web lint (0 errors), pnpm --filter @openlinker/web type-check (0 errors), full apps/web test suite (1908/1909 passing — same pre-existing, unrelated settings-page.test.tsx local-env failure called out in the PR description).

Branch is up to date with main (0 commits behind), no rebase was needed.

[norbert-kulus-blockydevs]

Added the "Default payment method" field this PR was missing for #1303 to be fully usable without editing raw JSON config:

• Connection wizard: new "Default payment method" select, defaulting to Transfer (the common case for online-shop invoicing), with Cash always available.
• Edit-connection screen: same field, tucked behind a new InlineDisclosure primitive (shared/ui/inline-disclosure.tsx) so it reads as an inline fact ("Payment method for invoice: Cash") rather than a permanently-open control — most operators never need to touch it.

Design reference: https://claude.ai/code/artifact/ee14c14d-bfac-4d5f-9b0f-ca3dfddb47a0

A follow-up (bank-account picker for Transfer invoices, in progress) will extend this same disclosure.

[piotrswierzy]

Tech Lead Review — inFakt FE plugin

Clean, faithful port of the KSeF/Subiekt slot precedents. Architecture holds across the board: plugin barrel wires all four platform slots, dependency direction (plugins → features → shared) is respected, all server state flows through TanStack Query hooks (no raw fetch), the correction mutation invalidates invoicingQueryKeys.all, the API key is write-only (password input, no readback), CSS uses design tokens (no raw hex), the .reg-card change is genuinely additive (KSeF/Subiekt keep their root classes + DOM shape, .trim() handles the empty-tone case), and the lazy-route count is correctly bumped to 49. The correction flow mirrors KsefInvoiceCorrectionFlow near-1:1.

IMPORTANT

• infakt-setup.schema.ts:53 — default payment method contradicts its own help copy. The wizard pre-selects defaultPaymentMethod: 'transfer', but the description directly beneath it (and on the edit section) says: "Transfer 422s on inFakt unless a bank account is configured… Leave Cash unless you have confirmed that prerequisite." An operator who accepts the default hits a 422 on their first issuance. Please default to 'cash' (fiscal-safe, matches the copy and the adapter fallback) — this also aligns with the BE default landing in #1309 (defaultPaymentMethod defaults to 'cash'). In a feature otherwise built around fiscal-safety gates, defaulting to the value the UI warns against stands out.

SUGGESTION

• route-lazy.test.ts:877-886 — constant is correctly 49, but the comment is stale: header says (46 total) and "9 plugin routes", whereas it's 10 plugin routes (Allegro = callback + setup) → 36 + 3 + 10 = 49. Keep the prose in sync per the "Bump this when…" note.
• index.css — .reg-card__reference and .reg-card__actions are defined but unused by any section; drop them or wire them.
• index.css — .reg-card__note { font-size: 12px; } uses raw px where neighbouring rules use rem; minor consistency nit.

Non-blocking notes: .infakt-correction root / __orig have no dedicated CSS, but that faithfully mirrors the KSeF precedent (same gap there), and the "inFakt · slot" provider tag mirrors "KSeF · slot" — both intentional, not leftovers.

Verdict: Approve with changes — resolve the payment-method default/copy contradiction before this leaves draft; the rest are trivial cleanups.

[norbert-kulus-blockydevs]

Addressed all findings from the tech-review:

IMPORTANT

• infakt-setup.schema.ts — default defaultPaymentMethod changed from transfer to cash, matching the help copy, the adapter's own fallback, and the BE default landing in fix(infakt): stop hardcoding payment_method, make it a per-connection setting #1309. Updated the corresponding wizard tests (default-value assertion + submit-payload assertions) to match; added coverage for explicitly selecting transfer.

SUGGESTION

• route-lazy.test.ts — fixed the stale comment header (46 total → 49 total, 9 plugin routes → 10 plugin routes); the EXPECTED_LAZY_ROUTE_COUNT = 49 constant itself was already correct.
• index.css — dropped the unused .reg-card__reference and .reg-card__actions classes (no section references either).
• index.css — .reg-card__note now uses 0.75rem instead of the raw 12px, matching the neighbouring rem-based rules.

Also rebased onto #1293 (which is itself rebased onto latest main), so this branch is now current with both.

Verified: pnpm --filter @openlinker/web lint (0 errors), pnpm --filter @openlinker/web type-check (0 errors), pnpm --filter @openlinker/web test (all green except the pre-existing, unrelated local-env-only settings-page.test.tsx failure noted in the PR description).

[piotrswierzy]

Re-reviewed at head d441dbe7 (was 0012af00). All prior findings addressed — the new commits are a tight, on-target response.

Resolved

• IMPORTANT — wizard now defaults defaultPaymentMethod: 'cash' (was 'transfer'), consistent with its own help copy ("Transfer 422s unless a bank account is configured — leave Cash unless confirmed"), the adapter-side fallback, and the #1309 BE default. Tests updated across the board; the transfer path is retained as an explicit-override case.
• Route-count comment in route-lazy.test.ts corrected to "49 total / 10 plugin routes"; matches the EXPECTED_LAZY_ROUTE_COUNT = 49 constant and the passing assertion.
• Dead CSS .reg-card__reference / .reg-card__actions removed (confirmed zero references), and .reg-card__note migrated 12px → 0.75rem.

Verified

• The .reg-card change is safe for the KSeF/Subiekt detail sections — the removed subclasses were unused, and the base .reg-card + all live modifiers remain intact.
• Affected suites pass locally: 3 files / 69 tests green (infakt-setup-form, route-lazy, infakt-invoice-detail-section).

No new findings. Ready to un-draft from a review perspective. (Merge-order: this is base for #1307 and #1310, so land it before those.)

[norbert-kulus-blockydevs]

Follow-up: the "Download PDF" button introduced in this PR's E2E walkthrough was found to be non-functional during that same verification pass — InfaktInvoicingAdapter was reading a pdf_url field that inFakt's invoice resource doesn't actually expose, so InvoiceRecord.pdfUrl was always null.

Filed as #1321, fixed and merged on #1323 (stacked on this branch):

• InfaktInvoicingAdapter now implements RegulatoryDocumentReader.getRegulatoryDocument for kind: 'rendered' against the real GET /invoices/{uuid}/pdf.json?document_type=original&invoice_type={kind} endpoint (verified live against the sandbox, returns a valid PDF binary).
• Dead pdf_url / print_url fields removed from the Infakt wire type.
• FE gets a working "Download PDF" button in InfaktInvoiceDetailSection via a new useInvoiceRenderedDocumentDownload hook, routed through the existing GET /invoices/:invoiceId/document?kind=rendered controller route.

Description above updated to reflect this.

[piotrswierzy]

Re-review (head 356b293e) — Approve

Re-reviewed the delta since the previous pass (d441dbe7). Two real work commits absorbed, the rest is main merged in.

What's new

• #1293 (61d5e5c0) — backend only: Infakt plugin registered in API/worker plugins.ts + webhook ingestion wiring (decoder / translator / connection-tester adapters + specs). No apps/web changes.
• #1323 (356b293e) — real PDF download via RegulatoryDocumentReader: new useInvoiceRenderedDocumentDownload hook, one barrel export, and a "Download PDF" button in the inFakt invoiceDetailSection slot.
• Main merges: demo-banner, /v1 versioning, Users pagination, erli — merge noise, not plugin work.

Prior findings — all still resolved

Every infakt FE file is byte-identical to d441dbe7 (git diff --stat empty): default→cash, route-lazy 49/10 comment, dead .reg-card__* CSS removal, .reg-card__note rem, KSeF/Subiekt-safe .reg-card. The index.css delta since the last pass is demo-banner CSS (merge #1264), not reg-card. No regression.

New code — clean

• No raw fetch/axios; the hook goes through apiClient.invoicing.downloadDocument → shared requestBlob (with encodeURIComponent).
• Correct blob-download pattern (object URL + programmatic <a download>, revokeObjectURL deferred past the tick).
• Dep direction plugins/infakt → features/invoicing barrel (allowed); shared/ stays clean at value level.
• Detail section reuses shared Button/useToast, i18n fallbacks, void-guarded promise, disabled+loading states, toast on failure. No raw hex tokens; route-lazy count test intact.

Suggestions (non-blocking)

• useInvoiceRenderedDocumentDownload is an imperative one-shot (not a TanStack mutation) — deliberate, mirrors useKsefUpoDownload; downloads aren't cacheable server state, so this is fine.
• Confirm the "Download PDF" button is offered in every regulatory state where inFakt has already rendered the PDF (it currently sits inside the clearance-number block).

CI

Please confirm the check-runs are green before merge (I couldn't read them from the legacy statuses API). Low risk (green-main merge + small additive FE). This is the base for #1307/#1310/#1323, so land it first.

Verdict: Approve.