@battle-racing/br-common-lib 5.0.0-rc.0 → 6.0.0

package/RELEASING.md

@@ -0,0 +1,111 @@
+# Publicar versiones de `br-common-lib`
+
+Esta librería la consumen cuatro repositorios (`game-manager-backend`, `kart-manager`,
+`webapp-battle-racing`, `screen-web-RPI`). Un cambio incompatible los rompe a todos, así que
+todo cambio se prueba primero como **release candidate (RC)** y solo se publica como versión
+oficial cuando ya se validó el cambio.
+
+Hay dos roles:
+
+| Rol                     | Qué publica        | Cómo                                 |
+| :---------------------- | :----------------- | :----------------------------------- |
+| Cualquier desarrollador | RCs (`X.Y.Z-rc.N`) | GitHub Actions → **Publish RC**      |
+| Mantenedor              | Versión oficial    | `npm run release:*` desde su máquina |
+
+---
+
+## Elegir el bump: la tabla que evita el error
+
+Esta es la parte donde se equivoca todo el mundo. La pregunta no es "qué tan grande es mi
+cambio", sino **"¿es la primera RC de este cambio, o ya venía iterando?"**
+
+| Situación                                                | Bump         | Ejemplo desde `6.0.0-rc.0` |
+| :------------------------------------------------------- | :----------- | :------------------------- |
+| **Primera** RC de un cambio incompatible                 | `premajor`   | `7.0.0-rc.0`               |
+| **Primera** RC de una funcionalidad retrocompatible      | `preminor`   | `6.1.0-rc.0`               |
+| **Primera** RC de un arreglo menor                       | `prepatch`   | `6.0.1-rc.0`               |
+| **Otra** RC del mismo cambio (corregir algo, reintentar) | `prerelease` | `6.0.0-rc.1`               |
+
+> **La regla:** `premajor` / `preminor` / `prepatch` se usan **una sola vez por cambio**.
+> A partir de ahí, siempre `prerelease`.
+
+Si te equivocas y usas `premajor` dos veces, terminas con una versión mayor que nunca existió
+como release (`5.0.0` saltando a `6.0.0`). El error que cometió el bruto de JD **No es grave y no hay que arreglarlo:** `latest` no
+se movió y nadie consumió esa versión. Sigue con `prerelease` desde donde quedaste. Las
+versiones publicadas en npm no se pueden reutilizar ni borrar, así que no intentes "volver atrás".
+
+---
+
+## Publicar una RC
+
+0. Has push de tu rama.
+1. Repositorio → pestaña **Actions**
+2. En la barra izquierda: **Publish RC**
+3. **Run workflow**
+4. **Branch:** la rama que estás probando
+5. **Version bump:** según la tabla de arriba
+6. **Run workflow**
+
+Al terminar, abrí el run → **Summary**. Ahí está la línea lista para pegar en el consumidor.
+
+### Probarla en un consumidor
+
+Versión **exacta**, sin `^`:
+
+```json
+"@battle-racing/br-common-lib": "6.0.0-rc.1"
+```
+
+El caret con prereleases se comporta de forma poco intuitiva, y sobre hardware querés saber
+exactamente qué build está corriendo.
+
+```bash
+npm install @battle-racing/br-common-lib@6.0.0-rc.1
+```
+
+### Verificar que salió bien
+
+```bash
+npm view @battle-racing/br-common-lib dist-tags
+# esperado:  { latest: '<la oficial>', rc: '6.0.0-rc.1' }
+```
+
+Si `latest` se movió, algo está mal en el workflow. Pará y avisá antes de seguir.
+
+---
+
+## Publicar la versión oficial
+
+Solo el mantenedor, y solo cuando la RC ya se validó en pista.
+
+```bash
+git checkout main && git pull
+npm run release:major     # o release:minor / release:patch
+```
+
+Desde `6.0.0-rc.3`, `release:major` publica `6.0.0` — quita el sufijo de RC, no salta a `7.0.0`.
+
+Después, repinear los consumidores a la versión final y quitar el pin exacto de la RC.
+
+---
+
+## Qué protege a `latest`
+
+- El workflow tiene `--tag rc` **hardcodeado**, sin input. Desde Actions no se puede mover `latest`.
+- Los rangos de semver nunca resuelven a prereleases salvo que se pidan explícitamente: un
+  consumidor en `^4.9.1` no va a agarrar una `6.0.0-rc.0` ni por accidente.
+- La publicación usa **trusted publishing (OIDC)**: no hay token de npm en ningún lado.
+
+**Límite conocido:** al despachar el workflow se ejecuta la copia del `.yml` **de la rama
+seleccionada**. Quien tenga permiso de escritura puede editar ese archivo en su rama y quitar
+el `--tag rc`. La protección real contra eso es un Environment con revisor obligatorio, que
+requiere repo público o plan de pago.
+
+---
+
+## Notas
+
+- El commit y el tag de versión quedan en la rama desde la que publicaste. Al mergear a `main`
+  puede haber conflicto en el `package.json` si `main` avanzó por otro lado.
+- Las RC publicadas son públicas y permanentes (se pueden deprecar, pero solo desaparecen si se
+  despublican dentro de las primeras 72 horas).

