@fiado/type-kit 3.509.0 → 3.511.0

package/src/rewards/dtos/RewardDependency.ts

@@ -0,0 +1,18 @@
+import { InputField } from '../../dynamicForm/dtos/InputField';
+import { DependencyIfMissingEnum } from '../enums/DependencyIfMissingEnum';
+
+/**
+ * Una dependencia de una recompensa: lo que quien consume debe enviar para poder entregarla.
+ * Adopta la forma de `InputField` (formulario dinámico compartido) y suma los campos propios
+ * de rewards (spec A 5.1).
+ */
+export class RewardDependency extends InputField {
+    /** Condición que la vuelve necesaria (sobre otras dependencias), si aplica. */
+    requiredWhen?: string;
+    /** Qué pasa si falta cuando se necesitaba. Por defecto, REJECT. */
+    ifMissing?: DependencyIfMissingEnum;
+    /** De dónde la saca el lambda solo cuando no se envía. */
+    resolvedFrom?: string;
+    /** Texto corto para quien consume. */
+    description?: string;
+}

package/src/rewards/dtos/RewardSource.ts

@@ -0,0 +1,27 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsOptional, IsString, Validate } from 'class-validator';
+import { IsRewardTags } from '../validators/IsRewardTags';
+
+/**
+ * Quién pide la entrega. El lambda no interpreta `reference` ni `tags`: los guarda y los usa como
+ * filtro/auditoría (spec A D1, D10).
+ */
+export class RewardSource {
+    /** Servicio llamador (ej. `rewards-eligibility`). Entra en el `grantId`. */
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    service!: string;
+
+    /** Referencia opaca del llamador (ej. `runId`). */
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    reference!: string;
+
+    /** Etiquetas opacas (ej. `campaignId`, `evaluationId`). Máx. 10 llaves. */
+    @Expose()
+    @IsOptional()
+    @Validate(IsRewardTags)
+    tags?: Record<string, string>;
+}

package/src/rewards/dtos/responses/GrantAttemptResponse.ts

@@ -0,0 +1,16 @@
+import { ItemErrorCategoryEnum } from '../../enums/ItemErrorCategoryEnum';
+
+/**
+ * Un intento de ejecutar un ítem. Sin `providerResponse`, `requestSnapshot` ni `correlationIds`:
+ * contienen PII y solo se leen en el backoffice (spec A R2).
+ */
+export class GrantAttemptResponse {
+    attempt: number;
+    /** Epoch en milisegundos. */
+    startedAt: number;
+    /** Epoch en milisegundos. */
+    finishedAt: number;
+    errorCategory?: ItemErrorCategoryEnum;
+    errorCode?: string;
+    httpStatus?: number;
+}

package/src/rewards/dtos/responses/GrantItemResponse.ts

@@ -0,0 +1,21 @@
+import { GrantItemStatusEnum } from '../../enums/GrantItemStatusEnum';
+import { RewardChargeTo } from '../RewardChargeTo';
+import { RewardCost } from '../RewardCost';
+import { GrantAttemptResponse } from './GrantAttemptResponse';
+
+export class GrantItemResponse {
+    itemKey: string;
+    catalogItemId: string;
+    status: GrantItemStatusEnum;
+    /** Solo si `status` es SKIPPED (ej. `DEPENDENCY_MISSING`, `ITEM_NOT_APPLICABLE`). */
+    skipReason?: string;
+    chargeTo: RewardChargeTo;
+    cost: RewardCost;
+    attemptCount: number;
+    /** Epoch en milisegundos; solo si `status` es GRANTED. */
+    grantedAt?: number;
+    /** Referencias del proveedor (ej. `{ transactionNumber }`). */
+    externalRef?: Record<string, string>;
+    /** Últimos intentos (máx. 5). */
+    attempts: GrantAttemptResponse[];
+}

package/src/rewards/dtos/responses/GrantResponse.ts

