refactor: Unify leggen and leggend packages into single leggen package

- Merge leggend API components into leggen (api/, services/, background/)
- Replace leggend command with 'leggen server' subcommand
- Consolidate configuration systems into leggen.utils.config
- Update environment variables: LEGGEND_API_URL -> LEGGEN_API_URL
- Rename LeggendAPIClient -> LeggenAPIClient
- Update all documentation, Docker configs, and compose files
- Fix all import statements and test references
- Remove duplicate utility files and clean up package structure

All tests passing (101/101), linting clean, server functionality preserved.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

leggen/api/models/accounts.py

@@ -0,0 +1,77 @@
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+
+from pydantic import BaseModel
+
+
+class AccountBalance(BaseModel):
+    """Account balance model"""
+
+    amount: float
+    currency: str
+    balance_type: str
+    last_change_date: Optional[datetime] = None
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class AccountDetails(BaseModel):
+    """Account details model"""
+
+    id: str
+    institution_id: str
+    status: str
+    iban: Optional[str] = None
+    name: Optional[str] = None
+    currency: Optional[str] = None
+    created: datetime
+    last_accessed: Optional[datetime] = None
+    balances: List[AccountBalance] = []
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class AccountUpdate(BaseModel):
+    """Account update model"""
+
+    name: Optional[str] = None
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class Transaction(BaseModel):
+    """Transaction model"""
+
+    transaction_id: str  # NEW: stable bank-provided transaction ID
+    internal_transaction_id: Optional[str] = None  # OLD: unstable GoCardless ID
+    institution_id: str
+    iban: Optional[str] = None
+    account_id: str
+    transaction_date: datetime
+    description: str
+    transaction_value: float
+    transaction_currency: str
+    transaction_status: str  # "booked" or "pending"
+    raw_transaction: Dict[str, Any]
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class TransactionSummary(BaseModel):
+    """Transaction summary for lists"""
+
+    transaction_id: str  # NEW: stable bank-provided transaction ID
+    internal_transaction_id: Optional[str] = None
+    date: datetime
+    description: str
+    amount: float
+    currency: str
+    status: str
+    account_id: str
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}

leggen/api/models/banks.py

@@ -0,0 +1,52 @@
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class BankInstitution(BaseModel):
+    """Bank institution model"""
+
+    id: str
+    name: str
+    bic: Optional[str] = None
+    transaction_total_days: int
+    countries: List[str]
+    logo: Optional[str] = None
+
+
+class BankConnectionRequest(BaseModel):
+    """Request to connect to a bank"""
+
+    institution_id: str
+    redirect_url: Optional[str] = "http://localhost:8000/"
+
+
+class BankRequisition(BaseModel):
+    """Bank requisition/connection model"""
+
+    id: str
+    institution_id: str
+    status: str
+    status_display: Optional[str] = None
+    created: datetime
+    link: str
+    accounts: List[str] = []
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class BankConnectionStatus(BaseModel):
+    """Bank connection status response"""
+
+    bank_id: str
+    bank_name: str
+    status: str
+    status_display: str
+    created_at: datetime
+    requisition_id: str
+    accounts_count: int
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}

leggen/api/models/common.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+
+class APIResponse(BaseModel):
+    """Base API response model"""
+
+    success: bool = True
+    message: Optional[str] = None
+    data: Optional[Any] = None
+
+
+class ErrorResponse(BaseModel):
+    """Error response model"""
+
+    success: bool = False
+    message: str
+    error_code: Optional[str] = None
+    details: Optional[Dict[str, Any]] = None
+
+
+class PaginatedResponse(BaseModel):
+    """Paginated response model"""
+
+    success: bool = True
+    data: list
+    pagination: Dict[str, Any]
+    message: Optional[str] = None

leggen/api/models/notifications.py

@@ -0,0 +1,51 @@
+from typing import Optional, List
+
+from pydantic import BaseModel
+
+
+class DiscordConfig(BaseModel):
+    """Discord notification configuration"""
+
+    webhook: str
+    enabled: bool = True
+
+
+class TelegramConfig(BaseModel):
+    """Telegram notification configuration"""
+
+    token: str
+    chat_id: int
+    enabled: bool = True
+
+
+class NotificationFilters(BaseModel):
+    """Notification filters configuration"""
+
+    case_insensitive: List[str] = []
+    case_sensitive: Optional[List[str]] = None
+
+
+class NotificationSettings(BaseModel):
+    """Complete notification settings"""
+
+    discord: Optional[DiscordConfig] = None
+    telegram: Optional[TelegramConfig] = None
+    filters: NotificationFilters = NotificationFilters()
+
+
+class NotificationTest(BaseModel):
+    """Test notification request"""
+
+    service: str  # "discord" or "telegram"
+    message: str = "Test notification from Leggen"
+
+
+class NotificationHistory(BaseModel):
+    """Notification history entry"""
+
+    id: str
+    service: str
+    message: str
+    status: str  # "sent", "failed"
+    sent_at: str
+    error: Optional[str] = None

leggen/api/models/sync.py

