@fiado/type-kit 3.583.0 → 3.585.0

package/bin/retailIntegration/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./constants/retailIntegrationLimits"), exports);
 __exportStar(require("./constants/retailIntegrationErrorHttpStatus"), exports);
 __exportStar(require("./enums"), exports);
 __exportStar(require("./validators/IsIsoDateTimeWithZone"), exports);
+__exportStar(require("./validators/IsMovementsRangeValid"), exports);
 __exportStar(require("./dtos/RetailEventEnvelope"), exports);
 __exportStar(require("./dtos/ReceiveStoreEventRequest"), exports);
 __exportStar(require("./dtos/ReceiveRetailUserEventRequest"), exports);
@@ -37,11 +38,13 @@ __exportStar(require("./dtos/RetailPagedQuery"), exports);
 __exportStar(require("./dtos/ListRetailStoresRequest"), exports);
 __exportStar(require("./dtos/ListRetailCatalogRequest"), exports);
 __exportStar(require("./dtos/GetRetailInventoryRequest"), exports);
+__exportStar(require("./dtos/ListRetailInventoryMovementsRequest"), exports);
 __exportStar(require("./dtos/ListRetailUsersRequest"), exports);
 __exportStar(require("./dtos/RegisterRetailSaleRequest"), exports);
 __exportStar(require("./dtos/CancelRetailSaleRequest"), exports);
 __exportStar(require("./dtos/CheckRetailInventoryRequest"), exports);
 __exportStar(require("./dtos/RetailOutboundResponses"), exports);
+__exportStar(require("./dtos/RetailSystemResponses"), exports);
 __exportStar(require("./models/RetailPageMeta"), exports);
 __exportStar(require("./models/RetailSystemStore"), exports);
 __exportStar(require("./models/RetailSystemProduct"), exports);

package/bin/retailIntegration/models/RetailPageMeta.d.ts

@@ -3,8 +3,10 @@ export interface RetailPageMeta {
     count: number;
     nextToken: string | null;
 }
-/** `meta` del inventario de una tienda. */
+/** `meta` del inventario de una tienda; `count` y `nextToken` llegan cuando la lectura pagina. */
 export interface RetailInventoryMeta {
     storeId: string;
     generatedAt: string;
+    count?: number;
+    nextToken?: string | null;
 }

package/bin/retailIntegration/models/RetailSystemInventory.d.ts

@@ -1,4 +1,5 @@
-import { RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
+import type { InventoryEventPayload } from '../dtos/InventoryEventPayload';
+import { InventoryEventTypeEnum, RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
 export type RetailPieceStatus = `${RetailPieceStatusEnum}`;
 export type RetailPieceReason = `${RetailPieceReasonEnum}`;
 /** Pieza con IMEI o número de serie. */
@@ -15,3 +16,10 @@ export interface RetailSystemStock {
     storeId: string;
     qty: number;
 }
+/** Movimiento de inventario de Zentral: el mismo sobre que llega a `POST /webhooks/inventory`. */
+export interface RetailSystemInventoryMovement {
+    eventId: string;
+    eventType: `${InventoryEventTypeEnum}`;
+    occurredAt: string;
+    payload: InventoryEventPayload;
+}

package/bin/retailIntegration/validators/IsMovementsRangeValid.d.ts

@@ -0,0 +1,6 @@
+import { ValidationArguments, ValidatorConstraintInterface } from 'class-validator';
+/** `to`: mayor que `from` y a lo más 7 días después; sin `from` legible lo rechaza su propio validador. */
+export declare class IsMovementsRangeValid implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailIntegration/validators/IsMovementsRangeValid.js

@@ -0,0 +1,28 @@
+"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.IsMovementsRangeValid = void 0;
+const class_validator_1 = require("class-validator");
+const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
+/** `to`: mayor que `from` y a lo más 7 días después; sin `from` legible lo rechaza su propio validador. */
+let IsMovementsRangeValid = class IsMovementsRangeValid {
+    validate(value, args) {
+        const from = Date.parse(String(args.object.from));
+        const to = Date.parse(String(value));
+        if (Number.isNaN(from) || Number.isNaN(to))
+            return true;
+        return to > from && to - from <= retailIntegrationLimits_1.RETAIL_MOVEMENTS_RANGE_MAX_MS;
+    }
+    defaultMessage() {
+        return 'to debe ser mayor que from y a lo más 7 días después';
+    }
+};
+exports.IsMovementsRangeValid = IsMovementsRangeValid;
+exports.IsMovementsRangeValid = IsMovementsRangeValid = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'isMovementsRangeValid', async: false })
+], IsMovementsRangeValid);

