@fiado/type-kit 3.512.0 → 3.513.0

package/_test_/unit/retailPromotions/activeSalePromotionsBySkus.test.ts

@@ -0,0 +1,58 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+    ACTIVE_SALE_PROMOTIONS_MAX_SKUS,
+    ActiveSalePromotionsBySkusRequest,
+    SkuSalePromotionLookupStatusEnum,
+} from '../../../src/retailPromotions/index';
+import type { ActiveSalePromotionsBySkusResponse } from '../../../src/retailPromotions/index';
+import { CatalogSourceStatusEnum } from '../../../src/retailCatalog/index';
+import type { GetInventorySkuResponse, InventoryLensListItem, InventoryLensResponse } from '../../../src/retailCatalog/index';
+
+const errorsOf = async (body: object) =>
+    (await validate(plainToInstance(ActiveSalePromotionsBySkusRequest, body, { excludeExtraneousValues: true }))).map((e) => e.property);
+
+const valid = { tenantId: 'SUREKEEP', retailerId: 'ret-1', items: [{ sku: 'SKU-1', category: 'PHONE', tier: 'MID' }] };
+
+describe('ActiveSalePromotionsBySkusRequest', () => {
+    it('acepta tenant, cadena, tienda opcional y SKUs con tipo y gama opcionales', async () => {
+        expect(await errorsOf(valid)).toEqual([]);
+        expect(await errorsOf({ ...valid, storeId: 'st-1', items: [{ sku: 'SKU-2' }] })).toEqual([]);
+    });
+
+    it('un SKU vacío no tumba el lote: se resuelve como INVALID_ID por entrada', async () => {
+        expect(await errorsOf({ ...valid, items: [{ sku: '' }] })).toEqual([]);
+    });
+
+    it.each([
+        ['sin tenantId', { ...valid, tenantId: undefined }, 'tenantId'],
+        ['sin retailerId', { ...valid, retailerId: '' }, 'retailerId'],
+        ['sin items', { ...valid, items: undefined }, 'items'],
+        ['tipo fuera del enum', { ...valid, items: [{ sku: 'A', category: 'CAR' }] }, 'items'],
+    ])('rechaza %s', async (_l, body, property) => {
+        expect(await errorsOf(body)).toContain(property);
+    });
+
+    it(`rechaza más de ${ACTIVE_SALE_PROMOTIONS_MAX_SKUS} SKUs`, async () => {
+        const items = Array.from({ length: ACTIVE_SALE_PROMOTIONS_MAX_SKUS + 1 }, (_v, i) => ({ sku: `S${i}` }));
+        expect(await errorsOf({ ...valid, items })).toContain('items');
+    });
+});
+
+describe('contratos de promos vigentes por SKU', () => {
+    it('una entrada por SKU con su estado y sus promos', () => {
+        const response: ActiveSalePromotionsBySkusResponse = {
+            items: [{ sku: 'SKU-1', status: SkuSalePromotionLookupStatusEnum.OK, promotions: [] }],
+        };
+        expect(Object.values(SkuSalePromotionLookupStatusEnum)).toEqual(['OK', 'UNAVAILABLE', 'INVALID_ID']);
+        expect(response.items[0]?.status).toBe('OK');
+    });
+
+    it('la ficha y el lente del catálogo llevan las promos y el estado de su fuente', () => {
+        const sku: Pick<GetInventorySkuResponse, 'promotions' | 'sources'> = { promotions: null, sources: { promotions: CatalogSourceStatusEnum.UNAVAILABLE } };
+        const row: Pick<InventoryLensListItem, 'hasPromotion' | 'promotionNames'> = { hasPromotion: true, promotionNames: ['Hot Sale'] };
+        const lens: Pick<InventoryLensResponse, 'sources'> = { sources: { promotions: CatalogSourceStatusEnum.OK } };
+        expect([sku.sources?.promotions, row.promotionNames, lens.sources?.promotions]).toEqual(['UNAVAILABLE', ['Hot Sale'], 'OK']);
+    });
+});

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

@@ -2,6 +2,8 @@ import type { InventoryItemStatusEnum } from '../../enums/InventoryItemStatusEnu
 import type { InventoryMovementTypeEnum } from '../../enums/InventoryMovementTypeEnum';
 import type { InventoryMovementReasonEnum } from '../../enums/InventoryMovementReasonEnum';
 import type { SkuPriceEntry } from './SkuPriceEntry';
