Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

feat: add payee/entity tracking (#50)

Tássio Noronha03c2894d1013
diff --git a/backend/alembic/versions/019_payees.py b/backend/alembic/versions/019_payees.py
new file mode 100644
index 00000000..122fb5f8
--- /dev/null
+++ b/backend/alembic/versions/019_payees.py
@@ -0,0 +1,66 @@
+"""add payees and payee_mapping tables, add payee_id to transactions
+
+Revision ID: 019
+Revises: 018
+Create Date: 2026-04-01
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import UUID
+
+revision: str = "019"
+down_revision: Union[str, None] = "018"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ # Create payees table
+ op.create_table(
+ "payees",
+ sa.Column("id", UUID(as_uuid=True), primary_key=True),
+ sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),
+ sa.Column("name", sa.String(255), nullable=False),
+ sa.Column("type", sa.String(20), server_default="merchant", nullable=False),
+ sa.Column("is_favorite", sa.Boolean, server_default=sa.text("false"), nullable=False),
+ sa.Column("notes", sa.String(1000), nullable=True),
+ sa.Column(
+ "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+ ),
+ )
+ op.create_index("ix_payees_user_id", "payees", ["user_id"])
+ op.create_unique_constraint("uq_payees_user_id_name", "payees", ["user_id", "name"])
+
+ # Create payee_mapping table (for merge/dedup)
+ op.create_table(
+ "payee_mapping",
+ sa.Column("id", UUID(as_uuid=True), primary_key=True),
+ sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),
+ sa.Column(
+ "target_id",
+ UUID(as_uuid=True),
+ sa.ForeignKey("payees.id", ondelete="CASCADE"),
+ nullable=False,
+ ),
+ )
+ op.create_index("ix_payee_mapping_user_id_target_id", "payee_mapping", ["user_id", "target_id"])
+
+ # Add payee_id FK to transactions
+ op.add_column(
+ "transactions",
+ sa.Column("payee_id", UUID(as_uuid=True), sa.ForeignKey("payees.id", ondelete="SET NULL"), nullable=True),
+ )
+ op.create_index("ix_transactions_payee_id", "transactions", ["payee_id"])
+
+
+def downgrade() -> None:
+ op.drop_index("ix_transactions_payee_id", table_name="transactions")
+ op.drop_column("transactions", "payee_id")
+ op.drop_index("ix_payee_mapping_user_id_target_id", table_name="payee_mapping")
+ op.drop_table("payee_mapping")
+ op.drop_constraint("uq_payees_user_id_name", "payees", type_="unique")
+ op.drop_index("ix_payees_user_id", table_name="payees")
+ op.drop_table("payees")
diff --git a/backend/app/api/payees.py b/backend/app/api/payees.py
new file mode 100644
index 00000000..1528873d
--- /dev/null
+++ b/backend/app/api/payees.py
@@ -0,0 +1,109 @@
+import uuid
+from datetime import date
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import current_active_user
+from app.core.database import get_async_session
+from app.models.user import User
+from app.schemas.payee import PayeeCreate, PayeeMergeRequest, PayeeRead, PayeeSummary, PayeeUpdate
+from app.schemas.category import CategoryRead
+from app.services import payee_service
+
+router = APIRouter(prefix="/api/payees", tags=["payees"])
+
+
[email protected]("", response_model=list[PayeeRead])
+async def list_payees(
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ return await payee_service.get_payees(session, user.id)
+
+
[email protected]("/{payee_id}", response_model=PayeeRead)
+async def get_payee(
+ payee_id: uuid.UUID,
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ payee = await payee_service.get_payee(session, payee_id, user.id)
+ if not payee:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")
+ return payee
+
+
[email protected]("/{payee_id}/summary", response_model=PayeeSummary)
+async def get_payee_summary(
+ payee_id: uuid.UUID,
+ start_date: Optional[date] = Query(None, alias="from"),
+ end_date: Optional[date] = Query(None, alias="to"),
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ try:
+ result = await payee_service.get_payee_summary(session, payee_id, user.id, start_date, end_date)
+ return PayeeSummary(
+ payee=PayeeRead.model_validate(result["payee"], from_attributes=True),
+ total_spent=result["total_spent"],
+ total_received=result["total_received"],
+ transaction_count=result["transaction_count"],
+ most_common_category=CategoryRead.model_validate(result["most_common_category"], from_attributes=True) if result["most_common_category"] else None,
+ last_transaction_date=result["last_transaction_date"],
+ )
+ except ValueError as e:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+
+
[email protected]("", response_model=PayeeRead, status_code=status.HTTP_201_CREATED)
+async def create_payee(
+ data: PayeeCreate,
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ try:
+ return await payee_service.create_payee(session, user.id, data)
+ except ValueError as e:
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
[email protected]("/{payee_id}", response_model=PayeeRead)
+async def update_payee(
+ payee_id: uuid.UUID,
+ data: PayeeUpdate,
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ try:
+ payee = await payee_service.update_payee(session, payee_id, user.id, data)
+ except ValueError as e:
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+ if not payee:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")
+ return payee
+
+
[email protected]("/{payee_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_payee(
+ payee_id: uuid.UUID,
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ deleted = await payee_service.delete_payee(session, payee_id, user.id)
+ if not deleted:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")
+
+
+async def merge_payees(
+ data: PayeeMergeRequest,
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ try:
+ reassigned = await payee_service.merge_payees(session, user.id, data.target_id, data.source_ids)
+ return {"merged": len(data.source_ids), "transactions_reassigned": reassigned}
+ except ValueError as e:
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.py
index 23ddf56a..49d74287 100644
--- a/backend/app/api/transactions.py
+++ b/backend/app/api/transactions.py
@@ -36,6 +36,7 @@ class PaginatedTransactions(BaseModel):
async def list_transactions(
account_id: Optional[uuid.UUID] = Query(None),
category_id: Optional[uuid.UUID] = Query(None),
+ payee_id: Optional[uuid.UUID] = Query(None),
from_date: Optional[date] = Query(None, alias="from"),
to_date: Optional[date] = Query(None, alias="to"),
q: Optional[str] = Query(None),
@@ -48,7 +49,7 @@ async def list_transactions(
user: User = Depends(current_active_user),
):
transactions, total = await transaction_service.get_transactions(
- session, user.id, account_id, category_id, from_date, to_date, page, limit,
+ session, user.id, account_id, category_id, payee_id, from_date, to_date, page, limit,
include_opening_balance, search=q, uncategorized=uncategorized, txn_type=type,
)
primary_currency = user.primary_currency
@@ -60,6 +61,7 @@ async def list_transactions(
async def export_transactions(
account_id: Optional[uuid.UUID] = Query(None),
category_id: Optional[uuid.UUID] = Query(None),
+ payee_id: Optional[uuid.UUID] = Query(None),
from_date: Optional[date] = Query(None, alias="from"),
to_date: Optional[date] = Query(None, alias="to"),
q: Optional[str] = Query(None),
@@ -69,14 +71,14 @@ async def export_transactions(
user: User = Depends(current_active_user),
):
transactions, _ = await transaction_service.get_transactions(
- session, user.id, account_id, category_id, from_date, to_date,
+ session, user.id, account_id, category_id, payee_id, from_date, to_date,
search=q, uncategorized=uncategorized, txn_type=type, skip_pagination=True,
)
output = io.StringIO()
output.write("\ufeff") # UTF-8 BOM for Excel
writer = csv.writer(output)
- writer.writerow(["date", "description", "amount", "type", "currency", "category", "account", "payee", "notes", "status", "source", "amount_primary", "fx_rate_used"])
+ writer.writerow(["date", "description", "amount", "type", "currency", "category", "account", "payee", "payee_name", "notes", "status", "source", "amount_primary", "fx_rate_used"])
for tx in transactions:
writer.writerow([
tx.date.isoformat(),
@@ -87,6 +89,7 @@ async def export_transactions(
tx.category.name if tx.category else "",
tx.account.name if tx.account else "",
tx.payee or "",
+ getattr(tx, "payee_name", "") or "",
tx.notes or "",
tx.status,
tx.source,
diff --git a/backend/app/main.py b/backend/app/main.py
index 06a98148..1a03b25e 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -21,6 +21,7 @@ from app.api.currencies import router as currencies_router
from app.api.export import router as export_router
from app.api.fx_rates import router as fx_rates_router
from app.api.attachments import router as attachments_router
+from app.api.payees import router as payees_router
from app.api.settings import router as settings_router
from app.api.transactions import router as transactions_router
from app.core.auth import auth_backend, fastapi_users
@@ -100,6 +101,7 @@ app.include_router(currencies_router)
app.include_router(fx_rates_router)
app.include_router(export_router)
app.include_router(attachments_router)
+app.include_router(payees_router)
app.include_router(settings_router)
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 0671c0fa..306da326 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -12,6 +12,7 @@ from app.models.asset import Asset
from app.models.asset_value import AssetValue
from app.models.fx_rate import FxRate
from app.models.transaction_attachment import TransactionAttachment
+from app.models.payee import Payee, PayeeMapping
__all__ = [
"User",
@@ -28,4 +29,6 @@ __all__ = [
"AssetValue",
"FxRate",
"TransactionAttachment",
+ "Payee",
+ "PayeeMapping",
]
diff --git a/backend/app/models/payee.py b/backend/app/models/payee.py
new file mode 100644
index 00000000..a585760c
--- /dev/null
+++ b/backend/app/models/payee.py
@@ -0,0 +1,38 @@
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+if TYPE_CHECKING:
+ from app.models.transaction import Transaction
+ from app.models.user import User
+
+
+class Payee(Base):
+ __tablename__ = "payees"
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+ user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"))
+ name: Mapped[str] = mapped_column(String(255))
+ type: Mapped[str] = mapped_column(String(20), default="merchant")
+ is_favorite: Mapped[bool] = mapped_column(Boolean, default=False)
+ notes: Mapped[Optional[str]] = mapped_column(String(1000), nullable=True)
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+
+ user: Mapped["User"] = relationship()
+ transactions: Mapped[list["Transaction"]] = relationship(back_populates="payee_entity")
+
+
+class PayeeMapping(Base):
+ __tablename__ = "payee_mapping"
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+ user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"))
+ target_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("payees.id", ondelete="CASCADE"))
+
+ target: Mapped["Payee"] = relationship()
diff --git a/backend/app/models/transaction.py b/backend/app/models/transaction.py
index 3dc20d2c..fd38ad16 100644
--- a/backend/app/models/transaction.py
+++ b/backend/app/models/transaction.py
@@ -13,6 +13,7 @@ if TYPE_CHECKING:
from app.models.account import Account
from app.models.category import Category
from app.models.import_log import ImportLog
+ from app.models.payee import Payee
from app.models.transaction_attachment import TransactionAttachment
@@ -32,6 +33,7 @@ class Transaction(Base):
source: Mapped[str] = mapped_column(String(20)) # sync, ofx, csv, manual
status: Mapped[str] = mapped_column(String(10), default="posted") # posted, pending
payee: Mapped[Optional[str]] = mapped_column(String(500), nullable=True)
+ payee_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("payees.id", ondelete="SET NULL"), nullable=True)
notes: Mapped[Optional[str]] = mapped_column(String(1000), nullable=True)
raw_data: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)
import_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("import_logs.id"), nullable=True)
@@ -42,6 +44,7 @@ class Transaction(Base):
account: Mapped["Account"] = relationship(back_populates="transactions")
category: Mapped[Optional["Category"]] = relationship()
+ payee_entity: Mapped[Optional["Payee"]] = relationship(back_populates="transactions")
import_log: Mapped[Optional["ImportLog"]] = relationship(back_populates="transactions")
attachments: Mapped[list["TransactionAttachment"]] = relationship(
back_populates="transaction", cascade="all, delete-orphan"
diff --git a/backend/app/schemas/payee.py b/backend/app/schemas/payee.py
new file mode 100644
index 00000000..b170b842
--- /dev/null
+++ b/backend/app/schemas/payee.py
@@ -0,0 +1,48 @@
+import uuid
+from datetime import date as _Date, datetime
+from decimal import Decimal
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from app.schemas.category import CategoryRead
+
+
+class PayeeCreate(BaseModel):
+ name: str
+ type: str = "merchant"
+ notes: Optional[str] = None
+
+
+class PayeeUpdate(BaseModel):
+ name: Optional[str] = None
+ type: Optional[str] = None
+ is_favorite: Optional[bool] = None
+ notes: Optional[str] = None
+
+
+class PayeeRead(BaseModel):
+ id: uuid.UUID
+ user_id: uuid.UUID
+ name: str
+ type: str
+ is_favorite: bool
+ notes: Optional[str] = None
+ created_at: datetime
+ transaction_count: int = 0
+
+ model_config = ConfigDict(from_attributes=True)
+
+
+class PayeeSummary(BaseModel):
+ payee: PayeeRead
+ total_spent: Decimal = Decimal("0")
+ total_received: Decimal = Decimal("0")
+ transaction_count: int = 0
+ most_common_category: Optional[CategoryRead] = None
+ last_transaction_date: Optional[_Date] = None
+
+
+class PayeeMergeRequest(BaseModel):
+ source_ids: list[uuid.UUID]
+ target_id: uuid.UUID
diff --git a/backend/app/schemas/transaction.py b/backend/app/schemas/transaction.py
index 538339f0..65b550a8 100644
--- a/backend/app/schemas/transaction.py
+++ b/backend/app/schemas/transaction.py
@@ -16,11 +16,13 @@ class TransactionBase(BaseModel):
external_id: Optional[str] = None
currency: Optional[str] = None
fx_rate: Optional[Decimal] = None
+ payee_raw: Optional[str] = None # raw payee string from import (OFX/QIF)
class TransactionCreate(TransactionBase):
account_id: uuid.UUID
category_id: Optional[uuid.UUID] = None
+ payee_id: Optional[uuid.UUID] = None
currency: Optional[str] = None
notes: Optional[str] = None
amount_primary: Optional[Decimal] = None
@@ -34,6 +36,7 @@ class TransactionUpdate(BaseModel):
type: Optional[str] = None
currency: Optional[str] = None
category_id: Optional[uuid.UUID] = None
+ payee_id: Optional[uuid.UUID] = None
notes: Optional[str] = None
amount_primary: Optional[Decimal] = None
fx_rate_used: Optional[Decimal] = None
@@ -49,6 +52,8 @@ class TransactionRead(TransactionBase):
source: str
status: str = "posted"
payee: Optional[str] = None
+ payee_id: Optional[uuid.UUID] = None
+ payee_name: Optional[str] = None
notes: Optional[str] = None
transfer_pair_id: Optional[uuid.UUID] = None
amount_primary: Optional[float] = None
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index dd883d15..0077604e 100644
--- a/backend/app/services/connection_service.py
+++ b/backend/app/services/connection_service.py
@@ -16,6 +16,7 @@ from app.providers import get_provider
from app.services.rule_service import apply_rules_to_transaction
from app.services.transfer_detection_service import detect_transfer_pairs
from app.services.fx_rate_service import stamp_primary_amount
+from app.services.payee_service import get_or_create_payee
settings = get_settings()
@@ -160,6 +161,12 @@ async def handle_oauth_callback(
category_id = await _match_pluggy_category(
session, user_id, txn_data.pluggy_category
)
+ # Resolve payee entity from raw payee text
+ payee_id = None
+ if txn_data.payee:
+ payee_entity = await get_or_create_payee(session, user_id, txn_data.payee)
+ payee_id = payee_entity.id
+
transaction = Transaction(
user_id=user_id,
account_id=account.id,
@@ -172,6 +179,7 @@ async def handle_oauth_callback(
source="sync",
status=txn_data.status,
payee=txn_data.payee,
+ payee_id=payee_id,
raw_data=txn_data.raw_data,
category_id=category_id,
)
@@ -340,6 +348,13 @@ async def sync_connection(
category_id = await _match_pluggy_category(
session, user_id, txn_data.pluggy_category
)
+
+ # Resolve payee entity from raw payee text
+ sync_payee_id = None
+ if txn_data.payee:
+ sync_payee_entity = await get_or_create_payee(session, user_id, txn_data.payee)
+ sync_payee_id = sync_payee_entity.id
+
transaction = Transaction(
user_id=user_id,
account_id=account.id,
@@ -352,6 +367,7 @@ async def sync_connection(
source="sync",
status=txn_data.status,
payee=txn_data.payee,
+ payee_id=sync_payee_id,
raw_data=txn_data.raw_data,
category_id=category_id,
)
diff --git a/backend/app/services/import_service.py b/backend/app/services/import_service.py
index 22e4c8ca..0588caf4 100644
--- a/backend/app/services/import_service.py
+++ b/backend/app/services/import_service.py
@@ -16,6 +16,7 @@ from app.models.transaction import Transaction
from app.schemas.transaction import TransactionBase
from app.services.rule_service import apply_rules_to_transaction
from app.services.fx_rate_service import stamp_primary_amount
+from app.services.payee_service import get_or_create_payee
def parse_ofx(content: bytes) -> list[TransactionBase]:
@@ -25,12 +26,14 @@ def parse_ofx(content: bytes) -> list[TransactionBase]:
for account in ofx.accounts:
for txn in account.statement.transactions:
+ raw_payee = getattr(txn, 'payee', None) or None
transactions.append(TransactionBase(
description=txn.memo or txn.payee or "Unknown",
amount=abs(Decimal(str(txn.amount))),
date=txn.date.date() if hasattr(txn.date, 'date') else txn.date,
type="credit" if txn.amount > 0 else "debit",
external_id=getattr(txn, 'id', None),
+ payee_raw=raw_payee,
))
return transactions
@@ -93,6 +96,7 @@ def parse_qif(content: bytes) -> list[TransactionBase]:
amount=abs(amount),
date=txn_date,
type="credit" if amount > 0 else "debit",
+ payee_raw=payee,
))
return transactions
@@ -399,6 +403,13 @@ async def import_transactions(
skipped += 1
continue
+ # Resolve payee entity from raw payee text (OFX/QIF)
+ import_payee_id = None
+ import_payee_raw = getattr(txn_data, "payee_raw", None)
+ if import_payee_raw:
+ import_payee_entity = await get_or_create_payee(session, user_id, import_payee_raw)
+ import_payee_id = import_payee_entity.id
+
transaction = Transaction(
user_id=user_id,
account_id=account_id,
@@ -410,6 +421,8 @@ async def import_transactions(
import_id=import_log.id,
external_id=txn_data.external_id,
currency=txn_currency,
+ payee=import_payee_raw,
+ payee_id=import_payee_id,
)
# If CSV provided an fx_rate, use it directly
diff --git a/backend/app/services/payee_service.py b/backend/app/services/payee_service.py
new file mode 100644
index 00000000..32a5e291
--- /dev/null
+++ b/backend/app/services/payee_service.py
@@ -0,0 +1,263 @@
+import uuid
+from datetime import date
+from decimal import Decimal
+from typing import Optional
+
+from sqlalchemy import case, select, func, update, delete
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.payee import Payee, PayeeMapping
+from app.models.transaction import Transaction
+from app.models.category import Category
+from app.schemas.payee import PayeeCreate, PayeeUpdate
+
+
+async def get_payees(session: AsyncSession, user_id: uuid.UUID) -> list[Payee]:
+ """List all payees for a user with transaction counts."""
+ count_subq = (
+ select(
+ Transaction.payee_id,
+ func.count(Transaction.id).label("tx_count"),
+ )
+ .where(Transaction.payee_id.isnot(None))
+ .group_by(Transaction.payee_id)
+ .subquery()
+ )
+ result = await session.execute(
+ select(Payee, func.coalesce(count_subq.c.tx_count, 0).label("transaction_count"))
+ .outerjoin(count_subq, Payee.id == count_subq.c.payee_id)
+ .where(Payee.user_id == user_id)
+ .order_by(Payee.name)
+ )
+ payees = []
+ for row in result.all():
+ payee = row[0]
+ payee.transaction_count = row[1]
+ payees.append(payee)
+ return payees
+
+
+async def get_payee(session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID) -> Optional[Payee]:
+ result = await session.execute(
+ select(Payee).where(Payee.id == payee_id, Payee.user_id == user_id)
+ )
+ return result.scalar_one_or_none()
+
+
+async def get_or_create_payee(session: AsyncSession, user_id: uuid.UUID, name: str) -> Payee:
+ """Find a payee by name (case-insensitive) or create a new one."""
+ name = name.strip()
+ if not name:
+ raise ValueError("Payee name cannot be empty")
+
+ result = await session.execute(
+ select(Payee).where(Payee.user_id == user_id, func.lower(Payee.name) == name.lower())
+ )
+ payee = result.scalar_one_or_none()
+ if payee:
+ return payee
+
+ payee = Payee(user_id=user_id, name=name)
+ session.add(payee)
+ await session.flush()
+ return payee
+
+
+async def create_payee(session: AsyncSession, user_id: uuid.UUID, data: PayeeCreate) -> Payee:
+ # Check uniqueness
+ existing = await session.execute(
+ select(Payee).where(Payee.user_id == user_id, func.lower(Payee.name) == data.name.strip().lower())
+ )
+ if existing.scalar_one_or_none():
+ raise ValueError("A payee with this name already exists")
+
+ payee = Payee(user_id=user_id, **data.model_dump())
+ session.add(payee)
+ await session.flush()
+
+ # Self-mapping for merge tracking
+ mapping = PayeeMapping(id=payee.id, user_id=user_id, target_id=payee.id)
+ session.add(mapping)
+
+ await session.commit()
+ await session.refresh(payee)
+ payee.transaction_count = 0
+ return payee
+
+
+async def update_payee(
+ session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID, data: PayeeUpdate
+) -> Optional[Payee]:
+ payee = await get_payee(session, payee_id, user_id)
+ if not payee:
+ return None
+
+ update_data = data.model_dump(exclude_unset=True)
+
+ # Check name uniqueness if name is being changed
+ if "name" in update_data and update_data["name"]:
+ existing = await session.execute(
+ select(Payee).where(
+ Payee.user_id == user_id,
+ func.lower(Payee.name) == update_data["name"].strip().lower(),
+ Payee.id != payee_id,
+ )
+ )
+ if existing.scalar_one_or_none():
+ raise ValueError("A payee with this name already exists")
+
+ for key, value in update_data.items():
+ setattr(payee, key, value)
+
+ await session.commit()
+ await session.refresh(payee)
+ return payee
+
+
+async def delete_payee(session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID) -> bool:
+ payee = await get_payee(session, payee_id, user_id)
+ if not payee:
+ return False
+
+ # Null out transaction references
+ await session.execute(
+ update(Transaction)
+ .where(Transaction.payee_id == payee_id)
+ .values(payee_id=None)
+ )
+
+ # Delete mappings pointing to this payee
+ await session.execute(
+ delete(PayeeMapping).where(PayeeMapping.target_id == payee_id)
+ )
+
+ await session.delete(payee)
+ await session.commit()
+ return True
+
+
+async def merge_payees(
+ session: AsyncSession,
+ user_id: uuid.UUID,
+ target_id: uuid.UUID,
+ source_ids: list[uuid.UUID],
+) -> int:
+ """Merge source payees into target. Returns number of transactions reassigned."""
+ # Validate target
+ target = await get_payee(session, target_id, user_id)
+ if not target:
+ raise ValueError("Target payee not found")
+
+ # Validate sources
+ for source_id in source_ids:
+ if source_id == target_id:
+ continue
+ source = await get_payee(session, source_id, user_id)
+ if not source:
+ raise ValueError(f"Source payee {source_id} not found")
+
+ # Reassign transactions
+ result = await session.execute(
+ update(Transaction)
+ .where(Transaction.payee_id.in_(source_ids))
+ .values(payee_id=target_id)
+ )
+ reassigned = result.rowcount
+
+ # Update mappings: point source mappings to target
+ for source_id in source_ids:
+ if source_id == target_id:
+ continue
+ await session.execute(
+ update(PayeeMapping)
+ .where(PayeeMapping.target_id == source_id)
+ .values(target_id=target_id)
+ )
+
+ # Delete source payees
+ for source_id in source_ids:
+ if source_id == target_id:
+ continue
+ source = await get_payee(session, source_id, user_id)
+ if source:
+ await session.delete(source)
+
+ await session.commit()
+ return reassigned
+
+
+async def get_payee_summary(
+ session: AsyncSession,
+ payee_id: uuid.UUID,
+ user_id: uuid.UUID,
+ start_date: Optional[date] = None,
+ end_date: Optional[date] = None,
+) -> dict:
+ """Return spending analytics for a payee."""
+ payee = await get_payee(session, payee_id, user_id)
+ if not payee:
+ raise ValueError("Payee not found")
+
+ base = select(Transaction).where(
+ Transaction.payee_id == payee_id,
+ Transaction.user_id == user_id,
+ )
+ if start_date:
+ base = base.where(Transaction.date >= start_date)
+ if end_date:
+ base = base.where(Transaction.date <= end_date)
+
+ # Totals
+ totals = await session.execute(
+ select(
+ func.coalesce(func.sum(
+ case(
+ (Transaction.type == "debit", Transaction.amount),
+ else_=Decimal("0"),
+ )
+ ), Decimal("0")).label("total_spent"),
+ func.coalesce(func.sum(
+ case(
+ (Transaction.type == "credit", Transaction.amount),
+ else_=Decimal("0"),
+ )
+ ), Decimal("0")).label("total_received"),
+ func.count(Transaction.id).label("count"),
+ func.max(Transaction.date).label("last_date"),
+ )
+ .where(
+ Transaction.payee_id == payee_id,
+ Transaction.user_id == user_id,
+ )
+ )
+ row = totals.one()
+
+ # Most common category
+ cat_result = await session.execute(
+ select(Transaction.category_id, func.count(Transaction.id).label("cnt"))
+ .where(
+ Transaction.payee_id == payee_id,
+ Transaction.user_id == user_id,
+ Transaction.category_id.isnot(None),
+ )
+ .group_by(Transaction.category_id)
+ .order_by(func.count(Transaction.id).desc())
+ .limit(1)
+ )
+ cat_row = cat_result.first()
+ most_common_category = None
+ if cat_row:
+ cat = await session.execute(
+ select(Category).where(Category.id == cat_row[0])
+ )
+ most_common_category = cat.scalar_one_or_none()
+
+ payee.transaction_count = row.count
+ return {
+ "payee": payee,
+ "total_spent": row.total_spent,
+ "total_received": row.total_received,
+ "transaction_count": row.count,
+ "most_common_category": most_common_category,
+ "last_transaction_date": row.last_date,
+ }
diff --git a/backend/app/services/rule_engine.py b/backend/app/services/rule_engine.py
index 000e8f5b..0f68e0d2 100644
--- a/backend/app/services/rule_engine.py
+++ b/backend/app/services/rule_engine.py
@@ -98,6 +98,12 @@ def apply_rule_actions(
except (ValueError, AttributeError):
pass
+ elif op == "set_payee":
+ try:
+ tx.payee_id = uuid.UUID(str(value))
+ except (ValueError, AttributeError):
+ pass
+
elif op == "append_notes":
new_tags = str(value or "").strip()
if not new_tags:
diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.py
index 55b7b96e..6be04156 100644
--- a/backend/app/services/transaction_service.py
+++ b/backend/app/services/transaction_service.py
@@ -10,6 +10,7 @@ from app.models.transaction import Transaction
from app.models.transaction_attachment import TransactionAttachment
from app.models.account import Account
from app.models.bank_connection import BankConnection
+from app.models.payee import Payee
from app.schemas.transaction import TransactionCreate, TransactionUpdate, TransferCreate
from app.services.rule_service import apply_rules_to_transaction
from app.services.fx_rate_service import stamp_primary_amount, convert as fx_convert
@@ -46,6 +47,7 @@ async def get_transactions(
user_id: uuid.UUID,
account_id: Optional[uuid.UUID] = None,
category_id: Optional[uuid.UUID] = None,
+ payee_id: Optional[uuid.UUID] = None,
from_date: Optional[date] = None,
to_date: Optional[date] = None,
page: int = 1,
@@ -61,13 +63,14 @@ async def get_transactions(
select(Transaction)
.outerjoin(Account)
.outerjoin(BankConnection)
+ .outerjoin(Payee, Transaction.payee_id == Payee.id)
.where(
or_(
Transaction.user_id == user_id,
BankConnection.user_id == user_id,
)
)
- .options(selectinload(Transaction.category), selectinload(Transaction.account))
+ .options(selectinload(Transaction.category), selectinload(Transaction.account), selectinload(Transaction.payee_entity))
)
# Exclude opening_balance transactions from the normal list unless explicitly requested
@@ -79,6 +82,8 @@ async def get_transactions(
base_query = base_query.where(Transaction.account_id == account_id)
if category_id:
base_query = base_query.where(Transaction.category_id == category_id)
+ if payee_id:
+ base_query = base_query.where(Transaction.payee_id == payee_id)
if uncategorized:
base_query = base_query.where(
Transaction.category_id == None,
@@ -97,6 +102,7 @@ async def get_transactions(
Transaction.description.ilike(term),
Transaction.payee.ilike(term),
Transaction.notes.ilike(term),
+ Payee.name.ilike(term),
)
)
@@ -126,6 +132,7 @@ async def get_transactions(
counts = dict(count_rows.all())
for tx in transactions:
tx.attachment_count = counts.get(tx.id, 0)
+ tx.payee_name = tx.payee_entity.name if tx.payee_entity else None
return transactions, total or 0
@@ -144,7 +151,7 @@ async def get_transaction(
BankConnection.user_id == user_id,
),
)
- .options(selectinload(Transaction.category))
+ .options(selectinload(Transaction.category), selectinload(Transaction.payee_entity))
)
transaction = result.scalar_one_or_none()
if transaction:
@@ -154,6 +161,7 @@ async def get_transaction(
)
)
transaction.attachment_count = count_result.scalar_one()
+ transaction.payee_name = transaction.payee_entity.name if transaction.payee_entity else None
return transaction
@@ -183,6 +191,7 @@ async def create_transaction(
user_id=user_id,
account_id=data.account_id,
category_id=data.category_id, # use provided category if given
+ payee_id=data.payee_id,
description=data.description,
amount=data.amount,
currency=currency,
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 5ae3c66c..682cbff0 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -21,6 +21,7 @@ from app.models.rule import Rule
from app.models.asset import Asset # noqa: F401
from app.models.asset_value import AssetValue # noqa: F401
from app.models.transaction_attachment import TransactionAttachment # noqa: F401
+from app.models.payee import Payee, PayeeMapping # noqa: F401
# Use SQLite for tests — fast, no external dependency
TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
diff --git a/backend/tests/test_payee_service.py b/backend/tests/test_payee_service.py
new file mode 100644
index 00000000..d9e2a535
--- /dev/null
+++ b/backend/tests/test_payee_service.py
@@ -0,0 +1,362 @@
+import uuid
+from datetime import date, datetime, timezone
+from decimal import Decimal
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.payee import PayeeMapping
+from app.models.transaction import Transaction
+from app.models.account import Account
+from app.models.user import User
+from app.schemas.payee import PayeeCreate, PayeeUpdate
+from app.services.payee_service import (
+ create_payee,
+ delete_payee,
+ get_or_create_payee,
+ get_payee,
+ get_payees,
+ get_payee_summary,
+ merge_payees,
+ update_payee,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _make_account(session: AsyncSession, user: User) -> Account:
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=user.id,
+ name="Test Account",
+ type="checking",
+ balance=Decimal("1000.00"),
+ currency="BRL",
+ )
+ session.add(account)
+ await session.flush()
+ return account
+
+
+# ---------------------------------------------------------------------------
+# create_payee
+# ---------------------------------------------------------------------------
+
+
+async def test_create_payee(session: AsyncSession, test_user):
+ data = PayeeCreate(name="Starbucks", type="merchant")
+ payee = await create_payee(session, test_user.id, data)
+
+ assert payee.name == "Starbucks"
+ assert payee.type == "merchant"
+ assert payee.is_favorite is False
+ assert payee.transaction_count == 0
+ assert payee.user_id == test_user.id
+
+
+async def test_create_payee_with_notes(session: AsyncSession, test_user):
+ data = PayeeCreate(name="Coffee Shop", type="merchant", notes="Morning coffee")
+ payee = await create_payee(session, test_user.id, data)
+
+ assert payee.notes == "Morning coffee"
+
+
+async def test_create_payee_duplicate_name_rejected(session: AsyncSession, test_user):
+ await create_payee(session, test_user.id, PayeeCreate(name="Starbucks"))
+ with pytest.raises(ValueError, match="already exists"):
+ await create_payee(session, test_user.id, PayeeCreate(name="starbucks")) # case-insensitive
+
+
+async def test_create_payee_creates_self_mapping(session: AsyncSession, test_user):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Mapped"))
+ from sqlalchemy import select
+ result = await session.execute(
+ select(PayeeMapping).where(PayeeMapping.id == payee.id)
+ )
+ mapping = result.scalar_one_or_none()
+ assert mapping is not None
+ assert mapping.target_id == payee.id
+
+
+# ---------------------------------------------------------------------------
+# get_payee / get_payees
+# ---------------------------------------------------------------------------
+
+
+async def test_get_payee(session: AsyncSession, test_user):
+ created = await create_payee(session, test_user.id, PayeeCreate(name="Target"))
+ fetched = await get_payee(session, created.id, test_user.id)
+
+ assert fetched is not None
+ assert fetched.id == created.id
+ assert fetched.name == "Target"
+
+
+async def test_get_payee_not_found(session: AsyncSession, test_user):
+ result = await get_payee(session, uuid.uuid4(), test_user.id)
+ assert result is None
+
+
+async def test_get_payees_empty(session: AsyncSession, test_user):
+ payees = await get_payees(session, test_user.id)
+ assert payees == []
+
+
+async def test_get_payees_with_transaction_counts(session: AsyncSession, test_user):
+ p1 = await create_payee(session, test_user.id, PayeeCreate(name="Payee A"))
+ p2 = await create_payee(session, test_user.id, PayeeCreate(name="Payee B"))
+
+ account = await _make_account(session, test_user)
+
+ # Add 2 transactions for p1, 1 for p2
+ for i in range(2):
+ session.add(Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ description=f"Tx {i}", amount=Decimal("10"), date=date.today(),
+ type="debit", source="manual", payee_id=p1.id,
+ created_at=datetime.now(timezone.utc),
+ ))
+ session.add(Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ description="Tx single", amount=Decimal("5"), date=date.today(),
+ type="debit", source="manual", payee_id=p2.id,
+ created_at=datetime.now(timezone.utc),
+ ))
+ await session.commit()
+
+ payees = await get_payees(session, test_user.id)
+ payees_by_name = {p.name: p for p in payees}
+
+ assert payees_by_name["Payee A"].transaction_count == 2
+ assert payees_by_name["Payee B"].transaction_count == 1
+
+
+async def test_get_payees_ordered_by_name(session: AsyncSession, test_user):
+ await create_payee(session, test_user.id, PayeeCreate(name="Zebra"))
+ await create_payee(session, test_user.id, PayeeCreate(name="Apple"))
+ await create_payee(session, test_user.id, PayeeCreate(name="Mango"))
+
+ payees = await get_payees(session, test_user.id)
+ names = [p.name for p in payees]
+ assert names == sorted(names)
+
+
+# ---------------------------------------------------------------------------
+# get_or_create_payee
+# ---------------------------------------------------------------------------
+
+
+async def test_get_or_create_payee_creates_new(session: AsyncSession, test_user):
+ payee = await get_or_create_payee(session, test_user.id, "New Payee")
+ assert payee.name == "New Payee"
+ assert payee.user_id == test_user.id
+
+
+async def test_get_or_create_payee_returns_existing(session: AsyncSession, test_user):
+ original = await create_payee(session, test_user.id, PayeeCreate(name="Existing"))
+ found = await get_or_create_payee(session, test_user.id, "existing") # case-insensitive
+ assert found.id == original.id
+
+
+async def test_get_or_create_payee_strips_whitespace(session: AsyncSession, test_user):
+ payee = await get_or_create_payee(session, test_user.id, " Trimmed ")
+ assert payee.name == "Trimmed"
+
+
+async def test_get_or_create_payee_empty_raises(session: AsyncSession, test_user):
+ with pytest.raises(ValueError, match="cannot be empty"):
+ await get_or_create_payee(session, test_user.id, " ")
+
+
+# ---------------------------------------------------------------------------
+# update_payee
+# ---------------------------------------------------------------------------
+
+
+async def test_update_payee(session: AsyncSession, test_user):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Old Name"))
+ updated = await update_payee(
+ session, payee.id, test_user.id,
+ PayeeUpdate(name="New Name", is_favorite=True),
+ )
+
+ assert updated is not None
+ assert updated.name == "New Name"
+ assert updated.is_favorite is True
+ assert updated.type == "merchant" # unchanged
+
+
+async def test_update_payee_not_found(session: AsyncSession, test_user):
+ result = await update_payee(
+ session, uuid.uuid4(), test_user.id, PayeeUpdate(name="Nope")
+ )
+ assert result is None
+
+
+async def test_update_payee_duplicate_name_rejected(session: AsyncSession, test_user):
+ await create_payee(session, test_user.id, PayeeCreate(name="A"))
+ b = await create_payee(session, test_user.id, PayeeCreate(name="B"))
+
+ with pytest.raises(ValueError, match="already exists"):
+ await update_payee(session, b.id, test_user.id, PayeeUpdate(name="A"))
+
+
+# ---------------------------------------------------------------------------
+# delete_payee
+# ---------------------------------------------------------------------------
+
+
+async def test_delete_payee(session: AsyncSession, test_user):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="ToDelete"))
+ assert await delete_payee(session, payee.id, test_user.id) is True
+ assert await get_payee(session, payee.id, test_user.id) is None
+
+
+async def test_delete_payee_not_found(session: AsyncSession, test_user):
+ assert await delete_payee(session, uuid.uuid4(), test_user.id) is False
+
+
+async def test_delete_payee_nulls_transaction_refs(session: AsyncSession, test_user):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Linked"))
+ account = await _make_account(session, test_user)
+
+ tx = Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ description="Linked Tx", amount=Decimal("50"), date=date.today(),
+ type="debit", source="manual", payee_id=payee.id,
+ created_at=datetime.now(timezone.utc),
+ )
+ session.add(tx)
+ await session.commit()
+
+ await delete_payee(session, payee.id, test_user.id)
+
+ await session.refresh(tx)
+ assert tx.payee_id is None
+
+
+# ---------------------------------------------------------------------------
+# merge_payees
+# ---------------------------------------------------------------------------
+
+
+async def test_merge_payees(session: AsyncSession, test_user):
+ target = await create_payee(session, test_user.id, PayeeCreate(name="Target"))
+ source1 = await create_payee(session, test_user.id, PayeeCreate(name="Source1"))
+ source2 = await create_payee(session, test_user.id, PayeeCreate(name="Source2"))
+
+ account = await _make_account(session, test_user)
+
+ # Create transactions assigned to source payees
+ for p in [source1, source2]:
+ session.add(Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ description=f"Tx for {p.name}", amount=Decimal("10"), date=date.today(),
+ type="debit", source="manual", payee_id=p.id,
+ created_at=datetime.now(timezone.utc),
+ ))
+ await session.commit()
+
+ reassigned = await merge_payees(
+ session, test_user.id, target.id, [source1.id, source2.id]
+ )
+
+ assert reassigned == 2
+
+ # Sources should be deleted
+ assert await get_payee(session, source1.id, test_user.id) is None
+ assert await get_payee(session, source2.id, test_user.id) is None
+
+ # Target should still exist
+ assert await get_payee(session, target.id, test_user.id) is not None
+
+
+async def test_merge_payees_target_not_found(session: AsyncSession, test_user):
+ source = await create_payee(session, test_user.id, PayeeCreate(name="Source"))
+ with pytest.raises(ValueError, match="Target payee not found"):
+ await merge_payees(session, test_user.id, uuid.uuid4(), [source.id])
+
+
+async def test_merge_payees_source_not_found(session: AsyncSession, test_user):
+ target = await create_payee(session, test_user.id, PayeeCreate(name="Target"))
+ with pytest.raises(ValueError, match="Source payee"):
+ await merge_payees(session, test_user.id, target.id, [uuid.uuid4()])
+
+
+# ---------------------------------------------------------------------------
+# get_payee_summary
+# ---------------------------------------------------------------------------
+
+
+async def test_get_payee_summary(session: AsyncSession, test_user, test_categories):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Summary"))
+ account = await _make_account(session, test_user)
+ cat = test_categories[0]
+
+ today = date.today()
+ # 2 debits, 1 credit
+ for desc, amount, typ in [
+ ("Buy 1", Decimal("100"), "debit"),
+ ("Buy 2", Decimal("50"), "debit"),
+ ("Refund", Decimal("30"), "credit"),
+ ]:
+ session.add(Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ description=desc, amount=amount, date=today,
+ type=typ, source="manual", payee_id=payee.id,
+ category_id=cat.id, created_at=datetime.now(timezone.utc),
+ ))
+ await session.commit()
+
+ summary = await get_payee_summary(session, payee.id, test_user.id)
+
+ assert summary["total_spent"] == Decimal("150")
+ assert summary["total_received"] == Decimal("30")
+ assert summary["transaction_count"] == 3
+ assert summary["last_transaction_date"] == today
+ assert summary["most_common_category"] is not None
+ assert summary["most_common_category"].name == cat.name
+
+
+async def test_get_payee_summary_not_found(session: AsyncSession, test_user):
+ with pytest.raises(ValueError, match="Payee not found"):
+ await get_payee_summary(session, uuid.uuid4(), test_user.id)
+
+
+async def test_get_payee_summary_no_transactions(session: AsyncSession, test_user):
+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Empty"))
+ summary = await get_payee_summary(session, payee.id, test_user.id)
+
+ assert summary["total_spent"] == Decimal("0")
+ assert summary["total_received"] == Decimal("0")
+ assert summary["transaction_count"] == 0
+ assert summary["last_transaction_date"] is None
+ assert summary["most_common_category"] is None
diff --git a/backend/tests/test_payees_api.py b/backend/tests/test_payees_api.py
new file mode 100644
index 00000000..4bb2695f
--- /dev/null
+++ b/backend/tests/test_payees_api.py
@@ -0,0 +1,264 @@
+import uuid
+from datetime import date, datetime, timezone
+from decimal import Decimal
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.account import Account
+from app.models.transaction import Transaction
+from app.models.user import User
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _create_payee(client: AsyncClient, auth_headers: dict, name: str, **kwargs) -> dict:
+ resp = await client.post(
+ "/api/payees", headers=auth_headers,
+ json={"name": name, **kwargs},
+ )
+ assert resp.status_code == 201
+ return resp.json()
+
+
+async def _make_account_and_tx(
+ session: AsyncSession, user: User, payee_id: str,
+ amount: Decimal = Decimal("10"), tx_type: str = "debit",
+) -> None:
+ # Reuse existing account if possible, otherwise create
+ from sqlalchemy import select
+ result = await session.execute(
+ select(Account).where(Account.user_id == user.id).limit(1)
+ )
+ account = result.scalar_one_or_none()
+ if not account:
+ account = Account(
+ id=uuid.uuid4(), user_id=user.id,
+ name="API Test Account", type="checking",
+ balance=Decimal("1000"), currency="BRL",
+ )
+ session.add(account)
+ await session.flush()
+
+ session.add(Transaction(
+ id=uuid.uuid4(), user_id=user.id, account_id=account.id,
+ description="API Test Tx", amount=amount, date=date.today(),
+ type=tx_type, source="manual", payee_id=uuid.UUID(payee_id),
+ created_at=datetime.now(timezone.utc),
+ ))
+ await session.commit()
+
+
+# ---------------------------------------------------------------------------
+# List
+# ---------------------------------------------------------------------------
+
+
+async def test_list_payees_empty(client: AsyncClient, auth_headers):
+ resp = await client.get("/api/payees", headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.json() == []
+
+
+async def test_list_payees(client: AsyncClient, auth_headers):
+ await _create_payee(client, auth_headers, "Alpha")
+ await _create_payee(client, auth_headers, "Beta")
+
+ resp = await client.get("/api/payees", headers=auth_headers)
+ assert resp.status_code == 200
+ data = resp.json()
+ assert len(data) == 2
+ names = {p["name"] for p in data}
+ assert names == {"Alpha", "Beta"}
+
+
+# ---------------------------------------------------------------------------
+# Create
+# ---------------------------------------------------------------------------
+
+
+async def test_create_payee(client: AsyncClient, auth_headers):
+ resp = await client.post(
+ "/api/payees", headers=auth_headers,
+ json={"name": "Starbucks", "type": "merchant", "notes": "Coffee"},
+ )
+ assert resp.status_code == 201
+ data = resp.json()
+ assert data["name"] == "Starbucks"
+ assert data["type"] == "merchant"
+ assert data["notes"] == "Coffee"
+ assert data["is_favorite"] is False
+ assert data["transaction_count"] == 0
+ assert "id" in data
+
+
+async def test_create_payee_duplicate(client: AsyncClient, auth_headers):
+ await _create_payee(client, auth_headers, "Unique")
+ resp = await client.post(
+ "/api/payees", headers=auth_headers,
+ json={"name": "unique"}, # case-insensitive duplicate
+ )
+ assert resp.status_code == 400
+
+
+# ---------------------------------------------------------------------------
+# Get single
+# ---------------------------------------------------------------------------
+
+
+async def test_get_payee(client: AsyncClient, auth_headers):
+ created = await _create_payee(client, auth_headers, "Single")
+ resp = await client.get(f"/api/payees/{created['id']}", headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.json()["name"] == "Single"
+
+
+async def test_get_payee_not_found(client: AsyncClient, auth_headers):
+ resp = await client.get(
+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,
+ )
+ assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Update
+# ---------------------------------------------------------------------------
+
+
+async def test_update_payee(client: AsyncClient, auth_headers):
+ created = await _create_payee(client, auth_headers, "OldName")
+ resp = await client.patch(
+ f"/api/payees/{created['id']}", headers=auth_headers,
+ json={"name": "NewName", "is_favorite": True},
+ )
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["name"] == "NewName"
+ assert data["is_favorite"] is True
+ assert data["type"] == "merchant" # unchanged
+
+
+async def test_update_payee_not_found(client: AsyncClient, auth_headers):
+ resp = await client.patch(
+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,
+ json={"name": "Nope"},
+ )
+ assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Delete
+# ---------------------------------------------------------------------------
+
+
+async def test_delete_payee(client: AsyncClient, auth_headers):
+ created = await _create_payee(client, auth_headers, "ToDelete")
+ resp = await client.delete(
+ f"/api/payees/{created['id']}", headers=auth_headers,
+ )
+ assert resp.status_code == 204
+
+ # Confirm gone
+ resp = await client.get(f"/api/payees/{created['id']}", headers=auth_headers)
+ assert resp.status_code == 404
+
+
+async def test_delete_payee_not_found(client: AsyncClient, auth_headers):
+ resp = await client.delete(
+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,
+ )
+ assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Merge
+# ---------------------------------------------------------------------------
+
+
+async def test_merge_payees(
+ client: AsyncClient, auth_headers, session: AsyncSession, test_user,
+):
+ target = await _create_payee(client, auth_headers, "MergeTarget")
+ source = await _create_payee(client, auth_headers, "MergeSource")
+
+ # Create a transaction linked to source
+ await _make_account_and_tx(session, test_user, source["id"])
+
+ resp = await client.post(
+ "/api/payees/merge", headers=auth_headers,
+ json={"target_id": target["id"], "source_ids": [source["id"]]},
+ )
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["transactions_reassigned"] == 1
+
+ # Source should be gone
+ resp = await client.get(f"/api/payees/{source['id']}", headers=auth_headers)
+ assert resp.status_code == 404
+
+
+async def test_merge_payees_invalid_target(client: AsyncClient, auth_headers):
+ source = await _create_payee(client, auth_headers, "SrcOnly")
+ resp = await client.post(
+ "/api/payees/merge", headers=auth_headers,
+ json={"target_id": str(uuid.uuid4()), "source_ids": [source["id"]]},
+ )
+ assert resp.status_code == 400
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+
+async def test_get_payee_summary(
+ client: AsyncClient, auth_headers, session: AsyncSession, test_user,
+):
+ payee = await _create_payee(client, auth_headers, "SummaryPayee")
+ await _make_account_and_tx(session, test_user, payee["id"], Decimal("100"), "debit")
+ await _make_account_and_tx(session, test_user, payee["id"], Decimal("30"), "credit")
+
+ resp = await client.get(
+ f"/api/payees/{payee['id']}/summary", headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["transaction_count"] == 2
+ assert float(data["total_spent"]) == 100.0
+ assert float(data["total_received"]) == 30.0
+
+
+async def test_get_payee_summary_not_found(client: AsyncClient, auth_headers):
+ resp = await client.get(
+ f"/api/payees/{uuid.uuid4()}/summary", headers=auth_headers,
+ )
+ assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+
+
+async def test_payees_unauthenticated(client: AsyncClient, clean_db):
+ resp = await client.get("/api/payees")
+ assert resp.status_code == 401
diff --git a/backend/tests/test_rule_engine.py b/backend/tests/test_rule_engine.py
index 125a0492..3aea6c52 100644
--- a/backend/tests/test_rule_engine.py
+++ b/backend/tests/test_rule_engine.py
@@ -304,3 +304,37 @@ def test_rule_priority_ordering():
category_set = apply_rule_actions(actions_high, tx, category_already_set=category_set)
assert tx.category_id == cat_low
+
+
+# --- set_payee action tests ---
+
+
+def test_set_payee_action():
+ payee_id = uuid.uuid4()
+ actions = [{"op": "set_payee", "value": str(payee_id)}]
+ tx = make_tx()
+ tx.payee_id = None
+ apply_rule_actions(actions, tx, category_already_set=False)
+ assert tx.payee_id == payee_id
+
+
+def test_set_payee_invalid_uuid_ignored():
+ actions = [{"op": "set_payee", "value": "not-a-uuid"}]
+ tx = make_tx()
+ tx.payee_id = None
+ apply_rule_actions(actions, tx, category_already_set=False)
+ assert tx.payee_id is None
+
+
+def test_set_payee_combined_with_category():
+ cat_id = uuid.uuid4()
+ payee_id = uuid.uuid4()
+ actions = [
+ {"op": "set_category", "value": str(cat_id)},
+ {"op": "set_payee", "value": str(payee_id)},
+ ]
+ tx = make_tx()
+ tx.payee_id = None
+ apply_rule_actions(actions, tx, category_already_set=False)
+ assert tx.category_id == cat_id
+ assert tx.payee_id == payee_id
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 02b6b040..a0423557 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -21,6 +21,7 @@ const BudgetsPage = lazy(() => import('@/pages/budgets'))
const RecurringPage = lazy(() => import('@/pages/recurring'))
const AssetsPage = lazy(() => import('@/pages/assets'))
const ReportsPage = lazy(() => import('@/pages/reports'))
+const PayeesPage = lazy(() => import('@/pages/payees'))
const queryClient = new QueryClient({
defaultOptions: {
@@ -68,6 +69,7 @@ function App() {
<Route path="/recurring" element={<RecurringPage />} />
<Route path="/assets" element={<AssetsPage />} />
<Route path="/reports" element={<ReportsPage />} />
+ <Route path="/payees" element={<PayeesPage />} />
</Route>
</Routes>
</Suspense>
diff --git a/frontend/src/components/app-layout.tsx b/frontend/src/components/app-layout.tsx
index b9b64e12..8e13909d 100644
--- a/frontend/src/components/app-layout.tsx
+++ b/frontend/src/components/app-layout.tsx
@@ -34,6 +34,7 @@ import {
EyeOff,
Repeat,
Landmark,
+ Users,
BarChart3,
Sun,
Moon,
@@ -60,6 +61,7 @@ const navItems: NavItem[] = [
{ type: 'link', key: 'budgets', path: '/budgets', icon: PiggyBank },
{ type: 'link', key: 'recurring', path: '/recurring', icon: Repeat },
{ type: 'link', key: 'categories', path: '/categories', icon: Tag },
+ { type: 'link', key: 'payees', path: '/payees', icon: Users },
{ type: 'link', key: 'rules', path: '/rules', icon: SlidersHorizontal },
]
diff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsx
index b7bad8a7..f605e338 100644
--- a/frontend/src/components/transaction-dialog.tsx
+++ b/frontend/src/components/transaction-dialog.tsx
@@ -2,7 +2,7 @@ import { useState, useEffect, useCallback, useRef } from 'react'
import { useTranslation } from 'react-i18next'
import { useQuery } from '@tanstack/react-query'
import { useAuth } from '@/contexts/auth-context'
-import { currencies as currenciesApi, transactions as transactionsApi, settings as settingsApi } from '@/lib/api'
+import { currencies as currenciesApi, transactions as transactionsApi, settings as settingsApi, payees as payeesApi } from '@/lib/api'
import { cn } from '@/lib/utils'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
@@ -279,12 +279,17 @@ function TransactionForm({
queryFn: currenciesApi.list,
staleTime: Infinity,
})
+ const { data: payeesList } = useQuery({
+ queryKey: ['payees'],
+ queryFn: payeesApi.list,
+ })
const [description, setDescription] = useState(transaction?.description ?? '')
const [amount, setAmount] = useState(transaction?.amount?.toString() ?? '')
const [date, setDate] = useState(transaction?.date ?? new Date().toISOString().split('T')[0])
const [type, setType] = useState<'debit' | 'credit'>(transaction?.type ?? 'debit')
const [currency, setCurrency] = useState(transaction?.currency ?? userCurrency)
const [categoryId, setCategoryId] = useState(transaction?.category_id ?? '')
+ const [payeeId, setPayeeId] = useState(transaction?.payee_id ?? '')
const [accountId, setAccountId] = useState(transaction?.account_id ?? accounts[0]?.id ?? '')
const [notes, setNotes] = useState(transaction?.notes ?? '')
const [convertedAmount, setConvertedAmount] = useState(
@@ -395,6 +400,7 @@ function TransactionForm({
const txData = isSynced
? {
category_id: categoryId || null,
+ payee_id: payeeId || null,
notes: notes.trim() || undefined,
} as Partial<Transaction>
: {
@@ -404,6 +410,7 @@ function TransactionForm({
type,
currency,
category_id: categoryId || null,
+ payee_id: payeeId || null,
account_id: accountId || undefined,
notes: notes.trim() || undefined,
...fxFields,
@@ -554,21 +561,39 @@ function TransactionForm({
</select>
</div>
</div>
- {!isSynced && (
+ <div className={cn("grid gap-4", isSynced ? "grid-cols-1" : "grid-cols-2")}>
<div className="space-y-2">
- <Label>{t('transactions.account')}</Label>
+ <Label>{t('payees.payee')}</Label>
<select
className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
- value={accountId}
- onChange={(e) => setAccountId(e.target.value)}
- required
+ value={payeeId}
+ onChange={(e) => setPayeeId(e.target.value)}
>
- {accounts.map((acc) => (
- <option key={acc.id} value={acc.id}>{acc.name}</option>
+ <option value="">{t('payees.noPayee')}</option>
+ {(payeesList ?? []).map((p) => (
+ <option key={p.id} value={p.id}>{p.name}</option>
))}
</select>
+ {isSynced && transaction?.payee && (
+ <p className="text-xs text-muted-foreground">{t('payees.rawPayee')}: {transaction.payee}</p>
+ )}
</div>
- )}
+ {!isSynced && (
+ <div className="space-y-2">
+ <Label>{t('transactions.account')}</Label>
+ <select
+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
+ value={accountId}
+ onChange={(e) => setAccountId(e.target.value)}
+ required
+ >
+ {accounts.map((acc) => (
+ <option key={acc.id} value={acc.id}>{acc.name}</option>
+ ))}
+ </select>
+ </div>
+ )}
+ </div>
<div className="space-y-2">
<Label>{t('transactions.notes')} <span className="text-muted-foreground font-normal text-xs">({t('transactions.notesHint')})</span></Label>
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 2b57d876..9c470319 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -8,6 +8,8 @@ import type {
Account,
AccountSummary,
Transaction,
+ Payee,
+ PayeeSummary,
RecurringTransaction,
ProjectedTransaction,
Budget,
@@ -212,6 +214,7 @@ export const transactions = {
list: async (params?: {
account_id?: string
category_id?: string
+ payee_id?: string
uncategorized?: boolean
type?: string
from?: string
@@ -324,6 +327,37 @@ export const transactions = {
},
}
+// Payees
+export const payees = {
+ list: async (): Promise<Payee[]> => {
+ const { data } = await api.get('/payees')
+ return data
+ },
+ get: async (id: string): Promise<Payee> => {
+ const { data } = await api.get(`/payees/${id}`)
+ return data
+ },
+ summary: async (id: string, from?: string, to?: string): Promise<PayeeSummary> => {
+ const { data } = await api.get(`/payees/${id}/summary`, { params: { from, to } })
+ return data
+ },
+ create: async (payee: { name: string; type?: string; notes?: string }): Promise<Payee> => {
+ const { data } = await api.post('/payees', payee)
+ return data
+ },
+ update: async (id: string, payee: Partial<Payee>): Promise<Payee> => {
+ const { data } = await api.patch(`/payees/${id}`, payee)
+ return data
+ },
+ delete: async (id: string): Promise<void> => {
+ await api.delete(`/payees/${id}`)
+ },
+ merge: async (targetId: string, sourceIds: string[]): Promise<{ merged: number; transactions_reassigned: number }> => {
+ const { data } = await api.post('/payees/merge', { target_id: targetId, source_ids: sourceIds })
+ return data
+ },
+}
+
// Categorization Rules
export const rules = {
list: async (): Promise<Rule[]> => {
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 3b3a0a8c..74ff3dff 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -13,6 +13,7 @@
"settings": "Settings",
"recurring": "Recurring",
"assets": "Assets",
+ "payees": "Payees",
"reports": "Reports",
"groupAnalysis": "Analysis",
"groupSetup": "Setup",
@@ -318,6 +319,8 @@
"addCondition": "Add condition",
"addAction": "Add action",
"setCategory": "Set category",
+ "setPayee": "Set payee",
+ "selectPayee": "Select payee...",
"appendNotes": "Append tags/notes",
"selectCategory": "Select category...",
"selectAccount": "Select account...",
@@ -510,6 +513,38 @@
"uncategorized": "Uncategorized",
"categoryTrends": "Category Trends"
},
+ "payees": {
+ "title": "Payees",
+ "section": "Setup",
+ "payee": "Payee",
+ "noPayee": "No payee",
+ "rawPayee": "Original payee",
+ "name": "Name",
+ "type": "Type",
+ "notes": "Notes",
+ "add": "Add Payee",
+ "edit": "Edit Payee",
+ "created": "Payee created",
+ "updated": "Payee updated",
+ "deleted": "Payee deleted",
+ "empty": "No payees yet",
+ "searchPlaceholder": "Search payees...",
+ "transactionCount": "Transactions",
+ "totalSpent": "Total Spent",
+ "totalReceived": "Total Received",
+ "lastTransaction": "Last Transaction",
+ "topCategory": "Top Category",
+ "viewAllTransactions": "View all {{count}} transactions",
+ "merge": "Merge",
+ "mergeTitle": "Merge Payees",
+ "mergeDescription": "All transactions from the selected payees will be reassigned to the target payee. The other payees will be deleted.",
+ "mergeTarget": "Merge into",
+ "selectTarget": "Select target payee...",
+ "merged": "Payees merged ({{count}} transactions reassigned)",
+ "typeMerchant": "Merchant",
+ "typePerson": "Person",
+ "typeCompany": "Company"
+ },
"common": {
"save": "Save",
"cancel": "Cancel",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index 7b6dbe42..95415004 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -13,6 +13,7 @@
"settings": "Configurações",
"recurring": "Recorrentes",
"assets": "Patrimônio",
+ "payees": "Beneficiários",
"reports": "Relatórios",
"groupAnalysis": "Análise",
"groupSetup": "Configuração",
@@ -318,6 +319,8 @@
"addCondition": "Adicionar condição",
"addAction": "Adicionar ação",
"setCategory": "Definir categoria",
+ "setPayee": "Definir beneficiário",
+ "selectPayee": "Selecionar beneficiário...",
"appendNotes": "Adicionar tags/notas",
"selectCategory": "Selecionar categoria...",
"selectAccount": "Selecionar conta...",
@@ -510,6 +513,38 @@
"uncategorized": "Sem categoria",
"categoryTrends": "Tendência por Categoria"
},
+ "payees": {
+ "title": "Beneficiários",
+ "section": "Configuração",
+ "payee": "Beneficiário",
+ "noPayee": "Sem beneficiário",
+ "rawPayee": "Beneficiário original",
+ "name": "Nome",
+ "type": "Tipo",
+ "notes": "Notas",
+ "add": "Adicionar Beneficiário",
+ "edit": "Editar Beneficiário",
+ "created": "Beneficiário criado",
+ "updated": "Beneficiário atualizado",
+ "deleted": "Beneficiário excluído",
+ "empty": "Nenhum beneficiário ainda",
+ "searchPlaceholder": "Buscar beneficiários...",
+ "transactionCount": "Transações",
+ "totalSpent": "Total Gasto",
+ "totalReceived": "Total Recebido",
+ "lastTransaction": "Última Transação",
+ "topCategory": "Categoria Principal",
+ "viewAllTransactions": "Ver todas as {{count}} transações",
+ "merge": "Mesclar",
+ "mergeTitle": "Mesclar Beneficiários",
+ "mergeDescription": "Todas as transações dos beneficiários selecionados serão reatribuídas ao beneficiário destino. Os demais serão excluídos.",
+ "mergeTarget": "Mesclar em",
+ "selectTarget": "Selecionar beneficiário destino...",
+ "merged": "Beneficiários mesclados ({{count}} transações reatribuídas)",
+ "typeMerchant": "Comerciante",
+ "typePerson": "Pessoa",
+ "typeCompany": "Empresa"
+ },
"common": {
"save": "Salvar",
"cancel": "Cancelar",
diff --git a/frontend/src/pages/account-detail.tsx b/frontend/src/pages/account-detail.tsx
index 010225bf..ae68d8d7 100644
--- a/frontend/src/pages/account-detail.tsx
+++ b/frontend/src/pages/account-detail.tsx
@@ -486,8 +486,8 @@ export default function AccountDetailPage() {
<Paperclip size={12} className="ml-2 inline text-muted-foreground" />
)}
</div>
- {tx.payee && tx.payee !== tx.description && (
- <p className="text-xs text-muted-foreground mt-0.5">{tx.payee}</p>
+ {(tx.payee_name || tx.payee) && (tx.payee_name || tx.payee) !== tx.description && (
+ <p className="text-xs text-muted-foreground mt-0.5">{tx.payee_name || tx.payee}</p>
)}
</td>
<td className="px-4 py-3 hidden md:table-cell">
diff --git a/frontend/src/pages/payees.tsx b/frontend/src/pages/payees.tsx
new file mode 100644
index 00000000..51250d90
--- /dev/null
+++ b/frontend/src/pages/payees.tsx
@@ -0,0 +1,478 @@
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useNavigate } from 'react-router-dom'
+import { payees as payeesApi, transactions as transactionsApi } from '@/lib/api'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { Skeleton } from '@/components/ui/skeleton'
+import {
+ Dialog,
+ DialogContent,
+ DialogHeader,
+ DialogTitle,
+ DialogFooter,
+} from '@/components/ui/dialog'
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHead,
+ TableHeader,
+ TableRow,
+} from '@/components/ui/table'
+import { PageHeader } from '@/components/page-header'
+import { Search, Star, Merge, Trash2, ArrowRight } from 'lucide-react'
+import { usePrivacyMode } from '@/hooks/use-privacy-mode'
+import { useAuth } from '@/contexts/auth-context'
+import type { Payee } from '@/types'
+
+function formatCurrency(value: number, currency = 'USD', locale = 'en-US') {
+ return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(value)
+}
+
+export default function PayeesPage() {
+ const { t, i18n } = useTranslation()
+ const navigate = useNavigate()
+ const locale = i18n.language === 'en' ? 'en-US' : i18n.language
+ const { mask } = usePrivacyMode()
+ const { user } = useAuth()
+ const userCurrency = user?.preferences?.currency_display ?? 'USD'
+ const queryClient = useQueryClient()
+ const [search, setSearch] = useState('')
+ const [dialogOpen, setDialogOpen] = useState(false)
+ const [editingPayee, setEditingPayee] = useState<Payee | null>(null)
+ const [summaryPayee, setSummaryPayee] = useState<string | null>(null)
+ const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+ const [mergeDialogOpen, setMergeDialogOpen] = useState(false)
+ const [mergeTargetId, setMergeTargetId] = useState<string>('')
+
+ // Form state
+ const [formName, setFormName] = useState('')
+ const [formType, setFormType] = useState<string>('merchant')
+ const [formNotes, setFormNotes] = useState('')
+
+ const { data: payeesList, isLoading } = useQuery({
+ queryKey: ['payees'],
+ queryFn: payeesApi.list,
+ })
+
+ const { data: summaryData, isLoading: summaryLoading } = useQuery({
+ queryKey: ['payees', summaryPayee, 'summary'],
+ queryFn: () => payeesApi.summary(summaryPayee!),
+ enabled: !!summaryPayee,
+ })
+
+ const { data: recentTxData } = useQuery({
+ queryKey: ['payees', summaryPayee, 'recent-transactions'],
+ queryFn: () => transactionsApi.list({ payee_id: summaryPayee!, limit: 5 }),
+ enabled: !!summaryPayee,
+ })
+
+ const createMutation = useMutation({
+ mutationFn: (data: { name: string; type?: string; notes?: string }) => payeesApi.create(data),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['payees'] })
+ setDialogOpen(false)
+ toast.success(t('payees.created'))
+ },
+ onError: () => toast.error(t('common.error')),
+ })
+
+ const updateMutation = useMutation({
+ mutationFn: ({ id, ...data }: Partial<Payee> & { id: string }) => payeesApi.update(id, data),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['payees'] })
+ setDialogOpen(false)
+ setEditingPayee(null)
+ toast.success(t('payees.updated'))
+ },
+ onError: () => toast.error(t('common.error')),
+ })
+
+ const deleteMutation = useMutation({
+ mutationFn: (id: string) => payeesApi.delete(id),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['payees'] })
+ queryClient.invalidateQueries({ queryKey: ['transactions'] })
+ setDialogOpen(false)
+ setEditingPayee(null)
+ toast.success(t('payees.deleted'))
+ },
+ onError: () => toast.error(t('common.error')),
+ })
+
+ const favoriteMutation = useMutation({
+ mutationFn: ({ id, is_favorite }: { id: string; is_favorite: boolean }) =>
+ payeesApi.update(id, { is_favorite }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['payees'] })
+ },
+ })
+
+ const mergeMutation = useMutation({
+ mutationFn: ({ targetId, sourceIds }: { targetId: string; sourceIds: string[] }) =>
+ payeesApi.merge(targetId, sourceIds),
+ onSuccess: (result) => {
+ queryClient.invalidateQueries({ queryKey: ['payees'] })
+ queryClient.invalidateQueries({ queryKey: ['transactions'] })
+ setMergeDialogOpen(false)
+ setSelectedIds(new Set())
+ setMergeTargetId('')
+ toast.success(t('payees.merged', { count: result.transactions_reassigned }))
+ },
+ onError: () => toast.error(t('common.error')),
+ })
+
+ const openCreate = () => {
+ setEditingPayee(null)
+ setFormName('')
+ setFormType('merchant')
+ setFormNotes('')
+ setDialogOpen(true)
+ }
+
+ const openEdit = (payee: Payee) => {
+ setEditingPayee(payee)
+ setFormName(payee.name)
+ setFormType(payee.type)
+ setFormNotes(payee.notes ?? '')
+ setDialogOpen(true)
+ }
+
+ const handleSave = () => {
+ if (editingPayee) {
+ updateMutation.mutate({ id: editingPayee.id, name: formName, type: formType as Payee['type'], notes: formNotes || undefined })
+ } else {
+ createMutation.mutate({ name: formName, type: formType, notes: formNotes || undefined })
+ }
+ }
+
+ const toggleSelect = (id: string) => {
+ setSelectedIds(prev => {
+ const next = new Set(prev)
+ if (next.has(id)) next.delete(id)
+ else next.add(id)
+ return next
+ })
+ }
+
+ const filtered = (payeesList ?? []).filter(p =>
+ !search || p.name.toLowerCase().includes(search.toLowerCase())
+ )
+
+ return (
+ <div>
+ <PageHeader
+ section={t('payees.section')}
+ title={t('payees.title')}
+ action={
+ <div className="flex items-center gap-2">
+ {selectedIds.size >= 2 && (
+ <Button variant="outline" onClick={() => { setMergeTargetId(''); setMergeDialogOpen(true) }}>
+ <Merge size={16} className="mr-1.5" />
+ {t('payees.merge')} ({selectedIds.size})
+ </Button>
+ )}
+ <Button onClick={openCreate}>
+ + {t('payees.add')}
+ </Button>
+ </div>
+ }
+ />
+
+ {/* Search */}
+ <div className="bg-card rounded-xl border border-border shadow-sm p-3 md:p-4 mb-4">
+ <div className="relative w-full md:w-auto">
+ <Search className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground" size={16} />
+ <Input
+ type="text"
+ placeholder={t('payees.searchPlaceholder')}
+ value={search}
+ onChange={(e) => setSearch(e.target.value)}
+ className="pl-9 w-full md:w-[300px] h-[38px] text-sm"
+ />
+ </div>
+ </div>
+
+ {/* Table */}
+ <div className="bg-card rounded-xl border border-border shadow-sm overflow-hidden mb-4">
+ {isLoading ? (
+ <div className="p-6 space-y-3">
+ {Array.from({ length: 5 }).map((_, i) => (
+ <Skeleton key={i} className="h-14 w-full" />
+ ))}
+ </div>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow className="border-b border-border hover:bg-transparent">
+ <TableHead className="w-[40px] py-3 pl-4 pr-0" />
+ <TableHead className="text-xs font-medium text-muted-foreground py-3 w-[32px]" />
+ <TableHead className="text-xs font-medium text-muted-foreground py-3">{t('payees.name')}</TableHead>
+ <TableHead className="hidden md:table-cell text-xs font-medium text-muted-foreground py-3 w-[120px]">{t('payees.type')}</TableHead>
+ <TableHead className="text-xs font-medium text-muted-foreground py-3 text-right w-[120px]">{t('payees.transactionCount')}</TableHead>
+ <TableHead className="w-[60px]" />
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {filtered.map((payee) => (
+ <TableRow
+ key={payee.id}
+ className={`cursor-pointer hover:bg-muted border-b border-border last:border-0 ${selectedIds.has(payee.id) ? 'bg-primary/5' : ''}`}
+ onClick={() => {
+ setSummaryPayee(summaryPayee === payee.id ? null : payee.id)
+ }}
+ >
+ <TableCell className="py-2.5 pl-4 pr-0 w-[40px]">
+ <input
+ type="checkbox"
+ checked={selectedIds.has(payee.id)}
+ onChange={() => toggleSelect(payee.id)}
+ onClick={(e) => e.stopPropagation()}
+ className="h-4 w-4 rounded border-border accent-primary cursor-pointer"
+ />
+ </TableCell>
+ <TableCell className="py-2.5 w-[32px]">
+ <button
+ onClick={(e) => {
+ e.stopPropagation()
+ favoriteMutation.mutate({ id: payee.id, is_favorite: !payee.is_favorite })
+ }}
+ className="p-1 rounded hover:bg-accent"
+ >
+ <Star
+ size={14}
+ className={payee.is_favorite ? 'fill-amber-400 text-amber-400' : 'text-muted-foreground'}
+ />
+ </button>
+ </TableCell>
+ <TableCell className="py-2.5">
+ <span className="text-sm font-semibold text-foreground">{payee.name}</span>
+ {payee.notes && (
+ <p className="text-xs text-muted-foreground mt-0.5 truncate max-w-[300px]">{payee.notes}</p>
+ )}
+ </TableCell>
+ <TableCell className="hidden md:table-cell py-2.5">
+ <span className="text-xs bg-muted text-muted-foreground px-2 py-0.5 rounded-full capitalize">{payee.type}</span>
+ </TableCell>
+ <TableCell className="py-2.5 text-right">
+ <span className="text-sm tabular-nums text-muted-foreground">{payee.transaction_count}</span>
+ </TableCell>
+ <TableCell className="py-2.5 pr-4">
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={(e) => { e.stopPropagation(); openEdit(payee) }}
+ >
+ {t('common.edit')}
+ </Button>
+ </TableCell>
+ </TableRow>
+ ))}
+ {filtered.length === 0 && (
+ <TableRow>
+ <TableCell colSpan={6} className="text-center py-16 text-muted-foreground">
+ {t('payees.empty')}
+ </TableCell>
+ </TableRow>
+ )}
+ </TableBody>
+ </Table>
+ )}
+ </div>
+
+ {/* Summary panel */}
+ {summaryPayee && (
+ <div className="bg-card rounded-xl border border-border shadow-sm p-5 mb-4">
+ {summaryLoading ? (
+ <Skeleton className="h-24 w-full" />
+ ) : summaryData ? (
+ <div className="space-y-3">
+ <div className="flex items-center justify-between">
+ <h3 className="text-lg font-bold">{summaryData.payee.name}</h3>
+ <Button variant="ghost" size="sm" onClick={() => setSummaryPayee(null)}>
+ &times;
+ </Button>
+ </div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+ <div>
+ <p className="text-xs text-muted-foreground">{t('payees.totalSpent')}</p>
+ <p className="text-lg font-bold text-rose-500 tabular-nums">
+ {mask(formatCurrency(summaryData.total_spent, userCurrency, locale))}
+ </p>
+ </div>
+ <div>
+ <p className="text-xs text-muted-foreground">{t('payees.totalReceived')}</p>
+ <p className="text-lg font-bold text-emerald-600 tabular-nums">
+ {mask(formatCurrency(summaryData.total_received, userCurrency, locale))}
+ </p>
+ </div>
+ <div>
+ <p className="text-xs text-muted-foreground">{t('payees.transactionCount')}</p>
+ <p className="text-lg font-bold tabular-nums">{summaryData.transaction_count}</p>
+ </div>
+ <div>
+ <p className="text-xs text-muted-foreground">{t('payees.lastTransaction')}</p>
+ <p className="text-sm font-medium">
+ {summaryData.last_transaction_date
+ ? new Date(summaryData.last_transaction_date + 'T00:00:00').toLocaleDateString(locale)
+ : '—'}
+ </p>
+ </div>
+ </div>
+ {summaryData.most_common_category && (
+ <p className="text-xs text-muted-foreground">
+ {t('payees.topCategory')}: <span className="font-medium text-foreground">{summaryData.most_common_category.name}</span>
+ </p>
+ )}
+
+ {/* Recent transactions */}
+ {recentTxData && recentTxData.items.length > 0 && (
+ <div className="pt-3 border-t border-border space-y-2">
+ <p className="text-xs font-medium text-muted-foreground">{t('dashboard.recentTransactions')}</p>
+ <div className="divide-y divide-border rounded-lg border border-border overflow-hidden">
+ {recentTxData.items.map((tx) => (
+ <div key={tx.id} className="flex items-center justify-between px-3 py-2 bg-background text-sm">
+ <div className="flex-1 min-w-0">
+ <p className="text-sm font-medium text-foreground truncate">{tx.description}</p>
+ <p className="text-xs text-muted-foreground">
+ {new Date(tx.date + 'T00:00:00').toLocaleDateString(locale)}
+ {tx.category?.name && <> · {tx.category.name}</>}
+ </p>
+ </div>
+ <span className={`text-sm font-semibold tabular-nums ml-3 ${tx.type === 'debit' ? 'text-rose-500' : 'text-emerald-600'}`}>
+ {mask(formatCurrency(tx.amount, tx.currency, locale))}
+ </span>
+ </div>
+ ))}
+ </div>
+ {recentTxData.total > 5 && (
+ <Button
+ variant="ghost"
+ size="sm"
+ className="w-full text-xs text-muted-foreground hover:text-foreground gap-1"
+ onClick={() => navigate(`/transactions?payee_id=${summaryPayee}`)}
+ >
+ {t('payees.viewAllTransactions', { count: recentTxData.total })}
+ <ArrowRight size={12} />
+ </Button>
+ )}
+ </div>
+ )}
+ </div>
+ ) : null}
+ </div>
+ )}
+
+ {/* Create/Edit Dialog */}
+ <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle>{editingPayee ? t('payees.edit') : t('payees.add')}</DialogTitle>
+ </DialogHeader>
+ <div className="space-y-4">
+ <div className="space-y-2">
+ <Label>{t('payees.name')}</Label>
+ <Input value={formName} onChange={(e) => setFormName(e.target.value)} required />
+ </div>
+ <div className="space-y-2">
+ <Label>{t('payees.type')}</Label>
+ <select
+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
+ value={formType}
+ onChange={(e) => setFormType(e.target.value)}
+ >
+ <option value="merchant">{t('payees.typeMerchant')}</option>
+ <option value="person">{t('payees.typePerson')}</option>
+ <option value="company">{t('payees.typeCompany')}</option>
+ </select>
+ </div>
+ <div className="space-y-2">
+ <Label>{t('payees.notes')}</Label>
+ <textarea
+ className="w-full border border-input rounded-md px-3 py-2 text-sm bg-background resize-none focus:outline-none focus:ring-2 focus:ring-ring"
+ rows={2}
+ value={formNotes}
+ onChange={(e) => setFormNotes(e.target.value)}
+ />
+ </div>
+ </div>
+ <DialogFooter className={editingPayee ? 'flex justify-between sm:justify-between' : ''}>
+ {editingPayee && (
+ <Button
+ variant="destructive"
+ onClick={() => deleteMutation.mutate(editingPayee.id)}
+ disabled={deleteMutation.isPending}
+ >
+ <Trash2 size={14} className="mr-1" />
+ {t('common.delete')}
+ </Button>
+ )}
+ <div className="flex gap-2">
+ <Button variant="outline" onClick={() => setDialogOpen(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button
+ onClick={handleSave}
+ disabled={!formName.trim() || createMutation.isPending || updateMutation.isPending}
+ >
+ {t('common.save')}
+ </Button>
+ </div>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+
+ {/* Merge Dialog */}
+ <Dialog open={mergeDialogOpen} onOpenChange={setMergeDialogOpen}>
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle>{t('payees.mergeTitle')}</DialogTitle>
+ </DialogHeader>
+ <div className="space-y-4">
+ <p className="text-sm text-muted-foreground">{t('payees.mergeDescription')}</p>
+ <div className="space-y-1">
+ {Array.from(selectedIds).map(id => {
+ const p = payeesList?.find(x => x.id === id)
+ return p ? (
+ <div key={id} className="text-sm py-1 px-2 rounded bg-muted">{p.name} ({p.transaction_count})</div>
+ ) : null
+ })}
+ </div>
+ <div className="space-y-2">
+ <Label>{t('payees.mergeTarget')}</Label>
+ <select
+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
+ value={mergeTargetId}
+ onChange={(e) => setMergeTargetId(e.target.value)}
+ >
+ <option value="">{t('payees.selectTarget')}</option>
+ {Array.from(selectedIds).map(id => {
+ const p = payeesList?.find(x => x.id === id)
+ return p ? <option key={id} value={id}>{p.name}</option> : null
+ })}
+ </select>
+ </div>
+ </div>
+ <DialogFooter>
+ <Button variant="outline" onClick={() => setMergeDialogOpen(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button
+ disabled={!mergeTargetId || mergeMutation.isPending}
+ onClick={() => {
+ const sourceIds = Array.from(selectedIds).filter(id => id !== mergeTargetId)
+ mergeMutation.mutate({ targetId: mergeTargetId, sourceIds })
+ }}
+ >
+ {t('payees.merge')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </div>
+ )
+}
diff --git a/frontend/src/pages/rules.tsx b/frontend/src/pages/rules.tsx
index 04e135a1..ee6bd305 100644
--- a/frontend/src/pages/rules.tsx
+++ b/frontend/src/pages/rules.tsx
@@ -1,7 +1,7 @@
import { useState, useMemo } from 'react'
import { useTranslation } from 'react-i18next'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { categories as categoriesApi, rules as rulesApi, accounts as accountsApi } from '@/lib/api'
+import { categories as categoriesApi, rules as rulesApi, accounts as accountsApi, payees as payeesApi } from '@/lib/api'
import { toast } from 'sonner'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
@@ -13,7 +13,7 @@ import {
DialogTitle,
DialogFooter,
} from '@/components/ui/dialog'
-import type { Category, Rule, RuleCondition, RuleAction } from '@/types'
+import type { Category, Payee, Rule, RuleCondition, RuleAction } from '@/types'
import { Trash2, Plus, RefreshCw, X, Package, Check, ArrowUpDown, ArrowUp, ArrowDown } from 'lucide-react'
import { cn } from '@/lib/utils'
import { PageHeader } from '@/components/page-header'
@@ -81,12 +81,16 @@ function conditionSummary(conditions: RuleCondition[], conditionsOp: string, t:
return parts.join(` ${conditionsOp === 'or' ? t('rules.orOp') : t('rules.andOp')} `) || t('rules.noConditions')
}
-function actionSummary(actions: RuleAction[], categories: Category[], t: (key: string) => string): string {
+function actionSummary(actions: RuleAction[], categories: Category[], payeesList: Payee[], t: (key: string) => string): string {
return actions.map(a => {
if (a.op === 'set_category') {
const cat = categories.find(c => c.id === a.value)
return cat ? `→ ${cat.name}` : `→ ${t('transactions.category')}`
}
+ if (a.op === 'set_payee') {
+ const p = payeesList.find(p => p.id === a.value)
+ return p ? `→ ${t('payees.payee')}: ${p.name}` : `→ ${t('payees.payee')}`
+ }
if (a.op === 'append_notes') return `→ ${t('rules.fieldNotes')}: ${a.value}`
return a.op
}).join(' ') || t('rules.noActions')
@@ -114,6 +118,11 @@ export default function RulesPage() {
queryFn: () => accountsApi.list(),
})
+ const { data: payeesList } = useQuery({
+ queryKey: ['payees'],
+ queryFn: payeesApi.list,
+ })
+
const createMutation = useMutation({
mutationFn: (data: Omit<Rule, 'id' | 'user_id'>) => rulesApi.create(data),
onSuccess: () => {
@@ -170,6 +179,7 @@ export default function RulesPage() {
})
const categories = categoriesList ?? []
+ const payees = payeesList ?? []
const [sortBy, setSortBy] = useState<'priority' | 'name' | 'category'>('priority')
const [sortDir, setSortDir] = useState<'asc' | 'desc'>('asc')
@@ -274,7 +284,7 @@ export default function RulesPage() {
{conditionSummary(rule.conditions, rule.conditions_op, t)}
</p>
<p className="text-xs text-emerald-600 font-medium mt-0.5">
- {actionSummary(rule.actions, categories, t)}
+ {actionSummary(rule.actions, categories, payees, t)}
</p>
</div>
<div className="flex items-center gap-1 shrink-0">
@@ -307,6 +317,7 @@ export default function RulesPage() {
rule={editing}
categories={categories}
accounts={accountsList ?? []}
+ payees={payees}
onSave={(data) => {
if (editing) {
updateMutation.mutate({ id: editing.id, ...data })
@@ -389,13 +400,14 @@ function RulePacksDialog({ open, onClose }: { open: boolean; onClose: () => void
}
function RuleDialog({
- open, onClose, rule, categories, accounts, onSave, loading,
+ open, onClose, rule, categories, accounts, payees, onSave, loading,
}: {
open: boolean
onClose: () => void
rule: Rule | null
categories: Category[]
accounts: { id: string; name: string }[]
+ payees: Payee[]
onSave: (data: Partial<Rule>) => void
loading: boolean
}) {
@@ -562,6 +574,7 @@ function RuleDialog({
onChange={(e) => updateAction(i, 'op', e.target.value)}
>
<option value="set_category">{t('rules.setCategory')}</option>
+ <option value="set_payee">{t('rules.setPayee')}</option>
<option value="append_notes">{t('rules.appendNotes')}</option>
</select>
{action.op === 'set_category' ? (
@@ -576,6 +589,18 @@ function RuleDialog({
<option key={cat.id} value={cat.id}>{cat.name}</option>
))}
</select>
+ ) : action.op === 'set_payee' ? (
+ <select
+ className={`${selectClass} flex-1`}
+ value={action.value}
+ onChange={(e) => updateAction(i, 'value', e.target.value)}
+ required
+ >
+ <option value="">{t('rules.selectPayee')}</option>
+ {payees.map(p => (
+ <option key={p.id} value={p.id}>{p.name}</option>
+ ))}
+ </select>
) : (
<Input
className="flex-1 h-8 text-sm"
diff --git a/frontend/src/pages/transactions.tsx b/frontend/src/pages/transactions.tsx
index 66231262..09a48b2e 100644
--- a/frontend/src/pages/transactions.tsx
+++ b/frontend/src/pages/transactions.tsx
@@ -1,7 +1,8 @@
import { useState, useMemo, useEffect, useRef } from 'react'
+import { useSearchParams } from 'react-router-dom'
import { useTranslation } from 'react-i18next'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { transactions, categories as categoriesApi, accounts as accountsApi, recurring } from '@/lib/api'
+import { transactions, categories as categoriesApi, accounts as accountsApi, recurring, payees as payeesApi } from '@/lib/api'
import { toast } from 'sonner'
import { Button } from '@/components/ui/button'
import {
@@ -36,6 +37,7 @@ function parseHashtags(notes: string | null): string[] {
export default function TransactionsPage() {
const { t, i18n } = useTranslation()
+ const [searchParams] = useSearchParams()
const locale = i18n.language === 'en' ? 'en-US' : i18n.language
const { mask } = usePrivacyMode()
const { user } = useAuth()
@@ -50,6 +52,7 @@ export default function TransactionsPage() {
const [searchQuery, setSearchQuery] = useState('')
const [dialogOpen, setDialogOpen] = useState(false)
const [editingTx, setEditingTx] = useState<Transaction | null>(null)
+ const [filterPayee, setFilterPayee] = useState<string>(searchParams.get('payee_id') ?? '')
const [tagFilter, setTagFilter] = useState<string | null>(null)
const [exporting, setExporting] = useState(false)
const [transferDialogOpen, setTransferDialogOpen] = useState(false)
@@ -70,16 +73,17 @@ export default function TransactionsPage() {
useEffect(() => {
setSelectedIds(new Set())
setBulkCategory('')
- }, [page, filterAccount, filterCategory, filterFrom, filterTo, searchQuery])
+ }, [page, filterAccount, filterCategory, filterPayee, filterFrom, filterTo, searchQuery])
const { data, isLoading } = useQuery({
- queryKey: ['transactions', page, filterAccount, filterCategory, filterFrom, filterTo, searchQuery],
+ queryKey: ['transactions', page, filterAccount, filterCategory, filterPayee, filterFrom, filterTo, searchQuery],
queryFn: () =>
transactions.list({
page,
limit: 20,
account_id: filterAccount || undefined,
category_id: filterCategory === '__uncategorized__' ? undefined : (filterCategory || undefined),
+ payee_id: filterPayee || undefined,
uncategorized: filterCategory === '__uncategorized__' ? true : undefined,
from: filterFrom || undefined,
to: filterTo || undefined,
@@ -97,6 +101,11 @@ export default function TransactionsPage() {
queryFn: () => accountsApi.list(),
})
+ const { data: payeesList } = useQuery({
+ queryKey: ['payees'],
+ queryFn: payeesApi.list,
+ })
+
const { data: recurringList } = useQuery({
queryKey: ['recurring'],
queryFn: recurring.list,
@@ -311,6 +320,16 @@ export default function TransactionsPage() {
<option key={cat.id} value={cat.id}>{cat.name}</option>
))}
</select>
+ <select
+ className="border border-border rounded-lg px-3 py-2 text-sm bg-card text-foreground focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px] min-w-0"
+ value={filterPayee}
+ onChange={(e) => { setFilterPayee(e.target.value); setPage(1) }}
+ >
+ <option value="">{t('payees.payee')}: {t('transactions.all')}</option>
+ {payeesList?.map((p) => (
+ <option key={p.id} value={p.id}>{p.name}</option>
+ ))}
+ </select>
</div>
<div className="grid grid-cols-2 gap-2 md:flex md:gap-3">
<div className="flex items-center gap-2">
@@ -330,12 +349,12 @@ export default function TransactionsPage() {
/>
</div>
</div>
- {(filterFrom || filterTo || filterAccount || filterCategory || searchInput) && (
+ {(filterFrom || filterTo || filterAccount || filterCategory || filterPayee || searchInput) && (
<Button
variant="ghost"
size="sm"
className="text-muted-foreground hover:text-foreground"
- onClick={() => { setFilterFrom(''); setFilterTo(''); setFilterAccount(''); setFilterCategory(''); setSearchInput(''); setSearchQuery(''); setPage(1) }}
+ onClick={() => { setFilterFrom(''); setFilterTo(''); setFilterAccount(''); setFilterCategory(''); setFilterPayee(''); setSearchInput(''); setSearchQuery(''); setPage(1) }}
>
{t('transactions.clearFilters')}
</Button>
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 7775ef0f..363badc2 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -92,6 +92,8 @@ export interface Transaction {
source: string
status: 'posted' | 'pending'
payee: string | null
+ payee_id: string | null
+ payee_name: string | null
notes: string | null
transfer_pair_id: string | null
amount_primary: number | null
@@ -100,6 +102,26 @@ export interface Transaction {
attachment_count?: number
}
+export interface Payee {
+ id: string
+ user_id: string
+ name: string
+ type: 'merchant' | 'person' | 'company'
+ is_favorite: boolean
+ notes: string | null
+ created_at: string
+ transaction_count: number
+}
+
+export interface PayeeSummary {
+ payee: Payee
+ total_spent: number
+ total_received: number
+ transaction_count: number
+ most_common_category: Category | null
+ last_transaction_date: string | null
+}
+
export interface RuleCondition {
field: string
op: string