broker-sync/broker_sync/providers/fidelity_planviewer.py

"""Fidelity UK PlanViewer provider — workplace pension backfill + monthly sync.

PlanViewer has no public individual-member API; Fidelity International's
developer portal only catalogues B2B scheme/HR endpoints. The SPA (at
``pv.planviewer.fidelity.co.uk``) does call a private JSON backend at
``prd.wiciam.fidelity.co.uk/cvmfe/api/*`` — we reverse-engineer that and feed
it through a Playwright-maintained session.

## Session lifecycle

1. **One-off seed** (``broker-sync fidelity-seed``): Viktor runs a headed
   Chromium, logs in (password + memorable word + MFA), clicks "Remember
   device". Playwright dumps the resulting ``storage_state.json`` (cookies +
   localStorage) which we stash in Vault.

2. **Monthly cron**: loads storage_state, boots headless Chromium, navigates
   to the SPA once to let it refresh rolling session tokens, intercepts the
   first outbound XHR to capture the ``sid``/``fid``/``tbid``/``rid`` headers,
   then closes the browser and continues with plain httpx.

3. **Re-seed trigger**: on any 401 from the JSON API we raise
   :class:`FidelitySessionError`; the CronJob fails loudly and Prometheus
   alerts Viktor to run the seed command again.

Remember-device typically survives 30-90 days on Fidelity, so we expect the
re-seed to be a quarterly manual step — not monthly.

## Data model

Salary-sacrifice scheme with two contribution streams (employee + employer),
both pre-tax. Each contribution buys units across one or more funds. We emit:

- ``DEPOSIT`` per employee-or-employer cash inflow (external_id carries
  ``fidelity:<doc-id>:<source>``).
- ``BUY`` per fund-unit purchase (``symbol`` = fund ISIN or Fidelity code,
  ``quantity`` = units, ``unit_price`` = GBp or GBP per unit).

All currency is GBP. The single WF account is ``AccountType.WORKPLACE_PENSION``.
"""
from __future__ import annotations

import logging
from collections.abc import AsyncIterator
from datetime import datetime
from typing import NamedTuple

from broker_sync.models import Account, AccountType, Activity

log = logging.getLogger(__name__)

ACCOUNT_ID = "fidelity-workplace-pension"
_CCY = "GBP"

# PlanViewer's private JSON backend. Endpoint paths are reverse-engineered from
# Viktor's DevTools cURLs and validated by the unit tests' fixtures.
_API_BASE = "https://prd.wiciam.fidelity.co.uk"


class FidelityCreds(NamedTuple):
    """Credentials + session state required to hit the PlanViewer backend."""
    storage_state_path: str
    plan_id: str
    headless: bool = True


class FidelitySessionError(Exception):
    """Raised when PlanViewer returns 401/403 — storage_state is stale.

    Recovery: run ``broker-sync fidelity-seed`` in a browser to refresh the
    storage_state blob in Vault, then re-run the CronJob.
    """


class FidelityProviderConfigError(Exception):
    """Raised when the provider is asked to run but required config (plan id,
    storage_state path) is missing or obviously wrong."""


class FidelityPlanViewerProvider:
    """Read-only provider against Fidelity UK PlanViewer.

    Per the Provider protocol consumed by ``broker_sync.pipeline``:

    - ``.accounts()`` advertises the single workplace-pension WF account we
      write into.
    - ``.fetch(since, before)`` is an async generator that yields canonical
      ``Activity`` objects.
    """
    name = "fidelity-planviewer"

    def __init__(self, creds: FidelityCreds) -> None:
        self._creds = creds

    def accounts(self) -> list[Account]:
        return [
            Account(
                id=ACCOUNT_ID,
                name="Fidelity UK Pension",
                account_type=AccountType.WORKPLACE_PENSION,
                currency=_CCY,
                provider=self.name,
            ),
        ]

    async def fetch(
        self,
        *,
        since: datetime | None = None,
        before: datetime | None = None,
    ) -> AsyncIterator[Activity]:
        """Yield Activity records.

        Implementation blocked on captured endpoint shapes. Viktor will paste
        the transactions + holdings POST cURLs from DevTools, then we wire the
        parsers and this method lights up.
        """
        # Guard against accidentally running before endpoint reverse-engineering
        # is done — makes the CronJob fail loudly with an actionable message
        # rather than silently importing nothing.
        raise FidelityProviderConfigError(
            "Fidelity ingest not yet enabled — PlanViewer endpoint paths have "
            "not been captured. Paste the POST cURLs from DevTools for the "
            "transactions + holdings views and re-apply the provider update."
        )
        # Unreachable yield — keeps the return type AsyncIterator[Activity]
        # once the raise above is removed.
        if False:  # pragma: no cover
            yield