+import type { CatalogSourceStatusEnum } from '../../enums/CatalogSourceStatusEnum';
+import type { ActiveSalePromotionSummary } from '../../../retailPromotions/dtos/responses/ActiveSalePromotionsBySkusResponse';
 /** Un movimiento del libro de inventario. */
 export interface InventoryMovementEntry {
     storeId: string;
@@ -36,4 +38,11 @@ export interface GetInventorySkuResponse {
     /** Vacío si el SKU se rastrea por cantidad. */
     piecesByStore: InventoryStorePieces[];
     currentPrice: SkuPriceEntry | null;
+    /** Promos de venta vigentes del SKU; `null` si retail-promotions no respondió. */
+    promotions?: ActiveSalePromotionSummary[] | null;
+    sources?: InventorySkuSources;
+}
+/** Estado de las fuentes externas de la ficha. */
+export interface InventorySkuSources {
+    promotions: CatalogSourceStatusEnum;
 }

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

@@ -5,6 +5,7 @@ import type { ProductTierEnum } from '../../enums/ProductTierEnum';
 import type { InventoryLensUnavailableReasonEnum } from '../../enums/InventoryLensUnavailableReasonEnum';
 import type { InventoryTransferReasonEnum } from '../../enums/InventoryTransferReasonEnum';
 import type { ItemTypeEnum } from '../../enums/ItemTypeEnum';
+import type { CatalogSourceStatusEnum } from '../../enums/CatalogSourceStatusEnum';
 /**
  * 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.
@@ -115,6 +116,10 @@ export interface InventoryLensListItem {
     sold30d: number;
     /** Producto físico o servicio. Ausente = PRODUCT. */
     itemType?: ItemTypeEnum;
+    /** Tiene al menos una promo de venta vigente; `null` si retail-promotions no respondió. */
+    hasPromotion?: boolean | null;
+    /** Nombres de sus promos de venta vigentes; `null` si retail-promotions no respondió. */
+    promotionNames?: string[] | null;
 }
 /** Fila del lente — el tipo depende del tab pedido. */
 export type InventoryLensItem = InventoryLensSkuItem | InventoryLensTransferSuggestion | InventoryLensListItem;
@@ -147,4 +152,9 @@ export interface InventoryLensResponse {
     unavailable?: boolean;
     /** Por qué no se pudo. Presente solo junto a `unavailable: true`. */
     reason?: InventoryLensUnavailableReasonEnum;
+    /** Estado de las fuentes externas; solo en el modo `list`. */
+    sources?: InventoryLensSources;
+}
+export interface InventoryLensSources {
+    promotions: CatalogSourceStatusEnum;
 }

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

@@ -0,0 +1,5 @@
+/** Si una fuente externa de una respuesta del catálogo contestó (`OK`) o falló (`UNAVAILABLE`). */
+export declare enum CatalogSourceStatusEnum {
+    OK = "OK",
+    UNAVAILABLE = "UNAVAILABLE"
+}

package/bin/retailCatalog/enums/CatalogSourceStatusEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogSourceStatusEnum = void 0;
+/** Si una fuente externa de una respuesta del catálogo contestó (`OK`) o falló (`UNAVAILABLE`). */
+var CatalogSourceStatusEnum;
+(function (CatalogSourceStatusEnum) {
+    CatalogSourceStatusEnum["OK"] = "OK";
+    CatalogSourceStatusEnum["UNAVAILABLE"] = "UNAVAILABLE";
+})(CatalogSourceStatusEnum || (exports.CatalogSourceStatusEnum = CatalogSourceStatusEnum = {}));

package/bin/retailCatalog/index.d.ts

@@ -36,6 +36,7 @@ export * from './enums/InventorySyncResultStatusEnum';
 export * from './enums/InventorySyncRejectionCodeEnum';
 export * from './enums/PriceSourceEnum';
 export * from './enums/InventoryLensPeriodEnum';
+export * from './enums/CatalogSourceStatusEnum';
 export * from './dtos/ProductComponent';
 export * from './dtos/requests/ReservationLineRef';
 export * from './dtos/requests/StockLine';

package/bin/retailCatalog/index.js

