Ejemplos

Spraxium incluye un conjunto completo de aplicaciones reales y ejecutables en apps/. En 0.2.0, esos ejemplos están alineados con las APIs más recientes, incluyendo builders de componentes asíncronos, patrones modernos de interacción y una arquitectura orientada a producción.

Esta página te ayuda a elegir el punto de partida correcto según tu objetivo y luego te da un flujo práctico para ejecutar, inspeccionar y modificar ejemplos de forma segura.

Mapa de aplicaciones (0.2.0)

Actualmente Spraxium incluye 13 aplicaciones de ejemplo oficiales:

1. components-bot
2. context-menu-bot
3. dynamic-bot
4. guard-bot
5. http-bot
6. i18n-bot
7. i18n-components-bot
8. modal-bot
9. sandbox
10. schedule-bot
11. signal-bot
12. slash-bot
13. webhook-bot

upgrade-test-bot se eliminó intencionalmente y no forma parte del conjunto de aplicaciones de 0.2.0.

Qué enseña cada aplicación

1) slash-bot

Úsala primero si quieres el punto de entrada más limpio.

Aprenderás:

• Registro y ejecución básicos de slash commands.
• Organización de handlers/módulos con la mínima complejidad.
• Flujo base de comandos antes de agregar infraestructura avanzada.

2) context-menu-bot

Úsala si el flujo de tu bot parte de acciones de contexto de mensaje/usuario en lugar de slash commands.

Aprenderás:

• Comandos de menú contextual de usuario y mensaje.
• Patrones de defer y respuesta que evitan fallos por timeout.
• Composición de guards y servicios alrededor de handlers de interacción.

3) guard-bot

Úsala para entender control de acceso y capas de políticas.

Aprenderás:

• Composición de guards para roles, permisos y condiciones.
• Verificaciones de seguridad reutilizables a nivel de módulo/handler.
• Patrones para mantener la lógica de autorización fuera del código de negocio.

4) components-bot

Úsala cuando necesites botones/select menus con flujos más ricos.

Aprenderás:

• Uso de Component V2 con builders guiados por await.
• Flujos de interacción de múltiples pasos tipo UI.
• Mapeo de interacciones de componentes a handlers tipados.

5) dynamic-bot

Úsala cuando los datos de payload deban viajar dentro de interacciones de componentes.

Aprenderás:

• Estrategias de identidad/payload para componentes dinámicos.
• Manejo más seguro de interacciones con estado sin parsing frágil.
• Estructura amigable para migraciones en contratos de componentes evolutivos.

6) modal-bot

Úsala para recolección de entradas tipo formulario.

Aprenderás:

• Apertura de modales y handlers de envío.
• Validación y feedback de errores para campos enviados.
• Integración de la salida del modal en flujos de comandos.

7) i18n-bot

Úsala cuando la localización sea un requisito principal.

Aprenderás:

• Detección de locale y carga de traducciones.
• Composición de mensajes con utilidades sensibles al idioma.
• Estructuración de salida multilingüe de comandos.

8) i18n-components-bot

Úsala para combinar localización con flujos complejos de componentes.

Aprenderás:

• Labels y contenido localizados en árboles de componentes.
• Estados dinámicos de UI seguros por locale.
• Límites de traducción prácticos en UX con muchas interacciones.

9) http-bot

Úsala cuando tu bot de Discord también exponga endpoints HTTP.

Aprenderás:

• Ejecución conjunta del runtime del bot y del runtime HTTP.
• Organización de endpoints de API alrededor de servicios/módulos.
• Patrones básicos de middleware usados por el framework.

10) webhook-bot

Úsala cuando eventos externos deban disparar acciones en Discord.

Aprenderás:

• Recepción y validación de requests de webhook.
• Enrutamiento de eventos de webhook a los handlers correctos.
• Patrones de confiabilidad y estrategia de errores explícita.

11) signal-bot

Úsala para patrones de comunicación dirigidos por eventos.

Aprenderás:

• Publicación y consumo de señales/eventos.
• Desacople entre productores y consumidores.
• Arquitectura de comunicación interna escalable.

12) schedule-bot

Úsala para automatización recurrente.

Aprenderás:

• Tareas programadas y flujo de ejecución tipo cron.
• Límites de programación seguros para operaciones de Discord.
• Organización de lógica de jobs con observabilidad en mente.

13) sandbox

Úsala como tu laboratorio de integración.

Aprenderás:

• Patrones mixtos de muchas funcionalidades del framework.
• Demos de excepciones y manejo de casos límite.
• Cómo prototipar rápido antes de extraer módulos de producción.

Rutas de aprendizaje recomendadas

Elige una ruta y síguela de forma secuencial para comprender más rápido.

Ruta A: fundamentos de comandos

1. slash-bot
2. context-menu-bot
3. guard-bot

Ruta B: UX intensiva en interacciones

1. components-bot
2. dynamic-bot
3. modal-bot
4. i18n-components-bot

Ruta C: arquitectura de backend/integración

1. http-bot
2. webhook-bot
3. signal-bot
4. schedule-bot
5. sandbox

Ruta D: productos centrados en localización

1. i18n-bot
2. i18n-components-bot
3. sandbox

Cómo ejecutar un ejemplo

Desde la raíz del workspace:

pnpm install
pnpm --filter @spraxium/slash-bot build
pnpm --filter @spraxium/slash-bot start

Sustituye @spraxium/slash-bot por el paquete de la aplicación que quieras ejecutar.

Flujo práctico para estudiar ejemplos

Usa este ciclo al analizar cualquier aplicación:

1. Lee spraxium.config.ts para entender el wiring de módulos y hooks de runtime.
2. Lee primero los handlers en src/, luego servicios/providers.
3. Ejecuta un comando/interacción de extremo a extremo e inspecciona logs.
4. Modifica un comportamiento y vuelve a ejecutar de inmediato.
5. Conserva experimentos exitosos y descarta rápido los experimentos ruidosos.

Esto mantiene tu aprendizaje enfocado en rutas de ejecución, no solo en lectura estática de código.

Notas de migración 0.2.0 para lectores de ejemplos

Si usaste revisiones antiguas de los ejemplos, ten en cuenta estos puntos:

1. Los ejemplos de Component V2 ahora enfatizan el uso de builders asíncronos.
2. Los flujos de componentes dinámicos se modernizaron para coincidir con los patrones actuales de payload.
3. Los ejemplos HTTP/webhook están alineados con las interfaces más recientes de los paquetes.
4. Los manifiestos de aplicaciones se normalizaron para consistencia de dependencias en el workspace.

Construir tu propia aplicación desde un ejemplo

Un enfoque seguro orientado a producción:

1. Elige el ejemplo más cercano por comportamiento, no por tamaño.
2. Copia solo módulos que puedas explicar línea por línea.
3. Sustituye primero variables de entorno y secretos.
4. Agrega guards, logging y manejo de errores antes de agregar funcionalidades.
5. Agrega tests alrededor de tu primer comando crítico o flujo de interacción.

Los ejemplos están pensados como referencias de arquitectura, no como plantillas de producción listas para usar.