@@ -0,0 +1,24 @@
+import { GrantRejectReasonEnum } from '../../enums/GrantRejectReasonEnum';
+import { GrantStatusEnum } from '../../enums/GrantStatusEnum';
+import { RewardSource } from '../RewardSource';
+import { GrantItemResponse } from './GrantItemResponse';
+
+/** Respuesta de `GET /grants/{id}`: estado de la entrega y de cada ítem (spec A 6.4). */
+export class GrantResponse {
+    id: string;
+    directoryId: string;
+    packageId: string;
+    /** Versión del paquete congelada al crear la entrega. */
+    packageVersion: number;
+    source: RewardSource;
+    status: GrantStatusEnum;
+    /** Solo si `status` es REJECTED. */
+    rejectReason?: GrantRejectReasonEnum;
+    /** Solo si `rejectReason` es `INPUT_INVALID`: claves de los campos inválidos, `itemKey.inputKey` (spec A §6.2). */
+    invalidFields?: string[];
+    items: GrantItemResponse[];
+    /** Epoch en milisegundos. */
+    createdAt: number;
+    /** Epoch en milisegundos. */
+    updatedAt: number;
+}

package/src/rewards/dtos/responses/PackageContractItem.ts

@@ -0,0 +1,13 @@
+import { RewardCost } from '../RewardCost';
+import { RewardDependency } from '../RewardDependency';
+
+/** Una recompensa dentro del contrato de un paquete (spec A 6.3). */
+export class PackageContractItem {
+    itemKey: string;
+    catalogItemId: string;
+    name: string;
+    description: string;
+    cost: RewardCost;
+    /** Lo que el llamador debe enviar en `inputs[itemKey]`. */
+    dependencies: RewardDependency[];
+}

package/src/rewards/dtos/responses/PackageContractResponse.ts

@@ -0,0 +1,14 @@
+import { RewardStatusEnum } from '../../enums/RewardStatusEnum';
+import { RewardCost } from '../RewardCost';
+import { PackageContractItem } from './PackageContractItem';
+
+/** Respuesta de `GET /packages/{id}`: el contrato de entrada del paquete (spec A 6.3). */
+export class PackageContractResponse {
+    id: string;
+    name: string;
+    status: RewardStatusEnum;
+    version: number;
+    items: PackageContractItem[];
+    /** Costo total declarado del paquete, por moneda (sin conversión). */
+    totalCost: RewardCost[];
+}

package/src/rewards/enums/DependencyIfMissingEnum.ts

@@ -0,0 +1,5 @@
+/** Qué pasa si falta una dependencia que se necesitaba (spec A 5.1). */
+export enum DependencyIfMissingEnum {
+    REJECT = 'REJECT',
+    SKIP = 'SKIP',
+}

package/src/rewards/enums/GrantFailedReasonEnum.ts

@@ -0,0 +1,15 @@
+/**
+ * `reason` de `GRANT_FAILED` (spec A 6.5). `INPUT_INVALID`, `PACKAGE_NOT_FOUND` y `PACKAGE_INACTIVE` son las
+ * de `GrantRejectReasonEnum` (entrega REJECTED); `ITEMS_FAILED` es una entrega FAILED: ningún ítem se entregó.
+ * Decisión P-2 aprobada.
+ *
+ * Excepción: un REJECTED por `GrantRejectReasonEnum.UNSUPPORTED_REWARD_TYPE` se avisa como `INPUT_INVALID`
+ * (el paquete pide algo que el núcleo no puede ejecutar, o sea una solicitud inválida para este lambda).
+ * No se agregó un valor nuevo para no ampliar el contrato de la cola.
+ */
+export enum GrantFailedReasonEnum {
+    INPUT_INVALID = 'INPUT_INVALID',
+    PACKAGE_NOT_FOUND = 'PACKAGE_NOT_FOUND',
+    PACKAGE_INACTIVE = 'PACKAGE_INACTIVE',
+    ITEMS_FAILED = 'ITEMS_FAILED',
+}

package/src/rewards/enums/GrantItemStatusEnum.ts

