fin-infra 0.1.56__py3-none-any.whl → 0.1.58__py3-none-any.whl

fin_infra/banking/history.py

@@ -4,6 +4,9 @@ This module provides functionality to record and retrieve historical account bal
 snapshots over time. This enables balance trend analysis, sparklines, and time-series
 visualizations in fintech dashboards.
 
+⚠️ WARNING: This module uses IN-MEMORY storage by default. All data is LOST on restart.
+For production use, integrate with svc-infra SQL database or set FIN_INFRA_STORAGE_BACKEND.
+
 Features:
 - Record daily balance snapshots for accounts
 - Store snapshots in time-series optimized format
@@ -36,6 +39,8 @@ Integration with svc-infra:
 
 from __future__ import annotations
 
+import logging
+import os
 from datetime import date, datetime, timedelta
 from typing import List, Optional
 from pydantic import BaseModel, Field, ConfigDict
@@ -50,8 +55,31 @@ __all__ = [
 ]
 
 
+_logger = logging.getLogger(__name__)
+
 # In-memory storage for testing (will be replaced with SQL database in production)
+# ⚠️ WARNING: All data is LOST on restart when using in-memory storage!
 _balance_snapshots: List[BalanceSnapshot] = []
+_production_warning_logged = False
+
+
+def _check_in_memory_warning() -> None:
+    """Log a warning if using in-memory storage in production."""
+    global _production_warning_logged
+    if _production_warning_logged:
+        return
+    
+    env = os.getenv("ENV", "development").lower()
+    storage_backend = os.getenv("FIN_INFRA_STORAGE_BACKEND", "memory").lower()
+    
+    if env in ("production", "staging") and storage_backend == "memory":
+        _logger.warning(
+            "⚠️ CRITICAL: Balance history using IN-MEMORY storage in %s environment! "
+            "All balance snapshots will be LOST on restart. "
+            "Set FIN_INFRA_STORAGE_BACKEND=sql for production persistence.",
+            env,
+        )
+        _production_warning_logged = True
 
 
 class BalanceSnapshot(BaseModel):
