@fiado/type-kit 3.550.0 → 3.551.0

package/_test_/unit/retailCommission/commissionPayments.test.ts

@@ -0,0 +1,168 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+
+describe('retailCommission — enums de los pagos', () => {
+    it('expone los estados de un depósito', () => {
+        expect(Object.values(RetailCommission.CommissionPaymentStatusEnum)).toEqual([
+            'PENDING', 'ACCREDITED', 'FAILED', 'UNVERIFIED',
+        ]);
+    });
+
+    it('expone por qué un saldo necesita atención', () => {
+        expect(Object.values(RetailCommission.CommissionPaymentAttentionEnum)).toEqual(['NO_WALLET', 'REJECTED', 'PAUSED', 'DEBT']);
+    });
+
+    it('expone los tipos de movimiento del libro', () => {
+        expect(Object.values(RetailCommission.CommissionLedgerMovementKindEnum)).toEqual([
+            'EARN', 'DEDUCT', 'RELEASE', 'PAID_OUTSIDE',
+        ]);
+    });
+
+    it('expone qué pide pagarle a un vendedor', () => {
+        expect(Object.values(RetailCommission.CommissionPayTriggerEnum)).toEqual([
+            'SALE', 'CUT', 'RELEASE', 'ADJUSTMENT', 'WALLET_LINKED', 'RETRY',
+        ]);
+    });
+});
+
+// Ana después del cierre del 12 de octubre: ganó $300, le descontaron $100 de una venta cancelada,
+// se le depositaron $180 y le quedan $20 de renta retenidos hasta el 1 de noviembre.
+const balance: RetailCommission.CommissionSellerBalance = {
+    retailerId: 'RET-1',
+    sellerId: 'V-01',
+    retainedCents: 2_000,
+    payableCents: 0,
+    inTransitCents: 0,
+    earnedCents: 30_000,
+    deductedCents: 10_000,
+    accreditedCents: 18_000,
+    paidOutsideCents: 0,
+    attention: null,
+    attentionCode: null,
+    attentionSince: null,
+    updatedAt: '2026-10-12T07:00:00.000Z',
+};
+
+const cut: RetailCommission.CommissionLedgerMovement = {
+    movementKey: 'MOV#2026-10-05#CUT',
+    kind: RetailCommission.CommissionLedgerMovementKindEnum.EARN,
+    periodId: '2026-10-05',
+    retainedDeltaCents: 2_000,
+    payableDeltaCents: 8_000,
+    byRule: [
+        { ruleId: 'RC-BASE', payTiming: RetailCommission.CommissionPayTimingEnum.ON_CUT, cents: 8_000 },
+        { ruleId: 'RC-RENTA', payTiming: RetailCommission.CommissionPayTimingEnum.MONTHLY, cents: 2_000 },
+    ],
+    saleId: null,
+    adjustmentId: null,
+    releaseMonth: null,
+    reason: null,
+    createdAt: '2026-10-12T06:00:00.000Z',
+    createdBy: 'system',
+};
+
+const accredited: RetailCommission.CommissionPayment = {
+    paymentId: '01JPAY0000000000000000001',
+    retailerId: 'RET-1',
+    sellerId: 'V-01',
+    amountCents: 10_000,
+    status: RetailCommission.CommissionPaymentStatusEnum.ACCREDITED,
+    directoryId: 'DIR-1',
+    transactionId: 'TX-1',
+    errorCode: null,
+    concept: 'Comisiones VentasLuga · 5 oct 2026',
+    requestedAt: '2026-10-05T18:00:00.000Z',
+    resolvedAt: '2026-10-05T18:00:02.000Z',
+    resolvedBy: null,
+    note: null,
+};
+
+const statement: RetailCommission.CommissionChainStatement = {
+    statementId: '01JSTMT00000000000000001',
+    retailerId: 'RET-1',
+    period: RetailCommission.CommissionBillingPeriodEnum.WEEKLY,
+    startDate: '2026-10-05',
+    endDate: '2026-10-11',
+    accreditedCents: 10_000,
+    paymentsCount: 1,
+    sellersCount: 1,
+    generatedAt: '2026-10-12T07:00:00.000Z',
+};
+
+describe('retailCommission — libro de pagos', () => {
+    it('lo que queda en las tres bolsas es lo ganado menos lo descontado, lo depositado y lo pagado por fuera', () => {
+        const inPockets = balance.retainedCents + balance.payableCents + balance.inTransitCents;
+        expect(inPockets).toBe(balance.earnedCents - balance.deductedCents - balance.accreditedCents - balance.paidOutsideCents);
+    });
+
+    it('el movimiento del cierre reparte por regla entre retenido y exigible', () => {
+        const total = cut.byRule.reduce((sum, r) => sum + r.cents, 0);
+        expect(total).toBe(cut.retainedDeltaCents + cut.payableDeltaCents);
+    });
+
+    it('un depósito confirmado trae folio y uno rechazado su código', () => {
+        const failed: RetailCommission.CommissionPayment = {
+            ...accredited,
+            paymentId: '01JPAY0000000000000000002',
+            status: RetailCommission.CommissionPaymentStatusEnum.FAILED,
+            transactionId: null,
+            errorCode: 'USER_NOT_ACTIVE',
+        };
+        expect([failed.transactionId, failed.errorCode]).toEqual([null, 'USER_NOT_ACTIVE']);
+    });
+
+    it('el estado de cuenta cubre un periodo de cobro', () => {
+        expect([statement.period, statement.startDate, statement.endDate]).toEqual(['WEEKLY', '2026-10-05', '2026-10-11']);
+    });
+});
+
+describe('retailCommission — contratos de los pagos', () => {
+    it('"Por pagar" trae pendientes, depósitos sin confirmar y deudas', () => {
+        const unverified: RetailCommission.CommissionPayment = {
+            ...accredited,
+            status: RetailCommission.CommissionPaymentStatusEnum.UNVERIFIED,
+            transactionId: null,
+            resolvedAt: null,
+        };
+        const debt: RetailCommission.CommissionSellerBalance = {
+            ...balance,
+            payableCents: -5_000,
+            attention: RetailCommission.CommissionPaymentAttentionEnum.DEBT,
+            attentionSince: '2026-10-09T18:00:00.000Z',
+        };
+        const report: RetailCommission.GetPaymentAttentionResponse = { pending: [], unverified: [unverified], debts: [debt] };
+        expect([report.unverified[0]?.status, report.debts[0]?.attention]).toEqual(['UNVERIFIED', 'DEBT']);
+    });
+
+    it('pagado por fuera lleva motivo; la revisión manda folio solo si sí se depositó', () => {
+        const outside: RetailCommission.MarkPaidOutsideRequest = { amountCents: 8_000, reason: 'Pagado en efectivo en tienda' };
+        const yes: RetailCommission.ResolvePaymentRequest = { accredited: true, transactionId: 'TX-9', note: 'Folio confirmado' };
+        const no: RetailCommission.ResolvePaymentRequest = { accredited: false, note: 'No llegó a la wallet' };
+        expect([outside.amountCents, yes.transactionId, no.transactionId]).toEqual([8_000, 'TX-9', undefined]);
+    });
+
+    it('el historial del vendedor y los estados de cuenta de la cadena', () => {
+        const ledger: RetailCommission.GetSellerLedgerResponse = { balance, movements: [cut], payments: [accredited] };
+        const list: RetailCommission.ListStatementsResponse = { statements: [statement] };
+        const detail: RetailCommission.GetStatementResponse = { statement, payments: [accredited] };
+        expect([ledger.movements.length, list.statements.length, detail.payments.length]).toEqual([1, 1, 1]);
+    });
+
+    it('el vendedor sin nada en el libro ve su saldo en null', () => {
+        const mine: RetailCommission.GetMyPaymentsResponse = { balance: null, payments: [] };
+        expect(mine.balance).toBeNull();
+    });
+
+    it('las respuestas de las acciones de "Por pagar" y del aviso privado de wallet vinculada', () => {
+        const retry: RetailCommission.RetrySellerPaymentView = { sellerId: 'V-01', triggerId: '01JRETRY0000000000000000001' };
+        const outside: RetailCommission.MarkPaidOutsideView = { balance, movement: cut };
+        const resolved: RetailCommission.ResolvePaymentView = { payment: accredited };
+        const trigger: RetailCommission.PrivateTriggerSellerPaymentResponse = { enqueued: false };
+        expect([retry.sellerId, outside.movement.movementKey, resolved.payment.status, trigger.enqueued]).toEqual([
+            'V-01',
+            'MOV#2026-10-05#CUT',
+            'ACCREDITED',
+            false,
+        ]);
+    });
+});

