docs(infakt): ADR-030 KSeF indirection model + operator setup guide

[norbert-kulus-blockydevs]

Summary

• Adds ADR-030 (docs/architecture/adrs/030-infakt-ksef-indirection.md) documenting why InfaktInvoicingAdapter implements RegulatoryStatusReader (not RegulatoryTransmitter): inFakt auto-submits to KSeF on its own timing via its own native integration, so OL has no submit primitive to call — it only ever reads clearance status back via GET /invoices/{uuid}.json.
• Adds the operator setup guide (docs/integrations/infakt/setup-guide.md): prerequisites, guided connection creation, webhook configuration (URL pattern, HMAC secret, verification handshake), a full verification walkthrough, and a troubleshooting table — illustrated with the 20 real screenshots already captured on this branch for feat(web): inFakt FE plugin — connection setup + invoice detail + KOR correction #1300's E2E walkthrough (libs/integrations/infakt/docs/assets/), including the inFakt-dashboard side (login, API key page, webhooks list, webhook subscription form, invoice-confirmed).
• Adds libs/integrations/infakt/README.md — the package README this adapter was missing, mirroring the shape of the other integration READMEs added in docs(integrations): package READMEs + operator tutorials for KSeF and Subiekt nexo #1284 (adapter key, capabilities, credentials/config shape, notable implementation details).
• Updates docs/architecture-overview.md § 14 Invoicing with a "Second provider" paragraph for inFakt, alongside the existing KSeF entry.
• Adds the implementation plan (docs/plans/implementation-plan-infakt-docs-adr.md) per the repo's /plan workflow.

Why this PR targets 1282-infakt-fe-plugin, not main

