kroger-api 0.1.0__py3-none-any.whl

kroger_api/__init__.py

@@ -0,0 +1,6 @@
+# Make the KrogerAPI class available at the package level
+from kroger_api.kroger_api import KrogerAPI
+from . import auth
+from . import utils
+
+__all__ = ['KrogerAPI', 'auth', 'utils']

kroger_api/api/authorization.py

@@ -0,0 +1,107 @@
+from typing import Dict, Optional, Any
+
+from kroger_api.client import KrogerClient
+from kroger_api.token_storage import get_refresh_token, load_token
+
+
+class AuthorizationAPI:
+    """
+    Provides access to the Kroger Authorization API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Authorization API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def get_authorization_url(self, scope: str, state: Optional[str] = None, banner: Optional[str] = None) -> str:
+        """
+        Get the URL to redirect the user to for authorization
+        
+        Args:
+            scope: The level of access your application is requesting
+            state: A random string to verify that the response belongs to the initiated request
+            banner: Sets the chain specific branding displayed on the authorization consent screen
+            
+        Returns:
+            The authorization URL
+        """
+        return self.client.get_authorization_url(scope, state, banner)
+    
+    def get_token_with_client_credentials(self, scope: str) -> Dict[str, Any]:
+        """
+        Get an access token using client credentials
+        
+        Args:
+            scope: The level of access your application is requesting
+            
+        Returns:
+            The token information
+        """
+        return self.client.get_token_with_client_credentials(scope)
+    
+    def get_token_with_authorization_code(self, code: str) -> Dict[str, Any]:
+        """
+        Get an access token using an authorization code
+        
+        Args:
+            code: The authorization code received from the redirect
+            
+        Returns:
+            The token information
+        """
+        return self.client.get_token_with_authorization_code(code)
+    
+    def refresh_token(self, refresh_token: str) -> Dict[str, Any]:
+        """
+        Refresh an access token using a refresh token
+        
+        Args:
+            refresh_token: The refresh token received from a previous token request
+            
+        Returns:
+            The token information
+        """
+        return self.client.refresh_token(refresh_token)
+    
+    def refresh_token_if_needed(self, token_file: str = None) -> Dict[str, Any]:
+        """
+        Check if the token needs refreshing and refresh it if necessary
+        
+        Args:
+            token_file: The file path to load the token from
+        
+        Returns:
+            The token information (either existing or refreshed)
+        """
+        # Determine which token file to use
+        if token_file is None:
+            if self.client.token_file:
+                token_file = self.client.token_file
+            else:
+                token_file = ".kroger_token_user.json"
+        
+        # Load the token
+        token_info = load_token(token_file)
+        
+        if token_info:
+            # Test if the token is valid
+            if self.client.test_token(token_info):
+                # Token is valid, return it
+                return token_info
+            
+            # Token is invalid, check if we have a refresh token
+            refresh_token = get_refresh_token(token_file)
+            if refresh_token:
+                # Try to refresh the token
+                try:
+                    return self.refresh_token(refresh_token)
+                except Exception as e:
+                    print(f"Failed to refresh token: {e}")
+        
+        # If we couldn't refresh or there was no token, return None
+        return None

kroger_api/api/cart.py

@@ -0,0 +1,37 @@
+from typing import Dict, List, Any
+
+from kroger_api.client import KrogerClient
+
+
+class CartAPI:
+    """
+    Provides access to the Kroger Cart API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Cart API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def add_to_cart(self, items: List[Dict[str, Any]]) -> None:
+        """
+        Add items to an authenticated customer's cart
+        
+        Args:
+            items: A list of items to add to the cart. Each item should be a dictionary with keys:
+                  - upc: The UPC of the item
+                  - quantity: The quantity of the item
+                  - modality: (Optional) The modality including: DELIVERY, PICKUP
+                  
+        Returns:
+            None if successful
+        """
+        data = {
+            "items": items
+        }
+        
+        return self.client._make_request('PUT', '/v1/cart/add', data=data)

kroger_api/api/identity.py

