@fiado/type-kit 3.262.0 → 3.265.0

package/bin/retailCatalog/dtos/responses/InventoryLensResponse.d.ts

@@ -0,0 +1,106 @@
+import type { InventoryLensFilterEnum } from '../../enums/InventoryLensFilterEnum';
+import type { InventoryLensUnavailableReasonEnum } from '../../enums/InventoryLensUnavailableReasonEnum';
+import type { InventoryTransferReasonEnum } from '../../enums/InventoryTransferReasonEnum';
+/**
+ * Los contadores que la pantalla «Inventario» del Admin VL pinta arriba, siempre — los cuatro viajan
+ * con cualquier `filter`, porque las tarjetas no cambian al cambiar de tab.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ **No hay contador de `gap`.** El mockup pinta cinco tarjetas, pero la quinta compara contra las
+ * ventas de LUGA (INT6) y no se puede calcular. Se omite en vez de mandar un cero mentiroso.
+ */
+export interface InventoryLensCounters {
+    /** Unidades `AVAILABLE` del retailer, sumadas sobre todas las tiendas. */
+    totalStock: number;
+    /** SKUs distintos del catálogo del retailer — el subtítulo de la tarjeta de stock. */
+    distinctSkus: number;
+    /** Pares (SKU, tienda) en stock crítico. */
+    critical: number;
+    /** Pares (SKU, tienda) sin rotación o recién llegados sin venta. */
+    stale: number;
+    /** Traspasos sugeridos entre tiendas. */
+    transfers: number;
+}
+/**
+ * Una fila de los tabs `critical` y `stale`: un SKU **en una tienda concreta**. El mismo SKU aparece
+ * una vez por cada tienda donde vive, porque la acción (traspasar, promocionar) es por tienda.
+ */
+export interface InventoryLensSkuItem {
+    sku: string;
+    productId: string;
+    brand: string;
+    model: string;
+    capacity: string;
+    storeId: string;
+    /** Unidades `AVAILABLE` de este SKU en esta tienda. */
+    stock: number;
+    /**
+     * Días sin vender este SKU, medidos sobre **todo el retailer** (no por tienda) — es la definición
+     * del mockup, donde la rotación es un atributo del producto.
+     *
+     * Si el SKU nunca se vendió no hay `soldAt` del que restar: se cae a los días desde el ingreso más
+     * antiguo del SKU en el retailer, que es la cota inferior honesta de «cuánto lleva sin venderse».
+     */
+    rotationDays: number;
+    /** Días desde que este SKU entró a ESTA tienda (el lote más reciente). */
+    daysSinceArrival: number;
+    /** Fecha ISO-8601 de ese ingreso. */
+    arrivedAt: string;
+    /** El lote llegó hace menos de 7 días. */
+    recentArrival: boolean;
+    /** `rotationDays > 90`. */
+    noRotation90d: boolean;
+    /** No hubo ninguna venta del SKU posterior a su ingreso a esta tienda. */
+    noSaleSinceArrival: boolean;
+    /** `0 < stock < 3`. */
+    criticalStock: boolean;
+    /** Unidades de este SKU vendidas hoy en esta tienda, **financiadas por SureKeep**. */
+    soldTodayUnits: number;
+    /** Precio de contado en centavos (`listPriceCents`, o `basePriceCents` si no hay lista). */
+    cashPriceCents: number;
+}
+/** Una fila del tab `transfers`: mover unidades de un SKU de una tienda con excedente a una en crítico. */
+export interface InventoryLensTransferSuggestion {
+    sku: string;
+    productId: string;
+    brand: string;
+    model: string;
+    /** Tienda con excedente (≥ 5 unidades del SKU). */
+    fromStoreId: string;
+    fromStoreStock: number;
+    /** Tienda en stock crítico. */
+    toStoreId: string;
+    toStoreStock: number;
+    /** Unidades sugeridas: `min(floor(fromStoreStock / 3), 3)`. */
+    units: number;
+    reason: InventoryTransferReasonEnum;
+}
+/** Fila del lente — el tipo depende del tab pedido. */
+export type InventoryLensItem = InventoryLensSkuItem | InventoryLensTransferSuggestion;
+/**
+ * `GET /backoffice/inventory/lens?filter=…` — la pantalla «Inventario» del Portal Admin VentasLuga.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Es una **lente, no un clon** (D11): se sirve de solo lectura sobre el inventario propio y ninguna
+ * acción de la pantalla muta nada — los botones son deep links al ERP de LUGA. El inventario lo mueve
+ * La Central, no SureKeep.
+ *
+ * `counters` viaja siempre, con cualquier `filter`. `items` trae el tab pedido.
+ */
+export interface InventoryLensResponse {
+    /** El tab que se resolvió — eco del query, para que el front no se confunda de pestaña. */
+    filter: InventoryLensFilterEnum;
+    counters: InventoryLensCounters;
+    /** Filas del tab. Vacío cuando `unavailable` es `true`. */
+    items: InventoryLensItem[];
+    /**
+     * `true` cuando el tab **no se puede calcular** (hoy solo `filter=gap`).
+     *
+     * ⚠️ El front DEBE distinguirlo de una lista vacía normal: `unavailable: true` significa «este
+     * comparativo necesita la integración con La Central», no «no hay gap». Pintar un cero acá sería
+     * dar por buena una medición que nunca se hizo.
+     */
+    unavailable?: boolean;
+    /** Por qué no se pudo. Presente solo junto a `unavailable: true`. */
+    reason?: InventoryLensUnavailableReasonEnum;
+}

