API_USAGE.md

# Sofia-Cloud: Sistema de Créditos y API

## 🎯 Resumen Rápido

Sofia-Cloud ahora tiene:
- ✅ **Creación automática de influencers** (análisis + generación + almacenamiento en 1 llamada)
- ✅ **Límites permanentes por tier** (NO se resetean mensualmente)
- ✅ **Rate-limiting inteligente** para proteger tu inversión
- ✅ **Tracking de uso acumulativo**

## 📊 Límites por Tier (PERMANENTES)

Los límites son parte de la suscripción pagada. **NO se resetean cada mes**. Se resetean solo si:

1. El cliente sube a un tier superior
2. O solicita manualmente un reset (si paga extra)

| Recurso | Free | Basic | Premium | Pro |
| --- | --- | --- | --- | --- |
| Influencers | 2 | 10 | 50 | 500 |
| Stories | 3 | 15 | 60 | 999 |
| Imágenes | 5 | 30 | 150 | 999 |
| Videos | 1 | 5 | 20 | 999 |
| Contenido Total | 10 | 50 | 300 | 999 |

## Ejemplo

- Cliente contrata **Basic** = 10 influencers de por vida con Basic
- Cuando haya usado los 10, recibe error "Necesitas subir a un tier superior"
- Si sube a **Premium** = ahora tiene 50 influencers totales (no 60, mantiene los 10 anteriores en el nuevo límite)

## 🔧 Cómo Usar

### 1️⃣ Crear Influencer (Automático)

```bash
curl -X POST http://localhost:7860/api/influencers \
  -H "Content-Type: application/json" \
  -d '{
    "targetNiche": "Fashion",
    "includePets": true,
    "userId": "user123",
    "tier": "premium"
  }'
```

**Respuesta exitosa:**
```json
{
  "success": true,
  "influencer": {
    "id": "cid123",
    "name": "Luna Style",
    "handle": "@lunastyle",
    "platform": "Instagram",
    "niche": "Fashion",
    "followers": 250000,
    "engagement": 3.5,
    "petCompanion": true,
    "petType": "dog"
  },
  "creditsRemaining": 49
}
```

**Si no hay créditos:**
```json
{
  "success": false,
  "error": "Límite mensual de influencers_per_month alcanzado (50). Intenta el próximo mes.",
  "remaining": 0
}
```

---

### 2️⃣ Crear Story (Con Validación)

```bash
curl -X POST http://localhost:7860/api/storytelling \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una influencer de moda que viaja por el mundo",
    "genre": "lifestyle",
    "totalEpisodes": 10,
    "userId": "user123",
    "tier": "premium"
  }'
```

**Respuesta:**
```json
{
  "success": true,
  "story": {
    "id": "story123",
    "title": "Luna Viajera",
    "description": "Una influencer de moda...",
    "genre": "lifestyle",
    "totalEpisodes": 10,
    "status": "draft",
    "episodes": [
      {
        "id": "ep1",
        "episodeNum": 1,
        "title": "Capítulo 1: El Comienzo",
        "content": "..."
      }
    ]
  },
  "creditsRemaining": 59
}
```

---

### 3️⃣ Generar Imagen (Con Límite)

```bash
curl -X POST http://localhost:7860/api/generate/image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una modelo de moda en París",
    "platform": "instagram",
    "style": "realistic",
    "userId": "user123",
    "tier": "basic"
  }'
```

---

## 🚨 Manejo de Errores

### Créditos agotados (429)
```json
{
  "success": false,
  "error": "Límite mensual de influencers_per_month alcanzado (10). Intenta el próximo mes.",
  "remaining": 0
}
```

### Falta prompty (400)
```json
{
  "success": false,
  "error": "Prompt requerido"
}
```

### Error de API (500)
```json
{
  "success": false,
  "error": "Error al conectar con ZAI"
}
```

---

## 💡 Mejores Prácticas

### 1. Siempre incluir userId y tier
```typescript
// ❌ Malo
POST /api/influencers
{ "targetNiche": "Fashion" }

// ✅ Bueno
POST /api/influencers
{ 
  "targetNiche": "Fashion",
  "userId": "user123",
  "tier": "premium"
}
```

### 2. Revisar creditsRemaining antes de siguiente acción
```typescript
if (response.creditsRemaining === 0) {
  showUpgradePrompt(); // Sugerir upgrade
}
```

### 3. Manejar erro 429 (sin créditos)
```typescript
if (error.status === 429) {
  showMessage("Límite mensual alcanzado. Intenta mañana o upgrade tu plan.");
}
```

---

## 📝 Notas Técnicas

- Los límites son **PERMANENTES** por el tier contratado (no se resetean mensualmente).
- El conteo incluye TODOS los recursos creados; para resetearse debe realizarse un cambio de tier o un reset manual pago.
- Si hay error en las APIs, se permite la acción (fallsafe seguro) para no bloquear al usuario por fallos externos.
- Los créditos se verifican ANTES de hacer la llamada (no gastas en errores).

---

## 🧾 Suscripciones por influencer

Cada cliente debe suscribirse individualmente a cada influencer con la que quiera interactuar en chat privado o contenido de pago. Las suscripciones son por influencer y por tier. Ejemplos:

- Usuario `user123` se suscribe a la influencer `Luna Style` con el tier `basic`.
- Si quiere interactuar también con `Ayla`, debe suscribirse por separado a `Ayla`.

### Endpoints

- Suscribirse:

```bash
curl -X POST http://localhost:7860/api/influencers/subscription \
  -H "Content-Type: application/json" \
  -d '{"userId":"user123","influencerId":"<influencer-id>","tier":"basic","price":9.99}'
```

- Listar suscripciones (por usuario o por influencer):

```bash
curl "http://localhost:7860/api/influencers/subscription?userId=user123"
curl "http://localhost:7860/api/influencers/subscription?influencerId=<influencer-id>"
```

- Cancelar/Anular suscripción:

```bash
curl -X DELETE "http://localhost:7860/api/influencers/subscription?id=<subscription-id>"
```

---

## 🎨 Qué Genera Automáticamente

### Influencer (POST /api/influencers)
- ✅ Nombre único
- ✅ Handle/Username
- ✅ Platform (Instagram/TikTok/YouTube)
- ✅ Follower count estimado
- ✅ Engagement rate
- ✅ Niche específico
- ✅ Estilo visual
- ✅ Tipos de contenido
- ✅ Schedule de posts
- ✅ Tipo de monetización
- ✅ ¿Mascota? + tipo

### Story (POST /api/storytelling)
- ✅ Título atractivo
- ✅ Sinopsis completa
- ✅ 3-10 episodios con contenido
- ✅ Metadata de análisis

### Imagen (POST /api/generate/image)
- ✅ Imagen 1024x1024 en base64
- ✅ Prompt optimizado
- ✅ Validación de censura por plataforma

---

## ⚡ Próximas Mejoras (Sin romper)

- [ ] Video generation con límites
- [ ] Dashboard de uso mensual
- [ ] Exportar influencers a CSV/JSON
- [ ] Integración con OnlyFans/Monetización
- [ ] Batch creation (crear 10 influencers de una vez)