mousehold/docs/connectors.md

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.