@fiado/api-invoker 5.37.0 → 5.39.0

package/bin/container.config.js

@@ -128,6 +128,8 @@ import { ResearchSheetsApi } from "./research-sheets/index.js";
 import { AuthBusinessApi } from "./auth-business/index.js";
 // KYC verifications business — lectura confirmatoria server-side del KYC por directoryId (SureKeep F2)
 import { KycVerificationsBusinessApi } from "./kyc/index.js";
+// Webhook business — publisher de la cola compartida de entrega de eventos a suscriptores externos
+import { WebhookBusinessPublisher } from "./webhook-business/index.js";
 import { CentralPaymentsWebhookApi } from "./central-payments-webhook/index.js";
 import CollectionEngineApi from "./collection-engine/api/CollectionEngineApi.js";
 import DomainCallbackApi from "./domain-callback/api/DomainCallbackApi.js";
@@ -274,6 +276,9 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     // KYC verifications business — lectura confirmatoria server-side del KYC por directoryId.
     // La consume el wizard de SureKeep F2 tras el aviso async del stream de `KycVerifications`.
     bind("IKycVerificationsBusinessApi").to(KycVerificationsBusinessApi);
+    // Webhook business — lo produce cualquier lambda que tenga algo que avisarle a un externo.
+    // El productor necesita WEBHOOK_BUSINESS_QUEUE_URL y sqs:SendMessage sobre la cola.
+    bind("IWebhookBusinessPublisher").to(WebhookBusinessPublisher);
     bind("ICentralPaymentsWebhookApi").to(CentralPaymentsWebhookApi);
     // Collection engine — motor de cobro central multitenant (collect/registerCollectible/deregister)
     bind("ICollectionEngineApi").to(CollectionEngineApi);

package/bin/index.d.ts

@@ -85,6 +85,7 @@ export * from "./datalakeQuery/index.js";
 export * from "./retailCustomer/index.js";
 export * from "./retailCatalog/index.js";
 export * from "./retailCards/index.js";
+export * from "./retailNotifications/index.js";
 export * from "./shortlink/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
@@ -111,3 +112,4 @@ export * from "./central-payments-webhook/index.js";
 export * from "./collection-engine/index.js";
 export * from "./domain-callback/index.js";
 export * from "./datacultrConnector/index.js";
+export * from "./webhook-business/index.js";

package/bin/index.js

@@ -85,6 +85,7 @@ export * from "./datalakeQuery/index.js";
 export * from "./retailCustomer/index.js";
 export * from "./retailCatalog/index.js";
 export * from "./retailCards/index.js";
+export * from "./retailNotifications/index.js";
 export * from "./shortlink/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
@@ -111,3 +112,4 @@ export * from "./central-payments-webhook/index.js";
 export * from "./collection-engine/index.js";
 export * from "./domain-callback/index.js";
 export * from "./datacultrConnector/index.js";
+export * from "./webhook-business/index.js";

package/bin/retailNotifications/api/RetailNotificationsWebsocketApi.d.ts

@@ -0,0 +1,17 @@
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { IRetailNotificationsWebsocketApi } from "./interfaces/IRetailNotificationsWebsocketApi.js";
+import { NotifySubjectRequest } from "./dtos/NotifySubjectRequest.js";
+import { NotifySubjectResult } from "./dtos/NotifySubjectResult.js";
+/**
+ * Publisher HTTP del lambda `retail-notifications-websocket` (SureKeep Fase 2) para su privado M2M de
+ * avisos al vendedor. Contrato y semántica completos → `IRetailNotificationsWebsocketApi`.
+ *
+ * Env var requerida en el consumer: `RETAIL_NOTIFICATIONS_WEBSOCKET_URL`.
+ */
+export default class RetailNotificationsWebsocketApi implements IRetailNotificationsWebsocketApi {
+    private httpRequest;
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    notifySubject(payload: NotifySubjectRequest): Promise<StandardResponse<NotifySubjectResult>>;
+}

package/bin/retailNotifications/api/RetailNotificationsWebsocketApi.js

