@fiado/type-kit 3.494.0 → 3.496.0

package/src/retailIntegration/dtos/RegisterRetailSaleRequest.ts

@@ -0,0 +1,4 @@
+import { RetailTenantQuery } from './RetailTenantQuery';
+
+/** Query de `POST /private/retail/sales`; el cuerpo es la venta y no se valida aquí. */
+export class RegisterRetailSaleRequest extends RetailTenantQuery {}

package/src/retailIntegration/dtos/RetailEventEnvelope.ts

@@ -0,0 +1,20 @@
+import { IsObject, IsString, Matches, MaxLength, Validate } from 'class-validator';
+import { RETAIL_EVENT_ID_MAX_LENGTH } from '../constants/retailIntegrationLimits';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+
+/** Payload del evento: el connector no lo valida, lo valida el lambda destino. */
+export type RetailEventPayload = Record<string, unknown>;
+
+/** Campos comunes del sobre de un webhook; cada ruta agrega su `eventType`. */
+export abstract class RetailEventEnvelope {
+    @IsString()
+    @Matches(/\S/)
+    @MaxLength(RETAIL_EVENT_ID_MAX_LENGTH)
+    eventId!: string;
+
+    @Validate(IsIsoDateTimeWithZone)
+    occurredAt!: string;
+
+    @IsObject()
+    payload!: RetailEventPayload;
+}

package/src/retailIntegration/dtos/RetailEventResult.ts

@@ -0,0 +1,14 @@
+import { RetailEventResultEnum } from '../enums/RetailEventResultEnum';
+
+/** Resultado de un evento; `code` explica un `REJECTED` y es `null` en los demás. */
+export interface RetailEventResult {
+    eventId: string;
+    result: RetailEventResultEnum;
+    code: string | null;
+}
+
+export type ReceiveStoreEventResponse = RetailEventResult;
+export type ReceiveRetailUserEventResponse = RetailEventResult;
+export type ReceiveProductEventResponse = RetailEventResult;
+export type ReceiveInventoryEventResponse = RetailEventResult;
+export type ReceiveRetailEventResponse = RetailEventResult;

package/src/retailIntegration/dtos/RetailOutboundResponses.ts

@@ -0,0 +1,35 @@
+import { RetailInventoryMeta, RetailPageMeta } from '../models/RetailPageMeta';
+import { RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
+import { RetailSystemProduct } from '../models/RetailSystemProduct';
+import { RetailSystemStore } from '../models/RetailSystemStore';
+import { RetailSystemUser } from '../models/RetailSystemUser';
+
+/** `data` de `GET /private/retail/stores`. */
+export interface ListRetailStoresResponse {
+    items: RetailSystemStore[];
+    meta: RetailPageMeta;
+}
+
+/** `data` de `GET /private/retail/catalog`. */
+export interface ListRetailCatalogResponse {
+    items: RetailSystemProduct[];
+    meta: RetailPageMeta;
+}
+
+/** `data` de `GET /private/retail/inventory`. */
+export interface GetRetailInventoryResponse {
+    pieces: RetailSystemPiece[];
+    stock: RetailSystemStock[];
+    meta: RetailInventoryMeta;
+}
+
+/** `data` de `GET /private/retail/users`. */
+export interface ListRetailUsersResponse {
+    items: RetailSystemUser[];
+    meta: RetailPageMeta;
+}
+
+/** `data` de `POST /private/retail/sales`: el id de la venta en el sistema del retailer. */
+export interface RegisterRetailSaleResponse {
+    externalSaleId: string;
+}

package/src/retailIntegration/dtos/RetailPagedQuery.ts

@@ -0,0 +1,19 @@
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, IsString, Matches, Max, Min } from 'class-validator';
+import { RETAIL_LIST_LIMIT_MAX, RETAIL_LIST_LIMIT_MIN } from '../constants/retailIntegrationLimits';
+import { RetailTenantQuery } from './RetailTenantQuery';
+
+/** Base de las listas paginadas; `nextToken` es opaco y viaja tal cual. */
+export class RetailPagedQuery extends RetailTenantQuery {
+    @IsOptional()
+    @Type(() => Number)
+    @IsInt()
+    @Min(RETAIL_LIST_LIMIT_MIN)
+    @Max(RETAIL_LIST_LIMIT_MAX)
+    limit?: number;
+
+    @IsOptional()
+    @IsString()
+    @Matches(/\S/)
+    nextToken?: string;
+}