@@ -0,0 +1,11 @@
+export enum GrantItemStatusEnum {
+    PENDING = 'PENDING',
+    /**
+     * Reclamado por el worker antes de ejecutar; si un reintento lo encuentra así, el envío pudo haber
+     * ocurrido y el adaptador debe reconciliar antes de reintentar.
+     */
+    PROCESSING = 'PROCESSING',
+    GRANTED = 'GRANTED',
+    FAILED = 'FAILED',
+    SKIPPED = 'SKIPPED',
+}

package/src/rewards/enums/GrantRejectReasonEnum.ts

@@ -0,0 +1,11 @@
+/** Por qué una solicitud quedó REJECTED (spec A 6.2). */
+export enum GrantRejectReasonEnum {
+    INPUT_INVALID = 'INPUT_INVALID',
+    PACKAGE_NOT_FOUND = 'PACKAGE_NOT_FOUND',
+    PACKAGE_INACTIVE = 'PACKAGE_INACTIVE',
+    /**
+     * El paquete contiene un tipo de recompensa sin adaptador registrado; se rechaza antes de ejecutar
+     * cualquier ítem.
+     */
+    UNSUPPORTED_REWARD_TYPE = 'UNSUPPORTED_REWARD_TYPE',
+}

package/src/rewards/enums/GrantStatusEnum.ts

@@ -0,0 +1,8 @@
+export enum GrantStatusEnum {
+    PENDING = 'PENDING',
+    IN_PROGRESS = 'IN_PROGRESS',
+    COMPLETED = 'COMPLETED',
+    PARTIAL = 'PARTIAL',
+    FAILED = 'FAILED',
+    REJECTED = 'REJECTED',
+}

package/src/rewards/enums/ItemErrorCategoryEnum.ts

@@ -0,0 +1,7 @@
+export enum ItemErrorCategoryEnum {
+    PROVIDER_UNAVAILABLE = 'PROVIDER_UNAVAILABLE',
+    REQUEST_INVALID = 'REQUEST_INVALID',
+    PROVIDER_REJECTED = 'PROVIDER_REJECTED',
+    INPUT_UNRESOLVABLE = 'INPUT_UNRESOLVABLE',
+    INTERNAL_ERROR = 'INTERNAL_ERROR',
+}

package/src/rewards/enums/RewardStatusEnum.ts

@@ -0,0 +1,4 @@
+export enum RewardStatusEnum {
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+}

package/src/rewards/enums/RewardsErrorCodeEnum.ts

@@ -0,0 +1,5 @@
+/** Códigos de error de las lecturas privadas de rewards-business. */
+export enum RewardsErrorCodeEnum {
+    PACKAGE_NOT_FOUND = 'PACKAGE_NOT_FOUND',
+    GRANT_NOT_FOUND = 'GRANT_NOT_FOUND',
+}

package/src/rewards/enums/RewardsMessageTypeEnum.ts

@@ -0,0 +1,4 @@
+export enum RewardsMessageTypeEnum {
+    GRANT_REQUESTED = 'GRANT_REQUESTED',
+    GRANT_FAILED = 'GRANT_FAILED',
+}

package/src/rewards/index.ts

@@ -0,0 +1,37 @@
+//Enums
+export * from './enums/RewardsMessageTypeEnum';
+export * from './enums/GrantStatusEnum';
+export * from './enums/GrantItemStatusEnum';
+export * from './enums/GrantRejectReasonEnum';
+export * from './enums/GrantFailedReasonEnum';
+export * from './enums/ItemErrorCategoryEnum';
+export * from './enums/RewardStatusEnum';
+export * from './enums/DependencyIfMissingEnum';
+export * from './enums/RewardsErrorCodeEnum';
+
+//Types
+export * from './types/RewardInputs';
+
+//DTOs
+export * from './dtos/RewardCost';
+export * from './dtos/RewardChargeTo';
+export * from './dtos/RewardDependency';
+
+//Constants
+export * from './constants/RewardsLimits';
+
+//Validators
+export * from './validators/IsRewardTags';
+export * from './validators/IsRewardInputs';
+
+//Messages (colas compartidas)
+export * from './dtos/RewardSource';
+export * from './dtos/GrantRequestedMessage';
+export * from './dtos/GrantFailedMessage';
+
+//Responses (lecturas privadas)
+export * from './dtos/responses/PackageContractItem';
+export * from './dtos/responses/PackageContractResponse';
+export * from './dtos/responses/GrantAttemptResponse';
+export * from './dtos/responses/GrantItemResponse';
+export * from './dtos/responses/GrantResponse';

