@fiado/type-kit 3.314.0 → 3.315.0

package/_test_/unit/retailCards/cardStockRequests.test.ts

@@ -30,6 +30,29 @@ describe('RegisterCardBatchRequest — el lote se recibe por cantidad, no por n
         ).toContain('supplierBatchRef');
     });
 
+    it('rechaza un folio en blanco: degradaría la clave del marcador a una constante por tienda', () => {
+        for (const supplierBatchRef of ['', '   ']) {
+            expect(
+                errorsOf(RegisterCardBatchRequest, {
+                    storeId: 'STORE#1',
+                    quantity: 50,
+                    supplierBatchRef,
+                }),
+            ).toContain('supplierBatchRef');
+        }
+    });
+
+    // El folio es la clave de idempotencia: sin recortar, reteclearlo con un espacio de más registra
+    // el mismo lote dos veces y suma el stock doble.
+    it('recorta los espacios del folio antes de que llegue al dominio', () => {
+        const dto = plainToInstance(RegisterCardBatchRequest, {
+            storeId: 'STORE#1',
+            quantity: 50,
+            supplierBatchRef: '  L-4471 ',
+        });
+        expect(dto.supplierBatchRef).toBe('L-4471');
+    });
+
     it('rechaza una cantidad de 0, negativa o fraccionaria', () => {
         for (const quantity of [0, -1, 1.5]) {
             expect(
@@ -103,18 +126,44 @@ describe('RegisterCardDeliveryRequest — entrega en un solo acto, idempotente p
 });
 
 describe('WriteOffCardStockRequest — baja de inventario por cantidad', () => {
-    it('acepta cantidad + motivo del catálogo', () => {
+    const OPERATION_ID = '3f1a9c52-8d0e-4b7a-9c31-6ad2f0e15b74';
+
+    it('acepta cantidad + motivo del catálogo + clave de operación', () => {
         expect(
             errorsOf(WriteOffCardStockRequest, {
                 quantity: 3,
                 reason: CardWriteOffReasonEnum.PLASTIC_DAMAGED,
+                operationId: OPERATION_ID,
             }),
         ).toEqual([]);
     });
 
+    it('la clave de operación es obligatoria: sin ella un doble clic descuenta dos veces', () => {
+        expect(
+            errorsOf(WriteOffCardStockRequest, {
+                quantity: 3,
+                reason: CardWriteOffReasonEnum.LOST,
+            }),
+        ).toContain('operationId');
+    });
+
+    it('rechaza una clave de operación que no sea un UUID', () => {
+        expect(
+            errorsOf(WriteOffCardStockRequest, {
+                quantity: 3,
+                reason: CardWriteOffReasonEnum.LOST,
+                operationId: 'baja-del-martes',
+            }),
+        ).toContain('operationId');
+    });
+
     it('rechaza un motivo fuera del catálogo', () => {
         expect(
-            errorsOf(WriteOffCardStockRequest, { quantity: 3, reason: 'THEFT_REPORTED' }),
+            errorsOf(WriteOffCardStockRequest, {
+                quantity: 3,
+                reason: 'THEFT_REPORTED',
+                operationId: OPERATION_ID,
+            }),
         ).toContain('reason');
     });
 
@@ -124,6 +173,7 @@ describe('WriteOffCardStockRequest — baja de inventario por cantidad', () => {
                 errorsOf(WriteOffCardStockRequest, {
                     quantity,
                     reason: CardWriteOffReasonEnum.LOST,
+                    operationId: OPERATION_ID,
                 }),
             ).toContain('quantity');
         }

package/bin/retailCards/dtos/requests/RegisterCardBatchRequest.d.ts

@@ -5,7 +5,10 @@
 export declare class RegisterCardBatchRequest {
     storeId: string;
     quantity: number;
-    /** Folio de la remesa del proveedor: lo único que distingue dos entradas iguales a la misma tienda. */
+    /**
+     * Folio de la remesa del proveedor: lo único que distingue dos entradas iguales a la misma tienda.
+     * Se recorta y no admite blanco, porque es la clave de idempotencia de la recepción.
+     */
     supplierBatchRef: string;
     notes?: string | null;
 }

package/bin/retailCards/dtos/requests/RegisterCardBatchRequest.js

@@ -10,6 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegisterCardBatchRequest = void 0;
+const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 /**
  * Body del registro (recepción) de un lote de tarjetas para una tienda. Los sobres llegan sellados:
@@ -30,6 +31,8 @@ __decorate([
 ], RegisterCardBatchRequest.prototype, "quantity", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
+    (0, class_transformer_1.Transform)(({ value }) => (typeof value === 'string' ? value.trim() : value)),
+    (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], RegisterCardBatchRequest.prototype, "supplierBatchRef", void 0);
 __decorate([

package/bin/retailCards/dtos/requests/WriteOffCardStockRequest.d.ts

@@ -3,5 +3,10 @@ import { CardWriteOffReasonEnum } from '../../enums/CardWriteOffReasonEnum';
 export declare class WriteOffCardStockRequest {
     quantity: number;
     reason: CardWriteOffReasonEnum;
+    /**
+     * Clave de idempotencia de la baja, generada por el caller una vez por intento. Un reintento
+     * devuelve el asiento original: sin ella un doble clic descontaría el doble.
+     */
+    operationId: string;
     notes?: string | null;
 }

package/bin/retailCards/dtos/requests/WriteOffCardStockRequest.js

@@ -25,6 +25,10 @@ __decorate([
     (0, class_validator_1.IsEnum)(CardWriteOffReasonEnum_1.CardWriteOffReasonEnum),
     __metadata("design:type", String)
 ], WriteOffCardStockRequest.prototype, "reason", void 0);
+__decorate([
+    (0, class_validator_1.IsUUID)(),
+    __metadata("design:type", String)
+], WriteOffCardStockRequest.prototype, "operationId", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.IsString)(),

package/bin/retailCards/dtos/responses/CardDeliveryResponse.d.ts

@@ -5,7 +5,10 @@
 export interface CardDeliveryResponse {
     deliveryId: string;
     movementSk: string;
-    /** Saldo disponible que quedó en la tienda después de descontar la entrega. */
-    availableAfter: number;
+    /**
+     * Saldo disponible de la tienda al momento de responder, leído después de la transacción. No es
+     * el saldo del instante del asiento: si otra entrega cae en medio, refleja las dos.
+     */
+    availableNow: number;
     occurredAt: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.314.0",
+  "version": "3.315.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/retailCards/dtos/requests/RegisterCardBatchRequest.ts

@@ -1,4 +1,5 @@
-import { IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { IsInt, IsNotEmpty, IsOptional, IsString, Max, Min } from 'class-validator';
 
 /**
  * Body del registro (recepción) de un lote de tarjetas para una tienda. Los sobres llegan sellados:
@@ -13,8 +14,13 @@ export class RegisterCardBatchRequest {
     @Max(1000)
     quantity!: number;
 
-    /** Folio de la remesa del proveedor: lo único que distingue dos entradas iguales a la misma tienda. */
+    /**
+     * Folio de la remesa del proveedor: lo único que distingue dos entradas iguales a la misma tienda.
+     * Se recorta y no admite blanco, porque es la clave de idempotencia de la recepción.
+     */
     @IsString()
+    @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+    @IsNotEmpty()
     supplierBatchRef!: string;
 
     @IsOptional()

package/src/retailCards/dtos/requests/WriteOffCardStockRequest.ts

@@ -1,4 +1,4 @@
-import { IsEnum, IsInt, IsOptional, IsString, Min } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, IsString, IsUUID, Min } from 'class-validator';
 import { CardWriteOffReasonEnum } from '../../enums/CardWriteOffReasonEnum';
 
 /** Body de la baja de inventario de tarjetas de una tienda, por cantidad. */
@@ -10,6 +10,13 @@ export class WriteOffCardStockRequest {
     @IsEnum(CardWriteOffReasonEnum)
     reason!: CardWriteOffReasonEnum;
 
+    /**
+     * Clave de idempotencia de la baja, generada por el caller una vez por intento. Un reintento
+     * devuelve el asiento original: sin ella un doble clic descontaría el doble.
+     */
+    @IsUUID()
+    operationId!: string;
+
     @IsOptional()
     @IsString()
     notes?: string | null;

package/src/retailCards/dtos/responses/CardDeliveryResponse.ts

@@ -5,7 +5,10 @@
 export interface CardDeliveryResponse {
     deliveryId: string;
     movementSk: string;
-    /** Saldo disponible que quedó en la tienda después de descontar la entrega. */
-    availableAfter: number;
+    /**
+     * Saldo disponible de la tienda al momento de responder, leído después de la transacción. No es
+     * el saldo del instante del asiento: si otra entrega cae en medio, refleja las dos.
+     */
+    availableNow: number;
     occurredAt: string;
 }