package/bin/retailCatalog/dtos/responses/InventoryLensResponse.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * Los cuatro tabs de la pantalla «Inventario» del Portal Admin VentasLuga (B-INV).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El valor viaja como query string en `GET /backoffice/inventory/lens?filter=…`, así que son las
+ * cadenas literales del mockup, no SCREAMING_CASE.
+ *
+ * ⚠️ `GAP` está en el contrato pero **no se puede calcular**: compara las ventas de LUGA contra las
+ * que financia SureKeep, y el lado LUGA llega por La Central (INT6), cuyo spec todavía no existe.
+ * El endpoint lo acepta y responde con `unavailable: true` — ver `InventoryLensResponse`.
+ */
+export declare enum InventoryLensFilterEnum {
+    /** SKUs con stock por agotarse en una tienda. */
+    CRITICAL = "critical",
+    /** SKUs sin rotación, o recién llegados que todavía no venden. */
+    STALE = "stale",
+    /** Top vendidos en LUGA que SureKeep no financia. **No disponible** (INT6). */
+    GAP = "gap",
+    /** Desbalance de stock del mismo SKU entre tiendas. */
+    TRANSFERS = "transfers"
+}

package/bin/retailCatalog/enums/InventoryLensFilterEnum.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryLensFilterEnum = void 0;
+/**
+ * Los cuatro tabs de la pantalla «Inventario» del Portal Admin VentasLuga (B-INV).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El valor viaja como query string en `GET /backoffice/inventory/lens?filter=…`, así que son las
+ * cadenas literales del mockup, no SCREAMING_CASE.
+ *
+ * ⚠️ `GAP` está en el contrato pero **no se puede calcular**: compara las ventas de LUGA contra las
+ * que financia SureKeep, y el lado LUGA llega por La Central (INT6), cuyo spec todavía no existe.
+ * El endpoint lo acepta y responde con `unavailable: true` — ver `InventoryLensResponse`.
+ */
+var InventoryLensFilterEnum;
+(function (InventoryLensFilterEnum) {
+    /** SKUs con stock por agotarse en una tienda. */
+    InventoryLensFilterEnum["CRITICAL"] = "critical";
+    /** SKUs sin rotación, o recién llegados que todavía no venden. */
+    InventoryLensFilterEnum["STALE"] = "stale";
+    /** Top vendidos en LUGA que SureKeep no financia. **No disponible** (INT6). */
+    InventoryLensFilterEnum["GAP"] = "gap";
+    /** Desbalance de stock del mismo SKU entre tiendas. */
+    InventoryLensFilterEnum["TRANSFERS"] = "transfers";
+})(InventoryLensFilterEnum || (exports.InventoryLensFilterEnum = InventoryLensFilterEnum = {}));

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

