@fiado/type-kit 3.189.0 → 3.191.0

package/bin/retailCatalog/dtos/validation/ValidateProductResponse.d.ts

@@ -0,0 +1,20 @@
+import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
+import { MdmProviderEnum } from '../../enums/MdmProviderEnum';
+import { ProductStatusEnum } from '../../enums/ProductStatusEnum';
+import { ProductTierEnum } from '../../enums/ProductTierEnum';
+/**
+ * Response de GET /private/products/:retailerId/:sku — validar que el producto existe + status.
+ * Incluye los campos que los downstream consumen: `eligibleFinanciers` (wizard F2 paso 4)
+ * y la config MDM (device router F4+). Shape de salida → sin class-validator.
+ */
+export declare class ValidateProductResponse {
+    productId: string;
+    retailerId: string;
+    sku: string;
+    status: ProductStatusEnum;
+    tier: ProductTierEnum;
+    eligibleFinanciers: string[];
+    mdmEnabled: boolean;
+    mdmProvider: MdmProviderEnum | null;
+    mdmLockMode: MdmLockModeEnum | null;
+}

package/bin/retailCatalog/dtos/validation/ValidateProductResponse.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidateProductResponse = void 0;
+/**
+ * Response de GET /private/products/:retailerId/:sku — validar que el producto existe + status.
+ * Incluye los campos que los downstream consumen: `eligibleFinanciers` (wizard F2 paso 4)
+ * y la config MDM (device router F4+). Shape de salida → sin class-validator.
+ */
+class ValidateProductResponse {
+}
+exports.ValidateProductResponse = ValidateProductResponse;

package/bin/retailCatalog/enums/InventoryItemStatusEnum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado de una unidad física (IMEI) en inventario.
+ * Transiciones: AVAILABLE → RESERVED → SOLD/AVAILABLE (release); RETURNED desde SOLD; DAMAGED.
+ * @enum {string}
+ *
+ * @property {string} AVAILABLE - Disponible en stock.
+ * @property {string} RESERVED - Reservada para una venta en curso.
+ * @property {string} SOLD - Vendida.
+ * @property {string} RETURNED - Devuelta por el cliente.
+ * @property {string} DAMAGED - Dañada, fuera de stock vendible.
+ */
+export declare enum InventoryItemStatusEnum {
+    AVAILABLE = "AVAILABLE",
+    RESERVED = "RESERVED",
+    SOLD = "SOLD",
+    RETURNED = "RETURNED",
+    DAMAGED = "DAMAGED"
+}

package/bin/retailCatalog/enums/InventoryItemStatusEnum.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryItemStatusEnum = void 0;
+/**
+ * Estado de una unidad física (IMEI) en inventario.
+ * Transiciones: AVAILABLE → RESERVED → SOLD/AVAILABLE (release); RETURNED desde SOLD; DAMAGED.
+ * @enum {string}
+ *
+ * @property {string} AVAILABLE - Disponible en stock.
+ * @property {string} RESERVED - Reservada para una venta en curso.
+ * @property {string} SOLD - Vendida.
+ * @property {string} RETURNED - Devuelta por el cliente.
+ * @property {string} DAMAGED - Dañada, fuera de stock vendible.
+ */
+var InventoryItemStatusEnum;
+(function (InventoryItemStatusEnum) {
+    InventoryItemStatusEnum["AVAILABLE"] = "AVAILABLE";
+    InventoryItemStatusEnum["RESERVED"] = "RESERVED";
+    InventoryItemStatusEnum["SOLD"] = "SOLD";
+    InventoryItemStatusEnum["RETURNED"] = "RETURNED";
+    InventoryItemStatusEnum["DAMAGED"] = "DAMAGED";
+})(InventoryItemStatusEnum || (exports.InventoryItemStatusEnum = InventoryItemStatusEnum = {}));

