@fiado/type-kit 3.616.0 → 3.618.0

package/src/transferNote/dtos/responses/TransferNoteResponses.ts

@@ -0,0 +1,51 @@
+import { CurrencyId } from '../../../currency/enums/CurrencyId';
+import { TransferNote, TransferNoteStatusCount, TransferNoteSubtotal, TransferNoteSummary } from '../TransferNote';
+import { TransferNoteHistoryEntry } from '../TransferNoteHistoryEntry';
+import { TransferNoteItem } from '../TransferNoteItem';
+import { TransferNoteSignedUrl } from '../TransferNoteSignedUrl';
+
+export interface ListTransferNotesResponse {
+    items: TransferNoteSummary[];
+    statusCounts: TransferNoteStatusCount[];
+    nextToken?: string;
+}
+
+export interface ListTransferNotePoolResponse {
+    items: TransferNoteItem[];
+    nextToken?: string;
+}
+
+export interface ListTransferNoteItemsResponse {
+    items: TransferNoteItem[];
+    nextToken?: string;
+}
+
+export interface GetTransferNoteHistoryResponse {
+    items: TransferNoteHistoryEntry[];
+}
+
+/** Neto y subtotales de una selección, sin emitir. */
+export interface PreviewTransferNoteResponse {
+    pairKey: string;
+    netAmountCents: number;
+    currency: CurrencyId;
+    itemCount: number;
+    subtotals: TransferNoteSubtotal[];
+}
+
+/** Al aceptar, trae la regenerada si el neto quedó positivo. */
+export interface ResolveTransferNoteDisputeResponse {
+    note: TransferNote;
+    regeneratedNote?: TransferNote;
+}
+
+export type GetTransferNoteResponse = TransferNote;
+export type IssueTransferNoteResponse = TransferNote;
+export type CaptureTransferNoteSpeiResponse = TransferNote;
+export type RevertTransferNoteSpeiResponse = TransferNote;
+export type ConfirmTransferNoteReceptionResponse = TransferNote;
+export type CancelTransferNoteResponse = TransferNote;
+/** URL firmada de PUT para subir el comprobante en PDF. */
+export type CreateSpeiReceiptUploadUrlResponse = TransferNoteSignedUrl;
+/** URL firmada de GET del PDF de la nota. */
+export type GetTransferNotePdfResponse = TransferNoteSignedUrl;

package/src/transferNote/enums/TransferNoteConceptEnum.ts

@@ -0,0 +1,16 @@
+/** Concepto de un item de nota; el par y el signo de cada uno salen de la configuración del tenant. */
+export enum TransferNoteConceptEnum {
+    INSTALLMENT_COLLECTION = 'INSTALLMENT_COLLECTION',
+    CREDIT_PROMOTION_REIMBURSEMENT = 'CREDIT_PROMOTION_REIMBURSEMENT',
+    /** Cubre los bonos WELCOME, SALE_PROMOTION y REFERRAL de retail-customer. */
+    SALE_PROMOTION_REIMBURSEMENT = 'SALE_PROMOTION_REIMBURSEMENT',
+    SALE_COMMISSION = 'SALE_COMMISSION',
+    DEVICE_PAYMENT = 'DEVICE_PAYMENT',
+    DOWN_PAYMENT = 'DOWN_PAYMENT',
+    /** Derivado de cada crédito firmado con la tarifa del tenant. */
+    ORIGINATION_BONUS = 'ORIGINATION_BONUS',
+    /** Derivado de cada crédito firmado con la tarifa del tenant. */
+    ACCOUNT_OPENING = 'ACCOUNT_OPENING',
+    /** Ajuste entre empresas; viaja en el par de su item original. */
+    ADJUSTMENT = 'ADJUSTMENT',
+}

package/src/transferNote/enums/TransferNoteConceptSignEnum.ts

@@ -0,0 +1,5 @@
+/** Signo con que un concepto suma al neto que el pagador le debe al receptor. */
+export enum TransferNoteConceptSignEnum {
+    POSITIVE = 'POSITIVE',
+    NEGATIVE = 'NEGATIVE',
+}

package/src/transferNote/enums/TransferNoteConfigRecordTypeEnum.ts

