@battle-racing/br-common-lib 4.4.0 → 4.6.0

package/dist/domains/session/Session.schema.d.ts

@@ -118,6 +118,8 @@ export declare const gameSessionWithPlayersSchema: z.ZodObject<{
     }, z.core.$strip>>;
     turns: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        turnNumber: z.ZodNumber;
+        groupName: z.ZodOptional<z.ZodString>;
         purchaseId: z.ZodString;
         sessionId: z.ZodOptional<z.ZodString>;
         leaderPlayerId: z.ZodString;
@@ -166,6 +168,9 @@ export declare const joinSessionSchema: z.ZodObject<{
     nickname: z.ZodString;
     birthDate: z.ZodCoercedDate<unknown>;
 }, z.core.$strip>;
+export declare const addExistingPlayersSchema: z.ZodObject<{
+    playerIds: z.ZodArray<z.ZodUUID>;
+}, z.core.$strip>;
 export declare const updateSessionStatusSchema: z.ZodObject<{
     status: z.ZodEnum<{
         readonly REGISTRATION: "REGISTRATION";

package/dist/domains/session/Session.schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bulkCreateGameTurnSchema = exports.assignSessionTicketsInputSchema = exports.createGameTurnInputSchema = exports.updateSessionStatusSchema = exports.joinSessionSchema = exports.createSessionInputSchema = exports.gameSessionWithPlayersSchema = exports.gameSessionSchema = exports.sessionTicketSchema = exports.sessionStatusSchema = void 0;
+exports.bulkCreateGameTurnSchema = exports.assignSessionTicketsInputSchema = exports.createGameTurnInputSchema = exports.updateSessionStatusSchema = exports.addExistingPlayersSchema = exports.joinSessionSchema = exports.createSessionInputSchema = exports.gameSessionWithPlayersSchema = exports.gameSessionSchema = exports.sessionTicketSchema = exports.sessionStatusSchema = void 0;
 const zod_1 = require("zod");
 const Session_const_1 = require("./Session.const");
 const Game_schema_1 = require("../game/Game.schema");
@@ -36,6 +36,9 @@ exports.joinSessionSchema = zod_1.z.object({
     nickname: zod_1.z.string().min(2),
     birthDate: zod_1.z.coerce.date(),
 });
+exports.addExistingPlayersSchema = zod_1.z.object({
+    playerIds: zod_1.z.array(zod_1.z.uuidv4()).min(1),
+});
 exports.updateSessionStatusSchema = zod_1.z.object({
     status: exports.sessionStatusSchema,
 });

package/dist/domains/socket/index.d.ts

@@ -5,3 +5,4 @@ export * from './SocketHardwareModulesEventsParams';
 export * from './SocketHardwareOnDataEventsParams';
 export * from './SocketPowerUpEventsParams';
 export * from './utils';
+export * from './screen';

package/dist/domains/socket/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./SocketHardwareModulesEventsParams"), exports);
 __exportStar(require("./SocketHardwareOnDataEventsParams"), exports);
 __exportStar(require("./SocketPowerUpEventsParams"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./screen"), exports);

package/dist/domains/socket/screen/SocketScreenServerToClientEventsParams.d.ts

@@ -0,0 +1,14 @@
+import type { ScreenCountdownParams, ScreenDebugViewInput, ScreenFinishViewInput, ScreenHomeViewInput, ScreenUpdateGameViewInput } from '../../hardware';
+/**
+ * Socket events from Raspberry Pi to Screen
+ */
+export interface SocketScreenServerToClientEventsParams {
+    'view:home': ScreenHomeViewInput;
+    'view:countdown': ScreenCountdownParams;
+    'game:sync_state': ScreenUpdateGameViewInput;
+    'view:summary': ScreenFinishViewInput & {
+        state: 'Victory' | 'Defeat';
+    };
+    'view:debug': ScreenDebugViewInput;
+    'view:instruction_video': Record<string, never>;
+}

package/dist/domains/socket/screen/SocketScreenServerToClientEventsParams.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domains/socket/screen/index.d.ts

@@ -0,0 +1 @@
+export * from './SocketScreenServerToClientEventsParams';

package/dist/domains/socket/screen/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./SocketScreenServerToClientEventsParams"), exports);

package/dist/domains/ticketing/Ticketing.schema.d.ts

@@ -136,6 +136,8 @@ export declare const gameTurnTaskSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const gameTurnSchema: z.ZodObject<{
     id: z.ZodString;
+    turnNumber: z.ZodNumber;
+    groupName: z.ZodOptional<z.ZodString>;
     purchaseId: z.ZodString;
     sessionId: z.ZodOptional<z.ZodString>;
     leaderPlayerId: z.ZodString;
@@ -170,6 +172,8 @@ export declare const gameTurnSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const gameTurnQueueItemSchema: z.ZodObject<{
     id: z.ZodString;
+    turnNumber: z.ZodNumber;
+    groupName: z.ZodOptional<z.ZodString>;
     purchaseId: z.ZodString;
     sessionId: z.ZodOptional<z.ZodString>;
     leaderPlayerId: z.ZodString;

package/dist/domains/ticketing/Ticketing.schema.js

@@ -63,6 +63,8 @@ exports.gameTurnTaskSchema = zod_1.z.object({
 });
 exports.gameTurnSchema = zod_1.z.object({
     id: zod_1.z.string(),
+    turnNumber: zod_1.z.number().int().positive(),
+    groupName: zod_1.z.string().optional(),
     purchaseId: zod_1.z.string(),
     sessionId: zod_1.z.string().optional(),
     leaderPlayerId: zod_1.z.string(),

package/dist/domains/user/User.schema.d.ts

@@ -4,12 +4,13 @@ export declare const userTypeSchema: z.ZodEnum<{
     readonly PLAYER: "PLAYER";
 }>;
 export declare const PHONE_REGEX: RegExp;
+export declare const emailOrPhoneSchema: z.ZodString;
 export declare const userSchema: z.ZodObject<{
     id: z.ZodUUID;
     name: z.ZodString;
     lastName: z.ZodString;
-    email: z.ZodOptional<z.ZodEmail>;
-    phoneNumber: z.ZodOptional<z.ZodString>;
+    email: z.ZodNullable<z.ZodOptional<z.ZodEmail>>;
+    phoneNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     role: z.ZodEnum<{
         readonly SUPER_ADMIN: "SUPER_ADMIN";
         readonly OPERATOR: "OPERATOR";
@@ -27,12 +28,54 @@ export declare const userSchema: z.ZodObject<{
     createdAt: z.ZodDate;
     lastLoginAt: z.ZodOptional<z.ZodDate>;
 }, z.core.$strip>;
+/**
+ * When a user registers, we don't have all the information, so we use this schema
+ */
+export declare const initialUserSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        readonly STAFF: "STAFF";
+        readonly PLAYER: "PLAYER";
+    }>;
+    id: z.ZodUUID;
+    createdAt: z.ZodDate;
+    email: z.ZodNullable<z.ZodOptional<z.ZodEmail>>;
+    phoneNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    isEmailVerified: z.ZodDefault<z.ZodBoolean>;
+    isPhoneVerified: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * The schema for the user returned on login
+ */
+export declare const authUserSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodString;
+    lastName: z.ZodString;
+    email: z.ZodNullable<z.ZodOptional<z.ZodEmail>>;
+    phoneNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    role: z.ZodEnum<{
+        readonly SUPER_ADMIN: "SUPER_ADMIN";
+        readonly OPERATOR: "OPERATOR";
+        readonly PLAYER: "PLAYER";
+        readonly CASHIER: "CASHIER";
+    }>;
+    type: z.ZodEnum<{
+        readonly STAFF: "STAFF";
+        readonly PLAYER: "PLAYER";
+    }>;
+    isActive: z.ZodDefault<z.ZodBoolean>;
+    isEmailVerified: z.ZodDefault<z.ZodBoolean>;
+    isPhoneVerified: z.ZodDefault<z.ZodBoolean>;
+    defaultPlayerId: z.ZodOptional<z.ZodUUID>;
+    createdAt: z.ZodDate;
+    lastLoginAt: z.ZodOptional<z.ZodDate>;
+    authToken: z.ZodString;
+}, z.core.$strip>;
 export declare const userWithPasswordSchema: z.ZodIntersection<z.ZodObject<{
     id: z.ZodUUID;
     name: z.ZodString;
     lastName: z.ZodString;
-    email: z.ZodOptional<z.ZodEmail>;
-    phoneNumber: z.ZodOptional<z.ZodString>;
+    email: z.ZodNullable<z.ZodOptional<z.ZodEmail>>;
+    phoneNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     role: z.ZodEnum<{
         readonly SUPER_ADMIN: "SUPER_ADMIN";
         readonly OPERATOR: "OPERATOR";
@@ -52,11 +95,27 @@ export declare const userWithPasswordSchema: z.ZodIntersection<z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     password: z.ZodString;
 }, z.core.$strip>>;
+export declare const userInitialRegistrationSchema: z.ZodObject<{
+    emailOrPhone: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+export declare const userVerifySchema: z.ZodObject<{
+    emailOrPhone: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strip>;
+export declare const userCompleteProfileSchema: z.ZodObject<{
+    name: z.ZodString;
+    lastName: z.ZodOptional<z.ZodString>;
+    nickname: z.ZodString;
+    birthDate: z.ZodCoercedDate<unknown>;
+    waiverSignature: z.ZodBoolean;
+    teamName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const userRegistrationInputSchema: z.ZodObject<{
     name: z.ZodString;
+    email: z.ZodNullable<z.ZodOptional<z.ZodEmail>>;
     lastName: z.ZodString;
-    email: z.ZodOptional<z.ZodEmail>;
-    phoneNumber: z.ZodOptional<z.ZodString>;
+    phoneNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     password: z.ZodString;
     nickname: z.ZodString;
     birthDate: z.ZodCoercedDate<unknown>;

package/dist/domains/user/User.schema.js

@@ -1,18 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.userLoginInputSchema = exports.userRegistrationInputSchema = exports.userWithPasswordSchema = exports.userSchema = exports.PHONE_REGEX = exports.userTypeSchema = void 0;
+exports.userLoginInputSchema = exports.userRegistrationInputSchema = exports.userCompleteProfileSchema = exports.userVerifySchema = exports.userInitialRegistrationSchema = exports.userWithPasswordSchema = exports.authUserSchema = exports.initialUserSchema = exports.userSchema = exports.emailOrPhoneSchema = exports.PHONE_REGEX = exports.userTypeSchema = void 0;
 const zod_1 = require("zod");
 const role_1 = require("../role");
 const User_const_1 = require("./User.const");
 exports.userTypeSchema = zod_1.z.enum(User_const_1.USER_TYPE);
 exports.PHONE_REGEX = /^([+]?[\\s0-9]+)?(\\d{3}|[(]?[0-9]+[)])?([-]?[\\s]?[0-9])+$/;
 const MIN_PASSWORD_LENGTH = 6;
+exports.emailOrPhoneSchema = zod_1.z
+    .string()
+    .min(1, 'Email or phone is required')
+    .refine((val) => {
+    const isEmail = zod_1.z.email().safeParse(val).success;
+    const isPhone = exports.PHONE_REGEX.test(val);
+    return isEmail || isPhone;
+}, { message: 'Must be a valid email or phone number' });
 const baseUserObj = zod_1.z.object({
     id: zod_1.z.uuidv4(),
     name: zod_1.z.string(),
     lastName: zod_1.z.string(),
-    email: zod_1.z.email().toLowerCase().optional(),
-    phoneNumber: zod_1.z.string().regex(exports.PHONE_REGEX, 'Invalid phone number format').optional(),
+    email: zod_1.z.email().toLowerCase().optional().nullable(),
+    phoneNumber: zod_1.z.string().regex(exports.PHONE_REGEX, 'Invalid phone number format').optional().nullable(),
     // --- ACCESS CONTROL ---
     role: role_1.userRoleSchema,
     type: exports.userTypeSchema,
@@ -28,9 +36,49 @@ exports.userSchema = baseUserObj.refine((data) => data.email || data.phoneNumber
     message: 'User must have either an email or a phone number',
     path: ['email', 'phoneNumber'],
 });
+/**
+ * When a user registers, we don't have all the information, so we use this schema
+ */
+exports.initialUserSchema = baseUserObj.pick({
+    id: true,
+    email: true,
+    phoneNumber: true,
+    isEmailVerified: true,
+    isPhoneVerified: true,
+    type: true,
+    createdAt: true,
+});
+/**
+ * The schema for the user returned on login
+ */
+exports.authUserSchema = baseUserObj.extend({
+    authToken: zod_1.z.string(),
+});
 exports.userWithPasswordSchema = exports.userSchema.and(zod_1.z.object({
     password: zod_1.z.string().min(MIN_PASSWORD_LENGTH),
 }));
+exports.userInitialRegistrationSchema = zod_1.z.object({
+    emailOrPhone: exports.emailOrPhoneSchema,
+    password: zod_1.z.string().min(MIN_PASSWORD_LENGTH, `Password must be at least ${MIN_PASSWORD_LENGTH} characters`),
+});
+exports.userVerifySchema = zod_1.z.object({
+    emailOrPhone: exports.emailOrPhoneSchema,
+    code: zod_1.z.string().min(6, 'Code must be at least 6 characters').max(10, 'Code is too long'),
+});
+exports.userCompleteProfileSchema = baseUserObj
+    .pick({
+    name: true,
+})
+    .extend({
+    lastName: zod_1.z.string().optional(),
+    nickname: zod_1.z.string().min(2),
+    birthDate: zod_1.z.coerce.date(),
+    waiverSignature: zod_1.z.boolean().refine((val) => val === true, {
+        message: 'You must accept the waiver signature',
+    }),
+    teamName: zod_1.z.string().optional(),
+});
+// Deprecated in favor of multi-step registration
 exports.userRegistrationInputSchema = baseUserObj
     .pick({
     name: true,
@@ -48,13 +96,6 @@ exports.userRegistrationInputSchema = baseUserObj
     path: ['email', 'phoneNumber'],
 });
 exports.userLoginInputSchema = zod_1.z.object({
-    emailOrPhone: zod_1.z
-        .string()
-        .min(1, 'Email or phone is required')
-        .refine((val) => {
-        const isEmail = zod_1.z.email().safeParse(val).success;
-        const isPhone = exports.PHONE_REGEX.test(val);
-        return isEmail || isPhone;
-    }, { message: 'Must be a valid email or phone number' }),
+    emailOrPhone: exports.emailOrPhoneSchema,
     password: zod_1.z.string().min(MIN_PASSWORD_LENGTH, `Password must be at least ${MIN_PASSWORD_LENGTH} characters`),
 });

package/dist/domains/user/User.types.d.ts

@@ -1,5 +1,11 @@
 import { z } from 'zod';
-import { userSchema, userTypeSchema, userWithPasswordSchema } from './User.schema';
+import { authUserSchema, initialUserSchema, userCompleteProfileSchema, userInitialRegistrationSchema, userLoginInputSchema, userSchema, userTypeSchema, userVerifySchema, userWithPasswordSchema } from './User.schema';
 export type UserType = z.infer<typeof userTypeSchema>;
 export type User = z.infer<typeof userSchema>;
 export type UserWithPassword = z.infer<typeof userWithPasswordSchema>;
+export type AuthUser = z.infer<typeof authUserSchema>;
+export type InitialUser = z.infer<typeof initialUserSchema>;
+export type UserInitialRegistration = z.infer<typeof userInitialRegistrationSchema>;
+export type UserVerify = z.infer<typeof userVerifySchema>;
+export type UserCompleteProfile = z.infer<typeof userCompleteProfileSchema>;
+export type UserLogin = z.infer<typeof userLoginInputSchema>;

package/docs/TICKETING_AND_PURCHASE_FLOW.md

@@ -0,0 +1,110 @@
+# Flujo de Compra de Tickets y Separación User/Player
+
+Este documento explica de forma detallada cómo está estructurado el flujo de compra de tickets en **Battle Racing**, cómo se separa la entidad que paga (User) de la entidad que corre (Player), qué hemos implementado hasta ahora y qué nos hace falta por implementar.
+
+---
+
+## 👥 1. Separación: Users vs. Players
+
+Para asegurar "cero fricción" en el entorno físico de la pista, hemos separado estrictamente el concepto de la cuenta (quien paga) del corredor (quien se sube al Kart).
+
+### `User` (La Cuenta / El Pagador)
+
+- **Propósito:** La persona física que se registra, gestiona un método de pago y posee el historial transaccional de compras.
+- **Autenticación:** Usa `email` o `phoneNumber` (sin `username`), contraseña y roles (`SUPER_ADMIN`, `CASHIER`, `PLAYER`).
+- **Relaciones:**
+  - Tiene un `defaultPlayerId` que apunta a su propio perfil de corredor.
+  - Puede ser tutor y ser "dueño" (`ownerUserId`) de múltiples `Players` menores de edad (`MINOR`).
+
+### `Player` (El Corredor / Perfil Gamificado)
+
+- **Propósito:** Es la entidad gamificada que se asigna físicamente a un Kart y cuyo nombre sale en las pantallas.
+- **Identificador (`nickname`):** No son únicos en la base de datos. Varios corredores pueden llamarse "Maverick" al mismo tiempo para no generar errores al registrarse rápidamente en el POS.
+- **Waivers:** Contiene el estado de la firma del documento de exención de responsabilidad (`waiver`).
+- **Relaciones:** Si es un invitado anónimo (`isGuest`), no está atado a ningún `User`. Si es un menor, su firma (`waiver`) es implícitamente otorgada por el `User` tutor.
+
+---
+
+## 🎟️ 2. Flujo de Compras (Purchases y Tickets)
+
+La adquisición de carreras sigue un ciclo de vida de tres grandes capas:
+
+### Capa 1: La Compra (`Purchase`)
+
+1. **Creación:** Se crea un `Purchase` agrupando varios ítems de compra (ej. 3 tickets de tipo `RACE`).
+   - Se crea en el endpoint: `POST /ticketing/purchases`
+   - Si el cliente está logueado en la Web App, se asocia su `buyerUserId`.
+   - Si la compra es 100% anónima en la sucursal (POS), `buyerUserId` es `null` y se usan `guestName` y `guestContact`.
+2. **Pago:** El pago se confirma asíncronamente vía Webhooks (`POST /ticketing/webhook/payment`) o manualmente en caja registradora (`POST /ticketing/purchases/:id/manual-payment`).
+3. **Generación de GameTickets:** Una vez confirmada y pagada la compra, esta se _desfragmenta_ y la base de datos genera los `GameTicket` individuales correspondientes (con estado `CREATED`).
+
+### Capa 2: La Sesión (`Game Session`)
+
+Dado que una persona puede comprar 10 tickets, pero a la pista se van a subir sus 5 amigos 2 veces, se usa una **Session**.
+
+1. **Creación:** Se agrupan tickets recién comprados bajo un código alfanumérico corto (ej. `A1B2C3`).
+2. **Unión:** Los amigos escanean un QR o dictan el código para unirse a la sesión (`POST /sessions/:code/join`). Aquí sus `Players` ingresan a la sesión.
+3. **Asignación:** Se asigna cada `GameTicket` disponible en la sesión a un `playerId` específico (`POST /sessions/:code/tickets/assign`).
+
+### Capa 3: El Turno Físico en Pista (`Game Turn`)
+
+1. **Cola de Carrera:** Cuando el grupo de la sesión está listo (o el operador del POS organiza la carrera), se crea un `GameTurn`.
+   - Endpoint: `POST /game-turns` o `POST /game-turns/bulk`.
+2. **Vinculación Final:** El `GameTurn` toma los `GameTickets` asignados y los `playerIds` correspondientes, bloqueándolos para esta carrera específica.
+3. **Ejecución y Hardware:** El hardware vincula a los jugadores con sus respectivos Karts y avanza las tareas de la carrera (preparación, en sus marcas, carrera, meta).
+   - El progreso se guarda mediante: `POST /game-turns/:id/tasks/:taskId/complete`
+
+---
+
+## ✅ 3. ¿Qué tenemos implementado hasta ahora?
+
+### En `br-common-lib` (Schemas)
+
+- Zod schemas altamente detallados para `User`, `Player`, `Session`, `Ticketing` (Purchase y Tickets) y `Payment`.
+- Control absoluto y fuente de verdad centralizada para la validación de estos modelos.
+
+### En `game-manager-backend` (REST API)
+
+- **Módulo `ticketing`:**
+  - Creación de compras.
+  - Procesamiento manual de pagos (para POS/Cashiers).
+  - Cancelación de compras.
+  - Recepción de webhooks de pasarelas de pago.
+  - Listado mis compras y resumen de mis tickets (`my-purchases`, `my-tickets`).
+- **Módulo `session`:**
+  - Obtener sesión por código corto.
+  - Unirse (y unirse en bulk) a una sesión.
+  - Asignar tickets a jugadores dentro de la sesión.
+- **Módulo `game-turn`:**
+  - Listado general de turnos (`GET /game-turns`).
+  - Creación de turnos y turnos en bloque.
+  - Avance de etapas (tasks) dentro del turno (`completeTask`).
+  - Capacidad para avanzar (`/advance`) o posponer (`/postpone`) el turno en la fila.
+- **Módulo `player` & `user`:**
+  - Estructuras en DB/Repositorios y controladores listos para manipular estos perfiles.
+
+---
+
+## 🚧 4. ¿Qué nos hace falta implementar? (Faltantes / TODOs)
+
+1. **Autenticación Severa (Guards):**
+   - Varios enpoints importantes como la creación de compras y modificación de sesiones todavía usan `request.user?.id` asumiendo que el usuario está inyectado, pero faltan **Guards** (e.g., JWT Guards) sólidos y globales para denegar acceso a usuarios no autorizados de forma segura o están marcados como `@Public()`.
+
+2. **Validación de Identidad de Email/Teléfono (`User`):**
+   - Aunque la base de datos soporta `isEmailVerified` e `isPhoneVerified`, el mecanismo de envío de OTP / SMS / Enlace Mágico para confirmar la propiedad aún no está programado.
+
+3. **Verificación de Seguridad de Asignación de Tickets:**
+   - Comprobar que un User no pueda asignar tickets de un Purchase que NO le pertenece (cuando la abstracción de sesión permita saltos de seguridad).
+   - Actualmente falta un "Ownership Check" robusto en varios GET de compras y lectura de turnos.
+
+4. **Actualización Automática de Estadísticas del Player:**
+   - Actualmente la base de datos de Players tiene sub-schemas listos para Stats (`totalRaces`, `bestTimeMs`, `xp`). Sin embargo, una vez que el `GameTurn` se completa en la pista, falta implementar el webhook o servicio que **calcule los resultados finales y actualice estos stats** dentro de cada `Player` que participó.
+
+5. **Flujos de Error de Pagos y Reembolsos Avanzados:**
+   - Manejo exhaustivo de reembolsos desde Stripe hacia el sistema para revocar `GameTickets` si una persona pide chargeback manual.
+
+6. **Integración Completa con POS (Front-end UI):**
+   - Falta validar en el frontend de POS que estos flujos asíncronos (como el crear compra en cash, asignar players de forma anónima) no se bloqueen por dependencias de cuentas "Guest". Asegurarse de que el frontend POS pueda transitar estas 3 capas sin recargar.
+
+7. **Asociación Dinámica de Hardware (Karts ↔ Players) en el GameTurn:**
+   - Hay que madurar la lógica donde un `playerId` que entra a un `GameTurn` es asignado al IP / Socket / ID Hardware específico del Kart en el que se acaba de sentar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battle-racing/br-common-lib",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Common library for all Battle Racing Repositorios",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/domains/command/Command.schema.ts

@@ -10,6 +10,8 @@ import {
   screenCountdownParamsSchema,
   screenFinishViewInputSchema,
   screenUpdateGameViewInputSchema,
+  showLightsColorParamsSchema,
+  showLightsEffectParamsSchema,
   speedChangeOptionsSchema,
   speedConfigurationSchema,
   starLaserConfigureModuleOptionsSchema,
@@ -152,16 +154,32 @@ export const steeringWheelModuleCommandSchema = z.union([
   z.object({ module: z.literal('steeringWheel'), action: z.literal('turnLedOff') }),
 ]);
 
-// --- All Commands Union ---
-export const allCommandsConfigSchema = z.union([
-  ballSensorDiskThrowerModuleCommandSchema,
-  diskSensorBallShooterModuleCommandSchema,
-  flagModuleCommandSchema,
-  rgbModuleCommandSchema,
-  speedModuleCommandSchema,
-  leftStarBackLaserModuleCommandSchema,
-  rightStarFrontLaserModuleCommandSchema,
-  screenModuleCommandSchema,
-  steeringWheelModuleCommandSchema,
-  soundModuleCommandSchema,
+// --- Emergency ---
+export const emergencyModuleCommandSchema = z.union([
+  z.object({ module: z.literal('emergency'), action: z.literal('activate') }),
+  z.object({ module: z.literal('emergency'), action: z.literal('deactivate') }),
+]);
+
+// --- Lights ---
+export const lightsModuleCommandSchema = z.union([
+  z.object({ module: z.literal('lights'), action: z.literal('showColor'), params: showLightsColorParamsSchema }),
+  z.object({ module: z.literal('lights'), action: z.literal('showEffect'), params: showLightsEffectParamsSchema }),
 ]);
+
+// --- All Commands Union ---
+export const allCommandsConfigSchema = z
+  .union([
+    ballSensorDiskThrowerModuleCommandSchema,
+    diskSensorBallShooterModuleCommandSchema,
+    flagModuleCommandSchema,
+    rgbModuleCommandSchema,
+    speedModuleCommandSchema,
+    leftStarBackLaserModuleCommandSchema,
+    rightStarFrontLaserModuleCommandSchema,
+    screenModuleCommandSchema,
+    steeringWheelModuleCommandSchema,
+    soundModuleCommandSchema,
+    emergencyModuleCommandSchema,
+    lightsModuleCommandSchema,
+  ])
+  .and(z.object({ params: z.unknown().optional() }));

package/src/domains/command/Command.types.ts

@@ -4,8 +4,10 @@ import {
   ballSensorDiskThrowerModuleCommandSchema,
   changeSpeedActionCommandOptionsSchema,
   diskSensorBallShooterModuleCommandSchema,
+  emergencyModuleCommandSchema,
   flagModuleCommandSchema,
   leftStarBackLaserModuleCommandSchema,
+  lightsModuleCommandSchema,
   playSoundActionCommandOptionsSchema,
   rgbModuleCommandSchema,
   rightStarFrontLaserModuleCommandSchema,
@@ -28,5 +30,7 @@ export type RightStarFrontLaserModuleCommands = z.infer<typeof rightStarFrontLas
 export type ScreenModuleCommands = z.infer<typeof screenModuleCommandSchema>;
 export type SteeringWheelModuleCommands = z.infer<typeof steeringWheelModuleCommandSchema>;
 export type SoundModuleCommands = z.infer<typeof soundModuleCommandSchema>;
+export type EmergencyModuleCommands = z.infer<typeof emergencyModuleCommandSchema>;
+export type LightsModuleCommands = z.infer<typeof lightsModuleCommandSchema>;
 
 export type AllCommandsConfig = z.infer<typeof allCommandsConfigSchema>;

package/src/domains/hardware/KartHardwareState.schema.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { checkpointTypeSchema } from '../checkpoint/Checkpoint.schema';
-import { flagStatusSchema } from './flag/Flag.schema';
-import { rgbStatusSchema } from './rgb/RGB.schema';
-import { screenStatusSchema } from './screen/Screen.schema';
-import { speedStatusSchema } from './speed/Speed.schema';
+import { flagStatusSchema } from './flag';
+import { rgbStatusSchema } from './rgb';
+import { screenStatusSchema } from './screen';
+import { speedStatusSchema } from './speed';
 
 export const kartHardwareStateSchema = z.object({
   speed: z

package/src/domains/hardware/KartHardwareState.types.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import { kartHardwareStateSchema } from './KartHardwareState.schema';
+
+export type KartHardwareState = z.infer<typeof kartHardwareStateSchema>;

package/src/domains/hardware/ModuleStatus.schema.ts

@@ -3,9 +3,11 @@ import { ballSensorDiskThrowerModuleStatusSchema } from './ballSensor';
 import { diskSensorBallShooterModuleStatusSchema } from './diskSensor';
 import { emergencyModuleStatusSchema } from './emergency';
 import { flagModuleStatusSchema } from './flag';
+import { lightsModuleStatusSchema } from './lights';
 import { MODULE_NAME } from './ModuleName.const';
 import { rgbModuleStatusSchema } from './rgb';
 import { speedModuleStatusSchema } from './speed';
+import { screenModuleStatusSchema } from './screen';
 import { starLaserModuleStatusSchema } from './star-laser';
 import { steeringWheelModuleStatusSchema } from './steering-wheel';
 
@@ -20,4 +22,6 @@ export const moduleStatusSchema = z.union([
   starLaserModuleStatusSchema,
   steeringWheelModuleStatusSchema,
   emergencyModuleStatusSchema,
+  screenModuleStatusSchema,
+  lightsModuleStatusSchema,
 ]);

package/src/domains/hardware/ballSensor/BallSensor.const.ts

@@ -11,3 +11,9 @@ export const BALL_SENSOR_STATUS = {
   SENSOR_HIT: 'Sensor Hit',
   UNKNOWN: 'Unknown',
 } as const;
+
+export const DISK_THROWER_COMMAND = {
+  ACTIVATE_THROWER: 'Activate Thrower',
+  DEACTIVATE_THROWER: 'Deactivate Thrower',
+  THROW_DISK: 'Throw Disk',
+} as const;

package/src/domains/hardware/ballSensor/BallSensor.schema.ts

@@ -1,8 +1,10 @@
 import { z } from 'zod';
-import { BALL_SENSOR_COMMAND, BALL_SENSOR_STATUS } from './BallSensor.const';
+import { BALL_SENSOR_COMMAND, BALL_SENSOR_STATUS, DISK_THROWER_COMMAND } from './BallSensor.const';
 
 export const ballSensorCommandSchema = z.enum(BALL_SENSOR_COMMAND);
 
+export const diskThrowerCommandSchema = z.enum(DISK_THROWER_COMMAND);
+
 export const ballSensorStatusSchema = z.enum(BALL_SENSOR_STATUS);
 
 export const configureBallSensorDiskThrowerModuleOptionsSchema = z.object({

package/src/domains/hardware/ballSensor/BallSensor.types.ts

@@ -4,9 +4,11 @@ import {
   ballSensorDiskThrowerModuleStatusSchema,
   ballSensorStatusSchema,
   configureBallSensorDiskThrowerModuleOptionsSchema,
+  diskThrowerCommandSchema,
 } from './BallSensor.schema';
 
 export type BallSensorCommand = z.infer<typeof ballSensorCommandSchema>;
+export type DiskThrowerCommand = z.infer<typeof diskThrowerCommandSchema>;
 export type BallSensorStatus = z.infer<typeof ballSensorStatusSchema>;
 export type ConfigureBallSensorDiskThrowerModuleOptions = z.infer<
   typeof configureBallSensorDiskThrowerModuleOptionsSchema

package/src/domains/hardware/flag/Flag.const.ts

@@ -82,3 +82,11 @@ export const FLAG_MEDIA_NAME = {
   STATIC_BEATING_HEART: 'static_beating_heart',
   STATIC_SPEED_PAD: 'static_speed_pad',
 } as const;
+
+export const FLAG_ACTION_COMMAND = {
+  ACTIVATE: 'Activate',
+  DEACTIVATE: 'Deactivate',
+  SHOW_MEDIA_INDEFINITELY: 'Show Media Indefinitely',
+  SHOW_MEDIA_TEMPORARILY: 'Show Media Temporarily',
+  CONFIGURE: 'Configure',
+} as const;

package/src/domains/hardware/flag/Flag.schema.ts

@@ -1,11 +1,15 @@
 import { z } from 'zod';
 import { colorNameSchema } from '../../color';
 import { checkpointTypeSchema } from '../../checkpoint';
-import { FLAG_MEDIA_NAME, FLAG_STATUS } from './Flag.const';
+import { FLAG_MEDIA_NAME, FLAG_STATUS, FLAG_ACTION_COMMAND } from './Flag.const';
 
 export const flagStatusSchema = z.enum(FLAG_STATUS);
 
-export const flagMediaNameSchema = z.enum(FLAG_MEDIA_NAME);
+export const flagActionCommandSchema = z.enum(FLAG_ACTION_COMMAND);
+
+export const flagMediaNameSchema = z
+  .union([z.number().min(0).max(255), z.enum(FLAG_MEDIA_NAME)])
+  .describe('The Media source could be the name of the icon on Flag Module or a number to render');
 
 export const flagModuleStatusSchema = z.object({
   flagStatus: flagStatusSchema,

package/src/domains/hardware/flag/Flag.types.ts

@@ -5,9 +5,11 @@ import {
   flagModuleStatusSchema,
   flagShowMediaOptionsSchema,
   flagStatusSchema,
+  flagActionCommandSchema,
 } from './Flag.schema';
 
 export type FlagStatus = z.infer<typeof flagStatusSchema>;
+export type FlagActionCommand = z.infer<typeof flagActionCommandSchema>;
 export type FlagMediaName = z.infer<typeof flagMediaNameSchema>;
 export type FlagModuleStatus = z.infer<typeof flagModuleStatusSchema>;
 export type FlagConfigurationOptions = z.infer<typeof flagConfigurationOptionsSchema>;