package/package.json

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

package/src/platformRbac/dtos/CreateTenantUserRequest.ts

@@ -14,7 +14,8 @@ const hasAnyGrantField = (o: CreateTenantUserRequest): boolean =>
  * Consumido por el alta de usuario orquestada de SureKeep F1 (retail-org → RBAC → RetailUser) vía api-invoker.
  * - Usuario provisionado en estado INVITED (mitiga orphan si el paso siguiente en retail-org falla).
  * - Idempotente por identidad Cognito.
- * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol no hay invitación.
+ * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol exige `suppressInvitation: true`
+ *   y la invitación queda pendiente (`invitationPending`) hasta asignar el primer rol.
  * - `createdBy` = cognitoSub del admin real (audit + grantedBy del assignment).
  * - `customFields` = valores de los campos personalizados del tenant; si el correo ya tiene usuario, se fusionan.
  */

package/src/platformRbac/dtos/UpdateTenantUserEmailRequest.ts

@@ -0,0 +1,12 @@
+import { Expose, Transform } from 'class-transformer';
+import { IsEmail, IsNotEmpty, IsString } from 'class-validator';
+
+/** Body M2M que cambia el correo de un usuario del tenant; el correo se guarda en minúsculas. */
+export class UpdateTenantUserEmailRequest {
+    @Expose()
+    @Transform(({ value }) => (typeof value === 'string' ? value.trim().toLowerCase() : value))
+    @IsEmail()
+    email!: string;
+
+    @Expose() @IsString() @IsNotEmpty() actedBy!: string;
+}

package/src/platformRbac/enums/Permission.ts

@@ -165,6 +165,8 @@ export enum Permission {
     TENANT_INTEGRATION_DIAGNOSTIC = 'tenant.integration.diagnostic',
     // Alta, rotación de secreto y edición de IPs de usuarios de API; se exige además de tenant.user.create.
     TENANT_API_USER_MANAGE = 'tenant.api_user.manage',
+    // Activa la integración de un retailer externo (Zentral); scope PLATFORM.
+    PLATFORM_RETAIL_INTEGRATION_ACTIVATE = 'platform.retail_integration.activate',
 }
 
 /**
@@ -286,6 +288,7 @@ export const PERMISSION_BIT_ORDER: readonly Permission[] = [
     Permission.PLATFORM_INTEGRATION_KEY_REVOKE,
     Permission.TENANT_INTEGRATION_DIAGNOSTIC,
     Permission.TENANT_API_USER_MANAGE,
+    Permission.PLATFORM_RETAIL_INTEGRATION_ACTIVATE,
 ] as const;
 
 function djb2(input: string): number {

package/src/platformRbac/index.ts

@@ -167,6 +167,7 @@ export type { ListTenantUsersResponse } from './dtos/ListTenantUsersResponse';
 export type { TenantUserListItemResponse } from './dtos/TenantUserListItemResponse';
 export type { GetTenantUserResponse } from './dtos/GetTenantUserResponse';
 export * from './dtos/UpdateTenantUserRequest';
+export * from './dtos/UpdateTenantUserEmailRequest';
 export * from './dtos/DeleteTenantUserRequest';
 export * from './dtos/DisableTenantUserRequest';
 export * from './dtos/EnableTenantUserRequest';

package/src/retailIntegration/constants/retailIntegrationLimits.ts

@@ -29,3 +29,40 @@ export const RETAIL_DECIMAL_PATTERN = /^\d+\.\d{2}$/;
 
 /** Tope de identificadores por consulta de inventario en vivo. */
 export const RETAIL_LIVE_CHECK_IDENTIFIERS_MAX = 50;