@@ -0,0 +1,7 @@
+/** Tipo de registro de la configuración del tenant; es el prefijo de su `recordKey`. */
+export enum TransferNoteConfigRecordTypeEnum {
+    TENANT = 'TENANT',
+    PARTY = 'PARTY',
+    CONCEPT = 'CONCEPT',
+    PAIR = 'PAIR',
+}

package/src/transferNote/enums/TransferNoteConfirmationSourceEnum.ts

@@ -0,0 +1,5 @@
+/** Origen de una confirmación: la dio una persona o la llenó la conciliación bancaria. */
+export enum TransferNoteConfirmationSourceEnum {
+    MANUAL = 'MANUAL',
+    LAYER_4_AUTO = 'LAYER_4_AUTO',
+}

package/src/transferNote/enums/TransferNoteConfirmationTypeEnum.ts

@@ -0,0 +1,5 @@
+/** Confirmación que puede exigir una nota: la recepción del receptor o la de FSA en su estado de cuenta. */
+export enum TransferNoteConfirmationTypeEnum {
+    PAYEE_RECEPTION = 'PAYEE_RECEPTION',
+    GATEWAY_SETTLEMENT = 'GATEWAY_SETTLEMENT',
+}

package/src/transferNote/enums/TransferNoteDisputeCategoryEnum.ts

@@ -0,0 +1,7 @@
+/** Categoría de la objeción de un retailer a una nota. */
+export enum TransferNoteDisputeCategoryEnum {
+    INCORRECT_AMOUNT = 'INCORRECT_AMOUNT',
+    MISSING_ITEMS = 'MISSING_ITEMS',
+    EXTRA_ITEMS = 'EXTRA_ITEMS',
+    OTHER = 'OTHER',
+}

package/src/transferNote/enums/TransferNoteDisputeDecisionEnum.ts

@@ -0,0 +1,5 @@
+/** ACCEPT cancela y regenera la nota; REJECT la regresa a su estado previo. */
+export enum TransferNoteDisputeDecisionEnum {
+    ACCEPT = 'ACCEPT',
+    REJECT = 'REJECT',
+}

package/src/transferNote/enums/TransferNoteErrorCodeEnum.ts

@@ -0,0 +1,34 @@
+import { ReconciliationFeedErrorCodeEnum } from '../../reconciliation/enums/ReconciliationFeedErrorCodeEnum';
+
+/**
+ * Codes de error de transfer-note-business; el status de cada uno está en
+ * `TRANSFER_NOTE_ERROR_HTTP_STATUS`. Las clases `DomainError` viven en el lambda.
+ */
+export enum TransferNoteErrorCodeEnum {
+    TRANSFER_NOTE_NOT_FOUND = 'TRANSFER_NOTE_NOT_FOUND',
+    NOTE_NOT_DISPUTABLE = 'NOTE_NOT_DISPUTABLE',
+    NET_NOT_POSITIVE = 'NET_NOT_POSITIVE',
+    NOT_NOTE_CONTROLLER = 'NOT_NOTE_CONTROLLER',
+    PAYEE_ACCOUNT_NOT_REGISTERED = 'PAYEE_ACCOUNT_NOT_REGISTERED',
+    ITEM_ALREADY_INCLUDED = 'ITEM_ALREADY_INCLUDED',
+    /** La semana del par ya tiene nota de corte. */
+    WEEK_ALREADY_CUT = 'WEEK_ALREADY_CUT',
+    NOTE_NOT_ISSUED = 'NOTE_NOT_ISSUED',
+    NOTE_DISPUTED = 'NOTE_DISPUTED',
+    NOT_NOTE_PAYER = 'NOT_NOTE_PAYER',
+    NOTE_NOT_SENT = 'NOTE_NOT_SENT',
+    NOT_NOTE_PAYEE = 'NOT_NOTE_PAYEE',
+    NOTE_NOT_DISPUTED = 'NOTE_NOT_DISPUTED',
+    CONTACT_EMAIL_MISSING = 'CONTACT_EMAIL_MISSING',
+    INVALID_CONFIG_RECORD_TYPE = 'INVALID_CONFIG_RECORD_TYPE',
+    /** El `author` del espejo privado no está en la lista permitida del lambda. */
+    AUTHOR_NOT_ALLOWED = 'AUTHOR_NOT_ALLOWED',
+    /** La nota no exige confirmación de FSA en su estado de cuenta. */
+    SETTLEMENT_NOT_REQUIRED = 'SETTLEMENT_NOT_REQUIRED',
+    RUN_IN_PROGRESS = 'RUN_IN_PROGRESS',
+    SOURCE_ITEM_NOT_FOUND = 'SOURCE_ITEM_NOT_FOUND',
+    /** No hay item para el concepto y registro de origen pedidos en by-source. */
+    TRANSFER_NOTE_ITEM_NOT_FOUND = 'TRANSFER_NOTE_ITEM_NOT_FOUND',
+    /** Mismo code del feed genérico que implementa cada dueño. */
+    FEED_RECORD_NOT_FOUND = ReconciliationFeedErrorCodeEnum.FEED_RECORD_NOT_FOUND,
+}

