@fiado/api-invoker 4.71.0 → 4.72.0

package/bin/index.d.ts

@@ -79,6 +79,8 @@ export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
 export * from "./retailCustomer/index.js";
+export * from "./retailCatalog/index.js";
+export * from "./retailCards/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";

package/bin/index.js

@@ -79,6 +79,8 @@ export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
 export * from "./retailCustomer/index.js";
+export * from "./retailCatalog/index.js";
+export * from "./retailCards/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";

package/bin/retailCards/api/RetailCardsBusinessApi.d.ts

@@ -0,0 +1,24 @@
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { AssignCardRequest } from "@fiado/type-kit/bin/retailCards/index.js";
+import { IRetailCardsBusinessApi, MarkDeliveredBody, ReleaseCardBody } from "./interfaces/IRetailCardsBusinessApi.js";
+/**
+ * Publisher HTTP del lambda `retail-cards-business` (SureKeep Fase 1, pista Retail) para sus endpoints
+ * privados de la tarjeta física PCF. Contrato y semántica completos → `IRetailCardsBusinessApi`
+ * (tenant por `?tenantId=` canónico, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CARDS_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CARDS_BUSINESS_URL: '{{resolve:ssm:retail-cards-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export default class RetailCardsBusinessApi implements IRetailCardsBusinessApi {
+    private httpRequest;
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    assign(cardNumber: string, body: AssignCardRequest, tenantId: string): Promise<StandardResponse<void>>;
+    markDelivered(cardNumber: string, body: MarkDeliveredBody, tenantId: string): Promise<StandardResponse<void>>;
+    release(cardNumber: string, body: ReleaseCardBody, tenantId: string): Promise<StandardResponse<void>>;
+}

package/bin/retailCards/api/RetailCardsBusinessApi.js

@@ -0,0 +1,51 @@
+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-cards-business` (SureKeep Fase 1, pista Retail) para sus endpoints
+ * privados de la tarjeta física PCF. Contrato y semántica completos → `IRetailCardsBusinessApi`
+ * (tenant por `?tenantId=` canónico, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CARDS_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CARDS_BUSINESS_URL: '{{resolve:ssm:retail-cards-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+let RetailCardsBusinessApi = class RetailCardsBusinessApi {
+    httpRequest;
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    baseUrl = (process.env.RETAIL_CARDS_BUSINESS_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    async assign(cardNumber, body, tenantId) {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/assign?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+    async markDelivered(cardNumber, body, tenantId) {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/deliver?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+    async release(cardNumber, body, tenantId) {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/release?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+};
+RetailCardsBusinessApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], RetailCardsBusinessApi);
+export default RetailCardsBusinessApi;

package/bin/retailCards/api/interfaces/IRetailCardsBusinessApi.d.ts

@@ -0,0 +1,41 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { AssignCardRequest } from "@fiado/type-kit/bin/retailCards/index.js";
+/**
+ * Contrato del publisher HTTP del lambda `retail-cards-business` (SureKeep Fase 1, pista Retail) para
+ * sus endpoints privados de la tarjeta física PCF, consumidos por el wizard F2 (paso 09, spike S7).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TENANT — `?tenantId=` CANÓNICO (query), NO header `x-tenant-issuer`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El silo se resuelve por el `tenantId` canónico que manda el caller (`?tenantId=` →
+ * `withContextByTenantId`). Los privados son `Feature.ANONIMUS` (sin RBAC; protección VPC). Sin
+ * `tenantId` → `UnknownTenantError` (fail-closed).
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ * Errores: el destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ *
+ * `deliver`/`release` reciben un body ligero (`{ deliveredByUserId? }` / `{ releasedByUserId? }`) que el
+ * destino no publica como DTO en `@fiado/type-kit` → se declara INLINE aquí. `assign` sí usa el DTO
+ * `AssignCardRequest` del type-kit (`{ assignedToCustomerId, assignedByUserId, creditId? }`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CARDS_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CARDS_BUSINESS_URL: '{{resolve:ssm:retail-cards-business}}'
+ */
+/** Body de POST `/private/cards/{cardNumber}/deliver`. */
+export interface MarkDeliveredBody {
+    deliveredByUserId?: string;
+}
+/** Body de POST `/private/cards/{cardNumber}/release`. */
+export interface ReleaseCardBody {
+    releasedByUserId?: string;
+}
+export interface IRetailCardsBusinessApi {
+    /** POST `/private/cards/{cardNumber}/assign` — asigna la tarjeta física a un cliente (paso 09). */
+    assign(cardNumber: string, body: AssignCardRequest, tenantId: string): Promise<StandardResponse<void>>;
+    /** POST `/private/cards/{cardNumber}/deliver` — marca la tarjeta como entregada al cliente (D8). */
+    markDelivered(cardNumber: string, body: MarkDeliveredBody, tenantId: string): Promise<StandardResponse<void>>;
+    /** POST `/private/cards/{cardNumber}/release` — revierte la asignación si la venta se cancela (DEC-007 destino). */
+    release(cardNumber: string, body: ReleaseCardBody, tenantId: string): Promise<StandardResponse<void>>;
+}