+
+/** Tope de piezas por evento `InventoryMovementV1`; más se rechaza con INVALID_PAYLOAD. */
+export const RETAIL_EVENT_PIECES_MAX = 30;
+
+/** Tope de ids y códigos libres del retailer, como `externalId`. */
+export const RETAIL_ID_TEXT_MAX_LENGTH = 64;
+
+/** Tope de textos cortos de los payloads: nombres, dirección, teléfono, marca, modelo, `identifier`. */
+export const RETAIL_SHORT_TEXT_MAX_LENGTH = 255;
+
+/** Tope de textos largos de los payloads: descripción y referencia. */
+export const RETAIL_LONG_TEXT_MAX_LENGTH = 1000;
+
+/** Tope de existencias por evento `InventoryMovementV1`. */
+export const RETAIL_EVENT_STOCK_MAX = 200;
+
+/** Tope de financieras elegibles por producto. */
+export const RETAIL_ELIGIBLE_FINANCIERS_MAX = 50;
+
+/** Decimal de los eventos del retailer: hasta 12 enteros y dos decimales, nunca negativo. */
+export const RETAIL_EVENT_DECIMAL_PATTERN = /^\d{1,12}\.\d{2}$/;
+
+/** Tope del `nextToken` opaco que devuelve Zentral. */
+export const RETAIL_NEXT_TOKEN_MAX_LENGTH = 2048;
+
+/** Id que asigna Zentral, como `externalSaleId`: no vacío, sin espacios y de a lo más 64. */
+export const RETAIL_EXTERNAL_ID_PATTERN = /^\S{1,64}$/;
+
+/** Tope del `code` en el cuerpo de error de Zentral. */
+export const RETAIL_ERROR_CODE_MAX_LENGTH = 64;
+
+/** Rango de `lineIndex` en un error de línea de venta. */
+export const RETAIL_LINE_INDEX_MIN = 0;
+export const RETAIL_LINE_INDEX_MAX = 999;
+
+/** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
+export const RETAIL_MOVEMENTS_RANGE_MAX_MS = 7 * 24 * 60 * 60 * 1000;

package/src/retailIntegration/dtos/CheckRetailInventoryRequest.ts

@@ -8,7 +8,10 @@ function csvToArray({ value }: { value: unknown }): unknown {
     return typeof value === 'string' ? value.split(',').map((item) => item.trim()) : value;
 }
 
-/** Query de `GET /private/retail/inventory/live-check`; `identifiers` llega como csv. */
+/**
+ * Query de `GET /private/retail/inventory/live-check`; `identifiers` llega como csv.
+ * @deprecated el live-check se va a quitar; el inventario se toma de movimientos y de la lectura diaria.
+ */
 export class CheckRetailInventoryRequest extends RetailTenantQuery {
     @IsString() @Matches(/\S/) storeId!: string;
 

package/src/retailIntegration/dtos/GetRetailInventoryRequest.ts

@@ -1,8 +1,8 @@
 import { IsString, Matches } from 'class-validator';
-import { RetailListQuery } from './RetailListQuery';
+import { RetailPagedQuery } from './RetailPagedQuery';
 
-/** Query de `GET /private/retail/inventory`; el inventario es por tienda y no pagina. */
-export class GetRetailInventoryRequest extends RetailListQuery {
+/** Query de `GET /private/retail/inventory`; el inventario es por tienda y pagina con `limit`/`nextToken`. */
+export class GetRetailInventoryRequest extends RetailPagedQuery {
     @IsString()
     @Matches(/\S/)
     storeId!: string;

package/src/retailIntegration/dtos/InventoryEventPayload.ts

@@ -1,6 +1,12 @@
 import { Type } from 'class-transformer';
-import { IsArray, IsIn, IsInt, IsString, Matches, Min, Validate, ValidateNested } from 'class-validator';
-import { RETAIL_ENTITY_ID_PATTERN, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
+import { ArrayMaxSize, IsArray, IsIn, IsInt, IsString, Matches, MaxLength, Min, Validate, ValidateNested } from 'class-validator';
+import {
+    RETAIL_EVENT_PIECES_MAX,
+    RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_EVENT_STOCK_MAX,
+    RETAIL_SHORT_TEXT_MAX_LENGTH,
+    RETAIL_SKU_PATTERN,
+} from '../constants/retailIntegrationLimits';
 import { RetailMovementTypeEnum, RetailPieceStatusEnum } from '../enums';
 import type { RetailPieceReason, RetailPieceStatus, RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
 import { HasUniqueKeys, ReasonMatchesStatus, TargetStoreMatchesMovement } from '../validators/payloadValidators';
@@ -10,7 +16,7 @@ export type RetailMovementType = `${RetailMovementTypeEnum}`;
 /** Pieza con IMEI o serie, como quedó después del movimiento. */
 export class PieceEventPayload implements RetailSystemPiece {
     @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
-    @IsString() @Matches(/\S/) identifier!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) identifier!: string;
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
     @IsIn(Object.values(RetailPieceStatusEnum)) status!: RetailPieceStatus;
     @Validate(ReasonMatchesStatus) reason!: RetailPieceReason | null;
@@ -28,6 +34,6 @@ export class InventoryEventPayload {
     @IsIn(Object.values(RetailMovementTypeEnum)) movementType!: RetailMovementType;
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
     @Validate(TargetStoreMatchesMovement) targetStoreId!: string | null;
-    @IsArray() @ValidateNested({ each: true }) @Type(() => PieceEventPayload) @Validate(HasUniqueKeys, ['identifier']) pieces!: PieceEventPayload[];
-    @IsArray() @ValidateNested({ each: true }) @Type(() => StockEventPayload) @Validate(HasUniqueKeys, ['storeId', 'sku']) stock!: StockEventPayload[];
+    @IsArray() @ArrayMaxSize(RETAIL_EVENT_PIECES_MAX) @ValidateNested({ each: true }) @Type(() => PieceEventPayload) @Validate(HasUniqueKeys, ['identifier']) pieces!: PieceEventPayload[];
+    @IsArray() @ArrayMaxSize(RETAIL_EVENT_STOCK_MAX) @ValidateNested({ each: true }) @Type(() => StockEventPayload) @Validate(HasUniqueKeys, ['storeId', 'sku']) stock!: StockEventPayload[];
 }

package/src/retailIntegration/dtos/ListRetailInventoryMovementsRequest.ts

@@ -0,0 +1,14 @@
+import { Validate } from 'class-validator';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+import { IsMovementsRangeValid } from '../validators/IsMovementsRangeValid';
+import { RetailPagedQuery } from './RetailPagedQuery';
+
+/** Query de `GET /private/retail/inventory/movements`: rango `[from, to)` de a lo más 7 días. */
+export class ListRetailInventoryMovementsRequest extends RetailPagedQuery {
+    @Validate(IsIsoDateTimeWithZone)
+    from!: string;
+
+    @Validate(IsIsoDateTimeWithZone)
+    @Validate(IsMovementsRangeValid)
+    to!: string;
+}

package/src/retailIntegration/dtos/ProductEventPayload.ts

@@ -1,6 +1,13 @@
 import { Type } from 'class-transformer';
-import { IsArray, IsDefined, IsIn, IsString, Matches, Validate, ValidateIf, ValidateNested } from 'class-validator';
-import { RETAIL_DECIMAL_PATTERN, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
+import { ArrayMaxSize, IsArray, IsDefined, IsIn, IsObject, IsString, Matches, MaxLength, Validate, ValidateIf, ValidateNested } from 'class-validator';
+import {
+    RETAIL_ELIGIBLE_FINANCIERS_MAX,
+    RETAIL_EVENT_DECIMAL_PATTERN,
+    RETAIL_ID_TEXT_MAX_LENGTH,
+    RETAIL_LONG_TEXT_MAX_LENGTH,
+    RETAIL_SHORT_TEXT_MAX_LENGTH,
+    RETAIL_SKU_PATTERN,
+} from '../constants/retailIntegrationLimits';
 import {
     RetailCurrencyEnum,
     RetailFinancierEnum,
@@ -26,26 +33,26 @@ import { isNullOrValidated } from '../validators/payloadValidators';
 
 /** Precio del producto en decimales string. */
 export class ProductEventPricePayload implements RetailSystemProductPrice {
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) basePrice!: string;
-    @ValidateIf(isNullOrValidated) @IsString() @Matches(RETAIL_DECIMAL_PATTERN) listPrice!: string | null;
+    @IsString() @Matches(RETAIL_EVENT_DECIMAL_PATTERN) basePrice!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @Matches(RETAIL_EVENT_DECIMAL_PATTERN) listPrice!: string | null;
     @Validate(IsIsoDateTimeWithZone) effectiveFrom!: string;
 }
 
 /** Payload de los eventos de producto: el producto completo. */
 export class ProductEventPayload implements RetailSystemProduct {
     @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
-    @IsString() @Matches(/\S/) externalId!: string;
-    @IsString() @Matches(/\S/) brand!: string;
-    @IsString() @Matches(/\S/) model!: string;
-    @ValidateIf(isNullOrValidated) @IsString() color!: string | null;
-    @ValidateIf(isNullOrValidated) @IsString() capacity!: string | null;
-    @ValidateIf(isNullOrValidated) @IsString() description!: string | null;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_ID_TEXT_MAX_LENGTH) externalId!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) brand!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) model!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) color!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) capacity!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_LONG_TEXT_MAX_LENGTH) description!: string | null;
     @IsIn(Object.values(RetailProductCategoryEnum)) category!: RetailProductCategory;
     @IsIn(Object.values(RetailTrackingModeEnum)) trackingMode!: RetailTrackingMode;
     @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailProductTierEnum)) tier!: RetailProductTier | null;
     @IsIn(Object.values(RetailCurrencyEnum)) currencyId!: RetailCurrency;
