vhi-python 0.1.0__py3-none-any.whl

vhi/__init__.py

@@ -0,0 +1,11 @@
+from .client import VhiClient
+from .exceptions import VhiAuthenticationError, VhiMfaRequiredError, VhiApiError
+from .models import ClaimStatement
+
+__all__ = [
+    "VhiClient",
+    "VhiAuthenticationError",
+    "VhiMfaRequiredError",
+    "VhiApiError",
+    "ClaimStatement"
+]

vhi/client.py

@@ -0,0 +1,199 @@
+import requests
+import os
+from typing import Callable, Optional, List
+from .exceptions import VhiAuthenticationError, VhiMfaRequiredError, VhiApiError
+from .models import ClaimStatement
+
+class VhiClient:
+    """
+    A client library for interacting with the Vhi API.
+    Handles authentication, MFA callbacks, claims retrieval, and document downloads.
+    """
+    DEFAULT_CONFIG_URL = "https://www.vhi.ie/myvhi/myclaimstatements" # Usually embedded here
+    
+    def __init__(self, username: str, password: str, mfa_callback: Optional[Callable[[], str]] = None):
+        """
+        Initialize the VhiClient.
+        
+        Args:
+            username: User's email address.
+            password: User's password.
+            mfa_callback: A callable that returns the 2FA OTP string when invoked.
+        """
+        self.username = username
+        self.password = password
+        self.mfa_callback = mfa_callback
+        
+        # State management
+        self.session = requests.Session()
+        
+        # Default Browser Headers to mimic browser and avoid WAF
+        self.session.headers.update({
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+            "Accept-Language": "en-US,en;q=0.9",
+        })
+        
+        self.is_authenticated = False
+        self.apis_base_url = "https://apis.vhi.ie" # Will be updated during discovery if necessary
+        
+    def _fetch_environment_config(self):
+        """
+        Optional: Dynamically discovers the API base URL.
+        Currently defaults to known https://apis.vhi.ie.
+        """
+        try:
+            # We skip full parsing of the config to avoid complex scraping
+            # We hardcode the reliable apis.vhi.ie gateway for now as per instructions.
+            pass
+        except Exception:
+            pass
+
+    def login(self):
+        """
+        Performs the login flow. Handles the MFA challenge if required.
+        """
+        # Set proper fetch headers
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Origin": "https://www.vhi.ie",
+            "Referer": "https://www.vhi.ie/",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-site",
+        }
+        
+        payload = {
+            "username": self.username,
+            "password": self.password
+        }
+        
+        # 1. Primary Authentication
+        # The path here is a presumed standard, will likely be updated if the actual path varies
+        login_url = f"{self.apis_base_url}/auth/v1/login"
+        
+        response = self.session.post(login_url, json=payload, headers=headers)
+        
+        if response.status_code == 200:
+            self.is_authenticated = True
+            return
+            
+        elif response.status_code == 202:
+            # MFA Challenge Required
+            try:
+                data = response.json()
+            except ValueError:
+                raise VhiApiError("MFA response was not valid JSON", status_code=response.status_code)
+                
+            if data.get("mfa_required"):
+                state_token = data.get("state_token")
+                if not state_token:
+                    raise VhiApiError("MFA required but no state_token provided in response")
+                    
+                self._handle_mfa_challenge(state_token, headers)
+            else:
+                raise VhiApiError("Received 202 but not MFA challenge", status_code=response.status_code, response=response)
+                
+        elif response.status_code == 401:
+            raise VhiAuthenticationError("Invalid credentials provided.")
+        else:
+            raise VhiApiError(f"Login failed with status {response.status_code}", status_code=response.status_code, response=response)
+            
+    def _handle_mfa_challenge(self, state_token: str, base_headers: dict):
+        """
+        Internal method to submit the MFA code.
+        """
+        if not self.mfa_callback:
+            raise VhiMfaRequiredError("MFA is required but no mfa_callback was provided to VhiClient.")
+            
+        # Pause execution and invoke the user-defined callback to get the OTP
+        otp_code = self.mfa_callback()
+        
+        if not otp_code:
+            raise VhiAuthenticationError("MFA callback did not return a valid OTP code.")
+            
+        mfa_url = f"{self.apis_base_url}/auth/v1/mfa/verify"
+        payload = {
+            "otp": otp_code,
+            "state_token": state_token
+        }
+        
+        response = self.session.post(mfa_url, json=payload, headers=base_headers)
+        
+        if response.status_code == 200:
+            self.is_authenticated = True
+            
+            # The session cookie jar has now been populated with the authorized session
+            # Or we might need to extract a Bearer token. This implementation relies
+            # on cookies being correctly set via Set-Cookie headers by the API.
+        else:
+            raise VhiAuthenticationError(f"MFA verification failed. Status: {response.status_code}")
+
+    def get_claims(self) -> List[ClaimStatement]:
+        """
+        Retrieves the list of claim statements.
+        
+        Returns:
+            List of ClaimStatement objects.
+        """
+        if not self.is_authenticated:
+            raise VhiAuthenticationError("Client is not authenticated. Call login() first.")
+            
+        url = f"{self.apis_base_url}/claims/v1/statements"
+        
+        headers = {
+            "Accept": "application/json",
+            "Origin": "https://www.vhi.ie",
+            "Referer": "https://www.vhi.ie/",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-site",
+        }
+        
+        response = self.session.get(url, headers=headers)
+        
+        if response.status_code == 200:
+            try:
+                data = response.json()
+            except ValueError:
+                raise VhiApiError("Invalid JSON received for claims statements.", status_code=response.status_code)
+                
+            claims_data = data.get("claims", [])
+            return [ClaimStatement.from_dict(claim) for claim in claims_data]
+        elif response.status_code == 401:
+            self.is_authenticated = False
+            raise VhiAuthenticationError("Session expired or unauthorized.")
+        else:
+            raise VhiApiError(f"Failed to fetch claims: {response.status_code}", status_code=response.status_code, response=response)
+            
+    def download_document(self, document_id: str, dest_path: str):
+        """
+        Streams a claim PDF document to the local disk.
+        
+        Args:
+            document_id: The ID of the document to download.
+            dest_path: The file path where the PDF should be saved.
+        """
+        if not self.is_authenticated:
+            raise VhiAuthenticationError("Client is not authenticated. Call login() first.")
+            
+        url = f"{self.apis_base_url}/documents/v1/{document_id}/download"
+        
+        headers = {
+            "Accept": "application/pdf",
+            "Origin": "https://www.vhi.ie",
+            "Referer": "https://www.vhi.ie/",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-site",
+        }
+        
+        # Use stream=True to prevent loading large PDFs into memory
+        with self.session.get(url, headers=headers, stream=True) as response:
+            if response.status_code == 200:
+                with open(dest_path, 'wb') as f:
+                    for chunk in response.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+            elif response.status_code == 401:
+                self.is_authenticated = False
+                raise VhiAuthenticationError("Session expired or unauthorized while downloading document.")
+            else:
+                raise VhiApiError(f"Failed to download document {document_id}: {response.status_code}", status_code=response.status_code, response=response)

