@fiado/type-kit 3.310.0 → 3.311.0

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

@@ -0,0 +1,148 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { RegisterCardBatchRequest } from '../../../src/retailCards/dtos/requests/RegisterCardBatchRequest';
+import { RegisterCardDeliveryRequest } from '../../../src/retailCards/dtos/requests/RegisterCardDeliveryRequest';
+import { WriteOffCardStockRequest } from '../../../src/retailCards/dtos/requests/WriteOffCardStockRequest';
+import { ReverseCardMovementRequest } from '../../../src/retailCards/dtos/requests/ReverseCardMovementRequest';
+import { CardWriteOffReasonEnum } from '../../../src/retailCards/enums/CardWriteOffReasonEnum';
+
+/** Valida como lo hace `retail-cards-business`: sin `excludeExtraneousValues`, o sea sin `@Expose`. */
+function errorsOf<T extends object>(cls: new () => T, payload: Record<string, unknown>): string[] {
+    const dto = plainToInstance(cls, payload);
+    return validateSync(dto).map((e) => e.property);
+}
+
+describe('RegisterCardBatchRequest — el lote se recibe por cantidad, no por números', () => {
+    it('acepta cantidad + folio de la remesa del proveedor', () => {
+        expect(
+            errorsOf(RegisterCardBatchRequest, {
+                storeId: 'STORE#1',
+                quantity: 50,
+                supplierBatchRef: 'REMESA-2026-001',
+            }),
+        ).toEqual([]);
+    });
+
+    it('el folio del proveedor es obligatorio: es lo único que distingue dos remesas iguales', () => {
+        expect(
+            errorsOf(RegisterCardBatchRequest, { storeId: 'STORE#1', quantity: 50 }),
+        ).toContain('supplierBatchRef');
+    });
+
+    it('rechaza una cantidad de 0, negativa o fraccionaria', () => {
+        for (const quantity of [0, -1, 1.5]) {
+            expect(
+                errorsOf(RegisterCardBatchRequest, {
+                    storeId: 'STORE#1',
+                    quantity,
+                    supplierBatchRef: 'REMESA-2026-001',
+                }),
+            ).toContain('quantity');
+        }
+    });
+
+    it('rechaza una cantidad por encima del tope de 1000', () => {
+        expect(
+            errorsOf(RegisterCardBatchRequest, {
+                storeId: 'STORE#1',
+                quantity: 1001,
+                supplierBatchRef: 'REMESA-2026-001',
+            }),
+        ).toContain('quantity');
+    });
+
+    it('las notas son opcionales', () => {
+        expect(
+            errorsOf(RegisterCardBatchRequest, {
+                storeId: 'STORE#1',
+                quantity: 1,
+                supplierBatchRef: 'REMESA-2026-001',
+                notes: 'llegó abierta una caja',
+            }),
+        ).toEqual([]);
+    });
+});
+
+describe('RegisterCardDeliveryRequest — entrega en un solo acto, idempotente por sesión', () => {
+    it('acepta la entrega mínima', () => {
+        expect(
+            errorsOf(RegisterCardDeliveryRequest, {
+                customerId: 'CUS#1',
+                deliveredByUserId: 'USR#1',
+                sessionId: 'SES#1',
+            }),
+        ).toEqual([]);
+    });
+
+    it('el sessionId es obligatorio: es la clave de idempotencia de la entrega', () => {
+        expect(
+            errorsOf(RegisterCardDeliveryRequest, {
+                customerId: 'CUS#1',
+                deliveredByUserId: 'USR#1',
+            }),
+        ).toContain('sessionId');
+    });
+
+    it('exige cliente y vendedor', () => {
+        const errors = errorsOf(RegisterCardDeliveryRequest, { sessionId: 'SES#1' });
+        expect(errors).toContain('customerId');
+        expect(errors).toContain('deliveredByUserId');
+    });
+
+    it('el creditId es opcional (solo ventas a crédito)', () => {
+        expect(
+            errorsOf(RegisterCardDeliveryRequest, {
+                customerId: 'CUS#1',
+                deliveredByUserId: 'USR#1',
+                sessionId: 'SES#1',
+                creditId: 'CRE#1',
+            }),
+        ).toEqual([]);
+    });
+});
+
+describe('WriteOffCardStockRequest — baja de inventario por cantidad', () => {
+    it('acepta cantidad + motivo del catálogo', () => {
+        expect(
+            errorsOf(WriteOffCardStockRequest, {
+                quantity: 3,
+                reason: CardWriteOffReasonEnum.PLASTIC_DAMAGED,
+            }),
+        ).toEqual([]);
+    });
+
+    it('rechaza un motivo fuera del catálogo', () => {
+        expect(
+            errorsOf(WriteOffCardStockRequest, { quantity: 3, reason: 'THEFT_REPORTED' }),
+        ).toContain('reason');
+    });
+
+    it('rechaza una cantidad de 0 o fraccionaria', () => {
+        for (const quantity of [0, 2.5]) {
+            expect(
+                errorsOf(WriteOffCardStockRequest, {
+                    quantity,
+                    reason: CardWriteOffReasonEnum.LOST,
+                }),
+            ).toContain('quantity');
+        }
+    });
+});
+
+describe('ReverseCardMovementRequest — revierte un asiento del libro mayor', () => {
+    it('acepta el asiento a revertir con su motivo', () => {
+        expect(
+            errorsOf(ReverseCardMovementRequest, {
+                movementSk: 'MOV#2026-08-14T10:00:00.000Z#abc',
+                reason: 'venta cancelada en mostrador',
+            }),
+        ).toEqual([]);
+    });
+
+    it('exige el asiento y el motivo', () => {
+        const errors = errorsOf(ReverseCardMovementRequest, {});
+        expect(errors).toContain('movementSk');
+        expect(errors).toContain('reason');
+    });
+});