package/src/rewards/types/RewardInputs.ts

@@ -0,0 +1,4 @@
+import { DynamicFormValue } from '../../dynamicForm/types/DynamicFormValue';
+
+/** `inputs` de un pedido de entrega: `itemKey → inputKey → valor` (spec A 6.1). */
+export type RewardInputs = Record<string, Record<string, DynamicFormValue>>;

package/src/rewards/validators/IsRewardInputs.ts

@@ -0,0 +1,18 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { JsonValue } from '../../common/types/JsonValue';
+import { isDynamicFormValue, isPlainObject } from '../../dynamicForm/helpers/isDynamicFormValue';
+
+/** `inputs`: `itemKey → inputKey → valor` (dos niveles exactos; la hoja es un DynamicFormValue). */
+@ValidatorConstraint({ name: 'IsRewardInputs', async: false })
+export class IsRewardInputs implements ValidatorConstraintInterface {
+    validate(value: JsonValue, _args: ValidationArguments): boolean {
+        if (!isPlainObject(value)) return false;
+        return Object.values(value).every(
+            (porItem) => isPlainObject(porItem) && Object.values(porItem).every(isDynamicFormValue),
+        );
+    }
+
+    defaultMessage(_args: ValidationArguments): string {
+        return 'inputs debe ser un mapa itemKey → (inputKey → string | number | boolean | {from, to})';
+    }
+}

package/src/rewards/validators/IsRewardTags.ts

@@ -0,0 +1,18 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { JsonValue } from '../../common/types/JsonValue';
+import { isPlainObject } from '../../dynamicForm/helpers/isDynamicFormValue';
+import { REWARD_TAGS_MAX_KEYS } from '../constants/RewardsLimits';
+
+/** `source.tags`: mapa texto → texto, máximo `REWARD_TAGS_MAX_KEYS` llaves. */
+@ValidatorConstraint({ name: 'IsRewardTags', async: false })
+export class IsRewardTags implements ValidatorConstraintInterface {
+    validate(value: JsonValue, _args: ValidationArguments): boolean {
+        if (!isPlainObject(value)) return false;
+        const entries = Object.entries(value);
+        return entries.length <= REWARD_TAGS_MAX_KEYS && entries.every(([, tag]) => typeof tag === 'string');
+    }
+
+    defaultMessage(_args: ValidationArguments): string {
+        return `tags debe ser un mapa texto → texto de máximo ${REWARD_TAGS_MAX_KEYS} llaves`;
+    }
+}

package/src/rewardsEligibility/dtos/EventRunResult.ts

@@ -0,0 +1,12 @@
+import { EvaluationOutcomeEnum } from '../enums/EvaluationOutcomeEnum';
+import { GrantRequestStatusEnum } from '../enums/GrantRequestStatusEnum';
+
+/** Resultado de una evaluación suscrita al evento (una corrida con lote de 1). */
+export class EventRunResult {
+    evaluationId: string;
+    runId: string;
+    outcome: EvaluationOutcomeEnum;
+    grantStatus: GrantRequestStatusEnum;
+    /** true si el `idempotencyKey` ya había creado esta corrida. */
+    idempotentReplay: boolean;
+}

package/src/rewardsEligibility/dtos/EventSource.ts

@@ -0,0 +1,15 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+/** Quién emite el evento. El validador no interpreta `reference`. */
+export class EventSource {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    service!: string;
+
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    reference!: string;
+}

