feat(erli): wire per-connection Allegro category-catalog capability + credential/config validation

[norbert-kulus-blockydevs]

Summary

Part of #1381, sub-task 2 of 4 (depends on #1382, merged; see also #1384, #1387).

Implements the issue #1383 spec on top of libs/integrations/erli/src/infrastructure/http/allegro-category-catalog-client.ts (#1382):

• ErliOfferManagerAdapter: adds an optional constructor param allegroCategoryCatalog?: AllegroCategoryCatalogClient. fetchCategories/fetchCategoryParameters are declared as optional instance properties, assigned only in the constructor when the catalog client is provided — the class's static implements clause deliberately does NOT include CategoryBrowser/CategoryParametersReader (ADR-031). This keeps isCategoryBrowser/isCategoryParametersReader per-connection-accurate instead of a static, connection-independent capability.
• ErliAdapterFactory: createAdapters checks the resolved credentials for a non-empty allegroClientId and allegroClientSecret pair; when both are present it constructs an AllegroCategoryCatalogClient (environment from config.allegroEnvironment ?? 'production') and passes it into the offer-manager constructor. Otherwise undefined is passed.
• Credentials shape validator: enforces "both or neither" for allegroClientId/allegroClientSecret — rejects a payload carrying exactly one.
• Config shape validator: allegroEnvironment, when present, must be exactly 'sandbox' or 'production'.
• Verified (not assumed) that CategoriesCacheService and ListingsController's GET /listings/connections/:connectionId/categories/:categoryId/parameters need no code changes — both already resolve capabilities generically via getCapabilityAdapter + isCategoryBrowser/isCategoryParametersReader guards, so a misconfigured Erli connection behaves exactly like today's "adapter doesn't implement this capability" case (empty array / 422), not a new error path.

A note on connection.supportedCapabilities in the acceptance criteria

The issue's acceptance criteria mentions asserting connection.supportedCapabilities includes/excludes CategoryBrowser/CategoryParametersReader. That field is populated from the static, per-adapterKey AdapterMetadata.supportedCapabilities (see IntegrationsService.resolveAdapterMetadata / ConnectionController.toResponse) — it is never connection-instance-aware. Declaring these capabilities in erliAdapterManifest.supportedCapabilities would advertise them for every Erli connection regardless of Allegro-credential configuration, which is exactly the regression ADR-031 rules out (and would falsely trip the #1367 bulk-wizard gate for unconfigured Erli connections). Per ADR-031's explicit "do NOT add to the static implements/manifest" constraint, this PR keeps erliAdapterManifest.supportedCapabilities unchanged (['OfferManager', 'OrderSource']) and the real per-connection signal is exposed via isCategoryBrowser/isCategoryParametersReader on the resolved adapter instance, and via the real HTTP endpoint's 200-with-data vs 422 behaviour — both of which the integration test exercises directly, alongside confirming supportedCapabilities stays identical (and thus non-regressed) across configured/unconfigured connections.

Test plan