@@ -60,6 +60,7 @@ __exportStar(require("./enums/InventorySyncResultStatusEnum"), exports);
 __exportStar(require("./enums/InventorySyncRejectionCodeEnum"), exports);
 __exportStar(require("./enums/PriceSourceEnum"), exports);
 __exportStar(require("./enums/InventoryLensPeriodEnum"), exports);
+__exportStar(require("./enums/CatalogSourceStatusEnum"), exports);
 __exportStar(require("./dtos/ProductComponent"), exports);
 __exportStar(require("./dtos/requests/ReservationLineRef"), exports);
 __exportStar(require("./dtos/requests/StockLine"), exports);

package/bin/retailPromotions/constants/activeSalePromotionsBySkus.d.ts

@@ -0,0 +1,2 @@
+/** Tope de SKUs por llamada a `POST /private/sale-promotions/active-by-skus`; el caller parte en bloques. */
+export declare const ACTIVE_SALE_PROMOTIONS_MAX_SKUS = 100;

package/bin/retailPromotions/constants/activeSalePromotionsBySkus.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_SALE_PROMOTIONS_MAX_SKUS = void 0;
+/** Tope de SKUs por llamada a `POST /private/sale-promotions/active-by-skus`; el caller parte en bloques. */
+exports.ACTIVE_SALE_PROMOTIONS_MAX_SKUS = 100;

package/bin/retailPromotions/dtos/requests/ActiveSalePromotionsBySkusRequest.d.ts

@@ -0,0 +1,17 @@
+import { ProductCategoryEnum } from '../../../retailCatalog/enums/ProductCategoryEnum';
+import { ProductTierEnum } from '../../../retailCatalog/enums/ProductTierEnum';
+/** Un SKU con su tipo y gama; sin ellos no cumple un alcance por tipo o por gama. */
+export declare class ActiveSalePromotionsSkuInput {
+    /** Un SKU vacío no invalida el lote: sale como `INVALID_ID`. */
+    sku: string;
+    category?: ProductCategoryEnum | null;
+    tier?: ProductTierEnum | null;
+}
+/** Body de `POST /private/sale-promotions/active-by-skus` (M2M): hasta 100 SKUs; los repetidos se cuentan una vez. */
+export declare class ActiveSalePromotionsBySkusRequest {
+    tenantId: string;
+    retailerId: string;
+    /** Con tienda, solo las promos cuyo alcance la incluye; sin ella, las de cualquier tienda. */
+    storeId?: string;
+    items: ActiveSalePromotionsSkuInput[];
+}

package/bin/retailPromotions/dtos/requests/ActiveSalePromotionsBySkusRequest.js

@@ -0,0 +1,69 @@
+"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;
+};
+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.ActiveSalePromotionsBySkusRequest = exports.ActiveSalePromotionsSkuInput = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const ProductCategoryEnum_1 = require("../../../retailCatalog/enums/ProductCategoryEnum");
+const ProductTierEnum_1 = require("../../../retailCatalog/enums/ProductTierEnum");
+const activeSalePromotionsBySkus_1 = require("../../constants/activeSalePromotionsBySkus");
+/** Un SKU con su tipo y gama; sin ellos no cumple un alcance por tipo o por gama. */
+class ActiveSalePromotionsSkuInput {
+}
+exports.ActiveSalePromotionsSkuInput = ActiveSalePromotionsSkuInput;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], ActiveSalePromotionsSkuInput.prototype, "sku", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ProductCategoryEnum_1.ProductCategoryEnum),
+    __metadata("design:type", String)
+], ActiveSalePromotionsSkuInput.prototype, "category", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ProductTierEnum_1.ProductTierEnum),
+    __metadata("design:type", String)
+], ActiveSalePromotionsSkuInput.prototype, "tier", void 0);
+/** Body de `POST /private/sale-promotions/active-by-skus` (M2M): hasta 100 SKUs; los repetidos se cuentan una vez. */
+class ActiveSalePromotionsBySkusRequest {
+}
+exports.ActiveSalePromotionsBySkusRequest = ActiveSalePromotionsBySkusRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ActiveSalePromotionsBySkusRequest.prototype, "tenantId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ActiveSalePromotionsBySkusRequest.prototype, "retailerId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ActiveSalePromotionsBySkusRequest.prototype, "storeId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(activeSalePromotionsBySkus_1.ACTIVE_SALE_PROMOTIONS_MAX_SKUS),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => ActiveSalePromotionsSkuInput),
+    __metadata("design:type", Array)
+], ActiveSalePromotionsBySkusRequest.prototype, "items", void 0);