package/bin/remittance/dtos/RemittanceFavoriteItem.d.ts

@@ -0,0 +1,44 @@
+import { ReceptionMethod } from "../enums/ReceptionMethod";
+import { RemittanceCountryISO } from "../enums/RemittanceCountryISO";
+/**
+ * Estado del beneficiario tal como lo ve el listado de favoritos de remesa.
+ * `UNKNOWN` = no se pudo enriquecer (el connector no respondió, o respondió y ese
+ * beneficiario no vino en su lista — favorito huérfano).
+ */
+export type RemittanceFavoriteStatus = "ACTIVE" | "DEACTIVATED" | "UNKNOWN";
+/**
+ * Ítem de `GET /remittance/favorites`. Shape PLANO: mezcla lo propio de
+ * benefits-marketplace (alias, foto, orden, uso) con los datos vivos del beneficiario
+ * que devuelve uniteller-connector.
+ *
+ * Los campos del beneficiario son opcionales porque el listado degrada al snapshot
+ * denormalizado local cuando el connector no está disponible (`enriched: false`).
+ */
+export declare class RemittanceFavoriteItem {
+    id: string;
+    alias: string | null;
+    photo: string | null;
+    position: number;
+    usageCount: number;
+    lastUsedAt: number;
+    /** Handle opaco de UNIR. Viaja en claro, igual que en `FavoriteItem`. */
+    beneficiaryId: string;
+    firstName?: string;
+    middleName?: string;
+    lastName?: string;
+    secondLastName?: string;
+    phone?: string;
+    countryISO?: RemittanceCountryISO;
+    currencyISO?: string;
+    receptionMethod?: ReceptionMethod;
+    payerCode?: string;
+    payerName?: string;
+    payerBranchCode?: string;
+    payerBranchName?: string;
+    /** Cuenta completa para display (pedido de producto 2026-08-11). */
+    accNumber?: string;
+    accNumberLastFour?: string;
+    status: RemittanceFavoriteStatus;
+    /** `false` cuando el item se sirve solo con el snapshot denormalizado local. */
+    enriched: boolean;
+}

