@fiado/api-invoker 5.11.0 → 5.13.0

package/bin/biometrics-business/BiometricsBusinessApi.d.ts

@@ -0,0 +1,27 @@
+import type { IBiometricsBusinessApi } from "./interfaces/IBiometricsBusinessApi.js";
+import type { BiometricVerificationChangedV1, BiometricVerificationResponse, CreateBiometricVerificationRequest } from "@fiado/type-kit/bin/biometrics/index.js";
+import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+import type { IHttpRequest } from "@fiado/http-client";
+/**
+ * Implementación del cliente de `biometrics-business`. Ver `IBiometricsBusinessApi` para el
+ * contrato y el manejo de respuestas.
+ *
+ * El `/private` NO va en el path: lo aporta el `baseUrl` que se resuelve del SSM.
+ */
+export default class BiometricsBusinessApi implements IBiometricsBusinessApi {
+    private httpRequest;
+    /**
+     * ⚠️ Se le quita el slash final y los paths lo ponen explícito.
+     *
+     * No es cosmético: hay dos convenciones conviviendo en esta lib. `MetamapConnectorApi` hace
+     * `${baseUrl}facematch/signature` — o sea que **depende** de que el SSM devuelva la URL
+     * terminada en `/`, y si algún día no la devuelve así arma `...v1/privatefacematch/signature`
+     * y el 404 no dice por qué. `KycVerificationsBusinessApi` normaliza. Acá se sigue el segundo,
+     * que funciona con las dos formas.
+     */
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    getBiometricVerification(biometricVerificationId: string): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<ApiGatewayResponse<void>>;
+}

package/bin/biometrics-business/BiometricsBusinessApi.js

@@ -0,0 +1,55 @@
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from "inversify";
+/**
+ * Implementación del cliente de `biometrics-business`. Ver `IBiometricsBusinessApi` para el
+ * contrato y el manejo de respuestas.
+ *
+ * El `/private` NO va en el path: lo aporta el `baseUrl` que se resuelve del SSM.
+ */
+let BiometricsBusinessApi = class BiometricsBusinessApi {
+    httpRequest;
+    /**
+     * ⚠️ Se le quita el slash final y los paths lo ponen explícito.
+     *
+     * No es cosmético: hay dos convenciones conviviendo en esta lib. `MetamapConnectorApi` hace
+     * `${baseUrl}facematch/signature` — o sea que **depende** de que el SSM devuelva la URL
+     * terminada en `/`, y si algún día no la devuelve así arma `...v1/privatefacematch/signature`
+     * y el 404 no dice por qué. `KycVerificationsBusinessApi` normaliza. Acá se sigue el segundo,
+     * que funciona con las dos formas.
+     */
+    baseUrl = (process.env.BIOMETRICS_BUSINESS_LAMBDA_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    async createBiometricVerification(data) {
+        const url = `${this.baseUrl}/biometric-verifications`;
+        return await this.httpRequest.post(url, data);
+    }
+    async getBiometricVerification(biometricVerificationId) {
+        // encodeURIComponent y no interpolación pelada: el id va en el path, y aunque hoy lo genera
+        // biometrics-business, el día que un caller pase basura preferimos un 404 a una URL rota.
+        const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}`;
+        return await this.httpRequest.get(url);
+    }
+    async applyBiometricEvent(biometricVerificationId, data) {
+        const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}/events`;
+        return await this.httpRequest.post(url, data);
+    }
+};
+BiometricsBusinessApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], BiometricsBusinessApi);
+export default BiometricsBusinessApi;

package/bin/biometrics-business/index.d.ts

@@ -0,0 +1,2 @@
+export * from './interfaces/IBiometricsBusinessApi.js';
+export * from './BiometricsBusinessApi.js';

package/bin/biometrics-business/index.js

@@ -0,0 +1,2 @@
+export * from './interfaces/IBiometricsBusinessApi.js';
+export * from './BiometricsBusinessApi.js';