package/bin/retailPromotions/dtos/responses/ActiveSalePromotionsBySkusResponse.d.ts

@@ -0,0 +1,26 @@
+import type { SalePromotionLevers, SalePromotionScope, SalePromotionSegmentation } from '../SalePromotionLevers';
+import type { SkuSalePromotionLookupStatusEnum } from '../../enums/SkuSalePromotionLookupStatusEnum';
+/** Promo de venta vigente hoy que alcanza al SKU, con su contenido de la versión actual. */
+export interface ActiveSalePromotionSummary {
+    promotionId: string;
+    name: string;
+    /** Palancas en español: «$500 de descuento + 3× $50 de tiempo aire + $300 al Wallet Fiado». */
+    benefitSummary: string;
+    levers: SalePromotionLevers;
+    /** `null` = arrancó al publicarse. */
+    validFrom: string | null;
+    /** `null` = permanente. */
+    validUntil: string | null;
+    segmentation: SalePromotionSegmentation;
+    scope: SalePromotionScope;
+}
+export interface SkuActiveSalePromotions {
+    sku: string;
+    status: SkuSalePromotionLookupStatusEnum;
+    /** Vacío si no tiene ninguna o si el estado no es `OK`. */
+    promotions: ActiveSalePromotionSummary[];
+}
+/** Response de `POST /private/sale-promotions/active-by-skus`: una entrada por SKU, en el orden pedido. */
+export interface ActiveSalePromotionsBySkusResponse {
+    items: SkuActiveSalePromotions[];
+}

package/bin/retailPromotions/dtos/responses/ActiveSalePromotionsBySkusResponse.js

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

package/bin/retailPromotions/enums/SkuSalePromotionLookupStatusEnum.d.ts

@@ -0,0 +1,9 @@
+/** Cómo se resolvió cada SKU del lote de promos vigentes; hay una entrada por SKU pedido. */
+export declare enum SkuSalePromotionLookupStatusEnum {
+    /** Se leyeron las promos; `promotions` vacío es un dato: no tiene ninguna vigente. */
+    OK = "OK",
+    /** No se pudieron leer las promos; el caller lo pinta como fuente caída y reintenta. */
+    UNAVAILABLE = "UNAVAILABLE",
+    /** El SKU no tiene forma de SKU; reintentarlo igual nunca sirve. */
+    INVALID_ID = "INVALID_ID"
+}

package/bin/retailPromotions/enums/SkuSalePromotionLookupStatusEnum.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkuSalePromotionLookupStatusEnum = void 0;
+/** Cómo se resolvió cada SKU del lote de promos vigentes; hay una entrada por SKU pedido. */
+var SkuSalePromotionLookupStatusEnum;
+(function (SkuSalePromotionLookupStatusEnum) {
+    /** Se leyeron las promos; `promotions` vacío es un dato: no tiene ninguna vigente. */
+    SkuSalePromotionLookupStatusEnum["OK"] = "OK";
+    /** No se pudieron leer las promos; el caller lo pinta como fuente caída y reintenta. */
+    SkuSalePromotionLookupStatusEnum["UNAVAILABLE"] = "UNAVAILABLE";
+    /** El SKU no tiene forma de SKU; reintentarlo igual nunca sirve. */
+    SkuSalePromotionLookupStatusEnum["INVALID_ID"] = "INVALID_ID";
+})(SkuSalePromotionLookupStatusEnum || (exports.SkuSalePromotionLookupStatusEnum = SkuSalePromotionLookupStatusEnum = {}));

package/bin/retailPromotions/index.d.ts

@@ -17,9 +17,11 @@ export * from './enums/EntitlementKindEnum';
 export * from './enums/SaleCouponAvailabilityEnum';
 export * from './enums/RetailPromotionsErrorCodeEnum';
 export * from './enums/SalePromotionKindEnum';
+export * from './enums/SkuSalePromotionLookupStatusEnum';
 export * from './constants/retailPromotionsErrorHttpStatus';
 export * from './constants/salePromotionTransitions';
 export * from './constants/bonusPreMoney';
+export * from './constants/activeSalePromotionsBySkus';
 export * from './helpers/resolveSalePromotionTransition';
 export * from './helpers/computeBudgetUsedBps';
 export * from './helpers/resolveSalePromotionKind';