package/bin/retailCatalog/enums/MdmLockModeEnum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Modo de bloqueo MDM. Valores del flow 04 de F1 (ONDEMAND/SCHEDULED).
+ *
+ * TD-007: el `DeviceLockModeEnum` del dominio `mdm` hoy tiene TEMPORARY/FIRM (semántica
+ * distinta: qué tan firme es el lock, no cuándo se dispara). Reconciliación pendiente con
+ * el dueño del dominio `mdm` (decidir reuso vs enum nuevo). En F1 el campo es pasivo
+ * (se guarda, no se ejerce) → no bloqueante.
+ *
+ * @enum {string}
+ *
+ * @property {string} ONDEMAND - El bloqueo se dispara bajo demanda.
+ * @property {string} SCHEDULED - El bloqueo se dispara de forma programada.
+ */
+export declare enum MdmLockModeEnum {
+    ONDEMAND = "ONDEMAND",
+    SCHEDULED = "SCHEDULED"
+}

package/bin/retailCatalog/enums/MdmLockModeEnum.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MdmLockModeEnum = void 0;
+/**
+ * Modo de bloqueo MDM. Valores del flow 04 de F1 (ONDEMAND/SCHEDULED).
+ *
+ * TD-007: el `DeviceLockModeEnum` del dominio `mdm` hoy tiene TEMPORARY/FIRM (semántica
+ * distinta: qué tan firme es el lock, no cuándo se dispara). Reconciliación pendiente con
+ * el dueño del dominio `mdm` (decidir reuso vs enum nuevo). En F1 el campo es pasivo
+ * (se guarda, no se ejerce) → no bloqueante.
+ *
+ * @enum {string}
+ *
+ * @property {string} ONDEMAND - El bloqueo se dispara bajo demanda.
+ * @property {string} SCHEDULED - El bloqueo se dispara de forma programada.
+ */
+var MdmLockModeEnum;
+(function (MdmLockModeEnum) {
+    MdmLockModeEnum["ONDEMAND"] = "ONDEMAND";
+    MdmLockModeEnum["SCHEDULED"] = "SCHEDULED";
+})(MdmLockModeEnum || (exports.MdmLockModeEnum = MdmLockModeEnum = {}));

package/bin/retailCatalog/enums/MdmProviderEnum.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Proveedor MDM (Mobile Device Management) para el enrolamiento de dispositivos (F4+).
+ * @enum {string}
+ *
+ * @property {string} TRUSTONIC - Proveedor Trustonic.
+ * @property {string} DATACULTR - Proveedor Datacultr.
+ */
+export declare enum MdmProviderEnum {
+    TRUSTONIC = "TRUSTONIC",
+    DATACULTR = "DATACULTR"
+}

package/bin/retailCatalog/enums/MdmProviderEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MdmProviderEnum = void 0;
+/**
+ * Proveedor MDM (Mobile Device Management) para el enrolamiento de dispositivos (F4+).
+ * @enum {string}
+ *
+ * @property {string} TRUSTONIC - Proveedor Trustonic.
+ * @property {string} DATACULTR - Proveedor Datacultr.
+ */
+var MdmProviderEnum;
+(function (MdmProviderEnum) {
+    MdmProviderEnum["TRUSTONIC"] = "TRUSTONIC";
+    MdmProviderEnum["DATACULTR"] = "DATACULTR";
+})(MdmProviderEnum || (exports.MdmProviderEnum = MdmProviderEnum = {}));

package/bin/retailCatalog/enums/ProductStatusEnum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Estado del producto en el catálogo.
+ * @enum {string}
+ *
+ * @property {string} ACTIVE - Producto activo y vendible.
+ * @property {string} INACTIVE - Producto inactivo temporalmente.
+ * @property {string} DISCONTINUED - Producto descontinuado.
+ */
+export declare enum ProductStatusEnum {
+    ACTIVE = "ACTIVE",
+    INACTIVE = "INACTIVE",
+    DISCONTINUED = "DISCONTINUED"
+}