@@ -0,0 +1,14 @@
+/**
+ * Por qué un tab del lente de inventario no se puede calcular. SureKeep Fase 3 — pista Retail.
+ *
+ * Existe para que el front distinga **«no lo puedo calcular»** de **«calculé y dio cero»**. Un tab
+ * que no se puede servir viaja con `items: []` + `unavailable: true` + este motivo; sin él, el cero
+ * se leería como un dato bueno y la pantalla mentiría.
+ */
+export declare enum InventoryLensUnavailableReasonEnum {
+    /**
+     * El tab necesita las ventas de LUGA, que llegan por La Central (INT6). La integración no está
+     * especificada todavía, así que el dato no existe — no es que valga cero.
+     */
+    INT6_NOT_AVAILABLE = "INT6_NOT_AVAILABLE"
+}

package/bin/retailCatalog/enums/InventoryLensUnavailableReasonEnum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryLensUnavailableReasonEnum = void 0;
+/**
+ * Por qué un tab del lente de inventario no se puede calcular. SureKeep Fase 3 — pista Retail.
+ *
+ * Existe para que el front distinga **«no lo puedo calcular»** de **«calculé y dio cero»**. Un tab
+ * que no se puede servir viaja con `items: []` + `unavailable: true` + este motivo; sin él, el cero
+ * se leería como un dato bueno y la pantalla mentiría.
+ */
+var InventoryLensUnavailableReasonEnum;
+(function (InventoryLensUnavailableReasonEnum) {
+    /**
+     * El tab necesita las ventas de LUGA, que llegan por La Central (INT6). La integración no está
+     * especificada todavía, así que el dato no existe — no es que valga cero.
+     */
+    InventoryLensUnavailableReasonEnum["INT6_NOT_AVAILABLE"] = "INT6_NOT_AVAILABLE";
+})(InventoryLensUnavailableReasonEnum || (exports.InventoryLensUnavailableReasonEnum = InventoryLensUnavailableReasonEnum = {}));

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

@@ -0,0 +1,11 @@
+/**
+ * Motivo por el que el lente sugiere mover unidades de una tienda a otra. SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ El mockup rotula el motivo como «Stock crítico + demanda hoy», pero la **demanda** sale de las
+ * ventas de LUGA (INT6, no disponible). Acá solo se declara la mitad que sí se puede probar con
+ * datos propios: la tienda destino está en crítico y hay otra con excedente del mismo SKU.
+ */
+export declare enum InventoryTransferReasonEnum {
+    /** El destino tiene stock crítico y el origen tiene excedente del mismo SKU. */
+    CRITICAL_STOCK_AT_DESTINATION = "CRITICAL_STOCK_AT_DESTINATION"
+}

package/bin/retailCatalog/enums/InventoryTransferReasonEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryTransferReasonEnum = void 0;
+/**
+ * Motivo por el que el lente sugiere mover unidades de una tienda a otra. SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ El mockup rotula el motivo como «Stock crítico + demanda hoy», pero la **demanda** sale de las
+ * ventas de LUGA (INT6, no disponible). Acá solo se declara la mitad que sí se puede probar con
+ * datos propios: la tienda destino está en crítico y hay otra con excedente del mismo SKU.
+ */
+var InventoryTransferReasonEnum;
+(function (InventoryTransferReasonEnum) {
+    /** El destino tiene stock crítico y el origen tiene excedente del mismo SKU. */
+    InventoryTransferReasonEnum["CRITICAL_STOCK_AT_DESTINATION"] = "CRITICAL_STOCK_AT_DESTINATION";
+})(InventoryTransferReasonEnum || (exports.InventoryTransferReasonEnum = InventoryTransferReasonEnum = {}));

