@fiado/type-kit 3.490.0 → 3.492.0

package/_test_/unit/retailWizard/ventaSagaMessages.test.ts

@@ -2,12 +2,16 @@ import 'reflect-metadata';
 import { plainToInstance, type ClassConstructor } from 'class-transformer';
 import { validateSync, type ValidationError } from 'class-validator';
 import {
+  ExternalProviderEnum,
+  LinePaymentTypeEnum,
   RetailCommissionInboundMessage,
+  RetailCommissionInboundMessageTypeEnum,
   RetailPromotionInboundMessage,
   RetailPromotionInboundMessageTypeEnum,
+  SaleTypeEnum,
   WizardLineRoleEnum,
 } from '../../../src/retailWizard';
-import { ItemTypeEnum } from '../../../src/retailCatalog';
+import { ItemTypeEnum, ProductCategoryEnum, ProductTierEnum } from '../../../src/retailCatalog';
 
 function paths(errors: ValidationError[], prefix = ''): string[] {
   return errors.flatMap((e) => {
@@ -133,33 +137,126 @@ describe('RetailPromotionInboundMessage', () => {
   });
 });
 
+describe('RetailCommissionInboundMessageTypeEnum', () => {
+  it('distingue venta y cancelación', () => {
+    expect(Object.values(RetailCommissionInboundMessageTypeEnum)).toEqual(['SALE_COMPLETED', 'SALE_CANCELLED']);
+  });
+});
+
 describe('RetailCommissionInboundMessage', () => {
+  const phone = {
+    lineId: 'L1',
+    sku: 'PHONE-1',
+    qty: 1,
+    netCents: 299900,
+    itemType: ItemTypeEnum.PRODUCT,
+    category: ProductCategoryEnum.PHONE,
+    tier: ProductTierEnum.HIGH,
+    brand: 'Samsung',
+    paymentType: LinePaymentTypeEnum.CREDIT,
+  };
+  const service = {
+    lineId: 'L2',
+    sku: 'SVC-1',
+    qty: 1,
+    netCents: 9900,
+    itemType: ItemTypeEnum.SERVICE,
+    category: null,
+    tier: null,
+    brand: null,
+    paymentType: LinePaymentTypeEnum.CASH,
+  };
+  const gift = {
+    ...service,
+    lineId: 'L3',
+    sku: 'CASE-1',
+    netCents: 0,
+    itemType: ItemTypeEnum.PRODUCT,
+    category: ProductCategoryEnum.ACCESSORY,
+    role: WizardLineRoleEnum.GIFT,
+  };
   const ok = {
+    type: RetailCommissionInboundMessageTypeEnum.SALE_COMPLETED,
     tenantId: 't',
     retailerId: 'ret',
     storeId: 'st',
     saleId: 'sale-1',
     sessionId: 'ses-1',
+    sellerRetailUserId: 'seller-1',
+    saleType: SaleTypeEnum.CREDIT,
+    externalProvider: null,
+    creditId: 'cred-1',
     soldAt: '2026-09-28T20:00:00.000Z',
-    lines: [
-      { sku: 'PHONE-1', qty: 1, netCents: 299900, itemType: ItemTypeEnum.PRODUCT },
-      { sku: 'SVC-1', qty: 1, netCents: 9900, itemType: ItemTypeEnum.SERVICE },
-    ],
+    occurredAt: '2026-09-28T20:00:00.000Z',
+    lines: [phone, service, gift],
   };
 
-  it('acepta la venta con sus líneas', () => expect(errorsOf(RetailCommissionInboundMessage, ok)).toEqual([]));
+  it('acepta la venta a crédito con sus líneas', () => expect(errorsOf(RetailCommissionInboundMessage, ok)).toEqual([]));
 
-  it('exige la identidad de la venta', () => {
-    const { saleId: _s, soldAt: _so, ...rest } = ok;
-    expect(errorsOf(RetailCommissionInboundMessage, rest)).toEqual(expect.arrayContaining(['saleId', 'soldAt']));
+  it('acepta una derivada a financiera externa sin crédito', () =>
+    expect(
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        saleType: SaleTypeEnum.EXTERNAL_REFERRAL,
+        externalProvider: ExternalProviderEnum.PAYJOY,
+        creditId: null,
+      }),
+    ).toEqual([]));
+
+  it('acepta una cancelación con su motivo', () =>
+    expect(
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        type: RetailCommissionInboundMessageTypeEnum.SALE_CANCELLED,
+        occurredAt: '2026-09-29T15:00:00.000Z',
+        cancelReason: 'el cliente se arrepintió',
+      }),
+    ).toEqual([]));
+
+  it('la cancelación sin motivo también vale', () => {
+    const cancelled = { ...ok, type: RetailCommissionInboundMessageTypeEnum.SALE_CANCELLED };
+    expect(errorsOf(RetailCommissionInboundMessage, cancelled)).toEqual([]);
+    expect(errorsOf(RetailCommissionInboundMessage, { ...cancelled, cancelReason: '' })).toEqual([]);
+  });
+
+  it('exige el tipo de mensaje, el vendedor, el tipo de venta y la identidad', () => {
+    const { type: _t, sellerRetailUserId: _s, saleType: _st, saleId: _id, soldAt: _so, occurredAt: _o, ...rest } = ok;
+    expect(errorsOf(RetailCommissionInboundMessage, rest)).toEqual(
+      expect.arrayContaining(['type', 'sellerRetailUserId', 'saleType', 'saleId', 'soldAt', 'occurredAt']),
+    );
   });
 
   it('rechaza sin líneas', () => expect(errorsOf(RetailCommissionInboundMessage, { ...ok, lines: [] })).toContain('lines'));
 
   it('valida cada línea', () =>
     expect(
-      errorsOf(RetailCommissionInboundMessage, { ...ok, lines: [{ sku: 'X', qty: 0, netCents: -1, itemType: 'KIT' }] }),
-    ).toEqual(expect.arrayContaining(['lines.0.qty', 'lines.0.netCents', 'lines.0.itemType'])));
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        lines: [
+          {
+            lineId: '',
+            sku: 'X',
+            qty: 0,
+            netCents: -1,
+            itemType: 'KIT',
+            category: 'CELULAR',
+            tier: 'ORO',
+            brand: null,
+            paymentType: 'TARJETA',
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'lines.0.lineId',
+        'lines.0.qty',
+        'lines.0.netCents',
+        'lines.0.itemType',
+        'lines.0.category',
+        'lines.0.tier',
+        'lines.0.paymentType',
+      ]),
+    ));
 });
 
 describe('RetailPromotionInboundMessage — tipos nullables y ids no vacíos', () => {

package/bin/loanCredit/dtos/InstallmentPaidEvent.d.ts

@@ -0,0 +1,18 @@
+import type { LoanInstallmentStatusEnum } from '../enums/LoanInstallmentStatusEnum';
+/** `eventType` del outbox cuando una cuota queda pagada. */
+export declare const INSTALLMENT_PAID_EVENT_TYPE = "InstallmentPaidV1";
+/**
+ * Payload de `InstallmentPaidV1`: una cuota que pasó a `PAID` o `PAID_IN_ADVANCE` por cualquier
+ * camino (cargo de la cuota, revisión, adelanto, liquidación o recuperación). Se escribe al outbox en
+ * la misma transacción que la cuota. Sin PII.
+ */
+export interface InstallmentPaidV1Payload {
+    creditId: string;
+    installmentNumber: number;
+    /** Lo pagado de la cuota en total (capital + interés + IVA), en centavos. */
+    paidCents: number;
+    /** Instante del pago (ISO): decide el corte de la renta. */
+    paidAt: string;
+    installmentStatus: LoanInstallmentStatusEnum;
+    paymentId: string;
+}

package/bin/loanCredit/dtos/InstallmentPaidEvent.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALLMENT_PAID_EVENT_TYPE = void 0;
+/** `eventType` del outbox cuando una cuota queda pagada. */
+exports.INSTALLMENT_PAID_EVENT_TYPE = 'InstallmentPaidV1';

package/bin/loanCredit/dtos/requests/CreateCustomerPaymentRequest.d.ts

@@ -2,8 +2,10 @@ import { LoanCustomerPaymentTypeEnum } from '../../enums/LoanCustomerPaymentType
 /** Body de `POST /private/customers/:directoryId/credits/:creditId/payments` (loan-credit-business). */
 export declare class CreateCustomerPaymentRequest {
     type: LoanCustomerPaymentTypeEnum;
-    /** Monto que vio el cliente; si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
+    /** Monto que vio el cliente (en PREPAYMENT, el que eligió); si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
     expectedAmountCents: number;
     /** Llave del reintento: la misma llave con el mismo cuerpo devuelve la misma respuesta. */
     idempotencyKey: string;
+    /** Solo ADVANCE: cuántas cuotas adelanta. */
+    installmentCount?: number;
 }

package/bin/loanCredit/dtos/requests/CreateCustomerPaymentRequest.js

@@ -33,3 +33,10 @@ __decorate([
     (0, class_validator_1.IsUUID)(),
     __metadata("design:type", String)
 ], CreateCustomerPaymentRequest.prototype, "idempotencyKey", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(2),
+    __metadata("design:type", Number)
+], CreateCustomerPaymentRequest.prototype, "installmentCount", void 0);

package/bin/loanCredit/dtos/responses/LoanCustomerPaymentOptions.d.ts

@@ -8,6 +8,13 @@ export interface LoanCustomerPaymentOption {
     unavailableReason?: LoanPaymentOptionUnavailableReasonEnum;
     amountCents?: number;
 }
+/** Una cuota que se puede adelantar. */
+export interface LoanCustomerAdvanceInstallment {
+    installmentNumber: number;
+    /** `YYYY-MM-DD`. */
+    dueDate: string;
+    amountCents: number;
+}
 /** Response de `GET /private/customers/:directoryId/credits/:creditId/payment-options`. Montos en cents. */
 export interface LoanCustomerPaymentOptions {
     creditId: string;
@@ -15,6 +22,8 @@ export interface LoanCustomerPaymentOptions {
     pendingCharge?: {
         kind: LoanAdHocChargeKindEnum;
         amountCents: number;
+        /** Solo en un adelanto: las cuotas que cubre. */
+        installmentNumbers?: number[];
     };
     nextInstallment: LoanCustomerPaymentOption & {
         mode?: LoanNextInstallmentModeEnum;
@@ -22,8 +31,18 @@ export interface LoanCustomerPaymentOptions {
         /** `YYYY-MM-DD`. */
         dueDate?: string;
     };
-    /** Varias cuotas: hoy siempre `available: false` con `NOT_AVAILABLE_YET`. */
-    advance: LoanCustomerPaymentOption;
+    /** Varias cuotas. `installments` trae las `maxInstallments` que se pueden adelantar, en orden. */
+    advance: LoanCustomerPaymentOption & {
+        minInstallments?: number;
+        maxInstallments?: number;
+        installments?: LoanCustomerAdvanceInstallment[];
+    };
+    /** Abono a capital: monto libre entre `minAmountCents` y `maxAmountCents`. */
+    prepayment: LoanCustomerPaymentOption & {
+        minAmountCents?: number;
+        maxAmountCents?: number;
+        outstandingCapitalCents?: number;
+    };
     settlement: LoanCustomerPaymentOption & {
         /** La cotización de hoy; su `settlementAmountCents` es el `amountCents`. */
         quote?: LoanSettlementQuote;

package/bin/loanCredit/dtos/responses/LoanCustomerPaymentResult.d.ts

@@ -11,4 +11,6 @@ export interface LoanCustomerPaymentResult {
         status: CollectionResultStatus;
         amountCollectedCents: number;
     };
+    /** Solo ADVANCE: cuántas cuotas cubre. */
+    installmentCount?: number;
 }

package/bin/loanCredit/enums/LoanCustomerPaymentTypeEnum.d.ts

@@ -1,5 +1,9 @@
 /** Pago que el cliente puede pedir desde la app. */
 export declare enum LoanCustomerPaymentTypeEnum {
     NEXT_INSTALLMENT = "NEXT_INSTALLMENT",
-    SETTLEMENT = "SETTLEMENT"
+    SETTLEMENT = "SETTLEMENT",
+    /** Varias cuotas: las siguientes N tal como están, sin cambiar la tabla. */
+    ADVANCE = "ADVANCE",
+    /** Abono a capital: va completo a capital y baja las cuotas siguientes. */
+    PREPAYMENT = "PREPAYMENT"
 }

package/bin/loanCredit/enums/LoanCustomerPaymentTypeEnum.js

@@ -6,4 +6,8 @@ var LoanCustomerPaymentTypeEnum;
 (function (LoanCustomerPaymentTypeEnum) {
     LoanCustomerPaymentTypeEnum["NEXT_INSTALLMENT"] = "NEXT_INSTALLMENT";
     LoanCustomerPaymentTypeEnum["SETTLEMENT"] = "SETTLEMENT";
+    /** Varias cuotas: las siguientes N tal como están, sin cambiar la tabla. */
+    LoanCustomerPaymentTypeEnum["ADVANCE"] = "ADVANCE";
+    /** Abono a capital: va completo a capital y baja las cuotas siguientes. */
+    LoanCustomerPaymentTypeEnum["PREPAYMENT"] = "PREPAYMENT";
 })(LoanCustomerPaymentTypeEnum || (exports.LoanCustomerPaymentTypeEnum = LoanCustomerPaymentTypeEnum = {}));

package/bin/loanCredit/index.d.ts

@@ -6,6 +6,7 @@ export * from './dtos/LoanBorrower';
 export * from './dtos/LoanBeneficiary';
 export * from './dtos/LoanCredit';
 export * from './dtos/LoanInstallment';
+export * from './dtos/InstallmentPaidEvent';
 export * from './dtos/LoanContract';
 export * from './dtos/ActivationChecklist';
 export * from './dtos/AppliedPromotionSnapshot';

package/bin/loanCredit/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./dtos/LoanBorrower"), exports);
 __exportStar(require("./dtos/LoanBeneficiary"), exports);
 __exportStar(require("./dtos/LoanCredit"), exports);
 __exportStar(require("./dtos/LoanInstallment"), exports);
+__exportStar(require("./dtos/InstallmentPaidEvent"), exports);
 __exportStar(require("./dtos/LoanContract"), exports);
 __exportStar(require("./dtos/ActivationChecklist"), exports);
 __exportStar(require("./dtos/AppliedPromotionSnapshot"), exports);

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

@@ -2,6 +2,11 @@ import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStat
 import type { CommissionPayeeTypeEnum } from '../enums/CommissionPayeeTypeEnum';
 import type { SaleFinancierEnum } from '../../retailWizard/enums/SaleFinancierEnum';
 import type { CommissionCalcTrace } from './CommissionCalcTrace';
+import type { CommissionBonusModeEnum } from '../enums/CommissionBonusModeEnum';
+import type { ProductCategoryEnum } from '../../retailCatalog/enums/ProductCategoryEnum';
+import type { ProductTierEnum } from '../../retailCatalog/enums/ProductTierEnum';
+import type { LinePaymentTypeEnum } from '../../retailWizard/enums/LinePaymentTypeEnum';
+import type { WizardLineRoleEnum } from '../../retailWizard/enums/WizardLineRoleEnum';
 /**
  * El devengo: lo que se le debe a un vendedor por UNA venta.
  * SureKeep Fase 3 — pista Retail.
@@ -50,6 +55,10 @@ export interface CommissionAccrual {
     payoutId: string | null;
     reversalReason: string | null;
     calcTrace: CommissionCalcTrace;
+    /** Los bonos por venta que sumaron, uno por regla y por pieza. Solo en devengos calculados con reglas. */
+    appliedBonuses?: CommissionAppliedBonus[];
+    /** Suma de `appliedBonuses`. Solo en devengos calculados con reglas. */
+    subtotalBonusCents?: number;
 }
 /**
  * Lo mínimo de una venta para devengarla. Es lo que llega por la cola y lo que se reconstruye
@@ -75,4 +84,31 @@ export interface CommissionSaleInput {
     /** `CASH` | `CREDIT`, para `PERCENT_BY_PAYMENT`. */
     paymentType: string;
     soldAt: string;
+    /** Las líneas de la venta. Las ventas que se calculan con reglas siempre las traen. */
+    lines?: CommissionSaleLine[];
+}
+/** Una línea de la venta, congelada en el devengo. */
+export interface CommissionSaleLine {
+    lineId: string;
+    sku: string;
+    qty: number;
+    /** Precio neto de la línea completa (todas sus piezas). */
+    netCents: number;
+    category: ProductCategoryEnum | null;
+    tier: ProductTierEnum | null;
+    brand: string | null;
+    paymentType: LinePaymentTypeEnum;
+    /** `GIFT` = regalo: no comisiona ni cuenta en la posición. */
+    role?: WizardLineRoleEnum;
+}
+/** Un bono por venta que sumó en el devengo. */
+export interface CommissionAppliedBonus {
+    ruleId: string;
+    name: string;
+    lineId: string;
+    sku: string;
+    /** Posición de la pieza en el contador de la regla dentro del periodo. */
+    position: number;
+    mode: CommissionBonusModeEnum;
+    amountCents: number;
 }

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

@@ -1,8 +1,16 @@
 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';
+import type { CommissionAccrual, CommissionAppliedBonus, CommissionSaleInput, CommissionSaleLine } from './CommissionAccrual';
+import type { CommissionAdjustment, CommissionAppliedMultiplier, CommissionAppliedThreshold, CommissionPayout, CommissionPayoutSeller, CommissionSellerBreakdown } from './CommissionPayout';
+import type { CommissionPolicies, CommissionRule, CommissionRuleCondition, CommissionRuleLevers, CommissionRuleScope, CommissionRuleSetSnapshot } from './CommissionRule';
+import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
+import type { CommissionAggregateByEnum } from '../enums/CommissionAggregateByEnum';
+import type { CommissionSeriesByEnum } from '../enums/CommissionSeriesByEnum';
+import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStatusEnum';
+import type { CommissionSimulationSkipEnum } from '../enums/CommissionSimulationSkipEnum';
+import type { ProductCategoryEnum } from '../../retailCatalog/enums/ProductCategoryEnum';
+import type { ProductTierEnum } from '../../retailCatalog/enums/ProductTierEnum';
 /**
  * Los contratos HTTP del motor de comisiones — uno por endpoint, sin reutilizar.
  * SureKeep Fase 3 — pista Retail.
@@ -167,3 +175,234 @@ export interface ClosePayoutResponse {
 }
 /** Lo que el simulador reconstruye desde el data lake para volver a correr el motor. */
 export type CommissionSimulationSale = CommissionSaleInput;
+/** `GET /backoffice/commissions/plan` — el plan vigente con reglas. `null` mientras no se publica nada. */
+export interface GetRuleSetResponse {
+    active: CommissionRuleSetSnapshot | null;
+}
+/** `GET /backoffice/commissions/rules` — la última versión de cada regla. */
+export interface ListRulesResponse {
+    rules: CommissionRule[];
+}
+/** Lo que el editor manda al crear o guardar una regla. */
+export interface CommissionRuleInput {
+    name: string;
+    description: string | null;
+    levers: CommissionRuleLevers;
+    scope: CommissionRuleScope;
+    condition: CommissionRuleCondition | null;
+    effectiveFrom: string;
+    effectiveTo: string | null;
+    priority: number;
+    replacesOthers: boolean;
+}
+/** `POST /backoffice/commissions/rules` — la regla nace en borrador. */
+export type CreateRuleRequest = CommissionRuleInput;
+/** `PUT /backoffice/commissions/rules/{ruleId}` — `expectedVersion` es la versión que el editor cargó. */
+export interface UpdateRuleRequest extends CommissionRuleInput {
+    expectedVersion: number;
+}
+export interface RuleResponse {
+    rule: CommissionRule;
+}
+/** `POST /backoffice/commissions/rules/{ruleId}/publish | pause | resume | expire` */
+export interface RuleActionRequest {
+    expectedVersion: number;
+}
+/** Las acciones que cambian el plan vigente devuelven la regla y el snapshot nuevo. */
+export interface RuleActionResponse {
+    rule: CommissionRule;
+    snapshotId: string;
+}
+/** Un evento del historial de una regla. */
+export interface CommissionRuleEvent {
+    at: string;
+    action: string;
+    performedBy: string;
+    version: number | null;
+}
+/** `GET /backoffice/commissions/rules/{ruleId}/history` — del más nuevo al más viejo. */
+export interface RuleHistoryResponse {
+    events: CommissionRuleEvent[];
+}
+/** `GET /backoffice/commissions/policies` */
+export interface GetPoliciesResponse {
+    policies: CommissionPolicies;
+}
+/** `PUT /backoffice/commissions/policies` — las dos políticas se guardan juntas. */
+export interface UpdatePoliciesRequest {
+    clawback: {
+        cancelacionDias: number;
+        devolucionDias: number;
+        npiM30Dias: number;
+    };
+    commissions: {
+        multiplicadorMaxBps: number;
+        ventanaDefault: CommissionWindowEnum;
+    };
+}
+export interface UpdatePoliciesResponse {
+    policies: CommissionPolicies;
+    snapshotId: string;
+}
+/** `GET /backoffice/commissions/live?periodId=` — el corte calculado al momento, sin escribir nada. */
+export interface GetLivePayoutResponse {
+    periodId: string;
+    periodStart: string;
+    periodEnd: string;
+    status: CommissionPayoutStatusEnum;
+    sellers: CommissionSellerBreakdown[];
+}
+/** Una venta del vendedor en el corte, con sus bonos recalculados en orden. Sin datos del cliente. */
+export interface CommissionLiveSale {
+    saleId: string;
+    soldAt: string;
+    storeId: string;
+    status: CommissionAccrualStatusEnum;
+    /** El snapshot con el que se devengó: es el que se usa para recalcularla. */
+    planSnapshotId: string;
+    lines: CommissionSaleLine[];
+    appliedBonuses: CommissionAppliedBonus[];
+    subtotalBonusCents: number;
+}
+/** `GET /backoffice/commissions/live/sellers/{sellerId}?periodId=` */
+export interface GetLiveSellerResponse {
+    periodId: string;
+    seller: CommissionSellerBreakdown;
+    sales: CommissionLiveSale[];
+}
+/** Un renglón del agregado. `name` es el de la regla; tienda, SKU y vendedor los resuelve el front. */
+export interface CommissionAggregateRow {
+    key: string;
+    name: string | null;
+    sellersCount: number;
+    salesCount: number;
+    unitsCount: number;
+    placementCents: number;
+    paidCents: number;
+}
+/** `GET /backoffice/commissions/payouts/aggregates?by=&from=&to=` — sobre los cortes cerrados del rango. */
+export interface GetPayoutAggregatesResponse {
+    by: CommissionAggregateByEnum;
+    from: string;
+    to: string;
+    /** Los cortes cerrados que entraron. */
+    periodIds: string[];
+    rows: CommissionAggregateRow[];
+    totalPaidCents: number;
+}
+/** Un punto de la serie: un corte cerrado. */
+export interface CommissionSeriesPoint {
+    periodId: string;
+    salesCount: number;
+    unitsCount: number;
+    placementCents: number;
+    paidCents: number;
+}
+/** `GET /backoffice/commissions/payouts/series?by=&id=&weeks=` — del corte más viejo al más nuevo. */
+export interface GetPayoutSeriesResponse {
+    by: CommissionSeriesByEnum;
+    id: string;
+    points: CommissionSeriesPoint[];
+}
+/** El vendedor modelo: cómo va su semana. */
+export interface CommissionSimulationProfile {
+    unitsInWeek: number;
+    placementCents: number;
+    distinctSkus: number;
+}
+/** El producto que vende en la simulación. */
+export interface CommissionSimulationProduct {
+    sku: string;
+    category: ProductCategoryEnum | null;
+    tier: ProductTierEnum | null;
+    netCents: number;
+}
+/** `POST /backoffice/commissions/rules/simulate` */
+export interface SimulateRulesRequest {
+    /** Reglas por id, en su última versión, como si estuvieran publicadas. Vacío = el plan vigente. */
+    ruleIds: string[];
+    profile: CommissionSimulationProfile;
+    product: CommissionSimulationProduct;
+    /** Con tienda se evalúa el alcance por tienda; sin ella, se ignora. */
+    storeId: string | null;
+    /** `YYYY-MM-DD`. `null` = hoy. */
+    date: string | null;
+}
+/** Lo que una regla de bono por venta pagaría en una posición, o por qué no. */
+export interface CommissionSimulatedRule {
+    ruleId: string;
+    name: string;
+    amountCents: number;
+    skipped: CommissionSimulationSkipEnum | null;
+}
+export interface SimulateRulesResponse {
+    date: string;
+    /** La venta siguiente, en la posición `unitsInWeek + 1`. */
+    nextSale: {
+        position: number;
+        subtotalBonusCents: number;
+        rules: CommissionSimulatedRule[];
+    };
+    /** Las piezas de la semana, en las posiciones 1 a `unitsInWeek`. */
+    progression: Array<{
+        position: number;
+        subtotalBonusCents: number;
+        cumulativeBonusCents: number;
+    }>;
+    /** El corte de esa semana. */
+    week: {
+        subtotalBonusCents: number;
+        multiplierBps: number;
+        multiplierBeforeCapBps: number;
+        multipliers: CommissionAppliedMultiplier[];
+        thresholdBonusCents: number;
+        thresholds: CommissionAppliedThreshold[];
+        releasedCents: number;
+    };
+}
+/** Una regla como la ve el vendedor: sin estado interno ni datos de auditoría. */
+export interface CommissionRuleView {
+    ruleId: string;
+    name: string;
+    description: string | null;
+    levers: CommissionRuleLevers;
+    scope: CommissionRuleScope;
+    condition: CommissionRuleCondition | null;
+    effectiveFrom: string;
+    effectiveTo: string | null;
+}
+/** Lo pagado en varios cortes. */
+export interface MyCommissionsTotals {
+    periodsCount: number;
+    salesCount: number;
+    unitsCount: number;
+    netCents: number;
+}
+/**
+ * `GET /commissions/me?weeks=` — las comisiones del vendedor que llama. El vendedor sale del token;
+ * no se puede pedir el de otro.
+ */
+export interface GetMyCommissionsResponse {
+    seller: {
+        sellerId: string;
+        name: string | null;
+        storeId: string | null;
+    };
+    period: {
+        periodId: string;
+        periodStart: string;
+        periodEnd: string;
+    };
+    /** El corte en curso; `null` si todavía no tiene ventas, renta ni ajustes. */
+    week: CommissionSellerBreakdown | null;
+    /** Cortes cuya semana empieza en el mes de hoy: cerrados, el anterior aún sin cerrar y el en curso. */
+    month: MyCommissionsTotals;
+    /** Cortes cuya semana empieza en el año de hoy: cerrados, el anterior aún sin cerrar y el en curso. */
+    year: MyCommissionsTotals;
+    /** Los cortes cerrados de las últimas `weeks` semanas, del más viejo al más nuevo. `paidCents` es el neto. */
+    history: CommissionSeriesPoint[];
+    /** Las reglas vigentes hoy que pueden pagarle: las de corte, las sin tienda y las de su tienda o de donde vendió. */
+    rules: CommissionRuleView[];
+    /** Tope del multiplicador de la política; `null` sin política. */
+    multiplierCapBps: number | null;
+}

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

@@ -69,5 +69,15 @@ export type CommissionCalcTraceEntry = {
         sku: string;
         brand: string | null;
     };
+} | {
+    /** Una regla con bono por venta sumó por una pieza. */
+    step: CommissionCalcStepEnum.BONUS_PER_SALE;
+    label: string;
+    outputCents: number;
+    detail: {
+        ruleId: string;
+        lineId: string;
+        position: number;
+    };
 };
 export type CommissionCalcTrace = CommissionCalcTraceEntry[];

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

@@ -0,0 +1,31 @@
+import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStatusEnum';
+import type { CommissionBonusModeEnum } from '../enums/CommissionBonusModeEnum';
+/** Lo que paga una regla de renta de cartera por una cuota cobrada. */
+export interface CommissionCouponAppliedBonus {
+    ruleId: string;
+    name: string;
+    mode: CommissionBonusModeEnum;
+    amountCents: number;
+}
+/**
+ * La renta de cartera de una cuota pagada, en el corte de su pago.
+ * Clave `SELLER#<sellerId>` · `COUPON#<periodId>#<creditId>#<cuota>`: determinista, idempotente.
+ */
+export interface CommissionCouponAccrual {
+    sellerId: string;
+    retailerId: string;
+    periodId: string;
+    creditId: string;
+    /** La venta que originó el crédito. */
+    saleId: string;
+    installmentNumber: number;
+    /** Lo pagado de la cuota (capital + interés + IVA). */
+    couponAmountCents: number;
+    paidAt: string;
+    /** El snapshot con que se evaluó: de ahí salen las condiciones al cerrar el corte. */
+    planSnapshotId: string;
+    bonuses: CommissionCouponAppliedBonus[];
+    subtotalCents: number;
+    status: CommissionAccrualStatusEnum;
+    createdAt: string;
+}

package/bin/retailCommission/dtos/CommissionCouponAccrual.js

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