Huso

Agenda pública y gestión de citas para freelancers, coaches y equipos chicos.

Tu agenda, sin fricción.

Huso es una herramienta open source de scheduling en etapa MVP. Cada usuario obtiene una página pública (/u/tu-usuario) donde sus clientes pueden reservar un horario según los tipos de evento y la disponibilidad configurada. No hace falta crear una cuenta para reservar y las fechas se muestran correctamente en la zona horaria de cada persona.

Funcionalidades

• Página pública de reservas para cada usuario.
• Registro, inicio de sesión y magic link con Supabase Auth.
• Tipos de evento con duración, slug, modalidad y buffers configurables.
• Disponibilidad semanal y bloqueos de fechas puntuales.
• Selector de zona horaria para quien reserva.
• Protección contra doble reserva mediante una restricción de base de datos.
• Emails transaccionales de confirmación y cancelación con Resend.
• Dashboard para gestionar citas, eventos, disponibilidad y perfil.
• Modo claro/oscuro y una interfaz responsive.
• Row Level Security (RLS) para que cada usuario solo pueda administrar sus propios datos.

Estado del proyecto

El proyecto está en desarrollo y actualmente cubre el alcance del MVP. Las funcionalidades previstas para después del MVP están documentadas en el roadmap.

Stack

• Next.js 16 con App Router, Server Actions y TypeScript.
• React 19.
• Tailwind CSS.
• Supabase para autenticación, PostgreSQL, RLS y Storage.
• Resend y React Email para los emails transaccionales.
• Zod para validación.
• date-fns y date-fns-tz para fechas y zonas horarias.
• Radix UI, Framer Motion, Sonner y Lucide React para la interfaz.

Requisitos

• Node.js 18.18 o superior.
• npm.
• Un proyecto de Supabase.
• Una cuenta de Resend para enviar emails. Es opcional durante el desarrollo, pero necesaria para probar el flujo completo de notificaciones.

Instalación local

1. Clonar e instalar dependencias

git clone <URL_DEL_REPOSITORIO>
cd huso
npm install

2. Configurar Supabase

Creá un proyecto en Supabase o iniciá uno local con Docker y la Supabase CLI:

npx supabase init
npx supabase start

Aplicá las migraciones versionadas:

npx supabase db push

Si usás Supabase Cloud, también podés ejecutar los archivos de supabase/migrations/ en el SQL Editor, en orden.

3. Configurar las variables de entorno

Copiá el archivo de ejemplo:

cp .env.example .env.local

Después completá .env.local con los valores de tu proyecto:

Variable	Descripción
NEXT_PUBLIC_SUPABASE_URL	URL del proyecto en Supabase.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Publishable key pública de Supabase.
SUPABASE_SECRET_KEY	Secret key privada de Supabase; solo se usa en el servidor.
RESEND_API_KEY	API key de Resend.
RESEND_FROM_EMAIL	Remitente verificado, por ejemplo Huso <notificaciones@tudominio.com>.
NEXT_PUBLIC_APP_URL	URL de la aplicación, por ejemplo http://localhost:3000.

Las variables antiguas NEXT_PUBLIC_SUPABASE_ANON_KEY y SUPABASE_SERVICE_ROLE_KEY también son compatibles. Nunca expongas la secret key o la service role key al navegador ni la subas al repositorio.

Para probar emails sin un dominio propio podés usar:

RESEND_FROM_EMAIL="Huso <onboarding@resend.dev>"

4. Ejecutar la aplicación

npm run dev

Abrí http://localhost:3000.

Datos de demostración

El seed crea un usuario demo con dos tipos de evento y disponibilidad de lunes a viernes:

npm run seed

Luego podés probar la agenda pública en http://localhost:3000/u/demo.

Credenciales del usuario demo:

Email: demo@huso.app
Contraseña: HusoDemo123!

El seed requiere que .env.local tenga configurada la secret key de Supabase.

Scripts disponibles

Comando	Uso
npm run dev	Inicia el servidor de desarrollo.
npm run build	Genera el build de producción.
npm run start	Sirve el build de producción.
npm run lint	Ejecuta ESLint.
npm run typecheck	Verifica los tipos con TypeScript.
npm run format	Formatea el proyecto con Prettier.
npm run seed	Carga datos de demostración.
npm run email:dev	Abre el preview de emails en el puerto 3010.

Estructura principal

app/                  Rutas y layouts de Next.js.
  (auth)/             Login y registro.
  dashboard/          Área protegida del host.
  onboarding/         Configuración inicial del perfil.
  u/[username]/       Página pública y flujo de reservas.
components/           Componentes de UI, dashboard y marketing.
emails/               Templates de React Email.
lib/                  Lógica de negocio, validaciones y clientes de Supabase.
scripts/              Scripts auxiliares, incluido el seed.
supabase/migrations/  Esquema y migraciones SQL versionadas.
types/                Tipos de base de datos y dominio.

Arquitectura y seguridad

Las tablas de negocio usan RLS con acceso exclusivo para el propietario. La agenda pública y la creación de reservas se ejecutan en el servidor mediante lib/supabase/admin.ts, protegido con server-only, para no depender de la sesión del visitante.

La base de datos también incluye una restricción EXCLUDE que evita reservas duplicadas en condiciones de carrera. La secret key de Supabase nunca debe importarse desde un Client Component.

Documentación

• Marca y dirección visual
• Especificación de assets
• Checklist de QA
• Roadmap post-MVP

Contribuir

Las contribuciones son bienvenidas. Antes de abrir un pull request:

npm run lint
npm run typecheck
npm run build

Para validar cambios de interfaz o del flujo de reservas, seguí también el checklist de QA.

Licencia

La licencia del proyecto todavía no está definida. Agregá un archivo LICENSE antes de distribuirlo formalmente como software open source.