-    @IsDefined() @ValidateNested() @Type(() => ProductEventPricePayload) price!: ProductEventPricePayload;
-    @IsArray() @IsIn(Object.values(RetailFinancierEnum), { each: true }) eligibleFinanciers!: RetailFinancier[];
+    @IsDefined() @IsObject() @ValidateNested() @Type(() => ProductEventPricePayload) price!: ProductEventPricePayload;
+    @IsArray() @ArrayMaxSize(RETAIL_ELIGIBLE_FINANCIERS_MAX) @IsIn(Object.values(RetailFinancierEnum), { each: true }) eligibleFinanciers!: RetailFinancier[];
     @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailMdmProviderEnum)) mdmProvider!: RetailMdmProvider | null;
     @IsIn(Object.values(RetailProductStatusEnum)) status!: RetailProductStatus;
 }

package/src/retailIntegration/dtos/ReconciliationPageMessage.ts

@@ -1,6 +1,7 @@
 import { Expose } from 'class-transformer';
-import { IsEnum, IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
+import { IsEnum, IsInt, IsNotEmpty, IsOptional, IsString, Matches, Min, Validate } from 'class-validator';
 import { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
 
 /** Mensaje de la cola de revisión: una página, o una tienda completa en inventario. */
 export class ReconciliationPageMessage {
@@ -43,4 +44,23 @@ export class ReconciliationPageMessage {
     @IsInt()
     @Min(0)
     requeueCount?: number;
+
+    /** Cursor de Zentral para la siguiente página del inventario de la tienda. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(/\S/)
+    nextToken?: string;
+
+    /** Inicio del rango de movimientos, incluido. */
+    @Expose()
+    @IsOptional()
+    @Validate(IsIsoDateTimeWithZone)
+    from?: string;
+
+    /** Fin del rango de movimientos, excluido. */
+    @Expose()
+    @IsOptional()
+    @Validate(IsIsoDateTimeWithZone)
+    to?: string;
 }

package/src/retailIntegration/dtos/RetailOutboundResponses.ts

@@ -1,5 +1,5 @@
 import { RetailInventoryMeta, RetailPageMeta } from '../models/RetailPageMeta';
-import { RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
+import { RetailSystemInventoryMovement, RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
 import { RetailSystemProduct } from '../models/RetailSystemProduct';
 import { RetailSystemStore } from '../models/RetailSystemStore';
 import { RetailSystemUser } from '../models/RetailSystemUser';
@@ -23,6 +23,12 @@ export interface GetRetailInventoryResponse {
     meta: RetailInventoryMeta;
 }
 
+/** `data` de `GET /private/retail/inventory/movements`. */
+export interface ListRetailInventoryMovementsResponse {
+    items: RetailSystemInventoryMovement[];
+    meta: RetailPageMeta;
+}
+
 /** `data` de `GET /private/retail/users`. */
 export interface ListRetailUsersResponse {
     items: RetailSystemUser[];
@@ -39,7 +45,10 @@ export interface CancelRetailSaleResponse {
     saleId: string;
 }
 
-/** `data` de `GET /private/retail/inventory/live-check`: los identificadores que el retailer lista en la tienda. */
+/**
+ * `data` de `GET /private/retail/inventory/live-check`: los identificadores que el retailer lista en la tienda.
+ * @deprecated el live-check se va a quitar; el inventario se toma de movimientos y de la lectura diaria.
+ */
 export interface CheckRetailInventoryResponse {
     listed: string[];
     generatedAt: string;

package/src/retailIntegration/dtos/RetailSystemResponses.ts

@@ -0,0 +1,75 @@
+import { Type } from 'class-transformer';
+import {
+    IsArray,
+    IsInt,
+    IsObject,
+    IsOptional,
+    IsString,
+    Matches,
+    Max,
+    MaxLength,
+    Min,
+    Validate,
+    ValidateIf,
+    ValidateNested,
+} from 'class-validator';
+import {
+    RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_ERROR_CODE_MAX_LENGTH,
+    RETAIL_ID_TEXT_MAX_LENGTH,
+    RETAIL_LINE_INDEX_MAX,
+    RETAIL_LINE_INDEX_MIN,
+    RETAIL_NEXT_TOKEN_MAX_LENGTH,
+    RETAIL_EXTERNAL_ID_PATTERN,
+} from '../constants/retailIntegrationLimits';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+import { isNullOrValidated } from '../validators/payloadValidators';
+import { ReceiveInventoryEventRequest } from './ReceiveInventoryEventRequest';
+
+/** `meta` de una página de Zentral; `nextToken` en `null` cierra la lectura y nunca se omite. */
+export class RetailSystemPageMeta {
+    @IsInt() @Min(0) count!: number;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_NEXT_TOKEN_MAX_LENGTH) nextToken!: string | null;
+}
+
+/** Página de una lista de Zentral; cada consumidor valida sus renglones de `data`. */
+export class RetailSystemPageResponse {
+    @IsArray() data!: unknown[];
+    @IsObject() @ValidateNested() @Type(() => RetailSystemPageMeta) meta!: RetailSystemPageMeta;
+}
+
+/** `data` de una página de `GET /inventory`: piezas y existencias crudas. */
+export class RetailSystemInventoryData {
+    @IsArray() pieces!: unknown[];
+    @IsArray() stock!: unknown[];
+}
+
+/** `meta` de una página de `GET /inventory`; `generatedAt` es igual en toda la lectura. */
+export class RetailSystemInventoryMeta extends RetailSystemPageMeta {
+    @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
+    @Validate(IsIsoDateTimeWithZone) generatedAt!: string;
+}
+
+/** Respuesta de `GET /inventory` de Zentral. */
+export class RetailSystemInventoryResponse {
+    @IsObject() @ValidateNested() @Type(() => RetailSystemInventoryData) data!: RetailSystemInventoryData;
+    @IsObject() @ValidateNested() @Type(() => RetailSystemInventoryMeta) meta!: RetailSystemInventoryMeta;
+}
+
+/** `data` de `POST /sales` de Zentral. */
+export class RetailSystemSaleResponse {
+    @IsString() @MaxLength(RETAIL_ID_TEXT_MAX_LENGTH) @Matches(RETAIL_EXTERNAL_ID_PATTERN) externalSaleId!: string;
+}
+
+/** Cuerpo de error de Zentral; `lineIndex` solo viene en errores de una línea de venta. */
+export class RetailSystemErrorBody {
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_ERROR_CODE_MAX_LENGTH) code!: string;
+    @IsOptional() @IsString() msg?: string;
+    @IsOptional() @IsInt() @Min(RETAIL_LINE_INDEX_MIN) @Max(RETAIL_LINE_INDEX_MAX) lineIndex?: number;
+}
+
+/** Respuesta de `GET /inventory/movements`: cada elemento es el mismo sobre del webhook de inventario. */
+export class RetailSystemMovementsResponse {
+    @IsArray() @ValidateNested({ each: true }) @Type(() => ReceiveInventoryEventRequest) data!: ReceiveInventoryEventRequest[];
+    @IsObject() @ValidateNested() @Type(() => RetailSystemPageMeta) meta!: RetailSystemPageMeta;
+}

package/src/retailIntegration/dtos/RetailUserEventPayload.ts

@@ -1,5 +1,5 @@
-import { IsEmail, IsIn, IsString, Matches, ValidateIf } from 'class-validator';
-import { RETAIL_ENTITY_ID_PATTERN, RETAIL_ZONE_ID_PATTERN } from '../constants/retailIntegrationLimits';
+import { IsEmail, IsIn, IsString, Matches, MaxLength, ValidateIf } from 'class-validator';
+import { RETAIL_ENTITY_ID_PATTERN, RETAIL_SHORT_TEXT_MAX_LENGTH, RETAIL_ZONE_ID_PATTERN } from '../constants/retailIntegrationLimits';
 import { RetailUserAccessStatusEnum, RetailUserRoleEnum } from '../enums';
 import type { RetailSystemUser, RetailUserAccessStatus, RetailUserRole } from '../models/RetailSystemUser';
 import { isNullOrValidated } from '../validators/payloadValidators';
@@ -7,9 +7,9 @@ import { isNullOrValidated } from '../validators/payloadValidators';
 /** Payload de los cuatro eventos de usuario: el usuario completo. */
 export class RetailUserEventPayload implements RetailSystemUser {
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) retailUserId!: string;
-    @IsString() @Matches(/\S/) displayName!: string;
-    @IsEmail() email!: string;
-    @ValidateIf(isNullOrValidated) @IsString() phone!: string | null;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) displayName!: string;
+    @IsEmail() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) email!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) phone!: string | null;
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) homeStoreId!: string;
     @ValidateIf(isNullOrValidated) @IsString() @Matches(RETAIL_ZONE_ID_PATTERN) zoneId!: string | null;
     @IsIn(Object.values(RetailUserRoleEnum)) role!: RetailUserRole;

package/src/retailIntegration/dtos/StoreEventPayload.ts

@@ -1,7 +1,9 @@
 import { Type } from 'class-transformer';
-import { IsDefined, IsIn, IsNumber, IsString, Length, Matches, Max, Min, ValidateIf, ValidateNested } from 'class-validator';
+import { IsDefined, IsIn, IsNumber, IsObject, IsString, Length, Matches, Max, MaxLength, Min, ValidateIf, ValidateNested } from 'class-validator';
 import {
     RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_LONG_TEXT_MAX_LENGTH,
+    RETAIL_SHORT_TEXT_MAX_LENGTH,
     RETAIL_STORE_CODE_MAX_LENGTH,
     RETAIL_ZIP_CODE_MAX_LENGTH,
     RETAIL_ZIP_CODE_MIN_LENGTH,
@@ -16,15 +18,15 @@ const LNG_MAX = 180;
 
 /** Dirección de la tienda; los opcionales llegan como `null`, nunca se omiten. */
 export class StoreEventAddressPayload implements RetailSystemStoreAddress {
-    @IsString() @Matches(/\S/) address1!: string;
-    @ValidateIf(isNullOrValidated) @IsString() externalNumber!: string | null;
-    @ValidateIf(isNullOrValidated) @IsString() internalNumber!: string | null;
-    @ValidateIf(isNullOrValidated) @IsString() neighborhood!: string | null;
-    @IsString() @Matches(/\S/) city!: string;
-    @IsString() @Matches(/\S/) state!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) address1!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) externalNumber!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) internalNumber!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) neighborhood!: string | null;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) city!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) state!: string;
     @IsString() @Length(RETAIL_ZIP_CODE_MIN_LENGTH, RETAIL_ZIP_CODE_MAX_LENGTH) zipCode!: string;