package/src/retailIntegration/dtos/RetailTenantQuery.ts

@@ -0,0 +1,9 @@
+import { IsString, Matches } from 'class-validator';
+import { RETAIL_TENANT_ID_PATTERN } from '../constants/retailIntegrationLimits';
+
+/** Base de toda llamada de salida: el tenant cuyo retailer se consulta. */
+export class RetailTenantQuery {
+    @IsString()
+    @Matches(RETAIL_TENANT_ID_PATTERN)
+    tenantId!: string;
+}

package/src/retailIntegration/enums/InventoryEventTypeEnum.ts

@@ -0,0 +1,4 @@
+/** `eventType` válidos en `POST /webhooks/inventory`. */
+export enum InventoryEventTypeEnum {
+    INVENTORY_MOVEMENT_V1 = 'InventoryMovementV1',
+}

package/src/retailIntegration/enums/ProductEventTypeEnum.ts

@@ -0,0 +1,6 @@
+/** `eventType` válidos en `POST /webhooks/catalog`. */
+export enum ProductEventTypeEnum {
+    PRODUCT_CREATED_V1 = 'ProductCreatedV1',
+    PRODUCT_UPDATED_V1 = 'ProductUpdatedV1',
+    PRODUCT_STATUS_CHANGED_V1 = 'ProductStatusChangedV1',
+}

package/src/retailIntegration/enums/RetailCurrencyEnum.ts

@@ -0,0 +1,5 @@
+/** Moneda de precios y ventas. */
+export enum RetailCurrencyEnum {
+    MXN = 'MXN',
+    USD = 'USD',
+}

package/src/retailIntegration/enums/RetailEventResultEnum.ts

@@ -0,0 +1,6 @@
+/** Resultado de aplicar un evento del retailer en el lambda destino. */
+export enum RetailEventResultEnum {
+    APPLIED = 'APPLIED',
+    NOOP = 'NOOP',
+    REJECTED = 'REJECTED',
+}

package/src/retailIntegration/enums/RetailFinancierEnum.ts

@@ -0,0 +1,8 @@
+/** Financieras que pueden financiar un producto. */
+export enum RetailFinancierEnum {
+    SUREKEEP = 'SUREKEEP',
+    PAYJOY = 'PAYJOY',
+    CREDIYA = 'CREDIYA',
+    LESPAGO = 'LESPAGO',
+    INNOVA = 'INNOVA',
+}

package/src/retailIntegration/enums/RetailLinePaymentTypeEnum.ts

@@ -0,0 +1,5 @@
+/** Forma de pago de una línea de la venta. */
+export enum RetailLinePaymentTypeEnum {
+    CASH = 'CASH',
+    CREDIT = 'CREDIT',
+}

package/src/retailIntegration/enums/RetailMdmProviderEnum.ts

@@ -0,0 +1,5 @@
+/** Proveedor de MDM del equipo. */
+export enum RetailMdmProviderEnum {
+    TRUSTONIC = 'TRUSTONIC',
+    DATACULTR = 'DATACULTR',
+}

package/src/retailIntegration/enums/RetailPaymentMethodEnum.ts

@@ -0,0 +1,6 @@
+/** Método de pago de la venta. */
+export enum RetailPaymentMethodEnum {
+    CASH = 'CASH',
+    CARD = 'CARD',
+    SPEI = 'SPEI',
+}

package/src/retailIntegration/enums/RetailPieceReasonEnum.ts