vhi/exceptions.py

@@ -0,0 +1,18 @@
+class VhiError(Exception):
+    """Base exception for Vhi Python Client"""
+    pass
+
+class VhiAuthenticationError(VhiError):
+    """Raised when authentication fails (invalid credentials)"""
+    pass
+
+class VhiMfaRequiredError(VhiError):
+    """Raised when MFA is required but no callback is provided or callback fails"""
+    pass
+
+class VhiApiError(VhiError):
+    """Raised when the Vhi API returns an error response"""
+    def __init__(self, message, status_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response

vhi/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class ClaimStatement:
+    claim_id: str
+    date_of_service: str
+    practitioner: str
+    document_id: str
+    status: str
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "ClaimStatement":
+        return cls(
+            claim_id=data.get("claimId", ""),
+            date_of_service=data.get("dateOfService", ""),
+            practitioner=data.get("practitioner", ""),
+            document_id=data.get("documentId", ""),
+            status=data.get("status", "")
+        )

vhi_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: vhi-python
+Version: 0.1.0
+Summary: A Python client library for the Vhi API, handling authentication, MFA callbacks, claims retrieval, and document downloads.
+Author-email: Agent <agent@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/agent/vhi-python
+Project-URL: Repository, https://github.com/agent/vhi-python.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+
+# Vhi Python Client
+
+A Python client library for interacting dynamically with the Vhi API. Provides automated handling of Session state, Multi-Factor Authentication (MFA) callbacks, Claims Retrieval, and memory-efficient Document Downloads.
+
+## Installation
+
+You can install the library directly from source (or via pip once published):
+
+```bash
+pip install vhi-python
+```
+
+Alternatively, to install it locally for development:
+
+```bash
+git clone https://github.com/agent/vhi-python.git
+cd vhi-python
+pip install -e .
+```
+
+## Quick Start Example
+
+This example demonstrates how to use the library to log in, handle an MFA callback (simulated via CLI input), retrieve claims, and download a claim PDF.
+
+```python
+import os
+from vhi.client import VhiClient
+from vhi.exceptions import VhiAuthenticationError, VhiApiError
+
+def my_cli_mfa_callback() -> str:
+    """
+    A simple callback function that pauses execution
+    and waits for the user to input the 2FA code sent to their phone/email.
+    """
+    return input("Vhi 2FA Code Required. Enter OTP: ").strip()
+
+def main():
+    # 1. Initialize the client
+    # Replace with your actual credentials
+    username = os.getenv("VHI_USERNAME", "your_email@example.com")
+    password = os.getenv("VHI_PASSWORD", "your_password")
+    
+    # We pass our callback function so the client can automatically 
+    # pause and invoke it if the server demands MFA.
+    client = VhiClient(
+        username=username, 
+        password=password, 
+        mfa_callback=my_cli_mfa_callback
+    )
+
+    try:
+        # 2. Login
+        print("Logging in...")
+        client.login()
+        print("Login successful!")
+
+        # 3. Retrieve Claims
+        print("\nRetrieving claims...")
+        statements = client.get_claims()
+        
+        if not statements:
+            print("No claim statements found.")
+            return
+
+        for claim in statements:
+            print(f"- Claim {claim.claim_id} | Date: {claim.date_of_service} | Status: {claim.status}")
+
+        # 4. Download a Document
+        # We will download the first available document as an example
+        first_claim = statements[0]
+        if first_claim.document_id:
+            download_path = f"{first_claim.claim_id}.pdf"
+            print(f"\nDownloading document {first_claim.document_id} to {download_path}...")
+            client.download_document(first_claim.document_id, download_path)
+            print("Download complete!")
+
+    except VhiAuthenticationError as e:
+        print(f"Authentication failed: {e}")
+    except VhiApiError as e:
+        print(f"API Error occurred: {e}")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Error Handling
+
+The library provides structural custom exceptions:
+- `VhiAuthenticationError`: Raised when login fails due to invalid credentials.
+- `VhiMfaRequiredError`: Raised when the server requests MFA but you didn't provide a callback, or when the callback returns an invalid OTP.
+- `VhiApiError`: Raised for any other 4xx or 5xx API errors. Contains standard HTTP status codes for debugging.

vhi_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+vhi/__init__.py,sha256=ytq-BfovdJwn0P833AR1Zmli8Equ5fUU1fQ33fRdMUg,275
+vhi/client.py,sha256=24NgKrzhQC0VkbSZstdkx2VW-IMHXEIlwPOa7Hq0uCY,8131
+vhi/exceptions.py,sha256=5IcdRp-QoEUllPywhWLug6sHp1RTUzUETm-TGSenPSg,591
+vhi/models.py,sha256=8QUa08OOtKFiraPFYpyzwQApH6mqwum2ssVp9pYlG1E,560
+vhi_python-0.1.0.dist-info/METADATA,sha256=cbdpGDkZUWJXqYhAyKyNC9SBhUtOxoqSyQCpplWERLU,3807
+vhi_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vhi_python-0.1.0.dist-info/top_level.txt,sha256=IS0GUlyapVqQTomxbPnevKR6YgXGoQsgdAQ8RYDQki0,4
+vhi_python-0.1.0.dist-info/RECORD,,

vhi_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vhi_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vhi