Primera edición educativa · v0.1.0 · Solo Windows 10/11
Aplicación autohospedada, gratuita y educativa: lee tu bandeja de entrada de Gmail, usa IA para detectar oportunidades comerciales y las organiza en una hoja de Google Sheets. Todo se ejecuta en tu propio equipo, con tus propias credenciales.
Next.js · React · TypeScript · Supabase · OpenAI
Cedazo es una aplicación autohospedada que lee la bandeja de entrada de tu Gmail, usa IA (OpenAI) para decidir qué correos son oportunidades comerciales («leads») y los anota en una hoja de Google Sheets. Se ejecuta en tu propio equipo, con tu propia clave de OpenAI y tu propio proyecto de Google.
Es una edición educativa: está pensada para aprender de un proyecto real (Next.js, Supabase, OAuth de Google, cifrado de credenciales, trabajos por lotes reanudables, pruebas de aislamiento entre usuarios), para uso personal, educativo o no comercial, o para uso interno en tu propio negocio. No es un servicio alojado ni un producto comercial: es una edición educativa que funciona solo en local.
No hay servidor, base de datos ni cola alojados por el proyecto: todo lo que configures se guarda en tu equipo, y las credenciales se configuran dentro de la aplicación, nunca por variables de entorno.
Conectar tu cuenta de Google
Solo lectura de Gmail y acceso a la hoja que la propia aplicación crea o que tú indicas.
Definir el filtro
Dominios y palabras del asunto, hasta 30 días, solo INBOX, y cuántos mensajes revisar por escaneo.
Clasificar con OpenAI
Cada mensaje elegible se envía a OpenAI con tu clave para extraer nombre, correo, empresa y necesidad. Solo los que superan un umbral de confianza pasan a tu hoja.
Gestionar los leads
Archivar, restaurar y eliminar leads, con o sin vaciar sus celdas en la hoja. El correo eliminado no vuelve a importarse.
Dirigí, revisé y validé el desarrollo de Cedazo con apoyo de herramientas de inteligencia artificial.
Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4. Server Components y rutas /api, servida en 127.0.0.1.
La pila oficial de Supabase en local (Postgres + Auth), gestionada por el CLI de Supabase fijado en package.json. Las tablas propias viven en el esquema app; ningún objeto es accesible por la API de datos salvo mediante GRANT explícitos por objeto.
Gmail API (solo lectura), Google Sheets y Drive, a través de una única puerta: withGoogle(userId, tipo, fn).
OpenAI (Chat Completions con salida estructurada), con la clave de cada usuario.
Cifrado AES-256-GCM con un anillo de claves con versión, bajo APP_SECRETS_ENC_KEY.
Comandos selfhost:* (instalar, arrancar, parar, actualizar, migrar, restablecer); migraciones solo de adición.
Cada mensaje elegible se envía a OpenAI (Chat Completions con salida estructurada), con la clave de cada usuario, para extraer nombre, correo, empresa y necesidad. Solo los que superan un umbral de confianza pasan a la hoja.
El tamaño de escaneo por usuario limita las solicitudes a OpenAI reservadas; «todos» se pausa a 1.000 por hora. OpenAI cobra por el uso de tu clave; el proyecto recomienda fijar un límite de gasto en la cuenta de OpenAI antes de empezar y no puede garantizar un coste.
Un escaneo interrumpido justo después de que OpenAI responda puede clasificar ese mensaje otra vez al reanudar (acotado por las reservas).
Una sola puerta hacia Google
Todo acceso a Gmail/Sheets/Drive pasa por withGoogle(userId, tipo, fn), que entrega a la función una pasarela estrecha por tipo, nunca un cliente OAuth en bruto. Un chequeo estático (npm run check:boundary) rechaza cualquier otro módulo que importe googleapis.
Credenciales por ámbito, cifradas
El cliente OAuth de Google es una configuración única de la instalación que solo puede fijar un administrador (ciclo pendiente → activo → retirado; solo se activa tras un intercambio de código real y satisfactorio). La clave de OpenAI la configura y guarda cada usuario. Ambas se guardan cifradas.
Escaneos como trabajos reanudables
Un escaneo es un trabajo persistente que el navegador avanza lote a lote. El tamaño por usuario (10/25/50/100/todos) limita las solicitudes a OpenAI reservadas; «todos» se pausa a 1.000 por hora. Mientras el trabajo está abierto solo se guardan identificadores de mensaje.
Reintentos sin duplicar filas
Cada lead pasa por una máquina de estados con comparación e intercambio (pending → inflight → written | failed | ambiguous), de modo que un reintento tras un fallo de red no duplica filas en Sheets.
Borrado seguro en Google Sheets
«Eliminar y vaciar en Sheets» localiza la fila por identificador de mensaje, se detiene si hay 0 o más de 1 coincidencias, vacía solo las columnas mapeadas y lo verifica, todo dentro de una llamada a Google, con una máquina de estados duradera para recuperarse de caídas.
Mantener el filtro coherente
El filtro de Gmail se valida tanto en TypeScript como en SQL, y una prueba de paridad comprueba que ambas implementaciones aceptan y rechazan los mismos valores.
Puras · integración · e2e
tres niveles de pruebas
Pila aislada
integración y e2e contra una segunda pila de Supabase totalmente separada
check:boundary
chequeo estático que impide importar googleapis fuera de la puerta única
Las pruebas que borran datos nunca deben ejecutarse contra una instalación con datos reales: hay comprobaciones previas que se niegan a arrancar si la base contiene usuarios o credenciales reales. Los valores con forma de credencial que usan las pruebas se construyen en tiempo de ejecución, para que ningún escáner de secretos los confunda con reales.
Todo corre en un único equipo, el tuyo: no hay servidor, base de datos ni cola alojados por el proyecto. Las claves de OpenAI, el secreto del cliente de Google y los refresh tokens se guardan cifrados con AES-256-GCM bajo una clave que fijas tú; perderla hace ilegible lo guardado. El acceso a Gmail es de solo lectura y todo acceso a Google pasa por una única puerta con pasarelas estrechas por tipo. Maneja credenciales de Google y de OpenAI y contenido de correo: úsalo con criterio, en un equipo que controles, y lee SECURITY.md y PRIVACY.md. Nada de esto es una garantía absoluta de ausencia de errores.
Primera distribución de Cedazo: la edición educativa 0.1.0, solo para Windows 10/11. Incluye la instalación y operación local con un comando por tarea, la conexión con Google y OpenAI, el escaneo por lotes reanudables con filtro editable, la clasificación con IA y la escritura idempotente en Google Sheets, el ciclo de vida de los leads (archivar, restaurar, eliminar) y pruebas puras, de integración y e2e sobre una pila aislada. No incluye ninguna versión alojada, ni compatibilidad verificada con macOS o Linux, ni soporte garantizado, garantía o contribuciones externas.
Aplicación autohospedada, gratuita y educativa: lee tu bandeja de entrada de Gmail, usa IA para detectar oportunidades comerciales y las organiza en una hoja de Google Sheets. Todo se ejecuta en tu propio equipo, con tus propias credenciales.
Primera edición educativa · v0.1.0 · Solo Windows 10/11
Cedazo se distribuye como primera edición educativa, para aprender de un proyecto real y para uso personal, educativo, no comercial o interno en tu propio negocio. No hay versión alojada ni servicio gestionado, y por ahora no se aceptan contribuciones externas.
Reventa, SaaS, operarlo para clientes u otros usos que ninguna de las dos licencias cubra no se presentan como autorizados.