hpde-analytics-cli 1.0.0__py3-none-any.whl

hpde_analytics_cli/__init__.py

@@ -0,0 +1,4 @@
+"""HPDE Analytics CLI: Event Registration API integration for HPDE and Time Trials programs."""
+
+__version__ = "1.0.0"
+__app_name__ = "hpde-analytics-cli"

hpde_analytics_cli/api/__init__.py

@@ -0,0 +1 @@
+"""API client module."""

hpde_analytics_cli/api/client.py

@@ -0,0 +1,325 @@
+"""
+MotorsportsReg API client module.
+
+Provides a high-level interface for accessing MotorsportsReg API endpoints.
+"""
+
+import time
+from typing import Any, Dict, Optional
+
+from requests_oauthlib import OAuth1Session
+
+from hpde_analytics_cli.auth.oauth import MSROAuth
+
+
+class APIError(Exception):
+    """Exception raised for API errors."""
+
+    def __init__(
+        self, message: str, status_code: Optional[int] = None, response_body: Optional[str] = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class MSRClient:
+    """Client for interacting with MotorsportsReg API endpoints."""
+
+    def __init__(self, oauth: MSROAuth, organization_id: Optional[str] = None):
+        """
+        Initialize the API client.
+
+        Args:
+            oauth: Authenticated MSROAuth instance
+            organization_id: Organization ID for admin API access (optional)
+        """
+        self.oauth = oauth
+        self.base_url = oauth.base_url
+        self.organization_id = organization_id
+
+        # Retry configuration
+        self.max_retries = 3
+        self.retry_delay = 1.0  # seconds
+
+    def _get_session(self) -> OAuth1Session:
+        """Get an authenticated OAuth session."""
+        return self.oauth.get_oauth_session()
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        include_org_header: bool = True,
+        retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an authenticated API request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path (e.g., /rest/me.json)
+            params: Query parameters
+            include_org_header: Include X-Organization-Id header
+            retries: Number of retries (defaults to self.max_retries)
+
+        Returns:
+            Parsed JSON response (unwrapped from MSR response envelope)
+
+        Raises:
+            APIError: If the request fails
+        """
+        if retries is None:
+            retries = self.max_retries
+
+        session = self._get_session()
+
+        # Ensure endpoint has .json suffix for JSON response
+        if not endpoint.endswith(".json"):
+            endpoint = endpoint + ".json"
+
+        url = f"{self.base_url}{endpoint}"
+
+        headers = {}
+        if include_org_header and self.organization_id:
+            headers["X-Organization-Id"] = self.organization_id
+
+        last_error: APIError = APIError("Request failed with unknown error")
+
+        for attempt in range(retries + 1):
+            try:
+                if method.upper() == "GET":
+                    response = session.get(url, params=params, headers=headers)
+                elif method.upper() == "POST":
+                    response = session.post(url, data=params, headers=headers)
+                else:
+                    raise APIError(f"Unsupported HTTP method: {method}")
+
+                # Handle response
+                if response.status_code == 200:
+                    data = response.json()
+                    # MSR wraps responses in {"response": {...}}
+                    if isinstance(data, dict) and "response" in data:
+                        data = data["response"]
+                    return data
+                elif response.status_code == 401:
+                    raise APIError(
+                        "Authentication failed - tokens may be invalid or expired",
+                        status_code=401,
+                        response_body=response.text,
+                    )
+                elif response.status_code == 403:
+                    raise APIError(
+                        "Access forbidden - insufficient permissions",
+                        status_code=403,
+                        response_body=response.text,
+                    )
+                elif response.status_code == 404:
+                    raise APIError(
+                        f"Resource not found: {endpoint}",
+                        status_code=404,
+                        response_body=response.text,
+                    )
+                elif response.status_code >= 500:
+                    # Server error - retry
+                    last_error = APIError(
+                        f"Server error: {response.status_code}",
+                        status_code=response.status_code,
+                        response_body=response.text,
+                    )
+                    if attempt < retries:
+                        time.sleep(self.retry_delay * (attempt + 1))
+                        continue
+                    raise last_error
+                else:
+                    raise APIError(
+                        f"Request failed with status {response.status_code}",
+                        status_code=response.status_code,
+                        response_body=response.text,
+                    )
+
+            except APIError:
+                raise
+            except Exception as e:
+                last_error = APIError(f"Request failed: {str(e)}")
+                if attempt < retries:
+                    time.sleep(self.retry_delay * (attempt + 1))
+                    continue
+                raise last_error
+
+        raise last_error
+
+    def get_me(self) -> Dict[str, Any]:
+        """
+        Get the authenticated user's profile.
+
+        Returns:
+            User profile data including organizations
+        """
+        return self._request("GET", "/rest/me", include_org_header=False)
+
+    def get_organization_calendar(self, organization_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get the organization's event calendar.
+
+        Args:
+            organization_id: Organization ID (uses default if not provided)
+
+        Returns:
+            Calendar data with list of events
+
+        Endpoint: GET /rest/calendars/organization/{organization_id}
+        """
+        org_id = organization_id or self.organization_id
+        if not org_id:
+            raise ValueError("Organization ID is required")
+
+        return self._request("GET", f"/rest/calendars/organization/{org_id}")
+
+    def get_event_entrylist(self, event_id: str) -> Dict[str, Any]:
+        """
+        Get the entry list for an event.
+
+        Args:
+            event_id: Event ID
+
+        Returns:
+            Entry list data
+
+        Endpoint: GET /rest/events/{event_id}/entrylist
+        """
+        if not event_id:
+            raise ValueError("Event ID is required")
+
+        return self._request("GET", f"/rest/events/{event_id}/entrylist")
+
+    def get_event_attendees(self, event_id: str) -> Dict[str, Any]:
+        """
+        Get complete attendee list for an event.
+
+        Args:
+            event_id: Event ID
+
+        Returns:
+            Attendee data
+
+        Endpoint: GET /rest/events/{event_id}/attendees
+        """
+        if not event_id:
+            raise ValueError("Event ID is required")
+
+        return self._request("GET", f"/rest/events/{event_id}/attendees")
+
+    def get_event_assignments(self, event_id: str) -> Dict[str, Any]:
+        """
+        Get event assignments/entries including vehicle information.
+
+        Args:
+            event_id: Event ID
+
+        Returns:
+            Assignment data with vehicle details
+
+        Endpoint: GET /rest/events/{event_id}/assignments
+        """
+        if not event_id:
+            raise ValueError("Event ID is required")
+
+        return self._request("GET", f"/rest/events/{event_id}/assignments")
+
+    def get_timing_feed(self, event_id: str) -> Dict[str, Any]:
+        """
+        Get timing and scoring feed for an event.
+
+        Args:
+            event_id: Event ID
+
+        Returns:
+            Timing/scoring data
+
+        Endpoint: GET /rest/events/{event_id}/feeds/timing
+        """
+        if not event_id:
+            raise ValueError("Event ID is required")
+
+        return self._request("GET", f"/rest/events/{event_id}/feeds/timing")
+
+    def get_all_endpoint_data(self, event_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Fetch data from all available endpoints for field discovery.
+
+        Args:
+            event_id: Optional event ID for event-specific endpoints
+
+        Returns:
+            Dict with data from each endpoint, keyed by endpoint name
+        """
+        results = {}
+
+        # Always fetch user profile
+        print("  Fetching /rest/me...")
+        try:
+            results["me"] = self.get_me()
+            print("    [OK] User profile retrieved")
+        except APIError as e:
+            print(f"    [ERROR] {e}")
+            results["me"] = {"error": str(e)}
+
+        # Fetch organization calendar
+        if self.organization_id:
+            print(f"  Fetching organization calendar (org: {self.organization_id})...")
+            try:
+                results["calendar"] = self.get_organization_calendar()
+                print("    [OK] Calendar retrieved")
+
+                # Get first event ID if not provided
+                if not event_id:
+                    events = results["calendar"].get("events", [])
+                    if events:
+                        event_id = events[0].get("id")
+                        print(f"    Using first event from calendar: {event_id}")
+            except APIError as e:
+                print(f"    [ERROR] {e}")
+                results["calendar"] = {"error": str(e)}
+
+        # Event-specific endpoints (require event_id)
+        if event_id:
+            event_endpoints = [
+                ("entrylist", self.get_event_entrylist, "Entry list"),
+                ("attendees", self.get_event_attendees, "Attendees"),
+                ("assignments", self.get_event_assignments, "Assignments"),
+                ("timing", self.get_timing_feed, "Timing feed"),
+            ]
+
+            for key, method, description in event_endpoints:
+                print(f"  Fetching {description} (event: {event_id})...")
+                try:
+                    results[key] = method(event_id)
+                    print(f"    [OK] {description} retrieved")
+                except APIError as e:
+                    print(f"    [ERROR] {e}")
+                    results[key] = {"error": str(e)}
+        else:
+            print("  [SKIP] No event ID available - skipping event-specific endpoints")
+            print("         Use --event-id to specify an event, or ensure calendar has events")
+
+        return results
+
+
+def create_client_from_oauth(oauth: MSROAuth, organization_id: Optional[str] = None) -> MSRClient:
+    """
+    Create an API client from an authenticated OAuth handler.
+
+    Args:
+        oauth: Authenticated MSROAuth instance
+        organization_id: Optional organization ID override
+
+    Returns:
+        Configured MSRClient instance
+    """
+    # Use provided org ID, or fall back to first organization from profile
+    if not organization_id and oauth.organizations:
+        organization_id = oauth.organizations[0].get("id")
+
+    return MSRClient(oauth=oauth, organization_id=organization_id)

hpde_analytics_cli/auth/__init__.py

@@ -0,0 +1 @@
+"""OAuth authentication module."""

hpde_analytics_cli/auth/credentials.py

@@ -0,0 +1,256 @@
+"""
+Credential Manager Module
+
+Securely stores and retrieves OAuth credentials using the system keyring.
+Falls back to environment variables/.env file if keyring is unavailable.
+"""
+
+import getpass
+import os
+from typing import Optional, Tuple
+
+# Application identifier for keyring storage
+APP_NAME = "hpde-analytics-cli"
+
+# Credential keys
+KEY_CONSUMER_KEY = "msr_consumer_key"
+KEY_CONSUMER_SECRET = "msr_consumer_secret"
+
+# Try to import keyring, but don't fail if unavailable
+try:
+    import keyring
+
+    KEYRING_AVAILABLE = True
+except ImportError:
+    KEYRING_AVAILABLE = False
+
+
+class CredentialManager:
+    """
+    Manages OAuth credentials with secure storage.
+
+    Priority order for credential retrieval:
+    1. System keyring (if available and credentials stored)
+    2. Environment variables
+    3. Interactive prompt (for --configure)
+    """
+
+    def __init__(self, app_name: str = APP_NAME):
+        """
+        Initialize the credential manager.
+
+        Args:
+            app_name: Application identifier for keyring storage
+        """
+        self.app_name = app_name
+
+    def keyring_available(self) -> bool:
+        """Check if keyring is available and functional."""
+        if not KEYRING_AVAILABLE:
+            return False
+
+        # Test if keyring backend is actually working
+        try:
+            # Try to get a non-existent key to test functionality
+            keyring.get_password(self.app_name, "__test__")
+            return True
+        except Exception:
+            return False
+
+    def get_credentials_from_keyring(self) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Retrieve credentials from system keyring.
+
+        Returns:
+            Tuple of (consumer_key, consumer_secret) or (None, None) if not found
+        """
+        if not self.keyring_available():
+            return None, None
+
+        try:
+            consumer_key = keyring.get_password(self.app_name, KEY_CONSUMER_KEY)
+            consumer_secret = keyring.get_password(self.app_name, KEY_CONSUMER_SECRET)
+            return consumer_key, consumer_secret
+        except Exception:
+            return None, None
+
+    def get_credentials_from_env(self) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Retrieve credentials from environment variables.
+
+        Returns:
+            Tuple of (consumer_key, consumer_secret) or (None, None) if not found
+        """
+        consumer_key = os.environ.get("MSR_CONSUMER_KEY")
+        consumer_secret = os.environ.get("MSR_CONSUMER_SECRET")
+        return consumer_key, consumer_secret
+
+    def get_credentials(self) -> Tuple[str, str]:
+        """
+        Get credentials from the best available source.
+
+        Priority:
+        1. System keyring
+        2. Environment variables
+
+        Returns:
+            Tuple of (consumer_key, consumer_secret)
+
+        Raises:
+            ValueError: If credentials cannot be found from any source
+        """
+        # Try keyring first
+        consumer_key, consumer_secret = self.get_credentials_from_keyring()
+        if consumer_key and consumer_secret:
+            return consumer_key, consumer_secret
+
+        # Fall back to environment variables
+        consumer_key, consumer_secret = self.get_credentials_from_env()
+        if consumer_key and consumer_secret:
+            return consumer_key, consumer_secret
+
+        # No credentials found
+        raise ValueError(
+            "No credentials found. Run with --configure to set up credentials, "
+            "or set MSR_CONSUMER_KEY and MSR_CONSUMER_SECRET environment variables."
+        )
+
+    def store_credentials(self, consumer_key: str, consumer_secret: str) -> bool:
+        """
+        Store credentials in system keyring.
+
+        Args:
+            consumer_key: OAuth consumer key
+            consumer_secret: OAuth consumer secret
+
+        Returns:
+            True if stored successfully, False otherwise
+        """
+        if not self.keyring_available():
+            print("Warning: System keyring not available. Cannot store credentials securely.")
+            return False
+
+        try:
+            keyring.set_password(self.app_name, KEY_CONSUMER_KEY, consumer_key)
+            keyring.set_password(self.app_name, KEY_CONSUMER_SECRET, consumer_secret)
+            return True
+        except Exception as e:
+            print(f"Warning: Failed to store credentials in keyring: {e}")
+            return False
+
+    def delete_credentials(self) -> bool:
+        """
+        Delete credentials from system keyring.
+
+        Returns:
+            True if deleted successfully, False otherwise
+        """
+        if not self.keyring_available():
+            return False
+
+        try:
+            keyring.delete_password(self.app_name, KEY_CONSUMER_KEY)
+            keyring.delete_password(self.app_name, KEY_CONSUMER_SECRET)
+            return True
+        except Exception:
+            return False
+
+    def has_stored_credentials(self) -> bool:
+        """
+        Check if credentials are stored in keyring.
+
+        Returns:
+            True if credentials exist in keyring
+        """
+        consumer_key, consumer_secret = self.get_credentials_from_keyring()
+        return bool(consumer_key and consumer_secret)
+
+    def configure_interactive(self) -> bool:
+        """
+        Interactively configure credentials via command line prompts.
+
+        Returns:
+            True if configuration successful
+        """
+        print("\n" + "=" * 60)
+        print("HPDE Analytics - Credential Configuration")
+        print("=" * 60)
+
+        if not self.keyring_available():
+            print("\nWarning: System keyring is not available.")
+            print("Credentials will need to be set via environment variables.")
+            print("\nTo use environment variables, add to your .env file:")
+            print("  MSR_CONSUMER_KEY=your_key_here")
+            print("  MSR_CONSUMER_SECRET=your_secret_here")
+            return False
+
+        print("\nThis will store your MotorsportsReg OAuth credentials securely")
+        print("in your system's credential manager (Keychain/Credential Locker).")
+
+        # Check for existing credentials
+        if self.has_stored_credentials():
+            print("\nExisting credentials found in keyring.")
+            response = input("Do you want to replace them? (y/N): ").strip().lower()
+            if response != "y":
+                print("Configuration cancelled.")
+                return False
+
+        print("\nEnter your MotorsportsReg OAuth credentials:")
+        print("(These are provided by MotorsportsReg for API access)")
+        print()
+
+        # Get consumer key
+        consumer_key = input("Consumer Key: ").strip()
+        if not consumer_key:
+            print("Error: Consumer key cannot be empty.")
+            return False
+
+        # Get consumer secret (hidden input)
+        consumer_secret = getpass.getpass("Consumer Secret: ").strip()
+        if not consumer_secret:
+            print("Error: Consumer secret cannot be empty.")
+            return False
+
+        # Store credentials
+        if self.store_credentials(consumer_key, consumer_secret):
+            print("\n[OK] Credentials stored securely in system keyring.")
+            print("     You can now run the application without environment variables.")
+            return True
+        else:
+            print("\n[ERROR] Failed to store credentials.")
+            return False
+
+    def show_status(self) -> None:
+        """Display current credential configuration status."""
+        print("\n" + "=" * 60)
+        print("Credential Status")
+        print("=" * 60)
+
+        # Check keyring availability
+        print(f"\nSystem keyring available: {'Yes' if self.keyring_available() else 'No'}")
+
+        # Check keyring credentials
+        keyring_key, keyring_secret = self.get_credentials_from_keyring()
+        has_keyring = bool(keyring_key and keyring_secret)
+        print(f"Credentials in keyring: {'Yes' if has_keyring else 'No'}")
+
+        # Check environment variables
+        env_key, env_secret = self.get_credentials_from_env()
+        has_env = bool(env_key and env_secret)
+        print(f"Credentials in environment: {'Yes' if has_env else 'No'}")
+
+        # Show which source will be used
+        if has_keyring:
+            print("\n[Active] Using credentials from system keyring")
+        elif has_env:
+            print("\n[Active] Using credentials from environment variables")
+        else:
+            print("\n[Warning] No credentials configured")
+            print("          Run with --configure to set up credentials")
+
+        print()
+
+
+def get_credential_manager() -> CredentialManager:
+    """Get a configured credential manager instance."""
+    return CredentialManager()