package/bin/biometrics-business/interfaces/IBiometricsBusinessApi.d.ts

@@ -0,0 +1,55 @@
+import type { BiometricVerificationChangedV1, BiometricVerificationResponse, CreateBiometricVerificationRequest } from "@fiado/type-kit/bin/biometrics/index.js";
+import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+/**
+ * Cliente de `biometrics-business`, el master de la lógica biométrica de Fiado.
+ *
+ * Tres endpoints privados (VPC-only) con DOS audiencias distintas:
+ *
+ * - **Cualquier producto que necesite un biométrico** usa `createBiometricVerification` +
+ *   `getBiometricVerification` (polling).
+ * - **`kyc-metamap-webhook` y solo él** usa `applyBiometricEvent`, para avisar que llegó un
+ *   resultado del proveedor.
+ *
+ * `baseUrl` = `process.env.BIOMETRICS_BUSINESS_LAMBDA_URL` (SSM key = nombre del repo, que lo
+ * publica su propio buildspec).
+ */
+export interface IBiometricsBusinessApi {
+    /**
+     * Pide una verificación biométrica. Devuelve lo que haga falta para ejecutarla, según el
+     * `deliveryMode`: con Metamap es un link hospedado ya acortado.
+     *
+     * **Idempotente por persona**: si ya hay una verificación viva del mismo `directoryId` + `type`
+     * + `provider`, devuelve ESA — mismo id, mismo link. Reintentar no publica otra selfie ni deja
+     * links huérfanos.
+     *
+     * ⚠️ Lanza tipado si no se puede armar (sin foto de referencia, proveedor caído, combinación no
+     * soportada). **`biometrics-business` NO degrada**: no sabe qué debe pasar en tu flujo si falla.
+     * Esa política es tuya — el wizard, por ejemplo, degrada a KYC completo.
+     */
+    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    /**
+     * El estado actual de una verificación. Es el endpoint de polling.
+     *
+     * Leer `status` (dónde va el proceso) y `result` (qué dijo el biométrico) **por separado**: el
+     * veredicto del facematch llega antes del cierre, así que `result` puede venir en `MATCH` con
+     * `status` todavía en `IN_PROGRESS`. No es una inconsistencia.
+     *
+     * La expiración no depende de que llegue ningún evento: este `GET` la calcula y la persiste.
+     */
+    getBiometricVerification(biometricVerificationId: string): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    /**
+     * Avisa que el proveedor reportó algo sobre una verificación. **Su único caller legítimo es
+     * `kyc-metamap-webhook`** — un producto normal no llama acá.
+     *
+     * 🔴 **Idempotente por `eventId`, y eso NO es un detalle.** Este canal reemplaza a una cola, así
+     * que la durabilidad la da el reintento del proveedor: recibir el mismo evento dos veces es el
+     * camino NORMAL, no la excepción. Un `eventId` repetido devuelve 200 y no aplica nada.
+     *
+     * Cómo tratar la respuesta desde el webhook:
+     * - `200` → aplicado o descartado por duplicado. Los dos son éxito.
+     * - `404` / `409` → **no reintentar**: no existe, o ya está en un estado terminal.
+     * - `5xx` → devolver no-200 al proveedor **para que reintente**. Esto es seguro SOLO en la rama
+     *   biométrica, que corta antes de escribir nada y no tiene efectos que duplicar.
+     */
+    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<ApiGatewayResponse<void>>;
+}

package/bin/biometrics-business/interfaces/IBiometricsBusinessApi.js

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

package/bin/container.config.js

@@ -9,6 +9,7 @@ import { Publisher } from "./account-fiadoinc/index.js";
 import AccountFiadoIncApi from "./account-fiadoinc/AccountFiadoIncApi.js";
 import AccountPagoConfiadoApi from "./account-pagoconfiado/AccountPagoConfiadoApi.js";
 import MetamapConnectorApi from "./metamap-connector/MetamapConnectorApi.js";
