@fiado/api-invoker 5.66.0 → 5.68.0

package/bin/trustonicConnector/api/interfaces/ITrustonicConnectorApi.d.ts

@@ -0,0 +1,158 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { DeviceAutoLockScheduleRequest, DeviceAutoLockScheduleResponse, DeviceEnrollInitiateResponse, DeviceEnrollRequest, DeviceEnrollStatusRequest, DeviceEnrollStatusResponse, DeviceLastSeenRequest, DeviceLastSeenResponse, DeviceLockRequest, DeviceLockResponse, DeviceNotifyRequest, DeviceNotifyResponse, DevicePinUnlockRequest, DevicePinUnlockResponse, DeviceReleaseInitiateResponse, DeviceReleaseRequest, DeviceReleaseStatusRequest, DeviceReleaseStatusResponse, DeviceStatusRequest, DeviceStatusResponse, DeviceUnlockRequest, DeviceUnlockResponse, MdmProviderEnum } from "@fiado/type-kit/bin/mdm/index.js";
+import { DeviceBatchRequest, DeviceBatchResult } from "../../../utils/MdmEnvelopes.js";
+/**
+ * Contrato del publisher HTTP del lambda `trustonic-connector` — el segundo provider MDM de
+ * SureKeep, que traduce el contrato agnóstico de dispositivo (`@fiado/type-kit/bin/mdm`) a la API
+ * de Trustonic. Su consumidor es el módulo `device/` de `loan-credit-business`, que NUNCA le pega
+ * por `http-client` directo: entre lambdas Fiado se habla siempre por `@fiado/api-invoker`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SUPERFICIE — 11 operaciones, las mismas que `IDatacultrConnectorApi`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El connector expone 16 endpoints. Quedan afuera `restrictApps`, `archive`, `deactivate`,
+ * `deactivateStatus` y `deviceLog`: `IMdmProviderAdapter` de `loan-credit-business` no los pide y
+ * el adapter tiene un solo contrato para los dos providers. Sumar operaciones que solo soporta
+ * Trustonic es un cambio aparte, con su propia decisión.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PATHS — `/devices/...`, SIN prefijo `/private`. Igual que Datacultr.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El aislamiento no lo da el prefijo sino la red: la API privada es `EndpointConfiguration:
+ * PRIVATE` con ResourcePolicy que deniega todo lo que no venga de los VPC Endpoints de Fiado.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SIN TENANT y `Feature.ANONIMUS`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Ningún método lleva `tenantId`: el `PrivateController` del destino no lee `X-Tenant-Id` ni
+ * `x-tenant-issuer`, y las credenciales de Trustonic salen de un único secret del lambda. Los
+ * privados son `Feature.ANONIMUS` — sin RBAC y sin claims, así que el caller no manda
+ * `Authorization`. Misma deuda que Datacultr: cuando el MDM sea multi-tenant, este contrato suma
+ * el tenant y pasa a ser un cambio MAJOR.
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ * Errores de transporte (falla el lambda entero, no un ítem): el publisher RECHAZA con el
+ * `DomainError` tipado del destino. Nunca fallback: el caller jamás recibe un batch vacío
+ * disfrazado de éxito.
+ *
+ * Granularidad POR ÍTEM — el batch NUNCA falla entero:
+ * - Cada `results[i]` trae su propio `status` (`SUCCESS` | `PENDING` | `ERROR`) y un `error`
+ *   opcional. Un 200 puede traer ítems en `ERROR`: el caller TIENE que recorrer `results`.
+ * - El `error.code` del ítem es un `MdmErrorCodeEnum`. El `status` no lleva el motivo.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * DIFERENCIAS DE CONTRATO CONTRA DATACULTR — no son intercambiables.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 1. `enrollDevices` devuelve `pollingHandle` + `provider` además de `results`; en Datacultr solo
+ *    devuelve `results`. Acá el enroll es async de verdad y el handle es obligatorio para polear.
+ * 2. `enrollStatus` y `releaseStatus` EXIGEN `pollingHandle` en el body. En Datacultr el sobre de
+ *    entrada es solo `{ items }`.
+ * 3. `lockDevices` soporta `TEMPORARY` de verdad; Datacultr lo degrada por ítem.
+ * 4. `autoLockSchedule` está degradado en Trustonic; en Datacultr es la vía real del bloqueo.
+ * 5. `notifyDevices` usa `title` + `content` (texto crudo) e ignora `notificationCode`; en
+ *    Datacultr es al revés.
+ *
+ * Env var requerida en el consumer: `TRUSTONIC_CONNECTOR_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   TRUSTONIC_CONNECTOR_URL: '{{resolve:ssm:trustonic-connector}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+/**
+ * Sobre de entrada de los endpoints `/status` de Trustonic: además de los ítems exige el
+ * `pollingHandle` que devolvió el initiate. Es un string opaco — no lo inspecciones.
+ */
+export interface DevicePollingBatchRequest<TItem> {
+    pollingHandle: string;
+    items: TItem[];
+}
+/**
+ * Sobre de salida de un initiate async de Trustonic. `pollingHandle` es lo que el caller manda
+ * después a `/status`; `provider` identifica qué MDM atendió la operación.
+ */
+export interface DeviceInitiateBatchResult<TItem> {
+    pollingHandle: string;
+    provider: MdmProviderEnum;
+    results: TItem[];
+}
+export interface ITrustonicConnectorApi {
+    /**
+     * POST `/devices/enroll` — inicia el enrolamiento de cada IMEI en Trustonic (upload de
+     * inventario + activación del servicio `DeviceFinancing` en una call atómica).
+     *
+     * ASYNC de verdad, a diferencia de Datacultr: el destino devuelve `pollingHandle` y el caller
+     * DEBE polear `enrollStatus` con ese handle hasta que todos los ítems sean terminales. El caso
+     * típico es que todos vuelvan en `PENDING`.
+     *
+     * `DeviceEnrollRequest.lockMode` (`ONDEMAND` pospago / `SCHEDULED` prepago) es opcional; si se
+     * omite el destino asume `ONDEMAND`.
+     */
+    enrollDevices(input: DeviceBatchRequest<DeviceEnrollRequest>): Promise<StandardResponse<DeviceInitiateBatchResult<DeviceEnrollInitiateResponse>>>;
+    /**
+     * POST `/devices/enroll/status` — estado del enrolamiento iniciado con `enrollDevices`.
+     *
+     * ⚠️ EXIGE `pollingHandle`: sin él el destino responde 400 `MISSING_POLLING_HANDLE`.
+     *
+     * Los campos `enrolledAt`, `enrollmentMode`, `enrollmentId`, `brand` y `model` siempre vienen
+     * `undefined` — el endpoint de Trustonic no los expone; existen para Datacultr.
+     */
+    enrollStatus(input: DevicePollingBatchRequest<DeviceEnrollStatusRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceEnrollStatusResponse>>>;
+    /** POST `/devices/status` — estado actual de cada IMEI, con `brand`, `model` y `lastSeenAt`. */
+    getStatus(input: DeviceBatchRequest<DeviceStatusRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceStatusResponse>>>;
+    /** POST `/devices/last-seen` — último contacto reportado por cada IMEI (heartbeat). */
+    getLastSeen(input: DeviceBatchRequest<DeviceLastSeenRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceLastSeenResponse>>>;
+    /**
+     * POST `/devices/lock` — bloquea cada IMEI, con mensaje opcional en pantalla.
+     * Acepta `mode: TEMPORARY` de verdad (con `durationSeconds`), que Datacultr degrada por ítem.
+     */
+    lockDevices(input: DeviceBatchRequest<DeviceLockRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceLockResponse>>>;
+    /**
+     * POST `/devices/unlock` — desbloquea cada IMEI.
+     * `unlockUntil` (ISO-8601) acota hasta cuándo vale el desbloqueo y solo aplica en modo
+     * `SCHEDULED`; si el modo lo exige y falta, el ítem vuelve en `ERROR` con
+     * `MdmErrorCodeEnum.UNLOCK_UNTIL_REQUIRED`.
+     */
+    unlockDevices(input: DeviceBatchRequest<DeviceUnlockRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceUnlockResponse>>>;
+    /**
+     * POST `/devices/auto-lock-schedule` — programa el bloqueo de cada IMEI en una fecha futura.
+     *
+     * ⚠️ DEGRADADO en Trustonic: el destino no llama al proveedor y devuelve cada ítem en `ERROR`
+     * con `PROVIDER_NOT_SUPPORTED`. Es el espejo exacto de Datacultr, donde ésta es la vía real del
+     * bloqueo. El caller no debe asumir la misma semántica entre providers.
+     */
+    autoLockSchedule(input: DeviceBatchRequest<DeviceAutoLockScheduleRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>>;
+    /**
+     * POST `/devices/pin-unlock` — pide a Trustonic el PIN offline de un equipo sin conectividad.
+     *
+     * ⚠️ NO ES BATCH y NO LLEVA SOBRE, a diferencia del resto del contrato: el body es el
+     * `DevicePinUnlockRequest` pelado y la respuesta es el `DevicePinUnlockResponse` directo en
+     * `data`, sin `{ result }` — ahí difiere del `pinUnlock` de Datacultr.
+     *
+     * Operación sensible: `pin`, `validitySeconds` y `generatedAt` solo vienen con `status`
+     * `SUCCESS`. El PIN viaja únicamente en esta respuesta — nunca loggearlo.
+     */
+    pinUnlock(input: DevicePinUnlockRequest): Promise<StandardResponse<DevicePinUnlockResponse>>;
+    /**
+     * POST `/devices/notify` — manda una notificación (`BANNER` o `FULLSCREEN`) a cada IMEI.
+     * Trustonic usa `title` y `content` como texto crudo e ignora `notificationCode`, al revés que
+     * Datacultr, que resuelve el texto por catálogo.
+     */
+    notifyDevices(input: DeviceBatchRequest<DeviceNotifyRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>>;
+    /**
+     * POST `/devices/release` — libera definitivamente cada IMEI del MDM (fin de tenure).
+     *
+     * ⚠️ IRREVERSIBLE: un equipo liberado no se puede re-enrolar en Trustonic.
+     * Es sync y terminal — cada ítem vuelve `SUCCESS` o `ERROR`, nunca `PENDING`, y la respuesta NO
+     * trae `pollingHandle` (asimetría con `enrollDevices`).
+     */
+    releaseDevices(input: DeviceBatchRequest<DeviceReleaseRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>>;
+    /**
+     * POST `/devices/release/status` — consulta el estado de una liberación.
+     *
+     * ⚠️ EXIGE `pollingHandle` aunque `releaseDevices` no devuelva ninguno: el caller tiene que
+     * inventar o reusar un identificador de tracing. Existe solo por simetría con Datacultr, donde
+     * el release sí es async; contra Trustonic normalmente no hace falta llamarlo.
+     */
+    releaseStatus(input: DevicePollingBatchRequest<DeviceReleaseStatusRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>>;
+}

package/bin/trustonicConnector/api/interfaces/ITrustonicConnectorApi.js

@@ -0,0 +1 @@
+export {};

package/bin/trustonicConnector/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/ITrustonicConnectorApi.js";
+export { default as TrustonicConnectorApi } from "./api/TrustonicConnectorApi.js";

package/bin/trustonicConnector/index.js

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/ITrustonicConnectorApi.js";
+export { default as TrustonicConnectorApi } from "./api/TrustonicConnectorApi.js";

package/bin/utils/MdmEnvelopes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sobres de request/response compartidos por los connectors MDM (`datacultr-connector`,
+ * `trustonic-connector`). No viven en `@fiado/type-kit/bin/mdm` porque los DTOs publicados
+ * son de UN imei; el sobre es dominio del líder (gap E8), migrar a type-kit cuando lo publique.
+ */
+/** Sobre de entrada de los endpoints batch de un connector MDM. */
+export interface DeviceBatchRequest<TItem> {
+    items: TItem[];
+}
+/** Sobre de salida de los endpoints batch: viaja dentro de `StandardResponse.data`. */
+export interface DeviceBatchResult<TItem> {
+    results: TItem[];
+}
+/** Sobre de salida de los endpoints de UN solo IMEI. Hoy solo `pinUnlock` no es batch. */
+export interface DeviceSingleResult<TItem> {
+    result: TItem;
+}

package/bin/utils/MdmEnvelopes.js

@@ -0,0 +1,6 @@
+/**
+ * Sobres de request/response compartidos por los connectors MDM (`datacultr-connector`,
+ * `trustonic-connector`). No viven en `@fiado/type-kit/bin/mdm` porque los DTOs publicados
+ * son de UN imei; el sobre es dominio del líder (gap E8), migrar a type-kit cuando lo publique.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.66.0",
+  "version": "5.68.0",
   "description": "Sirve como un puente entre diferentes funciones lambda, facilitando la comunicación entre ellas a través de invocaciones http",
   "type": "module",
   "main": "bin/index.js",
@@ -34,7 +34,7 @@
     "@fiado/gateway-adapter": "^3.9.0",
     "@fiado/http-client": "^2.0.1",
     "@fiado/logger": "^1.1.3",
-    "@fiado/type-kit": "^3.390.0",
+    "@fiado/type-kit": "^3.400.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/datacultrConnector/api/interfaces/IDatacultrConnectorApi.ts

@@ -23,6 +23,7 @@ import {
     DeviceUnlockRequest,
     DeviceUnlockResponse,
 } from "@fiado/type-kit/bin/mdm/index.js";
+import { DeviceBatchRequest, DeviceBatchResult, DeviceSingleResult } from "../../../utils/MdmEnvelopes.js";
 
 /**
  * Contrato del publisher HTTP del lambda `datacultr-connector` — el provider MDM que traduce el
@@ -71,24 +72,9 @@ import {
  * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
  */
 
-/**
- * Sobre de entrada de los endpoints batch del connector. No vive en `@fiado/type-kit/bin/mdm`
- * porque los DTOs publicados son de UN imei; el sobre es dominio del líder (gap E8), migrar a
- * type-kit cuando lo publique.
- */
-export interface DeviceBatchRequest<TItem> {
-    items: TItem[];
-}
-
-/** Sobre de salida de los endpoints batch: viaja dentro de `StandardResponse.data`. Mismo gap E8. */
-export interface DeviceBatchResult<TItem> {
-    results: TItem[];
-}
-
-/** Sobre de salida de los endpoints de UN solo IMEI. Hoy solo `pinUnlock` no es batch. */
-export interface DeviceSingleResult<TItem> {
-    result: TItem;
-}
+// Los sobres viven en `utils/MdmEnvelopes` porque los comparten todos los connectors MDM.
+// Se re-exportan acá para no cambiar la superficie pública de `@fiado/api-invoker`.
+export * from "../../../utils/MdmEnvelopes.js";
 
 export interface IDatacultrConnectorApi {
     /**

package/src/index.ts

@@ -114,3 +114,4 @@ export * from "./collection-engine/index.js";
 export * from "./domain-callback/index.js";
 export * from "./datacultrConnector/index.js";
 export * from "./webhook-business/index.js";
+export * from "./trustonicConnector/index.js";

package/src/loanCredit/api/LoanCreditDeviceApi.ts

@@ -2,6 +2,7 @@ import { inject, injectable } from "inversify";
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import {
+    LOAN_DEVICE_MAX_BATCH,
     LoanDeviceEnrollRequest,
     LoanDeviceEnrollResponse,
     LoanDeviceEnrollStatusRequest,
@@ -12,6 +13,10 @@ import {
     LoanDeviceManualLockResponse,
     LoanDeviceManualUnlockRequest,
     LoanDeviceManualUnlockResponse,
+    LoanDeviceNotifyRequest,
+    LoanDeviceNotifyResponse,
+    LoanDeviceReleaseRequest,
+    LoanDeviceReleaseResponse,
     LoanDeviceStatusRequest,
     LoanDeviceStatusResponse,
 } from "@fiado/type-kit/bin/loanCredit/index.js";
@@ -36,6 +41,13 @@ export default class LoanCreditDeviceApi implements ILoanCreditDeviceApi {
 
     constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
 
+    // Se corta aquí: mandar un lote que el destino va a rechazar solo gasta un round-trip.
+    private assertBatchSize(itemCount: number): void {
+        if (itemCount > LOAN_DEVICE_MAX_BATCH) {
+            throw new Error(`El lote admite hasta ${LOAN_DEVICE_MAX_BATCH} ítems y llegaron ${itemCount}`);
+        }
+    }
+
     async enroll(
         input: LoanDeviceEnrollRequest,
         tenantId: string,
@@ -83,4 +95,22 @@ export default class LoanCreditDeviceApi implements ILoanCreditDeviceApi {
         const url = `${this.baseUrl}/private/devices/manual-unlock?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.post(url, input);
     }
+
+    async notify(
+        input: LoanDeviceNotifyRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanDeviceNotifyResponse>> {
+        this.assertBatchSize(input.items.length);
+        const url = `${this.baseUrl}/private/devices/notify?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, input);
+    }
+
+    async release(
+        input: LoanDeviceReleaseRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanDeviceReleaseResponse>> {
+        this.assertBatchSize(input.items.length);
+        const url = `${this.baseUrl}/private/devices/release?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, input);
+    }
 }

package/src/loanCredit/api/interfaces/ILoanCreditDeviceApi.ts

@@ -10,14 +10,19 @@ import {
     LoanDeviceManualLockResponse,
     LoanDeviceManualUnlockRequest,
     LoanDeviceManualUnlockResponse,
+    LoanDeviceNotifyRequest,
+    LoanDeviceNotifyResponse,
+    LoanDeviceReleaseRequest,
+    LoanDeviceReleaseResponse,
     LoanDeviceStatusRequest,
     LoanDeviceStatusResponse,
 } from "@fiado/type-kit/bin/loanCredit/index.js";
 
 /**
  * Contrato del publisher de dispositivo/MDM de `loan-credit-business` (componente 09 SureKeep F2).
- * Endpoints PRIVADOS (VPC) que envuelven al motor MDM: enrolamiento del equipo, consulta de estado
- * y bloqueo/desbloqueo manual. El contrato de crédito vive en `ILoanCreditBusinessApi`.
+ * Endpoints PRIVADOS (VPC) que envuelven al motor MDM: enrolamiento del equipo, consulta de estado,
+ * bloqueo/desbloqueo manual, aviso de cobranza y liberación definitiva. El contrato de crédito vive
+ * en `ILoanCreditBusinessApi`.
  *
  * Convenciones (idénticas a `ILoanCreditBusinessApi`):
  * - `tenantId` OBLIGATORIO en todos los métodos — viaja por query `?tenantId=` (convención de los
@@ -26,9 +31,12 @@ import {
  * - Errores de transporte (falla el lambda entero, no un ítem): el publisher RECHAZA con el
  *   `DomainError` tipado del motor — `400 UNKNOWN_TENANT` / `400` de validación del body /
  *   `5xx` del motor. Nunca fallback: el caller jamás recibe un batch vacío disfrazado de éxito.
- * - Idempotencia: las 3 mutaciones (`enroll`, `manualLock`, `manualUnlock`) son idempotentes por
- *   `input.operationReference` — es el idempotencyKey del caller. Reintentar el mismo lote con la
- *   misma referencia no vuelve a enrolar ni a bloquear; sin ella un retry tras timeout duplica.
+ * - Techo de lote: `notify` y `release` cortan acá el lote de más de `LOAN_DEVICE_MAX_BATCH` ítems,
+ *   sin salir a la red. DEUDA: los otros seis mandan el body tal cual y devuelven el 400 del
+ *   destino, que valida el mismo techo — dos formas de error para la misma causa.
+ * - Idempotencia: las mutaciones (`enroll`, `manualLock`, `manualUnlock`, `notify`, `release`) son
+ *   idempotentes por `input.operationReference` — es el idempotencyKey del caller. Reintentar el
+ *   mismo lote con la misma referencia no repite la operación; sin ella un retry tras timeout duplica.
  *
  * Granularidad POR ÍTEM — el batch NUNCA falla entero:
  * - Cada `results[i]` trae su propio `status` (`SUCCESS` | `PENDING` | `ERROR`) y un `error`
@@ -86,9 +94,41 @@ export interface ILoanCreditDeviceApi {
         tenantId: string,
     ): Promise<StandardResponse<LoanDeviceManualLockResponse>>;
 
-    /** Desbloqueo manual del dispositivo disparado desde el backoffice (acción de un operador). */
+    /**
+     * Desbloqueo manual del dispositivo disparado desde el backoffice (acción de un operador).
+     *
+     * ⚠️ El `unlockUntil` del ítem solo aplica en modo `SCHEDULED` y HOY `loan-credit-business` no
+     * lo lee: su `IDeviceControlService.manualUnlock` recibe `{ creditId }` y lo descarta en silencio.
+     */
     manualUnlock(
         input: LoanDeviceManualUnlockRequest,
         tenantId: string,
     ): Promise<StandardResponse<LoanDeviceManualUnlockResponse>>;
+
+    /**
+     * Manda al dispositivo el aviso de cobranza (banner o pantalla completa) sin bloquearlo.
+     *
+     * ⚠️ `loan-credit-business` TODAVÍA NO publica esta ruta: no está en su `openapi/private.yaml`
+     * ni en su `PrivateController`. Cablear un consumer antes de ese deploy devuelve 403/404.
+     *
+     * @throws Error si el lote supera `LOAN_DEVICE_MAX_BATCH` ítems (se corta acá, sin salir a la red).
+     */
+    notify(
+        input: LoanDeviceNotifyRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanDeviceNotifyResponse>>;
+
+    /**
+     * Libera el dispositivo del MDM de forma DEFINITIVA (crédito liquidado o castigado contablemente).
+     * No es un desbloqueo: saca el equipo del control del proveedor y no se revierte con `manualLock`.
+     *
+     * ⚠️ `loan-credit-business` TODAVÍA NO publica esta ruta: no está en su `openapi/private.yaml`
+     * ni en su `PrivateController`. Cablear un consumer antes de ese deploy devuelve 403/404.
+     *
+     * @throws Error si el lote supera `LOAN_DEVICE_MAX_BATCH` ítems (se corta acá, sin salir a la red).
+     */
+    release(
+        input: LoanDeviceReleaseRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanDeviceReleaseResponse>>;
 }

package/src/retailCatalog/api/RetailCatalogBusinessApi.ts

@@ -1,9 +1,8 @@
 import { inject, injectable } from "inversify";
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
+import type { ValidateProductResponse } from "@fiado/type-kit/bin/retailCatalog/index.js";
 import {
-    IMEI_PRODUCT_BATCH_MAX,
-    ImeiProductLookupResponse,
     IRetailCatalogBusinessApi,
     ProductsByRetailersBody,
     ProductsByRetailersResponse,
@@ -47,18 +46,17 @@ export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessA
         return await this.httpRequest.get(url, undefined, this.tenantHeader(issuer));
     }
 
-    async getProductsByImei(
-        imeis: string[],
-        tenantId: string,
-    ): Promise<StandardResponse<ImeiProductLookupResponse>> {
-        // Se corta acá: mandar un lote que el destino va a rechazar solo gasta un round-trip.
-        if (imeis.length > IMEI_PRODUCT_BATCH_MAX) {
-            throw new Error(`El lote admite hasta ${IMEI_PRODUCT_BATCH_MAX} IMEIs y llegaron ${imeis.length}`);
-        }
-        // `URLSearchParams` codifica la coma del separador; el destino hace `split(',')` sobre el
-        // valor ya decodificado por API Gateway.
-        const query = new URLSearchParams({ imeis: imeis.join(","), tenantId });
-        return await this.httpRequest.get(`${this.baseUrl}/private/products/by-imei?${query.toString()}`);
+    async validateProduct(
+        retailerId: string,
+        sku: string,
+        issuer: string,
+    ): Promise<StandardResponse<ValidateProductResponse>> {
+        const path = `${encodeURIComponent(retailerId)}/${encodeURIComponent(sku)}`;
+        return await this.httpRequest.get(
+            `${this.baseUrl}/private/products/${path}`,
+            undefined,
+            this.tenantHeader(issuer),
+        );
     }
 
     async getProductsByRetailers(

package/src/retailCatalog/api/interfaces/IRetailCatalogBusinessApi.ts

@@ -1,5 +1,9 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import type { MdmLockModeEnum, MdmProviderEnum } from "@fiado/type-kit/bin/retailCatalog/index.js";
+import type {
+    MdmLockModeEnum,
+    MdmProviderEnum,
+    ValidateProductResponse,
+} from "@fiado/type-kit/bin/retailCatalog/index.js";
 
 /**
  * Contrato del publisher HTTP del lambda `retail-catalog-business` (SureKeep Fase 1, pista Retail)
@@ -8,15 +12,15 @@ import type { MdmLockModeEnum, MdmProviderEnum } from "@fiado/type-kit/bin/retai
  * ─────────────────────────────────────────────────────────────────────────────
  * TENANT — DOS convenciones conviven acá. Mirá la firma de cada método.
  * ─────────────────────────────────────────────────────────────────────────────
- * Los cinco métodos del ciclo de venta del IMEI toman `issuer` y lo mandan en el header
+ * Todos los métodos menos `getProductsByRetailers` toman `issuer` y lo mandan en el header
  * `x-tenant-issuer` (`PrivateController.issuerFromHeader` → `TenantContextService.withContext`).
- * `getProductsByImei` toma `tenantId` y lo manda por `?tenantId=`
+ * `getProductsByRetailers` toma `tenantId` y lo manda por `?tenantId=`
  * (→ `TenantContextService.withContextByTenantId`), porque su consumidor es un backoffice que no
  * tiene el issuer Cognito. Los privados son `Feature.ANONIMUS` (sin RBAC; la protección es la red
  * VPC), así que el caller DEBE declarar uno de los dos — no hay default.
  *
- * TD: converger los cinco del ciclo de venta a `?tenantId=`, el camino canónico para
- * service-to-service. No se migran acá para no romper al wizard, que ya consume el header.
+ * TD: converger los que van por header a `?tenantId=`, el camino canónico para service-to-service
+ * (TD-014 del destino). No se migran acá para no romper al wizard, que ya consume el header.
  *
  * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
  * Errores: el destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null); cada
@@ -67,32 +71,6 @@ export interface StoreCatalogItem {
     mdmLockMode: MdmLockModeEnum | null;
 }
 
-/** Techo de IMEIs por request del lote IMEI->producto. Lo declara y lo honra el destino. */
-export const IMEI_PRODUCT_BATCH_MAX = 100;
-
-/** Por que se pudo (o no) resolver el producto de un IMEI del lote. */
-export type ImeiProductLookupStatus = "OK" | "NOT_FOUND" | "UNAVAILABLE" | "INVALID_ID";
-
-/** Una entrada del lote IMEI->producto (espeja `ImeiProductLookupEntry` del destino). */
-export interface ImeiProductLookupEntry {
-    imei: string;
-    /**
-     * `OK` trae sku/brand/model · `NOT_FOUND` el catalogo no llega al producto (dato POSITIVO) ·
-     * `UNAVAILABLE` no se pudo leer ese IMEI, reintentalo · `INVALID_ID` no tiene forma de IMEI.
-     */
-    status: ImeiProductLookupStatus;
-    sku?: string;
-    /** Marca comercial (p. ej. "Apple"). Solo viene con `status: OK`. */
-    brand?: string;
-    /** Modelo (p. ej. "iPhone 15 Pro"). Solo viene con `status: OK`. */
-    model?: string;
-}
-
-/** Respuesta del lote: UNA entrada por IMEI pedido, en el MISMO orden. */
-export interface ImeiProductLookupResponse {
-    items: ImeiProductLookupEntry[];
-}
-
 /** Techo de cadenas por request del lote cadena->catálogo. Lo declara y lo honra el destino. */
 export const RETAILER_PRODUCTS_BATCH_MAX = 100;
 
@@ -148,29 +126,24 @@ export interface IRetailCatalogBusinessApi {
     getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>>;
 
     /**
-     * GET `/private/products/by-imei?imeis=&tenantId=` — resuelve un lote de IMEIs a su producto
-     * (sku + marca + modelo). Para los lambdas que del equipo solo guardan el IMEI.
-     *
-     * ─────────────────────────────────────────────────────────────────────────────
-     * ⚠️ El tenant va por `?tenantId=`, NO por el header `x-tenant-issuer` del resto de este publisher.
-     * ─────────────────────────────────────────────────────────────────────────────
-     * El consumidor es un backoffice que solo tiene el `tenantId` de su contexto; el issuer Cognito
-     * no existe de su lado. El destino entra por `TenantContextService.withContextByTenantId`, con las
-     * mismas garantías (mismo diccionario, AssumeRole del silo, fail-closed sin tenant).
+     * GET `/private/products/{retailerId}/{sku}` — valida que el producto exista y devuelve su
+     * `status`, su `tier`, sus financieras elegibles y su política MDM.
      *
-     * ── El contrato del lote ────────────────────────────────────────────────────────────────────
-     * Devuelve UNA entrada por cada IMEI pedido, en el MISMO orden — el caller nunca reconcilia. Los
-     * repetidos se consultan una sola vez pero salen repetidos. Techo de `IMEI_PRODUCT_BATCH_MAX`
-     * IMEIs por request; el caller parte los lotes mayores.
+     * ⚠️ El tenant va en el header `x-tenant-issuer`, NO por `?tenantId=` — el destino lo resuelve
+     * con `issuerFromHeader` y su `openapi/private.yaml` no declara ningún parámetro de tenant.
      *
-     * Ningún IMEI tumba el lote: el mal formado sale `INVALID_ID`, el que el catálogo no alcanza a
-     * resolver sale `NOT_FOUND` y el que DynamoDB no llegó a leer sale `UNAVAILABLE` (reintentable).
-     * Solo un fallo total del destino rechaza la promesa.
+     * La política MDM viaja completa cuando `mdmEnabled: true`; con `false`, `mdmProvider` y
+     * `mdmLockMode` vienen en `null` (invariante `validateMdmCoherence` del catálogo).
      *
-     * @throws Error si el lote supera el techo (se corta acá, sin salir a la red) ·
-     *   `400 IMEI_BATCH_REQUIRED` si `imeis` viene vacío · `400 UNKNOWN_TENANT` sin `tenantId`.
+     * @throws `404 PRODUCT_NOT_FOUND` el producto no existe para esa cadena ·
+     *   `400 UNKNOWN_TENANT` falta o no se reconoce el issuer ·
+     *   `500 TENANT_ASSUME_ROLE_FAILED` fallo de infra del silo.
      */
-    getProductsByImei(imeis: string[], tenantId: string): Promise<StandardResponse<ImeiProductLookupResponse>>;
+    validateProduct(
+        retailerId: string,
+        sku: string,
+        issuer: string,
+    ): Promise<StandardResponse<ValidateProductResponse>>;
 
     /**
      * POST `/private/products/by-retailers?tenantId=` — catálogo de productos de VARIAS cadenas en
@@ -179,8 +152,8 @@ export interface IRetailCatalogBusinessApi {
      * ─────────────────────────────────────────────────────────────────────────────
      * ⚠️ El tenant va por `?tenantId=`, NO por el header `x-tenant-issuer` del resto de este publisher.
      * ─────────────────────────────────────────────────────────────────────────────
-     * Es obligatorio. El destino entra por `TenantContextService.withContextByTenantId`, igual que
-     * `getProductsByImei`.
+     * Es obligatorio. El destino entra por `TenantContextService.withContextByTenantId`, con las
+     * mismas garantías (mismo diccionario, AssumeRole del silo, fail-closed sin tenant).
      *
      * ── El contrato del lote ────────────────────────────────────────────────────────────────────
      * `retailerIds` no puede venir vacío, sin repetidos y con un techo de