package/bin/retailCatalog/enums/ProductStatusEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProductStatusEnum = void 0;
+/**
+ * Estado del producto en el catálogo.
+ * @enum {string}
+ *
+ * @property {string} ACTIVE - Producto activo y vendible.
+ * @property {string} INACTIVE - Producto inactivo temporalmente.
+ * @property {string} DISCONTINUED - Producto descontinuado.
+ */
+var ProductStatusEnum;
+(function (ProductStatusEnum) {
+    ProductStatusEnum["ACTIVE"] = "ACTIVE";
+    ProductStatusEnum["INACTIVE"] = "INACTIVE";
+    ProductStatusEnum["DISCONTINUED"] = "DISCONTINUED";
+})(ProductStatusEnum || (exports.ProductStatusEnum = ProductStatusEnum = {}));

package/bin/retailCatalog/enums/ProductTierEnum.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tier comercial del producto (segmenta catálogo por rango de precio/posicionamiento).
+ * @enum {string}
+ *
+ * @property {string} LOW - Gama de entrada.
+ * @property {string} MID - Gama media.
+ * @property {string} HIGH - Gama alta.
+ * @property {string} PREMIUM - Gama premium.
+ */
+export declare enum ProductTierEnum {
+    LOW = "LOW",
+    MID = "MID",
+    HIGH = "HIGH",
+    PREMIUM = "PREMIUM"
+}

package/bin/retailCatalog/enums/ProductTierEnum.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProductTierEnum = void 0;
+/**
+ * Tier comercial del producto (segmenta catálogo por rango de precio/posicionamiento).
+ * @enum {string}
+ *
+ * @property {string} LOW - Gama de entrada.
+ * @property {string} MID - Gama media.
+ * @property {string} HIGH - Gama alta.
+ * @property {string} PREMIUM - Gama premium.
+ */
+var ProductTierEnum;
+(function (ProductTierEnum) {
+    ProductTierEnum["LOW"] = "LOW";
+    ProductTierEnum["MID"] = "MID";
+    ProductTierEnum["HIGH"] = "HIGH";
+    ProductTierEnum["PREMIUM"] = "PREMIUM";
+})(ProductTierEnum || (exports.ProductTierEnum = ProductTierEnum = {}));

package/bin/retailCatalog/index.d.ts

@@ -0,0 +1,22 @@
+export * from './enums/ProductTierEnum';
+export * from './enums/ProductStatusEnum';
+export * from './enums/InventoryItemStatusEnum';
+export * from './enums/MdmProviderEnum';
+export * from './enums/MdmLockModeEnum';
+export * from './constants/SkuPattern';
+export * from './validators/IsMdmCoherentConstraint';
+export * from './dtos/Product';
+export * from './dtos/InventoryItem';
+export * from './dtos/requests/CreateProductRequest';
+export * from './dtos/requests/UpdateProductRequest';
+export * from './dtos/requests/UpdateProductStatusRequest';
+export * from './dtos/requests/ListProductsQuery';
+export * from './dtos/requests/RegisterInventoryRequest';
+export * from './dtos/requests/TransferInventoryRequest';
+export * from './dtos/requests/ChangeInventoryStatusRequest';
+export * from './dtos/responses/ProductResponse';
+export * from './dtos/responses/InventoryItemResponse';
+export * from './dtos/responses/ImportCsvFailure';
+export * from './dtos/responses/ImportCsvResult';
+export * from './dtos/validation/ValidateProductResponse';
+export * from './dtos/validation/ValidateInventoryResponse';

package/bin/retailCatalog/index.js