package/src/transferNote/enums/TransferNoteFeedConceptEnum.ts

@@ -0,0 +1,5 @@
+/** Conceptos que transfer-note-business expone en `GET /private/reconciliation-feeds/{concept}`. */
+export enum TransferNoteFeedConceptEnum {
+    TRANSFER_NOTE_ITEM = 'TRANSFER_NOTE_ITEM',
+    TRANSFER_NOTE_SETTLEMENT = 'TRANSFER_NOTE_SETTLEMENT',
+}

package/src/transferNote/enums/TransferNoteHistoryActionEnum.ts

@@ -0,0 +1,13 @@
+/** Acción registrada en el historial de una nota. */
+export enum TransferNoteHistoryActionEnum {
+    ISSUE = 'ISSUE',
+    CAPTURE_SPEI = 'CAPTURE_SPEI',
+    REVERT_SPEI = 'REVERT_SPEI',
+    CONFIRM_RECEPTION = 'CONFIRM_RECEPTION',
+    CONFIRM_SETTLEMENT = 'CONFIRM_SETTLEMENT',
+    RECONCILE = 'RECONCILE',
+    CANCEL = 'CANCEL',
+    DISPUTE = 'DISPUTE',
+    RESOLVE_DISPUTE = 'RESOLVE_DISPUTE',
+    SEND_NOTICE = 'SEND_NOTICE',
+}

package/src/transferNote/enums/TransferNoteIssueOriginEnum.ts

@@ -0,0 +1,6 @@
+/** Cómo nació la nota: corte semanal, emisión manual o regenerada tras aceptar una objeción. */
+export enum TransferNoteIssueOriginEnum {
+    CUTOFF = 'CUTOFF',
+    MANUAL = 'MANUAL',
+    REGENERATED = 'REGENERATED',
+}

package/src/transferNote/enums/TransferNoteItemStatusEnum.ts

@@ -0,0 +1,5 @@
+/** Estado de un item: en el pool de su par o incluido en una nota. */
+export enum TransferNoteItemStatusEnum {
+    POOLED = 'POOLED',
+    INCLUDED = 'INCLUDED',
+}

package/src/transferNote/enums/TransferNotePartyTypeEnum.ts

@@ -0,0 +1,6 @@
+/** Tipo de parte de un par: GATEWAY es quien mueve el dinero (FSA), SOFOM la financiera, RETAILER cada tienda. */
+export enum TransferNotePartyTypeEnum {
+    GATEWAY = 'GATEWAY',
+    SOFOM = 'SOFOM',
+    RETAILER = 'RETAILER',
+}

package/src/transferNote/enums/TransferNoteStatusEnum.ts

@@ -0,0 +1,9 @@
+/** Estado de una nota; ISSUING es transitorio mientras el corte o la emisión toman sus items. */
+export enum TransferNoteStatusEnum {
+    ISSUING = 'ISSUING',
+    ISSUED = 'ISSUED',
+    SENT = 'SENT',
+    RECONCILED = 'RECONCILED',
+    CANCELLED = 'CANCELLED',
+    DISPUTED = 'DISPUTED',
+}

package/src/transferNote/events/TransferNoteReconciledEventDetail.ts

