@fiado/type-kit 3.260.0 → 3.261.0

package/bin/retailWizard/dtos/SaleLogEntry.d.ts

@@ -0,0 +1,29 @@
+/** Un campo que cambió en una acción auditada. `from` ausente en un alta. */
+export interface SaleLogChange {
+    field: string;
+    from: string | null;
+    to: string | null;
+}
+/**
+ * Una entrada del tab «Bitácora» del drawer de una venta. Proyección de `SharedAuditTrail_GT`
+ * (`pk = ENTITY#SALE#<saleId>`, `sk = TS#<iso>#<ulid>`, orden cronológico nativo).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El diff viaja APLANADO en `changes` y no como los objetos `old`/`new` crudos de la tabla: la
+ * pantalla dibuja una lista de «campo: antes → después», y un objeto libre en el contrato obligaría al
+ * front a adivinar la forma. Los valores se serializan a string por eso mismo.
+ *
+ * ⚠️ `changes` NUNCA lleva PII: la tabla de auditoría solo guarda identificadores y valores
+ * operacionales (status, storeId, type…). Ver `fiado-logging`.
+ */
+export interface SaleLogEntry {
+    /** ISO-8601 del momento de la acción (sale del `sk`). */
+    at: string;
+    /** Acción auditada: `SALE_COMPLETE`, `SALE_CANCEL`, `PAYMENT_REGISTERED`… */
+    action: string;
+    /** Actor: userId del AuthContext, o `system` si la disparó un proceso interno. */
+    performedBy: string;
+    /** Motivo, cuando la acción lo exige (cancelación, excepción aplicada). */
+    reason: string | null;
+    changes: SaleLogChange[];
+}

package/bin/retailWizard/dtos/SaleLogEntry.js

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

package/bin/retailWizard/dtos/SalesReportDefinition.d.ts

@@ -0,0 +1,20 @@
+import type { SalesReportIdEnum } from '../enums/SalesReportIdEnum';
+import type { ReportPeriodicityEnum } from '../enums/ReportPeriodicityEnum';
+import type { ReportFormatEnum } from '../enums/ReportFormatEnum';
+/**
+ * Un reporte del catálogo del Admin VL (M6 §5.1). Es CONFIGURACIÓN, no una fila de tabla: el catálogo
+ * de los 5 reportes vive en código y no se persiste — cambia con un deploy, no con un write.
+ * SureKeep Fase 3 — pista Retail.
+ */
+export interface SalesReportDefinition {
+    reportId: SalesReportIdEnum;
+    /** Nombre para mostrar, en español mexicano. */
+    name: string;
+    description: string;
+    periodicity: ReportPeriodicityEnum;
+    formats: ReportFormatEnum[];
+    /** Referencia al documento de negocio que lo define (ej. `M6 §5.1`). */
+    reference: string;
+    /** ISO-8601 de la última corrida conocida; `null` si nunca corrió. */
+    lastRunAt: string | null;
+}

package/bin/retailWizard/dtos/SalesReportDefinition.js

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

package/bin/retailWizard/dtos/SalesReportRun.d.ts

@@ -0,0 +1,39 @@
+import type { SalesReportIdEnum } from '../enums/SalesReportIdEnum';
+import type { ReportFormatEnum } from '../enums/ReportFormatEnum';
+import type { ReportRunStatusEnum } from '../enums/ReportRunStatusEnum';
+/**
+ * Una corrida de reporte (`<T>RetailReportRun_GT`, pk `RETAILER#<retailerId>` ·
+ * sk `RUN#<requestedAt>#<runId>`, CERO GSIs). Es el log de la sección 3 de la pantalla de Reportes.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * La generación es ASÍNCRONA: el `POST .../run` persiste la corrida en `QUEUED` y devuelve el `runId`;
+ * el front poletea `GET /backoffice/reports`. API Gateway corta a los 29 s y un reporte de red
+ * completa no entra en una respuesta síncrona.
+ */
+export interface SalesReportRun {
+    runId: string;
+    retailerId: string;
+    reportId: SalesReportIdEnum;
+    format: ReportFormatEnum;
+    status: ReportRunStatusEnum;
+    /** userId de quien la disparó; `system` si la lanzó el cron. */
+    requestedBy: string;
+    requestedByName: string | null;
+    /** ISO-8601. Es parte del sort key: ordena el log de corridas. */
+    requestedAt: string;
+    /** ISO-8601 del fin de la generación. `null` mientras no termine. */
+    completedAt: string | null;
+    /** Ventana de datos del reporte, ISO-8601. */
+    periodFrom: string | null;
+    periodTo: string | null;
+    /** Filas generadas. `null` mientras no termine. */
+    rowCount: number | null;
+    /** URL prefirmada de descarga. Solo con `status: READY`; `null` en cualquier otro estado. */
+    downloadUrl: string | null;
+    /** Por qué falló. Solo con `status: FAILED`. */
+    failureReason: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: number;
+    updatedAt: number;
+}

