@fiado/type-kit 3.60.0 → 3.61.0

package/_test_/unit/platformRbac/dtos/CreateTenantRequest.test.ts

@@ -1,68 +1,68 @@
-import 'reflect-metadata';
-import { plainToInstance } from 'class-transformer';
-import { validate } from 'class-validator';
-import { CreateTenantRequest } from '../../../../src/platformRbac/dtos/CreateTenantRequest';
-
-describe('CreateTenantRequest', () => {
-    const valid = {
-        tenantId: 'acme-mx',
-        displayName: 'Acme México',
-        emailDomain: 'acme.com',
-        tablePrefix: 'acme',
-        adminEmail: 'admin@acme.com',
-        adminName: 'Admin Acme',
-        region: 'us-east-1',
-        mfaRequired: true,
-        passwordMinLength: 12,
-    };
-
-    it('valida happy path (0 errores)', async () => {
-        const dto = plainToInstance(CreateTenantRequest, valid);
-        const errors = await validate(dto);
-        expect(errors).toEqual([]);
-    });
-
-    it('valida sin campos opcionales (mfaRequired / passwordMinLength)', async () => {
-        const { mfaRequired, passwordMinLength, ...sinOpcionales } = valid;
-        const dto = plainToInstance(CreateTenantRequest, sinOpcionales);
-        const errors = await validate(dto);
-        expect(errors).toEqual([]);
-    });
-
-    it('falla si adminEmail es inválido', async () => {
-        const dto = plainToInstance(CreateTenantRequest, { ...valid, adminEmail: 'no-es-email' });
-        const errors = await validate(dto);
-        expect(errors.some(e => e.property === 'adminEmail')).toBe(true);
-    });
-
-    it('falla si tenantId tiene mayúsculas', async () => {
-        const dto = plainToInstance(CreateTenantRequest, { ...valid, tenantId: 'Acme-MX' });
-        const errors = await validate(dto);
-        expect(errors.some(e => e.property === 'tenantId')).toBe(true);
-    });
-
-    it('falla si tenantId tiene caracteres inválidos (espacios / underscore)', async () => {
-        const dto = plainToInstance(CreateTenantRequest, { ...valid, tenantId: 'acme_mx 01' });
-        const errors = await validate(dto);
-        expect(errors.some(e => e.property === 'tenantId')).toBe(true);
-    });
-
-    it('falla si passwordMinLength es menor a 8', async () => {
-        const dto = plainToInstance(CreateTenantRequest, { ...valid, passwordMinLength: 6 });
-        const errors = await validate(dto);
-        expect(errors.some(e => e.property === 'passwordMinLength')).toBe(true);
-    });
-
-    it('NO expone temporaryPassword en el request (campo del response, no del body)', () => {
-        // El request NO debe llevar temporaryPassword (es solo del response, fallback out-of-band F-11).
-        // Con excludeExtraneousValues solo sobreviven las props @Expose() del DTO → el contrato lo excluye.
-        const dto = plainToInstance(
-            CreateTenantRequest,
-            { ...valid, temporaryPassword: 'Secreto123!' },
-            { excludeExtraneousValues: true },
-        );
-        expect((dto as unknown as Record<string, unknown>).temporaryPassword).toBeUndefined();
-        // sanity: una prop sí declarada en el contrato sí sobrevive
-        expect(dto.tenantId).toBe('acme-mx');
-    });
-});
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { CreateTenantRequest } from '../../../../src/platformRbac/dtos/CreateTenantRequest';
+
+describe('CreateTenantRequest', () => {
+    const valid = {
+        tenantId: 'acme-mx',
+        displayName: 'Acme México',
+        emailDomain: 'acme.com',
+        tablePrefix: 'acme',
+        adminEmail: 'admin@acme.com',
+        adminName: 'Admin Acme',
+        region: 'us-east-1',
+        mfaRequired: true,
+        passwordMinLength: 12,
+    };
+
+    it('valida happy path (0 errores)', async () => {
+        const dto = plainToInstance(CreateTenantRequest, valid);
+        const errors = await validate(dto);
+        expect(errors).toEqual([]);
+    });
+
+    it('valida sin campos opcionales (mfaRequired / passwordMinLength)', async () => {
+        const { mfaRequired, passwordMinLength, ...sinOpcionales } = valid;
+        const dto = plainToInstance(CreateTenantRequest, sinOpcionales);
+        const errors = await validate(dto);
+        expect(errors).toEqual([]);
+    });
+
+    it('falla si adminEmail es inválido', async () => {
+        const dto = plainToInstance(CreateTenantRequest, { ...valid, adminEmail: 'no-es-email' });
+        const errors = await validate(dto);
+        expect(errors.some(e => e.property === 'adminEmail')).toBe(true);
+    });
+
+    it('falla si tenantId tiene mayúsculas', async () => {
+        const dto = plainToInstance(CreateTenantRequest, { ...valid, tenantId: 'Acme-MX' });
+        const errors = await validate(dto);
+        expect(errors.some(e => e.property === 'tenantId')).toBe(true);
+    });
+
+    it('falla si tenantId tiene caracteres inválidos (espacios / underscore)', async () => {
+        const dto = plainToInstance(CreateTenantRequest, { ...valid, tenantId: 'acme_mx 01' });
+        const errors = await validate(dto);
+        expect(errors.some(e => e.property === 'tenantId')).toBe(true);
+    });
+
+    it('falla si passwordMinLength es menor a 8', async () => {
+        const dto = plainToInstance(CreateTenantRequest, { ...valid, passwordMinLength: 6 });
+        const errors = await validate(dto);
+        expect(errors.some(e => e.property === 'passwordMinLength')).toBe(true);
+    });
+
+    it('NO expone temporaryPassword en el request (campo del response, no del body)', () => {
+        // El request NO debe llevar temporaryPassword (es solo del response, fallback out-of-band F-11).
+        // Con excludeExtraneousValues solo sobreviven las props @Expose() del DTO → el contrato lo excluye.
+        const dto = plainToInstance(
+            CreateTenantRequest,
+            { ...valid, temporaryPassword: 'Secreto123!' },
+            { excludeExtraneousValues: true },
+        );
+        expect((dto as unknown as Record<string, unknown>).temporaryPassword).toBeUndefined();
+        // sanity: una prop sí declarada en el contrato sí sobrevive
+        expect(dto.tenantId).toBe('acme-mx');
+    });
+});