package/_test_/unit/retailCommission/commissionRules.test.ts

@@ -28,6 +28,14 @@ describe('retailCommission — enums de las reglas', () => {
         expect(Object.values(RetailCommission.CommissionCountByEnum)).toEqual(['PIECE', 'SALE']);
     });
 
+    it('una regla se paga al momento, al cierre de la semana o al cierre del mes', () => {
+        expect(Object.values(RetailCommission.CommissionPayTimingEnum)).toEqual(['ON_SALE', 'ON_CUT', 'MONTHLY']);
+    });
+
+    it('a la cadena se le cobra cada semana o cada mes', () => {
+        expect(Object.values(RetailCommission.CommissionBillingPeriodEnum)).toEqual(['WEEKLY', 'MONTHLY']);
+    });
+
     it('expone las ventanas del corte', () => {
         expect(Object.values(RetailCommission.CommissionWindowEnum)).toEqual(['SEMANA_OPERATIVA', 'ROLLING_7D', 'MES']);
     });
@@ -99,6 +107,12 @@ describe('retailCommission — regla, políticas y snapshot', () => {
         expect(npi.condition?.minSample).toBe(5);
     });
 
+    it('la regla dice cuándo se paga, y una sin el campo sigue siendo válida', () => {
+        const monthly: RetailCommission.CommissionRule = { ...base, payTiming: RetailCommission.CommissionPayTimingEnum.MONTHLY };
+        expect(base.payTiming).toBeUndefined();
+        expect(monthly.payTiming).toBe('MONTHLY');
+    });
+
     it('el snapshot congela las reglas publicadas y las políticas', () => {
         const snapshot: RetailCommission.CommissionRuleSetSnapshot = {
             retailerId: 'RET-1',
@@ -124,6 +138,17 @@ describe('retailCommission — regla, políticas y snapshot', () => {
         const policies: RetailCommission.CommissionPolicies = { clawback: null, commissions: null };
         expect(policies.clawback).toBeNull();
     });
+
+    it('la política de pagos es opcional y viaja con las demás', () => {
+        const payouts: RetailCommission.CommissionPayoutPolicy = {
+            walletDeposits: false,
+            chainBillingPeriod: RetailCommission.CommissionBillingPeriodEnum.MONTHLY,
+        };
+        const legacy: RetailCommission.CommissionPolicies = { clawback: null, commissions: null };
+        const withPayouts: RetailCommission.CommissionPolicies = { ...legacy, payouts };
+        expect(legacy.payouts).toBeUndefined();
+        expect(withPayouts.payouts?.chainBillingPeriod).toBe('MONTHLY');
+    });
 });
 
 describe('retailCommission — devengo con reglas', () => {
@@ -234,6 +259,23 @@ describe('retailCommission — contratos de reglas y políticas', () => {
         expect([create.name, update.expectedVersion, action.expectedVersion]).toEqual(['Bono Accesorios', 2, 3]);
     });
 
+    it('el editor manda cuándo se paga y el vendedor lo ve', () => {
+        const create: RetailCommission.CreateRuleRequest = { ...input, payTiming: RetailCommission.CommissionPayTimingEnum.ON_SALE };
+        const view: RetailCommission.CommissionRuleView = {
+            ruleId: 'RC-01',
+            name: create.name,
+            description: create.description,
+            levers: create.levers,
+            scope: create.scope,
+            condition: create.condition,
+            effectiveFrom: create.effectiveFrom,
+            effectiveTo: create.effectiveTo,
+            payTiming: create.payTiming,
+        };
+        expect(input.payTiming).toBeUndefined();
+        expect(view.payTiming).toBe('ON_SALE');
+    });
+
     it('las políticas se guardan juntas', () => {
         const request: RetailCommission.UpdatePoliciesRequest = {
             clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30 },
@@ -242,6 +284,17 @@ describe('retailCommission — contratos de reglas y políticas', () => {
         expect(request.commissions.multiplicadorMaxBps).toBe(25000);
     });
 
+    it('la política de pagos se guarda con las demás, y un editor que no la manda sigue siendo válido', () => {
+        const request: RetailCommission.UpdatePoliciesRequest = {
+            clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30 },
+            commissions: { multiplicadorMaxBps: 25000, ventanaDefault: CommissionWindowEnum.SEMANA_OPERATIVA },
+            payouts: { walletDeposits: true, chainBillingPeriod: RetailCommission.CommissionBillingPeriodEnum.WEEKLY },
+        };
+        const legacy: RetailCommission.UpdatePoliciesRequest = { clawback: request.clawback, commissions: request.commissions };
+        expect(request.payouts?.walletDeposits).toBe(true);
+        expect(legacy.payouts).toBeUndefined();
+    });
+
     it('el plan vigente con reglas puede no existir todavía', () => {
         const response: RetailCommission.GetRuleSetResponse = { active: null };
         const history: RetailCommission.RuleHistoryResponse = {

package/_test_/unit/retailOrg/dtos/RetailUser.test.ts

@@ -5,6 +5,7 @@ import { RetailUser } from '../../../../src/retailOrg/dtos/RetailUser';
 import { EmploymentTypeEnum } from '../../../../src/retailOrg/enums/EmploymentTypeEnum';
 import { RetailUserStatusEnum } from '../../../../src/retailOrg/enums/RetailUserStatusEnum';
 import { CollectorSeniorityEnum } from '../../../../src/retailOrg/enums/CollectorSeniorityEnum';
+import { RetailUserWalletLinkMethodEnum } from '../../../../src/retailOrg/enums/RetailUserWalletLinkMethodEnum';
 
 const valid = {
     retailUserId: 'ru_001',
@@ -82,3 +83,49 @@ describe('RetailUser', () => {
         expect(errors.some(e => e.property === 'cognitoSub')).toBe(true);
     });
 });
+
+describe('RetailUser — wallet PCF', () => {
+    const linked = {
+        ...valid,
+        fiadoDirectoryId: 'dir_001',
+        pcfAccountId: 'pcf_001',
+        walletLinkMethod: RetailUserWalletLinkMethodEnum.CLABE,
+        walletClabeLast4: '9012',
+        walletLinkedAt: '2026-10-20T10:00:00.000Z',
+        walletLinkedBy: 'admin_001',
+    };
+
+    it('valida con la wallet vinculada', async () => {
+        const errors = await validate(plainToInstance(RetailUser, linked));
+        expect(errors).toEqual([]);
+    });
+
+    it('valida con la wallet desvinculada (campos en null)', async () => {
+        const unlinked = {
+            ...valid,
+            fiadoDirectoryId: null,
+            pcfAccountId: null,
+            walletLinkMethod: null,
+            walletClabeLast4: null,
+            walletLinkedAt: null,
+            walletLinkedBy: null,
+        };
+        const errors = await validate(plainToInstance(RetailUser, unlinked));
+        expect(errors).toEqual([]);
+    });
+
+    it('falla si walletLinkMethod está fuera del enum', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletLinkMethod: 'EMAIL' }));
+        expect(errors.some(e => e.property === 'walletLinkMethod')).toBe(true);
+    });
+
+    it('falla si walletClabeLast4 trae la CLABE completa', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletClabeLast4: '646180123456789012' }));
+        expect(errors.some(e => e.property === 'walletClabeLast4')).toBe(true);
+    });
+
+    it('falla si walletLinkedAt no es ISO 8601', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletLinkedAt: '20/10/2026' }));
+        expect(errors.some(e => e.property === 'walletLinkedAt')).toBe(true);
+    });
+});

