@fiado/type-kit 3.501.0 → 3.503.0

package/src/platformRbac/dtos/CreateTenantUserRequest.ts

@@ -1,7 +1,11 @@
 import { Expose } from 'class-transformer';
-import { IsEmail, IsEnum, IsNotEmpty, IsObject, IsOptional, IsString, Validate } from 'class-validator';
+import { IsEmail, IsEnum, IsNotEmpty, IsObject, IsOptional, IsString, Validate, ValidateIf } from 'class-validator';
 import { PermissionScope } from '../enums/PermissionScope';
 import { IsStringValueRecord } from '../../common/validators/IsStringValueRecord';
+import { SuppressInvitationRequiredWithoutRole } from '../validators/SuppressInvitationRequiredWithoutRole';
+
+const hasAnyGrantField = (o: CreateTenantUserRequest): boolean =>
+    o.roleId !== undefined || o.scope !== undefined || o.scopeRef !== undefined;
 
 /**
  * Body del POST /internal/tenants/{tenantId}/users (endpoint privado, VPC/ANONIMUS). `tenantId` viaja en el path.
@@ -10,16 +14,18 @@ import { IsStringValueRecord } from '../../common/validators/IsStringValueRecord
  * 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.
- * - `scope`/`scopeRef` = grant del rol (ej. LEVEL_3 + storeId para un vendedor de tienda).
+ * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol no hay invitación.
  * - `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.
  */
 export class CreateTenantUserRequest {
     @Expose() @IsEmail() email!: string;
     @Expose() @IsOptional() @IsString() @IsNotEmpty() displayName?: string;
-    @Expose() @IsString() @IsNotEmpty() roleId!: string;
-    @Expose() @IsEnum(PermissionScope) scope!: PermissionScope;
-    @Expose() @IsString() @IsNotEmpty() scopeRef!: string;
+    @Expose() @ValidateIf(hasAnyGrantField) @IsString() @IsNotEmpty() roleId?: string;
+    @Expose() @ValidateIf(hasAnyGrantField) @IsEnum(PermissionScope) scope?: PermissionScope;
+    @Expose() @ValidateIf(hasAnyGrantField) @IsString() @IsNotEmpty() scopeRef?: string;
+    /** Solo en el alta sin rol: no se manda invitación hasta que alguien asigne el primer rol. */
+    @Expose() @Validate(SuppressInvitationRequiredWithoutRole) suppressInvitation?: boolean;
     @Expose() @IsString() @IsNotEmpty() createdBy!: string;
     @Expose()
     @IsOptional()

package/src/platformRbac/validators/SuppressInvitationRequiredWithoutRole.ts

@@ -0,0 +1,14 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+
+/** Sin rol el alta exige `suppressInvitation: true`; con rol no se admite, porque el alta con rol siempre invita. */
+@ValidatorConstraint({ name: 'suppressInvitationRequiredWithoutRole', async: false })
+export class SuppressInvitationRequiredWithoutRole implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const hasRole = (args.object as { roleId?: unknown }).roleId !== undefined;
+        return hasRole ? value === undefined : value === true;
+    }
+
+    defaultMessage(): string {
+        return 'suppressInvitation: true va solo y siempre en el alta sin rol';
+    }
+}

package/src/retailIntegration/constants/retailIntegrationLimits.ts

@@ -7,3 +7,22 @@ export const RETAIL_LIST_LIMIT_MAX = 200;
 
 /** Forma válida de un `tenantId`; también arma el nombre del secreto del retailer. */
 export const RETAIL_TENANT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Id de tienda, usuario o zona del retailer: llave de DynamoDB y BYOID de RBAC. */
+export const RETAIL_ENTITY_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Zona del retailer; `NOZONE-` queda reservado para la zona centinela de Fiado. */
+export const RETAIL_ZONE_ID_PATTERN = /^(?!NOZONE-)[A-Za-z0-9_-]{1,64}$/;
+
+/** Código corto de tienda: de 1 a 10 caracteres. */
+export const RETAIL_STORE_CODE_MAX_LENGTH = 10;
+
+/** Código postal: de 4 a 10 caracteres. */
+export const RETAIL_ZIP_CODE_MIN_LENGTH = 4;
+export const RETAIL_ZIP_CODE_MAX_LENGTH = 10;
+
+/** SKU del catálogo del retailer. */
+export const RETAIL_SKU_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
+
+/** Decimal del contrato: string con dos decimales, nunca negativo. */
+export const RETAIL_DECIMAL_PATTERN = /^\d+\.\d{2}$/;

