fin-infra 0.5.0__tar.gz → 0.6.0__tar.gz

{fin_infra-0.5.0 → fin_infra-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fin-infra
-Version: 0.5.0
+Version: 0.6.0
 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.5.0 → fin_infra-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "fin-infra"
-version = "0.5.0"
+version = "0.6.0"
 description = "Financial infrastructure toolkit: banking connections, market data, credit, cashflows, and brokerage integrations"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"

{fin_infra-0.5.0 → fin_infra-0.6.0}/src/fin_infra/banking/__init__.py

@@ -89,6 +89,15 @@ class CreateLinkTokenResponse(BaseModel):
     link_token: str
 
 
+class CreateUpdateLinkTokenRequest(BaseModel):
+    """Request model for creating a link token in update mode (re-authentication)."""
+
+    user_id: str
+    access_token: str = Field(
+        ..., description="Existing access token for the item requiring re-auth"
+    )
+
+
 class ExchangeTokenRequest(BaseModel):
     """Request model for exchanging public token."""
 
@@ -334,6 +343,23 @@ def add_banking(
         link_token = banking.create_link_token(user_id=request.user_id)
         return CreateLinkTokenResponse(link_token=link_token)
 
+    @router.post("/link/update", response_model=CreateLinkTokenResponse)
+    async def create_update_link_token(request: CreateUpdateLinkTokenRequest):
+        """Create link token in update mode for re-authentication.
+
+        Use this endpoint when a user's bank connection has expired
+        (ITEM_LOGIN_REQUIRED error). The returned link token will open
+        Plaid Link in update mode, allowing the user to re-authenticate
+        without creating a new connection.
+
+        After successful re-authentication, the existing access_token
+        remains valid and no token exchange is needed.
+        """
+        link_token = banking.create_link_token(
+            user_id=request.user_id, access_token=request.access_token
+        )
+        return CreateLinkTokenResponse(link_token=link_token)
+
     @router.post("/exchange", response_model=ExchangeTokenResponse)
     async def exchange_token(request: ExchangeTokenRequest):
         """Exchange public token for access token (Plaid flow)."""
@@ -343,8 +369,29 @@ def add_banking(
     @router.get("/accounts")
     async def get_accounts(access_token: str = Depends(get_access_token)):
         """List accounts for access token."""
-        accounts = banking.accounts(access_token=access_token)
-        return {"accounts": accounts}
+        try:
+            accounts = banking.accounts(access_token=access_token)
+            return {"accounts": accounts}
+        except Exception as e:
+            error_str = str(e)
+            # Check for Plaid-specific errors that require user action
+            if "ITEM_LOGIN_REQUIRED" in error_str:
+                raise HTTPException(
+                    status_code=401,
+                    detail="ITEM_LOGIN_REQUIRED: Your bank connection has expired. Please re-authenticate your bank account.",
+                )
+            elif "INVALID_ACCESS_TOKEN" in error_str:
+                raise HTTPException(
+                    status_code=401,
+                    detail="INVALID_ACCESS_TOKEN: The access token is invalid or expired. Please reconnect your bank account.",
+                )
+            elif "ITEM_NOT_FOUND" in error_str:
+                raise HTTPException(
+                    status_code=404,
+                    detail="ITEM_NOT_FOUND: This bank connection no longer exists. Please reconnect your bank account.",
+                )
+            # Re-raise other errors
+            raise
 
     @router.get("/transactions")
     async def get_transactions(

{fin_infra-0.5.0 → fin_infra-0.6.0}/src/fin_infra/providers/banking/plaid_client.py

@@ -81,21 +81,41 @@ class PlaidClient(BankingProvider):
         api_client = plaid.ApiClient(configuration)
         self.client = plaid_api.PlaidApi(api_client)
 
-    def create_link_token(self, user_id: str) -> str:
-        request = LinkTokenCreateRequest(
-            user=LinkTokenCreateRequestUser(client_user_id=user_id),
-            client_name="fin-infra",
-            products=[
+    def create_link_token(self, user_id: str, access_token: str | None = None) -> str:
+        """Create a Plaid Link token for new connections or re-authentication.
+
+        Args:
+            user_id: Client-defined user ID for the Link session
+            access_token: If provided, creates Link in update mode for re-authentication
+                         (used when ITEM_LOGIN_REQUIRED error occurs)
+
+        Returns:
+            Link token string for Plaid Link initialization
+        """
+        # Build base request parameters
+        request_params = {
+            "user": LinkTokenCreateRequestUser(client_user_id=user_id),
+            "client_name": "fin-infra",
+            "country_codes": [CountryCode("US")],
+            "language": "en",
+        }
+
+        if access_token:
+            # Update mode: re-authenticate existing connection
+            # Don't include products - Plaid uses existing item's products
+            request_params["access_token"] = access_token
+        else:
+            # New connection: specify products to enable
+            request_params["products"] = [
                 Products("auth"),  # Account/routing numbers for ACH
                 Products("transactions"),  # Transaction history
                 Products("liabilities"),  # Credit cards, loans, student loans
                 Products("investments"),  # Brokerage, retirement accounts
                 Products("assets"),  # Asset reports for lending/verification
                 Products("identity"),  # Account holder info (name, email, phone)
-            ],
-            country_codes=[CountryCode("US")],
-            language="en",
-        )
+            ]
+
+        request = LinkTokenCreateRequest(**request_params)
         response = self.client.link_token_create(request)
         return cast("str", response["link_token"])
 

{fin_infra-0.5.0 → fin_infra-0.6.0}/src/fin_infra/providers/banking/teller_client.py

@@ -121,7 +121,7 @@ class TellerClient(BankingProvider):
         response.raise_for_status()
         return response.json()
 
-    def create_link_token(self, user_id: str) -> str:
+    def create_link_token(self, user_id: str, access_token: str | None = None) -> str:
         """Create link token for user authentication.
 
         Note: Teller uses a simpler auth flow than Plaid. In production,
@@ -130,6 +130,9 @@ class TellerClient(BankingProvider):
 
         Args:
             user_id: Your application's user identifier
+            access_token: If provided, creates Link in update mode for re-authentication
+                         (used when connection needs to be repaired). Teller handles
+                         this differently than Plaid - see Teller Connect docs.
 
         Returns:
             Link token or enrollment ID for user to authenticate
@@ -138,13 +141,18 @@ class TellerClient(BankingProvider):
             httpx.HTTPStatusError: On HTTP errors
         """
         # Teller's enrollment endpoint for creating application links
+        payload: dict[str, Any] = {
+            "user_id": user_id,
+            "products": ["accounts", "transactions", "balances", "identity"],
+        }
+        # If access_token provided, add it for update mode (re-authentication)
+        if access_token:
+            payload["access_token"] = access_token
+
         response = self._request(
             "POST",
             "/enrollments",
-            json={
-                "user_id": user_id,
-                "products": ["accounts", "transactions", "balances", "identity"],
-            },
+            json=payload,
         )
         return cast("str", response.get("enrollment_id", ""))
 

{fin_infra-0.5.0 → fin_infra-0.6.0}/src/fin_infra/providers/base.py

@@ -32,6 +32,13 @@ from ..models import Candle, Quote
 
 
 class MarketDataProvider(ABC):
+    """Abstract base class for stock and equity market data providers.
+
+    Implement this class to integrate with market data sources like
+    Yahoo Finance, Alpha Vantage, or Polygon.io for real-time quotes
+    and historical price data.
+    """
+
     @abstractmethod
     def quote(self, symbol: str) -> Quote:
         pass
@@ -44,6 +51,12 @@ class MarketDataProvider(ABC):
 
 
 class CryptoDataProvider(ABC):
+    """Abstract base class for cryptocurrency market data providers.
+
+    Implement this class to integrate with crypto exchanges like
+    Binance, Coinbase, or Kraken for ticker data and OHLCV candles.
+    """
+
     @abstractmethod
     def ticker(self, symbol_pair: str) -> Any:
         pass
@@ -57,8 +70,17 @@ class BankingProvider(ABC):
     """Abstract provider for bank account aggregation (Teller, Plaid, MX)."""
 
     @abstractmethod
-    def create_link_token(self, user_id: str) -> str:
-        """Create a link/connect token for user to authenticate with their bank."""
+    def create_link_token(self, user_id: str, access_token: str | None = None) -> str:
+        """Create a link/connect token for user to authenticate with their bank.
+
+        Args:
+            user_id: Client-defined user ID for the Link session
+            access_token: If provided, creates Link in update mode for re-authentication
+                         (used when ITEM_LOGIN_REQUIRED error occurs)
+
+        Returns:
+            Link token string for initializing the bank connection UI
+        """
         pass
 
     @abstractmethod
@@ -90,6 +112,13 @@ class BankingProvider(ABC):
 
 
 class BrokerageProvider(ABC):
+    """Abstract base class for brokerage trading integrations.
+
+    Implement this class to integrate with trading platforms like
+    Alpaca, Interactive Brokers, or TD Ameritrade for order execution,
+    position management, and portfolio tracking.
+    """
+
     @abstractmethod
     def submit_order(
         self,
@@ -185,6 +214,13 @@ class IdentityProvider(ABC):
 
 
 class CreditProvider(ABC):
+    """Abstract base class for credit data providers.
+
+    Implement this class to integrate with credit bureaus like
+    Experian, Equifax, or TransUnion for credit score retrieval
+    and full credit report access.
+    """
+
     @abstractmethod
     def get_credit_score(self, user_id: str, **kwargs: Any) -> Any:
         pass