-    @ValidateIf(isNullOrValidated) @IsString() country!: string | null;
-    @ValidateIf(isNullOrValidated) @IsString() reference!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) country!: string | null;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_LONG_TEXT_MAX_LENGTH) reference!: string | null;
 }
 
 /** Coordenada de la tienda; `null` si no se informa. */
@@ -37,11 +39,11 @@ export class StoreEventLocationPayload implements RetailSystemStoreLocation {
 export class StoreEventPayload implements RetailSystemStore {
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
     @IsString() @Length(1, RETAIL_STORE_CODE_MAX_LENGTH) code!: string;
-    @IsString() @Matches(/\S/) name!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) name!: string;
     @ValidateIf(isNullOrValidated) @IsString() @Matches(RETAIL_ZONE_ID_PATTERN) zoneId!: string | null;
-    @IsDefined() @ValidateNested() @Type(() => StoreEventAddressPayload) address!: StoreEventAddressPayload;
-    @IsDefined() @ValidateNested() @Type(() => StoreEventLocationPayload) location!: StoreEventLocationPayload;
-    @IsString() @Matches(/\S/) phone!: string;
-    @ValidateIf(isNullOrValidated) @IsString() schedule!: string | null;
+    @IsDefined() @IsObject() @ValidateNested() @Type(() => StoreEventAddressPayload) address!: StoreEventAddressPayload;
+    @IsDefined() @IsObject() @ValidateNested() @Type(() => StoreEventLocationPayload) location!: StoreEventLocationPayload;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) phone!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) schedule!: string | null;
     @IsIn(Object.values(RetailStoreStatusEnum)) status!: RetailStoreStatus;
 }

