# DataForge Lead API — Multi-Tenant Lead Capture

## Identificación del Proyecto

| Campo              | Valor                                                  |
|--------------------|--------------------------------------------------------|
| **ID**             | PROJ-W03                                               |
| **Nombre**         | DataForge Lead API — Multi-Tenant Lead Capture         |
| **Tipo**           | SaaS — Lead Capture API multi-tenant                   |
| **Worker CF**      | `broad-bonus-2baf`                                     |
| **Dominio**        | Por configurar (ej: leads.vulnerafix.com)              |
| **Responsable**    | Daniel (dev) · Cloudflare (infra) · Marketing (GTM)   |
| **Fecha registro** | 2026-03-10                                             |
| **Estado**         | ✅ PRODUCCIÓN — 100% OPERATIVO                         |
| **Prioridad**      | ALTA                                                   |

---

## Descripción

API de captura de leads multi-tenant construida sobre Cloudflare Workers + D1 + KV. Permite a múltiples clientes (tenants) recibir eventos de lead desde sus propias fuentes, con autenticación por API key, rate limiting, deduplicación automática y notificaciones Telegram configurables por cliente.

### Propuesta de valor
- Multi-tenancy real: cada cliente tiene su API key, plan, y configuración de notificaciones
- Rate limiting automático (ventana deslizante KV): 60 req/min por cliente
- Deduplicación de eventos por fingerprint SHA-256: ventana de 10 minutos
- Notificaciones Telegram por cliente: configurable individualmente (bot_token + chat_id)
- Infraestructura serverless: Cloudflare Workers + D1 + KV — costo operativo mínimo

---

## Arquitectura

```
Cliente externo (Form / App)
    → POST /api/ingest (Bearer {api_key})
        → CF Worker (broad-bonus-2baf)
            → KV: validar API key + plan + rate limit
            → KV: deduplicación SHA-256 (10 min TTL)
            → D1: INSERT evento en tabla events
            → KV: leer bot_token + chat_id del tenant
                → Telegram API: notificación formateada
            ← 200 OK / 429 Too Many Requests / 409 Duplicate
```

### Stack Tecnológico

| Capa              | Tecnología            | Estado         |
|-------------------|-----------------------|----------------|
| Runtime           | Cloudflare Workers    | Desplegado     |
| Base de datos     | Cloudflare D1 (SQL)   | Schema migrado |
| Caché / Auth      | Cloudflare KV         | Binding FALTA  |
| Notificaciones    | Telegram Bot API      | Implementado   |
| Billing           | Planes por tier       | Diseñado       |

---

## Endpoints

### Endpoints Públicos

| Endpoint         | Método | Auth              | Descripción                          |
|------------------|--------|-------------------|--------------------------------------|
| `/api/ingest`    | POST   | Bearer {api_key}  | Ingestar evento de lead              |
| `/api/events`    | GET    | Bearer {api_key}  | Listar eventos del cliente           |

### Endpoints Admin

| Endpoint                | Método | Auth                | Descripción                        |
|-------------------------|--------|---------------------|------------------------------------|
| `/admin/create-client`  | POST   | Bearer {ADMIN_TOKEN}| Crear nuevo cliente/tenant         |
| `/admin/set-telegram`   | POST   | Bearer {ADMIN_TOKEN}| Configurar Telegram por cliente    |

---

## Funcionalidades implementadas en código

- **Autenticación por API key por cliente:** header `Authorization: Bearer {key}`, validada contra KV
- **Rate limiting:** 60 req/min por cliente, ventana deslizante gestionada en KV
- **Deduplicación de eventos:** fingerprint SHA-256 del payload, TTL de 10 minutos en KV
- **Notificaciones Telegram:** configurable por cliente via `bot_token` + `chat_id` almacenados en KV
- **Multi-tenant con planes:** lógica de planes `starter` / `pro` / `business` en código
- **Formato de leads para Telegram:** nombre, teléfono, fuente, mensaje

---

## Modelo de Monetización

| Plan      | Precio    | Eventos/mes | Características                             |
|-----------|-----------|-------------|---------------------------------------------|
| Starter   | $0        | 1,000       | Ingest básico, notificaciones Telegram      |
| Pro       | $29/mes   | Ilimitado   | Rate limit elevado, deduplicación, `/events`|
| Business  | $79/mes   | Ilimitado   | Multi-source, soporte prioritario, SLA      |

---

## Bindings de Cloudflare (estado actual)

| Binding       | Tipo   | Nombre en código | Recurso CF                              | UUID / ID                              | Estado       |
|---------------|--------|------------------|-----------------------------------------|----------------------------------------|--------------|
| D1 Database   | D1     | `DB`             | `schema`                                | `321ad1f8-0e96-4f97-a316-f01b1753adb0` | FALTA        |
| KV Namespace  | KV     | `DF_KV`          | `worker`                                | `539f154969744094a0b69eb0efa52157`     | FALTA        |
| Secret        | Secret | `ADMIN_TOKEN`    | (valor a configurar)                    | —                                      | FALTA        |