@@ -0,0 +1,6 @@
+/** Motivo de una pieza fuera de venta. */
+export enum RetailPieceReasonEnum {
+    WARRANTY = 'WARRANTY',
+    DAMAGED_RETURN = 'DAMAGED_RETURN',
+    SHRINKAGE = 'SHRINKAGE',
+}

package/src/retailIntegration/enums/RetailPieceStatusEnum.ts

@@ -0,0 +1,7 @@
+/** Estatus de una pieza con IMEI o serie. */
+export enum RetailPieceStatusEnum {
+    AVAILABLE = 'AVAILABLE',
+    IN_TRANSIT = 'IN_TRANSIT',
+    SOLD = 'SOLD',
+    DAMAGED = 'DAMAGED',
+}

package/src/retailIntegration/enums/RetailProductCategoryEnum.ts

@@ -0,0 +1,7 @@
+/** Categoría de un producto del retailer. */
+export enum RetailProductCategoryEnum {
+    PHONE = 'PHONE',
+    MODEM = 'MODEM',
+    ACCESSORY = 'ACCESSORY',
+    SIM = 'SIM',
+}

package/src/retailIntegration/enums/RetailProductStatusEnum.ts

@@ -0,0 +1,6 @@
+/** Estatus de un producto del catálogo. */
+export enum RetailProductStatusEnum {
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+    DISCONTINUED = 'DISCONTINUED',
+}

package/src/retailIntegration/enums/RetailProductTierEnum.ts

@@ -0,0 +1,7 @@
+/** Gama de un producto. */
+export enum RetailProductTierEnum {
+    LOW = 'LOW',
+    MID = 'MID',
+    HIGH = 'HIGH',
+    PREMIUM = 'PREMIUM',
+}

package/src/retailIntegration/enums/RetailSaleFinancierEnum.ts

@@ -0,0 +1,9 @@
+/** Financiera de la venta; `NONE` en una venta de contado. */
+export enum RetailSaleFinancierEnum {
+    NONE = 'NONE',
+    SUREKEEP = 'SUREKEEP',
+    PAYJOY = 'PAYJOY',
+    CREDIYA = 'CREDIYA',
+    LESPAGO = 'LESPAGO',
+    INNOVA = 'INNOVA',
+}

package/src/retailIntegration/enums/RetailSaleTypeEnum.ts

@@ -0,0 +1,6 @@
+/** Tipo de venta. */
+export enum RetailSaleTypeEnum {
+    CASH = 'CASH',
+    CREDIT = 'CREDIT',
+    EXTERNAL_REFERRAL = 'EXTERNAL_REFERRAL',
+}

package/src/retailIntegration/enums/RetailStoreStatusEnum.ts

@@ -0,0 +1,6 @@
+/** Estatus de una tienda del retailer. */
+export enum RetailStoreStatusEnum {
+    ACTIVE = 'ACTIVE',
+    SUSPENDED = 'SUSPENDED',
+    INACTIVE = 'INACTIVE',
+}

package/src/retailIntegration/enums/RetailTrackingModeEnum.ts

@@ -0,0 +1,6 @@
+/** Cómo se rastrea un producto: por IMEI, por serie o por cantidad. */
+export enum RetailTrackingModeEnum {
+    IMEI = 'IMEI',
+    SERIAL = 'SERIAL',
+    QUANTITY = 'QUANTITY',
+}

package/src/retailIntegration/enums/RetailUserAccessStatusEnum.ts

@@ -0,0 +1,6 @@
+/** Estatus de acceso de un usuario del retailer. */
+export enum RetailUserAccessStatusEnum {
+    ACTIVE = 'ACTIVE',
+    SUSPENDED = 'SUSPENDED',
+    INACTIVE = 'INACTIVE',
+}

package/src/retailIntegration/enums/RetailUserEventTypeEnum.ts