package/src/retailIntegration/dtos/ApplyRetailEventRequest.ts

@@ -11,6 +11,11 @@ export class ApplyStoreEventRequest extends ReceiveStoreEventRequest {
     @IsString()
     @Matches(RETAIL_TENANT_ID_PATTERN)
     tenantId!: string;
+
+    /** Retailer de la conexión; lo pone el connector, nunca viene del payload. */
+    @IsString()
+    @Matches(/\S/)
+    retailerId!: string;
 }
 
 /** Evento de usuario que el connector manda a retail-org-business, con el tenant de la credencial. */
@@ -18,6 +23,11 @@ export class ApplyRetailUserEventRequest extends ReceiveRetailUserEventRequest {
     @IsString()
     @Matches(RETAIL_TENANT_ID_PATTERN)
     tenantId!: string;
+
+    /** Retailer de la conexión; lo pone el connector, nunca viene del payload. */
+    @IsString()
+    @Matches(/\S/)
+    retailerId!: string;
 }
 
 /** Evento de producto que el connector manda a retail-catalog-business, con el tenant de la credencial. */
@@ -25,6 +35,11 @@ export class ApplyProductEventRequest extends ReceiveProductEventRequest {
     @IsString()
     @Matches(RETAIL_TENANT_ID_PATTERN)
     tenantId!: string;
+
+    /** Retailer de la conexión; lo pone el connector, nunca viene del payload. */
+    @IsString()
+    @Matches(/\S/)
+    retailerId!: string;
 }
 
 /** Evento de inventario que el connector manda a retail-catalog-business, con el tenant de la credencial. */
@@ -32,6 +47,11 @@ export class ApplyInventoryEventRequest extends ReceiveInventoryEventRequest {
     @IsString()
     @Matches(RETAIL_TENANT_ID_PATTERN)
     tenantId!: string;
+
+    /** Retailer de la conexión; lo pone el connector, nunca viene del payload. */
+    @IsString()
+    @Matches(/\S/)
+    retailerId!: string;
 }
 
 /** Cualquiera de los cuatro eventos que el connector manda a un destino. */

package/src/retailIntegration/dtos/InventoryEventPayload.ts

@@ -0,0 +1,33 @@
+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 { RetailMovementTypeEnum, RetailPieceStatusEnum } from '../enums';
+import type { RetailPieceReason, RetailPieceStatus, RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
+import { HasUniqueKeys, ReasonMatchesStatus, TargetStoreMatchesMovement } from '../validators/payloadValidators';
+
+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(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
+    @IsIn(Object.values(RetailPieceStatusEnum)) status!: RetailPieceStatus;
+    @Validate(ReasonMatchesStatus) reason!: RetailPieceReason | null;
+}
+
+/** Existencia de un SKU por cantidad, como quedó después del movimiento. */
+export class StockEventPayload implements RetailSystemStock {
+    @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
+    @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
+    @IsInt() @Min(0) qty!: number;
+}
+
+/** Payload de `InventoryMovementV1`. */
+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[];
+}

package/src/retailIntegration/dtos/ProductEventPayload.ts

@@ -0,0 +1,51 @@
+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 {
+    RetailCurrencyEnum,
+    RetailFinancierEnum,
+    RetailMdmProviderEnum,
+    RetailProductCategoryEnum,
+    RetailProductStatusEnum,
+    RetailProductTierEnum,
+    RetailTrackingModeEnum,
+} from '../enums';
+import type {
+    RetailCurrency,
+    RetailFinancier,
+    RetailMdmProvider,
+    RetailProductCategory,
+    RetailProductStatus,
+    RetailProductTier,
+    RetailSystemProduct,
+    RetailSystemProductPrice,
+    RetailTrackingMode,
+} from '../models/RetailSystemProduct';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+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;
+    @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;
+    @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[];
+    @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailMdmProviderEnum)) mdmProvider!: RetailMdmProvider | null;
+    @IsIn(Object.values(RetailProductStatusEnum)) status!: RetailProductStatus;
+}

package/src/retailIntegration/dtos/RetailUserEventPayload.ts