package/bin/remittance/dtos/RemittanceFavoriteItem.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemittanceFavoriteItem = void 0;
+/**
+ * Ítem de `GET /remittance/favorites`. Shape PLANO: mezcla lo propio de
+ * benefits-marketplace (alias, foto, orden, uso) con los datos vivos del beneficiario
+ * que devuelve uniteller-connector.
+ *
+ * Los campos del beneficiario son opcionales porque el listado degrada al snapshot
+ * denormalizado local cuando el connector no está disponible (`enriched: false`).
+ */
+class RemittanceFavoriteItem {
+}
+exports.RemittanceFavoriteItem = RemittanceFavoriteItem;

package/bin/remittance/dtos/RemittanceFavoriteListResponse.d.ts

@@ -0,0 +1,14 @@
+import { RemittanceFavoriteItem } from "./RemittanceFavoriteItem";
+/**
+ * Respuesta de `GET /remittance/favorites`.
+ *
+ * `totalActive` / `maxActive` son el cupo de beneficiarios de UniTeller: son
+ * GLOBALES del usuario y NO se ven afectados por el filtro `countryISO` — sirven
+ * para que el front sepa si puede dar de alta otro beneficiario. Ambos quedan
+ * ausentes si el connector no respondió.
+ */
+export declare class RemittanceFavoriteListResponse {
+    items: RemittanceFavoriteItem[];
+    totalActive?: number;
+    maxActive?: number;
+}

package/bin/remittance/dtos/RemittanceFavoriteListResponse.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemittanceFavoriteListResponse = void 0;
+/**
+ * Respuesta de `GET /remittance/favorites`.
+ *
+ * `totalActive` / `maxActive` son el cupo de beneficiarios de UniTeller: son
+ * GLOBALES del usuario y NO se ven afectados por el filtro `countryISO` — sirven
+ * para que el front sepa si puede dar de alta otro beneficiario. Ambos quedan
+ * ausentes si el connector no respondió.
+ */
+class RemittanceFavoriteListResponse {
+}
+exports.RemittanceFavoriteListResponse = RemittanceFavoriteListResponse;

package/bin/remittance/dtos/index.d.ts

@@ -46,3 +46,5 @@ export * from "./RemittanceRule";
 export * from "./RemittancePricingTable";
 export * from "./RemittanceExceptionCatalog";
 export * from "./RemittanceCountryConfig";
+export * from "./RemittanceFavoriteItem";
+export * from "./RemittanceFavoriteListResponse";

package/bin/remittance/dtos/index.js

@@ -62,3 +62,5 @@ __exportStar(require("./RemittanceRule"), exports);
 __exportStar(require("./RemittancePricingTable"), exports);
 __exportStar(require("./RemittanceExceptionCatalog"), exports);
 __exportStar(require("./RemittanceCountryConfig"), exports);
+__exportStar(require("./RemittanceFavoriteItem"), exports);
+__exportStar(require("./RemittanceFavoriteListResponse"), exports);

package/bin/remittance/enums/RemittanceCountryISO.d.ts

@@ -7,5 +7,6 @@ export declare enum RemittanceCountryISO {
     GT = "GT",
     SV = "SV",
     HN = "HN",
+    NI = "NI",
     MX = "MX"
 }

package/bin/remittance/enums/RemittanceCountryISO.js

@@ -11,5 +11,6 @@ var RemittanceCountryISO;
     RemittanceCountryISO["GT"] = "GT";
     RemittanceCountryISO["SV"] = "SV";
     RemittanceCountryISO["HN"] = "HN";
+    RemittanceCountryISO["NI"] = "NI";
     RemittanceCountryISO["MX"] = "MX";
 })(RemittanceCountryISO || (exports.RemittanceCountryISO = RemittanceCountryISO = {}));

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