package/_test_/unit/retailOrg/dtos/requests/retailUserWalletRequests.test.ts

@@ -0,0 +1,41 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import { LinkRetailUserWalletRequest, LookupRetailUserWalletRequest } from '../../../../../src/retailOrg';
+
+const CLABE = '646180123456789012';
+const PHONE = '+525512345678';
+
+function validate(cls: ClassConstructor<object>, payload: object): ValidationError[] {
+    return validateSync(plainToInstance(cls, payload, { excludeExtraneousValues: true }));
+}
+
+function errorsOf(cls: ClassConstructor<object>, payload: object): string[] {
+    return validate(cls, payload).map((e) => e.property);
+}
+
+function clabeConstraints(cls: ClassConstructor<object>, payload: object): string[] {
+    return Object.keys(validate(cls, payload).find((e) => e.property === 'clabe')?.constraints ?? {});
+}
+
+const requests: Array<[string, ClassConstructor<object>]> = [
+    ['LookupRetailUserWalletRequest', LookupRetailUserWalletRequest],
+    ['LinkRetailUserWalletRequest', LinkRetailUserWalletRequest],
+];
+
+describe.each(requests)('%s', (_name, cls) => {
+    it('acepta solo la CLABE', () => expect(errorsOf(cls, { clabe: CLABE })).toEqual([]));
+    it('acepta solo el teléfono', () => expect(errorsOf(cls, { phone: PHONE })).toEqual([]));
+    it('rechaza la CLABE y el teléfono juntos', () => expect(errorsOf(cls, { clabe: CLABE, phone: PHONE })).toContain('clabe'));
+    it('rechaza un body sin ninguno', () => expect(clabeConstraints(cls, {})).toContain('isSingleWalletKey'));
+    it('rechaza un teléfono en null sin CLABE', () =>
+        expect(clabeConstraints(cls, { phone: null })).toContain('isSingleWalletKey'));
+    it('acepta la CLABE en null con teléfono', () => expect(errorsOf(cls, { clabe: null, phone: '5512345678' })).toEqual([]));
+    it('rechaza la CLABE vacía con teléfono', () => expect(errorsOf(cls, { clabe: '', phone: '5512345678' })).toContain('clabe'));
+    it('rechaza una CLABE que no son 18 dígitos', () => expect(errorsOf(cls, { clabe: '64618012345678901' })).toContain('clabe'));
+    it('acepta el teléfono en 10 dígitos, sin +52', () => expect(errorsOf(cls, { phone: '5512345678' })).toEqual([]));
+    it('rechaza un teléfono que no son 10 dígitos o que trae otra lada', () => {
+        expect(errorsOf(cls, { phone: '551234567' })).toContain('phone');
+        expect(errorsOf(cls, { phone: '+15512345678' })).toContain('phone');
+    });
+});

