@fiado/type-kit 3.354.0 → 3.356.0

package/src/webhookBusiness/dtos/requests/RedeliverWebhookEventRequest.ts

@@ -0,0 +1,28 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsNotEmptyObject, IsObject, IsOptional, IsString, MaxLength } from 'class-validator';
+import { WEBHOOK_EVENT_ID_MAX_LENGTH } from '../../constants/WebhookFieldLimits';
+
+/**
+ * Body de `POST /private/webhook-deliveries/redeliver` — reposición manual de un evento.
+ * El `payload` viaja en el request porque la bitácora guarda el desenlace, nunca el evento: de la
+ * fila salen el tipo, el origen y el destinatario; el contenido lo repone quien lo produjo.
+ */
+export class RedeliverWebhookEventRequest {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    @MaxLength(WEBHOOK_EVENT_ID_MAX_LENGTH)
+    eventId!: string;
+
+    @Expose()
+    @IsObject()
+    @IsNotEmptyObject()
+    payload!: unknown;
+
+    /** Quién dispara el reenvío, para el log de la reposición. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(128)
+    actor?: string;
+}

package/src/webhookBusiness/dtos/requests/UpsertWebhookSubscriptionRequest.ts

@@ -0,0 +1,69 @@
+import { Expose, Type } from 'class-transformer';
+import { IsEnum, IsInt, IsNotEmpty, IsOptional, IsPositive, IsString, IsUrl, MaxLength } from 'class-validator';
+import { WebhookEventType } from '../../enums/WebhookEventType';
+import { SubscriptionStatusEnum } from '../../enums/SubscriptionStatusEnum';
+import { SubscriptionVisibilityEnum } from '../../enums/SubscriptionVisibilityEnum';
+import { WEBHOOK_TAG_MAX_LENGTH } from '../../constants/WebhookFieldLimits';
+
+/**
+ * Body de `PUT /private/webhook-subscriptions` — alta o actualización de una fila del padrón.
+ * Es idempotente: el par `(tag, eventType)` es la llave, así que reenviar el mismo body no duplica.
+ */
+export class UpsertWebhookSubscriptionRequest {
+    /** Tag de enrutamiento. El prefijo reservado lo verifica el manager, no el DTO. */
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    @MaxLength(WEBHOOK_TAG_MAX_LENGTH)
+    tag!: string;
+
+    @Expose()
+    @IsEnum(WebhookEventType)
+    eventType!: WebhookEventType;
+
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    @MaxLength(128)
+    subscriberName!: string;
+
+    /** Absoluta en los dos modos de visibilidad: el dispatcher hace POST contra ella tal cual. */
+    @Expose()
+    @IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })
+    url!: string;
+
+    @Expose()
+    @IsEnum(SubscriptionVisibilityEnum)
+    visibility!: SubscriptionVisibilityEnum;
+
+    @Expose()
+    @IsEnum(SubscriptionStatusEnum)
+    status!: SubscriptionStatusEnum;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(128)
+    integrationId?: string;
+
+    @Expose()
+    @IsOptional()
+    @Type(() => Number)
+    @IsInt()
+    @IsPositive()
+    timeoutMs?: number;
+
+    @Expose()
+    @IsOptional()
+    @Type(() => Number)
+    @IsInt()
+    @IsPositive()
+    maxRetries?: number;
+
+    /** Quién dispara el alta. Sin él la auditoría queda en `system`, que es el actor de los procesos. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(128)
+    actor?: string;
+}

package/src/webhookBusiness/dtos/responses/DeactivateWebhookSubscriptionResponse.ts

@@ -0,0 +1,6 @@
+import type { WebhookSubscriptionView } from '../WebhookSubscriptionView';
+
+/** Respuesta de `POST /private/webhook-subscriptions/deactivate`. */
+export interface DeactivateWebhookSubscriptionResponse {
+    subscription: WebhookSubscriptionView;
+}

package/src/webhookBusiness/dtos/responses/GetWebhookSubscriptionResponse.ts

