@fiado/api-invoker 5.128.0 → 5.130.0

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

@@ -1,6 +1,6 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, PromotionBonusEntryResponse, UpsertPromotionBonusRequest, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { UpsertCustomerFromKycRequest, EnsureCustomerByPhoneRequest, EnsureCustomerByPhoneResponse, AccountResultRequest, CustomerResponse, PromotionBonusEntryResponse, UpsertPromotionBonusRequest, 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";
@@ -24,6 +24,7 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
     upsertCustomerFromKyc(payload: UpsertCustomerFromKycRequest, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
+    ensureCustomerByPhone(payload: EnsureCustomerByPhoneRequest, tenantId: string): Promise<StandardResponse<EnsureCustomerByPhoneResponse>>;
     setAccountResult(customerId: string, payload: AccountResultRequest, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
     getCustomerByPhone(phone: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
     getCustomer(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;

package/bin/retailCustomer/api/RetailCustomerBusinessApi.js

@@ -35,6 +35,10 @@ let RetailCustomerBusinessApi = class RetailCustomerBusinessApi {
         const url = `${this.baseUrl}/private/customers/upsert-from-kyc?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.post(url, payload);
     }
+    async ensureCustomerByPhone(payload, tenantId) {
+        const url = `${this.baseUrl}/private/customers/ensure-by-phone?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, payload);
+    }
     async setAccountResult(customerId, payload, tenantId) {
         const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}/account-result?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.put(url, payload);

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

@@ -1,18 +1,18 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, PromotionBonusEntryResponse, UpsertPromotionBonusRequest, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { UpsertCustomerFromKycRequest, EnsureCustomerByPhoneRequest, EnsureCustomerByPhoneResponse, AccountResultRequest, CustomerResponse, PromotionBonusEntryResponse, UpsertPromotionBonusRequest, 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).
+ * para sus endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 7 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en todos los métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC), así que
  * el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller declara el
@@ -54,6 +54,15 @@ export interface IRetailCustomerBusinessApi {
      * aditivo al type-kit (backlog) — no acá.
      */
     upsertCustomerFromKyc(payload: UpsertCustomerFromKycRequest, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
+    /**
+     * POST /private/customers/ensure-by-phone?tenantId= — devuelve el cliente de ese celular o lo da
+     * de alta solo con el celular (ya verificado por OTP). Idempotente: dos llamadas con el mismo
+     * número devuelven el mismo cliente. `created=true` solo cuando esta llamada lo dio de alta.
+     *
+     * @throws `422 CUSTOMER_INACTIVE` si el número es de un cliente dado de baja.
+     * @throws `400 VALIDATION_ERROR` si el celular no trae 10 dígitos o falta la tienda.
+     */
+    ensureCustomerByPhone(payload: EnsureCustomerByPhoneRequest, tenantId: string): Promise<StandardResponse<EnsureCustomerByPhoneResponse>>;
     /**
      * PUT /private/customers/{customerId}/account-result?tenantId= — aterriza el resultado terminal de
      * la apertura de cuenta async (D35). Solo acepta OPEN/FAILED (nunca el intermedio OPENING). OPEN

package/bin/rules-business/api/RulesApi.d.ts

@@ -1,6 +1,6 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
-import type { EvaluateRulesRequest, EvaluateRulesResponse, GenerateRulesRequest, GenerateRulesResponse, RulesCatalogResponse, ValidateRulesRequest, ValidateRulesResponse } from "@fiado/type-kit/bin/rules/index.js";
+import type { EvaluateRulesRequest, EvaluateRulesResponse, GenerateRulesRequest, GenerateRulesResponse, PopulationCompileRequest, PopulationCompileResponse, PopulationExecutionPageResponse, PopulationExecutionRequest, PopulationExecutionResponse, PopulationTestRequest, PopulationTestResponse, RulesCatalogResponse, SegmentSchemaResponse, SegmentTableSchemaResponse, ValidateRulesRequest, ValidateRulesResponse } from "@fiado/type-kit/bin/rules/index.js";
 import type { IRulesApi } from "./interfaces/IRulesApi.js";
 /**
  * Contrato y semántica completos → `IRulesApi` (`StandardResponse` → leer `result.data`).
@@ -14,4 +14,11 @@ export declare class RulesApi implements IRulesApi {
     validate(request: ValidateRulesRequest): Promise<StandardResponse<ValidateRulesResponse>>;
     generate(request: GenerateRulesRequest): Promise<StandardResponse<GenerateRulesResponse>>;
     evaluate(request: EvaluateRulesRequest): Promise<StandardResponse<EvaluateRulesResponse>>;
+    populationSchema(consumer?: string): Promise<StandardResponse<SegmentSchemaResponse>>;
+    populationTableSchema(table: string, consumer?: string): Promise<StandardResponse<SegmentTableSchemaResponse>>;
+    populationCompile(request: PopulationCompileRequest): Promise<StandardResponse<PopulationCompileResponse>>;
+    populationTestStart(request: PopulationTestRequest): Promise<StandardResponse<PopulationTestResponse>>;
+    populationTestGet(testId: string, consumer?: string): Promise<StandardResponse<PopulationTestResponse>>;
+    populationExecutionStart(request: PopulationExecutionRequest): Promise<StandardResponse<PopulationExecutionResponse>>;
+    populationExecutionPage(executionId: string, nextToken?: string, consumer?: string): Promise<StandardResponse<PopulationExecutionPageResponse>>;
 }

package/bin/rules-business/api/RulesApi.js

@@ -11,6 +11,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject, injectable } from "inversify";
+// P2: el gateway de rewards corta a 29 s; el central corta la prueba a 12 s. Solo dispara ante falla real.
+const POPULATION_TEST_CLIENT_TIMEOUT_MS = 20000;
+const consumerQuery = (consumer) => consumer === undefined ? "" : `consumer=${encodeURIComponent(consumer)}`;
+const withQuery = (url, ...parts) => {
+    const query = parts.filter((part) => part !== "").join("&");
+    return query === "" ? url : `${url}?${query}`;
+};
 /**
  * Contrato y semántica completos → `IRulesApi` (`StandardResponse` → leer `result.data`).
  * Env: `RULES_BUSINESS_LAMBDA_URL` (SSM `fiado-rulesbusiness-lambda`).
@@ -36,6 +43,32 @@ let RulesApi = class RulesApi {
     async evaluate(request) {
         return await this.httpRequest.post(`${this.baseUrl}/evaluate`, request);
     }
+    async populationSchema(consumer) {
+        const url = withQuery(`${this.baseUrl}/population/schema`, consumerQuery(consumer));
+        return await this.httpRequest.get(url);
+    }
+    async populationTableSchema(table, consumer) {
+        const url = withQuery(`${this.baseUrl}/population/schema/${encodeURIComponent(table)}`, consumerQuery(consumer));
+        return await this.httpRequest.get(url);
+    }
+    async populationCompile(request) {
+        return await this.httpRequest.post(`${this.baseUrl}/population/compile`, request);
+    }
+    async populationTestStart(request) {
+        return await this.httpRequest.post(`${this.baseUrl}/population/tests`, request, undefined, undefined, undefined, { timeout: POPULATION_TEST_CLIENT_TIMEOUT_MS });
+    }
+    async populationTestGet(testId, consumer) {
+        const url = withQuery(`${this.baseUrl}/population/tests/${encodeURIComponent(testId)}`, consumerQuery(consumer));
+        return await this.httpRequest.get(url);
+    }
+    async populationExecutionStart(request) {
+        return await this.httpRequest.post(`${this.baseUrl}/population/executions`, request);
+    }
+    async populationExecutionPage(executionId, nextToken, consumer) {
+        const tokenQuery = nextToken === undefined ? "" : `nextToken=${encodeURIComponent(nextToken)}`;
+        const url = withQuery(`${this.baseUrl}/population/executions/${encodeURIComponent(executionId)}`, tokenQuery, consumerQuery(consumer));
+        return await this.httpRequest.get(url);
+    }
 };
 RulesApi = __decorate([
     injectable(),

package/bin/rules-business/api/interfaces/IRulesApi.d.ts

@@ -1,5 +1,5 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
-import type { EvaluateRulesRequest, EvaluateRulesResponse, GenerateRulesRequest, GenerateRulesResponse, RulesCatalogResponse, ValidateRulesRequest, ValidateRulesResponse } from "@fiado/type-kit/bin/rules/index.js";
+import type { EvaluateRulesRequest, EvaluateRulesResponse, GenerateRulesRequest, GenerateRulesResponse, PopulationCompileRequest, PopulationCompileResponse, PopulationExecutionPageResponse, PopulationExecutionRequest, PopulationExecutionResponse, PopulationTestRequest, PopulationTestResponse, RulesCatalogResponse, SegmentSchemaResponse, SegmentTableSchemaResponse, ValidateRulesRequest, ValidateRulesResponse } from "@fiado/type-kit/bin/rules/index.js";
 /**
  * Cliente del lambda central `rules-business` (catálogo, validación, generación con IA y evaluación de reglas).
  *
@@ -15,4 +15,21 @@ export interface IRulesApi {
     generate(request: GenerateRulesRequest): Promise<StandardResponse<GenerateRulesResponse>>;
     /** POST /evaluate — evalúa reglas sobre hasta 100 sujetos por llamada (400 `TOO_MANY_SUBJECTS`). */
     evaluate(request: EvaluateRulesRequest): Promise<StandardResponse<EvaluateRulesResponse>>;
+    /** GET /population/schema — tablas del datalake disponibles para segmentar población. */
+    populationSchema(consumer?: string): Promise<StandardResponse<SegmentSchemaResponse>>;
+    /** GET /population/schema/{table} — columnas de una tabla del datalake. */
+    populationTableSchema(table: string, consumer?: string): Promise<StandardResponse<SegmentTableSchemaResponse>>;
+    /** POST /population/compile — compila una `definition` a SQL parametrizado (no ejecuta nada). */
+    populationCompile(request: PopulationCompileRequest): Promise<StandardResponse<PopulationCompileResponse>>;
+    /**
+     * POST /population/tests — prueba sin estado. El central corta a 12 s y responde RUNNING + `testId`;
+     * el cliente usa un timeout explícito de 20000 ms (solo dispara ante falla real → 503).
+     */
+    populationTestStart(request: PopulationTestRequest): Promise<StandardResponse<PopulationTestResponse>>;
+    /** GET /population/tests/{testId} — sondeo de una prueba iniciada. */
+    populationTestGet(testId: string, consumer?: string): Promise<StandardResponse<PopulationTestResponse>>;
+    /** POST /population/executions — inicia la ejecución de una población. */
+    populationExecutionStart(request: PopulationExecutionRequest): Promise<StandardResponse<PopulationExecutionResponse>>;
+    /** GET /population/executions/{id} — página (≤1000 ids) de una ejecución; `nextToken` para continuar. */
+    populationExecutionPage(executionId: string, nextToken?: string, consumer?: string): Promise<StandardResponse<PopulationExecutionPageResponse>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.128.0",
+  "version": "5.130.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.14.0",
     "@fiado/http-client": "^2.0.1",
     "@fiado/logger": "^1.1.3",
-    "@fiado/type-kit": "^3.539.0",
+    "@fiado/type-kit": "^3.541.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/retailCustomer/api/RetailCustomerBusinessApi.ts

@@ -3,6 +3,8 @@ import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import {
     UpsertCustomerFromKycRequest,
+    EnsureCustomerByPhoneRequest,
+    EnsureCustomerByPhoneResponse,
     AccountResultRequest,
     CustomerResponse,
     PromotionBonusEntryResponse,
@@ -45,6 +47,14 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
         return await this.httpRequest.post(url, payload);
     }
 
+    async ensureCustomerByPhone(
+        payload: EnsureCustomerByPhoneRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<EnsureCustomerByPhoneResponse>> {
+        const url = `${this.baseUrl}/private/customers/ensure-by-phone?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, payload);
+    }
+
     async setAccountResult(
         customerId: string,
         payload: AccountResultRequest,

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

@@ -1,6 +1,8 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import {
     UpsertCustomerFromKycRequest,
+    EnsureCustomerByPhoneRequest,
+    EnsureCustomerByPhoneResponse,
     AccountResultRequest,
     CustomerResponse,
     PromotionBonusEntryResponse,
@@ -16,14 +18,14 @@ 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).
+ * para sus endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 7 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en todos los métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC), así que
  * el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller declara el
@@ -69,6 +71,19 @@ export interface IRetailCustomerBusinessApi {
         tenantId: string,
     ): Promise<StandardResponse<CustomerResponse>>;
 
+    /**
+     * POST /private/customers/ensure-by-phone?tenantId= — devuelve el cliente de ese celular o lo da
+     * de alta solo con el celular (ya verificado por OTP). Idempotente: dos llamadas con el mismo
+     * número devuelven el mismo cliente. `created=true` solo cuando esta llamada lo dio de alta.
+     *
+     * @throws `422 CUSTOMER_INACTIVE` si el número es de un cliente dado de baja.
+     * @throws `400 VALIDATION_ERROR` si el celular no trae 10 dígitos o falta la tienda.
+     */
+    ensureCustomerByPhone(
+        payload: EnsureCustomerByPhoneRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<EnsureCustomerByPhoneResponse>>;
+
     /**
      * PUT /private/customers/{customerId}/account-result?tenantId= — aterriza el resultado terminal de
      * la apertura de cuenta async (D35). Solo acepta OPEN/FAILED (nunca el intermedio OPENING). OPEN

package/src/rules-business/api/RulesApi.ts

@@ -6,12 +6,32 @@ import type {
     EvaluateRulesResponse,
     GenerateRulesRequest,
     GenerateRulesResponse,
+    PopulationCompileRequest,
+    PopulationCompileResponse,
+    PopulationExecutionPageResponse,
+    PopulationExecutionRequest,
+    PopulationExecutionResponse,
+    PopulationTestRequest,
+    PopulationTestResponse,
     RulesCatalogResponse,
+    SegmentSchemaResponse,
+    SegmentTableSchemaResponse,
     ValidateRulesRequest,
     ValidateRulesResponse,
 } from "@fiado/type-kit/bin/rules/index.js";
 import type { IRulesApi } from "./interfaces/IRulesApi.js";
 
+// P2: el gateway de rewards corta a 29 s; el central corta la prueba a 12 s. Solo dispara ante falla real.
+const POPULATION_TEST_CLIENT_TIMEOUT_MS = 20000;
+
+const consumerQuery = (consumer?: string): string =>
+    consumer === undefined ? "" : `consumer=${encodeURIComponent(consumer)}`;
+
+const withQuery = (url: string, ...parts: string[]): string => {
+    const query = parts.filter((part) => part !== "").join("&");
+    return query === "" ? url : `${url}?${query}`;
+};
+
 /**
  * Contrato y semántica completos → `IRulesApi` (`StandardResponse` → leer `result.data`).
  * Env: `RULES_BUSINESS_LAMBDA_URL` (SSM `fiado-rulesbusiness-lambda`).
@@ -41,4 +61,44 @@ export class RulesApi implements IRulesApi {
     async evaluate(request: EvaluateRulesRequest): Promise<StandardResponse<EvaluateRulesResponse>> {
         return await this.httpRequest.post<StandardResponse<EvaluateRulesResponse>>(`${this.baseUrl}/evaluate`, request);
     }
+
+    async populationSchema(consumer?: string): Promise<StandardResponse<SegmentSchemaResponse>> {
+        const url = withQuery(`${this.baseUrl}/population/schema`, consumerQuery(consumer));
+        return await this.httpRequest.get<StandardResponse<SegmentSchemaResponse>>(url);
+    }
+
+    async populationTableSchema(table: string, consumer?: string): Promise<StandardResponse<SegmentTableSchemaResponse>> {
+        const url = withQuery(`${this.baseUrl}/population/schema/${encodeURIComponent(table)}`, consumerQuery(consumer));
+        return await this.httpRequest.get<StandardResponse<SegmentTableSchemaResponse>>(url);
+    }
+
+    async populationCompile(request: PopulationCompileRequest): Promise<StandardResponse<PopulationCompileResponse>> {
+        return await this.httpRequest.post<StandardResponse<PopulationCompileResponse>>(`${this.baseUrl}/population/compile`, request);
+    }
+
+    async populationTestStart(request: PopulationTestRequest): Promise<StandardResponse<PopulationTestResponse>> {
+        return await this.httpRequest.post<StandardResponse<PopulationTestResponse>>(
+            `${this.baseUrl}/population/tests`,
+            request,
+            undefined,
+            undefined,
+            undefined,
+            { timeout: POPULATION_TEST_CLIENT_TIMEOUT_MS },
+        );
+    }
+
+    async populationTestGet(testId: string, consumer?: string): Promise<StandardResponse<PopulationTestResponse>> {
+        const url = withQuery(`${this.baseUrl}/population/tests/${encodeURIComponent(testId)}`, consumerQuery(consumer));
+        return await this.httpRequest.get<StandardResponse<PopulationTestResponse>>(url);
+    }
+
+    async populationExecutionStart(request: PopulationExecutionRequest): Promise<StandardResponse<PopulationExecutionResponse>> {
+        return await this.httpRequest.post<StandardResponse<PopulationExecutionResponse>>(`${this.baseUrl}/population/executions`, request);
+    }
+
+    async populationExecutionPage(executionId: string, nextToken?: string, consumer?: string): Promise<StandardResponse<PopulationExecutionPageResponse>> {
+        const tokenQuery = nextToken === undefined ? "" : `nextToken=${encodeURIComponent(nextToken)}`;
+        const url = withQuery(`${this.baseUrl}/population/executions/${encodeURIComponent(executionId)}`, tokenQuery, consumerQuery(consumer));
+        return await this.httpRequest.get<StandardResponse<PopulationExecutionPageResponse>>(url);
+    }
 }

package/src/rules-business/api/interfaces/IRulesApi.ts

@@ -4,7 +4,16 @@ import type {
     EvaluateRulesResponse,
     GenerateRulesRequest,
     GenerateRulesResponse,
+    PopulationCompileRequest,
+    PopulationCompileResponse,
+    PopulationExecutionPageResponse,
+    PopulationExecutionRequest,
+    PopulationExecutionResponse,
+    PopulationTestRequest,
+    PopulationTestResponse,
     RulesCatalogResponse,
+    SegmentSchemaResponse,
+    SegmentTableSchemaResponse,
     ValidateRulesRequest,
     ValidateRulesResponse,
 } from "@fiado/type-kit/bin/rules/index.js";
@@ -27,4 +36,28 @@ export interface IRulesApi {
 
     /** POST /evaluate — evalúa reglas sobre hasta 100 sujetos por llamada (400 `TOO_MANY_SUBJECTS`). */
     evaluate(request: EvaluateRulesRequest): Promise<StandardResponse<EvaluateRulesResponse>>;
+
+    /** GET /population/schema — tablas del datalake disponibles para segmentar población. */
+    populationSchema(consumer?: string): Promise<StandardResponse<SegmentSchemaResponse>>;
+
+    /** GET /population/schema/{table} — columnas de una tabla del datalake. */
+    populationTableSchema(table: string, consumer?: string): Promise<StandardResponse<SegmentTableSchemaResponse>>;
+
+    /** POST /population/compile — compila una `definition` a SQL parametrizado (no ejecuta nada). */
+    populationCompile(request: PopulationCompileRequest): Promise<StandardResponse<PopulationCompileResponse>>;
+
+    /**
+     * POST /population/tests — prueba sin estado. El central corta a 12 s y responde RUNNING + `testId`;
+     * el cliente usa un timeout explícito de 20000 ms (solo dispara ante falla real → 503).
+     */
+    populationTestStart(request: PopulationTestRequest): Promise<StandardResponse<PopulationTestResponse>>;
+
+    /** GET /population/tests/{testId} — sondeo de una prueba iniciada. */
+    populationTestGet(testId: string, consumer?: string): Promise<StandardResponse<PopulationTestResponse>>;
+
+    /** POST /population/executions — inicia la ejecución de una población. */
+    populationExecutionStart(request: PopulationExecutionRequest): Promise<StandardResponse<PopulationExecutionResponse>>;
+
+    /** GET /population/executions/{id} — página (≤1000 ids) de una ejecución; `nextToken` para continuar. */
+    populationExecutionPage(executionId: string, nextToken?: string, consumer?: string): Promise<StandardResponse<PopulationExecutionPageResponse>>;
 }