package/_test_/unit/retailOrg/dtos/responses/retailUserWalletResponses.test.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata';
+import {
+    RetailUserWalletLinkMethodEnum,
+    type LookupRetailUserWalletResponse,
+    type PrivateRetailUserWalletResponse,
+} from '../../../../../src/retailOrg';
+
+describe('respuestas de la wallet del vendedor', () => {
+    it('la búsqueda dice si la encontró, si está activa y a nombre de quién', () => {
+        const found: LookupRetailUserWalletResponse = {
+            found: true,
+            active: true,
+            holderName: 'Ana López',
+            method: RetailUserWalletLinkMethodEnum.CLABE,
+        };
+        const missing: LookupRetailUserWalletResponse = {
+            found: false,
+            active: false,
+            holderName: null,
+            method: RetailUserWalletLinkMethodEnum.PHONE,
+        };
+        expect([found.holderName, missing.holderName]).toEqual(['Ana López', null]);
+    });
+
+    it('el privado devuelve la wallet o null si no tiene', () => {
+        const linked: PrivateRetailUserWalletResponse = { directoryId: 'dir_001', pcfAccountId: 'pcf_001' };
+        const none: PrivateRetailUserWalletResponse = { directoryId: null, pcfAccountId: null };
+        expect([linked.directoryId, none.directoryId]).toEqual(['dir_001', null]);
+    });
+});

