Skip to content

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

feat(assets): accept external ids via API (#755)

Leonardo Zanivan7975e14cf427
diff --git a/backend/app/schemas/asset.py b/backend/app/schemas/asset.py
index b3e50574..41491de7 100644
--- a/backend/app/schemas/asset.py
+++ b/backend/app/schemas/asset.py
@@ -3,7 +3,7 @@ from datetime import date as _date, datetime
from decimal import Decimal
from typing import Optional
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
class AssetCreate(BaseModel):
@@ -24,6 +24,7 @@ class AssetCreate(BaseModel):
is_archived: bool = False
position: int = 0
group_id: Optional[uuid.UUID] = None
+ external_id: Optional[str] = None
# Market-priced assets: ticker is enough to create one. The service
# fetches the live quote on create and seeds the first AssetValue.
ticker: Optional[str] = None
@@ -34,6 +35,18 @@ class AssetCreate(BaseModel):
# service seeds the buy at the live quote ("bought at market now").
unit_price: Optional[Decimal] = None
+ @field_validator("external_id")
+ @classmethod
+ def normalize_external_id(cls, value: Optional[str]) -> Optional[str]:
+ if value is None:
+ return None
+ normalized = value.strip()
+ if not normalized:
+ raise ValueError("external_id must not be blank")
+ if len(normalized) > 255:
+ raise ValueError("external_id must be at most 255 characters")
+ return normalized
+
class AssetUpdate(BaseModel):
name: Optional[str] = None
@@ -83,6 +96,7 @@ class AssetRead(BaseModel):
gain_loss_primary: Optional[float] = None
value_count: int = 0
source: str = "manual"
+ external_id: Optional[str] = None
connection_id: Optional[uuid.UUID] = None
isin: Optional[str] = None
maturity_date: Optional[_date] = None
diff --git a/backend/app/services/asset_service.py b/backend/app/services/asset_service.py
index 35baf55e..fa8d7930 100644
--- a/backend/app/services/asset_service.py
+++ b/backend/app/services/asset_service.py
@@ -6,6 +6,7 @@ from typing import Any, Optional, cast
from fastapi import HTTPException, status
from sqlalchemy import select, func, desc
+from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.asset import Asset
@@ -158,6 +159,7 @@ def _asset_to_read(
gain_loss=gain_loss,
value_count=value_count,
source=asset.source,
+ external_id=asset.external_id,
connection_id=asset.connection_id,
isin=asset.isin,
maturity_date=asset.maturity_date,
@@ -446,6 +448,25 @@ async def create_asset(
detail=f"Could not fetch quote for {data.ticker}",
)
+ source = (
+ "tesouro_direto"
+ if quote and quote.exchange == "Tesouro Direto"
+ else ("yfinance" if data.valuation_method == "market_price" else "manual")
+ )
+ if data.external_id is not None:
+ existing_result = await session.execute(
+ select(Asset).where(
+ Asset.workspace_id == workspace_id,
+ Asset.source == source,
+ Asset.external_id == data.external_id,
+ )
+ )
+ existing = existing_result.scalar_one_or_none()
+ if existing is not None:
+ existing_read = await get_asset(session, existing.id, workspace_id)
+ assert existing_read is not None
+ return existing_read
+
asset = Asset(
user_id=user_id,
workspace_id=workspace_id,
@@ -474,14 +495,29 @@ async def create_asset(
last_price=Decimal(str(quote.price)) if quote else None,
last_price_at=datetime.now(timezone.utc) if quote else None,
logo_url=quote.logo_url if quote else None,
- source=(
- "tesouro_direto"
- if quote and quote.exchange == "Tesouro Direto"
- else ("yfinance" if data.valuation_method == "market_price" else "manual")
- ),
+ external_id=data.external_id,
+ source=source,
)
session.add(asset)
- await session.flush()
+ try:
+ await session.flush()
+ except IntegrityError:
+ # Return the winner when concurrent requests use the same external ID.
+ await session.rollback()
+ if data.external_id is not None:
+ existing_result = await session.execute(
+ select(Asset).where(
+ Asset.workspace_id == workspace_id,
+ Asset.source == source,
+ Asset.external_id == data.external_id,
+ )
+ )
+ existing = existing_result.scalar_one_or_none()
+ if existing is not None:
+ existing_read = await get_asset(session, existing.id, workspace_id)
+ assert existing_read is not None
+ return existing_read
+ raise
# Seed the first AssetValue from the live quote so the portfolio chart
# has a starting data point without waiting for the scheduled refresh.
diff --git a/backend/tests/test_asset_service.py b/backend/tests/test_asset_service.py
index 52421511..cd4632ca 100644
--- a/backend/tests/test_asset_service.py
+++ b/backend/tests/test_asset_service.py
@@ -1,9 +1,11 @@
import uuid
from datetime import date, timedelta
from decimal import Decimal
+from unittest.mock import AsyncMock, Mock
import pytest
import pytest_asyncio
+from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.asset import Asset
@@ -158,6 +160,57 @@ async def test_create_asset_with_initial_value(session: AsyncSession, test_user:
assert result.value_count == 1
+async def test_create_asset_recovers_from_concurrent_external_id_conflict(monkeypatch):
+ workspace_id = uuid.uuid4()
+ user_id = uuid.uuid4()
+ existing_asset = Mock(id=uuid.uuid4())
+ missing_result = Mock()
+ missing_result.scalar_one_or_none.return_value = None
+ existing_result = Mock()
+ existing_result.scalar_one_or_none.return_value = existing_asset
+
+ session = Mock(spec=AsyncSession)
+ results = iter([missing_result, existing_result])
+
+ async def execute_scoped_lookup(statement):
+ statement_text = str(statement)
+ assert "assets.workspace_id" in statement_text
+ assert "assets.source" in statement_text
+ assert "assets.external_id" in statement_text
+ bound_values = set(statement.compile().params.values())
+ assert workspace_id in bound_values
+ assert "manual" in bound_values
+ assert "external-asset-1" in bound_values
+ return next(results)
+
+ session.execute = AsyncMock(side_effect=execute_scoped_lookup)
+ session.flush = AsyncMock(
+ side_effect=IntegrityError("INSERT INTO assets", {}, Exception("duplicate"))
+ )
+ session.rollback = AsyncMock()
+ session.add = Mock()
+ expected = Mock()
+ get_asset = AsyncMock(return_value=expected)
+ monkeypatch.setattr(asset_service, "get_asset", get_asset)
+
+ result = await asset_service.create_asset(
+ session,
+ workspace_id,
+ user_id,
+ AssetCreate(
+ name="External holding",
+ type="investment",
+ currency="USD",
+ external_id="external-asset-1",
+ ),
+ )
+
+ assert result is expected
+ session.rollback.assert_awaited_once()
+ get_asset.assert_awaited_once_with(session, existing_asset.id, workspace_id)
+
+
@pytest.mark.asyncio
async def test_list_assets(session: AsyncSession, test_user: User, test_workspace, test_asset: Asset):
results = await asset_service.get_assets(session, test_workspace.id)
diff --git a/backend/tests/test_assets_api.py b/backend/tests/test_assets_api.py
index 90cfd002..e376a045 100644
--- a/backend/tests/test_assets_api.py
+++ b/backend/tests/test_assets_api.py
@@ -1,6 +1,7 @@
import uuid
from datetime import date
from decimal import Decimal
+from unittest.mock import AsyncMock, patch
import pytest
import pytest_asyncio
@@ -10,6 +11,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.models.asset import Asset
from app.models.asset_value import AssetValue
from app.models.user import User
+from app.models.workspace import Workspace, WorkspaceMember
+from app.schemas.asset import MarketSymbolQuote
@pytest_asyncio.fixture
@@ -83,6 +86,149 @@ async def test_create_asset(client: AsyncClient, auth_headers: dict):
assert data["value_count"] == 1
+async def test_create_asset_with_external_id_returns_it_via_rest(
+ client: AsyncClient, auth_headers: dict
+):
+ response = await client.post(
+ "/api/assets",
+ headers=auth_headers,
+ json={
+ "name": "Exterior ETF",
+ "type": "investment",
+ "currency": "USD",
+ "current_value": 1250,
+ "external_id": " portfolio-asset-1 ",
+ },
+ )
+ assert response.status_code == 201
+ created = response.json()
+ assert created["external_id"] == "portfolio-asset-1"
+ assert created["source"] == "manual"
+
+ detail = await client.get(f"/api/assets/{created['id']}", headers=auth_headers)
+ assert detail.status_code == 200
+ assert detail.json()["external_id"] == "portfolio-asset-1"
+
+ listed = await client.get("/api/assets", headers=auth_headers)
+ assert listed.status_code == 200
+ assert any(
+ asset["id"] == created["id"]
+ and asset["external_id"] == "portfolio-asset-1"
+ for asset in listed.json()
+ )
+
+
+async def test_create_market_price_asset_with_external_id_via_rest(
+ client: AsyncClient, auth_headers: dict
+):
+ provider = AsyncMock()
+ provider.get_quote.return_value = MarketSymbolQuote(
+ symbol="VOO",
+ name="Vanguard S&P 500 ETF",
+ exchange="NYSE Arca",
+ currency="USD",
+ price=625.50,
+ quote_type="ETF",
+ )
+ payload = {
+ "name": "Vanguard S&P 500 ETF",
+ "type": "investment",
+ "valuation_method": "market_price",
+ "ticker": "VOO",
+ "units": 3.5,
+ "external_id": "portfolio-voo",
+ }
+
+ with patch(
+ "app.services.asset_service.get_market_price_provider",
+ return_value=provider,
+ ):
+ first = await client.post("/api/assets", headers=auth_headers, json=payload)
+ second = await client.post("/api/assets", headers=auth_headers, json=payload)
+
+ assert first.status_code == 201
+ assert second.status_code == 201
+ assert second.json()["id"] == first.json()["id"]
+ assert first.json()["external_id"] == "portfolio-voo"
+ assert first.json()["source"] == "yfinance"
+ assert first.json()["ticker"] == "VOO"
+
+
+async def test_create_asset_is_idempotent_by_external_id_within_workspace(
+ client: AsyncClient, auth_headers: dict
+):
+ payload = {
+ "name": "Synced Holding",
+ "type": "investment",
+ "currency": "USD",
+ "current_value": 500,
+ "external_id": "portfolio-stable-id",
+ }
+
+ first = await client.post("/api/assets", headers=auth_headers, json=payload)
+ second = await client.post("/api/assets", headers=auth_headers, json=payload)
+
+ assert first.status_code == 201
+ assert second.status_code == 201
+ assert second.json()["id"] == first.json()["id"]
+ assert second.json()["value_count"] == 1
+
+ listed = await client.get("/api/assets", headers=auth_headers)
+ matching = [
+ asset
+ for asset in listed.json()
+ if asset["external_id"] == "portfolio-stable-id"
+ ]
+ assert len(matching) == 1
+
+
+async def test_same_external_id_is_allowed_in_different_workspaces(
+ client: AsyncClient,
+ auth_headers: dict,
+ session: AsyncSession,
+ test_user: User,
+ test_workspace: Workspace,
+):
+ other_workspace = Workspace(
+ id=uuid.uuid4(),
+ name="Other portfolio",
+ kind="personal",
+ created_by_user_id=test_user.id,
+ default_currency="USD",
+ )
+ session.add(other_workspace)
+ await session.flush()
+ session.add(
+ WorkspaceMember(
+ id=uuid.uuid4(),
+ workspace_id=other_workspace.id,
+ user_id=test_user.id,
+ role="owner",
+ )
+ )
+ await session.commit()
+
+ payload = {
+ "name": "Shared external key",
+ "type": "investment",
+ "currency": "USD",
+ "external_id": "same-provider-id",
+ }
+ first_headers = {**auth_headers, "X-Workspace-Id": str(test_workspace.id)}
+ second_headers = {**auth_headers, "X-Workspace-Id": str(other_workspace.id)}
+
+ first = await client.post("/api/assets", headers=first_headers, json=payload)
+ second = await client.post("/api/assets", headers=second_headers, json=payload)
+
+ assert first.status_code == 201
+ assert second.status_code == 201
+ assert first.json()["id"] != second.json()["id"]
+
+
@pytest.mark.asyncio
async def test_update_asset(client: AsyncClient, auth_headers: dict, test_asset_api: Asset):
response = await client.patch(
diff --git a/backend/tests/test_market_price_assets.py b/backend/tests/test_market_price_assets.py
index b0eabd0c..bc2cf82e 100644
--- a/backend/tests/test_market_price_assets.py
+++ b/backend/tests/test_market_price_assets.py
@@ -129,6 +129,41 @@ async def test_create_market_price_asset_seeds_quote_and_initial_value(
assert created.value_count == 1
+async def test_create_market_price_asset_is_idempotent_by_external_id(
+ session: AsyncSession, test_user: User, test_workspace
+):
+ provider = FakeMarketProvider({"VOO": _quote("VOO", 625.50)})
+ data = AssetCreate(
+ name="Vanguard S&P 500 ETF",
+ type="investment",
+ valuation_method="market_price",
+ ticker="VOO",
+ units=Decimal("3.5"),
+ external_id="portfolio-voo",
+ )
+
+ first = await asset_service.create_asset(
+ session, test_workspace.id, test_user.id, data, market_provider=provider
+ )
+ second = await asset_service.create_asset(
+ session, test_workspace.id, test_user.id, data, market_provider=provider
+ )
+
+ assert second.id == first.id
+ assert second.external_id == "portfolio-voo"
+ assert second.source == "yfinance"
+ assert second.value_count == 1
+ rows = await session.execute(
+ select(Asset).where(
+ Asset.workspace_id == test_workspace.id,
+ Asset.source == "yfinance",
+ Asset.external_id == "portfolio-voo",
+ )
+ )
+ assert len(rows.scalars().all()) == 1
+
+
@pytest.mark.asyncio
async def test_create_market_price_seeds_opening_buy_at_unit_price(
session: AsyncSession, test_user: User, test_workspace
diff --git a/frontend/src/locales/el.json b/frontend/src/locales/el.json
index 09121471..8b6aa969 100644
--- a/frontend/src/locales/el.json
+++ b/frontend/src/locales/el.json
@@ -521,6 +521,9 @@
"drillDownUncategorized": "Συναλλαγές χωρίς κατηγορία",
"drillDownDay": "Συναλλαγές — {{date}}",
"drillDownTotal": "{{count}} συναλλαγές · {{total}}",
+ "drillDownSettledTotal": "Διακανονισμένα · συνολικό ποσό",
+ "drillDownPendingTotal": "Εκκρεμεί διακανονισμός",
+ "drillDownShownTotal": "Εμφανιζόμενο σύνολο",
"drillDownEmpty": "Δεν βρέθηκαν συναλλαγές",
"drillDownClose": "Κλείσιμο",
"accrualNote": "Οι συναλλαγές πιστωτικών καρτών ομαδοποιούνται κατά την ημερομηνία λήξης του λογαριασμού (λειτουργία δεδουλευμένων).",
@@ -912,6 +915,9 @@
"confirmTransferCategoryBoth": "Ενημέρωση και των δύο",
"ignoreTransfer": "Αγνόηση αυτής της συναλλαγής",
"ignoreTransferHint": "Οι αγνοημένες συναλλαγές δεν θα εμφανίζονται στις αναφορές και στο υπόλοιπο",
+ "excludeFromReports": "Εξαίρεση από τις αναφορές",
+ "excludeFromReportsHint": "Αυτή η συναλλαγή δεν θα υπολογίζεται ως έσοδο ή έξοδο, αλλά θα εξακολουθεί να επηρεάζει το υπόλοιπο του λογαριασμού και να παραμένει στο ιστορικό συναλλαγών.",
+ "excludedFromReports": "Εκτός αναφορών",
"ignored": "Αγνοήθηκε",
"ignoreAction": "Αγνόηση",
"unignoreAction": "Επαναφορά",