@@ -0,0 +1,36 @@
+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";
+/**
+ * Publisher HTTP del lambda `retail-notifications-websocket` (SureKeep Fase 2) para su privado M2M de
+ * avisos al vendedor. Contrato y semántica completos → `IRetailNotificationsWebsocketApi`.
+ *
+ * Env var requerida en el consumer: `RETAIL_NOTIFICATIONS_WEBSOCKET_URL`.
+ */
+let RetailNotificationsWebsocketApi = class RetailNotificationsWebsocketApi {
+    httpRequest;
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    baseUrl = (process.env.RETAIL_NOTIFICATIONS_WEBSOCKET_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    async notifySubject(payload) {
+        return await this.httpRequest.post(`${this.baseUrl}/private/notifications`, payload);
+    }
+};
+RetailNotificationsWebsocketApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], RetailNotificationsWebsocketApi);
+export default RetailNotificationsWebsocketApi;

package/bin/retailNotifications/api/dtos/NotifySubjectRequest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Catálogo de avisos que el canal WebSocket de SureKeep sabe empujar. Espeja el
+ * `NotificationTypeEnum` de `retail-notifications-websocket`, que valida el cuerpo con `@IsEnum`: un tipo
+ * fuera del catálogo se rechaza con 400 `INVALID_PAYLOAD`.
+ */
+export type RetailNotificationType = 'SALE_UPDATED';
+/**
+ * Lo que viaja por el privado M2M: a qué vendedor avisarle, de qué y sobre cuál de sus ventas.
+ * NO lleva ningún dato del comprador — el navegador recibe solo el tipo y el id de la venta, y el
+ * detalle se lo pide después al wizard.
+ */
+export interface NotifySubjectRequest {
+    /** `sub` de Cognito del vendedor destinatario. Máx. 128 caracteres. */
+    subjectId: string;
+    type: RetailNotificationType;
+    /** Id de la venta, para que el vendedor sepa de cuál de las suyas se trata. Máx. 128 caracteres. */
+    sessionId: string;
+}

package/bin/retailNotifications/api/dtos/NotifySubjectRequest.js

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

package/bin/retailNotifications/api/dtos/NotifySubjectResult.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resultado de una entrega. `delivered: 0` significa que el vendedor NO tiene ningún socket abierto
+ * —tiene la pestaña cerrada— y NO es un error: el llamador no debe reintentar ni alarmar.
+ */
+export interface NotifySubjectResult {
+    /** Conexiones a las que llegó el aviso. */
+    delivered: number;
+    /** Filas de conexiones muertas que el destino limpió de paso. */
+    staleRemoved: number;
+    /** Conexiones vivas a las que el envío falló. */
+    failed: number;
+}

package/bin/retailNotifications/api/dtos/NotifySubjectResult.js

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

package/bin/retailNotifications/api/interfaces/IRetailNotificationsWebsocketApi.d.ts

@@ -0,0 +1,43 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { NotifySubjectRequest } from "../dtos/NotifySubjectRequest.js";
+import { NotifySubjectResult } from "../dtos/NotifySubjectResult.js";
+/**
+ * Contrato del publisher HTTP del lambda `retail-notifications-websocket` (SureKeep Fase 2): el canal por
+ * el que el portal le avisa al VENDEDOR que su venta cambió de estado.
+ *
+ * Consumidor previsto:
+ *   - `retail-wizard-business` → al asentar el desenlace de una venta (stream de la cuenta PCF).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SIN TENANT — a diferencia de los clients retail, este NO manda `?tenantId=`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El destino resuelve el silo de SU PROPIO entorno (`resolveTenantId`), nunca del request: el
+ * `tenantId` es el hash del GSI de ruteo, así que el aislamiento no puede depender de quien llama.
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ *
+ * Los DTOs viven acá y no en `@fiado/type-kit` porque el destino tampoco depende de type-kit: sus
+ * DTOs son locales. Si algún día el contrato se comparte con un tercer repo, mudarlos a type-kit.
+ *
+ * Env var requerida en el consumer: `RETAIL_NOTIFICATIONS_WEBSOCKET_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_NOTIFICATIONS_WEBSOCKET_URL: '{{resolve:ssm:retail-notifications-websocket}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface IRetailNotificationsWebsocketApi {
+    /**
+     * POST `/private/notifications` — empuja un aviso al vendedor por su WebSocket abierto.
+     *
+     * Semántica de la respuesta, que decide qué hacer ante cada desenlace:
+     *   · 200 con `delivered: 0` → el vendedor tiene la pestaña cerrada. NO es error, NO reintentar.
+     *   · 400 `INVALID_PAYLOAD` → el cuerpo está mal (falta un campo, tipo fuera del catálogo).
+     *     NO reintentar: reintentarlo igual da lo mismo.
+     *   · 500 `INTERNAL_ERROR` → falló el canal. El request estaba bien y se PUEDE reintentar.
+     *
+     * Avisar es un efecto de borde: si falla, el aviso se pierde y lo cubre el barrido del wizard.
+     * Nunca debe bloquear ni deshacer la operación que lo disparó.
+     */
+    notifySubject(payload: NotifySubjectRequest): Promise<StandardResponse<NotifySubjectResult>>;
+}