package/src/retailIntegration/enums/ReconciliationEntityEnum.ts

@@ -4,4 +4,5 @@ export enum ReconciliationEntityEnum {
     USERS = 'USERS',
     CATALOG = 'CATALOG',
     INVENTORY = 'INVENTORY',
+    MOVEMENTS = 'MOVEMENTS',
 }

package/src/retailIntegration/enums/ReconciliationTriggerEnum.ts

@@ -1,6 +1,8 @@
-/** Quién abrió la corrida: el reloj horario, el botón «Actualizar» o la activación del retailer. */
+/** Quién abrió la corrida: el reloj horario o diario, el botón «Actualizar», la activación o una discrepancia. */
 export enum ReconciliationTriggerEnum {
     SCHEDULED = 'SCHEDULED',
     MANUAL = 'MANUAL',
     ACTIVATION = 'ACTIVATION',
+    DISCREPANCY = 'DISCREPANCY',
+    DAILY = 'DAILY',
 }

package/src/retailIntegration/index.ts

@@ -2,6 +2,7 @@ export * from './constants/retailIntegrationLimits';
 export * from './constants/retailIntegrationErrorHttpStatus';
 export * from './enums';
 export * from './validators/IsIsoDateTimeWithZone';
+export * from './validators/IsMovementsRangeValid';
 export * from './dtos/RetailEventEnvelope';
 export * from './dtos/ReceiveStoreEventRequest';
 export * from './dtos/ReceiveRetailUserEventRequest';
