# Connector Boundary

Mousehold treats connectors as evidence producers. A connector submits `RawObservation`
payloads; the backend turns them into reviewable `FinancialEvent` candidates and links
the source evidence.

## Local-First Rule

Bank and mailbox credentials should stay in the local agent where possible.
The API stores:

- connection type and display name
- owner user and household
- sync status and last error
- a local secret reference, not the secret itself
- normalized observations

## Current PoC Routes

- Manual entry: `POST /observations/manual`
- Generic normalized import: `POST /observations/import`
- Local-agent batch sync: `POST /observations/sync`
- Connector metadata: `POST /connections`
- Local-agent registration: `POST /local-agent/register`
- Browser IMAP folder listing: `POST /agent/imap/folders`
- Browser IMAP scan: `POST /agent/imap/scan`
- PayPal CSV statement parsing: `POST /agent/paypal/statement/parse`
- Klarna CSV statement parsing: `POST /agent/klarna/statement/parse`

## Data Source Mapping

- Bank CSV, FinTS, PSD2: confirmed cash movement observations. FinTS fetching is implemented in the local agent.
- PayPal CSV: confirmed PayPal account observations.
- PayPal email: announced or outstanding purchase/payment evidence.
- Klarna email: usually outstanding obligation evidence.
- Order confirmation email: announced purchase evidence.

Bank debits that fund PayPal, Klarna, or cards should be linked as settlements or
liability payments instead of duplicated as new expenses.

## Reconciliation

The reconciliation service computes reviewable suggestions from imported events
instead of linking automatically. Current suggestions cover:

- PayPal/Klarna/order email evidence matched to PayPal or Klarna statement rows
- PayPal/Klarna statement rows matched to FinTS, bank CSV, or PSD2 cash movement
- exact amount/currency matches with date windows, party overlap, provider names,
  and shared references

Accepting a suggestion creates an event relation, attaches the confirming
observation to the primary event as evidence, and upgrades the primary event to
`confirmed` when the confirming event is confirmed. The confirming event is kept
for auditability; later UI cleanup can decide how aggressively to collapse or
hide duplicate-looking rows.

## IMAP Flow

The web app has a `Mail` panel for IMAP proof-of-concept imports. It sends IMAP
credentials to the configured agent route for that request only, selects the
requested folder read-only, scans recent messages, and returns previews plus
normalized observations. The backend stores observations only after the user
clicks import.

The parser currently recognizes EUR amounts, simple due-date phrases, Klarna
references, PayPal transaction IDs, order numbers, and invoice numbers. Email
evidence is classified as `announced` unless it is a Klarna or due-date driven
promised payment, which becomes `outstanding`. Confirmed cash movement should
still come from FinTS, bank CSV, PSD2, or PayPal/Klarna statement CSV.

## PayPal Statement Flow

The active PayPal path is statement and email based.

The `Statements` panel supports PayPal Activity Download CSV exports. It
recognizes fields such as `Date`, `Name`, `Type`, `Status`, `Currency`, `Gross`,
`Fee`, `Net`, and `Transaction ID`, then imports confirmed `paypal_csv`
observations.

PayPal emails remain early evidence for announced or outstanding obligations.
Later PayPal statements and bank debits should confirm or settle those events
instead of creating duplicate household expenses.

## Klarna Statement Flow

The `Statements` panel also supports Klarna CSV. It handles Klarna Merchant
settlement reports with a summary section followed by a `type`/`amount`
transaction table, and a simpler consumer-style CSV with date, description,
amount, currency, reference, and type columns. Klarna CSV observations use
`source_type=klarna_csv` and are treated as confirmed statement evidence, while
Klarna emails remain the early outstanding/announced signal.