package/bin/retailWizard/dtos/SalesReportRun.js

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

package/bin/retailWizard/dtos/requests/BackofficeCancelSaleRequest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * POST /backoffice/sales/:saleId/cancel — cancelación del Admin VL. SureKeep Fase 3 — pista Retail.
+ *
+ * Es un endpoint SEPARADO de `POST /sales/:saleId/cancel` (el del vendedor), no una rama del mismo, y
+ * por eso lleva su propio DTO. Son dos reglas de negocio distintas: la del vendedor está acotada a su
+ * propia venta y a la ventana de 7 días; la del admin puede cancelar FUERA de ventana — que es justo
+ * lo que habilita la excepción `LATE_CANCEL`. Mezclarlas en un handler enredaría las dos.
+ *
+ * `outOfWindowExceptionId` es el puente entre las dos piezas: cancelar fuera de ventana exige una
+ * excepción `LATE_CANCEL` ya aprobada. Sin ella el manager rechaza, aunque el actor tenga el permiso.
+ */
+export declare class BackofficeCancelSaleRequest {
+    reason: string;
+    /**
+     * Confirmación de que el equipo se verificó físicamente en tienda. Ausente y `false` se tratan
+     * igual (fail-closed): el manager responde `412 IMEI_NOT_RETURNABLE`, que es la respuesta
+     * semánticamente correcta y no un error de forma. `@IsBoolean()` estricto — el string `"false"` se
+     * rechaza en vez de colarse como truthy.
+     */
+    equipmentVerified?: boolean;
+    /**
+     * Excepción `LATE_CANCEL` aprobada que autoriza cancelar fuera de la ventana. Solo se exige cuando
+     * la venta YA está fuera de ventana; dentro de ventana se ignora.
+     */
+    outOfWindowExceptionId?: string;
+}

package/bin/retailWizard/dtos/requests/BackofficeCancelSaleRequest.js

@@ -0,0 +1,48 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.BackofficeCancelSaleRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * POST /backoffice/sales/:saleId/cancel — cancelación del Admin VL. SureKeep Fase 3 — pista Retail.
+ *
+ * Es un endpoint SEPARADO de `POST /sales/:saleId/cancel` (el del vendedor), no una rama del mismo, y
+ * por eso lleva su propio DTO. Son dos reglas de negocio distintas: la del vendedor está acotada a su
+ * propia venta y a la ventana de 7 días; la del admin puede cancelar FUERA de ventana — que es justo
+ * lo que habilita la excepción `LATE_CANCEL`. Mezclarlas en un handler enredaría las dos.
+ *
+ * `outOfWindowExceptionId` es el puente entre las dos piezas: cancelar fuera de ventana exige una
+ * excepción `LATE_CANCEL` ya aprobada. Sin ella el manager rechaza, aunque el actor tenga el permiso.
+ */
+class BackofficeCancelSaleRequest {
+}
+exports.BackofficeCancelSaleRequest = BackofficeCancelSaleRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MinLength)(10),
+    (0, class_validator_1.MaxLength)(200),
+    __metadata("design:type", String)
+], BackofficeCancelSaleRequest.prototype, "reason", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], BackofficeCancelSaleRequest.prototype, "equipmentVerified", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], BackofficeCancelSaleRequest.prototype, "outOfWindowExceptionId", void 0);

package/bin/retailWizard/dtos/requests/CreateSaleExceptionRequest.d.ts