@@ -0,0 +1,27 @@
+from typing import Dict, Any
+
+from kroger_api.client import KrogerClient
+
+
+class IdentityAPI:
+    """
+    Provides access to the Kroger Identity API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Identity API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def get_profile(self) -> Dict[str, Any]:
+        """
+        Get the profile ID of an authenticated customer
+        
+        Returns:
+            The user profile information
+        """
+        return self.client._make_request('GET', '/v1/identity/profile')

kroger_api/api/location.py

@@ -0,0 +1,185 @@
+from typing import Dict, Optional, Any, List, Union
+import requests
+
+from kroger_api.client import KrogerClient
+
+
+class LocationAPI:
+    """
+    Provides access to the Kroger Location API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Location API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def search_locations(self, 
+                         zip_code: Optional[str] = None,
+                         lat_long: Optional[str] = None,
+                         lat: Optional[str] = None,
+                         lon: Optional[str] = None,
+                         radius_in_miles: Optional[int] = None,
+                         limit: Optional[int] = None,
+                         chain: Optional[str] = None,
+                         department: Optional[str] = None,
+                         location_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Search for locations
+        
+        Args:
+            zip_code: The zip code to use as a starting point for results
+            lat_long: The latitude and longitude to use as a starting point for results (comma separated)
+            lat: The latitude to use as a starting point for results
+            lon: The longitude to use as a starting point for results
+            radius_in_miles: The mile radius of results (1-100)
+            limit: The number of results to return (1-200)
+            chain: The chain name
+            department: The departmentId of the department (comma separated)
+            location_id: Comma-separated list of locationIds
+            
+        Returns:
+            The locations matching the search criteria
+        """
+        params = {}
+        
+        if zip_code:
+            params['filter.zipCode.near'] = zip_code
+        
+        if lat_long:
+            params['filter.latLong.near'] = lat_long
+        
+        if lat:
+            params['filter.lat.near'] = lat
+        
+        if lon:
+            params['filter.lon.near'] = lon
+        
+        if radius_in_miles:
+            params['filter.radiusInMiles'] = radius_in_miles
+        
+        if limit:
+            params['filter.limit'] = limit
+        
+        if chain:
+            params['filter.chain'] = chain
+        
+        if department:
+            params['filter.department'] = department
+        
+        if location_id:
+            params['filter.locationId'] = location_id
+        
+        return self.client._make_request('GET', '/v1/locations', params=params)
+    
+    def get_location(self, location_id: str) -> Dict[str, Any]:
+        """
+        Get details for a specific location
+        
+        Args:
+            location_id: The locationId of the store
+            
+        Returns:
+            The location details
+        """
+        return self.client._make_request('GET', f'/v1/locations/{location_id}')
+    
+    def location_exists(self, location_id: str) -> bool:
+        """
+        Check if a location exists
+        
+        Args:
+            location_id: The locationId of the store
+            
+        Returns:
+            True if the location exists, False otherwise
+        """
+        try:
+            self.client._make_request('HEAD', f'/v1/locations/{location_id}')
+            return True
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                return False
+            raise
+    
+    def list_chains(self) -> Dict[str, Any]:
+        """
+        Get a list of all chains
+        
+        Returns:
+            A list of all chains
+        """
+        return self.client._make_request('GET', '/v1/chains')
+    
+    def get_chain(self, name: str) -> Dict[str, Any]:
+        """
+        Get details for a specific chain
+        
+        Args:
+            name: The name of the chain
+            
+        Returns:
+            The chain details
+        """
+        return self.client._make_request('GET', f'/v1/chains/{name}')
+    
+    def chain_exists(self, name: str) -> bool:
+        """
+        Check if a chain exists
+        
+        Args:
+            name: The name of the chain
+            
+        Returns:
+            True if the chain exists, False otherwise
+        """
+        try:
+            self.client._make_request('HEAD', f'/v1/chains/{name}')
+            return True
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                return False
+            raise
+    
+    def list_departments(self) -> Dict[str, Any]:
+        """
+        Get a list of all departments
+        
+        Returns:
+            A list of all departments
+        """
+        return self.client._make_request('GET', '/v1/departments')
+    
+    def get_department(self, department_id: str) -> Dict[str, Any]:
+        """
+        Get details for a specific department
+        
+        Args:
+            department_id: The departmentId of the department
+            
+        Returns:
+            The department details
+        """
+        return self.client._make_request('GET', f'/v1/departments/{department_id}')
+    
+    def department_exists(self, department_id: str) -> bool:
+        """
+        Check if a department exists
+        
+        Args:
+            department_id: The departmentId of the department
+            
+        Returns:
+            True if the department exists, False otherwise
+        """
+        try:
+            self.client._make_request('HEAD', f'/v1/departments/{department_id}')
+            return True
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                return False
+            raise

kroger_api/api/product.py

@@ -0,0 +1,84 @@
+from typing import Dict, Optional, Any, List, Union
+
+from kroger_api.client import KrogerClient
+
+
+class ProductAPI:
+    """
+    Provides access to the Kroger Product API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Product API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def search_products(self, 
+                        term: Optional[str] = None, 
+                        location_id: Optional[str] = None,
+                        product_id: Optional[str] = None,
+                        brand: Optional[str] = None,
+                        fulfillment: Optional[str] = None,
+                        start: Optional[int] = None,
+                        limit: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Search for products
+        
+        Args:
+            term: A search term to filter product results
+            location_id: The locationId of the location
+            product_id: The productId of the products(s) to return (comma-separated)
+            brand: The brand name of the products to return (pipe-separated)
+            fulfillment: The available fulfillment types (comma-separated)
+            start: The number of products to skip
+            limit: The number of products to return
+            
+        Returns:
+            The products matching the search criteria
+        """
+        params = {}
+        
+        if term:
+            params['filter.term'] = term
+        
+        if location_id:
+            params['filter.locationId'] = location_id
+        
+        if product_id:
+            params['filter.productId'] = product_id
+        
+        if brand:
+            params['filter.brand'] = brand
+        
+        if fulfillment:
+            params['filter.fulfillment'] = fulfillment
+        
+        if start:
+            params['filter.start'] = start
+        
+        if limit:
+            params['filter.limit'] = limit
+        
+        return self.client._make_request('GET', '/v1/products', params=params)
+    
+    def get_product(self, product_id: str, location_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get details for a specific product
+        
+        Args:
+            product_id: The productId of the product
+            location_id: The locationId of the location for pricing and availability
+            
+        Returns:
+            The product details
+        """
+        params = {}
+        
+        if location_id:
+            params['filter.locationId'] = location_id
+        
+        return self.client._make_request('GET', f'/v1/products/{product_id}', params=params)

kroger_api/auth/__init__.py

@@ -0,0 +1,6 @@
+"""
+Authentication modules for Kroger API client.
+"""
+from .interactive import authenticate_user, switch_to_client_credentials
+
+__all__ = ['authenticate_user', 'switch_to_client_credentials']

kroger_api/auth/interactive.py

@@ -0,0 +1,173 @@
+"""
+Interactive authentication utilities for Kroger API client.
+This module provides functions for interactive authentication flows.
+"""
+import os
+import threading
+import time
+from typing import Dict, Any, Tuple, Optional
+
+from ..utils.oauth import (
+    start_oauth_server,
+    extract_port_from_redirect_uri,
+    generate_random_state,
+    open_browser_for_auth
+)
+from ..utils.env import get_redirect_uri
+from ..kroger_api import KrogerAPI
+from ..token_storage import load_token, get_refresh_token
+
+def authenticate_user(scopes: str = "cart.basic:write profile.compact", 
+                      token_file: str = ".kroger_token_user.json", 
+                      timeout: int = 120) -> KrogerAPI:
+    """
+    Authenticate a user and return a KrogerAPI client with valid tokens
+    
+    This function implements the complete OAuth2 authorization code flow,
+    including token refresh and browser-based authorization.
+    
+    Args:
+        scopes: The OAuth scopes to request
+        token_file: The file to store the token in
+        timeout: The timeout for waiting for the authorization code (in seconds)
+        
+    Returns:
+        A KrogerAPI instance with valid tokens
+        
+    Raises:
+        TimeoutError: If the authorization flow times out
+        ValueError: If the authentication fails for other reasons
+    """
+    # Initialize the API client
+    kroger = KrogerAPI()
+    
+    # Set the token file
+    kroger.client.token_file = token_file
+    
+    # Try to load a saved token and test if it's valid
+    token_info = load_token(token_file)
+    if token_info:
+        kroger.client.token_info = token_info
+        
+        # Test if the token is valid
+        try:
+            print("Found saved token, testing if it's still valid...")
+            is_valid = kroger.test_current_token()
+            if is_valid:
+                print("Token is valid - no need to log in again!")
+                return kroger
+        except Exception:
+            print("Token validation failed, will try to refresh")
+            # Token is invalid, continue with the flow
+            pass
+            
+    # If token is invalid, try to refresh it
+    try:
+        refresh_token = get_refresh_token(token_file)
+        if refresh_token:
+            print("Refreshing token...")
+            token_info = kroger.authorization.refresh_token(refresh_token)
+            # Test the refreshed token
+            is_valid = kroger.test_current_token()
+            if is_valid:
+                print("Token refreshed successfully.")
+                return kroger
+    except Exception as e:
+        print(f"Token refresh failed: {e}")
+        print("Will proceed with new authorization...")
+        # Refresh failed, continue with the full authorization flow
+        pass
+        
+    print("Starting new OAuth authorization flow...")
+    
+    # Extract the port from the redirect URI
+    redirect_uri = get_redirect_uri()
+    port = extract_port_from_redirect_uri(redirect_uri)
+    
+    # Variables to store the authorization code
+    auth_code = None
+    auth_state = None
+    auth_event = threading.Event()
+    
+    # Callback for when the authorization code is received
+    def on_code_received(code, state):
+        nonlocal auth_code, auth_state
+        auth_code = code
+        auth_state = state
+        auth_event.set()
+    
+    # Start the server to handle the OAuth2 redirect
+    server, _ = start_oauth_server(port, on_code_received)
+    
+    try:
+        # Generate a random state value for security
+        state = generate_random_state()
+        
+        # Get the authorization URL with the required scopes
+        auth_url = kroger.authorization.get_authorization_url(
+            scope=scopes,
+            state=state
+        )
+        
+        # Open the authorization URL in the default browser
+        open_browser_for_auth(auth_url)
+        
+        # Wait for the authorization code (timeout after specified seconds)
+        print(f"Waiting for authorization... (timeout: {timeout} seconds)")
+        if not auth_event.wait(timeout):
+            raise TimeoutError("Authorization flow timed out. Please try again.")
+        
+        # Verify the state parameter to prevent CSRF attacks
+        if auth_state != state:
+            raise ValueError("State parameter mismatch. Possible CSRF attack.")
+        
+        # Exchange the authorization code for an access token
+        print("Authorization code received, exchanging for access token...")
+        token_info = kroger.authorization.get_token_with_authorization_code(auth_code)
+        
+        print("Authentication successful.")
+        return kroger
+        
+    except Exception as e:
+        # Ensure the server is shut down, then re-raise the exception
+        server.shutdown()
+        raise e
+    finally:
+        # Ensure the server is shut down
+        server.shutdown()
+
+def switch_to_client_credentials(kroger: KrogerAPI, scope: str = "product.compact") -> Tuple[KrogerAPI, Dict, str]:
+    """
+    Switch the KrogerAPI client to use client credentials flow
+    
+    This is useful when switching from user token to client credentials
+    for operations that don't require user authentication.
+    
+    This function DOES NOT modify the kroger.client.user_token_info or similar attributes.
+    Instead, it returns the original token info for the caller to manage.
+    
+    Args:
+        kroger: The KrogerAPI instance
+        scope: The scope to request
+        
+    Returns:
+        A tuple containing:
+        - The same KrogerAPI instance with updated token
+        - The original token_info (or None)
+        - The original token_file (or None)
+    """
+    # Save the current token info and file for later
+    user_token_info = None
+    user_token_file = None
+    
+    if hasattr(kroger.client, 'token_info'):
+        user_token_info = kroger.client.token_info
+    
+    if hasattr(kroger.client, 'token_file'):
+        user_token_file = kroger.client.token_file
+        
+    # Get a client credentials token
+    kroger.authorization.get_token_with_client_credentials(scope)
+    
+    # Return the kroger instance and the saved token info
+    return kroger, user_token_info, user_token_file