package/dist/domains/game/swap-kart.schema.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const swapKartSchema: z.ZodObject<{
+    playerId: z.ZodString;
+    oldKartGuid: z.ZodString;
+    newKartGuid: z.ZodString;
+}, z.core.$strip>;
+export type SwapKartDto = z.infer<typeof swapKartSchema>;

package/dist/domains/game/swap-kart.schema.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swapKartSchema = void 0;
+const zod_1 = require("zod");
+exports.swapKartSchema = zod_1.z.object({
+    playerId: zod_1.z.string(),
+    oldKartGuid: zod_1.z.string(),
+    newKartGuid: zod_1.z.string(),
+});

package/dist/domains/socket/inputs/SocketInitRaspberryInput.d.ts

@@ -0,0 +1,4 @@
+export type SocketInitRaspberryInput = {
+    macAddress: string;
+    hostname: string;
+};

package/dist/domains/socket/inputs/SocketInitRaspberryInput.js

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

package/dist/domains/waiver/Waiver.const.d.ts

@@ -0,0 +1,15 @@
+export declare const WAIVER_SIGNER_ROLE: {
+    readonly SELF: "SELF";
+    readonly GUARDIAN: "GUARDIAN";
+};
+export declare const WAIVER_RELATIONSHIP: {
+    readonly PARENT: "PARENT";
+    readonly LEGAL_GUARDIAN: "LEGAL_GUARDIAN";
+    readonly OTHER: "OTHER";
+};
+export declare const WAIVER_CONTEXT_TYPE: {
+    readonly SESSION: "SESSION";
+    readonly RACING_TEAM: "RACING_TEAM";
+};
+export declare const WAIVER_VALIDITY_DAYS = 365;
+export declare const WAIVER_DRAFT_TEMPLATE_VERSION = "draft-1";

package/dist/domains/waiver/Waiver.const.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAIVER_DRAFT_TEMPLATE_VERSION = exports.WAIVER_VALIDITY_DAYS = exports.WAIVER_CONTEXT_TYPE = exports.WAIVER_RELATIONSHIP = exports.WAIVER_SIGNER_ROLE = void 0;
+exports.WAIVER_SIGNER_ROLE = {
+    SELF: 'SELF',
+    GUARDIAN: 'GUARDIAN',
+};
+exports.WAIVER_RELATIONSHIP = {
+    PARENT: 'PARENT',
+    LEGAL_GUARDIAN: 'LEGAL_GUARDIAN',
+    OTHER: 'OTHER',
+};
+exports.WAIVER_CONTEXT_TYPE = {
+    SESSION: 'SESSION',
+    RACING_TEAM: 'RACING_TEAM',
+};
+exports.WAIVER_VALIDITY_DAYS = 365;
+exports.WAIVER_DRAFT_TEMPLATE_VERSION = 'draft-1';