+import BiometricsBusinessApi from "./biometrics-business/BiometricsBusinessApi.js";
 import AccountFiadoSAApi from "./account-fiadosa/AccountFiadoSAApi.js";
 import STPAccountApi from "./stpAccount/api/STPAccountApi.js";
 import { SessionActivityPublisher } from "./sessionActivity/index.js";
@@ -140,6 +141,7 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     bind("IAccountFiadoIncApi").to(AccountFiadoIncApi);
     bind("IAccountPagoConfiadoApi").to(AccountPagoConfiadoApi);
     bind("IMetamapConnectorApi").to(MetamapConnectorApi);
+    bind("IBiometricsBusinessApi").to(BiometricsBusinessApi);
     bind("IAccountFiadoSAApi").to(AccountFiadoSAApi);
     bind("INotificationMessagesPublisher").to(NotificationMessagePublisher);
     bind("INotificationWSMessagesPublisher").to(NotificationWSMessagePublisher);

package/bin/index.d.ts

@@ -11,6 +11,7 @@ export * from "./account-fiadoinc/index.js";
 export * from "./account-fiadosa/index.js";
 export * from "./account-pagoconfiado/index.js";
 export * from "./metamap-connector/index.js";
+export * from "./biometrics-business/index.js";
 export * from "./account-beneficiary/index.js";
 export * from "./exchangeRates/index.js";
 export * from "./authentication/index.js";

package/bin/index.js

@@ -11,6 +11,7 @@ export * from "./account-fiadoinc/index.js";
 export * from "./account-fiadosa/index.js";
 export * from "./account-pagoconfiado/index.js";
 export * from "./metamap-connector/index.js";
+export * from "./biometrics-business/index.js";
 export * from "./account-beneficiary/index.js";
 export * from "./exchangeRates/index.js";
 export * from "./authentication/index.js";

package/bin/zendesk/ZendeskApi.d.ts

