@fiado/type-kit 3.278.0 → 3.280.0

package/bin/retailCommission/enums/CommissionMechanicTypeEnum.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionMechanicTypeEnum = void 0;
+/**
+ * Las 6 formas de calcular la comisión de una categoría (D12).
+ *
+ * Son el producto cartesiano de dos ejes —cómo se elige la celda y en qué unidad paga— y por eso
+ * un solo evaluador las cubre todas: `toCells(mechanic)` normaliza cualquiera a
+ * `[{ match, baseValue, withQuotaValue }]` + `valueKind`.
+ *
+ * PRICE_TIER - Por rango de precio del equipo (D/C/B/A). Equipos.
+ * FLAT - Monto fijo por unidad. MiFi, PayJoy.
+ * PERCENT - Porcentaje del precio, en bps. Accesorios.
+ * MATRIX - Celda por N dimensiones. SIMs: operador × origen.
+ * VARIANT - Monto por variante enumerada. Pospago: plan $339 → $220.
+ * PERCENT_BY_PAYMENT - Porcentaje según forma de pago. Zmotos: contado 2% / crédito 4%.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionMechanicTypeEnum;
+(function (CommissionMechanicTypeEnum) {
+    CommissionMechanicTypeEnum["PRICE_TIER"] = "PRICE_TIER";
+    CommissionMechanicTypeEnum["FLAT"] = "FLAT";
+    CommissionMechanicTypeEnum["PERCENT"] = "PERCENT";
+    CommissionMechanicTypeEnum["MATRIX"] = "MATRIX";
+    CommissionMechanicTypeEnum["VARIANT"] = "VARIANT";
+    CommissionMechanicTypeEnum["PERCENT_BY_PAYMENT"] = "PERCENT_BY_PAYMENT";
+})(CommissionMechanicTypeEnum || (exports.CommissionMechanicTypeEnum = CommissionMechanicTypeEnum = {}));

package/bin/retailCommission/enums/CommissionPayeeTypeEnum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Quién cobra una fila de devengo.
+ *
+ * SELLER - El vendedor que originó la venta. Único que se devenga en el primer corte.
+ * STORE_ADMIN - El admin de la tienda, por el `storeOverrideBps`. ⚠️ Modelado pero NO devengado
+ *   hasta que se defina quién es ese admin en `retail-org-business`.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionPayeeTypeEnum {
+    SELLER = "SELLER",
+    STORE_ADMIN = "STORE_ADMIN"
+}

package/bin/retailCommission/enums/CommissionPayeeTypeEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionPayeeTypeEnum = void 0;
+/**
+ * Quién cobra una fila de devengo.
+ *
+ * SELLER - El vendedor que originó la venta. Único que se devenga en el primer corte.
+ * STORE_ADMIN - El admin de la tienda, por el `storeOverrideBps`. ⚠️ Modelado pero NO devengado
+ *   hasta que se defina quién es ese admin en `retail-org-business`.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionPayeeTypeEnum;
+(function (CommissionPayeeTypeEnum) {
+    CommissionPayeeTypeEnum["SELLER"] = "SELLER";
+    CommissionPayeeTypeEnum["STORE_ADMIN"] = "STORE_ADMIN";
+})(CommissionPayeeTypeEnum || (exports.CommissionPayeeTypeEnum = CommissionPayeeTypeEnum = {}));

package/bin/retailCommission/enums/CommissionPayoutStatusEnum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado del corte semanal.
+ *
+ * OPEN - Acumulando devengos. Nadie lo «abre»: el ítem META se crea con upsert al primer ajuste o al cerrar.
+ * CLOSING - Cierre encolado o corriendo. Es el candado: sin este estado, dos clicks en «Cerrar»
+ *   encolan dos workers que liquidan en paralelo, y la UI no puede distinguir «abierto» de «cerrando».
+ * CLOSED - Terminado. Es la ÚLTIMA escritura del worker, no la primera: significa «se pagó todo»,
+ *   no «se empezó a pagar».
+ *
+ * ⚠️ No existe `PAID`: **Fiado no dispersa el pago**. El archivo se entrega a la nómina de LUGA.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionPayoutStatusEnum {
+    OPEN = "OPEN",
+    CLOSING = "CLOSING",
+    CLOSED = "CLOSED"
+}

package/bin/retailCommission/enums/CommissionPayoutStatusEnum.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionPayoutStatusEnum = void 0;
+/**
+ * Estado del corte semanal.
+ *
+ * OPEN - Acumulando devengos. Nadie lo «abre»: el ítem META se crea con upsert al primer ajuste o al cerrar.
+ * CLOSING - Cierre encolado o corriendo. Es el candado: sin este estado, dos clicks en «Cerrar»
+ *   encolan dos workers que liquidan en paralelo, y la UI no puede distinguir «abierto» de «cerrando».
+ * CLOSED - Terminado. Es la ÚLTIMA escritura del worker, no la primera: significa «se pagó todo»,
+ *   no «se empezó a pagar».
+ *
+ * ⚠️ No existe `PAID`: **Fiado no dispersa el pago**. El archivo se entrega a la nómina de LUGA.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionPayoutStatusEnum;
+(function (CommissionPayoutStatusEnum) {
+    CommissionPayoutStatusEnum["OPEN"] = "OPEN";
+    CommissionPayoutStatusEnum["CLOSING"] = "CLOSING";
+    CommissionPayoutStatusEnum["CLOSED"] = "CLOSED";
+})(CommissionPayoutStatusEnum || (exports.CommissionPayoutStatusEnum = CommissionPayoutStatusEnum = {}));

package/bin/retailCommission/enums/CommissionPeriodTypeEnum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Periodicidad de la cuota. El modal del plan ofrece las tres.
+ *
+ * ⚠️ El primer corte implementa SOLO `WEEKLY`; las otras dos se rechazan con error tipado en vez de
+ * calcularse mal en silencio.
+ *
+ * WEEKLY - Semanal. `M6_ADMIN` §9.3 y §9.4: corte de martes a lunes.
+ * BIWEEKLY - Quincenal. No implementada.
+ * MONTHLY - Mensual. No implementada.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionPeriodTypeEnum {
+    WEEKLY = "WEEKLY",
+    BIWEEKLY = "BIWEEKLY",
+    MONTHLY = "MONTHLY"
+}

package/bin/retailCommission/enums/CommissionPeriodTypeEnum.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionPeriodTypeEnum = void 0;
+/**
+ * Periodicidad de la cuota. El modal del plan ofrece las tres.
+ *
+ * ⚠️ El primer corte implementa SOLO `WEEKLY`; las otras dos se rechazan con error tipado en vez de
+ * calcularse mal en silencio.
+ *
+ * WEEKLY - Semanal. `M6_ADMIN` §9.3 y §9.4: corte de martes a lunes.
+ * BIWEEKLY - Quincenal. No implementada.
+ * MONTHLY - Mensual. No implementada.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionPeriodTypeEnum;
+(function (CommissionPeriodTypeEnum) {
+    CommissionPeriodTypeEnum["WEEKLY"] = "WEEKLY";
+    CommissionPeriodTypeEnum["BIWEEKLY"] = "BIWEEKLY";
+    CommissionPeriodTypeEnum["MONTHLY"] = "MONTHLY";
+})(CommissionPeriodTypeEnum || (exports.CommissionPeriodTypeEnum = CommissionPeriodTypeEnum = {}));

package/bin/retailCommission/enums/CommissionPlanStatusEnum.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Estado de una versión del plan de comisiones.
+ *
+ * DRAFT - Borrador en edición. Ítem ÚNICO (`sk = DRAFT`): se pisa, no versiona.
+ * PUBLISHED - Snapshot sellado y vigente. Apuntado por el puntero `ACTIVE`.
+ * SUPERSEDED - Snapshot que fue vigente y ya no lo es. Inmutable: lo devengado con él ya se devengó.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionPlanStatusEnum {
+    DRAFT = "DRAFT",
+    PUBLISHED = "PUBLISHED",
+    SUPERSEDED = "SUPERSEDED"
+}

package/bin/retailCommission/enums/CommissionPlanStatusEnum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionPlanStatusEnum = void 0;
+/**
+ * Estado de una versión del plan de comisiones.
+ *
+ * DRAFT - Borrador en edición. Ítem ÚNICO (`sk = DRAFT`): se pisa, no versiona.
+ * PUBLISHED - Snapshot sellado y vigente. Apuntado por el puntero `ACTIVE`.
+ * SUPERSEDED - Snapshot que fue vigente y ya no lo es. Inmutable: lo devengado con él ya se devengó.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionPlanStatusEnum;
+(function (CommissionPlanStatusEnum) {
+    CommissionPlanStatusEnum["DRAFT"] = "DRAFT";
+    CommissionPlanStatusEnum["PUBLISHED"] = "PUBLISHED";
+    CommissionPlanStatusEnum["SUPERSEDED"] = "SUPERSEDED";
+})(CommissionPlanStatusEnum || (exports.CommissionPlanStatusEnum = CommissionPlanStatusEnum = {}));

package/bin/retailCommission/enums/CommissionPriceReferenceEnum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Contra qué precio se evalúa la mecánica de una categoría.
+ *
+ * ⚠️ En el primer corte las tres resuelven contra el mismo número: la venta trae UN precio
+ * (`equipmentPriceCents`, con `amountCents` de respaldo). Se modela porque el plan de Jaime lo
+ * declara por categoría y borrarlo obligaría a migrar los snapshots cuando lleguen los tres precios.
+ *
+ * LIST - Precio de lista.
+ * FINAL - Precio final cobrado.
+ * PUBLIC - Precio público sugerido.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionPriceReferenceEnum {
+    LIST = "LIST",
+    FINAL = "FINAL",
+    PUBLIC = "PUBLIC"
+}

package/bin/retailCommission/enums/CommissionPriceReferenceEnum.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionPriceReferenceEnum = void 0;
+/**
+ * Contra qué precio se evalúa la mecánica de una categoría.
+ *
+ * ⚠️ En el primer corte las tres resuelven contra el mismo número: la venta trae UN precio
+ * (`equipmentPriceCents`, con `amountCents` de respaldo). Se modela porque el plan de Jaime lo
+ * declara por categoría y borrarlo obligaría a migrar los snapshots cuando lleguen los tres precios.
+ *
+ * LIST - Precio de lista.
+ * FINAL - Precio final cobrado.
+ * PUBLIC - Precio público sugerido.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionPriceReferenceEnum;
+(function (CommissionPriceReferenceEnum) {
+    CommissionPriceReferenceEnum["LIST"] = "LIST";
+    CommissionPriceReferenceEnum["FINAL"] = "FINAL";
+    CommissionPriceReferenceEnum["PUBLIC"] = "PUBLIC";
+})(CommissionPriceReferenceEnum || (exports.CommissionPriceReferenceEnum = CommissionPriceReferenceEnum = {}));

package/bin/retailCommission/enums/CommissionQuotaMeasureEnum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Qué se mide para evaluar la cuota.
+ *
+ * UNITS - Piezas vendidas en el periodo.
+ * SK_AMOUNT - Monto vendido, contando SOLO las ventas con financiera SUREKEEP.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionQuotaMeasureEnum {
+    UNITS = "UNITS",
+    SK_AMOUNT = "SK_AMOUNT"
+}

package/bin/retailCommission/enums/CommissionQuotaMeasureEnum.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionQuotaMeasureEnum = void 0;
+/**
+ * Qué se mide para evaluar la cuota.
+ *
+ * UNITS - Piezas vendidas en el periodo.
+ * SK_AMOUNT - Monto vendido, contando SOLO las ventas con financiera SUREKEEP.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionQuotaMeasureEnum;
+(function (CommissionQuotaMeasureEnum) {
+    CommissionQuotaMeasureEnum["UNITS"] = "UNITS";
+    CommissionQuotaMeasureEnum["SK_AMOUNT"] = "SK_AMOUNT";
+})(CommissionQuotaMeasureEnum || (exports.CommissionQuotaMeasureEnum = CommissionQuotaMeasureEnum = {}));

package/bin/retailCommission/enums/CommissionQuotaModeEnum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cómo se aplica la cuota al alcanzarse.
+ *
+ * Queda con un solo valor A PROPÓSITO: es un campo enumerable del dominio, no un flag. Guardarlo
+ * como booleano obligaría a migrar los snapshots el día que aparezca un modo prospectivo.
+ *
+ * RETROACTIVE - Aplica a TODO lo devengado en el periodo, no solo a lo que vino después.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionQuotaModeEnum {
+    RETROACTIVE = "RETROACTIVE"
+}

package/bin/retailCommission/enums/CommissionQuotaModeEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionQuotaModeEnum = void 0;
+/**
+ * Cómo se aplica la cuota al alcanzarse.
+ *
+ * Queda con un solo valor A PROPÓSITO: es un campo enumerable del dominio, no un flag. Guardarlo
+ * como booleano obligaría a migrar los snapshots el día que aparezca un modo prospectivo.
+ *
+ * RETROACTIVE - Aplica a TODO lo devengado en el periodo, no solo a lo que vino después.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionQuotaModeEnum;
+(function (CommissionQuotaModeEnum) {
+    CommissionQuotaModeEnum["RETROACTIVE"] = "RETROACTIVE";
+})(CommissionQuotaModeEnum || (exports.CommissionQuotaModeEnum = CommissionQuotaModeEnum = {}));

package/bin/retailCommission/enums/CommissionQuotaSubjectEnum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sobre quién se acumula la cuota.
+ *
+ * SELLER - Por vendedor. Único implementado en el primer corte.
+ * STORE - Por tienda: la alcanza el equipo completo.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionQuotaSubjectEnum {
+    SELLER = "SELLER",
+    STORE = "STORE"
+}

package/bin/retailCommission/enums/CommissionQuotaSubjectEnum.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionQuotaSubjectEnum = void 0;
+/**
+ * Sobre quién se acumula la cuota.
+ *
+ * SELLER - Por vendedor. Único implementado en el primer corte.
+ * STORE - Por tienda: la alcanza el equipo completo.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionQuotaSubjectEnum;
+(function (CommissionQuotaSubjectEnum) {
+    CommissionQuotaSubjectEnum["SELLER"] = "SELLER";
+    CommissionQuotaSubjectEnum["STORE"] = "STORE";
+})(CommissionQuotaSubjectEnum || (exports.CommissionQuotaSubjectEnum = CommissionQuotaSubjectEnum = {}));

package/bin/retailCommission/enums/CommissionQuotaTypeEnum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tipo de cuota. Cuota y acelerador quedaron unificados en un solo concepto (Jaime, 28-jul).
+ *
+ * BINARY - Un gate: alcanzarlo cambia de columna (`base` → `withQuota`) para las categorías que la referencian.
+ * TIERED - N niveles con multiplicador RETROACTIVO sobre el resultado. Es el «acelerador».
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionQuotaTypeEnum {
+    BINARY = "BINARY",
+    TIERED = "TIERED"
+}

package/bin/retailCommission/enums/CommissionQuotaTypeEnum.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionQuotaTypeEnum = void 0;
+/**
+ * Tipo de cuota. Cuota y acelerador quedaron unificados en un solo concepto (Jaime, 28-jul).
+ *
+ * BINARY - Un gate: alcanzarlo cambia de columna (`base` → `withQuota`) para las categorías que la referencian.
+ * TIERED - N niveles con multiplicador RETROACTIVO sobre el resultado. Es el «acelerador».
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionQuotaTypeEnum;
+(function (CommissionQuotaTypeEnum) {
+    CommissionQuotaTypeEnum["BINARY"] = "BINARY";
+    CommissionQuotaTypeEnum["TIERED"] = "TIERED";
+})(CommissionQuotaTypeEnum || (exports.CommissionQuotaTypeEnum = CommissionQuotaTypeEnum = {}));

package/bin/retailCommission/index.d.ts

@@ -0,0 +1,18 @@
+export * from './enums/CommissionPlanStatusEnum';
+export * from './enums/CommissionMechanicTypeEnum';
+export * from './enums/CommissionPriceReferenceEnum';
+export * from './enums/CommissionQuotaTypeEnum';
+export * from './enums/CommissionQuotaMeasureEnum';
+export * from './enums/CommissionQuotaSubjectEnum';
+export * from './enums/CommissionPeriodTypeEnum';
+export * from './enums/CommissionQuotaModeEnum';
+export * from './enums/CommissionAccrualStatusEnum';
+export * from './enums/CommissionPayoutStatusEnum';
+export * from './enums/CommissionPayeeTypeEnum';
+export * from './enums/CommissionExceptionTypeEnum';
+export * from './enums/CommissionCalcStepEnum';
+export * from './dtos/CommissionPlan';
+export * from './dtos/CommissionCalcTrace';
+export * from './dtos/CommissionAccrual';
+export * from './dtos/CommissionPayout';
+export * from './dtos/CommissionApi';

package/bin/retailCommission/index.js

@@ -0,0 +1,37 @@
+"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 });
+// Enums
+__exportStar(require("./enums/CommissionPlanStatusEnum"), exports);
+__exportStar(require("./enums/CommissionMechanicTypeEnum"), exports);
+__exportStar(require("./enums/CommissionPriceReferenceEnum"), exports);
+__exportStar(require("./enums/CommissionQuotaTypeEnum"), exports);
+__exportStar(require("./enums/CommissionQuotaMeasureEnum"), exports);
+__exportStar(require("./enums/CommissionQuotaSubjectEnum"), exports);
+__exportStar(require("./enums/CommissionPeriodTypeEnum"), exports);
+__exportStar(require("./enums/CommissionQuotaModeEnum"), exports);
+__exportStar(require("./enums/CommissionAccrualStatusEnum"), exports);
+__exportStar(require("./enums/CommissionPayoutStatusEnum"), exports);
+__exportStar(require("./enums/CommissionPayeeTypeEnum"), exports);
+__exportStar(require("./enums/CommissionExceptionTypeEnum"), exports);
+__exportStar(require("./enums/CommissionCalcStepEnum"), exports);
+// Entidades del dominio
+__exportStar(require("./dtos/CommissionPlan"), exports);
+__exportStar(require("./dtos/CommissionCalcTrace"), exports);
+__exportStar(require("./dtos/CommissionAccrual"), exports);
+__exportStar(require("./dtos/CommissionPayout"), exports);
+// Contratos HTTP — uno por endpoint
+__exportStar(require("./dtos/CommissionApi"), exports);

package/package.json

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

package/src/collection/dtos/CollectionAttemptDto.ts

@@ -0,0 +1,17 @@
+import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { MechanismType } from '../enums/MechanismType';
+import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+
+/** Un intento de cobro ejecutado sobre un intent, para el backoffice de monitoreo. */
+export class CollectionAttemptDto {
+  @IsString() attemptId!: string;
+  @IsString() intentId!: string;
+  @IsString() source!: string;
+  @IsEnum(MechanismType) mechanism!: MechanismType;
+  @IsInt() amount!: number;
+  @IsOptional() @IsString() holdTxId?: string;
+  @IsOptional() @IsEnum(CollectionResultStatus) result?: CollectionResultStatus;
+  @IsOptional() @IsString() errorCode?: string;
+  @IsOptional() @IsString() errorDetail?: string;
+  @IsInt() createdAt!: number;                    // epoch ms
+}