@@ -0,0 +1,7 @@
+/** `eventType` válidos en `POST /webhooks/users`. */
+export enum RetailUserEventTypeEnum {
+    RETAIL_USER_CREATED_V1 = 'RetailUserCreatedV1',
+    RETAIL_USER_UPDATED_V1 = 'RetailUserUpdatedV1',
+    RETAIL_USER_TRANSFERRED_V1 = 'RetailUserTransferredV1',
+    RETAIL_USER_STATUS_CHANGED_V1 = 'RetailUserStatusChangedV1',
+}

package/src/retailIntegration/enums/RetailUserRoleEnum.ts

@@ -0,0 +1,7 @@
+/** Rol de un usuario de la operación del retailer. */
+export enum RetailUserRoleEnum {
+    SELLER = 'SELLER',
+    STORE_MANAGER = 'STORE_MANAGER',
+    RETAILER_ADMIN = 'RETAILER_ADMIN',
+    COLLECTION_AGENT = 'COLLECTION_AGENT',
+}

package/src/retailIntegration/enums/StoreEventTypeEnum.ts

@@ -0,0 +1,6 @@
+/** `eventType` válidos en `POST /webhooks/stores`. */
+export enum StoreEventTypeEnum {
+    STORE_CREATED_V1 = 'StoreCreatedV1',
+    STORE_UPDATED_V1 = 'StoreUpdatedV1',
+    STORE_STATUS_CHANGED_V1 = 'StoreStatusChangedV1',
+}

package/src/retailIntegration/enums/index.ts

@@ -0,0 +1,21 @@
+export * from './RetailEventResultEnum';
+export * from './StoreEventTypeEnum';
+export * from './RetailUserEventTypeEnum';
+export * from './ProductEventTypeEnum';
+export * from './InventoryEventTypeEnum';
+export * from './RetailStoreStatusEnum';
+export * from './RetailProductCategoryEnum';
+export * from './RetailTrackingModeEnum';
+export * from './RetailProductTierEnum';
+export * from './RetailCurrencyEnum';
+export * from './RetailFinancierEnum';
+export * from './RetailMdmProviderEnum';
+export * from './RetailProductStatusEnum';
+export * from './RetailPieceStatusEnum';
+export * from './RetailPieceReasonEnum';
+export * from './RetailUserRoleEnum';
+export * from './RetailUserAccessStatusEnum';
+export * from './RetailSaleTypeEnum';
+export * from './RetailSaleFinancierEnum';
+export * from './RetailPaymentMethodEnum';
+export * from './RetailLinePaymentTypeEnum';

package/src/retailIntegration/index.ts

@@ -0,0 +1,25 @@
+export * from './constants/retailIntegrationLimits';
+export * from './enums';
+export * from './validators/IsIsoDateTimeWithZone';
+export * from './dtos/RetailEventEnvelope';
+export * from './dtos/ReceiveStoreEventRequest';
+export * from './dtos/ReceiveRetailUserEventRequest';
+export * from './dtos/ReceiveProductEventRequest';
+export * from './dtos/ReceiveInventoryEventRequest';
+export * from './dtos/ReceiveRetailEventRequest';
+export * from './dtos/RetailEventResult';
+export * from './dtos/ApplyRetailEventRequest';
+export * from './dtos/RetailTenantQuery';
+export * from './dtos/RetailPagedQuery';
+export * from './dtos/ListRetailStoresRequest';
+export * from './dtos/ListRetailCatalogRequest';
+export * from './dtos/GetRetailInventoryRequest';
+export * from './dtos/ListRetailUsersRequest';
+export * from './dtos/RegisterRetailSaleRequest';
+export * from './dtos/RetailOutboundResponses';
+export * from './models/RetailPageMeta';
+export * from './models/RetailSystemStore';
+export * from './models/RetailSystemProduct';
+export * from './models/RetailSystemInventory';
+export * from './models/RetailSystemUser';
+export * from './models/RetailSystemSale';

package/src/retailIntegration/models/RetailPageMeta.ts