@@ -50,8 +52,10 @@ export * from './dtos/requests/HoldPromotionInput';
 export * from './dtos/requests/HoldSalePromotionRequest';
 export * from './dtos/requests/GetSaleCouponQuery';
 export * from './dtos/requests/SkuSalePromotionsQuery';
+export * from './dtos/requests/ActiveSalePromotionsBySkusRequest';
 export * from './dtos/responses/SalePromotionCrudResponses';
 export * from './dtos/responses/DiscountCodeResponses';
 export * from './dtos/responses/WizardSalePromotionResponses';
 export * from './dtos/responses/SkuSalePromotionsResponse';
 export * from './dtos/responses/SalePromotionSegmentsResponse';
+export * from './dtos/responses/ActiveSalePromotionsBySkusResponse';

package/bin/retailPromotions/index.js

@@ -34,10 +34,12 @@ __exportStar(require("./enums/EntitlementKindEnum"), exports);
 __exportStar(require("./enums/SaleCouponAvailabilityEnum"), exports);
 __exportStar(require("./enums/RetailPromotionsErrorCodeEnum"), exports);
 __exportStar(require("./enums/SalePromotionKindEnum"), exports);
+__exportStar(require("./enums/SkuSalePromotionLookupStatusEnum"), exports);
 // Constantes y helpers puros
 __exportStar(require("./constants/retailPromotionsErrorHttpStatus"), exports);
 __exportStar(require("./constants/salePromotionTransitions"), exports);
 __exportStar(require("./constants/bonusPreMoney"), exports);
+__exportStar(require("./constants/activeSalePromotionsBySkus"), exports);
 __exportStar(require("./helpers/resolveSalePromotionTransition"), exports);
 __exportStar(require("./helpers/computeBudgetUsedBps"), exports);
 __exportStar(require("./helpers/resolveSalePromotionKind"), exports);
@@ -71,9 +73,11 @@ __exportStar(require("./dtos/requests/HoldPromotionInput"), exports);
 __exportStar(require("./dtos/requests/HoldSalePromotionRequest"), exports);
 __exportStar(require("./dtos/requests/GetSaleCouponQuery"), exports);
 __exportStar(require("./dtos/requests/SkuSalePromotionsQuery"), exports);
+__exportStar(require("./dtos/requests/ActiveSalePromotionsBySkusRequest"), exports);
 // Response DTOs
 __exportStar(require("./dtos/responses/SalePromotionCrudResponses"), exports);
 __exportStar(require("./dtos/responses/DiscountCodeResponses"), exports);
 __exportStar(require("./dtos/responses/WizardSalePromotionResponses"), exports);
 __exportStar(require("./dtos/responses/SkuSalePromotionsResponse"), exports);
 __exportStar(require("./dtos/responses/SalePromotionSegmentsResponse"), exports);
+__exportStar(require("./dtos/responses/ActiveSalePromotionsBySkusResponse"), exports);

package/package.json

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

package/src/retailCatalog/dtos/responses/GetInventorySkuResponse.ts

@@ -2,6 +2,8 @@ import type { InventoryItemStatusEnum } from '../../enums/InventoryItemStatusEnu
 import type { InventoryMovementTypeEnum } from '../../enums/InventoryMovementTypeEnum';
 import type { InventoryMovementReasonEnum } from '../../enums/InventoryMovementReasonEnum';
 import type { SkuPriceEntry } from './SkuPriceEntry';
