@fiado/api-invoker 5.61.0 → 5.63.0

package/bin/loanOfferings/api/LoanOfferingsBusinessApi.d.ts

@@ -1,6 +1,7 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { ConsumePromotionRequest, PromotedSkusResponse, ConsumePromotionResponse, CreditPlanLevelEnum, CreditPlanResponse, FinancierResponse, ReservePromotionBonusRequest, ReservePromotionBonusResponse, ResolveCustomerSegmentsRequest, ResolveCustomerSegmentsResponse, ScopeWidePromotionsResponse, SkuPromotionsResponse, SettlePromotionBonusRequest, PromotionBonusResponse, SimulateCreditPlanRequest, SimulationResultResponse } from "@fiado/type-kit/bin/loanOfferings/index.js";
+import { SegmentMembersResponse } from "./dtos/SegmentMembers.js";
 import { ILoanOfferingsBusinessApi } from "./interfaces/ILoanOfferingsBusinessApi.js";
 /**
  * Publisher HTTP del lambda `loan-offerings-business` (componente 07 SureKeep Fase 1) para sus
@@ -29,4 +30,5 @@ export default class LoanOfferingsBusinessApi implements ILoanOfferingsBusinessA
     settlePromotionBonus(promotionId: string, input: SettlePromotionBonusRequest, tenantId: string): Promise<StandardResponse<PromotionBonusResponse>>;
     listSkuPromotions(storeId: string, tenantId: string, level?: CreditPlanLevelEnum, segmentId?: string): Promise<StandardResponse<SkuPromotionsResponse>>;
     listScopeWidePromotions(storeId: string, tenantId: string, level?: CreditPlanLevelEnum, segmentId?: string): Promise<StandardResponse<ScopeWidePromotionsResponse>>;
+    getSegmentMembers(retailCustomerIds: string[], tenantId: string): Promise<StandardResponse<SegmentMembersResponse>>;
 }

package/bin/loanOfferings/api/LoanOfferingsBusinessApi.js

@@ -86,6 +86,14 @@ let LoanOfferingsBusinessApi = class LoanOfferingsBusinessApi {
             url += `&segmentId=${encodeURIComponent(segmentId)}`;
         return await this.httpRequest.get(url);
     }
+    async getSegmentMembers(retailCustomerIds, tenantId) {
+        const params = new URLSearchParams({
+            retailCustomerIds: retailCustomerIds.join(","),
+            tenantId,
+        });
+        const url = `${this.baseUrl}/private/segments/members?${params.toString()}`;
+        return await this.httpRequest.get(url);
+    }
 };
 LoanOfferingsBusinessApi = __decorate([
     injectable(),

package/bin/loanOfferings/api/dtos/SegmentMembers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tipos de la pertenencia a segmentos EN LOTE. Viven en esta lib (y no en `@fiado/type-kit`) porque
+ * el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local.
+ */
+/** Un segmento al que pertenece el cliente, con lo mínimo para pintarlo. */
+export interface CustomerSegmentMembership {
+    segmentId: string;
+    name: string;
+    /**
+     * Segmento por omisión del catálogo. Su semántica cambia por motor (alcanza a todos en
+     * promociones y a nadie en políticas), así que el consumidor decide si lo pinta.
+     */
+    isDefault: boolean;
+}
+/** Un cliente y los segmentos que le tocan. `segments: []` afirma que no está en ninguno. */
+export interface SegmentMembersItem {
+    retailCustomerId: string;
+    segments: CustomerSegmentMembership[];
+}
+/** Una fila por cada id PEDIDO, no por cada id con segmentos. */
+export interface SegmentMembersResponse {
+    items: SegmentMembersItem[];
+}

package/bin/loanOfferings/api/dtos/SegmentMembers.js

@@ -0,0 +1,5 @@
+/**
+ * Tipos de la pertenencia a segmentos EN LOTE. Viven en esta lib (y no en `@fiado/type-kit`) porque
+ * el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local.
+ */
+export {};

package/bin/loanOfferings/api/interfaces/ILoanOfferingsBusinessApi.d.ts