@@ -0,0 +1,6 @@
+import type { WebhookSubscriptionView } from '../WebhookSubscriptionView';
+
+/** Respuesta de `GET /private/webhook-subscriptions/lookup`. */
+export interface GetWebhookSubscriptionResponse {
+    subscription: WebhookSubscriptionView;
+}

package/src/webhookBusiness/dtos/responses/ListWebhookDeliveriesResponse.ts

@@ -0,0 +1,11 @@
+import type { WebhookDeliveryView } from '../WebhookDeliveryView';
+
+/**
+ * Respuesta de `GET /private/webhook-deliveries`. Un comprador sin asientos devuelve la lista
+ * vacía y no un 404: que nunca le haya salido un evento es un estado válido.
+ */
+export interface ListWebhookDeliveriesResponse {
+    directoryId: string;
+    deliveries: WebhookDeliveryView[];
+    count: number;
+}

package/src/webhookBusiness/dtos/responses/ListWebhookSubscriptionsResponse.ts

@@ -0,0 +1,11 @@
+import type { WebhookSubscriptionView } from '../WebhookSubscriptionView';
+
+/**
+ * Respuesta de `GET /private/webhook-subscriptions` — el padrón completo.
+ * `truncated` avisa que se alcanzó el tope de la lectura y quedaron filas afuera.
+ */
+export interface ListWebhookSubscriptionsResponse {
+    subscriptions: WebhookSubscriptionView[];
+    count: number;
+    truncated: boolean;
+}

package/src/webhookBusiness/dtos/responses/RedeliverWebhookEventResponse.ts

@@ -0,0 +1,12 @@
+import type { WebhookEventType } from '../../enums/WebhookEventType';
+
+/**
+ * Respuesta de `POST /private/webhook-deliveries/redeliver`. Devuelve qué se repuso, no cómo
+ * terminó cada destino: eso queda en la bitácora, que es la fuente de los desenlaces.
+ */
+export interface RedeliverWebhookEventResponse {
+    eventId: string;
+    eventType: WebhookEventType;
+    directoryId: string;
+    redeliveredAt: string;
+}

package/src/webhookBusiness/dtos/responses/UpsertWebhookSubscriptionResponse.ts

@@ -0,0 +1,8 @@
+import type { WebhookSubscriptionView } from '../WebhookSubscriptionView';
+
+/** Respuesta de `PUT /private/webhook-subscriptions`. */
+export interface UpsertWebhookSubscriptionResponse {
+    /** `true` cuando el par `(tag, eventType)` no existía y se dio de alta. */
+    created: boolean;
+    subscription: WebhookSubscriptionView;
+}

package/src/webhookBusiness/enums/ComplianceDecisionEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Desenlace del dictamen del oficial de cumplimiento, en los únicos dos términos accionables.
+ * Deliberadamente NO existe un valor que insinúe sobre qué se dictaminó: avisar de una coincidencia
+ * en listas es delito, y este enum viaja a un externo.
+ */
+export enum ComplianceDecisionEnum {
+    /** Se liberó el caso: el siguiente intento de abrir la cuenta puede pasar. */
+    CLEARED = 'CLEARED',
+    /** Terminal: la cuenta no se abre y la venta no continúa. Nadie lo va a destrabar. */
+    REJECTED = 'REJECTED',
+}

package/src/webhookBusiness/enums/DeliveryOutcomeEnum.ts

@@ -0,0 +1,15 @@
+/** Desenlace de un evento frente a un destinatario, tal como queda asentado en la bitácora. */
+export enum DeliveryOutcomeEnum {
+    /** El suscriptor aceptó el evento. */
+    DELIVERED = 'DELIVERED',
+    /** El suscriptor rechazó la entrega o no respondió. El mensaje vuelve a la cola. */
+    FAILED = 'FAILED',
+    /** Se agotaron los intentos que el destino admite. No se vuelve a intentar. */
+    EXHAUSTED = 'EXHAUSTED',
+    /** El directoryId no traía ningún tag `wh:*`: el evento se descarta sin reintento. */
+    NO_RECIPIENT = 'NO_RECIPIENT',
+    /** El tag existe pero nadie declaró un destino para ese eventType. */
+    NO_SUBSCRIPTION = 'NO_SUBSCRIPTION',
+    /** El destino está dado de baja: es un no-op registrado, no un error. */
+    SKIPPED_INACTIVE = 'SKIPPED_INACTIVE',
+}