package/bin/cognitoBackofficeConnector/dtos/MfaPoolConfig.d.ts

@@ -0,0 +1,7 @@
+declare const ALLOWED_MFA_TYPES: readonly ["SOFTWARE_TOKEN_MFA"];
+export type AllowedMfaType = (typeof ALLOWED_MFA_TYPES)[number];
+export declare class MfaPoolConfig {
+    requireMfa: boolean;
+    mfaTypes: AllowedMfaType[];
+}
+export {};

package/bin/cognitoBackofficeConnector/dtos/MfaPoolConfig.js

@@ -0,0 +1,36 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MfaPoolConfig = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const MfaTypesRequiresOne_1 = require("../validators/MfaTypesRequiresOne");
+// EMAIL_OTP removido (3.41.0): el cognito-backoffice-connector no provisiona
+// EmailMfaConfiguration a nivel pool (requiere infra SES que no está montada
+// y la integración con messages-lambda aún no tiene diseño). Ver TD-020 +
+// DEC-001 en cognito-backoffice-connector/docs/. Si se reintroduce, agregar
+// 'EMAIL_OTP' a este array.
+const ALLOWED_MFA_TYPES = ['SOFTWARE_TOKEN_MFA'];
+class MfaPoolConfig {
+}
+exports.MfaPoolConfig = MfaPoolConfig;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], MfaPoolConfig.prototype, "requireMfa", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsIn)(ALLOWED_MFA_TYPES, { each: true }),
+    (0, class_validator_1.Validate)(MfaTypesRequiresOne_1.MfaTypesRequiresOne),
+    __metadata("design:type", Array)
+], MfaPoolConfig.prototype, "mfaTypes", void 0);

package/bin/cognitoBackofficeConnector/dtos/PoolConfigResponse.d.ts

