@fiado/type-kit 3.279.0 → 3.281.0

package/bin/index.d.ts

@@ -91,6 +91,7 @@ export * as Modelias from './modelias';
 export * as NetworkConnector from './networkConnector';
 export * as EmailVerification from './emailVerification';
 export * as RetailOrg from './retailOrg';
+export * as RetailCommission from './retailCommission';
 export * as RetailCatalog from './retailCatalog';
 export * as RetailCards from './retailCards';
 export * as RetailCustomer from './retailCustomer';

package/bin/index.js

@@ -37,8 +37,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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.UserTags = exports.Group = exports.File = exports.ExchangeRate = exports.Directory = exports.Currency = exports.Country = exports.Card = exports.Authentication = exports.AppContent = exports.App = exports.Offices = exports.Places = exports.Address = exports.Beneficiary = exports.Activity = exports.Biometrics = exports.MetamapConnector = exports.Account = exports.Crypto = void 0;
-exports.Shortlink = exports.LoanConfig = exports.DatalakeQuery = exports.RetailWizard = exports.RetailCustomer = exports.RetailCards = exports.RetailCatalog = exports.RetailOrg = exports.EmailVerification = exports.NetworkConnector = exports.Modelias = exports.TotpSecurity = exports.Passport = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.TwilioConnector = 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 = exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = exports.Observations = void 0;
-exports.Collection = exports.Shipping = exports.PhoneSales = exports.Onboarding = exports.Kyc = exports.LoanScoring = exports.LoanCredit = exports.LoanCollectorAssignment = exports.LoanOfferings = void 0;
+exports.LoanConfig = exports.DatalakeQuery = exports.RetailWizard = exports.RetailCustomer = exports.RetailCards = exports.RetailCatalog = exports.RetailCommission = exports.RetailOrg = exports.EmailVerification = exports.NetworkConnector = exports.Modelias = exports.TotpSecurity = exports.Passport = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.TwilioConnector = 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 = exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = exports.Observations = void 0;
+exports.Collection = exports.Shipping = exports.PhoneSales = exports.Onboarding = exports.Kyc = exports.LoanScoring = exports.LoanCredit = exports.LoanCollectorAssignment = exports.LoanOfferings = exports.Shortlink = void 0;
 exports.Crypto = __importStar(require("./crypto"));
 exports.Account = __importStar(require("./account"));
 exports.MetamapConnector = __importStar(require("./metamapConnector"));