@@ -0,0 +1,44 @@
+"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("./enums/ProductTierEnum"), exports);
+__exportStar(require("./enums/ProductStatusEnum"), exports);
+__exportStar(require("./enums/InventoryItemStatusEnum"), exports);
+__exportStar(require("./enums/MdmProviderEnum"), exports);
+__exportStar(require("./enums/MdmLockModeEnum"), exports);
+// Constantes del dominio
+__exportStar(require("./constants/SkuPattern"), exports);
+// Validators custom
+__exportStar(require("./validators/IsMdmCoherentConstraint"), exports);
+// Entity DTOs
+__exportStar(require("./dtos/Product"), exports);
+__exportStar(require("./dtos/InventoryItem"), exports);
+// Request DTOs (input validado por endpoint)
+__exportStar(require("./dtos/requests/CreateProductRequest"), exports);
+__exportStar(require("./dtos/requests/UpdateProductRequest"), exports);
+__exportStar(require("./dtos/requests/UpdateProductStatusRequest"), exports);
+__exportStar(require("./dtos/requests/ListProductsQuery"), exports);
+__exportStar(require("./dtos/requests/RegisterInventoryRequest"), exports);
+__exportStar(require("./dtos/requests/TransferInventoryRequest"), exports);
+__exportStar(require("./dtos/requests/ChangeInventoryStatusRequest"), exports);
+// Response DTOs
+__exportStar(require("./dtos/responses/ProductResponse"), exports);
+__exportStar(require("./dtos/responses/InventoryItemResponse"), exports);
+__exportStar(require("./dtos/responses/ImportCsvFailure"), exports);
+__exportStar(require("./dtos/responses/ImportCsvResult"), exports);
+// Validation DTOs (shapes de endpoints privados)
+__exportStar(require("./dtos/validation/ValidateProductResponse"), exports);
+__exportStar(require("./dtos/validation/ValidateInventoryResponse"), exports);

package/bin/retailCatalog/validators/IsMdmCoherentConstraint.d.ts

@@ -0,0 +1,10 @@
+import { type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+/**
+ * Coherencia de la config MDM del producto:
+ * - mdmEnabled === true  → mdmProvider y mdmLockMode obligatorios.
+ * - mdmEnabled !== true   → mdmProvider y mdmLockMode deben omitirse (null/undefined).
+ */
+export declare class IsMdmCoherentConstraint implements ValidatorConstraintInterface {
+    validate(_value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailCatalog/validators/IsMdmCoherentConstraint.js

@@ -0,0 +1,31 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsMdmCoherentConstraint = void 0;
+const class_validator_1 = require("class-validator");
+/**
+ * Coherencia de la config MDM del producto:
+ * - mdmEnabled === true  → mdmProvider y mdmLockMode obligatorios.
+ * - mdmEnabled !== true   → mdmProvider y mdmLockMode deben omitirse (null/undefined).
+ */
+let IsMdmCoherentConstraint = class IsMdmCoherentConstraint {
+    validate(_value, args) {
+        const o = args.object;
+        if (o.mdmEnabled === true) {
+            return o.mdmProvider != null && o.mdmLockMode != null;
+        }
+        return o.mdmProvider == null && o.mdmLockMode == null;
+    }
+    defaultMessage() {
+        return 'Configuración MDM incoherente: con mdmEnabled=true se requieren mdmProvider y mdmLockMode; con mdmEnabled=false deben omitirse';
+    }
+};
+exports.IsMdmCoherentConstraint = IsMdmCoherentConstraint;
+exports.IsMdmCoherentConstraint = IsMdmCoherentConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'isMdmCoherent', async: false })
+], IsMdmCoherentConstraint);

package/bin/retailOrg/dtos/validation/CollectorValidationDto.d.ts

@@ -0,0 +1,21 @@
+import type { CollectorSeniorityEnum } from '../../enums/CollectorSeniorityEnum';
+import type { RetailUserStatusEnum } from '../../enums/RetailUserStatusEnum';
+/**
+ * Shape mínimo de un cobrador retail que devuelve el endpoint privado de validación de cobradores
+ * (consumido por loan-collector-assignment-business vía @fiado/api-invoker) para alimentar el
+ * algoritmo de asignación de cartera.
+ *
+ * `coverageStoreIds` va requerido (siempre presente; si el cobrador aún no cubre tiendas, `[]`).
+ *
+ * `collectorSeniority` es OPCIONAL: el modelo de datos no obliga a que un usuario con
+ * `commissionTier === 'collector'` tenga seniority poblado, así que un cobrador sin seniority es
+ * válido. Las estrategias de asignación BY_STORE / BY_LOAD / ROUND_ROBIN no lo necesitan; solo
+ * BY_SENIORITY lo usa para rankear (y ahí un cobrador sin seniority simplemente no rankea).
+ */
+export interface CollectorValidationDto {
+    retailUserId: string;
+    coverageStoreIds: string[];
+    collectorSeniority?: CollectorSeniorityEnum;
+    status: RetailUserStatusEnum;
+    commissionTier: string;
+}