@@ -0,0 +1,17 @@
+import { IsEmail, IsIn, IsString, Matches, ValidateIf } from 'class-validator';
+import { RETAIL_ENTITY_ID_PATTERN, 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';
+
+/** 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(RETAIL_ENTITY_ID_PATTERN) homeStoreId!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @Matches(RETAIL_ZONE_ID_PATTERN) zoneId!: string | null;
+    @IsIn(Object.values(RetailUserRoleEnum)) role!: RetailUserRole;
+    @IsIn(Object.values(RetailUserAccessStatusEnum)) status!: RetailUserAccessStatus;
+}

package/src/retailIntegration/dtos/StoreEventPayload.ts

@@ -0,0 +1,47 @@
+import { Type } from 'class-transformer';
+import { IsDefined, IsIn, IsNumber, IsString, Length, Matches, Max, Min, ValidateIf, ValidateNested } from 'class-validator';
+import {
+    RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_STORE_CODE_MAX_LENGTH,
+    RETAIL_ZIP_CODE_MAX_LENGTH,
+    RETAIL_ZIP_CODE_MIN_LENGTH,
+    RETAIL_ZONE_ID_PATTERN,
+} from '../constants/retailIntegrationLimits';
+import { RetailStoreStatusEnum } from '../enums';
+import type { RetailStoreStatus, RetailSystemStore, RetailSystemStoreAddress, RetailSystemStoreLocation } from '../models/RetailSystemStore';
+import { isNullOrValidated } from '../validators/payloadValidators';
+
+const LAT_MAX = 90;
+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() @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;
+}
+
+/** Coordenada de la tienda; `null` si no se informa. */
+export class StoreEventLocationPayload implements RetailSystemStoreLocation {
+    @ValidateIf(isNullOrValidated) @IsNumber() @Min(-LAT_MAX) @Max(LAT_MAX) lat!: number | null;
+    @ValidateIf(isNullOrValidated) @IsNumber() @Min(-LNG_MAX) @Max(LNG_MAX) lng!: number | null;
+}
+
+/** Payload de `StoreCreatedV1`, `StoreUpdatedV1` y `StoreStatusChangedV1`: la tienda completa. */
+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;
+    @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;
+    @IsIn(Object.values(RetailStoreStatusEnum)) status!: RetailStoreStatus;
+}

package/src/retailIntegration/enums/RetailEventRejectCodeEnum.ts

@@ -0,0 +1,16 @@
+/** `code` de un `REJECTED`; uno solo para los cuatro endpoints que aplican eventos del retailer. */
+export enum RetailEventRejectCodeEnum {
+    INVALID_PAYLOAD = 'INVALID_PAYLOAD',
+    STORE_RETAILER_MISMATCH = 'STORE_RETAILER_MISMATCH',
+    RETAIL_USER_RETAILER_MISMATCH = 'RETAIL_USER_RETAILER_MISMATCH',
+    STORE_CODE_TAKEN = 'STORE_CODE_TAKEN',
+    EMAIL_ALREADY_IN_USE = 'EMAIL_ALREADY_IN_USE',
+    UNSUPPORTED_CURRENCY = 'UNSUPPORTED_CURRENCY',
+    FUTURE_PRICE_NOT_SUPPORTED = 'FUTURE_PRICE_NOT_SUPPORTED',
+    SKU_OWNED_BY_BACKOFFICE = 'SKU_OWNED_BY_BACKOFFICE',
+    STORE_NOT_IN_RETAILER = 'STORE_NOT_IN_RETAILER',
+    SKU_NOT_STOCKABLE = 'SKU_NOT_STOCKABLE',
+    TRACKING_MODE_MISMATCH = 'TRACKING_MODE_MISMATCH',
+    INVALID_IMEI = 'INVALID_IMEI',
+    IDENTIFIER_CONFLICT = 'IDENTIFIER_CONFLICT',
+}

package/src/retailIntegration/enums/RetailMovementTypeEnum.ts

@@ -0,0 +1,10 @@
+/** `payload.movementType` de `InventoryMovementV1`. */
+export enum RetailMovementTypeEnum {
+    ENTRY = 'ENTRY',
+    SALE = 'SALE',
+    RETURN = 'RETURN',
+    ADJUSTMENT = 'ADJUSTMENT',
+    TRANSFER_OUT = 'TRANSFER_OUT',
+    TRANSFER_IN = 'TRANSFER_IN',
+    TRANSFER_CANCEL = 'TRANSFER_CANCEL',
+}

