portfolio-hub/app/repositories/portfolio_repository.py

"""Portfolio repository contract."""

from __future__ import annotations

from datetime import datetime
from typing import Protocol

from app.domain.models import AuthToken, BrokerCredential, Daemon, LedgerEntry, LedgerTrade, Portfolio, PortfolioComment, PortfolioTag, StrategySet, TokenPrincipal, User


class PortfolioRepository(Protocol):
    def ping(self) -> None: ...

    def get_user(self, user_id: str) -> User: ...

    def get_user_by_username(self, username: str) -> User | None: ...

    def list_users(self) -> list[User]: ...

    def create_user(
        self,
        username: str,
        *,
        email: str | None = None,
        password_hash: str | None = None,
        permission: str = "read",
        is_active: bool = True,
    ) -> User: ...

    def update_user(
        self,
        user_id: str,
        *,
        username: str | None = None,
        email: str | None = None,
        password_hash: str | None = None,
        permission: str | None = None,
        is_active: bool | None = None,
    ) -> User: ...

    def delete_user(self, user_id: str) -> None: ...

    def update_user_last_login(self, user_id: str) -> None: ...

    def upsert_broker_credential(
        self,
        user_id: str,
        broker: str,
        *,
        account_ref: str,
        encrypted_payload: str,
    ) -> BrokerCredential: ...

    def list_broker_credentials(self, user_id: str) -> list[BrokerCredential]: ...

    def delete_broker_credential(self, user_id: str, broker: str) -> bool: ...

    def create_auth_token(
        self,
        user_id: str,
        *,
        name: str,
        token_hash: str,
        token_prefix: str,
        permission: str,
        token_type: str,
        expires_at: datetime | None = None,
        runtime_id: str | None = None,
        daemon_id: str | None = None,
    ) -> AuthToken: ...

    def list_auth_tokens(self, user_id: str) -> list[AuthToken]: ...

    def list_service_tokens(
        self,
        user_id: str | None = None,
        *,
        include_revoked: bool = False,
    ) -> list[AuthToken]: ...

    def revoke_auth_token(self, user_id: str, token_id: str) -> None: ...

    def get_service_token_by_name(self, name: str) -> AuthToken | None: ...

    def get_token_principal(self, token_hash: str) -> TokenPrincipal | None: ...

    def rotate_service_token(self, name: str) -> tuple[str, AuthToken]: ...

    def rebind_service_token(self, name: str, daemon_id: str) -> AuthToken: ...

    def create_daemon(
        self,
        owner_user_id: str,
        *,
        daemon_slug: str,
        display_name: str | None = None,
    ) -> Daemon: ...

    def get_daemon_by_id(self, daemon_id: str) -> Daemon | None: ...

    def get_daemon_by_slug(self, owner_user_id: str, daemon_slug: str) -> Daemon | None: ...

    def list_daemons_for_user(self, owner_user_id: str) -> list[Daemon]: ...

    def update_daemon(
        self,
        daemon_id: str,
        *,
        display_name: str | None = None,
        is_active: bool | None = None,
    ) -> Daemon: ...

    def get(self, portfolio_id: str) -> Portfolio: ...

    def get_portfolio_by_name_and_user(self, owner_user_id: str, name: str) -> Portfolio | None: ...

    def get_or_create(
        self,
        portfolio_id: str,
        symbol: str,
        *,
        name: str | None = None,
        broker: str = "kis",
        status: str = "enabled",
        active_strategy_id: str | None = None,
        avabile_strategies: list[str] | None = None,
        owner_user_id: str | None = None,
        initial_cash: float = 0.0,
    ) -> Portfolio: ...

    def create_portfolio(
        self,
        portfolio_id: str,
        *,
        owner_user_id: str,
        broker: str,
        status: str,
        name: str,
        symbol: str,
        cash_balance: float,
        asset_quantity: float,
        asset_price: float,
        profit_buffer: float,
        active_strategy_id: str | None,
        avabile_strategies: list[str] | None,
    ) -> Portfolio: ...

    def update_portfolio(self, portfolio_id: str, **fields: object) -> Portfolio: ...

    def list_portfolios(
        self,
        *,
        broker: str | None = None,
        status: str | None = None,
        owner_user_id: str | None = None,
        include_tags: list[str] | None = None,
        exclude_tags: list[str] | None = None,
        match_mode: str | None = None,
        managed_by_daemon_id: str | None = None,
    ) -> list[Portfolio]: ...

    def list_portfolios_with_strategies(
        self,
        owner_user_id: str,
        *,
        include_disabled: bool = True,
        managed_by_daemon_id: str | None = None,
    ) -> list[Portfolio]: ...

    def add_tag(self, portfolio_id: str, *, tag: str) -> PortfolioTag: ...

    def list_tags(self, portfolio_id: str) -> list[PortfolioTag]: ...

    def remove_tag(self, portfolio_id: str, *, tag: str) -> None: ...

    def get_or_create_strategy_set(self, name: str, config: str) -> StrategySet: ...

    def get_strategy_set(self, id: str) -> StrategySet | None: ...

    def list_strategy_sets(self) -> list[StrategySet]: ...

    def delete_strategy_set(self, id: str) -> None: ...

    def save(
        self,
        portfolio: Portfolio,
        *,
        current_price: float,
        action: str,
        trade_price: float,
        quantity: float,
        fee_amount: float,
        tax_amount: float,
        total_value_after: float,
        strategy_set_id: str = "manual",
        note: str = "",
    ) -> None: ...

    def list_recent_trades(self, portfolio_id: str, limit: int = 5) -> list[LedgerEntry]: ...

    def insert_ledger_trade(
        self,
        *,
        asset_id: str,
        order_id: str,
        execution_id: str,
        side: str,
        quantity: float,
        price: float,
        executed_at: datetime,
        fee_amount: float = 0.0,
        tax_amount: float = 0.0,
    ) -> tuple[LedgerTrade, bool]: ...

    def reset(self, portfolio_id: str) -> Portfolio: ...

    def adjust_buffer(self, portfolio_id: str, amount: float, action: str, note: str = "") -> Portfolio: ...

    def transfer_buffer(self, portfolio_id: str, amount: float, direction: str, note: str = "") -> Portfolio: ...

    def delete(self, portfolio_id: str, *, clear_ledger: bool = True) -> None: ...

    def create_comment(self, portfolio_id: str, *, content: str) -> PortfolioComment: ...

    def list_comments(self, portfolio_id: str) -> list[PortfolioComment]: ...

    def update_comment(self, portfolio_id: str, comment_id: str, *, content: str) -> PortfolioComment: ...

    def delete_comment(self, portfolio_id: str, comment_id: str) -> None: ...