package/bin/retailCatalog/index.d.ts

@@ -3,6 +3,9 @@ export * from './enums/ProductStatusEnum';
 export * from './enums/InventoryItemStatusEnum';
 export * from './enums/MdmProviderEnum';
 export * from './enums/MdmLockModeEnum';
+export * from './enums/InventoryLensFilterEnum';
+export * from './enums/InventoryLensUnavailableReasonEnum';
+export * from './enums/InventoryTransferReasonEnum';
 export * from './constants/SkuPattern';
 export * from './validators/IsMdmCoherentConstraint';
 export * from './dtos/Product';
@@ -14,9 +17,11 @@ export * from './dtos/requests/ListProductsQuery';
 export * from './dtos/requests/RegisterInventoryRequest';
 export * from './dtos/requests/TransferInventoryRequest';
 export * from './dtos/requests/ChangeInventoryStatusRequest';
+export * from './dtos/requests/InventoryLensQuery';
 export * from './dtos/responses/ProductResponse';
 export * from './dtos/responses/InventoryItemResponse';
 export * from './dtos/responses/ImportCsvFailure';
 export * from './dtos/responses/ImportCsvResult';
+export * from './dtos/responses/InventoryLensResponse';
 export * from './dtos/validation/ValidateProductResponse';
 export * from './dtos/validation/ValidateInventoryResponse';

package/bin/retailCatalog/index.js

@@ -19,6 +19,10 @@ __exportStar(require("./enums/ProductStatusEnum"), exports);
 __exportStar(require("./enums/InventoryItemStatusEnum"), exports);
 __exportStar(require("./enums/MdmProviderEnum"), exports);
 __exportStar(require("./enums/MdmLockModeEnum"), exports);
+// F3 — lente de inventario del Portal Admin VentasLuga
+__exportStar(require("./enums/InventoryLensFilterEnum"), exports);
+__exportStar(require("./enums/InventoryLensUnavailableReasonEnum"), exports);
+__exportStar(require("./enums/InventoryTransferReasonEnum"), exports);
 // Constantes del dominio
 __exportStar(require("./constants/SkuPattern"), exports);
 // Validators custom
@@ -34,11 +38,13 @@ __exportStar(require("./dtos/requests/ListProductsQuery"), exports);
 __exportStar(require("./dtos/requests/RegisterInventoryRequest"), exports);
 __exportStar(require("./dtos/requests/TransferInventoryRequest"), exports);
 __exportStar(require("./dtos/requests/ChangeInventoryStatusRequest"), exports);
+__exportStar(require("./dtos/requests/InventoryLensQuery"), 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);
+__exportStar(require("./dtos/responses/InventoryLensResponse"), exports);
 // Validation DTOs (shapes de endpoints privados)
 __exportStar(require("./dtos/validation/ValidateProductResponse"), exports);
 __exportStar(require("./dtos/validation/ValidateInventoryResponse"), exports);

package/bin/retailWizard/events/SaleCancelledV2.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Emitido al cancelar una venta, en la MISMA `TransactWriteItems` de la cancelación.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * **La V1 NO se toca** (tiene consumers en producción). La V2 se emite además y es la que consume el
+ * motor de comisiones, que necesita el `sellerRetailUserId` para saber a QUIÉN revertirle la comisión
+ * y el `soldAt` para saber en qué CORTE se había liquidado.
+ *
+ * ⚠️ `tenantId` NO va en el payload: viaja en el sobre del outbox.
+ */
+export interface SaleCancelledV2 {
+    saleId: string;
+    /** A quién se le revierte la comisión. */
+    sellerRetailUserId: string;
+    /** Fecha de la venta ORIGINAL — identifica el corte en el que se había liquidado. */
+    soldAt: string;
+    reason: string;
+    cancelledAt: string;
+    occurredAt: string;
+}