package/bin/retailOrg/dtos/validation/CollectorValidationDto.js

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

package/bin/retailOrg/index.d.ts

@@ -13,6 +13,7 @@ export * from './dtos/RetailUser';
 export * from './dtos/validation/RetailerValidationDto';
 export * from './dtos/validation/StoreValidationDto';
 export * from './dtos/validation/RetailUserValidationDto';
+export * from './dtos/validation/CollectorValidationDto';
 export * from './dtos/PaginatedResult';
 export * from './dtos/requests/RetailAddressInput';
 export * from './dtos/requests/CreateRetailerRequest';

package/bin/retailOrg/index.js

@@ -31,6 +31,7 @@ __exportStar(require("./dtos/RetailUser"), exports);
 __exportStar(require("./dtos/validation/RetailerValidationDto"), exports);
 __exportStar(require("./dtos/validation/StoreValidationDto"), exports);
 __exportStar(require("./dtos/validation/RetailUserValidationDto"), exports);
+__exportStar(require("./dtos/validation/CollectorValidationDto"), exports);
 // Paginación genérica
 __exportStar(require("./dtos/PaginatedResult"), exports);
 // Request DTOs (input validado por endpoint)

package/package.json

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

package/src/index.ts

@@ -103,6 +103,12 @@ export * as EmailVerification from './emailVerification';
 // RetailOrg: DTOs/enums del lambda retail-org-business (SureKeep Fase 1 — pista Retail).
 // Dominio de retailers → zonas → tiendas → usuarios retail.
 export * as RetailOrg from './retailOrg';
+// RetailCatalog: DTOs/enums del lambda retail-catalog-business (comp 05 — catálogo de productos
+// por SKU + inventario por IMEI; SureKeep Fase 1 — pista Retail).
+export * as RetailCatalog from './retailCatalog';
+// RetailCards: DTOs/enums del lambda retail-cards-business (comp 06 — tarjetas físicas PCF:
+// lotes, stock y asignación; SureKeep Fase 1 — pista Retail).
+export * as RetailCards from './retailCards';
 // LoanConfig: DTOs/enums del lambda loan-config-business (comp 09 — parámetros operativos del SOFOM).
 export * as LoanConfig from './loanConfig';
 // LoanOfferings: DTOs/enums del lambda loan-offerings-business (comp 07 — planes de crédito,

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

@@ -0,0 +1,14 @@
+import { IsOptional, IsString } from 'class-validator';
+
+/** Body de la asignación de una tarjeta física a un cliente. */
+export class AssignCardRequest {
+    @IsString()
+    assignedToCustomerId!: string;
+
+    @IsString()
+    assignedByUserId!: string;
+
+    @IsOptional()
+    @IsString()
+    creditId?: string;
+}

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

@@ -0,0 +1,8 @@
+import { IsEnum } from 'class-validator';
+import { CardCancelReasonEnum } from '../../enums/CardCancelReasonEnum';
+
+/** Body de la cancelación (anulación) de una tarjeta física. */
+export class CancelCardRequest {
+    @IsEnum(CardCancelReasonEnum)
+    reason!: CardCancelReasonEnum;
+}

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