@@ -0,0 +1,28 @@
+import { SaleExceptionTypeEnum } from '../../enums/SaleExceptionTypeEnum';
+/** Lo que la excepción pide cambiar. Cada tipo usa los campos que le tocan; todos son opcionales. */
+export declare class SaleExceptionPayloadInput {
+    sku?: string;
+    amountCents?: number;
+    soldAt?: string;
+    imei?: string;
+}
+/**
+ * POST /backoffice/exceptions — levanta una excepción sobre una venta. SureKeep Fase 3 — pista Retail.
+ *
+ * La `justification` es OBLIGATORIA y con mínimo real: es lo único que vuelve auditable la excepción,
+ * y un campo libre que acepta `"x"` no audita nada. Escribe `RetailSaleException_GT` +
+ * `SharedAuditTrail_GT` en la MISMA `TransactWriteItems`.
+ *
+ * El `retailerId` NO viaja en el request: sale del token (`scopeFromRetailer`).
+ */
+export declare class CreateSaleExceptionRequest {
+    type: SaleExceptionTypeEnum;
+    /** `null`/ausente en las excepciones generales, que no cuelgan de una venta puntual. */
+    saleId?: string;
+    /** Obligatorio cuando NO hay `saleId`; si hay venta, se toma el de la venta. */
+    storeId?: string;
+    justification: string;
+    /** Impacto económico con signo, en centavos. Negativo si la excepción resta (descuento). */
+    impactCents?: number;
+    payload?: SaleExceptionPayloadInput;
+}

package/bin/retailWizard/dtos/requests/CreateSaleExceptionRequest.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.CreateSaleExceptionRequest = exports.SaleExceptionPayloadInput = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const SaleExceptionTypeEnum_1 = require("../../enums/SaleExceptionTypeEnum");
+/** Lo que la excepción pide cambiar. Cada tipo usa los campos que le tocan; todos son opcionales. */
+class SaleExceptionPayloadInput {
+}
+exports.SaleExceptionPayloadInput = SaleExceptionPayloadInput;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], SaleExceptionPayloadInput.prototype, "sku", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    __metadata("design:type", Number)
+], SaleExceptionPayloadInput.prototype, "amountCents", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], SaleExceptionPayloadInput.prototype, "soldAt", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(20),
+    __metadata("design:type", String)
+], SaleExceptionPayloadInput.prototype, "imei", void 0);
+/**
+ * POST /backoffice/exceptions — levanta una excepción sobre una venta. SureKeep Fase 3 — pista Retail.
+ *
+ * La `justification` es OBLIGATORIA y con mínimo real: es lo único que vuelve auditable la excepción,
+ * y un campo libre que acepta `"x"` no audita nada. Escribe `RetailSaleException_GT` +
+ * `SharedAuditTrail_GT` en la MISMA `TransactWriteItems`.
+ *
+ * El `retailerId` NO viaja en el request: sale del token (`scopeFromRetailer`).
+ */
+class CreateSaleExceptionRequest {
+}
+exports.CreateSaleExceptionRequest = CreateSaleExceptionRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(SaleExceptionTypeEnum_1.SaleExceptionTypeEnum),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "type", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "saleId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "storeId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MinLength)(20),
+    (0, class_validator_1.MaxLength)(1000),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "justification", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    __metadata("design:type", Number)
+], CreateSaleExceptionRequest.prototype, "impactCents", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => SaleExceptionPayloadInput),
+    __metadata("design:type", SaleExceptionPayloadInput)
+], CreateSaleExceptionRequest.prototype, "payload", void 0);

package/bin/retailWizard/dtos/requests/ResolveSaleExceptionRequest.d.ts

@@ -0,0 +1,15 @@
+import { SaleExceptionDecisionEnum } from '../../enums/SaleExceptionDecisionEnum';
+/**
+ * POST /backoffice/exceptions/:exceptionId/resolve — aprueba o rechaza una excepción.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * La `resolution` es OBLIGATORIA en los dos veredictos, no solo al rechazar: un «aprobada» sin motivo
+ * escrito es exactamente el registro que después nadie puede defender ante una auditoría.
+ *
+ * **Idempotente** con el guard local (`IIdempotencyGuard` + `SureKeepSharedIdempotency_GT`): un doble
+ * click no puede resolver dos veces. ⚠️ El decorador `@Idempotent` NO existe en el gateway-adapter.
+ */
+export declare class ResolveSaleExceptionRequest {
+    decision: SaleExceptionDecisionEnum;
+    resolution: string;
+}

package/bin/retailWizard/dtos/requests/ResolveSaleExceptionRequest.js

