Metadata-Version: 2.4
Name: kroger-api
Version: 0.2.0
Summary: A Python client library for the Kroger Public API
Home-page: https://github.com/CupOfOwls/kroger-api
Author: Stephen Thoemmes
Author-email: Stephen Thoemmes <thoemmes.stephen@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Stephen Thoemmes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/CupOfOwls/kroger-api
Project-URL: Repository, https://github.com/CupOfOwls/kroger-api
Project-URL: Documentation, https://developer.kroger.com/documentation/public/
Project-URL: Bug Reports, https://github.com/CupOfOwls/kroger-api/issues
Project-URL: Demo Video, https://github.com/CupOfOwls/kroger-api/blob/main/assets/kroger-api-python-add-to-cart-demo.mp4
Keywords: kroger,api,grocery,shopping,retail
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dotenv>=0.15.0
Requires-Dist: certifi>=2021.0.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
Requires-Dist: requests-mock>=1.9.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: examples
Requires-Dist: tabulate>=0.8.0; extra == "examples"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🛒 Kroger Public API 🛍️  --  with Examples in Python 🐍

A comprehensive Python client library for the Kroger Public API, featuring robust token management, comprehensive examples, and easy-to-use interfaces for all available endpoints.

## 📺 Demo

Adding an item to your cart via an interactive Python script, and checking that it appears in your account:

https://github.com/user-attachments/assets/0079cbc7-5af0-473b-909a-d43508fe43d5

## 🚀 Quick Start

### Installation

#### From PyPI (Recommended)
```bash
pip install kroger-api
```

#### From Source
```bash
git clone https://github.com/CupOfOwls/kroger-api.git
cd kroger-api
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
```

### Basic Usage

```python
from kroger_api import KrogerAPI
from kroger_api.utils.env import load_and_validate_env, get_zip_code

# Env -- set in .env
load_and_validate_env(["KROGER_CLIENT_ID", "KROGER_CLIENT_SECRET"])
zip_code = get_zip_code(default="10001")

# Initialize the client
kroger = KrogerAPI()

# Get a client credentials token for public data
token_info = kroger.authorization.get_token_with_client_credentials("product.compact")

locations = kroger.location.search_locations(
                zip_code=zip_code,
                radius_in_miles=10,
                limit=1
            )

# Search for products
products = kroger.product.search_products(
        term="milk",
        location_id=locations["data"][0]["locationId"],
        limit=5
    )

print(f"Found {len(products['data'])} products!")
```

## 🔐 Getting Started with Credentials