package/bin/retailWizard/events/SaleCancelledV2.js

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

package/bin/retailWizard/events/SaleCompletedV2.d.ts

@@ -0,0 +1,41 @@
+import type { SaleTypeEnum } from '../enums/SaleTypeEnum';
+import type { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
+/**
+ * Emitido al cerrar una venta, en la MISMA `TransactWriteItems` del cierre (patrón Outbox).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * **La V1 NO se toca:** ya tiene consumers en producción (La Central, datalake). La V2 se emite
+ * ADEMÁS, en la misma transacción, y es la que consume el motor de comisiones — que necesita saber
+ * QUIÉN vendió (`sellerRetailUserId`), CÓMO se financió (`type` + `externalProvider`) y de qué MARCA
+ * era el equipo (`brand`), tres datos que la V1 no lleva.
+ *
+ * ⚠️ `tenantId` NO va en el payload: ya viaja en el sobre del outbox (`OutboxEventPublisher`).
+ * Duplicarlo abriría la puerta a que los dos discrepen.
+ *
+ * ⚠️ NO hay `lines[]`: una `RetailSale` es de UN solo producto (D16) y se comisiona la venta, no un
+ * renglón. Modelarlo como array sugeriría un carrito que el wizard no tiene.
+ */
+export interface SaleCompletedV2 {
+    saleId: string;
+    folio: string;
+    retailerId: string;
+    storeId: string;
+    /** Quién vendió — el eje del cálculo de comisión. Es lo que más falta en la V1. */
+    sellerRetailUserId: string;
+    retailCustomerId: string;
+    sku: string;
+    /** Marca del equipo, del snapshot congelado al cerrar. `null` si no se pudo resolver. */
+    brand: string | null;
+    imei: string | null;
+    /** Lo COBRADO en caja. En contado == precio del equipo; en CREDIT es SOLO el enganche. */
+    amountCents: number;
+    /** Precio de lista del equipo — la base de comisión. `null` en ventas sin el dato. */
+    equipmentPriceCents: number | null;
+    downPaymentCents: number | null;
+    creditId: string | null;
+    type: SaleTypeEnum;
+    /** Proveedor externo cuando `type = EXTERNAL_REFERRAL`; `null` en contado y crédito propio. */
+    externalProvider: ExternalProviderEnum | null;
+    soldAt: string;
+    occurredAt: string;
+}

package/bin/retailWizard/events/SaleCompletedV2.js

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

package/bin/retailWizard/index.d.ts

@@ -92,4 +92,6 @@ export * from './dtos/responses/BackofficeSalesKpisResponse';
 export * from './dtos/responses/BackofficeReportsResponse';
 export * from './events/SaleCompletedV1';
 export * from './events/SaleCancelledV1';
+export * from './events/SaleCompletedV2';
+export * from './events/SaleCancelledV2';
 export * from './events/SessionExpiredV1';

package/bin/retailWizard/index.js

@@ -121,4 +121,6 @@ __exportStar(require("./dtos/responses/BackofficeReportsResponse"), exports);
 // Contratos de eventos (PascalCase + sufijo V1)
 __exportStar(require("./events/SaleCompletedV1"), exports);
 __exportStar(require("./events/SaleCancelledV1"), exports);
+__exportStar(require("./events/SaleCompletedV2"), exports);
+__exportStar(require("./events/SaleCancelledV2"), exports);
 __exportStar(require("./events/SessionExpiredV1"), exports);

package/package.json

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

package/src/collection/dtos/AuthorizeCollectionMovementRequest.ts

@@ -0,0 +1,15 @@
+import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { MechanismType } from '../enums/MechanismType';
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+
+export class AuthorizeCollectionMovementRequest {
+  @IsString() executionId!: string;    // idempotencia (@IdempotencyController)
+  @IsString() directoryId!: string;
+  @IsString() provider!: string;       // lo pone el motor desde la config
+  @IsEnum(MechanismType) mechanism!: MechanismType;
+  @IsInt() amount!: number;            // ya convertido por el motor (FX previo)
+  @IsEnum(CurrencyId) currencyId!: CurrencyId;
+  @IsOptional() @IsString() intentId?: string;
+  @IsOptional() @IsString() chargeId?: string;
+  @IsOptional() @IsString() holdTxId?: string;
+}

package/src/collection/dtos/AuthorizeCollectionMovementResponse.ts

@@ -0,0 +1,9 @@
+import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+
+export class AuthorizeCollectionMovementResponse {
+  @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
+  @IsInt() amount!: number;            // reservado o cobrado
+  @IsOptional() @IsString() holdTxId?: string;
+  @IsOptional() @IsString() transactionId?: string;
+}

package/src/collection/dtos/CollectRequest.ts

@@ -0,0 +1,10 @@
+import { IsString, IsInt } from 'class-validator';
+
+export class CollectRequest {
+  @IsString() ownerRef!: string;
+  @IsString() tenantId!: string;
+  @IsString() domain!: string;
+  @IsString() productId!: string;
+  @IsString() chargeId!: string;
+  @IsInt() amount!: number;
+}

package/src/collection/dtos/CollectResponse.ts

@@ -0,0 +1,9 @@
+import { IsString, IsInt, IsEnum } from 'class-validator';
+import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+
+export class CollectResponse {
+  @IsString() intentId!: string;
+  @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
+  @IsInt() amountReserved!: number;
+  @IsInt() amountCollected!: number;
+}

package/src/collection/dtos/CollectionResultEvent.ts

@@ -0,0 +1,14 @@
+import { IsString, IsInt, IsEnum } from 'class-validator';
+import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+import { MechanismType } from '../enums/MechanismType';
+
+export class CollectionResultEvent {
+  @IsString() attemptId!: string;      // dedupe en el consumidor
+  @IsString() intentId!: string;
+  @IsString() domain!: string;         // routing (filter policy)
+  @IsString() tenantId!: string;
+  @IsString() chargeId!: string;
+  @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
+  @IsEnum(MechanismType) mechanism!: MechanismType;
+  @IsInt() amount!: number;            // reservado o cobrado según mecanismo
+}

package/src/collection/dtos/PendingChargeDto.ts

@@ -0,0 +1,21 @@
+import { IsString, IsInt, IsOptional, IsEnum, IsObject } from 'class-validator';
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+
+export class PendingChargeDto {
+  @IsString() chargeId!: string;          // record_id / INSTALLMENT#n
+  @IsString() ownerRef!: string;          // directoryId
+  @IsString() tenantId!: string;          // FIADO | surekeep
+  @IsString() domain!: string;            // une-credit | surekeep-retail
+  @IsString() parentDebtId!: string;      // credit_id / CREDIT#id
+  @IsInt() installmentNumber!: number;    // coupon_number / installment_number
+  @IsInt() amount!: number;               // centavos
+  @IsEnum(CurrencyId) currency!: CurrencyId;
+  @IsString() dueDate!: string;           // ISO date
+  @IsString() status!: string;            // estado del cargo en el dominio (normalizado por el motor)
+  @IsOptional() @IsInt() principalAmount?: number;
+  @IsOptional() @IsInt() interestAmount?: number;
+  @IsOptional() @IsInt() taxAmount?: number;
+  @IsOptional() @IsInt() outstandingBalance?: number;
+  @IsOptional() @IsInt() amountCollected?: number;
+  @IsOptional() @IsObject() metadata?: Record<string, unknown>; // por-dominio (fiado_/loanco_interest, imei…)
+}

package/src/collection/dtos/RegisterCollectibleRequest.ts

@@ -0,0 +1,9 @@
+import { IsString } from 'class-validator';
+
+export class RegisterCollectibleRequest {
+  @IsString() ownerRef!: string;
+  @IsString() tenantId!: string;
+  @IsString() domain!: string;
+  @IsString() productId!: string;
+  @IsString() chargeId!: string;
+}

package/src/collection/enums/CollectionResultStatus.ts

@@ -0,0 +1,5 @@
+export enum CollectionResultStatus {
+  FULL = 'FULL',
+  PARTIAL = 'PARTIAL',
+  NONE = 'NONE',
+}

package/src/collection/enums/CollectionState.ts

@@ -0,0 +1,8 @@
+export enum CollectionState {
+  PENDING = 'PENDING',
+  ATTEMPT = 'ATTEMPT',
+  RESERVED = 'RESERVED',
+  COLLECTED = 'COLLECTED',
+  AWAITING_FUNDS = 'AWAITING_FUNDS',
+  CANCELLED = 'CANCELLED',
+}

package/src/collection/enums/MechanismType.ts

@@ -0,0 +1,5 @@
+export enum MechanismType {
+  USD_PREAUTH = 'USD_PREAUTH',
+  USD_DIRECT = 'USD_DIRECT',
+  MXN_DIRECT = 'MXN_DIRECT',
+}

package/src/collection/enums/SagaStep.ts

@@ -0,0 +1,7 @@
+export enum SagaStep {
+  RESOLVE = 'RESOLVE',
+  PICK_SOURCE = 'PICK_SOURCE',
+  EXECUTE = 'EXECUTE',
+  PERSIST = 'PERSIST',
+  DISPATCH = 'DISPATCH',
+}

package/src/collection/index.ts

@@ -0,0 +1,14 @@
+// Enums
+export * from './enums/MechanismType';
+export * from './enums/CollectionState';
+export * from './enums/SagaStep';
+export * from './enums/CollectionResultStatus';
+
+// DTOs
+export * from './dtos/PendingChargeDto';
+export * from './dtos/CollectRequest';
+export * from './dtos/CollectResponse';
+export * from './dtos/RegisterCollectibleRequest';
+export * from './dtos/CollectionResultEvent';
+export * from './dtos/AuthorizeCollectionMovementRequest';
+export * from './dtos/AuthorizeCollectionMovementResponse';

package/src/index.ts

@@ -153,3 +153,8 @@ export * as PhoneSales from './phoneSales';
 // (tarjetas, teléfonos, …). ExternalShippingStatus se reexporta acá desde `card/` sin moverlo,
 // para no romper a los consumidores actuales del namespace Card.
 export * as Shipping from './shipping';
+// Collection: contrato del motor de cobro central (collection-engine-business) — dominio
+// agnóstico de proveedores/cuentas. PendingChargeDto es la deuda genérica; CollectRequest/
+// CollectResponse el contrato dominio↔motor; AuthorizeCollectionMovementRequest/Response el
+// contrato motor↔processor. Ver spec 2026-07-29-motor-cobro-central-design.
+export * as Collection from './collection';

package/src/retailCatalog/dtos/requests/InventoryLensQuery.ts

@@ -0,0 +1,16 @@
+import { IsEnum } from 'class-validator';
+import { InventoryLensFilterEnum } from '../../enums/InventoryLensFilterEnum';
+
+/**
+ * Query string de `GET /backoffice/inventory/lens`. SureKeep Fase 3 — pista Retail.
+ *
+ * `filter` es **obligatorio** a propósito: no hay un tab «por defecto» razonable, y caer a uno en
+ * silencio le devolvería al front una vista que no pidió. Un filtro ausente o desconocido es un 400.
+ *
+ * No lleva `retailerId`: el scope del endpoint es LEVEL_1 y el retailer se **impone desde el token**,
+ * nunca se acepta del request (si viajara, sería un IDOR entre cadenas).
+ */
+export class InventoryLensQuery {
+    @IsEnum(InventoryLensFilterEnum)
+    filter!: InventoryLensFilterEnum;
+}