package/src/retailIntegration/enums/index.ts

@@ -19,3 +19,5 @@ export * from './RetailSaleTypeEnum';
 export * from './RetailSaleFinancierEnum';
 export * from './RetailPaymentMethodEnum';
 export * from './RetailLinePaymentTypeEnum';
+export * from './RetailEventRejectCodeEnum';
+export * from './RetailMovementTypeEnum';

package/src/retailIntegration/index.ts

@@ -9,6 +9,11 @@ export * from './dtos/ReceiveInventoryEventRequest';
 export * from './dtos/ReceiveRetailEventRequest';
 export * from './dtos/RetailEventResult';
 export * from './dtos/ApplyRetailEventRequest';
+export * from './validators/payloadValidators';
+export * from './dtos/StoreEventPayload';
+export * from './dtos/RetailUserEventPayload';
+export * from './dtos/ProductEventPayload';
+export * from './dtos/InventoryEventPayload';
 export * from './dtos/RetailTenantQuery';
 export * from './dtos/RetailPagedQuery';
 export * from './dtos/ListRetailStoresRequest';

package/src/retailIntegration/validators/payloadValidators.ts

@@ -0,0 +1,56 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { RETAIL_ENTITY_ID_PATTERN } from '../constants/retailIntegrationLimits';
+import { RetailMovementTypeEnum, RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
+
+/** `ValidateIf` de un campo nullable: con `null` no valida; ausente sí, porque el contrato nunca omite llaves. */
+export function isNullOrValidated(_object: object, value: unknown): boolean {
+    return value !== null;
+}
+
+/** Rechaza un arreglo de objetos con dos elementos que repiten la llave compuesta de `constraints`. */
+@ValidatorConstraint({ name: 'hasUniqueKeys', async: false })
+export class HasUniqueKeys implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        if (!Array.isArray(value)) return true;
+        const keys = args.constraints as string[];
+        const seen = new Set<string>();
+        for (const item of value) {
+            const key = keys.map((k) => String((item as Record<string, unknown>)?.[k])).join('#');
+            if (seen.has(key)) return false;
+            seen.add(key);
+        }
+        return true;
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        return `no puede repetir ${(args.constraints as string[]).join(' + ')}`;
+    }
+}
+
+/** `targetStoreId`: obligatorio en `TRANSFER_OUT` y `null` en los demás movimientos. */
+@ValidatorConstraint({ name: 'targetStoreMatchesMovement', async: false })
+export class TargetStoreMatchesMovement implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const movementType = (args.object as { movementType?: string }).movementType;
+        if (movementType === RetailMovementTypeEnum.TRANSFER_OUT) return typeof value === 'string' && RETAIL_ENTITY_ID_PATTERN.test(value);
+        return value === null;
+    }
+
+    defaultMessage(): string {
+        return 'targetStoreId es obligatorio en TRANSFER_OUT y null en los demás movimientos';
+    }
+}
+
+/** `reason`: obligatorio en `DAMAGED` y `null` en los demás estados. */
+@ValidatorConstraint({ name: 'reasonMatchesStatus', async: false })
+export class ReasonMatchesStatus implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const status = (args.object as { status?: string }).status;
+        if (status === RetailPieceStatusEnum.DAMAGED) return (Object.values(RetailPieceReasonEnum) as unknown[]).includes(value);
+        return value === null;
+    }
+
+    defaultMessage(): string {
+        return 'reason es obligatorio con DAMAGED y null en los demás estados';
+    }
+}

package/src/retailOrg/dtos/Store.ts

@@ -1,5 +1,6 @@
 import { Expose, Type } from 'class-transformer';
 import {
+    IsBoolean,
     IsDefined,
     IsEnum,
     IsNumber,
@@ -89,6 +90,12 @@ export class Store {
     @IsEnum(StoreStatusEnum)
     status!: StoreStatusEnum;
 
+    /** `true` si la tienda la administra la integración del retailer y no se edita a mano. */
+    @Expose()
+    @IsOptional()
+    @IsBoolean()
+    managedByIntegration?: boolean;
+
     @Expose()
     @IsString()
     @Matches(regexIso8601, { message: 'createdAt debe ser una fecha ISO 8601' })