@@ -2,6 +2,7 @@ import { IHttpRequest } from "@fiado/http-client";
 import { IZendeskApi } from "./interfaces/IZendeskApi.js";
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { HelpdeskCreateUserRequest, HelpdeskCreateTicketRequest } from '@fiado/type-kit/bin/helpdesk/index.js';
+import { SendProactiveMessageRequest, ISendProactiveMessageResponse } from '@fiado/type-kit/bin/zendeskMessaging/index.js';
 export declare class ZendeskApi implements IZendeskApi {
     private httpRequest;
     private readonly baseUrl;
@@ -11,5 +12,6 @@ export declare class ZendeskApi implements IZendeskApi {
     deleteByDirectoryId(directoryId: string): Promise<FiadoApiResponse<{
         deletedCount: number;
     }>>;
+    sendProactiveMessage(data: SendProactiveMessageRequest): Promise<FiadoApiResponse<ISendProactiveMessageResponse>>;
 }
 export {};

package/bin/zendesk/ZendeskApi.js

@@ -31,6 +31,10 @@ let ZendeskApi = class ZendeskApi {
         const url = `${this.baseUrl}private/directory/${directoryId}`;
         return await this.httpRequest.delete(url);
     }
+    async sendProactiveMessage(data) {
+        const url = `${this.baseUrl}messaging/send-proactive`;
+        return await this.httpRequest.post(url, data);
+    }
 };
 ZendeskApi = __decorate([
     injectable(),

package/bin/zendesk/interfaces/IZendeskApi.d.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { HelpdeskCreateTicketRequest, HelpdeskCreateUserRequest } from '@fiado/type-kit/bin/helpdesk/index.js';
+import { SendProactiveMessageRequest, ISendProactiveMessageResponse } from '@fiado/type-kit/bin/zendeskMessaging/index.js';
 /**
  * Interfaz para el servicio de Zendesk
  */
@@ -14,5 +15,11 @@ export interface IZendeskApi {
     deleteByDirectoryId(directoryId: string): Promise<FiadoApiResponse<{
         deletedCount: number;
     }>>;
+    /**
+     * Envia un mensaje proactivo a un usuario via Zendesk Messaging (Sunshine Conversations).
+     * Crea (o reutiliza) el usuario y la conversacion en Sunshine a partir del directoryId.
+     * @param data directoryId + message (displayName opcional).
+     */
+    sendProactiveMessage(data: SendProactiveMessageRequest): Promise<FiadoApiResponse<ISendProactiveMessageResponse>>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.11.0",
+  "version": "5.13.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.235.0",
+    "@fiado/type-kit": "^3.253.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/biometrics-business/BiometricsBusinessApi.ts

@@ -0,0 +1,59 @@
+import { inject, injectable } from "inversify";
+import type { IBiometricsBusinessApi } from "./interfaces/IBiometricsBusinessApi.js";
+import type {
+    BiometricVerificationChangedV1,
+    BiometricVerificationResponse,
+    CreateBiometricVerificationRequest,
+} from "@fiado/type-kit/bin/biometrics/index.js";
+import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+// ⚠️ `import type` y NO un import de valor. `@fiado/http-client` se publica como CJS; importar
+// `IHttpRequest` como valor hace que jest falle al cargar el módulo bajo ESM
+// ("does not provide an export named 'IHttpRequest'"). Con `import type` se borra al compilar.
+// `MetamapConnectorApi` lo hace como valor y no lo nota porque no tiene tests.
+import type { IHttpRequest } from "@fiado/http-client";
+
+/**
+ * Implementación del cliente de `biometrics-business`. Ver `IBiometricsBusinessApi` para el
+ * contrato y el manejo de respuestas.
+ *
+ * El `/private` NO va en el path: lo aporta el `baseUrl` que se resuelve del SSM.
+ */
+@injectable()
+export default class BiometricsBusinessApi implements IBiometricsBusinessApi {
+    /**
+     * ⚠️ Se le quita el slash final y los paths lo ponen explícito.
+     *
+     * No es cosmético: hay dos convenciones conviviendo en esta lib. `MetamapConnectorApi` hace
+     * `${baseUrl}facematch/signature` — o sea que **depende** de que el SSM devuelva la URL
+     * terminada en `/`, y si algún día no la devuelve así arma `...v1/privatefacematch/signature`
+     * y el 404 no dice por qué. `KycVerificationsBusinessApi` normaliza. Acá se sigue el segundo,
+     * que funciona con las dos formas.
+     */
+    private readonly baseUrl = (process.env.BIOMETRICS_BUSINESS_LAMBDA_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async createBiometricVerification(
+        data: CreateBiometricVerificationRequest,
+    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>> {
+        const url = `${this.baseUrl}/biometric-verifications`;
+        return await this.httpRequest.post(url, data);
+    }
+
+    async getBiometricVerification(
+        biometricVerificationId: string,
+    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>> {
+        // encodeURIComponent y no interpolación pelada: el id va en el path, y aunque hoy lo genera
+        // biometrics-business, el día que un caller pase basura preferimos un 404 a una URL rota.
+        const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}`;
+        return await this.httpRequest.get(url);
+    }
+
+    async applyBiometricEvent(
+        biometricVerificationId: string,
+        data: BiometricVerificationChangedV1,
+    ): Promise<ApiGatewayResponse<void>> {
+        const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}/events`;
+        return await this.httpRequest.post(url, data);
+    }
+}

package/src/biometrics-business/index.ts

@@ -0,0 +1,2 @@
+export * from './interfaces/IBiometricsBusinessApi.js';
+export * from './BiometricsBusinessApi.js';

package/src/biometrics-business/interfaces/IBiometricsBusinessApi.ts

@@ -0,0 +1,69 @@
+import type {
+    BiometricVerificationChangedV1,
+    BiometricVerificationResponse,
+    CreateBiometricVerificationRequest,
+} from "@fiado/type-kit/bin/biometrics/index.js";
+import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+
+/**
+ * Cliente de `biometrics-business`, el master de la lógica biométrica de Fiado.
+ *
+ * Tres endpoints privados (VPC-only) con DOS audiencias distintas:
+ *
+ * - **Cualquier producto que necesite un biométrico** usa `createBiometricVerification` +
+ *   `getBiometricVerification` (polling).
+ * - **`kyc-metamap-webhook` y solo él** usa `applyBiometricEvent`, para avisar que llegó un
+ *   resultado del proveedor.
+ *
+ * `baseUrl` = `process.env.BIOMETRICS_BUSINESS_LAMBDA_URL` (SSM key = nombre del repo, que lo
+ * publica su propio buildspec).
+ */
+export interface IBiometricsBusinessApi {
+    /**
+     * Pide una verificación biométrica. Devuelve lo que haga falta para ejecutarla, según el
+     * `deliveryMode`: con Metamap es un link hospedado ya acortado.
+     *
+     * **Idempotente por persona**: si ya hay una verificación viva del mismo `directoryId` + `type`
+     * + `provider`, devuelve ESA — mismo id, mismo link. Reintentar no publica otra selfie ni deja
+     * links huérfanos.
+     *
+     * ⚠️ Lanza tipado si no se puede armar (sin foto de referencia, proveedor caído, combinación no
+     * soportada). **`biometrics-business` NO degrada**: no sabe qué debe pasar en tu flujo si falla.
+     * Esa política es tuya — el wizard, por ejemplo, degrada a KYC completo.
+     */
+    createBiometricVerification(
+        data: CreateBiometricVerificationRequest,
+    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+
+    /**
+     * El estado actual de una verificación. Es el endpoint de polling.
+     *
+     * Leer `status` (dónde va el proceso) y `result` (qué dijo el biométrico) **por separado**: el
+     * veredicto del facematch llega antes del cierre, así que `result` puede venir en `MATCH` con
+     * `status` todavía en `IN_PROGRESS`. No es una inconsistencia.
+     *
+     * La expiración no depende de que llegue ningún evento: este `GET` la calcula y la persiste.
+     */
+    getBiometricVerification(
+        biometricVerificationId: string,
+    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+
+    /**
+     * Avisa que el proveedor reportó algo sobre una verificación. **Su único caller legítimo es
+     * `kyc-metamap-webhook`** — un producto normal no llama acá.
+     *
+     * 🔴 **Idempotente por `eventId`, y eso NO es un detalle.** Este canal reemplaza a una cola, así
+     * que la durabilidad la da el reintento del proveedor: recibir el mismo evento dos veces es el
+     * camino NORMAL, no la excepción. Un `eventId` repetido devuelve 200 y no aplica nada.
+     *
+     * Cómo tratar la respuesta desde el webhook:
+     * - `200` → aplicado o descartado por duplicado. Los dos son éxito.
+     * - `404` / `409` → **no reintentar**: no existe, o ya está en un estado terminal.
+     * - `5xx` → devolver no-200 al proveedor **para que reintente**. Esto es seguro SOLO en la rama
+     *   biométrica, que corta antes de escribir nada y no tiene efectos que duplicar.
+     */
+    applyBiometricEvent(
+        biometricVerificationId: string,
+        data: BiometricVerificationChangedV1,
+    ): Promise<ApiGatewayResponse<void>>;
+}

package/src/container.config.ts

@@ -14,6 +14,8 @@ import { IAccountPagoConfiadoApi } from "./account-pagoconfiado/index.js";
 import AccountPagoConfiadoApi from "./account-pagoconfiado/AccountPagoConfiadoApi.js";
 import { IMetamapConnectorApi } from "./metamap-connector/index.js";
 import MetamapConnectorApi from "./metamap-connector/MetamapConnectorApi.js";
+import { IBiometricsBusinessApi } from "./biometrics-business/index.js";
+import BiometricsBusinessApi from "./biometrics-business/BiometricsBusinessApi.js";
 import { IAccountFiadoSAApi } from "./account-fiadosa/index.js";
 import AccountFiadoSAApi from "./account-fiadosa/AccountFiadoSAApi.js";
 import { ISTPAccountApi } from "./stpAccount/index.js";
@@ -204,6 +206,7 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     bind<IAccountFiadoIncApi>("IAccountFiadoIncApi").to(AccountFiadoIncApi);
     bind<IAccountPagoConfiadoApi>("IAccountPagoConfiadoApi").to(AccountPagoConfiadoApi);
     bind<IMetamapConnectorApi>("IMetamapConnectorApi").to(MetamapConnectorApi);
+    bind<IBiometricsBusinessApi>("IBiometricsBusinessApi").to(BiometricsBusinessApi);
     bind<IAccountFiadoSAApi>("IAccountFiadoSAApi").to(AccountFiadoSAApi);
     bind<INotificationMessagesPublisher>("INotificationMessagesPublisher").to(NotificationMessagePublisher);
     bind<INotificationWSMessagesPublisher>("INotificationWSMessagesPublisher").to(NotificationWSMessagePublisher);

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./account-fiadoinc/index.js";
 export * from "./account-fiadosa/index.js";
 export * from "./account-pagoconfiado/index.js";
 export * from "./metamap-connector/index.js";
+export * from "./biometrics-business/index.js";
 export * from "./account-beneficiary/index.js";
 export * from "./exchangeRates/index.js";
 export * from "./authentication/index.js";

package/src/zendesk/ZendeskApi.ts

@@ -4,6 +4,7 @@ import { IHttpRequest } from "@fiado/http-client";
 import { IZendeskApi } from "./interfaces/IZendeskApi.js";
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { HelpdeskCreateUserRequest, HelpdeskCreateTicketRequest } from '@fiado/type-kit/bin/helpdesk/index.js';
+import { SendProactiveMessageRequest, ISendProactiveMessageResponse } from '@fiado/type-kit/bin/zendeskMessaging/index.js';
 dotenv.config();
 
 @injectable()
@@ -26,4 +27,9 @@ export class ZendeskApi implements IZendeskApi {
         const url = `${this.baseUrl}private/directory/${directoryId}`;
         return await this.httpRequest.delete<FiadoApiResponse<{ deletedCount: number }>>(url);
     }
+
+    async sendProactiveMessage(data: SendProactiveMessageRequest): Promise<FiadoApiResponse<ISendProactiveMessageResponse>> {
+        const url: string = `${this.baseUrl}messaging/send-proactive`;
+        return await this.httpRequest.post<FiadoApiResponse<ISendProactiveMessageResponse>>(url, data);
+    }
 }

package/src/zendesk/interfaces/IZendeskApi.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { HelpdeskCreateTicketRequest, HelpdeskCreateUserRequest } from '@fiado/type-kit/bin/helpdesk/index.js';
+import { SendProactiveMessageRequest, ISendProactiveMessageResponse } from '@fiado/type-kit/bin/zendeskMessaging/index.js';
 
 /**
  * Interfaz para el servicio de Zendesk
@@ -15,4 +16,11 @@ export interface IZendeskApi {
      */
     // TODO(type-kit): swap a Directory.DeleteByDirectoryResponse cuando se publique
     deleteByDirectoryId(directoryId: string): Promise<FiadoApiResponse<{ deletedCount: number }>>;
+
+    /**
+     * Envia un mensaje proactivo a un usuario via Zendesk Messaging (Sunshine Conversations).
+     * Crea (o reutiliza) el usuario y la conversacion en Sunshine a partir del directoryId.
+     * @param data directoryId + message (displayName opcional).
+     */
+    sendProactiveMessage(data: SendProactiveMessageRequest): Promise<FiadoApiResponse<ISendProactiveMessageResponse>>;
 }