@@ -0,0 +1,11 @@
+/** `meta` de una lista paginada del retailer; `nextToken` en `null` cierra la lectura. */
+export interface RetailPageMeta {
+    count: number;
+    nextToken: string | null;
+}
+
+/** `meta` del inventario de una tienda. */
+export interface RetailInventoryMeta {
+    storeId: string;
+    generatedAt: string;
+}

package/src/retailIntegration/models/RetailSystemInventory.ts

@@ -0,0 +1,20 @@
+import { RetailPieceReasonEnum, RetailPieceStatusEnum } from '../enums';
+
+export type RetailPieceStatus = `${RetailPieceStatusEnum}`;
+export type RetailPieceReason = `${RetailPieceReasonEnum}`;
+
+/** Pieza con IMEI o número de serie. */
+export interface RetailSystemPiece {
+    sku: string;
+    identifier: string;
+    storeId: string;
+    status: RetailPieceStatus;
+    reason: RetailPieceReason | null;
+}
+
+/** Existencia de un producto sin identificador por unidad. */
+export interface RetailSystemStock {
+    sku: string;
+    storeId: string;
+    qty: number;
+}

package/src/retailIntegration/models/RetailSystemProduct.ts

@@ -0,0 +1,43 @@
+import {
+    RetailCurrencyEnum,
+    RetailFinancierEnum,
+    RetailMdmProviderEnum,
+    RetailProductCategoryEnum,
+    RetailProductStatusEnum,
+    RetailProductTierEnum,
+    RetailTrackingModeEnum,
+} from '../enums';
+
+export type RetailProductCategory = `${RetailProductCategoryEnum}`;
+export type RetailTrackingMode = `${RetailTrackingModeEnum}`;
+export type RetailProductTier = `${RetailProductTierEnum}`;
+export type RetailCurrency = `${RetailCurrencyEnum}`;
+export type RetailFinancier = `${RetailFinancierEnum}`;
+export type RetailMdmProvider = `${RetailMdmProviderEnum}`;
+export type RetailProductStatus = `${RetailProductStatusEnum}`;
+
+/** Precios como decimal en string con dos decimales. */
+export interface RetailSystemProductPrice {
+    basePrice: string;
+    listPrice: string | null;
+    effectiveFrom: string;
+}
+
+/** Producto tal como lo define la doc de integración. */
+export interface RetailSystemProduct {
+    sku: string;
+    externalId: string;
+    brand: string;
+    model: string;
+    color: string | null;
+    capacity: string | null;
+    description: string | null;
+    category: RetailProductCategory;
+    trackingMode: RetailTrackingMode;
+    tier: RetailProductTier | null;
+    currencyId: RetailCurrency;
+    price: RetailSystemProductPrice;
+    eligibleFinanciers: RetailFinancier[];
+    mdmProvider: RetailMdmProvider | null;
+    status: RetailProductStatus;
+}

package/src/retailIntegration/models/RetailSystemSale.ts

@@ -0,0 +1,51 @@
+import { RetailLinePaymentTypeEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleTypeEnum } from '../enums';
+import { RetailCurrency } from './RetailSystemProduct';
+
+export type RetailSaleType = `${RetailSaleTypeEnum}`;
+export type RetailSaleFinancier = `${RetailSaleFinancierEnum}`;
+export type RetailPaymentMethod = `${RetailPaymentMethodEnum}`;
+export type RetailLinePaymentType = `${RetailLinePaymentTypeEnum}`;
+
+export interface RetailSystemSaleCustomer {
+    customerId: string;
+    names: string;
+    paternalLastName: string;
+    maternalLastName: string | null;
+    phone: string;
+}
+
+export interface RetailSystemSaleComponent {
+    sku: string;
+    qty: number;
+    identifiers: string[];
+}
+
+export interface RetailSystemSaleLine {
+    lineId: string;
+    sku: string;
+    qty: number;
+    basePrice: string;
+    discount: string;
+    paymentType: RetailLinePaymentType;
+    financedAmount: string;
+    role: 'GIFT' | null;
+    components: RetailSystemSaleComponent[];
+}
+
+/** Cuerpo de `POST /sales` de la doc; `saleId` es la llave de idempotencia. */
+export interface RetailSystemSale {
+    saleId: string;
+    folio: string;
+    storeId: string;
+    sellerRetailUserId: string;
+    soldAt: string;
+    saleType: RetailSaleType;
+    financier: RetailSaleFinancier;
+    creditId: string | null;
+    currencyId: RetailCurrency;
+    customer: RetailSystemSaleCustomer;
+    equipmentPrice: string;
+    amountPaid: string;
+    paymentMethod: RetailPaymentMethod | null;
+    lines: RetailSystemSaleLine[];
+}

