@fiado/type-kit 3.584.0 → 3.586.0

package/package.json

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

package/src/collection/enums/DisbursementType.ts

@@ -7,4 +7,6 @@ export enum DisbursementType {
     MEX_BONUS = 'MEX_BONUS',
     /** Comisión de vendedor. */
     MEX_SELLER_COMMISSION = 'MEX_SELLER_COMMISSION',
+    /** Abono de recompensas de `rewards-business`. */
+    MEX_REWARD = 'MEX_REWARD',
 }

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/productCatalog/enums/ProductSubtypeEnum.ts

@@ -86,6 +86,10 @@ export enum ProductSubtypeEnum {
     // Comisión de vendedor de SureKeep abonada a la wallet.
     SUREKEEP_SELLER_COMMISSION_MX = "SELLER_COMMISSION_MX",
 
+    //REWARDS
+    // Abono de recompensas de `rewards-business`.
+    REWARD_MX = "REWARD_MX",
+
     //STORE
     STORE_PHONE = "PHONE",
 

package/src/productCatalog/enums/ProductTypeEnum.ts

@@ -63,5 +63,7 @@ export enum ProductTypeEnum {
      * Dispersión SPEI de liquidaciones de beneficios (money-transfer-connector).
      * Producto del catálogo para la orden STP que sale con `source=BENEFITS_SETTLEMENT`.
      */
-    MONEY_TRANSFER_SA = "MONEY_TRANSFER_SA"
+    MONEY_TRANSFER_SA = "MONEY_TRANSFER_SA",
+    /** Abono de recompensas de `rewards-business`. */
+    REWARDS = "REWARDS"
 }

package/src/retailIntegration/constants/retailIntegrationLimits.ts

@@ -50,3 +50,19 @@ 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/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/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/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';
+    }
+}

package/src/rewards/dtos/backoffice/BackofficeGrantItemResponse.ts

@@ -1,8 +1,17 @@
 import { GrantItemResponse } from '../responses/GrantItemResponse';
+import { LimitWaitReasonEnum } from '../../enums/LimitWaitReasonEnum';
 import { BackofficeGrantAttemptResponse } from './BackofficeGrantAttemptResponse';
 
 export class BackofficeGrantItemResponse extends GrantItemResponse {
     /** Nombre de la recompensa congelada en la entrega. */
     name: string;
     attempts: BackofficeGrantAttemptResponse[];
+    /** Motivo de la espera por tope; solo cuando el ítem está en `WAITING_LIMIT`. */
+    waitReason?: LimitWaitReasonEnum;
+    /** Epoch ms del próximo intento programado. */
+    retryNotBefore?: number;
+    /** Epoch ms en que el ítem entró en espera. */
+    waitingSince?: number;
+    /** Cantidad de rechazos por tope acumulados. */
+    limitRejections?: number;
 }

package/src/rewards/enums/GrantItemStatusEnum.ts

@@ -5,6 +5,8 @@ export enum GrantItemStatusEnum {
      * ocurrido y el adaptador debe reconciliar antes de reintentar.
      */
     PROCESSING = 'PROCESSING',
+    /** Espera por tope de nivel de la cuenta destino: no es `PROCESSING` ni `FAILED`; se reintenta solo. */
+    WAITING_LIMIT = 'WAITING_LIMIT',
     GRANTED = 'GRANTED',
     FAILED = 'FAILED',
     SKIPPED = 'SKIPPED',

package/src/rewards/enums/LimitWaitReasonEnum.ts

@@ -0,0 +1,7 @@
+/** Motivo por el que un ítem espera: `processorCode` del rechazo por tope de nivel de la cuenta destino. */
+export enum LimitWaitReasonEnum {
+    /** Tope mensual de monto del nivel de la cuenta. */
+    MONTHLY_AMOUNT_EXCEEDED = 'ACCOUNT_LEVEL_MAX_MONTHLY_AMOUNT_EXCEEDED',
+    /** Tope de saldo disponible del nivel de la cuenta. */
+    AVAILABLE_BALANCE_EXCEEDED = 'ACCOUNT_LEVEL_MAX_AVAILABLE_BALANCE_EXCEEDED',
+}

package/src/rewards/enums/RewardItemCodeEnum.ts

@@ -0,0 +1,9 @@
+/** Códigos de resultado de un ítem de entrega que no vienen del proveedor. */
+export enum RewardItemCodeEnum {
+    /** El monto del ítem supera el máximo permitido. */
+    AMOUNT_ABOVE_MAX = 'AMOUNT_ABOVE_MAX',
+    /** Venció la espera por tope (30 días desde `waitingSince`). */
+    LIMIT_WAIT_EXPIRED = 'LIMIT_WAIT_EXPIRED',
+    /** Resultado desconocido agotado: no se puede asegurar si el abono ocurrió. */
+    OUTCOME_UNKNOWN = 'OUTCOME_UNKNOWN',
+}

package/src/rewards/index.ts

@@ -2,6 +2,8 @@
 export * from './enums/RewardsMessageTypeEnum';
 export * from './enums/GrantStatusEnum';
 export * from './enums/GrantItemStatusEnum';
+export * from './enums/LimitWaitReasonEnum';
+export * from './enums/RewardItemCodeEnum';
 export * from './enums/GrantRejectReasonEnum';
 export * from './enums/GrantFailedReasonEnum';
 export * from './enums/ItemErrorCategoryEnum';