@@ -0,0 +1,40 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.ResolveSaleExceptionRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const SaleExceptionDecisionEnum_1 = require("../../enums/SaleExceptionDecisionEnum");
+/**
+ * POST /backoffice/exceptions/:exceptionId/resolve — aprueba o rechaza una excepción.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * La `resolution` es OBLIGATORIA en los dos veredictos, no solo al rechazar: un «aprobada» sin motivo
+ * escrito es exactamente el registro que después nadie puede defender ante una auditoría.
+ *
+ * **Idempotente** con el guard local (`IIdempotencyGuard` + `SureKeepSharedIdempotency_GT`): un doble
+ * click no puede resolver dos veces. ⚠️ El decorador `@Idempotent` NO existe en el gateway-adapter.
+ */
+class ResolveSaleExceptionRequest {
+}
+exports.ResolveSaleExceptionRequest = ResolveSaleExceptionRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(SaleExceptionDecisionEnum_1.SaleExceptionDecisionEnum),
+    __metadata("design:type", String)
+], ResolveSaleExceptionRequest.prototype, "decision", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MinLength)(10),
+    (0, class_validator_1.MaxLength)(1000),
+    __metadata("design:type", String)
+], ResolveSaleExceptionRequest.prototype, "resolution", void 0);

package/bin/retailWizard/dtos/requests/RunSalesReportRequest.d.ts

@@ -0,0 +1,18 @@
+import { ReportFormatEnum } from '../../enums/ReportFormatEnum';
+/**
+ * POST /backoffice/reports/:reportId/run — encola la generación de un reporte.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Devuelve el `SalesReportRun` en `QUEUED`, NO el archivo: la generación es asíncrona por el límite de
+ * 29 s de API Gateway. El front poletea `GET /backoffice/reports` hasta ver `READY` y ahí usa el
+ * `downloadUrl`.
+ *
+ * El `reportId` viaja en el path, no acá. El `retailerId` sale del token.
+ */
+export declare class RunSalesReportRequest {
+    format: ReportFormatEnum;
+    /** Inicio de la ventana de datos, ISO-8601. Si falta, la resuelve la periodicidad del reporte. */
+    periodFrom?: string;
+    /** Fin de la ventana de datos, ISO-8601. Si falta, la resuelve la periodicidad del reporte. */
+    periodTo?: string;
+}

package/bin/retailWizard/dtos/requests/RunSalesReportRequest.js

@@ -0,0 +1,45 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.RunSalesReportRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const ReportFormatEnum_1 = require("../../enums/ReportFormatEnum");
+/**
+ * POST /backoffice/reports/:reportId/run — encola la generación de un reporte.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Devuelve el `SalesReportRun` en `QUEUED`, NO el archivo: la generación es asíncrona por el límite de
+ * 29 s de API Gateway. El front poletea `GET /backoffice/reports` hasta ver `READY` y ahí usa el
+ * `downloadUrl`.
+ *
+ * El `reportId` viaja en el path, no acá. El `retailerId` sale del token.
+ */
+class RunSalesReportRequest {
+}
+exports.RunSalesReportRequest = RunSalesReportRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(ReportFormatEnum_1.ReportFormatEnum),
+    __metadata("design:type", String)
+], RunSalesReportRequest.prototype, "format", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], RunSalesReportRequest.prototype, "periodFrom", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], RunSalesReportRequest.prototype, "periodTo", void 0);

package/bin/retailWizard/dtos/responses/BackofficeReportsResponse.d.ts

@@ -0,0 +1,14 @@
+import type { SalesReportDefinition } from '../SalesReportDefinition';
+import type { SalesReportRun } from '../SalesReportRun';
+/**
+ * GET /backoffice/reports — el catálogo de los 5 reportes de ventas MÁS el log de corridas recientes,
+ * que es exactamente lo que la pantalla dibuja en sus dos secciones. SureKeep Fase 3 — pista Retail.
+ *
+ * Van juntos en una sola respuesta y no en dos endpoints porque la pantalla siempre necesita los dos,
+ * y el catálogo son 5 ítems de configuración en código: partirlo costaría un round-trip para nada.
+ */
+export interface BackofficeReportsResponse {
+    definitions: SalesReportDefinition[];
+    /** Últimas corridas del retailer, más recientes primero. */
+    runs: SalesReportRun[];
+}

package/bin/retailWizard/dtos/responses/BackofficeReportsResponse.js

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

package/bin/retailWizard/dtos/responses/BackofficeSalesKpisResponse.d.ts