@@ -21,11 +22,13 @@ export * from './dtos/RetailPagedQuery';
 export * from './dtos/ListRetailStoresRequest';
 export * from './dtos/ListRetailCatalogRequest';
 export * from './dtos/GetRetailInventoryRequest';
+export * from './dtos/ListRetailInventoryMovementsRequest';
 export * from './dtos/ListRetailUsersRequest';
 export * from './dtos/RegisterRetailSaleRequest';
 export * from './dtos/CancelRetailSaleRequest';
 export * from './dtos/CheckRetailInventoryRequest';
 export * from './dtos/RetailOutboundResponses';
+export * from './dtos/RetailSystemResponses';
 export * from './models/RetailPageMeta';
 export * from './models/RetailSystemStore';
 export * from './models/RetailSystemProduct';

package/src/retailIntegration/models/RetailPageMeta.ts

@@ -4,8 +4,10 @@ export interface RetailPageMeta {
     nextToken: string | null;
 }
 
-/** `meta` del inventario de una tienda. */
+/** `meta` del inventario de una tienda; `count` y `nextToken` llegan cuando la lectura pagina. */
 export interface RetailInventoryMeta {
     storeId: string;
     generatedAt: string;
+    count?: number;
+    nextToken?: string | null;
 }

package/src/retailIntegration/models/RetailSystemInventory.ts

