feat(integrations): production-harden Infakt plugin - validators, retry classifier, NestJS module, tests

[norbert-kulus-blockydevs]

Summary

Production-hardens the Infakt accounting integration, turning the sandbox-validated POC (#1274/#1275, closed without merging) into a real plugin. Part of the Infakt epic (#1279).

• Adds InfaktConnectionConfigShapeValidatorAdapter / InfaktConnectionCredentialsShapeValidatorAdapter (ConnectionConfigShapeValidatorPort / ConnectionCredentialsShapeValidatorPort) so creating a connection with a malformed baseUrl or missing apiKey fails fast with a 400 instead of surfacing as a runtime error on first invoice issuance
• Adds InfaktRetryClassifierAdapter for fiscal-safety-correct retry semantics: 4xx (except 429) → rejected (terminal, safe to reissue), 429 → transient (rate-limited), 5xx/network → in-doubt (the document may already exist server-side - must not blind-retry)
• Wires InfaktIntegrationModule via createNestAdapterModule(createInfaktPlugin()) (no plugin-specific Nest providers needed) and exports it from the package barrel so a host app can register the plugin
• Wires infakt-plugin.ts register() to register all three side-registrations above (previously a no-op)
• Carries over the adapter source from the POC (factory, HTTP client, invoicing adapter, webhook translator, exception/type definitions) since docs(invoicing): Infakt invoicing spike — feasibility artifact + POC plan #1275 was closed unmerged - this PR is where that code first lands on main
• Removes unused class-transformer / class-validator deps from libs/integrations/infakt/package.json
• Adds unit tests: fake HTTP client, adapter (happy + error path per method), HTTP client, webhook translator, factory, both shape validators - 7 suites / 81 tests
• Addresses PR review findings: gross->net conversion in issueCorrection (fiscal-correctness bug), moved POC sandbox script out of src/, stopped logging raw HTTP error bodies (PII), domain InfaktConfigException instead of a bare Error in the factory

Closes #1280

Test plan

• pnpm --filter @openlinker/integrations-infakt test - 7 suites, 81 tests passing
• pnpm lint
• pnpm type-check
• Manual: create an Infakt connection with an empty API key → expect 400 with errors[]
• Manual: create an Infakt connection with valid credentials → expect validation to pass

[norbert-kulus-blockydevs]

Tech review: PR #1292 (feat(integrations): production-harden Infakt plugin)

Summary

Solid, well-tested hardening pass that follows the KSeF/Subiekt plugin precedent closely (validators, retry classifier, createNestAdapterModule wiring, capability guards). Test coverage is thorough (7 suites / 80 tests, happy + error paths per method). The main concerns are a couple of correctness gaps in InfaktInvoicingAdapter (hardcoded invoice_type, unrounded floating-point price strings) and a documented-standard deviation (inline types instead of *.types.ts) that the sibling KSeF plugin does not have. Nothing here blocks merge, but the two IMPORTANT items should be fixed or explicitly deferred with a follow-up issue before this ships to production traffic.

Issues

[IMPORTANT] - libs/integrations/infakt/src/infrastructure/adapters/infakt-invoicing.adapter.ts:199 (getInvoice) and :212 (getClearanceStatus)

invoice_kind_to_type(invoice_uuid_kind(providerInvoiceId)) always evaluates to 'vat' - invoice_uuid_kind ignores its argument and returns a hardcoded string, so the composition is dead complexity around a constant. More importantly, getClearanceStatus calls this.http.get(..., { invoice_type: 'vat' }) unconditionally, so looking up a correction document (kind: 'corrective', produced by issueCorrection) queries Infakt with the wrong invoice_type and will likely 404 or return stale data. Since CorrectionIssuer is declared as a supported capability, getClearanceStatus/getInvoice on a correction record is a real code path, not hypothetical. Either resolve invoice_type from the stored InvoiceRecord.documentType (available in getClearanceStatus's record param) or drop the pretend-dynamic helpers and track the limitation explicitly in a follow-up issue if 'vat'-only is an acceptable v1 scope.

[IMPORTANT] - libs/integrations/infakt/src/infrastructure/adapters/infakt-invoicing.adapter.ts:146

unit_net_price: ${l.unitPriceGross / (1 + this.taxRateNumeric(l.taxRate))} ${currency ?? 'PLN'}`` does floating-point division with no rounding, so a value like 123 / 1.23 produces `"100.00000000000001 PLN"` (or a long repeating decimal for other tax rates). This gets sent verbatim to Infakt's API as the price string. Money math should round to 2 decimal places before interpolating into the payload (e.g. `.toFixed(2)`), same as `issueCorrection`'s `corrPrice` branch, which also has this gap (`svc.unit_net_price` / `corrLine.newUnitPriceGross` interpolated raw).

[IMPORTANT] - libs/integrations/infakt/src/application/infakt-adapter.factory.ts:15-19

InfaktCredentials and InfaktConnectionConfig are defined inline in the factory file rather than in a *.types.ts file, which is a documented MUST in docs/engineering-standards.md § Type Definitions in Separate Files. The sibling KsefAdapterFactory (libs/integrations/ksef/src/application/factories/ksef-adapter.factory.ts) follows the rule correctly - KsefConnectionConfig/KsefCredentials live in domain/types/ksef-connection.types.ts. Move both interfaces into libs/integrations/infakt/src/domain/types/infakt.types.ts (or a new infakt-connection.types.ts) for consistency with the established plugin pattern.

[SUGGESTION] - libs/integrations/infakt/src/infrastructure/adapters/infakt-invoicing.adapter.ts:358-363

invoice_uuid_kind and invoice_kind_to_type are snake_case function names, which violates docs/engineering-standards.md § Variables and Functions (functions must be camelCase). If the dead-constant issue above is fixed by removing these helpers, this becomes moot; otherwise rename to inferInvoiceKind / mapInvoiceKindToType.

[SUGGESTION] - libs/integrations/infakt/src/infakt-plugin.ts:557-578 (createCapabilityAdapter)

The try { ... } catch (err) { return Promise.reject(err as Error); } wrapper is a no-op - an async function already returns a rejected promise on a thrown error, so this adds nothing except an unsound err as Error cast (the caught value isn't guaranteed to be an Error). Safe to delete the try/catch entirely.

[SUGGESTION] - libs/integrations/infakt/src/application/infakt-adapter.factory.ts

InfaktAdapterFactory has no implements clause / interface, unlike KsefAdapterFactory implements IKsefAdapterFactory. Not enforced by CI for plugin packages, but worth aligning with the sibling plugin's pattern for consistency, especially since this factory is on the standard "single per-connection construction seam" path other plugins document explicitly.

Verdict

🔄 Approve with changes - no architecture or security violations; the IMPORTANT items are real correctness gaps in the correction/clearance-lookup and price-formatting paths that should be fixed (or explicitly deferred via a tracked follow-up) before this handles live fiscal documents.

[norbert-kulus-blockydevs]

Addressed all IMPORTANT and SUGGESTION items from the tech review (80e98c1):

IMPORTANT

• getClearanceStatus now resolves invoice_type from InvoiceRecord.documentType (corrected → corrective, proforma → proforma, else vat) instead of the dead-constant invoice_kind_to_type(invoice_uuid_kind(...)) pair, so correction-status lookups hit the right Infakt kind. getInvoice has no InvoiceRecord to read a kind from, so it now tries vat then corrective in turn (skipping on 404, propagating any other error).
• unit_net_price / corrPrice are now rounded with .toFixed(2) before interpolation, so the Infakt payload never carries raw floating-point strings like "100.00000000000001".
• InfaktCredentials / InfaktConnectionConfig moved out of the factory file into domain/types/infakt-connection.types.ts, mirroring the KSeF plugin's ksef-connection.types.ts layout.

SUGGESTION

• The dead invoice_uuid_kind / invoice_kind_to_type snake_case helpers are deleted (moot once the dead-constant issue was fixed).
• Removed the no-op try { ... } catch (err) { return Promise.reject(err as Error) } wrapper in createCapabilityAdapter - an async function already rejects on a thrown error.
• Added IInfaktAdapterFactory interface, implemented by InfaktAdapterFactory, aligning with the IKsefAdapterFactory sibling pattern.

All 7 suites / 80 tests still pass; type-check and lint are clean for the package.

[piotrswierzy]

Tech review: production-harden Infakt plugin

Reviewed at head 80e98c15 — this already includes the fixes from the earlier self-review (invoice_type resolution, price rounding, types moved to infakt-connection.types.ts, dead helpers + no-op try/catch removed). Thorough pass overall: it follows the KSeF/Subiekt precedent closely, ADR-026 neutrality holds (all nip/ksef/tax_symbol vocabulary stays in the package, core stays neutral), HostServices purity is intact, capability manifest lists only Invoicing with sub-capabilities narrowed via guards, no any/console in production code, and the apiKey is never logged. 80 tests cover happy + error paths per method.

One net-new correctness defect remains beyond the earlier review:

🔴 BLOCKING

libs/integrations/infakt/src/infrastructure/adapters/infakt-invoicing.adapter.ts:274-294 — correction writes a gross price into the net field

issueCorrection interpolates corrLine.newUnitPriceGross (a gross price, per IssueCorrectionCommand — invoicing.types.ts:233-234) straight into Infakt's unit_net_price, while issueInvoice:158 correctly converts gross → net first (l.unitPriceGross / (1 + taxRateNumeric(l.taxRate))). The fallback branch (svc.unit_net_price, already net) is correct, so a price-changing correction line overstates the net amount by the tax fraction and emits an incorrect fiscal correction document that Infakt forwards to KSeF. CorrectionIssuer is a declared capability core can invoke, so this is a live path. Please apply the same gross → net conversion (reuse taxRateNumeric with svc.tax_symbol) before .toFixed(2), ideally via a shared grossToNet helper both call sites use.

🟡 SUGGESTION

• Correction currency is hardcoded PLN (l.276/294) while issueInvoice uses currency ?? 'PLN' — inconsistent; read currency from the command or add a comment.
• src/scripts/poc-sandbox-test.ts sits under src/**, so it compiles into dist and ships to consumers, and its poc:sandbox npm script depends on ts-node/tsconfig-paths not in the package deps. No hardcoded secrets (env-driven). Consider moving it out of src/ or excluding it from the build.
• HTTP client logs the raw error response body ({ body: text }, infakt-http-client.ts:78), which can carry buyer PII; consider trimming on non-error bodies (matches KSeF, low priority).
• InfaktWebhookTranslator is exported from the barrel but doesn't implement the canonical WebhookEventTranslator port and is unwired (deferred to #1281) — effectively dead on main until then; confirm #1281 reshapes it to the CanonicalInboundEvent contract.
• Factory throws a bare Error on missing credentialsRef rather than a domain exception (minor).

Process: branch is behind main (rebase before merge), and the repo-level pnpm lint / pnpm type-check checklist items are still unticked — get the full gate green first.

Verdict: Request changes — one fiscal-correctness bug in the correction price path. Everything else is solid and mirrors the KSeF precedent; fix the gross→net conversion in issueCorrection and this is an easy approve.

[norbert-kulus-blockydevs]

Addressed all findings from the latest review (commit a3b6823):

BLOCKING

• issueCorrection was writing a gross price (newUnitPriceGross) straight into Infakt's net-only unit_net_price field for price-changing correction lines, overstating the corrected amount by the tax fraction. Extracted the gross→net conversion issueInvoice already used into a shared grossToNet helper and reused it in issueCorrection (keyed off the original line's tax_symbol). Added a regression test asserting 61.50 PLN gross converts to 50.00 PLN net at a 23% rate.

Suggestions

• Correction currency was hardcoded to 'PLN' inline in two places; extracted to a local currency const with a comment explaining why (Infakt's invoice type carries no currency field; PLN is the only value the API has ever returned).
• Moved poc-sandbox-test.ts out of src/ into a top-level scripts/ folder so it no longer compiles into dist or ships to consumers; moved its ts-node/tsconfig-paths deps into devDependencies.
• InfaktHttpClient no longer logs the raw error response body (could carry buyer PII) — the full body is still available to callers via InfaktApiError.responseBody.
• InfaktAdapterFactory now throws a domain InfaktConfigException instead of a bare Error on a missing credentialsRef, matching the DPD/KSeF precedent.
• InfaktWebhookTranslator's wiring remains deferred to feat(infakt): register Infakt plugin in API + wire webhook ingestion #1281 as noted in the review — no change needed here.

Branch is already even with main (0 ahead/behind), so no rebase was required. Package-scoped lint / type-check / test (81 tests, 7 suites) all pass; the repo-wide CI Lint and Type Check checks are green on this head.

[piotrswierzy]

Re-review — de23a27 (was 80e98c1)

Re-verified the prior BLOCKING finding and all suggestions. Verdict: Approve.

BLOCKING — gross→net in issueCorrection: ✅ ADDRESSED

infakt-invoicing.adapter.ts now extracts a shared grossToNet(unitPriceGross, taxRate) helper and applies it in both issueInvoice and issueCorrection. The corrected line uses grossToNet(corrLine.newUnitPriceGross, svc.tax_symbol), so correction documents are no longer overstated. Confirmed the conversion is correct across tax symbols (23 → 0.23; zw/np → 0, no division) and that the untouched-line fallback re-emits the original net price without double-converting. Exactly the fix requested, via a shared helper.

Suggestions

• Correction currency hardcoded 'PLN' — ✅ addressed with justification. Confirmed IssueCorrectionCommand carries no currency field (unlike IssueInvoiceCommand), so 'PLN' + explanatory comment is the correct resolution.
• poc-sandbox-test.ts under src/ — ✅ moved to scripts/, outside tsconfig rootDir/include; won't ship to dist.
• HTTP client logging raw error body (PII) — ✅ now logs only method path → status; full body still reaches the caller via InfaktApiError.
• Factory bare Error — ✅ now throws InfaktConfigException(message, connectionId).
• InfaktWebhookTranslator unwired — ⏸ explicitly deferred to #1281 (host registration + webhook routing), documented in the integration-module docstring. Fine to defer.

New (non-blocking, for the sandbox POC to confirm)

InfaktInvoiceService.unit_net_price is typed number and the correction path calls .toFixed(2) on the value read back from Infakt. If Infakt v3 returns monetary fields in grosze (integer minor units) rather than decimal PLN, the echoed "before"/fallback rows would be 100× off. Unverified against the live API and equally applicable to any read path — worth confirming with the sandbox POC; no code change requested now.

Nice, clean resolution — approving. Run the standard lint/type-check/test gate before merge.

[norbert-kulus-blockydevs]

Addressed the non-blocking follow-up from the latest re-review (commit de23a27c).

Fixed

InfaktInvoiceService.unit_net_price (and sibling monetary fields) were typed number, but Infakt's v3 API returns them as "amount currency" strings (e.g. "100.00 PLN") — confirmed against the official vat_invoice/corrective_invoice schema, not the grosze/minor-units concern raised in the review. issueCorrection called .toFixed(2) directly on svc.unit_net_price, which would throw a runtime TypeError against the real API since strings don't have .toFixed.

Fix:

• InfaktInvoice.{gross,net,tax}_price and InfaktInvoiceService.{unit_net,net,tax,gross}_price are now typed string in infakt.types.ts, matching the documented wire shape.
• Added a parseInfaktAmount(value: string): number helper in infakt-invoicing.adapter.ts and used it in issueCorrection before formatting the "before" row and the untouched-line fallback.
• Updated test fixtures to use real "NN.NN PLN" string values and added a regression test asserting the untouched-line fallback path parses and re-formats correctly.

Also done

• Rebased onto main (was behind).
• pnpm --filter @openlinker/integrations-infakt test — 7 suites / 82 tests passing.
• pnpm --filter @openlinker/integrations-infakt type-check — clean.
• check-cross-context-imports / check-service-interfaces invariants — clean.

Ready for merge.

[norbert-kulus-blockydevs]

Resolved in PR #1293 — invoice amounts are now sent as plain-integer groszy, not decimal strings. Moving discussion there since #1292 is already merged.