package/src/webhookBusiness/enums/SubscriptionStatusEnum.ts

@@ -0,0 +1,5 @@
+/** Permite apagar un destino sin borrar su fila del padrón. */
+export enum SubscriptionStatusEnum {
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+}

package/src/webhookBusiness/enums/SubscriptionVisibilityEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Qué cliente y qué credenciales lleva la entrega. No es "dentro o fuera de la VPC".
+ * Es enum y no un booleano para poder sumar un tercer modo (firma, mTLS, bearer) sin migrar la tabla.
+ */
+export enum SubscriptionVisibilityEnum {
+    /** Receptor dentro de la VPC: la baseUrl se resuelve por destino y se pasa por llamada. */
+    PRIVATE = 'PRIVATE',
+    /** Receptor fuera de la VPC: HTTP plano contra la URL absoluta, sin token ni headers propios. */
+    PUBLIC = 'PUBLIC',
+}

package/src/webhookBusiness/enums/WebhookEventType.ts

@@ -0,0 +1,10 @@
+/**
+ * Catálogo cerrado de eventos que `webhook-business` entrega a suscriptores externos (corte 1).
+ * El valor es el nombre versionado del contrato: el receptor rutea por él y no por el shape.
+ */
+export enum WebhookEventType {
+    /** La emisión de la cuenta PCF llegó a su desenlace terminal (abrió o falló). */
+    AccountIssuanceCompleted = 'AccountIssuanceCompletedV1',
+    /** El oficial de cumplimiento dictaminó sobre el caso. */
+    ComplianceDecision = 'ComplianceDecisionV1',
+}

package/src/webhookBusiness/events/AccountIssuanceCompletedV1.ts