@@ -0,0 +1,32 @@
+import type { SaleFinancierEnum } from '../../enums/SaleFinancierEnum';
+/** Un tramo del mix por financiera del Home del Admin VL. */
+export interface SalesFinancierMixEntry {
+    financier: SaleFinancierEnum;
+    count: number;
+    amountCents: number;
+}
+/**
+ * GET /backoffice/sales/kpis — los KPIs del Home del Admin VL. SureKeep Fase 3 — pista Retail.
+ *
+ * 🟡 **Incompleto por diseño:** el panel «Meta del día» necesita las metas por tienda, que viven en
+ * `retail-org-business` y **todavía no existen**. `goal` viaja `null` hasta entonces; todo lo demás
+ * son datos reales. El front debe tratar `null` como «sin meta configurada», no como cero.
+ *
+ * Las llaves van en inglés (el diseño no fija un payload literal acá, a diferencia de
+ * `BackofficeSalesStatsResponse`).
+ */
+export interface BackofficeSalesKpisResponse {
+    /** Monto colocado hoy, en centavos. Mide precio del equipo, no lo cobrado en caja (DEC-032). */
+    soldTodayCents: number;
+    /** Piezas vendidas hoy. */
+    unitsToday: number;
+    /** Ticket promedio de hoy, en centavos. 0 si no hubo ventas. */
+    averageTicketCents: number;
+    /** Delta porcentual del monto de hoy contra ayer. `null` si ayer no hubo ventas (no se divide por cero). */
+    deltaVsYesterdayPct: number | null;
+    /** Monto del MISMO día de la semana pasada, en centavos — el baseline honesto contra la estacionalidad. */
+    baselineSameWeekdayCents: number;
+    mix: SalesFinancierMixEntry[];
+    /** Meta del día del retailer, en centavos. `null` mientras no exista la tabla de metas. */
+    goalCents: number | null;
+}

package/bin/retailWizard/dtos/responses/BackofficeSalesKpisResponse.js

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

package/bin/retailWizard/dtos/responses/BackofficeSalesStatsResponse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * GET /backoffice/sales/stats — los pills de conteo arriba de la tabla de Ventas del Admin VL.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ **Las llaves van en ESPAÑOL, a propósito y como única excepción del dominio.** Es el contrato
+ * literal que fija el diseño de F3 (`03_backoffice_ventasluga/lambdas/retail-wizard-business.md`) y
+ * contra el que el front ya mockeó la pantalla. Cambiarlas a inglés por consistencia rompería una
+ * pantalla ya construida sin ganar nada. Decisión de Andrés, 2026-08-03.
+ *
+ * `contado` + `credito` == `total`. `surekeep` + `externas` == `credito`: las dos particiones son
+ * completas y NO se solapan (ver `helpers/saleFinancier`).
+ */
+export interface BackofficeSalesStatsResponse {
+    /** Ventas del retailer en la ventana consultada. */
+    total: number;
+    /** Subconjunto de `total` con `soldAt` en el día de hoy. */
+    hoy: number;
+    /** `type: CASH`. */
+    contado: number;
+    /** `type: CREDIT` o `EXTERNAL_REFERRAL` — todo lo que no es contado. */
+    credito: number;
+    /** Financiadas por la SOFOM (`type: CREDIT`). */
+    surekeep: number;
+    /** Financiadas por un tercero (`EXTERNAL_REFERRAL` con proveedor). */
+    externas: number;
+}

package/bin/retailWizard/dtos/responses/BackofficeSalesStatsResponse.js

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

package/bin/retailWizard/enums/ReportFormatEnum.d.ts

@@ -0,0 +1,5 @@
+/** Formato de salida de un reporte del Admin VL. SureKeep Fase 3 — pista Retail. */
+export declare enum ReportFormatEnum {
+    CSV = "CSV",
+    PDF = "PDF"
+}

package/bin/retailWizard/enums/ReportFormatEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportFormatEnum = void 0;
+/** Formato de salida de un reporte del Admin VL. SureKeep Fase 3 — pista Retail. */
+var ReportFormatEnum;
+(function (ReportFormatEnum) {
+    ReportFormatEnum["CSV"] = "CSV";
+    ReportFormatEnum["PDF"] = "PDF";
+})(ReportFormatEnum || (exports.ReportFormatEnum = ReportFormatEnum = {}));

package/bin/retailWizard/enums/ReportPeriodicityEnum.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Periodicidad de un reporte del Admin VL. Los diarios y semanales corren por cron; los mensuales
+ * requieren corrida manual (M6 §5.1). SureKeep Fase 3 — pista Retail.
+ */
+export declare enum ReportPeriodicityEnum {
+    DAILY = "DAILY",
+    WEEKLY = "WEEKLY",
+    MONTHLY = "MONTHLY"
+}

