# Feature Request: Stripe Product Management CLI Commands

## Overview
Request to add Stripe product and price management capabilities to the `augint-billing-lib` CLI (`ai-billing` command). Currently, users must manually create products in Stripe or write custom scripts, which is error-prone and inconsistent.

## Problem Statement
The billing infrastructure requires specific Stripe products and prices to be configured correctly:
- Products must have the correct metadata and configuration
- Prices must be set up with proper metered/subscription types
- Product IDs must be added to `.env` for deployment
- Different configurations needed for staging vs production

Currently, this requires manual Stripe dashboard work or custom scripts that may not be maintained.

## Proposed Solution
Add a new command group to the CLI: `ai-billing products` (or `ai-billing stripe-products`)

### Command Structure
```bash
# Create/update products for an environment
ai-billing products setup [staging|production] [options]

# Verify existing products
ai-billing products verify [staging|production]

# List products in an environment
ai-billing products list [staging|production]

# Show product details
ai-billing products show <product_id>
```

## Detailed Requirements

### 1. Product Setup Command
```bash
ai-billing products setup staging --model subscription-plus-metered
```

#### Supported Pricing Models

**Model 1: `subscription-plus-metered` (Recommended)**
- Base subscription price (e.g., $29.99/month)
- Plus metered usage with tiered pricing
- First X requests included in base
- Additional requests charged per tier

**Model 2: `metered-only`**
- No base fee
- Pure usage-based pricing
- Tiered pricing structure

**Model 3: `subscription-only`**
- Fixed monthly price
- No usage tracking

#### Configuration Options
```bash
--base-price <amount>          # Base subscription price in cents (default: 2999 for $29.99)
--currency <code>              # Currency code (default: usd)
--included-requests <number>   # Requests included in base (default: 1000)
--tier-1-limit <number>        # Upper limit for tier 1 (default: 10000)
--tier-1-price <amount>        # Price per request in tier 1 in cents (default: 10 for $0.10)
--tier-2-limit <number>        # Upper limit for tier 2 (default: 100000)
--tier-2-price <amount>        # Price per request in tier 2 in cents (default: 8 for $0.08)
--tier-3-price <amount>        # Price per request in tier 3+ in cents (default: 5 for $0.05)
--product-name <name>          # Custom product name (default: "AI API Subscription (Environment)")
--update-env                   # Automatically update .env file (default: true)
--dry-run                      # Show what would be created without making changes
```

### 2. Output Format
The command should output the created/found product and price IDs in a format ready for `.env`:

```
✅ Product setup complete for staging environment

Add these to your .env file:
STAGING_API_USAGE_PRODUCT_ID=prod_SvMVAtX3274YgH
STAGING_BASE_SUBSCRIPTION_PRICE_ID=price_1RzVnBBfKwfsUOJQkeR26xbz
STAGING_METERED_USAGE_PRICE_ID=price_1RzVoKBfKwfsUOJQYAdgyyU1

Or run with --update-env to automatically update your .env file.

Pricing Structure:
- Base: $29.99/month
- Included: 1,000 requests
- 1,001-10,000: $0.10/request
- 10,001-100,000: $0.08/request
- 100,001+: $0.05/request

Example monthly bills:
- 500 requests: $29.99
- 5,000 requests: $429.99
- 50,000 requests: $3,629.99
```

### 3. Verification Command
```bash
ai-billing products verify staging
```

Should check:
- Products exist in Stripe
- Prices are configured correctly
- Environment variables are set
- Products match expected configuration

Output:
```
✅ Stripe products configured correctly for staging

Product: AI API Subscription (Staging) [prod_xxx]
- Base price: $29.99/month [price_xxx]
- Metered price: Configured with 4 tiers [price_xxx]
- Environment variables: Set in .env
```

### 4. Smart Detection
The command should be smart about existing products:
- Check if products with the same name already exist
- Reuse existing products when appropriate
- Create new prices if pricing structure changed
- Handle API version compatibility issues

### 5. Environment Integration
- Read Stripe keys from `.env` (using existing pattern)
- Support `STAGING_` and `PROD_` prefixes
- Validate keys before attempting operations
- Handle both test and live modes appropriately

## Implementation Considerations

### Stripe API Version
- Must handle Stripe API version compatibility
- Should work with both old metered pricing and new meter-based pricing
- Specify API version in requests for consistency

### Error Handling
- Clear error messages if Stripe keys are missing/invalid
- Handle rate limits gracefully
- Provide rollback guidance if setup fails partway

### Idempotency
- Commands should be idempotent
- Running setup multiple times should not create duplicate products
- Should detect and reuse existing products/prices

### Testing
- Must work with Stripe test mode keys
- Should validate against test products before production
- Include dry-run mode for safety

## Example Usage Flow

```bash
# 1. Initial setup for staging
$ ai-billing products setup staging --model subscription-plus-metered
Creating products for staging environment...
✅ Created product: AI API Subscription (Staging)
✅ Created base price: $29.99/month
✅ Created metered price with 4 tiers
✅ Updated .env file

# 2. Verify setup
$ ai-billing products verify staging
✅ All products configured correctly

# 3. Deploy infrastructure
$ python scripts/deploy.py staging
[Uses product IDs from .env]

# 4. Later: Adjust pricing
$ ai-billing products setup staging --base-price 3999 --update-env
⚠️  Product exists, creating new price...
✅ Created new base price: $39.99/month
✅ Updated .env file with new price ID

# 5. Setup production (when ready)
$ ai-billing products setup production --model subscription-plus-metered
[Creates separate products for production]
```

## Benefits
1. **Consistency**: Ensures products are created with correct configuration
2. **Safety**: Dry-run mode and verification prevent mistakes
3. **Integration**: Works seamlessly with existing CLI and infrastructure
4. **Documentation**: Command help serves as documentation for pricing models
5. **Automation**: Can be integrated into CI/CD pipelines

## Priority
**HIGH** - This is a critical setup step that every user of the billing infrastructure needs to perform. Without proper products in Stripe, the entire billing system cannot function.

## Related Commands
This would complement existing CLI commands:
- `ai-billing billing env show` - Shows current configuration
- `ai-billing test stripe` - Tests Stripe integration
- `ai-billing monitor` - Monitors billing operations

## Alternative Approaches Considered
1. **Terraform/CloudFormation**: Cannot manage Stripe resources
2. **Separate script**: Current approach, but not integrated with CLI
3. **Manual setup**: Error-prone and not reproducible
4. **Stripe Dashboard**: Not automatable, not version controlled

## Acceptance Criteria
- [ ] Can create products and prices in Stripe for staging/production
- [ ] Handles existing products gracefully (idempotent)
- [ ] Updates `.env` file with product/price IDs
- [ ] Supports multiple pricing models
- [ ] Includes verification command
- [ ] Has comprehensive error handling
- [ ] Includes dry-run mode
- [ ] Works with both test and live Stripe keys
- [ ] Handles Stripe API version compatibility