package/bin/retailNotifications/api/interfaces/IRetailNotificationsWebsocketApi.js

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

package/bin/retailNotifications/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./api/dtos/NotifySubjectRequest.js";
+export * from "./api/dtos/NotifySubjectResult.js";
+export * from "./api/interfaces/IRetailNotificationsWebsocketApi.js";
+export { default as RetailNotificationsWebsocketApi } from "./api/RetailNotificationsWebsocketApi.js";

package/bin/retailNotifications/index.js

@@ -0,0 +1,4 @@
+export * from "./api/dtos/NotifySubjectRequest.js";
+export * from "./api/dtos/NotifySubjectResult.js";
+export * from "./api/interfaces/IRetailNotificationsWebsocketApi.js";
+export { default as RetailNotificationsWebsocketApi } from "./api/RetailNotificationsWebsocketApi.js";

package/bin/transactionProcessor/api/TransactionProcessorApi.d.ts

@@ -1,6 +1,6 @@
 import { ITransactionProcessorApi } from "./interfaces/ITransactionProcessorApi.js";
 import type { IHttpRequest } from "@fiado/http-client";
-import { AuthorizeCollectorOrderRequest, AuthorizeCollectorOrderResponse, AuthorizeCollectorTransactionRequest, AuthorizeCreditCardPurchaseRequest, AuthorizeSpeiBankTransferNcRequest, AuthorizeSpeiMexBankTransferInRequest, AuthorizeRenewalPreAuthRequest, AuthorizeRenewalPreAuthResponse } from "@fiado/type-kit/bin/transactionProcessor/index.js";
+import { AuthorizeCollectorOrderRequest, AuthorizeCollectorOrderResponse, AuthorizeCollectorTransactionRequest, AuthorizeCreditCardPurchaseRequest, AuthorizeSpeiBankTransferNcRequest, AuthorizeSpeiMexBankTransferInRequest, AuthorizeRenewalPreAuthRequest, AuthorizeRenewalPreAuthResponse, AuthorizeBonusRequest, TransactionProcessorResponse } from "@fiado/type-kit/bin/transactionProcessor/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import { ValidateWalletFundingRequest, ValidateWalletFundingResponse, CreditWalletFundingRequest, CreditWalletFundingResponse, ReverseWalletFundingRequest, ReverseWalletFundingResponse, GetWalletFundingLimitRequest, GetWalletFundingLimitResponse } from "@fiado/type-kit/bin/walletFunding/index.js";
 import { RemittanceCreditBackRequest, RemittanceCreditBackResponse } from "@fiado/type-kit/bin/remittance/index.js";
@@ -24,5 +24,6 @@ export default class TransactionProcessorApi implements ITransactionProcessorApi
     walletFundingGetLimit(request: GetWalletFundingLimitRequest): Promise<ApiGatewayResponse<GetWalletFundingLimitResponse>>;
     creditBack(request: RemittanceCreditBackRequest): Promise<FiadoApiResponse<RemittanceCreditBackResponse>>;
     authorizeCollectionMovement(request: AuthorizeCollectionMovementRequest): Promise<FiadoApiResponse<AuthorizeCollectionMovementResponse>>;
+    authorizeWelcomeBonus(request: AuthorizeBonusRequest): Promise<FiadoApiResponse<TransactionProcessorResponse>>;
 }
 export {};