@@ -0,0 +1,20 @@
+import { PoolKind } from '../../rbac/enums/PoolKind';
+/**
+ * Shape del `PoolConfigRow` expuesto al caller (BFF M18 / otros lambdas Fiado).
+ * Refleja la configuración de un Cognito User Pool registrado en la tabla
+ * `PoolConfigs_GT` del lambda `cognito-backoffice-connector`.
+ */
+export declare class PoolConfigResponse {
+    userPoolId: string;
+    userPoolArn: string;
+    region: string;
+    poolKind: PoolKind;
+    displayName: string;
+    appClients: Record<string, {
+        clientId: string;
+        clientName: string;
+    }>;
+    status: 'active' | 'deprecated';
+    createdAt: number;
+    updatedAt: number;
+}

package/bin/cognitoBackofficeConnector/dtos/PoolConfigResponse.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolConfigResponse = void 0;
+/**
+ * Shape del `PoolConfigRow` expuesto al caller (BFF M18 / otros lambdas Fiado).
+ * Refleja la configuración de un Cognito User Pool registrado en la tabla
+ * `PoolConfigs_GT` del lambda `cognito-backoffice-connector`.
+ */
+class PoolConfigResponse {
+}
+exports.PoolConfigResponse = PoolConfigResponse;

package/bin/cognitoBackofficeConnector/dtos/PoolsListResponse.d.ts

@@ -0,0 +1,4 @@
+import { PoolConfigResponse } from './PoolConfigResponse';
+export declare class PoolsListResponse {
+    pools: PoolConfigResponse[];
+}

package/bin/cognitoBackofficeConnector/dtos/PoolsListResponse.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolsListResponse = void 0;
+class PoolsListResponse {
+}
+exports.PoolsListResponse = PoolsListResponse;

package/bin/cognitoBackofficeConnector/validators/MfaTypesRequiresOne.d.ts

@@ -0,0 +1,17 @@
+import { ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+/**
+ * Cross-field validator: si `requireMfa: true`, entonces `mfaTypes` debe tener
+ * al menos 1 elemento. Si `requireMfa: false`, `mfaTypes` puede ser vacío.
+ *
+ * Razón: cuando el pool nace con MFA habilitado, el connector llama
+ * `SetUserPoolMfaConfigCommand` con la lista de tipos del DTO. Si el array
+ * llega vacío con `requireMfa: true`, el SDK rechaza con InvalidParameterException
+ * y el pool queda en estado inconsistente (MfaConfiguration:'ON' sin tipos).
+ * Mejor rechazar en validación del DTO antes de tocar AWS.
+ *
+ * Ver pivote v1.4.1 TD-017 cerrado + spec doc §1 R3.
+ */
+export declare class MfaTypesRequiresOne implements ValidatorConstraintInterface {
+    validate(mfaTypes: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/cognitoBackofficeConnector/validators/MfaTypesRequiresOne.js

@@ -0,0 +1,39 @@
+"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.MfaTypesRequiresOne = void 0;
+const class_validator_1 = require("class-validator");
+/**
+ * Cross-field validator: si `requireMfa: true`, entonces `mfaTypes` debe tener
+ * al menos 1 elemento. Si `requireMfa: false`, `mfaTypes` puede ser vacío.
+ *
+ * Razón: cuando el pool nace con MFA habilitado, el connector llama
+ * `SetUserPoolMfaConfigCommand` con la lista de tipos del DTO. Si el array
+ * llega vacío con `requireMfa: true`, el SDK rechaza con InvalidParameterException
+ * y el pool queda en estado inconsistente (MfaConfiguration:'ON' sin tipos).
+ * Mejor rechazar en validación del DTO antes de tocar AWS.
+ *
+ * Ver pivote v1.4.1 TD-017 cerrado + spec doc §1 R3.
+ */
+let MfaTypesRequiresOne = class MfaTypesRequiresOne {
+    validate(mfaTypes, args) {
+        const obj = args.object;
+        if (obj.requireMfa === true) {
+            return Array.isArray(mfaTypes) && mfaTypes.length >= 1;
+        }
+        // requireMfa: false → cualquier mfaTypes pasa.
+        return true;
+    }
+    defaultMessage() {
+        return 'mfaTypes requiere al menos un tipo cuando requireMfa=true';
+    }
+};
+exports.MfaTypesRequiresOne = MfaTypesRequiresOne;
+exports.MfaTypesRequiresOne = MfaTypesRequiresOne = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'MfaTypesRequiresOneWhenMfaRequired', async: false })
+], MfaTypesRequiresOne);

