@battle-racing/br-common-lib 3.8.0 → 4.3.0

package/dist/types/racingTeam/RacingTeam.schema.d.ts

@@ -2,20 +2,19 @@ import { z } from 'zod';
 export declare const racingTeamSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    imageUrl: z.ZodOptional<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodURL>;
     adminUserId: z.ZodString;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
 }, z.core.$strip>;
 export declare const createRacingTeamSchema: z.ZodObject<{
     name: z.ZodString;
-    imageUrl: z.ZodOptional<z.ZodString>;
-    adminUserId: z.ZodString;
+    imageUrl: z.ZodOptional<z.ZodURL>;
 }, z.core.$strip>;
 export declare const updateRacingTeamSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
-    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodURL>>;
     adminUserId: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodDate>;
     updatedAt: z.ZodOptional<z.ZodDate>;
@@ -23,15 +22,20 @@ export declare const updateRacingTeamSchema: z.ZodObject<{
 export declare const filterRacingTeamSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     adminUserId: z.ZodOptional<z.ZodString>;
-    page: z.ZodDefault<z.ZodNumber>;
-    limit: z.ZodDefault<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const racingTeamSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    imageUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
 export declare const paginatedRacingTeamSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
-        imageUrl: z.ZodOptional<z.ZodString>;
+        imageUrl: z.ZodOptional<z.ZodURL>;
         adminUserId: z.ZodString;
         createdAt: z.ZodDate;
         updatedAt: z.ZodDate;
@@ -42,3 +46,15 @@ export declare const paginatedRacingTeamSchema: z.ZodObject<{
         limit: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const paginatedRacingTeamSummarySchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        imageUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    meta: z.ZodObject<{
+        nextCursor: z.ZodOptional<z.ZodString>;
+        hasMore: z.ZodOptional<z.ZodBoolean>;
+        limit: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/types/racingTeam/RacingTeam.schema.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.paginatedRacingTeamSchema = exports.filterRacingTeamSchema = exports.updateRacingTeamSchema = exports.createRacingTeamSchema = exports.racingTeamSchema = void 0;
+exports.paginatedRacingTeamSummarySchema = exports.paginatedRacingTeamSchema = exports.racingTeamSummarySchema = exports.filterRacingTeamSchema = exports.updateRacingTeamSchema = exports.createRacingTeamSchema = exports.racingTeamSchema = void 0;
 const zod_1 = require("zod");
 const pagination_1 = require("../pagination");
 exports.racingTeamSchema = zod_1.z.object({
     id: zod_1.z.string(),
     name: zod_1.z.string().min(3).max(50),
-    imageUrl: zod_1.z.string().url().optional(),
+    imageUrl: zod_1.z.url().optional(),
     adminUserId: zod_1.z.string(),
     createdAt: zod_1.z.date(),
     updatedAt: zod_1.z.date(),
@@ -15,13 +15,20 @@ exports.createRacingTeamSchema = exports.racingTeamSchema.omit({
     id: true,
     createdAt: true,
     updatedAt: true,
+    adminUserId: true,
 });
 exports.updateRacingTeamSchema = exports.racingTeamSchema.partial();
 exports.filterRacingTeamSchema = zod_1.z.object({
     name: zod_1.z.string().optional(),
     adminUserId: zod_1.z.string().optional(),
-    page: zod_1.z.number().min(1).default(1),
-    limit: zod_1.z.number().min(1).max(100).default(10),
+    page: zod_1.z.coerce.number().min(1).default(1),
+    limit: zod_1.z.coerce.number().min(1).max(100).default(10),
     cursor: zod_1.z.string().optional(),
 });
+exports.racingTeamSummarySchema = exports.racingTeamSchema.pick({
+    id: true,
+    name: true,
+    imageUrl: true,
+});
 exports.paginatedRacingTeamSchema = (0, pagination_1.paginatedResponseSchema)(exports.racingTeamSchema);
+exports.paginatedRacingTeamSummarySchema = (0, pagination_1.paginatedResponseSchema)(exports.racingTeamSummarySchema);

package/dist/types/racingTeam/RacingTeamMembership.schema.d.ts

@@ -15,9 +15,9 @@ export declare const teamMemberSchema: z.ZodObject<{
     racingTeamId: z.ZodString;
     userId: z.ZodString;
     role: z.ZodEnum<{
-        PILOT: "PILOT";
-        TECHNICIAN: "TECHNICIAN";
-        COACH: "COACH";
+        readonly PILOT: "PILOT";
+        readonly TECHNICIAN: "TECHNICIAN";
+        readonly COACH: "COACH";
     }>;
     joinedAt: z.ZodDate;
 }, z.core.$strip>;

package/dist/types/racingTeam/RacingTeamMembership.schema.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.answerJoinRequestSchema = exports.createJoinRequestSchema = exports.teamMemberSchema = exports.joinRequestSchema = void 0;
 const zod_1 = require("zod");
+const constants_1 = require("../../constants");
 exports.joinRequestSchema = zod_1.z.object({
     id: zod_1.z.string(),
     racingTeamId: zod_1.z.string(),
@@ -14,7 +15,7 @@ exports.joinRequestSchema = zod_1.z.object({
 exports.teamMemberSchema = zod_1.z.object({
     racingTeamId: zod_1.z.string(),
     userId: zod_1.z.string(),
-    role: zod_1.z.enum(['PILOT', 'TECHNICIAN', 'COACH']),
+    role: zod_1.z.enum(constants_1.RACING_TEAM_ROLE),
     joinedAt: zod_1.z.date(),
 });
 exports.createJoinRequestSchema = zod_1.z.object({

package/dist/types/ticketing/Ticketing.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { PurchaseSchema, GameTicketSchema, TicketUserTypeSchema, TicketTypeSchema, GameTicketStatusSchema, CreatePurchasePublicSchema, CreatePurchaseInternalSchema, TicketSummarySchema } from './ticketing.schemas';
+export type TicketType = z.infer<typeof TicketTypeSchema>;
+export type GameTicketStatus = z.infer<typeof GameTicketStatusSchema>;
+export type TicketUserType = z.infer<typeof TicketUserTypeSchema>;
+export type TicketSummary = z.infer<typeof TicketSummarySchema>;
+export type Purchase = z.infer<typeof PurchaseSchema>;
+export type CreatePurchasePublicInput = z.infer<typeof CreatePurchasePublicSchema>;
+export type CreatePurchaseInternalInput = z.infer<typeof CreatePurchaseInternalSchema>;
+export type GameTicket = z.infer<typeof GameTicketSchema>;

package/dist/types/ticketing/Ticketing.js

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

package/dist/types/ticketing/index.d.ts

@@ -1,9 +1,7 @@
-export * from './GameTicket';
-export * from './PaymentProvider';
 export * from './GameTurn';
-export * from './Purchase';
-export * from './ticketing.schemas';
-export * from './ticketing.schemas';
+export * from './GameTurn.schema';
 export * from './GameTurnTask';
 export * from './GameTurnTask.schema';
-export * from './GameTurn.schema';
+export * from './PaymentProvider';
+export * from './ticketing.schemas';
+export * from './Ticketing';

package/dist/types/ticketing/index.js

@@ -14,12 +14,10 @@ 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("./GameTicket"), exports);
-__exportStar(require("./PaymentProvider"), exports);
 __exportStar(require("./GameTurn"), exports);
-__exportStar(require("./Purchase"), exports);
-__exportStar(require("./ticketing.schemas"), exports);
-__exportStar(require("./ticketing.schemas"), exports);
+__exportStar(require("./GameTurn.schema"), exports);
 __exportStar(require("./GameTurnTask"), exports);
 __exportStar(require("./GameTurnTask.schema"), exports);
-__exportStar(require("./GameTurn.schema"), exports);
+__exportStar(require("./PaymentProvider"), exports);
+__exportStar(require("./ticketing.schemas"), exports);
+__exportStar(require("./Ticketing"), exports);

package/dist/types/ticketing/ticketing.schemas.d.ts

@@ -11,6 +11,11 @@ export declare const TICKET_USER_TYPE: {
     readonly EXISTING: "existing";
     readonly GUEST: "guest";
 };
+export declare const TICKET_TYPE: {
+    readonly RACE: "race";
+    readonly BATTLE: "battle";
+    readonly SOCCER: "soccer";
+};
 export declare const GameTicketStatusSchema: z.ZodEnum<{
     readonly CREATED: "created";
     readonly ASSIGNED: "assigned";
@@ -23,6 +28,16 @@ export declare const TicketUserTypeSchema: z.ZodEnum<{
     readonly EXISTING: "existing";
     readonly GUEST: "guest";
 }>;
+export declare const TicketTypeSchema: z.ZodEnum<{
+    readonly RACE: "race";
+    readonly BATTLE: "battle";
+    readonly SOCCER: "soccer";
+}>;
+export declare const TicketSummarySchema: z.ZodRecord<z.ZodEnum<{
+    readonly RACE: "race";
+    readonly BATTLE: "battle";
+    readonly SOCCER: "soccer";
+}>, z.ZodNumber>;
 export declare const GameTicketSchema: z.ZodObject<{
     id: z.ZodString;
     purchaseId: z.ZodString;
@@ -40,6 +55,11 @@ export declare const GameTicketSchema: z.ZodObject<{
         readonly ACTIVE: "active";
         readonly COMPLETED: "completed";
     }>;
+    type: z.ZodDefault<z.ZodEnum<{
+        readonly RACE: "race";
+        readonly BATTLE: "battle";
+        readonly SOCCER: "soccer";
+    }>>;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
     completedAt: z.ZodOptional<z.ZodDate>;
@@ -49,10 +69,36 @@ export declare const PurchaseSchema: z.ZodObject<{
     purchaseNumber: z.ZodNumber;
     buyerUserId: z.ZodString;
     totalTickets: z.ZodNumber;
-    availableTickets: z.ZodNumber;
-    usedTickets: z.ZodNumber;
     purchaseDate: z.ZodDate;
+    ticketType: z.ZodDefault<z.ZodEnum<{
+        readonly RACE: "race";
+        readonly BATTLE: "battle";
+        readonly SOCCER: "soccer";
+    }>>;
     paymentData: z.ZodOptional<z.ZodAny>;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
 }, z.core.$strip>;
+/**
+ * Probably temporary as the purchase will be a webhook called by the provider (Stripe, PayPal, etc)
+ */
+export declare const CreatePurchasePublicSchema: z.ZodObject<{
+    ticketType: z.ZodDefault<z.ZodEnum<{
+        readonly RACE: "race";
+        readonly BATTLE: "battle";
+        readonly SOCCER: "soccer";
+    }>>;
+    ticketCount: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The public input doesn't receive a userId, as it's resolved on the backend
+ */
+export declare const CreatePurchaseInternalSchema: z.ZodObject<{
+    buyerUserId: z.ZodString;
+    ticketType: z.ZodDefault<z.ZodEnum<{
+        readonly RACE: "race";
+        readonly BATTLE: "battle";
+        readonly SOCCER: "soccer";
+    }>>;
+    ticketCount: z.ZodNumber;
+}, z.core.$strip>;

package/dist/types/ticketing/ticketing.schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PurchaseSchema = exports.GameTicketSchema = exports.TicketUserTypeSchema = exports.GameTicketStatusSchema = exports.TICKET_USER_TYPE = exports.GAME_TICKET_STATUS = void 0;
+exports.CreatePurchaseInternalSchema = exports.CreatePurchasePublicSchema = exports.PurchaseSchema = exports.GameTicketSchema = exports.TicketSummarySchema = exports.TicketTypeSchema = exports.TicketUserTypeSchema = exports.GameTicketStatusSchema = exports.TICKET_TYPE = exports.TICKET_USER_TYPE = exports.GAME_TICKET_STATUS = void 0;
 const zod_1 = require("zod");
 exports.GAME_TICKET_STATUS = {
     CREATED: 'created',
@@ -14,8 +14,15 @@ exports.TICKET_USER_TYPE = {
     EXISTING: 'existing',
     GUEST: 'guest',
 };
+exports.TICKET_TYPE = {
+    RACE: 'race',
+    BATTLE: 'battle',
+    SOCCER: 'soccer',
+};
 exports.GameTicketStatusSchema = zod_1.z.enum(exports.GAME_TICKET_STATUS);
 exports.TicketUserTypeSchema = zod_1.z.enum(exports.TICKET_USER_TYPE);
+exports.TicketTypeSchema = zod_1.z.enum(exports.TICKET_TYPE);
+exports.TicketSummarySchema = zod_1.z.record(exports.TicketTypeSchema, zod_1.z.number());
 exports.GameTicketSchema = zod_1.z.object({
     id: zod_1.z.string(),
     purchaseId: zod_1.z.string(),
@@ -23,6 +30,7 @@ exports.GameTicketSchema = zod_1.z.object({
     ownerUsername: zod_1.z.string(),
     userType: exports.TicketUserTypeSchema,
     status: exports.GameTicketStatusSchema,
+    type: exports.TicketTypeSchema.default(exports.TICKET_TYPE.RACE),
     createdAt: zod_1.z.date(),
     updatedAt: zod_1.z.date(),
     completedAt: zod_1.z.date().optional(),
@@ -32,10 +40,26 @@ exports.PurchaseSchema = zod_1.z.object({
     purchaseNumber: zod_1.z.number(),
     buyerUserId: zod_1.z.string(),
     totalTickets: zod_1.z.number(),
-    availableTickets: zod_1.z.number(),
-    usedTickets: zod_1.z.number(),
     purchaseDate: zod_1.z.date(),
+    ticketType: exports.TicketTypeSchema.default(exports.TICKET_TYPE.RACE),
     paymentData: zod_1.z.any().optional(),
     createdAt: zod_1.z.date(),
     updatedAt: zod_1.z.date(),
 });
+/**
+ * Probably temporary as the purchase will be a webhook called by the provider (Stripe, PayPal, etc)
+ */
+exports.CreatePurchasePublicSchema = exports.PurchaseSchema.pick({
+    ticketType: true,
+}).extend({
+    ticketCount: zod_1.z.number(),
+});
+/**
+ * The public input doesn't receive a userId, as it's resolved on the backend
+ */
+exports.CreatePurchaseInternalSchema = exports.PurchaseSchema.pick({
+    ticketType: true,
+    buyerUserId: true,
+}).extend({
+    ticketCount: zod_1.z.number(),
+});

package/dist/types/user/user.schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 export declare const UserRoleSchema: z.ZodEnum<{
+    PLAYER: "PLAYER";
     SUPER_ADMIN: "SUPER_ADMIN";
     OPERATOR: "OPERATOR";
-    PLAYER: "PLAYER";
 }>;
 export declare const UserSchema: z.ZodObject<{
     id: z.ZodString;
@@ -11,9 +11,9 @@ export declare const UserSchema: z.ZodObject<{
     email: z.ZodEmail;
     phone: z.ZodOptional<z.ZodString>;
     role: z.ZodEnum<{
+        PLAYER: "PLAYER";
         SUPER_ADMIN: "SUPER_ADMIN";
         OPERATOR: "OPERATOR";
-        PLAYER: "PLAYER";
     }>;
     type: z.ZodEnum<{
         readonly STAFF: "STAFF";
@@ -27,9 +27,9 @@ export declare const UserWithPasswordSchema: z.ZodObject<{
     email: z.ZodEmail;
     phone: z.ZodOptional<z.ZodString>;
     role: z.ZodEnum<{
+        PLAYER: "PLAYER";
         SUPER_ADMIN: "SUPER_ADMIN";
         OPERATOR: "OPERATOR";
-        PLAYER: "PLAYER";
     }>;
     type: z.ZodEnum<{
         readonly STAFF: "STAFF";

package/dist/utils/roles.utils.d.ts

@@ -1,4 +1,4 @@
-import { Permission, UserRole } from '../types';
+import { Permission, UserRole } from '../domains';
 export declare function hasPermission(userRole: UserRole, requiredPermission: Permission): boolean;
 export declare function hasAnyPermission(userRole: UserRole, requiredPermissions: Permission[]): boolean;
 export declare function hasAllPermissions(userRole: UserRole, requiredPermissions: Permission[]): boolean;

package/dist/utils/roles.utils.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasPermission = hasPermission;
 exports.hasAnyPermission = hasAnyPermission;
 exports.hasAllPermissions = hasAllPermissions;
-const constants_1 = require("../constants");
 const data_1 = require("../data");
+const domains_1 = require("../domains");
 function hasPermission(userRole, requiredPermission) {
-    if (userRole === constants_1.USER_ROLE.SUPER_ADMIN) {
+    if (userRole === domains_1.USER_ROLE.SUPER_ADMIN) {
         return true;
     }
     const roleDefinition = data_1.ROLE_DEFINITIONS.find((def) => def.role === userRole);

package/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,50 @@
+# Hardware Domain Migration Guide
+
+This document serves as a step-by-step cleaning and refactoring guide for an AI Model to migrate legacy hardware types to the new `src/domains` structure.
+
+We are migrating from `src/types` to `src/domains`.
+We will keep the old types in `src/types` for now, but we will remove them in the next major release. (don't change anything on the /types folder).
+
+## 1. Architecture Principles
+
+For each component (e.g., `Lights`, `Sound`, `Race`), we must create a dedicated directory in `src/domains/hardware/[component-name]` with 4 files:
+
+1.  **`[ComponentName].const.ts`**:
+    - Contains all constants (Status, Commands, Configuration options).
+    - Use `as const` assertions.
+    - **NO** TypeScript `enum`. Use objects.
+    - Example: `LIGHTS_STATUS`, `LIGHTS_ACTION_COMMAND`.
+
+2.  **`[ComponentName].schema.ts`**:
+    - Depends on `[ComponentName].const.ts`.
+    - Contains Zod schemas.
+    - Use `z.enum(CONSTANT)` for string unions.
+    - Example: `lightsStatusSchema`, `lightsConfigurationSchema`.
+
+3.  **`[ComponentName].types.ts`**:
+    - Depends on `[ComponentName].schema.ts`.
+    - Contains **inferred** TypeScript types using `z.infer<>`.
+    - **DO NOT** manually define interfaces if a schema exists.
+    - Example: `export type LightsStatus = z.infer<typeof lightsStatusSchema>;`.
+
+4.  **`index.ts`**:
+    - Exports everything from the above 3 files.
+    - Some domains could have more than one Entity, but they are, so we should export all of them.
+
+you need to be sure in the index.ts you're exporting domains, and not types, otherwise you'll get errors of duplicate Types.
+
+## 2. Migration Checklist
+
+Double check the existing types and verify the new ones on `domains` are compatible.
+
+Create a migration plan, and don't change anything on the /types folder son we can compare the new ones are correct.
+
+## 3. Clean Up & wiring
+
+- [ ] Update `src/domains/hardware/index.ts` to export new modules.
+- [ ] Remove duplicate constants in `src/constants/`.
+
+## 4. Verification
+
+- [ ] Run `npm run build` to ensure no type errors.
+- [ ] Check for circular dependencies.

package/docs/USER_VS_PLAYER.md

@@ -0,0 +1,87 @@
+# Battle Racing Common Library (`br-common-lib`)
+
+Este repositorio contiene los esquemas de validación Zod, los tipos TypeScript, y las constantes compartidas de domino que actúan como la **fuente única de verdad (Single Source of Truth)** para los microservicios y clientes del ecosistema de Battle Racing (POS, Game Manager Backend, y Web Apps).
+
+Para asegurar la coherencia arquitectónica y facilitar la integración con futuras herramientas de IA (agentes), **todas las modificaciones al ecosistema deben respetar las siguientes convenciones y flujos**.
+
+---
+
+## 🏗️ 1. Modelo de Dominio Crítico: `User` vs `Player`
+
+La decisión arquitectónica más importante del sistema es la inyección de **cero fricción** en el entorno físico de la pista. Para ello, se ha separado estrictamente el concepto de "Cuenta" (quien paga y se loguea) del concepto de "Corredor" (quien sale en la pantalla y maneja el Kart).
+
+### `User` (La Cuenta / El Pagador)
+
+- **Propósito:** Representa a la persona física que se registra en la app, gestiona un método de pago, y posee un historial transaccional.
+- **Autenticación (Email o Teléfono):** En lugar de utilizar un `username` de foros antiguos, **la autenticación se realiza estrictamente a través de `email` o `phoneNumber`**. Esto asegura un proceso de on-boarding sin fricción y previene cuellos de botella en los puntos de venta (POS) donde un cajero o totém no puede adivinar qué `username` no está registrado.
+- **Propiedades Clave:** `password`, `role` (SUPER_ADMIN, CASHIER, PLAYER), `type`.
+- **Relación:** Un `User` siempre tiene asignado automáticamente un `defaultPlayerId` (su perfil de corredor). Sin embargo, un `User` (tutor o papá) puede administrar y poseer múltiples `Players` hijos (`MINOR`).
+
+### `Player` (El Corredor)
+
+- **Propósito:** Es la entidad gamificada. Representa los datos que ven los espectadores en la pantalla del líder, en la pista, y lo que se le asigna físicamente a un Kart.
+- **Identificador (`nickname`):** Los jugadores se identifican por su `nickname` (ej. "Maverick 🏎️💨").
+- **Regla de Oro (No Unicidad):** **Los `nicknames` NO son únicos en la base de datos**. Diferentes jugadores pueden llamarse "Juan" para evitar fricción en un sábado por la noche lleno de clientes registrándose. El sistema interno los diferencia mediante su `UUID` o vinculándolos temporalmente al número de Kart en la carrera activa.
+- **Waivers:** Los `Players` deben firmar (o sus tutores deben firmar por ellos) un documento de exención de responsabilidad (`waiver`).
+
+---
+
+## 🛡️ 2. Práctica de Validación (Zod First)
+
+Nuestra arquitectura delega TODA la validación de negocio y seguridad a **Zod**. En lugar de duplicar lógicas de validación en frontend, backend, y bases de datos, los moldes residen aquí en `br-common-lib`.
+
+### Organización de Archivos (Arquitectura de Dominio)
+
+Dentro de `src/domains/{domainName}/`:
+
+- `*.schema.ts`: Aquí residen todos los objetos Zod (ej. `userSchema`, `userLoginInputSchema`).
+- `*.types.ts`: Tipos estáticos autogenerados mediante `z.infer<typeof schema>`. Nunca se debe escribir un `interface` manualmente si ya existe un esquema de validación.
+- `*.const.ts`: Enums, literales y variables constantes.
+
+### DTOs en NestJS (`nestjs-zod`)
+
+En el ecosistema Backend (`game-manager-backend`), está **estrictamente prohibido** usar decoradores de `class-validator` (como `@IsString()`).
+En su lugar, los DTOs heredan del esquema Zod importado de esta librería utilizando la función `createZodDto`:
+
+```typescript
+// En game-manager-backend: src/modules/auth/dto/login.dto.ts
+import { createZodDto } from 'nestjs-zod';
+import { userLoginInputSchema } from '@battle-racing/br-common-lib';
+
+export class LoginInputDto extends createZodDto(userLoginInputSchema) {}
+```
+
+Cualquier cambio a los endpoints o al pipeline de registro DEBE comenzar por actualizar el `.schema.ts` dentro de `br-common-lib` y recompilar la librería (`npm run build`).
+
+---
+
+## 🎟️ 3. Flujo Transaccional: Compras y Turnos de Juego (Ticketing)
+
+### The `Purchase` (Compra)
+
+- Agrupa múltiples "Items" de juegos bajo una misma transacción de pago con un `buyerUserId` (que puede ser Null si la compra se hace 100% anónima como Guest en el POS).
+- La creación de compras asíncronas es un proceso validado por Webhooks (ej. una vez liquidado el pago en el gateway, se genera legalmente la compra).
+
+### The `GameTicket` (El Boleto individual)
+
+- Una compra de "3 Carreras" se desfragmenta en 3 `GameTicket` separados en la base de datos.
+- Los Boletos nacen en estado `CREATED`.
+- Un boleto es asignado a un corredor físico mediante el `playerId`. **Ya no se usa `ownerUsername`**.
+
+### The `GameTurn` (El Turno Físico en Pista)
+
+- Cuando un grupo de amigos se acerca a la fila, el operador (o el sistema automático) los agrupa en un `GameTurn`.
+- El `GameTurn` toma un conjunto de `GameTickets` válidos (de cualquier compra anterior) y un conjunto de `playerIds` participantes.
+- Enlaza la lógica del hardware, controlando qué `Kart` se le asigna a cada integrante para la carrera real y las misiones/tareas (`tasks`) escaneadas por QR.
+
+---
+
+## 🔄 4. Flujo de Trabajo para Inteligencias Múltiples (Agentes)
+
+Si eres un modelo de IA leyendo este archivo para continuar con el desarrollo de Battle Racing:
+
+1. **Nunca añadas `username`** ni regreses a prácticas de validación por foros.
+2. Si un endpoint o componente frontend necesita una regla de UI o validación nueva, módificala **primero** en los schemas de `br-common-lib` y recompila con `npm run build`.
+3. Evita las dependencias circulares usando los archivos de mapeo de barril (`index.ts`) y organizando siempre el código en `/domains`.
+4. Todos los identificadores (ID's) a través del sistema están diseñados con `z.uuidv4()`. Mantén ese estándar para migraciones futuras a bases de datos escalables.
+5. Emplea variables `emailOrPhone` cuando realices un flujo de acceso. No dupliques ni requieras ambas salvo expresamente configurado.

package/package.json

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

package/src/__deprecated__/constants/hardware/index.ts

@@ -0,0 +1,9 @@
+export * from './base-hardware-status';
+export * from './damage';
+export * from './flag-media-name';
+export * from './flag-status';
+export * from './lights-effect';
+export * from './rgb-status';
+export * from './screen-status';
+export * from './screen-view';
+export * from './speed-status';

package/src/__deprecated__/constants/index.ts

@@ -0,0 +1,9 @@
+export * from './checkpoint-type';
+export * from './hardware';
+export * from './kart-status';
+export * from './module-name';
+export * from './payment-provider';
+export * from './payment-status';
+export * from './permission';
+export * from './user-role';
+export * from './racing-team-role';

package/src/__deprecated__/constants/racing-team-role.ts

@@ -0,0 +1,5 @@
+export const RACING_TEAM_ROLE = {
+  PILOT: 'PILOT',
+  TECHNICIAN: 'TECHNICIAN',
+  COACH: 'COACH',
+} as const;

package/src/__deprecated__/types/checkpoint/index.ts

@@ -0,0 +1,2 @@
+export * from './Checkpoint';
+export * from './CheckpointType';

package/src/__deprecated__/types/color/index.ts

@@ -0,0 +1,2 @@
+export * from './ColorInfo';
+export * from './ColorName';

package/src/__deprecated__/types/command/index.ts

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

package/src/__deprecated__/types/damage/DamageTarget.ts

@@ -0,0 +1 @@
+export type DamageTarget = 'Any' | 'All' | 'First' | 'Last' | 'Next' | 'Previous';

package/src/__deprecated__/types/damage/index.ts

@@ -0,0 +1,3 @@
+export * from './Damage';
+export * from './DamageName';
+export * from './DamageTarget';

package/src/__deprecated__/types/flow/index.ts

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

package/src/__deprecated__/types/game/GameWarningEvent.ts

@@ -0,0 +1 @@
+export type GameWarningEvent = 'yellow-flag' | 'red-flag';

package/src/__deprecated__/types/game/battle/index.ts

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

package/src/__deprecated__/types/game/index.ts

@@ -0,0 +1,7 @@
+export * from './battle';
+export * from './Game';
+export * from './GameStatus';
+export * from './GameType';
+export * from './GameWarningEvent';
+export * from './KartRankingItem';
+export * from './race';

package/src/__deprecated__/types/game/race/index.ts

@@ -0,0 +1,3 @@
+export * from './KartProgress';
+export * from './Race';
+export * from './LapTime';

package/src/__deprecated__/types/gameTrack/index.ts

@@ -0,0 +1,4 @@
+export * from './GameTrack';
+export * from './GameTrackGameDefaultValues';
+export * from './GameTrackKartConfig';
+export * from './GameTrackKartsConfig';

package/src/__deprecated__/types/hardware/ballSensor/BallSensorCommand.ts

@@ -0,0 +1 @@
+export type BallSensorCommand = 'Deactivate Sensor' | 'Activate Sensor' | 'Configure Module';

package/src/__deprecated__/types/hardware/ballSensor/BallSensorStatus.ts

@@ -0,0 +1 @@
+export type BallSensorStatus = 'Sensor Standby' | 'Sensor Deactivated' | 'Sensor Activated' | 'Sensor Hit' | 'Unknown';

package/src/__deprecated__/types/hardware/ballSensor/index.ts

@@ -0,0 +1,4 @@
+export * from './BallSensorCommand';
+export * from './BallSensorDiskThrowerModuleStatus';
+export * from './BallSensorStatus';
+export * from './ConfigureBallSensorDiskThrowerModuleOptions';

package/src/__deprecated__/types/hardware/ballShooter/BallShooterCommand.ts

@@ -0,0 +1 @@
+export type BallShooterCommand = 'Shooter Off' | 'Shooter Ready' | 'Shooter Attack';

package/src/__deprecated__/types/hardware/ballShooter/index.ts

@@ -0,0 +1,2 @@
+export * from './BallShooterCommand';
+export * from './BallShooterStatus';

package/src/__deprecated__/types/hardware/diskSensor/DiskSensorCommand.ts

@@ -0,0 +1 @@
+export type DiskSensorCommand = 'Deactivate Sensor' | 'Activate Sensor' | 'Calibrate Sensor' | 'Configure Module';

package/src/__deprecated__/types/hardware/diskSensor/index.ts

@@ -0,0 +1,4 @@
+export * from './ConfigDiskSensorBallShooterModuleOptions';
+export * from './DiskSensorBallShooterModuleStatus';
+export * from './DiskSensorCommand';
+export * from './DiskSensorStatus';

package/src/__deprecated__/types/hardware/diskThrower/DiskThrowerCommand.ts

@@ -0,0 +1 @@
+export type DiskThrowerCommand = 'Activate Thrower' | 'Deactivate Thrower' | 'Throw Disk';

package/src/__deprecated__/types/hardware/diskThrower/DiskThrowerStatus.ts

@@ -0,0 +1 @@
+export type DiskThrowerStatus = 'Thrower Deactivated' | 'Thrower Activated' | 'Throwing Disk' | 'Unknown';

package/src/__deprecated__/types/hardware/diskThrower/index.ts

@@ -0,0 +1,2 @@
+export * from './DiskThrowerCommand';
+export * from './DiskThrowerStatus';