package/src/rewardsEligibility/dtos/GetRunResponse.ts

@@ -0,0 +1,23 @@
+import { RunModeEnum } from '../enums/RunModeEnum';
+import { RunStatusEnum } from '../enums/RunStatusEnum';
+import { TriggerTypeEnum } from '../enums/TriggerTypeEnum';
+import { RunCounts } from './RunCounts';
+import { RunResultItem } from './RunResultItem';
+
+/** Respuesta de `GET /runs/{id}` (spec B 6.2). */
+export class GetRunResponse {
+    runId: string;
+    evaluationId: string;
+    trigger: TriggerTypeEnum;
+    mode: RunModeEnum;
+    status: RunStatusEnum;
+    counts: RunCounts;
+    /** Una página de resultados. */
+    results: RunResultItem[];
+    /** Presente si hay más resultados. */
+    nextToken?: string;
+    /** Epoch en milisegundos. */
+    createdAt: number;
+    /** Epoch en milisegundos. */
+    updatedAt: number;
+}

package/src/rewardsEligibility/dtos/PostEventRequest.ts

@@ -0,0 +1,32 @@
+import { Expose, Type } from 'class-transformer';
+import { IsNotEmpty, IsString, Validate, ValidateNested } from 'class-validator';
+import { DynamicFormValue } from '../../dynamicForm/types/DynamicFormValue';
+import { IsDynamicFormValues } from '../../dynamicForm/validators/IsDynamicFormValues';
+import { EventSource } from './EventSource';
+
+/**
+ * Cuerpo de `POST /events` (spec B 6.1). El emisor informa qué pasó y quién participó; NO decide
+ * la elegibilidad (E3). Parsear con `excludeExtraneousValues: true`: cualquier campo extra
+ * (p. ej. `prefetchedFacts`) se descarta.
+ */
+export class PostEventRequest {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    eventKey!: string;
+
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    idempotencyKey!: string;
+
+    @Expose()
+    @ValidateNested()
+    @Type(() => EventSource)
+    source!: EventSource;
+
+    /** Los `fields` del tipo de evento (`RewardEventType_GT`), con su valor. */
+    @Expose()
+    @Validate(IsDynamicFormValues)
+    inputs!: Record<string, DynamicFormValue>;
+}

package/src/rewardsEligibility/dtos/PostEventResponse.ts

@@ -0,0 +1,6 @@
+import { EventRunResult } from './EventRunResult';
+
+/** Respuesta 202 de `POST /events`; `runs` vacío si ninguna evaluación escucha el evento. */
+export class PostEventResponse {
+    runs: EventRunResult[];
+}

package/src/rewardsEligibility/dtos/RunCounts.ts

@@ -0,0 +1,12 @@
+/** Conteos de una corrida (mismos nombres que las métricas, spec B 5.7). */
+export class RunCounts {
+    evaluated: number;
+    match: number;
+    noMatch: number;
+    error: number;
+    alreadyGranted: number;
+    quotaExhausted: number;
+    excluded: number;
+    requested: number;
+    requestFailed: number;
+}

package/src/rewardsEligibility/dtos/RunResultItem.ts

@@ -0,0 +1,17 @@
+import { EvaluationOutcomeEnum } from '../enums/EvaluationOutcomeEnum';
+import { GrantRequestStatusEnum } from '../enums/GrantRequestStatusEnum';
+
+/** Un resultado por sujeto, SIN traza (la traza es del backoffice). Asumido hasta cerrar P-7. */
+export class RunResultItem {
+    subjectKey: string;
+    beneficiaryDirectoryId: string;
+    campaignId: string;
+    evaluationId: string;
+    packageId: string;
+    outcome: EvaluationOutcomeEnum;
+    grantStatus: GrantRequestStatusEnum;
+    /** `grantIdFor("rewards-eligibility", idempotencyKey)`; cruza con `GET /grants/{id}` de rewards. */
+    grantId?: string;
+    /** Solo si `outcome` es ERROR. */
+    errorMessage?: string;
+}