package/dist/domains/waiver/Waiver.schema.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare const waiverSignerRoleSchema: z.ZodEnum<{
+    readonly SELF: "SELF";
+    readonly GUARDIAN: "GUARDIAN";
+}>;
+export declare const waiverRelationshipSchema: z.ZodEnum<{
+    readonly PARENT: "PARENT";
+    readonly LEGAL_GUARDIAN: "LEGAL_GUARDIAN";
+    readonly OTHER: "OTHER";
+}>;
+export declare const waiverContextTypeSchema: z.ZodEnum<{
+    readonly SESSION: "SESSION";
+    readonly RACING_TEAM: "RACING_TEAM";
+}>;
+export declare const waiverTemplateSchema: z.ZodObject<{
+    version: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    hash: z.ZodString;
+    isActive: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodDate;
+}, z.core.$strip>;
+export declare const waiverContextSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        readonly SESSION: "SESSION";
+        readonly RACING_TEAM: "RACING_TEAM";
+    }>;
+    refId: z.ZodString;
+}, z.core.$strip>;
+export declare const waiverSignerSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        readonly SELF: "SELF";
+        readonly GUARDIAN: "GUARDIAN";
+    }>;
+    legalName: z.ZodString;
+    relationship: z.ZodOptional<z.ZodEnum<{
+        readonly PARENT: "PARENT";
+        readonly LEGAL_GUARDIAN: "LEGAL_GUARDIAN";
+        readonly OTHER: "OTHER";
+    }>>;
+    playerId: z.ZodOptional<z.ZodUUID>;
+    userId: z.ZodOptional<z.ZodUUID>;
+    contact: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const waiverRecordSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    playerId: z.ZodUUID;
+    signer: z.ZodObject<{
+        role: z.ZodEnum<{
+            readonly SELF: "SELF";
+            readonly GUARDIAN: "GUARDIAN";
+        }>;
+        legalName: z.ZodString;
+        relationship: z.ZodOptional<z.ZodEnum<{
+            readonly PARENT: "PARENT";
+            readonly LEGAL_GUARDIAN: "LEGAL_GUARDIAN";
+            readonly OTHER: "OTHER";
+        }>>;
+        playerId: z.ZodOptional<z.ZodUUID>;
+        userId: z.ZodOptional<z.ZodUUID>;
+        contact: z.ZodOptional<z.ZodString>;
+        documentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    context: z.ZodObject<{
+        type: z.ZodEnum<{
+            readonly SESSION: "SESSION";
+            readonly RACING_TEAM: "RACING_TEAM";
+        }>;
+        refId: z.ZodString;
+    }, z.core.$strip>;
+    templateVersion: z.ZodString;
+    templateHash: z.ZodString;
+    documentSnapshot: z.ZodString;
+    signature: z.ZodOptional<z.ZodString>;
+    acceptedAt: z.ZodDate;
+    expiresAt: z.ZodDate;
+    supersedesWaiverId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+    ipAddress: z.ZodOptional<z.ZodString>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodDate;
+}, z.core.$strip>;
+export declare const signWaiverSchema: z.ZodObject<{
+    accepted: z.ZodLiteral<true>;
+    signerRole: z.ZodDefault<z.ZodEnum<{
+        readonly SELF: "SELF";
+        readonly GUARDIAN: "GUARDIAN";
+    }>>;
+    legalName: z.ZodString;
+    relationship: z.ZodOptional<z.ZodEnum<{
+        readonly PARENT: "PARENT";
+        readonly LEGAL_GUARDIAN: "LEGAL_GUARDIAN";
+        readonly OTHER: "OTHER";
+    }>>;
+    signerPlayerId: z.ZodOptional<z.ZodUUID>;
+    signerContact: z.ZodOptional<z.ZodString>;
+    signerDocumentId: z.ZodOptional<z.ZodString>;
+    context: z.ZodObject<{
+        type: z.ZodEnum<{
+            readonly SESSION: "SESSION";
+            readonly RACING_TEAM: "RACING_TEAM";
+        }>;
+        refId: z.ZodString;
+    }, z.core.$strip>;
+    templateVersion: z.ZodString;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const filterWaiverSchema: z.ZodObject<{
+    playerId: z.ZodOptional<z.ZodUUID>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    racingTeamId: z.ZodOptional<z.ZodString>;
+    signerRole: z.ZodOptional<z.ZodEnum<{
+        readonly SELF: "SELF";
+        readonly GUARDIAN: "GUARDIAN";
+    }>>;
+}, z.core.$strip>;

package/dist/domains/waiver/Waiver.schema.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterWaiverSchema = exports.signWaiverSchema = exports.waiverRecordSchema = exports.waiverSignerSchema = exports.waiverContextSchema = exports.waiverTemplateSchema = exports.waiverContextTypeSchema = exports.waiverRelationshipSchema = exports.waiverSignerRoleSchema = void 0;
+const zod_1 = require("zod");
+const Waiver_const_1 = require("./Waiver.const");
+exports.waiverSignerRoleSchema = zod_1.z.enum(Waiver_const_1.WAIVER_SIGNER_ROLE);
+exports.waiverRelationshipSchema = zod_1.z.enum(Waiver_const_1.WAIVER_RELATIONSHIP);
+exports.waiverContextTypeSchema = zod_1.z.enum(Waiver_const_1.WAIVER_CONTEXT_TYPE);
+exports.waiverTemplateSchema = zod_1.z.object({
+    version: zod_1.z.string().min(1),
+    title: zod_1.z.string().min(1),
+    body: zod_1.z.string().min(1),
+    hash: zod_1.z.string().length(64),
+    isActive: zod_1.z.boolean().default(false),
+    createdAt: zod_1.z.date(),
+});
+exports.waiverContextSchema = zod_1.z.object({
+    type: exports.waiverContextTypeSchema,
+    refId: zod_1.z.string().min(1),
+});
+exports.waiverSignerSchema = zod_1.z.object({
+    role: exports.waiverSignerRoleSchema,
+    legalName: zod_1.z.string().min(3).max(120),
+    relationship: exports.waiverRelationshipSchema.optional(),
+    playerId: zod_1.z.uuidv4().optional(),
+    userId: zod_1.z.uuidv4().optional(),
+    contact: zod_1.z.string().max(60).optional(),
+    documentId: zod_1.z.string().max(60).optional(),
+});
+exports.waiverRecordSchema = zod_1.z.object({
+    id: zod_1.z.uuidv4(),
+    playerId: zod_1.z.uuidv4(),
+    signer: exports.waiverSignerSchema,
+    context: exports.waiverContextSchema,
+    templateVersion: zod_1.z.string().min(1),
+    templateHash: zod_1.z.string().length(64),
+    documentSnapshot: zod_1.z.string().min(1),
+    signature: zod_1.z.string().optional(),
+    acceptedAt: zod_1.z.date(),
+    expiresAt: zod_1.z.date(),
+    supersedesWaiverId: zod_1.z.uuidv4().nullable().optional(),
+    ipAddress: zod_1.z.string().max(45).optional(),
+    userAgent: zod_1.z.string().max(255).optional(),
+    createdAt: zod_1.z.date(),
+});
+exports.signWaiverSchema = zod_1.z
+    .object({
+    accepted: zod_1.z.literal(true),
+    signerRole: exports.waiverSignerRoleSchema.default(Waiver_const_1.WAIVER_SIGNER_ROLE.SELF),
+    legalName: zod_1.z.string().min(3).max(120),
+    relationship: exports.waiverRelationshipSchema.optional(),
+    signerPlayerId: zod_1.z.uuidv4().optional(),
+    signerContact: zod_1.z.string().max(60).optional(),
+    signerDocumentId: zod_1.z.string().max(60).optional(),
+    context: exports.waiverContextSchema,
+    templateVersion: zod_1.z.string().min(1),
+    signature: zod_1.z.string().optional(),
+})
+    .refine((input) => input.signerRole !== Waiver_const_1.WAIVER_SIGNER_ROLE.GUARDIAN || Boolean(input.relationship), {
+    message: 'relationship is required when signing as GUARDIAN',
+    path: ['relationship'],
+});
+exports.filterWaiverSchema = zod_1.z.object({
+    playerId: zod_1.z.uuidv4().optional(),
+    sessionId: zod_1.z.string().optional(),
+    racingTeamId: zod_1.z.string().optional(),
+    signerRole: exports.waiverSignerRoleSchema.optional(),
+});

package/dist/domains/waiver/Waiver.types.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { filterWaiverSchema, signWaiverSchema, waiverContextSchema, waiverContextTypeSchema, waiverRecordSchema, waiverRelationshipSchema, waiverSignerRoleSchema, waiverSignerSchema, waiverTemplateSchema } from './Waiver.schema';
+export type WaiverSignerRole = z.infer<typeof waiverSignerRoleSchema>;
+export type WaiverRelationship = z.infer<typeof waiverRelationshipSchema>;
+export type WaiverContextType = z.infer<typeof waiverContextTypeSchema>;
+export type WaiverTemplate = z.infer<typeof waiverTemplateSchema>;
+export type WaiverContext = z.infer<typeof waiverContextSchema>;
+export type WaiverSigner = z.infer<typeof waiverSignerSchema>;
+export type WaiverRecord = z.infer<typeof waiverRecordSchema>;
+export type SignWaiverInput = z.infer<typeof signWaiverSchema>;
+export type FilterWaiverInput = z.infer<typeof filterWaiverSchema>;

package/dist/domains/waiver/Waiver.types.js

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

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

@@ -0,0 +1,3 @@
+export * from './Waiver.const';
+export * from './Waiver.schema';
+export * from './Waiver.types';

package/dist/domains/waiver/index.js

@@ -0,0 +1,19 @@
+"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("./Waiver.const"), exports);
+__exportStar(require("./Waiver.schema"), exports);
+__exportStar(require("./Waiver.types"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battle-racing/br-common-lib",
-  "version": "5.0.0-rc.0",
+  "version": "6.0.0",
   "description": "Common library for all Battle Racing Repositorios",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -37,8 +37,5 @@
   },
   "peerDependencies": {
     "zod": "^4.4.3"
-  },
-  "dependencies": {
-    "@battle-racing/br-common-lib": "^4.6.1"
   }
 }