feat: pluggable bank sync connector architecture (closes #75)

[pabloDarkmoon24]

Bank Sync Connector Architecture — Closes #75

Summary

Implements a fully pluggable bank integration system via the Indian Account Aggregator (AA) framework, meeting all acceptance criteria and designed to scale to any AA provider.

What's included

1. BankConnector — Abstract Base Class (services/bank_connector.py)

• Clear contract: initiate_consent → confirm_consent → fetch_accounts → import_transactions → refresh
• Typed domain objects: BankTransaction, BankAccount, ConsentHandle
• Connector registry with get_connector(provider) factory and register_connector() for extension

2. MockConnector — Full in-memory implementation

• No external calls — deterministic, seeded test data
• 8 realistic INR transactions (salary, groceries, subscriptions, utilities)
• Used for local development and automated tests

3. SetuAAConnector — Real Indian AA integration

• Implements the ReBIT AA spec via Setu partner API
• Full consent lifecycle: initiate → user approves → confirm → fetch accounts
• FI data request with exponential-backoff polling until READY
• HMAC-SHA256 request signing per Setu spec
• Normalises Setu response → BankTransaction domain objects
• Configurable via env vars: SETU_CLIENT_ID, SETU_CLIENT_SECRET, SETU_BASE_URL

4. Database models (models.py + schema.sql)

• BankAccount — stores linked accounts with consent metadata
• BankTransaction — stores normalised transactions, linkable to existing Expense rows
• Unique constraints prevent duplicate transactions on re-sync
• Indexed for fast date-range queries

5. REST API (routes/bank.py)

Method	Endpoint	Description
POST	/api/bank/connect	Start consent flow → returns redirect URL
GET	/api/bank/callback	AA redirect after user approval
GET	/api/bank/accounts	List linked accounts
DELETE	/api/bank/accounts/:id	Revoke & remove account
POST	/api/bank/accounts/:id/import	Full historical import
POST	/api/bank/accounts/:id/refresh	Incremental sync
GET	/api/bank/accounts/:id/transactions	List stored transactions

6. Tests (tests/test_bank_connector.py)

• 11 tests covering the full MockConnector lifecycle
• Validates transaction uniqueness, date ranges, type safety, registry

How to add a new provider

from app.services.bank_connector import BankConnector, register_connector

class FinvuConnector(BankConnector):
    provider_name = "Finvu"
    # implement the 5 abstract methods...

register_connector("finvu", FinvuConnector)

Environment variables required (Setu)

SETU_CLIENT_ID=your_client_id
SETU_CLIENT_SECRET=your_client_secret
SETU_BASE_URL=https://fiu-uat.setu.co   # or prod URL

Testing locally with Mock

from app.services.bank_connector import get_connector
from datetime import date

connector = get_connector("mock")
handle = connector.initiate_consent("user-123", "http://localhost/callback")
handle = connector.confirm_consent(handle, {})
accounts = connector.fetch_accounts(handle)
transactions = connector.import_transactions(handle, accounts[0].account_id,
                                             date(2024, 1, 1), date.today())

Closes #75