@fiado/type-kit 3.278.0 → 3.280.0

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 });

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

@@ -0,0 +1,182 @@
+import type { CommissionMechanicTypeEnum } from '../enums/CommissionMechanicTypeEnum';
+import type { CommissionPlanStatusEnum } from '../enums/CommissionPlanStatusEnum';
+import type { CommissionPriceReferenceEnum } from '../enums/CommissionPriceReferenceEnum';
+import type { CommissionQuotaTypeEnum } from '../enums/CommissionQuotaTypeEnum';
+import type { CommissionQuotaMeasureEnum } from '../enums/CommissionQuotaMeasureEnum';
+import type { CommissionQuotaSubjectEnum } from '../enums/CommissionQuotaSubjectEnum';
+import type { CommissionQuotaModeEnum } from '../enums/CommissionQuotaModeEnum';
+import type { CommissionPeriodTypeEnum } from '../enums/CommissionPeriodTypeEnum';
+import type { CommissionExceptionTypeEnum } from '../enums/CommissionExceptionTypeEnum';
+/**
+ * El plan de comisiones de VentasLuga, versionado por snapshot inmutable.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Todo lo de este archivo vive DENTRO de un snapshot: se congela al publicar y no se vuelve a tocar.
+ * Esa es la razón de que hasta las reglas de `sku → categoría` (`CommissionCategoryMatch`) vivan acá
+ * y no en el código del motor — si vivieran en el código, un redespliegue cambiaría montos ya
+ * devengados y dos accruals del mismo snapshot podrían calcularse distinto.
+ *
+ * Montos en centavos (`*Cents`), porcentajes en puntos base (`*Bps`, 10000 = 100%).
+ */
+/**
+ * Un par de valores: sin cuota y con cuota.
+ *
+ * ⚠️ **No es un descuento: son dos tablas de precios.** Alcanzar la cuota no «suma un bono», elige
+ * columna. Por eso `base: 0, withQuota: 2500` (PayJoy) es válido y significa «solo comisiona si
+ * alcanzó la cuota», no un error de captura.
+ */
+export interface CommissionValuePair {
+    /** Valor cuando NO se alcanzó la cuota. Puede ser 0. */
+    base: number;
+    /** Valor cuando SÍ se alcanzó. Puede ser igual al base si la categoría no discrimina. */
+    withQuota: number;
+}
+/** Un tramo de precio del equipo. Los tramos no se solapan y cubren de 0 a infinito. */
+export interface CommissionPriceTier extends CommissionValuePair {
+    /** Etiqueta visible: `D`, `C`, `B`, `A`. */
+    grade: string;
+    minCents: number;
+    /** `null` = sin tope superior (el tramo más alto). */
+    maxCents: number | null;
+}
+/** Una celda de la matriz, identificada por sus coordenadas. */
+export interface CommissionMatrixCell extends CommissionValuePair {
+    /** Un valor por dimensión, en el mismo orden que `dimensions`. */
+    coords: string[];
+}
+/** Una variante enumerada (un plan de pospago, por ejemplo). */
+export interface CommissionVariant extends CommissionValuePair {
+    variantId: string;
+    label: string;
+}
+/** Una variante por forma de pago. Los valores van en bps. */
+export interface CommissionPaymentVariant extends CommissionValuePair {
+    /** `CASH` | `CREDIT` — cómo pagó el cliente. */
+    paymentType: string;
+    label: string;
+}
+/**
+ * La mecánica de una categoría, discriminada por `type`.
+ *
+ * `PRICE_TIER`, `FLAT`, `MATRIX` y `VARIANT` pagan en CENTAVOS; `PERCENT` y `PERCENT_BY_PAYMENT`
+ * pagan en BPS sobre el precio. Esa distinción la resuelve el evaluador con `valueKind`, no una rama
+ * por tipo.
+ */
+export type CommissionMechanic = {
+    type: CommissionMechanicTypeEnum.PRICE_TIER;
+    tiers: CommissionPriceTier[];
+} | {
+    type: CommissionMechanicTypeEnum.FLAT;
+    value: CommissionValuePair;
+} | {
+    type: CommissionMechanicTypeEnum.PERCENT;
+    value: CommissionValuePair;
+} | {
+    type: CommissionMechanicTypeEnum.MATRIX;
+    dimensions: string[];
+    cells: CommissionMatrixCell[];
+} | {
+    type: CommissionMechanicTypeEnum.VARIANT;
+    variants: CommissionVariant[];
+} | {
+    type: CommissionMechanicTypeEnum.PERCENT_BY_PAYMENT;
+    variants: CommissionPaymentVariant[];
+};
+/** Un nivel del acelerador. `factorBps` 10000 = 1.0×, 12000 = 1.2×. */
+export interface CommissionQuotaLevel {
+    minAmountCents: number;
+    factorBps: number;
+}
+/**
+ * Una cuota. Binaria (un gate) o escalonada (N niveles con multiplicador).
+ *
+ * ⚠️ **Todas se resuelven al CERRAR el periodo**, nunca al devengar. Ese es el diseño de Jaime y es
+ * lo que evita el mecanismo más peligroso posible: reescribir filas ya devengadas cada vez que una
+ * venta nueva mueve el conteo.
+ */
+export interface CommissionQuota {
+    quotaId: string;
+    name: string;
+    description: string | null;
+    active: boolean;
+    type: CommissionQuotaTypeEnum;
+    measure: CommissionQuotaMeasureEnum;
+    subject: CommissionQuotaSubjectEnum;
+    period: CommissionPeriodTypeEnum;
+    mode: CommissionQuotaModeEnum;
+    /** Solo `BINARY`. El umbral a alcanzar, en la unidad de `measure`. */
+    threshold: number | null;
+    /** Solo `TIERED`. Ordenados de menor a mayor. */
+    levels: CommissionQuotaLevel[] | null;
+    /** Si el valor `withQuota` REEMPLAZA al base (`true`) o se suma. Hoy siempre `true`. */
+    replacesBase: boolean;
+}
+/**
+ * Cómo se decide que una venta pertenece a esta categoría.
+ *
+ * Vive DENTRO del snapshot (versionado e inmutable con el plan). Si viviera en el código del motor,
+ * cambiar el mapa reescribiría el pasado.
+ */
+export interface CommissionCategoryMatch {
+    skus: string[];
+    brands: string[];
+    /** Prefijos de SKU, para familias completas. */
+    skuPrefixes: string[];
+}
+/**
+ * Una excepción: un SKU o una marca que paga distinto que su categoría.
+ *
+ * Precedencia: **SKU gana sobre BRAND, y BRAND sobre la mecánica.**
+ */
+export interface CommissionException {
+    exceptionId: string;
+    type: CommissionExceptionTypeEnum;
+    /** El SKU exacto o el nombre de la marca, según `type`. */
+    target: string;
+    label: string;
+    value: CommissionValuePair;
+}
+/** Una categoría de producto con su mecánica, su cuota y sus excepciones. */
+export interface CommissionCategory {
+    categoryId: string;
+    name: string;
+    icon: string | null;
+    description: string | null;
+    match: CommissionCategoryMatch;
+    /** `null` = la categoría NO está condicionada a ninguna cuota (Pospago, Zmotos). */
+    quotaId: string | null;
+    priceReference: CommissionPriceReferenceEnum;
+    mechanic: CommissionMechanic;
+    exceptions: CommissionException[];
+}
+/** Un add-on: monto fijo que se suma FUERA del stacking y fuera del máximo. */
+export interface CommissionAddOn {
+    addOnId: string;
+    label: string;
+    amountCents: number;
+    active: boolean;
+}
+/**
+ * Una versión del plan. Publicada es inmutable; el borrador se pisa.
+ *
+ * `storeOverrideBps` es un **pago a OTRA persona** (el admin de la tienda) sobre las ventas de su
+ * equipo. Se modela pero **no se devenga** en el primer corte, hasta que se defina quién es ese
+ * admin en `retail-org-business`.
+ */
+export interface CommissionPlanSnapshot {
+    retailerId: string;
+    /** `null` mientras es borrador: el ULID se asigna al publicar. */
+    snapshotId: string | null;
+    status: CommissionPlanStatusEnum;
+    effectiveFrom: string;
+    categories: CommissionCategory[];
+    quotas: CommissionQuota[];
+    addOns: CommissionAddOn[];
+    /** `storeId` → bps adicionales para el admin de esa tienda. */
+    storeOverrideBps: Record<string, number>;
+    changeNote: string | null;
+    publishedBy: string | null;
+    publishedAt: string | null;
+    updatedAt: string | null;
+    updatedBy: string | null;
+}

