feat(subiekt): payment method / bank account / cash register per invoice (#1324)

[norbert-kulus-blockydevs]

Summary

Adds payment method / bank account / cash register (Stanowisko Kasowe) per invoice for the Subiekt nexo invoicing integration, mirroring the inFakt pattern (#1303/#1308) and reusing the existing core capabilities BankAccountsReader / BankAccountDefaultSetter (no new core ports).

• Bridge client (libs/integrations/subiekt/src/bridge/**): listBankAccounts / setDefaultBankAccount / listCashRegisters.
• Connection config (SubiektConnectionConfig + DTO + factory): defaultPaymentMethod, bankAccountId, defaultStanowiskoKasoweId.
• Adapter (subiekt-invoicing.adapter.ts): implements BankAccountsReader / BankAccountDefaultSetter; owner-aware listBankAccountsWithOwner + listCashRegisters; stamps payment / bank-account / cash-register fields onto issueInvoice.
• API (apps/api/src/integrations/http/subiekt.controller.ts): owner-aware GET .../bank-accounts + GET .../cash-registers.
• FE (apps/web/src/plugins/subiekt/components/subiekt-structured-section.tsx + features/connections hooks/types): payment-method select, owner-grouped bank-account picker with a multi-payer warning, and a Stanowisko Kasowe picker with a Centrala help line. The Oddział axis is intentionally cut - it is bound read-only to the bridge's Sfera session and cannot be overridden per invoice (decision 8b).

⚠️ Draft - depends on #1310 (must merge first)

This branch is stacked on the inFakt prerequisite chain. #1300 and #1309 are already merged to main; #1310 (bank-account picker core capabilities) is still open and #1324 reuses exactly those capabilities.

Do not merge until #1310 is merged to main. The current diff is inflated because #1310 (and the surrounding inFakt/KSeF prereq work) are not yet on main, so their files show up here. Once #1310 merges, this branch will be rebased onto main and the diff will collapse to the Subiekt-only delta listed above. Please review only the libs/integrations/subiekt/**, apps/api/src/integrations/http/subiekt.controller.ts, and apps/web/src/plugins/subiekt/** + features/connections Subiekt additions here; the inFakt / KSeF churn belongs to the prereq PRs.

Verification

• Per-package: subiekt 216 tests, api subiekt controller 6/6, web suite green; web type-check clean after integrating feat(infakt): bank-account picker with live inFakt default sync (#1303 follow-up) #1310.
• Live E2E against a real Nexo_Demo_1 Sfera install, both directly through the bridge and full-stack through OpenLinker (Presta-sourced order -> OL -> Subiekt adapter -> bridge -> Sfera): 8 invoices across all payment configs (cash / transfer + bank account / two distinct Stanowiska Kasowe), each confirmed by SQL read-back on the real document. Config-driven, no caching; explicit payment selection correctly requires a faktura (a paragon is rejected 422).

Operator docs (setup guide + tutorial) for this feature are in PR #1284.

Closes #1324

[norbert-kulus-blockydevs]

E2E verification - confirmed working (post-merge)

I re-ran a full end-to-end test on the merged code (this branch's merge of #1310 + main, commit 296eafae) and confirm the feature works: OpenLinker issues Subiekt invoices for PrestaShop-sourced orders across payment variants, and each selection lands correctly on the real Subiekt/Sfera document.

Post-merge checks

• pnpm --filter @openlinker/web type-check clean.
• pnpm --filter @openlinker/web test -> 1967 passed (covers the Subiekt structured section + the shared features/connections files touched by the feat(infakt): bank-account picker with live inFakt default sync (#1303 follow-up) #1310 merge).

Live run against a real Nexo_Demo_1 Sfera install - 3 new invoices issued through OpenLinker (POST /v1/invoices -> Subiekt adapter -> bridge -> Sfera) for Presta-sourced orders, one per payment config, then read back straight from the Dokumenty table:

Variant	Invoice	Sfera read-back (form / cash / deferred / cash-register)
cash	FS 197/CENTRALA/2026	1 Gotowka / 349.00 / 0 / 100065
transfer + bank account 100004	FS 198/CENTRALA/2026	2 Przelew / 0 / 49.00 / 100065
cash + cash-register 100066	FS 199/CENTRALA/2026	1 Gotowka / 492.00 / 0 / 100066

Behavior is identical to the pre-merge run: transfer flips FormaPlatnosciId to 2 and moves the amount to the deferred bucket; an explicit cash-register (Stanowisko Kasowe) 100066 reads back distinct from the session default 100065. Config-driven, no caching. Explicit payment selection correctly requires a faktura (a paragon is rejected 422).

Full report with screenshots (invoices list showing FS 197-199 + FS 199 detail issued via the Subiekt connection): https://claude.ai/code/artifact/afbfaca3-bef5-4067-9639-d34a1d95f754

Dependency note still stands: this PR must land after #1310 is merged to main (the current diff is inflated by the not-yet-merged prerequisites and will collapse to the Subiekt-only delta once #1310 merges and this branch is rebased).

[piotrswierzy]

/pr-review — systematic review

The Subiekt-scoped delta itself is high quality (details below), but there is one branch-state problem that goes beyond the documented "stacked-diff inflation" and must be repaired before this PR can even be meaningfully rebased.

🔴 BLOCKING

The branch reverts work already merged to main — a rebase will NOT fix this automatically.
Verified independently: the merge-base of 296eafae with origin/main is main's current tip (678041c0) — meaning main was merged into this branch — yet the branch tree is missing merged work:

• apps/api/src/migrations/1818000000003-add-invoice-issued-line-snapshot.ts (#1297) is deleted, and git grep issuedLineSnapshot over libs/core/src/invoicing on the branch finds nothing.
• The #1330 buildEditConnectionSchema / ConnectionConfigContribution plugin-slot seam (plus its tests) is rolled back.
• The #1317 KSeF FA(3) Płatność code and scripts/check-ksef-forma-platnosci-drift.mjs are rolled back.

This looks like a bad conflict resolution when main was merged in. Because the branch tip's file contents themselves lack the merged work, merging as-is silently reverts three shipped features — and the PR's "diff will collapse once #1310 merges and this rebases" claim won't hold. Fix: re-merge/rebase keeping main's side for all inFakt/KSeF/core/schema-seam files, then re-verify with git diff origin/main...HEAD showing zero deletions of merged work before undrafting.

🟡 IMPORTANT (in-scope Subiekt delta)

1. apps/web/src/features/connections/components/edit-connection.schema.ts (~829-836, 1077-1101) — the three Subiekt fields are wired the pre-#1330 way (host-inlined schema clauses + StructuredConfigPatch keys). Current main's sanctioned mechanism is the plugin ConnectionConfigContribution slot — which this branch currently deletes. After the merge repair, rework the fields as a plugins/subiekt contribution instead of growing the host schema.
2. subiekt-structured-section.tsx:63,139,156-157 — unset payment state is misrepresented as "Cash". The adapter deliberately sends nothing when defaultPaymentMethod is absent (and per your own E2E, explicit selection has real consequences — paragon → 422), but the summary label shows "Cash" and the Select has no empty option, so once an operator picks a value there's no way back to the unset/legacy state. Add an explicit Not set (Subiekt default) <option value=""> (mirroring the cash-register select) and derive the summary from the real tri-state.
3. use-set-default-bank-account-mutation.ts:33-34 + subiekt-structured-section.tsx:97 — after flipping the provider default, onSuccess invalidates only connectionsQueryKeys.bankAccounts(id), but the Subiekt section reads subiektBankAccounts(id) — the owner-aware list's isDefault flags go stale ("(default in Subiekt)" sticks to the old account; the !account.isDefault skip-check operates on stale data). Invalidate both keys.
4. subiekt-structured-section.tsx:97 — void setDefaultBankAccount.mutateAsync({...}) produces an unhandled promise rejection on failure (mutateAsync re-throws even though onError toasts). Use .mutate() per the hook's own documented contract.
5. use-set-default-bank-account-mutation.ts:40-41 — the error toast is hardcoded to inFakt ("Could not update the inFakt default account…") but this PR makes Subiekt a second call site — a Subiekt bridge failure would show an inFakt error. Parameterize or neutralize the copy.
6. subiekt-adapter.factory.ts:60-62 — the comment "this call intentionally does not type-check (the adapter still has a 3-arg constructor)" is false in the final tree — the 4-arg constructor ships in this same PR. Delete the stale mid-stack narration.

🟢 SUGGESTIONS

• subiekt-invoicing.adapter.ts:515-533 — paymentFields() silently returns {} for transfer without bankAccountId; add a logger.warn so the misconfiguration is observable (nothing prevents saving that half-configured state).
• subiekt-invoicing.adapter.ts:456 — Number(accountId) unvalidated → /api/bank-accounts/NaN/default on a non-numeric id; guard and throw the config domain error.
• subiekt-structured-section.tsx:45-48, 230 — PAYMENT_METHOD_LABELS bypasses t() and the cash-register help default is Polish amid English defaults; unify.
• subiekt-structured-section.tsx:74-81 — group accounts by ownerPodmiotId, not ownerName (two Podmioty sharing a display name would merge into one optgroup).

✅ Positive observations

• Capability reuse is exactly as chartered — the adapter implements the existing core BankAccountsReader/BankAccountDefaultSetter with guard-narrowing; no new core ports snuck in. Subiekt-only concepts (Podmiot owner tag, Stanowiska Kasowe) stay plugin-local; the generic route 501s on unsupported adapters; the Subiekt controller narrows with a type-only adapter import — clean CORE↔integration boundary.
• Fiscal-safe additive request building — byte-identical legacy request for unconfigured connections, with an exemplary test matrix + live E2E with SQL read-back.
• Conventions all honored: as const unions, types in *.types.ts, shared Logger, colocated specs everywhere, @Roles('admin'), no any, no credential leakage.

Verdict: ❌ Request changes — formally moot while draft-blocked on #1310, but the merged-work reversion must be repaired first; the in-scope IMPORTANTs should land with the rebase.

[norbert-kulus-blockydevs]

Thanks for the thorough review. All findings are addressed. #1310 has since merged to main, so the draft blocker is cleared too. Pushed as a force-update (the branch was rebased — see BLOCKING below).

🔴 BLOCKING — merged-work reversion — FIXED

You were right: the branch had merged an older main and a bad conflict resolution silently reverted shipped work (#1297 issued-line snapshot, #1317 KSeF FA(3) Płatność + check-ksef-forma-platnosci-drift.mjs, #1330 buildEditConnectionSchema/ConnectionConfigContribution, plus the release-please plumbing).

Rather than re-merging and re-resolving, I reset the branch to current origin/main and re-applied only the Subiekt-scoped delta on top. The diff is now Subiekt-only (git diff origin/main..HEAD = 35 files, 0 deletions of merged work). Verified the previously-reverted work is present again: 1818000000003-add-invoice-issued-line-snapshot.ts, issuedLineSnapshot in core, buildEditConnectionSchema/ConnectionConfigContribution, and check-ksef-forma-platnosci-drift.mjs (which now runs green in check:invariants).

🟡 IMPORTANT

1. Plugin config slot, not host schema — the three fields now live in a new plugins/subiekt/subiekt-connection-config.ts ConnectionConfigContribution (mirrors KSeF), wired via platform.connectionConfig + a declare module merge into PluginEditConnectionFields. The host edit-connection.schema.ts is untouched. (The pre-existing subiektBridgeUrl/subiektTriggerModel/subiektCapabilities stay host-inlined — their web: move plugin-specific connection-config assembly behind a plugin slot #1330 migration is out of [FEATURE] Integration+Frontend — Subiekt bank-account/payment-method + Oddział/Stanowisko Kasowe per invoice #1324 scope, same as inFakt/InPost today.)
2. Payment tri-state — added an explicit Not set (Subiekt default) <option value="">; the summary now derives from the real tri-state ('' | cash | transfer), so an unset method no longer shows a misleading "Cash". readConfigToForm hydrates an absent key to '', not 'cash'.
3. Stale isDefault flags — use-set-default-bank-account-mutation now invalidates both bankAccounts(id) and subiektBankAccounts(id) on success.
4. Unhandled rejection — the section fires the default-sync via .mutate() (not void mutateAsync), per the hook's documented contract.
5. inFakt-hardcoded toast — the set-default error toast copy is now provider-neutral ("Could not update the default account… the invoicing provider still shows the previous default"); updated the two inFakt tests that asserted the old string.
6. Stale factory comment — removed the "this call intentionally does not type-check (3-arg constructor)" narration in subiekt-adapter.factory.ts; the 4-arg constructor ships here (its 4th param defaults to {}, keeping the 3-arg test call sites valid).

🟢 SUGGESTIONS (all applied)

• paymentFields() now logger.warns when transfer is configured without a bankAccountId (observable half-config).
• setDefaultBankAccount guards the Number(accountId) coercion and throws SubiektConfigException on a non-numeric id instead of POSTing /bank-accounts/NaN/default.
• Payment-method labels routed through t(); the cash-register help default is now English.
• Bank accounts group by the stable numeric ownerPodmiotId (display label still prefers ownerName), so two Podmioty sharing a name no longer merge into one optgroup.

Verification

• pnpm type-check (web, api, subiekt) — clean.
• pnpm lint + check:invariants — green (cross-context imports, service-interfaces, migration-timestamps, KSeF forma-płatności drift all pass).
• Tests: subiekt 218 passed; web 2017 passed (incl. new tri-state, group-by-id, .mutate(), NaN-guard, transfer-without-account-warn cases); api subiekt.controller 6 passed.

[norbert-kulus-blockydevs]

Consolidated review (tech-review + pr-review)

Two independent passes on the Subiekt-only delta (libs/integrations/subiekt/**, apps/api/src/integrations/http/subiekt.controller.ts + DTOs, apps/web/src/plugins/subiekt/** + the Subiekt bits of features/connections). The inFakt/KSeF churn was excluded (it belongs to the prereq PRs; #1310 is now on main and the head is rebased, so the GitHub diff already collapses to the clean Subiekt delta).

Verdict: Request changes - one confirmed blocking correctness regression + the test gap that let it through. Everything else is merge-ready polish.

The design is genuinely strong: capability reuse verified (zero changes under libs/core/, adapter implements the pre-existing BankAccountsReader / BankAccountDefaultSetter verbatim - no new ports), hexagonal boundaries clean (owner-aware view stays Subiekt-local, neutral listBankAccounts drops ownerPodmiotId/ownerName), admin-gated read-only endpoints with SSRF/IMDS guards preserved, no token leakage, and thorough tests at every layer. The "drop on missing sibling" config-sync pattern is handled correctly, and the Oddział cut is documented consistently as session-bound.

---

BLOCKING

Payment fields are stamped on paragons, which the bridge rejects - libs/integrations/subiekt/src/infrastructure/adapters/subiekt-invoicing.adapter.ts:180-181 (helper at :525-545)

issueInvoice spreads ...this.paymentFields() unconditionally, with no gate on the resolved bridgeDocumentType. But deriveNeutralDocumentType maps a buyer without a pl-nip tax id to receipt -> PA (paragon), and the bridge's own contract states paymentMethod is "not supported for documentType: "PA"" (subiekt-bridge.types.ts:121-122).

Failure scenario: a seller doing mixed B2B/B2C sets defaultPaymentMethod (e.g. transfer + bankAccountId) so their fakturas carry bank details. Every subsequent B2C order (no NIP) derives to a paragon, the adapter still attaches paymentMethod, and the bridge rejects it (400/422) -> SubiektInvoiceRejectedError, a terminal failure. B2C paragon issuance, which worked before this PR, is now broken for any connection that configures payment. This is not theoretical - the PR's own verification note ("a paragon is rejected 422") is exactly this reject; the adapter just doesn't prevent a no-NIP order from reaching it. Applies to cash too, since the constraint is on the field's presence on PA at all.

Fix: gate the payment fields on the faktura path only - pass bridgeDocumentType into paymentFields() and return {} when it is 'PA'. Keep cashRegisterFields() unconditional (the bridge documents no PA restriction on stanowiskoKasoweId - it is in fact the paragon-relevant routing field).

IMPORTANT

Test gap that hid the blocker - libs/integrations/subiekt/src/infrastructure/adapters/__tests__/subiekt-invoicing.adapter.spec.ts

The payment/cash-register stamping suite only exercises the faktura (FV) path - every asserted request derives to FV. There is no test for the paragon (PA) interaction, which is exactly the broken branch. Add: "issueInvoice does not stamp paymentMethod on a receipt/PA document even when defaultPaymentMethod is configured" (it will fail until the fix above lands - that is the point).

SUGGESTIONS / NITs

1. Side-effectful external write from a config picker (flag, not a defect) - apps/web/src/plugins/subiekt/components/subiekt-structured-section.tsx: onBankAccountChange fires setDefaultBankAccount.mutate(...), which flips Subiekt's global default bank account as a side effect of editing an OL connection. Intentional and mirrors the inFakt feat(infakt): bank-account picker with live inFakt default sync (#1303 follow-up) #1310 precedent, failures surface via toast - flagging only so it is a conscious sign-off that editing OL config mutates external ERP state.

2. Cash-register query fetches unconditionally - subiekt-structured-section.tsx: useSubiektCashRegistersQuery runs on every Subiekt connection edit, even when the payment disclosure is collapsed (the bank-accounts query is correctly gated on isTransfer). Harmless (retries off, degrades gracefully) but a wasted bridge round-trip; consider gating on disclosure-open for symmetry.

3. Mapping duplication - subiekt-invoicing.adapter.ts: listBankAccounts and listBankAccountsWithOwner map the same bridge response nearly identically. The neutral one could delegate to the owner-aware variant and strip the two owner fields, keeping the null-coercion rules in one place. Same idea for the positive-integer id guard duplicated between setDefaultBankAccount and the factory's parsePositiveIntField.

4. View-id type/doc wording - subiekt-invoicing-views.types.ts: SubiektBankAccountView.id is string (a deliberate mirror of neutral InvoicingBankAccount.id: string) while SubiektCashRegisterView.id is number, yet the file header says ids are "surfaced as the bridge-native NUMBERs ... NOT stringified". Code is consistent end-to-end; just narrow the header wording so it doesn't read as contradicting the bank-account case.

5. Endpoint templating consistency - SUBIEKT_BRIDGE_ENDPOINTS.setDefaultBankAccount(id) interpolates ${id} without encodeURIComponent (the status endpoint uses it). Safe here (id is a validated positive integer) - purely a consistency observation.

6. Multi-payer picker is warning-only - on a multi-płatnik install an account from any Podmiot can be picked and persisted; because the issuing płatnik is session-bound (unknowable to OL) a mismatched account can be mis-billed/rejected. Matches the documented [FEATURE] Integration+Frontend — Subiekt bank-account/payment-method + Oddział/Stanowisko Kasowe per invoice #1324 limitation and is surfaced honestly, so acceptable here; a follow-up could at least record the chosen account's ownerPodmiotId for a future session-aware bridge to validate.

---

Once the PA suppression lands with the covering test, this is an approve.

[norbert-kulus-blockydevs]

CI green + un-drafted

The draft blocker (#1310) is merged to main, so I marked this PR ready for review. The full pipeline now runs (the code jobs were previously skipped only because of the draft == false gate) and is green on run 28775341654:

• Build - pass
• Lint (incl. check:invariants: cross-context imports, service-interfaces, migration-timestamps, KSeF forma-płatności drift) - pass
• Type Check - pass
• Test (unit) - pass
• Integration Tests - pass (16m59s)
• PHP Unit Tests - pass

Branch is rebased on current main (git merge-base HEAD origin/main == origin/main tip); git diff origin/main..HEAD is the Subiekt-only delta with zero deletions of merged work. All review findings (BLOCKING + 6 IMPORTANT + 4 SUGGESTIONS) were addressed in the previous comment's commit. Ready for another look.

[piotrswierzy]

/pr-review — delta re-review (296eafae → 1d51d76c)

The BLOCKING reversion from my earlier Request-changes is fully resolved, and every prior in-scope IMPORTANT is addressed. Approving.

✅ GATE — merged-work reversion → RESOLVED

• Merge-base = a9fd03ab = current origin/main tip; branch is properly rebased onto main containing #1310 (b279e171 confirmed as an ancestor).
• git diff origin/main...1d51d76c --diff-filter=D returns empty — zero file deletions. The diffstat "deletions" are line-level edits within Subiekt-scoped/shared files.
• All three previously-reverted works are present: #1297 snapshot migration (1818000000003-add-invoice-issued-line-snapshot.ts), #1330 seam (buildEditConnectionSchema/ConnectionConfigContribution), #1317 KSeF Płatność.
• Three-dot diff is now Subiekt-scoped only, plus the legitimate neutral features/connections bank-account hooks/api/types and one controller registration.

✅ #1310 capability reuse → RESOLVED

BankAccountsReader/BankAccountDefaultSetter come from merged #1310 in libs/core — not re-declared under libs/integrations/subiekt. The adapter cleanly implements them alongside InvoicingPort, RegulatoryStatusReader, CorrectionIssuer. No new core ports.

✅ Prior IMPORTANTs — all addressed (code even cites the review-item numbers)

1. Unset payment "Cash" → explicit <option value="">Not set (Subiekt default)</option> + tri-state summary.
2. Stale invalidation → onSuccess invalidates both bankAccounts(id) and subiektBankAccounts(id).
3. void mutateAsync → now .mutate({...}); hook owns the single error seam.
4. inFakt-hardcoded toast → now provider-neutral.
5. False mid-stack factory comment → gone; new validateAndParseConfig/parsePositiveIntField are fiscal-safe additive (absent field → send nothing, no 'cash' default).
6. FE fields now go through the #1330 ConnectionConfigContribution slot (plugins/subiekt/subiekt-connection-config.ts); host edit-connection.schema.ts diff is empty — no inlined Subiekt clauses.

✅ Positives

Guard-narrowing controller (getCapabilityAdapter<InvoicingPort> → isSubiektInvoicingAdapter → 400 on non-Subiekt), @Roles('admin'), fiscal-safe additive request building, and a thorough spec set (controller/factory/adapter/structured-section/validator/bridge-client + the #1310 capability specs).

🟢 Minor (non-blocking)

isSubiektInvoicingAdapter is an inline module-level duck-type guard in subiekt.controller.ts, and the API layer imports the concrete SubiektInvoicingAdapter type. Acceptable for a platform-specific controller; could optionally become an exported guard from the integration package, but no correctness issue.

Verdict: ✅ Approve. One housekeeping note: the PR body still carries the stale "⚠️ Draft — depends on #1310 (must merge first)" text — please refresh it, since the draft flag is false and #1310 has merged.