+import type { CatalogSourceStatusEnum } from '../../enums/CatalogSourceStatusEnum';
+import type { ActiveSalePromotionSummary } from '../../../retailPromotions/dtos/responses/ActiveSalePromotionsBySkusResponse';
 
 /** Un movimiento del libro de inventario. */
 export interface InventoryMovementEntry {
@@ -40,4 +42,12 @@ export interface GetInventorySkuResponse {
     /** Vacío si el SKU se rastrea por cantidad. */
     piecesByStore: InventoryStorePieces[];
     currentPrice: SkuPriceEntry | null;
+    /** Promos de venta vigentes del SKU; `null` si retail-promotions no respondió. */
+    promotions?: ActiveSalePromotionSummary[] | null;
+    sources?: InventorySkuSources;
+}
+
+/** Estado de las fuentes externas de la ficha. */
+export interface InventorySkuSources {
+    promotions: CatalogSourceStatusEnum;
 }

package/src/retailCatalog/dtos/responses/InventoryLensResponse.ts

@@ -5,6 +5,7 @@ import type { ProductTierEnum } from '../../enums/ProductTierEnum';
 import type { InventoryLensUnavailableReasonEnum } from '../../enums/InventoryLensUnavailableReasonEnum';
 import type { InventoryTransferReasonEnum } from '../../enums/InventoryTransferReasonEnum';
 import type { ItemTypeEnum } from '../../enums/ItemTypeEnum';
+import type { CatalogSourceStatusEnum } from '../../enums/CatalogSourceStatusEnum';
 
 /**
  * Los contadores que la pantalla «Inventario» del Admin VL pinta arriba, siempre — los cuatro viajan
@@ -130,6 +131,10 @@ export interface InventoryLensListItem {
     sold30d: number;
     /** Producto físico o servicio. Ausente = PRODUCT. */
     itemType?: ItemTypeEnum;
+    /** Tiene al menos una promo de venta vigente; `null` si retail-promotions no respondió. */
+    hasPromotion?: boolean | null;
+    /** Nombres de sus promos de venta vigentes; `null` si retail-promotions no respondió. */
+    promotionNames?: string[] | null;
 }
 
 /** Fila del lente — el tipo depende del tab pedido. */
@@ -169,4 +174,11 @@ export interface InventoryLensResponse {
 
     /** Por qué no se pudo. Presente solo junto a `unavailable: true`. */
     reason?: InventoryLensUnavailableReasonEnum;
+
+    /** Estado de las fuentes externas; solo en el modo `list`. */
+    sources?: InventoryLensSources;
+}
+
+export interface InventoryLensSources {
+    promotions: CatalogSourceStatusEnum;
 }

package/src/retailCatalog/enums/CatalogSourceStatusEnum.ts

@@ -0,0 +1,5 @@
+/** Si una fuente externa de una respuesta del catálogo contestó (`OK`) o falló (`UNAVAILABLE`). */
+export enum CatalogSourceStatusEnum {
+    OK = 'OK',
+    UNAVAILABLE = 'UNAVAILABLE',
+}

package/src/retailCatalog/index.ts

@@ -52,6 +52,7 @@ export * from './enums/InventorySyncResultStatusEnum';
 export * from './enums/InventorySyncRejectionCodeEnum';
 export * from './enums/PriceSourceEnum';
 export * from './enums/InventoryLensPeriodEnum';
+export * from './enums/CatalogSourceStatusEnum';
 export * from './dtos/ProductComponent';
 export * from './dtos/requests/ReservationLineRef';
 export * from './dtos/requests/StockLine';

package/src/retailPromotions/constants/activeSalePromotionsBySkus.ts

@@ -0,0 +1,2 @@
+/** Tope de SKUs por llamada a `POST /private/sale-promotions/active-by-skus`; el caller parte en bloques. */
+export const ACTIVE_SALE_PROMOTIONS_MAX_SKUS = 100;

package/src/retailPromotions/dtos/requests/ActiveSalePromotionsBySkusRequest.ts

