fin-infra 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

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/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/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/providers/base.py

@@ -70,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

{fin_infra-0.5.1.dist-info → fin_infra-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fin-infra
-Version: 0.5.1
+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.1.dist-info → fin_infra-0.6.0.dist-info}/RECORD

@@ -11,7 +11,7 @@ fin_infra/analytics/rebalancing.py,sha256=VM8MgoJofmrCXPK1rbmVqWGB4FauNmHCL5HOEb
 fin_infra/analytics/savings.py,sha256=n3rGNFP8TU5mW-uz9kOuqX_mDiVnDyAeDN06Q7Abotw,7570
 fin_infra/analytics/scenarios.py,sha256=LE_dZVkbxxAx5sxitGhiOhZfWTlYtVbIvS9pEXkijLc,12246
 fin_infra/analytics/spending.py,sha256=ogLcfF5ZOLMkBIj02RISnA3hiY_PsLWZ2_AAzA7FenY,26209
-fin_infra/banking/__init__.py,sha256=6wwGNITzyehC9MBQc5jy0ewSTuNetyQu2AdND51O55w,22450
+fin_infra/banking/__init__.py,sha256=Lt82vzUZUmekNi_abWz5ySvZlO64FVefd05RAxEd4gU,24537
 fin_infra/banking/history.py,sha256=YB-v9A03IZ_qki6A6mA-RO5Y4imlqk1CyP0W482ufdQ,10563
 fin_infra/banking/utils.py,sha256=HhxZbeaA8zqVttgMiJGnShTo_r_0DaD7T3IMq8n8340,15252
 fin_infra/brokerage/__init__.py,sha256=IXm5ko5T607LodexYSbKNZc6I_2CQGaOwQUlb-w9-ks,17137
@@ -126,9 +126,9 @@ fin_infra/obs/__init__.py,sha256=kMMVl0fdwtJtZeKiusTuw0iO61Jo9-HNXsLmn3ffLRE,631
 fin_infra/obs/classifier.py,sha256=S7kSphgHN1O4GiMUdr3IjuXpoXU0XgGq132_U-njXX4,5153
 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=8Nvd9Ow_v6Scnw79R86uSvRcBRHPgc3ytsQze50E7aM,6524
-fin_infra/providers/banking/teller_client.py,sha256=733Eq-o9Yt7Sm_aWOeunJU4EWYRAaZNS7vgDVGqR0W4,10279
-fin_infra/providers/base.py,sha256=qKRv8C3TBP7r9J9gFxqeSU3Podh6w_eKI5iCPa15Ta8,8668
+fin_infra/providers/banking/plaid_client.py,sha256=6yaXbPxg4QvebZAXyUFUthBIAN1EuXN59BnmTi69n0U,7374
+fin_infra/providers/banking/teller_client.py,sha256=4chf7fQIybp-sgOWOiW9uJfMq31A9KMPcyMfn0Yi_IY,10752
+fin_infra/providers/base.py,sha256=T8XoHTc3SY30XibfrS4eAMXTujgY8s2mJjBeKzscgDo,9037
 fin_infra/providers/brokerage/alpaca.py,sha256=BObiI_dFQZ3fOpTfmZMkri8sVrsz5uW6i5ZVUb0etCU,9923
 fin_infra/providers/brokerage/base.py,sha256=JJFH0Cqca4Rg4rmxfiwcQt-peRoBf4JpG3g6jx8DVks,106
 fin_infra/providers/credit/experian.py,sha256=r7lpFecgOdNEhb_Lxz2Z-BG8R3p2n0XlqDKL7y8NZ-0,482
@@ -174,8 +174,8 @@ fin_infra/utils/deprecation.py,sha256=DTcqv7ECnrWOOwoA07JOnRci4Hqqo9YtKSSmoS-DVP
 fin_infra/utils/http.py,sha256=rDEgYsEBrEe75ml5RA-iSs3xeU5W-3j-czJlT7WbrM4,632
 fin_infra/utils/retry.py,sha256=YiyTgy26eJ1ah7fE2_-ZPa4hv4bIT4OzjYolkNWb5j0,1057
 fin_infra/version.py,sha256=4t_crzhrLum--oyowUMxtjBTzUtWp7oRTF22ewEvJG4,49
-fin_infra-0.5.1.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
-fin_infra-0.5.1.dist-info/METADATA,sha256=u93UU3fU8TPtAPA7YcnL32rFqo7o8VIxQfVeZ6970aA,10842
-fin_infra-0.5.1.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-fin_infra-0.5.1.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
-fin_infra-0.5.1.dist-info/RECORD,,
+fin_infra-0.6.0.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
+fin_infra-0.6.0.dist-info/METADATA,sha256=47DVsqLkuor-waj8iItVs9AECCOctwqOfzfqHM60Qsc,10842
+fin_infra-0.6.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+fin_infra-0.6.0.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
+fin_infra-0.6.0.dist-info/RECORD,,