@@ -1,7 +1,11 @@
-/** Body del registro (recepción) de un lote de tarjetas para una tienda. */
+/**
+ * Body del registro (recepción) de un lote de tarjetas para una tienda. Los sobres llegan sellados:
+ * el lote lleva cantidad, no números.
+ */
 export declare class RegisterCardBatchRequest {
     storeId: string;
-    totalCards: number;
-    cardNumbers: string[];
+    quantity: number;
+    /** Folio de la remesa del proveedor: lo único que distingue dos entradas iguales a la misma tienda. */
+    supplierBatchRef: string;
     notes?: string | null;
 }

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

@@ -11,7 +11,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegisterCardBatchRequest = void 0;
 const class_validator_1 = require("class-validator");
-/** Body del registro (recepción) de un lote de tarjetas para una tienda. */
+/**
+ * Body del registro (recepción) de un lote de tarjetas para una tienda. Los sobres llegan sellados:
+ * el lote lleva cantidad, no números.
+ */
 class RegisterCardBatchRequest {
 }
 exports.RegisterCardBatchRequest = RegisterCardBatchRequest;
@@ -24,13 +27,11 @@ __decorate([
     (0, class_validator_1.Min)(1),
     (0, class_validator_1.Max)(1000),
     __metadata("design:type", Number)
-], RegisterCardBatchRequest.prototype, "totalCards", void 0);
+], RegisterCardBatchRequest.prototype, "quantity", void 0);
 __decorate([
-    (0, class_validator_1.IsArray)(),
-    (0, class_validator_1.ArrayMaxSize)(1000),
-    (0, class_validator_1.IsString)({ each: true }),
-    __metadata("design:type", Array)
-], RegisterCardBatchRequest.prototype, "cardNumbers", void 0);
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RegisterCardBatchRequest.prototype, "supplierBatchRef", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.IsString)(),

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

@@ -0,0 +1,11 @@
+/**
+ * Body de la entrega de una tarjeta física a un cliente. Descuenta el saldo de la tienda y asienta el
+ * movimiento en una sola operación: en mostrador asignar y entregar son el mismo acto.
+ */
+export declare class RegisterCardDeliveryRequest {
+    customerId: string;
+    deliveredByUserId: string;
+    /** Clave de idempotencia de la entrega: un reintento devuelve el `deliveryId` original. */
+    sessionId: string;
+    creditId?: string;
+}

package/bin/{retailWizard/dtos/requests/MarkPcfCardDeliveredRequest.js → retailCards/dtos/requests/RegisterCardDeliveryRequest.js}

@@ -9,15 +9,29 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkPcfCardDeliveredRequest = void 0;
-const class_transformer_1 = require("class-transformer");
+exports.RegisterCardDeliveryRequest = void 0;
 const class_validator_1 = require("class-validator");