@@ -0,0 +1,22 @@
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+
+// Origen de los eventos de EventBridge que publica transfer-note-business.
+export const TRANSFER_NOTE_EVENTS_SOURCE = 'fiado.transferNote';
+
+export enum TransferNoteEventDetailTypeEnum {
+    TRANSFER_NOTE_RECONCILED = 'transferNote.TransferNoteReconciled',
+}
+
+// `detail` de TransferNoteReconciled; el motor recalcula con él el agregado de la semana del par.
+export class TransferNoteReconciledEventDetail {
+    /** Fijo por nota: un reenvío llega con el mismo id y el consumidor lo descarta. */
+    eventId!: string;
+    tenantId!: string;
+    noteId!: string;
+    pairKey!: string;
+    isoWeek!: string;
+    netAmountCents!: number;
+    currency!: CurrencyId;
+    /** ISO 8601 de la última confirmación. */
+    reconciledAt!: string;
+}

package/src/transferNote/index.ts

@@ -0,0 +1,45 @@
+// Enums
+export * from './enums/TransferNoteStatusEnum';
+export * from './enums/TransferNoteItemStatusEnum';
+export * from './enums/TransferNoteConceptEnum';
+export * from './enums/TransferNoteConceptSignEnum';
+export * from './enums/TransferNotePartyTypeEnum';
+export * from './enums/TransferNoteDisputeCategoryEnum';
+export * from './enums/TransferNoteDisputeDecisionEnum';
+export * from './enums/TransferNoteIssueOriginEnum';
+export * from './enums/TransferNoteConfigRecordTypeEnum';
+export * from './enums/TransferNoteConfirmationTypeEnum';
+export * from './enums/TransferNoteConfirmationSourceEnum';
+export * from './enums/TransferNoteHistoryActionEnum';
+export * from './enums/TransferNoteFeedConceptEnum';
+export * from './enums/TransferNoteErrorCodeEnum';
+
+// Constantes y validadores
+export * from './constants/transferNoteErrorHttpStatus';
+export * from './constants/transferNoteValidation';
+export * from './constants/transferNoteDefaultFees';
+export * from './validators/IsTransferNoteSelectionConstraint';
+
+// Entidades del dominio
+export * from './dtos/TransferNote';
+export * from './dtos/TransferNoteItem';
+export * from './dtos/TransferNoteHistoryEntry';
+export * from './dtos/TransferNoteSignedUrl';
+export * from './dtos/TransferNoteConfigRecords';
+export * from './dtos/TransferNoteFeedRecords';
+
+// Request DTOs
+export * from './dtos/requests/TransferNoteActionRequests';
+export * from './dtos/requests/TransferNoteQueries';
+export * from './dtos/requests/RetailerTransferNoteRequests';
+export * from './dtos/requests/TransferNoteConfigRequests';
+export * from './dtos/requests/PrivateTransferNoteRequests';
+
+// Response DTOs
+export * from './dtos/responses/TransferNoteResponses';
+export * from './dtos/responses/RetailerTransferNoteResponses';
+export * from './dtos/responses/TransferNoteConfigResponses';
+export * from './dtos/responses/PrivateTransferNoteResponses';
+
+// Eventos
+export * from './events/TransferNoteReconciledEventDetail';

package/src/transferNote/validators/IsTransferNoteSelectionConstraint.ts

@@ -0,0 +1,16 @@
+import { ValidatorConstraint, type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+
+/** Exige `itemIds` (no vacío, sin strings vacíos) o `isoWeek`, nunca los dos ni ninguno. */
+@ValidatorConstraint({ name: 'isTransferNoteSelection', async: false })
+export class IsTransferNoteSelectionConstraint implements ValidatorConstraintInterface {
+    validate(itemIds: unknown, args: ValidationArguments): boolean {
+        const hasWeek = (args.object as { isoWeek?: unknown }).isoWeek !== undefined;
+        if (itemIds === undefined) return hasWeek;
+        if (hasWeek || !Array.isArray(itemIds) || itemIds.length === 0) return false;
+        return itemIds.every((id) => typeof id === 'string' && id.trim().length > 0);
+    }
+
+    defaultMessage(): string {
+        return 'manda itemIds no vacío o isoWeek, uno de los dos';
+    }
+}