package/src/collection/dtos/CollectionErrorLogDto.ts

@@ -0,0 +1,14 @@
+import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { SagaStep } from '../enums/SagaStep';
+
+/** Entrada del log estructurado de errores del motor de cobro, para el backoffice de monitoreo. */
+export class CollectionErrorLogDto {
+  @IsString() errorId!: string;
+  @IsOptional() @IsString() intentId?: string;
+  @IsOptional() @IsString() attemptId?: string;
+  @IsOptional() @IsEnum(SagaStep) sagaStep?: SagaStep;
+  @IsString() errorCode!: string;
+  @IsOptional() @IsString() errorDetail?: string;
+  @IsString() tenantId!: string;
+  @IsInt() createdAt!: number;                    // epoch ms
+}

package/src/collection/dtos/CollectionIntentDetailDto.ts

@@ -0,0 +1,13 @@
+import { IsArray, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
+import { CollectionIntentSummaryDto } from './CollectionIntentSummaryDto';
+import { CollectionAttemptDto } from './CollectionAttemptDto';
+import { CollectionOutboxEventDto } from './CollectionOutboxEventDto';
+import { CollectionErrorLogDto } from './CollectionErrorLogDto';
+
+/** Detalle de un intent para el backoffice de monitoreo: el resumen más su historial completo. */
+export class CollectionIntentDetailDto extends CollectionIntentSummaryDto {
+  @IsArray() @ValidateNested({ each: true }) @Type(() => CollectionAttemptDto) attempts!: CollectionAttemptDto[];
+  @IsArray() @ValidateNested({ each: true }) @Type(() => CollectionOutboxEventDto) outbox!: CollectionOutboxEventDto[];
+  @IsArray() @ValidateNested({ each: true }) @Type(() => CollectionErrorLogDto) errors!: CollectionErrorLogDto[];
+}

package/src/collection/dtos/CollectionIntentSummaryDto.ts

@@ -0,0 +1,24 @@
+import { IsString, IsInt, IsBoolean, IsEnum, IsOptional } from 'class-validator';
+import { CollectionState } from '../enums/CollectionState';
+import { SagaStep } from '../enums/SagaStep';
+
+/** Fila de listado de intents para el backoffice de monitoreo del motor de cobro. */
+export class CollectionIntentSummaryDto {
+  @IsString() intentId!: string;
+  @IsString() ownerRef!: string;
+  @IsString() tenantId!: string;
+  @IsString() domain!: string;
+  @IsString() chargeId!: string;
+  @IsInt() amount!: number;
+  @IsOptional() @IsInt() reserved?: number;
+  @IsEnum(CollectionState) state!: CollectionState;
+  @IsEnum(SagaStep) sagaStep!: SagaStep;
+  @IsOptional() @IsBoolean() attention?: boolean;
+  @IsOptional() @IsInt() failureCount?: number;
+  @IsOptional() @IsInt() retryCount?: number;
+  @IsOptional() @IsInt() nextRetryAt?: number;    // epoch ms
+  @IsOptional() @IsString() lastErrorCode?: string;
+  @IsOptional() @IsString() lastErrorMsg?: string;
+  @IsInt() createdAt!: number;                    // epoch ms
+  @IsInt() updatedAt!: number;                     // epoch ms
+}

package/src/collection/dtos/CollectionMetricsDto.ts

@@ -0,0 +1,11 @@
+import { IsInt, IsNumber, IsObject } from 'class-validator';
+
+/** Métricas agregadas del motor de cobro, para el dashboard del backoffice de monitoreo. */
+export class CollectionMetricsDto {
+  @IsObject() countsByState!: Record<string, number>;
+  @IsNumber() successRate!: number;
+  @IsInt() amountReserved!: number;
+  @IsInt() amountCollected!: number;
+  @IsInt() backlogAwaitingFunds!: number;
+  @IsInt() dlqCount!: number;
+}

package/src/collection/dtos/CollectionOutboxEventDto.ts

@@ -0,0 +1,17 @@
+import { IsString, IsInt, IsOptional } from 'class-validator';
+
+/**
+ * Mensaje del outbox transaccional (publicación de `CollectionResult` hacia el dominio), para el
+ * backoffice de monitoreo. `status` viaja como texto (p.ej. `PENDING`, `SENT`, `FAILED`, `DLQ`) — su
+ * enum de origen es interno a la mecánica de entrega del motor.
+ */
+export class CollectionOutboxEventDto {
+  @IsString() eventId!: string;
+  @IsString() attemptId!: string;
+  @IsString() domain!: string;
+  @IsString() status!: string;
+  @IsOptional() @IsInt() deliveryAttempts?: number;
+  @IsOptional() @IsString() lastError?: string;
+  @IsOptional() @IsInt() movedToDlqAt?: number;   // epoch ms
+  @IsInt() createdAt!: number;                     // epoch ms
+}

package/src/collection/index.ts

@@ -17,3 +17,11 @@ export * from './dtos/CollectionSourceDto';
 export * from './dtos/CollectionProductConfigDto';
 export * from './dtos/UpsertProductConfigRequest';
 export * from './dtos/ApplyCollectionResultRequest';
+
+// DTOs — backoffice de monitoreo
+export * from './dtos/CollectionIntentSummaryDto';
+export * from './dtos/CollectionAttemptDto';
+export * from './dtos/CollectionOutboxEventDto';
+export * from './dtos/CollectionErrorLogDto';
+export * from './dtos/CollectionIntentDetailDto';
+export * from './dtos/CollectionMetricsDto';

package/src/index.ts

@@ -105,6 +105,10 @@ export * as EmailVerification from './emailVerification';
 // RetailOrg: DTOs/enums del lambda retail-org-business (SureKeep Fase 1 — pista Retail).
 // Dominio de retailers → zonas → tiendas → usuarios retail.
 export * as RetailOrg from './retailOrg';
+// RetailCommission: DTOs/enums del lambda retail-commission-business (SureKeep Fase 3 — pista
+// Retail). El motor de comisiones de VentasLuga: el plan versionado por snapshot, el devengo por
+// venta y el corte semanal.
+export * as RetailCommission from './retailCommission';
 // RetailCatalog: DTOs/enums del lambda retail-catalog-business (comp 05 — catálogo de productos
 // por SKU + inventario por IMEI; SureKeep Fase 1 — pista Retail).
 export * as RetailCatalog from './retailCatalog';

package/src/retailCommission/dtos/CommissionAccrual.ts

@@ -0,0 +1,81 @@
+import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStatusEnum';
+import type { CommissionPayeeTypeEnum } from '../enums/CommissionPayeeTypeEnum';
+import type { SaleFinancierEnum } from '../../retailWizard/enums/SaleFinancierEnum';
+import type { CommissionCalcTrace } from './CommissionCalcTrace';
+
+/**
+ * El devengo: lo que se le debe a un vendedor por UNA venta.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * **Se comisiona la venta, no la línea.** Una `RetailSale` es de un solo producto: no hay `lines[]`
+ * que repartir.
+ *
+ * ⚠️ **Append-only solo hasta el cierre.** Al devengar se escriben el monto base y la traza; al
+ * cerrar el corte se escriben `quotaMet`, `quotaFactorBps`, `settledAmountCents`, `payoutId` y el
+ * `status`. Es un mutable con historia, no un log inmutable.
+ */
+export interface CommissionAccrual {
+    sellerId: string;
+    periodId: string;
+    saleId: string;
+    /** Denormalizados: son lo que hace posible aislar por retailer sin un GSI. */
+    retailerId: string;
+    storeId: string;
+    payeeType: CommissionPayeeTypeEnum;
+    status: CommissionAccrualStatusEnum;
+    /** Con qué versión del plan se calculó. Apunta a un `SNAPSHOT#<ulid>` consultable. */
+    planSnapshotId: string;
+    /**
+     * Versión del motor que lo calculó.
+     *
+     * El snapshot congela el PLAN, no el CÓDIGO. Sin este campo, un cambio en el evaluador vuelve
+     * imposible reproducir un monto viejo aunque el plan esté intacto.
+     */
+    calcEngineVersion: string;
+    categoryId: string | null;
+    mechanicType: string | null;
+    /** Resultado de mecánica + excepciones + add-ons. **Sin cuota ni acelerador.** */
+    baseAmountCents: number;
+    /** Derivada de `type` + `externalProvider` con `financierOfSale` del type-kit. */
+    financier: SaleFinancierEnum;
+
+    /** Al CERRAR: si el vendedor alcanzó la cuota de su categoría. */
+    quotaMet: boolean | null;
+    /** Al CERRAR: factor del acelerador. 10000 = 1.0×. */
+    quotaFactorBps: number | null;
+    /**
+     * Al CERRAR: el total liquidado.
+     *
+     * Se llama así —y no `amountCents`— para que nadie lo lea como definitivo antes del cierre.
+     */
+    settledAmountCents: number | null;
+    payoutId: string | null;
+    reversalReason: string | null;
+    calcTrace: CommissionCalcTrace;
+}
+
+/**
+ * Lo mínimo de una venta para devengarla. Es lo que llega por la cola y lo que se reconstruye
+ * desde el data lake al simular — por eso vive en el type-kit y no dentro del motor.
+ */
+export interface CommissionSaleInput {
+    saleId: string;
+    sellerId: string;
+    retailerId: string;
+    storeId: string;
+    sku: string;
+    brand: string | null;
+    /**
+     * 🔴 **La base de comisión es el PRECIO DEL EQUIPO, no lo cobrado en caja.**
+     *
+     * En una venta a crédito `amountCents` es SOLO el enganche: comisionar sobre él pagaría una
+     * fracción de lo que corresponde. Se usa `equipmentPriceCents` y se cae a `amountCents` solo
+     * cuando no está (ventas viejas sin el dato).
+     */
+    equipmentPriceCents: number | null;
+    amountCents: number;
+    financier: SaleFinancierEnum;
+    /** `CASH` | `CREDIT`, para `PERCENT_BY_PAYMENT`. */
+    paymentType: string;
+    soldAt: string;
+}