package/bin/index.d.ts

@@ -21,6 +21,7 @@ export * as EventBridgeMessage from './eventBridge';
 export * as GenericMessage from './genericMessage';
 export * as TransactionProcessor from './transactionProcessor';
 export * as Transaction from './transaction';
+export * as TransactionAnalytics from './transactionAnalytics';
 export * as ContactInfo from './contactInfo';
 export * as ProductCatalog from './productCatalog';
 export * as Contract from './contract';

package/bin/index.js

@@ -36,8 +36,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Pricelist = exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = exports.Observations = exports.IssuanceBusiness = exports.Blacklist = exports.CentralPayments = exports.Helpdesk = exports.FiadoApiResponse = exports.Auth = exports.LegalDocumentsBusiness = exports.Role = exports.STPAccount = exports.RiskProfile = exports.FraudPreventionEngine = exports.BBVARst = exports.Stp = exports.BenefitCenter = exports.BankAccount = exports.P2pContact = exports.CreditContract = exports.Contract = exports.ProductCatalog = exports.ContactInfo = exports.Transaction = exports.TransactionProcessor = exports.GenericMessage = exports.EventBridgeMessage = exports.SessionActivity = exports.NotificationMessages = exports.ServicePayment = exports.Header = exports.Identity = exports.Group = exports.File = exports.ExchangeRate = exports.Directory = exports.Currency = exports.Country = exports.Card = exports.Authentication = exports.App = exports.Address = exports.Beneficiary = exports.Activity = exports.Account = exports.Crypto = void 0;
-exports.TotpSecurity = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.MessagesConnector = exports.Mdm = exports.MilestoneBusiness = exports.CirculoCredito = exports.CreditStatements = exports.Sentry = exports.AiEngine = exports.Funnel = exports.TeamsConnector = exports.PlatformErrorEvents = exports.CustomerFile = exports.CreditBackoffice = exports.CreditDashboard = exports.CreditEngine = exports.Credit = exports.ComissionBusiness = exports.ReferralBusiness = exports.ZendeskMessaging = exports.NotificationWS = exports.Event = exports.PayrollBusiness = exports.Cnbv = exports.DirectorySetting = exports.InvoiceCollector = exports.Collector = void 0;
+exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = exports.Observations = exports.IssuanceBusiness = exports.Blacklist = exports.CentralPayments = exports.Helpdesk = exports.FiadoApiResponse = exports.Auth = exports.LegalDocumentsBusiness = exports.Role = exports.STPAccount = exports.RiskProfile = exports.FraudPreventionEngine = exports.BBVARst = exports.Stp = exports.BenefitCenter = exports.BankAccount = exports.P2pContact = exports.CreditContract = exports.Contract = exports.ProductCatalog = exports.ContactInfo = exports.TransactionAnalytics = exports.Transaction = exports.TransactionProcessor = exports.GenericMessage = exports.EventBridgeMessage = exports.SessionActivity = exports.NotificationMessages = exports.ServicePayment = exports.Header = exports.Identity = exports.Group = exports.File = exports.ExchangeRate = exports.Directory = exports.Currency = exports.Country = exports.Card = exports.Authentication = exports.App = exports.Address = exports.Beneficiary = exports.Activity = exports.Account = exports.Crypto = void 0;
+exports.TotpSecurity = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.MessagesConnector = exports.Mdm = exports.MilestoneBusiness = exports.CirculoCredito = exports.CreditStatements = exports.Sentry = exports.AiEngine = exports.Funnel = exports.TeamsConnector = exports.PlatformErrorEvents = exports.CustomerFile = exports.CreditBackoffice = exports.CreditDashboard = exports.CreditEngine = exports.Credit = exports.ComissionBusiness = exports.ReferralBusiness = exports.ZendeskMessaging = exports.NotificationWS = exports.Event = exports.PayrollBusiness = exports.Cnbv = exports.DirectorySetting = exports.InvoiceCollector = exports.Collector = exports.Pricelist = void 0;
 exports.Crypto = __importStar(require("./crypto"));
 exports.Account = __importStar(require("./account"));
 exports.Activity = __importStar(require("./activity"));