@@ -0,0 +1,50 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, IsArray, IsEnum, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { ProductCategoryEnum } from '../../../retailCatalog/enums/ProductCategoryEnum';
+import { ProductTierEnum } from '../../../retailCatalog/enums/ProductTierEnum';
+import { ACTIVE_SALE_PROMOTIONS_MAX_SKUS } from '../../constants/activeSalePromotionsBySkus';
+
+/** Un SKU con su tipo y gama; sin ellos no cumple un alcance por tipo o por gama. */
+export class ActiveSalePromotionsSkuInput {
+    /** Un SKU vacío no invalida el lote: sale como `INVALID_ID`. */
+    @Expose()
+    @IsString()
+    sku!: string;
+
+    @Expose()
+    @IsOptional()
+    @IsEnum(ProductCategoryEnum)
+    category?: ProductCategoryEnum | null;
+
+    @Expose()
+    @IsOptional()
+    @IsEnum(ProductTierEnum)
+    tier?: ProductTierEnum | null;
+}
+
+/** Body de `POST /private/sale-promotions/active-by-skus` (M2M): hasta 100 SKUs; los repetidos se cuentan una vez. */
+export class ActiveSalePromotionsBySkusRequest {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    tenantId!: string;
+
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    retailerId!: string;
+
+    /** Con tienda, solo las promos cuyo alcance la incluye; sin ella, las de cualquier tienda. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @IsNotEmpty()
+    storeId?: string;
+
+    @Expose()
+    @IsArray()
+    @ArrayMaxSize(ACTIVE_SALE_PROMOTIONS_MAX_SKUS)
+    @ValidateNested({ each: true })
+    @Type(() => ActiveSalePromotionsSkuInput)
+    items!: ActiveSalePromotionsSkuInput[];
+}

package/src/retailPromotions/dtos/responses/ActiveSalePromotionsBySkusResponse.ts

@@ -0,0 +1,29 @@
+import type { SalePromotionLevers, SalePromotionScope, SalePromotionSegmentation } from '../SalePromotionLevers';
+import type { SkuSalePromotionLookupStatusEnum } from '../../enums/SkuSalePromotionLookupStatusEnum';
+
+/** Promo de venta vigente hoy que alcanza al SKU, con su contenido de la versión actual. */
+export interface ActiveSalePromotionSummary {
+    promotionId: string;
+    name: string;
+    /** Palancas en español: «$500 de descuento + 3× $50 de tiempo aire + $300 al Wallet Fiado». */
+    benefitSummary: string;
+    levers: SalePromotionLevers;
+    /** `null` = arrancó al publicarse. */
+    validFrom: string | null;
+    /** `null` = permanente. */
+    validUntil: string | null;
+    segmentation: SalePromotionSegmentation;
+    scope: SalePromotionScope;
+}
+
+export interface SkuActiveSalePromotions {
+    sku: string;
+    status: SkuSalePromotionLookupStatusEnum;
+    /** Vacío si no tiene ninguna o si el estado no es `OK`. */
+    promotions: ActiveSalePromotionSummary[];
+}
+
+/** Response de `POST /private/sale-promotions/active-by-skus`: una entrada por SKU, en el orden pedido. */
+export interface ActiveSalePromotionsBySkusResponse {
+    items: SkuActiveSalePromotions[];
+}

package/src/retailPromotions/enums/SkuSalePromotionLookupStatusEnum.ts

@@ -0,0 +1,9 @@
+/** Cómo se resolvió cada SKU del lote de promos vigentes; hay una entrada por SKU pedido. */
+export enum SkuSalePromotionLookupStatusEnum {
+    /** Se leyeron las promos; `promotions` vacío es un dato: no tiene ninguna vigente. */
+    OK = 'OK',
+    /** No se pudieron leer las promos; el caller lo pinta como fuente caída y reintenta. */
+    UNAVAILABLE = 'UNAVAILABLE',
+    /** El SKU no tiene forma de SKU; reintentarlo igual nunca sirve. */
+    INVALID_ID = 'INVALID_ID',
+}

package/src/retailPromotions/index.ts

@@ -18,11 +18,13 @@ export * from './enums/EntitlementKindEnum';
 export * from './enums/SaleCouponAvailabilityEnum';
 export * from './enums/RetailPromotionsErrorCodeEnum';
 export * from './enums/SalePromotionKindEnum';
+export * from './enums/SkuSalePromotionLookupStatusEnum';
 
 // Constantes y helpers puros
 export * from './constants/retailPromotionsErrorHttpStatus';
 export * from './constants/salePromotionTransitions';
 export * from './constants/bonusPreMoney';
+export * from './constants/activeSalePromotionsBySkus';
 export * from './helpers/resolveSalePromotionTransition';
 export * from './helpers/computeBudgetUsedBps';
 export * from './helpers/resolveSalePromotionKind';
@@ -59,6 +61,7 @@ export * from './dtos/requests/HoldPromotionInput';
 export * from './dtos/requests/HoldSalePromotionRequest';
 export * from './dtos/requests/GetSaleCouponQuery';
 export * from './dtos/requests/SkuSalePromotionsQuery';
+export * from './dtos/requests/ActiveSalePromotionsBySkusRequest';
 
 // Response DTOs
 export * from './dtos/responses/SalePromotionCrudResponses';
@@ -66,3 +69,4 @@ export * from './dtos/responses/DiscountCodeResponses';
 export * from './dtos/responses/WizardSalePromotionResponses';
 export * from './dtos/responses/SkuSalePromotionsResponse';
 export * from './dtos/responses/SalePromotionSegmentsResponse';
+export * from './dtos/responses/ActiveSalePromotionsBySkusResponse';