# Content Generation Engine - API Documentation

## 🎯 Overview

The Content Generation Engine takes JSON blueprints containing spintax and variables, generates unique combinations via Cartesian expansion, resolves spintax to create unique variations, and produces full 2000-word articles.

## 📡 API Endpoints

### 1. Create Campaign
**POST** `/api/god/campaigns/create`

Creates a new campaign from a JSON blueprint.

**Headers:**
```
X-God-Token: <your_god_token>
Content-Type: application/json
```

**Request Body:**
```json
{
  "name": "Campaign Name (optional)",
  "blueprint": {
    "asset_name": "{{CITY}} Solar Revenue",
    "deployment_target": "High-Value Funnel",
    "variables": {
      "STATE": "California",
      "CITY": "San Diego|Irvine|Anaheim",
      "AVATAR_A": "Solar CEO"
    },
    "content": {
      "url_path": "{{CITY}}.example.com",
      "meta_description": "{Stop|Eliminate} waste in {{CITY}}",
      "body": [
        {
          "block_type": "Hero",
          "content": "<h1>{Title A|Title B}</h1><p>Content for {{CITY}}</p>"
        }
      ]
    }
  }
}
```

**Response:**
```json
{
  "success": true,
  "campaignId": "uuid",
  "message": "Campaign created. Use /launch/<id> to generate."
}
```

---

### 2. Launch Campaign
**POST** `/api/god/campaigns/launch/:id`

Queues a campaign for content generation.

**Headers:**
```
X-God-Token: <your_god_token>
```

**Response:**
```json
{
  "success": true,
  "campaignId": "uuid",
  "status": "processing"
}
```

---

### 3. Check Status
**GET** `/api/god/campaigns/status/:id`

Get campaign generation status and stats.

**Headers:**
```
X-God-Token: <your_god_token>
```

**Response:**
```json
{
  "campaignId": "uuid",
  "name": "Campaign Name",
  "status": "completed",
  "postsCreated": 15,
  "blockUsage": [
    { "block_type": "Hero", "total_uses": 15 }
  ]
}
```

---

## 🎨 Blueprint Structure

### Variables
Pipe-separated values generate Cartesian products:
```json
{
  "CITY": "A|B|C",     // 3 values
  "STATE": "X|Y"       // 2 values
  // = 6 total combinations
}
```

### Spintax Syntax
```
{Option A|Option B|Option C}
```

### Variable Placeholders
```
{{VARIABLE_NAME}}
```

## 📊 Usage Tracking

Every block use and spintax choice is tracked:
- `block_usage_stats` - How many times each block was used
- `spintax_variation_stats` - Which spintax choices were selected
- `variation_registry` - Hash of every unique variation

## 🔧 Worker Process

The BullMQ worker (`contentGenerator.ts`):
1. Fetches blueprint from DB
2. Generates Cartesian product of variables
3. For each combination:
   - Expands `{{VARIABLES}}`
   - Resolves `{spin|tax}`
   - Checks uniqueness hash
   - Creates post in DB
   - Records variation & updates stats

## 🚀 Quick Start

### Via UI
1. Go to `/admin/content-generator`
2. Paste JSON blueprint
3. Click "Create Campaign"
4. Launch from campaigns list

### Via API
```bash
# 1. Create
curl -X POST https://spark.jumpstartscaling.com/api/god/campaigns/create \
  -H "X-God-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @blueprint.json

# 2. Launch
curl -X POST https://spark.jumpstartscaling.com/api/god/campaigns/launch/CAMPAIGN_ID \
  -H "X-God-Token: YOUR_TOKEN"

# 3. Check status
curl https://spark.jumpstartscaling.com/api/god/campaigns/status/CAMPAIGN_ID \
  -H "X-God-Token: YOUR_TOKEN"
```

## 📦 Database Schema

Key tables:
- `campaign_masters` - Stores blueprints
- `content_fragments` - Individual blocks
- `variation_registry` - Unique variations
- `block_usage_stats` - Block usage counts
- `posts` - Final generated content