@@ -0,0 +1,55 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class SyncRequest(BaseModel):
+    """Request to trigger a sync"""
+
+    account_ids: Optional[list[str]] = None  # If None, sync all accounts
+    force: bool = False  # Force sync even if recently synced
+
+
+class SyncStatus(BaseModel):
+    """Sync operation status"""
+
+    is_running: bool
+    last_sync: Optional[datetime] = None
+    next_sync: Optional[datetime] = None
+    accounts_synced: int = 0
+    total_accounts: int = 0
+    transactions_added: int = 0
+    errors: list[str] = []
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
+
+
+class SyncResult(BaseModel):
+    """Result of a sync operation"""
+
+    success: bool
+    accounts_processed: int
+    transactions_added: int
+    transactions_updated: int
+    balances_updated: int
+    duration_seconds: float
+    errors: list[str] = []
+    started_at: datetime
+    completed_at: datetime
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class SchedulerConfig(BaseModel):
+    """Scheduler configuration model"""
+
+    enabled: bool = True
+    hour: Optional[int] = 3
+    minute: Optional[int] = 0
+    cron: Optional[str] = None  # Custom cron expression
+
+    class Config:
+        extra = "forbid"

leggen/api/routes/accounts.py

@@ -0,0 +1,356 @@
+from typing import Optional, List, Union
+from fastapi import APIRouter, HTTPException, Query
+from loguru import logger
+
+from leggen.api.models.common import APIResponse
+from leggen.api.models.accounts import (
+    AccountDetails,
+    AccountBalance,
+    Transaction,
+    TransactionSummary,
+    AccountUpdate,
+)
+from leggen.services.database_service import DatabaseService
+
+router = APIRouter()
+database_service = DatabaseService()
+
+
+@router.get("/accounts", response_model=APIResponse)
+async def get_all_accounts() -> APIResponse:
+    """Get all connected accounts from database"""
+    try:
+        accounts = []
+
+        # Get all account details from database
+        db_accounts = await database_service.get_accounts_from_db()
+
+        # Process accounts found in database
+        for db_account in db_accounts:
+            try:
+                # Get latest balances from database for this account
+                balances_data = await database_service.get_balances_from_db(
+                    db_account["id"]
+                )
+
+                # Process balances
+                balances = []
+                for balance in balances_data:
+                    balances.append(
+                        AccountBalance(
+                            amount=balance["amount"],
+                            currency=balance["currency"],
+                            balance_type=balance["type"],
+                            last_change_date=balance.get("timestamp"),
+                        )
+                    )
+
+                accounts.append(
+                    AccountDetails(
+                        id=db_account["id"],
+                        institution_id=db_account["institution_id"],
+                        status=db_account["status"],
+                        iban=db_account.get("iban"),
+                        name=db_account.get("name"),
+                        currency=db_account.get("currency"),
+                        created=db_account["created"],
+                        last_accessed=db_account.get("last_accessed"),
+                        balances=balances,
+                    )
+                )
+
+            except Exception as e:
+                logger.error(
+                    f"Failed to process database account {db_account['id']}: {e}"
+                )
+                continue
+
+        return APIResponse(
+            success=True,
+            data=accounts,
+            message=f"Retrieved {len(accounts)} accounts from database",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get accounts: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get accounts: {str(e)}"
+        ) from e
+
+
+@router.get("/accounts/{account_id}", response_model=APIResponse)
+async def get_account_details(account_id: str) -> APIResponse:
+    """Get details for a specific account from database"""
+    try:
+        # Get account details from database
+        db_account = await database_service.get_account_details_from_db(account_id)
+
+        if not db_account:
+            raise HTTPException(
+                status_code=404, detail=f"Account {account_id} not found in database"
+            )
+
+        # Get latest balances from database for this account
+        balances_data = await database_service.get_balances_from_db(account_id)
+
+        # Process balances
+        balances = []
+        for balance in balances_data:
+            balances.append(
+                AccountBalance(
+                    amount=balance["amount"],
+                    currency=balance["currency"],
+                    balance_type=balance["type"],
+                    last_change_date=balance.get("timestamp"),
+                )
+            )
+
+        account = AccountDetails(
+            id=db_account["id"],
+            institution_id=db_account["institution_id"],
+            status=db_account["status"],
+            iban=db_account.get("iban"),
+            name=db_account.get("name"),
+            currency=db_account.get("currency"),
+            created=db_account["created"],
+            last_accessed=db_account.get("last_accessed"),
+            balances=balances,
+        )
+
+        return APIResponse(
+            success=True,
+            data=account,
+            message=f"Account details retrieved from database for {account_id}",
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get account details for {account_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get account details: {str(e)}"
+        ) from e
+
+
+@router.get("/accounts/{account_id}/balances", response_model=APIResponse)
+async def get_account_balances(account_id: str) -> APIResponse:
+    """Get balances for a specific account from database"""
+    try:
+        # Get balances from database instead of GoCardless API
+        db_balances = await database_service.get_balances_from_db(account_id=account_id)
+
+        balances = []
+        for balance in db_balances:
+            balances.append(
+                AccountBalance(
+                    amount=balance["amount"],
+                    currency=balance["currency"],
+                    balance_type=balance["type"],
+                    last_change_date=balance.get("timestamp"),
+                )
+            )
+
+        return APIResponse(
+            success=True,
+            data=balances,
+            message=f"Retrieved {len(balances)} balances for account {account_id}",
+        )
+
+    except Exception as e:
+        logger.error(
+            f"Failed to get balances from database for account {account_id}: {e}"
+        )
+        raise HTTPException(
+            status_code=404, detail=f"Failed to get balances: {str(e)}"
+        ) from e
+
+
+@router.get("/balances", response_model=APIResponse)
+async def get_all_balances() -> APIResponse:
+    """Get all balances from all accounts in database"""
+    try:
+        # Get all accounts first to iterate through them
+        db_accounts = await database_service.get_accounts_from_db()
+
+        all_balances = []
+        for db_account in db_accounts:
+            try:
+                # Get balances for this account
+                db_balances = await database_service.get_balances_from_db(
+                    account_id=db_account["id"]
+                )
+
+                # Process balances and add account info
+                for balance in db_balances:
+                    balance_data = {
+                        "id": f"{db_account['id']}_{balance['type']}",  # Create unique ID
+                        "account_id": db_account["id"],
+                        "balance_amount": balance["amount"],
+                        "balance_type": balance["type"],
+                        "currency": balance["currency"],
+                        "reference_date": balance.get(
+                            "timestamp", db_account.get("last_accessed")
+                        ),
+                        "created_at": db_account.get("created"),
+                        "updated_at": db_account.get("last_accessed"),
+                    }
+                    all_balances.append(balance_data)
+
+            except Exception as e:
+                logger.error(
+                    f"Failed to get balances for account {db_account['id']}: {e}"
+                )
+                continue
+
+        return APIResponse(
+            success=True,
+            data=all_balances,
+            message=f"Retrieved {len(all_balances)} balances from {len(db_accounts)} accounts",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get all balances: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get balances: {str(e)}"
+        ) from e
+
+
+@router.get("/balances/history", response_model=APIResponse)
+async def get_historical_balances(
+    days: Optional[int] = Query(
+        default=365, le=1095, ge=1, description="Number of days of history to retrieve"
+    ),
+    account_id: Optional[str] = Query(
+        default=None, description="Filter by specific account ID"
+    ),
+) -> APIResponse:
+    """Get historical balance progression calculated from transaction history"""
+    try:
+        # Get historical balances from database
+        historical_balances = await database_service.get_historical_balances_from_db(
+            account_id=account_id, days=days or 365
+        )
+
+        return APIResponse(
+            success=True,
+            data=historical_balances,
+            message=f"Retrieved {len(historical_balances)} historical balance points over {days} days",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get historical balances: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get historical balances: {str(e)}"
+        ) from e
+
+
+@router.get("/accounts/{account_id}/transactions", response_model=APIResponse)
+async def get_account_transactions(
+    account_id: str,
+    limit: Optional[int] = Query(default=100, le=500),
+    offset: Optional[int] = Query(default=0, ge=0),
+    summary_only: bool = Query(
+        default=False, description="Return transaction summaries only"
+    ),
+) -> APIResponse:
+    """Get transactions for a specific account from database"""
+    try:
+        # Get transactions from database instead of GoCardless API
+        db_transactions = await database_service.get_transactions_from_db(
+            account_id=account_id,
+            limit=limit,
+            offset=offset,
+        )
+
+        # Get total count for pagination info
+        total_transactions = await database_service.get_transaction_count_from_db(
+            account_id=account_id,
+        )
+
+        data: Union[List[TransactionSummary], List[Transaction]]
+
+        if summary_only:
+            # Return simplified transaction summaries
+            data = [
+                TransactionSummary(
+                    transaction_id=txn["transactionId"],  # NEW: stable bank-provided ID
+                    internal_transaction_id=txn.get("internalTransactionId"),
+                    date=txn["transactionDate"],
+                    description=txn["description"],
+                    amount=txn["transactionValue"],
+                    currency=txn["transactionCurrency"],
+                    status=txn["transactionStatus"],
+                    account_id=txn["accountId"],
+                )
+                for txn in db_transactions
+            ]
+        else:
+            # Return full transaction details
+            data = [
+                Transaction(
+                    transaction_id=txn["transactionId"],  # NEW: stable bank-provided ID
+                    internal_transaction_id=txn.get("internalTransactionId"),
+                    institution_id=txn["institutionId"],
+                    iban=txn["iban"],
+                    account_id=txn["accountId"],
+                    transaction_date=txn["transactionDate"],
+                    description=txn["description"],
+                    transaction_value=txn["transactionValue"],
+                    transaction_currency=txn["transactionCurrency"],
+                    transaction_status=txn["transactionStatus"],
+                    raw_transaction=txn["rawTransaction"],
+                )
+                for txn in db_transactions
+            ]
+
+        actual_offset = offset or 0
+        return APIResponse(
+            success=True,
+            data=data,
+            message=f"Retrieved {len(data)} transactions (showing {actual_offset + 1}-{actual_offset + len(data)} of {total_transactions})",
+        )
+
+    except Exception as e:
+        logger.error(
+            f"Failed to get transactions from database for account {account_id}: {e}"
+        )
+        raise HTTPException(
+            status_code=404, detail=f"Failed to get transactions: {str(e)}"
+        ) from e
+
+
+@router.put("/accounts/{account_id}", response_model=APIResponse)
+async def update_account_details(
+    account_id: str, update_data: AccountUpdate
+) -> APIResponse:
+    """Update account details (currently only name)"""
+    try:
+        # Get current account details
+        current_account = await database_service.get_account_details_from_db(account_id)
+
+        if not current_account:
+            raise HTTPException(
+                status_code=404, detail=f"Account {account_id} not found"
+            )
+
+        # Prepare updated account data
+        updated_account_data = current_account.copy()
+        if update_data.name is not None:
+            updated_account_data["name"] = update_data.name
+
+        # Persist updated account details
+        await database_service.persist_account_details(updated_account_data)
+
+        return APIResponse(
+            success=True,
+            data={"id": account_id, "name": update_data.name},
+            message=f"Account {account_id} name updated successfully",
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to update account {account_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to update account: {str(e)}"
+        ) from e

leggen/api/routes/banks.py

@@ -0,0 +1,179 @@
+from fastapi import APIRouter, HTTPException, Query
+from loguru import logger
+
+from leggen.api.models.common import APIResponse
+from leggen.api.models.banks import (
+    BankInstitution,
+    BankConnectionRequest,
+    BankRequisition,
+    BankConnectionStatus,
+)
+from leggen.services.gocardless_service import GoCardlessService
+from leggen.utils.gocardless import REQUISITION_STATUS
+
+router = APIRouter()
+gocardless_service = GoCardlessService()
+
+
+@router.get("/banks/institutions", response_model=APIResponse)
+async def get_bank_institutions(
+    country: str = Query(default="PT", description="Country code (e.g., PT, ES, FR)"),
+) -> APIResponse:
+    """Get available bank institutions for a country"""
+    try:
+        institutions_data = await gocardless_service.get_institutions(country)
+
+        institutions = [
+            BankInstitution(
+                id=inst["id"],
+                name=inst["name"],
+                bic=inst.get("bic"),
+                transaction_total_days=inst["transaction_total_days"],
+                countries=inst["countries"],
+                logo=inst.get("logo"),
+            )
+            for inst in institutions_data
+        ]
+
+        return APIResponse(
+            success=True,
+            data=institutions,
+            message=f"Found {len(institutions)} institutions for {country}",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get institutions for {country}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get institutions: {str(e)}"
+        ) from e
+
+
+@router.post("/banks/connect", response_model=APIResponse)
+async def connect_to_bank(request: BankConnectionRequest) -> APIResponse:
+    """Create a connection to a bank (requisition)"""
+    try:
+        redirect_url = request.redirect_url or "http://localhost:8000/"
+        requisition_data = await gocardless_service.create_requisition(
+            request.institution_id, redirect_url
+        )
+
+        requisition = BankRequisition(
+            id=requisition_data["id"],
+            institution_id=requisition_data["institution_id"],
+            status=requisition_data["status"],
+            created=requisition_data["created"],
+            link=requisition_data["link"],
+            accounts=requisition_data.get("accounts", []),
+        )
+
+        return APIResponse(
+            success=True,
+            data=requisition,
+            message="Bank connection created. Please visit the link to authorize.",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to connect to bank {request.institution_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to connect to bank: {str(e)}"
+        ) from e
+
+
+@router.get("/banks/status", response_model=APIResponse)
+async def get_bank_connections_status() -> APIResponse:
+    """Get status of all bank connections"""
+    try:
+        requisitions_data = await gocardless_service.get_requisitions()
+
+        connections = []
+        for req in requisitions_data.get("results", []):
+            status = req["status"]
+            status_display = REQUISITION_STATUS.get(status, "UNKNOWN")
+
+            connections.append(
+                BankConnectionStatus(
+                    bank_id=req["institution_id"],
+                    bank_name=req[
+                        "institution_id"
+                    ],  # Could be enhanced with actual bank names
+                    status=status,
+                    status_display=status_display,
+                    created_at=req["created"],
+                    requisition_id=req["id"],
+                    accounts_count=len(req.get("accounts", [])),
+                )
+            )
+
+        return APIResponse(
+            success=True,
+            data=connections,
+            message=f"Found {len(connections)} bank connections",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get bank connection status: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get bank status: {str(e)}"
+        ) from e
+
+
+@router.delete("/banks/connections/{requisition_id}", response_model=APIResponse)
+async def delete_bank_connection(requisition_id: str) -> APIResponse:
+    """Delete a bank connection"""
+    try:
+        # This would need to be implemented in GoCardlessService
+        # For now, return success
+        return APIResponse(
+            success=True,
+            message=f"Bank connection {requisition_id} deleted successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to delete bank connection {requisition_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to delete connection: {str(e)}"
+        ) from e
+
+
+@router.get("/banks/countries", response_model=APIResponse)
+async def get_supported_countries() -> APIResponse:
+    """Get list of supported countries"""
+    countries = [
+        {"code": "AT", "name": "Austria"},
+        {"code": "BE", "name": "Belgium"},
+        {"code": "BG", "name": "Bulgaria"},
+        {"code": "HR", "name": "Croatia"},
+        {"code": "CY", "name": "Cyprus"},
+        {"code": "CZ", "name": "Czech Republic"},
+        {"code": "DK", "name": "Denmark"},
+        {"code": "EE", "name": "Estonia"},
+        {"code": "FI", "name": "Finland"},
+        {"code": "FR", "name": "France"},
+        {"code": "DE", "name": "Germany"},
+        {"code": "GR", "name": "Greece"},
+        {"code": "HU", "name": "Hungary"},
+        {"code": "IS", "name": "Iceland"},
+        {"code": "IE", "name": "Ireland"},
+        {"code": "IT", "name": "Italy"},
+        {"code": "LV", "name": "Latvia"},
+        {"code": "LI", "name": "Liechtenstein"},
+        {"code": "LT", "name": "Lithuania"},
+        {"code": "LU", "name": "Luxembourg"},
+        {"code": "MT", "name": "Malta"},
+        {"code": "NL", "name": "Netherlands"},
+        {"code": "NO", "name": "Norway"},
+        {"code": "PL", "name": "Poland"},
+        {"code": "PT", "name": "Portugal"},
+        {"code": "RO", "name": "Romania"},
+        {"code": "SK", "name": "Slovakia"},
+        {"code": "SI", "name": "Slovenia"},
+        {"code": "ES", "name": "Spain"},
+        {"code": "SE", "name": "Sweden"},
+        {"code": "GB", "name": "United Kingdom"},
+    ]
+
+    return APIResponse(
+        success=True,
+        data=countries,
+        message="Supported countries retrieved successfully",
+    )

leggen/api/routes/notifications.py

@@ -0,0 +1,203 @@
+from typing import Dict, Any
+from fastapi import APIRouter, HTTPException
+from loguru import logger
+
+from leggen.api.models.common import APIResponse
+from leggen.api.models.notifications import (
+    NotificationSettings,
+    NotificationTest,
+    DiscordConfig,
+    TelegramConfig,
+    NotificationFilters,
+)
+from leggen.services.notification_service import NotificationService
+from leggen.utils.config import config
+
+router = APIRouter()
+notification_service = NotificationService()
+
+
+@router.get("/notifications/settings", response_model=APIResponse)
+async def get_notification_settings() -> APIResponse:
+    """Get current notification settings"""
+    try:
+        notifications_config = config.notifications_config
+        filters_config = config.filters_config
+
+        # Build response safely without exposing secrets
+        discord_config = notifications_config.get("discord", {})
+        telegram_config = notifications_config.get("telegram", {})
+
+        settings = NotificationSettings(
+            discord=DiscordConfig(
+                webhook="***" if discord_config.get("webhook") else "",
+                enabled=discord_config.get("enabled", True),
+            )
+            if discord_config.get("webhook")
+            else None,
+            telegram=TelegramConfig(
+                token="***" if telegram_config.get("api-key") else "",
+                chat_id=telegram_config.get("chat-id", 0),
+                enabled=telegram_config.get("enabled", True),
+            )
+            if telegram_config.get("api-key")
+            else None,
+            filters=NotificationFilters(
+                case_insensitive=filters_config.get("case-insensitive", []),
+                case_sensitive=filters_config.get("case-sensitive"),
+            ),
+        )
+
+        return APIResponse(
+            success=True,
+            data=settings,
+            message="Notification settings retrieved successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get notification settings: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get notification settings: {str(e)}"
+        ) from e
+
+
+@router.put("/notifications/settings", response_model=APIResponse)
+async def update_notification_settings(settings: NotificationSettings) -> APIResponse:
+    """Update notification settings"""
+    try:
+        # Update notifications config
+        notifications_config = {}
+
+        if settings.discord:
+            notifications_config["discord"] = {
+                "webhook": settings.discord.webhook,
+                "enabled": settings.discord.enabled,
+            }
+
+        if settings.telegram:
+            notifications_config["telegram"] = {
+                "api-key": settings.telegram.token,
+                "chat-id": settings.telegram.chat_id,
+                "enabled": settings.telegram.enabled,
+            }
+
+        # Update filters config
+        filters_config: Dict[str, Any] = {}
+        if settings.filters.case_insensitive:
+            filters_config["case-insensitive"] = settings.filters.case_insensitive
+        if settings.filters.case_sensitive:
+            filters_config["case-sensitive"] = settings.filters.case_sensitive
+
+        # Save to config
+        if notifications_config:
+            config.update_section("notifications", notifications_config)
+        if filters_config:
+            config.update_section("filters", filters_config)
+
+        return APIResponse(
+            success=True,
+            data={"updated": True},
+            message="Notification settings updated successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to update notification settings: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to update notification settings: {str(e)}"
+        ) from e
+
+
+@router.post("/notifications/test", response_model=APIResponse)
+async def test_notification(test_request: NotificationTest) -> APIResponse:
+    """Send a test notification"""
+    try:
+        success = await notification_service.send_test_notification(
+            test_request.service, test_request.message
+        )
+
+        if success:
+            return APIResponse(
+                success=True,
+                data={"sent": True},
+                message=f"Test notification sent to {test_request.service} successfully",
+            )
+        else:
+            return APIResponse(
+                success=False,
+                message=f"Failed to send test notification to {test_request.service}",
+            )
+
+    except Exception as e:
+        logger.error(f"Failed to send test notification: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to send test notification: {str(e)}"
+        ) from e
+
+
+@router.get("/notifications/services", response_model=APIResponse)
+async def get_notification_services() -> APIResponse:
+    """Get available notification services and their status"""
+    try:
+        notifications_config = config.notifications_config
+
+        services = {
+            "discord": {
+                "name": "Discord",
+                "enabled": bool(notifications_config.get("discord", {}).get("webhook")),
+                "configured": bool(
+                    notifications_config.get("discord", {}).get("webhook")
+                ),
+                "active": notifications_config.get("discord", {}).get("enabled", True),
+            },
+            "telegram": {
+                "name": "Telegram",
+                "enabled": bool(
+                    notifications_config.get("telegram", {}).get("api-key")
+                    and notifications_config.get("telegram", {}).get("chat-id")
+                ),
+                "configured": bool(
+                    notifications_config.get("telegram", {}).get("api-key")
+                    and notifications_config.get("telegram", {}).get("chat-id")
+                ),
+                "active": notifications_config.get("telegram", {}).get("enabled", True),
+            },
+        }
+
+        return APIResponse(
+            success=True,
+            data=services,
+            message="Notification services status retrieved successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get notification services: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get notification services: {str(e)}"
+        ) from e
+
+
+@router.delete("/notifications/settings/{service}", response_model=APIResponse)
+async def delete_notification_service(service: str) -> APIResponse:
+    """Delete/disable a notification service"""
+    try:
+        if service not in ["discord", "telegram"]:
+            raise HTTPException(
+                status_code=400, detail="Service must be 'discord' or 'telegram'"
+            )
+
+        notifications_config = config.notifications_config.copy()
+        if service in notifications_config:
+            del notifications_config[service]
+            config.update_section("notifications", notifications_config)
+
+        return APIResponse(
+            success=True,
+            data={"deleted": service},
+            message=f"{service.capitalize()} notification service deleted successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to delete notification service {service}: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to delete notification service: {str(e)}"
+        ) from e

leggen/api/routes/sync.py

@@ -0,0 +1,212 @@
+from typing import Optional
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from loguru import logger
+
+from leggen.api.models.common import APIResponse
+from leggen.api.models.sync import SyncRequest, SchedulerConfig
+from leggen.services.sync_service import SyncService
+from leggen.background.scheduler import scheduler
+from leggen.utils.config import config
+
+router = APIRouter()
+sync_service = SyncService()
+
+
+@router.get("/sync/status", response_model=APIResponse)
+async def get_sync_status() -> APIResponse:
+    """Get current sync status"""
+    try:
+        status = await sync_service.get_sync_status()
+
+        # Add scheduler information
+        next_sync_time = scheduler.get_next_sync_time()
+        if next_sync_time:
+            status.next_sync = next_sync_time
+
+        return APIResponse(
+            success=True, data=status, message="Sync status retrieved successfully"
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get sync status: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get sync status: {str(e)}"
+        ) from e
+
+
+@router.post("/sync", response_model=APIResponse)
+async def trigger_sync(
+    background_tasks: BackgroundTasks, sync_request: Optional[SyncRequest] = None
+) -> APIResponse:
+    """Trigger a manual sync operation"""
+    try:
+        # Check if sync is already running
+        status = await sync_service.get_sync_status()
+        if status.is_running and not (sync_request and sync_request.force):
+            return APIResponse(
+                success=False,
+                message="Sync is already running. Use 'force: true' to override.",
+            )
+
+        # Determine what to sync
+        if sync_request and sync_request.account_ids:
+            # Sync specific accounts in background
+            background_tasks.add_task(
+                sync_service.sync_specific_accounts,
+                sync_request.account_ids,
+                sync_request.force if sync_request else False,
+            )
+            message = (
+                f"Started sync for {len(sync_request.account_ids)} specific accounts"
+            )
+        else:
+            # Sync all accounts in background
+            background_tasks.add_task(
+                sync_service.sync_all_accounts,
+                sync_request.force if sync_request else False,
+            )
+            message = "Started sync for all accounts"
+
+        return APIResponse(
+            success=True,
+            data={
+                "sync_started": True,
+                "force": sync_request.force if sync_request else False,
+            },
+            message=message,
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to trigger sync: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to trigger sync: {str(e)}"
+        ) from e
+
+
+@router.post("/sync/now", response_model=APIResponse)
+async def sync_now(sync_request: Optional[SyncRequest] = None) -> APIResponse:
+    """Run sync synchronously and return results (slower, for testing)"""
+    try:
+        if sync_request and sync_request.account_ids:
+            result = await sync_service.sync_specific_accounts(
+                sync_request.account_ids, sync_request.force
+            )
+        else:
+            result = await sync_service.sync_all_accounts(
+                sync_request.force if sync_request else False
+            )
+
+        return APIResponse(
+            success=result.success,
+            data=result,
+            message="Sync completed"
+            if result.success
+            else f"Sync failed with {len(result.errors)} errors",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to run sync: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to run sync: {str(e)}"
+        ) from e
+
+
+@router.get("/sync/scheduler", response_model=APIResponse)
+async def get_scheduler_config() -> APIResponse:
+    """Get current scheduler configuration"""
+    try:
+        scheduler_config = config.scheduler_config
+        next_sync_time = scheduler.get_next_sync_time()
+
+        response_data = {
+            **scheduler_config,
+            "next_scheduled_sync": next_sync_time.isoformat()
+            if next_sync_time
+            else None,
+            "is_running": scheduler.scheduler.running
+            if hasattr(scheduler, "scheduler")
+            else False,
+        }
+
+        return APIResponse(
+            success=True,
+            data=response_data,
+            message="Scheduler configuration retrieved successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get scheduler config: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get scheduler config: {str(e)}"
+        ) from e
+
+
+@router.put("/sync/scheduler", response_model=APIResponse)
+async def update_scheduler_config(scheduler_config: SchedulerConfig) -> APIResponse:
+    """Update scheduler configuration"""
+    try:
+        # Validate cron expression if provided
+        if scheduler_config.cron:
+            try:
+                cron_parts = scheduler_config.cron.split()
+                if len(cron_parts) != 5:
+                    raise ValueError(
+                        "Cron expression must have 5 parts: minute hour day month day_of_week"
+                    )
+            except Exception as e:
+                raise HTTPException(
+                    status_code=400, detail=f"Invalid cron expression: {str(e)}"
+                ) from e
+
+        # Update configuration
+        schedule_data = scheduler_config.dict(exclude_none=True)
+        config.update_section("scheduler", {"sync": schedule_data})
+
+        # Reschedule the job
+        scheduler.reschedule_sync(schedule_data)
+
+        return APIResponse(
+            success=True,
+            data=schedule_data,
+            message="Scheduler configuration updated successfully",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to update scheduler config: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to update scheduler config: {str(e)}"
+        ) from e
+
+
+@router.post("/sync/scheduler/start", response_model=APIResponse)
+async def start_scheduler() -> APIResponse:
+    """Start the background scheduler"""
+    try:
+        if not scheduler.scheduler.running:
+            scheduler.start()
+            return APIResponse(success=True, message="Scheduler started successfully")
+        else:
+            return APIResponse(success=True, message="Scheduler is already running")
+
+    except Exception as e:
+        logger.error(f"Failed to start scheduler: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to start scheduler: {str(e)}"
+        ) from e
+
+
+@router.post("/sync/scheduler/stop", response_model=APIResponse)
+async def stop_scheduler() -> APIResponse:
+    """Stop the background scheduler"""
+    try:
+        if scheduler.scheduler.running:
+            scheduler.shutdown()
+            return APIResponse(success=True, message="Scheduler stopped successfully")
+        else:
+            return APIResponse(success=True, message="Scheduler is already stopped")
+
+    except Exception as e:
+        logger.error(f"Failed to stop scheduler: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to stop scheduler: {str(e)}"
+        ) from e

leggen/api/routes/transactions.py

@@ -0,0 +1,254 @@
+from typing import Optional, List, Union
+from datetime import datetime, timedelta
+from fastapi import APIRouter, HTTPException, Query
+from loguru import logger
+
+from leggen.api.models.common import APIResponse, PaginatedResponse
+from leggen.api.models.accounts import Transaction, TransactionSummary
+from leggen.services.database_service import DatabaseService
+
+router = APIRouter()
+database_service = DatabaseService()
+
+
+@router.get("/transactions", response_model=PaginatedResponse)
+async def get_all_transactions(
+    page: int = Query(default=1, ge=1, description="Page number (1-based)"),
+    per_page: int = Query(default=50, le=500, description="Items per page"),
+    summary_only: bool = Query(
+        default=True, description="Return transaction summaries only"
+    ),
+    date_from: Optional[str] = Query(
+        default=None, description="Filter from date (YYYY-MM-DD)"
+    ),
+    date_to: Optional[str] = Query(
+        default=None, description="Filter to date (YYYY-MM-DD)"
+    ),
+    min_amount: Optional[float] = Query(
+        default=None, description="Minimum transaction amount"
+    ),
+    max_amount: Optional[float] = Query(
+        default=None, description="Maximum transaction amount"
+    ),
+    search: Optional[str] = Query(
+        default=None, description="Search in transaction descriptions"
+    ),
+    account_id: Optional[str] = Query(default=None, description="Filter by account ID"),
+) -> PaginatedResponse:
+    """Get all transactions from database with filtering options"""
+    try:
+        # Calculate offset from page and per_page
+        offset = (page - 1) * per_page
+        limit = per_page
+
+        # Get transactions from database instead of GoCardless API
+        db_transactions = await database_service.get_transactions_from_db(
+            account_id=account_id,
+            limit=limit,
+            offset=offset,
+            date_from=date_from,
+            date_to=date_to,
+            min_amount=min_amount,
+            max_amount=max_amount,
+            search=search,
+        )
+
+        # Get total count for pagination info (respecting the same filters)
+        total_transactions = await database_service.get_transaction_count_from_db(
+            account_id=account_id,
+            date_from=date_from,
+            date_to=date_to,
+            min_amount=min_amount,
+            max_amount=max_amount,
+            search=search,
+        )
+
+        data: Union[List[TransactionSummary], List[Transaction]]
+
+        if summary_only:
+            # Return simplified transaction summaries
+            data = [
+                TransactionSummary(
+                    transaction_id=txn["transactionId"],  # NEW: stable bank-provided ID
+                    internal_transaction_id=txn.get("internalTransactionId"),
+                    date=txn["transactionDate"],
+                    description=txn["description"],
+                    amount=txn["transactionValue"],
+                    currency=txn["transactionCurrency"],
+                    status=txn["transactionStatus"],
+                    account_id=txn["accountId"],
+                )
+                for txn in db_transactions
+            ]
+        else:
+            # Return full transaction details
+            data = [
+                Transaction(
+                    transaction_id=txn["transactionId"],  # NEW: stable bank-provided ID
+                    internal_transaction_id=txn.get("internalTransactionId"),
+                    institution_id=txn["institutionId"],
+                    iban=txn["iban"],
+                    account_id=txn["accountId"],
+                    transaction_date=txn["transactionDate"],
+                    description=txn["description"],
+                    transaction_value=txn["transactionValue"],
+                    transaction_currency=txn["transactionCurrency"],
+                    transaction_status=txn["transactionStatus"],
+                    raw_transaction=txn["rawTransaction"],
+                )
+                for txn in db_transactions
+            ]
+
+        total_pages = (total_transactions + per_page - 1) // per_page
+
+        return PaginatedResponse(
+            success=True,
+            data=data,
+            pagination={
+                "total": total_transactions,
+                "page": page,
+                "per_page": per_page,
+                "total_pages": total_pages,
+                "has_next": page < total_pages,
+                "has_prev": page > 1,
+            },
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get transactions from database: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get transactions: {str(e)}"
+        ) from e
+
+
+@router.get("/transactions/stats", response_model=APIResponse)
+async def get_transaction_stats(
+    days: int = Query(default=30, description="Number of days to include in stats"),
+    account_id: Optional[str] = Query(default=None, description="Filter by account ID"),
+) -> APIResponse:
+    """Get transaction statistics for the last N days from database"""
+    try:
+        # Date range for stats
+        end_date = datetime.now()
+        start_date = end_date - timedelta(days=days)
+
+        # Format dates for database query
+        date_from = start_date.isoformat()
+        date_to = end_date.isoformat()
+
+        # Get transactions from database
+        recent_transactions = await database_service.get_transactions_from_db(
+            account_id=account_id,
+            date_from=date_from,
+            date_to=date_to,
+            limit=None,  # Get all matching transactions for stats
+        )
+
+        # Calculate stats
+        total_transactions = len(recent_transactions)
+        total_income = sum(
+            txn["transactionValue"]
+            for txn in recent_transactions
+            if txn["transactionValue"] > 0
+        )
+        total_expenses = sum(
+            abs(txn["transactionValue"])
+            for txn in recent_transactions
+            if txn["transactionValue"] < 0
+        )
+        net_change = total_income - total_expenses
+
+        # Count by status
+        booked_count = len(
+            [txn for txn in recent_transactions if txn["transactionStatus"] == "booked"]
+        )
+        pending_count = len(
+            [
+                txn
+                for txn in recent_transactions
+                if txn["transactionStatus"] == "pending"
+            ]
+        )
+
+        # Count unique accounts
+        unique_accounts = len({txn["accountId"] for txn in recent_transactions})
+
+        stats = {
+            "period_days": days,
+            "total_transactions": total_transactions,
+            "booked_transactions": booked_count,
+            "pending_transactions": pending_count,
+            "total_income": round(total_income, 2),
+            "total_expenses": round(total_expenses, 2),
+            "net_change": round(net_change, 2),
+            "average_transaction": round(
+                sum(txn["transactionValue"] for txn in recent_transactions)
+                / total_transactions,
+                2,
+            )
+            if total_transactions > 0
+            else 0,
+            "accounts_included": unique_accounts,
+        }
+
+        return APIResponse(
+            success=True,
+            data=stats,
+            message=f"Transaction statistics for last {days} days",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get transaction stats from database: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get transaction stats: {str(e)}"
+        ) from e
+
+
+@router.get("/transactions/analytics", response_model=APIResponse)
+async def get_transactions_for_analytics(
+    days: int = Query(default=365, description="Number of days to include"),
+    account_id: Optional[str] = Query(default=None, description="Filter by account ID"),
+) -> APIResponse:
+    """Get all transactions for analytics (no pagination) for the last N days"""
+    try:
+        # Date range for analytics
+        end_date = datetime.now()
+        start_date = end_date - timedelta(days=days)
+
+        # Format dates for database query
+        date_from = start_date.isoformat()
+        date_to = end_date.isoformat()
+
+        # Get ALL transactions from database (no limit for analytics)
+        transactions = await database_service.get_transactions_from_db(
+            account_id=account_id,
+            date_from=date_from,
+            date_to=date_to,
+            limit=None,  # No limit - get all transactions
+        )
+
+        # Transform for frontend (summary format)
+        transaction_summaries = [
+            {
+                "transaction_id": txn["transactionId"],
+                "date": txn["transactionDate"],
+                "description": txn["description"],
+                "amount": txn["transactionValue"],
+                "currency": txn["transactionCurrency"],
+                "status": txn["transactionStatus"],
+                "account_id": txn["accountId"],
+            }
+            for txn in transactions
+        ]
+
+        return APIResponse(
+            success=True,
+            data=transaction_summaries,
+            message=f"Retrieved {len(transaction_summaries)} transactions for analytics",
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get transactions for analytics: {e}")
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get analytics transactions: {str(e)}"
+        ) from e