@@ -1,4 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
+import { SegmentMembersResponse } from "../dtos/SegmentMembers.js";
 import { ConsumePromotionRequest, PromotedSkusResponse, ConsumePromotionResponse, CreditPlanLevelEnum, CreditPlanResponse, FinancierResponse, ReservePromotionBonusRequest, ReservePromotionBonusResponse, ResolveCustomerSegmentsRequest, ResolveCustomerSegmentsResponse, ScopeWidePromotionsResponse, SkuPromotionsResponse, SettlePromotionBonusRequest, PromotionBonusResponse, SimulateCreditPlanRequest, SimulationResultResponse } from "@fiado/type-kit/bin/loanOfferings/index.js";
 /**
  * Contrato del publisher HTTP del lambda `loan-offerings-business` (componente 07 SureKeep Fase 1)
@@ -133,4 +134,17 @@ export interface ILoanOfferingsBusinessApi {
      * hay ninguna vigente; nunca 404.
      */
     listScopeWidePromotions(storeId: string, tenantId: string, level?: CreditPlanLevelEnum, segmentId?: string): Promise<StandardResponse<ScopeWidePromotionsResponse>>;
+    /**
+     * `GET /private/segments/members?retailCustomerIds=<csv>` — pertenencia a segmentos EN LOTE.
+     * Es la alternativa a resolver segmento por cliente: una llamada por página de tabla.
+     *
+     * Devuelve una fila por cada id PEDIDO: los que no están en ningún segmento vuelven con
+     * `segments: []`, no se omiten. Aun así, indexa por `retailCustomerId` — nunca por posición.
+     *
+     * Tope de 100 ids por request, medido sobre lo que manda el caller.
+     *
+     * @throws `400 SEGMENT_MEMBERS_BATCH_TOO_LARGE` si el lote pasa de 100 ids.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    getSegmentMembers(retailCustomerIds: string[], tenantId: string): Promise<StandardResponse<SegmentMembersResponse>>;
 }

package/bin/loanOfferings/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./api/dtos/SegmentMembers.js";
 export * from "./api/interfaces/ILoanOfferingsBusinessApi.js";
 export { default as LoanOfferingsBusinessApi } from "./api/LoanOfferingsBusinessApi.js";

package/bin/loanOfferings/index.js

@@ -1,2 +1,3 @@
+export * from "./api/dtos/SegmentMembers.js";
 export * from "./api/interfaces/ILoanOfferingsBusinessApi.js";
 export { default as LoanOfferingsBusinessApi } from "./api/LoanOfferingsBusinessApi.js";

package/bin/retailCatalog/api/RetailCatalogBusinessApi.d.ts

@@ -1,6 +1,6 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { ImeiProductLookupResponse, IRetailCatalogBusinessApi, ReleaseReservationBody, ReserveInventoryBody, ReserveInventoryResult, SellInventoryBody, StoreCatalogItem } from "./interfaces/IRetailCatalogBusinessApi.js";
+import { ImeiProductLookupResponse, IRetailCatalogBusinessApi, ProductsByRetailersResponse, ReleaseReservationBody, ReserveInventoryBody, ReserveInventoryResult, SellInventoryBody, StoreCatalogItem } from "./interfaces/IRetailCatalogBusinessApi.js";
 /**
  * Publisher HTTP del lambda `retail-catalog-business` (SureKeep Fase 1, pista Retail) para sus
  * endpoints privados del ciclo de venta del IMEI. Contrato y semántica completos →
@@ -21,6 +21,7 @@ export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessA
     private tenantHeader;
     getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>>;
     getProductsByImei(imeis: string[], tenantId: string): Promise<StandardResponse<ImeiProductLookupResponse>>;
+    getProductsByRetailers(retailerIds: string[], tenantId: string): Promise<StandardResponse<ProductsByRetailersResponse>>;
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
     sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
     releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;

package/bin/retailCatalog/api/RetailCatalogBusinessApi.js

@@ -11,7 +11,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject, injectable } from "inversify";
-import { IMEI_PRODUCT_BATCH_MAX, } from "./interfaces/IRetailCatalogBusinessApi.js";
+import { IMEI_PRODUCT_BATCH_MAX, RETAILER_PRODUCTS_BATCH_MAX, } from "./interfaces/IRetailCatalogBusinessApi.js";
 /** Header por el que el destino resuelve el silo (issuer Cognito forwardeado por el caller). */
 const TENANT_ISSUER_HEADER = "x-tenant-issuer";
 /**
@@ -51,6 +51,15 @@ let RetailCatalogBusinessApi = class RetailCatalogBusinessApi {
         const query = new URLSearchParams({ imeis: imeis.join(","), tenantId });
         return await this.httpRequest.get(`${this.baseUrl}/private/products/by-imei?${query.toString()}`);
     }
+    async getProductsByRetailers(retailerIds, tenantId) {
+        // Se corta aquí: mandar un lote que el destino va a rechazar solo gasta un round-trip.
+        if (retailerIds.length > RETAILER_PRODUCTS_BATCH_MAX) {
+            throw new Error(`El lote admite hasta ${RETAILER_PRODUCTS_BATCH_MAX} cadenas y llegaron ${retailerIds.length}`);
+        }
+        const query = new URLSearchParams({ tenantId });
+        const body = { retailerIds };
+        return await this.httpRequest.post(`${this.baseUrl}/private/products/by-retailers?${query.toString()}`, body);
+    }
     async reserveInventory(imei, body, issuer) {
         const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/reserve`;
         return await this.httpRequest.put(url, body, this.tenantHeader(issuer));

package/bin/retailCatalog/api/interfaces/IRetailCatalogBusinessApi.d.ts

@@ -80,6 +80,30 @@ export interface ImeiProductLookupEntry {
 export interface ImeiProductLookupResponse {
     items: ImeiProductLookupEntry[];
 }
+/** Techo de cadenas por request del lote cadena->catálogo. Lo declara y lo honra el destino. */
+export declare const RETAILER_PRODUCTS_BATCH_MAX = 100;
+/** Body de POST `/private/products/by-retailers`. */
+export interface ProductsByRetailersBody {
+    retailerIds: string[];
+}
+/** Un producto vendible de una cadena (espeja `RetailerProductItem` del destino). */
+export interface RetailerProductItem {
+    /** Cadena a la que pertenece el producto; es la llave con la que el caller agrupa. */
+    retailerId: string;
+    sku: string;
+    /** Marca comercial (p. ej. "Samsung"). */
+    brand: string;
+    /** Modelo (p. ej. "A54"). */
+    model: string;
+}
+/** Respuesta del lote cadena->catálogo: los productos de TODAS las cadenas pedidas, en una lista plana. */
+export interface ProductsByRetailersResponse {
+    items: RetailerProductItem[];
+    /** Cuántos productos trae `items`. */
+    count: number;
+    /** `true` si el destino recortó el resultado; pide las cadenas en lotes más chicos. */
+    truncated: boolean;
+}
 /** Resultado de la reserva (espeja `ReserveInventoryResponse` del destino). */
 export interface ReserveInventoryResult {
     reservationExpiresAt: string;
@@ -125,6 +149,32 @@ export interface IRetailCatalogBusinessApi {
      *   `400 IMEI_BATCH_REQUIRED` si `imeis` viene vacío · `400 UNKNOWN_TENANT` sin `tenantId`.
      */
     getProductsByImei(imeis: string[], tenantId: string): Promise<StandardResponse<ImeiProductLookupResponse>>;
+    /**
+     * POST `/private/products/by-retailers?tenantId=` — catálogo de productos de VARIAS cadenas en
+     * una sola llamada, para el consumidor que arma su vista con N cadenas y no quiere N requests.
+     *
+     * ─────────────────────────────────────────────────────────────────────────────
+     * ⚠️ El tenant va por `?tenantId=`, NO por el header `x-tenant-issuer` del resto de este publisher.
+     * ─────────────────────────────────────────────────────────────────────────────
+     * Es obligatorio. El destino entra por `TenantContextService.withContextByTenantId`, igual que
+     * `getProductsByImei`.
+     *
+     * ── El contrato del lote ────────────────────────────────────────────────────────────────────
+     * `retailerIds` no puede venir vacío, sin repetidos y con un techo de
+     * `RETAILER_PRODUCTS_BATCH_MAX` cadenas; el caller parte los lotes mayores. La respuesta es una
+     * lista PLANA de productos con su `retailerId` — el caller agrupa. Una cadena sin catálogo
+     * simplemente no aporta ítems.
+     *
+     * O el lote sale completo o no sale: si falla la lectura de al menos una cadena el destino
+     * responde `INTERNAL_ERROR`. Nunca recibes una lista parcial.
+     *
+     * @throws Error si el lote supera el techo (se corta aquí, sin salir a la red) ·
+     *   `400 VALIDATION_ERROR` body vacío, con repetidos, con no-strings o de más de 100 ids ·
+     *   `400 UNKNOWN_TENANT` falta o no se reconoce el `tenantId` ·
+     *   `500 TENANT_ASSUME_ROLE_FAILED` fallo de infra del silo ·
+     *   `500 INTERNAL_ERROR` no se pudo leer alguna cadena.
+     */
+    getProductsByRetailers(retailerIds: string[], tenantId: string): Promise<StandardResponse<ProductsByRetailersResponse>>;
     /** PUT `/private/inventory/{imei}/reserve` — reserva atómica del IMEI para una sesión (AVAILABLE → RESERVED). */
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
     /** PUT `/private/inventory/{imei}/sell` — vende el IMEI (RESERVED → SOLD). */

package/bin/retailCatalog/api/interfaces/IRetailCatalogBusinessApi.js

@@ -1,2 +1,4 @@
 /** Techo de IMEIs por request del lote IMEI->producto. Lo declara y lo honra el destino. */
 export const IMEI_PRODUCT_BATCH_MAX = 100;
+/** Techo de cadenas por request del lote cadena->catálogo. Lo declara y lo honra el destino. */
+export const RETAILER_PRODUCTS_BATCH_MAX = 100;

package/bin/retailCustomer/api/RetailCustomerBusinessApi.d.ts

@@ -2,6 +2,8 @@ import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
 import { CustomersBatchRequest, CustomersBatchResponse } from "./dtos/CustomersBatch.js";
+import { CustomersPageQuery, PrivateCustomerListItem } from "./dtos/CustomersPage.js";
+import { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 /**
  * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 7
@@ -28,4 +30,5 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
     markWelcomeAccredited(customerId: string, tenantId: string, payload?: WelcomeAccreditationRequest): Promise<StandardResponse<WelcomeAccreditationResponse>>;
     setWelcomeAccreditationResult(customerId: string, payload: WelcomeAccreditationResultRequest, tenantId: string): Promise<StandardResponse<WelcomeBonusResponse>>;
     getCustomersBatch(payload: CustomersBatchRequest, tenantId: string): Promise<StandardResponse<CustomersBatchResponse>>;
+    listCustomersPage(query: CustomersPageQuery, tenantId: string): Promise<StandardResponse<PaginatedResult<PrivateCustomerListItem>>>;
 }

package/bin/retailCustomer/api/RetailCustomerBusinessApi.js

@@ -60,6 +60,16 @@ let RetailCustomerBusinessApi = class RetailCustomerBusinessApi {
         const url = `${this.baseUrl}/private/customers/batch?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.post(url, payload);
     }
+    async listCustomersPage(query, tenantId) {
+        const params = new URLSearchParams({ tenantId });
+        if (query.limit !== undefined)
+            params.set("limit", String(query.limit));
+        // El cursor viaja tal cual lo entregó el destino: componerlo o re-codificarlo lo rompe.
+        if (query.nextToken)
+            params.set("nextToken", query.nextToken);
+        const url = `${this.baseUrl}/private/customers?${params.toString()}`;
+        return await this.httpRequest.get(url);
+    }
 };
 RetailCustomerBusinessApi = __decorate([
     injectable(),

package/bin/retailCustomer/api/dtos/CustomersPage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tipos del listado paginado de clientes del tenant. Viven en esta lib (y no en `@fiado/type-kit`)
+ * porque el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO
+ * local, mismo criterio que `CustomersBatch`.
+ */
+/** Query de `GET /private/customers`. `limit` default 25, máximo 100 del lado del destino. */
+export interface CustomersPageQuery {
+    limit?: number;
+    /** Cursor opaco de la página anterior. Ausente = primera página. */
+    nextToken?: string;
+}
+/**
+ * Lo mínimo para pintar el renglón de un cliente. `fullName: null` significa que el cliente existe
+ * y no tiene ninguna parte del nombre resuelta — es distinto de que el id no vuelva.
+ */
+export interface PrivateCustomerListItem {
+    retailCustomerId: string;
+    /** `names + paternalLastName + maternalLastName` ya compuesto por el destino. */
+    fullName: string | null;
+    phone: string | null;
+    /** Tienda donde se dio de alta. La ficha del backoffice la nombra y resuelve su KYC con ella. */
+    originStoreId: string | null;
+    /** Alta del cliente en ISO-8601 UTC. Es el orden del listado (descendente). */
+    createdAt: string;
+}

package/bin/retailCustomer/api/dtos/CustomersPage.js

@@ -0,0 +1,6 @@
+/**
+ * Tipos del listado paginado de clientes del tenant. Viven en esta lib (y no en `@fiado/type-kit`)
+ * porque el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO
+ * local, mismo criterio que `CustomersBatch`.
+ */
+export {};

package/bin/retailCustomer/api/interfaces/IRetailCustomerBusinessApi.d.ts

@@ -1,6 +1,8 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
 import { CustomersBatchRequest, CustomersBatchResponse } from "../dtos/CustomersBatch.js";
+import { CustomersPageQuery, PrivateCustomerListItem } from "../dtos/CustomersPage.js";
+import { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
  * para sus 7 endpoints privados de cliente (service-to-service, VPC-only).
@@ -134,4 +136,18 @@ export interface IRetailCustomerBusinessApi {
      * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
      */
     getCustomersBatch(payload: CustomersBatchRequest, tenantId: string): Promise<StandardResponse<CustomersBatchResponse>>;
+    /**
+     * GET /private/customers?limit&nextToken&tenantId= — UNA página del padrón de clientes del
+     * tenant, del alta más reciente a la más vieja. Es el listado que alimenta las tablas de
+     * backoffice: una sola Query sobre el GSI de listado, sin fan-out por negocio.
+     *
+     * `nextToken` es OPACO: se pasea tal cual, no se compone ni se re-codifica. Ausente en la
+     * respuesta = última página. `count` son las filas de ESA página, nunca el total del padrón.
+     *
+     * `limit` default 25, máximo 100.
+     *
+     * @throws `400 INVALID_QUERY_PARAM` si `limit` no parsea o se pasa del tope.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    listCustomersPage(query: CustomersPageQuery, tenantId: string): Promise<StandardResponse<PaginatedResult<PrivateCustomerListItem>>>;
 }

package/bin/retailCustomer/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./api/dtos/CustomersBatch.js";
+export * from "./api/dtos/CustomersPage.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";

package/bin/retailCustomer/index.js

@@ -1,3 +1,4 @@
 export * from "./api/dtos/CustomersBatch.js";
+export * from "./api/dtos/CustomersPage.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.61.0",
+  "version": "5.63.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",

package/src/loanOfferings/api/LoanOfferingsBusinessApi.ts

@@ -19,6 +19,7 @@ import {
     SimulateCreditPlanRequest,
     SimulationResultResponse,
 } from "@fiado/type-kit/bin/loanOfferings/index.js";
+import { SegmentMembersResponse } from "./dtos/SegmentMembers.js";
 import { ILoanOfferingsBusinessApi } from "./interfaces/ILoanOfferingsBusinessApi.js";
 
 /**
@@ -142,4 +143,16 @@ export default class LoanOfferingsBusinessApi implements ILoanOfferingsBusinessA
         if (segmentId) url += `&segmentId=${encodeURIComponent(segmentId)}`;
         return await this.httpRequest.get(url);
     }
+
+    async getSegmentMembers(
+        retailCustomerIds: string[],
+        tenantId: string,
+    ): Promise<StandardResponse<SegmentMembersResponse>> {
+        const params = new URLSearchParams({
+            retailCustomerIds: retailCustomerIds.join(","),
+            tenantId,
+        });
+        const url = `${this.baseUrl}/private/segments/members?${params.toString()}`;
+        return await this.httpRequest.get(url);
+    }
 }

package/src/loanOfferings/api/dtos/SegmentMembers.ts

@@ -0,0 +1,26 @@
+/**
+ * Tipos de la pertenencia a segmentos EN LOTE. Viven en esta lib (y no en `@fiado/type-kit`) porque
+ * el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local.
+ */
+
+/** Un segmento al que pertenece el cliente, con lo mínimo para pintarlo. */
+export interface CustomerSegmentMembership {
+    segmentId: string;
+    name: string;
+    /**
+     * Segmento por omisión del catálogo. Su semántica cambia por motor (alcanza a todos en
+     * promociones y a nadie en políticas), así que el consumidor decide si lo pinta.
+     */
+    isDefault: boolean;
+}
+
+/** Un cliente y los segmentos que le tocan. `segments: []` afirma que no está en ninguno. */
+export interface SegmentMembersItem {
+    retailCustomerId: string;
+    segments: CustomerSegmentMembership[];
+}
+
+/** Una fila por cada id PEDIDO, no por cada id con segmentos. */
+export interface SegmentMembersResponse {
+    items: SegmentMembersItem[];
+}

package/src/loanOfferings/api/interfaces/ILoanOfferingsBusinessApi.ts

@@ -1,4 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
+import { SegmentMembersResponse } from "../dtos/SegmentMembers.js";
 import {
     ConsumePromotionRequest,
     PromotedSkusResponse,
@@ -203,4 +204,21 @@ export interface ILoanOfferingsBusinessApi {
         level?: CreditPlanLevelEnum,
         segmentId?: string,
     ): Promise<StandardResponse<ScopeWidePromotionsResponse>>;
+
+    /**
+     * `GET /private/segments/members?retailCustomerIds=<csv>` — pertenencia a segmentos EN LOTE.
+     * Es la alternativa a resolver segmento por cliente: una llamada por página de tabla.
+     *
+     * Devuelve una fila por cada id PEDIDO: los que no están en ningún segmento vuelven con
+     * `segments: []`, no se omiten. Aun así, indexa por `retailCustomerId` — nunca por posición.
+     *
+     * Tope de 100 ids por request, medido sobre lo que manda el caller.
+     *
+     * @throws `400 SEGMENT_MEMBERS_BATCH_TOO_LARGE` si el lote pasa de 100 ids.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    getSegmentMembers(
+        retailCustomerIds: string[],
+        tenantId: string,
+    ): Promise<StandardResponse<SegmentMembersResponse>>;
 }

package/src/loanOfferings/index.ts

@@ -1,2 +1,3 @@
+export * from "./api/dtos/SegmentMembers.js";
 export * from "./api/interfaces/ILoanOfferingsBusinessApi.js";
 export { default as LoanOfferingsBusinessApi } from "./api/LoanOfferingsBusinessApi.js";

package/src/retailCatalog/api/RetailCatalogBusinessApi.ts

@@ -5,9 +5,12 @@ import {
     IMEI_PRODUCT_BATCH_MAX,
     ImeiProductLookupResponse,
     IRetailCatalogBusinessApi,
+    ProductsByRetailersBody,
+    ProductsByRetailersResponse,
     ReleaseReservationBody,
     ReserveInventoryBody,
     ReserveInventoryResult,
+    RETAILER_PRODUCTS_BATCH_MAX,
     SellInventoryBody,
     StoreCatalogItem,
 } from "./interfaces/IRetailCatalogBusinessApi.js";
@@ -58,6 +61,21 @@ export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessA
         return await this.httpRequest.get(`${this.baseUrl}/private/products/by-imei?${query.toString()}`);
     }
 
+    async getProductsByRetailers(
+        retailerIds: string[],
+        tenantId: string,
+    ): Promise<StandardResponse<ProductsByRetailersResponse>> {
+        // Se corta aquí: mandar un lote que el destino va a rechazar solo gasta un round-trip.
+        if (retailerIds.length > RETAILER_PRODUCTS_BATCH_MAX) {
+            throw new Error(
+                `El lote admite hasta ${RETAILER_PRODUCTS_BATCH_MAX} cadenas y llegaron ${retailerIds.length}`,
+            );
+        }
+        const query = new URLSearchParams({ tenantId });
+        const body: ProductsByRetailersBody = { retailerIds };
+        return await this.httpRequest.post(`${this.baseUrl}/private/products/by-retailers?${query.toString()}`, body);
+    }
+
     async reserveInventory(
         imei: string,
         body: ReserveInventoryBody,

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

@@ -93,6 +93,34 @@ export interface ImeiProductLookupResponse {
     items: ImeiProductLookupEntry[];
 }
 
+/** Techo de cadenas por request del lote cadena->catálogo. Lo declara y lo honra el destino. */
+export const RETAILER_PRODUCTS_BATCH_MAX = 100;
+
+/** Body de POST `/private/products/by-retailers`. */
+export interface ProductsByRetailersBody {
+    retailerIds: string[];
+}
+
+/** Un producto vendible de una cadena (espeja `RetailerProductItem` del destino). */
+export interface RetailerProductItem {
+    /** Cadena a la que pertenece el producto; es la llave con la que el caller agrupa. */
+    retailerId: string;
+    sku: string;
+    /** Marca comercial (p. ej. "Samsung"). */
+    brand: string;
+    /** Modelo (p. ej. "A54"). */
+    model: string;
+}
+
+/** Respuesta del lote cadena->catálogo: los productos de TODAS las cadenas pedidas, en una lista plana. */
+export interface ProductsByRetailersResponse {
+    items: RetailerProductItem[];
+    /** Cuántos productos trae `items`. */
+    count: number;
+    /** `true` si el destino recortó el resultado; pide las cadenas en lotes más chicos. */
+    truncated: boolean;
+}
+
 /** Resultado de la reserva (espeja `ReserveInventoryResponse` del destino). */
 export interface ReserveInventoryResult {
     reservationExpiresAt: string;
@@ -144,6 +172,36 @@ export interface IRetailCatalogBusinessApi {
      */
     getProductsByImei(imeis: string[], tenantId: string): Promise<StandardResponse<ImeiProductLookupResponse>>;
 
+    /**
+     * POST `/private/products/by-retailers?tenantId=` — catálogo de productos de VARIAS cadenas en
+     * una sola llamada, para el consumidor que arma su vista con N cadenas y no quiere N requests.
+     *
+     * ─────────────────────────────────────────────────────────────────────────────
+     * ⚠️ El tenant va por `?tenantId=`, NO por el header `x-tenant-issuer` del resto de este publisher.
+     * ─────────────────────────────────────────────────────────────────────────────
+     * Es obligatorio. El destino entra por `TenantContextService.withContextByTenantId`, igual que
+     * `getProductsByImei`.
+     *
+     * ── El contrato del lote ────────────────────────────────────────────────────────────────────
+     * `retailerIds` no puede venir vacío, sin repetidos y con un techo de
+     * `RETAILER_PRODUCTS_BATCH_MAX` cadenas; el caller parte los lotes mayores. La respuesta es una
+     * lista PLANA de productos con su `retailerId` — el caller agrupa. Una cadena sin catálogo
+     * simplemente no aporta ítems.
+     *
+     * O el lote sale completo o no sale: si falla la lectura de al menos una cadena el destino
+     * responde `INTERNAL_ERROR`. Nunca recibes una lista parcial.
+     *
+     * @throws Error si el lote supera el techo (se corta aquí, sin salir a la red) ·
+     *   `400 VALIDATION_ERROR` body vacío, con repetidos, con no-strings o de más de 100 ids ·
+     *   `400 UNKNOWN_TENANT` falta o no se reconoce el `tenantId` ·
+     *   `500 TENANT_ASSUME_ROLE_FAILED` fallo de infra del silo ·
+     *   `500 INTERNAL_ERROR` no se pudo leer alguna cadena.
+     */
+    getProductsByRetailers(
+        retailerIds: string[],
+        tenantId: string,
+    ): Promise<StandardResponse<ProductsByRetailersResponse>>;
+
     /** PUT `/private/inventory/{imei}/reserve` — reserva atómica del IMEI para una sesión (AVAILABLE → RESERVED). */
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
 

package/src/retailCustomer/api/RetailCustomerBusinessApi.ts

@@ -11,6 +11,8 @@ import {
     WelcomeBonusResponse,
 } from "@fiado/type-kit/bin/retailCustomer/index.js";
 import { CustomersBatchRequest, CustomersBatchResponse } from "./dtos/CustomersBatch.js";
+import { CustomersPageQuery, PrivateCustomerListItem } from "./dtos/CustomersPage.js";
+import { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 
 /**
@@ -92,4 +94,16 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
         const url = `${this.baseUrl}/private/customers/batch?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.post(url, payload);
     }
+
+    async listCustomersPage(
+        query: CustomersPageQuery,
+        tenantId: string,
+    ): Promise<StandardResponse<PaginatedResult<PrivateCustomerListItem>>> {
+        const params = new URLSearchParams({ tenantId });
+        if (query.limit !== undefined) params.set("limit", String(query.limit));
+        // El cursor viaja tal cual lo entregó el destino: componerlo o re-codificarlo lo rompe.
+        if (query.nextToken) params.set("nextToken", query.nextToken);
+        const url = `${this.baseUrl}/private/customers?${params.toString()}`;
+        return await this.httpRequest.get(url);
+    }
 }

package/src/retailCustomer/api/dtos/CustomersPage.ts

@@ -0,0 +1,27 @@
+/**
+ * Tipos del listado paginado de clientes del tenant. Viven en esta lib (y no en `@fiado/type-kit`)
+ * porque el type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO
+ * local, mismo criterio que `CustomersBatch`.
+ */
+
+/** Query de `GET /private/customers`. `limit` default 25, máximo 100 del lado del destino. */
+export interface CustomersPageQuery {
+    limit?: number;
+    /** Cursor opaco de la página anterior. Ausente = primera página. */
+    nextToken?: string;
+}
+
+/**
+ * Lo mínimo para pintar el renglón de un cliente. `fullName: null` significa que el cliente existe
+ * y no tiene ninguna parte del nombre resuelta — es distinto de que el id no vuelva.
+ */
+export interface PrivateCustomerListItem {
+    retailCustomerId: string;
+    /** `names + paternalLastName + maternalLastName` ya compuesto por el destino. */
+    fullName: string | null;
+    phone: string | null;
+    /** Tienda donde se dio de alta. La ficha del backoffice la nombra y resuelve su KYC con ella. */
+    originStoreId: string | null;
+    /** Alta del cliente en ISO-8601 UTC. Es el orden del listado (descendente). */
+    createdAt: string;
+}

package/src/retailCustomer/api/interfaces/IRetailCustomerBusinessApi.ts

@@ -9,6 +9,8 @@ import {
     WelcomeBonusResponse,
 } from "@fiado/type-kit/bin/retailCustomer/index.js";
 import { CustomersBatchRequest, CustomersBatchResponse } from "../dtos/CustomersBatch.js";
+import { CustomersPageQuery, PrivateCustomerListItem } from "../dtos/CustomersPage.js";
+import { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
@@ -173,4 +175,22 @@ export interface IRetailCustomerBusinessApi {
         payload: CustomersBatchRequest,
         tenantId: string,
     ): Promise<StandardResponse<CustomersBatchResponse>>;
+
+    /**
+     * GET /private/customers?limit&nextToken&tenantId= — UNA página del padrón de clientes del
+     * tenant, del alta más reciente a la más vieja. Es el listado que alimenta las tablas de
+     * backoffice: una sola Query sobre el GSI de listado, sin fan-out por negocio.
+     *
+     * `nextToken` es OPACO: se pasea tal cual, no se compone ni se re-codifica. Ausente en la
+     * respuesta = última página. `count` son las filas de ESA página, nunca el total del padrón.
+     *
+     * `limit` default 25, máximo 100.
+     *
+     * @throws `400 INVALID_QUERY_PARAM` si `limit` no parsea o se pasa del tope.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    listCustomersPage(
+        query: CustomersPageQuery,
+        tenantId: string,
+    ): Promise<StandardResponse<PaginatedResult<PrivateCustomerListItem>>>;
 }

package/src/retailCustomer/index.ts

@@ -1,3 +1,4 @@
 export * from "./api/dtos/CustomersBatch.js";
+export * from "./api/dtos/CustomersPage.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";