The setup guide documents connection-wizard fields and webhook wiring that only exist on 1282-infakt-fe-plugin (which carries #1280's hardened adapter, #1281's registration + webhook routing, and #1282's FE plugin) — none of that has merged to main yet. Stacking this PR keeps its diff docs-only; it'll retarget to main automatically once 1282-infakt-fe-plugin merges.

Known gap, documented not hidden

The webhook-secret exchange direction (OL generates → paste into inFakt, vs. inFakt generates → paste into OL) couldn't be verified against inFakt's live dashboard UI in this session. The setup guide documents the more common HMAC-webhook UX (OL generates via Rotate webhook secret) and calls out the fallback + the fact that OL currently has no endpoint to set the webhook secret to an arbitrary caller-supplied value — only to rotate to a new random one.

Test plan

• All screenshot references resolve to files that exist in the repo tree (reused from PR feat(web): inFakt FE plugin — connection setup + invoice detail + KOR correction #1300, no new captures needed)
• All relative doc links resolve
• scripts/check-repo-urls.mjs passes
• ADR follows the template in docs/architecture/adrs/README.md, Status: Accepted
• ADR index + architecture-overview.md updated

Part of #1279. Closes #1283.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JvfZGWAWWqVeJsFZbH1atL

[piotrswierzy]

Tech-lead review (docs-only, reviewed against stacked base 1282-infakt-fe-plugin; diff = origin/1282...origin/1283).

Overall a well-structured docs set: ADR-030 is the next-free number, conforms to the ADR template (all required sections present), the ADR-README index row is added, all 20 referenced screenshots are committed and their paths resolve, relative links resolve, and no secrets are leaked. Adapter facts largely check out against the merged code (adapterKey infakt.accounting.v1, platformType infakt, displayName Infakt Accounting API v3, InvoicingPort + RegulatoryStatusReader + CorrectionIssuer with RegulatoryTransmitter deliberately absent, the ksef_data.status → RegulatoryStatus mapping, document types, gross→net + before/after correction rows).

One blocking accuracy issue plus a merge-ordering constraint:

🔴 BLOCKING — ADR-030's "no submit primitive" premise is contradicted by the shipped adapter and the POC it cites.
The ADR states "There is nothing for OL to submit … OL has no submit primitive to call at all" and that inFakt "auto-triggers KSeF submission the moment POST /invoices.json succeeds (confirmed live on sandbox, #1274: … zero further OL action)." But:

• infakt-invoicing.adapter.ts ships a public sendToKsef(invoiceUuid) → POST invoices/{uuid}/send_to_ksef.json.
• The cited POC (scripts/poc-sandbox-test.ts) runs issueInvoice → getInvoice → getClearanceStatus ("pre-submit clearance") → sendToKsef ("STEP 5 — trigger KSeF submission") → cleared — it explicitly invokes a submit primitive and checks a pre-submit status, rather than proving "zero further OL action."
• The Alternatives section says the OL-driven-submission fallback is "not modeled in code," yet sendToKsef models exactly that. (Note: #1293's rebased adapter now calls sendToKsef inline at issuance — so OL does drive submission.)

The decision (don't expose RegulatoryTransmitter) is probably still right, but the justification as written will mislead a maintainer who greps and finds sendToKsef. Please reword: OL retains an out-of-port sendToKsef trigger and does not surface it as a RegulatoryTransmitter method because clearance timing/status ownership stays with inFakt — rather than "there is no submit primitive."

🟠 IMPORTANT — merge ordering. ADR-030 and the README reference InfaktInboundWebhookDecoderAdapter, which does not exist on this PR's base (1282) — it lives on 1281-infakt-plugin-registration-webhook (#1293), and 1281 is not an ancestor of 1282. The docs correctly describe the merged end-state, but this PR can't land until #1293 and the 1282 base are on main. Confirm the class names still match after the stack collapses.

🟡 SUGGESTION — setup-guide §3 step 3 says the invoice "updates to accepted". The adapter historically mapped success → cleared; #1293 remaps it to accepted. Reconcile the guide with whichever value ships, and keep it consistent with ADR-030.

🟡 SUGGESTION — README names both InfaktWebhookTranslator and InfaktInboundWebhookDecoderAdapter; the final (#1293) code has three distinct webhook classes. Tighten the prose to name which class does what.

Draft looks close — main ask is the ADR premise reword; the rest is post-stack verification.

[piotrswierzy]

/pr-review — systematic review

Verdict: ❌ Request changes (consistent with draft status). Well-researched docs PR — ADR structure, link hygiene, and most technical claims check out against the code — but four accuracy defects need fixing before merge. All are small and mechanical.

Stacking status verified: the PR now targets main and the diff contains only docs (6 markdown files + 12 PNGs, no stacked code); the prereqs (#1293/#1300/#1309) have merged. Branch is behind main (#1297/#1329 landed since) — needs an update, no conflict expected.

🟡 IMPORTANT

1. docs/architecture/adrs/030-infakt-ksef-indirection.md:43 — wrong terminal status mapping. The Decision section maps ksef_data.status onto RegulatoryStatus as submitted | submitted | cleared | rejected. The shipped adapter (infakt-invoicing.adapter.ts:73-81) maps success → 'accepted' — and its own comment documents that a cleared mapping was a past bug. The ADR is the durable record and would re-canonize the exact mistake the code warns against; it also contradicts the setup guide's own verification step 3 ("updates to accepted"). One-word fix: submitted | submitted | accepted | rejected.

2. Setup guide (Capabilities table :23, bank-picker paragraphs ~:76-90) + README (capabilities row, #1310 bullet) — documents unmerged functionality as shipped. BankAccountsReader / BankAccountDefaultSetter don't exist on main — the adapter implements InvoicingPort, RegulatoryStatusReader, CorrectionIssuer, RegulatoryDocumentReader only, and InfaktConnectionConfig has no bankAccount field. The bank-picker walkthrough (with screenshots 06/07) describes UI an operator on main cannot find. Either sequence this PR after #1310 merges, or strip the bank-account rows/paragraphs/screenshots into #1310's own docs.

3. Setup guide § 2, step 5 (~:128) — the OL-side "Rotate webhook secret" affordance does not exist in the FE. The backend endpoint exists (POST /connections/:id/webhooks/secret/rotate, secret shown once — that part is accurate), but a repo-wide search of apps/web/src finds no caller and no such label; the inFakt credentials-panel rotate affordance rotates the API key, not the webhook secret. An operator following the step hits a dead end. Document the API call (curl/HTTP snippet) until an FE affordance ships, or land that affordance first.

4. Setup guide § 2, step 5 vs its own screenshot — the primary secret-exchange instruction is contradicted by if4-infakt-webhook-form.png. The embedded screenshot of inFakt's "Nowy webhook" form shows no secret field at all (URL, description, payload option, event checkboxes, account password). The guide instructs "Paste that same value into inFakt's webhook subscription secret field" as the primary path. The PR body honestly flags this as unverified — good — but the guide text asserts as fact a UI element its own screenshot disproves. Invert the framing: lead with what the screenshot shows, state the exchange direction is unverified, keep the fallback as the likely path (or verify against inFakt's webhook docs first).

🟢 SUGGESTIONS

• libs/integrations/infakt/README.md (~:40) — the Config JSON block omits defaultPaymentMethod, which InfaktConnectionConfig carries since #1309; add it so the documented shape matches the type.
• docs/plans/implementation-plan-infakt-docs-adr.md — plan constraints are stale (still says the PR targets 1282-infakt-fe-plugin, that #1281/#1282 are open, "no new screenshots" while four are added). A one-paragraph retarget addendum would prevent confusion.

✅ Verified-correct

• ADR-030 matches the ADR template exactly (header, Context, Decision, 3 Alternatives with rejection rationale, Consequences, References) and is indexed in the ADR README.
• All 24 screenshot references resolve (19 pre-existing from #1300, 4 new, + platform picker); all relative links and anchors resolve, including ADR-026's #amendments.
• Manifest facts accurate: infakt.accounting.v1, platformType infakt, capability Invoicing.
• Core claims coherent: RegulatoryStatusReader-not-RegulatoryTransmitter matches the code; document types, X-Infakt-Signature HMAC + verification_code handshake + send_to_ksef_* allowlist all match; RegulatoryDocumentReader (#1321) is on main; the not-applicable-forever consequence matches toRegulatoryStatus(null).
• No credentials leaked — placeholders only; screenshots show masked fields.
• The known-gap honesty (webhook-secret direction) is the right posture — only the primary-path framing overreaches (finding 4).

[norbert-kulus-blockydevs]

Pushed 999dda5 addressing all four IMPORTANT findings + both suggestions:

1. ADR-030 mapping fixed to submitted | submitted | accepted | rejected (matches the shipped adapter and its own anti-regression comment).
2. Bank-picker docs: BankAccountsReader/BankAccountDefaultSetter and the bank picker are no longer "unmerged" - feat(infakt): bank-account picker with live inFakt default sync (#1303 follow-up) #1310 merged to main on 2026-07-03, after your review. Merged origin/main into this branch; the docs now describe shipped code as-is, no strip needed.
3. Step 5 rewritten: dropped the nonexistent "Rotate webhook secret" FE button, replaced with the actual API call (POST /v1/connections/:id/webhooks/secret/rotate, curl snippet).
4. The secret-exchange framing now leads with what if4's screenshot actually shows (no secret field on inFakt's form) and marks the paste-direction explicitly unverified, per your finding.

Also: README config example now includes defaultPaymentMethod/bankAccount, and the plan doc has a retarget addendum noting the branch/prereq history.

[norbert-kulus-blockydevs]

Pushed e304219, addressing the tech-lead draft review's BLOCKING finding that the earlier fix commit (999dda5) missed.

The draft review flagged that ADR-030's premise — "there is nothing for OL to submit ... zero further OL action" — is contradicted by the shipped adapter: InfaktInvoicingAdapter ships a public sendToKsef(invoiceUuid) that issueInvoice/issueCorrection call inline, and the adapter's own docstring says an inFakt draft does not auto-submit on its own. That claim had propagated into the setup guide (Capabilities table + Prerequisites) and the README as well.

Reworded throughout, following the reviewer's suggested framing verbatim: OL retains an out-of-port sendToKsef trigger, not surfaced as a RegulatoryTransmitter method, because clearance timing and status ownership stay with inFakt — not because there is nothing to call. Concretely:

• ADR-030: Context, Decision, Alternatives, and Consequences sections all reworded to describe the real flow (OL explicitly triggers send_to_ksef.json inline; inFakt then owns the KSeF session/XML/status from that point on).
• Setup guide: Capabilities table row and Prerequisites bullet 2 reworded to match; the two Troubleshooting rows referencing an "auto-submit toggle" tightened to match (also dropped the leftover cleared/accepted inconsistency in the "stays submitted forever" row).
• README: same reword in the RegulatoryTransmitter-not-implemented paragraph and the "KSeF-as-intermediary" implementation-detail bullet.
• README: also addressed the draft review's suggestion that was still open — disambiguated the three actual webhook classes (InfaktWebhookTranslator, InfaktInboundWebhookDecoderAdapter, InfaktWebhookEventTranslatorAdapter) instead of naming only two.

Everything from the second (/pr-review) pass — the accepted mapping fix, the bank-picker docs, the webhook-secret reality check, the README config example, and the plan-doc retarget addendum — was already correctly addressed in 999dda5 and is unchanged here.

[norbert-kulus-blockydevs]

Combined review: /tech-review + /pr-review

Two independent passes (tech-lead review + systematic PR review) were run against the shipped libs/integrations/infakt/ source. They converged on the same single blocking issue. Docs-only PR, so the dominant axis was factual accuracy of the claims vs the code that actually ships.

Summary

High-quality, unusually well-researched docs set. The ADR-030, README, and setup guide are overwhelmingly accurate against the shipped InfaktInvoicingAdapter: the implements clause (6 capabilities, no RegulatoryTransmitter), the inline send_to_ksef.json submit model, the ksef_data.status -> RegulatoryStatus mapping, the config shape, the three webhook classes, the webhook HMAC/verification handshake, the rotate-secret endpoint, ADR template + index registration, all screenshot paths, and all doc links all check out. The one material problem: the single line this PR adds to architecture-overview.md § 14 contradicts the very ADR it ships alongside (and the code) by re-asserting the stale "auto-submit / no submit primitive" framing that commit e304219 corrected everywhere else.

Issues

[BLOCKING] - docs/architecture-overview.md (§ 14, new "Second provider" line)

The line states: "inFakt auto-triggers KSeF submission on its own - OL never opens a KSeF session itself. InfaktInvoicingAdapter implements ... RegulatoryStatusReader (not RegulatoryTransmitter - there is no submit primitive for OL to call)". Both claims are factually wrong and contradict this same PR's ADR-030. The adapter DOES call an explicit submit primitive: sendToKsef() at infakt-invoicing.adapter.ts:498 POSTs invoices/{uuid}/send_to_ksef.json, invoked inline by issueInvoice (:289) and issueCorrection (:465). The docstring (:9-10) is explicit: "an Infakt draft does NOT auto-submit to KSeF on its own". ADR-030 says the same. The real reason it declares RegulatoryStatusReader rather than RegulatoryTransmitter is submission timing/ownership staying with inFakt, not the absence of a primitive. Reword to match ADR-030/README/setup-guide: OL explicitly triggers submission via an inline send_to_ksef.json call, but inFakt owns the KSeF session/FA(3) XML/clearance timing, hence status-reader not transmitter.

[IMPORTANT] - PR description (Summary, first bullet) and docs/plans/implementation-plan-infakt-docs-adr.md (Context)

Both repeat the same stale claim ("inFakt auto-submits ... OL has no submit primitive to call - it only ever reads clearance status"). Both were touched recently (the plan carries a 2026-07-06 retarget addendum), so they should be corrected to the inline-send_to_ksef.json framing rather than shipped contradicting the ADR in the same PR. Anyone keying off the PR summary gets the wrong mental model.

[IMPORTANT] - libs/integrations/infakt/README.md (Config JSON example)

Example shows "baseUrl": "https://api.infakt.pl", but the real default is INFAKT_DEFAULT_BASE_URL = 'https://api.infakt.pl/api/v3' (infrastructure/http/infakt-http-client.ts:20) and a supplied baseUrl is used verbatim with no path appended (:37). An operator copying the sample into config would 404 on every request (missing /api/v3). The prose is fine (omit for production); fix the example value to include /api/v3 or make it an explicit sandbox host.

[SUGGESTION] - docs/integrations/infakt/setup-guide.md (Troubleshooting, "submitted forever" row)

Accurate but dense. Consider splitting "KSeF rejected the doc" vs "KSeF integration disabled" into two rows for scannability.

Positive observations (verified)

• Screenshot integrity clean: all referenced images resolve; the ones not added by this PR exist on origin/main (from feat(web): inFakt FE plugin — connection setup + invoice detail + KOR correction #1300), so nothing breaks on merge; zero orphan assets.
• node scripts/check-repo-urls.mjs passes.
• ADR-030 follows the template, Status: Accepted, correctly registered in docs/architecture/adrs/README.md with matching number/title/date.
• Rotate-secret curl is correct: route /v1/connections/{id}/webhooks/secret/rotate (URI versioning, no global prefix) and the { secret, revealedOnce, warning } response shape both match controller + DTO.
• The "Known gap" caveat (no OL endpoint to set a caller-supplied webhook secret; rotate-only, server-generated) is accurate against RotateWebhookSecretResponseDto.

Verdict: 🔄 Approve with changes

Priority fixes:

1. (BLOCKING) Rewrite the architecture-overview.md § 14 line so it no longer claims inFakt "auto-triggers" submission or that there is "no submit primitive for OL to call" - align with ADR-030/README/setup-guide.
2. (IMPORTANT) Correct the same stale claim in the PR description's first bullet and in the implementation plan's Context section.
3. (IMPORTANT) Fix the README baseUrl example to include /api/v3 (or mark sandbox-only).
4. (SUGGESTION) Split the troubleshooting row.

Everything else is accurate and well-sourced - fix the § 14 line and the two echoes of it and this is mergeable.

[piotrswierzy]

/pr-review — delta re-review (161ab4af → e30421988, docs-only)

All four findings from my earlier Request-changes are resolved. Verified against the actual files, not the PR body.

1. ADR-030 wrong terminal status mapping → RESOLVED. Now reads submitted | submitted | accepted | rejected with explicit prose "success maps to the terminal accepted state, not cleared" — matches the shipped adapter (infakt-invoicing.adapter.ts case 'success': return 'accepted').
2. #1310 bank-account functionality documented as shipped → MOOT (now merged). #1310 landed on main, the branch merged it, and the adapter implements the six capabilities the README table lists (InvoicingPort, RegulatoryStatusReader, CorrectionIssuer, RegulatoryDocumentReader, BankAccountsReader, BankAccountDefaultSetter). Docs match main.
3. Nonexistent "Rotate webhook secret" FE affordance → RESOLVED. Replaced with the real API call POST /v1/connections/{id}/webhooks/secret/rotate (confirmed at connection.controller.ts:223; response DTO matches). The doc's claim that there's no inFakt-connection FE webhook-secret affordance (unlike PrestaShop/Erli) is accurate.
4. Secret-exchange framing contradicted by its own screenshot → RESOLVED. Step 5 now leads with "inFakt's 'Nowy webhook' form has no secret field" (matching if4-…) and the Known Gap honestly discloses OL can't set its secret to inFakt's auto-generated value.

Also verified: README config JSON (baseUrl/defaultPaymentMethod/bankAccount{id,accountNumber,bankName}) matches InfaktConnectionConfig exactly and correctly excludes apiKey (a credential) — no config/secret drift; ADR-030 indexed as Accepted; asset links resolve; no unredacted secrets in text.

🟢 One minor wording nit (non-blocking)

Setup guide step 5 (~lines 129-130) still carries an actionable imperative — "set it as OL's webhook secret so X-Infakt-Signature verification matches" — while the Known Gap block immediately below says there's currently no mechanism to do that. The gap is disclosed adjacently, but soften the imperative (e.g. "you would set it — but note there's currently no mechanism; see Known Gap") so it doesn't tell the operator to do something the next paragraph calls impossible.

Verdict: ✅ Approve (docs-only). All Request-changes findings addressed; the wording nit is optional.