@@ -61,6 +61,7 @@ exports.EventBridgeMessage = __importStar(require("./eventBridge"));
 exports.GenericMessage = __importStar(require("./genericMessage"));
 exports.TransactionProcessor = __importStar(require("./transactionProcessor"));
 exports.Transaction = __importStar(require("./transaction"));
+exports.TransactionAnalytics = __importStar(require("./transactionAnalytics"));
 exports.ContactInfo = __importStar(require("./contactInfo"));
 exports.ProductCatalog = __importStar(require("./productCatalog"));
 exports.Contract = __importStar(require("./contract"));

package/bin/rbac/enums/PoolKind.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tipo de User Pool de Cognito desde la perspectiva del modelo RBAC Fiado.
+ *
+ * Origen: spec del proyecto `cognito-backoffice-connector` (Fase 0, componente 01
+ * documento `docs/superpowers/specs/2026-05-26-cognito-connector-decisiones-pendientes-design.md`).
+ *
+ * Decisión (TD-003): el proyecto converge en estos 2 valores. El documento componente 03
+ * lista 3 valores (incluyendo una variante adicional) pero queda como outlier — la
+ * decisión vigente en los 6 docs restantes y en el plan de implementación es 2 valores:
+ *  - BACKOFFICE_PLATFORM — pool del backoffice de plataforma (cross-tenant)
+ *  - BACKOFFICE_TENANT — pool por tenant (multi-tenant isolation)
+ */
+export declare enum PoolKind {
+    BACKOFFICE_PLATFORM = "BACKOFFICE_PLATFORM",
+    BACKOFFICE_TENANT = "BACKOFFICE_TENANT"
+}

package/bin/rbac/enums/PoolKind.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolKind = void 0;
+/**
+ * Tipo de User Pool de Cognito desde la perspectiva del modelo RBAC Fiado.
+ *
+ * Origen: spec del proyecto `cognito-backoffice-connector` (Fase 0, componente 01
+ * documento `docs/superpowers/specs/2026-05-26-cognito-connector-decisiones-pendientes-design.md`).
+ *
+ * Decisión (TD-003): el proyecto converge en estos 2 valores. El documento componente 03
+ * lista 3 valores (incluyendo una variante adicional) pero queda como outlier — la
+ * decisión vigente en los 6 docs restantes y en el plan de implementación es 2 valores:
+ *  - BACKOFFICE_PLATFORM — pool del backoffice de plataforma (cross-tenant)
+ *  - BACKOFFICE_TENANT — pool por tenant (multi-tenant isolation)
+ */
+var PoolKind;
+(function (PoolKind) {
+    PoolKind["BACKOFFICE_PLATFORM"] = "BACKOFFICE_PLATFORM";
+    PoolKind["BACKOFFICE_TENANT"] = "BACKOFFICE_TENANT";
+})(PoolKind || (exports.PoolKind = PoolKind = {}));

package/bin/rbac/index.d.ts

@@ -0,0 +1 @@
+export * from './enums/PoolKind';

package/bin/rbac/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./enums/PoolKind"), exports);

package/bin/transactionAnalytics/dtos/NormalizedTransaction.d.ts

