@fiado/type-kit 3.260.0 → 3.262.0

package/_test_/unit/platformRbac/PasswordPolicyInput.test.ts

@@ -0,0 +1,58 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+
+import { PasswordPolicyInput } from '../../../src/platformRbac/dtos/PasswordPolicyInput';
+
+// DEC-RBAC-111: política de contraseña per-tenant. Los 5 campos son opcionales — un campo ausente
+// cae a la plantilla de la app y, de ahí, a la policy global del lambda.
+describe('PasswordPolicyInput', () => {
+    it('acepta los 5 campos válidos', () => {
+        const dto = plainToInstance(PasswordPolicyInput, {
+            minLength: 16,
+            requireUppercase: true,
+            requireLowercase: true,
+            requireNumber: true,
+            requireSymbol: true,
+        });
+        expect(validateSync(dto)).toHaveLength(0);
+    });
+
+    it('acepta el objeto vacío (todos los campos son opcionales)', () => {
+        expect(validateSync(plainToInstance(PasswordPolicyInput, {}))).toHaveLength(0);
+    });
+
+    // Cognito acepta PasswordPolicy.MinimumLength en 6..99. Fuera de ese rango, CreateUserPool tira
+    // InvalidParameterException DESPUÉS de que la saga de onboarding ya escribió la ficha del tenant
+    // en estado 'provisioning' — o sea el fallo cae en la rama de compensación. Se ataja acá.
+    it.each([5, 100, 150])('rechaza minLength %i (fuera del rango 6-99 de Cognito)', (minLength) => {
+        const errors = validateSync(plainToInstance(PasswordPolicyInput, { minLength }));
+        expect(errors).toHaveLength(1);
+        expect(errors[0].property).toBe('minLength');
+    });
+
+    it.each([6, 99])('acepta minLength %i (los bordes del rango de Cognito)', (minLength) => {
+        expect(validateSync(plainToInstance(PasswordPolicyInput, { minLength }))).toHaveLength(0);
+    });
+
+    it('rechaza minLength no entero', () => {
+        const errors = validateSync(plainToInstance(PasswordPolicyInput, { minLength: 12.5 }));
+        expect(errors).toHaveLength(1);
+        expect(errors[0].property).toBe('minLength');
+    });
+
+    it('rechaza un require* que no es booleano', () => {
+        const errors = validateSync(
+            plainToInstance(PasswordPolicyInput, { requireSymbol: 'sí' as unknown as boolean }),
+        );
+        expect(errors).toHaveLength(1);
+        expect(errors[0].property).toBe('requireSymbol');
+    });
+
+    // El piso (que la policy no sea MÁS DÉBIL que la global del lambda) NO se valida acá a propósito:
+    // depende de env vars del lambda, así que ponerlo también en el type-kit sería una segunda fuente
+    // de verdad en otro repo, que driftea en cuanto alguien cambia la env var.
+    it('NO rechaza una policy débil: el piso lo decide el lambda, no el type-kit', () => {
+        expect(validateSync(plainToInstance(PasswordPolicyInput, { minLength: 6 }))).toHaveLength(0);
+    });
+});

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

@@ -0,0 +1,68 @@
+import { SaleTypeEnum } from '../../../src/retailWizard/enums/SaleTypeEnum';
+import { ExternalProviderEnum } from '../../../src/retailWizard/enums/ExternalProviderEnum';
+import { SaleFinancierEnum } from '../../../src/retailWizard/enums/SaleFinancierEnum';
+import {
+  financierOfSale,
+  isSureKeepFinanced,
+  isExternallyFinanced,
+} from '../../../src/retailWizard/helpers/saleFinancier';
+
+describe('financierOfSale', () => {
+  it('el contado no tiene financiera', () => {
+    expect(financierOfSale({ type: SaleTypeEnum.CASH, externalProvider: null })).toBe(
+      SaleFinancierEnum.NONE,
+    );
+  });
+
+  it('el crédito propio es SUREKEEP', () => {
+    expect(financierOfSale({ type: SaleTypeEnum.CREDIT, externalProvider: null })).toBe(
+      SaleFinancierEnum.SUREKEEP,
+    );
+  });
+
+  it.each([
+    [ExternalProviderEnum.PAYJOY, SaleFinancierEnum.PAYJOY],
+    [ExternalProviderEnum.CREDIYA, SaleFinancierEnum.CREDIYA],
+    [ExternalProviderEnum.LESPAGO, SaleFinancierEnum.LESPAGO],
+    [ExternalProviderEnum.INNOVA, SaleFinancierEnum.INNOVA],
+  ])('la derivación a %s mapea a su financiera', (provider, expected) => {
+    expect(financierOfSale({ type: SaleTypeEnum.EXTERNAL_REFERRAL, externalProvider: provider })).toBe(
+      expected,
+    );
+  });
+
+  it('una derivación sin proveedor cae en NONE, no revienta (ventas viejas sin el campo)', () => {
+    expect(financierOfSale({ type: SaleTypeEnum.EXTERNAL_REFERRAL, externalProvider: null })).toBe(
+      SaleFinancierEnum.NONE,
+    );
+  });
+
+  it('el crédito propio gana sobre un externalProvider colado en la fila', () => {
+    expect(
+      financierOfSale({ type: SaleTypeEnum.CREDIT, externalProvider: ExternalProviderEnum.PAYJOY }),
+    ).toBe(SaleFinancierEnum.SUREKEEP);
+  });
+});
+
+describe('particiones de los pills del Admin VL', () => {
+  it('SUREKEEP y externas son disjuntas', () => {
+    const surekeep = { type: SaleTypeEnum.CREDIT, externalProvider: null };
+    expect(isSureKeepFinanced(surekeep)).toBe(true);
+    expect(isExternallyFinanced(surekeep)).toBe(false);
+  });
+
+  it('una externa cuenta como externa y no como SureKeep', () => {
+    const externa = {
+      type: SaleTypeEnum.EXTERNAL_REFERRAL,
+      externalProvider: ExternalProviderEnum.CREDIYA,
+    };
+    expect(isExternallyFinanced(externa)).toBe(true);
+    expect(isSureKeepFinanced(externa)).toBe(false);
+  });
+
+  it('el contado NO cuenta en ninguna de las dos: no tiene financiera', () => {
+    const contado = { type: SaleTypeEnum.CASH, externalProvider: null };
+    expect(isSureKeepFinanced(contado)).toBe(false);
+    expect(isExternallyFinanced(contado)).toBe(false);
+  });
+});

package/bin/benefitCenter/enums/BenefitFlowEnum.d.ts

@@ -0,0 +1,11 @@
+export declare enum BenefitFlowEnum {
+    TOPUPS = "TOPUPS",
+    BILL_PAYMENT = "BILL_PAYMENT",
+    CREDIT = "CREDIT",
+    INSURANCE = "INSURANCE",
+    DONATION = "DONATION",
+    PHARMACY = "PHARMACY",
+    REMITTANCE = "REMITTANCE",
+    /** Fondeo de wallet PCF con efectivo via provider externo (Equality/Passport, OpenPay, …) — spec 13. */
+    WALLET_FUNDING = "WALLET_FUNDING"
+}

package/bin/benefitCenter/enums/BenefitFlowEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenefitFlowEnum = void 0;
+var BenefitFlowEnum;
+(function (BenefitFlowEnum) {
+    BenefitFlowEnum["TOPUPS"] = "TOPUPS";
+    BenefitFlowEnum["BILL_PAYMENT"] = "BILL_PAYMENT";
+    BenefitFlowEnum["CREDIT"] = "CREDIT";
+    BenefitFlowEnum["INSURANCE"] = "INSURANCE";
+    BenefitFlowEnum["DONATION"] = "DONATION";
+    BenefitFlowEnum["PHARMACY"] = "PHARMACY";
+    BenefitFlowEnum["REMITTANCE"] = "REMITTANCE";
+    /** Fondeo de wallet PCF con efectivo via provider externo (Equality/Passport, OpenPay, …) — spec 13. */
+    BenefitFlowEnum["WALLET_FUNDING"] = "WALLET_FUNDING";
+})(BenefitFlowEnum || (exports.BenefitFlowEnum = BenefitFlowEnum = {}));

package/bin/identity/dtos/PeopleResponse.d.ts

@@ -102,7 +102,16 @@ export declare class PeopleResponse {
         externalReferenceId: string | null;
         SSN_ITINRequired: boolean | null;
         hasSSN_ITIN: boolean | null;
+        /**
+         * @deprecated Typo histórico (tres `p`). NADIE escribe este campo:
+         * fiado-identity-lambda persiste `geoApproved` (una `p`), que es lo que
+         * está en DynamoDB. Quien lea este campo obtiene siempre `undefined`.
+         * Usar `geoApproved`. Se conserva solo para no romper a los consumidores
+         * que todavía lo referencian.
+         */
         geoAppproved?: boolean | null;
+        /** Geolocalización aprobada. `null` = no evaluada; solo `false` bloquea. */
+        geoApproved?: boolean | null;
         cnbvManualApproval?: ManualApproval | null;
         minorManualApproval?: ManualApproval | null;
     };

package/bin/identity/enums/SelfieSourceEnum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Con qué criterio se resolvió cuál archivo de S3 es la selfie del usuario.
+ * Le dice al consumidor qué tan confiable es el match antes de mandarla a un facematch.
+ */
+export declare enum SelfieSourceEnum {
+    /** Matcheó el verificationId de la verificación vigente en People. */
+    VERIFICATION = "VERIFICATION",
+    /** No hubo match por verificación: se tomó el archivo de selfie más reciente del bucket. */
+    LATEST = "LATEST"
+}

package/bin/identity/enums/SelfieSourceEnum.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SelfieSourceEnum = void 0;
+/**
+ * Con qué criterio se resolvió cuál archivo de S3 es la selfie del usuario.
+ * Le dice al consumidor qué tan confiable es el match antes de mandarla a un facematch.
+ */
+var SelfieSourceEnum;
+(function (SelfieSourceEnum) {
+    /** Matcheó el verificationId de la verificación vigente en People. */
+    SelfieSourceEnum["VERIFICATION"] = "VERIFICATION";
+    /** No hubo match por verificación: se tomó el archivo de selfie más reciente del bucket. */
+    SelfieSourceEnum["LATEST"] = "LATEST";
+})(SelfieSourceEnum || (exports.SelfieSourceEnum = SelfieSourceEnum = {}));

package/bin/platformRbac/application/Application.d.ts

@@ -44,6 +44,23 @@ export interface ApplicationDefaults {
      * UsernameAttributes del pool): true ⇒ pool con ['email','phone_number']. Heredado al tenant.
      */
     allowSecondary?: boolean;
+    /**
+     * DEC-RBAC-111: política de contraseña que heredan los tenants creados desde esta aplicación.
+     *
+     * TOP-LEVEL (hermano de `autoregister`), NO dentro de `securityPolicy`: en la ficha del tenant
+     * ese sub-objeto lo reescribe entero el PUT de security-policy, y acá se mantiene la simetría.
+     *
+     * La herencia ocurre UNA sola vez, en el onboarding: cambiar este default después NO re-escribe
+     * la policy de los tenants ya creados, solo aplica a los futuros. Los 5 campos son opcionales;
+     * `tempValidityDays` no es per-tenant y por eso no está.
+     */
+    passwordPolicy?: {
+        minLength?: number;
+        requireUppercase?: boolean;
+        requireLowercase?: boolean;
+        requireNumber?: boolean;
+        requireSymbol?: boolean;
+    };
 }
 export interface SeedRole {
     roleId: string;

package/bin/platformRbac/dtos/CreateTenantRequest.d.ts

@@ -1,4 +1,5 @@
 import { TokenValidationMode } from '../enums/TokenValidationMode';
+import { PasswordPolicyInput } from './PasswordPolicyInput';
 /**
  * Punto inicial de la política 2FA elegido en el alta del tenant (DEC-RBAC-064). Para el CREATE
  * ambos campos son OPCIONALES: es un override del punto de partida — si se omite, el onboarding
@@ -47,4 +48,15 @@ export declare class CreateTenantRequest {
      * onboarding hereda `app.defaults.securityPolicy`. Aditivo, no rompe altas existentes.
      */
     securityPolicy?: CreateTenantSecurityPolicy;
+    /**
+     * DEC-RBAC-111: política de contraseña del tenant. Opcional: ausente ⇒ hereda
+     * `app.defaults.passwordPolicy` y, si tampoco está, la policy global del lambda.
+     *
+     * TOP-LEVEL a propósito, NO dentro de `securityPolicy`: ese sub-objeto lo reescribe entero el
+     * PUT de security-policy desde una lectura cacheada, y se llevaría puesta la passwordPolicy.
+     *
+     * INMUTABLE después del alta: alimenta la política nativa del user pool de Cognito, y no existe
+     * un update de pool (ver TD-RBAC-138 del platform-rbac-business).
+     */
+    passwordPolicy?: PasswordPolicyInput;
 }

package/bin/platformRbac/dtos/CreateTenantRequest.js

@@ -13,6 +13,7 @@ exports.CreateTenantRequest = exports.CreateTenantSecurityPolicy = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const TokenValidationMode_1 = require("../enums/TokenValidationMode");
+const PasswordPolicyInput_1 = require("./PasswordPolicyInput");
 /**
  * Punto inicial de la política 2FA elegido en el alta del tenant (DEC-RBAC-064). Para el CREATE
  * ambos campos son OPCIONALES: es un override del punto de partida — si se omite, el onboarding
@@ -106,3 +107,10 @@ __decorate([
     (0, class_transformer_1.Type)(() => CreateTenantSecurityPolicy),
     __metadata("design:type", CreateTenantSecurityPolicy)
 ], CreateTenantRequest.prototype, "securityPolicy", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => PasswordPolicyInput_1.PasswordPolicyInput),
+    __metadata("design:type", PasswordPolicyInput_1.PasswordPolicyInput)
+], CreateTenantRequest.prototype, "passwordPolicy", void 0);

package/bin/platformRbac/dtos/PasswordPolicyInput.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DEC-RBAC-111: política de complejidad de contraseña de un tenant.
+ *
+ * Los 5 campos son OPCIONALES: un campo ausente cae a la plantilla de la aplicación
+ * (`ApplicationDefaults.passwordPolicy`) y, de ahí, a la policy global del lambda.
+ *
+ * Se usa en dos lugares, siempre TOP-LEVEL (nunca dentro de `securityPolicy`):
+ *  - `CreateTenantRequest.passwordPolicy` — override al crear el tenant.
+ *  - `ApplicationDefaults.passwordPolicy` — default de la plantilla que el tenant hereda.
+ *
+ * `tempValidityDays` NO está acá a propósito: la validez de la contraseña temporal no es per-tenant
+ * (es el único campo de la policy que no afecta la fuerza de la contraseña). Sale siempre de la
+ * env var global del lambda.
+ *
+ * El rango 6..99 de `minLength` es el que admite `PasswordPolicy.MinimumLength` de Cognito. Se valida
+ * ACÁ para que un valor fuera de rango se rechace en el borde: si llegara a `CreateUserPool`, la
+ * `InvalidParameterException` caería con la ficha del tenant ya escrita en estado 'provisioning',
+ * o sea dentro de la rama de compensación de la saga de onboarding.
+ *
+ * OJO: acá NO se valida el PISO (que la policy no sea más débil que la global). Ese piso depende de
+ * env vars del lambda; declararlo también en el type-kit sería una segunda fuente de verdad, en otro
+ * repo, que driftea en cuanto alguien cambia la env var. Lo decide el lambda.
+ */
+export declare class PasswordPolicyInput {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumber?: boolean;
+    requireSymbol?: boolean;
+}

package/bin/platformRbac/dtos/PasswordPolicyInput.js

@@ -0,0 +1,72 @@
+"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.PasswordPolicyInput = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * DEC-RBAC-111: política de complejidad de contraseña de un tenant.
+ *
+ * Los 5 campos son OPCIONALES: un campo ausente cae a la plantilla de la aplicación
+ * (`ApplicationDefaults.passwordPolicy`) y, de ahí, a la policy global del lambda.
+ *
+ * Se usa en dos lugares, siempre TOP-LEVEL (nunca dentro de `securityPolicy`):
+ *  - `CreateTenantRequest.passwordPolicy` — override al crear el tenant.
+ *  - `ApplicationDefaults.passwordPolicy` — default de la plantilla que el tenant hereda.
+ *
+ * `tempValidityDays` NO está acá a propósito: la validez de la contraseña temporal no es per-tenant
+ * (es el único campo de la policy que no afecta la fuerza de la contraseña). Sale siempre de la
+ * env var global del lambda.
+ *
+ * El rango 6..99 de `minLength` es el que admite `PasswordPolicy.MinimumLength` de Cognito. Se valida
+ * ACÁ para que un valor fuera de rango se rechace en el borde: si llegara a `CreateUserPool`, la
+ * `InvalidParameterException` caería con la ficha del tenant ya escrita en estado 'provisioning',
+ * o sea dentro de la rama de compensación de la saga de onboarding.
+ *
+ * OJO: acá NO se valida el PISO (que la policy no sea más débil que la global). Ese piso depende de
+ * env vars del lambda; declararlo también en el type-kit sería una segunda fuente de verdad, en otro
+ * repo, que driftea en cuanto alguien cambia la env var. Lo decide el lambda.
+ */
+class PasswordPolicyInput {
+}
+exports.PasswordPolicyInput = PasswordPolicyInput;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(6),
+    (0, class_validator_1.Max)(99),
+    __metadata("design:type", Number)
+], PasswordPolicyInput.prototype, "minLength", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PasswordPolicyInput.prototype, "requireUppercase", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PasswordPolicyInput.prototype, "requireLowercase", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PasswordPolicyInput.prototype, "requireNumber", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PasswordPolicyInput.prototype, "requireSymbol", void 0);

package/bin/platformRbac/index.d.ts

@@ -27,6 +27,7 @@ export * from './dtos/AuthorizeRequest';
 export * from './dtos/AuthorizeResponse';
 export * from './dtos/CreateTenantRequest';
 export type { CreateTenantResponse } from './dtos/CreateTenantResponse';
+export * from './dtos/PasswordPolicyInput';
 export type { TenantStatus } from './dtos/TenantStatus';
 export type { VerifyTenantInfraResponse } from './dtos/VerifyTenantInfraResponse';
 export type { TenantDetailResponse } from './dtos/TenantDetailResponse';

package/bin/platformRbac/index.js

@@ -63,6 +63,9 @@ __exportStar(require("./dtos/AuthorizeResponse"), exports);
 // F-11 — onboarding de tenant (POST backoffice createTenant). CreateTenantRequest lleva
 // decoradores class-validator → export de valor; CreateTenantResponse es interface → type-only.
 __exportStar(require("./dtos/CreateTenantRequest"), exports);
+// DEC-RBAC-111: policy de contraseña per-tenant. Lleva decoradores class-validator → export de valor.
+// La consumen CreateTenantRequest (override del alta) y ApplicationDefaults (default de la plantilla).
+__exportStar(require("./dtos/PasswordPolicyInput"), exports);
 // MFA por tenant — methodsAllowed (value-set 'EMAIL'|'TOTP', TD-RBAC-071, DEC-095).
 // UpdateTenantSecurityPolicyRequest lleva decoradores class-validator → export de valor;
 // TenantSecurityPolicyResponse es interface plain → type-only.

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

@@ -0,0 +1,54 @@
+import type { SaleExceptionTypeEnum } from '../enums/SaleExceptionTypeEnum';
+import type { SaleExceptionStatusEnum } from '../enums/SaleExceptionStatusEnum';
+import type { SaleExceptionEvent } from './SaleExceptionEvent';
+import type { SaleExceptionPayload } from './SaleExceptionPayload';
+/**
+ * Excepción de venta (`<T>RetailSaleException_GT`, pk `RETAILER#<retailerId>` ·
+ * sk `EXCEPTION#<createdAt>#<exceptionId>`, CERO GSIs). Bandeja del Admin VL, M6 §5.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El `status` NO va en el sort key: el sk es inmutable en DynamoDB y el estado recorre
+ * `NEW → IN_REVIEW → APPROVED → APPLIED`. Meterlo ahí obligaría a borrar y reescribir el ítem en cada
+ * transición, perdiendo atomicidad y estabilidad del `exceptionId`. El filtro por estado se hace en
+ * memoria; son eventos raros.
+ *
+ * 🔴 **Hueco declarado (DEC-034):** `CAPTURE_FIX`, `BACKDATING` y `PRICE_OVERRIDE` mutan la venta
+ * después de cerrada, y el motor de comisiones solo escucha `SaleCompleted` / `SaleCancelled`. En el
+ * primer corte las excepciones **NO re-liquidan comisión**. Se ataca en F4 con un `SaleAmendedV1`.
+ */
+export interface SaleException {
+    exceptionId: string;
+    retailerId: string;
+    storeId: string;
+    /** `null` en las excepciones generales, que no cuelgan de una venta puntual. */
+    saleId: string | null;
+    type: SaleExceptionTypeEnum;
+    status: SaleExceptionStatusEnum;
+    /** userId de quien la levantó (normalmente el vendedor). */
+    requestedBy: string;
+    /** Nombre para mostrar, congelado al alta. `null` si no se pudo resolver. */
+    requestedByName: string | null;
+    /** ISO-8601. */
+    requestedAt: string;
+    /** OBLIGATORIA. Es lo que hace auditable la excepción. */
+    justification: string;
+    /**
+     * Impacto económico en centavos, con signo: positivo si la excepción suma (devolución al cliente,
+     * reemplazo), negativo si resta (descuento autorizado). `null` cuando no aplica.
+     */
+    impactCents: number | null;
+    payload: SaleExceptionPayload;
+    /** userId del Admin VL que aprobó o rechazó. `null` mientras esté sin resolver. */
+    resolvedBy: string | null;
+    resolvedByName: string | null;
+    /** ISO-8601. `null` mientras esté sin resolver. */
+    resolvedAt: string | null;
+    /** Resolución OBLIGATORIA al aprobar o rechazar. `null` mientras esté sin resolver. */
+    resolution: string | null;
+    /** Hilo de solicitud, notas y resolución, en orden cronológico ascendente. */
+    timeline: SaleExceptionEvent[];
+    createdBy: string;
+    updatedBy: string;
+    createdAt: number;
+    updatedAt: number;
+}

package/bin/retailWizard/dtos/SaleException.js

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

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

@@ -0,0 +1,18 @@
+import type { SaleExceptionEventKindEnum } from '../enums/SaleExceptionEventKindEnum';
+/**
+ * Una entrada del timeline de una excepción: el hilo de solicitud, notas y resolución que la pantalla
+ * de Excepciones dibuja bajo la ficha. SureKeep Fase 3 — pista Retail.
+ *
+ * Va EMBEBIDO en el ítem de `RetailSaleException_GT`, no en una tabla aparte: son pocos eventos por
+ * excepción, se leen siempre junto con la ficha y nunca se consultan por su cuenta.
+ */
+export interface SaleExceptionEvent {
+    /** ISO-8601. */
+    at: string;
+    kind: SaleExceptionEventKindEnum;
+    /** userId del autor; `system` si lo escribió un proceso interno. */
+    authorId: string;
+    /** Nombre para mostrar, congelado al escribir el evento. `null` si no se pudo resolver. */
+    authorName: string | null;
+    body: string;
+}

package/bin/retailWizard/dtos/SaleExceptionEvent.js

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

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

@@ -0,0 +1,19 @@
+/**
+ * Lo que la excepción PIDE cambiar en la venta. Todos los campos son opcionales porque cada tipo usa
+ * los suyos: `CAPTURE_FIX` manda `sku`, `PRICE_OVERRIDE` manda `amountCents`, `BACKDATING` manda
+ * `soldAt`, `EXTENDED_WARRANTY` manda `imei`. `LATE_CANCEL` no manda ninguno.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Es un shape TIPADO y no un objeto libre a propósito: el payload cruza el borde HTTP y un
+ * `Record<string, unknown>` ahí deja al front sin contrato y al validador sin nada que validar.
+ */
+export interface SaleExceptionPayload {
+    /** SKU correcto (CAPTURE_FIX). */
+    sku?: string;
+    /** Monto correcto en centavos (PRICE_OVERRIDE, CAPTURE_FIX). */
+    amountCents?: number;
+    /** Fecha real de la venta, ISO-8601 (BACKDATING). */
+    soldAt?: string;
+    /** IMEI del equipo de reemplazo (EXTENDED_WARRANTY). */
+    imei?: string;
+}

package/bin/retailWizard/dtos/SaleExceptionPayload.js

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

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