@@ -0,0 +1,30 @@
+import { Expose } from 'class-transformer';
+import { IsIn, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+import { AccountStatusEnum } from '../../retailCustomer/enums/AccountStatusEnum';
+import { WEBHOOK_FAIL_REASON_MAX_LENGTH } from '../constants/WebhookFieldLimits';
+
+/**
+ * Desenlace terminal de la emisión de la cuenta PCF, entregado por webhook a un suscriptor externo.
+ * Espeja `RetailCustomer.AccountResultRequest`, el contrato que el receptor ya espera. No lleva CLABE.
+ */
+export class AccountIssuanceCompletedV1 {
+    /** Identidad de la persona en Fiado. El `directoryId` viaja en el sobre, no aquí. */
+    @Expose() @IsString() @IsNotEmpty()
+    peopleId!: string;
+
+    /** `OPENING` y `LINKED` no son valores válidos: este evento solo reporta el desenlace. */
+    @Expose() @IsIn([AccountStatusEnum.OPEN, AccountStatusEnum.FAILED])
+    status!: AccountStatusEnum;
+
+    /** Nivel de la cuenta PCF. Presente solo con `OPEN`. */
+    @Expose() @IsOptional() @IsIn([1, 2])
+    pcfAccountLevel?: 1 | 2;
+
+    /**
+     * Por qué no abrió, para soporte y administración. Presente solo con `FAILED`.
+     * Texto libre del core, que puede mencionar cumplimiento: nunca se le muestra al vendedor ni al
+     * comprador, misma regla que `WizardBlocked.detail`.
+     */
+    @Expose() @IsOptional() @IsString() @MaxLength(WEBHOOK_FAIL_REASON_MAX_LENGTH)
+    failReason?: string;
+}

package/src/webhookBusiness/events/ComplianceDecisionV1.ts

@@ -0,0 +1,36 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsISO8601, IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
+import { ComplianceDecisionEnum } from '../enums/ComplianceDecisionEnum';
+import { WEBHOOK_CASE_REF_MESSAGE, WEBHOOK_CASE_REF_PATTERN } from '../constants/CaseRefPattern';
+
+/**
+ * Dictamen del oficial de cumplimiento, entregado por webhook a un suscriptor externo.
+ * Lleva el desenlace accionable y nada más: el receptor necesita saber qué hacer, no por qué.
+ *
+ * Restricción legal, no preferencia de diseño. El DTO NO lleva qué lista disparó, ni la
+ * justificación del oficial, ni quién firmó, ni el `alertId` de PLD. Avisar de una coincidencia en
+ * listas de cumplimiento es delito. Cualquier campo que se agregue aquí tiene que pasar ese filtro.
+ */
+export class ComplianceDecisionV1 {
+    /** Identidad de la persona en Fiado. El `directoryId` viaja en el sobre, no aquí. */
+    @Expose() @IsString() @IsNotEmpty()
+    peopleId!: string;
+
+    /**
+     * Estado consolidado del caso, no el sello de una lista: `REJECTED` en cuanto una lista rechaza,
+     * `CLEARED` sólo cuando ya no queda ninguna trabando.
+     */
+    @Expose() @IsEnum(ComplianceDecisionEnum)
+    decision!: ComplianceDecisionEnum;
+
+    /** ISO-8601. Cuándo se estampó el dictamen. */
+    @Expose() @IsString() @IsISO8601()
+    decidedAt!: string;
+
+    /**
+     * Referencia OPACA para soporte, acuñada para el webhook: permite rastrear el caso sin nombrarlo.
+     * El formato con prefijo es lo que impide que entre el `alertId` de PLD. Ver `CaseRefPattern`.
+     */
+    @Expose() @IsOptional() @IsString() @Matches(WEBHOOK_CASE_REF_PATTERN, { message: WEBHOOK_CASE_REF_MESSAGE })
+    caseRef?: string;
+}

package/src/webhookBusiness/index.ts

@@ -0,0 +1,37 @@
+// Enums
+export * from './enums/WebhookEventType';
+export * from './enums/ComplianceDecisionEnum';
+export * from './enums/SubscriptionVisibilityEnum';
+export * from './enums/SubscriptionStatusEnum';
+export * from './enums/DeliveryOutcomeEnum';
+
+// Formatos y topes compartidos por los contratos
+export * from './constants/CaseRefPattern';
+export * from './constants/WebhookFieldLimits';
+
+// Contratos de eventos (PascalCase + sufijo V1)
+export * from './events/AccountIssuanceCompletedV1';
+export * from './events/ComplianceDecisionV1';
+
+// Sobre común + unión cerrada de la cola
+export * from './dtos/WebhookEventEnvelope';
+export * from './dtos/WebhookOutboundMessage';
+
+// Vistas del padrón y de la bitácora, tal como salen por la API de administración
+export * from './dtos/WebhookSubscriptionView';
+export * from './dtos/WebhookDeliveryView';
+
+// API privada de administración — requests
+export * from './dtos/requests/UpsertWebhookSubscriptionRequest';
+export * from './dtos/requests/GetWebhookSubscriptionRequest';
+export * from './dtos/requests/DeactivateWebhookSubscriptionRequest';
+export * from './dtos/requests/ListWebhookDeliveriesRequest';
+export * from './dtos/requests/RedeliverWebhookEventRequest';
+
+// API privada de administración — responses
+export * from './dtos/responses/UpsertWebhookSubscriptionResponse';
+export * from './dtos/responses/GetWebhookSubscriptionResponse';
+export * from './dtos/responses/ListWebhookSubscriptionsResponse';
+export * from './dtos/responses/DeactivateWebhookSubscriptionResponse';
+export * from './dtos/responses/ListWebhookDeliveriesResponse';
+export * from './dtos/responses/RedeliverWebhookEventResponse';