@@ -0,0 +1,41 @@
+import { AnalyticsTransactionStatusEnum } from "../enums/AnalyticsTransactionStatusEnum";
+import { AnalyticsErrorCategoryEnum } from "../enums/AnalyticsErrorCategoryEnum";
+/**
+ * Forma normalizada de una transacción (STP o Multicomm/Multicenter) para
+ * analítica read-only. La produce el clasificador/normalizador de CADA conector
+ * a partir del item crudo de su tabla; bmb la consume y unifica sin re-mapear.
+ *
+ * Sin decoradores `class-validator`: viaja por la red ya derivada/validada.
+ */
+export declare class NormalizedTransaction {
+    /** PK del item en la tabla del conector (claveRastreo/uuid en STP; uuid en MC). */
+    id: string;
+    /** Proveedor efectivo: "STP" | "MULTICOMM" | "MULTICENTER". */
+    provider: string;
+    /** Módulo conector dueño del dato (stp-service-pay-connector / multicomm-service-pay-connector). */
+    module: string;
+    directoryId: string;
+    transactionNumber: string;
+    /** Epoch ms (campo `createdAt` de la tabla). */
+    createdAt: number;
+    amount: number;
+    fees: number;
+    tax: number;
+    totalDebit: number;
+    /** Id canónico del servicio, derivado del request (servicio/idProducto en STP; codigoProducto/sku en MC). */
+    serviceKey: string;
+    /** Nombre legible si está enriquecido; null en históricos sin enrichment. */
+    serviceName: string | null;
+    /** Categoría del servicio si está enriquecida; null si no. */
+    serviceCategory: string | null;
+    /** País (MC multi-país; STP => MX). null si no aplica. */
+    countryId: string | null;
+    /** Outcome normalizado. */
+    status: AnalyticsTransactionStatusEnum;
+    /** Categoría de motivo (taxonomía de 7 buckets). */
+    errorCategory: AnalyticsErrorCategoryEnum;
+    /** Código crudo del proveedor (STP `estado`; MC `codigoRespuesta`/`codigoRecarga`). */
+    rawCode: string;
+    /** Mensaje crudo del proveedor (siempre presente en datos reales). Solo para display. */
+    rawMessage: string;
+}

package/bin/transactionAnalytics/dtos/NormalizedTransaction.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NormalizedTransaction = void 0;
+/**
+ * Forma normalizada de una transacción (STP o Multicomm/Multicenter) para
+ * analítica read-only. La produce el clasificador/normalizador de CADA conector
+ * a partir del item crudo de su tabla; bmb la consume y unifica sin re-mapear.
+ *
+ * Sin decoradores `class-validator`: viaja por la red ya derivada/validada.
+ */
+class NormalizedTransaction {
+}
+exports.NormalizedTransaction = NormalizedTransaction;

package/bin/transactionAnalytics/dtos/TransactionMetrics.d.ts

@@ -0,0 +1,27 @@
+import { AnalyticsTransactionStatusEnum } from "../enums/AnalyticsTransactionStatusEnum";
+import { AnalyticsErrorCategoryEnum } from "../enums/AnalyticsErrorCategoryEnum";
+import { TransactionServiceMetric } from "./TransactionServiceMetric";
+/**
+ * Agregado de transacciones que devuelve CADA conector sobre su propia tabla.
+ * bmb mergea los agregados de ambos conectores (suma conteos; une `byService`
+ * por `serviceKey`). Sin `class-validator`: es una respuesta read-only.
+ */
+export declare class TransactionMetrics {
+    /** Módulo conector que produjo el agregado. */
+    module: string;
+    /** Total de transacciones en el rango. */
+    total: number;
+    /** Conteo por outcome (todas las claves presentes, con 0 si no aplica). */
+    byStatus: Record<AnalyticsTransactionStatusEnum, number>;
+    /** Conteo por categoría de motivo (taxonomía de 7 buckets). */
+    byErrorCategory: Record<AnalyticsErrorCategoryEnum, number>;
+    /** Conteo por proveedor efectivo (STP / MULTICOMM / MULTICENTER). */
+    byProvider: Record<string, number>;
+    /** Ranking por servicio. */
+    byService: TransactionServiceMetric[];
+    /** Rango temporal cubierto (epoch ms). */
+    range: {
+        from: number;
+        to: number;
+    };
+}

package/bin/transactionAnalytics/dtos/TransactionMetrics.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionMetrics = void 0;
+/**
+ * Agregado de transacciones que devuelve CADA conector sobre su propia tabla.
+ * bmb mergea los agregados de ambos conectores (suma conteos; une `byService`
+ * por `serviceKey`). Sin `class-validator`: es una respuesta read-only.
+ */
+class TransactionMetrics {
+}
+exports.TransactionMetrics = TransactionMetrics;

package/bin/transactionAnalytics/dtos/TransactionMetricsRequest.d.ts