-/** POST /wizard/sessions/:id/pcf-card/mark-delivered — marca la tarjeta física PCF como entregada (S7). SureKeep Fase 2 — pista Retail. */
-class MarkPcfCardDeliveredRequest {
+/**
+ * Body de la entrega de una tarjeta física a un cliente. Descuenta el saldo de la tienda y asienta el
+ * movimiento en una sola operación: en mostrador asignar y entregar son el mismo acto.
+ */
+class RegisterCardDeliveryRequest {
 }
-exports.MarkPcfCardDeliveredRequest = MarkPcfCardDeliveredRequest;
+exports.RegisterCardDeliveryRequest = RegisterCardDeliveryRequest;
 __decorate([
-    (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
-], MarkPcfCardDeliveredRequest.prototype, "cardNumber", void 0);
+], RegisterCardDeliveryRequest.prototype, "customerId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RegisterCardDeliveryRequest.prototype, "deliveredByUserId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RegisterCardDeliveryRequest.prototype, "sessionId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RegisterCardDeliveryRequest.prototype, "creditId", void 0);

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

@@ -0,0 +1,9 @@
+/**
+ * Body del contraasiento que revierte un movimiento del libro mayor. No borra el asiento original:
+ * escribe uno nuevo que lo compensa.
+ */
+export declare class ReverseCardMovementRequest {
+    /** `sk` del asiento que se revierte (`MOV#<isoTs>#<uuid>`). */
+    movementSk: string;
+    reason: string;
+}

package/bin/retailCards/dtos/requests/{AssignCardRequest.js → ReverseCardMovementRequest.js}

@@ -9,22 +9,20 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AssignCardRequest = void 0;
+exports.ReverseCardMovementRequest = void 0;
 const class_validator_1 = require("class-validator");
-/** Body de la asignación de una tarjeta física a un cliente. */
-class AssignCardRequest {
+/**
+ * Body del contraasiento que revierte un movimiento del libro mayor. No borra el asiento original:
+ * escribe uno nuevo que lo compensa.
+ */
+class ReverseCardMovementRequest {
 }
-exports.AssignCardRequest = AssignCardRequest;
+exports.ReverseCardMovementRequest = ReverseCardMovementRequest;
 __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
-], AssignCardRequest.prototype, "assignedToCustomerId", void 0);
+], ReverseCardMovementRequest.prototype, "movementSk", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
-], AssignCardRequest.prototype, "assignedByUserId", void 0);
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], AssignCardRequest.prototype, "creditId", void 0);
+], ReverseCardMovementRequest.prototype, "reason", void 0);

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

@@ -0,0 +1,7 @@
+import { CardWriteOffReasonEnum } from '../../enums/CardWriteOffReasonEnum';
+/** Body de la baja de inventario de tarjetas de una tienda, por cantidad. */
+export declare class WriteOffCardStockRequest {
+    quantity: number;
+    reason: CardWriteOffReasonEnum;
+    notes?: string | null;
+}

package/bin/{retailWizard/dtos/requests/CompleteSaleRequest.js → retailCards/dtos/requests/WriteOffCardStockRequest.js}

@@ -9,21 +9,24 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CompleteSaleRequest = void 0;
-const class_transformer_1 = require("class-transformer");
+exports.WriteOffCardStockRequest = void 0;
 const class_validator_1 = require("class-validator");
-/**
- * POST /wizard/sessions/:id/complete-sale — cierra la venta (saga de 2 pasos, flujo 09). Exige
- * payment registrado (regla dura). Consume el IMEI del silo (SOLD), asigna la tarjeta PCF, persiste
- * la Sale con `UNIQ#FOLIO` y emite el outbox `SaleCompletedV1` en la MISMA tx. Cierra el prospecto
- * vinculado si lo hay. `cardNumber` = tarjeta física entregada en tienda (S7). SureKeep Fase 2 — pista Retail.
- */
-class CompleteSaleRequest {
+const CardWriteOffReasonEnum_1 = require("../../enums/CardWriteOffReasonEnum");
+/** Body de la baja de inventario de tarjetas de una tienda, por cantidad. */
+class WriteOffCardStockRequest {
 }
-exports.CompleteSaleRequest = CompleteSaleRequest;
+exports.WriteOffCardStockRequest = WriteOffCardStockRequest;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], WriteOffCardStockRequest.prototype, "quantity", void 0);
+__decorate([
+    (0, class_validator_1.IsEnum)(CardWriteOffReasonEnum_1.CardWriteOffReasonEnum),
+    __metadata("design:type", String)
+], WriteOffCardStockRequest.prototype, "reason", void 0);
 __decorate([
-    (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
-], CompleteSaleRequest.prototype, "cardNumber", void 0);
+], WriteOffCardStockRequest.prototype, "notes", void 0);

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