package/bin/retailCards/api/interfaces/IRetailCardsBusinessApi.js

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

package/bin/retailCards/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCardsBusinessApi.js";
+export { default as RetailCardsBusinessApi } from "./api/RetailCardsBusinessApi.js";

package/bin/retailCards/index.js

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCardsBusinessApi.js";
+export { default as RetailCardsBusinessApi } from "./api/RetailCardsBusinessApi.js";

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

@@ -0,0 +1,27 @@
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { IRetailCatalogBusinessApi, 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 →
+ * `IRetailCatalogBusinessApi` (tenant por header `x-tenant-issuer`, `StandardResponse` → leer
+ * `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CATALOG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CATALOG_BUSINESS_URL: '{{resolve:ssm:retail-catalog-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessApi {
+    private httpRequest;
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    private tenantHeader;
+    getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>>;
+    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>>;
+    returnInventory(imei: string, issuer: string): Promise<StandardResponse<void>>;
+}

package/bin/retailCatalog/api/RetailCatalogBusinessApi.js

@@ -0,0 +1,65 @@
+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";
+/** Header por el que el destino resuelve el silo (issuer Cognito forwardeado por el caller). */
+const TENANT_ISSUER_HEADER = "x-tenant-issuer";
+/**
+ * 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 →
+ * `IRetailCatalogBusinessApi` (tenant por header `x-tenant-issuer`, `StandardResponse` → leer
+ * `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CATALOG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CATALOG_BUSINESS_URL: '{{resolve:ssm:retail-catalog-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+let RetailCatalogBusinessApi = class RetailCatalogBusinessApi {
+    httpRequest;
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    baseUrl = (process.env.RETAIL_CATALOG_BUSINESS_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    tenantHeader(issuer) {
+        return { [TENANT_ISSUER_HEADER]: issuer };
+    }
+    async getStoreCatalog(storeId, issuer) {
+        const url = `${this.baseUrl}/private/stores/${encodeURIComponent(storeId)}/catalog`;
+        return await this.httpRequest.get(url, undefined, this.tenantHeader(issuer));
+    }
+    async reserveInventory(imei, body, issuer) {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/reserve`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+    async sellInventory(imei, body, issuer) {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/sell`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+    async releaseInventory(imei, body, issuer) {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/release`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+    async returnInventory(imei, issuer) {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/return`;
+        return await this.httpRequest.put(url, undefined, this.tenantHeader(issuer));
+    }
+};
+RetailCatalogBusinessApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], RetailCatalogBusinessApi);
+export default RetailCatalogBusinessApi;

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

@@ -0,0 +1,64 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+/**
+ * Contrato del publisher HTTP del lambda `retail-catalog-business` (SureKeep Fase 1, pista Retail)
+ * para sus endpoints privados del ciclo de venta del IMEI, consumidos por el wizard F2.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TENANT — header `x-tenant-issuer` (NO `?tenantId=`).
+ * ─────────────────────────────────────────────────────────────────────────────
+ * A diferencia de customer/cards/loan-config (que resuelven el silo por `?tenantId=` canónico), este
+ * lambda resuelve el tenant por el ISSUER Cognito forwardeado en el header `x-tenant-issuer`
+ * (`PrivateController.issuerFromHeader` → `TenantContextService.withContext(issuer)`). Los privados son
+ * `Feature.ANONIMUS` (sin RBAC; la protección es la red VPC), así que el caller DEBE declarar el issuer.
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ * Errores: el destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null); cada
+ * consumer mapea a su propio error de dominio.
+ *
+ * DTOs de catálogo/reserva: el lambda destino NO publica todavía estos shapes en `@fiado/type-kit`
+ * (`StoreCatalogItem`, `ReserveInventoryResult`), así que se declaran INLINE aquí (TD: migrar a
+ * type-kit cuando el contrato se estabilice). El shape espeja `StoreCatalogItemResponse` /
+ * `ReserveInventoryResponse` del `retail-catalog-business`.
+ *
+ * Env var requerida en el consumer: `RETAIL_CATALOG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CATALOG_BUSINESS_URL: '{{resolve:ssm:retail-catalog-business}}'
+ */
+/** Ítem del catálogo vendible de un store (espeja `StoreCatalogItemResponse` del destino). */
+export interface StoreCatalogItem {
+    sku: string;
+    imei: string;
+    cashPriceCents: number;
+    available: boolean;
+}
+/** Resultado de la reserva (espeja `ReserveInventoryResponse` del destino). */
+export interface ReserveInventoryResult {
+    reservationExpiresAt: string;
+}
+/** Body de PUT `/private/inventory/{imei}/reserve`. */
+export interface ReserveInventoryBody {
+    sku: string;
+    sessionId: string;
+}
+/** Body de PUT `/private/inventory/{imei}/sell` (DEC-020 del destino: `customerId` puebla `soldToCustomerId`). */
+export interface SellInventoryBody {
+    sessionId: string;
+    customerId: string;
+}
+/** Body de PUT `/private/inventory/{imei}/release` (DEC-018 del destino: verifica titularidad de la sesión). */
+export interface ReleaseReservationBody {
+    sessionId: string;
+}
+export interface IRetailCatalogBusinessApi {
+    /** GET `/private/stores/{storeId}/catalog` — catálogo vendible (sku, imei, precio de contado, disponibilidad). */
+    getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>>;
+    /** 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). */
+    sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
+    /** PUT `/private/inventory/{imei}/release` — libera la reserva (RESERVED → AVAILABLE, titularidad de la sesión). */
+    releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;
+    /** PUT `/private/inventory/{imei}/return` — devuelve el IMEI vendido al stock (SOLD → AVAILABLE, sin body). */
+    returnInventory(imei: string, issuer: string): Promise<StandardResponse<void>>;
+}

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

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

package/bin/retailCatalog/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCatalogBusinessApi.js";
+export { default as RetailCatalogBusinessApi } from "./api/RetailCatalogBusinessApi.js";

package/bin/retailCatalog/index.js

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCatalogBusinessApi.js";
+export { default as RetailCatalogBusinessApi } from "./api/RetailCatalogBusinessApi.js";

package/docs/TECH_DEBT.md

@@ -14,3 +14,10 @@ Registro vivo de deudas conscientes del repo. Cada entrada con ID estable `TD-AI
   5. `npx tsc --noEmit` verde.
   6. `npm publish` del api-invoker en su nueva version (Andres ejecuta).
 - **Bloqueante:** SÍ — el primer deploy productivo o CI run del api-invoker (y de cualquier consumer que bumpee a la 4.6.0) rompe si el publish del type-kit NO se materializó antes.
+
+## TD-AI-002 — 2026-07-20 — DTOs de catálogo/reserva/deliver tipados INLINE en los clients retail F2
+
+- **Contexto:** los clients nuevos `RetailCatalogBusinessApi` (`src/retailCatalog/`) y `RetailCardsBusinessApi` (`src/retailCards/`) declaran INLINE algunos shapes que el lambda destino aún NO publica en `@fiado/type-kit`: `StoreCatalogItem` y `ReserveInventoryResult` (catalog, espejan `StoreCatalogItemResponse`/`ReserveInventoryResponse` del destino), y los bodies ligeros `MarkDeliveredBody`/`ReleaseCardBody` (cards). `assign` sí usa el DTO real `AssignCardRequest` del type-kit.
+- **Asunción / pendiente:** se tiparon inline a propósito para no bloquear el cableado del wizard F2 en un bump de type-kit (regla de la sesión: NO tocar type-kit sin OK). Los shapes espejan fielmente el contrato del destino verificado en código.
+- **Condición para cerrar:** cuando `retail-catalog-business`/`retail-cards-business` publiquen esos DTOs en `@fiado/type-kit` (dominios `retailCatalog`/`retailCards`), reemplazar los inline por el import del type-kit y bumpear.
+- **Bloqueante:** NO — el contrato de red es correcto; es unificación de tipos con downstream.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "4.71.0",
+  "version": "4.72.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/index.ts

@@ -79,6 +79,8 @@ export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
 export * from "./retailCustomer/index.js";
+export * from "./retailCatalog/index.js";
+export * from "./retailCards/index.js";
 export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";

package/src/retailCards/api/RetailCardsBusinessApi.ts

@@ -0,0 +1,44 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { AssignCardRequest } from "@fiado/type-kit/bin/retailCards/index.js";
+import {
+    IRetailCardsBusinessApi,
+    MarkDeliveredBody,
+    ReleaseCardBody,
+} from "./interfaces/IRetailCardsBusinessApi.js";
+
+/**
+ * Publisher HTTP del lambda `retail-cards-business` (SureKeep Fase 1, pista Retail) para sus endpoints
+ * privados de la tarjeta física PCF. Contrato y semántica completos → `IRetailCardsBusinessApi`
+ * (tenant por `?tenantId=` canónico, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CARDS_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CARDS_BUSINESS_URL: '{{resolve:ssm:retail-cards-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+@injectable()
+export default class RetailCardsBusinessApi implements IRetailCardsBusinessApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    private readonly baseUrl = (process.env.RETAIL_CARDS_BUSINESS_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async assign(cardNumber: string, body: AssignCardRequest, tenantId: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/assign?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+
+    async markDelivered(cardNumber: string, body: MarkDeliveredBody, tenantId: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/deliver?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+
+    async release(cardNumber: string, body: ReleaseCardBody, tenantId: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/cards/${encodeURIComponent(cardNumber)}/release?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, body);
+    }
+}

package/src/retailCards/api/interfaces/IRetailCardsBusinessApi.ts

@@ -0,0 +1,47 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { AssignCardRequest } from "@fiado/type-kit/bin/retailCards/index.js";
+
+/**
+ * Contrato del publisher HTTP del lambda `retail-cards-business` (SureKeep Fase 1, pista Retail) para
+ * sus endpoints privados de la tarjeta física PCF, consumidos por el wizard F2 (paso 09, spike S7).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TENANT — `?tenantId=` CANÓNICO (query), NO header `x-tenant-issuer`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * El silo se resuelve por el `tenantId` canónico que manda el caller (`?tenantId=` →
+ * `withContextByTenantId`). Los privados son `Feature.ANONIMUS` (sin RBAC; protección VPC). Sin
+ * `tenantId` → `UnknownTenantError` (fail-closed).
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ * Errores: el destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ *
+ * `deliver`/`release` reciben un body ligero (`{ deliveredByUserId? }` / `{ releasedByUserId? }`) que el
+ * destino no publica como DTO en `@fiado/type-kit` → se declara INLINE aquí. `assign` sí usa el DTO
+ * `AssignCardRequest` del type-kit (`{ assignedToCustomerId, assignedByUserId, creditId? }`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CARDS_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CARDS_BUSINESS_URL: '{{resolve:ssm:retail-cards-business}}'
+ */
+
+/** Body de POST `/private/cards/{cardNumber}/deliver`. */
+export interface MarkDeliveredBody {
+    deliveredByUserId?: string;
+}
+
+/** Body de POST `/private/cards/{cardNumber}/release`. */
+export interface ReleaseCardBody {
+    releasedByUserId?: string;
+}
+
+export interface IRetailCardsBusinessApi {
+    /** POST `/private/cards/{cardNumber}/assign` — asigna la tarjeta física a un cliente (paso 09). */
+    assign(cardNumber: string, body: AssignCardRequest, tenantId: string): Promise<StandardResponse<void>>;
+
+    /** POST `/private/cards/{cardNumber}/deliver` — marca la tarjeta como entregada al cliente (D8). */
+    markDelivered(cardNumber: string, body: MarkDeliveredBody, tenantId: string): Promise<StandardResponse<void>>;
+
+    /** POST `/private/cards/{cardNumber}/release` — revierte la asignación si la venta se cancela (DEC-007 destino). */
+    release(cardNumber: string, body: ReleaseCardBody, tenantId: string): Promise<StandardResponse<void>>;
+}

package/src/retailCards/index.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCardsBusinessApi.js";
+export { default as RetailCardsBusinessApi } from "./api/RetailCardsBusinessApi.js";

package/src/retailCatalog/api/RetailCatalogBusinessApi.ts

@@ -0,0 +1,68 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import {
+    IRetailCatalogBusinessApi,
+    ReleaseReservationBody,
+    ReserveInventoryBody,
+    ReserveInventoryResult,
+    SellInventoryBody,
+    StoreCatalogItem,
+} 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";
+
+/**
+ * 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 →
+ * `IRetailCatalogBusinessApi` (tenant por header `x-tenant-issuer`, `StandardResponse` → leer
+ * `result.data`).
+ *
+ * Env var requerida en el consumer: `RETAIL_CATALOG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CATALOG_BUSINESS_URL: '{{resolve:ssm:retail-catalog-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+@injectable()
+export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    private readonly baseUrl = (process.env.RETAIL_CATALOG_BUSINESS_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    private tenantHeader(issuer: string): Record<string, string> {
+        return { [TENANT_ISSUER_HEADER]: issuer };
+    }
+
+    async getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>> {
+        const url = `${this.baseUrl}/private/stores/${encodeURIComponent(storeId)}/catalog`;
+        return await this.httpRequest.get(url, undefined, this.tenantHeader(issuer));
+    }
+
+    async reserveInventory(
+        imei: string,
+        body: ReserveInventoryBody,
+        issuer: string,
+    ): Promise<StandardResponse<ReserveInventoryResult>> {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/reserve`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+
+    async sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/sell`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+
+    async releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/release`;
+        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+    }
+
+    async returnInventory(imei: string, issuer: string): Promise<StandardResponse<void>> {
+        const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/return`;
+        return await this.httpRequest.put(url, undefined, this.tenantHeader(issuer));
+    }
+}

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

@@ -0,0 +1,75 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+
+/**
+ * Contrato del publisher HTTP del lambda `retail-catalog-business` (SureKeep Fase 1, pista Retail)
+ * para sus endpoints privados del ciclo de venta del IMEI, consumidos por el wizard F2.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TENANT — header `x-tenant-issuer` (NO `?tenantId=`).
+ * ─────────────────────────────────────────────────────────────────────────────
+ * A diferencia de customer/cards/loan-config (que resuelven el silo por `?tenantId=` canónico), este
+ * lambda resuelve el tenant por el ISSUER Cognito forwardeado en el header `x-tenant-issuer`
+ * (`PrivateController.issuerFromHeader` → `TenantContextService.withContext(issuer)`). Los privados son
+ * `Feature.ANONIMUS` (sin RBAC; la protección es la red VPC), así que el caller DEBE declarar el issuer.
+ *
+ * ⚠️ Retorno `StandardResponse<T>` — el consumer lee `result.data`, NO `result.body`.
+ * Errores: el destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null); cada
+ * consumer mapea a su propio error de dominio.
+ *
+ * DTOs de catálogo/reserva: el lambda destino NO publica todavía estos shapes en `@fiado/type-kit`
+ * (`StoreCatalogItem`, `ReserveInventoryResult`), así que se declaran INLINE aquí (TD: migrar a
+ * type-kit cuando el contrato se estabilice). El shape espeja `StoreCatalogItemResponse` /
+ * `ReserveInventoryResponse` del `retail-catalog-business`.
+ *
+ * Env var requerida en el consumer: `RETAIL_CATALOG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   RETAIL_CATALOG_BUSINESS_URL: '{{resolve:ssm:retail-catalog-business}}'
+ */
+
+/** Ítem del catálogo vendible de un store (espeja `StoreCatalogItemResponse` del destino). */
+export interface StoreCatalogItem {
+    sku: string;
+    imei: string;
+    cashPriceCents: number;
+    available: boolean;
+}
+
+/** Resultado de la reserva (espeja `ReserveInventoryResponse` del destino). */
+export interface ReserveInventoryResult {
+    reservationExpiresAt: string;
+}
+
+/** Body de PUT `/private/inventory/{imei}/reserve`. */
+export interface ReserveInventoryBody {
+    sku: string;
+    sessionId: string;
+}
+
+/** Body de PUT `/private/inventory/{imei}/sell` (DEC-020 del destino: `customerId` puebla `soldToCustomerId`). */
+export interface SellInventoryBody {
+    sessionId: string;
+    customerId: string;
+}
+
+/** Body de PUT `/private/inventory/{imei}/release` (DEC-018 del destino: verifica titularidad de la sesión). */
+export interface ReleaseReservationBody {
+    sessionId: string;
+}
+
+export interface IRetailCatalogBusinessApi {
+    /** GET `/private/stores/{storeId}/catalog` — catálogo vendible (sku, imei, precio de contado, disponibilidad). */
+    getStoreCatalog(storeId: string, issuer: string): Promise<StandardResponse<StoreCatalogItem[]>>;
+
+    /** 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). */
+    sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
+
+    /** PUT `/private/inventory/{imei}/release` — libera la reserva (RESERVED → AVAILABLE, titularidad de la sesión). */
+    releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;
+
+    /** PUT `/private/inventory/{imei}/return` — devuelve el IMEI vendido al stock (SOLD → AVAILABLE, sin body). */
+    returnInventory(imei: string, issuer: string): Promise<StandardResponse<void>>;
+}

package/src/retailCatalog/index.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/IRetailCatalogBusinessApi.js";
+export { default as RetailCatalogBusinessApi } from "./api/RetailCatalogBusinessApi.js";