### 1. Create a Kroger Developer Account
Visit the [Kroger Developer Portal](https://developer.kroger.com/manage/apps/register) to:
1. Create a developer account
2. Register your application
3. Get your `CLIENT_ID`, `CLIENT_SECRET`, and set your `REDIRECT_URI`

### 2. Set Up Environment Variables
Copy `.env.example` to `.env` and fill in your credentials:

```bash
# Kroger API Credentials
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
KROGER_REDIRECT_URI=http://localhost:8000/callback

# Optional (Recommended): Your zip code for location-based searches
KROGER_USER_ZIP_CODE=90210
```

**Important:** Set your `KROGER_REDIRECT_URI` during app registration. While marked as optional in the form, the OAuth flow requires it.

### 3. First Run Authorization
The first time you run a script requiring user authentication, you'll be prompted to authorize your app through your web browser. You're granting permission to **your own registered app**, not to any third party.

## 🔄 Token Management

This library implements robust, automatic token management:

### ✨ Features
- **Automatic token refresh** - No manual token handling required
- **Persistent storage** - Tokens saved securely to avoid repeated logins  
- **Proactive validation** - Tests tokens before use
- **Reactive recovery** - Automatically refreshes expired tokens during API calls
- **PKCE Support** - Enhanced OAuth security with Proof Key for Code Exchange

### 🔧 How it Works

**Proactive Approach:**
1. Loads saved tokens and tests them with a lightweight API request
2. Automatically refreshes if token is expired and refresh token is available

**Reactive Approach:**
1. Makes API requests with current token
2. On 401 Unauthorized errors, attempts token refresh
3. Retries original request with new token

Token files (automatically managed, stored in project root):
- `.kroger_token_client_product.compact.json` - Client credentials tokens
- `.kroger_token_user.json` - User authorization tokens

### 🔒 Enhanced Security with PKCE

This library supports PKCE (Proof Key for Code Exchange) for enhanced security in the OAuth flow:

```python
from kroger_api import KrogerAPI
from kroger_api.utils import generate_pkce_parameters

# Generate PKCE parameters
pkce_params = generate_pkce_parameters()

# Initialize the client
kroger = KrogerAPI()

# Get authorization URL with PKCE
auth_url = kroger.authorization.get_authorization_url(
    scope="cart.basic:write profile.compact",
    state="random_state_value",
    code_challenge=pkce_params['code_challenge'],
    code_challenge_method=pkce_params['code_challenge_method']
)

# After user authorization and redirect, exchange code for token with verifier
token_info = kroger.authorization.get_token_with_authorization_code(
    code="authorization_code_from_redirect",
    code_verifier=pkce_params['code_verifier']
)
```

PKCE helps protect against authorization code interception attacks, particularly important for public clients or those using external tools to manage OAuth flows.

## 📚 Example Scripts

The `examples/` directory contains comprehensive demonstrations:

| Script | Description | Authentication Required |
|--------|-------------|------------------------|
| `location_api_examples.py` | Search stores, get details about locations, chains, and departments | Client credentials |
| `product_api_examples.py` | Search products, get details, filter by various criteria | Client credentials |
| `cart_api_examples.py` | Add items to user's cart, full shopping workflow | User authorization |
| `identity_api_examples.py` | Get user profile information | User authorization |
| `oauth_flow.py` | Complete OAuth2 authorization code flow example | User authorization |
| `token_refresh_example.py` | Demonstrates automatic token refresh functionality | Both |
| `authorization_api_examples.py` | All authorization endpoints and flows | Both |
| `clear_tokens.py` | Utility to delete all saved token files | None |

### 🏃‍♂️ Running Examples

```bash
# Make sure your .env file is configured first!

# Public API examples (no user login required)
python examples/location_api_examples.py
python examples/product_api_examples.py

# User-specific examples (requires browser login)
python examples/cart_api_examples.py
python examples/identity_api_examples.py
python examples/oauth_flow.py

# Utility scripts
python examples/clear_tokens.py  # Clear saved tokens
```

Here's a quick demo of browsing via the Product API with `examples/product_api_examples.py`:

<div align="center">
  <img src="assets/product_api_script.gif" alt="Kroger API Python Demo">
</div>

## 🏪 Kroger Public API Information

### API Versions & Rate Limits

| API | Version | Rate Limit | Notes |
|-----|---------|------------|-------|
| **Authorization** | 1.0.13 | No specific limit | Token management |
| **Products** | 1.2.4 | 10,000 calls/day | Search and product details |
| **Locations** | 1.2.2 | 1,600 calls/day per endpoint | Store locations and details |
| **Cart** | 1.2.3 | 5,000 calls/day | Add/manage cart items |
| **Identity** | 1.2.3 | 5,000 calls/day | User profile information |

**Note:** Rate limits are enforced per endpoint, not per operation. You can distribute calls across operations using the same endpoint as needed.

### 🔑 Available Scopes

When requesting user authorization, you can specify these scopes:

- `product.compact` - Read product information
- `cart.basic:write` - Add items to cart  
- `profile.compact` - Read user profile information

## 📖 API Documentation

For complete API documentation, visit:
- [Kroger Developer Portal](https://developer.kroger.com/)
- [API Documentation](https://developer.kroger.com/documentation/public/)
- [Acceptable Use Policy](https://developer.kroger.com/documentation/public/getting-started/acceptable-use)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

This is an unofficial Python client for the Kroger Public API. It is not affiliated with, endorsed by, or sponsored by Kroger.