• pnpm --filter @openlinker/integrations-erli lint — 0 errors
• pnpm --filter @openlinker/integrations-erli type-check — clean
• pnpm --filter @openlinker/integrations-erli test — 331/331 passed (new: adapter per-instance wiring specs, factory with/without/partial Allegro-credential specs, credentials/config validator specs)
• pnpm --filter @openlinker/api type-check — clean
• pnpm --filter @openlinker/api lint — 0 errors (2 pre-existing unrelated warnings)
• pnpm --filter @openlinker/api test — 675/675 passed
• New integration test apps/api/test/integration/listings/erli-category-catalog.int-spec.ts — 3/3 passed against real Postgres/Testcontainers, exercising the REAL ErliAdapterFactory + ErliOfferManagerAdapter + AllegroCategoryCatalogClient (fetch stubbed) through the production adapter-resolution seam and the real HTTP endpoint (configured / unconfigured / partially-configured connections)
• apps/web bulk-edit-modal test ([BUG] Frontend — bulk offer wizard hides category-parameter step for Allegro (required "Stan" unsettable) #1367 gate) — 8/8 passed, unmodified
• node scripts/check-cross-context-imports.mjs — clean
• node scripts/check-service-interfaces.mjs — clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01RpsVFTpKZ1HoowEUKzbnWu

[norbert-kulus-blockydevs]

Follow-up commit pushed (07bb2b38): during doc review we found connection.supportedCapabilities is a static, per-adapterKey manifest value — not computed per connection instance — so it can't distinguish a configured-vs-unconfigured Erli connection. Added a new non-secret ErliConnectionConfig.allegroCategoryAccessEnabled?: boolean as the actual FE-visible signal instead (validated in the config shape validator, tests added). This doesn't change any of the capability-wiring logic already reviewed here — ErliOfferManagerAdapter/ErliAdapterFactory are untouched by this commit. Also fixed stale ADR-030 references to ADR-031 (renumbered to avoid a collision with #1307). ADR-031 and the implementation plan have been updated accordingly in PR #1380. Quality gate re-verified green (335/335 tests, lint, type-check).

[piotrswierzy]

/pr-review — feat(erli): per-connection Allegro category-catalog capability + validators (#1383)

This is the wiring sub-task I flagged during the #1380 plan review, and it lands the design correctly. The per-connection capability model is implemented exactly as ADR-031 prescribes, verified end-to-end. Backend is correct and mergeable. Two items: one concrete perf regression worth fixing here or as a fast-follow, and one forward-gate risk the FE sub-task (#1384) must not walk into.

Verified correct (the load-bearing checks)

• Sub-capability resolution is coherent — both consumers resolve by the base OfferManager capability, then narrow: ListingsController:433 getCapabilityAdapter<OfferManagerPort>(…'OfferManager') → :438 isCategoryParametersReader, and CategoriesCacheService:53/56 the same. Since CategoryBrowser/CategoryParametersReader are sub-capabilities (never top-level registry capabilities), Erli's OfferManager-only manifest resolves fine and the guard reads the per-instance property. Keeping them out of erliAdapterManifest.supportedCapabilities isn't just acceptable — it's required; adding a sub-capability to the registry manifest would be a category error. ✅
• Per-instance wiring is textbook ADR-031 — fetchCategories?/fetchCategoryParameters? are optional instance properties (not in implements), assigned only when the catalog client is present; the is* guards are structural (typeof … === 'function'), so unconfigured → undefined → guard false. Per-connection accurate. ✅
• Validators are both-or-neither + enum, defended twice — the credentials validator rejects an incomplete allegroClientId/allegroClientSecret pair at write time ("must include both … or neither"), the config validator constrains allegroEnvironment to sandbox|production, and the factory re-checks both (.trim()) at construction. Write-time + construction-time defense in depth. ✅
• Tests — the int-spec exercises all three credential states (configured → guards true + 200 data; unconfigured → guards false + 422; partial pair → guards false) through the real ErliAdapterFactory + adapter + client via the production resolution seam and the real HTTP endpoint. That's a proper vertical slice, not a mock dance. No any. ADR-031 boundary intact.

🟡 IMPORTANT — forward note for #1384 (FE): don't gate the Erli wizard on supportedCapabilities

Your PR description nails why connection.supportedCapabilities (static, per-adapterKey manifest) can't reflect the per-connection capability — correct. But there's an asymmetry the FE sub-task has to handle deliberately: Allegro (#1370) advertises its sub-capabilities statically in its manifest, so the existing FE bulk-wizard gate (#1367) reads supportedCapabilities.includes('CategoryBrowser'). Erli, by design, never will. So if #1384 reuses that same gate for the Erli offer wizard, a configured Erli connection will silently not show the category/parameters steps — the feature ships "wired but invisible." #1384 must drive the Erli gate off a genuine per-connection signal (probe the parameters endpoint: 200 → show, 422 → plain-text fallback; or a per-connection effective-capability read) — not the static manifest. Flagging here so the seam is on record before the FE PR; nothing to change in this PR.

🟡 IMPORTANT — token cache is per-request (realizes my #1388 forward note)

buildAllegroCategoryCatalog constructs a fresh AllegroCategoryCatalogClient on every createAdapters call, and adapters are built fresh per getCapabilityAdapter call (no memoization). So the client's per-instance app-token cache — the single-flight + expiry-aware logic added in #1388 — lives exactly one request and delivers zero cross-request benefit. Impact is asymmetric:

• fetchCategories is shielded by CategoriesCacheService's 24h DB cache → underlying client (and its OAuth round-trip) is hit only on cache-miss. Low.
• fetchCategoryParameters is uncached at the controller (pre-existing gap shared with Allegro) → every parameters request pays a full extra client_credentials OAuth round-trip (2 upstream calls instead of 1). That's a latency + Allegro-rate-limit cost, and a regression vs Allegro's shared AllegroConnectionTokenState.

The fix is cheap and the seam is already here: createAdapters already receives host.cache (CachePort param). Hoist the app-token cache to it (or a module-scope map keyed by clientId) so the token survives across per-request adapter instances. Fine as a fast-follow if you'd rather not widen this PR, but it should be tracked, not lost.

🟢 Minor

• The two plugin validators are named *.adapter.ts and implement the host *ShapeValidatorPorts — consistent with the existing Allegro/PrestaShop validator precedent. Good.
• Nice touch re-checking the credential pair at construction even though the write-time validator already guards it — belt-and-suspenders against a connection whose credentials were written before the validator existed.

Verdict

🔄 Approve with changes — the backend design is correct and directly implements the ADR-031 per-instance model I asked for in the #1380 review; it's mergeable onto the epic branch as-is (mergeable_state: clean). Priority items: (1) carry the FE-gating note into #1384 so a configured Erli connection actually shows the category UI, and (2) hoist the app-token cache to host.cache (here or a tracked fast-follow) so category-parameter browsing doesn't pay an OAuth round-trip per request.

[norbert-kulus-blockydevs]

Consolidated tech-review + pr-review (two independent passes)

Two independent automated reviews were run against the current HEAD (07bb2b38), each verifying the actual code (not just the PR description) and running the quality gate live in an isolated checkout. Both converge on the same verdict.

On Piotr's prior review

Confirmed via the GitHub API that his review's commit_id matches the current HEAD — it is not stale, it already reflects the allegroCategoryAccessEnabled fix commit. His two IMPORTANT items remain open by design (deferred, not blockers for this PR):

1. The bulk-wizard's supportedCapabilities gate won't surface the Erli category UI even when configured — informational note for #1384, nothing to fix here.
2. AllegroCategoryCatalogClient's token cache is per-request (no adapter-instance caching in IIntegrationsService.getCapabilityAdapter anywhere in this codebase), so every fetchCategoryParameters call pays a full OAuth round-trip. Real, confirmed independently, worth a tracked fast-follow via host.cache.

Independently verified claims

• connection.supportedCapabilities is genuinely static per-adapterKey — confirmed by reading connection.controller.ts's toResponse, which resolves it from resolveAdapterMetadata({ platformType, adapterKey }), never per-connection-instance. The allegroCategoryAccessEnabled config flag is the correct, narrow, plugin-local fix.
• ADR-031's static-implements constraint holds in code — ErliOfferManagerAdapter's implements clause has no CategoryBrowser/CategoryParametersReader; fetchCategories?/fetchCategoryParameters? are optional instance properties assigned only in the constructor when allegroCategoryCatalog is provided. isCategoryBrowser/isCategoryParametersReader are structural, so this is genuinely per-instance.
• No CORE changes; hexagonal boundary respected — everything confined to libs/integrations/erli + one new int-spec.

Quality gate — run live in isolated worktrees by both reviews (not trusted from the PR description)

• @openlinker/integrations-erli: lint clean, type-check clean, 335/335 tests passed.
• @openlinker/api: lint/type-check clean; new erli-category-catalog.int-spec.ts 3/3 passed against real Testcontainers Postgres, genuinely exercising the real getCapabilityAdapter seam and HTTP endpoint.
• bulk-edit-modal.test.tsx (#1367 gate), unmodified file, run directly — passed (one pass ran the full FE suite: 2029/2029).
• Repo invariants (check-cross-context-imports, check-service-interfaces, check-migration-timestamps) all green.

New findings from this pass (neither blocking)

1. ErliAdapterFactory.createAdapters resolves credentials twice per call (createHttpClient resolves for apiKey, then buildAllegroCategoryCatalog resolves again for the Allegro pair) — a second DB round-trip + decrypt on every adapter construction. Same class of issue as Piotr's token-cache point; worth fixing together, here or as a fast-follow.
2. allegroCategoryAccessEnabled has zero producers today — by design, scoped to #1384 per the commit message and ADR-031's "Correction" section. Flagging explicitly as a hard dependency to verify when #1384 lands: the write path there MUST set/clear this flag atomically alongside allegroClientId/allegroClientSecret, or the two state sources can drift.
3. (Minor, non-blocking) the epic branch hasn't picked up ADR-031 from main yet (still on PR #1380) — worth a sync before/shortly after merge, not a reason to hold this PR.

Verdict

Approve with changes. No blocking issues on either independent pass. Mergeable onto the epic branch as-is; the token-cache hoist + double-credential-resolve are good candidates to bundle into one fast-follow rather than reopening this PR.

[norbert-kulus-blockydevs]

Review follow-up (commit 771c1279)

Addressed both open IMPORTANT findings from the review round (Piotr's pass + the consolidated tech-review/pr-review pass). No BLOCKER or SUGGESTION items were left on the table — everything actionable in this PR's scope has been fixed; the remaining items were explicitly informational/deferred by design and are called out below.

Fixed

1. Token cache was per-request, not shared (Piotr, IMPORTANT) — AllegroCategoryCatalogClient cached its client_credentials app token only in-memory, but ErliAdapterFactory builds a fresh client per getCapabilityAdapter call, so every fetchCategoryParameters request paid a full extra OAuth round-trip. The client now accepts an optional CachePort (host.cache) and persists the acquired token there, keyed by clientId with a TTL matching the token's remaining lifetime, so it survives across per-request instances and across processes. ErliAdapterFactory threads its existing cache param through to the client. Falls back to the pre-existing in-memory-only behaviour when no cache is supplied (backward compatible). New unit tests cover: write-through on acquire, reuse across two separate client instances sharing one CachePort, and re-acquisition when the cached entry is expired.

2. createAdapters resolved credentials twice per call (self-review, IMPORTANT) — createHttpClient resolved credentials for apiKey, then a second resolveCredentials call resolved again for the Allegro pair — a second credentialsRef DB round-trip + decrypt on every adapter construction. Collapsed into a single resolve, shared by both the Erli http client and the optional Allegro category-catalog client via a new private buildHttpClient helper. New test asserts credentialsResolver.get is called exactly once per createAdapters call.

Not changed (informational / explicitly deferred by design, confirmed still correct)

• FE-gating forward note for [TASK] Frontend — Erli connection credentials checkbox + offer wizard category/parameters steps #1384 (Piotr, IMPORTANT) — correctly scoped to the FE sub-task, nothing to change in this backend PR.
• allegroCategoryAccessEnabled has zero producers today — by design, the write path lands with [TASK] Frontend — Erli connection credentials checkbox + offer wizard category/parameters steps #1384; flagged there as a hard dependency (must be set/cleared atomically with the Allegro credential pair).
• Epic branch hasn't picked up ADR-031 renumbering from main yet — a branch-sync housekeeping item, not something to fix inside this PR's diff.

Quality gate (re-verified on HEAD 771c1279)

• @openlinker/integrations-erli: lint clean, type-check clean, 340/340 tests passed (5 new: cache-hoist behaviour + single-resolve).
• @openlinker/api: lint clean (2 pre-existing unrelated warnings), type-check clean.
• erli-category-catalog.int-spec.ts — 3/3 passed against real Testcontainers Postgres, exercising the real adapter-resolution seam end-to-end.
• check-cross-context-imports / check-service-interfaces — clean.