@@ -0,0 +1,21 @@
+import { ArrayMaxSize, IsArray, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+
+/** Body del registro (recepción) de un lote de tarjetas para una tienda. */
+export class RegisterCardBatchRequest {
+    @IsString()
+    storeId!: string;
+
+    @IsInt()
+    @Min(1)
+    @Max(1000)
+    totalCards!: number;
+
+    @IsArray()
+    @ArrayMaxSize(1000)
+    @IsString({ each: true })
+    cardNumbers!: string[];
+
+    @IsOptional()
+    @IsString()
+    notes?: string | null;
+}

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

@@ -0,0 +1,18 @@
+import { CardBatchStatusEnum } from '../../enums/CardBatchStatusEnum';
+
+/** Representación de un lote de tarjetas hacia el cliente. */
+export interface CardBatchResponse {
+    batchId: string;
+    retailerId: string;
+    storeId: string;
+    totalCards: number;
+    expectedCardCount: number;
+    loadedCount: number;
+    availableCount: number;
+    assignedCount: number;
+    cancelledCount: number;
+    status: CardBatchStatusEnum;
+    receivedAt: string;
+    receivedByUserId: string;
+    notes: string | null;
+}

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

@@ -0,0 +1,13 @@
+import { RetailCardStatusEnum } from '../../enums/RetailCardStatusEnum';
+
+/** Representación de una tarjeta física hacia el cliente. */
+export interface RetailCardResponse {
+    cardNumber: string;
+    retailerId: string;
+    batchId: string;
+    storeId: string;
+    status: RetailCardStatusEnum;
+    assignedToCustomerId: string | null;
+    assignedAt: string | null;
+    assignedByUserId: string | null;
+}

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

@@ -0,0 +1,7 @@
+/** Ítem de alerta de stock por tienda. */
+export interface StockAlertItem {
+    storeId: string;
+    storeName: string;
+    availableCount: number;
+    threshold: number;
+}

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

@@ -0,0 +1,6 @@
+import { StockAlertItem } from './StockAlertItem';
+
+/** Respuesta del reporte de alertas de stock. */
+export interface StockAlertsResponse {
+    alerts: StockAlertItem[];
+}

package/src/retailCards/enums/CardBatchStatusEnum.ts

@@ -0,0 +1,17 @@
+/**
+ * Estado de un lote de tarjetas.
+ * @enum {string}
+ *
+ * @property {string} RECEIVING - Transitorio, carga en curso (DEC-004/DEC-008).
+ * @property {string} RECEIVED - Carga completada, lote atado a una tienda (happy-path F1).
+ * @property {string} FAILED - Terminal, la carga del lote falló (DEC-004/DEC-008).
+ * @property {string} DISTRIBUTED - Reservado F1 — lote centralizado repartido a varias tiendas (TD-008).
+ * @property {string} CLOSED - Reservado F1 — cierre manual del lote (TD-008).
+ */
+export enum CardBatchStatusEnum {
+    RECEIVING = 'RECEIVING',
+    RECEIVED = 'RECEIVED',
+    FAILED = 'FAILED',
+    DISTRIBUTED = 'DISTRIBUTED',
+    CLOSED = 'CLOSED',
+}

package/src/retailCards/enums/CardCancelReasonEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Motivo de cancelación de una tarjeta física.
+ * @enum {string}
+ *
+ * @property {string} PLASTIC_DAMAGED - Plástico dañado.
+ * @property {string} LOST - Tarjeta perdida.
+ * @property {string} THEFT_REPORTED - Robo reportado.
+ */
+export enum CardCancelReasonEnum {
+    PLASTIC_DAMAGED = 'PLASTIC_DAMAGED',
+    LOST = 'LOST',
+    THEFT_REPORTED = 'THEFT_REPORTED',
+}

package/src/retailCards/enums/RetailCardStatusEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Estado de una tarjeta física individual.
+ * @enum {string}
+ *
+ * @property {string} AVAILABLE - Cargada en stock, disponible para asignar.
+ * @property {string} ASSIGNED - Asignada a un cliente.
+ * @property {string} CANCELLED - Anulada (plástico dañado, pérdida o robo). Estado terminal.
+ */
+export enum RetailCardStatusEnum {
+    AVAILABLE = 'AVAILABLE',
+    ASSIGNED = 'ASSIGNED',
+    CANCELLED = 'CANCELLED',
+}

package/src/retailCards/events/CardBatchReceivedV1.ts

@@ -0,0 +1,9 @@
+/** Emitido cuando un lote de tarjetas se recibe (RECEIVED). */
+export interface CardBatchReceivedV1 {
+    batchId: string;
+    retailerId: string;
+    storeId: string;
+    totalCards: number;
+    receivedByUserId: string;
+    occurredAt: string;
+}

package/src/retailCards/events/RetailCardAssignedV1.ts

@@ -0,0 +1,10 @@
+/** Emitido cuando una tarjeta se asigna a un cliente. */
+export interface RetailCardAssignedV1 {
+    cardNumber: string;
+    retailerId: string;
+    storeId: string;
+    assignedToCustomerId: string;
+    assignedByUserId: string;
+    creditId?: string;
+    occurredAt: string;
+}

package/src/retailCards/events/RetailCardCancelledV1.ts

@@ -0,0 +1,10 @@
+import { CardCancelReasonEnum } from '../enums/CardCancelReasonEnum';
+
+/** Emitido cuando una tarjeta se cancela (anula). */
+export interface RetailCardCancelledV1 {
+    cardNumber: string;
+    retailerId: string;
+    storeId: string;
+    reason: CardCancelReasonEnum;
+    occurredAt: string;
+}

package/src/retailCards/events/RetailCardReleasedV1.ts

@@ -0,0 +1,7 @@
+/** Emitido cuando una tarjeta se libera (vuelve a AVAILABLE). */
+export interface RetailCardReleasedV1 {
+    cardNumber: string;
+    retailerId: string;
+    storeId: string;
+    occurredAt: string;
+}

package/src/retailCards/index.ts

@@ -0,0 +1,20 @@
+export * from './enums/RetailCardStatusEnum';
+export * from './enums/CardBatchStatusEnum';
+export * from './enums/CardCancelReasonEnum';
+
+// Request DTOs (input validado por endpoint)
+export * from './dtos/requests/RegisterCardBatchRequest';
+export * from './dtos/requests/CancelCardRequest';
+export * from './dtos/requests/AssignCardRequest';
+
+// Response DTOs
+export * from './dtos/responses/CardBatchResponse';
+export * from './dtos/responses/RetailCardResponse';
+export * from './dtos/responses/StockAlertItem';
+export * from './dtos/responses/StockAlertsResponse';
+
+// Contratos de eventos (PascalCase + sufijo V1)
+export * from './events/CardBatchReceivedV1';
+export * from './events/RetailCardAssignedV1';
+export * from './events/RetailCardReleasedV1';
+export * from './events/RetailCardCancelledV1';

package/src/retailCatalog/constants/SkuPattern.ts

@@ -0,0 +1,2 @@
+/** Charset permitido para el SKU: alfanumérico + guion, 1-64 chars. */
+export const SKU_PATTERN = /^[A-Za-z0-9-]+$/;

package/src/retailCatalog/dtos/InventoryItem.ts

@@ -0,0 +1,21 @@
+import { InventoryItemStatusEnum } from '../enums/InventoryItemStatusEnum';
+
+/**
+ * InventoryItem — unidad física de inventario identificada por IMEI
+ * (lambda retail-catalog-business, SureKeep Fase 1 — pista Retail).
+ * Representación de salida/datos: sin decoradores class-validator.
+ */
+export class InventoryItem {
+    imei!: string;
+    retailerId!: string;
+    productId!: string;
+    storeId!: string;
+    status!: InventoryItemStatusEnum;
+    receivedAt!: string;
+    soldAt!: string | null;
+    soldToCustomerId!: string | null;
+    createdBy!: string;
+    updatedBy!: string;
+    createdAt!: string;
+    updatedAt!: string;
+}