@@ -1,17 +1,15 @@
-import { CardBatchStatusEnum } from '../../enums/CardBatchStatusEnum';
-/** Representación de un lote de tarjetas hacia el cliente. */
+/**
+ * Lote de tarjetas recibido por una tienda (`sk = BATCH#<isoTs>#<uuid>`). Es un hecho histórico: el
+ * lote no cambia de estado ni lleva conteos, esos viven en el saldo.
+ */
 export interface CardBatchResponse {
-    batchId: string;
-    retailerId: string;
+    batchSk: string;
+    /** Folio de la remesa del proveedor. */
+    supplierBatchRef: string;
     storeId: string;
-    totalCards: number;
-    expectedCardCount: number;
-    loadedCount: number;
-    availableCount: number;
-    assignedCount: number;
-    cancelledCount: number;
-    status: CardBatchStatusEnum;
+    retailerId: string;
+    quantity: number;
+    notes: string | null;
     receivedAt: string;
     receivedByUserId: string;
-    notes: string | null;
 }

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

@@ -0,0 +1,11 @@
+/**
+ * Resultado de entregar una tarjeta física a un cliente. Un reintento con el mismo `sessionId`
+ * devuelve este mismo `deliveryId` con 200, no un error.
+ */
+export interface CardDeliveryResponse {
+    deliveryId: string;
+    movementSk: string;
+    /** Saldo disponible que quedó en la tienda después de descontar la entrega. */
+    availableAfter: number;
+    occurredAt: string;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Saldo vigente de tarjetas físicas de una tienda (`sk = BALANCE`). Es reconstruible sumando los
+ * asientos del libro mayor.
+ */
+export interface CardStockBalanceResponse {
+    storeId: string;
+    retailerId: string;
+    /** Unidades disponibles para entregar. Sin saldo no hay entrega. */
+    available: number;
+    deliveredTotal: number;
+    writtenOffTotal: number;
+    updatedAt: string;
+}

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

@@ -0,0 +1,19 @@
+import { CardStockMovementTypeEnum } from '../../enums/CardStockMovementTypeEnum';
+import { CardWriteOffReasonEnum } from '../../enums/CardWriteOffReasonEnum';
+/** Asiento del libro mayor de tarjetas de una tienda (`sk = MOV#<isoTs>#<uuid>`). */
+export interface CardStockMovementResponse {
+    movementSk: string;
+    type: CardStockMovementTypeEnum;
+    /** Con signo: positiva en las entradas, negativa en las salidas. */
+    quantity: number;
+    occurredAt: string;
+    actorUserId: string;
+    /** Cliente que recibió la tarjeta; solo en `OUT_DELIVERY`. */
+    customerId: string | null;
+    /** Motivo catalogado de la baja; solo en `OUT_WRITE_OFF`. */
+    reason: CardWriteOffReasonEnum | null;
+    /** Explicación libre del contraasiento; solo en `REVERSAL`. */
+    reversalReason: string | null;
+    /** `sk` referenciado: el lote en `IN_BATCH`, el asiento revertido en `REVERSAL`. */
+    refSk: string | null;
+}

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

@@ -0,0 +1,12 @@
+import { CardStockBalanceResponse } from './CardStockBalanceResponse';
+import { CardStockMovementResponse } from './CardStockMovementResponse';
+/**
+ * Pantalla de inventario de una tienda: el saldo vigente más una página de asientos. Ambos salen de
+ * la misma partición, así que viajan en una sola respuesta.
+ */
+export interface CardStockResponse {
+    balance: CardStockBalanceResponse;
+    movements: CardStockMovementResponse[];
+    count: number;
+    nextToken?: string;
+}

package/bin/retailCards/enums/CardStockMovementTypeEnum.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tipo de asiento del libro mayor de tarjetas físicas (`sk = MOV#<isoTs>#<uuid>`).
+ * @enum {string}
+ *
+ * @property {string} IN_BATCH - Entrada por recepción de un lote del proveedor (cantidad positiva).
+ * @property {string} OUT_DELIVERY - Salida por entrega de una tarjeta a un cliente en mostrador.
+ * @property {string} OUT_WRITE_OFF - Salida por baja de inventario (plástico dañado, extravío, robo).
+ * @property {string} REVERSAL - Contraasiento que revierte un movimiento previo vía `refSk`.
+ */
+export declare enum CardStockMovementTypeEnum {
+    IN_BATCH = "IN_BATCH",
+    OUT_DELIVERY = "OUT_DELIVERY",
+    OUT_WRITE_OFF = "OUT_WRITE_OFF",
+    REVERSAL = "REVERSAL"
+}

package/bin/retailCards/enums/CardStockMovementTypeEnum.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardStockMovementTypeEnum = void 0;
+/**
+ * Tipo de asiento del libro mayor de tarjetas físicas (`sk = MOV#<isoTs>#<uuid>`).
+ * @enum {string}
+ *
+ * @property {string} IN_BATCH - Entrada por recepción de un lote del proveedor (cantidad positiva).
+ * @property {string} OUT_DELIVERY - Salida por entrega de una tarjeta a un cliente en mostrador.
+ * @property {string} OUT_WRITE_OFF - Salida por baja de inventario (plástico dañado, extravío, robo).
+ * @property {string} REVERSAL - Contraasiento que revierte un movimiento previo vía `refSk`.
+ */
+var CardStockMovementTypeEnum;
+(function (CardStockMovementTypeEnum) {
+    CardStockMovementTypeEnum["IN_BATCH"] = "IN_BATCH";
+    CardStockMovementTypeEnum["OUT_DELIVERY"] = "OUT_DELIVERY";
+    CardStockMovementTypeEnum["OUT_WRITE_OFF"] = "OUT_WRITE_OFF";
+    CardStockMovementTypeEnum["REVERSAL"] = "REVERSAL";
+})(CardStockMovementTypeEnum || (exports.CardStockMovementTypeEnum = CardStockMovementTypeEnum = {}));

package/bin/retailCards/enums/CardWriteOffReasonEnum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Motivo de una baja de inventario de tarjetas físicas por cantidad.
+ * @enum {string}
+ *
+ * @property {string} PLASTIC_DAMAGED - Plásticos dañados, inservibles para entregar.
+ * @property {string} LOST - Unidades extraviadas en la tienda.
+ * @property {string} STOLEN - Unidades robadas del inventario de la tienda.
+ */
+export declare enum CardWriteOffReasonEnum {
+    PLASTIC_DAMAGED = "PLASTIC_DAMAGED",
+    LOST = "LOST",
+    STOLEN = "STOLEN"
+}

package/bin/retailCards/enums/CardWriteOffReasonEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardWriteOffReasonEnum = void 0;
+/**
+ * Motivo de una baja de inventario de tarjetas físicas por cantidad.
+ * @enum {string}
+ *
+ * @property {string} PLASTIC_DAMAGED - Plásticos dañados, inservibles para entregar.
+ * @property {string} LOST - Unidades extraviadas en la tienda.
+ * @property {string} STOLEN - Unidades robadas del inventario de la tienda.
+ */
+var CardWriteOffReasonEnum;
+(function (CardWriteOffReasonEnum) {
+    CardWriteOffReasonEnum["PLASTIC_DAMAGED"] = "PLASTIC_DAMAGED";
+    CardWriteOffReasonEnum["LOST"] = "LOST";
+    CardWriteOffReasonEnum["STOLEN"] = "STOLEN";
+})(CardWriteOffReasonEnum || (exports.CardWriteOffReasonEnum = CardWriteOffReasonEnum = {}));

package/bin/retailCards/events/CardBatchReceivedV1.d.ts

@@ -1,9 +1,11 @@
-/** Emitido cuando un lote de tarjetas se recibe (RECEIVED). */
+/** Emitido cuando una tienda recibe un lote de tarjetas físicas. */
 export interface CardBatchReceivedV1 {
-    batchId: string;
+    /** `sk` del lote en la partición de la tienda (`BATCH#<isoTs>#<uuid>`). */
+    batchSk: string;
+    supplierBatchRef: string;
     retailerId: string;
     storeId: string;
-    totalCards: number;
+    quantity: number;
     receivedByUserId: string;
     occurredAt: string;
 }