kroger-cli

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Kroger CLI 🛒

A comprehensive Ruby command-line interface for the Kroger API, providing full shopping functionality including product search, cart management, store location services, and real-time sales tracking.

## ✨ Features

### 🔐 Authentication
- **OAuth 2.0** client credentials flow for public data
- **User authentication** via browser for cart operations
- **Automatic token refresh** (27-minute strategy)
- **Secure token storage** (.token file)

### 🏪 Store Management
- **Store location search** by ZIP code
- **Default store configuration** for consistent pricing
- **Store-specific inventory** and pricing information
- **Interactive store selection**

### 🔍 Product Discovery
- **Smart product search** with fuzzy matching
- **Delivery-only filtering** for online orders
- **Real-time stock levels** (High/Low/Out)
- **Enhanced sales display** with savings calculations
- **Product details** including nutrition information

### 🛒 Shopping Cart
- **Add/remove items** from cart
- **Update quantities**
- **Store-specific cart** operations
- **Cart persistence** across sessions

### 💰 Sales & Pricing
- **Real-time pricing** from your selected store
- **Sale detection** with visual indicators (🏷️ ON SALE)
- **Savings calculations** ("💰 You Save: $0.16 (6% off)")
- **Promotional pricing** display

## 🚀 Installation

### Prerequisites
- **Ruby 3.0+** (tested with Ruby 3.3.2)
- **Bundler** for dependency management
- **Kroger API credentials** from [developer.kroger.com](https://developer.kroger.com/)

### Setup Steps

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd kroger-cli
   ```

2. **Install dependencies**
   ```bash
   bundle install
   ```

3. **Configure API credentials**
   ```bash
   cp .env.example .env
   ```
   Edit `.env` and add your Kroger API credentials:
   ```bash
   KROGER_CLIENT_ID=your_client_id_here
   KROGER_CLIENT_SECRET=your_client_secret_here
   ```

4. **Set up your default store** (recommended)
   ```bash
   ./bin/kroger store set
   # Follow prompts to select your preferred store
   ```

5. **Test the installation**
   ```bash
   ./bin/kroger auth
   ```

## 📋 API Credentials Setup

1. **Register at Kroger Developer Portal**
   - Visit [developer.kroger.com](https://developer.kroger.com/)
   - Create a developer account
   - Register a new application

2. **Configure your application**
   - **Redirect URI**: `http://localhost:8573`
   - **Required Scopes**:
     - `product.compact` (product search)
     - `cart.basic:write` (cart management)
     - `profile.compact` (user info)

3. **Copy credentials**
   - Client ID and Client Secret to your `.env` file

## 💻 Usage

### Authentication & Setup

```bash
# Test API connection
./bin/kroger auth

# Login for cart functionality (opens browser)
./bin/kroger login

# Set your default store
./bin/kroger store set

# Show current store
./bin/kroger store show

# Logout from user account
./bin/kroger logout
```

### Store Operations

```bash
# Find stores by ZIP code
./bin/kroger stores 80525

# Search with custom radius
./bin/kroger stores 80525 --radius 25
```

### Product Search

```bash
# Basic product search
./bin/kroger products "organic milk"

# Delivery-only items (recommended)
./bin/kroger products "bread" --delivery

# Limit results
./bin/kroger products "cheese" --delivery --limit 5

# Get detailed product information
./bin/kroger product 0001111041700
```

### Shopping Cart (requires login)

```bash
# View cart contents
./bin/kroger cart view

# Add items to cart
./bin/kroger cart add 0001111041700
./bin/kroger cart add 0001111041700 --quantity 3

# Update item quantity
./bin/kroger cart update 0001111041700 2

# Remove items
./bin/kroger cart remove <item_id>
```

### Help & Options

```bash
# Show all commands
./bin/kroger help

# Command-specific help
./bin/kroger products --help
./bin/kroger stores --help
```

## 🎯 Example Workflow

```bash
# 1. Set up authentication and store
./bin/kroger auth
./bin/kroger login
./bin/kroger store set

# 2. Search for delivery-available products
./bin/kroger products "milk" --delivery

# 3. Add items to cart using UPC from search results
./bin/kroger cart add 0001111050236 --quantity 2

# 4. Check what's in your cart
./bin/kroger cart view
```

## 📊 Output Examples

### Product Search (On Sale)
```
Kroger® Sharp Cheddar Block Cheese 🏷️ ON SALE
  UPC: 0001111058627
  Brand: Kroger
  Size: 8 oz
  Price: $2.49 $2.33
  💰 You Save: $0.16 (6% off)
  Status: ✓ In stock
```

### Product Search (Regular Price)
```
Kroger® Ice Cream Tub
  UPC: 0001111050508
  Brand: Kroger
  Size: 48 oz
  Price: $2.99
  Status: ✓ In stock
```

## 🔧 Configuration Files

- **`.env`** - API credentials (gitignored)
- **`.token`** - User authentication tokens (gitignored)
- **`.kroger_store`** - Default store configuration (gitignored)

## 🏗️ Architecture

```
kroger-cli/
├── bin/kroger              # Main executable
├── lib/
│   ├── kroger.rb          # Main module & configuration
│   ├── kroger/
│   │   ├── auth.rb        # Client credentials OAuth
│   │   ├── user_auth.rb   # User authentication flow
│   │   ├── store_config.rb # Store management
│   │   ├── api_client.rb  # HTTP client & API calls
│   │   ├── services/      # Business logic services
│   │   └── cli/           # Command-line interface
└── README.md
```

## 🛡️ Security

- **API credentials** stored in environment variables
- **User tokens** stored locally in `.token` file
- **No sensitive data** committed to repository
- **Automatic token refresh** prevents expired sessions
- **OAuth 2.0 PKCE flow** for secure user authentication

## 🐛 Troubleshooting

### Authentication Issues
```bash
# Check if credentials are loaded
./bin/kroger auth

# Clear and re-login if having user auth issues
./bin/kroger logout
./bin/kroger login
```

### Cart Issues
- **404 errors**: Ensure you're logged in (`./bin/kroger login`)
- **Invalid items**: Use `--delivery` flag to find deliverable products
- **Store not set**: Configure default store (`./bin/kroger store set`)

### API Rate Limits
- **10,000 calls per day** for public APIs
- Use `--delivery` flag to reduce unnecessary API calls
- Set default store to avoid repeated location lookups

## 🎯 Use Cases

- **Grocery shopping** - Search and add items to cart for delivery
- **Price comparison** - Check current prices and sales
- **Store information** - Find locations and hours
- **Sale hunting** - Identify discounted items with savings calculations
- **Meal planning** - Search for specific ingredients
- **Bulk shopping** - Add multiple quantities to cart efficiently

## 🚀 Future Enhancements

- **Recipe integration** - Add ingredients from recipes
- **Shopping lists** - Save and manage multiple lists
- **Price tracking** - Historical price monitoring
- **Coupon management** - Digital coupon application
- **Order history** - View past purchases
- **Nutritional analysis** - Aggregate nutrition information

## 📄 License

This project is for educational and personal use. Please respect Kroger's API terms of service.

---

Built with ❤️ using Ruby and the Kroger API

Kroger CLI 🛒

A comprehensive Ruby command-line interface for the Kroger API, providing full shopping functionality including product search, cart management, store location services, and real-time sales tracking.

✨ Features

🔐 Authentication

OAuth 2.0 client credentials flow for public data
User authentication via browser for cart operations
Automatic token refresh (27-minute strategy)
Secure token storage (.token file)

🏪 Store Management

Store location search by ZIP code
Default store configuration for consistent pricing
Store-specific inventory and pricing information
Interactive store selection

🔍 Product Discovery

Smart product search with fuzzy matching
Delivery-only filtering for online orders
Real-time stock levels (High/Low/Out)
Enhanced sales display with savings calculations
Product details including nutrition information

🛒 Shopping Cart

Add/remove items from cart
Update quantities
Store-specific cart operations
Cart persistence across sessions

💰 Sales & Pricing

Real-time pricing from your selected store
Sale detection with visual indicators (🏷️ ON SALE)
Savings calculations ("💰 You Save: $0.16 (6% off)")
Promotional pricing display

🚀 Installation

Prerequisites

Ruby 3.0+ (tested with Ruby 3.3.2)
Bundler for dependency management
Kroger API credentials from developer.kroger.com

Setup Steps

Clone the repository

git clone <repository-url>
cd kroger-cli

Install dependencies
```
bundle install
```

Configure API credentials

cp .env.example .env

Edit .env and add your Kroger API credentials:

KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here

Set up your default store (recommended)

./bin/kroger store set
# Follow prompts to select your preferred store

Test the installation
```
./bin/kroger auth
```

📋 API Credentials Setup

Register at Kroger Developer Portal
- Visit developer.kroger.com
- Create a developer account
- Register a new application
Configure your application
- Redirect URI: http://localhost:8573
- Required Scopes:
  - product.compact (product search)
  - cart.basic:write (cart management)
  - profile.compact (user info)
Copy credentials
- Client ID and Client Secret to your .env file

💻 Usage

Authentication & Setup

# Test API connection
./bin/kroger auth

# Login for cart functionality (opens browser)
./bin/kroger login

# Set your default store
./bin/kroger store set

# Show current store
./bin/kroger store show

# Logout from user account
./bin/kroger logout

Store Operations

# Find stores by ZIP code
./bin/kroger stores 80525

# Search with custom radius
./bin/kroger stores 80525 --radius 25

Product Search

# Basic product search
./bin/kroger products "organic milk"

# Delivery-only items (recommended)
./bin/kroger products "bread" --delivery

# Limit results
./bin/kroger products "cheese" --delivery --limit 5

# Get detailed product information
./bin/kroger product 0001111041700

Shopping Cart (requires login)

# View cart contents
./bin/kroger cart view

# Add items to cart
./bin/kroger cart add 0001111041700
./bin/kroger cart add 0001111041700 --quantity 3

# Update item quantity
./bin/kroger cart update 0001111041700 2

# Remove items
./bin/kroger cart remove <item_id>

Help & Options

# Show all commands
./bin/kroger help

# Command-specific help
./bin/kroger products --help
./bin/kroger stores --help

🎯 Example Workflow

# 1. Set up authentication and store
./bin/kroger auth
./bin/kroger login
./bin/kroger store set

# 2. Search for delivery-available products
./bin/kroger products "milk" --delivery

# 3. Add items to cart using UPC from search results
./bin/kroger cart add 0001111050236 --quantity 2

# 4. Check what's in your cart
./bin/kroger cart view

📊 Output Examples

Product Search (On Sale)

Kroger® Sharp Cheddar Block Cheese 🏷️ ON SALE
  UPC: 0001111058627
  Brand: Kroger
  Size: 8 oz
  Price: $2.49 $2.33
  💰 You Save: $0.16 (6% off)
  Status: ✓ In stock

Product Search (Regular Price)

Kroger® Ice Cream Tub
  UPC: 0001111050508
  Brand: Kroger
  Size: 48 oz
  Price: $2.99
  Status: ✓ In stock

🔧 Configuration Files

.env - API credentials (gitignored)
.token - User authentication tokens (gitignored)
.kroger_store - Default store configuration (gitignored)

🏗️ Architecture

kroger-cli/
├── bin/kroger              # Main executable
├── lib/
│   ├── kroger.rb          # Main module & configuration
│   ├── kroger/
│   │   ├── auth.rb        # Client credentials OAuth
│   │   ├── user_auth.rb   # User authentication flow
│   │   ├── store_config.rb # Store management
│   │   ├── api_client.rb  # HTTP client & API calls
│   │   ├── services/      # Business logic services
│   │   └── cli/           # Command-line interface
└── README.md

🛡️ Security

API credentials stored in environment variables
User tokens stored locally in .token file
No sensitive data committed to repository
Automatic token refresh prevents expired sessions
OAuth 2.0 PKCE flow for secure user authentication

🐛 Troubleshooting

Authentication Issues

# Check if credentials are loaded
./bin/kroger auth

# Clear and re-login if having user auth issues
./bin/kroger logout
./bin/kroger login

Cart Issues

404 errors: Ensure you're logged in (./bin/kroger login)
Invalid items: Use --delivery flag to find deliverable products
Store not set: Configure default store (./bin/kroger store set)

API Rate Limits

10,000 calls per day for public APIs
Use --delivery flag to reduce unnecessary API calls
Set default store to avoid repeated location lookups

🎯 Use Cases

Grocery shopping - Search and add items to cart for delivery
Price comparison - Check current prices and sales
Store information - Find locations and hours
Sale hunting - Identify discounted items with savings calculations
Meal planning - Search for specific ingredients
Bulk shopping - Add multiple quantities to cart efficiently

🚀 Future Enhancements

Recipe integration - Add ingredients from recipes
Shopping lists - Save and manage multiple lists
Price tracking - Historical price monitoring
Coupon management - Digital coupon application
Order history - View past purchases
Nutritional analysis - Aggregate nutrition information

📄 License

This project is for educational and personal use. Please respect Kroger's API terms of service.

Built with ❤️ using Ruby and the Kroger API