kroger-api 0.1.0__tar.gz

kroger_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

kroger_api-0.1.0/MANIFEST.in

@@ -0,0 +1,40 @@
+# Include the README
+include README.md
+
+# Include the license
+include LICENSE
+
+# Include requirements
+include requirements.txt
+
+# Include assets (demo videos, images, etc.)
+recursive-include assets *.mp4 *.gif *.png *.jpg *.jpeg
+
+# Include examples directory but don't package them in the main distribution
+recursive-include examples *.py
+prune examples/__pycache__
+
+# Exclude test files
+recursive-exclude tests *
+
+# Exclude development and build files
+exclude .env*
+exclude .gitignore
+exclude test_all_examples.sh
+exclude *.egg-info
+exclude .kroger_token*
+global-exclude *.pyc
+global-exclude __pycache__
+
+# Exclude documentation that shouldn't be in the package
+recursive-exclude docs_kroger_api *
+
+# Exclude virtual environment
+recursive-exclude venv *
+
+# Exclude git files
+recursive-exclude .git *
+
+# Exclude build artifacts
+recursive-exclude build *
+recursive-exclude dist *

kroger_api-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: kroger-api
+Version: 0.1.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
+
+Here's a quick demo of browsing via the Product API:
+
+<div align="center">
+  <img src="assets/product_api_script.gif" alt="Kroger API Python Demo">
+</div>
+
+## 🚀 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
+
+# Initialize the client
+kroger = KrogerAPI()
+
+# Get a client credentials token for public data
+kroger.authorization.get_token_with_client_credentials("product.compact")
+
+# Search for products
+products = kroger.product.search_products(
+    term="milk",
+    location_id="01400443",  # A Kroger store location
+    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
+
+### 🔧 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
+
+## 📚 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
+```
+
+## 🏪 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.

kroger_api-0.1.0/README.md

@@ -0,0 +1,176 @@
+# 🛒 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
+
+Here's a quick demo of browsing via the Product API:
+
+<div align="center">
+  <img src="assets/product_api_script.gif" alt="Kroger API Python Demo">
+</div>
+
+## 🚀 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
+
+# Initialize the client
+kroger = KrogerAPI()
+
+# Get a client credentials token for public data
+kroger.authorization.get_token_with_client_credentials("product.compact")
+
+# Search for products
+products = kroger.product.search_products(
+    term="milk",
+    location_id="01400443",  # A Kroger store location
+    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
+
+### 🔧 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
+
+## 📚 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
+```
+
+## 🏪 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.