package/src/retailIntegration/models/RetailSystemStore.ts

@@ -0,0 +1,33 @@
+import { RetailStoreStatusEnum } from '../enums';
+
+export type RetailStoreStatus = `${RetailStoreStatusEnum}`;
+
+export interface RetailSystemStoreAddress {
+    address1: string;
+    externalNumber: string | null;
+    internalNumber: string | null;
+    neighborhood: string | null;
+    city: string;
+    state: string;
+    zipCode: string;
+    country: string | null;
+    reference: string | null;
+}
+
+export interface RetailSystemStoreLocation {
+    lat: number | null;
+    lng: number | null;
+}
+
+/** Tienda tal como la define la doc de integración. */
+export interface RetailSystemStore {
+    storeId: string;
+    code: string;
+    name: string;
+    zoneId: string | null;
+    address: RetailSystemStoreAddress;
+    location: RetailSystemStoreLocation;
+    phone: string;
+    schedule: string | null;
+    status: RetailStoreStatus;
+}

package/src/retailIntegration/models/RetailSystemUser.ts

@@ -0,0 +1,16 @@
+import { RetailUserAccessStatusEnum, RetailUserRoleEnum } from '../enums';
+
+export type RetailUserRole = `${RetailUserRoleEnum}`;
+export type RetailUserAccessStatus = `${RetailUserAccessStatusEnum}`;
+
+/** Usuario de la operación del retailer, tal como lo define la doc de integración. */
+export interface RetailSystemUser {
+    retailUserId: string;
+    displayName: string;
+    email: string;
+    phone: string | null;
+    homeStoreId: string;
+    zoneId: string | null;
+    role: RetailUserRole;
+    status: RetailUserAccessStatus;
+}

package/src/retailIntegration/validators/IsIsoDateTimeWithZone.ts

@@ -0,0 +1,21 @@
+import { ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+
+const ISO_DATE_TIME_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero. */
+function isRealCalendarDate(value: string): boolean {
+    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
+}
+
+/** Acepta fecha y hora ISO-8601 con segundos y zona; sin zona se rechaza, como dice la doc. */
+@ValidatorConstraint({ name: 'isIsoDateTimeWithZone', async: false })
+export class IsIsoDateTimeWithZone implements ValidatorConstraintInterface {
+    validate(value: unknown): boolean {
+        return typeof value === 'string' && ISO_DATE_TIME_WITH_ZONE.test(value) && isRealCalendarDate(value);
+    }
+
+    defaultMessage(): string {
+        return 'debe ser fecha y hora ISO-8601 con zona, por ejemplo 2026-08-17T20:32:05Z';
+    }
+}

package/src/retailWizard/dtos/WizardSessionLookupEntry.ts

@@ -25,4 +25,6 @@ export interface WizardSessionLookupEntry {
     /** La venta que cerro esta sesion; `null` si todavia no cerro. */
     saleId?: string | null;
     folio?: string | null;
+    /** Vendedor de la sesión (`retailUserId` de retail-org). `null` si la sesión no lo tiene. */
+    sellerRetailUserId?: string | null;
 }