package/src/rewardsEligibility/enums/EvaluationOutcomeEnum.ts

@@ -0,0 +1,11 @@
+export enum EvaluationOutcomeEnum {
+    MATCH = 'MATCH',
+    NO_MATCH = 'NO_MATCH',
+    ERROR = 'ERROR',
+    /** La política de frecuencia lo bloqueó. */
+    ALREADY_GRANTED = 'ALREADY_GRANTED',
+    /** Calificó, pero la campaña no tenía cupo. */
+    QUOTA_EXHAUSTED = 'QUOTA_EXHAUSTED',
+    /** El operador lo sacó al aprobar. */
+    EXCLUDED = 'EXCLUDED',
+}

package/src/rewardsEligibility/enums/GrantRequestStatusEnum.ts

@@ -0,0 +1,11 @@
+export enum GrantRequestStatusEnum {
+    NOT_APPLICABLE = 'NOT_APPLICABLE',
+    PENDING_APPROVAL = 'PENDING_APPROVAL',
+    /** Reservado, esperando su tramo de publicación. */
+    QUEUED = 'QUEUED',
+    /** Publicado en RewardsGrantQueue al instante (en línea). */
+    REQUESTED = 'REQUESTED',
+    /** La publicación falló o llegó GRANT_FAILED. */
+    REQUEST_FAILED = 'REQUEST_FAILED',
+    CANCELLED = 'CANCELLED',
+}

package/src/rewardsEligibility/enums/RewardsEligibilityErrorCodeEnum.ts

@@ -0,0 +1,8 @@
+export enum RewardsEligibilityErrorCodeEnum {
+    /** 400: faltan campos obligatorios del evento o tienen tipo inválido. */
+    INPUT_INVALID = 'INPUT_INVALID',
+    /** 404: el eventKey no existe o está inactivo. */
+    EVENT_TYPE_NOT_FOUND = 'EVENT_TYPE_NOT_FOUND',
+    /** 404: GET /runs/{id} sin corrida. */
+    RUN_NOT_FOUND = 'RUN_NOT_FOUND',
+}

package/src/rewardsEligibility/enums/RunModeEnum.ts

@@ -0,0 +1,4 @@
+export enum RunModeEnum {
+    LIVE = 'LIVE',
+    SIMULATION = 'SIMULATION',
+}

package/src/rewardsEligibility/enums/RunStatusEnum.ts

@@ -0,0 +1,9 @@
+export enum RunStatusEnum {
+    RUNNING = 'RUNNING',
+    AWAITING_APPROVAL = 'AWAITING_APPROVAL',
+    PUBLISHING = 'PUBLISHING',
+    COMPLETED = 'COMPLETED',
+    PARTIAL = 'PARTIAL',
+    FAILED = 'FAILED',
+    REJECTED = 'REJECTED',
+}

package/src/rewardsEligibility/enums/TriggerTypeEnum.ts

@@ -0,0 +1,5 @@
+export enum TriggerTypeEnum {
+    EVENT = 'EVENT',
+    MANUAL = 'MANUAL',
+    CRON = 'CRON',
+}

package/src/rewardsEligibility/index.ts

@@ -0,0 +1,16 @@
+//Enums
+export * from './enums/EvaluationOutcomeEnum';
+export * from './enums/GrantRequestStatusEnum';
+export * from './enums/RunStatusEnum';
+export * from './enums/RunModeEnum';
+export * from './enums/TriggerTypeEnum';
+export * from './enums/RewardsEligibilityErrorCodeEnum';
+
+//DTOs
+export * from './dtos/EventSource';
+export * from './dtos/PostEventRequest';
+export * from './dtos/EventRunResult';
+export * from './dtos/PostEventResponse';
+export * from './dtos/RunCounts';
+export * from './dtos/RunResultItem';
+export * from './dtos/GetRunResponse';