@@ -146,6 +146,10 @@ exports.EmailVerification = __importStar(require("./emailVerification"));
 // RetailOrg: DTOs/enums del lambda retail-org-business (SureKeep Fase 1 — pista Retail).
 // Dominio de retailers → zonas → tiendas → usuarios retail.
 exports.RetailOrg = __importStar(require("./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.
+exports.RetailCommission = __importStar(require("./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).
 exports.RetailCatalog = __importStar(require("./retailCatalog"));

package/bin/phoneSales/DeviceVariantPriceRequestDto.d.ts

@@ -0,0 +1,9 @@
+import { CurrencyId } from '../currency';
+/**
+ * Item de precio usado dentro de `SetDeviceVariantPricesRequestDto.prices`.
+ * No se expone como endpoint propio, solo como elemento anidado validado.
+ */
+export declare class DeviceVariantPriceRequestDto {
+    currencyId: CurrencyId;
+    price: number;
+}

package/bin/{walletFunding/dtos/CancelWalletFundingRequest.js → phoneSales/DeviceVariantPriceRequestDto.js}

@@ -9,13 +9,21 @@ 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.CancelWalletFundingRequest = void 0;
+exports.DeviceVariantPriceRequestDto = void 0;
 const class_validator_1 = require("class-validator");
-class CancelWalletFundingRequest {
+const currency_1 = require("../currency");
+/**
+ * Item de precio usado dentro de `SetDeviceVariantPricesRequestDto.prices`.
+ * No se expone como endpoint propio, solo como elemento anidado validado.
+ */
+class DeviceVariantPriceRequestDto {
 }
-exports.CancelWalletFundingRequest = CancelWalletFundingRequest;
+exports.DeviceVariantPriceRequestDto = DeviceVariantPriceRequestDto;
 __decorate([
-    (0, class_validator_1.IsString)(),
-    (0, class_validator_1.MaxLength)(64),
+    (0, class_validator_1.IsEnum)(currency_1.CurrencyId),
     __metadata("design:type", String)
-], CancelWalletFundingRequest.prototype, "idempotencyKey", void 0);
+], DeviceVariantPriceRequestDto.prototype, "currencyId", void 0);
+__decorate([
+    (0, class_validator_1.IsNumber)(),
+    __metadata("design:type", Number)
+], DeviceVariantPriceRequestDto.prototype, "price", void 0);

package/bin/phoneSales/DeviceVariantPriceResponseDto.d.ts

@@ -0,0 +1,6 @@
+import { CurrencyId } from '../currency';
+/** Precio de una variante de dispositivo en una moneda especifica. */
+export declare class DeviceVariantPriceResponseDto {
+    currencyId: CurrencyId;
+    price: number;
+}

package/bin/phoneSales/DeviceVariantPriceResponseDto.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceVariantPriceResponseDto = void 0;
+/** Precio de una variante de dispositivo en una moneda especifica. */
+class DeviceVariantPriceResponseDto {
+}
+exports.DeviceVariantPriceResponseDto = DeviceVariantPriceResponseDto;

package/bin/phoneSales/SaleResponseDto.d.ts

@@ -1,3 +1,4 @@
+import { CurrencyId } from '../currency';
 export declare class SaleResponseDto {
     id: string;
     referenceCode: string;
@@ -16,4 +17,11 @@ export declare class SaleResponseDto {
     variantModel: string | null;
     /** Color de la variante — mismo criterio de resolución/degradación que `variantModel`. */
     variantColor: string | null;
+    /**
+     * Monto realmente cobrado, congelado al momento de la venta (multi-moneda).
+     * `null` en ventas anteriores a la feature de multi-moneda — no tenían este dato.
+     */
+    chargedAmount: number | null;
+    /** Moneda en la que se cobró `chargedAmount` — mismo motivo de nullability. */
+    chargedCurrencyId: CurrencyId | null;
 }

package/bin/phoneSales/SetDeviceVariantPricesRequestDto.d.ts

@@ -0,0 +1,8 @@
+import { DeviceVariantPriceRequestDto } from './DeviceVariantPriceRequestDto';
+/**
+ * Upsert bulk de todos los precios (por moneda) de una variante de dispositivo.
+ * Reemplaza el set completo — no hay historial/versionado de precios previos.
+ */
+export declare class SetDeviceVariantPricesRequestDto {
+    prices: DeviceVariantPriceRequestDto[];
+}

package/bin/{walletFunding/dtos/CancelFundingReferenceRequest.js → phoneSales/SetDeviceVariantPricesRequestDto.js}

@@ -9,23 +9,19 @@ 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.CancelFundingReferenceRequest = void 0;
+exports.SetDeviceVariantPricesRequestDto = void 0;
 const class_validator_1 = require("class-validator");
-class CancelFundingReferenceRequest {
+const class_transformer_1 = require("class-transformer");
+const DeviceVariantPriceRequestDto_1 = require("./DeviceVariantPriceRequestDto");
+/**
+ * Upsert bulk de todos los precios (por moneda) de una variante de dispositivo.
+ * Reemplaza el set completo — no hay historial/versionado de precios previos.
+ */
+class SetDeviceVariantPricesRequestDto {
 }
-exports.CancelFundingReferenceRequest = CancelFundingReferenceRequest;
+exports.SetDeviceVariantPricesRequestDto = SetDeviceVariantPricesRequestDto;
 __decorate([
-    (0, class_validator_1.IsString)(),
-    (0, class_validator_1.MaxLength)(64),
-    __metadata("design:type", String)
-], CancelFundingReferenceRequest.prototype, "reference", void 0);
-__decorate([
-    (0, class_validator_1.IsString)(),
-    (0, class_validator_1.MaxLength)(64),
-    __metadata("design:type", String)
-], CancelFundingReferenceRequest.prototype, "directoryId", void 0);
-__decorate([
-    (0, class_validator_1.IsString)(),
-    (0, class_validator_1.MaxLength)(64),
-    __metadata("design:type", String)
-], CancelFundingReferenceRequest.prototype, "idempotencyKey", void 0);
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => DeviceVariantPriceRequestDto_1.DeviceVariantPriceRequestDto),
+    __metadata("design:type", Array)
+], SetDeviceVariantPricesRequestDto.prototype, "prices", void 0);

package/bin/phoneSales/enums/DeviceVariantStatusEnum.d.ts

@@ -0,0 +1,4 @@
+export declare enum DeviceVariantStatusEnum {
+    ACTIVE = "ACTIVE",
+    HIDDEN = "HIDDEN"
+}

package/bin/phoneSales/enums/DeviceVariantStatusEnum.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceVariantStatusEnum = void 0;
+var DeviceVariantStatusEnum;
+(function (DeviceVariantStatusEnum) {
+    DeviceVariantStatusEnum["ACTIVE"] = "ACTIVE";
+    DeviceVariantStatusEnum["HIDDEN"] = "HIDDEN";
+})(DeviceVariantStatusEnum || (exports.DeviceVariantStatusEnum = DeviceVariantStatusEnum = {}));

package/bin/phoneSales/index.d.ts

@@ -6,4 +6,8 @@ export * from './SaleResponseDto';
 export * from './RedeemSaleCodeRequestDto';
 export * from './DeviceVariantImageUploadUrlRequestDto';
 export * from './DeviceVariantImageUploadUrlResponseDto';
+export * from './DeviceVariantPriceResponseDto';
+export * from './DeviceVariantPriceRequestDto';
+export * from './SetDeviceVariantPricesRequestDto';
 export * from './enums/DeviceImageContentTypeEnum';
+export * from './enums/DeviceVariantStatusEnum';

package/bin/phoneSales/index.js

@@ -22,4 +22,8 @@ __exportStar(require("./SaleResponseDto"), exports);
 __exportStar(require("./RedeemSaleCodeRequestDto"), exports);
 __exportStar(require("./DeviceVariantImageUploadUrlRequestDto"), exports);
 __exportStar(require("./DeviceVariantImageUploadUrlResponseDto"), exports);
+__exportStar(require("./DeviceVariantPriceResponseDto"), exports);
+__exportStar(require("./DeviceVariantPriceRequestDto"), exports);
+__exportStar(require("./SetDeviceVariantPricesRequestDto"), exports);
 __exportStar(require("./enums/DeviceImageContentTypeEnum"), exports);
+__exportStar(require("./enums/DeviceVariantStatusEnum"), exports);

package/bin/retailCommission/dtos/CommissionAccrual.d.ts

@@ -0,0 +1,78 @@
+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;
+}

package/bin/retailCommission/dtos/CommissionAccrual.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailCommission/dtos/CommissionApi.d.ts

@@ -0,0 +1,169 @@
+import type { CommissionPlanStatusEnum } from '../enums/CommissionPlanStatusEnum';
+import type { CommissionPayoutStatusEnum } from '../enums/CommissionPayoutStatusEnum';
+import type { CommissionAddOn, CommissionCategory, CommissionPlanSnapshot, CommissionQuota } from './CommissionPlan';
+import type { CommissionAccrual, CommissionSaleInput } from './CommissionAccrual';
+import type { CommissionAdjustment, CommissionPayout, CommissionPayoutSeller } from './CommissionPayout';
+/**
+ * Los contratos HTTP del motor de comisiones — uno por endpoint, sin reutilizar.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ **El `retailerId` NO aparece en ningún request.** Sale siempre del token: el silo aísla por
+ * *tenant*, no por *retailer*, y SureKeep tiene varios. Si un request lo mandara, se ignoraría — pero
+ * la mejor forma de que no se ignore mal es que no exista el campo.
+ */
+/**
+ * `GET /backoffice/commissions/plan`
+ *
+ * `active: null` es un estado legítimo, no un 404: una cadena recién dada de alta todavía no publicó
+ * su primer plan. Devolver 404 obligaría al front a tratar el arranque normal como excepción, y esa
+ * rama solo se ejercita el primer día de cada cadena — o sea, nunca se prueba.
+ */
+export interface GetCommissionPlanResponse {
+    active: CommissionPlanSnapshot | null;
+    draft: CommissionPlanSnapshot | null;
+}
+/** `GET /backoffice/commissions/plan/snapshots` — solo cabeceras, sin el contenido del plan. */
+export interface CommissionPlanSnapshotSummary {
+    snapshotId: string;
+    status: CommissionPlanStatusEnum;
+    effectiveFrom: string;
+    publishedBy: string | null;
+    publishedAt: string | null;
+    changeNote: string | null;
+    /**
+     * Calculado contra el puntero `ACTIVE`, **nunca desde `status`**.
+     *
+     * Son dos registros del mismo hecho: `status` son N ítems y el puntero es uno solo. Si alguna vez
+     * se desincronizan, el puntero es el que no puede mentir. `status` viaja igual para que la
+     * discrepancia se VEA en la respuesta en vez de quedar escondida.
+     */
+    active: boolean;
+}
+export interface ListPlanSnapshotsResponse {
+    snapshots: CommissionPlanSnapshotSummary[];
+    nextCursor: string | null;
+}
+/** `GET /backoffice/commissions/plan/snapshots/{snapshotId}` — el plan completo de una versión vieja. */
+export interface GetPlanSnapshotResponse {
+    snapshot: CommissionPlanSnapshot;
+}
+/**
+ * `PUT /backoffice/commissions/plan/draft`
+ *
+ * Se manda el documento COMPLETO, no el pedazo editado: `sk = DRAFT` es un ítem único y un `put`
+ * entero es una escritura atómica, sin merge del lado del servidor. Los 7 modales de la pantalla
+ * pegan a este mismo endpoint.
+ */
+export interface UpdatePlanDraftRequest {
+    /**
+     * El `updatedAt` que el editor tenía al cargar. Control de concurrencia optimista.
+     *
+     * Sin él, dos admins editando a la vez terminan en last-write-wins silencioso: el segundo pisa
+     * al primero, y el primero se entera cuando ve que su excepción desapareció. `null` solo cuando
+     * todavía no existe borrador.
+     */
+    expectedUpdatedAt: string | null;
+    categories: CommissionCategory[];
+    quotas: CommissionQuota[];
+    addOns: CommissionAddOn[];
+    storeOverrideBps: Record<string, number>;
+    effectiveFrom: string;
+}
+export interface UpdatePlanDraftResponse {
+    draft: CommissionPlanSnapshot;
+    updatedAt: string;
+}
+/**
+ * `POST /backoffice/commissions/plan/publish`
+ *
+ * El `changeNote` se pide ACÁ y no al guardar: la nota describe qué cambió **en esta versión**, y eso
+ * solo se sabe al sellarla. Pedirla en cada guardado sería pedirle al admin que justifique cada click.
+ */
+export interface PublishPlanRequest {
+    changeNote: string;
+    /** El `snapshotId` que el editor cree vigente. `null` en la PRIMERA publicación de la cadena. */
+    expectedActiveSnapshotId: string | null;
+}
+export interface PublishPlanResponse {
+    snapshotId: string;
+    publishedAt: string;
+}
+/**
+ * `POST /backoffice/commissions/plan/simulate`
+ *
+ * Contra un periodo real YA CERRADO. Un corte en curso daría un número que cambia con cada venta y
+ * que el Admin leería como predicción.
+ */
+export interface SimulatePlanRequest {
+    periodId: string;
+}
+export interface SimulatePlanSellerResult {
+    sellerId: string;
+    wouldPayCents: number;
+    currentPlanCents: number;
+    deltaCents: number;
+}
+export interface SimulatePlanResponse {
+    periodId: string;
+    totalCents: number;
+    /**
+     * 🔑 **El número que importa.** Un total de $184 000 no dice nada solo; «$12 400 más que el plan
+     * vigente» es una decisión.
+     */
+    vsCurrentPlanCents: number;
+    salesEvaluated: number;
+    /**
+     * `true` si el periodo tenía más ventas que el tope del data lake (10 000 filas).
+     *
+     * Un total de dinero calculado sobre filas truncadas **sin decirlo** es peor que un error: se ve
+     * exacto y no lo es.
+     */
+    truncated: boolean;
+    bySeller: SimulatePlanSellerResult[];
+}
+/** `GET /backoffice/commissions/payouts` */
+export interface ListPayoutsResponse {
+    payouts: CommissionPayout[];
+    nextCursor: string | null;
+}
+/** `GET /backoffice/commissions/payouts/{periodId}` — una sola Query trae las tres cosas. */
+export interface GetPayoutResponse {
+    payout: CommissionPayout;
+    sellers: CommissionPayoutSeller[];
+    adjustments: CommissionAdjustment[];
+}
+/** `GET /backoffice/commissions/payouts/{periodId}/sellers/{sellerId}` */
+export interface GetPayoutSellerResponse {
+    seller: CommissionPayoutSeller;
+    accruals: CommissionAccrual[];
+}
+/**
+ * `POST /backoffice/commissions/payouts/{periodId}/adjustments`
+ *
+ * La única escritura de dinero sin una venta detrás. Va con header `Idempotency-Key`.
+ */
+export interface CreateAdjustmentRequest {
+    sellerId: string;
+    /** Puede ser negativo. */
+    amountCents: number;
+    /** Obligatorio: un movimiento de dinero sin motivo no se puede auditar. */
+    reason: string;
+    saleId: string | null;
+    date: string;
+}
+export interface CreateAdjustmentResponse {
+    adjustment: CommissionAdjustment;
+}
+/**
+ * `POST /backoffice/commissions/payouts/{periodId}/close`
+ *
+ * Responde **202**, no 200: con 200 vendedores y 3 000 devengos el trabajo son ~200 Queries más ~120
+ * BatchWrites, y API Gateway corta a los 29 segundos. No es una preferencia de diseño: no cabe.
+ */
+export interface ClosePayoutResponse {
+    periodId: string;
+    status: CommissionPayoutStatusEnum;
+    startedAt: string;
+}
+/** Lo que el simulador reconstruye desde el data lake para volver a correr el motor. */
+export type CommissionSimulationSale = CommissionSaleInput;

package/bin/retailCommission/dtos/CommissionApi.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailCommission/dtos/CommissionCalcTrace.d.ts

@@ -0,0 +1,73 @@
+import type { CommissionCalcStepEnum } from '../enums/CommissionCalcStepEnum';
+import type { CommissionExceptionTypeEnum } from '../enums/CommissionExceptionTypeEnum';
+/**
+ * La traza de cálculo: el paso a paso de por qué un vendedor cobró ese monto.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * 🔴 **Es una unión CERRADA por `step`, no un mapa abierto.** Cada variante declara exactamente qué
+ * campos lleva su `detail`, y ninguno es libre.
+ *
+ * La razón es de PII: la traza se persiste junto al devengo y viaja a la pantalla de desglose, así
+ * que es el vehículo más probable de fuga de datos del comprador. **Sin campos libres no hay dónde
+ * meterlos.** Tipar el `detail` como `Record<string, unknown>` sería llamarlo whitelist sin
+ * implementarla — un control afirmado y no aplicado es peor que uno ausente.
+ *
+ * Sin traza no se puede explicar un monto, y explicar un monto es exactamente lo que hace falta
+ * cuando alguien reclama su comisión.
+ */
+export type CommissionCalcTraceEntry = {
+    step: CommissionCalcStepEnum.MECHANIC;
+    label: string;
+    outputCents: number;
+    detail: {
+        categoryId: string;
+        mechanicType: string;
+    };
+} | {
+    step: CommissionCalcStepEnum.EXCEPTION;
+    label: string;
+    outputCents: number;
+    detail: {
+        exceptionId: string;
+        matchedOn: CommissionExceptionTypeEnum;
+    };
+} | {
+    step: CommissionCalcStepEnum.ADDON;
+    label: string;
+    outputCents: number;
+    detail: {
+        addOnId: string;
+    };
+} | {
+    step: CommissionCalcStepEnum.QUOTA;
+    label: string;
+    inputCents: number;
+    outputCents: number;
+    detail: {
+        quotaId: string;
+        met: boolean;
+        factorBps: number;
+    };
+} | {
+    step: CommissionCalcStepEnum.ADJUSTMENT;
+    label: string;
+    outputCents: number;
+    detail: {
+        adjustmentId: string;
+    };
+} | {
+    /**
+     * El SKU no matcheó ninguna categoría del plan.
+     *
+     * Devenga 0 y queda VISIBLE en el corte, en vez de mandarse a la DLQ. Un mensaje en la DLQ
+     * no lo mira nadie hasta que hay un reclamo; una fila en 0 la ve quien revisa el corte.
+     */
+    step: CommissionCalcStepEnum.NO_CATEGORY;
+    label: string;
+    outputCents: number;
+    detail: {
+        sku: string;
+        brand: string | null;
+    };
+};
+export type CommissionCalcTrace = CommissionCalcTraceEntry[];

package/bin/retailCommission/dtos/CommissionCalcTrace.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailCommission/dtos/CommissionPayout.d.ts

@@ -0,0 +1,73 @@
+import type { CommissionPayoutStatusEnum } from '../enums/CommissionPayoutStatusEnum';
+/**
+ * El corte semanal y todo lo que cuelga de él.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Los tres tipos de ítem viven en la misma partición del retailer y se separan por el sort key
+ * (`…#META`, `…#ADJ#<id>`, `…#SELLER#<id>`), así que **una sola Query trae el corte completo**:
+ * totales, ajustes y roster.
+ *
+ * El sufijo `#META` no es decorativo: sin él, un `between` por rango de semanas arrastraría también
+ * los ajustes y el roster de cada corte y rompería la paginación.
+ */
+export interface CommissionPayout {
+    retailerId: string;
+    periodId: string;
+    periodStart: string;
+    periodEnd: string;
+    status: CommissionPayoutStatusEnum;
+    /** Suma de los devengos liquidados. Se sella al cerrar. */
+    grossCents: number | null;
+    /** Suma de los ajustes manuales, con signo. */
+    adjustmentsCents: number | null;
+    netCents: number | null;
+    sellerCount: number | null;
+    accrualCount: number | null;
+    closedBy: string | null;
+    closedAt: string | null;
+}
+/**
+ * El roster: un ítem por vendedor con devengos en el corte, escrito AL DEVENGAR.
+ *
+ * 🔑 **Es lo que hace el cierre autocontenido.** El fan-out itera este roster, no la lista que
+ * devuelva `retail-org-business`. Un vendedor dado de baja, transferido o creado a mitad de semana
+ * sigue acá — si el fan-out saliera del padrón, sus devengos nunca pasarían a `PAID`, nunca entrarían
+ * al total, y nadie se enteraría.
+ *
+ * Los dos contadores se acumulan con `ADD` al devengar. Son lo que permite pintar el desglose de un
+ * corte ABIERTO sin barrer todos los devengos en cada carga de pantalla.
+ */
+export interface CommissionPayoutSeller {
+    retailerId: string;
+    periodId: string;
+    sellerId: string;
+    accruedCount: number;
+    baseAmountCents: number;
+    /** Al cerrar: lo que efectivamente se le liquidó. */
+    settledAmountCents: number | null;
+    /** Al cerrar: si alcanzó su cuota. */
+    quotaMet: boolean | null;
+    quotaFactorBps: number | null;
+}
+/**
+ * Un ajuste manual sobre el corte.
+ *
+ * Es la **única escritura de dinero sin una venta que la respalde**, y por eso es la única operación
+ * del motor con guard de idempotencia. El devengo no lo necesita: su clave es determinista.
+ */
+export interface CommissionAdjustment {
+    retailerId: string;
+    periodId: string;
+    adjustmentId: string;
+    sellerId: string;
+    date: string;
+    /** El ticket al que se refiere, si aplica. */
+    saleId: string | null;
+    /** **Puede ser negativo.** Una reversa de un corte ya cerrado entra como ajuste negativo. */
+    amountCents: number;
+    /** Obligatorio. Un movimiento de dinero sin motivo no se puede auditar. */
+    reason: string;
+    /** Email de quien lo hizo, o `system` en los automáticos por cancelación. */
+    author: string;
+    createdAt: string;
+}

package/bin/retailCommission/dtos/CommissionPayout.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });