@fiado/type-kit 3.598.0 → 3.599.0

package/_test_/unit/retailIntegration/reconciliationPreviewContracts.test.ts

@@ -0,0 +1,94 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+  type GetCatalogReconciliationResponse,
+  type GetOrgReconciliationResponse,
+  RECONCILIATION_PREVIEW_MAX_ITEMS,
+  type ReconciliationPreview,
+  ReconciliationEntityEnum,
+  ReconciliationRunStatusEnum,
+  ReconciliationTriggerEnum,
+  RetailEventRejectCodeEnum,
+  type RetailEventResult,
+  RetailEventResultEnum,
+  StartCatalogReconciliationRequest,
+  StartOrgReconciliationRequest,
+} from '../../../src/retailIntegration';
+
+function propsWithErrors<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+  return validateSync(plainToInstance(cls, payload)).map((e) => e.property);
+}
+
+function exposed<T extends object>(cls: ClassConstructor<T>, payload: object): T {
+  return plainToInstance(cls, payload, { excludeExtraneousValues: true });
+}
+
+describe.each([
+  ['StartOrgReconciliationRequest', StartOrgReconciliationRequest as ClassConstructor<object>, 'STORES'],
+  ['StartCatalogReconciliationRequest', StartCatalogReconciliationRequest as ClassConstructor<object>, 'CATALOG'],
+] as const)('%s.dryRun', (_name, cls, entity) => {
+  it('es opcional', () => {
+    expect(propsWithErrors(cls, { entity })).toEqual([]);
+  });
+
+  it.each([true, false])('acepta %p', (dryRun) => {
+    expect(propsWithErrors(cls, { entity, dryRun })).toEqual([]);
+  });
+
+  it.each(['true', 1, 'yes'])('rechaza %p', (dryRun) => {
+    expect(propsWithErrors(cls, { entity, dryRun })).toContain('dryRun');
+  });
+
+  it('sobrevive a excludeExtraneousValues', () => {
+    expect({ ...exposed(cls, { entity, dryRun: true }) }).toMatchObject({ entity, dryRun: true });
+  });
+});
+
+describe('vista previa de la revisión', () => {
+  const counts = { seen: 3, created: 1, updated: 1, deactivated: 1, reactivated: 0, skipped: 0 };
+  const preview: ReconciliationPreview = {
+    created: [{ id: 's-1', label: 'Tienda Centro' }],
+    updated: [{ id: 'SKU-1', label: 'Equipo X', fields: ['price'] }],
+    deactivated: [{ id: '356938035643809', storeId: 's-1' }],
+    reactivated: [],
+    truncated: false,
+  };
+
+  it('el tope por lista es 200', () => {
+    expect(RECONCILIATION_PREVIEW_MAX_ITEMS).toBe(200);
+  });
+
+  it('las respuestas del GET llevan dryRun y preview', () => {
+    const org: GetOrgReconciliationResponse = {
+      runId: 'run-1',
+      retailerId: 'r-1',
+      entity: ReconciliationEntityEnum.STORES,
+      status: ReconciliationRunStatusEnum.COMPLETE,
+      trigger: ReconciliationTriggerEnum.MANUAL,
+      startedAt: '2026-10-27T10:00:00.000Z',
+      pagesProcessed: 1,
+      counts,
+      dryRun: true,
+      preview,
+    };
+    const catalog: GetCatalogReconciliationResponse = { ...org, entity: ReconciliationEntityEnum.INVENTORY };
+    expect(org.preview?.updated[0].fields).toEqual(['price']);
+    expect(catalog.dryRun).toBe(true);
+  });
+});
+
+describe('RetailEventResult.errors', () => {
+  it('lista todos los renglones malos de un REJECTED', () => {
+    const result: RetailEventResult = {
+      eventId: 'e-1',
+      result: RetailEventResultEnum.REJECTED,
+      code: RetailEventRejectCodeEnum.INVALID_IMEI,
+      errors: [
+        { index: 0, kind: 'piece', identifier: '123', sku: 'SKU-1', storeId: 's-1', code: RetailEventRejectCodeEnum.INVALID_IMEI },
+        { index: 2, kind: 'stock', sku: 'SKU-2', code: RetailEventRejectCodeEnum.SKU_NOT_STOCKABLE },
+      ],
+    };
+    expect(result.errors?.map((e) => e.index)).toEqual([0, 2]);
+  });
+});

package/bin/retailIntegration/dtos/GetReconciliationResponses.d.ts

@@ -1,6 +1,7 @@
 import type { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
 import type { ReconciliationRunStatusEnum } from '../enums/ReconciliationRunStatusEnum';
 import type { ReconciliationTriggerEnum } from '../enums/ReconciliationTriggerEnum';
+import type { ReconciliationPreview } from './ReconciliationPreview';
 import type { ReconciliationRunCounts } from './ReconciliationRunCounts';
 /** Respuesta 200 de GET .../reconciliations/{runId} en org (backofficeGetOrgReconciliation). */
 export interface GetOrgReconciliationResponse {
@@ -15,6 +16,10 @@ export interface GetOrgReconciliationResponse {
     finishedAt?: string;
     pagesProcessed: number;
     counts: ReconciliationRunCounts;
+    /** La corrida fue en modo prueba y no escribió nada. */
+    dryRun?: boolean;
+    /** Vista previa de una corrida en modo prueba. */
+    preview?: ReconciliationPreview;
 }
 /** Respuesta 200 de GET .../reconciliations/{runId} en catalog (backofficeGetCatalogReconciliation). */
 export interface GetCatalogReconciliationResponse {
@@ -40,4 +45,8 @@ export interface GetCatalogReconciliationResponse {
     /** Fin ISO de la ventana revisada en movimientos. */
     movementsTo?: string;
     counts: ReconciliationRunCounts;
+    /** La corrida fue en modo prueba y no escribió nada. */
+    dryRun?: boolean;
+    /** Vista previa de una corrida en modo prueba. */
+    preview?: ReconciliationPreview;
 }

package/bin/retailIntegration/dtos/ReconciliationPreview.d.ts

@@ -0,0 +1,21 @@
+/** Tope de renglones por lista de la vista previa; si se pasa, `truncated` es true. */
+export declare const RECONCILIATION_PREVIEW_MAX_ITEMS = 200;
+/** Renglón de la vista previa: `id` es storeId, retailUserId, sku o identifier según la entidad. */
+export interface ReconciliationPreviewItem {
+    id: string;
+    /** Nombre legible para mostrar en el backoffice. */
+    label?: string;
+    /** Campos que cambiarían, solo en `updated`. */
+    fields?: string[];
+    /** Tienda de la pieza en inventario. */
+    storeId?: string;
+}
+/** Lo que haría una corrida en modo prueba (`dryRun`), sin escribir nada. */
+export interface ReconciliationPreview {
+    created: ReconciliationPreviewItem[];
+    updated: ReconciliationPreviewItem[];
+    deactivated: ReconciliationPreviewItem[];
+    reactivated: ReconciliationPreviewItem[];
+    /** Alguna lista se cortó en RECONCILIATION_PREVIEW_MAX_ITEMS. */
+    truncated: boolean;
+}

package/bin/retailIntegration/dtos/ReconciliationPreview.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECONCILIATION_PREVIEW_MAX_ITEMS = void 0;
+/** Tope de renglones por lista de la vista previa; si se pasa, `truncated` es true. */
+exports.RECONCILIATION_PREVIEW_MAX_ITEMS = 200;

package/bin/retailIntegration/dtos/RetailEventResult.d.ts

@@ -1,9 +1,21 @@
+import type { RetailEventRejectCodeEnum } from '../enums/RetailEventRejectCodeEnum';
 import { RetailEventResultEnum } from '../enums/RetailEventResultEnum';
+/** Renglón inválido de un evento de inventario; `index` es 0-based en `pieces` o en `stock` según `kind`. */
+export interface RetailEventItemError {
+    index: number;
+    kind?: 'piece' | 'stock';
+    identifier?: string;
+    sku?: string;
+    storeId?: string;
+    code: RetailEventRejectCodeEnum;
+}
 /** Resultado de un evento; `code` explica un `REJECTED` y es `null` en los demás. */
 export interface RetailEventResult {
     eventId: string;
     result: RetailEventResultEnum;
     code: string | null;
+    /** Todos los renglones inválidos de un `REJECTED` de inventario, no solo el primero. */
+    errors?: RetailEventItemError[];
 }
 export type ReceiveStoreEventResponse = RetailEventResult;
 export type ReceiveRetailUserEventResponse = RetailEventResult;

package/bin/retailIntegration/dtos/StartCatalogReconciliationRequest.d.ts

@@ -4,6 +4,8 @@ export declare class StartCatalogReconciliationRequest {
     entity: ReconciliationEntityEnum.CATALOG | ReconciliationEntityEnum.INVENTORY;
     /** Tienda a revisar en inventario; sin ella se revisan todas las del padrón. */
     storeId?: string;
+    /** Modo prueba: calcula la vista previa sin escribir nada. */
+    dryRun?: boolean;
 }
 /** Respuesta 202 del arranque en catalog. */
 export interface StartCatalogReconciliationResponse {

package/bin/retailIntegration/dtos/StartCatalogReconciliationRequest.js

@@ -29,3 +29,9 @@ __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], StartCatalogReconciliationRequest.prototype, "storeId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], StartCatalogReconciliationRequest.prototype, "dryRun", void 0);

package/bin/retailIntegration/dtos/StartOrgReconciliationRequest.d.ts

@@ -2,6 +2,8 @@ import { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
 /** Body de POST /backoffice/retailers/{retailerId}/reconciliations en org (backofficeStartOrgReconciliation). */
 export declare class StartOrgReconciliationRequest {
     entity: ReconciliationEntityEnum.STORES | ReconciliationEntityEnum.USERS;
+    /** Modo prueba: calcula la vista previa sin escribir nada. */
+    dryRun?: boolean;
 }
 /** Respuesta 202 del arranque en org. */
 export interface StartOrgReconciliationResponse {

package/bin/retailIntegration/dtos/StartOrgReconciliationRequest.js

@@ -22,3 +22,9 @@ __decorate([
     (0, class_validator_1.IsIn)([ReconciliationEntityEnum_1.ReconciliationEntityEnum.STORES, ReconciliationEntityEnum_1.ReconciliationEntityEnum.USERS]),
     __metadata("design:type", String)
 ], StartOrgReconciliationRequest.prototype, "entity", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], StartOrgReconciliationRequest.prototype, "dryRun", void 0);

package/bin/retailIntegration/index.d.ts

@@ -38,5 +38,6 @@ export * from './models/RetailSystemSale';
 export * from './dtos/StartOrgReconciliationRequest';
 export * from './dtos/StartCatalogReconciliationRequest';
 export * from './dtos/ReconciliationRunCounts';
+export * from './dtos/ReconciliationPreview';
 export * from './dtos/GetReconciliationResponses';
 export * from './dtos/ReconciliationPageMessage';

package/bin/retailIntegration/index.js

@@ -54,5 +54,6 @@ __exportStar(require("./models/RetailSystemSale"), exports);
 __exportStar(require("./dtos/StartOrgReconciliationRequest"), exports);
 __exportStar(require("./dtos/StartCatalogReconciliationRequest"), exports);
 __exportStar(require("./dtos/ReconciliationRunCounts"), exports);
+__exportStar(require("./dtos/ReconciliationPreview"), exports);
 __exportStar(require("./dtos/GetReconciliationResponses"), exports);
 __exportStar(require("./dtos/ReconciliationPageMessage"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.598.0",
+  "version": "3.599.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/retailIntegration/dtos/GetReconciliationResponses.ts

@@ -1,6 +1,7 @@
 import type { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
 import type { ReconciliationRunStatusEnum } from '../enums/ReconciliationRunStatusEnum';
 import type { ReconciliationTriggerEnum } from '../enums/ReconciliationTriggerEnum';
+import type { ReconciliationPreview } from './ReconciliationPreview';
 import type { ReconciliationRunCounts } from './ReconciliationRunCounts';
 
 /** Respuesta 200 de GET .../reconciliations/{runId} en org (backofficeGetOrgReconciliation). */
@@ -16,6 +17,10 @@ export interface GetOrgReconciliationResponse {
     finishedAt?: string;
     pagesProcessed: number;
     counts: ReconciliationRunCounts;
+    /** La corrida fue en modo prueba y no escribió nada. */
+    dryRun?: boolean;
+    /** Vista previa de una corrida en modo prueba. */
+    preview?: ReconciliationPreview;
 }
 
 /** Respuesta 200 de GET .../reconciliations/{runId} en catalog (backofficeGetCatalogReconciliation). */
@@ -42,4 +47,8 @@ export interface GetCatalogReconciliationResponse {
     /** Fin ISO de la ventana revisada en movimientos. */
     movementsTo?: string;
     counts: ReconciliationRunCounts;
+    /** La corrida fue en modo prueba y no escribió nada. */
+    dryRun?: boolean;
+    /** Vista previa de una corrida en modo prueba. */
+    preview?: ReconciliationPreview;
 }

package/src/retailIntegration/dtos/ReconciliationPreview.ts

@@ -0,0 +1,23 @@
+/** Tope de renglones por lista de la vista previa; si se pasa, `truncated` es true. */
+export const RECONCILIATION_PREVIEW_MAX_ITEMS = 200;
+
+/** Renglón de la vista previa: `id` es storeId, retailUserId, sku o identifier según la entidad. */
+export interface ReconciliationPreviewItem {
+    id: string;
+    /** Nombre legible para mostrar en el backoffice. */
+    label?: string;
+    /** Campos que cambiarían, solo en `updated`. */
+    fields?: string[];
+    /** Tienda de la pieza en inventario. */
+    storeId?: string;
+}
+
+/** Lo que haría una corrida en modo prueba (`dryRun`), sin escribir nada. */
+export interface ReconciliationPreview {
+    created: ReconciliationPreviewItem[];
+    updated: ReconciliationPreviewItem[];
+    deactivated: ReconciliationPreviewItem[];
+    reactivated: ReconciliationPreviewItem[];
+    /** Alguna lista se cortó en RECONCILIATION_PREVIEW_MAX_ITEMS. */
+    truncated: boolean;
+}

package/src/retailIntegration/dtos/RetailEventResult.ts

@@ -1,10 +1,23 @@
+import type { RetailEventRejectCodeEnum } from '../enums/RetailEventRejectCodeEnum';
 import { RetailEventResultEnum } from '../enums/RetailEventResultEnum';
 
+/** Renglón inválido de un evento de inventario; `index` es 0-based en `pieces` o en `stock` según `kind`. */
+export interface RetailEventItemError {
+    index: number;
+    kind?: 'piece' | 'stock';
+    identifier?: string;
+    sku?: string;
+    storeId?: string;
+    code: RetailEventRejectCodeEnum;
+}
+
 /** Resultado de un evento; `code` explica un `REJECTED` y es `null` en los demás. */
 export interface RetailEventResult {
     eventId: string;
     result: RetailEventResultEnum;
     code: string | null;
+    /** Todos los renglones inválidos de un `REJECTED` de inventario, no solo el primero. */
+    errors?: RetailEventItemError[];
 }
 
 export type ReceiveStoreEventResponse = RetailEventResult;

package/src/retailIntegration/dtos/StartCatalogReconciliationRequest.ts

@@ -1,5 +1,5 @@
 import { Expose } from 'class-transformer';
-import { IsIn, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { IsBoolean, IsIn, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 import { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
 
 /** Body de POST /backoffice/retailers/{retailerId}/reconciliations en catalog (backofficeStartCatalogReconciliation). */
@@ -14,6 +14,12 @@ export class StartCatalogReconciliationRequest {
     @IsString()
     @IsNotEmpty()
     storeId?: string;
+
+    /** Modo prueba: calcula la vista previa sin escribir nada. */
+    @Expose()
+    @IsOptional()
+    @IsBoolean()
+    dryRun?: boolean;
 }
 
 /** Respuesta 202 del arranque en catalog. */

package/src/retailIntegration/dtos/StartOrgReconciliationRequest.ts

@@ -1,5 +1,5 @@
 import { Expose } from 'class-transformer';
-import { IsIn } from 'class-validator';
+import { IsBoolean, IsIn, IsOptional } from 'class-validator';
 import { ReconciliationEntityEnum } from '../enums/ReconciliationEntityEnum';
 
 /** Body de POST /backoffice/retailers/{retailerId}/reconciliations en org (backofficeStartOrgReconciliation). */
@@ -7,6 +7,12 @@ export class StartOrgReconciliationRequest {
     @Expose()
     @IsIn([ReconciliationEntityEnum.STORES, ReconciliationEntityEnum.USERS])
     entity!: ReconciliationEntityEnum.STORES | ReconciliationEntityEnum.USERS;
+
+    /** Modo prueba: calcula la vista previa sin escribir nada. */
+    @Expose()
+    @IsOptional()
+    @IsBoolean()
+    dryRun?: boolean;
 }
 
 /** Respuesta 202 del arranque en org. */

package/src/retailIntegration/index.ts

@@ -38,5 +38,6 @@ export * from './models/RetailSystemSale';
 export * from './dtos/StartOrgReconciliationRequest';
 export * from './dtos/StartCatalogReconciliationRequest';
 export * from './dtos/ReconciliationRunCounts';
+export * from './dtos/ReconciliationPreview';
 export * from './dtos/GetReconciliationResponses';
 export * from './dtos/ReconciliationPageMessage';