@@ -87,6 +115,8 @@ def record_balance_snapshot(
     This function stores a point-in-time balance record for trend analysis.
     In production, this would write to a SQL database via svc-infra.
 
+    ⚠️ WARNING: Uses in-memory storage by default. Data is LOST on restart!
+
     Args:
         account_id: Account identifier
         balance: Account balance at the snapshot time
@@ -103,6 +133,9 @@ def record_balance_snapshot(
         - In production, use unique constraint on (account_id, date) in SQL
         - Consider using svc-infra jobs for automatic daily snapshots
     """
+    # Check if in-memory storage is being used in production
+    _check_in_memory_warning()
+    
     snapshot = BalanceSnapshot(
         account_id=account_id,
         balance=balance,

fin_infra/credit/experian/auth.py

@@ -27,7 +27,6 @@ import base64
 
 import httpx
 from svc_infra.cache import cache_read
-from svc_infra.cache.tags import invalidate_tags
 
 # Cache key for OAuth tokens: "oauth_token:experian:{base_url_hash}"
 # TTL: 3600 seconds (1 hour) - matches typical OAuth token expiry
@@ -91,7 +90,7 @@ class ExperianAuthManager:
     @cache_read(
         key="oauth_token:experian:{client_id}",  # Use client_id for uniqueness
         ttl=3600,  # 1 hour - matches OAuth token expiry
-        tags=lambda **kw: ["oauth:experian"],
+        tags=lambda **kw: [f"oauth:experian:{kw['client_id']}"],  # Client-specific tag
     )
     async def _get_token_cached(self, *, client_id: str) -> str:
         """Cached token getter (internal method).
@@ -144,10 +143,10 @@ class ExperianAuthManager:
         return data["access_token"]
 
     async def invalidate(self) -> None:
-        """Invalidate cached token (force refresh on next get_token call).
+        """Invalidate cached token for THIS client (force refresh on next get_token call).
 
-        Uses svc-infra cache tag invalidation to clear all tokens with tag
-        "oauth:experian". Useful when token is rejected by API.
+        Invalidates only the token for this specific client_id, not all Experian tokens.
+        Useful when token is rejected by API.
 
         Example:
             >>> try:
@@ -157,4 +156,8 @@ class ExperianAuthManager:
             ...         await auth.invalidate()
             ...         # Next get_token() will fetch new token
         """
-        await invalidate_tags("oauth:experian")
+        # Import here to avoid circular import
+        from svc_infra.cache.tags import invalidate_tags
+
+        # Invalidate using client-specific tag, not all Experian tokens
+        await invalidate_tags(f"oauth:experian:{self.client_id}")

fin_infra/credit/experian/provider.py

@@ -7,6 +7,7 @@ Features:
 - HTTP client with retry logic
 - Response parsing to Pydantic models
 - FCRA compliance headers
+- FCRA audit logging (required for regulatory compliance)
 - Error handling
 
 Example:
@@ -28,6 +29,8 @@ Example:
     >>> print(len(report.accounts))  # Real credit accounts
 """
 
+import logging
+from datetime import datetime, timezone
 from typing import Literal
 
 from fin_infra.credit.experian.auth import ExperianAuthManager
@@ -37,6 +40,10 @@ from fin_infra.models.credit import CreditReport, CreditScore
 from fin_infra.providers.base import CreditProvider
 from fin_infra.settings import Settings
 
+# FCRA audit logger - use dedicated logger for compliance auditing
+# This should be configured to write to a tamper-evident, append-only log
+fcra_audit_logger = logging.getLogger("fin_infra.fcra_audit")
+
 
 class ExperianProvider(CreditProvider):
     """Experian credit bureau provider with real API integration.
@@ -143,11 +150,14 @@ class ExperianProvider(CreditProvider):
         """Retrieve current credit score for a user from Experian API.
 
         Makes real API call to Experian. Uses FCRA-compliant permissible purpose.
+        All credit pulls are logged for FCRA compliance (15 USC § 1681b).
 
         Args:
             user_id: User identifier (SSN hash or internal ID)
             **kwargs: Additional parameters
                 - permissible_purpose: FCRA purpose (default: "account_review")
+                - requester_ip: IP address of requester (for audit log)
+                - requester_user_id: ID of user/service making the request
 
         Returns:
             CreditScore with real FICO score from Experian
@@ -162,25 +172,79 @@ class ExperianProvider(CreditProvider):
             >>> print(score.score)  # Real FICO score (300-850)
         """
         permissible_purpose = kwargs.get("permissible_purpose", "account_review")
-
-        # Fetch from Experian API
-        data = await self._client.get_credit_score(
-            user_id,
-            permissible_purpose=permissible_purpose,
+        requester_ip = kwargs.get("requester_ip", "unknown")
+        requester_user_id = kwargs.get("requester_user_id", "unknown")
+        
+        # FCRA Audit Log - REQUIRED for regulatory compliance (15 USC § 1681b)
+        # This log must be retained for at least 2 years per FCRA requirements
+        timestamp = datetime.now(timezone.utc).isoformat()
+        fcra_audit_logger.info(
+            "FCRA_CREDIT_PULL",
+            extra={
+                "action": "credit_score_pull",
+                "subject_user_id": user_id,
+                "requester_user_id": requester_user_id,
+                "requester_ip": requester_ip,
+                "permissible_purpose": permissible_purpose,
+                "provider": "experian",
+                "environment": self.environment,
+                "timestamp": timestamp,
+                "result": "pending",
+            }
         )
 
-        # Parse response to CreditScore model
-        return parse_credit_score(data, user_id=user_id)
+        try:
+            # Fetch from Experian API
+            data = await self._client.get_credit_score(
+                user_id,
+                permissible_purpose=permissible_purpose,
+            )
+
+            # Parse response to CreditScore model
+            result = parse_credit_score(data, user_id=user_id)
+            
+            # Log successful pull
+            fcra_audit_logger.info(
+                "FCRA_CREDIT_PULL_SUCCESS",
+                extra={
+                    "action": "credit_score_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "success",
+                    "score_returned": result.score is not None,
+                }
+            )
+            
+            return result
+            
+        except Exception as e:
+            # Log failed pull - still required for FCRA audit trail
+            fcra_audit_logger.warning(
+                "FCRA_CREDIT_PULL_FAILED",
+                extra={
+                    "action": "credit_score_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "error",
+                    "error_type": type(e).__name__,
+                }
+            )
+            raise
 
     async def get_credit_report(self, user_id: str, **kwargs) -> CreditReport:
         """Retrieve full credit report for a user from Experian API.
 
         Makes real API call to Experian. Includes FCRA-required permissible purpose header.
+        All credit pulls are logged for FCRA compliance (15 USC § 1681b).
 
         Args:
             user_id: User identifier (SSN hash or internal ID)
             **kwargs: Additional parameters
                 - permissible_purpose: FCRA purpose (default: "account_review")
+                - requester_ip: IP address of requester (for audit log)
+                - requester_user_id: ID of user/service making the request
 
         Returns:
             CreditReport with real credit data from Experian
@@ -196,15 +260,69 @@ class ExperianProvider(CreditProvider):
             >>> print(report.score.score)  # Real FICO score
         """
         permissible_purpose = kwargs.get("permissible_purpose", "account_review")
-
-        # Fetch from Experian API
-        data = await self._client.get_credit_report(
-            user_id,
-            permissible_purpose=permissible_purpose,
+        requester_ip = kwargs.get("requester_ip", "unknown")
+        requester_user_id = kwargs.get("requester_user_id", "unknown")
+        
+        # FCRA Audit Log - REQUIRED for regulatory compliance (15 USC § 1681b)
+        # Full credit report pulls have stricter requirements than score-only pulls
+        # This log must be retained for at least 2 years per FCRA requirements
+        timestamp = datetime.now(timezone.utc).isoformat()
+        fcra_audit_logger.info(
+            "FCRA_CREDIT_PULL",
+            extra={
+                "action": "credit_report_pull",
+                "subject_user_id": user_id,
+                "requester_user_id": requester_user_id,
+                "requester_ip": requester_ip,
+                "permissible_purpose": permissible_purpose,
+                "provider": "experian",
+                "environment": self.environment,
+                "timestamp": timestamp,
+                "result": "pending",
+                "report_type": "full",
+            }
         )
 
-        # Parse response to CreditReport model
-        return parse_credit_report(data, user_id=user_id)
+        try:
+            # Fetch from Experian API
+            data = await self._client.get_credit_report(
+                user_id,
+                permissible_purpose=permissible_purpose,
+            )
+
+            # Parse response to CreditReport model
+            result = parse_credit_report(data, user_id=user_id)
+            
+            # Log successful pull
+            fcra_audit_logger.info(
+                "FCRA_CREDIT_PULL_SUCCESS",
+                extra={
+                    "action": "credit_report_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "success",
+                    "accounts_returned": len(result.accounts) if result.accounts else 0,
+                    "inquiries_returned": len(result.inquiries) if result.inquiries else 0,
+                }
+            )
+            
+            return result
+            
+        except Exception as e:
+            # Log failed pull - still required for FCRA audit trail
+            fcra_audit_logger.warning(
+                "FCRA_CREDIT_PULL_FAILED",
+                extra={
+                    "action": "credit_report_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "error",
+                    "error_type": type(e).__name__,
+                }
+            )
+            raise
 
     async def subscribe_to_changes(self, user_id: str, webhook_url: str, **kwargs) -> str:
         """Subscribe to credit score change notifications from Experian.

fin_infra/investments/ease.py

@@ -46,7 +46,7 @@ def easy_investments(
         Plaid:
             - PLAID_CLIENT_ID: Plaid client ID
             - PLAID_SECRET: Plaid secret key
-            - PLAID_ENV: Environment (sandbox/development/production), default: sandbox
+            - PLAID_ENVIRONMENT: Environment (sandbox/development/production), default: sandbox
 
         SnapTrade:
             - SNAPTRADE_CLIENT_ID: SnapTrade client ID
@@ -177,7 +177,7 @@ def _create_plaid_provider(**config: Any) -> InvestmentProvider:
     # Get credentials from config or environment
     client_id = config.get("client_id") or os.getenv("PLAID_CLIENT_ID")
     secret = config.get("secret") or os.getenv("PLAID_SECRET")
-    environment = config.get("environment") or os.getenv("PLAID_ENV", "sandbox")
+    environment = config.get("environment") or os.getenv("PLAID_ENVIRONMENT", "sandbox")
 
     # Validate required credentials
     if not client_id or not secret:

fin_infra/investments/providers/base.py

@@ -217,8 +217,9 @@ class InvestmentProvider(ABC):
         )
 
         total_gain_loss = total_value - total_cost_basis
+        # Use != 0 to handle short sales (negative cost basis)
         total_gain_loss_percent = (
-            (total_gain_loss / total_cost_basis * 100) if total_cost_basis > 0 else 0.0
+            (total_gain_loss / total_cost_basis * 100) if total_cost_basis != 0 else 0.0
         )
 
         return {

fin_infra/investments/providers/snaptrade.py

@@ -20,7 +20,6 @@ from ..models import (
     InvestmentAccount,
     InvestmentTransaction,
     Security,
-    SecurityType,
     TransactionType,
 )
 from .base import InvestmentProvider
@@ -96,6 +95,25 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
             timeout=30.0,
         )
 
+    def _auth_headers(self, user_id: str, user_secret: str) -> Dict[str, str]:
+        """Build authentication headers for SnapTrade API requests.
+        
+        SECURITY: User secrets are passed in headers, NOT URL params.
+        URL params are logged in access logs, browser history, and proxy logs.
+        Headers are not logged by default in most web servers.
+        
+        Args:
+            user_id: SnapTrade user ID
+            user_secret: SnapTrade user secret (sensitive!)
+            
+        Returns:
+            Dict with authentication headers
+        """
+        return {
+            "userId": user_id,
+            "userSecret": user_secret,
+        }
+
     async def get_holdings(
         self,
         access_token: str,
@@ -123,12 +141,12 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
             ...     print(f"{holding.security.ticker_symbol}: P&L ${pnl}")
         """
         user_id, user_secret = self._parse_access_token(access_token)
+        auth_headers = self._auth_headers(user_id, user_secret)
 
         try:
             # Get all accounts
             accounts_url = f"{self.base_url}/accounts"
-            params = {"userId": user_id, "userSecret": user_secret}
-            response = await self.client.get(accounts_url, params=params)
+            response = await self.client.get(accounts_url, headers=auth_headers)
             response.raise_for_status()
             accounts = await response.json()
 
@@ -143,8 +161,7 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
                 positions_url = (
                     f"{self.base_url}/accounts/{account_id}/positions"
                 )
-                pos_params = {"userId": user_id, "userSecret": user_secret}
-                pos_response = await self.client.get(positions_url, params=pos_params)
+                pos_response = await self.client.get(positions_url, headers=auth_headers)
                 pos_response.raise_for_status()
                 positions = await pos_response.json()
 
@@ -192,12 +209,12 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
             raise ValueError("start_date must be before end_date")
 
         user_id, user_secret = self._parse_access_token(access_token)
+        auth_headers = self._auth_headers(user_id, user_secret)
 
         try:
             # Get all accounts
             accounts_url = f"{self.base_url}/accounts"
-            params = {"userId": user_id, "userSecret": user_secret}
-            response = await self.client.get(accounts_url, params=params)
+            response = await self.client.get(accounts_url, headers=auth_headers)
             response.raise_for_status()
             accounts = await response.json()
 
@@ -212,13 +229,12 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
                 transactions_url = (
                     f"{self.base_url}/accounts/{account_id}/transactions"
                 )
+                # Date params are non-sensitive, only auth goes in headers
                 tx_params = {
-                    "userId": user_id,
-                    "userSecret": user_secret,
                     "startDate": start_date.isoformat(),
                     "endDate": end_date.isoformat(),
                 }
-                tx_response = await self.client.get(transactions_url, params=tx_params)
+                tx_response = await self.client.get(transactions_url, params=tx_params, headers=auth_headers)
                 tx_response.raise_for_status()
                 transactions = await tx_response.json()
 
@@ -297,12 +313,12 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
             ...     print(f"  P&L: {account.total_unrealized_gain_loss_percent:.2f}%")
         """
         user_id, user_secret = self._parse_access_token(access_token)
+        auth_headers = self._auth_headers(user_id, user_secret)
 
         try:
             # Get all accounts
             accounts_url = f"{self.base_url}/accounts"
-            params = {"userId": user_id, "userSecret": user_secret}
-            response = await self.client.get(accounts_url, params=params)
+            response = await self.client.get(accounts_url, headers=auth_headers)
             response.raise_for_status()
             accounts = await response.json()
 
@@ -315,8 +331,7 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
                 positions_url = (
                     f"{self.base_url}/accounts/{account_id}/positions"
                 )
-                pos_params = {"userId": user_id, "userSecret": user_secret}
-                pos_response = await self.client.get(positions_url, params=pos_params)
+                pos_response = await self.client.get(positions_url, headers=auth_headers)
                 pos_response.raise_for_status()
                 positions = await pos_response.json()
 
@@ -328,8 +343,7 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
 
                 # Get account balances
                 balances_url = f"{self.base_url}/accounts/{account_id}/balances"
-                bal_params = {"userId": user_id, "userSecret": user_secret}
-                bal_response = await self.client.get(balances_url, params=bal_params)
+                bal_response = await self.client.get(balances_url, headers=auth_headers)
                 bal_response.raise_for_status()
                 balances = await bal_response.json()
 
@@ -373,11 +387,11 @@ class SnapTradeInvestmentProvider(InvestmentProvider):
             ...     print(f"Connected: {conn['brokerage_name']}")
         """
         user_id, user_secret = self._parse_access_token(access_token)
+        auth_headers = self._auth_headers(user_id, user_secret)
 
         try:
             url = f"{self.base_url}/connections"
-            params = {"userId": user_id, "userSecret": user_secret}
-            response = await self.client.get(url, params=params)
+            response = await self.client.get(url, headers=auth_headers)
             response.raise_for_status()
             return await response.json()
 

fin_infra/models/accounts.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+from decimal import Decimal
 from enum import Enum
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 
 class AccountType(str, Enum):
@@ -16,11 +17,26 @@ class AccountType(str, Enum):
 
 
 class Account(BaseModel):
+    """Financial account model.
+    
+    Uses Decimal for balance fields to prevent floating-point precision errors
+    in financial calculations (e.g., $0.01 + $0.02 != $0.03 with float).
+    """
     id: str
     name: str
     type: AccountType
     mask: Optional[str] = None
     currency: str = "USD"
     institution: Optional[str] = None
-    balance_available: Optional[float] = None
-    balance_current: Optional[float] = None
+    balance_available: Optional[Decimal] = None
+    balance_current: Optional[Decimal] = None
+
+    @field_validator("balance_available", "balance_current", mode="before")
+    @classmethod
+    def _coerce_balance_to_decimal(cls, v):
+        """Coerce float/int to Decimal for backwards compatibility."""
+        if v is None:
+            return v
+        if isinstance(v, (int, float)):
+            return Decimal(str(v))
+        return v

fin_infra/models/transactions.py

@@ -1,16 +1,30 @@
 from __future__ import annotations
 
 from datetime import date
+from decimal import Decimal
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 
 class Transaction(BaseModel):
+    """Financial transaction model.
+    
+    Uses Decimal for amount to prevent floating-point precision errors
+    in financial calculations (e.g., $0.01 + $0.02 != $0.03 with float).
+    """
     id: str
     account_id: str
     date: date
-    amount: float
+    amount: Decimal
     currency: str = "USD"
     description: Optional[str] = None
     category: Optional[str] = None
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _coerce_amount_to_decimal(cls, v):
+        """Coerce float/int to Decimal for backwards compatibility."""
+        if isinstance(v, (int, float)):
+            return Decimal(str(v))
+        return v

fin_infra/net_worth/calculator.py

@@ -100,18 +100,27 @@ def calculate_net_worth(
 
     Returns:
         Net worth in base currency
+        
+    Raises:
+        ValueError: If assets or liabilities contain non-base currencies and no
+            exchange rate conversion is available. This prevents silent data loss.
     """
+    import logging
+    logger = logging.getLogger(__name__)
+    
+    # Collect any non-base currency items for error reporting
+    non_base_assets: list[tuple[str, str, float]] = []
+    non_base_liabilities: list[tuple[str, str, float]] = []
+    
     # Sum all assets (use market_value if available, otherwise balance)
     total_assets = 0.0
     for asset in assets:
         # Use market value for investments/crypto (includes unrealized gains)
         amount = asset.market_value if asset.market_value is not None else asset.balance
 
-        # Normalize to base currency (future: implement currency conversion)
-        # For now, assume all are in USD
+        # Check for non-base currency
         if asset.currency != base_currency:
-            # TODO: Implement currency conversion with exchange rate API
-            # For V1, we'll require all accounts in USD or skip non-USD
+            non_base_assets.append((asset.name or asset.account_id, asset.currency, amount))
             continue
 
         total_assets += amount
@@ -119,13 +128,30 @@ def calculate_net_worth(
     # Sum all liabilities
     total_liabilities = 0.0
     for liability in liabilities:
-        # Normalize to base currency
+        # Check for non-base currency
         if liability.currency != base_currency:
-            # TODO: Implement currency conversion
+            non_base_liabilities.append((liability.name or liability.account_id, liability.currency, liability.balance))
             continue
 
         total_liabilities += liability.balance
 
+    # If any non-base currency items were found, log warning and raise error
+    # This prevents silent data loss where user's net worth is wrong
+    if non_base_assets or non_base_liabilities:
+        items_msg = []
+        if non_base_assets:
+            items_msg.append(f"Assets: {non_base_assets}")
+        if non_base_liabilities:
+            items_msg.append(f"Liabilities: {non_base_liabilities}")
+        
+        error_msg = (
+            f"Cannot calculate net worth: found accounts in non-{base_currency} currencies. "
+            f"Currency conversion not yet implemented. {'; '.join(items_msg)}. "
+            f"Either convert all accounts to {base_currency} or wait for currency conversion feature."
+        )
+        logger.warning(error_msg)
+        raise ValueError(error_msg)
+
     return total_assets - total_liabilities
 
 

fin_infra/providers/banking/plaid_client.py

@@ -54,12 +54,20 @@ class PlaidClient(BankingProvider):
         
         # Map environment string to Plaid Environment enum
         # Note: Plaid only has Sandbox and Production (no Development in SDK)
+        env_str = environment or "sandbox"
         env_map = {
             "sandbox": plaid.Environment.Sandbox,
-            "development": plaid.Environment.Sandbox,  # Map development to sandbox
+            "development": plaid.Environment.Sandbox,  # Map development to sandbox (Plaid SDK limitation)
             "production": plaid.Environment.Production,
         }
-        host = env_map.get(environment or "sandbox", plaid.Environment.Sandbox)
+        
+        if env_str not in env_map:
+            raise ValueError(
+                f"Invalid Plaid environment: '{env_str}'. "
+                f"Must be one of: sandbox, development, production"
+            )
+        
+        host = env_map[env_str]
         
         # Configure Plaid client (v8.0.0+ API)
         configuration = plaid.Configuration(

fin_infra/providers/base.py

@@ -114,7 +114,27 @@ class TaxProvider(ABC):
 class InvestmentProvider(ABC):
     """Provider for investment holdings and portfolio data (Plaid, SnapTrade).
     
-    Full implementation in fin_infra.investments.providers.base.
-    This is a placeholder for consistency with other provider types.
+    This is a minimal ABC for type checking. The full implementation with
+    all abstract methods is in fin_infra.investments.providers.base.InvestmentProvider.
+    
+    Abstract Methods (defined in full implementation):
+        - get_holdings(access_token, account_ids) -> List[Holding]
+        - get_transactions(access_token, start_date, end_date, account_ids) -> List[InvestmentTransaction]
+        - get_securities(access_token, security_ids) -> List[Security]
+        - get_investment_accounts(access_token) -> List[InvestmentAccount]
+    
+    Example:
+        >>> from fin_infra.investments import easy_investments
+        >>> provider = easy_investments(provider="plaid")
+        >>> holdings = await provider.get_holdings(access_token)
     """
-    pass
+    
+    @abstractmethod
+    async def get_holdings(self, access_token: str, account_ids: list[str] | None = None) -> list:
+        """Fetch holdings for investment accounts."""
+        pass
+    
+    @abstractmethod
+    async def get_investment_accounts(self, access_token: str) -> list:
+        """Fetch investment accounts with aggregated holdings."""
+        pass

fin_infra/providers/brokerage/alpaca.py

@@ -105,6 +105,9 @@ class AlpacaBrokerage(BrokerageProvider):
     ) -> dict:
         """Submit an order to Alpaca.
 
+        IMPORTANT: client_order_id is auto-generated if not provided to ensure
+        idempotency. Network retries without idempotency can cause DOUBLE ORDERS.
+
         Args:
             symbol: Trading symbol (e.g., "AAPL")
             qty: Order quantity
@@ -113,14 +116,20 @@ class AlpacaBrokerage(BrokerageProvider):
             time_in_force: "day", "gtc", "ioc", or "fok" (default: "day")
             limit_price: Limit price (required for limit/stop_limit orders)
             stop_price: Stop price (required for stop/stop_limit orders)
-            client_order_id: Optional client order ID
+            client_order_id: Client order ID for idempotency. Auto-generated if not provided.
 
         Returns:
-            Order dict with id, status, filled_qty, etc.
+            Order dict with id, status, filled_qty, client_order_id, etc.
 
         Raises:
             Exception: If order submission fails
         """
+        # CRITICAL: Auto-generate client_order_id for idempotency if not provided.
+        # Without this, network retries can cause duplicate order execution = MONEY LOSS.
+        if client_order_id is None:
+            import uuid
+            client_order_id = str(uuid.uuid4())
+
         order = self.client.submit_order(
             symbol=symbol,
             qty=qty,

fin_infra/settings.py

@@ -12,7 +12,7 @@ class Settings(BaseSettings):
     # Plaid
     plaid_client_id: str | None = Field(default=None, alias="PLAID_CLIENT_ID")
     plaid_secret: str | None = Field(default=None, alias="PLAID_SECRET")
-    plaid_env: str = Field(default="sandbox", alias="PLAID_ENV")
+    plaid_env: str = Field(default="sandbox", alias="PLAID_ENVIRONMENT")
 
     # Alpaca
     alpaca_api_key: str | None = Field(default=None, alias="ALPACA_API_KEY")

{fin_infra-0.1.56.dist-info → fin_infra-0.1.58.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fin-infra
-Version: 0.1.56
+Version: 0.1.58
 Summary: Financial infrastructure toolkit: banking connections, market data, credit, cashflows, and brokerage integrations
 License: MIT
 Keywords: finance,banking,plaid,brokerage,markets,credit,tax,cashflow,fintech,infra

{fin_infra-0.1.56.dist-info → fin_infra-0.1.58.dist-info}/RECORD

@@ -12,7 +12,7 @@ fin_infra/analytics/savings.py,sha256=tavIRZtu9FjCm-DeWg5f060GcsdgD-cl-vgKOnieOU
 fin_infra/analytics/scenarios.py,sha256=LE_dZVkbxxAx5sxitGhiOhZfWTlYtVbIvS9pEXkijLc,12246
 fin_infra/analytics/spending.py,sha256=ypgL52JOsneTsFa2_aFB9fVuu9QWQsImQYChtECeA4Y,25833
 fin_infra/banking/__init__.py,sha256=wva1SEyrH2po79YycQ_00ZyC2tVeuO3uYcyvudOW484,22267
-fin_infra/banking/history.py,sha256=NvPwcP_phNbyA3bFejasocm1UjoX5pSbgdpEbbhni4g,9360
+fin_infra/banking/history.py,sha256=1ufAwkTnXr-QJetFzJl4xA2e3dqd1-TkT8pf46MNfho,10630
 fin_infra/banking/utils.py,sha256=B2ebnTeUz-56l8XMBWnf2txFOr0bXIo3cKPio7_bhc4,15711
 fin_infra/brokerage/__init__.py,sha256=RB0wbVlxM9PCbWUezzjrOf19JucVDpCvNlT62LoMzho,17023
 fin_infra/budgets/__init__.py,sha256=3VTYU_OdqblYiP5fjHHiw3m-FSj5trPz7XVTb3f3rBc,4106
@@ -50,10 +50,10 @@ fin_infra/compliance/__init__.py,sha256=03eXxRDFeQnEaz_W8MVYYDv_ni7Urue2StLf02jH
 fin_infra/credit/__init__.py,sha256=cwCP_WlrG-0yb_L4zYsuzEsSalcfiCY9ItqXfD7Jx9E,6719
 fin_infra/credit/add.py,sha256=etRbqw15vzUQfvnMTmznZlLiKy2GVEe8ok08Ea3pjdE,8490
 fin_infra/credit/experian/__init__.py,sha256=g3IJGvDOMsnB0er0Uwdvl6hGKKTOazqJxSDnB2oIBm0,761
-fin_infra/credit/experian/auth.py,sha256=vEOeUcLYe26Gw08doZy1pRY-ShxFH9YAnn4mUXrPIl8,5362
+fin_infra/credit/experian/auth.py,sha256=SHi3YNPFwEAS_SraAiAK7V-DEokgaq-7-eqkkBrcgMo,5562
 fin_infra/credit/experian/client.py,sha256=sxdoB9pyIntyZ9MKDN-x8tUuyllZSOq7KzOrHjeYs8s,8918
 fin_infra/credit/experian/parser.py,sha256=7ptdLyTWWqHWqCo1CXn6L7XaIn9ZRRuOaATbFmMZZ64,7489
-fin_infra/credit/experian/provider.py,sha256=5G1FJcMViFCOrCjJhrE5ZPJcx2USyM5Xl1cXZjs6lRc,8720
+fin_infra/credit/experian/provider.py,sha256=iG2cyftdc7c2pvKWVfeNd3vF_ylNayyhgyUG7Jnl1VI,13766
 fin_infra/credit/mock.py,sha256=xKWZk3fhuIYRfiZkNc9fbHUNViNKjmOLSj0MTI1f4ik,5356
 fin_infra/crypto/__init__.py,sha256=HpplYEY8GiBz55ehYRDQxs8SWJIW1smBs9eFOKt_nzI,8318
 fin_infra/crypto/insights.py,sha256=fuGFKkOkZoYKit29_kbH1T2XWvbMKVmhFUd57E2XOmQ,11695
@@ -80,12 +80,12 @@ fin_infra/insights/aggregator.py,sha256=XG32mN5w5Nc4AZllmfl1esL4q44mFAf0Fvj9mWev
 fin_infra/insights/models.py,sha256=xov_YV8oBLJt3YdyVjbryRfcXqmGeGiPvZsZHSbvtl8,3202
 fin_infra/investments/__init__.py,sha256=UiWvTdKH7V9aaqZLunPT1_QGfXBAZbPk_w4QmeLWLqo,6324
 fin_infra/investments/add.py,sha256=XjIuXnGY1-tJWeDqsgTpbP2-ruh-Ulbu0IsSlyKRsqw,16416
-fin_infra/investments/ease.py,sha256=Z-HqNgcB33cWIcRtuWLzUH5-Eou8mDWKNssp5tMgE2g,9213
+fin_infra/investments/ease.py,sha256=ocs7xvnZ1u8riFjH9KHi1yFEUF0lfuEcd-QMpsuiOu8,9229
 fin_infra/investments/models.py,sha256=NHnkvtMa1QYp_TpuuqT4u3cWEJi3OhW-1e-orMuR47o,16107
 fin_infra/investments/providers/__init__.py,sha256=V1eIzz6EnGJ-pq-9L3S2-evmcExF-YdZfd5P6JMyDtc,383
-fin_infra/investments/providers/base.py,sha256=cONlsu_z4eSpgzv5ky0-kjWarrC-KYd4tgaghSnarYg,9826
+fin_infra/investments/providers/base.py,sha256=KaJdIdeWi2WaWAogcFZw7jcqQ_IzMZw6misBNk-n6bE,9890
 fin_infra/investments/providers/plaid.py,sha256=OKzLNPAcBiZlqBRCOeaBogB5fvHdvlRpPuGHKvRGS2E,18069
-fin_infra/investments/providers/snaptrade.py,sha256=No7KgJ31r831Z1QoHLuKwRcfiGEiN9mkQsWvkMfqkZo,23047
+fin_infra/investments/providers/snaptrade.py,sha256=IUgXoI7UCBXOAxn2J62cOiQSW02sujqEk47nb638264,23508
 fin_infra/investments/scaffold_templates/README.md,sha256=PhgxfMLrro2Jz83b7XEnBi7lexiWKqlMrd2UU2Rbs8A,12149
 fin_infra/investments/scaffold_templates/__init__.py,sha256=iR0oiAzXFYXHBnVJjaEnAzk6omncYOLg0TKMJ7xomBc,82
 fin_infra/investments/scaffold_templates/models.py.tmpl,sha256=5inP5-jw-qEfPYxSN71tn4AojZ9PesOIeuHTw181N-c,5849
@@ -93,18 +93,18 @@ fin_infra/investments/scaffold_templates/repository.py.tmpl,sha256=XwOEpQZfuXut1
 fin_infra/investments/scaffold_templates/schemas.py.tmpl,sha256=knWmn-Kyr7AdgPD4ZPMb6T49ZuPXeuOMqmjYNyA0CA0,5451
 fin_infra/markets/__init__.py,sha256=mStcYiA4dq2yHEyStZyOLd-KkW-Jf657l8NSLLa_MU8,9512
 fin_infra/models/__init__.py,sha256=q3SkGzDGFkoAMxwqJw8i4cHWt5NGU5ypjOgntxDGVKo,860
-fin_infra/models/accounts.py,sha256=M5lgX3r1_PbN-UVNY78P6UhPtxp8Hd3uO2rr9EO7v1Q,551
+fin_infra/models/accounts.py,sha256=PeobjGg6WM70OvOTe0JIo0zo7tBM0PDAcyClQT-Jo4o,1141
 fin_infra/models/brokerage.py,sha256=z6Zyf0N5zmmXtrN2y_4fNmtIP5wNq40H8lrHLBwY7rc,8311
 fin_infra/models/candle.py,sha256=7vrDxR1JFZodMUG8OGB0ft1_oaGW16gZtawjZ_2OwhA,535
 fin_infra/models/credit.py,sha256=rSdSURsMe9_i2gxmwPTDwNQWOuM2zutL-OhvHsnbtmw,12144
 fin_infra/models/money.py,sha256=5BX8IQZkrNtjjnGIQAK2tyKnVim0R-yc1F_EBxUhcr0,400
 fin_infra/models/quotes.py,sha256=_2cDJS8_RLo4tLpJlqWd32J8uFNP0bbf1V_0u3NuLwo,543
 fin_infra/models/tax.py,sha256=lhNVIW650CdtpfgmSyMMJdojV7QnpHOUFQKiwMLTT4A,15656
-fin_infra/models/transactions.py,sha256=uBwxdlZh7tyIkqfQZggPZuMDpDRLhI8SeXwKZZgg4LU,318
+fin_infra/models/transactions.py,sha256=zlu7Ath91ZmqQWKn8Bd_iV_XreWTDXFWJyfTTZ3J-ss,828
 fin_infra/net_worth/__init__.py,sha256=EjEuHNg8gEfFwbfko1-o5j-gSUZ2FcO9h7l05C-zAJM,3101
 fin_infra/net_worth/add.py,sha256=5xYy2L5hEEPiQNF79i-ArWVztLXk2XM97DoZYNWGAz8,23100
 fin_infra/net_worth/aggregator.py,sha256=grif-N8qk77L_JQ4IlcOJaKKP1qpxel0lIV_ll3HgjI,12646
-fin_infra/net_worth/calculator.py,sha256=s09fbPEn1TMQjyqh09bUI5SdZNECcjll0P7GMeBy2fM,11966
+fin_infra/net_worth/calculator.py,sha256=JERDtZyFurw5x2NYqfHvJzv6qigamI3AFfR-wesTj_E,13133
 fin_infra/net_worth/ease.py,sha256=wrQ5zI2nVsbSCVFQXBSEt0DMI6xK-jv5m0AyZkyuOx8,15106
 fin_infra/net_worth/goals.py,sha256=BJGxdsMjvgQDELFEJo-ai3DvsAzUNXvzMXkwovHr8yQ,1238
 fin_infra/net_worth/insights.py,sha256=4GUyV-YEXgBs0ZuBx1OnSV0B2N-e0jvKoIgQ2yB7M7g,25250
@@ -125,10 +125,10 @@ fin_infra/obs/__init__.py,sha256=kMMVl0fdwtJtZeKiusTuw0iO61Jo9-HNXsLmn3ffLRE,631
 fin_infra/obs/classifier.py,sha256=6R2q-w71tk7WfXF5MBPqawxogcj6tILKZPlkpRZNDfg,5083
 fin_infra/providers/__init__.py,sha256=jxhQm79T6DVXf7Wpy7luL-p50cE_IMUbjt4o3apzJQU,768
 fin_infra/providers/banking/base.py,sha256=KeNU4ur3zLKHVsBF1LQifcs2AKX06IEE-Rx_SetFeAs,102
-fin_infra/providers/banking/plaid_client.py,sha256=q0JuU5ULYc2V-RoZGiJQSAprymcsSlJMGmildH0aHDg,6302
+fin_infra/providers/banking/plaid_client.py,sha256=t4pW6vkecx1AgkKDXUSiileAxA6pu6dA4L6c8zSff0k,6545
 fin_infra/providers/banking/teller_client.py,sha256=r4apwTNt8FJ2Rn2bC97orzaVYFkE0yMXXl--H5rtph0,9800
-fin_infra/providers/base.py,sha256=icMIQ6kmIvN15bkpDCR6C4DC2GaO-oMiFsaUsoWsRag,3303
-fin_infra/providers/brokerage/alpaca.py,sha256=f3mnsNxJ_daxuaHVmIhv8PZNnehf_LTulw1qoS4OEnc,9361
+fin_infra/providers/base.py,sha256=oLzdExPGE7yg-URtin3vGTQ8hEzG7UnTmDGDWJB5oL0,4273
+fin_infra/providers/brokerage/alpaca.py,sha256=eOzdRp45_VeD1r_2k0IudxFn0IRhGogn-htF5IJVKnk,9862
 fin_infra/providers/brokerage/base.py,sha256=JJFH0Cqca4Rg4rmxfiwcQt-peRoBf4JpG3g6jx8DVks,106
 fin_infra/providers/credit/experian.py,sha256=hNEVqmCaPT72NHV3Nw3sKOYPX0kIsl819ucqUc-7z2k,341
 fin_infra/providers/identity/stripe_identity.py,sha256=JQGJRuQdWP5dWDcROgtz1RrmpkytRv95H6Fn-x1kifU,501
@@ -164,7 +164,7 @@ fin_infra/security/models.py,sha256=riQO-083p5rDMRrFxRnc2PTkxkAf-HsSpGvrnzboCNE,
 fin_infra/security/pii_filter.py,sha256=lfARBmPRekkyXKJV0tWI_0KVaDsdV61VH-8RHxvbqUs,8307
 fin_infra/security/pii_patterns.py,sha256=hsW-2RwA8XW3wprsvzkqcWK9uX_HrdLH53g7OUKiwvM,3046
 fin_infra/security/token_store.py,sha256=lNnGUlQCJImc-OAcHbHij8xYHkV3jb6MgBpwEra-T_M,5862
-fin_infra/settings.py,sha256=C1sk05U77TWGMoHCqdHgHNGBfdAI-ryGFsvJGkdDfJU,1380
+fin_infra/settings.py,sha256=xitpBQJmuvSy9prQhvXOW1scbwB1KAyGD8XqYgU_hQU,1388
 fin_infra/tax/__init__.py,sha256=NXUjV-k-rw4774pookY3UOwEXYRQauJze6Yift5RjW0,6107
 fin_infra/tax/add.py,sha256=xmy0hXsWzEj5p-_9A5hkljFjF_FpnbCQQZ5e8FPChBI,14568
 fin_infra/tax/tlh.py,sha256=QFnepLuJW8L71SccRTE54eN5ILyDGs1XNG5p-aVM_b8,21543
@@ -173,8 +173,8 @@ fin_infra/utils/http.py,sha256=wgXo5amXyzAX49v_lRUvp4Xxq8nodX32CMJyWl6u89I,568
 fin_infra/utils/retry.py,sha256=VxT4ssP4r8Krl3KThvI-opPMhGCpZUCH4rUyit1LEUk,967
 fin_infra/utils.py,sha256=VxT4ssP4r8Krl3KThvI-opPMhGCpZUCH4rUyit1LEUk,967
 fin_infra/version.py,sha256=4t_crzhrLum--oyowUMxtjBTzUtWp7oRTF22ewEvJG4,49
-fin_infra-0.1.56.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
-fin_infra-0.1.56.dist-info/METADATA,sha256=ZVv5v_Fo-c24vxnUJZpdsE8ISvx3QBrTxacdLybp0lA,10182
-fin_infra-0.1.56.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-fin_infra-0.1.56.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
-fin_infra-0.1.56.dist-info/RECORD,,
+fin_infra-0.1.58.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
+fin_infra-0.1.58.dist-info/METADATA,sha256=YnC_rmHC_X1zvZu2BKMVDXDKABUbI5GeODWLWnLXSqQ,10182
+fin_infra-0.1.58.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+fin_infra-0.1.58.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
+fin_infra-0.1.58.dist-info/RECORD,,