@@ -0,0 +1,18 @@
+import { AnalyticsTransactionStatusEnum } from "../enums/AnalyticsTransactionStatusEnum";
+import { AnalyticsErrorCategoryEnum } from "../enums/AnalyticsErrorCategoryEnum";
+/**
+ * Filtros del agregado de métricas (GET /analytics/metrics del conector;
+ * GET /backoffice/transactions/metrics de bmb).
+ *
+ * Fechas en ISO-8601; el conector las convierte a epoch ms para el scan por
+ * `createdAt`. Rango por defecto 30 días, tope 90 días (lo aplica el manager;
+ * ver README §11).
+ */
+export declare class TransactionMetricsRequest {
+    dateFrom?: string;
+    dateTo?: string;
+    serviceKey?: string;
+    status?: AnalyticsTransactionStatusEnum;
+    errorCategory?: AnalyticsErrorCategoryEnum;
+    countryId?: string;
+}

package/bin/transactionAnalytics/dtos/TransactionMetricsRequest.js

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionMetricsRequest = void 0;
+const class_validator_1 = require("class-validator");
+const AnalyticsTransactionStatusEnum_1 = require("../enums/AnalyticsTransactionStatusEnum");
+const AnalyticsErrorCategoryEnum_1 = require("../enums/AnalyticsErrorCategoryEnum");
+/**
+ * Filtros del agregado de métricas (GET /analytics/metrics del conector;
+ * GET /backoffice/transactions/metrics de bmb).
+ *
+ * Fechas en ISO-8601; el conector las convierte a epoch ms para el scan por
+ * `createdAt`. Rango por defecto 30 días, tope 90 días (lo aplica el manager;
+ * ver README §11).
+ */
+class TransactionMetricsRequest {
+}
+exports.TransactionMetricsRequest = TransactionMetricsRequest;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "dateFrom", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "dateTo", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "serviceKey", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(AnalyticsTransactionStatusEnum_1.AnalyticsTransactionStatusEnum),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "status", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(AnalyticsErrorCategoryEnum_1.AnalyticsErrorCategoryEnum),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "errorCategory", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(16),
+    __metadata("design:type", String)
+], TransactionMetricsRequest.prototype, "countryId", void 0);

package/bin/transactionAnalytics/dtos/TransactionQueryRequest.d.ts

@@ -0,0 +1,12 @@
+import { TransactionMetricsRequest } from "./TransactionMetricsRequest";
+/**
+ * Filtros + paginación para el drill-down de filas
+ * (GET /analytics/query del conector; GET /backoffice/transactions de bmb).
+ * Hereda los filtros de {@link TransactionMetricsRequest}.
+ */
+export declare class TransactionQueryRequest extends TransactionMetricsRequest {
+    /** Cursor opaco (base64) para la próxima página. Ausente => primera página. */
+    index?: string;
+    /** Tamaño de página. */
+    pageSize?: number;
+}

package/bin/transactionAnalytics/dtos/TransactionQueryRequest.js

@@ -0,0 +1,34 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionQueryRequest = void 0;
+const class_validator_1 = require("class-validator");
+const TransactionMetricsRequest_1 = require("./TransactionMetricsRequest");
+/**
+ * Filtros + paginación para el drill-down de filas
+ * (GET /analytics/query del conector; GET /backoffice/transactions de bmb).
+ * Hereda los filtros de {@link TransactionMetricsRequest}.
+ */
+class TransactionQueryRequest extends TransactionMetricsRequest_1.TransactionMetricsRequest {
+}
+exports.TransactionQueryRequest = TransactionQueryRequest;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], TransactionQueryRequest.prototype, "index", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(500),
+    __metadata("design:type", Number)
+], TransactionQueryRequest.prototype, "pageSize", void 0);

package/bin/transactionAnalytics/dtos/TransactionQueryResponse.d.ts

@@ -0,0 +1,10 @@
+import { NormalizedTransaction } from "./NormalizedTransaction";
+/**
+ * Página de transacciones normalizadas (drill-down). El cursor `index` sigue la
+ * misma convención que el resto del repo (base64 opaco).
+ */
+export declare class TransactionQueryResponse {
+    items: NormalizedTransaction[];
+    /** Cursor opaco para la próxima página. Ausente => no hay más páginas. */
+    index?: string;
+}

package/bin/transactionAnalytics/dtos/TransactionQueryResponse.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionQueryResponse = void 0;
+/**
+ * Página de transacciones normalizadas (drill-down). El cursor `index` sigue la
+ * misma convención que el resto del repo (base64 opaco).
+ */
+class TransactionQueryResponse {
+}
+exports.TransactionQueryResponse = TransactionQueryResponse;