@fiado/api-invoker 5.66.0 → 5.68.0

package/src/trustonicConnector/api/TrustonicConnectorApi.ts

@@ -0,0 +1,118 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+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,
+} from "@fiado/type-kit/bin/mdm/index.js";
+import { DeviceBatchRequest, DeviceBatchResult } from "../../utils/MdmEnvelopes.js";
+import {
+    DeviceInitiateBatchResult,
+    DevicePollingBatchRequest,
+    ITrustonicConnectorApi,
+} from "./interfaces/ITrustonicConnectorApi.js";
+
+/**
+ * Publisher HTTP del lambda `trustonic-connector` (segundo provider MDM de SureKeep). Contrato y
+ * semántica completos → `ITrustonicConnectorApi` (paths sin prefijo `/private`, sin tenant,
+ * `StandardResponse` → leer `result.data`, granularidad por ítem, y las cinco diferencias reales
+ * contra el connector de Datacultr).
+ *
+ * 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.
+ */
+@injectable()
+export default class TrustonicConnectorApi implements ITrustonicConnectorApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//devices".
+    private readonly baseUrl = (process.env.TRUSTONIC_CONNECTOR_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async enrollDevices(
+        input: DeviceBatchRequest<DeviceEnrollRequest>,
+    ): Promise<StandardResponse<DeviceInitiateBatchResult<DeviceEnrollInitiateResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/enroll`, input);
+    }
+
+    async enrollStatus(
+        input: DevicePollingBatchRequest<DeviceEnrollStatusRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceEnrollStatusResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/enroll/status`, input);
+    }
+
+    async getStatus(
+        input: DeviceBatchRequest<DeviceStatusRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceStatusResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/status`, input);
+    }
+
+    async getLastSeen(
+        input: DeviceBatchRequest<DeviceLastSeenRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceLastSeenResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/last-seen`, input);
+    }
+
+    async lockDevices(
+        input: DeviceBatchRequest<DeviceLockRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceLockResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/lock`, input);
+    }
+
+    async unlockDevices(
+        input: DeviceBatchRequest<DeviceUnlockRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceUnlockResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/unlock`, input);
+    }
+
+    async autoLockSchedule(
+        input: DeviceBatchRequest<DeviceAutoLockScheduleRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/auto-lock-schedule`, input);
+    }
+
+    async pinUnlock(input: DevicePinUnlockRequest): Promise<StandardResponse<DevicePinUnlockResponse>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/pin-unlock`, input);
+    }
+
+    async notifyDevices(
+        input: DeviceBatchRequest<DeviceNotifyRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/notify`, input);
+    }
+
+    async releaseDevices(
+        input: DeviceBatchRequest<DeviceReleaseRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release`, input);
+    }
+
+    async releaseStatus(
+        input: DevicePollingBatchRequest<DeviceReleaseStatusRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release/status`, input);
+    }
+}

package/src/trustonicConnector/api/interfaces/ITrustonicConnectorApi.ts

@@ -0,0 +1,216 @@
+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/src/trustonicConnector/index.ts

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

package/src/utils/MdmEnvelopes.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}