breezi-cli/README.md

CLI tool to generate Breezi PayPal integration projects

# Breezi CLI

> 🚀 **Instant PayPal Integration Generator** - Create complete payment integration projects in seconds

## Overview

The Breezi CLI is a code generator that creates fully functional PayPal integration projects with zero configuration. Simply run the command, answer a few questions, and get a complete, working application ready for development.

## Installation

### Global Installation (Recommended)
```bash
npm install -g breezi-cli
breezi
```

### One-time Usage
```bash
npx breezi-cli
```

### Local Installation
```bash
npm install breezi-cli
npx breezi
```

## Usage

Simply run the CLI and answer the prompts:

```bash
$ breezi

🚀 Welcome to Breezi CLI - One-Click PayPal Integration

? Project name: my-store
? Choose your framework: React
? PayPal Client ID (sandbox): your_sandbox_client_id_here

✅ Project created successfully!

Next steps:
  cd my-store
  npm install
  npm start

🎉 Your PayPal integration is ready!
```

## Supported Frameworks

### React
Generates a complete React application with:
- ✅ **@breezi/react** component integration
- ✅ **TypeScript support** (optional)
- ✅ **Create React App** setup
- ✅ **Environment variables** configured
- ✅ **PayPal sandbox** integration
- ✅ **Production-ready** code structure

### Vanilla JavaScript
Generates a pure HTML/JS application with:
- ✅ **@breezi/js** widget integration
- ✅ **Zero dependencies** (except PayPal SDK)
- ✅ **Simple HTML** file structure
- ✅ **Instant testing** capability
- ✅ **CDN-ready** deployment

## Generated Project Structure

### React Project
```
my-project/
├── public/
│   └── index.html
├── src/
│   ├── App.js          # Main React component
│   ├── App.css         # Styling
│   └── index.js        # React entry point
├── .env                # Environment variables
└── package.json        # Dependencies & scripts
```

### Vanilla JS Project
```
my-project/
├── index.html          # Complete HTML application
├── .env                # Environment variables
└── package.json        # Basic package info
```

## PayPal Setup

### 1. Get Sandbox Credentials
1. Go to [PayPal Developer](https://developer.paypal.com)
2. Create a new application
3. Copy your **Sandbox Client ID**
4. Use this in the CLI when prompted

### 2. Environment Configuration
The CLI automatically creates an `.env` file:

**React:**
```bash
REACT_APP_PAYPAL_CLIENT_ID=your_sandbox_client_id_here
```

**Vanilla JS:**
```bash
PAYPAL_CLIENT_ID=your_sandbox_client_id_here
```

### 3. Testing Payments
- Use PayPal sandbox environment
- Create test buyer accounts in PayPal Developer
- No real money is charged in sandbox mode

### 4. Production Deployment
1. Get production Client ID from PayPal
2. Update environment variables
3. Change environment to `production`
4. Deploy your application

## Generated Code Examples

### React Component (Generated)
```jsx
import React from 'react';
import { BreeziPayPal } from '@breezi/react';

function App() {
  return (
    <BreeziPayPal
      clientId={process.env.REACT_APP_PAYPAL_CLIENT_ID}
      amount="10.00"
      currency="USD"
      onSuccess={(details) => {
        console.log('Payment successful:', details);
        alert('Payment successful!');
      }}
      onError={(error) => {
        console.error('Payment error:', error);
        alert('Payment failed.');
      }}
    />
  );
}
```

### Vanilla JS Widget (Generated)
```html
<div 
  data-breezi-paypal
  data-client-id="your_paypal_client_id"
  data-amount="10.00"
  data-currency="USD"
  data-environment="sandbox">
</div>

<script src="node_modules/@breezi/js/dist/sdk.js"></script>
```

## Post-Generation Steps

### React Projects
```bash
cd my-project
npm install           # Install dependencies
npm start            # Start development server
```

### Vanilla JS Projects
```bash
cd my-project
npm install          # Install Breezi SDK
npm run serve        # Start local server
# OR
open index.html      # Open directly in browser
```

## Customization

### Payment Amount
Update the `amount` prop in your generated code:
```jsx
<BreeziPayPal amount="29.99" />
```

### Currency
Change the currency:
```jsx
<BreeziPayPal currency="EUR" />
```

### Styling
React projects include CSS files you can customize:
- `src/App.css` - Component styles
- Add custom themes via the `theme` prop

### Event Handlers
Customize success/error handling:
```jsx
<BreeziPayPal
  onSuccess={(payment) => {
    // Custom success logic
    window.location.href = '/thank-you';
  }}
  onError={(error) => {
    // Custom error handling
    console.error('Payment failed:', error);
  }}
/>
```

## Troubleshooting

### Common Issues

**"PayPal Client ID is required"**
- Make sure your `.env` file has the correct Client ID
- Restart your development server after updating `.env`

**"Failed to load PayPal SDK"**
- Check your internet connection
- Verify your Client ID is valid
- Try using a different browser

**"Payment failed"**
- Ensure you're using sandbox mode for testing
- Check PayPal Developer dashboard for error logs
- Verify your test account has sufficient funds

### Getting Help

1. **Check the generated `.env` file** - Ensure Client ID is set
2. **Verify PayPal Developer setup** - Client ID should be active
3. **Test with PayPal sandbox accounts** - Create test buyers
4. **Check browser console** - Look for error messages

## Advanced Usage

### Multiple Environments
Set up different environments:

```bash
# Development
REACT_APP_PAYPAL_CLIENT_ID=sandbox_client_id
REACT_APP_PAYPAL_ENVIRONMENT=sandbox

# Production
REACT_APP_PAYPAL_CLIENT_ID=live_client_id
REACT_APP_PAYPAL_ENVIRONMENT=production
```

### Custom Configuration
Modify generated code for advanced features:
- Multiple payment amounts
- Product catalogs
- Subscription billing
- Webhook integration

## CLI Options

The CLI currently supports interactive mode only. Future versions may include:
- `--framework react|vanilla` - Skip framework selection
- `--name my-project` - Skip name prompt
- `--client-id abc123` - Skip Client ID prompt
- `--template basic|advanced` - Choose templates

---

**Need help?** Check out the [examples](../../examples/) or open an issue on [GitHub](https://github.com/breezi-dev/breezi-os-sdk/issues).