package/bin/retailWizard/enums/ReportPeriodicityEnum.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportPeriodicityEnum = void 0;
+/**
+ * Periodicidad de un reporte del Admin VL. Los diarios y semanales corren por cron; los mensuales
+ * requieren corrida manual (M6 §5.1). SureKeep Fase 3 — pista Retail.
+ */
+var ReportPeriodicityEnum;
+(function (ReportPeriodicityEnum) {
+    ReportPeriodicityEnum["DAILY"] = "DAILY";
+    ReportPeriodicityEnum["WEEKLY"] = "WEEKLY";
+    ReportPeriodicityEnum["MONTHLY"] = "MONTHLY";
+})(ReportPeriodicityEnum || (exports.ReportPeriodicityEnum = ReportPeriodicityEnum = {}));

package/bin/retailWizard/enums/ReportRunStatusEnum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado de una corrida de reporte. La generación es ASÍNCRONA: el `POST .../run` devuelve `QUEUED` y
+ * el front poletea el listado. SureKeep Fase 3 — pista Retail.
+ *
+ * Es async desde el día uno por el límite de 29 s de API Gateway: un reporte de red completa no entra
+ * en una respuesta síncrona. Mismo error que ya se corrigió en el cierre de corte de comisiones.
+ *
+ * QUEUED - Encolada, sin arrancar.
+ * RUNNING - Generándose.
+ * READY - Lista para descargar (`downloadUrl` presente).
+ * FAILED - Falló; `failureReason` explica por qué.
+ */
+export declare enum ReportRunStatusEnum {
+    QUEUED = "QUEUED",
+    RUNNING = "RUNNING",
+    READY = "READY",
+    FAILED = "FAILED"
+}

package/bin/retailWizard/enums/ReportRunStatusEnum.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportRunStatusEnum = void 0;
+/**
+ * Estado de una corrida de reporte. La generación es ASÍNCRONA: el `POST .../run` devuelve `QUEUED` y
+ * el front poletea el listado. SureKeep Fase 3 — pista Retail.
+ *
+ * Es async desde el día uno por el límite de 29 s de API Gateway: un reporte de red completa no entra
+ * en una respuesta síncrona. Mismo error que ya se corrigió en el cierre de corte de comisiones.
+ *
+ * QUEUED - Encolada, sin arrancar.
+ * RUNNING - Generándose.
+ * READY - Lista para descargar (`downloadUrl` presente).
+ * FAILED - Falló; `failureReason` explica por qué.
+ */
+var ReportRunStatusEnum;
+(function (ReportRunStatusEnum) {
+    ReportRunStatusEnum["QUEUED"] = "QUEUED";
+    ReportRunStatusEnum["RUNNING"] = "RUNNING";
+    ReportRunStatusEnum["READY"] = "READY";
+    ReportRunStatusEnum["FAILED"] = "FAILED";
+})(ReportRunStatusEnum || (exports.ReportRunStatusEnum = ReportRunStatusEnum = {}));

package/bin/retailWizard/enums/SaleExceptionDecisionEnum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Veredicto del Admin VL al resolver una excepción. Es un enum PROPIO y no un subconjunto de
+ * `SaleExceptionStatusEnum`: el request expresa una DECISIÓN («apruébala»), no un estado destino, y
+ * mezclarlos dejaría al caller mandar `APPLIED` o `NEW` en un endpoint que no los admite.
+ * SureKeep Fase 3 — pista Retail.
+ */
+export declare enum SaleExceptionDecisionEnum {
+    APPROVE = "APPROVE",
+    REJECT = "REJECT"
+}

package/bin/retailWizard/enums/SaleExceptionDecisionEnum.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SaleExceptionDecisionEnum = void 0;
+/**
+ * Veredicto del Admin VL al resolver una excepción. Es un enum PROPIO y no un subconjunto de
+ * `SaleExceptionStatusEnum`: el request expresa una DECISIÓN («apruébala»), no un estado destino, y
+ * mezclarlos dejaría al caller mandar `APPLIED` o `NEW` en un endpoint que no los admite.
+ * SureKeep Fase 3 — pista Retail.
+ */
+var SaleExceptionDecisionEnum;
+(function (SaleExceptionDecisionEnum) {
+    SaleExceptionDecisionEnum["APPROVE"] = "APPROVE";
+    SaleExceptionDecisionEnum["REJECT"] = "REJECT";
+})(SaleExceptionDecisionEnum || (exports.SaleExceptionDecisionEnum = SaleExceptionDecisionEnum = {}));