@fiado/api-invoker 5.44.0 → 5.46.0

package/bin/account-pagoconfiado/AccountPagoConfiadoApi.d.ts

@@ -1,7 +1,7 @@
 import { IAccountPagoConfiadoApi } from "./interfaces/IAccountPagoConfiadoApi.js";
-import { AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, GetAccountResponse, GetAccountResponseList } from "@fiado/type-kit/bin/account/index.js";
+import { AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, CollectDebitRequest, CollectDebitResponse, GetAccountResponse, GetAccountResponseList } from "@fiado/type-kit/bin/account/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
-import { IHttpRequest } from "@fiado/http-client";
+import type { IHttpRequest } from "@fiado/http-client";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 export default class AccountPagoConfiadoApi implements IAccountPagoConfiadoApi {
     private httpRequest;
@@ -11,6 +11,7 @@ export default class AccountPagoConfiadoApi implements IAccountPagoConfiadoApi {
     createAccount(provider: Provider, data: AccountCreateRequest): Promise<ApiGatewayResponse<AccountCreateResponse>>;
     getAccountByDirectoryId(directoryId: string): Promise<ApiGatewayResponse<GetAccountResponse[]>>;
     updateAccountBalance(accountId: string, params: AccountUpdateBalanceRequest): Promise<ApiGatewayResponse<Boolean>>;
+    collectDebit(accountId: string, request: CollectDebitRequest): Promise<ApiGatewayResponse<CollectDebitResponse>>;
     update(directoryId: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;
     updateByAccountNumber(accountNumber: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;
     getAccountByAccountNumber(accountNumber: string): Promise<ApiGatewayResponse<void>>;

package/bin/account-pagoconfiado/AccountPagoConfiadoApi.js

@@ -33,6 +33,10 @@ let AccountPagoConfiadoApi = class AccountPagoConfiadoApi {
         const url = `${this.baseUrl}${accountId}/balance`;
         return await this.httpRequest.put(url, params);
     }
+    async collectDebit(accountId, request) {
+        const url = `${this.baseUrl}accounts/${accountId}/collect-debit`;
+        return await this.httpRequest.post(url, request);
+    }
     async update(directoryId, data) {
         const url = `${this.baseUrl}users/${directoryId}`;
         return await this.httpRequest.put(url, data);

package/bin/account-pagoconfiado/interfaces/IAccountPagoConfiadoApi.d.ts

@@ -1,10 +1,22 @@
-import { AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, GetAccountResponse, GetAccountResponseList } from "@fiado/type-kit/bin/account/index.js";
+import { AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, CollectDebitRequest, CollectDebitResponse, GetAccountResponse, GetAccountResponseList } from "@fiado/type-kit/bin/account/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 export interface IAccountPagoConfiadoApi {
     createAccount(provider: Provider, data: AccountCreateRequest): Promise<ApiGatewayResponse<AccountCreateResponse>>;
     getAccountByDirectoryId(directoryId: string, provider: string): Promise<ApiGatewayResponse<GetAccountResponse[]>>;
     updateAccountBalance(accountId: string, params: AccountUpdateBalanceRequest): Promise<ApiGatewayResponse<Boolean>>;
+    /**
+     * Debita el saldo disponible de la cuenta para cobrar una deuda, en una sola operación que lleva
+     * la condición de fondos consigo: entre comprobar el saldo y descontarlo no cabe otra escritura,
+     * de modo que dos cobros simultáneos no pueden sobregirar la cuenta.
+     *
+     * Idempotente por `executionId`: reintentar el mismo intento de cobro devuelve el resultado del
+     * primero en vez de volver a debitar. Saldo insuficiente NO es un error — responde 200 con
+     * `result: NONE`, y quien cobra decide si buscar el dinero en otra fuente.
+     *
+     * Backend: POST /accounts/{accountId}/collect-debit (privado VPC).
+     */
+    collectDebit(accountId: string, request: CollectDebitRequest): Promise<ApiGatewayResponse<CollectDebitResponse>>;
     update(directoryId: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;
     updateByAccountNumber(accountNumber: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;
     getAccountByAccountNumber(accountNumber: string): Promise<ApiGatewayResponse<void>>;

package/bin/collection-engine/api/CollectionEngineApi.d.ts

@@ -1,5 +1,5 @@
 import type { IHttpRequest } from "@fiado/http-client";
-import { CollectRequest, CollectResponse, RegisterCollectibleRequest } from "@fiado/type-kit/bin/collection/index.js";
+import { CollectRequest, CollectResponse, DeregisterChargeResponse } from "@fiado/type-kit/bin/collection/index.js";
 import { ICollectionEngineApi } from "./interfaces/ICollectionEngineApi.js";
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 /**
@@ -11,7 +11,6 @@ export default class CollectionEngineApi implements ICollectionEngineApi {
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
     collect(request: CollectRequest): Promise<FiadoApiResponse<CollectResponse>>;
-    registerCollectible(request: RegisterCollectibleRequest): Promise<FiadoApiResponse<boolean>>;
-    deregister(ownerRef: string, productId: string, chargeId: string): Promise<FiadoApiResponse<boolean>>;
+    deregister(domain: string, chargeId: string): Promise<FiadoApiResponse<DeregisterChargeResponse>>;
 }
 export {};

package/bin/collection-engine/api/CollectionEngineApi.js

@@ -25,13 +25,13 @@ let CollectionEngineApi = class CollectionEngineApi {
         const url = `${this.baseUrl}collection/collect`;
         return await this.httpRequest.post(url, request);
     }
-    async registerCollectible(request) {
-        const url = `${this.baseUrl}collection/register`;
-        return await this.httpRequest.post(url, request);
-    }
-    async deregister(ownerRef, productId, chargeId) {
-        const url = `${this.baseUrl}collection/deregister`;
-        return await this.httpRequest.post(url, { ownerRef, productId, chargeId });
+    async deregister(domain, chargeId) {
+        // `chargeId` lleva separadores `#` en todos los dominios (`SALE#42#INSTALLMENT#3`): sin
+        // escapar, el navegador o el cliente HTTP lo tratan como fragmento y el motor recibe la
+        // parte anterior al primer `#`, o sea otro cargo.
+        const url = `${this.baseUrl}collection/domains/${encodeURIComponent(domain)}`
+            + `/charges/${encodeURIComponent(chargeId)}/deregister`;
+        return await this.httpRequest.post(url, {});
     }
 };
 CollectionEngineApi = __decorate([

package/bin/collection-engine/api/interfaces/ICollectionEngineApi.d.ts

@@ -1,30 +1,40 @@
-import { CollectRequest, CollectResponse, RegisterCollectibleRequest } from "@fiado/type-kit/bin/collection/index.js";
+import { CollectRequest, CollectResponse, DeregisterChargeResponse } from "@fiado/type-kit/bin/collection/index.js";
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 /**
  * Cliente para invocar los endpoints privados del lambda `collection-engine-business`.
  *
  * Los endpoints viven bajo `COLLECTION_ENGINE_LAMBDA_URL` (API Gateway privado / VPC).
- * El motor es agnóstico de proveedores/cuentas — los dominios (une-credit,
- * surekeep-retail, etc.) sólo hablan el contrato genérico de `PendingCharge`.
+ * El motor es agnóstico de proveedores y cuentas: el dominio dice QUÉ se debe y el motor
+ * decide de dónde cobrarlo según la config del producto.
+ *
+ * El alta explícita de un cargo cobrable (`registerCollectible`) todavía no existe en el
+ * motor: hoy `collect` crea el intent si no lo había, derivando su identidad de
+ * `domain#chargeId`. El método se reincorporará cuando el motor exponga la ruta.
  */
 export interface ICollectionEngineApi {
     /**
-     * Cobro on-demand síncrono. El dominio pide al motor que intente cobrar
-     * un cargo puntual (fuera del barrido normal de la cascada).
+     * Cobro on-demand síncrono. El dominio manda el cargo ya resuelto y el motor recorre la
+     * cascada de fuentes configurada para el producto. Idempotente por `domain#chargeId`:
+     * repetir la llamada sobre un cargo ya cobrado devuelve el resultado anterior sin volver
+     * a mover dinero.
+     *
      * Backend: POST /collection/collect (privado VPC).
      */
     collect(request: CollectRequest): Promise<FiadoApiResponse<CollectResponse>>;
     /**
-     * Alta de un cargo cobrable en el índice del motor. Lo invoca el dominio
-     * dueño cuando nace una deuda cobrable (installment, cuota, etc.).
-     * Backend: POST /collection/register (privado VPC).
-     */
-    registerCollectible(request: RegisterCollectibleRequest): Promise<FiadoApiResponse<boolean>>;
-    /**
-     * Baja de un cargo del índice del motor (equivalente a cancelar el intent
-     * en curso). Lo invoca el dominio dueño cuando el cargo deja de ser cobrable.
-     * Backend: POST /collection/deregister (privado VPC).
+     * Baja de un cargo: detiene los reintentos de un cobro que el dominio castigó, condonó o
+     * reestructuró. Sin esto, un cargo sin fondos se reintenta indefinidamente.
+     *
+     * Identifica el cobro por `domain` y `chargeId`, que es la llave con la que el motor lo
+     * registró. Es idempotente: dar de baja un cargo ya terminal devuelve `ALREADY_TERMINAL`
+     * sin alterarlo.
+     *
+     * Un cargo desconocido responde 404, y el cliente HTTP lo propaga como excepción — no llega
+     * como envelope con `code`. El dominio debe atraparlo si un cargo ya inexistente es un caso
+     * esperado de su flujo.
+     *
+     * Backend: POST /collection/domains/{domain}/charges/{chargeId}/deregister (privado VPC).
      */
-    deregister(ownerRef: string, productId: string, chargeId: string): Promise<FiadoApiResponse<boolean>>;
+    deregister(domain: string, chargeId: string): Promise<FiadoApiResponse<DeregisterChargeResponse>>;
 }
 export {};

package/bin/container.config.js

@@ -280,7 +280,7 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     // 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)
+    // Collection engine — motor de cobro central multitenant (collect/deregister)
     bind("ICollectionEngineApi").to(CollectionEngineApi);
     // Domain callback — el motor notifica al dominio dueño del cargo (applyCollectionResult)
     bind("IDomainCallbackApi").to(DomainCallbackApi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.44.0",
+  "version": "5.46.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.360.0",
+    "@fiado/type-kit": "^3.368.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/account-pagoconfiado/AccountPagoConfiadoApi.ts

@@ -1,8 +1,8 @@
 import {IAccountPagoConfiadoApi} from "./interfaces/IAccountPagoConfiadoApi.js";
-import {AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, GetAccountResponse, GetAccountResponseList} from "@fiado/type-kit/bin/account/index.js";
+import {AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, CollectDebitRequest, CollectDebitResponse, GetAccountResponse, GetAccountResponseList} from "@fiado/type-kit/bin/account/index.js";
 import {ApiGatewayResponse} from "@fiado/gateway-adapter";
 import {inject, injectable} from "inversify";
-import {IHttpRequest} from "@fiado/http-client";
+import type {IHttpRequest} from "@fiado/http-client";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 
 @injectable()
@@ -31,6 +31,11 @@ export default class AccountPagoConfiadoApi implements IAccountPagoConfiadoApi {
         return await this.httpRequest.put(url,params);
     }
 
+    async collectDebit(accountId: string, request: CollectDebitRequest): Promise<ApiGatewayResponse<CollectDebitResponse>> {
+        const url = `${this.baseUrl}accounts/${accountId}/collect-debit`;
+        return await this.httpRequest.post(url, request);
+    }
+
     async update(directoryId: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>> {
         const url = `${this.baseUrl}users/${directoryId}`;
         return await this.httpRequest.put(url, data);

package/src/account-pagoconfiado/interfaces/IAccountPagoConfiadoApi.ts

@@ -1,11 +1,4 @@
-import {
-    AccountCreateRequest,
-    AccountCreateResponse,
-    AccountUpdateBalanceRequest,
-    AccountUpdateRequest,
-    GetAccountResponse,
-    GetAccountResponseList
-} from "@fiado/type-kit/bin/account/index.js";
+import {AccountCreateRequest, AccountCreateResponse, AccountUpdateBalanceRequest, AccountUpdateRequest, CollectDebitRequest, CollectDebitResponse, GetAccountResponse, GetAccountResponseList} from "@fiado/type-kit/bin/account/index.js";
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 
@@ -17,6 +10,19 @@ export interface IAccountPagoConfiadoApi {
 
     updateAccountBalance(accountId: string, params: AccountUpdateBalanceRequest): Promise<ApiGatewayResponse<Boolean>>;
 
+    /**
+     * Debita el saldo disponible de la cuenta para cobrar una deuda, en una sola operación que lleva
+     * la condición de fondos consigo: entre comprobar el saldo y descontarlo no cabe otra escritura,
+     * de modo que dos cobros simultáneos no pueden sobregirar la cuenta.
+     *
+     * Idempotente por `executionId`: reintentar el mismo intento de cobro devuelve el resultado del
+     * primero en vez de volver a debitar. Saldo insuficiente NO es un error — responde 200 con
+     * `result: NONE`, y quien cobra decide si buscar el dinero en otra fuente.
+     *
+     * Backend: POST /accounts/{accountId}/collect-debit (privado VPC).
+     */
+    collectDebit(accountId: string, request: CollectDebitRequest): Promise<ApiGatewayResponse<CollectDebitResponse>>;
+
     update(directoryId: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;
 
     updateByAccountNumber(accountNumber: string, data: AccountUpdateRequest): Promise<ApiGatewayResponse<void>>;

package/src/collection-engine/api/CollectionEngineApi.ts

@@ -3,7 +3,7 @@ import type { IHttpRequest } from "@fiado/http-client";
 import {
     CollectRequest,
     CollectResponse,
-    RegisterCollectibleRequest,
+    DeregisterChargeResponse,
 } from "@fiado/type-kit/bin/collection/index.js";
 import { ICollectionEngineApi } from "./interfaces/ICollectionEngineApi.js";
 
@@ -26,13 +26,12 @@ export default class CollectionEngineApi implements ICollectionEngineApi {
         return await this.httpRequest.post(url, request);
     }
 
-    async registerCollectible(request: RegisterCollectibleRequest): Promise<FiadoApiResponse<boolean>> {
-        const url = `${this.baseUrl}collection/register`;
-        return await this.httpRequest.post(url, request);
-    }
-
-    async deregister(ownerRef: string, productId: string, chargeId: string): Promise<FiadoApiResponse<boolean>> {
-        const url = `${this.baseUrl}collection/deregister`;
-        return await this.httpRequest.post(url, { ownerRef, productId, chargeId });
+    async deregister(domain: string, chargeId: string): Promise<FiadoApiResponse<DeregisterChargeResponse>> {
+        // `chargeId` lleva separadores `#` en todos los dominios (`SALE#42#INSTALLMENT#3`): sin
+        // escapar, el navegador o el cliente HTTP lo tratan como fragmento y el motor recibe la
+        // parte anterior al primer `#`, o sea otro cargo.
+        const url = `${this.baseUrl}collection/domains/${encodeURIComponent(domain)}`
+            + `/charges/${encodeURIComponent(chargeId)}/deregister`;
+        return await this.httpRequest.post(url, {});
     }
 }

package/src/collection-engine/api/interfaces/ICollectionEngineApi.ts

@@ -1,7 +1,7 @@
 import {
     CollectRequest,
     CollectResponse,
-    RegisterCollectibleRequest,
+    DeregisterChargeResponse,
 } from "@fiado/type-kit/bin/collection/index.js";
 
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
@@ -10,29 +10,38 @@ type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApi
  * Cliente para invocar los endpoints privados del lambda `collection-engine-business`.
  *
  * Los endpoints viven bajo `COLLECTION_ENGINE_LAMBDA_URL` (API Gateway privado / VPC).
- * El motor es agnóstico de proveedores/cuentas — los dominios (une-credit,
- * surekeep-retail, etc.) sólo hablan el contrato genérico de `PendingCharge`.
+ * El motor es agnóstico de proveedores y cuentas: el dominio dice QUÉ se debe y el motor
+ * decide de dónde cobrarlo según la config del producto.
+ *
+ * El alta explícita de un cargo cobrable (`registerCollectible`) todavía no existe en el
+ * motor: hoy `collect` crea el intent si no lo había, derivando su identidad de
+ * `domain#chargeId`. El método se reincorporará cuando el motor exponga la ruta.
  */
 export interface ICollectionEngineApi {
 
     /**
-     * Cobro on-demand síncrono. El dominio pide al motor que intente cobrar
-     * un cargo puntual (fuera del barrido normal de la cascada).
+     * Cobro on-demand síncrono. El dominio manda el cargo ya resuelto y el motor recorre la
+     * cascada de fuentes configurada para el producto. Idempotente por `domain#chargeId`:
+     * repetir la llamada sobre un cargo ya cobrado devuelve el resultado anterior sin volver
+     * a mover dinero.
+     *
      * Backend: POST /collection/collect (privado VPC).
      */
     collect(request: CollectRequest): Promise<FiadoApiResponse<CollectResponse>>;
 
     /**
-     * Alta de un cargo cobrable en el índice del motor. Lo invoca el dominio
-     * dueño cuando nace una deuda cobrable (installment, cuota, etc.).
-     * Backend: POST /collection/register (privado VPC).
-     */
-    registerCollectible(request: RegisterCollectibleRequest): Promise<FiadoApiResponse<boolean>>;
-
-    /**
-     * Baja de un cargo del índice del motor (equivalente a cancelar el intent
-     * en curso). Lo invoca el dominio dueño cuando el cargo deja de ser cobrable.
-     * Backend: POST /collection/deregister (privado VPC).
+     * Baja de un cargo: detiene los reintentos de un cobro que el dominio castigó, condonó o
+     * reestructuró. Sin esto, un cargo sin fondos se reintenta indefinidamente.
+     *
+     * Identifica el cobro por `domain` y `chargeId`, que es la llave con la que el motor lo
+     * registró. Es idempotente: dar de baja un cargo ya terminal devuelve `ALREADY_TERMINAL`
+     * sin alterarlo.
+     *
+     * Un cargo desconocido responde 404, y el cliente HTTP lo propaga como excepción — no llega
+     * como envelope con `code`. El dominio debe atraparlo si un cargo ya inexistente es un caso
+     * esperado de su flujo.
+     *
+     * Backend: POST /collection/domains/{domain}/charges/{chargeId}/deregister (privado VPC).
      */
-    deregister(ownerRef: string, productId: string, chargeId: string): Promise<FiadoApiResponse<boolean>>;
+    deregister(domain: string, chargeId: string): Promise<FiadoApiResponse<DeregisterChargeResponse>>;
 }

package/src/container.config.ts

@@ -195,7 +195,7 @@ import { IKycVerificationsBusinessApi, KycVerificationsBusinessApi } from "./kyc
 // 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)
+// Collection engine — cliente del motor de cobro central (collect/deregister)
 import { ICollectionEngineApi } from "./collection-engine/index.js";
 import CollectionEngineApi from "./collection-engine/api/CollectionEngineApi.js";
 // Domain callback — cliente genérico que usa el motor para notificar a cualquier dominio
@@ -374,7 +374,7 @@ export const apiInvokerBindings = new ContainerModule(({ bind }) => {
     bind<IWebhookBusinessPublisher>("IWebhookBusinessPublisher").to(WebhookBusinessPublisher);
     bind<ICentralPaymentsWebhookApi>("ICentralPaymentsWebhookApi").to(CentralPaymentsWebhookApi);
 
-    // Collection engine — motor de cobro central multitenant (collect/registerCollectible/deregister)
+    // Collection engine — motor de cobro central multitenant (collect/deregister)
     bind<ICollectionEngineApi>("ICollectionEngineApi").to(CollectionEngineApi);
 
     // Domain callback — el motor notifica al dominio dueño del cargo (applyCollectionResult)