package/bin/retailCommission/dtos/CommissionPlan.js

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

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

@@ -0,0 +1,14 @@
+/**
+ * Estado de una fila de devengo.
+ *
+ * ACCRUED - Devengada con su monto base. La cuota y el factor TODAVÍA no están resueltos.
+ * PAID - Liquidada al cerrar el corte: ya tiene `quotaMet`, `quotaFactorBps` y `settledAmountCents`.
+ * REVERSED - Revertida por cancelación de la venta, con el corte aún abierto.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionAccrualStatusEnum {
+    ACCRUED = "ACCRUED",
+    PAID = "PAID",
+    REVERSED = "REVERSED"
+}

package/bin/retailCommission/enums/CommissionAccrualStatusEnum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionAccrualStatusEnum = void 0;
+/**
+ * Estado de una fila de devengo.
+ *
+ * ACCRUED - Devengada con su monto base. La cuota y el factor TODAVÍA no están resueltos.
+ * PAID - Liquidada al cerrar el corte: ya tiene `quotaMet`, `quotaFactorBps` y `settledAmountCents`.
+ * REVERSED - Revertida por cancelación de la venta, con el corte aún abierto.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionAccrualStatusEnum;
+(function (CommissionAccrualStatusEnum) {
+    CommissionAccrualStatusEnum["ACCRUED"] = "ACCRUED";
+    CommissionAccrualStatusEnum["PAID"] = "PAID";
+    CommissionAccrualStatusEnum["REVERSED"] = "REVERSED";
+})(CommissionAccrualStatusEnum || (exports.CommissionAccrualStatusEnum = CommissionAccrualStatusEnum = {}));

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

@@ -0,0 +1,23 @@
+/**
+ * Los pasos que puede registrar la traza de cálculo.
+ *
+ * La traza es una unión CERRADA por este enum, sin campos libres: es el vehículo más probable de
+ * fuga de PII del comprador y no debe haber dónde meterla.
+ *
+ * MECHANIC - Se evaluó la mecánica de la categoría.
+ * EXCEPTION - Una excepción por SKU o marca reemplazó el valor de la mecánica.
+ * ADDON - Se sumó un add-on. Van FUERA del stacking.
+ * QUOTA - Se resolvió la cuota (binaria o escalonada). Ocurre al CERRAR, no al devengar.
+ * ADJUSTMENT - Un ajuste manual del corte.
+ * NO_CATEGORY - El SKU no matcheó ninguna categoría del plan: devenga 0 y queda visible.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionCalcStepEnum {
+    MECHANIC = "MECHANIC",
+    EXCEPTION = "EXCEPTION",
+    ADDON = "ADDON",
+    QUOTA = "QUOTA",
+    ADJUSTMENT = "ADJUSTMENT",
+    NO_CATEGORY = "NO_CATEGORY"
+}

package/bin/retailCommission/enums/CommissionCalcStepEnum.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionCalcStepEnum = void 0;
+/**
+ * Los pasos que puede registrar la traza de cálculo.
+ *
+ * La traza es una unión CERRADA por este enum, sin campos libres: es el vehículo más probable de
+ * fuga de PII del comprador y no debe haber dónde meterla.
+ *
+ * MECHANIC - Se evaluó la mecánica de la categoría.
+ * EXCEPTION - Una excepción por SKU o marca reemplazó el valor de la mecánica.
+ * ADDON - Se sumó un add-on. Van FUERA del stacking.
+ * QUOTA - Se resolvió la cuota (binaria o escalonada). Ocurre al CERRAR, no al devengar.
+ * ADJUSTMENT - Un ajuste manual del corte.
+ * NO_CATEGORY - El SKU no matcheó ninguna categoría del plan: devenga 0 y queda visible.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionCalcStepEnum;
+(function (CommissionCalcStepEnum) {
+    CommissionCalcStepEnum["MECHANIC"] = "MECHANIC";
+    CommissionCalcStepEnum["EXCEPTION"] = "EXCEPTION";
+    CommissionCalcStepEnum["ADDON"] = "ADDON";
+    CommissionCalcStepEnum["QUOTA"] = "QUOTA";
+    CommissionCalcStepEnum["ADJUSTMENT"] = "ADJUSTMENT";
+    CommissionCalcStepEnum["NO_CATEGORY"] = "NO_CATEGORY";
+})(CommissionCalcStepEnum || (exports.CommissionCalcStepEnum = CommissionCalcStepEnum = {}));

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

@@ -0,0 +1,14 @@
+/**
+ * Sobre qué aplica una excepción del plan.
+ *
+ * Precedencia: SKU gana sobre BRAND, y BRAND sobre la mecánica de la categoría.
+ *
+ * SKU - Un SKU exacto.
+ * BRAND - Una marca completa.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+export declare enum CommissionExceptionTypeEnum {
+    SKU = "SKU",
+    BRAND = "BRAND"
+}

package/bin/retailCommission/enums/CommissionExceptionTypeEnum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommissionExceptionTypeEnum = void 0;
+/**
+ * Sobre qué aplica una excepción del plan.
+ *
+ * Precedencia: SKU gana sobre BRAND, y BRAND sobre la mecánica de la categoría.
+ *
+ * SKU - Un SKU exacto.
+ * BRAND - Una marca completa.
+ *
+ * SureKeep Fase 3 — pista Retail. Motor de comisiones de VentasLuga.
+ */
+var CommissionExceptionTypeEnum;
+(function (CommissionExceptionTypeEnum) {
+    CommissionExceptionTypeEnum["SKU"] = "SKU";
+    CommissionExceptionTypeEnum["BRAND"] = "BRAND";
+})(CommissionExceptionTypeEnum || (exports.CommissionExceptionTypeEnum = CommissionExceptionTypeEnum = {}));

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

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export declare enum CommissionMechanicTypeEnum {
+    PRICE_TIER = "PRICE_TIER",
+    FLAT = "FLAT",
+    PERCENT = "PERCENT",
+    MATRIX = "MATRIX",
+    VARIANT = "VARIANT",
+    PERCENT_BY_PAYMENT = "PERCENT_BY_PAYMENT"
+}