**PROBLEMA CRITICO:** El Worker `broad-bonus-2baf` no tiene NINGUN binding configurado actualmente. El código falla en runtime al intentar acceder a `env.DB`, `env.DF_KV` o `env.ADMIN_TOKEN`.

---

## Base de datos D1

**Database:** `schema` — UUID: `321ad1f8-0e96-4f97-a316-f01b1753adb0`

| Tabla     | Descripción                              | Estado          |
|-----------|------------------------------------------|-----------------|
| `clients` | Tenants registrados, planes, API keys    | Schema migrado  |
| `events`  | Eventos de lead ingresados               | Schema migrado  |

Schema migrado el: **2026-03-10**

---

## Estado por fases (Closer)

### Fase 1 — Core API (COMPLETADA — 70%)
- [x] Autenticación por API key multi-tenant
- [x] Rate limiting (ventana KV)
- [x] Deduplicación SHA-256
- [x] Notificaciones Telegram por cliente
- [x] Endpoints `/api/ingest` y `/api/events`
- [x] Endpoints admin `/admin/create-client` y `/admin/set-telegram`
- [x] Schema D1 migrado (clients + events)

### Fase 2 — Configuración de Bindings (BLOQUEANTE)
- [ ] **[Cloudflare]** Agregar binding D1 `DB` → database `schema` en CF Dashboard
- [ ] **[Cloudflare]** Agregar binding KV `DF_KV` → namespace `worker` en CF Dashboard
- [ ] **[Cloudflare]** Agregar Secret `ADMIN_TOKEN` → valor secreto en CF Dashboard
- [ ] Verificar que Worker responde sin errores tras bindings

### Fase 3 — Activación operativa
- [ ] **[Cloudflare]** Configurar route/dominio (ej: leads.vulnerafix.com)
- [ ] **[Daniel]** Crear primer cliente via `/admin/create-client`
- [ ] Prueba end-to-end: ingest → D1 → Telegram

### Fase 4 — GTM y Comercialización
- [ ] **[Marketing]** Landing page con pricing (Starter / Pro / Business)
- [ ] **[Daniel]** Documentación de API (OpenAPI / Swagger)
- [ ] **[Marketing]** Campaña de lanzamiento

---

## Condición real / Observaciones

| Área               | Condición                                                      |
|--------------------|----------------------------------------------------------------|
| Código Worker      | Implementado al 70%, funcional en lógica                      |
| Bindings CF        | NINGUNO configurado — causa error en runtime                  |
| D1 Schema          | Migrado correctamente (clients + events)                      |
| KV Namespace       | Creado, pero sin binding al Worker                            |
| Dominio/Route      | No configurado aún                                            |
| Primer cliente     | No creado — depende de bindings activos                       |
| Documentación API  | Pendiente (OpenAPI/Swagger)                                   |
| Landing/Marketing  | Pendiente                                                     |

---

## Agentes responsables

| Agente     | Responsabilidad sobre este proyecto                          |
|------------|--------------------------------------------------------------|
| Daniel     | Código Worker, schema D1, pruebas, documentación API        |
| Cloudflare | Bindings (D1, KV, Secret), route, dominio                   |
| Marketing  | Landing page, pricing copy, GTM, campaña de lanzamiento     |

---

## Acciones pendientes (próximos pasos)

- [ ] **[Cloudflare]** CF Dashboard → Workers → `broad-bonus-2baf` → Settings → Bindings → agregar `DB` (D1: `321ad1f8...`)
- [ ] **[Cloudflare]** CF Dashboard → Workers → `broad-bonus-2baf` → Settings → Bindings → agregar `DF_KV` (KV: `539f1549...`)
- [ ] **[Cloudflare]** CF Dashboard → Workers → `broad-bonus-2baf` → Settings → Variables → agregar Secret `ADMIN_TOKEN`
- [ ] **[Cloudflare]** Configurar route o dominio personalizado para el Worker
- [ ] **[Daniel]** Crear primer tenant via `POST /admin/create-client` tras activar bindings
- [ ] **[Daniel]** Documentar API en OpenAPI/Swagger
- [ ] **[Marketing]** Diseñar y publicar landing page con pricing

---

## Links de referencia

- Worker CF: `broad-bonus-2baf` — https://dash.cloudflare.com/
- D1 database `schema` UUID: `321ad1f8-0e96-4f97-a316-f01b1753adb0`
- KV namespace `worker` ID: `539f154969744094a0b69eb0efa52157`
- Cloudflare Workers Docs: https://developers.cloudflare.com/workers/
- D1 Docs: https://developers.cloudflare.com/d1/
- KV Docs: https://developers.cloudflare.com/kv/