@@ -1,4 +1,5 @@
-import { RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
+import type { InventoryEventPayload } from '../dtos/InventoryEventPayload';
+import { InventoryEventTypeEnum, RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
 
 export type RetailPieceStatus = `${RetailPieceStatusEnum}`;
 export type RetailPieceReason = `${RetailPieceReasonEnum}`;
@@ -18,3 +19,11 @@ export interface RetailSystemStock {
     storeId: string;
     qty: number;
 }
+
+/** Movimiento de inventario de Zentral: el mismo sobre que llega a `POST /webhooks/inventory`. */
+export interface RetailSystemInventoryMovement {
+    eventId: string;
+    eventType: `${InventoryEventTypeEnum}`;
+    occurredAt: string;
+    payload: InventoryEventPayload;
+}

package/src/retailIntegration/validators/IsMovementsRangeValid.ts

@@ -0,0 +1,17 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { RETAIL_MOVEMENTS_RANGE_MAX_MS } from '../constants/retailIntegrationLimits';
+
+/** `to`: mayor que `from` y a lo más 7 días después; sin `from` legible lo rechaza su propio validador. */
+@ValidatorConstraint({ name: 'isMovementsRangeValid', async: false })
+export class IsMovementsRangeValid implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const from = Date.parse(String((args.object as { from?: unknown }).from));
+        const to = Date.parse(String(value));
+        if (Number.isNaN(from) || Number.isNaN(to)) return true;
+        return to > from && to - from <= RETAIL_MOVEMENTS_RANGE_MAX_MS;
+    }
+
+    defaultMessage(): string {
+        return 'to debe ser mayor que from y a lo más 7 días después';
+    }
+}