package/bin/transactionProcessor/api/TransactionProcessorApi.js

@@ -69,6 +69,10 @@ let TransactionProcessorApi = class TransactionProcessorApi {
         const url = `${this.baseUrl}collection/authorize`;
         return await this.httpRequest.post(url, request);
     }
+    async authorizeWelcomeBonus(request) {
+        const url = `${this.baseUrl}bonus/authorize`;
+        return await this.httpRequest.post(url, request);
+    }
 };
 TransactionProcessorApi = __decorate([
     injectable(),

package/bin/transactionProcessor/api/interfaces/ITransactionProcessorApi.d.ts

@@ -1,5 +1,5 @@
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
-import { AuthorizeCollectorOrderRequest, AuthorizeCollectorOrderResponse, AuthorizeCollectorTransactionRequest, AuthorizeCreditCardPurchaseRequest, AuthorizeSpeiBankTransferNcRequest, AuthorizeSpeiMexBankTransferInRequest, AuthorizeRenewalPreAuthRequest, AuthorizeRenewalPreAuthResponse } from "@fiado/type-kit/bin/transactionProcessor/index.js";
+import { AuthorizeCollectorOrderRequest, AuthorizeCollectorOrderResponse, AuthorizeCollectorTransactionRequest, AuthorizeCreditCardPurchaseRequest, AuthorizeSpeiBankTransferNcRequest, AuthorizeSpeiMexBankTransferInRequest, AuthorizeRenewalPreAuthRequest, AuthorizeRenewalPreAuthResponse, AuthorizeBonusRequest, TransactionProcessorResponse } from "@fiado/type-kit/bin/transactionProcessor/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import { ValidateWalletFundingRequest, ValidateWalletFundingResponse, CreditWalletFundingRequest, CreditWalletFundingResponse, ReverseWalletFundingRequest, ReverseWalletFundingResponse, GetWalletFundingLimitRequest, GetWalletFundingLimitResponse } from "@fiado/type-kit/bin/walletFunding/index.js";
 import { RemittanceCreditBackRequest, RemittanceCreditBackResponse } from "@fiado/type-kit/bin/remittance/index.js";
@@ -54,5 +54,11 @@ export interface ITransactionProcessorApi {
      * Idempotente por `executionId` (@IdempotencyController).
      */
     authorizeCollectionMovement(request: AuthorizeCollectionMovementRequest): Promise<FiadoApiResponse<AuthorizeCollectionMovementResponse>>;
+    /**
+     * Acredita el bono de bienvenida de SureKeep en la wallet PagoConfiado del comprador.
+     * Backend: POST /transaction-processor/bonus/authorize (privado VPC).
+     * Idempotente por `idempotencyKey` (el `bonusId` del asiento).
+     */
+    authorizeWelcomeBonus(request: AuthorizeBonusRequest): Promise<FiadoApiResponse<TransactionProcessorResponse>>;
 }
 export {};

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

@@ -0,0 +1,2 @@
+export * from './queue/interfaces/IWebhookBusinessPublisher.js';
+export * from './queue/WebhookBusinessPublisher.js';

package/bin/webhook-business/index.js

@@ -0,0 +1,2 @@
+export * from './queue/interfaces/IWebhookBusinessPublisher.js';
+export * from './queue/WebhookBusinessPublisher.js';

package/bin/webhook-business/queue/WebhookBusinessPublisher.d.ts

@@ -0,0 +1,6 @@
+import { WebhookOutboundMessage } from "@fiado/type-kit/bin/webhookBusiness/index.js";
+import { IWebhookBusinessPublisher } from "./interfaces/IWebhookBusinessPublisher.js";
+export declare class WebhookBusinessPublisher implements IWebhookBusinessPublisher {
+    private readonly WEBHOOK_BUSINESS_QUEUE_URL;
+    publish(message: WebhookOutboundMessage): Promise<void>;
+}

package/bin/webhook-business/queue/WebhookBusinessPublisher.js

@@ -0,0 +1,32 @@
+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;
+};
+import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
+import { injectable } from "inversify";
+let WebhookBusinessPublisher = class WebhookBusinessPublisher {
+    WEBHOOK_BUSINESS_QUEUE_URL = process.env.WEBHOOK_BUSINESS_QUEUE_URL;
+    async publish(message) {
+        try {
+            const client = new SQSClient();
+            // Cola ESTÁNDAR (no FIFO): sin MessageGroupId/MessageDeduplicationId ni orden garantizado.
+            // El consumidor deduplica por `eventId` del sobre y reordena por `occurredAt`.
+            const sendMessageRequest = {
+                QueueUrl: this.WEBHOOK_BUSINESS_QUEUE_URL,
+                MessageBody: JSON.stringify(message),
+            };
+            const command = new SendMessageCommand(sendMessageRequest);
+            await client.send(command);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Error publishing message to WebhookBusinessQueue: ${errorMessage}`);
+        }
+    }
+};
+WebhookBusinessPublisher = __decorate([
+    injectable()
+], WebhookBusinessPublisher);
+export { WebhookBusinessPublisher };

package/bin/webhook-business/queue/interfaces/IWebhookBusinessPublisher.d.ts

@@ -0,0 +1,20 @@
+import { WebhookOutboundMessage } from "@fiado/type-kit/bin/webhookBusiness/index.js";
+/**
+ * Publisher de Fiado hacia `WebhookBusinessQueue`, que consume `webhook-business` para entregarle
+ * el evento a los suscriptores externos que tengan el tag `wh:*` del `directoryId`.
+ *
+ * Lo produce cualquier lambda de Fiado que tenga algo que avisarle a un externo (la emisión de la
+ * cuenta PCF, el dictamen de cumplimiento). Vive aquí —y no como SDK crudo en cada lambda— porque la
+ * cola es COMPARTIDA cross-lambda: el estándar Fiado publica a una cola compartida vía Publisher de
+ * `@fiado/api-invoker` (mismo patrón que `IRetailKycInboundPublisher`).
+ *
+ * El productor necesita la env var `WEBHOOK_BUSINESS_QUEUE_URL` en su `template.yml` (la misma que
+ * ya declara `webhook-business` del lado consumidor) y permiso `sqs:SendMessage` sobre la cola.
+ *
+ * El tipo del mensaje es la unión cerrada `WebhookOutboundMessage` del `@fiado/type-kit`: agregar un
+ * evento obliga a tocar también el router del consumidor, que es la conversación que tiene que
+ * pasar antes de meter un mensaje nuevo en una cola compartida.
+ */
+export interface IWebhookBusinessPublisher {
+    publish(message: WebhookOutboundMessage): Promise<void>;
+}

package/bin/webhook-business/queue/interfaces/IWebhookBusinessPublisher.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.37.0",
+  "version": "5.39.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.329.0",
+    "@fiado/type-kit": "^3.360.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/container.config.ts

@@ -192,6 +192,8 @@ import { IResearchSheetsApi, ResearchSheetsApi } from "./research-sheets/index.j
 import { IAuthBusinessApi, AuthBusinessApi } from "./auth-business/index.js";
 // KYC verifications business — lectura confirmatoria server-side del KYC por directoryId (SureKeep F2)
 import { IKycVerificationsBusinessApi, KycVerificationsBusinessApi } from "./kyc/index.js";
+// Webhook business — publisher de la cola compartida de entrega de eventos a suscriptores externos
+import { IWebhookBusinessPublisher, WebhookBusinessPublisher } from "./webhook-business/index.js";
 import { ICentralPaymentsWebhookApi, CentralPaymentsWebhookApi } from "./central-payments-webhook/index.js";
 // Collection engine — cliente del motor de cobro central (collect/registerCollectible/deregister)
 import { ICollectionEngineApi } from "./collection-engine/index.js";
@@ -366,6 +368,10 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     // KYC verifications business — lectura confirmatoria server-side del KYC por directoryId.
     // La consume el wizard de SureKeep F2 tras el aviso async del stream de `KycVerifications`.
     bind<IKycVerificationsBusinessApi>("IKycVerificationsBusinessApi").to(KycVerificationsBusinessApi);
+
+    // Webhook business — lo produce cualquier lambda que tenga algo que avisarle a un externo.
+    // El productor necesita WEBHOOK_BUSINESS_QUEUE_URL y sqs:SendMessage sobre la cola.
+    bind<IWebhookBusinessPublisher>("IWebhookBusinessPublisher").to(WebhookBusinessPublisher);
     bind<ICentralPaymentsWebhookApi>("ICentralPaymentsWebhookApi").to(CentralPaymentsWebhookApi);
 
     // Collection engine — motor de cobro central multitenant (collect/registerCollectible/deregister)

package/src/index.ts

@@ -85,6 +85,7 @@ export * from "./datalakeQuery/index.js";
 export * from "./retailCustomer/index.js";
 export * from "./retailCatalog/index.js";
 export * from "./retailCards/index.js";
+export * from "./retailNotifications/index.js";
 export * from "./shortlink/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
@@ -111,3 +112,4 @@ export * from "./central-payments-webhook/index.js";
 export * from "./collection-engine/index.js";
 export * from "./domain-callback/index.js";
 export * from "./datacultrConnector/index.js";
+export * from "./webhook-business/index.js";

package/src/retailNotifications/api/RetailNotificationsWebsocketApi.ts

@@ -0,0 +1,24 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { IRetailNotificationsWebsocketApi } from "./interfaces/IRetailNotificationsWebsocketApi.js";
+import { NotifySubjectRequest } from "./dtos/NotifySubjectRequest.js";
+import { NotifySubjectResult } from "./dtos/NotifySubjectResult.js";
+
+/**
+ * Publisher HTTP del lambda `retail-notifications-websocket` (SureKeep Fase 2) para su privado M2M de
+ * avisos al vendedor. Contrato y semántica completos → `IRetailNotificationsWebsocketApi`.
+ *
+ * Env var requerida en el consumer: `RETAIL_NOTIFICATIONS_WEBSOCKET_URL`.
+ */
+@injectable()
+export default class RetailNotificationsWebsocketApi implements IRetailNotificationsWebsocketApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    private readonly baseUrl = (process.env.RETAIL_NOTIFICATIONS_WEBSOCKET_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async notifySubject(payload: NotifySubjectRequest): Promise<StandardResponse<NotifySubjectResult>> {
+        return await this.httpRequest.post(`${this.baseUrl}/private/notifications`, payload);
+    }
+}

package/src/retailNotifications/api/dtos/NotifySubjectRequest.ts

@@ -0,0 +1,19 @@
+/**
+ * Catálogo de avisos que el canal WebSocket de SureKeep sabe empujar. Espeja el
+ * `NotificationTypeEnum` de `retail-notifications-websocket`, que valida el cuerpo con `@IsEnum`: un tipo
+ * fuera del catálogo se rechaza con 400 `INVALID_PAYLOAD`.
+ */
+export type RetailNotificationType = 'SALE_UPDATED';
+
+/**
+ * Lo que viaja por el privado M2M: a qué vendedor avisarle, de qué y sobre cuál de sus ventas.
+ * NO lleva ningún dato del comprador — el navegador recibe solo el tipo y el id de la venta, y el
+ * detalle se lo pide después al wizard.
+ */
+export interface NotifySubjectRequest {
+    /** `sub` de Cognito del vendedor destinatario. Máx. 128 caracteres. */
+    subjectId: string;
+    type: RetailNotificationType;
+    /** Id de la venta, para que el vendedor sepa de cuál de las suyas se trata. Máx. 128 caracteres. */
+    sessionId: string;
+}

package/src/retailNotifications/api/dtos/NotifySubjectResult.ts

@@ -0,0 +1,12 @@
+/**
+ * Resultado de una entrega. `delivered: 0` significa que el vendedor NO tiene ningún socket abierto
+ * —tiene la pestaña cerrada— y NO es un error: el llamador no debe reintentar ni alarmar.
+ */
+export interface NotifySubjectResult {
+    /** Conexiones a las que llegó el aviso. */
+    delivered: number;
+    /** Filas de conexiones muertas que el destino limpió de paso. */
+    staleRemoved: number;
+    /** Conexiones vivas a las que el envío falló. */
+    failed: number;
+}

package/src/retailNotifications/api/interfaces/IRetailNotificationsWebsocketApi.ts

@@ -0,0 +1,44 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { NotifySubjectRequest } from "../dtos/NotifySubjectRequest.js";
+import { NotifySubjectResult } from "../dtos/NotifySubjectResult.js";
+
+/**
+ * Contrato del publisher HTTP del lambda `retail-notifications-websocket` (SureKeep Fase 2): el canal por
+ * el que el portal le avisa al VENDEDOR que su venta cambió de estado.
+ *
+ * Consumidor previsto:
+ *   - `retail-wizard-business` → al asentar el desenlace de una venta (stream de la cuenta PCF).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SIN TENANT — a diferencia de los clients retail, este NO manda `?tenantId=`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El destino resuelve el silo de SU PROPIO entorno (`resolveTenantId`), nunca del request: el
+ * `tenantId` es el hash del GSI de ruteo, así que el aislamiento no puede depender de quien llama.
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ *
+ * Los DTOs viven acá y no en `@fiado/type-kit` porque el destino tampoco depende de type-kit: sus
+ * DTOs son locales. Si algún día el contrato se comparte con un tercer repo, mudarlos a type-kit.
+ *
+ * Env var requerida en el consumer: `RETAIL_NOTIFICATIONS_WEBSOCKET_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_NOTIFICATIONS_WEBSOCKET_URL: '{{resolve:ssm:retail-notifications-websocket}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface IRetailNotificationsWebsocketApi {
+    /**
+     * POST `/private/notifications` — empuja un aviso al vendedor por su WebSocket abierto.
+     *
+     * Semántica de la respuesta, que decide qué hacer ante cada desenlace:
+     *   · 200 con `delivered: 0` → el vendedor tiene la pestaña cerrada. NO es error, NO reintentar.
+     *   · 400 `INVALID_PAYLOAD` → el cuerpo está mal (falta un campo, tipo fuera del catálogo).
+     *     NO reintentar: reintentarlo igual da lo mismo.
+     *   · 500 `INTERNAL_ERROR` → falló el canal. El request estaba bien y se PUEDE reintentar.
+     *
+     * Avisar es un efecto de borde: si falla, el aviso se pierde y lo cubre el barrido del wizard.
+     * Nunca debe bloquear ni deshacer la operación que lo disparó.
+     */
+    notifySubject(payload: NotifySubjectRequest): Promise<StandardResponse<NotifySubjectResult>>;
+}

package/src/retailNotifications/index.ts

@@ -0,0 +1,4 @@
+export * from "./api/dtos/NotifySubjectRequest.js";
+export * from "./api/dtos/NotifySubjectResult.js";
+export * from "./api/interfaces/IRetailNotificationsWebsocketApi.js";
+export { default as RetailNotificationsWebsocketApi } from "./api/RetailNotificationsWebsocketApi.js";

package/src/transactionProcessor/api/TransactionProcessorApi.ts

@@ -8,7 +8,9 @@ import {
     AuthorizeCreditCardPurchaseRequest, AuthorizeSpeiBankTransferNcRequest,
     AuthorizeSpeiMexBankTransferInRequest,
     AuthorizeRenewalPreAuthRequest,
-    AuthorizeRenewalPreAuthResponse
+    AuthorizeRenewalPreAuthResponse,
+    AuthorizeBonusRequest,
+    TransactionProcessorResponse
 } from "@fiado/type-kit/bin/transactionProcessor/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import {
@@ -113,4 +115,11 @@ export default class TransactionProcessorApi implements ITransactionProcessorApi
         const url = `${this.baseUrl}collection/authorize`;
         return await this.httpRequest.post(url, request);
     }
+
+    async authorizeWelcomeBonus(
+        request: AuthorizeBonusRequest,
+    ): Promise<FiadoApiResponse<TransactionProcessorResponse>> {
+        const url = `${this.baseUrl}bonus/authorize`;
+        return await this.httpRequest.post(url, request);
+    }
 }

package/src/transactionProcessor/api/interfaces/ITransactionProcessorApi.ts

@@ -7,7 +7,9 @@ import {
     AuthorizeSpeiBankTransferNcRequest,
     AuthorizeSpeiMexBankTransferInRequest,
     AuthorizeRenewalPreAuthRequest,
-    AuthorizeRenewalPreAuthResponse
+    AuthorizeRenewalPreAuthResponse,
+    AuthorizeBonusRequest,
+    TransactionProcessorResponse
 } from "@fiado/type-kit/bin/transactionProcessor/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import {
@@ -101,4 +103,13 @@ export interface ITransactionProcessorApi {
     authorizeCollectionMovement(
         request: AuthorizeCollectionMovementRequest,
     ): Promise<FiadoApiResponse<AuthorizeCollectionMovementResponse>>;
+
+    /**
+     * Acredita el bono de bienvenida de SureKeep en la wallet PagoConfiado del comprador.
+     * Backend: POST /transaction-processor/bonus/authorize (privado VPC).
+     * Idempotente por `idempotencyKey` (el `bonusId` del asiento).
+     */
+    authorizeWelcomeBonus(
+        request: AuthorizeBonusRequest,
+    ): Promise<FiadoApiResponse<TransactionProcessorResponse>>;
 }

package/src/webhook-business/index.ts

@@ -0,0 +1,2 @@
+export * from './queue/interfaces/IWebhookBusinessPublisher.js';
+export * from './queue/WebhookBusinessPublisher.js';

package/src/webhook-business/queue/WebhookBusinessPublisher.ts

@@ -0,0 +1,26 @@
+import { SendMessageCommand, SendMessageRequest, SQSClient } from "@aws-sdk/client-sqs";
+import { injectable } from "inversify";
+import { WebhookOutboundMessage } from "@fiado/type-kit/bin/webhookBusiness/index.js";
+import { IWebhookBusinessPublisher } from "./interfaces/IWebhookBusinessPublisher.js";
+
+@injectable()
+export class WebhookBusinessPublisher implements IWebhookBusinessPublisher {
+    private readonly WEBHOOK_BUSINESS_QUEUE_URL = process.env.WEBHOOK_BUSINESS_QUEUE_URL;
+
+    async publish(message: WebhookOutboundMessage): Promise<void> {
+        try {
+            const client: SQSClient = new SQSClient();
+            // Cola ESTÁNDAR (no FIFO): sin MessageGroupId/MessageDeduplicationId ni orden garantizado.
+            // El consumidor deduplica por `eventId` del sobre y reordena por `occurredAt`.
+            const sendMessageRequest: SendMessageRequest = {
+                QueueUrl: this.WEBHOOK_BUSINESS_QUEUE_URL,
+                MessageBody: JSON.stringify(message),
+            };
+            const command: SendMessageCommand = new SendMessageCommand(sendMessageRequest);
+            await client.send(command);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Error publishing message to WebhookBusinessQueue: ${errorMessage}`);
+        }
+    }
+}

package/src/webhook-business/queue/interfaces/IWebhookBusinessPublisher.ts

@@ -0,0 +1,21 @@
+import { WebhookOutboundMessage } from "@fiado/type-kit/bin/webhookBusiness/index.js";
+
+/**
+ * Publisher de Fiado hacia `WebhookBusinessQueue`, que consume `webhook-business` para entregarle
+ * el evento a los suscriptores externos que tengan el tag `wh:*` del `directoryId`.
+ *
+ * Lo produce cualquier lambda de Fiado que tenga algo que avisarle a un externo (la emisión de la
+ * cuenta PCF, el dictamen de cumplimiento). Vive aquí —y no como SDK crudo en cada lambda— porque la
+ * cola es COMPARTIDA cross-lambda: el estándar Fiado publica a una cola compartida vía Publisher de
+ * `@fiado/api-invoker` (mismo patrón que `IRetailKycInboundPublisher`).
+ *
+ * El productor necesita la env var `WEBHOOK_BUSINESS_QUEUE_URL` en su `template.yml` (la misma que
+ * ya declara `webhook-business` del lado consumidor) y permiso `sqs:SendMessage` sobre la cola.
+ *
+ * El tipo del mensaje es la unión cerrada `WebhookOutboundMessage` del `@fiado/type-kit`: agregar un
+ * evento obliga a tocar también el router del consumidor, que es la conversación que tiene que
+ * pasar antes de meter un mensaje nuevo en una cola compartida.
+ */
+export interface IWebhookBusinessPublisher {
+    publish(message: WebhookOutboundMessage): Promise<void>;
+}