Add upstream error classification and optional persistent cache for finance connectors

[Copilot]

Summary

Closes the remaining gaps in the finance connector cluster: upstream error classification and an optional persistent cache strategy. Live authenticated connectors, query pagination, and date filters were already in place and verified.

Changes

• Error classification (src/observability/errors.js): maps every upstream failure to a stable category (AUTH, RATE_LIMIT, TIMEOUT, NETWORK, UPSTREAM_CLIENT_ERROR, UPSTREAM_SERVER_ERROR, UNKNOWN) with status and retryable.
• Schema: FinanceUpstreamError now exposes category, status, and retryable alongside source, code, and message.
• HTTP client: transport failures are tagged timeout vs network so they can be classified without message parsing; retry-failure metrics carry the kind label.
• Observability: new finance_upstream_errors_total{source,operation,category,retryable} counter; cache counters labelled with the active store; classified fields included in error logs.
• Optional persistent cache (src/cache/index.js): FINANCE_CACHE_STORE=memory|file with FINANCE_CACHE_FILE. The file store survives restarts and ignores expired or corrupt data. Payloads containing upstream errors are no longer cached, so a transient outage is not pinned for the whole TTL.
• Docs: README env-var table, observability, and caching sections updated; .cache/ added to .gitignore.

Testing

• npm test — 42/42 passing, including new test/resilience.test.js covering classification, error metrics, and both cache stores.
• CodeQL: 0 alerts.

Note: this repository has no Playwright setup or browser UI to exercise, so no Playwright screenshots are attached.

[Copilot]

🟡 Changes recommended

The new file-backed cache performs synchronous disk writes in resolver hot paths, which can block the Node event loop and materially impact latency when enabled.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the finance connector layer with (1) stable upstream error classification surfaced through the GraphQL schema and observability metrics/logs, and (2) an optional persistent (file-backed) cache store selected via environment configuration.

Changes:

• Adds upstream error classification (category, status, retryable) and exposes it via FinanceUpstreamError in the schema, plus per-category error metrics.
• Enhances the HTTP client to tag transport failures as timeout vs network, enabling classification without message parsing and adding kind to retry-failure metrics.
• Introduces pluggable resolver caching (memory default, optional file) and adds tests/docs for resilience, classification, and cache behavior.

File summaries

File	Description
test/resilience.test.js	New tests covering error classification, metrics counting, and memory/file cache behavior.
test/graphql.test.js	Updates GraphQL selections/assertions to include the new FinanceUpstreamError fields.
src/services/financeService.js	Replaces ad-hoc upstream error shaping with classifyUpstreamError, adds error counter, and switches caching to a pluggable store with store-labelled cache metrics.
src/schema.js	Extends FinanceUpstreamError with category, status, and retryable.
src/observability/errors.js	New module implementing stable upstream error categorization and retryability inference.
src/connectors/httpClient.js	Tags transport failures with kind and emits metrics including the kind label.
src/config/finance.js	Adds FINANCE_CACHE_STORE and FINANCE_CACHE_FILE configuration plumbing.
src/cache/index.js	New cache store implementations (memory + persistent file) and a selector helper.
README.md	Documents new env vars, caching strategy, and error classification/metrics.
.gitignore	Ignores .cache/ (default location for persistent cache file).

Review details

• Files reviewed: 9/10 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.