🛒 SuperBot — Bot de compras familiar por WhatsApp

Tu familia manda mensajes por WhatsApp y el bot arma la lista de compras, busca los productos en Carrefour y te arma el carrito listo para pagar.

Bot de WhatsApp con IA que gestiona la lista de compras compartida de una familia. Cada miembro habla por chat privado con el bot, y todos comparten la misma lista. Integra búsqueda de productos en Carrefour (VTEX API) y armado automático de carrito.

---

Cómo funciona

👨 Papá: "Poneme 2kg de asado"          →  ✅ Agregado: 🥩 asado x2 kg
👩 Mamá: "Sacá la leche y poné yogur"   →  ✅ Hecho
👦 Hijo: "Quiero hacer milanesas para 6" →  🍗 Receta: pollo, pan rallado, huevos...
👨 Papá: "Armá el carrito"              →  🛒 Carrito armado en Carrefour: $45.230

Características principales

• Lista compartida por WhatsApp — cada miembro agrega/saca items desde su chat privado
• IA conversacional — entiende lenguaje natural en argentino ("poneme", "sacá", "falta", "metele")
• Recetas con IA — pedís una receta y te genera la lista de ingredientes lista para agregar
• Recetas desde URLs — mandás un link de Instagram/TikTok y extrae los ingredientes
• Planificación semanal — genera un menú de 7 días y la lista de compras consolidada
• Audios de WhatsApp — transcribe audios con Whisper y los procesa como texto
• Búsqueda en Carrefour — busca productos reales vía VTEX Intelligent Search API
• Armado de carrito — arma el carrito en Carrefour con los SKUs reales, listo para pagar
• Normalización inteligente — "50g de harina" en una receta → "harina x1 kg" en la lista de compras
• Preferencias de marca — "mayonesa siempre Natura" y el bot lo recuerda
• Notificaciones — avisa a los otros miembros cuando alguien modifica la lista
• Historial de gastos — registro de compras realizadas

Tech Stack

Componente	Tecnología
Runtime	Node.js + Express
IA / NLP	OpenRouter (Gemini Flash)
Audio	Groq (Whisper) + ffmpeg
Base de datos	SQLite (better-sqlite3)
WhatsApp	Kapso API (Meta WhatsApp Business)
E-commerce	VTEX API (Carrefour Argentina)
Deploy	Render / Docker

Arquitectura

WhatsApp (Kapso)
    ↓ webhook
Express Server
    ↓
Intent Router ← LLM (OpenRouter/Gemini)
    ↓
┌─────────────┬──────────────┬───────────────┬──────────────┐
│ List Manager│ Recipe Gen   │ VTEX Search   │ Meal Planner │
│ (CRUD)      │ (IA)         │ (Carrefour)   │ (IA)         │
└──────┬──────┴──────┬───────┴───────┬───────┴──────┬───────┘
       │             │               │              │
       └─────────────┴───────┬───────┴──────────────┘
                             ↓
                    SQLite (listas, miembros,
                    preferencias, historial)

Estructura del proyecto

src/
├── index.js                 # Entry point (server o CLI)
├── cli.js                   # Modo CLI para testing local
├── ai/
│   ├── llm.js               # Clasificación de intenciones + recetas con IA
│   └── transcriber.js       # Transcripción de audio (Groq/Whisper)
├── db/
│   ├── database.js          # Capa de datos (SQLite)
│   └── schema.sql           # Schema de la base de datos
├── list/
│   ├── listManager.js       # CRUD de la lista de compras
│   └── shopNormalizer.js     # Normalización de cantidades y packaging
├── notifications/
│   └── notifier.js           # Notificaciones a miembros
├── preferences/
│   └── preferencesManager.js # Preferencias de marca
├── router/
│   └── intentRouter.js       # Router de intenciones (orchestrator)
├── server/
│   ├── webhook.js            # Webhook de WhatsApp
│   ├── health.js             # Health check
│   └── cartLoader.js         # Página de carga de carrito
├── utils/
│   └── urlExtractor.js       # Extractor de contenido de URLs
├── vtex/
│   ├── auth.js               # Autenticación VTEX
│   ├── search.js             # Búsqueda de productos
│   ├── cart.js               # Armado de carrito
│   └── skuMatcher.js         # Matching de items → SKUs reales
└── whatsapp/
    ├── handler.js            # Handler principal de mensajes
    └── sender.js             # Envío de mensajes + media download

Instalación

Requisitos

• Node.js 20+
• ffmpeg (para procesar audios/videos)
• Cuentas en: Kapso (WhatsApp API), OpenRouter (IA), Groq (audio)

Setup

git clone https://github.com/maximovieyra/compras_bot.git
cd compras_bot
npm install

# Configurar credenciales
cp _env.example .env
# Editar .env con tus API keys

# Modo CLI (testing sin WhatsApp)
npm run cli

# Servidor (producción)
npm start

Variables de entorno

# WhatsApp (Kapso)
KAPSO_API_KEY=
KAPSO_PHONE_NUMBER_ID=
META_APP_SECRET=

# IA
OPENROUTER_API_KEY=
LLM_MODEL=google/gemini-2.0-flash-001

# Audio
GROQ_API_KEY=

# Familia
ADMIN_PHONE=5492211234567
ALLOWED_PHONES=5492211234567,5492219876543

Comandos del bot

Comando	Ejemplo
Agregar items	"Poneme leche y pan"
Sacar items	"Sacá la leche"
Ver lista	"¿Qué hay?"
Receta	"Quiero hacer milanesas para 6"
Receta desde URL	(mandar link de Instagram/TikTok)
Menú semanal	"Planificá la semana para 4"
Buscar producto	"Buscá queso cremoso"
Armar carrito	"Armá el carrito"
Preferencia de marca	"Mayonesa siempre Natura"
Audios	(mandar audio y lo transcribe)

Autor

Maxi Vieyra — Estudiante de Ingeniería en Inteligencia Artificial @ Universidad de Palermo

---