# CompareKit

Professional featured image generator for SaaS comparisons, reviews, and alternatives. Built for Pragmaco.net.

## Features

- **4 Series Types**: Comparison, Review, Feature, Alternative (Comparison implemented)
- **Automatic Logo Fetching**: Clearbit API with Brandfetch fallback
- **Smart Randomization**: 24,000+ unique combinations with anti-repetition
- **Professional Effects**: Glass morphism, lighting, shadows, vignettes
- **Caching System**: Logo and background caching for performance
- **REST API**: Easy integration with n8n and other tools

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment

Copy `.env.example` to `.env` and add your API keys:

```bash
cp .env.example .env
```

Edit `.env`:
```env
CLEARBIT_API_KEY=optional_but_recommended
BRANDFETCH_API_KEY=optional_fallback
UNSPLASH_ACCESS_KEY=optional_for_real_photos
PORT=3000
```

**Note**: Clearbit's logo API is often free to use without a key for basic requests. Brandfetch and Unsplash are optional.

### 3. Generate Sample Backgrounds

```bash
node -e "const BgMgr = require('./src/lib/backgrounds'); new BgMgr().createSampleBackgrounds();"
```

### 4. Start Server

```bash
npm start
```

Or for development with auto-reload:
```bash
npm run dev
```

### 5. Open Test Interface

Visit `http://localhost:3000` in your browser.

## Usage

### Web Interface

1. Navigate to `http://localhost:3000`
2. Enter two product names (e.g., "Semrush" and "Ahrefs")
3. Click "Generate Image"
4. Download your professional comparison image!

### API Usage

#### Generate Single Comparison

```bash
curl -X POST http://localhost:3000/api/generate/comparison \
  -H "Content-Type: application/json" \
  -d '{"productA": "semrush", "productB": "ahrefs"}' \
  --output comparison.png
```

#### Generate Batch

```bash
curl -X POST http://localhost:3000/api/generate/batch \
  -H "Content-Type: application/json" \
  -d '{
    "comparisons": [
      ["semrush", "ahrefs"],
      ["monday", "asana"],
      ["shopify", "woocommerce"]
    ]
  }'
```

Images will be saved to `generated/` folder.

#### Get Available Styles

```bash
curl http://localhost:3000/api/generate/styles
```

#### Cache Management

```bash
# Get cache stats
curl http://localhost:3000/api/cache/stats

# Clear logo cache
curl -X DELETE http://localhost:3000/api/cache/logos

# Prefetch logos
curl -X POST http://localhost:3000/api/cache/prefetch \
  -H "Content-Type: application/json" \
  -d '{"products": ["semrush", "ahrefs", "monday"]}'
```

## Architecture

```
CompareKit/
├── src/
│   ├── api/
│   │   ├── generate.js      # Image generation endpoints
│   │   └── cache.js         # Cache management endpoints
│   ├── generators/
│   │   └── comparison.js    # Comparison image generator
│   ├── lib/
│   │   ├── canvas.js        # Canvas rendering engine
│   │   ├── logos.js         # Logo fetching & caching
│   │   ├── backgrounds.js   # Background management
│   │   └── randomizer.js    # Smart randomization
│   ├── config/
│   │   ├── brand.json       # Brand settings
│   │   ├── styles.json      # Visual styles
│   │   └── weights.json     # Randomization weights
│   └── server.js            # Express server
├── public/
│   ├── index.html           # Test interface
│   └── assets/
│       └── backgrounds/     # Background images
├── cache/
│   ├── logos/               # Cached logos
│   └── backgrounds/         # Cached backgrounds
└── generated/               # Generated images
```

## Customization

### Add Custom Product Domains

Edit `src/lib/logos.js` and add to the `domainMap`:

```javascript
const domainMap = {
  'yourproduct': 'yourproduct.com',
  // ...
};
```

### Adjust Style Weights

Edit `src/config/weights.json` to change how often certain styles appear:

```json
{
  "comparison": {
    "backgroundPreferences": {
      "photorealistic": 0.6,
      "abstract": 0.4
    }
  }
}
```

### Add Custom Color Schemes

Edit `src/config/styles.json`:

```json
{
  "colorSchemes": [
    {
      "id": "your-scheme",
      "name": "Your Scheme",
      "primary": "#1E40AF",
      "secondary": "#3B82F6",
      "accent": "#60A5FA",
      "text": "#FFFFFF"
    }
  ]
}
```

## Performance

- **Generation Time**: < 2 seconds per image
- **Logo Caching**: 30-day cache (configurable)
- **Image Size**: 1200x675px (optimal for featured images)
- **Format**: PNG with transparency support

## Deployment

### cPanel Deployment

1. Upload all files to your cPanel subdirectory
2. Install Node.js app in cPanel
3. Set document root to `public/`
4. Add environment variables in cPanel
5. Start the application

### PM2 (Production)

```bash
npm install -g pm2
pm2 start src/server.js --name comparekit
pm2 save
pm2 startup
```

## n8n Integration

Create an HTTP Request node in n8n:

```
Method: POST
URL: http://your-domain.com/api/generate/comparison
Headers: Content-Type: application/json
Body:
{
  "productA": "{{$json.productA}}",
  "productB": "{{$json.productB}}"
}
Binary Response: true
```

## Troubleshooting

### Logo Not Found

If a logo isn't fetched automatically:
1. Check the domain mapping in `src/lib/logos.js`
2. Verify API keys in `.env`
3. Check cache stats: `curl http://localhost:3000/api/cache/stats`

### Canvas/Sharp Installation Issues

If you encounter installation issues with `canvas` or `sharp`:

```bash
# macOS
brew install pkg-config cairo pango libpng jpeg giflib librsvg

# Ubuntu/Debian
sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

# Then reinstall
npm install
```

### Port Already in Use

Change the port in `.env`:
```env
PORT=3001
```

## Roadmap

- [ ] Review series generator
- [ ] Feature series generator
- [ ] Alternative series generator
- [ ] Real photo backgrounds via Unsplash
- [ ] Custom font support
- [ ] Batch processing UI
- [ ] Template presets

## License

MIT

## Support

For issues and questions, visit: https://pragmaco.net