package/_test_/unit/retailOrg/enums/RetailUserWalletLinkMethodEnum.test.ts

@@ -0,0 +1,12 @@
+import { RetailUserWalletLinkMethodEnum } from '../../../../src/retailOrg/enums/RetailUserWalletLinkMethodEnum';
+
+describe('RetailUserWalletLinkMethodEnum', () => {
+    it('contiene exactamente los métodos del contrato con value === key', () => {
+        expect(RetailUserWalletLinkMethodEnum.CLABE).toBe('CLABE');
+        expect(RetailUserWalletLinkMethodEnum.PHONE).toBe('PHONE');
+    });
+
+    it('no tiene valores de más', () => {
+        expect(Object.values(RetailUserWalletLinkMethodEnum).sort()).toEqual(['CLABE', 'PHONE']);
+    });
+});

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

@@ -4,8 +4,11 @@ import type { CommissionAddOn, CommissionCategory, CommissionPlanSnapshot, Commi
 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 { CommissionChainStatement, CommissionLedgerMovement, CommissionPayment, CommissionSellerBalance } from './CommissionLedger';
 import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
 import type { CommissionCountByEnum } from '../enums/CommissionCountByEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
 import type { CommissionAggregateByEnum } from '../enums/CommissionAggregateByEnum';
 import type { CommissionSeriesByEnum } from '../enums/CommissionSeriesByEnum';
 import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStatusEnum';
@@ -197,6 +200,8 @@ export interface CommissionRuleInput {
     replacesOthers: boolean;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
 }
 /** `POST /backoffice/commissions/rules` — la regla nace en borrador. */
 export type CreateRuleRequest = CommissionRuleInput;
@@ -231,7 +236,7 @@ export interface RuleHistoryResponse {
 export interface GetPoliciesResponse {
     policies: CommissionPolicies;
 }
-/** `PUT /backoffice/commissions/policies` — las dos políticas se guardan juntas. */
+/** `PUT /backoffice/commissions/policies` — las políticas se guardan juntas. */
 export interface UpdatePoliciesRequest {
     clawback: {
         cancelacionDias: number;
@@ -242,6 +247,11 @@ export interface UpdatePoliciesRequest {
         multiplicadorMaxBps: number;
         ventanaDefault: CommissionWindowEnum;
     };
+    /** Opcional para que un editor que todavía no la manda siga funcionando. */
+    payouts?: {
+        walletDeposits: boolean;
+        chainBillingPeriod: CommissionBillingPeriodEnum;
+    };
 }
 export interface UpdatePoliciesResponse {
     policies: CommissionPolicies;
@@ -375,6 +385,8 @@ export interface CommissionRuleView {
     effectiveTo: string | null;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
 }
 /** Lo pagado en varios cortes. */
 export interface MyCommissionsTotals {
@@ -411,3 +423,70 @@ export interface GetMyCommissionsResponse {
     /** Tope del multiplicador de la política; `null` sin política. */
     multiplierCapBps: number | null;
 }
+/** `GET /backoffice/commissions/payments/attention` — el reporte "Por pagar" de la cadena. */
+export interface GetPaymentAttentionResponse {
+    /** Saldos con exigible sin depositar, con su motivo. */
+    pending: CommissionSellerBalance[];
+    /** Depósitos sin confirmar: "Requiere revisión". */
+    unverified: CommissionPayment[];
+    /** Saldos con exigible negativo. */
+    debts: CommissionSellerBalance[];
+}
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/paid-outside` */
+export interface MarkPaidOutsideRequest {
+    amountCents: number;
+    /** Obligatorio: dinero que sale sin depósito tiene que poder auditarse. */
+    reason: string;
+}
+/** `POST /backoffice/commissions/payments/{paymentId}/resolve` — revisión de un depósito sin confirmar. */
+export interface ResolvePaymentRequest {
+    /** `true` = sí se depositó; `false` = no, y el monto vuelve al exigible. */
+    accredited: boolean;
+    /** El folio, cuando sí se depositó. */
+    transactionId?: string;
+    note: string;
+}
+/** `GET /backoffice/commissions/sellers/{sellerId}/ledger` — saldo e historial de un vendedor. */
+export interface GetSellerLedgerResponse {
+    balance: CommissionSellerBalance;
+    movements: CommissionLedgerMovement[];
+    payments: CommissionPayment[];
+}
+/** `GET /backoffice/commissions/statements` */
+export interface ListStatementsResponse {
+    statements: CommissionChainStatement[];
+}
+/** `GET /backoffice/commissions/statements/{statementId}` — el estado de cuenta y sus depósitos. */
+export interface GetStatementResponse {
+    statement: CommissionChainStatement;
+    payments: CommissionPayment[];
+}
+/** `GET /commissions/me/payments` — los pagos del vendedor que llama. */
+export interface GetMyPaymentsResponse {
+    /** `null` mientras no tiene nada en el libro. */
+    balance: CommissionSellerBalance | null;
+    payments: CommissionPayment[];
+}
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/retry` (202) — el pago quedó en la cola. */
+export interface RetrySellerPaymentView {
+    sellerId: string;
+    /** Id del disparo `RETRY` con que se encoló. */
+    triggerId: string;
+}
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/paid-outside` (201) — el saldo nuevo y el movimiento escrito. */
+export interface MarkPaidOutsideView {
+    balance: CommissionSellerBalance;
+    movement: CommissionLedgerMovement;
+}
+/** `POST /backoffice/commissions/payments/{paymentId}/resolve` — el depósito ya resuelto. */
+export interface ResolvePaymentView {
+    payment: CommissionPayment;
+}
+/**
+ * `POST /private/retailers/{retailerId}/sellers/{sellerId}/payments/trigger?tenantId=` (202) — retail-org
+ * avisa que el vendedor vinculó su wallet. El cuerpo va vacío (`{}`).
+ */
+export interface PrivateTriggerSellerPaymentResponse {
+    /** `false` si la cola no lo recibió: el saldo sigue pendiente y entra en el siguiente pago. */
+    enqueued: boolean;
+}

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

@@ -0,0 +1,96 @@
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
+import type { CommissionLedgerMovementKindEnum } from '../enums/CommissionLedgerMovementKindEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
+import type { CommissionPaymentAttentionEnum } from '../enums/CommissionPaymentAttentionEnum';
+import type { CommissionPaymentStatusEnum } from '../enums/CommissionPaymentStatusEnum';
+/**
+ * Saldo de un vendedor en una cadena. Es parte del libro de pagos: cada peso que se le acredita, se
+ * le descuenta o se le deposita en su wallet. Montos en centavos; fechas en ISO.
+ */
+export interface CommissionSellerBalance {
+    retailerId: string;
+    sellerId: string;
+    /** Ganado que todavía no toca pagar (reglas al cierre del mes). */
+    retainedCents: number;
+    /** Lo que se puede depositar ya. Negativo = el vendedor debe. */
+    payableCents: number;
+    /** Apartado para un depósito en curso o sin confirmar. */
+    inTransitCents: number;
+    /** Acumulado de todo lo ganado. */
+    earnedCents: number;
+    /** Acumulado de todo lo descontado. */
+    deductedCents: number;
+    /** Acumulado de lo depositado y confirmado. */
+    accreditedCents: number;
+    /** Acumulado de lo pagado por fuera. */
+    paidOutsideCents: number;
+    /** `null` si no necesita atención. */
+    attention: CommissionPaymentAttentionEnum | null;
+    /** Código del último rechazo, p. ej. `USER_NOT_ACTIVE`. */
+    attentionCode: string | null;
+    /** Desde cuándo tiene esa atención. */
+    attentionSince: string | null;
+    updatedAt: string;
+}
+/** Lo que una regla aporta a un movimiento. */
+export interface CommissionLedgerMovementRule {
+    ruleId: string;
+    payTiming: CommissionPayTimingEnum;
+    cents: number;
+}
+/** Un movimiento del libro. Nunca cambia. */
+export interface CommissionLedgerMovement {
+    /** Determinista por origen: una reentrega no duplica el movimiento. */
+    movementKey: string;
+    kind: CommissionLedgerMovementKindEnum;
+    periodId: string;
+    retainedDeltaCents: number;
+    payableDeltaCents: number;
+    byRule: CommissionLedgerMovementRule[];
+    saleId: string | null;
+    adjustmentId: string | null;
+    /** `YYYY-MM` de la liberación mensual. */
+    releaseMonth: string | null;
+    /** Obligatorio en lo pagado por fuera. */
+    reason: string | null;
+    createdAt: string;
+    createdBy: string;
+}
+/** Un depósito a la wallet del vendedor. Solo cambia su estado. */
+export interface CommissionPayment {
+    /** También es la llave de idempotencia del depósito. */
+    paymentId: string;
+    retailerId: string;
+    sellerId: string;
+    amountCents: number;
+    status: CommissionPaymentStatusEnum;
+    /** La wallet a la que se depositó. */
+    directoryId: string;
+    /** Folio del depósito; `null` mientras no se confirma. */
+    transactionId: string | null;
+    errorCode: string | null;
+    /** Lo que ve el vendedor en su wallet; máximo 120 caracteres. */
+    concept: string;
+    requestedAt: string;
+    resolvedAt: string | null;
+    resolvedBy: string | null;
+    /** Nota de quien lo revisó a mano. */
+    note: string | null;
+}
+/**
+ * Estado de cuenta para cobrarle a la cadena: los depósitos confirmados del periodo. Lo pagado por
+ * fuera no entra. Se genera una vez y no cambia.
+ */
+export interface CommissionChainStatement {
+    statementId: string;
+    retailerId: string;
+    period: CommissionBillingPeriodEnum;
+    /** `YYYY-MM-DD`, inclusive. */
+    startDate: string;
+    /** `YYYY-MM-DD`, inclusive. */
+    endDate: string;
+    accreditedCents: number;
+    paymentsCount: number;
+    sellersCount: number;
+    generatedAt: string;
+}

package/bin/retailCommission/dtos/CommissionLedger.js

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

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

@@ -1,9 +1,11 @@
 import type { ProductCategoryEnum } from '../../retailCatalog/enums/ProductCategoryEnum';
 import type { ProductTierEnum } from '../../retailCatalog/enums/ProductTierEnum';
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
 import type { CommissionBonusModeEnum } from '../enums/CommissionBonusModeEnum';
 import type { CommissionCountByEnum } from '../enums/CommissionCountByEnum';
 import type { CommissionMetricEnum } from '../enums/CommissionMetricEnum';
 import type { CommissionOperatorEnum } from '../enums/CommissionOperatorEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
 import type { CommissionRuleStatusEnum } from '../enums/CommissionRuleStatusEnum';
 import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
 /**
@@ -75,6 +77,8 @@ export interface CommissionRule {
     replacesOthers: boolean;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
     /** Sube en cada guardado. */
     version: number;
     /** La versión que está en el plan vigente. `null` si nunca se publicó. */
@@ -102,10 +106,19 @@ export interface CommissionPolicyCommissions {
     editedBy: string;
     editedAt: string;
 }
-/** Políticas de la cadena. Cada una es `null` mientras la cadena no la guarda. */
+/** Política de pagos a la wallet de los vendedores. */
+export interface CommissionPayoutPolicy {
+    /** Depositar las comisiones a la wallet. Apagado, todo se calcula y queda pendiente. */
+    walletDeposits: boolean;
+    /** Cada cuánto se le cobra a la cadena. */
+    chainBillingPeriod: CommissionBillingPeriodEnum;
+}
+/** Políticas de la cadena. `clawback` y `commissions` son `null` mientras la cadena no las guarda. */
 export interface CommissionPolicies {
     clawback: CommissionPolicyClawback | null;
     commissions: CommissionPolicyCommissions | null;
+    /** Ausente = depósitos encendidos y cobro semanal. */
+    payouts?: CommissionPayoutPolicy;
 }
 /**
  * El plan vigente: las reglas publicadas y las políticas, congeladas en un snapshot inmutable.